@watasu/sdk 0.1.25 → 0.1.30

package/README.md

@@ -31,23 +31,63 @@ await sbx.betaPause()
 await sbx.resume({ timeoutMs: 300_000 })
 ```
 
+Choose what happens when the sandbox timeout expires:
+
+```ts
+const sbx = await Sandbox.create({
+  lifecycle: { onTimeout: 'pause', autoResume: true },
+})
+```
+
+`onTimeout: 'kill'` is the default. `onTimeout: 'pause'` keeps the retained
+disk after timeout; `autoResume` lets a later data-plane request resume that
+paused sandbox automatically.
+
+Mount a named persistent volume when the sandbox starts:
+
+```ts
+const sbx = await Sandbox.create({
+  volumeMounts: {
+    '/workspace/cache': 'cache',
+    '/data/models': { name: 'models' },
+  },
+})
+```
+
+Create and edit a persistent volume while it is detached:
+
+```ts
+import { Volume } from '@watasu/sdk'
+
+const volume = await Volume.create('cache')
+await volume.makeDir('/workspace')
+await volume.writeFile('/workspace/status.txt', 'ready\n', { mode: '0644' })
+console.log(await volume.readFile('/workspace/status.txt'))
+console.log((await volume.list('/workspace')).map((entry) => entry.path))
+await volume.remove('/workspace/status.txt')
+await volume.destroy()
+```
+
 ## Code Interpreter
 
 ```ts
 import { Sandbox } from '@watasu/sdk/code-interpreter'
 
 const sbx = await Sandbox.create()
+const context = await sbx.createCodeContext()
 const execution = await sbx.runCode("print('hello')\n2 + 3", {
-  language: 'python',
+  context,
   onStdout: (message) => console.log(message.line),
 })
 
 console.log(execution.text)
+await sbx.removeCodeContext(context)
 await sbx.kill()
 ```
 
-`@watasu/sdk/code-interpreter` starts the `code-interpreter` template by default
-and returns structured `results`, `logs`, and `error` fields for each execution.
+`@watasu/sdk/code-interpreter` starts the `code-interpreter` template by default.
+Code runs in persistent Python contexts and returns structured `results`, `logs`,
+and `error` fields for each execution.
 
 ## MCP Gateway
 
@@ -191,7 +231,10 @@ instructions into Watasu's package-spec builder.
 import { Sandbox } from '@watasu/sdk'
 
 const sbx = await Sandbox.create()
-const metrics = await sbx.getMetrics()
+const metrics = await sbx.getMetrics({
+  start: new Date(Date.now() - 5 * 60_000),
+  end: new Date(),
+})
 const snapshot = await sbx.createSnapshot({ name: 'ready' })
 const snapshots = await sbx.listSnapshots().nextItems()
 const allSnapshots = await Sandbox.listSnapshots({ limit: 100 }).nextItems()

package/dist/codeInterpreter.d.ts

@@ -2,7 +2,7 @@ import { Sandbox as BaseSandbox, SandboxConnectOpts, SandboxCreateOpts } from '.
 export type RunCodeLanguage = 'python' | 'python3' | string;
 export interface RunCodeOpts {
     language?: RunCodeLanguage;
-    context?: Context;
+    context?: Context | string;
     onStdout?: (message: OutputMessage) => void;
     onStderr?: (message: OutputMessage) => void;
     onResult?: (result: Result) => void;
@@ -86,15 +86,15 @@ export declare class Sandbox extends BaseSandbox {
     /** Create a persistent code context. */
     createCodeContext(_opts?: CreateCodeContextOpts): Promise<Context>;
     /** Remove a persistent code context. */
-    removeCodeContext(_context: Context, _opts?: {
+    removeCodeContext(context: Context | string, opts?: {
         requestTimeoutMs?: number;
-    }): Promise<boolean>;
+    }): Promise<void>;
     /** List persistent code contexts. */
-    listCodeContexts(_opts?: {
+    listCodeContexts(opts?: {
         requestTimeoutMs?: number;
     }): Promise<Context[]>;
     /** Restart a persistent code context. */
-    restartCodeContext(_context: Context, _opts?: {
+    restartCodeContext(context: Context | string, opts?: {
         requestTimeoutMs?: number;
-    }): Promise<Context>;
+    }): Promise<void>;
 }

package/dist/codeInterpreter.js

@@ -1,4 +1,4 @@
-import { InvalidArgumentError, NotImplementedError } from './errors.js';
+import { InvalidArgumentError } from './errors.js';
 import { Sandbox as BaseSandbox } from './sandbox.js';
 /** One stdout or stderr line emitted by code execution. */
 export class OutputMessage {
@@ -172,19 +172,33 @@ export class Sandbox extends BaseSandbox {
     }
     /** Create a persistent code context. */
     async createCodeContext(_opts = {}) {
-        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+        const response = await this.runtimePostJson('/runtime/v1/code/contexts', compactRecord({
+            cwd: _opts.cwd,
+            language: _opts.language,
+        }), {
+            requestTimeoutMs: _opts.requestTimeoutMs,
+        });
+        return contextFromApi(response);
     }
     /** Remove a persistent code context. */
-    async removeCodeContext(_context, _opts = {}) {
-        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+    async removeCodeContext(context, opts = {}) {
+        await this.runtimeDeleteJson(`/runtime/v1/code/contexts/${encodeURIComponent(requireContextId(context))}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
     }
     /** List persistent code contexts. */
-    async listCodeContexts(_opts = {}) {
-        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+    async listCodeContexts(opts = {}) {
+        const response = await this.runtimeGetJson('/runtime/v1/code/contexts', {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        const contexts = Array.isArray(response) ? response : arrayOfUnknown(response.contexts);
+        return contexts.map((item) => contextFromApi(record(item)));
     }
     /** Restart a persistent code context. */
-    async restartCodeContext(_context, _opts = {}) {
-        throw new NotImplementedError('code contexts are not supported by Watasu yet');
+    async restartCodeContext(context, opts = {}) {
+        await this.runtimePostJson(`/runtime/v1/code/contexts/${encodeURIComponent(requireContextId(context))}/restart`, {}, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
     }
 }
 function executionFromApi(payload) {
@@ -219,7 +233,17 @@ function emitCallbacks(execution, opts) {
         opts.onError?.(execution.error);
 }
 function contextId(context) {
-    return context?.id;
+    if (context === undefined)
+        return undefined;
+    return requireContextId(context);
+}
+function requireContextId(context) {
+    if (typeof context === 'string')
+        return context;
+    return context.id;
+}
+function contextFromApi(payload) {
+    return new Context(String(payload.id ?? ''), stringValue(payload.language), stringValue(payload.cwd));
 }
 function compactRecord(payload) {
     return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { ApiError, AuthenticationError, ConflictError, FileNotFoundError, Invali
 export { ConnectionConfig, KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
 export { Sandbox, SandboxPaginator, SnapshotPaginator } from './sandbox.js';
 export { Sandbox as CodeInterpreterSandbox } from './codeInterpreter.js';
-export type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxCreateOpts, SandboxConnectOpts, SandboxInfo, SandboxListOpts, SandboxMetrics, McpServer, McpServerName, SandboxNetworkSelector, SandboxNetworkUpdate, SandboxNetworkUpdateOpts, SandboxUrlOpts, SnapshotInfo, FileUrlInfo, } from './sandbox.js';
+export type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxCreateOpts, SandboxConnectOpts, SandboxInfo, SandboxInfoLifecycle, SandboxLifecycle, SandboxListOpts, SandboxMetrics, SandboxMetricsOpts, McpServer, McpServerName, SandboxNetworkSelector, SandboxNetworkUpdate, SandboxNetworkUpdateOpts, SandboxUrlOpts, SnapshotInfo, FileUrlInfo, } from './sandbox.js';
 export type { CreateCodeContextOpts, RunCodeLanguage, RunCodeOpts, } from './codeInterpreter.js';
 export { Context as CodeInterpreterContext, Execution as CodeInterpreterExecution, ExecutionError as CodeInterpreterExecutionError, OutputMessage as CodeInterpreterOutputMessage, Result as CodeInterpreterResult, } from './codeInterpreter.js';
 export { CommandExitError, CommandHandle, Commands } from './commands.js';
@@ -17,6 +17,8 @@ export { Pty } from './pty.js';
 export type { PtyConnectOpts, PtyCreateOpts, PtySize } from './pty.js';
 export { Terminal, TerminalManager, TerminalOutput } from './terminal.js';
 export type { TerminalOpts } from './terminal.js';
+export { Volume } from './volume.js';
+export type { VolumeApiParams, VolumeConnectionConfig, VolumeEntryStat, VolumeFileType, VolumeInfo, VolumeListFilesOpts, VolumeListOpts, VolumeMetadataOpts, VolumeReadFileOpts, VolumeReadFormat, VolumeWriteData, VolumeWriteFileOpts, } from './volume.js';
 export { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
 export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, waitForUrl, } from './template.js';
 export type { BuildInfo, BuildOptions, BuildStatusReason, CopyItem, GetBuildStatusOptions, LogEntry, ReadyCommand, TemplateBuildStatus, TemplateBuildStatusResponse, TemplateBuilder, TemplateClass, TemplateFactory, TemplateFinal, TemplateFromImage, TemplateOptions, TemplateTag, TemplateTagInfo, } from './template.js';

package/dist/index.js

@@ -9,5 +9,6 @@ export { FileType, Filesystem, FilesystemWatcher, WatchHandle } from './filesyst
 export { Git } from './git.js';
 export { Pty } from './pty.js';
 export { Terminal, TerminalManager, TerminalOutput } from './terminal.js';
+export { Volume } from './volume.js';
 export { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
 export { ReadyCmd, Template, TemplateBase, waitForFile, waitForPort, waitForProcess, waitForTimeout, waitForURL, waitForUrl, } from './template.js';

package/dist/sandbox.d.ts

@@ -19,7 +19,16 @@ export interface SandboxCreateOpts extends ConnectionOpts {
     team?: string;
     /** MCP gateway configuration to launch inside an `mcp-gateway` sandbox. */
     mcp?: McpServer;
-    volumeMounts?: unknown;
+    /** Timeout lifecycle policy. Defaults to killing the sandbox at timeout. */
+    lifecycle?: SandboxLifecycle;
+    /** Persistent volumes to mount, keyed by guest path. */
+    volumeMounts?: Record<string, string | {
+        name: string;
+    }>;
+}
+export interface SandboxLifecycle {
+    onTimeout: 'kill' | 'pause';
+    autoResume?: boolean;
 }
 export type SandboxNetworkSelector = string | string[];
 export interface SandboxNetworkUpdate {
@@ -58,10 +67,19 @@ export interface SandboxInfo {
     templateId?: string;
     name?: string;
     state?: string;
+    lifecycle?: SandboxInfoLifecycle;
+    volumeMounts?: Array<{
+        name: string;
+        path: string;
+    }>;
     metadata: Record<string, string>;
     startedAt?: string;
     endAt?: string;
 }
+export interface SandboxInfoLifecycle {
+    onTimeout: 'kill' | 'pause' | string;
+    autoResume: boolean;
+}
 export interface SandboxMetrics {
     sandboxId?: string;
     state?: string;
@@ -71,6 +89,12 @@ export interface SandboxMetrics {
     memoryMb?: number;
     raw: Record<string, unknown>;
 }
+export interface SandboxMetricsOpts extends ConnectionOpts {
+    /** Start time for the metrics. Defaults to the sandbox start time. */
+    start?: Date;
+    /** End time for the metrics. Defaults to the current time. */
+    end?: Date;
+}
 export interface SnapshotInfo {
     snapshotId: string;
     sandboxId?: string;
@@ -194,7 +218,7 @@ export declare class Sandbox {
     /** Destroy a sandbox by id. */
     static kill(sandboxId: string, opts?: ConnectionOpts | string): Promise<boolean>;
     /** Fetch sandbox metrics by id. */
-    static getMetrics(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxMetrics[]>;
+    static getMetrics(sandboxId: string, opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>;
     /** Atomically replace a sandbox's network egress policy by id. */
     static updateNetwork(sandboxId: string, network: SandboxNetworkUpdate, opts?: SandboxNetworkUpdateOpts): Promise<void>;
     private static putNetwork;
@@ -221,7 +245,7 @@ export declare class Sandbox {
     /** Fetch the latest control-plane metadata for this sandbox. */
     getInfo(): Promise<SandboxInfo>;
     /** Fetch latest sandbox metrics. */
-    getMetrics(opts?: ConnectionOpts): Promise<SandboxMetrics[]>;
+    getMetrics(opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>;
     /** Create a Watasu checkpoint using snapshot naming. */
     createSnapshot(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
     /** Delete a snapshot by id. */
@@ -265,5 +289,9 @@ export declare class Sandbox {
     private fileUrl;
     /** POST JSON to the sandbox data-plane runtime API. */
     protected runtimePostJson(path: string, json: Record<string, unknown>, opts?: ConnectionOpts): Promise<Record<string, unknown>>;
+    /** GET JSON from the sandbox data-plane runtime API. */
+    protected runtimeGetJson(path: string, opts?: ConnectionOpts): Promise<Record<string, unknown>>;
+    /** DELETE JSON from the sandbox data-plane runtime API. */
+    protected runtimeDeleteJson(path: string, opts?: ConnectionOpts): Promise<Record<string, unknown>>;
     private configOptions;
 }

package/dist/sandbox.js

@@ -1,6 +1,6 @@
 import { Commands } from './commands.js';
 import { ConnectionConfig, SESSION_OPERATION_REQUEST_TIMEOUT_MS } from './connectionConfig.js';
-import { DataPlaneClient, ControlClient } from './transport.js';
+import { DataPlaneClient, ControlClient, withQuery } from './transport.js';
 import { ConflictError, FileNotFoundError, NotFoundError, SandboxError, unsupported } from './errors.js';
 import { Filesystem } from './filesystem.js';
 import { Git } from './git.js';
@@ -123,8 +123,6 @@ export class Sandbox {
         const template = typeof templateOrOpts === 'string'
             ? templateOrOpts
             : templateOrOpts?.template ?? (sandboxOpts.mcp === undefined ? this.defaultTemplate : undefined);
-        if (sandboxOpts.volumeMounts !== undefined)
-            unsupported('volumeMounts');
         const config = new ConnectionConfig(sandboxOpts);
         const control = new ControlClient(config);
         const sandboxPayload = {
@@ -136,6 +134,8 @@ export class Sandbox {
         };
         putIfPresent(sandboxPayload, 'template_id', template);
         putIfPresent(sandboxPayload, 'mcp', sandboxOpts.mcp);
+        putIfPresent(sandboxPayload, 'lifecycle', lifecyclePayload(sandboxOpts.lifecycle));
+        putIfPresent(sandboxPayload, 'volume_mounts', volumeMountsPayload(sandboxOpts.volumeMounts));
         Object.assign(sandboxPayload, networkUpdatePayload(sandboxOpts.network));
         putIfPresent(sandboxPayload, 'team', sandboxOpts.team);
         const response = await control.post('/sandboxes', {
@@ -229,7 +229,7 @@ export class Sandbox {
     /** Fetch sandbox metrics by id. */
     static async getMetrics(sandboxId, opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
-        const payload = await control.get(`/sandboxes/${sandboxId}/metrics`, {
+        const payload = await control.get(metricsPath(sandboxId, opts), {
             requestTimeoutMs: opts.requestTimeoutMs,
         });
         return metricsList(payload.metrics ?? payload);
@@ -465,6 +465,18 @@ export class Sandbox {
             requestTimeoutMs: opts.requestTimeoutMs,
         });
     }
+    /** GET JSON from the sandbox data-plane runtime API. */
+    async runtimeGetJson(path, opts = {}) {
+        return this.dataPlane.getJson(path, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+    }
+    /** DELETE JSON from the sandbox data-plane runtime API. */
+    async runtimeDeleteJson(path, opts = {}) {
+        return this.dataPlane.deleteJson(path, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+    }
     configOptions() {
         return {
             apiKey: this.config.apiKey,
@@ -515,6 +527,15 @@ function snapshotListPath(opts, nextToken) {
     const query = params.toString();
     return query ? `/sandbox_snapshots?${query}` : '/sandbox_snapshots';
 }
+function metricsPath(sandboxId, opts) {
+    return withQuery(`/sandboxes/${sandboxId}/metrics`, {
+        start: dateTimestampSeconds(opts.start),
+        end: dateTimestampSeconds(opts.end),
+    });
+}
+function dateTimestampSeconds(value) {
+    return value === undefined ? undefined : Math.round(value.getTime() / 1000);
+}
 function fileUrlInfo(payload) {
     return {
         method: String(payload.method ?? ''),
@@ -538,6 +559,8 @@ function sandboxInfo(payload) {
         templateId: typeof payload.template_id === 'string' ? payload.template_id : templateSlug(payload.template),
         name: typeof payload.name === 'string' ? payload.name : undefined,
         state: typeof payload.state === 'string' ? payload.state : undefined,
+        lifecycle: sandboxLifecycleInfo(payload.lifecycle),
+        volumeMounts: volumeMountsInfo(payload.volume_mounts ?? payload.volumeMounts),
         metadata: recordOfStrings(payload.metadata),
         startedAt: typeof payload.started_at === 'string'
             ? payload.started_at
@@ -547,6 +570,45 @@ function sandboxInfo(payload) {
             : typeof payload.deadline_at === 'string' ? payload.deadline_at : undefined,
     };
 }
+function lifecyclePayload(lifecycle) {
+    if (lifecycle === undefined)
+        return undefined;
+    const onTimeout = lifecycle.onTimeout ?? 'kill';
+    const autoResume = lifecycle.autoResume ?? false;
+    if (autoResume && onTimeout !== 'pause') {
+        throw new SandboxError("lifecycle.autoResume can only be true when lifecycle.onTimeout is 'pause'");
+    }
+    return { on_timeout: onTimeout, auto_resume: autoResume };
+}
+function volumeMountsPayload(volumeMounts) {
+    if (volumeMounts === undefined)
+        return undefined;
+    return Object.entries(volumeMounts).map(([path, volume]) => ({
+        path,
+        name: typeof volume === 'string' ? volume : volume.name,
+    }));
+}
+function volumeMountsInfo(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value
+        .map((item) => {
+        const entry = record(item);
+        return { name: String(entry.name ?? ''), path: String(entry.path ?? '') };
+    })
+        .filter((entry) => entry.name !== '' && entry.path !== '');
+}
+function sandboxLifecycleInfo(value) {
+    const lifecycle = record(value);
+    const onTimeout = stringValue(lifecycle.on_timeout ?? lifecycle.onTimeout);
+    const autoResume = booleanValue(lifecycle.auto_resume ?? lifecycle.autoResume);
+    if (onTimeout === undefined && autoResume === undefined)
+        return undefined;
+    return {
+        onTimeout: onTimeout ?? 'kill',
+        autoResume: autoResume ?? false,
+    };
+}
 function metricsList(value) {
     if (Array.isArray(value))
         return value.map((item) => metricsInfo(record(item)));
@@ -596,6 +658,15 @@ function stringValue(value) {
 function numberValue(value) {
     return typeof value === 'number' ? value : undefined;
 }
+function booleanValue(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'true' || value === '1')
+        return true;
+    if (value === 'false' || value === '0')
+        return false;
+    return undefined;
+}
 function templateSlug(value) {
     const template = record(value);
     return typeof template.slug === 'string' ? template.slug : undefined;

package/dist/volume.d.ts

@@ -0,0 +1,120 @@
+import { Blob } from 'node:buffer';
+import { ConnectionConfig, type ConnectionOpts } from './connectionConfig.js';
+import { ControlClient } from './transport.js';
+export type VolumeFileType = 'file' | 'directory' | 'symlink' | string;
+export type VolumeReadFormat = 'text' | 'bytes' | 'blob' | 'stream';
+export type VolumeWriteData = string | Uint8Array | ArrayBuffer | Blob;
+/** Control-plane metadata for a persistent Watasu volume. */
+export interface VolumeInfo {
+    volumeId: string;
+    id: string;
+    name: string;
+    state?: string;
+    token?: string;
+    sizeMb?: number;
+    sizeBytes?: number;
+    node?: string;
+    metadata: Record<string, string>;
+    createdAt?: string;
+    updatedAt?: string;
+    raw: Record<string, unknown>;
+}
+/** File or directory metadata returned by volume content operations. */
+export interface VolumeEntryStat {
+    path: string;
+    name: string;
+    type: VolumeFileType;
+    size?: number;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+    atime?: unknown;
+    mtime?: unknown;
+    ctime?: unknown;
+    raw: Record<string, unknown>;
+}
+export interface VolumeApiParams extends ConnectionOpts {
+    team?: string;
+}
+export interface VolumeConnectionConfig extends ConnectionOpts {
+}
+export interface VolumeListOpts extends ConnectionOpts {
+    team?: string;
+}
+export interface VolumeListFilesOpts extends ConnectionOpts {
+    depth?: number;
+}
+export interface VolumeReadFileOpts extends ConnectionOpts {
+    format?: VolumeReadFormat;
+}
+export interface VolumeWriteFileOpts extends ConnectionOpts {
+    uid?: number;
+    gid?: number;
+    mode?: number | string;
+    force?: boolean;
+}
+export interface VolumeMetadataOpts extends ConnectionOpts {
+    uid?: number;
+    gid?: number;
+    mode?: number | string;
+}
+/** Persistent volume that can be mounted into sandboxes and edited while detached. */
+export declare class Volume {
+    readonly volumeId: string;
+    readonly id: string;
+    readonly name: string;
+    readonly token?: string;
+    private readonly config;
+    private readonly control;
+    constructor(opts: {
+        volumeId: string;
+        name?: string;
+        token?: string;
+        connectionConfig: ConnectionConfig;
+        control?: ControlClient;
+    });
+    /** Create a persistent volume and return a connected SDK object. */
+    static create(name: string, opts?: VolumeApiParams): Promise<Volume>;
+    /** Connect to an existing volume by id or name. */
+    static connect(volumeId: string, opts?: VolumeConnectionConfig): Promise<Volume>;
+    /** Fetch metadata for an existing volume by id or name. */
+    static getInfo(volumeId: string, opts?: VolumeConnectionConfig): Promise<VolumeInfo>;
+    /** List volumes visible to the configured API key. */
+    static list(opts?: VolumeListOpts): Promise<VolumeInfo[]>;
+    /** Destroy a volume by id or name. Returns false when it does not exist. */
+    static destroy(volumeId: string, opts?: VolumeConnectionConfig): Promise<boolean>;
+    /** Alias for `destroy`. */
+    static delete(volumeId: string, opts?: VolumeConnectionConfig): Promise<boolean>;
+    /** Fetch this volume's latest metadata. */
+    getInfo(): Promise<VolumeInfo>;
+    /** Fetch metadata for a path inside this volume. */
+    getInfo(path: string, opts?: ConnectionOpts): Promise<VolumeEntryStat>;
+    /** List files and directories under `path`. */
+    list(path?: string, opts?: VolumeListFilesOpts): Promise<VolumeEntryStat[]>;
+    /** Create a directory inside the detached volume. */
+    makeDir(path: string, opts?: VolumeWriteFileOpts): Promise<VolumeEntryStat>;
+    /** Return whether a path exists inside the detached volume. */
+    exists(path: string, opts?: ConnectionOpts): Promise<boolean>;
+    /** Update ownership or mode metadata for a path. */
+    updateMetadata(path: string, opts?: VolumeMetadataOpts): Promise<VolumeEntryStat>;
+    /** Read a file from the detached volume. */
+    readFile(path: string, opts: VolumeReadFileOpts & {
+        format: 'bytes';
+    }): Promise<Uint8Array>;
+    readFile(path: string, opts: VolumeReadFileOpts & {
+        format: 'blob';
+    }): Promise<Blob>;
+    readFile(path: string, opts: VolumeReadFileOpts & {
+        format: 'stream';
+    }): Promise<ReadableStream<Uint8Array>>;
+    readFile(path: string, opts?: VolumeReadFileOpts): Promise<string>;
+    /** Write a file into the detached volume. */
+    writeFile(path: string, data: VolumeWriteData, opts?: VolumeWriteFileOpts): Promise<VolumeEntryStat>;
+    /** Remove a file or directory from the detached volume. */
+    remove(path: string, opts?: ConnectionOpts): Promise<boolean>;
+    /** Destroy this volume. Returns false when it no longer exists. */
+    destroy(opts?: ConnectionOpts): Promise<boolean>;
+    /** Alias for `destroy`. */
+    delete(opts?: ConnectionOpts): Promise<boolean>;
+    private configOptions;
+}

package/dist/volume.js

@@ -0,0 +1,267 @@
+import { Blob } from 'node:buffer';
+import { ConnectionConfig } from './connectionConfig.js';
+import { NotFoundError, SandboxError } from './errors.js';
+import { base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
+import { ControlClient, withQuery } from './transport.js';
+/** Persistent volume that can be mounted into sandboxes and edited while detached. */
+export class Volume {
+    volumeId;
+    id;
+    name;
+    token;
+    config;
+    control;
+    constructor(opts) {
+        this.volumeId = String(opts.volumeId);
+        this.id = this.volumeId;
+        this.name = opts.name ?? this.volumeId;
+        this.token = opts.token;
+        this.config = opts.connectionConfig;
+        this.control = opts.control ?? new ControlClient(this.config);
+    }
+    /** Create a persistent volume and return a connected SDK object. */
+    static async create(name, opts = {}) {
+        const config = new ConnectionConfig(opts);
+        const control = new ControlClient(config);
+        const payload = await control.post('/volumes', {
+            json: compactRecord({ name, team: opts.team }),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeFromPayload(payload, config, control);
+    }
+    /** Connect to an existing volume by id or name. */
+    static async connect(volumeId, opts = {}) {
+        const config = new ConnectionConfig(opts);
+        const control = new ControlClient(config);
+        const payload = await control.get(`/volumes/${encodeURIComponent(volumeId)}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeFromPayload(payload, config, control);
+    }
+    /** Fetch metadata for an existing volume by id or name. */
+    static async getInfo(volumeId, opts = {}) {
+        const config = new ConnectionConfig(opts);
+        const control = new ControlClient(config);
+        const payload = await control.get(`/volumes/${encodeURIComponent(volumeId)}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeInfo(record(payload.volume ?? payload));
+    }
+    /** List volumes visible to the configured API key. */
+    static async list(opts = {}) {
+        const config = new ConnectionConfig(opts);
+        const control = new ControlClient(config);
+        const path = withQuery('/volumes', { team: opts.team });
+        const payload = await control.get(path, { requestTimeoutMs: opts.requestTimeoutMs });
+        const volumes = Array.isArray(payload.volumes) ? payload.volumes : [];
+        return volumes.map((item) => volumeInfo(record(item)));
+    }
+    /** Destroy a volume by id or name. Returns false when it does not exist. */
+    static async destroy(volumeId, opts = {}) {
+        const config = new ConnectionConfig(opts);
+        const control = new ControlClient(config);
+        try {
+            await control.delete(`/volumes/${encodeURIComponent(volumeId)}`, {
+                requestTimeoutMs: opts.requestTimeoutMs,
+            });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof NotFoundError)
+                return false;
+            throw error;
+        }
+    }
+    /** Alias for `destroy`. */
+    static async delete(volumeId, opts = {}) {
+        return this.destroy(volumeId, opts);
+    }
+    async getInfo(path, opts = {}) {
+        if (path === undefined) {
+            return Volume.getInfo(this.volumeId, this.configOptions(opts));
+        }
+        const payload = await this.control.get(withQuery(`/volumes/${this.volumeId}/path`, { path }), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeEntry(record(payload.file ?? payload));
+    }
+    /** List files and directories under `path`. */
+    async list(path = '/', opts = {}) {
+        const payload = await this.control.get(withQuery(`/volumes/${this.volumeId}/directories`, {
+            path,
+            depth: opts.depth,
+        }), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        const entries = Array.isArray(payload.entries) ? payload.entries : [];
+        return entries.map((item) => volumeEntry(record(item)));
+    }
+    /** Create a directory inside the detached volume. */
+    async makeDir(path, opts = {}) {
+        const payload = await this.control.post(`/volumes/${this.volumeId}/directories`, {
+            json: compactRecord({ path, ...metadataPayload(opts) }),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeEntry(record(payload.file ?? payload));
+    }
+    /** Return whether a path exists inside the detached volume. */
+    async exists(path, opts = {}) {
+        try {
+            await this.getInfo(path, opts);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof NotFoundError)
+                return false;
+            throw error;
+        }
+    }
+    /** Update ownership or mode metadata for a path. */
+    async updateMetadata(path, opts = {}) {
+        const payload = await this.control.patch(`/volumes/${this.volumeId}/path`, {
+            json: compactRecord({ path, ...metadataPayload(opts) }),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeEntry(record(payload.file ?? payload));
+    }
+    async readFile(path, opts = {}) {
+        const payload = await this.control.get(withQuery(`/volumes/${this.volumeId}/files`, { path }), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        const file = record(payload.file ?? payload);
+        const content = file.content_b64 ?? file.contentBase64 ?? file.content ?? '';
+        switch (opts.format ?? 'text') {
+            case 'bytes':
+                return base64DecodeBytes(content);
+            case 'blob':
+                return new Blob([base64DecodeBytes(content)]);
+            case 'stream':
+                return new Blob([base64DecodeBytes(content)]).stream();
+            case 'text':
+                return file.content_b64 || file.contentBase64 ? base64DecodeText(content) : String(content);
+            default:
+                throw new SandboxError(`unsupported volume read format: ${String(opts.format)}`);
+        }
+    }
+    /** Write a file into the detached volume. */
+    async writeFile(path, data, opts = {}) {
+        const bytes = await bytesFromWriteData(data);
+        const payload = await this.control.put(`/volumes/${this.volumeId}/files`, {
+            json: compactRecord({
+                path,
+                content_b64: base64Encode(bytes),
+                ...metadataPayload(opts),
+                force: opts.force,
+            }),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return volumeEntry(record(payload.file ?? payload));
+    }
+    /** Remove a file or directory from the detached volume. */
+    async remove(path, opts = {}) {
+        await this.control.delete(withQuery(`/volumes/${this.volumeId}/path`, { path }), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return true;
+    }
+    /** Destroy this volume. Returns false when it no longer exists. */
+    async destroy(opts = {}) {
+        return Volume.destroy(this.volumeId, this.configOptions(opts));
+    }
+    /** Alias for `destroy`. */
+    async delete(opts = {}) {
+        return this.destroy(opts);
+    }
+    configOptions(opts = {}) {
+        return {
+            apiKey: this.config.apiKey,
+            apiUrl: this.config.apiUrl,
+            dataPlaneDomain: this.config.dataPlaneDomain,
+            requestTimeoutMs: this.config.requestTimeoutMs,
+            ...opts,
+        };
+    }
+}
+function volumeFromPayload(payload, config, control) {
+    const info = volumeInfo(record(payload.volume ?? payload));
+    return new Volume({
+        volumeId: info.volumeId,
+        name: info.name,
+        token: info.token,
+        connectionConfig: config,
+        control,
+    });
+}
+function volumeInfo(payload) {
+    const id = payload.volume_id ?? payload.volumeId ?? payload.id;
+    if (id === undefined)
+        throw new SandboxError('volume response did not include id');
+    return {
+        volumeId: String(id),
+        id: String(id),
+        name: String(payload.name ?? id),
+        state: stringValue(payload.state),
+        token: stringValue(payload.token),
+        sizeMb: numberValue(payload.size_mb ?? payload.sizeMb),
+        sizeBytes: numberValue(payload.size_bytes ?? payload.sizeBytes),
+        node: stringValue(payload.node ?? payload.node_name ?? payload.nodeName),
+        metadata: recordOfStrings(payload.metadata),
+        createdAt: stringValue(payload.created_at ?? payload.createdAt),
+        updatedAt: stringValue(payload.updated_at ?? payload.updatedAt),
+        raw: payload,
+    };
+}
+function volumeEntry(payload) {
+    return {
+        path: String(payload.path ?? ''),
+        name: String(payload.name ?? ''),
+        type: String(payload.type ?? 'file'),
+        size: numberValue(payload.size ?? payload.bytes),
+        mode: numberValue(payload.mode),
+        uid: numberValue(payload.uid),
+        gid: numberValue(payload.gid),
+        atime: payload.atime,
+        mtime: payload.mtime,
+        ctime: payload.ctime,
+        raw: payload,
+    };
+}
+async function bytesFromWriteData(data) {
+    if (typeof data === 'string')
+        return new TextEncoder().encode(data);
+    if (data instanceof Uint8Array)
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (data instanceof Blob)
+        return new Uint8Array(await data.arrayBuffer());
+    throw new SandboxError('unsupported volume write data');
+}
+function metadataPayload(opts) {
+    return compactRecord({
+        uid: opts.uid,
+        gid: opts.gid,
+        mode: opts.mode,
+    });
+}
+function compactRecord(payload) {
+    return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));
+}
+function record(value) {
+    return value && typeof value === 'object' ? value : {};
+}
+function recordOfStrings(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, String(item)]));
+}
+function stringValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return String(value);
+    return undefined;
+}
+function numberValue(value) {
+    return typeof value === 'number' ? value : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watasu/sdk",
-  "version": "0.1.25",
+  "version": "0.1.30",
   "type": "module",
   "license": "MIT OR Apache-2.0",
   "description": "TypeScript SDK for Watasu",