@upstash/box 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Upstash, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# @upstash/box
+
+TypeScript SDK for [Upstash Box](https://upstash.com/docs/box) — create sandboxed AI coding agents with streaming, structured output, file I/O, git operations, and snapshots.
+
+## Installation
+
+```bash
+npm install @upstash/box
+```
+
+## Quick start
+
+```ts
+import { Box, Runtime, ClaudeCode } from "@upstash/box";
+
+const box = await Box.create({
+  runtime: Runtime.Node,
+  agent: {
+    model: ClaudeCode.Sonnet_4_5,
+    apiKey: process.env.CLAUDE_KEY!,
+  },
+});
+
+const run = await box.agent.run({
+  prompt: "Create a hello world Express server",
+  onStream: (chunk) => process.stdout.write(chunk),
+});
+
+console.log(await run.result());
+await box.delete();
+```
+
+## Authentication
+
+Pass `apiKey` in the config or set the `UPSTASH_BOX_API_KEY` environment variable.
+
+## API
+
+### Static methods
+
+#### `Box.create(config: BoxConfig): Promise<Box>`
+
+Create a new sandboxed box.
+
+```ts
+const box = await Box.create({
+  apiKey: "abx_...",         // or set UPSTASH_BOX_API_KEY
+  runtime: Runtime.Node,     // node, python, golang, ruby, rust
+  agent: {
+    model: ClaudeCode.Sonnet_4_5,
+    apiKey: process.env.CLAUDE_KEY!,
+  },
+  git: { token: process.env.GITHUB_TOKEN! },
+  env: { NODE_ENV: "production" },
+  timeout: 600000,
+  debug: false,
+});
+```
+
+#### `Box.get(boxId: string, options?: BoxGetOptions): Promise<Box>`
+
+Reconnect to an existing box by ID.
+
+```ts
+const box = await Box.get("box_abc123");
+```
+
+#### `Box.list(options?: ListOptions): Promise<BoxData[]>`
+
+List all boxes for the authenticated user.
+
+```ts
+const boxes = await Box.list();
+```
+
+#### `Box.fromSnapshot(snapshotId: string, config: BoxConfig): Promise<Box>`
+
+Create a new box from a saved snapshot.
+
+```ts
+const box = await Box.fromSnapshot("snap_abc123", {
+  agent: { model: ClaudeCode.Sonnet_4_5, apiKey: process.env.CLAUDE_KEY! },
+});
+```
+
+### Agent
+
+#### `box.agent.run(options: RunOptions): Promise<Run>`
+
+Run the AI agent with a prompt. Supports streaming, structured output with Zod schemas, timeouts, retries, tool use callbacks, and webhooks.
+
+```ts
+// Streaming
+const run = await box.agent.run({
+  prompt: "Fix the bug in auth.ts",
+  onStream: (chunk) => process.stdout.write(chunk),
+});
+
+// Structured output
+import { z } from "zod";
+
+const schema = z.object({
+  name: z.string(),
+  score: z.number(),
+});
+
+const run = await box.agent.run({
+  prompt: "Analyze this candidate",
+  responseSchema: schema,
+});
+const result = await run.result(); // typed as { name: string, score: number }
+```
+
+#### `box.exec(command: string): Promise<Run>`
+
+Execute a shell command in the box.
+
+```ts
+const run = await box.exec("node index.js");
+console.log(await run.result());
+```
+
+### Files
+
+```ts
+await box.files.write({ path: "hello.txt", content: "Hello!" });
+const content = await box.files.read("hello.txt");
+const entries = await box.files.list(".");
+await box.files.upload([{ path: "./local.txt", destination: "remote.txt" }]);
+await box.files.download({ path: "output/" });
+```
+
+### Git
+
+```ts
+await box.git.clone({ repo: "https://github.com/user/repo", branch: "main" });
+const diff = await box.git.diff();
+const status = await box.git.status();
+await box.git.commit({ message: "feat: add feature" });
+await box.git.push({ branch: "main" });
+const pr = await box.git.createPR({ title: "New feature", body: "Description" });
+```
+
+### Lifecycle
+
+```ts
+await box.stop();            // Pause (preserves state)
+await box.start();           // Resume
+await box.delete();          // Permanent delete
+const { status } = await box.getStatus();
+```
+
+### Snapshots
+
+```ts
+const snapshot = await box.snapshot({ name: "checkpoint-1" });
+const snapshots = await box.listSnapshots();
+await box.deleteSnapshot(snapshot.id);
+```
+
+### Run object
+
+Every `agent.run()` and `exec()` call returns a `Run` object:
+
+```ts
+const run = await box.agent.run({ prompt: "..." });
+
+run.id;                      // Run ID
+await run.result();          // Final output (typed if schema provided)
+await run.status();          // "running" | "completed" | "failed" | "cancelled"
+await run.cost();            // { tokens, computeMs, totalUsd }
+await run.cancel();          // Abort
+await run.logs();            // Filtered log entries
+
+for await (const chunk of run.stream()) {
+  process.stdout.write(chunk);
+}
+```
+
+## Models
+
+### Claude Code
+
+| Enum | Value |
+|------|-------|
+| `ClaudeCode.Opus_4_5` | `claude/opus_4_5` |
+| `ClaudeCode.Opus_4_6` | `claude/opus_4_6` |
+| `ClaudeCode.Sonnet_4` | `claude/sonnet_4` |
+| `ClaudeCode.Sonnet_4_5` | `claude/sonnet_4_5` |
+| `ClaudeCode.Haiku_4_5` | `claude/haiku_4_5` |
+
+### OpenAI Codex
+
+| Enum | Value |
+|------|-------|
+| `OpenAICodex.GPT_5_3_Codex` | `openai/gpt-5.3-codex` |
+| `OpenAICodex.GPT_5_3_Codex_Spark` | `openai/gpt-5.3-codex-spark` |
+| `OpenAICodex.GPT_5_2_Codex` | `openai/gpt-5.2-codex` |
+| `OpenAICodex.GPT_5_1_Codex_Max` | `openai/gpt-5.1-codex-max` |
+
+## Runtimes
+
+| Enum | Value |
+|------|-------|
+| `Runtime.Node` | `node` |
+| `Runtime.Python` | `python` |
+| `Runtime.Golang` | `golang` |
+| `Runtime.Ruby` | `ruby` |
+| `Runtime.Rust` | `rust` |
+
+## Examples
+
+See the [`examples/`](./examples) directory for complete working examples:
+
+- `basic.ts` — Create a box, run an agent, read output
+- `streaming.ts` — Parallel boxes with structured output (Zod)
+- `file-upload.ts` — Upload local files into the box
+- `git-pr.ts` — Clone a repo, make changes, create a PR
+- `snapshot-restore.ts` — Save and restore workspace state
+- `webhook.ts` — Fire-and-forget with webhook callbacks
+- `multi-runtime.ts` — Run across different runtimes
+- `mcp-skills.ts` — Attach MCP servers to a box
+
+## License
+
+MIT

package/dist/__tests__/helpers.d.ts

@@ -0,0 +1,25 @@
+import { vi } from "vitest";
+import { Box } from "../client.js";
+import type { BoxData } from "../types.js";
+export declare const TEST_CONFIG: {
+    readonly apiKey: "test-api-key";
+    readonly baseUrl: "https://test.api.example.com";
+    readonly agent: {
+        readonly model: "claude/sonnet_4_5";
+        readonly apiKey: "test-agent-key";
+    };
+};
+export declare const TEST_BOX_DATA: BoxData;
+export declare function mockResponse(body: unknown, status?: number): Response;
+export declare function mockSSEResponse(events: Array<{
+    event: string;
+    data: unknown;
+}>): Response;
+/**
+ * Creates a real Box instance by mocking the fetch for Box.get().
+ */
+export declare function createTestBox(overrides?: Partial<BoxData>): Promise<{
+    box: Box;
+    fetchMock: ReturnType<typeof vi.fn>;
+}>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/__tests__/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/__tests__/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,eAAO,MAAM,WAAW;;;;;;;CAId,CAAC;AAEX,eAAO,MAAM,aAAa,EAAE,OAO3B,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,SAAM,GAAG,QAAQ,CAoBlE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,GAAG,QAAQ,CA8BzF;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,SAAS,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAC3B,OAAO,CAAC;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,SAAS,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC,CAS5D"}

package/dist/__tests__/helpers.js

@@ -0,0 +1,80 @@
+import { vi } from "vitest";
+import { Box } from "../client.js";
+export const TEST_CONFIG = {
+    apiKey: "test-api-key",
+    baseUrl: "https://test.api.example.com",
+    agent: { model: "claude/sonnet_4_5", apiKey: "test-agent-key" },
+};
+export const TEST_BOX_DATA = {
+    id: "box-123",
+    model: "claude/sonnet_4_5",
+    runtime: "node",
+    status: "running",
+    created_at: "2025-01-01T00:00:00Z",
+    updated_at: "2025-01-01T00:00:00Z",
+};
+export function mockResponse(body, status = 200) {
+    const json = JSON.stringify(body);
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        statusText: status === 200 ? "OK" : "Error",
+        headers: new Headers({ "content-type": "application/json" }),
+        json: () => Promise.resolve(body),
+        text: () => Promise.resolve(json),
+        body: null,
+        bodyUsed: false,
+        arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+        blob: () => Promise.resolve(new Blob()),
+        formData: () => Promise.resolve(new FormData()),
+        clone: () => mockResponse(body, status),
+        redirected: false,
+        type: "basic",
+        url: "",
+        bytes: () => Promise.resolve(new Uint8Array()),
+    };
+}
+export function mockSSEResponse(events) {
+    const lines = events
+        .map((e) => `event: ${e.event}\ndata: ${JSON.stringify(e.data)}\n\n`)
+        .join("");
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        start(controller) {
+            controller.enqueue(encoder.encode(lines));
+            controller.close();
+        },
+    });
+    return {
+        ok: true,
+        status: 200,
+        statusText: "OK",
+        headers: new Headers({ "content-type": "text/event-stream" }),
+        json: () => Promise.reject(new Error("SSE response")),
+        text: () => Promise.resolve(lines),
+        body: stream,
+        bodyUsed: false,
+        arrayBuffer: () => Promise.resolve(new ArrayBuffer(0)),
+        blob: () => Promise.resolve(new Blob()),
+        formData: () => Promise.resolve(new FormData()),
+        clone: () => mockSSEResponse(events),
+        redirected: false,
+        type: "basic",
+        url: "",
+        bytes: () => Promise.resolve(new Uint8Array()),
+    };
+}
+/**
+ * Creates a real Box instance by mocking the fetch for Box.get().
+ */
+export async function createTestBox(overrides) {
+    const data = { ...TEST_BOX_DATA, ...overrides };
+    const fetchMock = vi.fn().mockResolvedValueOnce(mockResponse(data));
+    vi.stubGlobal("fetch", fetchMock);
+    const box = await Box.get(data.id, {
+        apiKey: TEST_CONFIG.apiKey,
+        baseUrl: TEST_CONFIG.baseUrl,
+    });
+    return { box, fetchMock };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/__tests__/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/__tests__/helpers.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,229 @@
+import type { BoxConfig, BoxData, BoxGetOptions, BoxRunData, ListOptions, RunOptions, StreamOptions, RunStatus, RunCost, RunLog, SchemaLike, FileEntry, GitCloneOptions, GitPROptions, GitCommitResult, PullRequest, LogEntry, UploadFileEntry, Snapshot } from "./types.js";
+/**
+ * Error thrown by the Box SDK
+ */
+export declare class BoxError extends Error {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+/**
+ * A run represents a single agent or shell execution.
+ * Returned by box.agent.run() and box.exec().
+ */
+export declare class Run<T = string> {
+    readonly type: "agent" | "shell";
+    /** @internal */
+    _id: string;
+    /** @internal */
+    _result: T | null;
+    /** @internal */
+    _status: RunStatus;
+    /** @internal */
+    _inputTokens: number;
+    /** @internal */
+    _outputTokens: number;
+    /** @internal */
+    _computeMs: number;
+    /** @internal */
+    _box: Box;
+    /** @internal */
+    _abortController?: AbortController;
+    /** @internal */
+    _startTime: number;
+    /** The run ID. Initially a local UUID, replaced by backend run_id from run_start event. */
+    get id(): string;
+    /** @internal */
+    constructor(box: Box, type: "agent" | "shell", id?: string);
+    /**
+     * Get the current run status. Polls the backend for the latest status if the run may still be active.
+     */
+    status(): Promise<RunStatus>;
+    /**
+     * Get the run result. Returns the typed output when responseSchema was provided.
+     */
+    result(): Promise<T>;
+    /**
+     * Get token usage and cost information. Fetches from backend when available.
+     */
+    cost(): Promise<RunCost>;
+    /**
+     * Cancel a running execution.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Retrieve logs for this run.
+     */
+    logs(): Promise<RunLog[]>;
+}
+/**
+ * A sandboxed AI coding environment.
+ *
+ * @example
+ * ```ts
+ * import { Box, Runtime, ClaudeCode } from "@upstash/box";
+ *
+ * const box = await Box.create({
+ *   runtime: Runtime.Node,
+ *   agent: { model: ClaudeCode.Sonnet_4_5, apiKey: process.env.CLAUDE_KEY! },
+ * });
+ *
+ * // Non-streaming
+ * const run = await box.agent.run({ prompt: "Fix the bug in auth.ts" });
+ * console.log(await run.result());
+ *
+ * // Streaming
+ * for await (const chunk of box.agent.stream({ prompt: "Add tests" })) {
+ *   process.stdout.write(chunk);
+ * }
+ *
+ * await box.delete();
+ * ```
+ */
+export declare class Box {
+    readonly id: string;
+    /** Agent operations namespace */
+    readonly agent: {
+        run<T>(options: RunOptions<T> & {
+            responseSchema: SchemaLike<T>;
+        }): Promise<Run<T>>;
+        run(options: RunOptions): Promise<Run<string>>;
+        stream(options: StreamOptions): AsyncGenerator<string>;
+    };
+    /** File operations namespace */
+    readonly files: {
+        read: (path: string) => Promise<string>;
+        write: (options: {
+            path: string;
+            content: string;
+        }) => Promise<void>;
+        list: (path?: string) => Promise<FileEntry[]>;
+        upload: (files: UploadFileEntry[]) => Promise<void>;
+        download: (options?: {
+            path?: string;
+        }) => Promise<void>;
+    };
+    /** Git operations namespace */
+    readonly git: {
+        clone: (options: GitCloneOptions) => Promise<void>;
+        diff: () => Promise<string>;
+        status: () => Promise<string>;
+        commit: (options: {
+            message: string;
+        }) => Promise<GitCommitResult>;
+        push: (options?: {
+            branch?: string;
+        }) => Promise<void>;
+        createPR: (options: GitPROptions) => Promise<PullRequest>;
+    };
+    private _baseUrl;
+    private _headers;
+    private _timeout;
+    private _debug;
+    private _gitToken?;
+    private _isAgentConfigured;
+    private constructor();
+    /**
+     * Create a new sandboxed box.
+     */
+    static create(config: BoxConfig): Promise<Box>;
+    /**
+     * List all boxes for the authenticated user.
+     */
+    static list(options?: ListOptions): Promise<BoxData[]>;
+    /**
+     * Get an existing box by ID.
+     */
+    static get(boxId: string, options?: BoxGetOptions): Promise<Box>;
+    /** @internal */
+    _run<T>(options: RunOptions<T>): Promise<Run<T | string>>;
+    private _runWithRetries;
+    private _executeRun;
+    /** @internal */
+    _stream(options: StreamOptions): AsyncGenerator<string>;
+    private _processStreamEvent;
+    /**
+     * Execute an OS-level command in the box.
+     *
+     * @example
+     * ```ts
+     * const run = await box.exec("node /work/index.js");
+     * console.log(await run.result());
+     * console.log(await run.status()); // "completed"
+     * ```
+     */
+    exec(command: string): Promise<Run<string>>;
+    private static readonly WORKSPACE;
+    private _resolvePath;
+    private _readFile;
+    private _writeFile;
+    private _listFiles;
+    private _uploadFiles;
+    private _downloadFiles;
+    /**
+     * Get the current box status.
+     */
+    getStatus(): Promise<{
+        status: string;
+    }>;
+    /**
+     * Stop the box (release compute, preserve state).
+     */
+    stop(): Promise<void>;
+    /**
+     * Start a stopped box.
+     */
+    start(): Promise<void>;
+    /**
+     * Delete this box permanently.
+     */
+    delete(): Promise<void>;
+    /**
+     * Save workspace state as a snapshot for later restore.
+     * Creates the snapshot asynchronously and polls until ready.
+     */
+    snapshot(options: {
+        name: string;
+    }): Promise<Snapshot>;
+    /**
+     * List all snapshots for this box.
+     */
+    listSnapshots(): Promise<Snapshot[]>;
+    /**
+     * Delete a snapshot.
+     */
+    deleteSnapshot(snapshotId: string): Promise<void>;
+    /**
+     * Create a new box from a saved snapshot.
+     */
+    static fromSnapshot(snapshotId: string, config: BoxConfig): Promise<Box>;
+    /**
+     * Get structured logs for this box.
+     */
+    logs(options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<LogEntry[]>;
+    /**
+     * List all runs for this box, newest first.
+     */
+    listRuns(): Promise<BoxRunData[]>;
+    private log;
+    /** @internal */
+    _request<T>(method: string, path: string, options?: {
+        body?: unknown;
+        timeout?: number;
+    }): Promise<T>;
+    private _gitClone;
+    private _gitDiff;
+    private _gitStatus;
+    private _gitCommit;
+    private _gitPush;
+    private _gitCreatePR;
+}
+/** @internal */
+export declare function extractSchemaShape(schema: SchemaLike<unknown>): string | null;
+/** @internal */
+export declare function zodTypeToExample(field: unknown): string;
+/** @internal */
+export declare function parseErrorResponse(response: Response): Promise<string>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}