// 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 { RequestOptions } from '../../internal/request-options';

/**
 * Custom objects defined by the company
 */
export class Components extends APIResource {
  /**
   * Validate a complete metadata component package without installing it.
   *
   * Requires the Metadata entitlement.
   *
   * @example SDK usage
   * ```ts
   * const response = await client.metadata.components.validate({
   *   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/validate/ 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 200 OK
   * Content-Type: application/json
   *
   * {
   *   "valid": false,
   *   "results": [
   *     {
   *       "type": "string",
   *       "valid": false,
   *       "identifier": {},
   *       "normalized": {},
   *       "existing": {},
   *       "merged": {},
   *       "outcome": "CREATE",
   *       "errors": [
   *         {}
   *       ]
   *     }
   *   ],
   *   "errors": [
   *     {
   *       "code": "string",
   *       "message": "string",
   *       "component_type": "string",
   *       "cause": "string"
   *     }
   *   ]
   * }
   * ```
   */
  validate(body: ComponentValidateParams, options?: RequestOptions): APIPromise<ComponentValidateResponse> {
    return this._client.post('/metadata/validate/', { body, ...options });
  }

  /**
   * Create or update the supplied metadata components as one package. Call
   * validation first and deploy only valid input.
   *
   * Requires the Metadata entitlement.
   *
   * @example SDK usage
   * ```ts
   * const response = await client.metadata.components.deploy({
   *   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/deploy/ 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 200 OK
   * Content-Type: application/json
   *
   * {
   *   "success": false,
   *   "installations": [
   *     {
   *       "type": "string",
   *       "identifier": {},
   *       "status": "SUCCESS",
   *       "result": {},
   *       "navigation_target": {
   *         "url": "string",
   *         "title": "string",
   *         "target_type": "string"
   *       }
   *     }
   *   ],
   *   "error": {
   *     "code": "string",
   *     "message": "string",
   *     "component_type": "string",
   *     "cause": "string"
   *   }
   * }
   * ```
   */
  deploy(body: ComponentDeployParams, options?: RequestOptions): APIPromise<ComponentDeployResponse> {
    return this._client.post('/metadata/deploy/', { body, ...options });
  }
}

export interface ComponentValidateResponse {
  /**
   * Package-level validation issues.
   */
  errors: Array<ComponentValidateResponse.Error>;

  /**
   * Per-component validation results.
   */
  results: Array<ComponentValidateResponse.Result>;

  /**
   * True only when every component and dependency check passed.
   */
  valid: boolean;
}

export namespace ComponentValidateResponse {
  /**
   * A validation, dependency, permission, or deployment issue.
   */
  export interface Error {
    /**
     * Stable machine-readable issue code.
     */
    code: string;

    /**
     * Human-readable remediation message.
     */
    message: string;

    /**
     * Lower-level cause associated with the issue, when available.
     */
    cause?: string | null;

    /**
     * Component type associated with the issue, when available.
     */
    component_type?: string | null;

    [k: string]: unknown;
  }

  export interface Result {
    /**
     * Metadata component type.
     */
    type: string;

    /**
     * Whether this component passed validation.
     */
    valid: boolean;

    errors?: Array<Result.Error>;

    /**
     * Existing component config matched by the identifier, when available.
     */
    existing?: { [key: string]: unknown };

    /**
     * Resolved component identifier.
     */
    identifier?: { [key: string]: unknown };

    /**
     * Merged target state for updates, when available.
     */
    merged?: { [key: string]: unknown };

    /**
     * Schema-normalized component config.
     */
    normalized?: { [key: string]: unknown };

    /**
     * Upsert classification computed during validation.
     */
    outcome?: 'CREATE' | 'NO_OP' | 'UPDATE' | 'UNSUPPORTED_UPDATE' | null;

    [k: string]: unknown;
  }

  export namespace Result {
    /**
     * A validation, dependency, permission, or deployment issue.
     */
    export interface Error {
      /**
       * Stable machine-readable issue code.
       */
      code: string;

      /**
       * Human-readable remediation message.
       */
      message: string;

      /**
       * Lower-level cause associated with the issue, when available.
       */
      cause?: string | null;

      /**
       * Component type associated with the issue, when available.
       */
      component_type?: string | null;

      [k: string]: unknown;
    }
  }
}

export interface ComponentDeployResponse {
  /**
   * Per-component deployment results.
   */
  installations: Array<ComponentDeployResponse.Installation>;

  /**
   * Whether the package deployment completed.
   */
  success: boolean;

  /**
   * A validation, dependency, permission, or deployment issue.
   */
  error?: ComponentDeployResponse.Error;
}

export namespace ComponentDeployResponse {
  export interface Installation {
    /**
     * Installed component identifier.
     */
    identifier: { [key: string]: unknown };

    /**
     * Per-component install result.
     */
    status: 'SUCCESS' | 'FAILED' | 'SKIPPED_ALREADY_EXISTS' | 'UPDATED' | 'SKIPPED_NO_CHANGES';

    /**
     * Metadata component type.
     */
    type: string;

    /**
     * Navigation target for the installed component, when available.
     */
    navigation_target?: Installation.NavigationTarget | null;

    /**
     * Type-specific install result.
     */
    result?: { [key: string]: unknown };

    [k: string]: unknown;
  }

  export namespace Installation {
    /**
     * Navigation target for the installed component, when available.
     */
    export interface NavigationTarget {
      /**
       * Type of UI target.
       */
      target_type: string;

      /**
       * Display title for the navigation target.
       */
      title: string;

      /**
       * Relative URL for the installed component.
       */
      url: string;
    }
  }

  /**
   * A validation, dependency, permission, or deployment issue.
   */
  export interface Error {
    /**
     * Stable machine-readable issue code.
     */
    code: string;

    /**
     * Human-readable remediation message.
     */
    message: string;

    /**
     * Lower-level cause associated with the issue, when available.
     */
    cause?: string | null;

    /**
     * Component type associated with the issue, when available.
     */
    component_type?: string | null;

    [k: string]: unknown;
  }
}

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

export namespace ComponentValidateParams {
  /**
   * 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 interface ComponentDeployParams {
  /**
   * Complete package of metadata components, including dependencies.
   */
  components: Array<ComponentDeployParams.Component>;
}

export namespace ComponentDeployParams {
  /**
   * 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 Components {
  export {
    type ComponentValidateResponse as ComponentValidateResponse,
    type ComponentDeployResponse as ComponentDeployResponse,
    type ComponentValidateParams as ComponentValidateParams,
    type ComponentDeployParams as ComponentDeployParams,
  };
}