@brimble/sandbox 0.1.0 → 0.1.1

package/src/enums/code-language.ts

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

package/src/enums/destroy-reason.ts

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

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

package/src/enums/index.ts

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

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

package/src/enums/snapshot-mode.ts

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

package/src/enums/snapshot-status.ts

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

package/src/enums/volume-type.ts

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

package/src/errors/index.ts

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

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

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

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

@@ -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.`);
-    }
-  }
-}