@watasu/sdk 0.1.30 → 0.1.50

package/dist/sandbox.js

@@ -1,12 +1,24 @@
+import { createHash } from 'node:crypto';
 import { Commands } from './commands.js';
 import { ConnectionConfig, SESSION_OPERATION_REQUEST_TIMEOUT_MS } from './connectionConfig.js';
 import { DataPlaneClient, ControlClient, withQuery } from './transport.js';
-import { ConflictError, FileNotFoundError, NotFoundError, SandboxError, unsupported } from './errors.js';
+import { ConflictError, FileNotFoundError, NotFoundError, SandboxError } 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';
+export const ALL_TRAFFIC = '0.0.0.0/0';
+export async function getSignature({ path, operation, user, expirationInSeconds, envdAccessToken, }) {
+    if (!envdAccessToken)
+        throw new Error('Access token is not set and signature cannot be generated');
+    const expiration = expirationInSeconds ? Math.floor(Date.now() / 1000) + expirationInSeconds : null;
+    const signatureRaw = expiration === null
+        ? `${path}:${operation}:${user ?? ''}:${envdAccessToken}`
+        : `${path}:${operation}:${user ?? ''}:${envdAccessToken}:${expiration}`;
+    const hashBase64 = await sha256(signatureRaw);
+    return { signature: `v1_${hashBase64.replace(/=+$/, '')}`, expiration };
+}
 /** Paginator for listing sandbox snapshots. */
 export class SnapshotPaginator {
     opts;
@@ -24,6 +36,7 @@ export class SnapshotPaginator {
         const control = new ControlClient(config);
         const payload = await control.get(snapshotListPath(this.opts, this.nextToken), {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         this.nextToken = stringValue(payload.next_token ?? payload.nextToken);
         this.hasNext = this.nextToken !== undefined;
@@ -57,6 +70,7 @@ export class SandboxPaginator {
         const control = new ControlClient(config);
         const payload = await control.get(sandboxListPath(this.opts, this.nextToken), {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         this.nextToken = stringValue(payload.next_token ?? payload.nextToken);
         this.hasNext = this.nextToken !== undefined;
@@ -80,14 +94,12 @@ export class Sandbox {
     /** Default sandbox lifetime in milliseconds. */
     static defaultSandboxTimeoutMs = 300_000;
     files;
-    filesystem;
     commands;
     process;
     pty;
     terminal;
     git;
     cwd;
-    envVars;
     sandboxId;
     mcpPort = 50005;
     mcpToken;
@@ -101,19 +113,17 @@ 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. */
+    /** Unique sandbox identifier. */
     get id() {
         return this.sandboxId;
     }
@@ -141,6 +151,7 @@ export class Sandbox {
         const response = await control.post('/sandboxes', {
             json: sandboxPayload,
             requestTimeoutMs: sessionOperationRequestTimeout(config, sandboxOpts),
+            signal: sandboxOpts.signal,
         });
         const sandbox = record(response.sandbox ?? response);
         const sandboxId = sandbox.id ?? sandbox.sandbox_id;
@@ -160,10 +171,14 @@ export class Sandbox {
     static async connect(sandboxId, opts = {}) {
         const config = new ConnectionConfig(opts);
         const control = new ControlClient(config);
-        const info = await control.get(`/sandboxes/${sandboxId}`);
+        const info = await control.get(`/sandboxes/${sandboxId}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
         const response = await control.post(`/sandboxes/${sandboxId}/resume`, {
             json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(config, opts),
+            signal: opts.signal,
         });
         return new this({
             sandboxId,
@@ -173,22 +188,17 @@ 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}/resume`, {
             json: opts.timeoutMs ? { timeout: Math.ceil(opts.timeoutMs / 1000) } : {},
             requestTimeoutMs: sessionOperationRequestTimeout(this.config, opts),
+            signal: opts.signal,
         });
         this.sandbox = record(response.sandbox ?? this.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);
@@ -207,6 +217,7 @@ export class Sandbox {
         try {
             await control.post(`/sandboxes/${sandboxId}/pause`, {
                 requestTimeoutMs: opts.requestTimeoutMs,
+                signal: opts.signal,
             });
             return true;
         }
@@ -216,14 +227,18 @@ export class Sandbox {
             throw error;
         }
     }
-    /** Alias for `betaPause`. */
+    /** Pause a sandbox by id. */
     static async pause(sandboxId, opts = {}) {
         return this.betaPause(sandboxId, opts);
     }
     /** Destroy a sandbox by id. */
     static async kill(sandboxId, opts = {}) {
+        const requestOpts = typeof opts === 'string' ? {} : opts;
         const control = new ControlClient(new ConnectionConfig(typeof opts === 'string' ? { apiKey: opts } : opts));
-        await control.delete(`/sandboxes/${sandboxId}`);
+        await control.delete(`/sandboxes/${sandboxId}`, {
+            requestTimeoutMs: requestOpts.requestTimeoutMs,
+            signal: requestOpts.signal,
+        });
         return true;
     }
     /** Fetch sandbox metrics by id. */
@@ -231,6 +246,7 @@ export class Sandbox {
         const control = new ControlClient(new ConnectionConfig(opts));
         const payload = await control.get(metricsPath(sandboxId, opts), {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return metricsList(payload.metrics ?? payload);
     }
@@ -243,19 +259,17 @@ export class Sandbox {
         const response = await control.put(`/sandboxes/${sandboxId}/network`, {
             json: networkUpdatePayload(network),
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return response.sandbox === undefined ? undefined : record(response.sandbox);
     }
-    /** Deprecated alias for `getInfo`. */
-    static async getFullInfo(sandboxId, opts = {}) {
-        return this.getInfo(sandboxId, opts);
-    }
     /** 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}/snapshots`, {
             json: snapshotPayload(opts),
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return snapshotInfo(record(payload.sandbox_checkpoint ?? payload.snapshot ?? payload));
     }
@@ -269,6 +283,7 @@ export class Sandbox {
         try {
             await control.delete(`/sandbox_snapshots/${snapshotId}`, {
                 requestTimeoutMs: opts.requestTimeoutMs,
+                signal: opts.signal,
             });
             return true;
         }
@@ -279,8 +294,11 @@ export class Sandbox {
         }
     }
     /** Destroy this sandbox. */
-    async kill() {
-        await this.control.delete(`/sandboxes/${this.sandboxId}`);
+    async kill(opts = {}) {
+        await this.control.delete(`/sandboxes/${this.sandboxId}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
         return true;
     }
     /** Check if this sandbox is in a runtime-active lifecycle state. */
@@ -288,6 +306,7 @@ export class Sandbox {
         try {
             const payload = await this.control.get(`/sandboxes/${this.sandboxId}`, {
                 requestTimeoutMs: opts.requestTimeoutMs,
+                signal: opts.signal,
             });
             const item = record(payload.sandbox ?? payload);
             return ['creating', 'ready', 'checkpointing', 'restoring', 'stopping'].includes(String(item.state ?? ''));
@@ -303,27 +322,37 @@ export class Sandbox {
         const control = new ControlClient(new ConnectionConfig(opts));
         await control.post(`/sandboxes/${sandboxId}/timeout`, {
             json: { timeout: Math.ceil(timeoutMs / 1000) },
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
     }
     /** Set this sandbox's lifetime. */
-    async setTimeout(timeoutMs) {
+    async setTimeout(timeoutMs, opts = {}) {
         await this.control.post(`/sandboxes/${this.sandboxId}/timeout`, {
             json: { timeout: Math.ceil(timeoutMs / 1000) },
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
     }
-    /** 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));
-        const payload = await control.get(`/sandboxes/${sandboxId}`);
+        const payload = await control.get(`/sandboxes/${sandboxId}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
         return sandboxInfo(record(payload.sandbox ?? payload));
     }
+    /** Fetch full control-plane metadata for a sandbox by id. */
+    static async getFullInfo(sandboxId, opts = {}) {
+        return this.getInfo(sandboxId, opts);
+    }
     /** Fetch the latest control-plane metadata for this sandbox. */
-    async getInfo() {
-        const payload = await this.control.get(`/sandboxes/${this.sandboxId}`);
+    async getInfo(opts = {}) {
+        const payload = await this.control.get(`/sandboxes/${this.sandboxId}`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
+        });
         return sandboxInfo(record(payload.sandbox ?? payload));
     }
     /** Fetch latest sandbox metrics. */
@@ -338,10 +367,6 @@ export class Sandbox {
     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.configOptions(), ...opts, sandboxId: this.sandboxId });
@@ -355,13 +380,12 @@ export class Sandbox {
         if (checkpointId === undefined)
             throw new SandboxError('checkpointId or snapshotId is required');
         const payload = { checkpoint_id: checkpointId };
-        if (restoreOpts.timeout !== undefined)
-            payload.timeout_seconds = restoreOpts.timeout;
         if (restoreOpts.timeoutMs !== undefined)
             payload.timeout_seconds = Math.ceil(restoreOpts.timeoutMs / 1000);
         const response = await this.control.post(`/sandboxes/${this.sandboxId}/restore`, {
             json: payload,
             requestTimeoutMs: restoreOpts.requestTimeoutMs,
+            signal: restoreOpts.signal,
         });
         return sandboxInfo(record(response.sandbox ?? response));
     }
@@ -379,12 +403,6 @@ export class Sandbox {
             throw new SandboxError('port response did not include host or url');
         return `p${port}-${routeToken}.sandbox.${this.config.dataPlaneDomain}`;
     }
-    /** 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`;
@@ -404,12 +422,6 @@ export class Sandbox {
             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);
@@ -437,7 +449,7 @@ export class Sandbox {
     async betaPause(opts = {}) {
         return Sandbox.betaPause(this.sandboxId, { ...this.configOptions(), ...opts });
     }
-    /** Alias for `betaPause`. */
+    /** Pause this sandbox. Returns false when it was already paused. */
     async pause(opts = {}) {
         return this.betaPause(opts);
     }
@@ -455,6 +467,7 @@ export class Sandbox {
                 expires_in_seconds: opts.expiresInSeconds,
             }),
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
         return fileUrlInfo(record(payload.file_url ?? payload));
     }
@@ -463,33 +476,42 @@ export class Sandbox {
         return this.dataPlane.postJson(path, {
             json,
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
     }
     /** GET JSON from the sandbox data-plane runtime API. */
     async runtimeGetJson(path, opts = {}) {
         return this.dataPlane.getJson(path, {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
     }
     /** DELETE JSON from the sandbox data-plane runtime API. */
     async runtimeDeleteJson(path, opts = {}) {
         return this.dataPlane.deleteJson(path, {
             requestTimeoutMs: opts.requestTimeoutMs,
+            signal: opts.signal,
         });
     }
     configOptions() {
         return {
             apiKey: this.config.apiKey,
             apiUrl: this.config.apiUrl,
+            sandboxUrl: this.config.sandboxUrl,
             dataPlaneDomain: this.config.dataPlaneDomain,
             requestTimeoutMs: this.config.requestTimeoutMs,
+            headers: this.config.headers,
+            apiHeaders: this.config.apiHeaders,
+            debug: this.config.debug,
+            signal: this.config.signal,
+            proxy: this.config.proxy,
         };
     }
 }
 function dataPlaneFromSession(session, config) {
     const item = record(session);
     const token = item.token ?? item.access_token;
-    const url = item.data_plane_url;
+    const url = config.sandboxUrl ?? item.data_plane_url;
     if (!session)
         throw new SandboxError('sandbox session is required for data-plane operations');
     if (typeof token !== 'string' || typeof url !== 'string') {
@@ -499,8 +521,8 @@ function dataPlaneFromSession(session, config) {
 }
 function sandboxListPath(opts, nextToken) {
     const params = new URLSearchParams();
-    if (opts.team)
-        params.set('team', opts.team);
+    if (opts.team !== undefined)
+        params.set('team', String(opts.team));
     if (opts.limit !== undefined)
         params.set('limit', String(opts.limit));
     if (nextToken)
@@ -678,23 +700,37 @@ function putIfPresent(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');
+    const rules = network.rules instanceof Map
+        ? network.rules
+        : new Map(Object.entries(network.rules ?? {}));
     return compactRecord({
-        allow_out: network.allowOut,
-        deny_out: network.denyOut,
+        allow_out: resolveNetworkSelector(network.allowOut, rules),
+        deny_out: resolveNetworkSelector(network.denyOut, rules),
         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,
+        rules: network.rules === undefined ? undefined : resolveNetworkRules(rules),
+        mask_request_host: network.maskRequestHost,
     });
 }
+function resolveNetworkSelector(selector, rules) {
+    if (selector === undefined)
+        return undefined;
+    if (typeof selector === 'function')
+        return selector({ allTraffic: ALL_TRAFFIC, rules }).map(String);
+    if (typeof selector === 'string')
+        return [selector];
+    return selector.map(String);
+}
+function resolveNetworkRules(rules) {
+    return Object.fromEntries(Array.from(rules.entries()).map(([host, hostRules]) => [
+        host,
+        hostRules.map((rule) => rule.transform === undefined ? {} : { transform: rule.transform }),
+    ]));
+}
 function record(value) {
     return value && typeof value === 'object' ? value : {};
 }
@@ -716,3 +752,11 @@ function routeTokenFromDataPlaneUrl(value, dataPlaneDomain) {
     const token = host.slice(0, -suffix.length);
     return token || undefined;
 }
+async function sha256(data) {
+    if (globalThis.crypto?.subtle) {
+        const bytes = new TextEncoder().encode(data);
+        const hash = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+        return Buffer.from(hash).toString('base64');
+    }
+    return createHash('sha256').update(data, 'utf8').digest('base64');
+}

package/dist/template.d.ts

@@ -12,10 +12,20 @@ export interface BuildInfo {
     /** Build identifier. */
     buildId: string;
 }
-export interface LogEntry {
-    timestamp?: Date;
-    level: string;
-    message: string;
+export type LogEntryLevel = 'debug' | 'info' | 'warn' | 'error';
+export type Logger = (logEntry: LogEntry) => void;
+export declare class LogEntry {
+    readonly timestamp: Date;
+    readonly level: LogEntryLevel;
+    readonly message: string;
+    constructor(timestamp?: Date, level?: LogEntryLevel, message?: string);
+    toString(): string;
+}
+export declare class LogEntryStart extends LogEntry {
+    constructor(timestamp?: Date, message?: string);
+}
+export declare class LogEntryEnd extends LogEntry {
+    constructor(timestamp?: Date, message?: string);
 }
 export interface BuildStatusReason {
     message: string;
@@ -75,6 +85,9 @@ export type TemplateBuilder = TemplateBase;
 export type TemplateFinal = TemplateBase;
 export type TemplateFromImage = TemplateBase;
 export type ReadyCommand = string | ReadyCmd;
+export declare function defaultBuildLogger(options?: {
+    minLevel?: LogEntryLevel;
+}): Logger;
 interface TemplateFileSpec {
     path: string;
     content_b64: string;
@@ -84,6 +97,10 @@ interface TemplateFileSpec {
 }
 interface BuildSpec {
     base?: string;
+    from_template?: string;
+    from_image?: string;
+    from_image_registry?: Record<string, unknown>;
+    requested_from_image?: string;
     packages?: Record<string, string[]>;
     files?: TemplateFileSpec[];
     setup?: string[];
@@ -102,8 +119,6 @@ export declare class ReadyCmd {
 export declare function waitForPort(port: number): ReadyCmd;
 /** Return a ready check that waits for a URL to return an HTTP status code. */
 export declare function waitForURL(url: string, statusCode?: number): ReadyCmd;
-/** Alias for `waitForURL`. */
-export declare const waitForUrl: typeof waitForURL;
 /** Return a ready check that waits for a process name. */
 export declare function waitForProcess(processName: string): ReadyCmd;
 /** Return a ready check that waits for a file to exist. */
@@ -113,6 +128,8 @@ export declare function waitForTimeout(timeout: number): ReadyCmd;
 /** Chainable template builder for Watasu package-spec template builds. */
 export declare class TemplateBase {
     private base;
+    private fromImageReference;
+    private fromImageRegistry;
     private packages;
     private files;
     private setup;
@@ -137,24 +154,34 @@ export declare class TemplateBase {
     static getTags(templateId: string, options?: ConnectionOpts): Promise<TemplateTag[]>;
     static toJSON(template: TemplateClass): Promise<string>;
     static toDockerfile(template: TemplateClass): string;
+    /** Request a Debian public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromDebianImage(_variant?: string): TemplateBuilder;
+    /** Request an Ubuntu public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromUbuntuImage(_variant?: string): TemplateBuilder;
+    /** Request a Python public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromPythonImage(_version?: string): TemplateBuilder;
+    /** Request a Node.js public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromNodeImage(_variant?: string): TemplateBuilder;
+    /** Request a Bun public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromBunImage(_variant?: string): TemplateBuilder;
+    /** Start from the Watasu platform base template. */
     fromBaseImage(): TemplateBuilder;
-    fromImage(_baseImage: string, _credentials?: {
+    /** Request a public container image base. The Watasu API fails closed until OCI image import is enabled. */
+    fromImage(baseImage: string, credentials?: {
         username: string;
         password: string;
     }): TemplateBuilder;
-    fromAWSRegistry(_image: string, _credentials: {
+    /** Request an AWS registry image base. The Watasu API fails closed until registry image import is enabled. */
+    fromAWSRegistry(image: string, credentials: {
         accessKeyId: string;
         secretAccessKey: string;
         region: string;
     }): TemplateBuilder;
-    fromGCPRegistry(_image: string, _credentials: {
+    /** Request a GCP registry image base. The Watasu API fails closed until registry image import is enabled. */
+    fromGCPRegistry(image: string, credentials: {
         serviceAccountJSON: object | string;
     }): TemplateBuilder;
+    /** Start from a ready Watasu template slug, tag, or version id. */
     fromTemplate(template: string): TemplateBuilder;
     fromDockerfile(dockerfileContentOrPath: string): TemplateBuilder;
     copy(src: string | string[], dest: string, options?: CopyOptions): TemplateBuilder;
@@ -204,10 +231,13 @@ export declare class TemplateBase {
     }): TemplateBuilder;
     setStartCmd(startCommand: string, readyCommand: ReadyCommand): TemplateFinal;
     setReadyCmd(readyCommand: ReadyCommand): TemplateFinal;
+    betaDevContainerPrebuild(devcontainerDirectory: string): TemplateBuilder;
+    betaSetDevContainerStart(devcontainerDirectory: string): TemplateFinal;
     setEnvs(envs: Record<string, string>): TemplateBuilder;
     skipCache(): TemplateBuilder;
     toBuildSpec(): BuildSpec;
     private addPackages;
+    private requireDevContainerTemplate;
     private addCopySource;
     private addFileSpec;
     private resolveContextPath;