@brimble/sandbox 0.1.0 → 0.1.1

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;
-  }
-}

package/src/resources/scoped-sandbox.ts

@@ -1,65 +0,0 @@
-import { ExecResource } from './exec';
-import { FilesResource } from './files';
-import { SnapshotScopeResource } from './snapshots';
-import { StatsResource } from './stats';
-import { HttpTransport } from '../transport/http';
-import type { CodeInput, CreateSnapshotInput, ExecInput, ExecResult, FileUploadBody, Paginated, Pagination, Snapshot, Stats, StatsQuery } from '../types';
-import type { RequestOptions } from '../transport/http';
-
-export class ScopedSandboxResource {
-  /** Lower-level exec/code runner resource. */
-  public readonly execResource: ExecResource;
-  /** File upload/download resource. */
-  public readonly files: FilesResource;
-  /** Snapshot resource scoped to this sandbox. */
-  public readonly snapshots: SnapshotScopeResource;
-  /** Stats resource scoped to this sandbox. */
-  public readonly statsResource: StatsResource;
-
-  /** @internal Create a sandbox-scoped resource wrapper. */
-  public constructor(transport: HttpTransport, sandboxId: string) {
-    this.execResource = new ExecResource(transport, sandboxId);
-    this.files = new FilesResource(transport, sandboxId);
-    this.snapshots = new SnapshotScopeResource(transport, sandboxId);
-    this.statsResource = new StatsResource(transport, sandboxId);
-  }
-
-  /** Run a shell command in this 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>> {
-    return this.execResource.exec(input, options);
-  }
-
-  /** Run a code snippet in this 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>> {
-    return this.execResource.runCode(input, options);
-  }
-
-  /** Upload bytes to a file path inside this sandbox. */
-  public putFile(path: string, body: FileUploadBody, options?: RequestOptions): Promise<void> {
-    return this.files.put(path, body, options);
-  }
-
-  /** Download file bytes from this sandbox as a stream. */
-  public getFile(path: string, options?: RequestOptions): Promise<ReadableStream<Uint8Array>> {
-    return this.files.get(path, options);
-  }
-
-  /** Fetch CPU, memory, and network stats for this sandbox. */
-  public stats(query: StatsQuery = {}, options?: RequestOptions): Promise<Stats> {
-    return this.statsResource.stats(query, options);
-  }
-
-  /** Create a snapshot for this sandbox. */
-  public createSnapshot(input: CreateSnapshotInput, options?: RequestOptions): Promise<Snapshot> {
-    return this.snapshots.create(input, options);
-  }
-
-  /** List snapshots for this sandbox. */
-  public listSnapshots(query: Pagination = {}, options?: RequestOptions): Promise<Paginated<Snapshot>> {
-    return this.snapshots.list(query, options);
-  }
-}

package/src/resources/snapshots.ts

@@ -1,104 +0,0 @@
-import type { RequestOptions } from '../transport/http';
-import { HttpTransport } from '../transport/http';
-import { toPaginationQuery } from '../transport/pagination';
-import type { CreateSnapshotInput, Paginated, Pagination, Snapshot } from '../types';
-import { DEFAULT_PAGE, DEFAULT_PAGE_LIMIT } from '../constants';
-
-export class SnapshotScopeResource {
-  private readonly transport: HttpTransport;
-  private readonly sandboxId: string;
-
-  /** @internal Create a sandbox-scoped snapshots wrapper. */
-  public constructor(transport: HttpTransport, sandboxId: string) {
-    this.transport = transport;
-    this.sandboxId = sandboxId;
-  }
-
-  /** Create a snapshot for this specific sandbox. */
-  public create(input: CreateSnapshotInput, options?: RequestOptions): Promise<Snapshot> {
-    return this.transport.requestJson<Snapshot>({
-      endpoint: `/sandboxes/${this.sandboxId}/snapshots`,
-      method: 'POST',
-      body: input,
-      ...options,
-    }) as Promise<Snapshot>;
-  }
-
-  /** List snapshots for this specific sandbox. */
-  public list(query: Pagination = {}, options?: RequestOptions): Promise<Paginated<Snapshot>> {
-    return this.transport.requestJson<Paginated<Snapshot>>({
-      endpoint: `/sandboxes/${this.sandboxId}/snapshots`,
-      method: 'GET',
-      query: toPaginationQuery(query),
-      ...options,
-    }) as Promise<Paginated<Snapshot>>;
-  }
-
-  /** Iterate over all snapshots for this sandbox across pages. */
-  public async *iterate(query: Pagination = {}, options?: RequestOptions): AsyncGenerator<Snapshot> {
-    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 snapshot of paginated.data) {
-        yield snapshot;
-      }
-
-      if (page >= paginated.totalPages || paginated.data.length === 0) {
-        return;
-      }
-
-      page += 1;
-    }
-  }
-}
-
-export class SnapshotsResource {
-  private readonly transport: HttpTransport;
-
-  /** @internal Create the global snapshots resource wrapper. */
-  public constructor(transport: HttpTransport) {
-    this.transport = transport;
-  }
-
-  /** List all snapshots owned by the current caller. */
-  public listAll(query: Pagination = {}, options?: RequestOptions): Promise<Paginated<Snapshot>> {
-    return this.transport.requestJson<Paginated<Snapshot>>({
-      endpoint: '/sandboxes/snapshots',
-      method: 'GET',
-      query: toPaginationQuery(query),
-      ...options,
-    }) as Promise<Paginated<Snapshot>>;
-  }
-
-  /** Iterate over all snapshots owned by the caller across pages. */
-  public async *iterateAll(query: Pagination = {}, options?: RequestOptions): AsyncGenerator<Snapshot> {
-    const limit = query.limit ?? DEFAULT_PAGE_LIMIT;
-    let page = query.page ?? DEFAULT_PAGE;
-
-    while (true) {
-      const paginated = await this.listAll({ ...query, page, limit }, options);
-
-      for (const snapshot of paginated.data) {
-        yield snapshot;
-      }
-
-      if (page >= paginated.totalPages || paginated.data.length === 0) {
-        return;
-      }
-
-      page += 1;
-    }
-  }
-
-  /** Delete a snapshot by id. */
-  public async delete(snapshotId: string, options?: RequestOptions): Promise<void> {
-    await this.transport.requestJson({
-      endpoint: `/sandboxes/snapshots/${snapshotId}`,
-      method: 'DELETE',
-      ...options,
-    });
-  }
-}

package/src/resources/stats.ts

@@ -1,30 +0,0 @@
-import type { Stats, StatsQuery } from '../types';
-import type { RequestOptions } from '../transport/http';
-import { HttpTransport } from '../transport/http';
-
-export class StatsResource {
-  private readonly transport: HttpTransport;
-  private readonly sandboxId: string;
-
-  /** @internal Create the stats wrapper for one sandbox. */
-  public constructor(transport: HttpTransport, sandboxId: string) {
-    this.transport = transport;
-    this.sandboxId = sandboxId;
-  }
-
-  /** Fetch sandbox usage stats for a lookback window. */
-  public stats(query: StatsQuery = {}, options?: RequestOptions): Promise<Stats> {
-    const params = new URLSearchParams();
-
-    if (query.hoursAgo !== undefined) {
-      params.set('hoursAgo', String(query.hoursAgo));
-    }
-
-    return this.transport.requestJson<Stats>({
-      endpoint: `/sandboxes/${this.sandboxId}/stats`,
-      method: 'GET',
-      query: params,
-      ...options,
-    }) as Promise<Stats>;
-  }
-}

package/src/resources/volumes.ts

@@ -1,95 +0,0 @@
-import type { RequestOptions } from '../transport/http';
-import { HttpTransport } from '../transport/http';
-import { toPaginationQuery } from '../transport/pagination';
-import { VolumeType } from '../enums';
-import { DEFAULT_PAGE, DEFAULT_PAGE_LIMIT, MIN_VOLUME_SIZE_GB } from '../constants';
-import type { CreateVolumeInput, Paginated, TeamScopedPagination, Volume } from '../types';
-
-export class VolumesResource {
-  private readonly transport: HttpTransport;
-
-  /** @internal Create the volumes resource wrapper. */
-  public constructor(transport: HttpTransport) {
-    this.transport = transport;
-  }
-
-  /** List your volumes with pagination. */
-  public list(query: TeamScopedPagination = {}, options?: RequestOptions): Promise<Paginated<Volume>> {
-    const params = toPaginationQuery(query);
-
-    if (query.teamId) {
-      params.set('teamId', query.teamId);
-    }
-
-    return this.transport.requestJson<Paginated<Volume>>({
-      endpoint: '/volumes',
-      method: 'GET',
-      query: params,
-      ...options,
-    }) as Promise<Paginated<Volume>>;
-  }
-
-  /** Iterate over all volumes across paginated results. */
-  public async *iterate(query: TeamScopedPagination = {}, options?: RequestOptions): AsyncGenerator<Volume> {
-    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 volume of paginated.data) {
-        yield volume;
-      }
-
-      if (page >= paginated.totalPages || paginated.data.length === 0) {
-        return;
-      }
-
-      page += 1;
-    }
-  }
-
-  /**
-   * Create a new volume.
-   * This SDK accepts only `type: "sandbox"` and defaults to it when omitted.
-   */
-  public create(input: CreateVolumeInput, options?: RequestOptions): Promise<Volume> {
-    if (input.type && input.type !== VolumeType.Sandbox) {
-      throw new Error('Only volume type "sandbox" is supported by this package.');
-    }
-
-    if (input.sizeGB < MIN_VOLUME_SIZE_GB) {
-      throw new Error(`Volume size must be at least ${MIN_VOLUME_SIZE_GB}GB.`);
-    }
-
-    const body: CreateVolumeInput = {
-      ...input,
-      type: VolumeType.Sandbox,
-    };
-
-    return this.transport.requestJson<Volume>({
-      endpoint: '/volumes',
-      method: 'POST',
-      body,
-      ...options,
-    }) as Promise<Volume>;
-  }
-
-  /** Fetch one volume by id. */
-  public get(volumeId: string, options?: RequestOptions): Promise<Volume> {
-    return this.transport.requestJson<Volume>({
-      endpoint: `/volumes/${volumeId}`,
-      method: 'GET',
-      ...options,
-    }) as Promise<Volume>;
-  }
-
-  /** Delete a volume by id. */
-  public async delete(volumeId: string, options?: RequestOptions): Promise<void> {
-    await this.transport.requestJson({
-      endpoint: `/volumes/${volumeId}`,
-      method: 'DELETE',
-      ...options,
-    });
-  }
-}

package/src/transport/auth.ts

@@ -1,4 +0,0 @@
-/** Build the header value used by `x-brimble-key`. */
-export function buildApiKeyHeader(apiKey: string): string {
-  return apiKey;
-}