@arker-ai/sdk 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# Arker — TypeScript SDK
+
+TypeScript client for the [Arker](https://arker.ai) virtual computer
+platform. Spawn isolated Linux sandboxes, run shell / Python / Node
+code in them, read and write files. Zero runtime dependencies (uses
+the platform's built-in `fetch` and `crypto`).
+
+## Install
+
+```bash
+npm install @arker-ai/sdk
+```
+
+Works in Node ≥ 18. ESM + CJS + types all included.
+
+## Quickstart
+
+```ts
+import { Arker, ArkerError } from "@arker-ai/sdk";
+
+const arker = new Arker({ apiKey: "ark_live_..." });
+const vm    = await arker.vm("arkuntu").fork({ name: "hello" });
+
+const result = await vm.run("python3 -c 'print(2+2)'");
+console.log(new TextDecoder().decode(result.stdout));   // → "4\n"
+
+await vm.sync.writeFile("/home/user/data.csv", "a,b\n1,2\n");
+const data = await vm.sync.readFile("/home/user/data.csv");
+
+const child = await vm.fork({ name: "branch" });        // constant-time copy-on-write
+await child.delete();
+await vm.delete();
+```
+
+List your VMs:
+
+```ts
+const page = await arker.list({ limit: 10, sort: "-created_at" });
+console.log(`${page.total} total`);
+for (const summary of page.items) {
+  console.log(summary.vm_id, summary.name, summary.region, summary.created_at);
+}
+```
+
+## API
+
+```
+new Arker({ apiKey, baseUrl? })
+    .vm(vmId) -> Computer                         // open handle (no network call)
+    .list({ limit?, offset?, q?, sort? }) -> Promise<VmList>
+
+Computer
+    .id, .delete()
+    .fork({ name?, isPublic?, region? }) -> Promise<Computer>
+    .run(command, { sessionId?, timeout? }) -> Promise<RunResult>
+    .sync.readFile(path) -> Promise<Uint8Array>
+    .sync.writeFile(path, data: Uint8Array | string) -> Promise<void>
+
+RunResult: stdout, stderr (Uint8Array), exitCode, durationMs, sessionId, cwd
+VmSummary: vm_id, name, base_image, region, created_at (ISO 8601)
+VmList:    items (VmSummary[]), total (number)
+
+ArkerError(code, message, status) extends Error    // single error type
+```
+
+### Routing
+
+`fork`, `run`, `sync`, and `delete` use the regional endpoint set on the
+client (default `https://aws-us-west-2.burst.arker.ai`).
+
+`list` always goes through `https://arker.ai` regardless of `baseUrl`,
+because list data is served from a global host rather than a regional
+one.
+
+Public base-image names like `"arkuntu"` resolve to a ULID **client-side**
+(see `SOURCE_ALIASES` in `src/index.ts`), so `arker.vm("arkuntu").fork()`
+works on the default endpoint with no extra round-trip. Override
+`baseUrl` or set `ARKER_BASE_URL` to point at a different region or a
+self-hosted deployment.
+
+### Errors
+
+Every server-side error becomes an `ArkerError`:
+
+```ts
+try {
+  await vm.sync.readFile("/home/user/missing");
+} catch (err) {
+  if (err instanceof ArkerError) {
+    console.log(err.code);      // "not_found"
+    console.log(err.message);   // "not_found: file not found: ..."
+    console.log(err.status);    // 404
+  }
+}
+```
+
+`code` is a stable enum: `bad_request`, `unauthorized`, `payment_required`,
+`forbidden`, `not_found`, `conflict`, `payload_too_large`, `internal`,
+`not_implemented`, `vm_busy`, `unsupported_*`, `command_not_found`.
+
+### What the SDK does for you
+
+Hidden behind these six methods:
+
+- **Write strategy**: files up to 100 MB. Small payloads go in one call;
+  larger ones use a direct upload path so the bytes don't traverse the
+  API layer. `writeFile` resolves once the bytes are durably stored.
+- **Read coalescing**: `readFile` always resolves to a `Uint8Array`,
+  regardless of whether the server inlined the content or returned a
+  signed URL.
+- **Idempotent retry**: transient errors are retried with exponential
+  backoff. Writes are server-side idempotent on `upload_id`, so retries
+  never produce duplicates.
+- **Path validation**: only `/home/user/...` paths accepted; `..` rejected.
+
+## Demo / smoke test
+
+Run the full surface against a live deployment:
+
+```bash
+ARKER_API_KEY=ark_live_... npx tsx tests/demo.ts
+```
+
+It exercises every method (`list`, `vm`, `fork`, `run`, `sync.writeFile`,
+`sync.readFile`, error path, child fork, `delete`) and prints what each
+call hits on the wire — useful as living documentation.
+
+To fork from a specific source VM instead of the default `arkuntu`:
+
+```bash
+ARKER_API_KEY=ark_live_... ARKER_SOURCE_VM=01KQ... npx tsx tests/demo.ts
+```
+
+## License
+
+Apache-2.0.

package/dist/index.cjs

@@ -0,0 +1,321 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Arker: () => Arker,
+  ArkerError: () => ArkerError,
+  CHUNK_SIZE: () => CHUNK_SIZE,
+  Computer: () => Computer,
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  LIST_BASE_URL: () => LIST_BASE_URL,
+  SOURCE_ALIASES: () => SOURCE_ALIASES,
+  Sync: () => Sync
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_BASE_URL = "https://aws-us-west-2.burst.arker.ai";
+var LIST_BASE_URL = "https://arker.ai";
+var SOURCE_ALIASES = {
+  arkuntu: "01KQBYKEV5WJ7YB010603T1DCT_d8c0"
+};
+var CHUNK_SIZE = 4 * 1024 * 1024;
+var PRESIGN_PUT_TIMEOUT_MS = 6e5;
+var RETRYABLE_HTTP = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+var TRANSIENT_HINTS = ["503", "Service Unavailable", "throttle", "SlowDown", "ThrottlingException"];
+var MAX_ATTEMPTS = 4;
+var BACKOFF_MS = 200;
+var ULID_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+var ArkerError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(`${code}: ${message}`);
+    this.name = "ArkerError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var jitterMs = () => Math.floor(Math.random() * 50);
+function ulid() {
+  const time = BigInt(Date.now()) & (1n << 48n) - 1n;
+  const rand = new Uint8Array(10);
+  crypto.getRandomValues(rand);
+  let raw = time << 80n | rand.reduce((acc, b) => acc << 8n | BigInt(b), 0n);
+  const out = [];
+  for (let i = 0; i < 26; i++) {
+    out.push(ULID_ALPHABET[Number(raw & 31n)]);
+    raw >>= 5n;
+  }
+  return out.reverse().join("");
+}
+function looksLikeVmId(s) {
+  let head = s;
+  if (s.includes("_")) {
+    const [h, ...rest] = s.split("_");
+    const tail = rest.join("_");
+    if (!tail || !/^[A-Za-z0-9]+$/.test(tail)) return false;
+    head = h;
+  }
+  if (head.length !== 26) return false;
+  return [...head.toUpperCase()].every((c) => ULID_ALPHABET.includes(c));
+}
+function decodeStream(text, encoding) {
+  const s = typeof text === "string" ? text : "";
+  if (encoding === "base64") {
+    try {
+      const bin = atob(s);
+      const out = new Uint8Array(bin.length);
+      for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+      return out;
+    } catch {
+    }
+  }
+  return new TextEncoder().encode(s);
+}
+function bytesToBase64(data) {
+  let bin = "";
+  for (let i = 0; i < data.length; i++) bin += String.fromCharCode(data[i]);
+  return btoa(bin);
+}
+function isTransient(err) {
+  if (!err || err.code !== "internal") return false;
+  const msg = err.message ?? "";
+  return TRANSIENT_HINTS.some((h) => msg.includes(h));
+}
+var Arker = class {
+  apiKey;
+  baseUrl;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("apiKey is required");
+    this.apiKey = opts.apiKey;
+    const base = opts.baseUrl ?? process.env.ARKER_BASE_URL ?? DEFAULT_BASE_URL;
+    this.baseUrl = base.replace(/\/+$/, "");
+  }
+  /** @internal */
+  async _request(method, path, body, overrideBaseUrl) {
+    const url = (overrideBaseUrl ? overrideBaseUrl.replace(/\/+$/, "") : this.baseUrl) + path;
+    const headers = {
+      authorization: `Bearer ${this.apiKey}`,
+      "content-type": "application/json"
+    };
+    let lastStatus = 0;
+    let lastErr = null;
+    let lastText = "";
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const resp = await fetch(url, {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0
+      });
+      const text = await resp.text();
+      let payload = null;
+      try {
+        payload = text ? JSON.parse(text) : {};
+      } catch {
+        payload = null;
+      }
+      lastStatus = resp.status;
+      lastText = text;
+      const envelopeErr = payload && typeof payload === "object" && payload.ok === false ? payload.error : null;
+      lastErr = envelopeErr;
+      if (RETRYABLE_HTTP.has(resp.status) || isTransient(envelopeErr)) {
+        if (attempt === MAX_ATTEMPTS - 1) break;
+        await sleep(BACKOFF_MS * 2 ** attempt + jitterMs());
+        continue;
+      }
+      if (envelopeErr) {
+        throw new ArkerError(envelopeErr.code ?? "internal", envelopeErr.message ?? "", resp.status);
+      }
+      if (resp.status >= 400) {
+        throw new ArkerError("internal", text.slice(0, 200) || "request failed", resp.status);
+      }
+      return payload;
+    }
+    if (lastErr) {
+      throw new ArkerError(lastErr.code ?? "internal", lastErr.message ?? "", lastStatus);
+    }
+    throw new ArkerError("internal", lastText.slice(0, 200) || "no response", lastStatus);
+  }
+  /** Open a handle to a VM by ULID *or* template name. No network call. */
+  vm(vmId) {
+    return new Computer(this, vmId);
+  }
+  /** List VMs in the caller's organization. Always hits `https://arker.ai`. */
+  async list(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.limit !== void 0 && opts.limit !== 25) params.set("limit", String(opts.limit));
+    if (opts.offset !== void 0 && opts.offset !== 0) params.set("offset", String(opts.offset));
+    if (opts.q !== void 0) params.set("q", opts.q);
+    if (opts.sort !== void 0) params.set("sort", opts.sort);
+    const qs = params.toString();
+    const path = "/api/v1/vms/list" + (qs ? `?${qs}` : "");
+    const r = await this._request("GET", path, void 0, LIST_BASE_URL);
+    return { items: r.items ?? [], total: r.total ?? 0 };
+  }
+};
+var Computer = class _Computer {
+  id;
+  sync;
+  /** @internal */
+  _client;
+  constructor(client, vmId) {
+    this._client = client;
+    this.id = vmId;
+    this.sync = new Sync(this);
+  }
+  async delete() {
+    await this._client._request("DELETE", `/api/v1/vms/${this.id}`);
+  }
+  /** Fork this VM. Aliases like `"arkuntu"` resolve client-side. */
+  async fork(opts = {}) {
+    const body = { is_public: opts.isPublic ?? false };
+    if (opts.name !== void 0) body.name = opts.name;
+    if (opts.region !== void 0) body.region = opts.region;
+    const resolved = SOURCE_ALIASES[this.id] ?? this.id;
+    let r;
+    if (looksLikeVmId(resolved)) {
+      r = await this._client._request("POST", `/api/v1/vms/${resolved}/fork`, body);
+    } else {
+      body.from = this.id;
+      r = await this._client._request("POST", "/api/v1/vms/fork", body, LIST_BASE_URL);
+    }
+    if (!r.vm_id) throw new ArkerError("internal", "fork response missing vm_id", 200);
+    return new _Computer(this._client, r.vm_id);
+  }
+  async run(command, opts = {}) {
+    const body = {
+      command,
+      session_id: opts.sessionId ?? 0
+    };
+    if (opts.timeout !== void 0) body.timeout = opts.timeout;
+    const r = await this._client._request("POST", `/api/v1/vms/${this.id}/run`, body);
+    return {
+      stdout: decodeStream(r.stdout, r.stdout_encoding),
+      stderr: decodeStream(r.stderr, r.stderr_encoding),
+      exitCode: Number(r.exit_code ?? 0),
+      durationMs: Number(r.duration_ms ?? 0),
+      sessionId: String(r.session_id ?? ""),
+      cwd: String(r.cwd ?? "")
+    };
+  }
+};
+var Sync = class {
+  /** @internal */
+  _vm;
+  constructor(vm) {
+    this._vm = vm;
+  }
+  path() {
+    return `/api/v1/vms/${this._vm.id}/sync`;
+  }
+  async readFile(path) {
+    const r = await this._vm._client._request("POST", this.path(), { op: "read", path });
+    if (r.content !== void 0 && r.content !== null) {
+      return decodeStream(r.content, r.encoding);
+    }
+    if (r.presigned_url) {
+      const resp = await fetch(r.presigned_url);
+      if (!resp.ok) {
+        throw new ArkerError("internal", `signed GET failed: ${resp.status}`, resp.status);
+      }
+      return new Uint8Array(await resp.arrayBuffer());
+    }
+    throw new ArkerError("internal", "read response missing content/presigned_url", 200);
+  }
+  async writeFile(path, data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    if (!bytes.length) throw new ArkerError("bad_request", "writeFile: empty data", 400);
+    if (bytes.length <= CHUNK_SIZE) {
+      await this.fastPath(path, bytes);
+    } else {
+      await this.presignedPath(path, bytes);
+    }
+  }
+  async fastPath(path, data) {
+    const size = data.length;
+    const result = await this.sendOneWrite({
+      path,
+      size,
+      upload_id: ulid(),
+      start: 0,
+      end: size,
+      content: bytesToBase64(data)
+    });
+    if (!(result.complete && result.written)) {
+      throw new ArkerError("internal", "fast-path write returned without complete+written", 200);
+    }
+  }
+  async presignedPath(path, data) {
+    const size = data.length;
+    const e1 = await this.sendOneWrite({ path, size, presigned: true });
+    const url = e1.presigned_url;
+    const uploadId = e1.upload_id;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), PRESIGN_PUT_TIMEOUT_MS);
+      try {
+        const resp = await fetch(url, { method: "PUT", body: data, signal: ctrl.signal });
+        clearTimeout(t);
+        if (resp.ok) break;
+        if (!RETRYABLE_HTTP.has(resp.status) || attempt === MAX_ATTEMPTS - 1) {
+          throw new ArkerError("internal", `upload PUT failed: ${resp.status}`, resp.status);
+        }
+        await sleep(BACKOFF_MS * 2 ** attempt);
+      } catch (err) {
+        clearTimeout(t);
+        if (err instanceof ArkerError) throw err;
+        if (attempt === MAX_ATTEMPTS - 1) {
+          throw new ArkerError("internal", `upload PUT failed: ${err.message}`, 0);
+        }
+        await sleep(BACKOFF_MS * 2 ** attempt);
+      }
+    }
+    await this.sendOneWrite({ path, size, upload_id: uploadId });
+  }
+  async sendOneWrite(entry) {
+    let lastErr = null;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const r = await this._vm._client._request("POST", this.path(), {
+        op: "write",
+        writes: [entry]
+      });
+      const result = (r.results ?? [null])[0];
+      if (!result) throw new ArkerError("internal", "write response missing results[0]", 200);
+      const err = result.error ?? null;
+      if (!err) return result;
+      lastErr = err;
+      if (!isTransient(err) || attempt === MAX_ATTEMPTS - 1) break;
+      await sleep(BACKOFF_MS * 2 ** attempt + jitterMs());
+    }
+    throw new ArkerError(lastErr?.code ?? "internal", lastErr?.message ?? "write failed", 200);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Arker,
+  ArkerError,
+  CHUNK_SIZE,
+  Computer,
+  DEFAULT_BASE_URL,
+  LIST_BASE_URL,
+  SOURCE_ALIASES,
+  Sync
+});

package/dist/index.d.cts

@@ -0,0 +1,115 @@
+/**
+ * Arker SDK — TypeScript client.
+ *
+ * Quickstart:
+ *
+ *   import { Arker } from "@arker-ai/sdk";
+ *   const arker = new Arker({ apiKey: "ark_live_..." });
+ *   const vm    = await arker.vm("arkuntu").fork({ name: "hello" });
+ *
+ *   const result = await vm.run("echo hi");
+ *   console.log(new TextDecoder().decode(result.stdout)); // → "hi\n"
+ *
+ *   await vm.sync.writeFile("/home/user/data.bin", new Uint8Array([1, 2, 3]));
+ *   const blob = await vm.sync.readFile("/home/user/data.bin");
+ *
+ *   const child = await vm.fork({ name: "branch" });
+ *   await child.delete();
+ *   await vm.delete();
+ *
+ *   // List your VMs (paginated):
+ *   const page = await arker.list({ limit: 10 });
+ *   for (const summary of page.items) {
+ *     console.log(summary.vm_id, summary.name, summary.created_at);
+ *   }
+ *
+ * Errors are thrown as `ArkerError(code, message, status)`.
+ */
+declare const DEFAULT_BASE_URL = "https://aws-us-west-2.burst.arker.ai";
+/** `list` is served from a different host than the rest; used regardless of the client's baseUrl. */
+declare const LIST_BASE_URL = "https://arker.ai";
+/** Public base-image aliases resolved client-side so `vm("arkuntu").fork()` works on the default endpoint. */
+declare const SOURCE_ALIASES: Record<string, string>;
+/** Files above this size go through a direct upload path. */
+declare const CHUNK_SIZE: number;
+interface ArkerOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+interface ForkOptions {
+    name?: string;
+    isPublic?: boolean;
+    region?: string;
+}
+interface RunOptions {
+    sessionId?: string | number;
+    timeout?: number;
+}
+interface RunResult {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    exitCode: number;
+    durationMs: number;
+    sessionId: string;
+    cwd: string;
+}
+interface VmSummary {
+    vm_id: string;
+    name: string | null;
+    base_image: string;
+    region: string;
+    /** ISO 8601 UTC. */
+    created_at: string;
+}
+interface VmList {
+    items: VmSummary[];
+    /** Total matching the query, ignoring limit/offset. */
+    total: number;
+}
+interface ListOptions {
+    limit?: number;
+    offset?: number;
+    q?: string;
+    /** `created_at` | `-created_at` | `region` | `-region`. Default `-created_at`. */
+    sort?: string;
+}
+declare class ArkerError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}
+declare class Arker {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(opts: ArkerOptions);
+    /** @internal */
+    _request<T = any>(method: string, path: string, body?: unknown, overrideBaseUrl?: string): Promise<T>;
+    /** Open a handle to a VM by ULID *or* template name. No network call. */
+    vm(vmId: string): Computer;
+    /** List VMs in the caller's organization. Always hits `https://arker.ai`. */
+    list(opts?: ListOptions): Promise<VmList>;
+}
+declare class Computer {
+    readonly id: string;
+    readonly sync: Sync;
+    /** @internal */
+    readonly _client: Arker;
+    constructor(client: Arker, vmId: string);
+    delete(): Promise<void>;
+    /** Fork this VM. Aliases like `"arkuntu"` resolve client-side. */
+    fork(opts?: ForkOptions): Promise<Computer>;
+    run(command: string, opts?: RunOptions): Promise<RunResult>;
+}
+declare class Sync {
+    /** @internal */
+    readonly _vm: Computer;
+    constructor(vm: Computer);
+    private path;
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array | string): Promise<void>;
+    private fastPath;
+    private presignedPath;
+    private sendOneWrite;
+}
+
+export { Arker, ArkerError, type ArkerOptions, CHUNK_SIZE, Computer, DEFAULT_BASE_URL, type ForkOptions, LIST_BASE_URL, type ListOptions, type RunOptions, type RunResult, SOURCE_ALIASES, Sync, type VmList, type VmSummary };

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Arker SDK — TypeScript client.
+ *
+ * Quickstart:
+ *
+ *   import { Arker } from "@arker-ai/sdk";
+ *   const arker = new Arker({ apiKey: "ark_live_..." });
+ *   const vm    = await arker.vm("arkuntu").fork({ name: "hello" });
+ *
+ *   const result = await vm.run("echo hi");
+ *   console.log(new TextDecoder().decode(result.stdout)); // → "hi\n"
+ *
+ *   await vm.sync.writeFile("/home/user/data.bin", new Uint8Array([1, 2, 3]));
+ *   const blob = await vm.sync.readFile("/home/user/data.bin");
+ *
+ *   const child = await vm.fork({ name: "branch" });
+ *   await child.delete();
+ *   await vm.delete();
+ *
+ *   // List your VMs (paginated):
+ *   const page = await arker.list({ limit: 10 });
+ *   for (const summary of page.items) {
+ *     console.log(summary.vm_id, summary.name, summary.created_at);
+ *   }
+ *
+ * Errors are thrown as `ArkerError(code, message, status)`.
+ */
+declare const DEFAULT_BASE_URL = "https://aws-us-west-2.burst.arker.ai";
+/** `list` is served from a different host than the rest; used regardless of the client's baseUrl. */
+declare const LIST_BASE_URL = "https://arker.ai";
+/** Public base-image aliases resolved client-side so `vm("arkuntu").fork()` works on the default endpoint. */
+declare const SOURCE_ALIASES: Record<string, string>;
+/** Files above this size go through a direct upload path. */
+declare const CHUNK_SIZE: number;
+interface ArkerOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+interface ForkOptions {
+    name?: string;
+    isPublic?: boolean;
+    region?: string;
+}
+interface RunOptions {
+    sessionId?: string | number;
+    timeout?: number;
+}
+interface RunResult {
+    stdout: Uint8Array;
+    stderr: Uint8Array;
+    exitCode: number;
+    durationMs: number;
+    sessionId: string;
+    cwd: string;
+}
+interface VmSummary {
+    vm_id: string;
+    name: string | null;
+    base_image: string;
+    region: string;
+    /** ISO 8601 UTC. */
+    created_at: string;
+}
+interface VmList {
+    items: VmSummary[];
+    /** Total matching the query, ignoring limit/offset. */
+    total: number;
+}
+interface ListOptions {
+    limit?: number;
+    offset?: number;
+    q?: string;
+    /** `created_at` | `-created_at` | `region` | `-region`. Default `-created_at`. */
+    sort?: string;
+}
+declare class ArkerError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}
+declare class Arker {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(opts: ArkerOptions);
+    /** @internal */
+    _request<T = any>(method: string, path: string, body?: unknown, overrideBaseUrl?: string): Promise<T>;
+    /** Open a handle to a VM by ULID *or* template name. No network call. */
+    vm(vmId: string): Computer;
+    /** List VMs in the caller's organization. Always hits `https://arker.ai`. */
+    list(opts?: ListOptions): Promise<VmList>;
+}
+declare class Computer {
+    readonly id: string;
+    readonly sync: Sync;
+    /** @internal */
+    readonly _client: Arker;
+    constructor(client: Arker, vmId: string);
+    delete(): Promise<void>;
+    /** Fork this VM. Aliases like `"arkuntu"` resolve client-side. */
+    fork(opts?: ForkOptions): Promise<Computer>;
+    run(command: string, opts?: RunOptions): Promise<RunResult>;
+}
+declare class Sync {
+    /** @internal */
+    readonly _vm: Computer;
+    constructor(vm: Computer);
+    private path;
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, data: Uint8Array | string): Promise<void>;
+    private fastPath;
+    private presignedPath;
+    private sendOneWrite;
+}
+
+export { Arker, ArkerError, type ArkerOptions, CHUNK_SIZE, Computer, DEFAULT_BASE_URL, type ForkOptions, LIST_BASE_URL, type ListOptions, type RunOptions, type RunResult, SOURCE_ALIASES, Sync, type VmList, type VmSummary };

package/dist/index.js

@@ -0,0 +1,289 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://aws-us-west-2.burst.arker.ai";
+var LIST_BASE_URL = "https://arker.ai";
+var SOURCE_ALIASES = {
+  arkuntu: "01KQBYKEV5WJ7YB010603T1DCT_d8c0"
+};
+var CHUNK_SIZE = 4 * 1024 * 1024;
+var PRESIGN_PUT_TIMEOUT_MS = 6e5;
+var RETRYABLE_HTTP = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+var TRANSIENT_HINTS = ["503", "Service Unavailable", "throttle", "SlowDown", "ThrottlingException"];
+var MAX_ATTEMPTS = 4;
+var BACKOFF_MS = 200;
+var ULID_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+var ArkerError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status) {
+    super(`${code}: ${message}`);
+    this.name = "ArkerError";
+    this.code = code;
+    this.status = status;
+  }
+};
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var jitterMs = () => Math.floor(Math.random() * 50);
+function ulid() {
+  const time = BigInt(Date.now()) & (1n << 48n) - 1n;
+  const rand = new Uint8Array(10);
+  crypto.getRandomValues(rand);
+  let raw = time << 80n | rand.reduce((acc, b) => acc << 8n | BigInt(b), 0n);
+  const out = [];
+  for (let i = 0; i < 26; i++) {
+    out.push(ULID_ALPHABET[Number(raw & 31n)]);
+    raw >>= 5n;
+  }
+  return out.reverse().join("");
+}
+function looksLikeVmId(s) {
+  let head = s;
+  if (s.includes("_")) {
+    const [h, ...rest] = s.split("_");
+    const tail = rest.join("_");
+    if (!tail || !/^[A-Za-z0-9]+$/.test(tail)) return false;
+    head = h;
+  }
+  if (head.length !== 26) return false;
+  return [...head.toUpperCase()].every((c) => ULID_ALPHABET.includes(c));
+}
+function decodeStream(text, encoding) {
+  const s = typeof text === "string" ? text : "";
+  if (encoding === "base64") {
+    try {
+      const bin = atob(s);
+      const out = new Uint8Array(bin.length);
+      for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+      return out;
+    } catch {
+    }
+  }
+  return new TextEncoder().encode(s);
+}
+function bytesToBase64(data) {
+  let bin = "";
+  for (let i = 0; i < data.length; i++) bin += String.fromCharCode(data[i]);
+  return btoa(bin);
+}
+function isTransient(err) {
+  if (!err || err.code !== "internal") return false;
+  const msg = err.message ?? "";
+  return TRANSIENT_HINTS.some((h) => msg.includes(h));
+}
+var Arker = class {
+  apiKey;
+  baseUrl;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("apiKey is required");
+    this.apiKey = opts.apiKey;
+    const base = opts.baseUrl ?? process.env.ARKER_BASE_URL ?? DEFAULT_BASE_URL;
+    this.baseUrl = base.replace(/\/+$/, "");
+  }
+  /** @internal */
+  async _request(method, path, body, overrideBaseUrl) {
+    const url = (overrideBaseUrl ? overrideBaseUrl.replace(/\/+$/, "") : this.baseUrl) + path;
+    const headers = {
+      authorization: `Bearer ${this.apiKey}`,
+      "content-type": "application/json"
+    };
+    let lastStatus = 0;
+    let lastErr = null;
+    let lastText = "";
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const resp = await fetch(url, {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0
+      });
+      const text = await resp.text();
+      let payload = null;
+      try {
+        payload = text ? JSON.parse(text) : {};
+      } catch {
+        payload = null;
+      }
+      lastStatus = resp.status;
+      lastText = text;
+      const envelopeErr = payload && typeof payload === "object" && payload.ok === false ? payload.error : null;
+      lastErr = envelopeErr;
+      if (RETRYABLE_HTTP.has(resp.status) || isTransient(envelopeErr)) {
+        if (attempt === MAX_ATTEMPTS - 1) break;
+        await sleep(BACKOFF_MS * 2 ** attempt + jitterMs());
+        continue;
+      }
+      if (envelopeErr) {
+        throw new ArkerError(envelopeErr.code ?? "internal", envelopeErr.message ?? "", resp.status);
+      }
+      if (resp.status >= 400) {
+        throw new ArkerError("internal", text.slice(0, 200) || "request failed", resp.status);
+      }
+      return payload;
+    }
+    if (lastErr) {
+      throw new ArkerError(lastErr.code ?? "internal", lastErr.message ?? "", lastStatus);
+    }
+    throw new ArkerError("internal", lastText.slice(0, 200) || "no response", lastStatus);
+  }
+  /** Open a handle to a VM by ULID *or* template name. No network call. */
+  vm(vmId) {
+    return new Computer(this, vmId);
+  }
+  /** List VMs in the caller's organization. Always hits `https://arker.ai`. */
+  async list(opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.limit !== void 0 && opts.limit !== 25) params.set("limit", String(opts.limit));
+    if (opts.offset !== void 0 && opts.offset !== 0) params.set("offset", String(opts.offset));
+    if (opts.q !== void 0) params.set("q", opts.q);
+    if (opts.sort !== void 0) params.set("sort", opts.sort);
+    const qs = params.toString();
+    const path = "/api/v1/vms/list" + (qs ? `?${qs}` : "");
+    const r = await this._request("GET", path, void 0, LIST_BASE_URL);
+    return { items: r.items ?? [], total: r.total ?? 0 };
+  }
+};
+var Computer = class _Computer {
+  id;
+  sync;
+  /** @internal */
+  _client;
+  constructor(client, vmId) {
+    this._client = client;
+    this.id = vmId;
+    this.sync = new Sync(this);
+  }
+  async delete() {
+    await this._client._request("DELETE", `/api/v1/vms/${this.id}`);
+  }
+  /** Fork this VM. Aliases like `"arkuntu"` resolve client-side. */
+  async fork(opts = {}) {
+    const body = { is_public: opts.isPublic ?? false };
+    if (opts.name !== void 0) body.name = opts.name;
+    if (opts.region !== void 0) body.region = opts.region;
+    const resolved = SOURCE_ALIASES[this.id] ?? this.id;
+    let r;
+    if (looksLikeVmId(resolved)) {
+      r = await this._client._request("POST", `/api/v1/vms/${resolved}/fork`, body);
+    } else {
+      body.from = this.id;
+      r = await this._client._request("POST", "/api/v1/vms/fork", body, LIST_BASE_URL);
+    }
+    if (!r.vm_id) throw new ArkerError("internal", "fork response missing vm_id", 200);
+    return new _Computer(this._client, r.vm_id);
+  }
+  async run(command, opts = {}) {
+    const body = {
+      command,
+      session_id: opts.sessionId ?? 0
+    };
+    if (opts.timeout !== void 0) body.timeout = opts.timeout;
+    const r = await this._client._request("POST", `/api/v1/vms/${this.id}/run`, body);
+    return {
+      stdout: decodeStream(r.stdout, r.stdout_encoding),
+      stderr: decodeStream(r.stderr, r.stderr_encoding),
+      exitCode: Number(r.exit_code ?? 0),
+      durationMs: Number(r.duration_ms ?? 0),
+      sessionId: String(r.session_id ?? ""),
+      cwd: String(r.cwd ?? "")
+    };
+  }
+};
+var Sync = class {
+  /** @internal */
+  _vm;
+  constructor(vm) {
+    this._vm = vm;
+  }
+  path() {
+    return `/api/v1/vms/${this._vm.id}/sync`;
+  }
+  async readFile(path) {
+    const r = await this._vm._client._request("POST", this.path(), { op: "read", path });
+    if (r.content !== void 0 && r.content !== null) {
+      return decodeStream(r.content, r.encoding);
+    }
+    if (r.presigned_url) {
+      const resp = await fetch(r.presigned_url);
+      if (!resp.ok) {
+        throw new ArkerError("internal", `signed GET failed: ${resp.status}`, resp.status);
+      }
+      return new Uint8Array(await resp.arrayBuffer());
+    }
+    throw new ArkerError("internal", "read response missing content/presigned_url", 200);
+  }
+  async writeFile(path, data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    if (!bytes.length) throw new ArkerError("bad_request", "writeFile: empty data", 400);
+    if (bytes.length <= CHUNK_SIZE) {
+      await this.fastPath(path, bytes);
+    } else {
+      await this.presignedPath(path, bytes);
+    }
+  }
+  async fastPath(path, data) {
+    const size = data.length;
+    const result = await this.sendOneWrite({
+      path,
+      size,
+      upload_id: ulid(),
+      start: 0,
+      end: size,
+      content: bytesToBase64(data)
+    });
+    if (!(result.complete && result.written)) {
+      throw new ArkerError("internal", "fast-path write returned without complete+written", 200);
+    }
+  }
+  async presignedPath(path, data) {
+    const size = data.length;
+    const e1 = await this.sendOneWrite({ path, size, presigned: true });
+    const url = e1.presigned_url;
+    const uploadId = e1.upload_id;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const ctrl = new AbortController();
+      const t = setTimeout(() => ctrl.abort(), PRESIGN_PUT_TIMEOUT_MS);
+      try {
+        const resp = await fetch(url, { method: "PUT", body: data, signal: ctrl.signal });
+        clearTimeout(t);
+        if (resp.ok) break;
+        if (!RETRYABLE_HTTP.has(resp.status) || attempt === MAX_ATTEMPTS - 1) {
+          throw new ArkerError("internal", `upload PUT failed: ${resp.status}`, resp.status);
+        }
+        await sleep(BACKOFF_MS * 2 ** attempt);
+      } catch (err) {
+        clearTimeout(t);
+        if (err instanceof ArkerError) throw err;
+        if (attempt === MAX_ATTEMPTS - 1) {
+          throw new ArkerError("internal", `upload PUT failed: ${err.message}`, 0);
+        }
+        await sleep(BACKOFF_MS * 2 ** attempt);
+      }
+    }
+    await this.sendOneWrite({ path, size, upload_id: uploadId });
+  }
+  async sendOneWrite(entry) {
+    let lastErr = null;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+      const r = await this._vm._client._request("POST", this.path(), {
+        op: "write",
+        writes: [entry]
+      });
+      const result = (r.results ?? [null])[0];
+      if (!result) throw new ArkerError("internal", "write response missing results[0]", 200);
+      const err = result.error ?? null;
+      if (!err) return result;
+      lastErr = err;
+      if (!isTransient(err) || attempt === MAX_ATTEMPTS - 1) break;
+      await sleep(BACKOFF_MS * 2 ** attempt + jitterMs());
+    }
+    throw new ArkerError(lastErr?.code ?? "internal", lastErr?.message ?? "write failed", 200);
+  }
+};
+export {
+  Arker,
+  ArkerError,
+  CHUNK_SIZE,
+  Computer,
+  DEFAULT_BASE_URL,
+  LIST_BASE_URL,
+  SOURCE_ALIASES,
+  Sync
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@arker-ai/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Arker virtual computer platform — spawn sandboxed VMs, run code, sync files.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --target=node18",
+    "demo": "tsx tests/demo.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["arker", "vm", "sandbox", "agent", "code-execution"],
+  "license": "Apache-2.0",
+  "homepage": "https://arker.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArkerHQ/arker-sdks.git",
+    "directory": "typescript"
+  },
+  "bugs": "https://github.com/ArkerHQ/arker-sdks/issues",
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}