@watasu/sdk 0.1.5 → 0.1.24

package/dist/sandbox.js

@@ -1,33 +1,96 @@
 import { Commands } from './commands.js';
 import { ConnectionConfig, SESSION_OPERATION_REQUEST_TIMEOUT_MS } from './connectionConfig.js';
 import { DataPlaneClient, ControlClient } from './transport.js';
-import { NotFoundError, SandboxError, unsupported } from './errors.js';
+import { ConflictError, FileNotFoundError, NotFoundError, SandboxError, unsupported } from './errors.js';
 import { Filesystem } from './filesystem.js';
+import { Git } from './git.js';
+import { Pty } from './pty.js';
+import { ProcessManager } from './process.js';
+import { TerminalManager } from './terminal.js';
+/** Paginator for listing sandbox snapshots. */
 export class SnapshotPaginator {
-    loadItems;
-    consumed = false;
+    opts;
     hasNext = true;
     nextToken;
-    constructor(loadItems) {
-        this.loadItems = loadItems;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.nextToken = opts.nextToken;
     }
-    async nextItems() {
-        if (this.consumed)
+    /** Fetch the next page of snapshot metadata. */
+    async nextItems(opts = {}) {
+        if (!this.hasNext)
             throw new SandboxError('No more snapshots to fetch');
-        this.consumed = true;
-        this.hasNext = false;
-        return this.loadItems();
+        const config = new ConnectionConfig({ ...this.opts, ...opts });
+        const control = new ControlClient(config);
+        const payload = await control.get(snapshotListPath(this.opts, this.nextToken), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        this.nextToken = stringValue(payload.next_token ?? payload.nextToken);
+        this.hasNext = this.nextToken !== undefined;
+        const snapshots = Array.isArray(payload.snapshots)
+            ? payload.snapshots
+            : Array.isArray(payload.sandbox_checkpoints) ? payload.sandbox_checkpoints : [];
+        return snapshots.map((item) => snapshotInfo(record(item)));
+    }
+    /** Drain all remaining pages into one list. */
+    async listItems(opts = {}) {
+        const items = [];
+        while (this.hasNext)
+            items.push(...await this.nextItems(opts));
+        return items;
+    }
+}
+/** Paginator for listing sandboxes. */
+export class SandboxPaginator {
+    opts;
+    hasNext = true;
+    nextToken;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.nextToken = opts.nextToken;
+    }
+    /** Fetch the next page of sandbox metadata. */
+    async nextItems(opts = {}) {
+        if (!this.hasNext)
+            throw new SandboxError('No more sandboxes to fetch');
+        const config = new ConnectionConfig({ ...this.opts, ...opts });
+        const control = new ControlClient(config);
+        const payload = await control.get(sandboxListPath(this.opts, this.nextToken), {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        this.nextToken = stringValue(payload.next_token ?? payload.nextToken);
+        this.hasNext = this.nextToken !== undefined;
+        const sandboxes = Array.isArray(payload.sandboxes) ? payload.sandboxes : [];
+        return sandboxes.map((item) => sandboxInfo(record(item)));
+    }
+    /** Drain all remaining pages into one list. */
+    async listItems(opts = {}) {
+        const items = [];
+        while (this.hasNext)
+            items.push(...await this.nextItems(opts));
+        return items;
     }
 }
 /** Running Watasu sandbox with ready `files` and `commands` helpers. */
 export class Sandbox {
     /** Default template slug used when create is called without a template. */
     static defaultTemplate = 'base';
+    /** Default template slug used by MCP creation once Watasu supports it. */
+    static defaultMcpTemplate = 'mcp-gateway';
+    /** Default sandbox lifetime in milliseconds. */
+    static defaultSandboxTimeoutMs = 300_000;
     files;
+    filesystem;
     commands;
+    process;
+    pty;
+    terminal;
+    git;
+    cwd;
+    envVars;
     sandboxId;
-    pty = { create: () => unsupported('sandbox.pty') };
-    git = { clone: () => unsupported('sandbox.git') };
+    mcpPort = 50005;
+    mcpToken;
     config;
     control;
     envs;
@@ -38,32 +101,42 @@ export class Sandbox {
         this.config = opts.connectionConfig;
         this.control = opts.control ?? new ControlClient(this.config);
         this.envs = opts.envs ?? {};
+        this.envVars = this.envs;
         this.sandbox = opts.sandbox ?? {};
         const dataPlane = dataPlaneFromSession(opts.session, this.config);
         this.dataPlane = dataPlane;
         this.files = new Filesystem(dataPlane);
+        this.filesystem = this.files;
         this.commands = new Commands(dataPlane, this.config, this.envs);
+        this.process = new ProcessManager(this.commands);
+        this.pty = new Pty(dataPlane, this.config);
+        this.terminal = new TerminalManager(this.pty);
+        this.git = new Git(dataPlane);
+    }
+    /** Sandbox id alias used by SDK-compatible code. */
+    get id() {
+        return this.sandboxId;
     }
     /** Create a sandbox and return it only after the API supplies a data-plane session. */
     static async create(templateOrOpts, opts = {}) {
+        const sandboxOpts = typeof templateOrOpts === 'string' ? opts : templateOrOpts ?? {};
         const template = typeof templateOrOpts === 'string'
             ? templateOrOpts
-            : templateOrOpts?.template ?? Sandbox.defaultTemplate;
-        const sandboxOpts = typeof templateOrOpts === 'string' ? opts : templateOrOpts ?? {};
-        if (sandboxOpts.mcp !== undefined)
-            unsupported('mcp');
+            : templateOrOpts?.template ?? (sandboxOpts.mcp === undefined ? Sandbox.defaultTemplate : undefined);
         if (sandboxOpts.volumeMounts !== undefined)
             unsupported('volumeMounts');
         const config = new ConnectionConfig(sandboxOpts);
         const control = new ControlClient(config);
         const sandboxPayload = {
-            template_id: template,
             timeout: Math.ceil((sandboxOpts.timeoutMs ?? 300_000) / 1000),
             metadata: sandboxOpts.metadata ?? {},
             env_vars: sandboxOpts.envs ?? {},
             secure: sandboxOpts.secure ?? true,
             allow_internet_access: sandboxOpts.allowInternetAccess ?? true,
         };
+        putIfPresent(sandboxPayload, 'template_id', template);
+        putIfPresent(sandboxPayload, 'mcp', sandboxOpts.mcp);
+        Object.assign(sandboxPayload, networkUpdatePayload(sandboxOpts.network));
         putIfPresent(sandboxPayload, 'team', sandboxOpts.team);
         const response = await control.post('/sandboxes', {
             json: sandboxPayload,
@@ -73,7 +146,7 @@ export class Sandbox {
         const sandboxId = sandbox.id ?? sandbox.sandbox_id;
         if (sandboxId === undefined)
             throw new SandboxError('create response did not include sandbox id');
-        return new Sandbox({
+        const sandboxInstance = new Sandbox({
             sandboxId: String(sandboxId),
             connectionConfig: config,
             control,
@@ -81,13 +154,14 @@ export class Sandbox {
             sandbox,
             envs: sandboxOpts.envs,
         });
+        return sandboxInstance;
     }
     /** Connect to an existing sandbox and return it with a fresh data-plane session. */
     static async connect(sandboxId, opts = {}) {
         const config = new ConnectionConfig(opts);
         const control = new ControlClient(config);
         const info = await control.get(`/sandboxes/${sandboxId}`);
-        const response = await control.post(`/sandboxes/${sandboxId}/connect`, {
+        const response = await control.post(`/sandboxes/${sandboxId}/resume`, {
             json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(config, opts),
         });
@@ -99,9 +173,14 @@ export class Sandbox {
             sandbox: record(response.sandbox ?? info.sandbox ?? {}),
         });
     }
+    static async reconnect(sandboxOrOpts, opts = {}) {
+        if (typeof sandboxOrOpts === 'string')
+            return this.connect(sandboxOrOpts, opts);
+        return this.connect(sandboxOrOpts.sandboxID, sandboxOrOpts);
+    }
     /** Refresh this sandbox's data-plane session in place. */
     async connect(opts = {}) {
-        const response = await this.control.post(`/sandboxes/${this.sandboxId}/connect`, {
+        const response = await this.control.post(`/sandboxes/${this.sandboxId}/resume`, {
             json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(this.config, opts),
         });
@@ -109,12 +188,41 @@ export class Sandbox {
         const dataPlane = dataPlaneFromSession(response.session, this.config);
         this.dataPlane = dataPlane;
         this.files = new Filesystem(dataPlane);
+        this.filesystem = this.files;
         this.commands = new Commands(dataPlane, this.config, this.envs);
+        this.process = new ProcessManager(this.commands);
+        this.pty = new Pty(dataPlane, this.config);
+        this.terminal = new TerminalManager(this.pty);
+        this.git = new Git(dataPlane);
         return this;
     }
+    /** Resume a paused sandbox by id. */
+    static async resume(sandboxId, opts = {}) {
+        await Sandbox.connect(sandboxId, opts);
+        return true;
+    }
+    /** Pause a sandbox by id. Returns false when it was already paused. */
+    static async betaPause(sandboxId, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        try {
+            await control.post(`/sandboxes/${sandboxId}/pause`, {
+                requestTimeoutMs: opts.requestTimeoutMs,
+            });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof ConflictError)
+                return false;
+            throw error;
+        }
+    }
+    /** Alias for `betaPause`. */
+    static async pause(sandboxId, opts = {}) {
+        return this.betaPause(sandboxId, opts);
+    }
     /** Destroy a sandbox by id. */
     static async kill(sandboxId, opts = {}) {
-        const control = new ControlClient(new ConnectionConfig(opts));
+        const control = new ControlClient(new ConnectionConfig(typeof opts === 'string' ? { apiKey: opts } : opts));
         await control.delete(`/sandboxes/${sandboxId}`);
         return true;
     }
@@ -126,6 +234,18 @@ export class Sandbox {
         });
         return metricsList(payload.metrics ?? payload);
     }
+    /** Atomically replace a sandbox's network egress policy by id. */
+    static async updateNetwork(sandboxId, network, opts = {}) {
+        await this.putNetwork(sandboxId, network, opts);
+    }
+    static async putNetwork(sandboxId, network, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        const response = await control.put(`/sandboxes/${sandboxId}/network`, {
+            json: networkUpdatePayload(network),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return response.sandbox === undefined ? undefined : record(response.sandbox);
+    }
     /** Deprecated alias for `getInfo`. */
     static async getFullInfo(sandboxId, opts = {}) {
         return this.getInfo(sandboxId, opts);
@@ -133,26 +253,30 @@ export class Sandbox {
     /** Create a Watasu checkpoint using snapshot naming. */
     static async createSnapshot(sandboxId, opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
-        const payload = await control.post(`/sandboxes/${sandboxId}/checkpoints`, {
+        const payload = await control.post(`/sandboxes/${sandboxId}/snapshots`, {
             json: snapshotPayload(opts),
             requestTimeoutMs: opts.requestTimeoutMs,
         });
         return snapshotInfo(record(payload.sandbox_checkpoint ?? payload.snapshot ?? payload));
     }
-    /** List checkpoints for one sandbox using snapshot naming. */
-    static listSnapshots(sandboxId, opts = {}) {
-        return new SnapshotPaginator(async () => {
-            const control = new ControlClient(new ConnectionConfig(opts));
-            const payload = await control.get(`/sandboxes/${sandboxId}/checkpoints`, {
+    /** List snapshots visible to the configured API key. */
+    static listSnapshots(opts = {}) {
+        return new SnapshotPaginator(opts);
+    }
+    /** Delete a snapshot by id. Returns `false` when the snapshot does not exist. */
+    static async deleteSnapshot(snapshotId, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        try {
+            await control.delete(`/sandbox_snapshots/${snapshotId}`, {
                 requestTimeoutMs: opts.requestTimeoutMs,
             });
-            const snapshots = Array.isArray(payload.sandbox_checkpoints) ? payload.sandbox_checkpoints : [];
-            return snapshots.map((item) => snapshotInfo(record(item)));
-        });
-    }
-    /** Snapshot deletion is not backed by a Watasu checkpoint delete API yet. */
-    static deleteSnapshot(..._args) {
-        unsupported('Sandbox.deleteSnapshot');
+            return true;
+        }
+        catch (error) {
+            if (error instanceof NotFoundError)
+                return false;
+            throw error;
+        }
     }
     /** Destroy this sandbox. */
     async kill() {
@@ -187,6 +311,10 @@ export class Sandbox {
             json: { timeout: Math.ceil(timeoutMs / 1000) },
         });
     }
+    /** Keep the sandbox alive for `duration` milliseconds. */
+    async keepAlive(duration) {
+        await this.setTimeout(duration);
+    }
     /** Fetch control-plane metadata for a sandbox by id. */
     static async getInfo(sandboxId, opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
@@ -206,13 +334,17 @@ export class Sandbox {
     async createSnapshot(opts = {}) {
         return Sandbox.createSnapshot(this.sandboxId, { ...this.configOptions(), ...opts });
     }
+    /** Delete a snapshot by id. */
+    async deleteSnapshot(snapshotId, opts = {}) {
+        return Sandbox.deleteSnapshot(snapshotId, { ...this.configOptions(), ...opts });
+    }
     /** Watasu-native alias for `createSnapshot`. */
     async checkpoint(opts = {}) {
         return this.createSnapshot(opts);
     }
     /** List checkpoints for this sandbox using snapshot naming. */
     listSnapshots(opts = {}) {
-        return Sandbox.listSnapshots(this.sandboxId, { ...this.configOptions(), ...opts });
+        return Sandbox.listSnapshots({ ...this.configOptions(), ...opts, sandboxId: this.sandboxId });
     }
     /** Restore a checkpoint into a new sandbox and return its control-plane info. */
     async restore(opts = {}) {
@@ -233,12 +365,10 @@ export class Sandbox {
         });
         return sandboxInfo(record(response.sandbox ?? response));
     }
-    /** List sandboxes visible to the configured API key. */
-    static async list(opts = {}) {
-        const control = new ControlClient(new ConnectionConfig(opts));
-        const payload = await control.get(opts.team ? `/sandboxes?team=${encodeURIComponent(opts.team)}` : '/sandboxes');
-        const sandboxes = Array.isArray(payload.sandboxes) ? payload.sandboxes : [];
-        return sandboxes.map((item) => sandboxInfo(record(item)));
+    /** Return a paginator for sandboxes visible to the configured API key. */
+    static list(opts = {}) {
+        const listOpts = typeof opts === 'string' ? { apiKey: opts } : opts;
+        return new SandboxPaginator(listOpts);
     }
     /** Return the public hostname for an exposed sandbox port. */
     getHost(port) {
@@ -249,10 +379,85 @@ export class Sandbox {
             throw new SandboxError('port response did not include host or url');
         return `p${port}-${routeToken}.sandbox.${this.config.dataPlaneDomain}`;
     }
-    updateNetwork(..._args) { unsupported('Sandbox.updateNetwork'); }
-    pause() { unsupported('Sandbox.pause'); }
-    betaPause() { unsupported('Sandbox.betaPause'); }
-    resume() { unsupported('Sandbox.resume'); }
+    /** Return the public hostname for the sandbox or an exposed sandbox port. */
+    getHostname(port) {
+        if (port !== undefined)
+            return this.getHost(port);
+        return new URL(this.dataPlane.baseUrl).host;
+    }
+    /** Return the conventional MCP URL for this sandbox. */
+    getMcpUrl() {
+        return `https://${this.getHost(this.mcpPort)}/mcp`;
+    }
+    /** Return the MCP gateway token when the sandbox contains one. */
+    async getMcpToken() {
+        if (this.mcpToken !== undefined)
+            return this.mcpToken;
+        try {
+            const token = await this.files.read('/etc/mcp-gateway/.token', { user: 'root' });
+            this.mcpToken = String(token).trim() || undefined;
+            return this.mcpToken;
+        }
+        catch (error) {
+            if (error instanceof FileNotFoundError || error instanceof NotFoundError)
+                return undefined;
+            throw error;
+        }
+    }
+    /** Return a protocol string for a secure or insecure sandbox URL. */
+    getProtocol(baseProtocol = 'http', secure = true) {
+        return `${baseProtocol}${secure ? 's' : ''}`;
+    }
+    /** Close the local SDK attachment. This does not destroy the sandbox. */
+    async close() { }
+    /** Get a signed URL that accepts a POST upload for a sandbox file path. */
+    async uploadUrl(path = '', opts = {}) {
+        const fileUrl = await this.fileUrl('/upload_url', path, opts);
+        return fileUrl.url;
+    }
+    /** Get a signed URL that accepts a GET download for a sandbox file path. */
+    async downloadUrl(path, opts = {}) {
+        const fileUrl = await this.fileUrl('/download_url', path, opts);
+        return fileUrl.url;
+    }
+    /** Get signed upload URL metadata for a sandbox file path. */
+    async uploadUrlInfo(path = '', opts = {}) {
+        return this.fileUrl('/upload_url', path, opts);
+    }
+    /** Get signed download URL metadata for a sandbox file path. */
+    async downloadUrlInfo(path, opts = {}) {
+        return this.fileUrl('/download_url', path, opts);
+    }
+    /** Atomically replace this sandbox's network egress policy. */
+    async updateNetwork(network, opts = {}) {
+        const sandbox = await Sandbox.putNetwork(this.sandboxId, network, { ...this.configOptions(), ...opts });
+        this.sandbox = sandbox ?? this.sandbox;
+    }
+    /** Pause this sandbox. Returns false when it was already paused. */
+    async betaPause(opts = {}) {
+        return Sandbox.betaPause(this.sandboxId, { ...this.configOptions(), ...opts });
+    }
+    /** Alias for `betaPause`. */
+    async pause(opts = {}) {
+        return this.betaPause(opts);
+    }
+    /** Resume this sandbox and refresh its data-plane session. */
+    async resume(opts = {}) {
+        await this.connect(opts);
+        return true;
+    }
+    async fileUrl(route, path, opts) {
+        const payload = await this.control.post(`/sandboxes/${this.sandboxId}/files${route}`, {
+            json: compactRecord({
+                path,
+                user: opts.user,
+                use_signature_expiration: opts.useSignatureExpiration,
+                expires_in_seconds: opts.expiresInSeconds,
+            }),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return fileUrlInfo(record(payload.file_url ?? payload));
+    }
     configOptions() {
         return {
             apiKey: this.config.apiKey,
@@ -273,6 +478,48 @@ function dataPlaneFromSession(session, config) {
     }
     return new DataPlaneClient(url, token, config);
 }
+function sandboxListPath(opts, nextToken) {
+    const params = new URLSearchParams();
+    if (opts.team)
+        params.set('team', opts.team);
+    if (opts.limit !== undefined)
+        params.set('limit', String(opts.limit));
+    if (nextToken)
+        params.set('next_token', nextToken);
+    if (opts.query?.metadata) {
+        for (const [key, value] of Object.entries(opts.query.metadata)) {
+            params.append(`query[metadata][${key}]`, value);
+        }
+    }
+    for (const state of opts.query?.state ?? []) {
+        params.append('query[state][]', state);
+    }
+    const query = params.toString();
+    return query ? `/sandboxes?${query}` : '/sandboxes';
+}
+function snapshotListPath(opts, nextToken) {
+    const params = new URLSearchParams();
+    if (opts.sandboxId)
+        params.set('sandbox_id', opts.sandboxId);
+    if (opts.limit !== undefined)
+        params.set('limit', String(opts.limit));
+    if (nextToken)
+        params.set('next_token', nextToken);
+    const query = params.toString();
+    return query ? `/sandbox_snapshots?${query}` : '/sandbox_snapshots';
+}
+function fileUrlInfo(payload) {
+    return {
+        method: String(payload.method ?? ''),
+        path: String(payload.path ?? ''),
+        url: String(payload.url ?? ''),
+        expiresAt: typeof payload.expires_at === 'string' ? payload.expires_at : typeof payload.expiresAt === 'string' ? payload.expiresAt : undefined,
+        raw: payload,
+    };
+}
+function compactRecord(payload) {
+    return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));
+}
 function sessionOperationRequestTimeout(config, opts) {
     if (opts.requestTimeoutMs !== undefined)
         return opts.requestTimeoutMs;
@@ -350,6 +597,26 @@ function putIfPresent(target, key, value) {
     if (value !== undefined && value !== null)
         target[key] = value;
 }
+function networkUpdatePayload(network) {
+    if (network === undefined)
+        return {};
+    if (typeof network !== 'object' || network === null)
+        unsupported('network callable rules');
+    if (network.rules !== undefined)
+        unsupported('network rules');
+    if (network.maskRequestHost !== undefined)
+        unsupported('network request host masking');
+    return compactRecord({
+        allow_out: network.allowOut,
+        deny_out: network.denyOut,
+        allow_internet_access: network.allowInternetAccess,
+        allow_package_registry_access: network.allowPackageRegistryAccess,
+        allow_public_traffic: network.allowPublicTraffic,
+        egress_profile: network.egressProfile,
+        egress_profiles: network.egressProfiles,
+        network_class: network.networkClass,
+    });
+}
 function record(value) {
     return value && typeof value === 'object' ? value : {};
 }