sandbox-as-a-service 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandbox as a Service
+
+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.

package/README.md

@@ -0,0 +1,161 @@
+# sandbox-as-a-service
+
+A zero-dependency JavaScript/TypeScript client for
+[Sandbox as a Service](https://sandbox-as-a-service.com) — secure, disposable
+cloud sandboxes for AI agents and code execution. Each sandbox is a dedicated
+virtual machine, created with one call and destroyed when you are done.
+
+- Node.js 18+ (uses the built-in `fetch`; nothing to install alongside it)
+- ESM and CommonJS, with hand-written TypeScript definitions
+- Streaming command output via Server-Sent Events
+- Typed errors for every failure category
+
+## Install
+
+```sh
+npm install sandbox-as-a-service
+```
+
+## Quickstart
+
+ESM:
+
+```js
+import { Client } from 'sandbox-as-a-service';
+
+const client = new Client(); // reads AAS_API_KEY from the environment
+
+const sandbox = await client.createSandbox({ size: 'small', timeoutMinutes: 10 });
+try {
+  const result = await sandbox.exec('python3 -c "print(6 * 7)"');
+  console.log(result.stdout); // 42
+
+  await sandbox.writeFile('/workspace/app.py', "print('hello from the sandbox')");
+  console.log((await sandbox.readFile('/workspace/app.py')).content);
+} finally {
+  await sandbox.destroy();
+}
+```
+
+TypeScript:
+
+```ts
+import { Client, ExecutionFailed } from 'sandbox-as-a-service';
+
+const client = new Client(); // reads AAS_API_KEY from the environment
+const sandbox = await client.createSandbox({ size: 'small', timeoutMinutes: 10 });
+try {
+  const result = await sandbox.exec('python3 -m pytest -q', { timeoutMs: 300000, cwd: '/workspace' });
+  result.check(); // throws ExecutionFailed on a non-zero exit code
+} catch (err) {
+  if (err instanceof ExecutionFailed) console.error(err.execution.stderr);
+} finally {
+  await sandbox.destroy();
+}
+```
+
+CommonJS works the same way: `const { Client } = require('sandbox-as-a-service');`
+
+On Node.js 22+ you can let the scope destroy the sandbox for you:
+
+```js
+const client = new Client();
+await using sandbox = await client.createSandbox({ size: 'small', timeoutMinutes: 10 });
+const result = await sandbox.exec('echo hello');
+// the sandbox is destroyed here
+```
+
+Set `AAS_API_KEY` from [Dashboard → API keys](https://sandbox-as-a-service.com/dashboard/keys) and
+the client picks it up. Pass `new Client({ apiKey, baseUrl, timeoutMs })` to override; a bare
+`baseUrl` gets `/v1` appended. Creating a sandbox blocks until the machine is ready.
+
+## Streaming output
+
+Pass `onStdout` or `onStderr` and the same call streams: the callbacks fire
+as the sandbox produces output, and the return value is the same `Execution`
+a blocking call returns.
+
+```js
+const result = await sandbox.exec(
+  'for i in 1 2 3; do echo tick $i; sleep 1; done',
+  {
+    onStdout: (chunk) => process.stdout.write(chunk),
+    onStderr: (chunk) => process.stderr.write(chunk),
+  },
+);
+// callbacks fire as output arrives; result is the usual Execution object
+```
+
+Closing the connection mid-stream — the process exiting, Ctrl-C — kills the
+remote command and records it as `cancelled`.
+
+## Files
+
+```js
+await sandbox.writeFile('/workspace/app.py', "print('hello')");
+await sandbox.writeFile('/workspace/blob.bin', base64, { encoding: 'base64' });
+
+const file = await sandbox.readFile('/workspace/app.py');
+console.log(file.content, file.sizeBytes); // .text and .bytes are aliases
+
+const listing = await sandbox.listFiles('/workspace'); // entries: name, type, size_bytes
+console.log(listing.names());
+
+await sandbox.deleteFile('/workspace/app.py'); // { recursive: true } for a directory tree
+```
+
+## Ports
+
+```js
+const preview = await sandbox.exposePort(8000); // { url, port, ... }
+const open = await sandbox.listPorts();
+await sandbox.closePort(8000);
+```
+
+## Errors
+
+Non-2xx responses raise a specific error, so a caller can react to the reason
+rather than parse a status code. Every `SandboxApiError` carries `status`,
+`type`, `requestId` and the decoded `responseBody`; quote the request id in a
+support request.
+
+```js
+import { Client, NotFoundError, RateLimitError } from 'sandbox-as-a-service';
+
+const client = new Client();
+
+try {
+  const sandbox = await client.getSandbox('sbx_does_not_exist');
+} catch (err) {
+  if (err instanceof NotFoundError) console.log('gone');
+  if (err instanceof RateLimitError) console.log('slow down, retry after', err.retryAfter, 'seconds');
+}
+```
+
+| Error | Raised when |
+| --- | --- |
+| `AuthenticationError` | The key is missing, malformed or revoked (401). |
+| `PermissionDeniedError` | The key is valid but not allowed to do this (403). |
+| `NotFoundError` | No such sandbox, file or execution (404). |
+| `InvalidRequestError` | The request body or parameters were rejected (400); a 422 maps to the base `SandboxApiError`. |
+| `ConflictError` | The sandbox is in a state that forbids the operation (409). |
+| `PaymentRequiredError` | The account has no credit left (402). |
+| `RateLimitError` | A rate limit was hit (429); `retryAfter` is set when the header is present. |
+| `ServiceUnavailableError` | A transient server or upstream failure (503). |
+| `SandboxConnectionError` | The request never reached the API — DNS, TLS or timeout. |
+| `SandboxConfigurationError` | The client was constructed with something it cannot use. |
+
+## What the client covers
+
+- `client.createSandbox({ size, name, timeoutMinutes, idempotencyKey })` — creates a sandbox and returns it ready to use.
+- `client.getSandbox(id)`, `client.listSandboxes({ limit, startingAfter, includeDeleted })`, `client.iterSandboxes()`
+- `client.getAccount()`, `client.getUsage({ days })`
+- `sandbox.refresh()`, `sandbox.extend(additionalMinutes)`, `sandbox.destroy()`
+- `sandbox.exec(command, { timeoutMs, cwd, env, onStdout, onStderr })`, `sandbox.getExecution(id)`
+- `sandbox.writeFile(path, content, { encoding })`, `sandbox.readFile(path, { encoding })`
+- `sandbox.listFiles(path, { recursive })`, `sandbox.deleteFile(path, { recursive })`
+- `sandbox.exposePort(port)`, `sandbox.listPorts()`, `sandbox.closePort(port)`
+
+Snapshots are available over the REST API only for now.
+
+Full API reference: <https://sandbox-as-a-service.com/docs/api>

package/index.d.ts

@@ -0,0 +1,318 @@
+// Type definitions for sandbox-as-a-service 0.1.0
+// Zero-dependency JavaScript/TypeScript client for Sandbox as a Service.
+// API reference: https://sandbox-as-a-service.com/docs/api
+
+declare global {
+  // Present in lib.esnext.disposable; re-declared so the types also load on
+  // configurations that do not include that lib.
+  interface SymbolConstructor {
+    readonly asyncDispose: unique symbol;
+  }
+}
+
+export type SandboxSize = 'small' | 'medium' | 'large' | (string & {});
+export type FileEncoding = 'utf8' | 'base64' | (string & {});
+
+export interface ClientOptions {
+  /**
+   * A key created in the dashboard; it starts with `aas_sk_`. If omitted,
+   * `AAS_API_KEY` is read from the environment.
+   */
+  apiKey?: string | null;
+  /**
+   * The API root. The default is the public service (or `AAS_BASE_URL` when
+   * set); a bare host gets `/v1` appended, and a URL that already ends in
+   * `/v1` is used as-is.
+   */
+  baseUrl?: string | null;
+  /**
+   * Default per-request timeout in milliseconds. Sandbox creation blocks
+   * until the machine is ready, so this is generous by design.
+   * @default 600000
+   */
+  timeoutMs?: number;
+}
+
+export interface CreateSandboxOptions {
+  /** @default 'small' */
+  size?: SandboxSize;
+  name?: string | null;
+  timeoutMinutes?: number | null;
+  /**
+   * Retrying a create is safe when you pass the same key; the platform
+   * returns the original sandbox instead of a second one. When omitted, a
+   * fresh random key is generated for this call.
+   */
+  idempotencyKey?: string | null;
+}
+
+export interface ListSandboxesOptions {
+  /** @default 20 */
+  limit?: number;
+  startingAfter?: string | null;
+  includeDeleted?: boolean;
+}
+
+export interface ExecOptions {
+  /** Bounds the command itself, in milliseconds (1000–600000). @default 60000 */
+  timeoutMs?: number;
+  cwd?: string | null;
+  env?: Record<string, string> | null;
+  /** Fire per chunk as the sandbox produces stdout; switches the call to streaming. */
+  onStdout?: ((chunk: string) => void | Promise<void>) | null;
+  /** Fire per chunk as the sandbox produces stderr; switches the call to streaming. */
+  onStderr?: ((chunk: string) => void | Promise<void>) | null;
+}
+
+export interface WriteFileOptions {
+  /** @default 'utf8' */
+  encoding?: FileEncoding;
+}
+
+export interface ReadFileOptions {
+  /** @default 'utf8' */
+  encoding?: FileEncoding;
+}
+
+export interface ListFilesOptions {
+  /** @default true */
+  recursive?: boolean;
+}
+
+export interface DeleteFileOptions {
+  /** @default false */
+  recursive?: boolean;
+}
+
+export interface GetUsageOptions {
+  /** @default 30 */
+  days?: number;
+}
+
+export interface SandboxResources {
+  vcpu?: number | null;
+  memory_gb?: number | null;
+  disk_gb?: number | null;
+  [key: string]: unknown;
+}
+
+export interface FileEntry {
+  name?: string;
+  type?: string;
+  size_bytes?: number;
+  [key: string]: unknown;
+}
+
+export class Sandbox {
+  constructor(client: Client, data: Record<string, any>);
+  readonly id: string;
+  object: string;
+  name: string | null;
+  status: string;
+  size: string | null;
+  resources: SandboxResources;
+  timeoutMinutes: number | null;
+  createdAt: string | null;
+  readyAt: string | null;
+  expiresAt: string | null;
+  deletedAt: string | null;
+  /** The raw API object this sandbox was built from. */
+  raw: Record<string, any>;
+
+  /** Fetch the current state and update this object in place. */
+  refresh(): Promise<Sandbox>;
+  /** Add lifetime to a running sandbox and return the updated object. */
+  extend(additionalMinutes?: number): Promise<Sandbox>;
+  /** Destroy the sandbox. Billing stops at teardown. */
+  destroy(): Promise<Record<string, any>>;
+
+  /** Run a shell command inside the sandbox and return its result. */
+  exec(command: string, options?: ExecOptions): Promise<Execution>;
+  /** Fetch an execution by id. */
+  getExecution(executionId: string): Promise<Execution>;
+
+  /** Write a file inside the sandbox. */
+  writeFile(path: string, content: string, options?: WriteFileOptions): Promise<Record<string, any>>;
+  /** Read a file and decode it (`utf8` or `base64`). */
+  readFile(path: string, options?: ReadFileOptions): Promise<FileContent>;
+  /** List a directory. Returns entries with `name`, `type` and `size_bytes`. */
+  listFiles(path?: string, options?: ListFilesOptions): Promise<FileListing>;
+  /** Delete a file, or a directory tree when `recursive` is true. */
+  deleteFile(path: string, options?: DeleteFileOptions): Promise<Record<string, any>>;
+
+  /** Expose a port on a public preview URL. Returns `{url, port, ...}`. */
+  exposePort(port: number): Promise<Record<string, any>>;
+  /** List the preview URLs open on the sandbox. */
+  listPorts(): Promise<Record<string, any>[]>;
+  /** Close a preview URL previously opened for `port`. */
+  closePort(port: number): Promise<Record<string, any>>;
+
+  /**
+   * Destroys the sandbox when used with explicit resource management
+   * (`await using sandbox = await client.createSandbox()`), on runtimes
+   * that provide `Symbol.asyncDispose` (Node.js 22+).
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+export class Execution {
+  constructor(data: Record<string, any>);
+  readonly id: string;
+  object: string;
+  sandboxId: string | null;
+  status: string;
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  truncated: boolean;
+  durationMs: number | null;
+  startedAt: string | null;
+  finishedAt: string | null;
+  /** The raw API object this execution was built from. */
+  raw: Record<string, any>;
+
+  /** True when the exit code is zero and the command completed. */
+  readonly ok: boolean;
+  /** Raise `ExecutionFailed` if the command did not exit 0. */
+  check(): this;
+}
+
+export class ExecutionFailed extends Error {
+  constructor(execution: Execution);
+  /** The execution that failed. */
+  readonly execution: Execution;
+}
+
+export class FileContent {
+  constructor(data: Record<string, any>);
+  path: string;
+  /** The decoded content (text for `utf8`, base64 text for `base64`). */
+  content: string;
+  sizeBytes: number;
+  encoding: string;
+  /** The raw API object this file content was built from. */
+  raw: Record<string, any>;
+  /** Alias for `content`. */
+  readonly text: string;
+  /** Alias for `sizeBytes`. */
+  readonly bytes: number;
+}
+
+export class FileListing {
+  constructor(data: Record<string, any>);
+  path: string;
+  entries: FileEntry[];
+  truncated: boolean;
+  /** The entry names, in listing order. */
+  names(): string[];
+  [Symbol.iterator](): Iterator<FileEntry>;
+  readonly length: number;
+}
+
+export class Page {
+  constructor(data: Record<string, any>);
+  data: Record<string, any>[];
+  hasMore: boolean;
+  nextCursor: string | null;
+  [Symbol.iterator](): Iterator<Record<string, any>>;
+  readonly length: number;
+}
+
+export class Client {
+  constructor(options?: ClientOptions);
+  apiKey: string;
+  baseUrl: string;
+  timeoutMs: number;
+
+  /**
+   * Create a sandbox and return it once it is ready to accept commands.
+   * `POST /v1/sandboxes` is synchronous: the response arrives after the
+   * machine has booted.
+   */
+  createSandbox(options?: CreateSandboxOptions): Promise<Sandbox>;
+  /** Fetch one sandbox by id. */
+  getSandbox(sandboxId: string): Promise<Sandbox>;
+  /** List sandboxes, newest first. Follow `nextCursor` for more pages. */
+  listSandboxes(options?: ListSandboxesOptions): Promise<Page>;
+  /** Iterate every sandbox across pages, following the cursor for you. */
+  iterSandboxes(options?: ListSandboxesOptions): AsyncGenerator<Record<string, any>, void, unknown>;
+  /** Usage and spend over a window. */
+  getUsage(options?: GetUsageOptions): Promise<Record<string, any>>;
+  /** Balance, limits and current pricing. */
+  getAccount(): Promise<Record<string, any>>;
+  /** Release client resources (a no-op, kept for symmetry). */
+  close(): void;
+}
+
+// ------------------------------------------------------------------- errors
+
+export class SandboxError extends Error {}
+
+export class SandboxApiError extends SandboxError {
+  constructor(
+    message: string,
+    options?: {
+      status?: number | null;
+      type?: string | null;
+      requestId?: string | null;
+      responseBody?: unknown;
+    }
+  );
+  /** HTTP status code. */
+  status: number | null;
+  /** The API's stable machine-readable error code (`error.type`). */
+  type: string | null;
+  /** The API's request id, for support. */
+  requestId: string | null;
+  /** The decoded body, when it was JSON. */
+  responseBody: unknown;
+  /** Alias for `type`. */
+  readonly code: string | null;
+  /** Alias for `responseBody`. */
+  readonly body: unknown;
+  toString(): string;
+}
+
+/** The client was constructed or called with something it cannot use. Raised before any request is made. */
+export class SandboxConfigurationError extends SandboxError {}
+
+/** The request never produced an HTTP response (DNS, TLS, timeout, reset). */
+export class SandboxConnectionError extends SandboxError {}
+
+/** 401 — missing, malformed, unknown or revoked key. */
+export class AuthenticationError extends SandboxApiError {}
+
+/** 403 — the key is valid but not allowed to do this. */
+export class PermissionDeniedError extends SandboxApiError {}
+
+/** 404 — the sandbox, execution or file does not exist (or already expired). */
+export class NotFoundError extends SandboxApiError {}
+
+/** 400 — the request body or query is not accepted. A 422 maps to the base `SandboxApiError`. */
+export class InvalidRequestError extends SandboxApiError {}
+
+/** 409 — the sandbox is not in a state that allows this, or an idempotency clash. */
+export class ConflictError extends SandboxApiError {}
+
+/** 402 — the account has no credit left. */
+export class PaymentRequiredError extends SandboxApiError {}
+
+/** 429 — too many requests. `retryAfter` is set when the Retry-After header is sent. */
+export class RateLimitError extends SandboxApiError {
+  constructor(
+    message: string,
+    options?: {
+      status?: number | null;
+      type?: string | null;
+      requestId?: string | null;
+      responseBody?: unknown;
+      retryAfter?: number | null;
+    }
+  );
+  retryAfter: number | null;
+}
+
+/** 503 — the platform could not serve the request. Safe to retry later. */
+export class ServiceUnavailableError extends SandboxApiError {}
+
+export declare const VERSION: string;

package/index.js

@@ -0,0 +1,752 @@
+'use strict';
+
+// A zero-dependency Node.js client for the Sandbox as a Service REST API.
+//
+// The whole surface is a handful of endpoints — create a sandbox, run commands
+// in it, move files, expose a port, extend it, destroy it — so this client is
+// a thin, typed wrapper rather than a framework. It is built on the global
+// `fetch` that ships with Node.js 18 and newer: there is nothing to install
+// alongside it and nothing that can fail to resolve in a minimal agent
+// environment.
+//
+// Quickstart:
+//
+//     import { Client } from 'sandbox-as-a-service';
+//
+//     const client = new Client(); // reads AAS_API_KEY from the environment
+//     const sandbox = await client.createSandbox({ size: 'small', timeoutMinutes: 10 });
+//     try {
+//         const result = await sandbox.exec("python3 -c 'print(6 * 7)'");
+//         console.log(result.stdout.trim()); // -> 42
+//     } finally {
+//         await sandbox.destroy();
+//     }
+//
+// API reference: https://sandbox-as-a-service.com/docs/api
+
+const crypto = require('node:crypto');
+
+const VERSION = '0.1.0';
+const DEFAULT_BASE_URL = 'https://sandbox-as-a-service.com';
+const USER_AGENT = `sandbox-as-a-service-js/${VERSION}`;
+
+// ------------------------------------------------------------------- errors
+
+class SandboxError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+class SandboxApiError extends SandboxError {
+  /**
+   * @param {string} message
+   * @param {{status?: number|null, type?: string|null, requestId?: string|null, responseBody?: unknown}} [options]
+   */
+  constructor(message, options = {}) {
+    super(message);
+    const { status = null, type = null, requestId = null, responseBody = null } = options;
+    this.message = message;
+    this.status = status;
+    this.type = type;
+    this.requestId = requestId;
+    this.responseBody = responseBody;
+  }
+
+  // Aliases for the API field names, so callers can read either spelling.
+  get code() {
+    return this.type;
+  }
+
+  get body() {
+    return this.responseBody;
+  }
+
+  toString() {
+    let base = this.message;
+    if (this.status != null) {
+      let detail = `HTTP ${this.status}`;
+      if (this.type) detail += `, ${this.type}`;
+      base += ` (${detail})`;
+    }
+    if (this.requestId) base += ` [request_id=${this.requestId}]`;
+    return base;
+  }
+}
+
+class SandboxConfigurationError extends SandboxError {}
+
+class SandboxConnectionError extends SandboxError {}
+
+class AuthenticationError extends SandboxApiError {}
+
+class PermissionDeniedError extends SandboxApiError {}
+
+class NotFoundError extends SandboxApiError {}
+
+class InvalidRequestError extends SandboxApiError {}
+
+class ConflictError extends SandboxApiError {}
+
+class PaymentRequiredError extends SandboxApiError {}
+
+class RateLimitError extends SandboxApiError {
+  /**
+   * @param {string} message
+   * @param {{status?: number|null, type?: string|null, requestId?: string|null, responseBody?: unknown, retryAfter?: number|null}} [options]
+   */
+  constructor(message, options = {}) {
+    const { retryAfter = null, ...rest } = options;
+    super(message, rest);
+    this.retryAfter = retryAfter;
+  }
+}
+
+class ServiceUnavailableError extends SandboxApiError {}
+
+// Maps the API's `error.type` strings to a class. The type is the contract;
+// the status code is a second signal used when the type is unfamiliar.
+const BY_TYPE = {
+  invalid_request: InvalidRequestError,
+  unauthorized: AuthenticationError,
+  authentication_error: AuthenticationError,
+  forbidden: PermissionDeniedError,
+  not_found: NotFoundError,
+  conflict: ConflictError,
+  insufficient_credits: PaymentRequiredError,
+  payment_required: PaymentRequiredError,
+  rate_limited: RateLimitError,
+  service_unavailable: ServiceUnavailableError,
+};
+
+const BY_STATUS = {
+  400: InvalidRequestError,
+  401: AuthenticationError,
+  402: PaymentRequiredError,
+  403: PermissionDeniedError,
+  404: NotFoundError,
+  409: ConflictError,
+  429: RateLimitError,
+  503: ServiceUnavailableError,
+};
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function errorFromResponse(status, body, retryAfter = null) {
+  let errType = null;
+  let message = `Request failed with HTTP ${status}`;
+  let requestId = null;
+  if (isPlainObject(body)) {
+    requestId = body.request_id ?? null;
+    const err = body.error;
+    if (isPlainObject(err)) {
+      errType = err.type ?? null;
+      if (err.message) message = String(err.message);
+    }
+  }
+  const cls = (errType && BY_TYPE[errType]) || BY_STATUS[status] || SandboxApiError;
+  if (cls === RateLimitError) {
+    return new RateLimitError(message, {
+      status,
+      type: errType,
+      requestId,
+      responseBody: body,
+      retryAfter,
+    });
+  }
+  return new cls(message, { status, type: errType, requestId, responseBody: body });
+}
+
+// ------------------------------------------------------------------ helpers
+
+function decodeBody(text) {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function parseRetryAfter(value) {
+  if (value == null || value === '') return null;
+  const seconds = Number(value);
+  return Number.isFinite(seconds) ? seconds : null;
+}
+
+function connectionError(url, err) {
+  const reason = err && err.message ? err.message : String(err);
+  return new SandboxConnectionError(`Could not reach ${url}: ${reason}`);
+}
+
+// Parse a Server-Sent Events body, yielding [event, data] as events end.
+//
+// The stream is read chunk by chunk, so events surface as they arrive rather
+// than at EOF. Lines are split at "\n" in a text buffer, which keeps events
+// that arrive split across chunk boundaries intact, and a streaming
+// TextDecoder keeps multi-byte UTF-8 characters that straddle a chunk
+// boundary intact. Comment lines (": ping" heartbeats) are filtered out. A
+// block that ends without a trailing blank line is not dispatched; the caller
+// reports the missing terminal event rather than inventing one.
+async function* sseEvents(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder('utf-8');
+  let buffer = '';
+  let event = null;
+  let dataLines = [];
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let newline;
+      while ((newline = buffer.indexOf('\n')) !== -1) {
+        let line = buffer.slice(0, newline);
+        buffer = buffer.slice(newline + 1);
+        if (line.endsWith('\r')) line = line.slice(0, -1);
+        if (line === '') {
+          if (event !== null && dataLines.length > 0) yield [event, dataLines.join('\n')];
+          event = null;
+          dataLines = [];
+        } else if (line.startsWith(':')) {
+          continue; // heartbeat comment
+        } else if (line.startsWith('event: ')) {
+          event = line.slice('event: '.length);
+        } else if (line.startsWith('data: ')) {
+          dataLines.push(line.slice('data: '.length));
+        }
+      }
+    }
+    // A stream that ends without a final blank line leaves its last event
+    // undispatched; the caller reports the missing terminal event instead of
+    // inventing one.
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// ------------------------------------------------------------------- models
+
+class Sandbox {
+  /**
+   * A running (or recently created) sandbox.
+   *
+   * Instances are returned by `Client.createSandbox` and `Client.getSandbox`;
+   * you do not construct them yourself. The command and file helpers talk to
+   * the sandbox this object names, so the `id` is the only state that matters.
+   */
+  constructor(client, data) {
+    this._client = client;
+    this._apply(data);
+  }
+
+  _apply(data) {
+    this.id = data.id;
+    this.object = data.object ?? 'sandbox';
+    this.name = data.name ?? null;
+    this.status = data.status ?? 'running';
+    this.size = data.size ?? null;
+    this.resources = { ...(data.resources || {}) };
+    this.timeoutMinutes = data.timeout_minutes ?? null;
+    this.createdAt = data.created_at ?? null;
+    this.readyAt = data.ready_at ?? null;
+    this.expiresAt = data.expires_at ?? null;
+    this.deletedAt = data.deleted_at ?? null;
+    this.raw = { ...data };
+    return this;
+  }
+
+  // -------------------------------------------------------------- lifecycle
+
+  /** Fetch the current state and update this object in place. */
+  async refresh() {
+    return this._apply(await this._client._request('GET', `/sandboxes/${this.id}`));
+  }
+
+  /** Add lifetime to a running sandbox and return the updated object. */
+  async extend(additionalMinutes = 15) {
+    const data = await this._client._request('POST', `/sandboxes/${this.id}/extend`, {
+      body: { additional_minutes: additionalMinutes },
+    });
+    return this._apply(data);
+  }
+
+  /**
+   * Destroy the sandbox. Billing stops at teardown.
+   *
+   * Returns the API's confirmation object. A teardown still in progress comes
+   * back with `status === "deleting"` and is retried by the platform; it is
+   * not an error.
+   */
+  async destroy() {
+    return this._client._request('DELETE', `/sandboxes/${this.id}`);
+  }
+
+  // --------------------------------------------------------------- commands
+
+  /**
+   * Run a shell command inside the sandbox and return its result.
+   *
+   * This call resolves when the command finishes. `timeoutMs` bounds the
+   * command itself (1s–600s); the HTTP client is given a little longer so a
+   * command that runs to its limit still returns a result rather than a
+   * client-side timeout.
+   *
+   * Pass `onStdout` or `onStderr` to stream: the call switches to the API's
+   * event stream and the callback fires per chunk as the sandbox produces
+   * output, instead of everything arriving at the end. The return value is
+   * the usual `Execution`, built from the stream's terminal `exit` event. An
+   * exception thrown by a callback propagates and closes the stream — which
+   * kills the remote command, the same as disconnecting.
+   */
+  async exec(command, { timeoutMs = 60_000, cwd = null, env = null, onStdout = null, onStderr = null } = {}) {
+    const body = { command, timeout_ms: timeoutMs };
+    if (cwd !== null && cwd !== undefined) body.cwd = cwd;
+    if (env !== null && env !== undefined) body.env = { ...env };
+    const requestTimeoutMs = Math.max(this._client.timeoutMs, timeoutMs + 30_000);
+    let data;
+    if (onStdout !== null || onStderr !== null) {
+      body.stream = true;
+      data = await this._client._streamExec(
+        `/sandboxes/${this.id}/exec`,
+        body,
+        requestTimeoutMs,
+        onStdout,
+        onStderr
+      );
+    } else {
+      data = await this._client._request('POST', `/sandboxes/${this.id}/exec`, {
+        body,
+        timeoutMs: requestTimeoutMs,
+      });
+    }
+    return new Execution(data);
+  }
+
+  async getExecution(executionId) {
+    return new Execution(await this._client._request('GET', `/executions/${executionId}`));
+  }
+
+  // ------------------------------------------------------------------ files
+
+  /**
+   * Write a file inside the sandbox.
+   *
+   * `path` is relative to the workspace (`/workspace`) or absolute under it.
+   * Pass `encoding: "base64"` to write binary content.
+   */
+  async writeFile(path, content, { encoding = 'utf8' } = {}) {
+    return this._client._request('PUT', `/sandboxes/${this.id}/files`, {
+      body: { path, content, encoding },
+    });
+  }
+
+  /** Read a file and decode it (`utf8` or `base64`). */
+  async readFile(path, { encoding = 'utf8' } = {}) {
+    const data = await this._client._request('GET', `/sandboxes/${this.id}/files`, {
+      query: { path, encoding },
+    });
+    return new FileContent(data);
+  }
+
+  /** List a directory. Returns entries with `name`, `type` and `size_bytes`. */
+  async listFiles(path = '/workspace', { recursive = true } = {}) {
+    const data = await this._client._request('GET', `/sandboxes/${this.id}/files`, {
+      query: { path, list: 'true', recursive: recursive ? 'true' : 'false' },
+    });
+    return new FileListing(data);
+  }
+
+  /** Delete a file, or a directory tree when `recursive` is true. */
+  async deleteFile(path, { recursive = false } = {}) {
+    return this._client._request('DELETE', `/sandboxes/${this.id}/files`, {
+      query: { path, recursive: recursive ? 'true' : 'false' },
+    });
+  }
+
+  // ------------------------------------------------------------------ ports
+
+  /** Expose a port on a public preview URL. Returns `{url, port, ...}`. */
+  async exposePort(port) {
+    return this._client._request('POST', `/sandboxes/${this.id}/ports`, { body: { port } });
+  }
+
+  async listPorts() {
+    const data = await this._client._request('GET', `/sandboxes/${this.id}/ports`);
+    return isPlainObject(data) && Array.isArray(data.data) ? [...data.data] : [];
+  }
+
+  /** Close a preview URL previously opened for `port`. */
+  async closePort(port) {
+    return this._client._request('DELETE', `/sandboxes/${this.id}/ports/${port}`);
+  }
+
+  toString() {
+    return `<Sandbox id=${JSON.stringify(this.id)} status=${JSON.stringify(this.status)} size=${JSON.stringify(this.size)}>`;
+  }
+}
+
+// `await using sandbox = await client.createSandbox()` destroys the sandbox
+// when the scope ends — the same contract as the Python context manager.
+// The symbol only exists on Node.js 22 and newer, so the method is attached
+// conditionally to stay loadable on 18.
+if (typeof Symbol !== 'undefined' && typeof Symbol.asyncDispose !== 'undefined') {
+  Sandbox.prototype[Symbol.asyncDispose] = function asyncDispose() {
+    return this.destroy();
+  };
+}
+
+class Execution {
+  /** The result of `Sandbox.exec`. */
+  constructor(data) {
+    this.id = data.id;
+    this.object = data.object ?? 'execution';
+    this.sandboxId = data.sandbox_id ?? null;
+    this.status = data.status ?? 'completed';
+    this.exitCode = data.exit_code ?? null;
+    this.stdout = data.stdout || '';
+    this.stderr = data.stderr || '';
+    this.truncated = Boolean(data.truncated);
+    this.durationMs = data.duration_ms ?? null;
+    this.startedAt = data.started_at ?? null;
+    this.finishedAt = data.finished_at ?? null;
+    this.raw = { ...data };
+  }
+
+  get ok() {
+    return this.exitCode === 0 && this.status === 'completed';
+  }
+
+  /** Raise `ExecutionFailed` if the command did not exit 0. */
+  check() {
+    if (!this.ok) throw new ExecutionFailed(this);
+    return this;
+  }
+
+  toString() {
+    return `<Execution id=${JSON.stringify(this.id)} status=${JSON.stringify(this.status)} exit_code=${JSON.stringify(this.exitCode)}>`;
+  }
+}
+
+class ExecutionFailed extends Error {
+  constructor(execution) {
+    const stripped = execution.stderr.trim();
+    const lines = stripped === '' ? [] : stripped.split('\n');
+    const tail = lines.length > 0 ? `: ${lines[lines.length - 1]}` : '';
+    super(`command '${execution.status}' with exit code ${execution.exitCode}${tail}`);
+    this.name = 'ExecutionFailed';
+    this.execution = execution;
+  }
+}
+
+class FileContent {
+  /** A file read back from a sandbox. */
+  constructor(data) {
+    this.path = data.path ?? '';
+    this.content = data.content ?? '';
+    this.sizeBytes = data.bytes ?? 0;
+    this.encoding = data.encoding ?? 'utf8';
+    this.raw = { ...data };
+  }
+
+  get text() {
+    return this.content;
+  }
+
+  get bytes() {
+    return this.sizeBytes;
+  }
+
+  toString() {
+    return `<FileContent path=${JSON.stringify(this.path)} bytes=${JSON.stringify(this.sizeBytes)}>`;
+  }
+}
+
+class FileListing {
+  /** A directory listing, capped at the platform's entry limit. */
+  constructor(data) {
+    this.path = data.path ?? '';
+    this.entries = Array.isArray(data.entries) ? [...data.entries] : [];
+    this.truncated = Boolean(data.truncated);
+  }
+
+  names() {
+    return this.entries.map((entry) => (isPlainObject(entry) && entry.name != null ? entry.name : ''));
+  }
+
+  [Symbol.iterator]() {
+    return this.entries[Symbol.iterator]();
+  }
+
+  get length() {
+    return this.entries.length;
+  }
+
+  toString() {
+    return `<FileListing path=${JSON.stringify(this.path)} entries=${JSON.stringify(this.entries.length)}>`;
+  }
+}
+
+class Page {
+  /** One page of a cursor-paginated list. */
+  constructor(data) {
+    const source = isPlainObject(data) ? data : {};
+    this.data = Array.isArray(source.data) ? [...source.data] : [];
+    this.hasMore = Boolean(source.has_more);
+    this.nextCursor = source.next_cursor ?? null;
+  }
+
+  [Symbol.iterator]() {
+    return this.data[Symbol.iterator]();
+  }
+
+  get length() {
+    return this.data.length;
+  }
+
+  toString() {
+    return `<Page items=${JSON.stringify(this.data.length)} has_more=${JSON.stringify(this.hasMore)}>`;
+  }
+}
+
+// ------------------------------------------------------------------ client
+
+class Client {
+  /**
+   * Client for one account's API key.
+   *
+   * @param {{apiKey?: string|null, baseUrl?: string|null, timeoutMs?: number}} [options]
+   *
+   * `apiKey`: a key created in the dashboard; it starts with `aas_sk_`. If
+   * omitted, `AAS_API_KEY` is read from the environment.
+   *
+   * `baseUrl`: the API root. The default is the public service (or
+   * `AAS_BASE_URL` when set); a bare host gets `/v1` appended, and a URL that
+   * already ends in `/v1` is used as-is.
+   *
+   * `timeoutMs`: default per-request timeout in milliseconds. Sandbox
+   * creation blocks until the machine is ready, so this is generous by
+   * design.
+   */
+  constructor({ apiKey = null, baseUrl = null, timeoutMs = 600_000 } = {}) {
+    this.apiKey = apiKey ?? process.env.AAS_API_KEY ?? null;
+    if (!this.apiKey) {
+      throw new SandboxConfigurationError(
+        'No API key. Pass apiKey: ... or set the AAS_API_KEY environment variable.'
+      );
+    }
+    const base = baseUrl ?? process.env.AAS_BASE_URL ?? DEFAULT_BASE_URL;
+    if (!base.startsWith('http://') && !base.startsWith('https://')) {
+      throw new SandboxConfigurationError(`base_url must be http(s), got ${JSON.stringify(base)}`);
+    }
+    let normalized = base.replace(/\/+$/, '');
+    if (!normalized.endsWith('/v1')) normalized += '/v1';
+    this.baseUrl = normalized;
+    this.timeoutMs = Number(timeoutMs);
+  }
+
+  // ------------------------------------------------------------------ HTTP
+
+  async _request(method, path, { body = null, query = null, headers = null, timeoutMs = null } = {}) {
+    let url = `${this.baseUrl}${path}`;
+    if (query) {
+      const clean = Object.fromEntries(
+        Object.entries(query).filter(([, value]) => value !== null && value !== undefined)
+      );
+      const queryString = new URLSearchParams(clean).toString();
+      if (queryString) url += `?${queryString}`;
+    }
+
+    const requestHeaders = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: 'application/json',
+      'User-Agent': USER_AGENT,
+    };
+    let payload;
+    if (body !== null && body !== undefined) {
+      payload = JSON.stringify(body);
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+    if (headers) Object.assign(requestHeaders, headers);
+
+    const timeout = timeoutMs ?? this.timeoutMs;
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers: requestHeaders,
+        body: payload,
+        signal: AbortSignal.timeout(timeout),
+      });
+    } catch (err) {
+      if (err instanceof SandboxError) throw err;
+      throw connectionError(url, err);
+    }
+
+    const text = await response.text();
+    const decoded = decodeBody(text);
+    if (!response.ok) {
+      throw errorFromResponse(response.status, decoded, parseRetryAfter(response.headers.get('Retry-After')));
+    }
+    return decoded;
+  }
+
+  async _streamExec(path, body, timeoutMs, onStdout, onStderr) {
+    /**
+     * Consume a streamed exec, invoking callbacks per chunk.
+     *
+     * Returns the exit event's payload (the same object the non-streaming
+     * call returns). An `error` event is raised through the same exception
+     * mapping the rest of the client uses; an exception a callback raises
+     * propagates, which closes the connection and — like disconnecting —
+     * kills the remote command.
+     */
+    const url = `${this.baseUrl}${path}`;
+    let response;
+    try {
+      response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          Accept: 'text/event-stream',
+          'User-Agent': USER_AGENT,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (err) {
+      if (err instanceof SandboxError) throw err;
+      throw connectionError(url, err);
+    }
+    if (!response.ok) {
+      const text = await response.text();
+      throw errorFromResponse(response.status, decodeBody(text), parseRetryAfter(response.headers.get('Retry-After')));
+    }
+
+    const stream = response.body;
+    try {
+      if (stream) {
+        for await (const [event, payload] of sseEvents(stream)) {
+          if (event === 'stdout') {
+            if (onStdout !== null) await onStdout(JSON.parse(payload).data);
+          } else if (event === 'stderr') {
+            if (onStderr !== null) await onStderr(JSON.parse(payload).data);
+          } else if (event === 'exit') {
+            return JSON.parse(payload);
+          } else if (event === 'error') {
+            // The same error object the API returns out of band; use the
+            // client's existing status/type mapping. A failure that reaches
+            // the stream is always after the 200, so its status comes from
+            // the type alone.
+            throw errorFromResponse(502, JSON.parse(payload));
+          }
+        }
+      }
+    } finally {
+      // Cancelling the body closes the socket, which is what tells the
+      // platform the client went away — cancelling the command. This also
+      // fires when a callback raises or the exit event ends the loop early.
+      if (stream) {
+        try {
+          await stream.cancel();
+        } catch {
+          // Already closed; nothing to do.
+        }
+      }
+    }
+    throw new SandboxConnectionError('the event stream ended without an exit event');
+  }
+
+  // -------------------------------------------------------------- resources
+
+  /**
+   * Create a sandbox and return it once it is ready to accept commands.
+   *
+   * `POST /v1/sandboxes` is synchronous: the response arrives after the
+   * machine has booted. Sizes are `small`, `medium` and `large`.
+   *
+   * Retrying a create is safe when you pass the same `idempotencyKey`; the
+   * platform returns the original sandbox instead of a second one. When
+   * omitted, a fresh key is generated for this call.
+   */
+  async createSandbox({ size = 'small', name = null, timeoutMinutes = null, idempotencyKey = null } = {}) {
+    const body = { size };
+    if (name !== null && name !== undefined) body.name = name;
+    if (timeoutMinutes !== null && timeoutMinutes !== undefined) body.timeout_minutes = timeoutMinutes;
+    const key = idempotencyKey || crypto.randomUUID();
+    const data = await this._request('POST', '/sandboxes', { body, headers: { 'Idempotency-Key': key } });
+    return new Sandbox(this, data);
+  }
+
+  async getSandbox(sandboxId) {
+    return new Sandbox(this, await this._request('GET', `/sandboxes/${sandboxId}`));
+  }
+
+  /** List sandboxes, newest first. Follow `nextCursor` for more pages. */
+  async listSandboxes({ limit = 20, startingAfter = null, includeDeleted = false } = {}) {
+    const query = { limit };
+    if (startingAfter) query.starting_after = startingAfter;
+    if (includeDeleted) query.include_deleted = 'true';
+    return new Page(await this._request('GET', '/sandboxes', { query }));
+  }
+
+  /** Iterate every sandbox across pages, following the cursor for you. */
+  async *iterSandboxes({ limit = 20, includeDeleted = false } = {}) {
+    let cursor = null;
+    for (;;) {
+      const page = await this.listSandboxes({ limit, startingAfter: cursor, includeDeleted });
+      for (const item of page.data) yield item;
+      if (!page.hasMore || !page.nextCursor) return;
+      cursor = page.nextCursor;
+    }
+  }
+
+  async getUsage({ days = 30 } = {}) {
+    return this._request('GET', '/usage', { query: { days } });
+  }
+
+  async getAccount() {
+    return this._request('GET', '/account');
+  }
+
+  // ------------------------------------------------------------- lifecycle
+
+  /**
+   * Release client resources.
+   *
+   * The global fetch keeps no pooled connection the client owns, so this is
+   * a no-op kept for symmetry with the Python client and other clients.
+   */
+  close() {}
+
+  toString() {
+    return `<Client base_url=${JSON.stringify(this.baseUrl)}>`;
+  }
+}
+
+module.exports = {
+  Client,
+  Sandbox,
+  Execution,
+  ExecutionFailed,
+  FileContent,
+  FileListing,
+  Page,
+  SandboxError,
+  SandboxApiError,
+  SandboxConfigurationError,
+  SandboxConnectionError,
+  AuthenticationError,
+  PermissionDeniedError,
+  NotFoundError,
+  InvalidRequestError,
+  ConflictError,
+  PaymentRequiredError,
+  RateLimitError,
+  ServiceUnavailableError,
+  VERSION,
+};

package/index.mjs

@@ -0,0 +1,26 @@
+import cjs from './index.js';
+
+export const {
+  Client,
+  Sandbox,
+  Execution,
+  ExecutionFailed,
+  FileContent,
+  FileListing,
+  Page,
+  SandboxError,
+  SandboxApiError,
+  SandboxConfigurationError,
+  SandboxConnectionError,
+  AuthenticationError,
+  PermissionDeniedError,
+  NotFoundError,
+  InvalidRequestError,
+  ConflictError,
+  PaymentRequiredError,
+  RateLimitError,
+  ServiceUnavailableError,
+  VERSION,
+} = cjs;
+
+export default cjs;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "sandbox-as-a-service",
+  "version": "0.1.0",
+  "description": "Zero-dependency JavaScript/TypeScript client for Sandbox as a Service — secure, disposable cloud sandboxes for AI agents and code execution",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": "https://sandbox-as-a-service.com/docs/sdk",
+  "homepage": "https://sandbox-as-a-service.com/docs/sdk",
+  "keywords": [
+    "sandbox",
+    "sandbox-as-a-service",
+    "code-execution",
+    "ai-agents",
+    "cloud",
+    "vm",
+    "api-client",
+    "sdk"
+  ],
+  "sideEffects": false
+}