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

import { APIResource } from '../../core/resource';
import { APIPromise } from '../../core/api-promise';
import { buildHeaders } from '../../internal/headers';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

/**
 * Custom objects defined by the company
 */
export class DeploymentRuns extends APIResource {
  /**
   * Queue deployment for a metadata component package and return a run id for
   * polling.
   *
   * Requires the Metadata entitlement.
   *
   * @example SDK usage
   * ```ts
   * const deploymentRun =
   *   await client.metadata.deploymentRuns.create({
   *     components: [
   *       {
   *         type: 'CUSTOM_OBJECT',
   *         api_name: 'purchase_order__c',
   *         name: 'Purchase Order',
   *         description: 'Tracks purchase requests',
   *         category_api_name: 'procurement__c',
   *       },
   *       {
   *         type: 'CUSTOM_OBJECT_FIELD',
   *         custom_object_api_name: 'purchase_order__c',
   *         field_api_name: 'amount__c',
   *         field_display_name: 'Amount',
   *         data_type: {
   *           field_type: 'CURRENCY',
   *           currency: 'USD',
   *           num_of_decimal_places: 2,
   *         },
   *         is_standard: false,
   *       },
   *     ],
   *   });
   * ```
   *
   * @example HTTP
   * Representative request and response shapes.
   * ```
   * POST /metadata/deployment-runs/ HTTP/1.1
   * Host: rest.ripplingapis.com
   * Content-Type: application/json
   * Accept: application/json
   * Rippling-Api-Version: 2024-08-01
   *
   * {
   *   "components": [
   *     {
   *       "type": "CUSTOM_OBJECT",
   *       "api_name": "purchase_order__c",
   *       "name": "Purchase Order",
   *       "description": "Tracks purchase requests",
   *       "category_api_name": "procurement__c"
   *     },
   *     {
   *       "type": "CUSTOM_OBJECT_FIELD",
   *       "custom_object_api_name": "purchase_order__c",
   *       "field_api_name": "amount__c",
   *       "field_display_name": "Amount",
   *       "data_type": {
   *         "field_type": "CURRENCY",
   *         "currency": "USD",
   *         "num_of_decimal_places": 2
   *       },
   *       "is_standard": false
   *     }
   *   ]
   * }
   *
   * HTTP/1.1 202 Accepted
   * Content-Type: application/json
   *
   * {
   *   "id": "string",
   *   "type": "validation",
   *   "status": "queued",
   *   "terminal": false,
   *   "retry_after_ms": 0,
   *   "progress": {},
   *   "result": {},
   *   "error": {},
   *   "created_at": "2025-01-01T00:00:00Z",
   *   "updated_at": "2025-01-01T00:00:00Z",
   *   "started_at": "2025-01-01T00:00:00Z",
   *   "finished_at": "2025-01-01T00:00:00Z",
   *   "expires_at": "2025-01-01T00:00:00Z"
   * }
   * ```
   */
  create(
    params: DeploymentRunCreateParams,
    options?: RequestOptions,
  ): APIPromise<DeploymentRunCreateResponse> {
    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
    return this._client.post('/metadata/deployment-runs/', {
      body,
      ...options,
      headers: buildHeaders([
        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
        options?.headers,
      ]),
    });
  }

  /**
   * Poll a metadata deployment run until the terminal field is true.
   *
   * Requires the Metadata entitlement.
   *
   * @example SDK usage
   * ```ts
   * const deploymentRun =
   *   await client.metadata.deploymentRuns.get('run_id');
   * ```
   *
   * @example HTTP
   * Representative request and response shapes.
   * ```
   * GET /metadata/deployment-runs/{run_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
   *
   * {
   *   "id": "string",
   *   "type": "validation",
   *   "status": "queued",
   *   "terminal": false,
   *   "retry_after_ms": 0,
   *   "progress": {},
   *   "result": {},
   *   "error": {},
   *   "created_at": "2025-01-01T00:00:00Z",
   *   "updated_at": "2025-01-01T00:00:00Z",
   *   "started_at": "2025-01-01T00:00:00Z",
   *   "finished_at": "2025-01-01T00:00:00Z",
   *   "expires_at": "2025-01-01T00:00:00Z"
   * }
   * ```
   */
  get(runID: string, options?: RequestOptions): APIPromise<DeploymentRunGetResponse> {
    return this._client.get(path`/metadata/deployment-runs/${runID}/`, options);
  }
}

export interface DeploymentRunCreateResponse {
  /**
   * Metadata run id.
   */
  id: string;

  progress: { [key: string]: unknown };

  /**
   * Suggested client polling delay in milliseconds.
   */
  retry_after_ms: number;

  status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'expired';

  /**
   * Whether the run has reached a terminal status.
   */
  terminal: boolean;

  type: 'validation' | 'deployment';

  created_at?: string | null;

  error?: { [key: string]: unknown } | null;

  expires_at?: string | null;

  finished_at?: string | null;

  result?: { [key: string]: unknown } | null;

  started_at?: string | null;

  updated_at?: string | null;
}

export interface DeploymentRunGetResponse {
  /**
   * Metadata run id.
   */
  id: string;

  progress: { [key: string]: unknown };

  /**
   * Suggested client polling delay in milliseconds.
   */
  retry_after_ms: number;

  status: 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'expired';

  /**
   * Whether the run has reached a terminal status.
   */
  terminal: boolean;

  type: 'validation' | 'deployment';

  created_at?: string | null;

  error?: { [key: string]: unknown } | null;

  expires_at?: string | null;

  finished_at?: string | null;

  result?: { [key: string]: unknown } | null;

  started_at?: string | null;

  updated_at?: string | null;
}

export interface DeploymentRunCreateParams {
  /**
   * Body param: Complete package of metadata components, including dependencies.
   */
  components: Array<DeploymentRunCreateParams.Component>;

  /**
   * Header param: Optional idempotency key used to deduplicate retried create
   * requests.
   */
  'Idempotency-Key'?: string;
}

export namespace DeploymentRunCreateParams {
  /**
   * A metadata component config. The `type` field selects the concrete component
   * schema. Fetch type-specific fields from GET /metadata/schema/?type=<TYPE>.
   */
  export interface Component {
    /**
     * Metadata component type, such as CUSTOM_OBJECT or CUSTOM_OBJECT_FIELD.
     */
    type: string;

    [k: string]: unknown;
  }
}

export declare namespace DeploymentRuns {
  export {
    type DeploymentRunCreateResponse as DeploymentRunCreateResponse,
    type DeploymentRunGetResponse as DeploymentRunGetResponse,
    type DeploymentRunCreateParams as DeploymentRunCreateParams,
  };
}