@rippling/rippling-sdk 0.2.0-alpha.87 → 0.2.0-alpha.89

package/src/resources/metadata/components.ts

@@ -0,0 +1,630 @@
+// 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 {
+  /**
+   * Extract the company's selectable metadata components, optionally filtered by a
+   * search query.
+   *
+   * Requires the Metadata entitlement.
+   *
+   * @example
+   * ```ts
+   * const response = await client.metadata.components.extract();
+   * ```
+   */
+  extract(
+    query: ComponentExtractParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ComponentExtractResponse> {
+    return this._client.get('/metadata/v2/extract/', { query, ...options });
+  }
+
+  /**
+   * Validate component schemas and dependencies without installing them. Use the
+   * normalized results before deploy.
+   *
+   * Requires the Metadata entitlement.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.metadata.components.validateV2({
+   *     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,
+   *       },
+   *     ],
+   *   });
+   * ```
+   */
+  validateV2(
+    body: ComponentValidateV2Params,
+    options?: RequestOptions,
+  ): APIPromise<ComponentValidateV2Response> {
+    return this._client.post('/metadata/v2/validate/', { body, ...options });
+  }
+
+  /**
+   * Validate a complete metadata component package without installing it.
+   *
+   * Requires the Metadata entitlement.
+   *
+   * @example
+   * ```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,
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  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
+   * ```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,
+   *     },
+   *   ],
+   * });
+   * ```
+   */
+  deploy(body: ComponentDeployParams, options?: RequestOptions): APIPromise<ComponentDeployResponse> {
+    return this._client.post('/metadata/deploy/', { body, ...options });
+  }
+}
+
+export interface ComponentExtractResponse {
+  /**
+   * Full component configs needed to recreate the selected roots.
+   */
+  component_configs: Array<ComponentExtractResponse.ComponentConfig>;
+
+  /**
+   * Serialized dependency graph for the extracted package.
+   */
+  dependency_graph: { [key: string]: unknown };
+
+  /**
+   * Topological install order for the extracted package.
+   */
+  install_order: Array<{ [key: string]: unknown }>;
+
+  /**
+   * Components selected as extraction roots.
+   */
+  root_components: Array<ComponentExtractResponse.RootComponent>;
+
+  /**
+   * For search-backed extraction, whether contextual expansion completed.
+   */
+  context_complete?: boolean;
+
+  /**
+   * Warnings from search-backed contextual expansion.
+   */
+  context_warnings?: Array<string>;
+
+  external_managed_dependencies?: Array<{ [key: string]: unknown }>;
+
+  [k: string]: unknown;
+}
+
+export namespace ComponentExtractResponse {
+  /**
+   * A metadata component config. The `type` field selects the concrete component
+   * schema. Fetch type-specific fields from GET /metadata/schema/?type=<TYPE>.
+   */
+  export interface ComponentConfig {
+    /**
+     * Metadata component type, such as CUSTOM_OBJECT or CUSTOM_OBJECT_FIELD.
+     */
+    type: string;
+
+    [k: string]: unknown;
+  }
+
+  /**
+   * Selectable package root returned by metadata extraction.
+   */
+  export interface RootComponent {
+    /**
+     * Identifier for the selected component.
+     */
+    identifier?: { [key: string]: unknown };
+
+    /**
+     * Display name for the selectable component.
+     */
+    name?: string;
+
+    [k: string]: unknown;
+  }
+}
+
+export interface ComponentValidateV2Response {
+  /**
+   * Package-level validation issues.
+   */
+  errors: Array<ComponentValidateV2Response.Error>;
+
+  /**
+   * Per-component validation results.
+   */
+  results: Array<ComponentValidateV2Response.Result>;
+
+  /**
+   * True only when every component and dependency check passed.
+   */
+  valid: boolean;
+}
+
+export namespace ComponentValidateV2Response {
+  /**
+   * 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 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 ComponentExtractParams {
+  /**
+   * Maximum search results to return when q is provided.
+   */
+  limit?: number;
+
+  /**
+   * Optional text search over selectable components.
+   */
+  q?: string;
+}
+
+export interface ComponentValidateV2Params {
+  /**
+   * Complete package of metadata components, including dependencies.
+   */
+  components: Array<ComponentValidateV2Params.Component>;
+}
+
+export namespace ComponentValidateV2Params {
+  /**
+   * 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 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 ComponentExtractResponse as ComponentExtractResponse,
+    type ComponentValidateV2Response as ComponentValidateV2Response,
+    type ComponentValidateResponse as ComponentValidateResponse,
+    type ComponentDeployResponse as ComponentDeployResponse,
+    type ComponentExtractParams as ComponentExtractParams,
+    type ComponentValidateV2Params as ComponentValidateV2Params,
+    type ComponentValidateParams as ComponentValidateParams,
+    type ComponentDeployParams as ComponentDeployParams,
+  };
+}