@claxedo/sandbox-manager 0.7.0 → 0.10.0

package/dist/drivers/boat-client.d.ts

@@ -0,0 +1,95 @@
+import type { SandboxMachineClass } from "@claxedo/sandbox-contract";
+import { type SandboxStartLimit, type SandboxStartWindow } from "../lease-failure";
+export type BoatSandboxState = "init" | "provisioning" | "provisioned" | "cloning" | "ready" | "idle" | "running" | "archiving" | "archived" | "error" | "cancelled";
+/** `hydrated`: Boat has downloaded every file of the snapshot the sandbox started from (docs.boat.dev/readiness). */
+export type BoatSandbox = {
+    id: string;
+    state: BoatSandboxState;
+    hydrated: boolean;
+};
+export type BoatCommandResult = {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+};
+export type BoatFetch = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * What Boat's 429 `rate_limited` says about the account's start limit: the
+ * window that is used up, its limit, and the starts used of each window. It
+ * names no time the window reopens (2026-10-15), so none is kept.
+ */
+export type BoatStartLimit = {
+    window: SandboxStartWindow;
+    limit: number;
+    starts: Partial<Record<SandboxStartWindow, {
+        limit: number;
+        used: number;
+    }>>;
+};
+export declare class BoatApiError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    /** Boat answers 401 or 403 to the API key itself, never to a sandbox it was asked about. */
+    readonly providerKeyRefused: boolean;
+    /** Create, fork and resume each count as one start (Boat's own refusal, 2026-10-15). */
+    readonly providerRateLimited?: SandboxStartLimit;
+    readonly startLimit?: BoatStartLimit;
+    /** The state Boat's refusal gives the sandbox it refused, e.g. `archived` on a 400 `stop_failed` (2026-10-17). */
+    readonly sandboxState?: BoatSandboxState;
+    constructor(message: string, code: string, status?: number | undefined, refusal?: {
+        startLimit?: BoatStartLimit;
+        sandboxState?: BoatSandboxState;
+    });
+}
+export declare function invalid(): never;
+export declare function requiredText(value: unknown): string;
+export type BoatClientOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetchImpl?: BoatFetch;
+};
+export type BoatApi = ReturnType<typeof createBoatApi>;
+/** One Boat v1 call: the bearer key, the deadline, the bounded envelope, and the envelope types the call accepts. */
+export declare function createBoatApi(options: BoatClientOptions): (path: string, types: readonly string[], init?: {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}) => Promise<Record<string, unknown>>;
+export declare function createBoatClient(options: BoatClientOptions): {
+    /** `from` is a named snapshot or a share code (`bsh_…`) the sandbox starts from; omitted, Boat's base machine. */
+    create(input: {
+        idempotencyKey: string;
+        ttlSeconds: number | null;
+        type?: SandboxMachineClass;
+        from?: string;
+    }): Promise<BoatSandbox>;
+    get(id: string): Promise<BoatSandbox>;
+    /** `type` resumes the sandbox onto that machine size; omitted, it keeps the size it has (docs.boat.dev/machines/change-size). */
+    resume(id: string, input: {
+        ttlSeconds: number | null;
+        type?: SandboxMachineClass;
+    }): Promise<void>;
+    /**
+     * `ttlSeconds` sets the auto-stop deadline to now plus that many seconds; `null` removes it.
+     * Boat's reference example answers `sandbox.info`; the API answers `sandbox.updated` (2026-10-13).
+     */
+    update(id: string, input: {
+        ttlSeconds: number | null;
+    }): Promise<BoatSandbox>;
+    stop(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    writeFile(id: string, input: {
+        path: string;
+        content: string;
+    }): Promise<void>;
+    /** `ready` once a command runs, which Boat answers the moment the sandbox is ready; `starting` when Boat's hold ended first. */
+    whenReady(id: string): Promise<"ready" | "starting">;
+    command(id: string, input: {
+        command: string;
+        timeoutSeconds?: number;
+    }): Promise<BoatCommandResult>;
+};

package/dist/drivers/boat-named-snapshots.d.ts

@@ -0,0 +1,31 @@
+import { type BoatClientOptions } from "./boat-client";
+export type BoatNamedSnapshotStatus = "saving" | "ready" | "failed";
+export type BoatNamedSnapshot = {
+    name: string;
+    status: BoatNamedSnapshotStatus;
+    createdAt: string;
+};
+export type BoatSnapshotShare = {
+    id: string;
+    status: "active" | "revoked";
+    createdAt: string;
+};
+/** Boat's named snapshots and their share codes (docs.boat.dev/snapshots/templates). */
+export declare function createBoatNamedSnapshotClient(options: BoatClientOptions): {
+    /** A stopped sandbox is saved from its last snapshot; the save settles in the background. */
+    save(input: {
+        sandboxId: string;
+        name: string;
+    }): Promise<BoatNamedSnapshot>;
+    get(name: string): Promise<BoatNamedSnapshot | undefined>;
+    /** Newest first. */
+    list(): Promise<BoatNamedSnapshot[]>;
+    delete(name: string): Promise<void>;
+    /** Boat shows the code only in this answer and keeps a hash of it. */
+    share(name: string): Promise<{
+        shareCode: string;
+        share: BoatSnapshotShare;
+    }>;
+    shares(name: string): Promise<BoatSnapshotShare[]>;
+    revokeShare(name: string, shareId: string): Promise<void>;
+};

package/dist/drivers/boat-template.d.ts

@@ -0,0 +1,49 @@
+import { type BoatRuntimeTemplate, type BoatSandboxDriverOptions } from "./boat";
+import { type BoatClientOptions } from "./boat-client";
+export type BoatRuntimeTemplateOptions = BoatClientOptions & {
+    image: string;
+    /** Template names start with it, and pruning removes only names that do. */
+    prefix?: string;
+    /** How many templates of the prefix pruning keeps, the image's own and the newest others. */
+    keep?: number;
+    log?: (line: string) => void;
+    pollIntervalMs?: number;
+    hydrationTimeoutMs?: number;
+    stopTimeoutMs?: number;
+    saveTimeoutMs?: number;
+    driver?: Pick<BoatSandboxDriverOptions, "statePollMs" | "provisionTimeoutMs" | "healthIntervalMs" | "healthTimeoutMs">;
+};
+/** The image reference is content-addressed (its tag names the build), and the seeded trees are named by it, so it keys the template. */
+export declare function boatRuntimeTemplateName(image: string, prefix?: string): Promise<string>;
+/**
+ * Saves the template once per image: a ready template is reused, one still
+ * saving is waited for, and a missing or failed one is built on a builder
+ * sandbox that is deleted whatever the outcome.
+ */
+export declare function ensureBoatRuntimeTemplate(options: BoatRuntimeTemplateOptions): Promise<{
+    name: string;
+    built: boolean;
+}>;
+/**
+ * A new share code for the image's template, revoking none: until the deploy
+ * that carries it has succeeded, the running Worker creates with the code it
+ * holds. `shareId` names the code without being the secret.
+ */
+export declare function shareBoatRuntimeTemplate(options: BoatRuntimeTemplateOptions): Promise<{
+    template: BoatRuntimeTemplate;
+    shareId: string;
+}>;
+/**
+ * Run once the deploy carrying `deployedShareId` succeeded: every other code of
+ * the deployed image's template is revoked, those of earlier deploys and of
+ * deploys that failed alike.
+ */
+export declare function revokeBoatRuntimeTemplateShares(options: BoatRuntimeTemplateOptions, deployedShareId: string): Promise<string[]>;
+/**
+ * Run once the deploy of `options.image` succeeded, so the template it keeps
+ * is the one the live Worker creates from. Each template past Boat's ten free
+ * named snapshots costs $1.70 a month, and a template serves only the image it
+ * was built for, so templates of the prefix beyond the newest `keep` (the
+ * deployed image's among them) are removed; Boat removes their codes with them.
+ */
+export declare function pruneBoatRuntimeTemplates(options: BoatRuntimeTemplateOptions): Promise<string[]>;