@alibaba-group/opensandbox 0.1.0-dev1

package/dist/api/lifecycle.d.ts

@@ -0,0 +1,787 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/sandboxes": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List sandboxes
+         * @description List all sandboxes with optional filtering and pagination using query parameters.
+         *     All filter conditions use AND logic. Multiple `state` parameters use OR logic within states.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    /**
+                     * @description Filter by lifecycle state. Pass multiple times for OR logic.
+                     *     Example: `?state=Running&state=Paused`
+                     */
+                    state?: string[];
+                    /**
+                     * @description Arbitrary metadata key-value pairs for filtering，keys and values must be url encoded
+                     *     Example: To filter by `project=Apollo` and `note=Demo Test`: `?metadata=project%3DApollo%26note%3DDemo%252520Test`
+                     */
+                    metadata?: string;
+                    /** @description Page number for pagination */
+                    page?: number;
+                    /** @description Number of items per page */
+                    pageSize?: number;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Paginated collection of sandboxes */
+                200: {
+                    headers: {
+                        "X-Request-ID": components["headers"]["XRequestId"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ListSandboxesResponse"];
+                    };
+                };
+                400: components["responses"]["BadRequest"];
+                401: components["responses"]["Unauthorized"];
+                500: components["responses"]["InternalServerError"];
+            };
+        };
+        put?: never;
+        /**
+         * Create a sandbox from a container image
+         * @description Creates a new sandbox from a container image with optional resource limits,
+         *     environment variables, and metadata. Sandboxes are provisioned directly from
+         *     the specified image without requiring a pre-created template.
+         *
+         *     ## Authentication
+         *
+         *     API Key authentication is required via:
+         *     - `OPEN-SANDBOX-API-KEY: <api-key>` header
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["CreateSandboxRequest"];
+                };
+            };
+            responses: {
+                /**
+                 * @description Sandbox created and accepted for provisioning.
+                 *
+                 *     The returned sandbox includes:
+                 *     - `id`: Unique sandbox identifier
+                 *     - `status.state: "Pending"` (auto-starting provisioning)
+                 *     - `status.reason` and `status.message` indicating initialization stage
+                 *     - `metadata`, `expiresAt`, `createdAt`: Core sandbox information
+                 *
+                 *     Note: `image` and `updatedAt` are not included in the create response.
+                 *     Use GET /sandboxes/{sandboxId} to retrieve the complete sandbox information including image spec.
+                 *
+                 *     To track provisioning progress, poll GET /sandboxes/{sandboxId}.
+                 *     The sandbox will automatically transition to `Running` state once provisioning completes.
+                 */
+                202: {
+                    headers: {
+                        "X-Request-ID": components["headers"]["XRequestId"];
+                        Location: components["headers"]["Location"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CreateSandboxResponse"];
+                    };
+                };
+                400: components["responses"]["BadRequest"];
+                401: components["responses"]["Unauthorized"];
+                409: components["responses"]["Conflict"];
+                500: components["responses"]["InternalServerError"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandboxId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Unique sandbox identifier */
+                sandboxId: components["parameters"]["SandboxId"];
+            };
+            cookie?: never;
+        };
+        /**
+         * Fetch a sandbox by id
+         * @description Returns the complete sandbox information including:
+         *     - `id`, `status`, `metadata`, `expiresAt`, `createdAt`: Core information
+         *     - `image`: Container image specification (not included in create response)
+         *     - `entrypoint`: Entry process specification
+         *
+         *     This is the complete representation of the sandbox resource.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Unique sandbox identifier */
+                    sandboxId: components["parameters"]["SandboxId"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Sandbox current state and metadata */
+                200: {
+                    headers: {
+                        "X-Request-ID": components["headers"]["XRequestId"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Sandbox"];
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                403: components["responses"]["Forbidden"];
+                404: components["responses"]["NotFound"];
+                500: components["responses"]["InternalServerError"];
+            };
+        };
+        put?: never;
+        post?: never;
+        /**
+         * Delete a sandbox
+         * @description Delete a sandbox, terminating its execution. The sandbox will transition through Stopping state to Terminated.
+         */
+        delete: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Unique sandbox identifier */
+                    sandboxId: components["parameters"]["SandboxId"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /**
+                 * @description Sandbox successfully deleted.
+                 *
+                 *     Sandbox has been scheduled for termination and will transition to Stopping state, then Terminated.
+                 */
+                204: {
+                    headers: {
+                        "X-Request-ID": components["headers"]["XRequestId"];
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                401: components["responses"]["Unauthorized"];
+                403: components["responses"]["Forbidden"];
+                404: components["responses"]["NotFound"];
+                409: components["responses"]["Conflict"];
+                500: components["responses"]["InternalServerError"];
+            };
+        };
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandboxId}/pause": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Pause execution while retaining state
+         * @description Pause a running sandbox while preserving its state. Poll GET /sandboxes/{sandboxId} to track state transition to Paused.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Unique sandbox identifier */
+                    sandboxId: components["parameters"]["SandboxId"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /**
+                 * @description Pause operation accepted.
+                 *
+                 *     Sandbox will transition to Pausing state.
+                 *     Poll GET /sandboxes/{sandboxId} to track progress.
+                 */
+                202: {
+                    headers: {
+                        "X-Request-ID": components["headers"]["XRequestId"];
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                401: components["responses"]["Unauthorized"];
+                403: components["responses"]["Forbidden"];
+                404: components["responses"]["NotFound"];
+                409: components["responses"]["Conflict"];
+                500: components["responses"]["InternalServerError"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandboxId}/resume": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Resume a paused sandbox
+         * @description Resume execution of a paused sandbox. Poll GET /sandboxes/{sandboxId} to track state transition to Running.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Unique sandbox identifier */
+                    sandboxId: components["parameters"]["SandboxId"];
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /**
+                 * @description Resume operation accepted.
+                 *
+                 *     Sandbox will transition from Paused → Running.
+                 *     Poll GET /sandboxes/{sandboxId} to track progress.
+                 */
+                202: {
+                    headers: {
+                        "X-Request-ID": components["headers"]["XRequestId"];
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                401: components["responses"]["Unauthorized"];
+                403: components["responses"]["Forbidden"];
+                404: components["responses"]["NotFound"];
+                409: components["responses"]["Conflict"];
+                500: components["responses"]["InternalServerError"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandboxId}/renew-expiration": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Renew sandbox expiration
+         * @description Renew the absolute expiration time of a sandbox.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Unique sandbox identifier */
+                    sandboxId: components["parameters"]["SandboxId"];
+                };
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["RenewSandboxExpirationRequest"];
+                };
+            };
+            responses: {
+                /**
+                 * @description Sandbox expiration updated successfully.
+                 *
+                 *     Returns only the updated expiresAt field.
+                 */
+                200: {
+                    headers: {
+                        "X-Request-ID": components["headers"]["XRequestId"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["RenewSandboxExpirationResponse"];
+                    };
+                };
+                400: components["responses"]["BadRequest"];
+                401: components["responses"]["Unauthorized"];
+                403: components["responses"]["Forbidden"];
+                404: components["responses"]["NotFound"];
+                409: components["responses"]["Conflict"];
+                500: components["responses"]["InternalServerError"];
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/sandboxes/{sandboxId}/endpoints/{port}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get sandbox access endpoint
+         * @description Get the public access endpoint URL for accessing a service running on a specific port
+         *     within the sandbox. The service must be listening on the specified port inside
+         *     the sandbox for the endpoint to be available.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    /** @description Unique sandbox identifier */
+                    sandboxId: components["parameters"]["SandboxId"];
+                    /** @description Port number where the service is listening inside the sandbox */
+                    port: number;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /**
+                 * @description Endpoint retrieved successfully.
+                 *
+                 *     Returns the public URL for accessing the service on the specified port.
+                 */
+                200: {
+                    headers: {
+                        "X-Request-ID": components["headers"]["XRequestId"];
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["Endpoint"];
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                403: components["responses"]["Forbidden"];
+                404: components["responses"]["NotFound"];
+                500: components["responses"]["InternalServerError"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        ListSandboxesResponse: {
+            items: components["schemas"]["Sandbox"][];
+            pagination: components["schemas"]["PaginationInfo"];
+        };
+        /** @description Pagination metadata for list responses */
+        PaginationInfo: {
+            /** @description Current page number */
+            page: number;
+            /** @description Number of items per page */
+            pageSize: number;
+            /** @description Total number of items matching the filter */
+            totalItems: number;
+            /** @description Total number of pages */
+            totalPages: number;
+            /** @description Whether there are more pages after the current one */
+            hasNextPage: boolean;
+        };
+        /** @description Response from creating a new sandbox. Contains essential information without image and updatedAt. */
+        CreateSandboxResponse: {
+            /** @description Unique sandbox identifier */
+            id: string;
+            /** @description Current lifecycle status and detailed state information */
+            status: components["schemas"]["SandboxStatus"];
+            /** @description Custom metadata from creation request */
+            metadata?: {
+                [key: string]: string;
+            };
+            /**
+             * Format: date-time
+             * @description Timestamp when sandbox will auto-terminate
+             */
+            expiresAt: string;
+            /**
+             * Format: date-time
+             * @description Sandbox creation timestamp
+             */
+            createdAt: string;
+            /** @description Entry process specification from creation request */
+            entrypoint: string[];
+        };
+        /** @description Runtime execution environment provisioned from a container image */
+        Sandbox: {
+            /** @description Unique sandbox identifier */
+            id: string;
+            /**
+             * @description Container image specification used to provision this sandbox.
+             *     Only present in responses for GET/LIST operations. Not returned in createSandbox response.
+             */
+            image: components["schemas"]["ImageSpec"];
+            /** @description Current lifecycle status and detailed state information */
+            status: components["schemas"]["SandboxStatus"];
+            /** @description Custom metadata from creation request */
+            metadata?: {
+                [key: string]: string;
+            };
+            /**
+             * @description The command to execute as the sandbox's entry process.
+             *     Always present in responses since entrypoint is required in creation requests.
+             */
+            entrypoint: string[];
+            /**
+             * Format: date-time
+             * @description Timestamp when sandbox will auto-terminate
+             */
+            expiresAt: string;
+            /**
+             * Format: date-time
+             * @description Sandbox creation timestamp
+             */
+            createdAt: string;
+        };
+        /**
+         * @description High-level lifecycle state of the sandbox.
+         *
+         *     Common state values:
+         *     - Pending: Sandbox is being provisioned
+         *     - Running: Sandbox is running and ready to accept requests
+         *     - Pausing: Sandbox is in the process of pausing
+         *     - Paused: Sandbox has been paused while retaining its state
+         *     - Stopping: Sandbox is being terminated
+         *     - Terminated: Sandbox has been successfully terminated
+         *     - Failed: Sandbox encountered a critical error
+         *
+         *     State transitions:
+         *     - Pending → Running (after creation completes)
+         *     - Running → Pausing (when pause is requested)
+         *     - Pausing → Paused (pause operation completes)
+         *     - Paused → Running (when resume is requested)
+         *     - Running/Paused → Stopping (when kill is requested or TTL expires)
+         *     - Stopping → Terminated (kill/timeout operation completes)
+         *     - Pending/Running/Paused → Failed (on error)
+         *
+         *     Note: New state values may be added in future versions.
+         *     Clients should handle unknown state values gracefully.
+         */
+        SandboxState: string;
+        /** @description Detailed status information with lifecycle state and transition details */
+        SandboxStatus: {
+            /** @description Current lifecycle state of the sandbox */
+            state: components["schemas"]["SandboxState"];
+            /**
+             * @description Short machine-readable reason code for the current state.
+             *     Examples: "user_delete", "ttl_expiry", "provision_timeout", "runtime_error"
+             */
+            reason?: string;
+            /** @description Human-readable message describing the current state or reason for state transition */
+            message?: string;
+            /**
+             * Format: date-time
+             * @description Timestamp of the last state transition
+             */
+            lastTransitionAt?: string;
+        };
+        /**
+         * @description Container image specification for sandbox provisioning.
+         *
+         *     Supports public registry images and private registry images with authentication.
+         */
+        ImageSpec: {
+            /**
+             * @description Container image URI in standard format.
+             *
+             *     Examples:
+             *       - "python:3.11" (Docker Hub)
+             *       - "ubuntu:22.04"
+             *       - "gcr.io/my-project/model-server:v1.0"
+             *       - "private-registry.company.com:5000/app:latest"
+             */
+            uri: string;
+            /** @description Registry authentication credentials (required for private registries) */
+            auth?: {
+                /** @description Registry username or service account */
+                username?: string;
+                /** @description Registry password or authentication token */
+                password?: string;
+            };
+        };
+        /**
+         * @description Request to create a new sandbox from a container image.
+         *
+         *     **Note**: API Key authentication is required via the `OPEN-SANDBOX-API-KEY` header.
+         */
+        CreateSandboxRequest: {
+            /** @description Container image specification for the sandbox */
+            image: components["schemas"]["ImageSpec"];
+            /**
+             * @description Sandbox timeout in seconds. The sandbox will automatically terminate after this duration.
+             *     SDK clients should provide a default value (e.g., 3600 seconds / 1 hour).
+             */
+            timeout: number;
+            /**
+             * @description Runtime resource constraints for the sandbox instance.
+             *     SDK clients should provide sensible defaults (e.g., cpu: "500m", memory: "512Mi").
+             */
+            resourceLimits: components["schemas"]["ResourceLimits"];
+            /**
+             * @description Environment variables to inject into the sandbox runtime.
+             * @example {
+             *       "API_KEY": "secret-key",
+             *       "DEBUG": "true",
+             *       "LOG_LEVEL": "info"
+             *     }
+             */
+            env?: {
+                [key: string]: string;
+            };
+            /**
+             * @description Custom key-value metadata for management, filtering, and tagging.
+             *     Use "name" key for a human-readable identifier.
+             * @example {
+             *       "name": "Data Processing Sandbox",
+             *       "project": "data-processing",
+             *       "team": "ml",
+             *       "environment": "staging"
+             *     }
+             */
+            metadata?: {
+                [key: string]: string;
+            };
+            /**
+             * @description The command to execute as the sandbox's entry process (required).
+             *
+             *     Explicitly specifies the user's expected main process, allowing the sandbox management
+             *     service to reliably inject control processes before executing this command.
+             *
+             *     Format: [executable, arg1, arg2, ...]
+             *
+             *     Examples:
+             *     - ["python", "/app/main.py"]
+             *     - ["/bin/bash"]
+             *     - ["java", "-jar", "/app/app.jar"]
+             *     - ["node", "server.js"]
+             * @example [
+             *       "python",
+             *       "/app/main.py"
+             *     ]
+             */
+            entrypoint: string[];
+            /**
+             * @description Opaque container for provider-specific or transient parameters not supported by the core API.
+             *
+             *     **Note**: This field is reserved for internal features, experimental flags, or temporary behaviors. Standard parameters should be proposed as core API fields.
+             *
+             *     **Best Practices**:
+             *     - **Namespacing**: Use prefixed keys (e.g., `storage.id`) to prevent collisions.
+             *     - **Pass-through**: SDKs and middleware must treat this object as opaque and pass it through transparently.
+             */
+            extensions?: {
+                [key: string]: string;
+            };
+        };
+        /**
+         * @description Runtime resource constraints as key-value pairs. Similar to Kubernetes resource specifications,
+         *     allows flexible definition of resource limits. Common resource types include:
+         *     - `cpu`: CPU allocation in millicores (e.g., "250m" for 0.25 CPU cores)
+         *     - `memory`: Memory allocation in bytes or human-readable format (e.g., "512Mi", "1Gi")
+         *     - `gpu`: Number of GPU devices (e.g., "1")
+         *
+         *     New resource types can be added without API changes.
+         * @example {
+         *       "cpu": "500m",
+         *       "memory": "512Mi",
+         *       "gpu": "1"
+         *     }
+         */
+        ResourceLimits: {
+            [key: string]: string;
+        };
+        RenewSandboxExpirationRequest: {
+            /**
+             * Format: date-time
+             * @description New absolute expiration time in UTC (RFC 3339 format).
+             *     Must be in the future and after the current expiresAt time.
+             *
+             *     Example: "2025-11-16T14:30:45Z"
+             */
+            expiresAt: string;
+        };
+        RenewSandboxExpirationResponse: {
+            /**
+             * Format: date-time
+             * @description The new absolute expiration time in UTC (RFC 3339 format).
+             *
+             *     Example: "2025-11-16T14:30:45Z"
+             */
+            expiresAt: string;
+        };
+        /**
+         * @description Standard error response for all non-2xx HTTP responses.
+         *     HTTP status code indicates the error category; code and message provide details.
+         */
+        ErrorResponse: {
+            /**
+             * @description Machine-readable error code (e.g., INVALID_REQUEST, NOT_FOUND, INTERNAL_ERROR).
+             *     Use this for programmatic error handling.
+             */
+            code: string;
+            /** @description Human-readable error message describing what went wrong and how to fix it. */
+            message: string;
+        };
+        /**
+         * @description Endpoint for accessing a service running in the sandbox.
+         *     The service must be listening on the specified port inside the sandbox for the endpoint to be available.
+         */
+        Endpoint: {
+            /**
+             * @description Public URL to access the service from outside the sandbox.
+             *     Format: {endpoint-host}/sandboxes/{sandboxId}/port/{port}
+             *     Example: endpoint.opensandbox.io/sandboxes/abc123/port/8080
+             */
+            endpoint: string;
+        };
+    };
+    responses: {
+        /** @description Error response envelope */
+        Error: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description The request was invalid or malformed */
+        BadRequest: {
+            headers: {
+                "X-Request-ID": components["headers"]["XRequestId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description Authentication credentials are missing or invalid */
+        Unauthorized: {
+            headers: {
+                "X-Request-ID": components["headers"]["XRequestId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description The authenticated user lacks permission for this operation */
+        Forbidden: {
+            headers: {
+                "X-Request-ID": components["headers"]["XRequestId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description The requested resource does not exist */
+        NotFound: {
+            headers: {
+                "X-Request-ID": components["headers"]["XRequestId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description The operation conflicts with the current state */
+        Conflict: {
+            headers: {
+                "X-Request-ID": components["headers"]["XRequestId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+        /** @description An unexpected server error occurred */
+        InternalServerError: {
+            headers: {
+                "X-Request-ID": components["headers"]["XRequestId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ErrorResponse"];
+            };
+        };
+    };
+    parameters: {
+        /** @description Unique sandbox identifier */
+        SandboxId: string;
+    };
+    requestBodies: never;
+    headers: {
+        /** @description Unique request identifier for tracing */
+        XRequestId: string;
+        /** @description URI of the newly created or related resource */
+        Location: string;
+        /** @description Suggested delay in seconds before retrying */
+        RetryAfter: number;
+    };
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export type operations = Record<string, never>;
+//# sourceMappingURL=lifecycle.d.ts.map