@runblackcat/sdk 0.1.0-alpha.44 → 0.1.0-alpha.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runblackcat/sdk",
-  "version": "0.1.0-alpha.44",
+  "version": "0.1.0-alpha.46",
   "description": "TypeScript SDK for the Blackcat sandbox gateway",
   "license": "Apache-2.0",
   "repository": "https://github.com/TreebeardHQ/blackcat",
@@ -15,6 +15,7 @@
   "files": ["sdk/dist", "README.md", "LICENSE"],
   "scripts": {
     "build": "bun build sdk/src/index.ts --outdir sdk/dist --target node --format esm && tsc -p sdk/tsconfig.build.json",
+    "prepack": "bun run build",
     "typecheck": "tsc -p sdk/tsconfig.json --noEmit",
     "test": "bun test sdk/src/index.test.ts"
   },

package/sdk/dist/index.d.ts

@@ -115,19 +115,41 @@ export type TemplateDockerSource = TemplateDockerSourceBase & (TemplatePreparati
     parameters?: never;
     prepare?: never;
 });
+/** A build whose image was uploaded rather than pulled from a registry. */
+export type TemplateUploadedImageSource = Omit<TemplateDockerSourceBase, "docker"> & {
+    docker: UploadedImageSource;
+} & (TemplatePreparation | {
+    parameters?: never;
+    prepare?: never;
+});
+export interface UploadedImageSource {
+    /** The `sha256:<hex>` digest returned by `templates.uploadImage`. */
+    uploaded_image: string;
+}
+export interface UploadedImage {
+    image: string;
+    bytes: number;
+    /** True when the control plane already held this exact image. */
+    unchanged: boolean;
+}
 export interface TemplateSandboxSource {
     sandbox: {
         id: string;
     };
-    /** The gateway derives these from the source sandbox when omitted. */
-    defaults?: TemplateDefaults;
-    /** The gateway derives this from the source template when omitted. */
+    /**
+     * A promoted sandbox keeps the machine dimensions it was captured on, so
+     * the gateway rejects `defaults` here. Omit `egress` to inherit the source
+     * template's policy.
+     */
     egress?: TemplateEgressPolicy;
 }
-export type TemplateSource = TemplateDockerSource | TemplateSandboxSource;
+export type TemplateSource = TemplateDockerSource | TemplateUploadedImageSource | TemplateSandboxSource;
 export type CreateTemplateInput = {
     name: string;
     source: TemplateDockerSource;
+} | {
+    name: string;
+    source: TemplateUploadedImageSource;
 } | {
     name?: string;
     source: TemplateSandboxSource;
@@ -186,24 +208,6 @@ export interface SandboxLeaseInput {
     /** Hard lifetime from acquisition, at least ttl_secs and at most 30 days. */
     renewable_for_secs: number;
 }
-export interface WarmInventoryMember {
-    id: string;
-    tenant: string;
-    template: string;
-    memory_mib: number;
-    vcpus: number;
-    node: string | null;
-    state: "Warming" | "Warm" | "Retiring";
-    snapshot: string | null;
-    last_active: SystemTimeValue;
-}
-export interface WarmTargetResponse {
-    enabled: boolean;
-    fleet_ready_limit: number;
-}
-export interface WarmInventoryResponse extends WarmTargetResponse {
-    members: WarmInventoryMember[];
-}
 /** Response returned by POST /v1/sandboxes (the gateway has no template field). */
 export type CreateSandboxResponse = {
     request_id: string;
@@ -256,6 +260,24 @@ export interface FleetInterruption {
 export interface FleetResponse {
     nodes: FleetNode[];
 }
+export interface TemplateRefreshPolicy {
+    interval_seconds: number;
+    plugin_installation: string;
+}
+export interface ConfigureTemplateResourceInput {
+    keep_versions: number;
+    refresh: TemplateRefreshPolicy | null;
+}
+export interface TemplateResource {
+    name: string;
+    current_version_id: string;
+    retention: {
+        keep_versions: number;
+    };
+    refresh: TemplateRefreshPolicy | null;
+    next_refresh_at: number | null;
+    last_refresh?: unknown;
+}
 export interface ExecInput {
     command: string;
     args: string[];
@@ -397,15 +419,25 @@ declare class TemplatesResource {
     constructor(client: GatewayClient);
     create(input: CreateTemplateInput): Promise<CreateTemplateResponse>;
     list(): Promise<Template[]>;
+    /**
+     * Upload a `docker save` / OCI archive as a build input. The image is named
+     * by its own content, so re-uploading the same bytes is free, and a build
+     * that names it needs no registry credentials anywhere.
+     */
+    uploadImage(archive: BodyInit, options?: {
+        signal?: AbortSignal;
+    }): Promise<UploadedImage>;
     activate(id: string): Promise<{
         id: string;
         name: string;
         version: number;
     }>;
-    configureWarm(id: string, input: {
-        enabled: boolean;
-    }): Promise<WarmTargetResponse>;
-    inspectWarm(id: string): Promise<WarmInventoryResponse>;
+}
+declare class TemplateResourcesResource {
+    private readonly client;
+    constructor(client: GatewayClient);
+    get(name: string): Promise<TemplateResource>;
+    configure(name: string, input: ConfigureTemplateResourceInput): Promise<TemplateResource>;
 }
 declare class TemplateBuildsResource {
     private readonly client;
@@ -478,8 +510,12 @@ declare class SandboxesResource {
     }): Promise<void>;
     writeFileStream(id: string, input: WriteFileStreamInput): Promise<number>;
     writeFile(id: string, input: WriteFileInput): Promise<number>;
+    /**
+     * Capture a restore point. The sandbox keeps running, and the returned
+     * template version is what it restarts from.
+     */
     snapshot(id: string): Promise<{
-        snapshot: string;
+        template: string;
     }>;
     hibernate(id: string, input?: {
         mode: HibernateMode;
@@ -489,6 +525,7 @@ declare class SandboxesResource {
 }
 export declare class BlackcatClient extends GatewayClient {
     readonly templates: TemplatesResource;
+    readonly templateResources: TemplateResourcesResource;
     readonly templateBuilds: TemplateBuildsResource;
     readonly sandboxes: SandboxesResource;
     readonly tokens: TokensResource;

package/sdk/dist/index.js

@@ -36,7 +36,7 @@ class BlackcatProtocolError extends Error {
     this.name = "BlackcatProtocolError";
   }
 }
-var MAX_FILE_CHUNK = 3 * 1024 * 1024;
+var MAX_FILE_CHUNK = 512 * 1024;
 var MAX_FILE_READ_CHUNK = 1e6;
 var MAX_PROCESS_STDIN = 512 * 1024;
 var MAX_EXEC_STDIN = 512 * 1024;
@@ -323,14 +323,25 @@ class TemplatesResource {
   list() {
     return this.client.json("GET", "/v1/templates", undefined, "token");
   }
+  async uploadImage(archive, options) {
+    const response = await this.client.raw("POST", "/v1/template-images", archive, "either", "application/octet-stream", false, options?.signal);
+    return await response.json();
+  }
   activate(id) {
     return this.client.json("POST", `/v1/templates/${pathSegment(id)}/activate`, undefined, "token");
   }
-  configureWarm(id, input) {
-    return this.client.json("PUT", `/v1/templates/${pathSegment(id)}/warm`, input, "token");
+}
+
+class TemplateResourcesResource {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  get(name) {
+    return this.client.json("GET", `/v1/template-resources/${pathSegment(name)}`, undefined, "token");
   }
-  inspectWarm(id) {
-    return this.client.json("GET", `/v1/templates/${pathSegment(id)}/warm`, undefined, "token");
+  configure(name, input) {
+    return this.client.json("PUT", `/v1/template-resources/${pathSegment(name)}`, input, "token");
   }
 }
 
@@ -599,6 +610,7 @@ class SandboxesResource {
 
 class BlackcatClient extends GatewayClient {
   templates;
+  templateResources;
   templateBuilds;
   sandboxes;
   tokens;
@@ -608,6 +620,7 @@ class BlackcatClient extends GatewayClient {
       assertSecureBlackcatGatewayUrl(options.baseUrl);
     super(options);
     this.templates = new TemplatesResource(this);
+    this.templateResources = new TemplateResourcesResource(this);
     this.templateBuilds = new TemplateBuildsResource(this);
     this.sandboxes = new SandboxesResource(this);
     this.tokens = new TokensResource(this);