@watasu/sdk 0.1.30 → 0.1.50

package/dist/processSocket.d.ts

@@ -5,22 +5,35 @@ export declare class ProcessSocket implements AsyncIterable<ProcessFrame> {
     private readonly token;
     private readonly path;
     private readonly requestTimeoutMs;
+    private readonly headers;
     private ws?;
     private queue;
     private waiters;
+    private ackWaiters;
     private closed;
     private keepalive?;
-    constructor(baseUrl: string, token: string, path: string, requestTimeoutMs?: number);
+    constructor(baseUrl: string, token: string, path: string, requestTimeoutMs?: number, headers?: Record<string, string>);
     connect(): Promise<this>;
-    sendJson(payload: ProcessFrame): void;
-    sendStdin(data: string | Uint8Array): void;
-    closeStdin(): void;
+    sendJson(payload: ProcessFrame): Promise<void>;
+    sendStdin(data: string | Uint8Array, opts?: {
+        requestTimeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    closeStdin(opts?: {
+        requestTimeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
     close(): void;
     [Symbol.asyncIterator](): AsyncIterator<ProcessFrame>;
     private next;
     private onMessage;
     private finish;
     private flushDone;
+    private waitForControlAck;
+    private resolveControlAck;
+    private rejectControlAcks;
+    private removeControlAck;
+    private removeSignalListener;
 }
 export declare function base64Encode(bytes: Uint8Array): string;
 export declare function base64DecodeText(value: unknown): string;

package/dist/processSocket.js

@@ -8,20 +8,23 @@ export class ProcessSocket {
     token;
     path;
     requestTimeoutMs;
+    headers;
     ws;
     queue = [];
     waiters = [];
+    ackWaiters = new Map();
     closed = false;
     keepalive;
-    constructor(baseUrl, token, path, requestTimeoutMs = 60_000) {
+    constructor(baseUrl, token, path, requestTimeoutMs = 60_000, headers = {}) {
         this.baseUrl = baseUrl;
         this.token = token;
         this.path = path;
         this.requestTimeoutMs = requestTimeoutMs;
+        this.headers = headers;
     }
     async connect() {
         const ws = new WebSocket(wsUrl(this.baseUrl, this.path), {
-            headers: { Authorization: `Bearer ${this.token}` },
+            headers: { ...this.headers, Authorization: `Bearer ${this.token}` },
         });
         this.ws = ws;
         ws.on('message', (data) => this.onMessage(data));
@@ -45,18 +48,41 @@ export class ProcessSocket {
         }, KEEPALIVE_PING_INTERVAL_SEC * 1000);
         return this;
     }
-    sendJson(payload) {
+    async sendJson(payload) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
             throw new SandboxError('process websocket is not connected');
         }
-        this.ws.send(JSON.stringify(payload));
+        await new Promise((resolve, reject) => {
+            this.ws.send(JSON.stringify(payload), (error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
     }
-    sendStdin(data) {
+    async sendStdin(data, opts = {}) {
         const raw = typeof data === 'string' ? new TextEncoder().encode(data) : data;
-        this.sendJson({ type: 'stdin', data: base64Encode(raw) });
+        const ack = this.waitForControlAck('stdin_ack', opts);
+        try {
+            await this.sendJson({ type: 'stdin', data: base64Encode(raw) });
+            await ack.promise;
+        }
+        catch (error) {
+            ack.cancel();
+            throw error;
+        }
     }
-    closeStdin() {
-        this.sendJson({ type: 'close_stdin' });
+    async closeStdin(opts = {}) {
+        const ack = this.waitForControlAck('close_stdin_ack', opts);
+        try {
+            await this.sendJson({ type: 'close_stdin' });
+            await ack.promise;
+        }
+        catch (error) {
+            ack.cancel();
+            throw error;
+        }
     }
     close() {
         this.closed = true;
@@ -84,6 +110,10 @@ export class ProcessSocket {
             const frame = JSON.parse(text);
             if (frame.type === 'pong' || frame.type === 'ready')
                 return;
+            if (frame.type === 'stdin_ack' || frame.type === 'close_stdin_ack') {
+                this.resolveControlAck(String(frame.type));
+                return;
+            }
             if (frame.type === 'error') {
                 this.finish(new SandboxError(String(frame.message ?? frame.code ?? 'process error')));
                 return;
@@ -110,6 +140,7 @@ export class ProcessSocket {
             else
                 this.queue.push(frame);
         }
+        this.rejectControlAcks(error ?? new SandboxError('process websocket closed before acknowledgement'));
         this.flushDone();
     }
     flushDone() {
@@ -117,6 +148,79 @@ export class ProcessSocket {
             waiter({ done: true, value: undefined });
         }
     }
+    waitForControlAck(type, opts = {}) {
+        if (opts.signal?.aborted) {
+            return {
+                promise: Promise.reject(new SandboxError('process control acknowledgement aborted')),
+                cancel: () => { },
+            };
+        }
+        let entry;
+        const promise = new Promise((resolve, reject) => {
+            const rejectWithAbort = () => {
+                this.removeControlAck(type, entry);
+                clearTimeout(entry.timer);
+                reject(new SandboxError('process control acknowledgement aborted'));
+            };
+            const timer = setTimeout(() => {
+                this.removeControlAck(type, entry);
+                this.removeSignalListener(entry);
+                reject(new TimeoutError());
+            }, opts.requestTimeoutMs ?? this.requestTimeoutMs);
+            entry = { resolve, reject, timer, signal: opts.signal };
+            if (opts.signal) {
+                entry.abort = rejectWithAbort;
+                opts.signal.addEventListener('abort', rejectWithAbort, { once: true });
+            }
+            const waiters = this.ackWaiters.get(type) ?? [];
+            waiters.push(entry);
+            this.ackWaiters.set(type, waiters);
+        });
+        return {
+            promise,
+            cancel: () => {
+                this.removeControlAck(type, entry);
+                clearTimeout(entry.timer);
+                if (entry.abort)
+                    opts.signal?.removeEventListener('abort', entry.abort);
+            },
+        };
+    }
+    resolveControlAck(type) {
+        const entry = this.ackWaiters.get(type)?.shift();
+        if (!entry)
+            return;
+        clearTimeout(entry.timer);
+        if (entry.abort)
+            this.removeSignalListener(entry);
+        entry.resolve();
+    }
+    rejectControlAcks(error) {
+        for (const waiters of this.ackWaiters.values()) {
+            for (const entry of waiters.splice(0)) {
+                clearTimeout(entry.timer);
+                if (entry.abort)
+                    this.removeSignalListener(entry);
+                entry.reject(error);
+            }
+        }
+        this.ackWaiters.clear();
+    }
+    removeControlAck(type, entry) {
+        const waiters = this.ackWaiters.get(type);
+        if (!waiters)
+            return;
+        const index = waiters.indexOf(entry);
+        if (index !== -1)
+            waiters.splice(index, 1);
+        if (waiters.length === 0)
+            this.ackWaiters.delete(type);
+    }
+    removeSignalListener(entry) {
+        if (entry.abort)
+            entry.signal?.removeEventListener('abort', entry.abort);
+        entry.abort = undefined;
+    }
 }
 export function base64Encode(bytes) {
     return Buffer.from(bytes).toString('base64');

package/dist/pty.d.ts

@@ -1,5 +1,5 @@
 import { CommandHandle, CommandStartOpts } from './commands.js';
-import { ConnectionConfig } from './connectionConfig.js';
+import { ConnectionConfig, type ConnectionOpts } from './connectionConfig.js';
 import { DataPlaneClient } from './transport.js';
 export interface PtySize {
     cols: number;
@@ -28,10 +28,10 @@ export declare class Pty {
     connect(pid: number | string, opts?: PtyConnectOpts): Promise<CommandHandle>;
     /** Send input bytes or text to a PTY. */
     sendStdin(pid: number | string, data: string | Uint8Array, opts?: PtyConnectOpts): Promise<void>;
-    /** Alias for `sendStdin`. */
+    /** Send input bytes or text to a PTY. */
     sendInput(pid: number | string, data: string | Uint8Array, opts?: PtyConnectOpts): Promise<void>;
     /** Resize a running PTY. */
     resize(pid: number | string, size: PtySize, opts?: PtyConnectOpts): Promise<void>;
     /** Kill a running PTY. */
-    kill(pid: number | string): Promise<boolean>;
+    kill(pid: number | string, opts?: Pick<ConnectionOpts, 'requestTimeoutMs' | 'signal'>): Promise<boolean>;
 }

package/dist/pty.js

@@ -11,21 +11,21 @@ export class Pty {
     }
     /** Create an interactive shell PTY and return its live command handle. */
     async create(opts) {
-        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, '/runtime/v1/process', opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
-        const envs = { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', ...(opts.envVars ?? opts.envs ?? {}) };
+        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, '/runtime/v1/process', opts.requestTimeoutMs ?? this.config.requestTimeoutMs, this.config.headers).connect();
+        const envs = { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', ...(opts.envs ?? {}) };
         const size = opts.size ?? { cols: opts.cols ?? 80, rows: opts.rows ?? 24 };
         const args = opts.cmd === undefined ? ['-i', '-l'] : ['-l', '-c', opts.cmd];
-        socket.sendJson({
+        await socket.sendJson({
             type: 'start',
             cmd: '/bin/bash',
             args,
-            cwd: opts.cwd ?? opts.rootDir,
+            cwd: opts.cwd,
             user: opts.user,
             environment: envs,
             envs,
             stdin: true,
             pty: { cols: size.cols, rows: size.rows },
-            timeout_ms: opts.timeoutMs ?? opts.timeout ?? 60_000,
+            timeout_ms: opts.timeoutMs ?? 60_000,
         });
         const first = await nextStarted(socket);
         const pid = framePid(first);
@@ -35,7 +35,7 @@ export class Pty {
     }
     /** Connect to a running PTY by pid. */
     async connect(pid, opts = {}) {
-        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, `/runtime/v1/process/${pid}/connect?since=0`, opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
+        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, `/runtime/v1/process/${pid}/connect?since=0`, opts.requestTimeoutMs ?? this.config.requestTimeoutMs, this.config.headers).connect();
         const first = await nextStarted(socket);
         const actualPid = framePid(first) ?? pid;
         return new CommandHandle(actualPid, socket, () => this.kill(actualPid), withFirst(first, socket), undefined, undefined, opts.onData);
@@ -50,7 +50,7 @@ export class Pty {
             await handle.disconnect();
         }
     }
-    /** Alias for `sendStdin`. */
+    /** Send input bytes or text to a PTY. */
     async sendInput(pid, data, opts = {}) {
         return this.sendStdin(pid, data, opts);
     }
@@ -65,9 +65,11 @@ export class Pty {
         }
     }
     /** Kill a running PTY. */
-    async kill(pid) {
+    async kill(pid, opts = {}) {
         await this.dataPlane.postJson(`/runtime/v1/process/${pid}/signal`, {
             json: { signal: 'SIGKILL' },
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return true;
     }

package/dist/sandbox.d.ts

@@ -6,6 +6,8 @@ import { Git } from './git.js';
 import { Pty } from './pty.js';
 import { ProcessManager } from './process.js';
 import { TerminalManager } from './terminal.js';
+import type { Volume } from './volume.js';
+export declare const ALL_TRAFFIC = "0.0.0.0/0";
 export interface SandboxCreateOpts extends ConnectionOpts {
     /** Template slug to create. Defaults to "base". */
     template?: string;
@@ -22,7 +24,7 @@ export interface SandboxCreateOpts extends ConnectionOpts {
     /** Timeout lifecycle policy. Defaults to killing the sandbox at timeout. */
     lifecycle?: SandboxLifecycle;
     /** Persistent volumes to mount, keyed by guest path. */
-    volumeMounts?: Record<string, string | {
+    volumeMounts?: Record<string, string | Volume | {
         name: string;
     }>;
 }
@@ -30,7 +32,18 @@ export interface SandboxLifecycle {
     onTimeout: 'kill' | 'pause';
     autoResume?: boolean;
 }
-export type SandboxNetworkSelector = string | string[];
+export type SandboxNetworkTransform = {
+    headers?: Record<string, string>;
+};
+export type SandboxNetworkRule = {
+    transform?: SandboxNetworkTransform;
+};
+export type SandboxNetworkRules = Record<string, SandboxNetworkRule[]> | Map<string, SandboxNetworkRule[]>;
+export interface SandboxNetworkSelectorContext {
+    allTraffic: string;
+    rules: Map<string, SandboxNetworkRule[]>;
+}
+export type SandboxNetworkSelector = string | string[] | ((ctx: SandboxNetworkSelectorContext) => string[]);
 export interface SandboxNetworkUpdate {
     allowOut?: SandboxNetworkSelector;
     denyOut?: SandboxNetworkSelector;
@@ -40,9 +53,15 @@ export interface SandboxNetworkUpdate {
     egressProfile?: string;
     egressProfiles?: string[];
     networkClass?: string;
-    rules?: unknown;
+    rules?: SandboxNetworkRules;
     maskRequestHost?: string;
 }
+export type SandboxNetworkOpts = SandboxNetworkUpdate;
+export type SandboxNetworkInfo = SandboxNetworkUpdate;
+export type SandboxNetworkRuleInfo = Record<string, unknown>;
+export type SandboxOpts = SandboxCreateOpts;
+export type SandboxApiOpts = ConnectionOpts;
+export type SandboxState = string;
 export interface SandboxNetworkUpdateOpts extends ConnectionOpts {
 }
 export interface SandboxConnectOpts extends ConnectionOpts {
@@ -62,6 +81,7 @@ export interface SandboxListOpts extends ConnectionOpts {
     /** Team slug to list within. */
     team?: string;
 }
+type SandboxRequestOpts = Pick<ConnectionOpts, 'requestTimeoutMs' | 'signal'>;
 export interface SandboxInfo {
     sandboxId: string;
     templateId?: string;
@@ -138,9 +158,19 @@ export interface SnapshotListOpts extends ConnectionOpts {
 export interface RestoreSnapshotOpts extends ConnectionOpts {
     checkpointId?: string | number;
     snapshotId?: string | number;
-    timeout?: number;
     timeoutMs?: number;
 }
+export interface SignatureOpts {
+    path: string;
+    operation: 'read' | 'write';
+    user?: string;
+    expirationInSeconds?: number;
+    envdAccessToken?: string;
+}
+export declare function getSignature({ path, operation, user, expirationInSeconds, envdAccessToken, }: SignatureOpts): Promise<{
+    signature: string;
+    expiration: number | null;
+}>;
 /** Paginator for listing sandbox snapshots. */
 export declare class SnapshotPaginator {
     private readonly opts;
@@ -172,14 +202,12 @@ export declare class Sandbox {
     /** Default sandbox lifetime in milliseconds. */
     static readonly defaultSandboxTimeoutMs = 300000;
     files: Filesystem;
-    filesystem: Filesystem;
     commands: Commands;
     process: ProcessManager;
     pty: Pty;
     terminal: TerminalManager;
     git: Git;
     cwd: string | undefined;
-    envVars: Record<string, string>;
     readonly sandboxId: string;
     private readonly mcpPort;
     private mcpToken;
@@ -196,24 +224,19 @@ export declare class Sandbox {
         sandbox?: Record<string, unknown>;
         envs?: Record<string, string>;
     });
-    /** Sandbox id alias used by SDK-compatible code. */
+    /** Unique sandbox identifier. */
     get id(): string;
     static create(opts?: SandboxCreateOpts): Promise<Sandbox>;
     static create(template: string, opts?: SandboxCreateOpts): Promise<Sandbox>;
     /** Connect to an existing sandbox and return it with a fresh data-plane session. */
     static connect(sandboxId: string, opts?: SandboxConnectOpts): Promise<Sandbox>;
-    /** Alias for `connect`. */
-    static reconnect(sandboxId: string, opts?: SandboxConnectOpts): Promise<Sandbox>;
-    static reconnect(opts: SandboxConnectOpts & {
-        sandboxID: string;
-    }): Promise<Sandbox>;
     /** Refresh this sandbox's data-plane session in place. */
     connect(opts?: SandboxConnectOpts): Promise<this>;
     /** Resume a paused sandbox by id. */
     static resume(sandboxId: string, opts?: SandboxConnectOpts): Promise<boolean>;
     /** Pause a sandbox by id. Returns false when it was already paused. */
     static betaPause(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
-    /** Alias for `betaPause`. */
+    /** Pause a sandbox by id. */
     static pause(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy a sandbox by id. */
     static kill(sandboxId: string, opts?: ConnectionOpts | string): Promise<boolean>;
@@ -222,8 +245,6 @@ export declare class Sandbox {
     /** Atomically replace a sandbox's network egress policy by id. */
     static updateNetwork(sandboxId: string, network: SandboxNetworkUpdate, opts?: SandboxNetworkUpdateOpts): Promise<void>;
     private static putNetwork;
-    /** Deprecated alias for `getInfo`. */
-    static getFullInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     /** Create a Watasu checkpoint using snapshot naming. */
     static createSnapshot(sandboxId: string, opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
     /** List snapshots visible to the configured API key. */
@@ -231,27 +252,25 @@ export declare class Sandbox {
     /** Delete a snapshot by id. Returns `false` when the snapshot does not exist. */
     static deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy this sandbox. */
-    kill(): Promise<boolean>;
+    kill(opts?: SandboxRequestOpts): Promise<boolean>;
     /** Check if this sandbox is in a runtime-active lifecycle state. */
-    isRunning(opts?: Pick<ConnectionOpts, 'requestTimeoutMs'>): Promise<boolean>;
+    isRunning(opts?: SandboxRequestOpts): Promise<boolean>;
     /** Set a sandbox's lifetime by id. */
     static setTimeout(sandboxId: string, timeoutMs: number, opts?: ConnectionOpts): Promise<void>;
     /** Set this sandbox's lifetime. */
-    setTimeout(timeoutMs: number): Promise<void>;
-    /** Keep the sandbox alive for `duration` milliseconds. */
-    keepAlive(duration: number): Promise<void>;
+    setTimeout(timeoutMs: number, opts?: SandboxRequestOpts): Promise<void>;
     /** Fetch control-plane metadata for a sandbox by id. */
     static getInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
+    /** Fetch full control-plane metadata for a sandbox by id. */
+    static getFullInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     /** Fetch the latest control-plane metadata for this sandbox. */
-    getInfo(): Promise<SandboxInfo>;
+    getInfo(opts?: SandboxRequestOpts): Promise<SandboxInfo>;
     /** Fetch latest sandbox metrics. */
     getMetrics(opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>;
     /** Create a Watasu checkpoint using snapshot naming. */
     createSnapshot(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
     /** Delete a snapshot by id. */
     deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<boolean>;
-    /** Watasu-native alias for `createSnapshot`. */
-    checkpoint(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
     /** List checkpoints for this sandbox using snapshot naming. */
     listSnapshots(opts?: Omit<SnapshotListOpts, 'sandboxId'>): SnapshotPaginator;
     /** Restore a checkpoint into a new sandbox and return its control-plane info. */
@@ -260,16 +279,10 @@ export declare class Sandbox {
     static list(opts?: SandboxListOpts | string): SandboxPaginator;
     /** Return the public hostname for an exposed sandbox port. */
     getHost(port: number): string;
-    /** Return the public hostname for the sandbox or an exposed sandbox port. */
-    getHostname(port?: number): string;
     /** Return the conventional MCP URL for this sandbox. */
     getMcpUrl(): string;
     /** Return the MCP gateway token when the sandbox contains one. */
     getMcpToken(): Promise<string | undefined>;
-    /** Return a protocol string for a secure or insecure sandbox URL. */
-    getProtocol(baseProtocol?: string, secure?: boolean): string;
-    /** Close the local SDK attachment. This does not destroy the sandbox. */
-    close(): Promise<void>;
     /** Get a signed URL that accepts a POST upload for a sandbox file path. */
     uploadUrl(path?: string, opts?: SandboxUrlOpts): Promise<string>;
     /** Get a signed URL that accepts a GET download for a sandbox file path. */
@@ -282,7 +295,7 @@ export declare class Sandbox {
     updateNetwork(network: SandboxNetworkUpdate, opts?: SandboxNetworkUpdateOpts): Promise<void>;
     /** Pause this sandbox. Returns false when it was already paused. */
     betaPause(opts?: ConnectionOpts): Promise<boolean>;
-    /** Alias for `betaPause`. */
+    /** Pause this sandbox. Returns false when it was already paused. */
     pause(opts?: ConnectionOpts): Promise<boolean>;
     /** Resume this sandbox and refresh its data-plane session. */
     resume(opts?: SandboxConnectOpts): Promise<boolean>;
@@ -295,3 +308,4 @@ export declare class Sandbox {
     protected runtimeDeleteJson(path: string, opts?: ConnectionOpts): Promise<Record<string, unknown>>;
     private configOptions;
 }
+export {};