// 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'; import { path } from '../internal/utils/path'; /** * Author, publish, and install Unity Packages V2 packages */ export class PackageInstalls extends APIResource { /** * Start installing a published package version asynchronously. Poll GET * /package-installs/{tracker_id}/ for completion. A post-install function failure * sets PackageInstallationTracker.status to COMPLETE_WITH_WARNINGS and puts * warning details in error_message; installed components and data written by the * function are retained. Read post_install_function_error_code to classify hook * failures. When a run was created, post_install_function_api_name and * post_install_function_run_id identify its Function execution. The activity is * not automatically retried. Repeating an unmanaged installation can run the hook * again and duplicate business data; hook authors must make initialization safe to * repeat. Versions with a post-install function run it automatically after * installation. The function runs with the installer's permissions and a token * valid for 16 minutes with scope `read write`; product permissions still apply. * * @example HTTP * Representative request and response shapes. * ``` * POST /package-installs/ HTTP/1.1 * Host: rest.ripplingapis.com * Content-Type: application/json * Accept: application/json * Rippling-Api-Version: 2024-08-01 * * { * "version_id": "version_id" * } * * HTTP/1.1 202 Accepted * Content-Type: application/json * * { * "id": "string", * "created_at": "string", * "updated_at": "string", * "package_version_id": "string", * "status": "IN_PROGRESS", * "error_message": "string", * "post_install_function_api_name": "string", * "post_install_function_run_id": "string", * "post_install_function_error_code": "POST_INSTALL_FUNCTION_MAPPING_MISSING", * "installation_record_id": "string", * "post_install_landing_component": {}, * "progress": [ * null * ] * } * ``` */ create( body: PackageInstallCreateParams, options?: RequestOptions, ): APIPromise { return this._client.post('/package-installs/', { body, ...options }); } /** * Retrieve the status of a package installation. * * @example HTTP * Representative request and response shapes. * ``` * GET /package-installs/{tracker_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", * "created_at": "string", * "updated_at": "string", * "package_version_id": "string", * "status": "IN_PROGRESS", * "error_message": "string", * "post_install_function_api_name": "string", * "post_install_function_run_id": "string", * "post_install_function_error_code": "POST_INSTALL_FUNCTION_MAPPING_MISSING", * "installation_record_id": "string", * "post_install_landing_component": {}, * "progress": [ * null * ] * } * ``` */ retrieve(trackerID: string, options?: RequestOptions): APIPromise { return this._client.get(path`/package-installs/${trackerID}/`, options); } } /** * Async package installation tracker for subscriber companies. */ export interface PackageInstallCreateResponse { /** * Identifier field */ id: string; /** * Record creation date */ created_at: string; /** * Record update date */ updated_at: string; /** * Failure details when status is FAILED, or non-fatal warning details when status * is COMPLETE_WITH_WARNINGS. Warnings do not roll back installed components or * data written by the function. */ error_message?: string; /** * Installation record ID when installation completes */ installation_record_id?: string; /** * The package version being installed */ package_version_id?: string; /** * The installed Function's API name for retrieving its execution. Null if no hook * was attempted or for older installations. Managed names include the package and * install namespace. */ post_install_function_api_name?: string | null; /** * The last installation hook failure. Wire values start with * POST*INSTALL_FUNCTION*: MAPPING_MISSING means the installed Function mapping is * absent; DEPLOYMENT_NOT_FOUND means no deployment exists; DEPLOYMENT_FAILED means * deployment failed; DEPLOYMENT_TIMEOUT means deployment readiness timed out; * PERMISSION_DENIED means installer authorization failed; EXECUTION_FAILED means * execution failed; EXECUTION_TIMEOUT means the hook activity timed out. Null on * success, when no hook was attempted, or for older installations. Managed * upgrades do not rerun the hook and preserve this outcome. */ post_install_function_error_code?: | 'POST_INSTALL_FUNCTION_MAPPING_MISSING' | 'POST_INSTALL_FUNCTION_DEPLOYMENT_NOT_FOUND' | 'POST_INSTALL_FUNCTION_DEPLOYMENT_FAILED' | 'POST_INSTALL_FUNCTION_DEPLOYMENT_TIMEOUT' | 'POST_INSTALL_FUNCTION_PERMISSION_DENIED' | 'POST_INSTALL_FUNCTION_EXECUTION_FAILED' | 'POST_INSTALL_FUNCTION_EXECUTION_TIMEOUT' | null; /** * The Function execution ID, recorded on success and failure when a run was * created. Use with post_install_function_api_name at GET * /functions/{function_api_name}/executions/{execution_id}/. Function execution * permissions still apply. Null if no run was created or for older installations. */ post_install_function_run_id?: string | null; /** * Component to open after installation completes */ post_install_landing_component?: unknown; /** * Installation progress entries */ progress?: Array; /** * Installation status (IN_PROGRESS, COMPLETE, COMPLETE_WITH_WARNINGS, or FAILED). * COMPLETE_WITH_WARNINGS means components were installed but post-processing or * the post-install function failed. Read error_message for warning details. */ status?: 'IN_PROGRESS' | 'COMPLETE' | 'COMPLETE_WITH_WARNINGS' | 'FAILED' | 'UNINSTALLED'; } /** * Async package installation tracker for subscriber companies. */ export interface PackageInstallRetrieveResponse { /** * Identifier field */ id: string; /** * Record creation date */ created_at: string; /** * Record update date */ updated_at: string; /** * Failure details when status is FAILED, or non-fatal warning details when status * is COMPLETE_WITH_WARNINGS. Warnings do not roll back installed components or * data written by the function. */ error_message?: string; /** * Installation record ID when installation completes */ installation_record_id?: string; /** * The package version being installed */ package_version_id?: string; /** * The installed Function's API name for retrieving its execution. Null if no hook * was attempted or for older installations. Managed names include the package and * install namespace. */ post_install_function_api_name?: string | null; /** * The last installation hook failure. Wire values start with * POST*INSTALL_FUNCTION*: MAPPING_MISSING means the installed Function mapping is * absent; DEPLOYMENT_NOT_FOUND means no deployment exists; DEPLOYMENT_FAILED means * deployment failed; DEPLOYMENT_TIMEOUT means deployment readiness timed out; * PERMISSION_DENIED means installer authorization failed; EXECUTION_FAILED means * execution failed; EXECUTION_TIMEOUT means the hook activity timed out. Null on * success, when no hook was attempted, or for older installations. Managed * upgrades do not rerun the hook and preserve this outcome. */ post_install_function_error_code?: | 'POST_INSTALL_FUNCTION_MAPPING_MISSING' | 'POST_INSTALL_FUNCTION_DEPLOYMENT_NOT_FOUND' | 'POST_INSTALL_FUNCTION_DEPLOYMENT_FAILED' | 'POST_INSTALL_FUNCTION_DEPLOYMENT_TIMEOUT' | 'POST_INSTALL_FUNCTION_PERMISSION_DENIED' | 'POST_INSTALL_FUNCTION_EXECUTION_FAILED' | 'POST_INSTALL_FUNCTION_EXECUTION_TIMEOUT' | null; /** * The Function execution ID, recorded on success and failure when a run was * created. Use with post_install_function_api_name at GET * /functions/{function_api_name}/executions/{execution_id}/. Function execution * permissions still apply. Null if no run was created or for older installations. */ post_install_function_run_id?: string | null; /** * Component to open after installation completes */ post_install_landing_component?: unknown; /** * Installation progress entries */ progress?: Array; /** * Installation status (IN_PROGRESS, COMPLETE, COMPLETE_WITH_WARNINGS, or FAILED). * COMPLETE_WITH_WARNINGS means components were installed but post-processing or * the post-install function failed. Read error_message for warning details. */ status?: 'IN_PROGRESS' | 'COMPLETE' | 'COMPLETE_WITH_WARNINGS' | 'FAILED' | 'UNINSTALLED'; } export interface PackageInstallCreateParams { /** * The published package version to install. */ version_id: string; /** * @deprecated Accepted for backward compatibility and ignored. Configured * post-install functions always run after installation. */ allow_post_install_function?: boolean; /** * Optional service-account role id. Omit it to install as the authenticated * caller. When set, the role must be a service account in the caller's company * that the caller is allowed to assume. A missing role, a role in another company, * a role that is not a service account, or a service account the caller cannot * assume returns HTTP 400. Use a service-account role id this caller is allowed to * assume. There is no public list endpoint for these ids. */ service_account_role_id?: string; } export declare namespace PackageInstalls { export { type PackageInstallCreateResponse as PackageInstallCreateResponse, type PackageInstallRetrieveResponse as PackageInstallRetrieveResponse, type PackageInstallCreateParams as PackageInstallCreateParams, }; }