@archildata/api-types 0.0.46 → 0.0.47

package/index.d.ts

@@ -418,6 +418,55 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/images": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Build a sandbox image
+         * @description Starts pulling and converting an OCI image, or joins the build already
+         *     running for it. Poll the image until it is `ready`, then pass its
+         *     `image_id` when creating a sandbox. Requesting the same `source` again
+         *     returns the same image. A finished tag rebuilds, since the tag may have
+         *     moved; until the rebuild is `ready`, new sandboxes boot the previous
+         *     `digest`. A finished digest reference returns immediately.
+         *     `registry_auth` pulls from a private registry, and a private image is
+         *     visible only to its account. The credentials are passed to the build
+         *     and never stored. A failed build, or a build whose runtime host does
+         *     not answer, builds again on the next request.
+         */
+        post: operations["createImage"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/images/{image_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a sandbox image
+         * @description Reports build progress. A build its runtime host failed or lost reports `failed` with `failure_reason: interrupted`; one whose host does not answer stays `building`. Request the image again to rebuild either.
+         */
+        get: operations["getImage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/sandboxes": {
         parameters: {
             query?: never;
@@ -993,8 +1042,10 @@ export interface components {
             idle_ttl_seconds: number;
             /** @description Maximum number of concurrently attached process sessions. Detached processes and one-shot process controls do not count. */
             max_concurrent_execs: number;
-            /** @description OCI reference requested when the sandbox was created. */
+            /** @description OCI reference requested when the sandbox was created. Empty for a sandbox created from `image_id`. */
             base_image: string;
+            /** @description Image digest the sandbox was created from, if any. */
+            image_digest?: string;
             /**
              * @description Sandbox CPU architecture.
              * @enum {string}
@@ -1120,6 +1171,44 @@ export interface components {
             success: boolean;
             data: components["schemas"]["SandboxConnection"];
         };
+        RegistryAuth: {
+            username: string;
+            /** @description Password or access token, such as a GitHub personal access token with `read:packages`. */
+            password: string;
+        };
+        CreateImageRequest: {
+            /** @description Linux OCI image reference. Docker shorthand and tags are accepted. */
+            source: string;
+            registry_auth?: components["schemas"]["RegistryAuth"];
+        };
+        /** @enum {string} */
+        ImageState: "building" | "ready" | "failed";
+        Image: {
+            image_id: string;
+            /** @description Normalized OCI reference the image is pulled from. */
+            source: string;
+            /** @description Whether the image is pulled with registry credentials. */
+            private: boolean;
+            status: components["schemas"]["ImageState"];
+            /** @description The most recent successful build. Sandboxes created from this `image_id` boot it, and keep it after the image is rebuilt. */
+            digest?: string;
+            /** @description The pulled manifest, as `repository@sha256:...`. */
+            canonical_source?: string;
+            /**
+             * @description Set when `failed`. `invalid_source`: the registry reported the image missing or denied access, so requesting it again will not help. `interrupted`: the build did not finish; request the image again.
+             * @enum {string}
+             */
+            failure_reason?: "invalid_source" | "interrupted";
+            /** Format: date-time */
+            created_at: string;
+            /** Format: date-time */
+            updated_at: string;
+        };
+        ApiResponse_Image: {
+            /** @example true */
+            success: boolean;
+            data: components["schemas"]["Image"];
+        };
         ApiResponse_Sandbox: {
             /** @example true */
             success: boolean;
@@ -1137,11 +1226,10 @@ export interface components {
             vcpu_count: number;
             /** @default 2048 */
             mem_size_mib: number;
-            /**
-             * @description Public Linux OCI image reference. Docker shorthand and tags are accepted; the selected platform manifest is pinned at creation.
-             * @default ubuntu:26.04
-             */
-            base_image: string;
+            /** @description Public Linux OCI image reference. Docker shorthand and tags are accepted; the selected platform manifest is pinned at creation. Defaults to `ubuntu:26.04` when neither this nor `image_id` is set. Mutually exclusive with `image_id`. */
+            base_image?: string;
+            /** @description An image from the images API, for images that need registry credentials. The sandbox boots the image's current `digest`. Mutually exclusive with `base_image`. */
+            image_id?: string;
             /** @description TCP ports to expose publicly when the sandbox is created. */
             ports?: number[];
             /**
@@ -2846,6 +2934,58 @@ export interface operations {
             500: components["responses"]["InternalError"];
         };
     };
+    createImage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["CreateImageRequest"];
+            };
+        };
+        responses: {
+            /** @description The image build is running or finished */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_Image"];
+                };
+            };
+            400: components["responses"]["ValidationError"];
+            401: components["responses"]["Unauthorized"];
+            500: components["responses"]["InternalError"];
+        };
+    };
+    getImage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                image_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The sandbox image */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiResponse_Image"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            500: components["responses"]["InternalError"];
+        };
+    };
     listSandboxes: {
         parameters: {
             query?: {
@@ -2900,7 +3040,7 @@ export interface operations {
             400: components["responses"]["ValidationError"];
             401: components["responses"]["Unauthorized"];
             404: components["responses"]["NotFound"];
-            /** @description The requested sandbox name already exists in the account */
+            /** @description The requested sandbox name already exists in the account, or the requested `image_id` has no finished build yet */
             409: {
                 headers: {
                     [name: string]: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archildata/api-types",
-  "version": "0.0.46",
+  "version": "0.0.47",
   "description": "API types for the Archil control plane",
   "type": "module",
   "types": "index.d.ts",