@brimble/sandbox 0.1.0 → 0.1.2

package/src/types/sandbox.ts

@@ -1,103 +0,0 @@
-import { DestroyReason, DestroyTimeout, SandboxStatus, SnapshotMode } from '../enums';
-import type { RequestOptions } from '../transport/http';
-import type { RegionSummary } from './region';
-import type { CreateVolumeInput, Volume } from './volume';
-
-export type SandboxSpecs = {
-  cpu?: number;
-  memory?: number;
-  disk?: number;
-};
-
-export type SandboxRegionInput = string | 'auto';
-
-export type CreateSandboxInput = {
-  name?: string;
-  template?: string;
-  teamId?: string;
-  environmentId?: string;
-  region?: string;
-  specs?: SandboxSpecs;
-  autoDestroy?: boolean;
-  destroyTimeout?: DestroyTimeout;
-  oneShot?: boolean;
-  blockOutbound?: boolean;
-  persistent?: boolean;
-  persistentDiskGB?: number;
-  volumeId?: string;
-  fromSnapshot?: string;
-  snapshotMode?: SnapshotMode;
-  snapshotFrequency?: string;
-};
-
-export type CreateSandboxRequest = Omit<CreateSandboxInput, 'region'> & {
-  region?: SandboxRegionInput;
-};
-
-export type CreateSandboxResult = {
-  id: string;
-  name: string;
-  template: string;
-  status: SandboxStatus;
-  created_at: string;
-  expires_at: string;
-};
-
-export type Sandbox = {
-  id: string;
-  name: string;
-  template: string;
-  status: SandboxStatus;
-  region: RegionSummary | string;
-  specs: SandboxSpecs;
-  team: string | null;
-  project_environment: string | null;
-  auto_destroy: boolean;
-  destroy_timeout: DestroyTimeout | null;
-  one_shot: boolean;
-  block_outbound: boolean;
-  persistent: boolean;
-  persistent_disk_gb: number | null;
-  paused_at: string | null;
-  from_snapshot: string | null;
-  snapshot_mode: SnapshotMode;
-  snapshot_frequency: string | null;
-  created_at: string;
-  last_activity_at: string;
-  expires_at: string;
-  destroyed_at: string | null;
-  destroy_reason: DestroyReason | null;
-};
-
-export type AckMessage = {
-  message: string;
-};
-
-export type WaitUntilReadyOptions = {
-  timeoutMs?: number;
-  pollIntervalMs?: number;
-  signal?: AbortSignal;
-};
-
-export type WaitPreference = boolean | WaitUntilReadyOptions;
-
-export type SandboxRuntimeOptions = RequestOptions & {
-  waitUntilReady?: WaitPreference;
-};
-
-export type SandboxReadyRequestOptions = {
-  request?: RequestOptions;
-  wait?: WaitUntilReadyOptions;
-};
-
-export type CreateSandboxWithVolumeInput = {
-  sandbox: Omit<CreateSandboxRequest, 'volumeId' | 'persistent' | 'persistentDiskGB'>;
-  volume: Omit<CreateVolumeInput, 'region'> & {
-    region?: string;
-  };
-};
-
-export type CreateSandboxWithVolumeResult = {
-  sandbox: CreateSandboxResult;
-  volume: Volume;
-};

package/src/types/snapshot.ts

@@ -1,17 +0,0 @@
-import { SnapshotStatus } from '../enums';
-
-export type CreateSnapshotInput = {
-  name: string;
-};
-
-export type Snapshot = {
-  id: string;
-  sandbox_id: string;
-  name: string;
-  image_tag: string;
-  source_template: string;
-  status: SnapshotStatus;
-  failure_reason: string | null;
-  size_bytes: number | null;
-  created_at: string;
-};

package/src/types/stats.ts

@@ -1,35 +0,0 @@
-export type StatsAverageNumeric = {
-  totalInPercentage: number;
-  size: number;
-};
-
-export type StatsAverageNetwork = {
-  value?: number | null;
-  total?: number | null;
-  totalInPercentage?: number | null;
-  bytesPerSecond?: number | null;
-};
-
-export type StatsTimelinePoint = {
-  date: string;
-  memory: number;
-  cpu: number;
-  network: {
-    bytesPerSecond: number | null;
-  };
-};
-
-export type Stats = {
-  average: {
-    memory: StatsAverageNumeric;
-    cpu: StatsAverageNumeric;
-    network: StatsAverageNetwork;
-  };
-  replicaCount: number;
-  results: StatsTimelinePoint[];
-  responseTime: unknown;
-};
-
-export type StatsQuery = {
-  hoursAgo?: number;
-};

package/src/types/template.ts

@@ -1,5 +0,0 @@
-export type SandboxTemplate = {
-  name: string;
-  display_name: string;
-  description: string;
-};

package/src/types/volume.ts

@@ -1,26 +0,0 @@
-import { VolumeType } from '../enums';
-import type { RegionSummary } from './region';
-
-export type CreateVolumeInput = {
-  name: string;
-  sizeGB: number;
-  region: string;
-  type?: VolumeType;
-  teamId?: string;
-};
-
-export type Volume = {
-  id: string;
-  name: string;
-  type: VolumeType;
-  team: string | null;
-  csi_volume_id: string | null;
-  size: number;
-  region: RegionSummary | null;
-  mount_path: string | null;
-  attached_sandbox_id: string | null;
-  attached_project_id: string | null;
-  last_attached_at: string | null;
-  created_at: string | null;
-  updated_at: string | null;
-};

package/test/integration/sandbox.integration.test.ts

@@ -1,269 +0,0 @@
-import { describe, expect, test } from 'vitest';
-
-import { SandboxClient } from '../../src/client';
-import { MIN_VOLUME_SIZE_GB } from '../../src/constants';
-import { NotFoundError } from '../../src/errors';
-import { CodeLanguage, VolumeType } from '../../src/enums';
-import type { CreateSandboxRequest, ExecStreamFrame, SandboxHandle, SandboxTemplate } from '../../src/types';
-
-const apiKey = process.env.BRIMBLE_SANDBOX_KEY;
-const describeLive = apiKey ? describe : describe.skip;
-
-async function sleep(ms: number): Promise<void> {
-  await new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
-async function readStreamToText(stream: ReadableStream<Uint8Array>): Promise<string> {
-  const reader = stream.getReader();
-  const decoder = new TextDecoder('utf-8');
-  let text = '';
-
-  while (true) {
-    const { value, done } = await reader.read();
-    if (done) {
-      break;
-    }
-
-    if (value) {
-      text += decoder.decode(value, { stream: true });
-    }
-  }
-
-  text += decoder.decode();
-  return text;
-}
-
-function parseSseFrames(payload: string): ExecStreamFrame[] {
-  const frames: ExecStreamFrame[] = [];
-  const blocks = payload.split(/\n\n/);
-
-  for (const block of blocks) {
-    const line = block
-      .split('\n')
-      .map((value) => value.trim())
-      .find((value) => value.startsWith('data:'));
-
-    if (!line) {
-      continue;
-    }
-
-    const json = line.slice('data:'.length).trim();
-    if (!json) {
-      continue;
-    }
-
-    frames.push(JSON.parse(json) as ExecStreamFrame);
-  }
-
-  return frames;
-}
-
-function chooseTemplate(templates: SandboxTemplate[]): string | undefined {
-  const preferred = templates.find((template) => template.name === 'node-22');
-  if (preferred) {
-    return preferred.name;
-  }
-
-  return templates[0]?.name;
-}
-
-function isNotFoundError(error: unknown): boolean {
-  if (error instanceof NotFoundError) {
-    return true;
-  }
-
-  return error instanceof Error && error.name === 'NotFoundError';
-}
-
-async function createReadySandboxWithRetries(
-  client: SandboxClient,
-  input: CreateSandboxRequest,
-  attempts = 3,
-): Promise<SandboxHandle> {
-  let lastError: unknown = null;
-
-  for (let attempt = 1; attempt <= attempts; attempt += 1) {
-    const sandbox = await client.sandboxes.create(input);
-
-    try {
-      await sandbox.waitUntilReady({ timeoutMs: 180_000, pollIntervalMs: 2_000 });
-      return sandbox;
-    } catch (error) {
-      lastError = error;
-
-      try {
-        await sandbox.destroy();
-      } catch {
-        // Ignore cleanup failure for transient provisioner attempts.
-      }
-
-      if (!isNotFoundError(error) || attempt === attempts) {
-        throw error;
-      }
-
-      await sleep(2_000);
-    }
-  }
-
-  throw lastError instanceof Error ? lastError : new Error('Failed to create a ready sandbox after retries.');
-}
-
-describeLive('Sandbox SDK live integration', () => {
-  test('covers stable discovery endpoints', { timeout: 120_000 }, async () => {
-    const client = new SandboxClient({ apiKey, timeoutMs: 60_000 });
-
-    const templates = await client.sandboxes.listTemplates();
-    expect(Array.isArray(templates)).toBe(true);
-    expect(templates.length).toBeGreaterThan(0);
-
-    const selectedTemplate = chooseTemplate(templates);
-    expect(selectedTemplate).toBeTruthy();
-
-    const template = await client.sandboxes.getTemplate(selectedTemplate as string);
-    expect(template?.name).toBe(selectedTemplate);
-
-    const regionsResult = await client.sandboxes.listRegions();
-    expect(regionsResult.regions.length).toBeGreaterThan(0);
-    expect(regionsResult.regions[0]?.id).toBeTruthy();
-
-    const sandboxPage = await client.sandboxes.list({ page: 1, limit: 15 });
-    expect(Array.isArray(sandboxPage.data)).toBe(true);
-    expect(sandboxPage.currentPage).toBe(1);
-  });
-
-  test('covers volume lifecycle without attaching to sandbox', { timeout: 120_000 }, async () => {
-    const client = new SandboxClient({ apiKey, timeoutMs: 60_000 });
-
-    const regionsResult = await client.sandboxes.listRegions();
-    const regionId = regionsResult.regions[0]?.id;
-    expect(regionId).toBeTruthy();
-
-    const volume = await client.volumes.create({
-      name: `sdk-int-${Date.now()}`,
-      sizeGB: MIN_VOLUME_SIZE_GB,
-      region: regionId as string,
-      type: VolumeType.Sandbox,
-    });
-
-    try {
-      expect(volume.type).toBe(VolumeType.Sandbox);
-
-      const fetchedVolume = await client.volumes.get(volume.id);
-      expect(fetchedVolume.id).toBe(volume.id);
-
-      let volumeSeen = false;
-      for await (const iteratedVolume of client.volumes.iterate({ limit: 15 })) {
-        if (iteratedVolume.id === volume.id) {
-          volumeSeen = true;
-          break;
-        }
-      }
-      expect(volumeSeen).toBe(true);
-    } finally {
-      await client.volumes.delete(volume.id);
-    }
-  });
-
-  test('covers sandbox runtime/snapshots lifecycle end-to-end', { timeout: 420_000 }, async () => {
-    const client = new SandboxClient({ apiKey, timeoutMs: 60_000 });
-
-    const templates = await client.sandboxes.listTemplates();
-    const selectedTemplate = chooseTemplate(templates);
-
-    let sandbox: SandboxHandle | null = null;
-
-    try {
-      sandbox = await createReadySandboxWithRetries(
-        client,
-        {
-          ...(selectedTemplate ? { template: selectedTemplate } : {}),
-          persistent: true,
-          persistentDiskGB: MIN_VOLUME_SIZE_GB,
-        },
-        6,
-      );
-
-      const fetchedSandbox = await client.sandboxes.get(sandbox.id);
-      expect(fetchedSandbox.id).toBe(sandbox.id);
-
-      const readySandbox = await client.sandboxes.getReady(sandbox.id, {
-        wait: { timeoutMs: 180_000, pollIntervalMs: 2_000 },
-      });
-      expect(readySandbox.id).toBe(sandbox.id);
-
-      let sandboxSeen = false;
-      for await (const iteratedSandbox of client.sandboxes.iterate({ limit: 15 })) {
-        if (iteratedSandbox.id === sandbox.id) {
-          sandboxSeen = true;
-          break;
-        }
-      }
-      expect(sandboxSeen).toBe(true);
-
-      const execResult = await sandbox.exec({ cmd: 'echo brimble-sdk-test' });
-      expect(execResult.exit_code).toBe(0);
-      expect(execResult.stdout).toContain('brimble-sdk-test');
-
-      const scopedExec = await client.sandboxes.use(sandbox.id).exec({ cmd: 'printf scoped-runtime' });
-      expect(scopedExec.exit_code).toBe(0);
-      expect(scopedExec.stdout).toContain('scoped-runtime');
-
-      const codeResult = await sandbox.runCode({
-        language: CodeLanguage.Node,
-        code: 'console.log("run-code-ok")',
-      });
-      expect(codeResult.exit_code).toBe(0);
-      expect(codeResult.stdout).toContain('run-code-ok');
-
-      const sseStream = await sandbox.exec({
-        cmd: 'for i in 1 2 3; do echo $i; done',
-        stream: true,
-      });
-      const sseText = await readStreamToText(sseStream);
-      const sseFrames = parseSseFrames(sseText);
-      const doneFrame = sseFrames.find((frame) => frame.type === 'done');
-      expect(doneFrame).toBeTruthy();
-      expect(doneFrame && doneFrame.type === 'done' ? doneFrame.exit_code : 1).toBe(0);
-
-      await sandbox.putFile('tmp/sdk-integration.txt', Buffer.from('file-roundtrip-ok', 'utf-8'));
-      const fileStream = await sandbox.getFile('tmp/sdk-integration.txt');
-      const fileContents = await readStreamToText(fileStream);
-      expect(fileContents).toContain('file-roundtrip-ok');
-
-      const stats = await sandbox.stats({ hoursAgo: 1 });
-      expect(stats.replicaCount).toBeGreaterThanOrEqual(0);
-
-      const snapshot = await sandbox.createSnapshot({ name: `sdk-snap-${Date.now()}` });
-      expect(snapshot.id).toBeTruthy();
-
-      const sandboxSnapshots = await sandbox.listSnapshots({ limit: 15, page: 1 });
-      expect(sandboxSnapshots.data.some((item) => item.id === snapshot.id)).toBe(true);
-
-      const nestedSnapshots = await sandbox.snapshots.list({ limit: 15, page: 1 });
-      expect(nestedSnapshots.data.some((item) => item.id === snapshot.id)).toBe(true);
-
-      const allSnapshots = await client.snapshots.listAll({ limit: 15, page: 1 });
-      expect(allSnapshots.data.some((item) => item.id === snapshot.id)).toBe(true);
-
-      try {
-        await client.snapshots.delete(snapshot.id);
-      } catch {
-        // Snapshot deletion can fail when backend image cleanup is still in-flight.
-      }
-
-      await sandbox.pause();
-      await sandbox.resume();
-      await sandbox.waitUntilReady({ timeoutMs: 180_000, pollIntervalMs: 2_000 });
-    } finally {
-      if (sandbox) {
-        try {
-          await client.sandboxes.destroy(sandbox.id);
-        } catch {
-          // Ignore cleanup race failures in integration context.
-        }
-      }
-    }
-  });
-});

package/test/unit/client.test.ts

@@ -1,87 +0,0 @@
-import { afterEach, describe, expect, test, vi } from 'vitest';
-
-import { SandboxClient } from '../../src/client';
-import { SANDBOX_API_KEY_ENV_NAME } from '../../src/constants';
-
-const ORIGINAL_API_KEY = process.env[SANDBOX_API_KEY_ENV_NAME];
-
-function restoreApiKeyEnv(): void {
-  if (ORIGINAL_API_KEY === undefined) {
-    delete process.env[SANDBOX_API_KEY_ENV_NAME];
-    return;
-  }
-
-  process.env[SANDBOX_API_KEY_ENV_NAME] = ORIGINAL_API_KEY;
-}
-
-afterEach(() => {
-  restoreApiKeyEnv();
-});
-
-describe('SandboxClient auth resolution', () => {
-  test('throws when api key is missing in both options and env', () => {
-    delete process.env[SANDBOX_API_KEY_ENV_NAME];
-
-    expect(() => new SandboxClient()).toThrow(
-      `Sandbox API key is required. Pass "apiKey" explicitly or set ${SANDBOX_API_KEY_ENV_NAME} in your environment.`,
-    );
-  });
-
-  test('uses BRIMBLE_SANDBOX_KEY when constructor apiKey is not provided', async () => {
-    process.env[SANDBOX_API_KEY_ENV_NAME] = 'env-test-key';
-
-    let seenAuthHeader: string | null = null;
-
-    const fetchImpl = vi.fn(async (_url: URL | RequestInfo, init?: RequestInit) => {
-      const headers = new Headers(init?.headers);
-      seenAuthHeader = headers.get('x-brimble-key');
-
-      return new Response(
-        JSON.stringify({
-          message: 'ok',
-          data: { regions: [] },
-        }),
-        {
-          status: 200,
-          headers: {
-            'content-type': 'application/json',
-          },
-        },
-      );
-    }) as typeof fetch;
-
-    const client = new SandboxClient({ fetchImpl });
-    await client.sandboxes.listRegions();
-
-    expect(seenAuthHeader).toBe('env-test-key');
-  });
-
-  test('prefers explicit apiKey over BRIMBLE_SANDBOX_KEY', async () => {
-    process.env[SANDBOX_API_KEY_ENV_NAME] = 'env-test-key';
-
-    let seenAuthHeader: string | null = null;
-
-    const fetchImpl = vi.fn(async (_url: URL | RequestInfo, init?: RequestInit) => {
-      const headers = new Headers(init?.headers);
-      seenAuthHeader = headers.get('x-brimble-key');
-
-      return new Response(
-        JSON.stringify({
-          message: 'ok',
-          data: { regions: [] },
-        }),
-        {
-          status: 200,
-          headers: {
-            'content-type': 'application/json',
-          },
-        },
-      );
-    }) as typeof fetch;
-
-    const client = new SandboxClient({ apiKey: 'explicit-key', fetchImpl });
-    await client.sandboxes.listRegions();
-
-    expect(seenAuthHeader).toBe('explicit-key');
-  });
-});

package/test/unit/sandboxes.test.ts

@@ -1,69 +0,0 @@
-import { describe, expect, test, vi } from 'vitest';
-
-import { SandboxClient } from '../../src/client';
-
-describe('SandboxesResource templates helpers', () => {
-  test('listTemplates handles wrapped data.templates payload', async () => {
-    const fetchImpl = vi.fn(async () =>
-      new Response(
-        JSON.stringify({
-          message: 'Templates fetched',
-          data: {
-            templates: [
-              {
-                name: 'node-22',
-                display_name: 'Node.js 22',
-                description: 'Node runtime',
-              },
-            ],
-          },
-        }),
-        {
-          status: 200,
-          headers: { 'content-type': 'application/json' },
-        },
-      ),
-    ) as typeof fetch;
-
-    const client = new SandboxClient({
-      apiKey: 'test-key',
-      fetchImpl,
-    });
-
-    const templates = await client.sandboxes.listTemplates();
-    expect(templates.length).toBe(1);
-    expect(templates[0]?.name).toBe('node-22');
-  });
-
-  test('getTemplate finds template by name', async () => {
-    const fetchImpl = vi.fn(async () =>
-      new Response(
-        JSON.stringify({
-          message: 'Templates fetched',
-          data: {
-            templates: [
-              {
-                name: 'python-3.12',
-                display_name: 'Python 3.12',
-                description: 'Python runtime',
-              },
-            ],
-          },
-        }),
-        {
-          status: 200,
-          headers: { 'content-type': 'application/json' },
-        },
-      ),
-    ) as typeof fetch;
-
-    const client = new SandboxClient({
-      apiKey: 'test-key',
-      fetchImpl,
-    });
-
-    const template = await client.sandboxes.getTemplate('python-3.12');
-    expect(template?.name).toBe('python-3.12');
-  });
-});
-