@boxrouter/sdk 0.0.1-alpha.0 → 0.12.190

package/NOTICE

@@ -1,15 +1,39 @@
 BoxRouter TypeScript SDK
-Copyright 2026 BoxRouter
+Copyright 2026 BoxRouter, Inc.
 
 This distribution contains API client code generated from BoxRouter's OpenAPI
 contract and runtime support authored by BoxRouter. Third-party packages are
 installed separately and remain under their respective licenses.
 
 The OpenAPI contract includes schema material from the separately licensed
-Sandbox Provider Specification and provider-pricing projects. Both projects are
-licensed under Apache License 2.0; see their authoritative license files:
-https://github.com/boxrouter/sandbox-provider-spec/blob/main/LICENSE
-https://github.com/boxrouter/sandbox-provider-pricing/blob/main/LICENSE
+Sandbox Provider Specification and sandbox-provider-pricing projects. Both projects are
+licensed under Apache License 2.0; the Apache License text is included in LICENSE
+
+The files under dist/client and dist/core are runtime code emitted by
+@hey-api/openapi-ts (https://github.com/hey-api/openapi-ts), which is licensed
+under the MIT License:
+
+MIT License
+
+Copyright (c) Hey API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
 
 Provider names, provider API descriptions, and linked provider documentation
 remain the property of their respective owners. References do not imply

package/README.md

@@ -1,36 +1,509 @@
-# BoxRouter JavaScript SDK — discovery preview
+# BoxRouter TypeScript SDK
 
-An early, read-only client for discovering the provider routes available to your
-BoxRouter workspace. Requires Node.js 22.18 or later and access to a BoxRouter
-deployment. Sandbox creation and other SDK operations are not included.
-The API may change before the full SDK release.
+> **Alpha.** The API can change in any release, and a release can be withdrawn.
+> Pin an exact version.
 
-This release uses the `alpha` tag; no `latest` release is published.
+Requires the Node.js version declared in the package manifest's `engines.node` field. Install the SDK from npm:
 
 ```sh
-npm install @boxrouter/sdk@alpha
+npm install @boxrouter/sdk
 ```
 
-```js
-import { listProviders } from '@boxrouter/sdk';
+The package contains CommonJS JavaScript and TypeScript declarations. Use the
+named ESM import from an `.mjs` file or a project with `"type": "module"`;
+CommonJS applications can use `require('@boxrouter/sdk')` from `.cjs` files.
 
-const result = await listProviders({
-  baseUrl: process.env.BOXROUTER_BASE_URL,
-  auth: process.env.BOXROUTER_API_KEY,
-  throwOnError: true,
+Create an execution API key in BoxRouter, configure a provider account such as
+E2B or Modal. Provider credentials stay in BoxRouter. Sandbox creation may
+incur charges from the selected provider:
+
+```sh
+export BOXROUTER_API_KEY='your-execution-key'
+```
+
+The client defaults to the hosted API. Set `BOXROUTER_BASE_URL` (or pass `baseUrl`)
+for another deployment.
+
+<!-- quickstart:start -->
+```typescript
+import { BoxRouter } from '@boxrouter/sdk';
+
+const client = new BoxRouter({
+  apiKey: process.env.BOXROUTER_API_KEY,
+});
+let box;
+try {
+  box = await client.sandboxes.create({});
+  await box.files.write('/tmp/hello.txt', 'hello');
+  const result = await box.exec('cat /tmp/hello.txt');
+  process.stdout.write(result.stdout);
+} finally {
+  try {
+    if (box) await box.destroy();
+  } finally {
+    await client.close();
+  }
+}
+```
+<!-- quickstart:end -->
+
+The example prints `hello`.
+
+`box.destroy()` asks BoxRouter to destroy the remote sandbox and returns the `Sandbox` Cloud
+answers with (see "The sandbox object" below). `client.close()`
+closes only the local Node connection pool; it does not affect the sandbox. If
+destroying the sandbox fails or its response is lost, the remote outcome is
+unknown and should be checked before you try again. Closing still releases the
+local connection pool. A client created with a caller-supplied `fetch` does not
+close that fetch implementation; a `withUserAgentSuffix()` view does not own
+the parent client's pool. Closing either one therefore does not close the
+custom transport or the parent's pool; close the owning client instead. Before
+awaiting `client.close()`, consume or cancel any active response streams. The
+pool closes gracefully after in-flight requests finish, so an unread stream can
+keep `close()` pending.
+
+The following blocks are fragments. Create a fresh client as above and close it when you finish.
+Destroy any sandbox you create; the examples below show cleanup for their own sandboxes.
+
+To receive Cloud's bounded Server-Timing measurements, opt in with a fetch wrapper.
+The callback runs after the response body is consumed or canceled; `clientMs` includes
+fetch and body transfer, while `cloudMs`, `databaseMs`, `codeMs`, `providerConnectMs`
+and `providerWaitMs` are `null` when the server does not provide them. The wrapper keeps
+native `Response.clone()` behavior and pulls stream data only when the caller reads it.
+The callback receives only these durations and never request or credential data.
+
+```typescript
+import { BoxRouter, createServerTimingFetch } from '@boxrouter/sdk';
+
+const client = new BoxRouter({
+  apiKey: process.env.BOXROUTER_API_KEY!,
+  fetch: createServerTimingFetch(timing => console.log(timing)),
+});
+```
+
+State what the sandbox needs instead of naming a provider: gates by name in
+`requirements`, `resources`, a lifetime and ranking preferences. Routes that cannot
+satisfy them are excluded before routing, and the sandbox records its contract and why
+its route was chosen. `match` returns the same evaluation without creating anything:
+
+```typescript
+const needs = {
+  lifetime_seconds: 1800,
+  at_end: 'pause' as const,
+  requirements: { pause_resume: {} },
+  resources: { cpu_min: 2, memory_min_mib: 4096 },
+  preferences: { sort: 'price' as const },
+};
+console.log((await client.sandboxes.match(needs)).eligible.map(route => route.provider));
+const routed = await client.sandboxes.create(needs);
+try {
+  console.log(routed.route?.provider, routed.contract?.spec_version);
+} finally {
+  await routed.destroy();
+}
+```
+
+An image in a registry that needs a login: `privateImage()` returns the `image` and the
+request-only `registry_credentials` (Cloud never stores, logs or returns them). Spread it
+into a create, match or prepare body. Private images run on your own provider keys, so
+connect that provider account first:
+
+```typescript
+import { privateImage } from '@boxrouter/sdk';
+
+const login = { username: 'reader', password: process.env.REGISTRY_TOKEN! };
+const box = await client.sandboxes.create({
+  ...privateImage('ghcr.io/acme/app:1', login),
+  preferences: { only: ['e2b'] },
+});
+try {
+  console.log(box.id);
+} finally {
+  await box.destroy();
+}
+```
+
+`launch` takes it too, spread into its options. The manifest's `image` is `{ private_oci }` and
+the login goes only in the launch request's `registry_credentials`:
+
+```typescript
+const box = await client.sandboxes.launch(
+  { ...privateImage('ghcr.io/acme/app:1', login), provider: 'e2b' });
+```
+
+Prepare an image ahead of its first sandbox so no create pays for the setup. `prepare`
+waits: it resolves once no selected provider is `queued` or `preparing`, so read each
+provider's `state` in the result. Pass `{ wait: false }` as the second argument to get the
+started status at once; if preparation is still pending after the wait's bound, `prepare`
+rejects with a `WaitTimeoutError` (name `TimeoutError`), setup continues, and
+`preparations` reads it. Name the
+providers, or pass the body you would send to `create` as `match` and BoxRouter prepares
+the first `top` providers that create would rank best. `prepare` takes exactly one of the
+two forms and rejects otherwise. `privateImage()` works in both, on providers you
+connected with your own key; its login is used once for the setup and never stored:
+
+```typescript
+await client.images.prepare({ image: 'app:v12', providers: ['e2b'], sizes: [4] });
+await client.images.prepare({
+  match: { image: 'app:v12', resources: { cpu_min: 2 } },
+  top: 2,
+});
+await client.images.prepare({
+  match: { ...privateImage('ghcr.io/acme/app:1', login), resources: { cpu_min: 2 } },
+  top: 2,
+});
+const started = await client.images.prepare({ image: 'app:v12', providers: ['e2b'] }, { wait: false });
+console.log(await client.images.preparations('app:v12', ['e2b']));
+await client.images.unprepare('app:v12', ['e2b']);
+```
+
+Status and unprepare name a private tag that this workspace prepared or created with its
+login before; for any other private tag, name its digest (`repo@sha256:...`).
+
+Every handle has `pause()`, `resume()`, `extend()` and `previews.open()`. Name the
+requirement a method needs when you create the sandbox: `requirements` takes a list of
+requirement names or the object form, and the list `['pause_resume']` sends
+`{ "pause_resume": {} }`. A sandbox created without the requirement answers a gated
+call with an `APIError` whose `code` is `'not_named'` (status 409). An unknown name in
+the list throws a `TypeError` that lists the accepted names. The preview example opens a
+public link and destroys its sandbox immediately. To use the link, start a service on
+port 3000 and keep the sandbox running:
+
+```typescript
+const paused = await client.sandboxes.create({ requirements: ['pause_resume'] });
+try {
+  await paused.pause();           // Paused; paused.state is now 'paused'
+  await paused.resume();          // Resumed, or undefined when it was already running
+  await paused.extend({ lifetime_seconds: 1800 }); // Lifetime; 1800 is the new total, not an increment
+} finally {
+  await paused.destroy();
+}
+
+const previewable = await client.sandboxes.create({
+  requirements: { previews: { access: 'public', ports: [3000] } },
+});
+try {
+  console.log((await previewable.previews.open(3000)).url);
+} finally {
+  await previewable.destroy();
+}
+```
+
+`pause()`, `resume()` and `extend()` update the handle's `state` and `lifetime`.
+`client.sandboxes.list(query?)` returns one `SandboxPage` of your sandboxes.
+
+Editors use the declarations automatically. For a standalone type check or a CI
+type-check step, run:
+
+```sh
+npx tsc --noEmit --strict --target ES2022 --module NodeNext \
+  --moduleResolution NodeNext --lib ES2022,DOM,DOM.Iterable,ESNext.Disposable src/index.ts
+```
+
+## The sandbox object
+
+There is one sandbox shape. A handle from `create()` or `get(id)` exposes every field of the
+`Sandbox` as a read-only property, using the wire names: `box.id`, `box.state`,
+`box.lifetime`, `box.cost`, `box.route`, `box.contract`, `box.volume` and the rest. `route`
+and `contract` are `null` for a sandbox recorded without them. Properties show the last
+response, so they change only when you call `refresh()`, `destroy()`, `pause()`, `resume()` or `extend()`:
+
+```typescript
+const box = await client.sandboxes.get('SANDBOX_ID');
+console.log(box.state, box.lifetime.remaining_seconds, box.cost?.label);
+await box.refresh();
+console.log(box.state);
+```
+
+`refresh()` reads the sandbox again and updates the handle. A handle for an ended
+sandbox answers the first operation with the usual `sandbox_ended` API error.
+
+`destroy()` always answers with the `Sandbox`, and the handle takes its fields. While the
+destroy is pending, `state` is `destroying` and `operation_id` names the operation Cloud
+finishes without you; once confirmed, `state` is `destroyed` and `operation_id` is `null`.
+Destroying again returns the confirmed sandbox:
+
+```typescript
+const box = await client.sandboxes.create({});
+try {
+  await box.exec('true');
+} finally {
+  const ended = await box.destroy();
+  console.log(ended.state, box.state, ended.operation_id);
+}
+```
+
+Create, inspect, checkpoint and remove persistent volumes with `client.volumes`: use
+`create`, `list`, `get`, `listCheckpoints`, `getCheckpoint`, `save`, `deleteCheckpoint`,
+`release` and `delete`. A sandbox attached to a volume can call
+`box.saveVolume({ message })`; `box.destroy({ discardUnsaved: true })` explicitly
+allows destruction to discard changes if saving fails.
+
+When no route qualifies, creation throws `APIError` with code `no_eligible_route`;
+`error.error.details` lists every excluded route with the checks it failed and the
+nearest changes. A body written in the retired 0.2.0 words (`timeout_seconds`, `egress`,
+`provider`, a dotted `requirements` key) is refused by the type checker and, if sent
+anyway, by the server with `invalid_request`.
+
+For output while a command runs, start a background process (E2B, Modal, Blaxel):
+
+```typescript
+const running = await box.processes.start('make test');
+let output = await running.read(); // stdout_base64, stderr_base64, next_stdout, next_stderr, exit_code
+output = await running.read({ stdout: output.next_stdout, stderr: output.next_stderr });
+const done = await running.wait({ timeoutSeconds: 600 });
+console.log(done.exit_code);
+await running.remove();
+```
+
+`read()` returns up to 256 KiB per stream from the byte offsets you pass and never blocks;
+`exit_code` is set once the process ended and both streams were read to their ends.
+`wait()` polls `read()` and returns all output from its offsets, rejecting with a
+`TimeoutError` when `timeoutSeconds` passes; the command keeps running. Use
+`running.cancel()` to stop it and `running.remove()` to delete its retained output. With
+`stdin: true`, `writeStdin()` and `closeStdin()` feed it.
+
+Files read as `Uint8Array`. Commands return `stdout`, `stderr` and `exit_code`;
+nonzero exit status is a workload result. `native_error` keeps the provider's error for
+the command when it reports one. HTTP failures raise the exported
+`APIError`: retain `requestId`, `operationId`, `outcome` and `idempotencyKey`; its
+`error` object keeps the complete envelope, including `provider`, `native_status` and
+`native_code`.
+This applies to `BoxRouter`, direct `BoxRouterApi` calls, and transport result
+errors. Error diagnostics read at most 64 KiB; non-JSON error bodies are omitted
+and header request IDs remain available. Successful responses must match the
+operation's declared status and media type, and every property the client knows must
+match its JSON schema, including when selecting another parsing format. A property a
+newer API adds is accepted and left on the returned value; the types do not declare it.
+Invalid responses raise `APIError`, preserving status, request ID and mutation key
+without copying decoder text or payloads. For a read (GET) the message says the read
+failed, nothing was changed and it can be retried; for any other method it says the
+result is unconfirmed and to inspect the operation before retrying. When no kind of record
+matched, it adds that a newer SDK is needed if it keeps failing. A stream skips an event of
+a kind this client does not know and still ends at its terminal event. A response enum the
+API grows (a sandbox's `state` and `state_reason`, an API key's `permissions`) is typed as its
+known values plus any string, so a value added later reaches your code.
+Failures before HTTP headers remain fetch exceptions and are not resent. Every API error carries
+`retry` (`safe`, `after_fix`, `check_outcome` or `never`) and `retry_after_seconds`; `APIError` exposes them as
+`status`, `retry`, `retryAfterSeconds` and `details`, and `docUrl` is the page that explains the code. The client resends only `retry: "safe"` (nothing ran
+and waiting helps), with the same idempotency key, up to `maxRetries` times (`new BoxRouter({ maxRetries: 2 })`
+is the default; 0 turns it off), waiting `retry_after_seconds` or a doubling backoff; a wait longer than the
+client sleeps is raised instead. A call with a request body is resent only when it carries an idempotency key.
+HTTP redirects are rejected by default, including for buffered requests, so a
+redirect cannot automatically forward credentials or replay a mutation. Use the
+API's final URL as `baseUrl`. Low-level request options retain explicit Fetch
+redirect controls; choosing `redirect: 'follow'` permits request forwarding.
+A timeout or lost response can leave work running; inspect operation history
+before submitting new work. Failed cleanup does not establish destruction.
+
+Every method of this entry point is provider-neutral. Generated methods are broader
+than implemented hosted support: a sandbox may use only the gates its creation named, so
+read `box.contract?.gates` for what each was granted and the API repository's
+`docs/coverage.md` before relying on one. A call outside them is refused with `not_named`.
+A sandbox recorded without a contract has `box.contract === null`.
+
+`exec` returns text (`stdout`, `stderr`) unless the config says `output: 'bytes'`, which
+returns exact `Uint8Array` streams in `stdout` and `stderr`. The result keeps `exit_code`
+and both truncation flags in either mode; the types follow the config, so a literal
+`output` needs no check on the result.
+`box.files.list(path)` returns immediate entries with `name` and `type`.
+
+`client.sandboxes.openTerminal(sandboxId, options)` opens a PTY shell on any
+provider, or attaches with `terminalId`. `rows` and `cols` set the size of a new
+terminal. On attach, use `terminal.resize(rows, cols)` to request an explicit
+resize. It returns a `Terminal` handle:
+`output()` yields exact byte chunks and stops at exit; `events()` retains raw typed
+events. `lastEventId` tracks consumed SSE events, and omitted cursors resume from
+that point. A terminal error raises `TerminalError` with its `event`, `code`,
+`message`, `outcome` and `retry`. `close()` detaches local observers only; it does
+not stop the remote shell. The sandbox image must provide `python3`.
+
+```typescript
+const terminal = await client.sandboxes.openTerminal(sandboxId, { rows: 40, cols: 120 });
+try {
+  for await (const chunk of terminal.output()) process.stdout.write(chunk);
+  console.log(terminal.exitCode);
+} finally {
+  terminal.close();
+}
+```
+
+## Downloads
+
+Generated binary operations also provide `…Stream()` methods. They return
+`{ data, request, response }`, retaining the original Fetch request and response.
+Binary `data` is a `ReadableStream<Uint8Array>`; a declared JSON alternative is
+buffered and validated before returning its JSON value.
+
+```typescript
+import { createWriteStream } from 'node:fs';
+import { Writable } from 'node:stream';
+
+const download = await client.api.files.readStream({
+  path: { sandbox_id: box.id }, query: { path: '/tmp/hello.txt' },
 });
-console.log(result.data);
+await download.data.pipeTo(Writable.toWeb(createWriteStream('hello.txt')));
+```
+
+Consume or cancel the stream to close the transfer. `pipeTo` also cancels the
+source when its destination fails. A disconnected body raises `APIError` with the
+original response and mutation key; it does not restart the operation. Downloads
+can leave partial local files. Client streaming does not remove Cloud's provider
+buffering or transfer limits.
+
+Move files of any practical size with `box.files.upload` and `box.files.download`:
+
+```typescript
+await box.files.upload('./dataset.parquet', '/home/user/data/dataset.parquet');
+await box.files.download('/home/user/out/results.tar.gz', './results.tar.gz');
+const stream = await box.files.download('/home/user/out/results.tar.gz'); // ReadableStream<Uint8Array>
 ```
 
-Set `BOXROUTER_BASE_URL` to your deployment's API base URL and
-`BOXROUTER_API_KEY` to a BoxRouter API key. Discovery reports current visibility
-and eligibility; it does not reserve capacity. With `throwOnError: true`, HTTP
-failures reject the promise. This preview does not include the full SDK's typed
-error models.
+`upload` takes a local path, `Blob`, `Uint8Array` or `ReadableStream` (a stream needs `size`) and
+accepts `concurrency`, `progress(done, total)`, `signal` and `idempotencyKey`. A download to a path
+is written to `<path>.part-<random>` and renamed once the full length arrived; the stream form
+errors if the body ends short. An upload is never sent again once any byte may have gone: the
+upload is aborted and the error raised, and bytes already written may remain. `files.write` and
+`files.read` switch to the same flow above 1 MiB, so they need no change. Volumes use the same
+transfer engine.
 
-To rebuild this preview, sync its own `release-pins.txt` with `gh pins sync` from
-this directory, unpack `.artifacts/sdk-codegen.tgz` into `.artifacts`, then run
-`node src/build-preview.mjs` from the repository root. Run its installed-package
-checks with `node --test src/preview/tests/client.test.mjs`.
+## Tracing
 
-Licensed under Apache-2.0. Contact: maintainer@boxrouter.ai.
+The SDK uses the OpenTelemetry API; your application configures the tracer provider,
+context manager, W3C trace-context propagator, sampling and export. With no provider,
+instrumentation is inactive. The SDK installs no exporters or background workers.
+
+Buffered requests and SSE iteration emit `boxrouter.client` spans named for canonical
+operations. Spans include HTTP status and validated `boxrouter.request.id`; streams
+also record delivered event counts and `boxrouter.stream.end` (`completed`, `error`
+or `cancelled`). SSE spans start on first iteration and end on EOF, failure or close.
+Uncertain remote execution and local stream cancellation remain distinct. Binary
+stream spans remain open until EOF, failure or cancellation and record delivered,
+decoded bytes in `boxrouter.stream.bytes`. Raw `parseAs: 'stream'` reads use the
+same lifecycle instrumentation.
+Standard `TimeoutError` abort reasons record an error outcome, including in SSE
+iteration. Intentional stream closure remains `cancelled`. Buffered requests
+distinguish standard `TimeoutError` and `AbortError` without capturing their messages.
+
+Recording buffered request spans may also include three client timing attributes,
+all measured in milliseconds with a monotonic clock: `boxrouter.client.request_preparation.duration_ms`
+covers request construction and setup before the fetch callback starts;
+`boxrouter.client.response_headers.duration_ms` covers the fetch callback from
+dispatch until it returns a `Response` or rejects; and
+`boxrouter.client.response_processing.duration_ms` covers buffered body handling
+after the response is returned until the SDK finishes the operation. Request
+preparation is omitted when its clock readings are unavailable; when a request
+fails before fetch starts, it covers setup until the operation finishes. Response
+headers is omitted if its timing cannot
+be measured; it can be present even when fetch rejects, because it measures the
+time until that rejection. Response processing is omitted when fetch does not
+return a response or its timing cannot be measured. All three are omitted when
+the span is not recording.
+
+Applications that need these phases even when a span is not recording can opt in
+to the request phase observer exported by the generated client:
+
+```ts
+import { setRequestPhaseObserver } from '@boxrouter/sdk';
+
+setRequestPhaseObserver(({ phase, outcome, durationMs }) => {
+  // Record only the bounded phase and outcome dimensions.
+  // requestPhaseHistogram comes from the application's metrics setup.
+  requestPhaseHistogram.record(durationMs, { phase, outcome });
+});
+
+// Disable observations when they are no longer needed.
+setRequestPhaseObserver(undefined);
+```
+
+The observer reports `request_preparation`, `response_headers`, and
+`response_processing` for requests, plus `stream_lifetime` for SSE and binary
+streams. For streams, response processing covers setup before the stream body;
+the stream lifetime is reported separately through completion, failure, or
+cancellation. Every `durationMs` uses the monotonic clock and describes only
+its named phase; a phase is omitted when its interval cannot be measured.
+Outcomes come from a fixed, bounded set: `success`,
+`http_error`, `network_error`, `cancelled`, `parse_error`, `stream_error`,
+`stream_cancelled`, and `unknown`.
+Each observation contains only `phase`, `outcome`, and `durationMs`; it carries
+no request IDs, URLs, bodies, credentials, or exception details. The callback
+runs synchronously on the request path, so keep it lightweight and use only
+bounded metric labels. Callback errors are ignored so they cannot replace the
+request result. The observer is module-wide and applies to requests created
+after it is installed; disable it with `setRequestPhaseObserver(undefined)`.
+The SDK does not export these observations as metrics itself.
+
+Only W3C `traceparent` is injected from the configured propagator. Automatic baggage,
+URLs, resource IDs, request/response bodies, credentials, exception messages and stacks
+are excluded. Application-installed automatic instrumentation has its own capture
+policy; review it separately. Follow the
+[OpenTelemetry library guidance](https://opentelemetry.io/docs/concepts/instrumentation/libraries/)
+when configuring your application.
+
+JSON integers outside JavaScript's safe range are returned as `bigint`; generated
+numeric fields have type `number | bigint`. Use `.toString()` for display and
+`BigInt(value)` for exact integer arithmetic. Supply large request values as bigint
+(for example `9007199254740993n`); SDK serialization keeps them as JSON integers.
+Already-unsafe integer numbers fail before dispatch. Decimal-text timestamps remain
+strings. Native `JSON.stringify` cannot serialize bigint values.
+
+After a request is constructed, transport and stream failures raise `RequestError`.
+It retains `request`, any received `response`, `idempotencyKey`, `requestId` and the
+original error as `cause`. HTTP failures use `APIError`; streaming HTTP failures
+use its `StreamHTTPError` subclass with the same recovery fields. Streaming error
+bodies retain at most 64 KiB, with `bodyTruncated` indicating overflow; incomplete
+diagnostics may not contain recovery fields. Retain
+these identifiers for reconciliation; transport cancellation does not cancel remote
+work, and the SDK never resends a call whose `retry` is `check_outcome`, `after_fix` or `never`.
+For a persistent transport failure against `boxrouter.ai`, `RequestError.reportUrl`
+and its message point to Support, prefilled with a request ID when one was received;
+the message also offers `support@boxrouter.ai` if the page cannot be opened. Explicit
+cancellation and custom API hosts do not get BoxRouter reporting details.
+
+## Client identification
+
+Generated HTTP operations send `boxrouter-typescript/<SDK version>` in Node,
+including JSON, file streams and events. Pass
+`userAgentSuffix: 'my-app/1.0'` to append a product token (1–256 printable ASCII
+characters, including one non-space; complete header at most 512).
+`client.withUserAgentSuffix('integration/1.0')` returns an independent view of the
+current transport configuration and interceptors, without changing the owner.
+Browsers control their own User-Agent; BoxRouter's website Worker identifies its
+upstream API calls as `boxrouter-web`. Cloud stores only an allowlisted product
+name and major.minor version, never the raw header or arbitrary suffix.
+
+## Launch agents
+
+`client.sandboxes.launch(options)` and `launch(agent, options)` wait until the launch is
+ready and resolve to the sandbox: the same `SandboxHandle` that `create` returns. `destroy()`
+ends it. The handle's `launch` property is the `Launch` result (`undefined` for handles from
+`create` and `get`) with `interactive` resolved from the launch, then the manifest, then
+`true`, so `box.launch.interactive === false` tells an unattended launch. A launch that is
+still pending after its bound rejects with a `WaitTimeoutError` naming the operation id;
+read the operation before launching again. If the launch succeeded but reading the sandbox
+failed, the error message ends with `Sandbox ID: <id>`.
+
+```typescript
+await using box = await client.sandboxes.launch('codex', { repo: 'acme/agent@main' });
+const terminal = await box.openTerminal({ rows: 40, cols: 120 });
+for await (const chunk of terminal.output()) process.stdout.write(chunk);
+```
+
+After a launch, `box.openTerminal` opens a shell that first writes the launch's command
+(an interactive launch only) and defaults the terminal timeout to 3600 s; pass `terminalId`
+to attach to an existing shell instead. For `interactive: false`, Cloud starts the command
+during preparation and `openTerminal` opens a plain shell. `await using` closes remaining
+observers and destroys the sandbox when its scope ends. `manifest` takes a plain object;
+a `source` key marks a source manifest.
+
+## Wait for an operation
+
+`client.operations.wait(id)` reads an operation until its outcome is no longer `unknown`
+and returns it (`completed`, `partial` and `not_started` end the wait). It never repeats the
+mutation; after its bound it rejects with a `WaitTimeoutError`. `client.api.operations.get(id)`
+reads once.
+
+```typescript
+const operation = await client.operations.wait(operationId);
+console.log(operation.outcome);
+```

package/dist/addresses.d.ts

@@ -0,0 +1,5 @@
+export declare const SUPPORT = "support@boxrouter.ai";
+export declare const PRIVACY = "privacy@boxrouter.ai";
+export declare const SECURITY = "security@boxrouter.ai";
+export declare const ABUSE = "abuse@boxrouter.ai";
+export declare const CONDUCT = "conduct@boxrouter.ai";

package/dist/addresses.js

@@ -0,0 +1,10 @@
+"use strict";
+// Generated from the BoxRouter email registry. Do not edit.
+// Public email addresses: the ones that may appear in published packages.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONDUCT = exports.ABUSE = exports.SECURITY = exports.PRIVACY = exports.SUPPORT = void 0;
+exports.SUPPORT = "support@boxrouter.ai";
+exports.PRIVACY = "privacy@boxrouter.ai";
+exports.SECURITY = "security@boxrouter.ai";
+exports.ABUSE = "abuse@boxrouter.ai";
+exports.CONDUCT = "conduct@boxrouter.ai";

package/dist/api-error.d.ts

@@ -0,0 +1,62 @@
+import type { ErrorCode } from './error-codes.gen';
+/** Where to report an unexpected failure, with the request ID prefilled when there is one. */
+export declare function reportUrl(requestId?: string): string;
+/** A bounded, payload-free description of a response schema mismatch. */
+export type ResponseSchemaDiagnostic = Readonly<{
+    keyword: string;
+    instancePath: string;
+    schemaPath: string;
+}>;
+/**
+ * An API failure with an explanation and identifiers for reconciliation. An unexpected failure (a 5xx, an
+ * uncertain outcome or a reply this SDK cannot read) says where to report it; a failure the caller can fix, such
+ * as a bad key, does not. `unexpected` overrides that rule for a reply that is not BoxRouter's at all.
+ */
+export declare class APIError extends Error {
+    readonly response: Response;
+    readonly request: Request | undefined;
+    readonly status: number;
+    readonly error: Readonly<Record<string, unknown>>;
+    /** The documented codes complete in an editor; a code newer than this SDK is still a string. */
+    readonly code?: ErrorCode;
+    readonly requestId?: string;
+    readonly operationId?: string;
+    readonly sandboxId?: string;
+    readonly outcome?: string;
+    /** What to do next, when the API names a fix. */
+    readonly fix?: string;
+    /** What to do about sending the call again: `safe`, `after_fix`, `check_outcome` or `never` (a newer API may add values). */
+    readonly retry?: string;
+    /** How long to wait before a `retry: "safe"` resend; undefined when the API names no wait. */
+    readonly retryAfterSeconds?: number;
+    /** The documentation page for this code (`.../docs/error-codes#<code>`); undefined when the API names none. */
+    readonly docUrl?: string;
+    /** Code-specific context for programs; fields this SDK does not know are kept. */
+    readonly details: Readonly<Record<string, unknown>>;
+    /** Safe schema paths only; never includes response values or validator params. */
+    readonly schemaDiagnostics?: readonly ResponseSchemaDiagnostic[];
+    readonly idempotencyKey?: string;
+    /** Where to report this failure; undefined for a failure the caller can fix. */
+    readonly reportUrl?: string;
+    constructor(payload: unknown, response: Response, request: Request | undefined, message?: string, idempotencyKey?: string, unexpected?: boolean, schemaDiagnostics?: readonly ResponseSchemaDiagnostic[]);
+}
+/** Say what a failed call means: a read changed nothing, a mutation may have happened. */
+export declare function unconfirmed(request: Request, failure: string): string;
+/** Mark a failure that followed a send, so its message does not claim the request was never sent. */
+export declare function markAfterSend(error: unknown): unknown;
+/** A request failed locally; a mutation's remote outcome may still be unknown. */
+export declare class RequestError extends Error {
+    readonly request: Request;
+    readonly response?: Response | undefined;
+    readonly idempotencyKey?: string;
+    readonly requestId?: string;
+    /** Where to report a persistent transport failure against BoxRouter. */
+    readonly reportUrl?: string;
+    constructor(cause: unknown, request: Request, response?: Response | undefined);
+}
+export declare function requestFailure(error: unknown, request?: Request, response?: Response): unknown;
+/** Where no kind of record matched, a newer API may be the cause; say what then fixes it. */
+export declare const UNKNOWN_KIND = "It may hold a kind of record this SDK does not know; if it keeps failing, a newer SDK is needed.";
+/** A response BoxRouter did not send: every BoxRouter response carries a request ID. */
+export declare function foreign(response: Response, request: Request): string | undefined;
+export declare function invalidResponse(response: Response, request: Request, payload?: unknown, kind?: boolean, schemaDiagnostics?: readonly ResponseSchemaDiagnostic[]): APIError;