@rippling/rippling-sdk 0.2.0-alpha.100 → 0.2.0-alpha.101

package/src/resources/metadata/components.ts

@@ -13,7 +13,7 @@ export class Components extends APIResource {
    *
    * Requires the Metadata entitlement.
    *
-   * @example
+   * @example SDK usage
    * ```ts
    * const response = await client.metadata.components.validate({
    *   components: [
@@ -39,6 +39,69 @@ export class Components extends APIResource {
    *   ],
    * });
    * ```
+   *
+   * @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 });
@@ -50,7 +113,7 @@ export class Components extends APIResource {
    *
    * Requires the Metadata entitlement.
    *
-   * @example
+   * @example SDK usage
    * ```ts
    * const response = await client.metadata.components.deploy({
    *   components: [
@@ -76,6 +139,66 @@ export class Components extends APIResource {
    *   ],
    * });
    * ```
+   *
+   * @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 });

package/src/resources/metadata/deployment-runs.ts

@@ -16,7 +16,7 @@ export class DeploymentRuns extends APIResource {
    *
    * Requires the Metadata entitlement.
    *
-   * @example
+   * @example SDK usage
    * ```ts
    * const deploymentRun =
    *   await client.metadata.deploymentRuns.create({
@@ -43,6 +43,59 @@ export class DeploymentRuns extends APIResource {
    *     ],
    *   });
    * ```
+   *
+   * @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,
@@ -64,11 +117,39 @@ export class DeploymentRuns extends APIResource {
    *
    * Requires the Metadata entitlement.
    *
-   * @example
+   * @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);

package/src/resources/metadata/metadata.ts

@@ -42,14 +42,51 @@ export class Metadata extends APIResource {
 
   /**
    * Extract the company's selectable metadata components, optionally filtered by a
-   * search query.
+   * search query. Unreadable dependencies are omitted.
    *
    * Requires the Metadata entitlement.
    *
-   * @example
+   * @example SDK usage
    * ```ts
    * const response = await client.metadata.extract();
    * ```
+   *
+   * @example HTTP
+   * Representative request and response shapes.
+   * ```
+   * GET /metadata/extract/?q=q&limit=1 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
+   *
+   * {
+   *   "root_components": [
+   *     {
+   *       "name": "string",
+   *       "identifier": {}
+   *     }
+   *   ],
+   *   "component_configs": [
+   *     {
+   *       "type": "string"
+   *     }
+   *   ],
+   *   "install_order": [
+   *     {}
+   *   ],
+   *   "dependency_graph": {},
+   *   "external_managed_dependencies": [
+   *     {}
+   *   ],
+   *   "context_complete": false,
+   *   "context_warnings": [
+   *     "string"
+   *   ]
+   * }
+   * ```
    */
   extract(
     query: MetadataExtractParams | null | undefined = {},
@@ -59,16 +96,53 @@ export class Metadata extends APIResource {
   }
 
   /**
-   * Extract exact metadata components and their complete dependency closure.
+   * Extract exact metadata components and their readable dependency closure.
+   * Requested components that cannot be read return 403; unreadable dependencies are
+   * omitted.
    *
    * Requires the Metadata entitlement.
    *
-   * @example
+   * @example SDK usage
    * ```ts
    * const response = await client.metadata.extractByIdentifiers(
    *   { identifiers: [{ foo: 'bar' }] },
    * );
    * ```
+   *
+   * @example HTTP
+   * Representative request and response shapes.
+   * ```
+   * POST /metadata/extract/ HTTP/1.1
+   * Host: rest.ripplingapis.com
+   * Content-Type: application/json
+   * Accept: application/json
+   * Rippling-Api-Version: 2024-08-01
+   *
+   * {
+   *   "identifiers": [
+   *     {
+   *       "foo": "bar"
+   *     }
+   *   ]
+   * }
+   *
+   * HTTP/1.1 200 OK
+   * Content-Type: application/json
+   *
+   * {
+   *   "component_configs": [
+   *     {
+   *       "type": "string"
+   *     }
+   *   ],
+   *   "install_order": [
+   *     {}
+   *   ],
+   *   "external_managed_dependencies": [
+   *     {}
+   *   ]
+   * }
+   * ```
    */
   extractByIdentifiers(
     body: MetadataExtractByIdentifiersParams,
@@ -80,7 +154,8 @@ export class Metadata extends APIResource {
 
 export interface MetadataExtractResponse {
   /**
-   * Full component configs needed to recreate the selected roots.
+   * Readable component configs for the selected roots. Dependencies the caller
+   * cannot read are omitted, so the result may not be deployable as-is.
    */
   component_configs: Array<MetadataExtractResponse.ComponentConfig>;
 
@@ -100,7 +175,8 @@ export interface MetadataExtractResponse {
   root_components: Array<MetadataExtractResponse.RootComponent>;
 
   /**
-   * For search-backed extraction, whether contextual expansion completed.
+   * For search-backed extraction, whether contextual expansion completed without
+   * warnings or unreadable components being omitted.
    */
   context_complete?: boolean;
 
@@ -148,7 +224,8 @@ export namespace MetadataExtractResponse {
 
 export interface MetadataExtractByIdentifiersResponse {
   /**
-   * Full component configs needed to recreate the requested roots.
+   * Readable component configs for the requested roots. Unreadable dependencies are
+   * omitted, so the result may not be deployable as-is.
    */
   component_configs: Array<MetadataExtractByIdentifiersResponse.ComponentConfig>;
 

package/src/resources/metadata/schema.ts

@@ -13,12 +13,44 @@ export class Schema extends APIResource {
    *
    * Requires the Metadata entitlement.
    *
-   * @example
+   * @example SDK usage
    * ```ts
    * const schema = await client.metadata.schema.get({
    *   type: 'type',
    * });
    * ```
+   *
+   * @example HTTP
+   * Representative request and response shapes.
+   * ```
+   * GET /metadata/schema/?type=type 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
+   *
+   * {
+   *   "type": "string",
+   *   "display_name": "string",
+   *   "description": "string",
+   *   "config_schema": {},
+   *   "identifier_schema": {},
+   *   "usage_guide": "string",
+   *   "examples": [
+   *     {}
+   *   ],
+   *   "common_mistakes": [
+   *     {
+   *       "wrong": "string",
+   *       "right": "string",
+   *       "message": "string"
+   *     }
+   *   ],
+   *   "best_practices": "string"
+   * }
+   * ```
    */
   get(query: SchemaGetParams, options?: RequestOptions): APIPromise<SchemaGetResponse> {
     return this._client.get('/metadata/schema/', { query, ...options });

package/src/resources/metadata/types.ts

@@ -14,10 +14,32 @@ export class Types extends APIResource {
    *
    * Requires the Metadata entitlement.
    *
-   * @example
+   * @example SDK usage
    * ```ts
    * const types = await client.metadata.types.list();
    * ```
+   *
+   * @example HTTP
+   * Representative request and response shapes.
+   * ```
+   * GET /metadata/types/ 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
+   *
+   * {
+   *   "types": [
+   *     {
+   *       "type": "string",
+   *       "display_name": "string",
+   *       "description": "string"
+   *     }
+   *   ]
+   * }
+   * ```
    */
   list(options?: RequestOptions): APIPromise<TypeListResponse> {
     return this._client.get('/metadata/types/', options);

package/src/resources/metadata/validation-runs.ts

@@ -16,7 +16,7 @@ export class ValidationRuns extends APIResource {
    *
    * Requires the Metadata entitlement.
    *
-   * @example
+   * @example SDK usage
    * ```ts
    * const validationRun =
    *   await client.metadata.validationRuns.create({
@@ -43,6 +43,59 @@ export class ValidationRuns extends APIResource {
    *     ],
    *   });
    * ```
+   *
+   * @example HTTP
+   * Representative request and response shapes.
+   * ```
+   * POST /metadata/validation-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: ValidationRunCreateParams,
@@ -64,11 +117,39 @@ export class ValidationRuns extends APIResource {
    *
    * Requires the Metadata entitlement.
    *
-   * @example
+   * @example SDK usage
    * ```ts
    * const validationRun =
    *   await client.metadata.validationRuns.get('run_id');
    * ```
+   *
+   * @example HTTP
+   * Representative request and response shapes.
+   * ```
+   * GET /metadata/validation-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<ValidationRunGetResponse> {
     return this._client.get(path`/metadata/validation-runs/${runID}/`, options);