@arker-ai/sdk 0.2.1 → 0.5.1

package/README.md

@@ -1,9 +1,6 @@
-# Arker — TypeScript SDK
+# 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`).
+A small, typed wrapper around the Arker VM API: fork a machine, run commands, sync files.
 
 ## Install
 
@@ -11,126 +8,70 @@ the platform's built-in `fetch` and `crypto`).
 npm install @arker-ai/sdk
 ```
 
-Works in Node ≥ 18. ESM + CJS + types all included.
+Node 18+. The client reads your key from `ARKER_API_KEY` — get one in the [console](https://arker.ai/console).
 
 ## Quickstart
 
 ```ts
-import { Arker, ArkerError } from "@arker-ai/sdk";
+import { Arker } from "@arker-ai/sdk";
 
-const arker = new Arker({ apiKey: "ark_live_..." });
-const vm    = await arker.vm("arkuntu").fork({ name: "hello" });
+const ar = new Arker({ region: "us-west-2" });
 
-const result = await vm.run("python3 -c 'print(2+2)'");
-console.log(new TextDecoder().decode(result.stdout));   // → "4\n"
+// Fork a public golden, run a command, read/write a file.
+const vm = await ar.fork("ubuntu-full"); // public golden — org inferred
 
-await vm.sync.writeFile("/home/user/data.csv", "a,b\n1,2\n");
-const data = await vm.sync.readFile("/home/user/data.csv");
+const run = await vm.run("python3 -c 'print(2 + 2)'");
+if (run.type === "completed") console.log(new TextDecoder().decode(run.stdout));
+
+await vm.sync("/tmp/data.txt", "hello\n");   // write
+const data = await vm.sync("/tmp/data.txt"); // read -> Uint8Array
 
-const child = await vm.fork({ name: "branch" });        // constant-time copy-on-write
-await child.delete();
 await vm.delete();
 ```
 
-List your VMs:
+## Core API
 
 ```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
+const ar = new Arker({ region, apiKey?, baseUrl?, retry? });
+
+// VMs
+await ar.fork("ubuntu-full");                 // public golden by name (org inferred)
+await ar.fork(vm, { name: "child" });         // an existing VM (uses its id)
+await ar.fork({ sourceVmName, sourceOrgId, name?, durable? });
+await ar.listVms({ state? });
+ar.vm(vmId);                                  // bare handle
+await ar.vm(vmId).run(command, options?);
+await ar.vm(vmId).resize({ vcpu_count, memory_mib });
+await ar.vm(vmId).delete();
+
+// Files inside a VM
+await vm.sync(path);                          // read  -> Uint8Array
+await vm.sync(path, data);                    // write
+
+// Filesystems — standalone, persistent volumes
+await ar.createFilesystem({ name });
+await ar.listFilesystems();
+await ar.deleteFilesystem(filesystemId);
+
+// Syncs — mount a filesystem into a VM at a path
+await vm.createSync({ filesystemId, path });
+await vm.listSyncs();
+await vm.deleteSync(syncId);
 ```
 
-### Routing
-
-`fork`, `run`, `sync`, and `delete` use the regional endpoint set on the
-client (default `https://aws-us-west-2.burst.arker.ai`).
+`apiKey` falls back to `ARKER_API_KEY`; `region` to `ARKER_REGION`. Pass `baseUrl` for dev targets. Configure retries with `retry: { attempts, baseDelayMs, maxDelayMs }`, or `retry: false` to disable.
 
-`list` always goes through `https://arker.ai` regardless of `baseUrl`,
-because list data is served from a global host rather than a regional
-one.
+## Durability
 
-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`:
+For long-running or non-idempotent work, fork with `durable: true` and pass an idempotency key when retrying a run:
 
 ```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
-  }
-}
+const vm = await ar.fork("ubuntu-full", { durable: true });
+await vm.run("python3 train.py", { background: true, idempotencyKey: crypto.randomUUID() });
 ```
 
-`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
-```
+If the host fails mid-run, the run resumes on a healthy host with the VM's filesystem state preserved. Backends without durability return `ArkerError` code `unsupported_operation`.
 
 ## License
 
-Apache-2.0.
+Apache-2.0