Problem
Today the only clients for the /v1 HTTP control plane are sandboxwich-cli (Rust) and raw HTTP calls. There is no typed Python or TypeScript client, so every integration re-implements auth headers, the Idempotency-Key/x-request-id conventions, the { "ok": false, "code", "message" } error envelope, and the async-operation polling/SSE-reconnect pattern (GET /v1/operations/{id}, GET /v1/operations/{id}/events with Last-Event-ID) from scratch.
Evidence
README.md "Public API contract" section documents a stable, versioned /v1 surface with a runtime-generated OpenAPI document served at /v1/openapi.json (crates/sandboxwich-api, compiled from Rust handler/schema types) — this is complete enough to generate or hand-write typed clients against.crates/: only sandboxwich-cli (Rust) exists as a client crate; no sdks/, clients/, or equivalent Python/TypeScript package directory exists in the repo today.- The OpenAPI document coverage itself is out of scope here (already complete per current review) — this issue is specifically about consumable typed clients built on top of it, not the spec itself.
Suggested approach
- Generate (or hand-write, validated against
/v1/openapi.json) a Python SDK covering auth (shared-token and tenant-token modes), sandbox CRUD, command exec with the async-operation poll/SSE pattern, snapshots/forks, and typed error handling on the code field.
- Same for TypeScript, likely fetch-based with typed request/response interfaces matching the OpenAPI schemas.
- Ship runnable examples for both (e.g. "create a sandbox, run a command, stream events, clean up") mirroring the
README.md quick-start flow, so the SDKs are exercised rather than just published.
Status
A Python SDK PR is in progress today (parallel effort) — not yet numbered. This issue tracks the TypeScript SDK and runnable examples for both as remaining backlog.
Problem
Today the only clients for the
/v1HTTP control plane aresandboxwich-cli(Rust) and raw HTTP calls. There is no typed Python or TypeScript client, so every integration re-implements auth headers, theIdempotency-Key/x-request-idconventions, the{ "ok": false, "code", "message" }error envelope, and the async-operation polling/SSE-reconnect pattern (GET /v1/operations/{id},GET /v1/operations/{id}/eventswithLast-Event-ID) from scratch.Evidence
README.md"Public API contract" section documents a stable, versioned/v1surface with a runtime-generated OpenAPI document served at/v1/openapi.json(crates/sandboxwich-api, compiled from Rust handler/schema types) — this is complete enough to generate or hand-write typed clients against.crates/: onlysandboxwich-cli(Rust) exists as a client crate; nosdks/,clients/, or equivalent Python/TypeScript package directory exists in the repo today.Suggested approach
/v1/openapi.json) a Python SDK covering auth (shared-token and tenant-token modes), sandbox CRUD, command exec with the async-operation poll/SSE pattern, snapshots/forks, and typed error handling on thecodefield.README.mdquick-start flow, so the SDKs are exercised rather than just published.Status
A Python SDK PR is in progress today (parallel effort) — not yet numbered. This issue tracks the TypeScript SDK and runnable examples for both as remaining backlog.