@brimble/sandbox 0.1.0

package/CODEX.md

@@ -0,0 +1,188 @@
+# Coding Guidelines
+
+These are the rules you follow when writing or modifying code in this codebase. Read them once, apply them always.
+
+## 1. Separation of concerns
+
+Keep functions, types, enums, and classes in their own files (or at minimum, their own clearly-scoped sections). Do not mix concerns.
+
+- One responsibility per unit. A function does one thing; a class models one concept; a type describes one shape.
+- Types and enums live in dedicated files (`types.ts`, `enums.ts`, or a `types/` / `enums/` folder) unless they are trivially local to a single consumer.
+- Do not co-locate unrelated helpers inside a class or module just because they happen to touch the same data.
+- If a file starts doing two jobs, split it.
+
+## 2. Ternaries: short and flat, or not at all
+
+Use a ternary only when it is short, single-line, and obvious at a glance.
+
+```ts
+// Good
+const label = isActive ? 'on' : 'off';
+
+// Bad — nested
+const label = isActive ? (isAdmin ? 'admin-on' : 'user-on') : isAdmin ? 'admin-off' : 'user-off';
+```
+
+No nested ternaries. Ever. If branching gets past one level, use `if`/`else` or extract a function. Readability wins over cleverness.
+
+## 3. Stop using `typeof` everywhere
+
+`typeof` is a narrowing tool, not a default check. Do not reach for it when a simple truthy/falsy check is enough.
+
+```ts
+// Good
+if (!user) return;
+if (value) process(value);
+
+// Bad
+if (typeof user !== "undefined" && user !== null) { ... }
+if (typeof value === "string" && value.length > 0) { ... }  // when you just need truthiness
+```
+
+Use `typeof` only when you genuinely need to discriminate primitive types (e.g. inside a union where `string | number` matters). Otherwise, trust truthiness, optional chaining, and nullish coalescing.
+
+## 4. No over-engineered guard rails
+
+Write defenses for realistic failure modes, not hypothetical ones.
+
+- Validate at system boundaries (HTTP input, DB reads, external APIs). Do not re-validate the same data at every internal function call.
+- No `assert` chains at the top of ever4y function.
+- No wrapping every call in try/catch "just in case" — let errors bubble to a single handler that knows what to do with them.
+- If a guard clause is protecting against a case that cannot happen given the types, delete it.
+- Prefer types and schemas over runtime paranoia.
+
+The goal is correctness, not defensiveness theatre.
+
+## 5. Follow popular conventions
+
+Use the community standard for the language and ecosystem. Do not invent personal styles.
+
+- **TypeScript/JavaScript**: ESLint + Prettier defaults, camelCase for variables/functions, PascalCase for types/classes, `kebab-case` or `camelCase` file names consistent with the project.
+- **Go**: `gofmt`, idiomatic error handling (`if err != nil`), package names short and lowercase, no stutter.
+- **Python**: PEP 8, `ruff`/`black` formatting, `snake_case`.
+- Match the project's existing style before imposing anything new. When in doubt, grep the codebase and do what it already does.
+
+## 6. Comments: only when they add something
+
+Code should read itself. Comments are for things the code cannot say.
+
+Write a comment when:
+
+- The _why_ is non-obvious (business rule, workaround for an upstream bug, performance-sensitive choice).
+- A public API needs a docstring for consumers.
+- A `TODO` / `FIXME` with context and ownership.
+
+Do not write a comment when:
+
+- It restates the code (`// increment counter` above `counter++`).
+- It narrates obvious control flow (`// loop through users`).
+- It was auto-generated boilerplate that nobody reads.
+
+Delete stale comments on sight. A wrong comment is worse than no comment.
+
+## 7. Don't re-invent what already exists
+
+Before writing a helper, check:
+
+1. The language's stdlib.
+2. The framework the project uses.
+3. Utilities already in this codebase.
+
+Do not write a custom `debounce`, `deepClone`, `groupBy`, UUID generator, date parser, retry loop, or config loader when a well-tested one is already available. Do not introduce a second HTTP client, a second logger, or a second error class when the repo already has one — use what's there.
+
+The only reasons to roll your own: the existing option is genuinely insufficient, or pulling it in costs more than writing it.
+
+## 8. No `any`, no `as unknown as T`
+
+When types get annoying, fix the type — don't escape it.
+
+- `any` is banned except at genuine interop edges (and even then, narrow immediately).
+- `as` casts are a last resort. If you're writing `as unknown as T`, the real answer is usually a type guard, a discriminated union, or a schema parse (Zod, etc.).
+- `// @ts-ignore` and `// @ts-expect-error` require a comment explaining why.
+
+The type system earns its keep when you respect it.
+
+## 9. Delete dead code
+
+- No commented-out blocks "for reference." Git remembers.
+- No unused imports, unused variables, unused parameters (prefix with `_` if the signature forces it).
+- No stale feature flags still wired up months after launch.
+- No "v2" helper sitting next to the original with no caller.
+
+If it isn't used, it leaves.
+
+## 10. Consistent error handling
+
+Pick one error strategy per layer and stick to it.
+
+- Don't mix `throw`, `Result<T, E>`, `null` returns, and `{ error, data }` tuples in the same module.
+- Don't catch errors only to re-throw them unchanged — that's noise.
+- Don't swallow errors with empty `catch {}`. If you genuinely want to ignore one, log it or leave a comment saying why.
+- Handle errors at the layer that knows what to do with them (usually the HTTP handler or job runner), not at every function on the way down.
+
+## 11. No magic numbers or magic strings
+
+Named constants and enums beat literals scattered through the code.
+
+```ts
+// Bad
+setTimeout(retry, 86400000);
+if (user.status === "active") { ... }
+
+// Good
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+setTimeout(retry, ONE_DAY_MS);
+if (user.status === UserStatus.Active) { ... }
+```
+
+If a value appears more than once, or its meaning isn't obvious from the number/string alone, name it.
+
+## 12. Async correctness
+
+- Always `await` or explicitly handle the promise. No dangling promises.
+- Parallelize independent work with `Promise.all`; don't serialize it in a `for` loop by accident.
+- Don't mix `.then()` chains and `await` in the same function — pick one.
+- Handle rejections. An unhandled rejection in production is a bug waiting to page you.
+
+## 13. Don't mutate function arguments
+
+Treat inputs as read-only. If you need a modified version, return a new one.
+
+```ts
+// Bad
+function addTag(user, tag) {
+  user.tags.push(tag);
+  return user;
+}
+
+// Good
+function addTag(user, tag) {
+  return { ...user, tags: [...user.tags, tag] };
+}
+```
+
+Hidden mutation through a function call is one of the worst bugs to trace in a large system.
+
+## 14. Respect the codebase's existing patterns
+
+Before introducing something new, look around:
+
+- If the project uses a specific HTTP client, logger, error class, config loader, or validation library — use it.
+- If there's an established folder structure, follow it.
+- If there's a naming convention in neighboring files, match it.
+
+Don't bring in a new dependency or pattern just because it's what you reached for first. Consistency across the codebase is worth more than any individual preference.
+
+## 15. No hardcoded environment values
+
+URLs, ports, credentials, feature flags, and tunable limits belong in config or environment variables — not in source.
+
+- Secrets never land in the repo. Not even temporarily.
+- Defaults for local dev are fine in a `.env.example` or config file, but the real values are injected.
+- If a value differs between staging and prod, it's config.
+
+---
+
+## Summary
+
+Clean separation, flat logic, minimal runtime paranoia, community idioms, and comments only where they earn their place. Reuse what exists, respect the type system, delete what's dead, handle errors consistently, and keep configuration out of source. If a change adds complexity without earning it, reject the change.

package/PLAN.md

@@ -0,0 +1,364 @@
+# `@brimble/sandbox` — SDK Plan
+
+A TypeScript SDK that wraps the Brimble Sandbox API (`https://sandbox.brimble.io`). It exposes two top-level resources — **sandboxes** and **volumes** — plus their nested sub-resources (exec, code, files, stats, snapshots).
+
+The SDK is the canonical way for first- and third-party clients (Node services, CLIs, CI, the Brimble dashboard) to talk to the Sandbox API. It must work in Node ≥ 20. Browser support is **out of scope for v1**.
+
+This plan follows the rules in [CODEX.md](../CODEX.md): one responsibility per file, flat logic, no runtime paranoia, no reinvented helpers, no `any`, consistent error handling.
+
+---
+
+## 1. Goals & non-goals
+
+### Goals
+- Type-safe wrapper over every route in [`src/routes/v1/sandbox.route.ts`](../src/routes/v1/sandbox.route.ts) and [`src/routes/v1/volume.route.ts`](../src/routes/v1/volume.route.ts).
+- Match the OpenAPI contract in [`docs/sandbox-openapi.yaml`](./sandbox-openapi.yaml) exactly — request shape, response shape, status codes, query params.
+- One client instance, configured once, used for every call. No per-call URL/auth juggling.
+- First-class file streaming (PUT/GET `/files/*`) without buffering whole files in memory.
+- Errors surface as a single typed class (`SandboxApiError`) carrying status + server message — never a thrown raw `Response`.
+- Zero hidden defaults. The caller chooses retries, timeouts, fetch impl. No magic numbers in source.
+
+### Non-goals (v1)
+- Browser bundle / `window.fetch` polyfilling.
+- Ably real-time subscription helpers — the API events (`sandbox:ready`, `sandbox:paused`, etc.) are documented in the OpenAPI; subscription is the caller's problem for now. Tracked as a v1.1 follow-up.
+- HMAC request signing — middleware is a no-op today ([`src/middlewares/hmac.middleware.ts:1`](../src/middlewares/hmac.middleware.ts)). When it's switched on we'll add a `signer` option, not before.
+- A CLI. Separate package, separate plan.
+
+---
+
+## 2. Package layout
+
+```
+packages/sandbox-sdk/
+├── src/
+│   ├── client.ts              # SandboxClient — composes resources, owns transport
+│   ├── transport/
+│   │   ├── http.ts            # request() — fetch wrapper, envelope unwrap, error mapping
+│   │   ├── auth.ts            # buildAuthHeader(token)
+│   │   └── pagination.ts      # toPaginationQuery({ page, limit })
+│   ├── resources/
+│   │   ├── sandboxes.ts       # SandboxesResource — list/get/create/destroy/pause/resume
+│   │   ├── exec.ts            # ExecResource — exec, runCode
+│   │   ├── files.ts           # FilesResource — put/get with streams
+│   │   ├── stats.ts           # StatsResource — stats
+│   │   ├── snapshots.ts       # SnapshotsResource — create/list/listAll/delete
+│   │   └── volumes.ts         # VolumesResource — list/get/create/delete
+│   ├── errors/
+│   │   ├── sandbox-api-error.ts
+│   │   └── index.ts
+│   ├── types/
+│   │   ├── sandbox.ts         # Sandbox, SandboxStatus, SandboxSpecs, CreateSandboxInput…
+│   │   ├── snapshot.ts
+│   │   ├── volume.ts
+│   │   ├── exec.ts
+│   │   ├── stats.ts
+│   │   ├── pagination.ts
+│   │   └── index.ts
+│   ├── enums/
+│   │   ├── sandbox-status.ts
+│   │   ├── destroy-reason.ts
+│   │   ├── snapshot-mode.ts
+│   │   ├── code-language.ts
+│   │   ├── volume-type.ts
+│   │   └── index.ts
+│   ├── constants.ts           # DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, MAX_PAGE_LIMIT…
+│   └── index.ts               # public re-exports — SandboxClient + every type/enum/error
+├── test/
+│   ├── sandboxes.test.ts
+│   ├── volumes.test.ts
+│   ├── exec.test.ts
+│   ├── files.test.ts
+│   ├── stats.test.ts
+│   ├── snapshots.test.ts
+│   ├── errors.test.ts
+│   └── fixtures/              # canned API responses
+├── examples/
+│   ├── create-and-exec.ts
+│   ├── upload-download.ts
+│   ├── persistent-with-volume.ts
+│   └── snapshot-and-restore.ts
+├── package.json
+├── tsconfig.json
+├── tsup.config.ts             # build config (ESM + CJS + d.ts)
+├── vitest.config.ts
+└── README.md
+```
+
+Rationale: one responsibility per file (CODEX §1). Types and enums live in their own folders (CODEX §1, §11). Transport (HTTP, auth, pagination) is independent of business resources so it's testable in isolation.
+
+---
+
+## 3. Public surface
+
+The whole SDK is one class. Sub-resources are properties.
+
+```ts
+import { SandboxClient } from '@brimble/sandbox';
+
+const brimble = new SandboxClient({
+  apiKey: process.env.BRIMBLE_API_KEY,            // bearer token (JWT or API key)
+  baseUrl: 'https://sandbox.brimble.io',          // optional, defaults to prod
+  timeoutMs: 30_000,                              // optional
+});
+
+// Sandboxes
+await brimble.sandboxes.list({ page: 1, limit: 15 });
+await brimble.sandboxes.get(id);
+await brimble.sandboxes.create({ region, template, persistent: true, persistentDiskGB: 20 });
+await brimble.sandboxes.destroy(id);
+await brimble.sandboxes.pause(id);
+await brimble.sandboxes.resume(id);
+
+// Runtime — nested under .sandboxes(id) for ergonomics, but routes to the same transport
+const sb = brimble.sandboxes.scoped(id);
+await sb.exec({ cmd: 'ls -la', timeout_seconds: 30 });
+await sb.runCode({ language: CodeLanguage.Python, code: 'print(1+1)' });
+await sb.files.put('tmp/notes.txt', readable);
+const stream = await sb.files.get('tmp/notes.txt');
+
+// Stats
+await sb.stats({ hoursAgo: 6 });
+
+// Snapshots
+await sb.snapshots.create({ name: 'before-migration' });
+await sb.snapshots.list({ page: 1, limit: 15 });
+await brimble.snapshots.listAll({ page: 1, limit: 50 });
+await brimble.snapshots.delete(snapshotId);
+
+// Volumes
+await brimble.volumes.list({ page: 1, limit: 15 });
+await brimble.volumes.get(volumeId);
+await brimble.volumes.create({ name: 'pg-data', sizeGB: 20, region, type: VolumeType.Database });
+await brimble.volumes.delete(volumeId);
+```
+
+### Method ↔ route map
+
+| Method                                        | HTTP                                        | Notes |
+|-----------------------------------------------|---------------------------------------------|-------|
+| `sandboxes.create(input)`                     | `POST /sandboxes`                           | Returns `CreateSandboxResult`. Async transition — caller subscribes to Ably for `sandbox:ready` |
+| `sandboxes.list(query)`                       | `GET /sandboxes`                            | Paginated |
+| `sandboxes.get(id)`                           | `GET /sandboxes/:id`                        |       |
+| `sandboxes.destroy(id)`                       | `DELETE /sandboxes/:id`                     | Idempotent, returns `void` on `204` |
+| `sandboxes.pause(id)`                         | `POST /sandboxes/:id/pause`                 | Persistent only — server enforces |
+| `sandboxes.resume(id)`                        | `POST /sandboxes/:id/resume`                |       |
+| `sb.exec(input)`                              | `POST /sandboxes/:id/exec`                  |       |
+| `sb.runCode(input)`                           | `POST /sandboxes/:id/code`                  |       |
+| `sb.files.put(path, body)`                    | `PUT /sandboxes/:id/files/{path}`           | `body` is `ReadableStream \| Buffer \| Uint8Array`. Streams pass-through; never buffer. |
+| `sb.files.get(path)`                          | `GET /sandboxes/:id/files/{path}`           | Returns `ReadableStream` |
+| `sb.stats(query)`                             | `GET /sandboxes/:id/stats`                  |       |
+| `sb.snapshots.create(input)`                  | `POST /sandboxes/:id/snapshots`             | `202` accepted |
+| `sb.snapshots.list(query)`                    | `GET /sandboxes/:id/snapshots`              |       |
+| `snapshots.listAll(query)`                    | `GET /sandboxes/snapshots`                  | Caller-wide |
+| `snapshots.delete(snapshotId)`                | `DELETE /sandboxes/snapshots/:snapshotId`   |       |
+| `volumes.list(query)`                         | `GET /volumes`                              |       |
+| `volumes.create(input)`                       | `POST /volumes`                             |       |
+| `volumes.get(volumeId)`                       | `GET /volumes/:volumeId`                    |       |
+| `volumes.delete(volumeId)`                    | `DELETE /volumes/:volumeId`                 |       |
+
+Method naming: `delete` is a reserved word but valid as a property name; we use it because consumers will reach for it first. No `_id` suffixes in method names (CODEX §5 — community idioms).
+
+---
+
+## 4. Transport layer
+
+A single `request()` function in [`transport/http.ts`](#) does:
+
+1. Build the URL (`${baseUrl}${path}`).
+2. Build headers (`Authorization`, `Content-Type`, caller-provided).
+3. Call `fetch` with an `AbortSignal` from `AbortSignal.timeout(timeoutMs)`.
+4. If `response.status === 204` → return `undefined`.
+5. If `response.ok` and the response is JSON → parse, unwrap the `{ message, data }` envelope, return `data`.
+6. If `response.ok` and the response is binary (file download) → return `response.body` (`ReadableStream`).
+7. Otherwise → parse `{ message }`, throw `SandboxApiError`.
+
+This is the only place that touches `fetch`. Resources call `this.transport.request(...)` and never see the envelope.
+
+### Why one envelope-unwrapping path
+The OpenAPI guarantees every non-204 JSON response uses `{ message, data }`. Centralising the unwrap means resources return the right shape without each one duplicating the same `(await res.json()).data` line. If the envelope ever changes, one file changes. (CODEX §4 — no defensive paranoia at every call site; CODEX §10 — one error strategy per layer.)
+
+### File streaming
+- `PUT /files/*`: pass the caller's `ReadableStream | Buffer | Uint8Array` straight to `fetch` as `body`. Set `Content-Type: application/octet-stream`. If the caller passes a `Buffer`, set `Content-Length` so the server can reject oversize uploads before reading the body (per OpenAPI guidance).
+- `GET /files/*`: return `response.body`. Caller is responsible for piping / consuming. We **do not** `await response.arrayBuffer()` — that defeats the point.
+- Path encoding: the API rejects `%2F`. We split the user's path on `/` and `encodeURIComponent` each segment, then `.join('/')`. Documented in the JSDoc on `files.put` / `files.get`.
+
+### Retries
+Out of scope for v1. Sandbox state transitions are async and idempotent semantics vary per endpoint (DELETE is documented idempotent; POST is not). A naive retry on `POST /sandboxes` could spin up duplicates. We expose `fetch` as an option so callers who want retries can wrap their own fetch (e.g. `undici`'s retry agent).
+
+### Timeouts
+Single `timeoutMs` on the client, overridable per-call via a third arg `{ signal }` on every method. Default is **30 s** — exposed as `DEFAULT_TIMEOUT_MS` in `constants.ts` (CODEX §11 — no magic numbers).
+
+---
+
+## 5. Auth
+
+Bearer token only. Constructor takes `apiKey` (named that, not `token`, since the route mounting uses `apiKeyMiddleware`). Header is `Authorization: Bearer <apiKey>`.
+
+The SDK does **not** read environment variables itself. The caller passes the key. (CODEX §15 — no hardcoded env values in source; that includes "automatically read `BRIMBLE_API_KEY`" magic that surprises people.) Examples in `README.md` show the `process.env` pattern at the call site.
+
+Future: when HMAC signing is enabled server-side, add a `signer?: RequestSigner` option that takes `(req) => headers`. Not implemented in v1.
+
+---
+
+## 6. Types & enums
+
+Generated by hand from the OpenAPI for v1. We do **not** ship `openapi-typescript` output — the generated unions are noisy and we want the SDK types to be the source of truth for consumers.
+
+Every domain type from the OpenAPI gets a `.ts` file in `src/types/`:
+
+- `Sandbox`, `CreateSandboxInput`, `CreateSandboxResult`, `SandboxSpecs`
+- `Snapshot`, `CreateSnapshotInput`
+- `Volume`, `CreateVolumeInput`
+- `ExecInput`, `ExecResult`, `CodeInput`
+- `Stats`, `StatsAverageNumeric`, `StatsAverageNetwork`, `StatsTimelinePoint`
+- `Pagination`, `Paginated<T>`
+
+Every closed string union in the OpenAPI becomes a TypeScript `enum`:
+
+- `SandboxStatus` (`starting | ready | pausing | paused | resuming | failed | destroyed`)
+- `DestroyReason` (`user | idle_ttl | max_lifetime | one_shot_stopped | failed | paused_too_long`)
+- `SnapshotMode` (`manual | automatic`)
+- `SnapshotStatus` (`creating | ready | failed`)
+- `CodeLanguage` (`python | node`)
+- `DestroyTimeout` (`30m | 1h | 3h | 6h | 12h | 18h`)
+- `VolumeType` (`web | database | sandbox`) — matches [`src/enum/index.ts:171`](../src/enum/index.ts)
+
+Rule: no inline string literals in resource code. `if (sandbox.status === SandboxStatus.Ready)`, not `=== 'ready'` (CODEX §11).
+
+Field-naming note: the OpenAPI uses `snake_case` for response fields (`created_at`, `last_activity_at`, `expires_at`, `exit_code`, `duration_ms`). The SDK preserves that — **no auto-camelCasing of response payloads.** A consumer who sees `sandbox.created_at` in the API docs should see the same in TypeScript. Request inputs use whatever case the OpenAPI specifies (a mix — `teamId`, `volumeId`, `persistentDiskGB`, `hoursAgo`, but `timeout_seconds`). We mirror the spec; we don't normalise it.
+
+---
+
+## 7. Errors
+
+One class, in [`errors/sandbox-api-error.ts`](#):
+
+```ts
+export class SandboxApiError extends Error {
+  readonly status: number;
+  readonly endpoint: string;       // e.g. 'POST /sandboxes/:id/exec'
+  readonly responseBody: unknown;  // parsed JSON or raw text — for debugging
+
+  constructor(args: { status: number; message: string; endpoint: string; responseBody: unknown }) {
+    super(args.message);
+    this.name = 'SandboxApiError';
+    this.status = args.status;
+    this.endpoint = args.endpoint;
+    this.responseBody = args.responseBody;
+  }
+}
+```
+
+That's it. No subclass-per-status (`NotFoundError`, `ForbiddenError`, …) in v1 — consumers branch on `err.status` if they care. We can add tagged subclasses later without breaking callers.
+
+Network failures and aborts surface as the raw `TypeError` / `AbortError` from `fetch` — we don't wrap them. CODEX §10: don't catch errors only to re-throw them unchanged.
+
+---
+
+## 8. Pagination
+
+Helper in `transport/pagination.ts`:
+
+```ts
+export function toPaginationQuery({ page, limit }: Pagination): URLSearchParams { ... }
+```
+
+Constants:
+
+```ts
+export const DEFAULT_PAGE = 1;
+export const DEFAULT_PAGE_LIMIT = 15;
+export const MAX_PAGE_LIMIT = 100;
+```
+
+(Matches OpenAPI defaults / caps; CODEX §11.)
+
+No client-side validation that `limit <= 100` — the server enforces, and re-validating at every boundary is paranoia (CODEX §4). Server returns `400` → consumer gets a clear `SandboxApiError`.
+
+Optional `auto-paginate` async iterator helpers (`for await (const sandbox of brimble.sandboxes.iterate())`) are nice-to-have but **not in v1**. Tracked as v1.1.
+
+---
+
+## 9. Build & tooling
+
+- **Language**: TypeScript, `strict: true`, no `any`, no `as unknown as T` (CODEX §8).
+- **Bundler**: `tsup` → `dist/index.js` (CJS), `dist/index.mjs` (ESM), `dist/index.d.ts`. `package.json` declares both via `exports`.
+- **Target**: Node 20. We rely on `globalThis.fetch`, `AbortSignal.timeout`, and `ReadableStream` from undici — all GA in Node 20.
+- **Lint/format**: ESLint + Prettier with the monorepo defaults (CODEX §5).
+- **Tests**: Vitest. `msw` (Mock Service Worker) intercepts `fetch` and serves canned responses from `test/fixtures/`. No live API calls in CI.
+- **CI**: GitHub Actions matrix on Node 20 and 22 — lint, typecheck, test, build.
+- **Publishing**: `npm publish --access public` to npm under `@brimble`. Semver. Changesets for changelog.
+
+---
+
+## 10. Testing strategy
+
+One spec file per resource. Each spec covers:
+
+1. **Happy path** — fixture returns the envelope, SDK returns unwrapped `data`. Assert the exact request URL, method, headers, body.
+2. **204 path** — for `destroy`, `delete`, `files.put`. Assert the method returns `undefined`, not `{ message }`.
+3. **Error path** — fixture returns 400/403/404 with `{ message }`. Assert a `SandboxApiError` with the right `status`, `message`, `endpoint`.
+4. **Streaming** — for `files.put` / `files.get`. Use a `Readable` from `node:stream` and assert the body reaches the mocked endpoint un-buffered (msw exposes the raw request).
+5. **Auth header** — every method sends `Authorization: Bearer <key>`.
+
+Integration tests (live API) are run manually against staging, not in CI — covered in [verify.md](https://example) (out of scope here).
+
+Coverage target: **90% line, 100% on transport/**. Transport is the load-bearing piece; resources are mostly thin wiring.
+
+---
+
+## 11. Coding standards (recap against CODEX.md)
+
+| Rule                          | How the SDK applies it |
+|-------------------------------|------------------------|
+| §1 Separation of concerns     | One file per resource, per type, per enum. Transport split from resources. |
+| §2 No nested ternaries        | Use `if/else` in `transport/http.ts` status branching. |
+| §3 No `typeof` everywhere     | Discriminate `Buffer \| Uint8Array \| ReadableStream` with `body instanceof Readable` / `Buffer.isBuffer`, not `typeof`. |
+| §4 No over-engineered guards  | No client-side re-validation of OpenAPI patterns. Server is authoritative. |
+| §5 Community conventions      | ESLint + Prettier, camelCase methods, PascalCase types, kebab-case files. |
+| §6 Comments earn their place  | Public methods get JSDoc (it's a published SDK). Internal helpers stay uncommented. |
+| §7 No reinvention             | Use `URL`, `URLSearchParams`, `AbortSignal.timeout`, `globalThis.fetch`. No custom retry / debounce / deepClone. |
+| §8 No `any`, no `as unknown as T` | Every public method is fully typed. Internal `JSON.parse` result is typed via a single `parseEnvelope<T>` helper backed by a runtime shape check at the transport edge only. |
+| §9 Delete dead code           | No "// will be useful later" branches. |
+| §10 Consistent errors         | One `SandboxApiError` class. No mixed throw / Result / null. |
+| §11 No magic numbers          | `DEFAULT_TIMEOUT_MS`, `DEFAULT_PAGE_LIMIT`, `MAX_PAGE_LIMIT` in `constants.ts`. |
+| §12 Async correctness         | Every `fetch` is awaited. No `.then()` chains mixed with `await`. |
+| §13 No mutation of args       | Resource methods treat input objects as read-only — body is `JSON.stringify(input)`, never `input.foo = …`. |
+| §14 Respect existing patterns | Mirror server-side naming (`teamId`, `environmentId`, `persistentDiskGB`) so docs and SDK line up. |
+| §15 No hardcoded env values   | `apiKey` is required at construction; no `process.env` reads inside the package. |
+
+---
+
+## 12. Delivery plan
+
+1. **Skeleton** — package layout, `tsup` + Vitest + ESLint wired up. README stub. (≈ 0.5 day)
+2. **Transport + auth + errors + pagination** — covered by unit tests with msw. (≈ 1 day)
+3. **Sandboxes resource** — create / list / get / destroy / pause / resume + types/enums. (≈ 1 day)
+4. **Runtime resource** — exec / runCode + types. (≈ 0.5 day)
+5. **Files resource** — put / get with streaming, path-encoding helper, tests. (≈ 1 day)
+6. **Stats resource** — stats. (≈ 0.5 day)
+7. **Snapshots resource** — create / list / listAll / delete. (≈ 0.5 day)
+8. **Volumes resource** — list / create / get / delete. (≈ 0.5 day)
+9. **Examples + README** — 4 runnable example scripts; README with auth, install, quickstart, full API reference auto-linked to OpenAPI sections. (≈ 1 day)
+10. **Manual smoke against staging** — every method, every status path. (≈ 0.5 day)
+11. **Publish v0.1.0** to npm with `--tag next`. Internal teams kick the tires for a week. Promote to `latest` once we've taken feedback and bumped to `v1.0.0`.
+
+Total: ~7 dev-days. Single owner.
+
+---
+
+## 13. Open questions
+
+1. **Region resolution** — `CreateSandboxInput.region` is a region `_id`. Should the SDK expose a `brimble.regions.list()` helper, even though the OpenAPI doesn't include the regions endpoint? Defer to v1.1 unless someone asks for it.
+2. **Ably channel helper** — if we ship a `brimble.events.subscribe(sandboxId, handler)` helper, do we pull in `ably` as a dep, or expose just the channel name and let callers BYO client? Lean toward the latter — keeps the install slim. Decide before v1.1.
+3. **Browser support** — same SDK or a separate `@brimble/sandbox-browser`? Sandbox API is bearer-token only, which is risky to expose in a browser. Punt until there's a real use case.
+4. **HMAC** — once the server enforces `X-Brimble-Signature`, we'll need a `signer` option. Confirm the signing payload format with platform team before shipping.
+
+---
+
+## 14. Reference
+
+- API spec: [`docs/sandbox-openapi.yaml`](./sandbox-openapi.yaml)
+- Server routes: [`src/routes/v1/sandbox.route.ts`](../src/routes/v1/sandbox.route.ts), [`src/routes/v1/volume.route.ts`](../src/routes/v1/volume.route.ts)
+- Server-side validation (mirror the rules, don't duplicate them client-side): [`src/validations/sandbox.validation.ts`](../src/validations/sandbox.validation.ts), [`src/validations/volume.validation.ts`](../src/validations/volume.validation.ts)
+- Coding standards: [`CODEX.md`](../CODEX.md)