@watasu/sdk 0.1.40 → 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;
@@ -111,7 +123,7 @@ export class Sandbox {
         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;
     }
@@ -331,6 +343,10 @@ export class Sandbox {
         });
         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(opts = {}) {
         const payload = await this.control.get(`/sandboxes/${this.sandboxId}`, {
@@ -351,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 });
@@ -688,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 : {};
 }
@@ -726,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[];
@@ -111,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;
@@ -135,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;

package/dist/template.js

@@ -1,8 +1,45 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { ConnectionConfig } from './connectionConfig.js';
-import { InvalidArgumentError, NotFoundError, SandboxError, unsupported } from './errors.js';
+import { InvalidArgumentError, NotFoundError, SandboxError, TemplateError } from './errors.js';
 import { ControlClient, withQuery } from './transport.js';
+export class LogEntry {
+    timestamp;
+    level;
+    message;
+    constructor(timestamp = new Date(), level = 'info', message = '') {
+        this.timestamp = timestamp;
+        this.level = level;
+        this.message = message;
+    }
+    toString() {
+        return `[${this.timestamp.toISOString()}] ${this.level}: ${this.message}`;
+    }
+}
+export class LogEntryStart extends LogEntry {
+    constructor(timestamp = new Date(), message = 'Build started') {
+        super(timestamp, 'info', message);
+    }
+}
+export class LogEntryEnd extends LogEntry {
+    constructor(timestamp = new Date(), message = 'Build finished') {
+        super(timestamp, 'info', message);
+    }
+}
+export function defaultBuildLogger(options = {}) {
+    const order = { debug: 10, info: 20, warn: 30, error: 40 };
+    const minLevel = options.minLevel ?? 'info';
+    return (entry) => {
+        if (order[entry.level] < order[minLevel])
+            return;
+        if (entry.level === 'error')
+            console.error(entry.toString());
+        else if (entry.level === 'warn')
+            console.warn(entry.toString());
+        else
+            console.log(entry.toString());
+    };
+}
 /** Ready-check command wrapper accepted by template builders. */
 export class ReadyCmd {
     cmd;
@@ -38,6 +75,8 @@ export function waitForTimeout(timeout) {
 /** Chainable template builder for Watasu package-spec template builds. */
 export class TemplateBase {
     base;
+    fromImageReference;
+    fromImageRegistry;
     packages = {};
     files = [];
     setup = [];
@@ -55,10 +94,10 @@ export class TemplateBase {
     }
     static async build(template, nameOrOptions, options = {}) {
         const { name, buildOptions } = normalizeBuildArguments(nameOrOptions, options);
-        buildOptions.onBuildLogs?.({ timestamp: new Date(), level: 'info', message: 'Build started' });
+        buildOptions.onBuildLogs?.(new LogEntryStart());
         const data = await TemplateBase.buildInBackground(template, name, buildOptions);
         await waitForBuildFinish(data, buildOptions);
-        buildOptions.onBuildLogs?.({ timestamp: new Date(), level: 'info', message: 'Build finished' });
+        buildOptions.onBuildLogs?.(new LogEntryEnd());
         return data;
     }
     static async buildInBackground(template, nameOrOptions, options = {}) {
@@ -133,42 +172,73 @@ export class TemplateBase {
     static toDockerfile(template) {
         return template.toDockerfile();
     }
+    /** Request a Debian public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromDebianImage(_variant = 'stable') {
-        this.base = 'base';
-        return this;
+        return this.fromImage(`debian:${_variant}`);
     }
+    /** Request an Ubuntu public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromUbuntuImage(_variant = 'latest') {
-        this.base = 'base';
-        return this;
+        return this.fromImage(`ubuntu:${_variant}`);
     }
+    /** Request a Python public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromPythonImage(_version = '3') {
-        this.base = this.base ?? 'base';
-        return this;
+        return this.fromImage(`python:${_version}`);
     }
+    /** Request a Node.js public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromNodeImage(_variant = 'lts') {
-        this.base = this.base ?? 'base';
-        return this;
+        return this.fromImage(`node:${_variant}`);
     }
+    /** Request a Bun public base image. The Watasu API fails closed until OCI image import is enabled. */
     fromBunImage(_variant = 'latest') {
-        this.base = this.base ?? 'base';
-        return this;
+        return this.fromImage(`oven/bun:${_variant}`);
     }
+    /** Start from the Watasu platform base template. */
     fromBaseImage() {
-        this.base = 'base';
-        return this;
+        return this.fromTemplate('base');
     }
-    fromImage(_baseImage, _credentials) {
-        this.base = this.base ?? 'base';
+    /** Request a public container image base. The Watasu API fails closed until OCI image import is enabled. */
+    fromImage(baseImage, credentials) {
+        if (credentials && (!credentials.username || !credentials.password)) {
+            throw new InvalidArgumentError('Both username and password are required when providing registry credentials');
+        }
+        this.fromImageReference = baseImage;
+        this.base = undefined;
+        this.fromImageRegistry = credentials
+            ? {
+                type: 'registry',
+                username: credentials.username,
+                password: credentials.password,
+            }
+            : undefined;
         return this;
     }
-    fromAWSRegistry(_image, _credentials) {
-        unsupported('Template.fromAWSRegistry');
+    /** Request an AWS registry image base. The Watasu API fails closed until registry image import is enabled. */
+    fromAWSRegistry(image, credentials) {
+        this.fromImageReference = image;
+        this.base = undefined;
+        this.fromImageRegistry = {
+            type: 'aws',
+            aws_access_key_id: credentials.accessKeyId,
+            aws_secret_access_key: credentials.secretAccessKey,
+            aws_region: credentials.region,
+        };
+        return this;
     }
-    fromGCPRegistry(_image, _credentials) {
-        unsupported('Template.fromGCPRegistry');
+    /** Request a GCP registry image base. The Watasu API fails closed until registry image import is enabled. */
+    fromGCPRegistry(image, credentials) {
+        this.fromImageReference = image;
+        this.base = undefined;
+        this.fromImageRegistry = {
+            type: 'gcp',
+            service_account_json: credentials.serviceAccountJSON,
+        };
+        return this;
     }
+    /** Start from a ready Watasu template slug, tag, or version id. */
     fromTemplate(template) {
         this.base = template;
+        this.fromImageReference = undefined;
+        this.fromImageRegistry = undefined;
         return this;
     }
     fromDockerfile(dockerfileContentOrPath) {
@@ -303,7 +373,11 @@ export class TemplateBase {
     toBuildSpec() {
         const spec = {};
         if (this.base)
-            spec.base = this.base;
+            spec.from_template = this.base;
+        if (this.fromImageReference)
+            spec.from_image = this.fromImageReference;
+        if (this.fromImageRegistry)
+            spec.from_image_registry = this.fromImageRegistry;
         if (Object.keys(this.packages).length > 0)
             spec.packages = this.packages;
         if (this.files.length > 0)
@@ -379,7 +453,7 @@ export class TemplateBase {
             : commandText;
     }
     toDockerfile() {
-        const lines = ['FROM base'];
+        const lines = [`FROM ${this.fromImageReference ?? this.base ?? 'base'}`];
         for (const packageName of this.packages.apt ?? [])
             lines.push(`RUN apt-get update && apt-get install -y ${packageName}`);
         for (const packageName of this.packages.pip ?? [])
@@ -553,7 +627,7 @@ async function waitForBuildFinish(data, options) {
         if (status === 'ready')
             return;
         if (status === 'error')
-            throw new SandboxError(buildStatus.reason?.message ?? 'Template build failed');
+            throw new TemplateError(buildStatus.reason?.message ?? 'Template build failed');
         await new Promise((resolve) => setTimeout(resolve, 200));
     }
 }
@@ -600,11 +674,12 @@ function buildStatusReason(payload) {
 }
 function logEntry(payload) {
     const timestamp = stringValue(payload.timestamp);
-    return {
-        timestamp: timestamp ? new Date(timestamp) : undefined,
-        level: stringValue(payload.level) ?? 'info',
-        message: stringValue(payload.message) ?? '',
-    };
+    return new LogEntry(timestamp ? new Date(timestamp) : new Date(), logEntryLevel(stringValue(payload.level)), stringValue(payload.message) ?? '');
+}
+function logEntryLevel(value) {
+    if (value === 'debug' || value === 'info' || value === 'warn' || value === 'error')
+        return value;
+    return 'info';
 }
 function templateTag(payload) {
     return {

package/dist/terminal.d.ts

@@ -15,6 +15,7 @@ export type TerminalOpts = {
     cwd?: string;
     envs?: Record<string, string>;
     timeoutMs?: number;
+    requestTimeoutMs?: number;
 };
 /** A running terminal session in a sandbox. */
 export declare class Terminal {

package/dist/terminal.js

@@ -32,7 +32,10 @@ export class Terminal {
         return this.waitPromise;
     }
     async waitOnce() {
-        await this.handle.wait().catch((error) => {
+        await this.handle.wait().then((result) => {
+            if (this.output.data.length === 0 && result.stdout)
+                this.output.addData(result.stdout);
+        }).catch((error) => {
             if (typeof error?.stdout === 'string')
                 this.output.addData(error.stdout);
             else
@@ -62,6 +65,7 @@ export class TerminalManager {
             envs: opts.envs,
             size: opts.size,
             timeoutMs: opts.timeoutMs,
+            requestTimeoutMs: opts.requestTimeoutMs,
             onData: async (bytes) => {
                 const data = new TextDecoder().decode(bytes);
                 output.addData(data);

package/dist/volume.d.ts

@@ -1,7 +1,12 @@
 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 declare enum VolumeFileType {
+    UNKNOWN = "unknown",
+    FILE = "file",
+    DIRECTORY = "directory",
+    SYMLINK = "symlink"
+}
 export type VolumeReadFormat = 'text' | 'bytes' | 'blob' | 'stream';
 export type VolumeWriteData = string | Uint8Array | ArrayBuffer | Blob;
 /** Control-plane metadata for a persistent Watasu volume. */
@@ -23,7 +28,7 @@ export interface VolumeInfo {
 export interface VolumeEntryStat {
     path: string;
     name: string;
-    type: VolumeFileType;
+    type: VolumeFileType | string;
     size?: number;
     mode?: number;
     uid?: number;
@@ -36,8 +41,8 @@ export interface VolumeEntryStat {
 export interface VolumeApiParams extends ConnectionOpts {
     team?: string;
 }
-export interface VolumeConnectionConfig extends ConnectionOpts {
-}
+export type VolumeConnectionConfig = ConnectionOpts;
+export declare const VolumeConnectionConfig: typeof ConnectionConfig;
 export interface VolumeListOpts extends ConnectionOpts {
     team?: string;
 }
@@ -58,6 +63,12 @@ export interface VolumeMetadataOpts extends ConnectionOpts {
     gid?: number;
     mode?: number | string;
 }
+export type VolumeAndToken = VolumeInfo & {
+    token: string;
+};
+export type VolumeApiOpts = ConnectionOpts;
+export type VolumeMetadataOptions = Omit<VolumeMetadataOpts, keyof ConnectionOpts>;
+export type VolumeWriteOptions = Omit<VolumeWriteFileOpts, keyof ConnectionOpts>;
 /** Persistent volume that can be mounted into sandboxes and edited while detached. */
 export declare class Volume {
     readonly volumeId: string;

package/dist/volume.js

@@ -3,6 +3,14 @@ import { ConnectionConfig } from './connectionConfig.js';
 import { NotFoundError, SandboxError } from './errors.js';
 import { base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';
 import { ControlClient, withQuery } from './transport.js';
+export var VolumeFileType;
+(function (VolumeFileType) {
+    VolumeFileType["UNKNOWN"] = "unknown";
+    VolumeFileType["FILE"] = "file";
+    VolumeFileType["DIRECTORY"] = "directory";
+    VolumeFileType["SYMLINK"] = "symlink";
+})(VolumeFileType || (VolumeFileType = {}));
+export const VolumeConnectionConfig = ConnectionConfig;
 /** Persistent volume that can be mounted into sandboxes and edited while detached. */
 export class Volume {
     volumeId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watasu/sdk",
-  "version": "0.1.40",
+  "version": "0.1.50",
   "type": "module",
   "license": "MIT OR Apache-2.0",
   "description": "TypeScript SDK for Watasu",
@@ -23,7 +23,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test test/*.mjs"
+    "test": "npm run build && tsc -p tsconfig.test.json && node --test test/*.mjs"
   },
   "dependencies": {
     "ws": "^8.18.3"