@solarisdk/core 0.1.0

package/dist/http.js

@@ -0,0 +1,106 @@
+// Shared HTTP transport for the SDK ⇆ Gateway REST API. Both `DesktopClient`
+// and `SandboxClient` delegate here, so there is ONE place that owns auth
+// headers, error mapping, retries/backoff, idempotency keys, and timeouts.
+//
+// Retry policy: idempotent requests (GET, DELETE, or any request carrying an
+// Idempotency-Key) are retried on network errors, HTTP 5xx, 429, and bodies
+// flagged `retryable`, with exponential backoff + jitter. Non-idempotent writes
+// are never silently retried (could double-create) — pass an idempotencyKey to
+// opt a create into safe retries.
+import { ConnectionError, mapGatewayError, PinetreeError } from "./errors.js";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A fresh idempotency key (UUID where available). */
+export function newIdempotencyKey() {
+    const c = globalThis.crypto;
+    return c?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2, 12)}`;
+}
+export class HttpTransport {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    maxRetries;
+    requestTimeoutMs;
+    retryDelayMs;
+    constructor(o) {
+        if (!o.apiKey)
+            throw new PinetreeError("HttpTransport requires an apiKey");
+        if (!o.baseUrl)
+            throw new PinetreeError("HttpTransport requires a baseUrl");
+        this.apiKey = o.apiKey;
+        this.baseUrl = o.baseUrl.replace(/\/+$/, "");
+        const f = o.fetch ?? globalThis.fetch;
+        if (typeof f !== "function") {
+            throw new PinetreeError("No fetch implementation available; pass `fetch` in options");
+        }
+        this.fetchImpl = f;
+        this.maxRetries = o.maxRetries ?? 3;
+        this.requestTimeoutMs = o.requestTimeoutMs ?? 30_000;
+        this.retryDelayMs = o.retryDelayMs;
+    }
+    /** `Authorization` header for handles + WS upgrades. */
+    authHeaders() {
+        return { Authorization: `Bearer ${this.apiKey}` };
+    }
+    /** ws:// (or wss://) origin derived from the gateway base URL. */
+    wsOrigin() {
+        return this.baseUrl.replace(/^http/, "ws");
+    }
+    async request(method, path, body, opts = {}) {
+        const idempotent = method === "GET" || method === "DELETE" || opts.idempotencyKey !== undefined;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+        };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (opts.idempotencyKey)
+            headers["Idempotency-Key"] = opts.idempotencyKey;
+        let attempt = 0;
+        for (;;) {
+            let res;
+            try {
+                res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+                    method,
+                    headers,
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                    signal: AbortSignal.timeout(this.requestTimeoutMs),
+                });
+            }
+            catch (err) {
+                if (idempotent && attempt < this.maxRetries) {
+                    await sleep(this.backoffMs(attempt++));
+                    continue;
+                }
+                throw new ConnectionError(`${method} ${path} failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (!res.ok) {
+                let errBody;
+                try {
+                    errBody = (await res.json());
+                }
+                catch {
+                    errBody = undefined;
+                }
+                // 5xx or an explicit `retryable` hint. NOT 429 — that's our
+                // ConcurrencyLimitError (org at its session cap); retrying won't help.
+                const retryable = res.status >= 500 || errBody?.retryable === true;
+                if (idempotent && retryable && attempt < this.maxRetries) {
+                    await sleep(this.backoffMs(attempt++));
+                    continue;
+                }
+                throw mapGatewayError(res.status, errBody);
+            }
+            // DELETE / empty bodies have no JSON.
+            const text = await res.text();
+            if (text.length === 0)
+                return undefined;
+            return JSON.parse(text);
+        }
+    }
+    backoffMs(attempt) {
+        if (this.retryDelayMs !== undefined)
+            return this.retryDelayMs;
+        return Math.min(1000 * 2 ** attempt, 8000) + Math.floor(Math.random() * 250);
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/image.d.ts

@@ -0,0 +1,85 @@
+export type ImageKind = "sandbox" | "desktop";
+/** A local file/dir to stage into the build context (under `template-files/`). */
+export interface LocalCopy {
+    src: string;
+    dest: string;
+}
+/**
+ * A single ordered build operation. This is the backend-agnostic, structured
+ * form of the build recipe: the snapshot-based exec orchestrator (approach A)
+ * runs these directly (no Dockerfile parsing), while the Docker rootfs-rebuild
+ * path (approach B) renders them back to a `Dockerfile.fragment`. See
+ * docs/TEMPLATE-BUILD-PIPELINE.md.
+ */
+export type ImageStep = {
+    op: "pip";
+    packages: string[];
+} | {
+    op: "run";
+    command: string;
+} | {
+    op: "env";
+    key: string;
+    value: string;
+} | {
+    op: "workdir";
+    dir: string;
+} | {
+    op: "entrypoint";
+    command: string[];
+} | {
+    op: "cmd";
+    command: string[];
+};
+/** The build-context inputs the pipeline consumes. */
+export interface CompiledImage {
+    kind: ImageKind;
+    /** Conceptual base image (informational; the pipeline layers on Dockerfile.base/.sandbox). */
+    base?: string;
+    /** Build on top of an existing named template instead of a raw base. */
+    fromTemplate?: string;
+    /** apt packages → `template.packages` (installed before `steps`). */
+    packages: string[];
+    /** Ordered post-apt operations (approach A: exec'd in order). */
+    steps: ImageStep[];
+    /** Extra Dockerfile instructions rendered from `steps` (approach B: `Dockerfile.fragment`). */
+    fragment: string;
+    /** Local files staged into the context (copied to `/` preserving paths). */
+    localFiles: LocalCopy[];
+}
+export declare class Image {
+    private _kind;
+    private _base;
+    private _fromTemplate;
+    private readonly _packages;
+    private readonly _steps;
+    private readonly _localFiles;
+    private constructor();
+    /** Start from a base OS image (e.g. `"ubuntu:22.04"`). */
+    static base(image: string): Image;
+    /** Start from an existing Pinetree template (e.g. `"workstation"`). */
+    static fromTemplate(name: string): Image;
+    /** Set the session kind this image is for (`"sandbox"` headless or `"desktop"` GUI). */
+    kind(k: ImageKind): this;
+    /** apt packages installed by the pipeline's apt step. */
+    aptInstall(pkgs: string[]): this;
+    /** `RUN pip3 install …`. */
+    pipInstall(pkgs: string[]): this;
+    /** One `RUN` per command. */
+    runCommands(...cmds: string[]): this;
+    /** `ENV` vars. */
+    env(vars: Record<string, string>): this;
+    /** `WORKDIR`. */
+    workdir(dir: string): this;
+    /** `ENTRYPOINT` (exec form). */
+    entrypoint(cmd: string[]): this;
+    /** `CMD` (exec form). */
+    cmd(cmd: string[]): this;
+    /** Stage a local file into the guest at `dest` (copied via `template-files/`). */
+    addLocalFile(src: string, dest: string): this;
+    /** Stage a local directory into the guest at `dest`. */
+    addLocalDir(src: string, dest: string): this;
+    /** Compile to the build-context inputs. Pure + offline. */
+    compile(): CompiledImage;
+}
+//# sourceMappingURL=image.d.ts.map

package/dist/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9C,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACjC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,GACvC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAErC,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,8FAA8F;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iEAAiE;IACjE,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,+FAA+F;IAC/F,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAwBD,qBAAa,KAAK;IAChB,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;IAE/C,OAAO;IAEP,0DAA0D;IAC1D,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK;IAMjC,uEAAuE;IACvE,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAMxC,wFAAwF;IACxF,IAAI,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI;IAKxB,yDAAyD;IACzD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAKhC,4BAA4B;IAC5B,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAKhC,6BAA6B;IAC7B,WAAW,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAKpC,kBAAkB;IAClB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAKvC,iBAAiB;IACjB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK1B,gCAAgC;IAChC,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAK/B,yBAAyB;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI;IAKxB,kFAAkF;IAClF,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAK7C,wDAAwD;IACxD,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAK5C,2DAA2D;IAC3D,OAAO,IAAI,aAAa;CAWzB"}

package/dist/image.js

@@ -0,0 +1,126 @@
+// Declarative Image builder (Daytona-style). A fluent chain that compiles to
+// the inputs our golden pipeline (`build-rootfs.sh`) already consumes per
+// template: an apt `packages` list, a `Dockerfile.fragment`, and local files
+// staged into `template-files/` (which the base Dockerfile COPYs to `/`).
+//
+//   const img = Image.base("ubuntu:22.04")
+//     .aptInstall(["ffmpeg"])
+//     .pipInstall(["pandas", "matplotlib"])
+//     .runCommands("curl -fsSL https://example.com/i.sh | sh")
+//     .addLocalDir("./assets", "/opt/assets")
+//     .env({ TZ: "UTC" })
+//     .workdir("/work");
+//   const tpl = await pt.templates.build(img, { name: "data-sci", kind: "sandbox" });
+//
+// `.compile()` emits a structured `steps[]` (typed ops the snapshot
+// exec-orchestrator runs directly) plus a byte-identical `Dockerfile.fragment`
+// (the Docker rebuild path). NOTE: `.compile()` is pure + offline (unit-tested);
+// actually BUILDING a template (pt.templates.build) requires the gateway
+// `/templates` backend — Phases 2-6 in docs/TEMPLATE-BUILD-PIPELINE.md.
+function envValue(v) {
+    return /\s/.test(v) ? JSON.stringify(v) : v;
+}
+/** Render one structured step to its Dockerfile line (approach B). */
+function renderDockerfile(step) {
+    switch (step.op) {
+        case "pip":
+            return `RUN pip3 install --no-cache-dir ${step.packages.join(" ")}`;
+        case "run":
+            return `RUN ${step.command}`;
+        case "env":
+            return `ENV ${step.key}=${envValue(step.value)}`;
+        case "workdir":
+            return `WORKDIR ${step.dir}`;
+        case "entrypoint":
+            return `ENTRYPOINT ${JSON.stringify(step.command)}`;
+        case "cmd":
+            return `CMD ${JSON.stringify(step.command)}`;
+    }
+}
+export class Image {
+    _kind = "sandbox";
+    _base;
+    _fromTemplate;
+    _packages = [];
+    _steps = [];
+    _localFiles = [];
+    constructor() { }
+    /** Start from a base OS image (e.g. `"ubuntu:22.04"`). */
+    static base(image) {
+        const i = new Image();
+        i._base = image;
+        return i;
+    }
+    /** Start from an existing Pinetree template (e.g. `"workstation"`). */
+    static fromTemplate(name) {
+        const i = new Image();
+        i._fromTemplate = name;
+        return i;
+    }
+    /** Set the session kind this image is for (`"sandbox"` headless or `"desktop"` GUI). */
+    kind(k) {
+        this._kind = k;
+        return this;
+    }
+    /** apt packages installed by the pipeline's apt step. */
+    aptInstall(pkgs) {
+        this._packages.push(...pkgs);
+        return this;
+    }
+    /** `RUN pip3 install …`. */
+    pipInstall(pkgs) {
+        if (pkgs.length)
+            this._steps.push({ op: "pip", packages: [...pkgs] });
+        return this;
+    }
+    /** One `RUN` per command. */
+    runCommands(...cmds) {
+        for (const c of cmds)
+            this._steps.push({ op: "run", command: c });
+        return this;
+    }
+    /** `ENV` vars. */
+    env(vars) {
+        for (const [k, v] of Object.entries(vars))
+            this._steps.push({ op: "env", key: k, value: v });
+        return this;
+    }
+    /** `WORKDIR`. */
+    workdir(dir) {
+        this._steps.push({ op: "workdir", dir });
+        return this;
+    }
+    /** `ENTRYPOINT` (exec form). */
+    entrypoint(cmd) {
+        this._steps.push({ op: "entrypoint", command: [...cmd] });
+        return this;
+    }
+    /** `CMD` (exec form). */
+    cmd(cmd) {
+        this._steps.push({ op: "cmd", command: [...cmd] });
+        return this;
+    }
+    /** Stage a local file into the guest at `dest` (copied via `template-files/`). */
+    addLocalFile(src, dest) {
+        this._localFiles.push({ src, dest });
+        return this;
+    }
+    /** Stage a local directory into the guest at `dest`. */
+    addLocalDir(src, dest) {
+        this._localFiles.push({ src, dest });
+        return this;
+    }
+    /** Compile to the build-context inputs. Pure + offline. */
+    compile() {
+        return {
+            kind: this._kind,
+            ...(this._base !== undefined ? { base: this._base } : {}),
+            ...(this._fromTemplate !== undefined ? { fromTemplate: this._fromTemplate } : {}),
+            packages: [...this._packages],
+            steps: this._steps.map((s) => ({ ...s })),
+            fragment: this._steps.length ? this._steps.map(renderDockerfile).join("\n") + "\n" : "",
+            localFiles: [...this._localFiles],
+        };
+    }
+}
+//# sourceMappingURL=image.js.map

package/dist/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../src/image.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { SessionHandle } from "./handle.js";
+export type { SessionConfig, SessionHooks } from "./handle.js";
+export { Desktop } from "./desktop.js";
+export type { DesktopConfig } from "./desktop.js";
+export { Sandbox } from "./sandbox.js";
+export { Image } from "./image.js";
+export type { CompiledImage, ImageKind, ImageStep, LocalCopy } from "./image.js";
+export { TemplateClient } from "./template-client.js";
+export type { TemplateClientOptions } from "./template-client.js";
+export { HttpTransport, newIdempotencyKey } from "./http.js";
+export { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, PinetreeError, PlanError, TimeoutError, } from "./errors.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEjF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,WAAW,EACX,SAAS,EACT,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,aAAa,EACb,SAAS,EACT,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,mBAAmB,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// @solarisdk/core — shared runtime for @solarisdk/desktop and @solarisdk/sandbox.
+export { SessionHandle } from "./handle.js";
+export { Desktop } from "./desktop.js";
+export { Sandbox } from "./sandbox.js";
+export { Image } from "./image.js";
+export { TemplateClient } from "./template-client.js";
+export { HttpTransport, newIdempotencyKey } from "./http.js";
+export { ActionError, AuthError, ConcurrencyLimitError, ConnectionError, GatewayError, NoCapacityError, PinetreeError, PlanError, TimeoutError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE7D,OAAO,EACL,WAAW,EACX,SAAS,EACT,qBAAqB,EACrB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,aAAa,EACb,SAAS,EACT,YAAY,GACb,MAAM,aAAa,CAAC"}

package/dist/sandbox.d.ts

@@ -0,0 +1,8 @@
+import { SessionHandle, type SessionConfig } from "./handle.js";
+import type { CreateSandboxResponse } from "./types.js";
+export declare class Sandbox extends SessionHandle {
+    /** The sandbox id (alias of {@link SessionHandle.id}). */
+    get sandboxId(): string;
+    constructor(session: CreateSandboxResponse, config?: SessionConfig);
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,qBAAa,OAAQ,SAAQ,aAAa;IACxC,0DAA0D;IAC1D,IAAI,SAAS,IAAI,MAAM,CAEtB;gBAEW,OAAO,EAAE,qBAAqB,EAAE,MAAM,GAAE,aAAkB;CAGvE"}

package/dist/sandbox.js

@@ -0,0 +1,15 @@
+// `Sandbox` — a handle to one live headless session. All of its surface lives
+// on the shared {@link SessionHandle} base (commands, pty, runCode, files,
+// volumes, metrics, snapshot, revert, pause/resume, setTimeout, env,
+// kill). Construct via {@link SandboxClient}.
+import { SessionHandle } from "./handle.js";
+export class Sandbox extends SessionHandle {
+    /** The sandbox id (alias of {@link SessionHandle.id}). */
+    get sandboxId() {
+        return this.id;
+    }
+    constructor(session, config = {}) {
+        super(session.sandboxId, session.controlUrl, session.expiresAt, config);
+    }
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2EAA2E;AAC3E,qEAAqE;AACrE,8CAA8C;AAE9C,OAAO,EAAE,aAAa,EAAsB,MAAM,aAAa,CAAC;AAGhE,MAAM,OAAO,OAAQ,SAAQ,aAAa;IACxC,0DAA0D;IAC1D,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;IAED,YAAY,OAA8B,EAAE,SAAwB,EAAE;QACpE,KAAK,CAAC,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC1E,CAAC;CACF"}

package/dist/template-client.d.ts

@@ -0,0 +1,35 @@
+import { Image, type CompiledImage } from "./image.js";
+import type { BuildTemplateOptions, BuildTemplateResponse, TemplateView } from "./types.js";
+export interface TemplateClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    fetch?: typeof fetch;
+    /** Injectable sleep (tests drive the clock); defaults to real setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class TemplateClient {
+    private readonly http;
+    private readonly sleep;
+    constructor(options: TemplateClientOptions);
+    /**
+     * Build a custom template from an {@link Image} (or a pre-{@link CompiledImage}).
+     * Kicks off the async gateway build then waits until it is `ready` (or throws
+     * on `failed`/timeout). Returns the final template view.
+     */
+    build(image: Image | CompiledImage, opts: BuildTemplateOptions): Promise<TemplateView>;
+    /** Start a build without waiting (`POST /templates`). Returns ids immediately. */
+    buildRaw(image: Image | CompiledImage, opts: BuildTemplateOptions): Promise<BuildTemplateResponse>;
+    /** List templates — built-ins + this org's custom templates (`GET /templates`). */
+    list(): Promise<TemplateView[]>;
+    /** Get one template's status/metadata (`GET /templates/:id`). */
+    get(templateId: string): Promise<TemplateView>;
+    /** Delete a custom template (`DELETE /templates/:id`; refused while live sessions depend on it). */
+    delete(templateId: string): Promise<void>;
+    /**
+     * Poll `GET /templates/:id` until it leaves `building`. Resolves on `ready`,
+     * throws on `failed`, throws on timeout. `onLog` is invoked best-effort as the
+     * gateway exposes build logs (a no-op until the log stream ships).
+     */
+    waitUntilReady(templateId: string, opts: BuildTemplateOptions): Promise<TemplateView>;
+}
+//# sourceMappingURL=template-client.d.ts.map

package/dist/template-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-client.d.ts","sourceRoot":"","sources":["../src/template-client.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EACV,oBAAoB,EAEpB,qBAAqB,EAErB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAOD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgB;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAE1C,OAAO,EAAE,qBAAqB;IAW1C;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC;IAO5F,kFAAkF;IAC5E,QAAQ,CACZ,KAAK,EAAE,KAAK,GAAG,aAAa,EAC5B,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,qBAAqB,CAAC;IAcjC,mFAAmF;IAC7E,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAKrC,iEAAiE;IACjE,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAO9C,oGAAoG;IAC9F,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C;;;;OAIG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC;CAsB5F"}

package/dist/template-client.js

@@ -0,0 +1,95 @@
+// `TemplateClient` — talks the SDK ⇆ Gateway `/templates` HTTP API and turns a
+// declarative {@link Image} into a reusable template a session can launch:
+//
+//   const img = Image.base("ubuntu:22.04").aptInstall(["ffmpeg"]).kind("sandbox");
+//   const tpl = await pt.templates.build(img, { name: "media" });
+//   const sbx = await pt.sandboxes.create({ template: tpl.templateId });
+//
+// `build()` POSTs the compiled recipe (async build on the gateway) and then
+// polls to completion. See docs/TEMPLATE-BUILD-PIPELINE.md.
+import { PinetreeError } from "./errors.js";
+import { HttpTransport, newIdempotencyKey } from "./http.js";
+import { Image } from "./image.js";
+const DEFAULT_BUILD_TIMEOUT_MS = 900_000; // 15 min
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class TemplateClient {
+    http;
+    sleep;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new PinetreeError("TemplateClient requires an apiKey");
+        if (!options.baseUrl)
+            throw new PinetreeError("TemplateClient requires a baseUrl");
+        this.sleep = options.sleep ?? realSleep;
+        this.http = new HttpTransport({
+            apiKey: options.apiKey,
+            baseUrl: options.baseUrl,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+        });
+    }
+    /**
+     * Build a custom template from an {@link Image} (or a pre-{@link CompiledImage}).
+     * Kicks off the async gateway build then waits until it is `ready` (or throws
+     * on `failed`/timeout). Returns the final template view.
+     */
+    async build(image, opts) {
+        if (!opts?.name)
+            throw new PinetreeError("templates.build requires a name");
+        const { buildId, templateId } = await this.buildRaw(image, opts);
+        void buildId; // reserved for future log-stream correlation
+        return this.waitUntilReady(templateId, opts);
+    }
+    /** Start a build without waiting (`POST /templates`). Returns ids immediately. */
+    async buildRaw(image, opts) {
+        const compiled = image instanceof Image ? image.compile() : image;
+        const body = {
+            name: opts.name,
+            kind: opts.kind ?? compiled.kind,
+            ...(opts.cpu !== undefined ? { cpu: opts.cpu } : {}),
+            ...(opts.memMb !== undefined ? { memMb: opts.memMb } : {}),
+            compiled,
+        };
+        return this.http.request("POST", "/templates", body, {
+            idempotencyKey: newIdempotencyKey(),
+        });
+    }
+    /** List templates — built-ins + this org's custom templates (`GET /templates`). */
+    async list() {
+        const res = await this.http.request("GET", "/templates");
+        return res.templates;
+    }
+    /** Get one template's status/metadata (`GET /templates/:id`). */
+    get(templateId) {
+        return this.http.request("GET", `/templates/${encodeURIComponent(templateId)}`);
+    }
+    /** Delete a custom template (`DELETE /templates/:id`; refused while live sessions depend on it). */
+    async delete(templateId) {
+        await this.http.request("DELETE", `/templates/${encodeURIComponent(templateId)}`);
+    }
+    /**
+     * Poll `GET /templates/:id` until it leaves `building`. Resolves on `ready`,
+     * throws on `failed`, throws on timeout. `onLog` is invoked best-effort as the
+     * gateway exposes build logs (a no-op until the log stream ships).
+     */
+    async waitUntilReady(templateId, opts) {
+        const timeoutMs = opts.timeoutMs ?? DEFAULT_BUILD_TIMEOUT_MS;
+        const pollMs = opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        const deadline = timeoutMs; // relative budget; decremented per poll (clock-free for tests)
+        let waited = 0;
+        for (;;) {
+            const view = await this.get(templateId);
+            if (view.status === "ready")
+                return view;
+            if (view.status === "failed") {
+                throw new PinetreeError(`template build failed for ${templateId}: ${view.error ?? "unknown error"}`);
+            }
+            if (waited >= deadline) {
+                throw new PinetreeError(`template build for ${templateId} did not complete within ${timeoutMs}ms`);
+            }
+            await this.sleep(pollMs);
+            waited += pollMs;
+        }
+    }
+}
+//# sourceMappingURL=template-client.js.map

package/dist/template-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-client.js","sourceRoot":"","sources":["../src/template-client.ts"],"names":[],"mappings":"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"}