@brimble/sandbox 0.1.0 → 0.1.2

package/src/resources/exec.ts

@@ -1,56 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,16 +0,0 @@
-/** 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

@@ -1,215 +0,0 @@
-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.`);
-    }
-  }
-}

package/src/resources/sandboxes.ts

@@ -1,297 +0,0 @@
-import { DEFAULT_PAGE, DEFAULT_PAGE_LIMIT } from '../constants';
-import { VolumeType } from '../enums';
-import type { RequestOptions } from '../transport/http';
-import { HttpTransport } from '../transport/http';
-import { toPaginationQuery } from '../transport/pagination';
-import type {
-  AckMessage,
-  CreateSandboxRequest,
-  CreateSandboxResult,
-  CreateSandboxWithVolumeInput,
-  CreateVolumeInput,
-  Paginated,
-  Sandbox,
-  SandboxReadyRequestOptions,
-  SandboxRegionInput,
-  SandboxRegionsResult,
-  SandboxTemplate,
-  TeamScopedPagination,
-  Volume,
-  WaitPreference,
-} from '../types';
-import { SandboxHandle } from './sandbox-handle';
-import { ScopedSandboxResource } from './scoped-sandbox';
-import { VolumesResource } from './volumes';
-
-export type QuickstartSandboxInput = Omit<CreateSandboxRequest, 'template' | 'persistent' | 'persistentDiskGB'> & {
-  template?: string;
-  persistentDiskGB?: number;
-  waitUntilReady?: WaitPreference;
-};
-
-export class SandboxesResource {
-  private readonly transport: HttpTransport;
-  private readonly volumes: VolumesResource;
-
-  /** @internal Create the sandboxes resource wrapper. */
-  public constructor(transport: HttpTransport) {
-    this.transport = transport;
-    this.volumes = new VolumesResource(transport);
-  }
-
-  /**
-   * Create a new sandbox.
-   * Region is optional; when omitted this SDK picks the first available region.
-   * The sandbox starts asynchronously, so fetch it until `status` is `ready`
-   * before running commands or file operations.
-   */
-  public async create(input: CreateSandboxRequest, options?: RequestOptions): Promise<SandboxHandle> {
-    const region = await this.resolveRegionId(input.region, options);
-    const body: CreateSandboxRequest = {
-      ...input,
-      region,
-    };
-
-    const result = (await this.transport.requestJson<CreateSandboxResult>({
-      endpoint: '/sandboxes',
-      method: 'POST',
-      body,
-      ...options,
-    })) as CreateSandboxResult;
-
-    return new SandboxHandle(this, result);
-  }
-
-  /** Create a sandbox and wait until it is `ready` before returning it. */
-  public async createReady(input: CreateSandboxRequest, options: SandboxReadyRequestOptions = {}): Promise<SandboxHandle> {
-    const sandbox = await this.create(input, options.request);
-    await sandbox.waitUntilReady(options.wait);
-    return sandbox;
-  }
-
-  /**
-   * Create a volume and then create a sandbox attached to that volume.
-   * This is the one-call helper for persistent sandbox workflows.
-   */
-  public async withVolume(input: CreateSandboxWithVolumeInput, options?: RequestOptions): Promise<SandboxHandle> {
-    const region = await this.resolveRegionId(input.sandbox.region ?? input.volume.region, options);
-
-    const volume = await this.volumes.create(
-      {
-        ...input.volume,
-        region,
-        type: VolumeType.Sandbox,
-      },
-      options,
-    );
-
-    return this.create(
-      {
-        ...input.sandbox,
-        region,
-        volumeId: volume.id,
-      },
-      options,
-    );
-  }
-
-  /** Create a sandbox-scoped volume with package-level defaults and validation. */
-  public createVolume(input: CreateVolumeInput, options?: RequestOptions): Promise<Volume> {
-    return this.volumes.create(input, options);
-  }
-
-  /** List your sandboxes with pagination. */
-  public async list(query: TeamScopedPagination = {}, options?: RequestOptions): Promise<Paginated<SandboxHandle>> {
-    const page = await this.listData(query, options);
-
-    return {
-      ...page,
-      data: page.data.map((sandbox) => new SandboxHandle(this, sandbox)),
-    };
-  }
-
-  /** Iterate over all sandbox handles across paginated results. */
-  public async *iterate(query: TeamScopedPagination = {}, options?: RequestOptions): AsyncGenerator<SandboxHandle> {
-    const limit = query.limit ?? DEFAULT_PAGE_LIMIT;
-    let page = query.page ?? DEFAULT_PAGE;
-
-    while (true) {
-      const paginated = await this.list({ ...query, page, limit }, options);
-
-      for (const sandbox of paginated.data) {
-        yield sandbox;
-      }
-
-      if (page >= paginated.totalPages || paginated.data.length === 0) {
-        return;
-      }
-
-      page += 1;
-    }
-  }
-
-  /** Fetch one sandbox handle by id. */
-  public async get(sandboxId: string, options?: RequestOptions): Promise<SandboxHandle> {
-    const sandbox = await this.getData(sandboxId, options);
-    return new SandboxHandle(this, sandbox);
-  }
-
-  /** Fetch one sandbox and wait for `ready` before returning the handle. */
-  public async getReady(sandboxId: string, options: SandboxReadyRequestOptions = {}): Promise<SandboxHandle> {
-    const sandbox = await this.get(sandboxId, options.request);
-    await sandbox.waitUntilReady(options.wait);
-    return sandbox;
-  }
-
-  /** @internal Fetch raw sandbox payload by id. */
-  public getData(sandboxId: string, options?: RequestOptions): Promise<Sandbox> {
-    return this.transport.requestJson<Sandbox>({
-      endpoint: `/sandboxes/${sandboxId}`,
-      method: 'GET',
-      ...options,
-    }) as Promise<Sandbox>;
-  }
-
-  /** @internal Fetch raw paginated sandbox payload. */
-  public listData(query: TeamScopedPagination = {}, options?: RequestOptions): Promise<Paginated<Sandbox>> {
-    const params = toPaginationQuery(query);
-
-    if (query.teamId) {
-      params.set('teamId', query.teamId);
-    }
-
-    return this.transport.requestJson<Paginated<Sandbox>>({
-      endpoint: '/sandboxes',
-      method: 'GET',
-      query: params,
-      ...options,
-    }) as Promise<Paginated<Sandbox>>;
-  }
-
-  /** List regions where sandboxes can be provisioned. */
-  public listRegions(options?: RequestOptions): Promise<SandboxRegionsResult> {
-    return this.transport.requestJson<SandboxRegionsResult>({
-      endpoint: '/sandboxes/regions',
-      method: 'GET',
-      ...options,
-    }) as Promise<SandboxRegionsResult>;
-  }
-
-  /** List sandbox templates available for create operations. */
-  public async listTemplates(options?: RequestOptions): Promise<SandboxTemplate[]> {
-    const payload = await this.transport.requestJson<unknown>({
-      endpoint: '/sandbox/templates',
-      method: 'GET',
-      ...options,
-    });
-
-    if (Array.isArray(payload)) {
-      return payload as SandboxTemplate[];
-    }
-
-    if (payload && typeof payload === 'object' && 'templates' in payload) {
-      const templates = (payload as { templates?: unknown }).templates;
-      if (Array.isArray(templates)) {
-        return templates as SandboxTemplate[];
-      }
-    }
-
-    return [];
-  }
-
-  /** Fetch one template by name from the template catalog. */
-  public async getTemplate(templateName: string, options?: RequestOptions): Promise<SandboxTemplate | undefined> {
-    const templates = await this.listTemplates(options);
-    return templates.find((template) => template.name === templateName);
-  }
-
-  /** Destroy a sandbox (idempotent). */
-  public async destroy(sandboxId: string, options?: RequestOptions): Promise<void> {
-    await this.transport.requestJson({
-      endpoint: `/sandboxes/${sandboxId}`,
-      method: 'DELETE',
-      ...options,
-    });
-  }
-
-  /** Request sandbox pause. */
-  public pause(sandboxId: string, options?: RequestOptions): Promise<AckMessage | undefined> {
-    return this.transport.requestJson<AckMessage>({
-      endpoint: `/sandboxes/${sandboxId}/pause`,
-      method: 'POST',
-      ...options,
-    });
-  }
-
-  /** Request sandbox resume. */
-  public resume(sandboxId: string, options?: RequestOptions): Promise<AckMessage | undefined> {
-    return this.transport.requestJson<AckMessage>({
-      endpoint: `/sandboxes/${sandboxId}/resume`,
-      method: 'POST',
-      ...options,
-    });
-  }
-
-  /** Use runtime operations for a specific sandbox id. */
-  public use(sandboxId: string): ScopedSandboxResource {
-    return new ScopedSandboxResource(this.transport, sandboxId);
-  }
-
-  /** Opinionated Node.js quickstart (persistent sandbox + optional wait). */
-  public async quickstartNode(input: QuickstartSandboxInput = {}, options?: RequestOptions): Promise<SandboxHandle> {
-    return this.quickstart({
-      ...input,
-      template: input.template ?? 'node-22',
-      persistentDiskGB: input.persistentDiskGB ?? 20,
-    }, options);
-  }
-
-  /** Opinionated Python quickstart (persistent sandbox + optional wait). */
-  public async quickstartPython(input: QuickstartSandboxInput = {}, options?: RequestOptions): Promise<SandboxHandle> {
-    return this.quickstart({
-      ...input,
-      template: input.template ?? 'python-3.12',
-      persistentDiskGB: input.persistentDiskGB ?? 20,
-    }, options);
-  }
-
-  private async quickstart(input: QuickstartSandboxInput, options?: RequestOptions): Promise<SandboxHandle> {
-    const { waitUntilReady, persistentDiskGB, ...createInput } = input;
-
-    const sandbox = await this.create(
-      {
-        ...createInput,
-        persistent: true,
-        persistentDiskGB,
-      },
-      options,
-    );
-
-    if (waitUntilReady === false) {
-      return sandbox;
-    }
-
-    if (typeof waitUntilReady === 'object') {
-      await sandbox.waitUntilReady(waitUntilReady);
-      return sandbox;
-    }
-
-    await sandbox.waitUntilReady();
-    return sandbox;
-  }
-
-  private async resolveRegionId(region: SandboxRegionInput | undefined, options?: RequestOptions): Promise<string> {
-    if (region && region !== 'auto') {
-      return region;
-    }
-
-    const { regions } = await this.listRegions(options);
-    const regionId = regions[0]?.id;
-
-    if (!regionId) {
-      throw new Error('No sandbox regions available for this account.');
-    }
-
-    return regionId;
-  }
-}