@watasu/sdk 0.1.6 → 0.1.24

package/dist/sandbox.d.ts

@@ -4,6 +4,8 @@ import { ControlClient } from './transport.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';
 export interface SandboxCreateOpts extends ConnectionOpts {
     /** Template slug to create. Defaults to "base". */
     template?: string;
@@ -13,14 +15,44 @@ export interface SandboxCreateOpts extends ConnectionOpts {
     envs?: Record<string, string>;
     secure?: boolean;
     allowInternetAccess?: boolean;
+    network?: SandboxNetworkUpdate;
     team?: string;
-    mcp?: unknown;
+    /** MCP gateway configuration to launch inside an `mcp-gateway` sandbox. */
+    mcp?: McpServer;
     volumeMounts?: unknown;
 }
+export type SandboxNetworkSelector = string | string[];
+export interface SandboxNetworkUpdate {
+    allowOut?: SandboxNetworkSelector;
+    denyOut?: SandboxNetworkSelector;
+    allowInternetAccess?: boolean;
+    allowPackageRegistryAccess?: boolean;
+    allowPublicTraffic?: boolean;
+    egressProfile?: string;
+    egressProfiles?: string[];
+    networkClass?: string;
+    rules?: unknown;
+    maskRequestHost?: string;
+}
+export interface SandboxNetworkUpdateOpts extends ConnectionOpts {
+}
 export interface SandboxConnectOpts extends ConnectionOpts {
     /** Optional new sandbox lifetime in milliseconds. */
     timeoutMs?: number;
 }
+export interface SandboxListOpts extends ConnectionOpts {
+    /** Filters applied by the Watasu API. */
+    query?: {
+        metadata?: Record<string, string>;
+        state?: Array<'running' | 'paused' | string>;
+    };
+    /** Maximum number of sandboxes to return per page. */
+    limit?: number;
+    /** Pagination cursor returned by a previous page. */
+    nextToken?: string;
+    /** Team slug to list within. */
+    team?: string;
+}
 export interface SandboxInfo {
     sandboxId: string;
     templateId?: string;
@@ -56,6 +88,10 @@ export interface FileUrlInfo {
     expiresAt?: string;
     raw: Record<string, unknown>;
 }
+/** MCP gateway configuration accepted by `Sandbox.create({ mcp })`. */
+export type McpServer = Record<string, unknown>;
+/** Name accepted by `Template.addMcpServer`. Watasu keeps this open-ended. */
+export type McpServerName = string;
 export interface SandboxUrlOpts extends ConnectionOpts {
     user?: string;
     useSignatureExpiration?: number;
@@ -67,29 +103,62 @@ export interface CreateSnapshotOpts extends ConnectionOpts {
     expiresAt?: string;
     quiesceMode?: string;
 }
+export interface SnapshotListOpts extends ConnectionOpts {
+    /** Filter snapshots by source sandbox id. */
+    sandboxId?: string;
+    /** Maximum number of snapshots to return per page. */
+    limit?: number;
+    /** Pagination cursor returned by a previous page. */
+    nextToken?: string;
+}
 export interface RestoreSnapshotOpts extends ConnectionOpts {
     checkpointId?: string | number;
     snapshotId?: string | number;
     timeout?: number;
     timeoutMs?: number;
 }
+/** Paginator for listing sandbox snapshots. */
 export declare class SnapshotPaginator {
-    private readonly loadItems;
-    private consumed;
+    private readonly opts;
+    hasNext: boolean;
+    nextToken: string | undefined;
+    constructor(opts?: SnapshotListOpts);
+    /** Fetch the next page of snapshot metadata. */
+    nextItems(opts?: ConnectionOpts): Promise<SnapshotInfo[]>;
+    /** Drain all remaining pages into one list. */
+    listItems(opts?: ConnectionOpts): Promise<SnapshotInfo[]>;
+}
+/** Paginator for listing sandboxes. */
+export declare class SandboxPaginator {
+    private readonly opts;
     hasNext: boolean;
     nextToken: string | undefined;
-    constructor(loadItems: () => Promise<SnapshotInfo[]>);
-    nextItems(): Promise<SnapshotInfo[]>;
+    constructor(opts?: SandboxListOpts);
+    /** Fetch the next page of sandbox metadata. */
+    nextItems(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
+    /** Drain all remaining pages into one list. */
+    listItems(opts?: ConnectionOpts): Promise<SandboxInfo[]>;
 }
 /** Running Watasu sandbox with ready `files` and `commands` helpers. */
 export declare class Sandbox {
     /** Default template slug used when create is called without a template. */
     static readonly defaultTemplate = "base";
+    /** Default template slug used by MCP creation once Watasu supports it. */
+    static readonly defaultMcpTemplate = "mcp-gateway";
+    /** 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;
     private readonly config;
     private readonly control;
     private readonly envs;
@@ -103,22 +172,38 @@ export declare class Sandbox {
         sandbox?: Record<string, unknown>;
         envs?: Record<string, string>;
     });
+    /** Sandbox id alias used by SDK-compatible code. */
+    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`. */
+    static pause(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy a sandbox by id. */
-    static kill(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
+    static kill(sandboxId: string, opts?: ConnectionOpts | string): Promise<boolean>;
     /** Fetch sandbox metrics by id. */
     static getMetrics(sandboxId: string, opts?: ConnectionOpts): 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;
     /** 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 checkpoints for one sandbox using snapshot naming. */
-    static listSnapshots(sandboxId: string, opts?: ConnectionOpts): SnapshotPaginator;
+    /** List snapshots visible to the configured API key. */
+    static listSnapshots(opts?: SnapshotListOpts): SnapshotPaginator;
     /** Delete a snapshot by id. Returns `false` when the snapshot does not exist. */
     static deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy this sandbox. */
@@ -129,6 +214,8 @@ export declare class Sandbox {
     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>;
     /** Fetch control-plane metadata for a sandbox by id. */
     static getInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     /** Fetch the latest control-plane metadata for this sandbox. */
@@ -142,27 +229,39 @@ export declare class Sandbox {
     /** Watasu-native alias for `createSnapshot`. */
     checkpoint(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
     /** List checkpoints for this sandbox using snapshot naming. */
-    listSnapshots(opts?: ConnectionOpts): SnapshotPaginator;
+    listSnapshots(opts?: Omit<SnapshotListOpts, 'sandboxId'>): SnapshotPaginator;
     /** Restore a checkpoint into a new sandbox and return its control-plane info. */
     restore(opts?: RestoreSnapshotOpts | string | number): Promise<SandboxInfo>;
-    /** List sandboxes visible to the configured API key. */
-    static list(opts?: ConnectionOpts & {
-        team?: string;
-    }): Promise<SandboxInfo[]>;
+    /** Return a paginator for sandboxes visible to the configured API key. */
+    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>;
+    uploadUrl(path?: string, opts?: SandboxUrlOpts): Promise<string>;
     /** Get a signed URL that accepts a GET download for a sandbox file path. */
     downloadUrl(path: string, opts?: SandboxUrlOpts): Promise<string>;
     /** Get signed upload URL metadata for a sandbox file path. */
-    uploadUrlInfo(path: string, opts?: SandboxUrlOpts): Promise<FileUrlInfo>;
+    uploadUrlInfo(path?: string, opts?: SandboxUrlOpts): Promise<FileUrlInfo>;
     /** Get signed download URL metadata for a sandbox file path. */
     downloadUrlInfo(path: string, opts?: SandboxUrlOpts): Promise<FileUrlInfo>;
-    updateNetwork(..._args: unknown[]): never;
-    pause(): never;
-    betaPause(): never;
-    resume(): never;
+    /** Atomically replace this sandbox's network egress policy. */
+    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(opts?: ConnectionOpts): Promise<boolean>;
+    /** Resume this sandbox and refresh its data-plane session. */
+    resume(opts?: SandboxConnectOpts): Promise<boolean>;
     private fileUrl;
     private configOptions;
 }