@brimble/sandbox 0.1.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@brimble/sandbox",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Brimble Sandbox API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p .",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --config vitest.config.ts",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:all": "npm run test && npm run test:integration"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}

package/src/client.ts

@@ -0,0 +1,61 @@
+import { DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS, SANDBOX_API_KEY_ENV_NAME } from './constants';
+import { SandboxesResource, SnapshotsResource, VolumesResource } from './resources';
+import { HttpTransport } from './transport/http';
+import type { RetryOptions } from './transport/http';
+
+export type SandboxClientOptions = {
+  apiKey?: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  retry?: RetryOptions;
+  fetchImpl?: typeof fetch;
+};
+
+/**
+ * Resolves the API key from the constructor options first,
+ * then falls back to BRIMBLE_SANDBOX_KEY.
+ */
+function resolveApiKey(options: SandboxClientOptions): string {
+  if (options.apiKey) {
+    return options.apiKey;
+  }
+
+  const apiKeyFromEnv = process.env[SANDBOX_API_KEY_ENV_NAME];
+
+  if (apiKeyFromEnv) {
+    return apiKeyFromEnv;
+  }
+
+  throw new Error(
+    `Sandbox API key is required. Pass "apiKey" explicitly or set ${SANDBOX_API_KEY_ENV_NAME} in your environment.`,
+  );
+}
+
+export class SandboxClient {
+  /** Access sandbox lifecycle and per-sandbox scoped operations. */
+  public readonly sandboxes: SandboxesResource;
+  /** Access account-level snapshot operations. */
+  public readonly snapshots: SnapshotsResource;
+  /** Access volume lifecycle operations. */
+  public readonly volumes: VolumesResource;
+
+  private readonly transport: HttpTransport;
+
+  /**
+   * Creates a client instance for the Brimble Sandbox API.
+   * Pass `apiKey` directly or set `BRIMBLE_SANDBOX_KEY` in your environment.
+   */
+  public constructor(options: SandboxClientOptions = {}) {
+    this.transport = new HttpTransport({
+      apiKey: resolveApiKey(options),
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      retry: options.retry,
+      fetchImpl: options.fetchImpl,
+    });
+
+    this.sandboxes = new SandboxesResource(this.transport);
+    this.snapshots = new SnapshotsResource(this.transport);
+    this.volumes = new VolumesResource(this.transport);
+  }
+}

package/src/constants.ts

@@ -0,0 +1,17 @@
+import packageJson from '../package.json';
+
+export const DEFAULT_BASE_URL = 'https://sandbox.brimble.io';
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const SANDBOX_API_KEY_ENV_NAME = 'BRIMBLE_SANDBOX_KEY';
+export const SDK_PACKAGE_VERSION = packageJson.version;
+
+export const DEFAULT_PAGE = 1;
+export const DEFAULT_PAGE_LIMIT = 15;
+export const MAX_PAGE_LIMIT = 100;
+export const MIN_VOLUME_SIZE_GB = 10;
+export const DEFAULT_SANDBOX_READY_TIMEOUT_MS = 60_000;
+export const DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS = 2_000;
+export const DEFAULT_RETRY_MAX_ATTEMPTS = 1;
+export const DEFAULT_RETRY_BASE_DELAY_MS = 300;
+export const DEFAULT_RETRY_MAX_DELAY_MS = 3_000;
+export const DEFAULT_RETRY_STATUSES = [408, 429, 500, 502, 503, 504] as const;

package/src/enums/code-language.ts

@@ -0,0 +1,4 @@
+export enum CodeLanguage {
+  Python = 'python',
+  Node = 'node',
+}

package/src/enums/destroy-reason.ts

@@ -0,0 +1,8 @@
+export enum DestroyReason {
+  User = 'user',
+  IdleTtl = 'idle_ttl',
+  MaxLifetime = 'max_lifetime',
+  OneShotStopped = 'one_shot_stopped',
+  Failed = 'failed',
+  PausedTooLong = 'paused_too_long',
+}

package/src/enums/destroy-timeout.ts

@@ -0,0 +1,8 @@
+export enum DestroyTimeout {
+  ThirtyMinutes = '30m',
+  OneHour = '1h',
+  ThreeHours = '3h',
+  SixHours = '6h',
+  TwelveHours = '12h',
+  EighteenHours = '18h',
+}

package/src/enums/index.ts

@@ -0,0 +1,7 @@
+export { CodeLanguage } from './code-language';
+export { DestroyReason } from './destroy-reason';
+export { DestroyTimeout } from './destroy-timeout';
+export { SandboxStatus } from './sandbox-status';
+export { SnapshotMode } from './snapshot-mode';
+export { SnapshotStatus } from './snapshot-status';
+export { VolumeType } from './volume-type';

package/src/enums/sandbox-status.ts

@@ -0,0 +1,9 @@
+export enum SandboxStatus {
+  Starting = 'starting',
+  Ready = 'ready',
+  Pausing = 'pausing',
+  Paused = 'paused',
+  Resuming = 'resuming',
+  Failed = 'failed',
+  Destroyed = 'destroyed',
+}

package/src/enums/snapshot-mode.ts

@@ -0,0 +1,4 @@
+export enum SnapshotMode {
+  Manual = 'manual',
+  Automatic = 'automatic',
+}

package/src/enums/snapshot-status.ts

@@ -0,0 +1,5 @@
+export enum SnapshotStatus {
+  Creating = 'creating',
+  Ready = 'ready',
+  Failed = 'failed',
+}

package/src/enums/volume-type.ts

@@ -0,0 +1,3 @@
+export enum VolumeType {
+  Sandbox = 'sandbox',
+}

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export { AuthError, NotFoundError, RateLimitError, SandboxApiError, ValidationError } from './sandbox-api-error';
+export type { SandboxApiErrorArgs } from './sandbox-api-error';

package/src/errors/sandbox-api-error.ts

@@ -0,0 +1,54 @@
+export type SandboxApiErrorArgs = {
+  status: number;
+  message: string;
+  endpoint: string;
+  responseBody: unknown;
+  requestId?: string | null;
+};
+
+export class SandboxApiError extends Error {
+  public readonly status: number;
+  public readonly endpoint: string;
+  public readonly responseBody: unknown;
+  public readonly requestId: string | null;
+
+  public constructor(args: SandboxApiErrorArgs) {
+    super(args.message);
+    this.name = 'SandboxApiError';
+    this.status = args.status;
+    this.endpoint = args.endpoint;
+    this.responseBody = args.responseBody;
+    this.requestId = args.requestId ?? null;
+  }
+}
+
+export class AuthError extends SandboxApiError {
+  public constructor(args: SandboxApiErrorArgs) {
+    super(args);
+    this.name = 'AuthError';
+  }
+}
+
+export class ValidationError extends SandboxApiError {
+  public constructor(args: SandboxApiErrorArgs) {
+    super(args);
+    this.name = 'ValidationError';
+  }
+}
+
+export class NotFoundError extends SandboxApiError {
+  public constructor(args: SandboxApiErrorArgs) {
+    super(args);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class RateLimitError extends SandboxApiError {
+  public readonly retryAfterSeconds: number | null;
+
+  public constructor(args: SandboxApiErrorArgs & { retryAfterSeconds?: number | null }) {
+    super(args);
+    this.name = 'RateLimitError';
+    this.retryAfterSeconds = args.retryAfterSeconds ?? null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+export {
+  DEFAULT_BASE_URL,
+  DEFAULT_PAGE,
+  DEFAULT_PAGE_LIMIT,
+  DEFAULT_RETRY_BASE_DELAY_MS,
+  DEFAULT_RETRY_MAX_ATTEMPTS,
+  DEFAULT_RETRY_MAX_DELAY_MS,
+  DEFAULT_RETRY_STATUSES,
+  DEFAULT_TIMEOUT_MS,
+  MAX_PAGE_LIMIT,
+  SANDBOX_API_KEY_ENV_NAME,
+} from './constants';
+export { SandboxClient } from './client';
+export type { SandboxClientOptions } from './client';
+
+export { AuthError, NotFoundError, RateLimitError, SandboxApiError, ValidationError } from './errors';
+export type { SandboxApiErrorArgs } from './errors';
+
+export {
+  CodeLanguage,
+  DestroyReason,
+  DestroyTimeout,
+  SandboxStatus,
+  SnapshotMode,
+  SnapshotStatus,
+  VolumeType,
+} from './enums';
+
+export {
+  ExecResource,
+  FilesResource,
+  SandboxHandle,
+  SandboxesResource,
+  ScopedSandboxResource,
+  SnapshotScopeResource,
+  SnapshotsResource,
+  StatsResource,
+  VolumesResource,
+} from './resources';
+
+export type {
+  AckMessage,
+  CodeInput,
+  CreateSandboxInput,
+  CreateSandboxResult,
+  CreateSnapshotInput,
+  CreateVolumeInput,
+  ExecInput,
+  ExecResult,
+  ExecStreamFrame,
+  FileUploadBody,
+  Paginated,
+  Pagination,
+  RegionSummary,
+  SandboxRegion,
+  SandboxRegionsResult,
+  Sandbox,
+  SandboxSpecs,
+  Snapshot,
+  Stats,
+  StatsAverageNetwork,
+  StatsAverageNumeric,
+  StatsQuery,
+  StatsTimelinePoint,
+  TeamScopedPagination,
+  WaitUntilReadyOptions,
+  Volume,
+} from './types';
+
+export type { RequestOptions } from './transport/http';
+export type { RetryOptions } from './transport/http';

package/src/resources/exec.ts

@@ -0,0 +1,56 @@
+import type { CodeInput, ExecInput, ExecResult } from '../types';
+import type { RequestOptions } from '../transport/http';
+import { HttpTransport } from '../transport/http';
+
+export class ExecResource {
+  private readonly transport: HttpTransport;
+  private readonly sandboxId: string;
+
+  /** @internal Create the exec/code runner wrapper for one sandbox. */
+  public constructor(transport: HttpTransport, sandboxId: string) {
+    this.transport = transport;
+    this.sandboxId = sandboxId;
+  }
+
+  /** Run a shell command in the sandbox. */
+  public exec(input: ExecInput & { stream: true }, options?: RequestOptions): Promise<ReadableStream<Uint8Array>>;
+  public exec(input: ExecInput, options?: RequestOptions): Promise<ExecResult>;
+  public exec(input: ExecInput, options?: RequestOptions): Promise<ExecResult | ReadableStream<Uint8Array>> {
+    if (input.stream === true) {
+      return this.transport.requestJsonStream({
+        endpoint: `/sandboxes/${this.sandboxId}/exec`,
+        method: 'POST',
+        body: input,
+        ...options,
+      });
+    }
+
+    return this.transport.requestJson<ExecResult>({
+      endpoint: `/sandboxes/${this.sandboxId}/exec`,
+      method: 'POST',
+      body: input,
+      ...options,
+    }) as Promise<ExecResult>;
+  }
+
+  /** Run a code snippet in the sandbox. */
+  public runCode(input: CodeInput & { stream: true }, options?: RequestOptions): Promise<ReadableStream<Uint8Array>>;
+  public runCode(input: CodeInput, options?: RequestOptions): Promise<ExecResult>;
+  public runCode(input: CodeInput, options?: RequestOptions): Promise<ExecResult | ReadableStream<Uint8Array>> {
+    if (input.stream === true) {
+      return this.transport.requestJsonStream({
+        endpoint: `/sandboxes/${this.sandboxId}/code`,
+        method: 'POST',
+        body: input,
+        ...options,
+      });
+    }
+
+    return this.transport.requestJson<ExecResult>({
+      endpoint: `/sandboxes/${this.sandboxId}/code`,
+      method: 'POST',
+      body: input,
+      ...options,
+    }) as Promise<ExecResult>;
+  }
+}

package/src/resources/files.ts

@@ -0,0 +1,46 @@
+import type { FileUploadBody } from '../types';
+import type { RequestOptions } from '../transport/http';
+import { HttpTransport } from '../transport/http';
+import { encodeFilePath } from './path';
+
+export class FilesResource {
+  private readonly transport: HttpTransport;
+  private readonly sandboxId: string;
+
+  /** @internal Create the files wrapper for one sandbox. */
+  public constructor(transport: HttpTransport, sandboxId: string) {
+    this.transport = transport;
+    this.sandboxId = sandboxId;
+  }
+
+  /**
+   * Upload file bytes to a path inside the sandbox.
+   * Tip: pass a Buffer/Uint8Array when you can so Content-Length is set automatically.
+   */
+  public async put(path: string, body: FileUploadBody, options?: RequestOptions): Promise<void> {
+    const headers: Record<string, string> = {
+      'content-type': 'application/octet-stream',
+    };
+
+    if (Buffer.isBuffer(body) || body instanceof Uint8Array) {
+      headers['content-length'] = String(body.byteLength);
+    }
+
+    await this.transport.requestBinary({
+      endpoint: `/sandboxes/${this.sandboxId}/files/${encodeFilePath(path)}`,
+      method: 'PUT',
+      body,
+      headers,
+      ...options,
+    });
+  }
+
+  /** Download a file from the sandbox as a stream. */
+  public get(path: string, options?: RequestOptions): Promise<ReadableStream<Uint8Array>> {
+    return this.transport.requestStream({
+      endpoint: `/sandboxes/${this.sandboxId}/files/${encodeFilePath(path)}`,
+      method: 'GET',
+      ...options,
+    });
+  }
+}

package/src/resources/index.ts

@@ -0,0 +1,8 @@
+export { ExecResource } from './exec';
+export { FilesResource } from './files';
+export { SandboxHandle } from './sandbox-handle';
+export { SandboxesResource } from './sandboxes';
+export { ScopedSandboxResource } from './scoped-sandbox';
+export { SnapshotScopeResource, SnapshotsResource } from './snapshots';
+export { StatsResource } from './stats';
+export { VolumesResource } from './volumes';

package/src/resources/path.ts

@@ -0,0 +1,16 @@
+/** Encode a single path segment safely for URL usage. */
+export function encodePathSegment(value: string): string {
+  return encodeURIComponent(value);
+}
+
+/**
+ * Encode a sandbox file path without encoding forward slashes.
+ * Example: `tmp/my file.txt` -> `tmp/my%20file.txt`
+ */
+export function encodeFilePath(path: string): string {
+  return path
+    .split('/')
+    .filter((segment) => segment.length > 0)
+    .map(encodePathSegment)
+    .join('/');
+}

package/src/resources/sandbox-handle.ts

@@ -0,0 +1,215 @@
+import {
+  DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS,
+  DEFAULT_SANDBOX_READY_TIMEOUT_MS,
+} from '../constants';
+import { SandboxStatus } from '../enums';
+import type { RequestOptions } from '../transport/http';
+import type {
+  AckMessage,
+  CodeInput,
+  CreateSandboxResult,
+  CreateSnapshotInput,
+  ExecInput,
+  ExecResult,
+  FileUploadBody,
+  Paginated,
+  Pagination,
+  Sandbox,
+  SandboxRuntimeOptions,
+  Snapshot,
+  Stats,
+  StatsQuery,
+  WaitPreference,
+  WaitUntilReadyOptions,
+} from '../types';
+import { ScopedSandboxResource } from './scoped-sandbox';
+import type { SandboxesResource } from './sandboxes';
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+export class SandboxHandle {
+  private readonly sandboxes: SandboxesResource;
+  private readonly scope: ScopedSandboxResource;
+  private sandboxState: Sandbox | CreateSandboxResult;
+
+  /** Snapshot operations grouped under a dedicated namespace. */
+  public readonly snapshots: {
+    create: (input: CreateSnapshotInput, options?: RequestOptions) => Promise<Snapshot>;
+    list: (query?: Pagination, options?: RequestOptions) => Promise<Paginated<Snapshot>>;
+  };
+
+  /** @internal Create a sandbox handle from create/get responses. */
+  public constructor(sandboxes: SandboxesResource, state: Sandbox | CreateSandboxResult) {
+    this.sandboxes = sandboxes;
+    this.sandboxState = state;
+    this.scope = this.sandboxes.use(state.id);
+
+    this.snapshots = {
+      create: (input, options) => this.createSnapshot(input, options),
+      list: (query = {}, options) => this.listSnapshots(query, options),
+    };
+  }
+
+  /** Current sandbox id. */
+  public get id(): string {
+    return this.sandboxState.id;
+  }
+
+  /** Current cached sandbox status. */
+  public get status(): SandboxStatus {
+    return this.sandboxState.status;
+  }
+
+  /** Current cached sandbox payload. */
+  public get data(): Sandbox | CreateSandboxResult {
+    return this.sandboxState;
+  }
+
+  /** Refresh sandbox details from the API and update local state. */
+  public async refresh(options?: RequestOptions): Promise<Sandbox> {
+    const sandbox = await this.sandboxes.getData(this.id, options);
+    this.sandboxState = sandbox;
+    return sandbox;
+  }
+
+  /** Destroy this sandbox (idempotent). */
+  public async destroy(options?: RequestOptions): Promise<void> {
+    await this.sandboxes.destroy(this.id, options);
+  }
+
+  /** Request pause for this sandbox and refresh cached state. */
+  public async pause(options?: RequestOptions): Promise<AckMessage | undefined> {
+    const response = await this.sandboxes.pause(this.id, options);
+    await this.refresh(options);
+    return response;
+  }
+
+  /** Request resume for this sandbox and refresh cached state. */
+  public async resume(options?: RequestOptions): Promise<AckMessage | undefined> {
+    const response = await this.sandboxes.resume(this.id, options);
+    await this.refresh(options);
+    return response;
+  }
+
+  /**
+   * Poll sandbox status until it becomes `ready`.
+   * Throws on timeout or when `signal` is aborted.
+   */
+  public async waitUntilReady(options: WaitUntilReadyOptions = {}): Promise<Sandbox> {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SANDBOX_READY_TIMEOUT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_SANDBOX_READY_POLL_INTERVAL_MS;
+    const deadline = Date.now() + timeoutMs;
+
+    while (true) {
+      if (options.signal?.aborted) {
+        throw new Error('waitUntilReady aborted by signal');
+      }
+
+      const sandbox = await this.refresh({ signal: options.signal });
+      if (sandbox.status === SandboxStatus.Ready) {
+        return sandbox;
+      }
+
+      if (Date.now() >= deadline) {
+        throw new Error(`Sandbox ${this.id} did not become ready within ${timeoutMs}ms`);
+      }
+
+      await delay(pollIntervalMs);
+    }
+  }
+
+  /**
+   * Run a shell command in this sandbox.
+   * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+   */
+  public exec(input: ExecInput & { stream: true }, options?: SandboxRuntimeOptions): Promise<ReadableStream<Uint8Array>>;
+  public exec(input: ExecInput, options?: SandboxRuntimeOptions): Promise<ExecResult>;
+  public async exec(input: ExecInput, options: SandboxRuntimeOptions = {}): Promise<ExecResult | ReadableStream<Uint8Array>> {
+    await this.ensureReady(options.waitUntilReady);
+    return this.scope.exec(input, options);
+  }
+
+  /**
+   * Run a code snippet in this sandbox.
+   * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+   */
+  public runCode(input: CodeInput & { stream: true }, options?: SandboxRuntimeOptions): Promise<ReadableStream<Uint8Array>>;
+  public runCode(input: CodeInput, options?: SandboxRuntimeOptions): Promise<ExecResult>;
+  public async runCode(input: CodeInput, options: SandboxRuntimeOptions = {}): Promise<ExecResult | ReadableStream<Uint8Array>> {
+    await this.ensureReady(options.waitUntilReady);
+    return this.scope.runCode(input, options);
+  }
+
+  /**
+   * Upload a file into this sandbox.
+   * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+   */
+  public async putFile(path: string, body: FileUploadBody, options: SandboxRuntimeOptions = {}): Promise<void> {
+    await this.ensureReady(options.waitUntilReady);
+    await this.scope.putFile(path, body, options);
+  }
+
+  /**
+   * Download a file from this sandbox.
+   * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+   */
+  public async getFile(path: string, options: SandboxRuntimeOptions = {}): Promise<ReadableStream<Uint8Array>> {
+    await this.ensureReady(options.waitUntilReady);
+    return this.scope.getFile(path, options);
+  }
+
+  /**
+   * Fetch usage stats for this sandbox.
+   * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+   */
+  public async stats(query: StatsQuery = {}, options: SandboxRuntimeOptions = {}): Promise<Stats> {
+    await this.ensureReady(options.waitUntilReady);
+    return this.scope.stats(query, options);
+  }
+
+  /**
+   * Create a snapshot for this sandbox.
+   * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+   */
+  public async createSnapshot(input: CreateSnapshotInput, options: SandboxRuntimeOptions = {}): Promise<Snapshot> {
+    await this.ensureReady(options.waitUntilReady);
+    return this.scope.createSnapshot(input, options);
+  }
+
+  /**
+   * List snapshots for this sandbox.
+   * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+   */
+  public async listSnapshots(query: Pagination = {}, options: SandboxRuntimeOptions = {}): Promise<Paginated<Snapshot>> {
+    await this.ensureReady(options.waitUntilReady);
+    return this.scope.listSnapshots(query, options);
+  }
+
+  private async ensureReady(waitUntilReady: WaitPreference | undefined): Promise<void> {
+    if (this.status === SandboxStatus.Ready) {
+      return;
+    }
+
+    if (waitUntilReady) {
+      if (typeof waitUntilReady === 'object') {
+        await this.waitUntilReady(waitUntilReady);
+        return;
+      }
+
+      await this.waitUntilReady();
+      return;
+    }
+
+    this.assertReady();
+  }
+
+  private assertReady(): void {
+    if (this.status !== SandboxStatus.Ready) {
+      throw new Error(`Sandbox ${this.id} is ${this.status}. Call waitUntilReady() or refresh() before runtime operations.`);
+    }
+  }
+}