quilt-sdk 0.0.4 → 0.0.5

package/README.md

@@ -1,51 +1,120 @@
 # quilt-sdk
 
-Type-safe TypeScript SDK for interacting with Quilt platform APIs.
+Type-safe TypeScript SDK for Quilt production APIs.
 
-This package is the interaction plane for Quilt production APIs, including:
-
-- Core HTTP API resources (`containers`, `volumes`, `projects`, `clusters`, `functions`, etc.)
-- Production platform extensions (`platform` module: env/jobs/archive/ops/ICC and related endpoints)
-- Realtime APIs (SSE events and WebSocket terminal attach)
-- OpenAI-compatible tool schema export (`QUILT_TOOLS`)
+`quilt-sdk` is the programmatic client for the live Quilt backend. It is intended to be the typed source of truth for production automation, not a thin convenience wrapper around ad hoc fetch calls.
 
 ## Install
 
+```bash
+npm install quilt-sdk
+```
+
+or
+
 ```bash
 bun add quilt-sdk
 ```
 
+## Requirements
+
+- Node `>=20.10.0`
+- Quilt backend URL, usually `https://backend.quilt.sh`
+- either `QUILT_API_KEY` or `QUILT_JWT`
+
 ## Quick Start
 
 ```ts
 import { QuiltClient } from "quilt-sdk";
 
-const quilt = QuiltClient.connect({
-  baseUrl: "https://backend.quilt.sh",
+const client = QuiltClient.connect({
+  baseUrl: process.env.QUILT_BASE_URL ?? "https://backend.quilt.sh",
   apiKey: process.env.QUILT_API_KEY,
 });
 
-const containers = await quilt.containers.list();
-console.log(containers);
+const health = await client.system.health();
+const containers = await client.containers.list();
+
+console.log(health.status);
+console.log(containers.containers.length);
 ```
 
 ## Auth
 
 `QuiltClient.connect()` accepts:
 
-- `token` for bearer auth
 - `apiKey` for `X-Api-Key`
-- explicit `auth` union for advanced usage
+- `token` for bearer auth
+- `auth` for the explicit auth union when you need to control the transport directly
+
+If both `apiKey` and `token` are provided, API key auth wins.
+
+## Core Client Shape
+
+```ts
+import { QuiltClient } from "quilt-sdk";
+
+const client = QuiltClient.connect({
+  baseUrl: "https://backend.quilt.sh",
+  apiKey: process.env.QUILT_API_KEY,
+});
+```
+
+Primary SDK surfaces:
+
+- `client.system` for health, info, and activity
+- `client.containers` for container lifecycle, exec, logs, metrics, snapshots, network, and GUI URLs
+- `client.platform` for cross-cutting routes such as operations, env maps, archives, jobs, ICC, OCI, and helper control flows
+- `client.volumes` for volume lifecycle and file browsing
+- `client.clusters` for cluster, node, workload, placement, and join-token control-plane flows
+- `client.agent` for join-token and node-token authenticated agent calls
+- `client.functions` for serverless lifecycle, invoke, versions, invocations, and pool status
+- `client.elasticity` for resize, pool targeting, and orchestrator-safe control actions
+- `client.terminal` and `client.terminalRealtime` for terminal session lifecycle and WebSocket attach
+- `client.events` for SSE streams
+- `client.raw(...)` for authenticated access to backend routes that are intentionally still exposed as raw contract calls
+
+## Public Types
+
+The SDK ships declarations automatically.
+
+Use the client-owned type surface when you need explicit types:
 
-If both `token` and `apiKey` are provided, API key auth is used.
+```ts
+import { QuiltClient } from "quilt-sdk";
+
+const client = QuiltClient.connect({
+  apiKey: process.env.QUILT_API_KEY,
+});
+
+const options: QuiltClient.Options = {
+  baseUrl: "https://backend.quilt.sh",
+  apiKey: process.env.QUILT_API_KEY,
+};
+
+let invocation: QuiltClient.Functions.Invocation | null = null;
+let resize: QuiltClient.Elasticity.ContainerResizeResponse | null = null;
+```
+
+That keeps consumer imports simple while still exposing the production contract.
+
+## Execution Model
+
+Use the SDK in the same execution style the backend expects:
+
+- treat container lifecycle mutations as operation-driven when they return operation metadata
+- treat exec as submit-and-track, not inline command execution
+- use terminal attach and WebSocket flows for interactive sessions
+- invoke a shell explicitly when shell parsing is required
+- prefer typed module methods over `client.raw(...)`
 
 ## Realtime
 
 ### SSE
 
 ```ts
-const source = quilt.events.openEventSource();
-quilt.events.on(source, "container_update", (event) => {
+const source = client.events.openEventSource();
+client.events.on(source, "container_update", (event) => {
   console.log(event.data);
 });
 ```
@@ -53,40 +122,67 @@ quilt.events.on(source, "container_update", (event) => {
 ### WebSocket Terminal
 
 ```ts
-const ws = quilt.terminalRealtime.connect({ container_identifier: "ctr_123", cols: 120, rows: 30 });
+const ws = client.terminalRealtime.connect({
+  container_identifier: "ctr_123",
+  cols: 120,
+  rows: 30,
+});
+
 ws.addEventListener("message", (msg) => {
   if (typeof msg.data === "string") {
-    const parsed = quilt.terminalRealtime.parseServerMessage(msg.data);
+    const parsed = client.terminalRealtime.parseServerMessage(msg.data);
     console.log(parsed);
   }
 });
 ```
 
-## Production Platform Module
+## Examples
 
-The `platform` namespace exposes production endpoints that are part of live backend behavior and script-driven workflows, including:
+The repo ships production-validated examples in [examples/README.md](/home/ubuntu/quilt-sdk/examples/README.md).
 
-- Container env, rename, archive, jobs, ready/resume/fork
-- Snapshot clone and operation status
-- Volume archive/files helpers
-- Network allocations and monitor process queries
-- ICC endpoints
+Example files:
 
-```ts
-const op = await quilt.containers.stop("ctr_123", "async");
-if ("operation_id" in (op as Record<string, unknown>)) {
-  const done = await quilt.awaitOperation((op as { operation_id: string }).operation_id);
-  console.log(done.status);
-}
+- `examples/containers-volumes-and-network.ts`
+- `examples/sdk-runtime-and-functions.ts`
+- `examples/clusters-nodes-workloads-and-k8s.ts`
+- `examples/terminal-and-icc.ts`
+- `examples/elasticity-control.ts`
+- `examples/lifecycle-and-failures.ts`
+
+Run them from the repo root:
+
+```bash
+bun run example:containers
+bun run example:sdk
+bun run example:clusters
+bun run example:terminal
+bun run example:elasticity
+bun run example:lifecycle
+bun run examples:all
+```
+
+Expected environment variables:
+
+```text
+QUILT_BASE_URL=https://backend.quilt.sh
+QUILT_API_KEY=<api_key>
+```
+
+Alternative auth:
+
+```text
+QUILT_JWT=<jwt>
 ```
 
-## Scripts
+## Repository Validation
 
 ```bash
 bun run lint
 bun run typecheck
+bun run examples:typecheck
 bun run test
 bun run build
+bun run examples:all
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilt-sdk",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Fully type-safe TypeScript SDK for Quilt HTTP APIs",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,10 +22,18 @@
     "generate:types": "node ./scripts/generate-contract-types.mjs",
     "build": "bun run generate:types && tsc -p tsconfig.build.json",
     "typecheck": "bun run generate:types && tsc -p tsconfig.json --noEmit",
+    "examples:typecheck": "tsc -p tsconfig.examples.json --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "test": "bun test",
     "test:coverage": "bun test --coverage",
+    "examples:all": "bun run example:containers && bun run example:sdk && bun run example:clusters && bun run example:terminal && bun run example:elasticity && bun run example:lifecycle",
+    "example:containers": "node --env-file=.env --import tsx examples/containers-volumes-and-network.ts",
+    "example:sdk": "node --env-file=.env --import tsx examples/sdk-runtime-and-functions.ts",
+    "example:clusters": "node --env-file=.env --import tsx examples/clusters-nodes-workloads-and-k8s.ts",
+    "example:terminal": "node --env-file=.env --import tsx examples/terminal-and-icc.ts",
+    "example:elasticity": "node --env-file=.env --import tsx examples/elasticity-control.ts",
+    "example:lifecycle": "node --env-file=.env --import tsx examples/lifecycle-and-failures.ts",
     "prepublishOnly": "bun run clean && bun run lint && bun run typecheck && bun run test && bun run build"
   },
   "keywords": ["quilt", "sdk", "api", "typescript", "bun"],
@@ -33,8 +41,13 @@
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@types/node": "^24.0.0",
+    "@types/ws": "^8.18.1",
     "bun-types": "^1.3.0",
+    "eventsource": "^3.0.7",
     "openapi-typescript": "^7.6.1",
-    "typescript": "^5.8.3"
+    "protobufjs": "^8.0.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3",
+    "ws": "^8.20.0"
   }
 }