@platinum-dev/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kortix AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @platinum-dev/sdk
+
+Typed TypeScript client for [Platinum](https://github.com/kortix-ai/platinum) —
+hardware-isolated sandbox microVMs (one Cloud Hypervisor VM per sandbox, sub-second
+boots via a warm pool).
+
+> **Not on npm yet.** Until the first publish, install from source:
+> `git clone` the repo and import `packages/sdk-ts/src/index.ts` directly
+> (Bun and ts-aware bundlers consume it as-is), or `bun run build` and import `dist/`.
+
+## Quickstart
+
+```ts
+import { Platinum } from '@platinum-dev/sdk';
+
+const dn = new Platinum({
+  token: process.env.PT_TOKEN!,          // API key (pt_live_…) — mint in the dashboard
+  url:   process.env.PT_API_URL,         // e.g. https://api.platinum.dev
+});
+
+// Create → running in one round-trip (server holds the POST until ready).
+const sbx = await dn.sandboxes.create(
+  { template: 'pt-base', env: { GREETING: 'hi' } },
+  { waitForRunning: true },
+);
+
+const r = await sbx.exec(['uname', '-a']);
+console.log(r.exit_code, r.stdout);
+
+await sbx.delete();
+```
+
+Expose a port in the same call (no second round-trip):
+
+```ts
+const sbx = await dn.sandboxes.create(
+  { template: 'pt-base', expose: [{ port: 8000, public: true }] },
+  { waitForRunning: true },
+);
+console.log(sbx.exposedUrl(8000));   // reachable preview URL
+```
+
+Build a custom image inline (cache-hit on repeat, built on first use):
+
+```ts
+import { Template, Platinum } from '@platinum-dev/sdk';
+
+const image = Template.fromPythonImage('3.12-slim').pipInstall(['fastapi', 'uvicorn']).workdir('/app');
+const sbx = await dn.sandboxes.create({ image }, { waitForRunning: true, waitTimeoutMs: 600_000 });
+```
+
+## Configuration
+
+| Option / env | Default | Meaning |
+|---|---|---|
+| `token` / `PT_TOKEN` | — (required) | API key `pt_live_…`, org-scoped bearer token |
+| `url` / `PT_API_URL` | `http://127.0.0.1:3000` | Control-plane URL |
+| `timeoutMs` | `60000` | Per-request timeout (file transfer calls override per call) |
+
+Server-side runtimes only (Node ≥ 20, Bun) — never ship an API key to a browser.
+
+## What's wrapped today
+
+| Area | Methods |
+|---|---|
+| Sandboxes | `create` (inline image, inline expose, server-side wait) · `get` · `list` · `delete` · `rename` |
+| Lifecycle | `pause` · `resume` · `fork` · `snapshot` · `archive` · `backup` · `waitRunning` · `refresh` |
+| Execution | `exec(argv)` · `sh(script)` · `runCode(code, {lang})` — python/bash/node/sh |
+| Networking | `expose(port)` · `unexpose(port)` · `exposedUrl(port)` |
+| Files (vsock) | `files.read/write/delete/list/stat/mkdir` — small files anywhere in the guest FS |
+| Share (virtio-fs) | `share.get/put/list/stat/mkdir/delete/info` — bulk transfer, works while paused |
+| Platform | `templates.list` · `Template` builder · `regions.list` · `me()` · `health.check` |
+
+Not wrapped yet (REST endpoints exist; wrappers are on the roadmap): `stop`/`start`,
+`clone`, `restore`, snapshot listing/deletion, `resize`, `migrate`, ssh-keys,
+egress policy, `files find/grep/replace/watch`, metrics, usage, interactive
+terminal (WebSocket), volumes, API-key management, webhooks, audit logs.
+
+## Limits worth knowing (honest edition)
+
+- **`files.write` bodies must stay ≤ 16 MiB** — larger writes currently truncate and
+  fail through the vsock path. Use `share.put` for anything big (verified fine to
+  hundreds of MiB) and for bulk trees.
+- **`exec`/`runCode` are buffered**, not streaming: output arrives after the command
+  exits. Default timeout 30 s — pass `timeoutMs` for longer runs. `runCode` source is
+  capped at 1 MiB.
+- **The default `pt-base` template is busybox-based** — no git, pip, node, or even the
+  `httpd` applet inside (`nc` and `wget` are available). Use an inline `image`/template
+  built from a real distro image when you need tooling.
+- **Background processes are reaped when their `exec` call returns.** To leave a server
+  running (e.g. before hitting an exposed port), daemonize it:
+  `setsid sh -c '<server loop>' >/dev/null 2>&1 < /dev/null &` — see
+  [`examples/03-expose-service.ts`](./examples/03-expose-service.ts).
+- Errors throw `PlatinumError` with `.status` (HTTP status; `0` for non-HTTP failures —
+  a finer-grained error taxonomy is planned pre-1.0).
+
+## Examples
+
+Runnable scripts in [`examples/`](./examples): create→exec→delete, files vs share
+(including the 16 MiB boundary), expose + fetch a live service.
+
+```sh
+PT_API_URL=… PT_TOKEN=… bun examples/01-create-exec-delete.ts
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,340 @@
+export interface PlatinumOptions {
+    apiUrl?: string;
+    url?: string;
+    token: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+export type SandboxType = 'persistent' | 'ephemeral';
+export type ExecLang = 'python' | 'bash' | 'node' | 'sh';
+/** Inline declarative image spec — alternative to `template`. Mirror of
+ *  `POST /v1/templates/from-spec` body, minus `name`/`version` (Platinum
+ *  derives `inline-<hash>` deterministically). Identical specs across any
+ *  caller dedupe to one cached template. */
+export interface SandboxImageSpec {
+    base_image: string;
+    steps?: Array<Record<string, unknown>>;
+    entrypoint?: string;
+    ready_cmd?: string;
+    default_cpu?: number;
+    default_ram_mb?: number;
+    default_disk_gb?: number;
+    size_mb?: number;
+}
+export interface SandboxSpec {
+    /** Optional human-friendly label. If omitted, the sandbox id is used as the
+     *  display name. Must be unique among your org's active sandboxes (reusable
+     *  once a sandbox is destroyed); a clash returns 409. */
+    name?: string;
+    /** Pre-built template — name or `tpl_<ULID>`. Mutually exclusive with `image`. */
+    template?: string;
+    /** Inline image — either a `Template` builder instance OR a raw `SandboxImageSpec`.
+     *  Platinum hashes the spec, cache-hits a prior build or materializes a new
+     *  template on-demand, then boots the sandbox in one call. With
+     *  `waitForRunning: true`, the create resolves when the VM is ready. */
+    image?: SandboxImageSpec | {
+        toImageSpec(): Record<string, unknown>;
+    };
+    /** persistent (default) | ephemeral (auto-stop 15m, archive 7d, delete 30d). */
+    type?: SandboxType;
+    /** Pin to a specific region (must have at least one ready host). */
+    region?: string;
+    cpu?: number;
+    ram_mb?: number;
+    disk_gb?: number;
+    gpus?: number;
+    /** Env vars — written to /etc/environment on boot AND set on the running guest. */
+    env?: Record<string, string>;
+    /** Alias of `env` for E2B compatibility. Both are merged. */
+    envVars?: Record<string, string>;
+    /** Pre-existing volume IDs to attach at create-time. */
+    volume_ids?: string[];
+    /** OpenSSH public keys, one per line — written to /root/.ssh/authorized_keys. */
+    ssh_keys?: string[];
+    /** Default language for `runCode` calls. */
+    language?: ExecLang;
+    /** Auto-lifecycle overrides — 0 = disabled. Defaults set by `type`. */
+    auto_stop_minutes?: number;
+    auto_archive_days?: number;
+    auto_delete_days?: number;
+    /** Arbitrary metadata — surfaced on GET /v1/sandboxes/:id. */
+    metadata?: Record<string, unknown>;
+    /** Inline expose: same as POST /v1/sandboxes/:id/expose but folded into
+     *  the create response, saving one round-trip. With `waitForRunning`,
+     *  the spawn → reachable URL is a single Atlantic RTT. Max 8 entries. */
+    expose?: Array<{
+        port: number;
+        public?: boolean;
+        ttl_seconds?: number;
+    }>;
+}
+export interface SandboxState {
+    id: string;
+    /** Display label, or null when none was set (fall back to `id`). */
+    name: string | null;
+    orgId: string;
+    templateId: string;
+    hostId: string | null;
+    state: 'pending' | 'provisioning' | 'starting' | 'running' | 'stopping' | 'stopped' | 'resuming' | 'archived' | 'failed-provision' | 'failed-start' | 'lost' | 'deleted';
+    type?: SandboxType;
+    region: string | null;
+    cpu: number;
+    ramMb: number;
+    diskGb: number;
+    vsockCid: number | null;
+    internalIp: string | null;
+    exposedPorts: number[];
+    metadata: Record<string, unknown>;
+    errorMessage: string | null;
+    autoStopMinutes?: number;
+    autoArchiveDays?: number;
+    autoDeleteDays?: number;
+    lastActivityAt?: string | null;
+    createdAt: string;
+    startedAt: string | null;
+    stoppedAt: string | null;
+    deletedAt: string | null;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exit_code: number;
+    error?: string;
+}
+export interface ExposeResult {
+    url: string;
+    port: number;
+    sandbox_id: string;
+    token?: string;
+    public: boolean;
+}
+export interface SnapshotResult {
+    id: string;
+    size_bytes: number;
+    took_ms: number;
+    signed?: boolean;
+}
+export interface ForkResult {
+    id: string;
+    parent_id: string;
+    state: string;
+}
+export interface ShareEntry {
+    name: string;
+    size: number;
+    is_dir: boolean;
+    mode: string;
+    mtime_ms: number;
+}
+export interface ShareListResult {
+    entries: ShareEntry[];
+    path: string;
+}
+export interface ShareStatResult {
+    size: number;
+    is_dir: boolean;
+    mode: string;
+    mtime_ms: number;
+}
+export interface SharePutResult {
+    path: string;
+    bytes: number;
+}
+export interface ShareInfo {
+    guest_mount: string;
+    sandbox_id: string;
+    fs_type: 'virtio-fs';
+}
+export interface RegionInfo {
+    region: string;
+    hosts: number;
+}
+declare class PlatinumError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message: string);
+}
+export { PlatinumError };
+export declare class Platinum {
+    readonly apiUrl: string;
+    readonly token: string;
+    private readonly _fetch;
+    readonly timeoutMs: number;
+    constructor(opts: PlatinumOptions);
+    request<T = unknown>(method: string, path: string, body?: unknown, opts?: {
+        timeoutMs?: number;
+        rawBody?: Uint8Array | string | ArrayBuffer | Blob;
+        rawResponse?: boolean;
+        query?: Record<string, string | number | boolean | undefined>;
+    }): Promise<T>;
+    readonly sandboxes: {
+        /**
+         * Create a sandbox. Pass `template` (pre-built name/id) or `image`
+         * (inline spec — either a `Template` builder or raw `SandboxImageSpec`).
+         *
+         * With `waitForRunning: true` (or `waitTimeoutMs` set), the server holds
+         * the POST open until the sandbox reaches `running` — single Atlantic
+         * RTT, no client-side polling. Inline-image creates pay the build cost
+         * the first time and cache-hit thereafter, so bump the timeout when you
+         * expect a fresh build (default 60s; recommend 600000 for inline).
+         */
+        create: (spec: SandboxSpec, opts?: {
+            waitForRunning?: boolean;
+            waitTimeoutMs?: number;
+        }) => Promise<Sandbox>;
+        get: (id: string) => Promise<SandboxState>;
+        list: (opts?: {
+            limit?: number;
+            offset?: number;
+            state?: string;
+        }) => Promise<{
+            rows: SandboxState[];
+            total: number;
+            has_more: boolean;
+        }>;
+        delete: (id: string) => Promise<void>;
+        /** Set or clear a sandbox's display label by id. Pass null/'' to clear it.
+         *  Throws PlatinumError(409) if another active sandbox already uses the name. */
+        rename: (id: string, name: string | null) => Promise<SandboxState>;
+    };
+    readonly templates: {
+        list: () => Promise<Array<{
+            id: string;
+            name: string;
+            version: string;
+            state: string;
+            defaultCpu?: number;
+            defaultRamMb?: number;
+            defaultDiskGb?: number;
+            region?: string | null;
+        }>>;
+    };
+    readonly regions: {
+        /** GET /v1/regions — regions with at least one ready host. */
+        list: () => Promise<RegionInfo[]>;
+    };
+    readonly health: {
+        check: () => Promise<{
+            status: string;
+            ts: string;
+        }>;
+    };
+    /** Identity + role of the current bearer. */
+    me(): Promise<{
+        orgId: string;
+        role: 'admin' | 'org';
+        userId?: string;
+        orgRole?: 'owner' | 'admin' | 'member';
+    }>;
+}
+export interface SandboxInit {
+    state?: string;
+    name?: string | null;
+    hostId?: string | null;
+    warm?: boolean;
+    /** Ports the create() call already exposed via the inline `expose:` field
+     *  on the spawn request. Skips a follow-up POST /v1/sandboxes/:id/expose. */
+    exposed?: Array<{
+        port: number;
+        url: string;
+        token?: string;
+        public: boolean;
+    }>;
+}
+export declare class Sandbox {
+    readonly client: Platinum;
+    readonly id: string;
+    /** True if the create() returned a warm-pool VM (claim, not spawn). */
+    readonly warm: boolean;
+    /** Display label set at create (or via .rename()), or null if none. */
+    name: string | null;
+    /** Host that runs this sandbox — may change on cross-host resume. */
+    hostId: string | null;
+    /** Ports that came pre-exposed in the create response (inline `expose:`).
+     *  Populated only when spec.expose was set AND state reached `running`. */
+    readonly exposed: ReadonlyArray<{
+        port: number;
+        url: string;
+        token?: string;
+        public: boolean;
+    }>;
+    constructor(client: Platinum, id: string, init?: SandboxInit);
+    /** Convenience: URL of a port from the inline expose, or null if it
+     *  wasn't pre-exposed. For ports added after create, call .expose(). */
+    exposedUrl(port: number): string | null;
+    refresh(): Promise<SandboxState>;
+    /** Block until the sandbox reaches state='running'. */
+    waitRunning(opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<SandboxState>;
+    delete(): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    fork(): Promise<ForkResult>;
+    snapshot(opts?: {
+        name?: string;
+    }): Promise<SnapshotResult>;
+    archive(): Promise<void>;
+    /** Set or clear this sandbox's display label. Pass null/'' to clear it (the
+     *  id is shown again). Throws PlatinumError(409) if another active sandbox in
+     *  the org already uses the name. Returns the updated sandbox state. */
+    rename(name: string | null): Promise<SandboxState>;
+    backup(): Promise<{
+        id: string;
+        backup_state: string;
+    }>;
+    exec(cmd: string[], opts?: {
+        timeoutMs?: number;
+    }): Promise<ExecResult>;
+    /** Wrap a shell script — sugar for exec(['sh','-c', script]). */
+    sh(script: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<ExecResult>;
+    /** POST /v1/sandboxes/:id/run-code — run a snippet in a given language. */
+    runCode(code: string, opts?: {
+        lang?: ExecLang;
+        timeoutMs?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exit_code: number;
+    }>;
+    expose(port: number): Promise<ExposeResult>;
+    unexpose(port: number): Promise<void>;
+    readonly files: {
+        read: (path: string) => Promise<Uint8Array>;
+        write: (path: string, body: Uint8Array | string | ArrayBuffer | Blob) => Promise<void>;
+        delete: (path: string) => Promise<void>;
+        list: (path: string) => Promise<Array<{
+            name: string;
+            size: number;
+            mode: number;
+            is_dir: boolean;
+        }>>;
+        stat: (path: string) => Promise<{
+            size: number;
+            mode: string;
+            mtime_ms: number;
+        }>;
+        mkdir: (path: string) => Promise<void>;
+    };
+    readonly share: {
+        info: () => Promise<ShareInfo>;
+        list: (path?: string) => Promise<ShareListResult>;
+        stat: (path: string) => Promise<ShareStatResult>;
+        get: (path: string, opts?: {
+            timeoutMs?: number;
+        }) => Promise<Uint8Array>;
+        put: (path: string, body: Uint8Array | string | ArrayBuffer | Blob, opts?: {
+            timeoutMs?: number;
+        }) => Promise<SharePutResult>;
+        mkdir: (path: string) => Promise<void>;
+        delete: (path: string, opts?: {
+            recursive?: boolean;
+        }) => Promise<void>;
+    };
+}
+export { Template } from './template';
+export type { BuildStep, BuildOpts, BuildResult } from './template';
+export type { components as Schemas, paths as ApiPaths, operations as ApiOperations } from './generated/schema';

package/dist/index.js

@@ -0,0 +1,362 @@
+// src/template.ts
+import { readFileSync } from "node:fs";
+
+class Template {
+  base;
+  steps = [];
+  _entrypoint;
+  _readyCmd;
+  constructor(base) {
+    this.base = base;
+  }
+  static fromImage(ref) {
+    return new Template(ref);
+  }
+  static fromPythonImage(version) {
+    return new Template(`python:${version}`);
+  }
+  static fromNodeImage(version) {
+    return new Template(`node:${version}`);
+  }
+  static fromBunImage(version) {
+    return new Template(`oven/bun:${version}`);
+  }
+  static fromUbuntuImage(version) {
+    return new Template(`ubuntu:${version}`);
+  }
+  static fromDebianImage(version) {
+    return new Template(`debian:${version}`);
+  }
+  static fromAlpineImage(version) {
+    return new Template(`alpine:${version}`);
+  }
+  env(key, value) {
+    this.steps.push({ op: "env", key, value });
+    return this;
+  }
+  workdir(path) {
+    this.steps.push({ op: "workdir", path });
+    return this;
+  }
+  user(user) {
+    this.steps.push({ op: "user", user });
+    return this;
+  }
+  runCmd(cmd) {
+    this.steps.push({ op: "run", cmd });
+    return this;
+  }
+  pipInstall(packages) {
+    this.steps.push({ op: "pip", packages });
+    return this;
+  }
+  npmInstall(packages) {
+    this.steps.push({ op: "npm", packages });
+    return this;
+  }
+  aptInstall(packages) {
+    this.steps.push({ op: "apt", packages });
+    return this;
+  }
+  copy(src, dst, mode) {
+    const raw = typeof src === "string" ? readFileSync(src) : src;
+    if (raw.length > 256 * 1024)
+      throw new Error("copy(): file too large for inline (>256 KiB). Use a separate file PUT after build.");
+    this.steps.push({ op: "copy", content_b64: raw.toString("base64"), dst, mode });
+    return this;
+  }
+  entrypoint(cmd) {
+    this._entrypoint = cmd;
+    return this;
+  }
+  readyCmd(cmd) {
+    this._readyCmd = cmd;
+    return this;
+  }
+  toSpec(opts) {
+    return {
+      name: opts.name,
+      version: opts.version ?? "1.0.0",
+      base_image: this.base,
+      steps: this.steps,
+      entrypoint: this._entrypoint,
+      ready_cmd: this._readyCmd,
+      default_cpu: opts.default_cpu ?? 1,
+      default_ram_mb: opts.default_ram_mb ?? 512,
+      default_disk_gb: opts.default_disk_gb ?? 2,
+      size_mb: opts.size_mb ?? 1024
+    };
+  }
+  toImageSpec(opts) {
+    return {
+      base_image: this.base,
+      steps: this.steps,
+      entrypoint: this._entrypoint,
+      ready_cmd: this._readyCmd,
+      default_cpu: opts?.default_cpu,
+      default_ram_mb: opts?.default_ram_mb,
+      default_disk_gb: opts?.default_disk_gb,
+      size_mb: opts?.size_mb
+    };
+  }
+  async build(dn, opts) {
+    const r = await fetch(`${dn.url}/v1/templates/from-spec`, {
+      method: "POST",
+      headers: { Authorization: "Bearer " + dn.token, "Content-Type": "application/json" },
+      body: JSON.stringify(this.toSpec(opts))
+    });
+    const j = await r.json();
+    if (!r.ok)
+      throw new Error(`build queue: ${r.status} ${j.error || ""}`);
+    const id = j.id;
+    const waitMs = opts.wait_ms ?? 5 * 60000;
+    if (waitMs === 0)
+      return { id, name: opts.name, state: "building" };
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline) {
+      const list = await fetch(`${dn.url}/v1/templates`, { headers: { Authorization: "Bearer " + dn.token } });
+      const all = await list.json();
+      const me = all.find((t) => t.id === id);
+      if (me && (me.state === "ready" || me.state === "failed")) {
+        return { id, name: opts.name, state: me.state, build_logs: me.buildLogs ?? me.build_logs, content_hash: me.contentHash ?? me.content_hash };
+      }
+      await new Promise((res) => setTimeout(res, 3000));
+    }
+    return { id, name: opts.name, state: "building" };
+  }
+}
+
+// src/index.ts
+class PlatinumError extends Error {
+  status;
+  body;
+  constructor(status, body, message) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "PlatinumError";
+  }
+}
+class Platinum {
+  apiUrl;
+  token;
+  _fetch;
+  timeoutMs;
+  constructor(opts) {
+    this.apiUrl = (opts.apiUrl ?? opts.url ?? (typeof process !== "undefined" ? process.env?.PT_API_URL : "") ?? "http://127.0.0.1:3000").replace(/\/+$/, "");
+    this.token = opts.token;
+    this._fetch = opts.fetch ?? fetch;
+    this.timeoutMs = opts.timeoutMs ?? 60000;
+  }
+  async request(method, path, body, opts) {
+    const ctl = new AbortController;
+    const timer = setTimeout(() => ctl.abort(), opts?.timeoutMs ?? this.timeoutMs);
+    try {
+      const q = opts?.query ? "?" + Object.entries(opts.query).filter(([, v]) => v !== undefined && v !== "").map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&") : "";
+      const headers = { authorization: `Bearer ${this.token}` };
+      let payload;
+      if (opts?.rawBody !== undefined) {
+        payload = opts.rawBody;
+      } else if (body !== undefined) {
+        headers["content-type"] = "application/json";
+        payload = JSON.stringify(body);
+      }
+      const res = await this._fetch(this.apiUrl + path + q, { method, headers, body: payload, signal: ctl.signal });
+      if (opts?.rawResponse)
+        return res;
+      const text = await res.text();
+      const parsed = text ? safeParse(text) : null;
+      if (!res.ok) {
+        throw new PlatinumError(res.status, parsed ?? text, `${method} ${path} → ${res.status}`);
+      }
+      return parsed;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  sandboxes = {
+    create: async (spec, opts) => {
+      const body = { ...spec };
+      if (spec.image && typeof spec.image.toImageSpec === "function") {
+        body.image = spec.image.toImageSpec();
+      }
+      const wait = opts?.waitForRunning || opts?.waitTimeoutMs;
+      const query = wait ? { wait_for_state: "running", wait_timeout_ms: opts?.waitTimeoutMs ?? 60000 } : undefined;
+      const rpcMs = wait ? (opts?.waitTimeoutMs ?? 60000) + 30000 : this.timeoutMs;
+      const created = await this.request("POST", "/v1/sandboxes", body, { query, timeoutMs: rpcMs });
+      return new Sandbox(this, created.id, {
+        state: created.state,
+        name: created.name ?? null,
+        hostId: created.host_id,
+        warm: created.warm,
+        exposed: created.exposed
+      });
+    },
+    get: async (id) => this.request("GET", `/v1/sandboxes/${id}`),
+    list: async (opts) => {
+      return this.request("GET", "/v1/sandboxes", undefined, {
+        query: { paginated: "true", limit: opts?.limit ?? 50, offset: opts?.offset ?? 0, state: opts?.state }
+      });
+    },
+    delete: async (id) => {
+      await this.request("DELETE", `/v1/sandboxes/${id}`);
+    },
+    rename: async (id, name) => this.request("PATCH", `/v1/sandboxes/${id}`, { name })
+  };
+  templates = {
+    list: async () => this.request("GET", "/v1/templates")
+  };
+  regions = {
+    list: async () => this.request("GET", "/v1/regions")
+  };
+  health = {
+    check: async () => this.request("GET", "/health")
+  };
+  async me() {
+    return this.request("GET", "/v1/me");
+  }
+}
+
+class Sandbox {
+  client;
+  id;
+  warm;
+  name;
+  hostId;
+  exposed;
+  constructor(client, id, init = {}) {
+    this.client = client;
+    this.id = id;
+    this.warm = !!init.warm;
+    this.name = init.name ?? null;
+    this.hostId = init.hostId ?? null;
+    this.exposed = init.exposed ?? [];
+  }
+  exposedUrl(port) {
+    return this.exposed.find((e) => e.port === port)?.url ?? null;
+  }
+  async refresh() {
+    const s = await this.client.sandboxes.get(this.id);
+    this.hostId = s.hostId;
+    this.name = s.name ?? null;
+    return s;
+  }
+  async waitRunning(opts) {
+    const timeoutMs = opts?.timeoutMs ?? 30000;
+    const intervalMs = opts?.intervalMs ?? 250;
+    const deadline = Date.now() + timeoutMs;
+    let last;
+    while (Date.now() < deadline) {
+      last = await this.refresh();
+      if (last.state === "running")
+        return last;
+      if (last.state.startsWith("failed") || last.state === "lost" || last.state === "deleted") {
+        throw new PlatinumError(0, last, `sandbox ${this.id} entered terminal state: ${last.state}`);
+      }
+      await sleep(intervalMs);
+    }
+    throw new PlatinumError(0, last, `timeout waiting for running (last: ${last.state})`);
+  }
+  async delete() {
+    await this.client.sandboxes.delete(this.id);
+  }
+  async pause() {
+    await this.client.request("POST", `/v1/sandboxes/${this.id}/pause`, {});
+  }
+  async resume() {
+    await this.client.request("POST", `/v1/sandboxes/${this.id}/resume`, {});
+  }
+  async fork() {
+    return this.client.request("POST", `/v1/sandboxes/${this.id}/fork`, {});
+  }
+  async snapshot(opts) {
+    return this.client.request("POST", `/v1/sandboxes/${this.id}/snapshot`, opts ?? {});
+  }
+  async archive() {
+    await this.client.request("POST", `/v1/sandboxes/${this.id}/archive`, {});
+  }
+  async rename(name) {
+    const s = await this.client.request("PATCH", `/v1/sandboxes/${this.id}`, { name });
+    this.name = s.name ?? null;
+    return s;
+  }
+  async backup() {
+    return this.client.request("POST", `/v1/sandboxes/${this.id}/backup`, {});
+  }
+  async exec(cmd, opts) {
+    const r = await this.client.request("POST", `/v1/sandboxes/${this.id}/exec`, { cmd, timeout_ms: opts?.timeoutMs ?? 30000 }, { timeoutMs: (opts?.timeoutMs ?? 30000) + 5000 });
+    if (r.error)
+      throw new PlatinumError(0, r, r.error);
+    return r.result;
+  }
+  async sh(script, opts) {
+    return this.exec(["sh", "-c", script], opts);
+  }
+  async runCode(code, opts) {
+    return this.client.request("POST", `/v1/sandboxes/${this.id}/run-code`, { code, lang: opts?.lang ?? "python", timeout_ms: opts?.timeoutMs ?? 30000 });
+  }
+  async expose(port) {
+    return this.client.request("POST", `/v1/sandboxes/${this.id}/expose`, { port });
+  }
+  async unexpose(port) {
+    await this.client.request("DELETE", `/v1/sandboxes/${this.id}/expose/${port}`);
+  }
+  files = {
+    read: async (path) => {
+      const res = await this.client.request("GET", `/v1/sandboxes/${this.id}/files`, undefined, { query: { path }, rawResponse: true });
+      if (!res.ok)
+        throw new PlatinumError(res.status, await res.text(), `read ${path}: ${res.status}`);
+      return new Uint8Array(await res.arrayBuffer());
+    },
+    write: async (path, body) => {
+      await this.client.request("PUT", `/v1/sandboxes/${this.id}/files`, undefined, { query: { path }, rawBody: body });
+    },
+    delete: async (path) => {
+      await this.client.request("DELETE", `/v1/sandboxes/${this.id}/files`, undefined, { query: { path } });
+    },
+    list: async (path) => {
+      const r = await this.client.request("GET", `/v1/sandboxes/${this.id}/files/list`, undefined, { query: { path } });
+      if (r && r.ok === false)
+        throw new PlatinumError(0, r, r.error || `files.list ${path} failed`);
+      return r?.entries ?? [];
+    },
+    stat: async (path) => this.client.request("GET", `/v1/sandboxes/${this.id}/files/stat`, undefined, { query: { path } }),
+    mkdir: async (path) => {
+      await this.client.request("POST", `/v1/sandboxes/${this.id}/files/mkdir`, undefined, { query: { path } });
+    }
+  };
+  share = {
+    info: async () => this.client.request("GET", `/v1/sandboxes/${this.id}/share/info`),
+    list: async (path = "") => this.client.request("GET", `/v1/sandboxes/${this.id}/share/list`, undefined, { query: { path } }),
+    stat: async (path) => this.client.request("GET", `/v1/sandboxes/${this.id}/share/stat`, undefined, { query: { path } }),
+    get: async (path, opts) => {
+      const res = await this.client.request("GET", `/v1/sandboxes/${this.id}/share/get`, undefined, { query: { path }, rawResponse: true, timeoutMs: opts?.timeoutMs ?? 5 * 60000 });
+      if (!res.ok)
+        throw new PlatinumError(res.status, await res.text(), `share get ${path}: ${res.status}`);
+      return new Uint8Array(await res.arrayBuffer());
+    },
+    put: async (path, body, opts) => this.client.request("POST", `/v1/sandboxes/${this.id}/share/put`, undefined, { query: { path }, rawBody: body, timeoutMs: opts?.timeoutMs ?? 5 * 60000 }),
+    mkdir: async (path) => {
+      await this.client.request("POST", `/v1/sandboxes/${this.id}/share/mkdir`, undefined, { query: { path } });
+    },
+    delete: async (path, opts) => {
+      await this.client.request("DELETE", `/v1/sandboxes/${this.id}/share/delete`, undefined, { query: { path, recursive: opts?.recursive ? "1" : undefined } });
+    }
+  };
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function safeParse(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return;
+  }
+}
+export {
+  Template,
+  Sandbox,
+  PlatinumError,
+  Platinum
+};

package/dist/template.d.ts

@@ -0,0 +1,91 @@
+export type BuildStep = {
+    op: 'env';
+    key: string;
+    value: string;
+} | {
+    op: 'workdir';
+    path: string;
+} | {
+    op: 'user';
+    user: string;
+} | {
+    op: 'run';
+    cmd: string;
+} | {
+    op: 'pip';
+    packages: string[];
+} | {
+    op: 'npm';
+    packages: string[];
+} | {
+    op: 'apt';
+    packages: string[];
+} | {
+    op: 'copy';
+    content_b64: string;
+    dst: string;
+    mode?: string;
+};
+export interface BuildOpts {
+    name: string;
+    version?: string;
+    default_cpu?: number;
+    default_ram_mb?: number;
+    default_disk_gb?: number;
+    size_mb?: number;
+    /** Polls the template list until state != "building" — set 0 to fire-and-forget. */
+    wait_ms?: number;
+}
+export interface BuildResult {
+    id: string;
+    name: string;
+    state: 'building' | 'ready' | 'failed';
+    build_logs?: string;
+    content_hash?: string;
+}
+interface PlatinumLike {
+    url: string;
+    token: string;
+}
+export declare class Template {
+    private base;
+    private steps;
+    private _entrypoint?;
+    private _readyCmd?;
+    private constructor();
+    static fromImage(ref: string): Template;
+    static fromPythonImage(version: string): Template;
+    static fromNodeImage(version: string): Template;
+    static fromBunImage(version: string): Template;
+    static fromUbuntuImage(version: string): Template;
+    static fromDebianImage(version: string): Template;
+    static fromAlpineImage(version: string): Template;
+    env(key: string, value: string): this;
+    workdir(path: string): this;
+    user(user: string): this;
+    runCmd(cmd: string): this;
+    pipInstall(packages: string[]): this;
+    npmInstall(packages: string[]): this;
+    aptInstall(packages: string[]): this;
+    /** Inline copy. For small files only (<256 KiB). Pass a path to read it from disk. */
+    copy(src: string | Buffer, dst: string, mode?: string): this;
+    entrypoint(cmd: string): this;
+    /** Probe that runs inside the guest after entrypoint launches. Sandbox reports ready
+     *  only when this exits 0. Mirrors E2B's `setReadyCmd`. */
+    readyCmd(cmd: string): this;
+    toSpec(opts: BuildOpts): Record<string, unknown>;
+    /**
+     * Inline-image shape for `POST /v1/sandboxes`. Skips the explicit `name`/
+     * `version` — Platinum derives a deterministic `inline-<hash>` template
+     * name from the hashed spec, so identical specs from any caller dedupe to
+     * one row. Pass this directly via `sandboxes.create({ image: tpl, ... })`.
+     */
+    toImageSpec(opts?: {
+        default_cpu?: number;
+        default_ram_mb?: number;
+        default_disk_gb?: number;
+        size_mb?: number;
+    }): Record<string, unknown>;
+    build(dn: PlatinumLike, opts: BuildOpts): Promise<BuildResult>;
+}
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@platinum-dev/sdk",
+  "publishConfig": { "access": "public" },
+  "version": "0.2.0",
+  "description": "Platinum TypeScript SDK — typed client for hardware-isolated sandbox microVMs.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md", "LICENSE"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kortix-ai/platinum.git",
+    "directory": "packages/sdk-ts"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node --format esm && bun x tsc --emitDeclarationOnly --declaration --outDir dist src/index.ts",
+    "gen": "openapi-typescript ../../apps/api/openapi.codegen.json -o src/generated/schema.d.ts",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "openapi-typescript": "7.13.0",
+    "typescript": "^5.7.2"
+  }
+}