// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../core/resource';
import * as BusinessPartnersAPI from './business-partners';
import { APIPromise } from '../core/api-promise';
import { PageCursorURL, PagePromise } from '../core/pagination';
import { buildHeaders } from '../internal/headers';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

/**
 * Isolated environments used for development and testing
 */
export class Sandboxes extends APIResource {
  /**
   * A list of sandboxes.
   *
   * - Requires: `Developer Base`
   * - Filterable fields: `handle`, `type`
   * - Sortable fields: `id`, `created_at`, `updated_at`
   *
   * @example HTTP
   * Representative request and response shapes.
   * ```
   * GET /sandboxes/?filter=filter&order_by=order_by&limit=50&cursor=cursor HTTP/1.1
   * Host: rest.ripplingapis.com
   * Accept: application/json
   * Rippling-Api-Version: 2024-08-01
   *
   * HTTP/1.1 200 OK
   * Content-Type: application/json
   *
   * {
   *   "__meta": {
   *     "redacted_fields": [
   *       {
   *         "name": "date_of_birth",
   *         "reason": "Insufficient entitlements"
   *       }
   *     ]
   *   },
   *   "results": [
   *     {
   *       "id": "string",
   *       "created_at": "string",
   *       "updated_at": "string",
   *       "name": "string",
   *       "description": "string",
   *       "handle": "string",
   *       "type": "developer",
   *       "status": "string"
   *     }
   *   ],
   *   "next_link": "string"
   * }
   * ```
   */
  list(
    query: SandboxListParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<SandboxListResponsesPageCursorURL, SandboxListResponse> {
    return this._client.getAPIList('/sandboxes/', PageCursorURL<SandboxListResponse>, { query, ...options });
  }

  /**
   * Create a new sandbox
   *
   * @example HTTP
   * Representative request and response shapes.
   * ```
   * POST /sandboxes/ HTTP/1.1
   * Host: rest.ripplingapis.com
   * Content-Type: application/json
   * Accept: application/json
   * Rippling-Api-Version: 2024-08-01
   *
   * {
   *   "name": "name",
   *   "type": "developer"
   * }
   *
   * HTTP/1.1 200 OK
   * Content-Type: application/json
   *
   * {
   *   "id": "string",
   *   "created_at": "string",
   *   "updated_at": "string",
   *   "name": "string",
   *   "description": "string",
   *   "handle": "string",
   *   "type": "developer",
   *   "status": "string"
   * }
   * ```
   */
  create(body: SandboxCreateParams, options?: RequestOptions): APIPromise<SandboxCreateResponse> {
    return this._client.post('/sandboxes/', { body, ...options });
  }

  /**
   * Retrieve a specific sandbox
   *
   * @example HTTP
   * Representative request and response shapes.
   * ```
   * GET /sandboxes/{id}/ HTTP/1.1
   * Host: rest.ripplingapis.com
   * Accept: application/json
   * Rippling-Api-Version: 2024-08-01
   *
   * HTTP/1.1 200 OK
   * Content-Type: application/json
   *
   * {
   *   "__meta": {
   *     "redacted_fields": [
   *       {}
   *     ]
   *   }
   * }
   * ```
   */
  retrieve(id: string, options?: RequestOptions): APIPromise<SandboxRetrieveResponse> {
    return this._client.get(path`/sandboxes/${id}/`, options);
  }

  /**
   * Delete a sandbox
   *
   * @example HTTP
   * Representative request and response shapes.
   * ```
   * DELETE /sandboxes/{id}/ HTTP/1.1
   * Host: rest.ripplingapis.com
   * Rippling-Api-Version: 2024-08-01
   *
   * HTTP/1.1 204 No Content
   * ```
   */
  delete(id: string, options?: RequestOptions): APIPromise<void> {
    return this._client.delete(path`/sandboxes/${id}/`, {
      ...options,
      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
    });
  }

  /**
   * Get the company and administrator role used to enter a developer sandbox.
   *
   * @example HTTP
   * Representative request and response shapes.
   * ```
   * GET /sandboxes/{id}/developer-sandbox-entry-roles/ HTTP/1.1
   * Host: rest.ripplingapis.com
   * Accept: application/json
   * Rippling-Api-Version: 2024-08-01
   *
   * HTTP/1.1 200 OK
   * Content-Type: application/json
   *
   * {
   *   "target_company_id": "string",
   *   "admin_role_id": "string"
   * }
   * ```
   */
  developerSandboxEntryRoles(
    id: string,
    options?: RequestOptions,
  ): APIPromise<SandboxDeveloperSandboxEntryRolesResponse> {
    return this._client.get(path`/sandboxes/${id}/developer-sandbox-entry-roles/`, options);
  }
}

export type SandboxListResponsesPageCursorURL = PageCursorURL<SandboxListResponse>;

export interface SandboxListResponse {
  /**
   * Identifier field
   */
  id: string;

  /**
   * Record creation date
   */
  created_at: string;

  /**
   * Display name of the sandbox.
   */
  name: string;

  /**
   * Sandbox type. Supported value: "developer".
   */
  type: 'developer';

  /**
   * Record update date
   */
  updated_at: string;

  /**
   * Optional sandbox description.
   */
  description?: string;

  /**
   * Server-generated sandbox handle.
   */
  handle?: string;

  /**
   * Current lifecycle status.
   */
  status?: string;
}

export interface SandboxCreateResponse {
  /**
   * Identifier field
   */
  id: string;

  /**
   * Record creation date
   */
  created_at: string;

  /**
   * Display name of the sandbox.
   */
  name: string;

  /**
   * Sandbox type. Supported value: "developer".
   */
  type: 'developer';

  /**
   * Record update date
   */
  updated_at: string;

  /**
   * Optional sandbox description.
   */
  description?: string;

  /**
   * Server-generated sandbox handle.
   */
  handle?: string;

  /**
   * Current lifecycle status.
   */
  status?: string;
}

/**
 * Meta information for the response.
 */
export interface SandboxRetrieveResponse extends BusinessPartnersAPI.Meta {
  /**
   * Identifier field
   */
  id: string;

  /**
   * Record creation date
   */
  created_at: string;

  /**
   * Display name of the sandbox.
   */
  name: string;

  /**
   * Sandbox type. Supported value: "developer".
   */
  type: 'developer';

  /**
   * Record update date
   */
  updated_at: string;

  /**
   * Optional sandbox description.
   */
  description?: string;

  /**
   * Server-generated sandbox handle.
   */
  handle?: string;

  /**
   * Current lifecycle status.
   */
  status?: string;
}

/**
 * Company and administrator role used to enter a developer sandbox.
 */
export interface SandboxDeveloperSandboxEntryRolesResponse {
  /**
   * The unique identifier of the sandbox company's administrator role.
   */
  admin_role_id: string | null;

  /**
   * The unique identifier of the company inside the sandbox.
   */
  target_company_id: string | null;
}

export interface SandboxListParams {
  cursor?: string;

  filter?: string;

  /**
   * The maximum number of results to return. Defaults to 50. Maximum is 100.
   */
  limit?: number;

  order_by?: string;
}

export interface SandboxCreateParams {
  /**
   * Display name of the sandbox.
   */
  name: string;

  /**
   * Sandbox type. Supported value: "developer".
   */
  type: 'developer';

  /**
   * Optional create-only sandbox configuration.
   */
  config_override?: SandboxCreateParams.ConfigOverride;

  /**
   * Optional sandbox description.
   */
  description?: string;
}

export namespace SandboxCreateParams {
  /**
   * Optional create-only sandbox configuration.
   */
  export interface ConfigOverride {
    /**
     * Custom objects copied into the sandbox.
     */
    custom_objects?: ConfigOverride.CustomObjects;

    /**
     * Required for developer sandboxes and omitted for full-data sandboxes.
     */
    developer?: ConfigOverride.Developer;

    /**
     * General outbound notification controls.
     */
    general_notifications?: ConfigOverride.GeneralNotifications;

    /**
     * Required for connected full-data sandboxes.
     */
    integrations?: ConfigOverride.Integrations;

    /**
     * Required for full-data sandboxes. Developer sandboxes default to CONNECTED.
     */
    sandbox_mode?: 'CONNECTED' | 'ISOLATED';

    /**
     * Workflow webhook controls.
     */
    workflow_webhooks?: ConfigOverride.WorkflowWebhooks;
  }

  export namespace ConfigOverride {
    /**
     * Custom objects copied into the sandbox.
     */
    export interface CustomObjects {
      /**
       * Custom object API names copied into the sandbox.
       */
      co_api_names?: Array<string>;
    }

    /**
     * Required for developer sandboxes and omitted for full-data sandboxes.
     */
    export interface Developer {
      /**
       * Seed company size for the developer sandbox. MEDIUM is the supported value for
       * new sandboxes. SMALL is retained for existing sandboxes only and is not
       * supported on create.
       */
      company_size: 'SMALL' | 'MEDIUM';
    }

    /**
     * General outbound notification controls.
     */
    export interface GeneralNotifications {
      /**
       * Email notification configuration.
       */
      email: GeneralNotifications.Email;

      /**
       * Push notification configuration.
       */
      push_notifications: GeneralNotifications.PushNotifications;

      /**
       * SMS notification configuration.
       */
      sms: GeneralNotifications.SMS;

      /**
       * Slack notification configuration.
       */
      slack?: GeneralNotifications.Slack;

      /**
       * Microsoft Teams notification configuration.
       */
      teams?: GeneralNotifications.Teams;
    }

    export namespace GeneralNotifications {
      /**
       * Email notification configuration.
       */
      export interface Email {
        /**
         * Whether outbound messages are allowed or suppressed.
         */
        outbound_behavior: 'SUPPRESS' | 'ALLOW';

        /**
         * Users allowed to receive outbound messages.
         */
        allowed_users?: Array<string>;
      }

      /**
       * Push notification configuration.
       */
      export interface PushNotifications {
        /**
         * Whether outbound messages are allowed or suppressed.
         */
        outbound_behavior: 'SUPPRESS' | 'ALLOW';

        /**
         * Users allowed to receive outbound messages.
         */
        allowed_users?: Array<string>;
      }

      /**
       * SMS notification configuration.
       */
      export interface SMS {
        /**
         * Whether outbound messages are allowed or suppressed.
         */
        outbound_behavior: 'SUPPRESS' | 'ALLOW';

        /**
         * Users allowed to receive outbound messages.
         */
        allowed_users?: Array<string>;
      }

      /**
       * Slack notification configuration.
       */
      export interface Slack {
        /**
         * Whether outbound messages are allowed or suppressed.
         */
        outbound_behavior: 'SUPPRESS' | 'ALLOW';

        /**
         * Public channels allowed to receive outbound messages.
         */
        allowed_public_channels?: Array<string>;

        /**
         * Users allowed to receive outbound messages.
         */
        allowed_users?: Array<string>;
      }

      /**
       * Microsoft Teams notification configuration.
       */
      export interface Teams {
        /**
         * Whether outbound messages are allowed or suppressed.
         */
        outbound_behavior: 'SUPPRESS' | 'ALLOW';

        /**
         * Public channels allowed to receive outbound messages.
         */
        allowed_public_channels?: Array<string>;

        /**
         * Users allowed to receive outbound messages.
         */
        allowed_users?: Array<string>;
      }
    }

    /**
     * Required for connected full-data sandboxes.
     */
    export interface Integrations {
      /**
       * Confirms acceptance of the risks of connected third-party integrations.
       */
      is_risk_acknowledged: boolean;
    }

    /**
     * Workflow webhook controls.
     */
    export interface WorkflowWebhooks {
      /**
       * IP addresses allowed to receive workflow webhooks.
       */
      allowed_ips?: Array<string>;

      /**
       * Webhook URLs allowed in the sandbox.
       */
      allowlisted_webhook_urls?: Array<string>;

      /**
       * Whether workflow webhook traffic is allowed or suppressed.
       */
      outbound_behavior?: 'SUPPRESS' | 'ALLOW';
    }
  }
}

export declare namespace Sandboxes {
  export {
    type SandboxListResponse as SandboxListResponse,
    type SandboxCreateResponse as SandboxCreateResponse,
    type SandboxRetrieveResponse as SandboxRetrieveResponse,
    type SandboxDeveloperSandboxEntryRolesResponse as SandboxDeveloperSandboxEntryRolesResponse,
    type SandboxListResponsesPageCursorURL as SandboxListResponsesPageCursorURL,
    type SandboxListParams as SandboxListParams,
    type SandboxCreateParams as SandboxCreateParams,
  };
}