@brimble/sandbox 0.1.1 → 0.1.3

package/README.md

@@ -24,9 +24,9 @@ BRIMBLE_SANDBOX_KEY=your_key_here npm run test:all
 ## Quickstart
 
 ```ts
-import { CodeLanguage, SandboxClient } from '@brimble/sandbox';
+import { CodeLanguage, Sandbox } from '@brimble/sandbox';
 
-const client = new SandboxClient();
+const client = new Sandbox();
 
 const sandbox = await client.sandboxes.createReady({
   template: 'node-22',
@@ -37,6 +37,10 @@ const sandbox = await client.sandboxes.createReady({
 await sandbox.exec({ cmd: 'node -v' });
 
 await sandbox.putFile('tmp/notes.txt', Buffer.from('hello sandbox'));
+await sandbox.putFiles([
+  { path: '/tmp/hello.txt', body: 'hello from batch' },
+  { path: '/tmp/config.json', body: JSON.stringify({ mode: 'dev' }) },
+]);
 const stream = await sandbox.getFile('tmp/notes.txt');
 
 await sandbox.runCode({
@@ -98,7 +102,7 @@ Use `client.sandboxes.create({ ..., volumeId })` or `client.sandboxes.withVolume
 ## Retry, timeouts, and idempotency
 
 ```ts
-const client = new SandboxClient({
+const client = new Sandbox({
   timeoutMs: 30_000,
   retry: {
     maxAttempts: 3,
@@ -120,9 +124,9 @@ If `region` is omitted, the SDK resolves the first available sandbox region auto
 - `client.sandboxes`
   - `create`, `createReady`, `withVolume`, `list`, `iterate`, `get`, `getReady`, `listRegions`, `listTemplates`, `getTemplate`, `destroy`, `pause`, `resume`, `quickstartNode`, `quickstartPython`, `use`
 - `sandbox` handle (returned from `create/get/list`)
-  - `waitUntilReady`, `refresh`, `destroy`, `pause`, `resume`, `exec`, `runCode`, `putFile`, `getFile`, `stats`, `createSnapshot`, `listSnapshots`, `snapshots.create`, `snapshots.list`
+  - `waitUntilReady`, `refresh`, `destroy`, `pause`, `resume`, `exec`, `runCode`, `putFile`, `putFiles`, `getFile`, `stats`, `createSnapshot`, `listSnapshots`, `snapshots.create`, `snapshots.list`
 - `client.sandboxes.use(id)`
-  - `exec`, `runCode`, `putFile`, `getFile`, `stats`, `createSnapshot`, `listSnapshots`
+  - `exec`, `runCode`, `putFile`, `putFiles`, `getFile`, `stats`, `createSnapshot`, `listSnapshots`
 - `client.snapshots`
   - `listAll`, `iterateAll`, `delete`
 - `client.volumes`

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@brimble/sandbox",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "description": "TypeScript SDK for the Brimble Sandbox API",
     "main": "dist/src/index.js",
     "types": "dist/src/index.d.ts",

package/dist/src/client.d.ts

@@ -1,13 +1,13 @@
 import { SandboxesResource, SnapshotsResource, VolumesResource } from './resources';
 import type { RetryOptions } from './transport/http';
-export type SandboxClientOptions = {
+export type SandboxOptions = {
     apiKey?: string;
     baseUrl?: string;
     timeoutMs?: number;
     retry?: RetryOptions;
     fetchImpl?: typeof fetch;
 };
-export declare class SandboxClient {
+export declare class Sandbox {
     /** Access sandbox lifecycle and per-sandbox scoped operations. */
     readonly sandboxes: SandboxesResource;
     /** Access account-level snapshot operations. */
@@ -19,5 +19,5 @@ export declare class SandboxClient {
      * Creates a client instance for the Brimble Sandbox API.
      * Pass `apiKey` directly or set `BRIMBLE_SANDBOX_KEY` in your environment.
      */
-    constructor(options?: SandboxClientOptions);
+    constructor(options?: SandboxOptions);
 }

package/dist/src/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SandboxClient = void 0;
+exports.Sandbox = void 0;
 const constants_1 = require("./constants");
 const resources_1 = require("./resources");
 const http_1 = require("./transport/http");
@@ -18,7 +18,7 @@ function resolveApiKey(options) {
     }
     throw new Error(`Sandbox API key is required. Pass "apiKey" explicitly or set ${constants_1.SANDBOX_API_KEY_ENV_NAME} in your environment.`);
 }
-class SandboxClient {
+class Sandbox {
     /** Access sandbox lifecycle and per-sandbox scoped operations. */
     sandboxes;
     /** Access account-level snapshot operations. */
@@ -43,4 +43,4 @@ class SandboxClient {
         this.volumes = new resources_1.VolumesResource(this.transport);
     }
 }
-exports.SandboxClient = SandboxClient;
+exports.Sandbox = Sandbox;

package/dist/src/index.d.ts

@@ -1,10 +1,10 @@
 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 { Sandbox } from './client';
+export type { SandboxOptions } 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 { AckMessage, CodeInput, CreateSandboxInput, CreateSandboxResult, CreateSnapshotInput, CreateVolumeInput, ExecInput, ExecResult, ExecStreamFrame, FileUploadBody, Paginated, Pagination, RegionSummary, SandboxRegion, SandboxRegionsResult, Sandbox as SandboxData, 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/dist/src/index.js

@@ -1,6 +1,6 @@
 "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 = exports.VolumeType = exports.SnapshotStatus = exports.SnapshotMode = exports.SandboxStatus = exports.DestroyTimeout = exports.DestroyReason = exports.CodeLanguage = exports.ValidationError = exports.SandboxApiError = exports.RateLimitError = exports.NotFoundError = exports.AuthError = exports.SandboxClient = exports.SANDBOX_API_KEY_ENV_NAME = exports.MAX_PAGE_LIMIT = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_RETRY_STATUSES = exports.DEFAULT_RETRY_MAX_DELAY_MS = exports.DEFAULT_RETRY_MAX_ATTEMPTS = exports.DEFAULT_RETRY_BASE_DELAY_MS = exports.DEFAULT_PAGE_LIMIT = exports.DEFAULT_PAGE = exports.DEFAULT_BASE_URL = void 0;
+exports.VolumesResource = exports.StatsResource = exports.SnapshotsResource = exports.SnapshotScopeResource = exports.ScopedSandboxResource = exports.SandboxesResource = exports.SandboxHandle = exports.FilesResource = exports.ExecResource = exports.VolumeType = exports.SnapshotStatus = exports.SnapshotMode = exports.SandboxStatus = exports.DestroyTimeout = exports.DestroyReason = exports.CodeLanguage = exports.ValidationError = exports.SandboxApiError = exports.RateLimitError = exports.NotFoundError = exports.AuthError = exports.Sandbox = exports.SANDBOX_API_KEY_ENV_NAME = exports.MAX_PAGE_LIMIT = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_RETRY_STATUSES = exports.DEFAULT_RETRY_MAX_DELAY_MS = exports.DEFAULT_RETRY_MAX_ATTEMPTS = exports.DEFAULT_RETRY_BASE_DELAY_MS = exports.DEFAULT_PAGE_LIMIT = exports.DEFAULT_PAGE = exports.DEFAULT_BASE_URL = void 0;
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return constants_1.DEFAULT_BASE_URL; } });
 Object.defineProperty(exports, "DEFAULT_PAGE", { enumerable: true, get: function () { return constants_1.DEFAULT_PAGE; } });
@@ -13,7 +13,7 @@ Object.defineProperty(exports, "DEFAULT_TIMEOUT_MS", { enumerable: true, get: fu
 Object.defineProperty(exports, "MAX_PAGE_LIMIT", { enumerable: true, get: function () { return constants_1.MAX_PAGE_LIMIT; } });
 Object.defineProperty(exports, "SANDBOX_API_KEY_ENV_NAME", { enumerable: true, get: function () { return constants_1.SANDBOX_API_KEY_ENV_NAME; } });
 var client_1 = require("./client");
-Object.defineProperty(exports, "SandboxClient", { enumerable: true, get: function () { return client_1.SandboxClient; } });
+Object.defineProperty(exports, "Sandbox", { enumerable: true, get: function () { return client_1.Sandbox; } });
 var errors_1 = require("./errors");
 Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return errors_1.AuthError; } });
 Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_1.NotFoundError; } });

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

@@ -1,4 +1,4 @@
-import type { FileUploadBody } from '../types';
+import type { BatchFileUploadInput, BatchFileUploadResponse, FileUploadBody } from '../types';
 import type { RequestOptions } from '../transport/http';
 import { HttpTransport } from '../transport/http';
 export declare class FilesResource {
@@ -13,4 +13,9 @@ export declare class FilesResource {
     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>>;
+    /**
+     * Upload multiple files in one request using base64 payloads.
+     * Best for small/medium known files (max 100 per call).
+     */
+    putFiles(files: BatchFileUploadInput[], options?: RequestOptions): Promise<BatchFileUploadResponse>;
 }

package/dist/src/resources/files.js

@@ -37,5 +37,41 @@ class FilesResource {
             ...options,
         });
     }
+    /**
+     * Upload multiple files in one request using base64 payloads.
+     * Best for small/medium known files (max 100 per call).
+     */
+    async putFiles(files, options) {
+        if (files.length === 0) {
+            throw new Error('putFiles requires at least one file.');
+        }
+        if (files.length > 100) {
+            throw new Error('putFiles supports at most 100 files per request.');
+        }
+        const response = await this.transport.requestJson({
+            endpoint: `/sandboxes/${this.sandboxId}/files/batch`,
+            method: 'POST',
+            body: {
+                files: files.map((file) => ({
+                    path: normalizeBatchPath(file.path),
+                    content_base64: encodeBatchBody(file.body),
+                })),
+            },
+            ...options,
+        });
+        if (!response) {
+            throw new Error('Batch upload returned an empty response.');
+        }
+        return response;
+    }
 }
 exports.FilesResource = FilesResource;
+function normalizeBatchPath(path) {
+    return path.startsWith('/') ? path : `/${path}`;
+}
+function encodeBatchBody(body) {
+    if (typeof body === 'string') {
+        return Buffer.from(body, 'utf-8').toString('base64');
+    }
+    return Buffer.from(body).toString('base64');
+}

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

@@ -1,6 +1,6 @@
 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 { AckMessage, BatchFileUploadInput, BatchFileUploadResponse, 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;
@@ -58,6 +58,11 @@ export declare class SandboxHandle {
      * By default this throws when not ready; set `waitUntilReady` to auto-wait.
      */
     getFile(path: string, options?: SandboxRuntimeOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Upload multiple files in one call.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    putFiles(files: BatchFileUploadInput[], options?: SandboxRuntimeOptions): Promise<BatchFileUploadResponse>;
     /**
      * Fetch usage stats for this sandbox.
      * By default this throws when not ready; set `waitUntilReady` to auto-wait.

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

@@ -104,6 +104,14 @@ class SandboxHandle {
         await this.ensureReady(options.waitUntilReady);
         return this.scope.getFile(path, options);
     }
+    /**
+     * Upload multiple files in one call.
+     * By default this throws when not ready; set `waitUntilReady` to auto-wait.
+     */
+    async putFiles(files, options = {}) {
+        await this.ensureReady(options.waitUntilReady);
+        return this.scope.putFiles(files, options);
+    }
     /**
      * Fetch usage stats for this sandbox.
      * By default this throws when not ready; set `waitUntilReady` to auto-wait.

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

@@ -3,9 +3,11 @@ 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 { BatchFileUploadInput, BatchFileUploadResponse, CodeInput, CreateSnapshotInput, ExecInput, ExecResult, FileUploadBody, Paginated, Pagination, Snapshot, Stats, StatsQuery } from '../types';
 import type { RequestOptions } from '../transport/http';
 export declare class ScopedSandboxResource {
+    private readonly transport;
+    private readonly sandboxId;
     /** Lower-level exec/code runner resource. */
     readonly execResource: ExecResource;
     /** File upload/download resource. */
@@ -16,6 +18,8 @@ export declare class ScopedSandboxResource {
     readonly statsResource: StatsResource;
     /** @internal Create a sandbox-scoped resource wrapper. */
     constructor(transport: HttpTransport, sandboxId: string);
+    /** Destroy this sandbox. */
+    destroy(options?: RequestOptions): Promise<void>;
     /** Run a shell command in this sandbox. */
     exec(input: ExecInput & {
         stream: true;
@@ -30,6 +34,8 @@ export declare class ScopedSandboxResource {
     putFile(path: string, body: FileUploadBody, options?: RequestOptions): Promise<void>;
     /** Download file bytes from this sandbox as a stream. */
     getFile(path: string, options?: RequestOptions): Promise<ReadableStream<Uint8Array>>;
+    /** Upload multiple files to this sandbox in one request. */
+    putFiles(files: BatchFileUploadInput[], options?: RequestOptions): Promise<BatchFileUploadResponse>;
     /** Fetch CPU, memory, and network stats for this sandbox. */
     stats(query?: StatsQuery, options?: RequestOptions): Promise<Stats>;
     /** Create a snapshot for this sandbox. */

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

@@ -6,6 +6,8 @@ const files_1 = require("./files");
 const snapshots_1 = require("./snapshots");
 const stats_1 = require("./stats");
 class ScopedSandboxResource {
+    transport;
+    sandboxId;
     /** Lower-level exec/code runner resource. */
     execResource;
     /** File upload/download resource. */
@@ -16,11 +18,21 @@ class ScopedSandboxResource {
     statsResource;
     /** @internal Create a sandbox-scoped resource wrapper. */
     constructor(transport, sandboxId) {
+        this.transport = transport;
+        this.sandboxId = sandboxId;
         this.execResource = new exec_1.ExecResource(transport, sandboxId);
         this.files = new files_1.FilesResource(transport, sandboxId);
         this.snapshots = new snapshots_1.SnapshotScopeResource(transport, sandboxId);
         this.statsResource = new stats_1.StatsResource(transport, sandboxId);
     }
+    /** Destroy this sandbox. */
+    async destroy(options) {
+        await this.transport.requestJson({
+            endpoint: `/sandboxes/${this.sandboxId}`,
+            method: 'DELETE',
+            ...options,
+        });
+    }
     exec(input, options) {
         return this.execResource.exec(input, options);
     }
@@ -35,6 +47,10 @@ class ScopedSandboxResource {
     getFile(path, options) {
         return this.files.get(path, options);
     }
+    /** Upload multiple files to this sandbox in one request. */
+    putFiles(files, options) {
+        return this.files.putFiles(files, options);
+    }
     /** Fetch CPU, memory, and network stats for this sandbox. */
     stats(query = {}, options) {
         return this.statsResource.stats(query, options);

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

@@ -1 +1,17 @@
 export type FileUploadBody = ReadableStream<Uint8Array> | Buffer | Uint8Array;
+export type BatchFileUploadBody = Buffer | Uint8Array | string;
+export type BatchFileUploadInput = {
+    path: string;
+    body: BatchFileUploadBody;
+};
+export type BatchFileUploadResult = {
+    path: string;
+    bytes: number;
+    success: boolean;
+    error?: string;
+};
+export type BatchFileUploadResponse = {
+    uploaded: number;
+    failed: number;
+    results: BatchFileUploadResult[];
+};

package/dist/src/types/index.d.ts

@@ -1,5 +1,5 @@
 export type { CodeInput, ExecInput, ExecResult, ExecStreamFrame } from './exec';
-export type { FileUploadBody } from './files';
+export type { BatchFileUploadBody, BatchFileUploadInput, BatchFileUploadResponse, BatchFileUploadResult, FileUploadBody } from './files';
 export type { Paginated, Pagination, TeamScopedPagination } from './pagination';
 export type { RegionSummary, SandboxRegion, SandboxRegionsResult } from './region';
 export type { AckMessage, CreateSandboxInput, CreateSandboxRequest, CreateSandboxResult, CreateSandboxWithVolumeInput, CreateSandboxWithVolumeResult, Sandbox, SandboxReadyRequestOptions, SandboxRegionInput, SandboxRuntimeOptions, SandboxSpecs, WaitPreference, WaitUntilReadyOptions, } from './sandbox';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brimble/sandbox",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "TypeScript SDK for the Brimble Sandbox API",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",