@brimble/sandbox 0.1.0

package/dist/src/resources/exec.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecResource = void 0;
+class ExecResource {
+    transport;
+    sandboxId;
+    /** @internal Create the exec/code runner wrapper for one sandbox. */
+    constructor(transport, sandboxId) {
+        this.transport = transport;
+        this.sandboxId = sandboxId;
+    }
+    exec(input, options) {
+        if (input.stream === true) {
+            return this.transport.requestJsonStream({
+                endpoint: `/sandboxes/${this.sandboxId}/exec`,
+                method: 'POST',
+                body: input,
+                ...options,
+            });
+        }
+        return this.transport.requestJson({
+            endpoint: `/sandboxes/${this.sandboxId}/exec`,
+            method: 'POST',
+            body: input,
+            ...options,
+        });
+    }
+    runCode(input, options) {
+        if (input.stream === true) {
+            return this.transport.requestJsonStream({
+                endpoint: `/sandboxes/${this.sandboxId}/code`,
+                method: 'POST',
+                body: input,
+                ...options,
+            });
+        }
+        return this.transport.requestJson({
+            endpoint: `/sandboxes/${this.sandboxId}/code`,
+            method: 'POST',
+            body: input,
+            ...options,
+        });
+    }
+}
+exports.ExecResource = ExecResource;

package/dist/src/resources/files.d.ts

@@ -0,0 +1,16 @@
+import type { FileUploadBody } from '../types';
+import type { RequestOptions } from '../transport/http';
+import { HttpTransport } from '../transport/http';
+export declare class FilesResource {
+    private readonly transport;
+    private readonly sandboxId;
+    /** @internal Create the files wrapper for one sandbox. */
+    constructor(transport: HttpTransport, sandboxId: string);
+    /**
+     * Upload file bytes to a path inside the sandbox.
+     * Tip: pass a Buffer/Uint8Array when you can so Content-Length is set automatically.
+     */
+    put(path: string, body: FileUploadBody, options?: RequestOptions): Promise<void>;
+    /** Download a file from the sandbox as a stream. */
+    get(path: string, options?: RequestOptions): Promise<ReadableStream<Uint8Array>>;
+}

package/dist/src/resources/files.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilesResource = void 0;
+const path_1 = require("./path");
+class FilesResource {
+    transport;
+    sandboxId;
+    /** @internal Create the files wrapper for one sandbox. */
+    constructor(transport, sandboxId) {
+        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.
+     */
+    async put(path, body, options) {
+        const headers = {
+            '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/${(0, path_1.encodeFilePath)(path)}`,
+            method: 'PUT',
+            body,
+            headers,
+            ...options,
+        });
+    }
+    /** Download a file from the sandbox as a stream. */
+    get(path, options) {
+        return this.transport.requestStream({
+            endpoint: `/sandboxes/${this.sandboxId}/files/${(0, path_1.encodeFilePath)(path)}`,
+            method: 'GET',
+            ...options,
+        });
+    }
+}
+exports.FilesResource = FilesResource;

package/dist/src/resources/index.d.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/dist/src/resources/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VolumesResource = exports.StatsResource = exports.SnapshotsResource = exports.SnapshotScopeResource = exports.ScopedSandboxResource = exports.SandboxesResource = exports.SandboxHandle = exports.FilesResource = exports.ExecResource = void 0;
+var exec_1 = require("./exec");
+Object.defineProperty(exports, "ExecResource", { enumerable: true, get: function () { return exec_1.ExecResource; } });
+var files_1 = require("./files");
+Object.defineProperty(exports, "FilesResource", { enumerable: true, get: function () { return files_1.FilesResource; } });
+var sandbox_handle_1 = require("./sandbox-handle");
+Object.defineProperty(exports, "SandboxHandle", { enumerable: true, get: function () { return sandbox_handle_1.SandboxHandle; } });
+var sandboxes_1 = require("./sandboxes");
+Object.defineProperty(exports, "SandboxesResource", { enumerable: true, get: function () { return sandboxes_1.SandboxesResource; } });
+var scoped_sandbox_1 = require("./scoped-sandbox");
+Object.defineProperty(exports, "ScopedSandboxResource", { enumerable: true, get: function () { return scoped_sandbox_1.ScopedSandboxResource; } });
+var snapshots_1 = require("./snapshots");
+Object.defineProperty(exports, "SnapshotScopeResource", { enumerable: true, get: function () { return snapshots_1.SnapshotScopeResource; } });
+Object.defineProperty(exports, "SnapshotsResource", { enumerable: true, get: function () { return snapshots_1.SnapshotsResource; } });
+var stats_1 = require("./stats");
+Object.defineProperty(exports, "StatsResource", { enumerable: true, get: function () { return stats_1.StatsResource; } });
+var volumes_1 = require("./volumes");
+Object.defineProperty(exports, "VolumesResource", { enumerable: true, get: function () { return volumes_1.VolumesResource; } });

package/dist/src/resources/path.d.ts

@@ -0,0 +1,7 @@
+/** Encode a single path segment safely for URL usage. */
+export declare function encodePathSegment(value: string): string;
+/**
+ * Encode a sandbox file path without encoding forward slashes.
+ * Example: `tmp/my file.txt` -> `tmp/my%20file.txt`
+ */
+export declare function encodeFilePath(path: string): string;

package/dist/src/resources/path.js

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

package/dist/src/resources/sandbox-handle.d.ts

@@ -0,0 +1,78 @@
+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, WaitUntilReadyOptions } from '../types';
+import type { SandboxesResource } from './sandboxes';
+export declare class SandboxHandle {
+    private readonly sandboxes;
+    private readonly scope;
+    private sandboxState;
+    /** Snapshot operations grouped under a dedicated namespace. */
+    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. */
+    constructor(sandboxes: SandboxesResource, state: Sandbox | CreateSandboxResult);
+    /** Current sandbox id. */
+    get id(): string;
+    /** Current cached sandbox status. */
+    get status(): SandboxStatus;
+    /** Current cached sandbox payload. */
+    get data(): Sandbox | CreateSandboxResult;
+    /** Refresh sandbox details from the API and update local state. */
+    refresh(options?: RequestOptions): Promise<Sandbox>;
+    /** Destroy this sandbox (idempotent). */
+    destroy(options?: RequestOptions): Promise<void>;
+    /** Request pause for this sandbox and refresh cached state. */
+    pause(options?: RequestOptions): Promise<AckMessage | undefined>;
+    /** Request resume for this sandbox and refresh cached state. */
+    resume(options?: RequestOptions): Promise<AckMessage | undefined>;
+    /**
+     * Poll sandbox status until it becomes `ready`.
+     * Throws on timeout or when `signal` is aborted.
+     */
+    waitUntilReady(options?: WaitUntilReadyOptions): Promise<Sandbox>;
+    /**
+     * Run a shell command in this sandbox.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    exec(input: ExecInput & {
+        stream: true;
+    }, options?: SandboxRuntimeOptions): Promise<ReadableStream<Uint8Array>>;
+    exec(input: ExecInput, options?: SandboxRuntimeOptions): Promise<ExecResult>;
+    /**
+     * Run a code snippet in this sandbox.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    runCode(input: CodeInput & {
+        stream: true;
+    }, options?: SandboxRuntimeOptions): Promise<ReadableStream<Uint8Array>>;
+    runCode(input: CodeInput, options?: SandboxRuntimeOptions): Promise<ExecResult>;
+    /**
+     * Upload a file into this sandbox.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    putFile(path: string, body: FileUploadBody, options?: SandboxRuntimeOptions): Promise<void>;
+    /**
+     * Download a file from this sandbox.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    getFile(path: string, options?: SandboxRuntimeOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Fetch usage stats for this sandbox.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    stats(query?: StatsQuery, options?: SandboxRuntimeOptions): Promise<Stats>;
+    /**
+     * Create a snapshot for this sandbox.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    createSnapshot(input: CreateSnapshotInput, options?: SandboxRuntimeOptions): Promise<Snapshot>;
+    /**
+     * List snapshots for this sandbox.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    listSnapshots(query?: Pagination, options?: SandboxRuntimeOptions): Promise<Paginated<Snapshot>>;
+    private ensureReady;
+    private assertReady;
+}

package/dist/src/resources/sandbox-handle.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxHandle = void 0;
+const constants_1 = require("../constants");
+const enums_1 = require("../enums");
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+class SandboxHandle {
+    sandboxes;
+    scope;
+    sandboxState;
+    /** Snapshot operations grouped under a dedicated namespace. */
+    snapshots;
+    /** @internal Create a sandbox handle from create/get responses. */
+    constructor(sandboxes, state) {
+        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. */
+    get id() {
+        return this.sandboxState.id;
+    }
+    /** Current cached sandbox status. */
+    get status() {
+        return this.sandboxState.status;
+    }
+    /** Current cached sandbox payload. */
+    get data() {
+        return this.sandboxState;
+    }
+    /** Refresh sandbox details from the API and update local state. */
+    async refresh(options) {
+        const sandbox = await this.sandboxes.getData(this.id, options);
+        this.sandboxState = sandbox;
+        return sandbox;
+    }
+    /** Destroy this sandbox (idempotent). */
+    async destroy(options) {
+        await this.sandboxes.destroy(this.id, options);
+    }
+    /** Request pause for this sandbox and refresh cached state. */
+    async pause(options) {
+        const response = await this.sandboxes.pause(this.id, options);
+        await this.refresh(options);
+        return response;
+    }
+    /** Request resume for this sandbox and refresh cached state. */
+    async resume(options) {
+        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.
+     */
+    async waitUntilReady(options = {}) {
+        const timeoutMs = options.timeoutMs ?? constants_1.DEFAULT_SANDBOX_READY_TIMEOUT_MS;
+        const pollIntervalMs = options.pollIntervalMs ?? constants_1.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 === enums_1.SandboxStatus.Ready) {
+                return sandbox;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Sandbox ${this.id} did not become ready within ${timeoutMs}ms`);
+            }
+            await delay(pollIntervalMs);
+        }
+    }
+    async exec(input, options = {}) {
+        await this.ensureReady(options.waitUntilReady);
+        return this.scope.exec(input, options);
+    }
+    async runCode(input, options = {}) {
+        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.
+     */
+    async putFile(path, body, options = {}) {
+        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.
+     */
+    async getFile(path, options = {}) {
+        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.
+     */
+    async stats(query = {}, options = {}) {
+        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.
+     */
+    async createSnapshot(input, options = {}) {
+        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.
+     */
+    async listSnapshots(query = {}, options = {}) {
+        await this.ensureReady(options.waitUntilReady);
+        return this.scope.listSnapshots(query, options);
+    }
+    async ensureReady(waitUntilReady) {
+        if (this.status === enums_1.SandboxStatus.Ready) {
+            return;
+        }
+        if (waitUntilReady) {
+            if (typeof waitUntilReady === 'object') {
+                await this.waitUntilReady(waitUntilReady);
+                return;
+            }
+            await this.waitUntilReady();
+            return;
+        }
+        this.assertReady();
+    }
+    assertReady() {
+        if (this.status !== enums_1.SandboxStatus.Ready) {
+            throw new Error(`Sandbox ${this.id} is ${this.status}. Call waitUntilReady() or refresh() before runtime operations.`);
+        }
+    }
+}
+exports.SandboxHandle = SandboxHandle;

package/dist/src/resources/sandboxes.d.ts

@@ -0,0 +1,64 @@
+import type { RequestOptions } from '../transport/http';
+import { HttpTransport } from '../transport/http';
+import type { AckMessage, CreateSandboxRequest, CreateSandboxWithVolumeInput, CreateVolumeInput, Paginated, Sandbox, SandboxReadyRequestOptions, SandboxRegionsResult, SandboxTemplate, TeamScopedPagination, Volume, WaitPreference } from '../types';
+import { SandboxHandle } from './sandbox-handle';
+import { ScopedSandboxResource } from './scoped-sandbox';
+export type QuickstartSandboxInput = Omit<CreateSandboxRequest, 'template' | 'persistent' | 'persistentDiskGB'> & {
+    template?: string;
+    persistentDiskGB?: number;
+    waitUntilReady?: WaitPreference;
+};
+export declare class SandboxesResource {
+    private readonly transport;
+    private readonly volumes;
+    /** @internal Create the sandboxes resource wrapper. */
+    constructor(transport: HttpTransport);
+    /**
+     * 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.
+     */
+    create(input: CreateSandboxRequest, options?: RequestOptions): Promise<SandboxHandle>;
+    /** Create a sandbox and wait until it is `ready` before returning it. */
+    createReady(input: CreateSandboxRequest, options?: SandboxReadyRequestOptions): Promise<SandboxHandle>;
+    /**
+     * Create a volume and then create a sandbox attached to that volume.
+     * This is the one-call helper for persistent sandbox workflows.
+     */
+    withVolume(input: CreateSandboxWithVolumeInput, options?: RequestOptions): Promise<SandboxHandle>;
+    /** Create a sandbox-scoped volume with package-level defaults and validation. */
+    createVolume(input: CreateVolumeInput, options?: RequestOptions): Promise<Volume>;
+    /** List your sandboxes with pagination. */
+    list(query?: TeamScopedPagination, options?: RequestOptions): Promise<Paginated<SandboxHandle>>;
+    /** Iterate over all sandbox handles across paginated results. */
+    iterate(query?: TeamScopedPagination, options?: RequestOptions): AsyncGenerator<SandboxHandle>;
+    /** Fetch one sandbox handle by id. */
+    get(sandboxId: string, options?: RequestOptions): Promise<SandboxHandle>;
+    /** Fetch one sandbox and wait for `ready` before returning the handle. */
+    getReady(sandboxId: string, options?: SandboxReadyRequestOptions): Promise<SandboxHandle>;
+    /** @internal Fetch raw sandbox payload by id. */
+    getData(sandboxId: string, options?: RequestOptions): Promise<Sandbox>;
+    /** @internal Fetch raw paginated sandbox payload. */
+    listData(query?: TeamScopedPagination, options?: RequestOptions): Promise<Paginated<Sandbox>>;
+    /** List regions where sandboxes can be provisioned. */
+    listRegions(options?: RequestOptions): Promise<SandboxRegionsResult>;
+    /** List sandbox templates available for create operations. */
+    listTemplates(options?: RequestOptions): Promise<SandboxTemplate[]>;
+    /** Fetch one template by name from the template catalog. */
+    getTemplate(templateName: string, options?: RequestOptions): Promise<SandboxTemplate | undefined>;
+    /** Destroy a sandbox (idempotent). */
+    destroy(sandboxId: string, options?: RequestOptions): Promise<void>;
+    /** Request sandbox pause. */
+    pause(sandboxId: string, options?: RequestOptions): Promise<AckMessage | undefined>;
+    /** Request sandbox resume. */
+    resume(sandboxId: string, options?: RequestOptions): Promise<AckMessage | undefined>;
+    /** Use runtime operations for a specific sandbox id. */
+    use(sandboxId: string): ScopedSandboxResource;
+    /** Opinionated Node.js quickstart (persistent sandbox + optional wait). */
+    quickstartNode(input?: QuickstartSandboxInput, options?: RequestOptions): Promise<SandboxHandle>;
+    /** Opinionated Python quickstart (persistent sandbox + optional wait). */
+    quickstartPython(input?: QuickstartSandboxInput, options?: RequestOptions): Promise<SandboxHandle>;
+    private quickstart;
+    private resolveRegionId;
+}