@watasu/sdk 0.1.0

package/dist/commands.d.ts

@@ -0,0 +1,93 @@
+import { ConnectionConfig } from './connectionConfig.js';
+import { DataPlaneClient } from './transport.js';
+import { ProcessFrame, ProcessSocket } from './processSocket.js';
+import { SandboxError } from './errors.js';
+export interface CommandResult {
+    /** Process exit code. Zero means success. */
+    exitCode: number;
+    error?: string;
+    stdout: string;
+    stderr: string;
+}
+/** Error thrown by `CommandHandle.wait()` when a process exits non-zero. */
+export declare class CommandExitError extends SandboxError implements CommandResult {
+    private readonly result;
+    constructor(result: CommandResult);
+    get exitCode(): number;
+    get error(): string | undefined;
+    get stdout(): string;
+    get stderr(): string;
+}
+export interface ProcessInfo {
+    pid: number | string;
+    tag?: string;
+    cmd?: string;
+    args: string[];
+    envs: Record<string, string>;
+    cwd?: string;
+}
+export interface CommandStartOpts {
+    /** Return a `CommandHandle` immediately instead of waiting for exit. */
+    background?: boolean;
+    cwd?: string;
+    user?: string;
+    envs?: Record<string, string>;
+    onStdout?: (data: string) => void | Promise<void>;
+    onStderr?: (data: string) => void | Promise<void>;
+    stdin?: boolean;
+    timeoutMs?: number;
+    requestTimeoutMs?: number;
+}
+/** Live handle for one sandbox process stream. */
+export declare class CommandHandle implements Partial<CommandResult> {
+    readonly pid: number | string;
+    private readonly socket;
+    private readonly handleKill;
+    private readonly events;
+    private readonly onStdout?;
+    private readonly onStderr?;
+    private _stdout;
+    private _stderr;
+    private result?;
+    private readonly pending;
+    constructor(pid: number | string, socket: ProcessSocket, handleKill: () => Promise<boolean>, events: AsyncIterable<ProcessFrame>, onStdout?: ((data: string) => void | Promise<void>) | undefined, onStderr?: ((data: string) => void | Promise<void>) | undefined);
+    get stdout(): string;
+    get stderr(): string;
+    get exitCode(): number | undefined;
+    get error(): string | undefined;
+    /** Wait until the process exits and return captured output. */
+    wait(): Promise<CommandResult>;
+    /** Kill the process. */
+    kill(): Promise<boolean>;
+    /** Send stdin bytes or text to the process. */
+    sendStdin(data: string | Uint8Array): Promise<void>;
+    /** Detach the local stream without killing the process. */
+    disconnect(): void;
+    private handleEvents;
+}
+/** Command runner for a sandbox data-plane session. */
+export declare class Commands {
+    private readonly dataPlane;
+    private readonly config;
+    private readonly sandboxEnvs;
+    constructor(dataPlane: DataPlaneClient, config: ConnectionConfig, sandboxEnvs?: Record<string, string>);
+    /** List processes currently known by the sandbox runtime. */
+    list(opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<ProcessInfo[]>;
+    /** Send SIGKILL to a process by pid. */
+    kill(pid: number | string, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<boolean>;
+    /** Attach to a process and send stdin bytes or text. */
+    sendStdin(pid: number | string, data: string | Uint8Array, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<void>;
+    run(cmd: string, opts: CommandStartOpts & {
+        background: true;
+    }): Promise<CommandHandle>;
+    run(cmd: string, opts?: CommandStartOpts): Promise<CommandResult>;
+    /** Reconnect to a live process stream by pid. */
+    connect(pid: number | string, opts?: CommandStartOpts): Promise<CommandHandle>;
+    private start;
+}

package/dist/commands.js

@@ -0,0 +1,198 @@
+import { ProcessSocket, base64DecodeText } from './processSocket.js';
+import { SandboxError } from './errors.js';
+/** Error thrown by `CommandHandle.wait()` when a process exits non-zero. */
+export class CommandExitError extends SandboxError {
+    result;
+    constructor(result) {
+        super(result.error ?? `Command exited with code ${result.exitCode}`);
+        this.result = result;
+        this.name = 'CommandExitError';
+    }
+    get exitCode() { return this.result.exitCode; }
+    get error() { return this.result.error; }
+    get stdout() { return this.result.stdout; }
+    get stderr() { return this.result.stderr; }
+}
+/** Live handle for one sandbox process stream. */
+export class CommandHandle {
+    pid;
+    socket;
+    handleKill;
+    events;
+    onStdout;
+    onStderr;
+    _stdout = '';
+    _stderr = '';
+    result;
+    pending;
+    constructor(pid, socket, handleKill, events, onStdout, onStderr) {
+        this.pid = pid;
+        this.socket = socket;
+        this.handleKill = handleKill;
+        this.events = events;
+        this.onStdout = onStdout;
+        this.onStderr = onStderr;
+        this.pending = this.handleEvents();
+    }
+    get stdout() { return this._stdout; }
+    get stderr() { return this._stderr; }
+    get exitCode() { return this.result?.exitCode; }
+    get error() { return this.result?.error; }
+    /** Wait until the process exits and return captured output. */
+    async wait() {
+        await this.pending;
+        if (!this.result)
+            throw new SandboxError('Command ended without an exit event');
+        if (this.result.exitCode !== 0)
+            throw new CommandExitError(this.result);
+        return this.result;
+    }
+    /** Kill the process. */
+    async kill() {
+        return this.handleKill();
+    }
+    /** Send stdin bytes or text to the process. */
+    async sendStdin(data) {
+        this.socket.sendStdin(data);
+    }
+    /** Detach the local stream without killing the process. */
+    disconnect() {
+        this.socket.close();
+    }
+    async handleEvents() {
+        try {
+            for await (const frame of this.events) {
+                const type = frame.type;
+                if (type === 'started' || type === 'ready' || type === 'pong')
+                    continue;
+                if (type === 'stdout') {
+                    const out = base64DecodeText(frame.data);
+                    this._stdout += out;
+                    await this.onStdout?.(out);
+                }
+                else if (type === 'stderr') {
+                    const out = base64DecodeText(frame.data);
+                    this._stderr += out;
+                    await this.onStderr?.(out);
+                }
+                else if (type === 'exit') {
+                    this.result = {
+                        exitCode: Number(frame.exit_code ?? frame.exitCode ?? 0),
+                        error: typeof frame.error === 'string' ? frame.error : undefined,
+                        stdout: this._stdout,
+                        stderr: this._stderr,
+                    };
+                    return;
+                }
+                else if (type === 'error') {
+                    throw new SandboxError(String(frame.message ?? frame.code ?? 'process error'));
+                }
+            }
+        }
+        finally {
+            this.socket.close();
+        }
+    }
+}
+/** Command runner for a sandbox data-plane session. */
+export class Commands {
+    dataPlane;
+    config;
+    sandboxEnvs;
+    constructor(dataPlane, config, sandboxEnvs = {}) {
+        this.dataPlane = dataPlane;
+        this.config = config;
+        this.sandboxEnvs = sandboxEnvs;
+    }
+    /** List processes currently known by the sandbox runtime. */
+    async list(opts = {}) {
+        const payload = await this.dataPlane.getJson('/runtime/v1/process', opts);
+        const processes = Array.isArray(payload.processes) ? payload.processes : [];
+        return processes.map((item) => processInfo(item));
+    }
+    /** Send SIGKILL to a process by pid. */
+    async kill(pid, opts = {}) {
+        await this.dataPlane.postJson(`/runtime/v1/process/${pid}/signal`, {
+            ...opts,
+            json: { signal: 'SIGKILL' },
+        });
+        return true;
+    }
+    /** Attach to a process and send stdin bytes or text. */
+    async sendStdin(pid, data, opts = {}) {
+        const handle = await this.connect(pid, opts);
+        try {
+            await handle.sendStdin(data);
+        }
+        finally {
+            handle.disconnect();
+        }
+    }
+    /** Run a shell command over the WebSocket process runtime. */
+    async run(cmd, opts = {}) {
+        const handle = await this.start(cmd, opts);
+        if (opts.background)
+            return handle;
+        return handle.wait();
+    }
+    /** Reconnect to a live process stream 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 first = await nextStarted(socket);
+        const actualPid = framePid(first) ?? pid;
+        return new CommandHandle(actualPid, socket, () => this.kill(actualPid), socket, opts.onStdout, opts.onStderr);
+    }
+    async start(cmd, opts) {
+        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, '/runtime/v1/process', opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
+        const environment = { ...this.sandboxEnvs, ...(opts.envs ?? {}) };
+        socket.sendJson({
+            type: 'start',
+            cmd: '/bin/bash',
+            args: ['-l', '-c', cmd],
+            cwd: opts.cwd,
+            user: opts.user,
+            environment,
+            envs: environment,
+            stdin: opts.stdin ?? false,
+            timeout_ms: opts.timeoutMs ?? 60_000,
+        });
+        const first = await nextStarted(socket);
+        const pid = framePid(first);
+        if (pid === undefined)
+            throw new SandboxError('process started frame did not include pid');
+        return new CommandHandle(pid, socket, () => this.kill(pid), withFirst(first, socket), opts.onStdout, opts.onStderr);
+    }
+}
+async function nextStarted(events) {
+    for await (const frame of events) {
+        if (frame.type === 'started')
+            return frame;
+    }
+    throw new SandboxError('process ended before started frame');
+}
+async function* withFirst(first, rest) {
+    yield first;
+    yield* rest;
+}
+function framePid(frame) {
+    const process = frame.process && typeof frame.process === 'object' ? frame.process : {};
+    const pid = frame.pid ?? process.pid ?? process.id;
+    return typeof pid === 'number' || typeof pid === 'string' ? pid : undefined;
+}
+function processInfo(value) {
+    const item = value && typeof value === 'object' ? value : {};
+    const process = item.process && typeof item.process === 'object' ? item.process : item;
+    return {
+        pid: framePid(process) ?? '',
+        tag: typeof process.tag === 'string' ? process.tag : undefined,
+        cmd: typeof process.cmd === 'string' ? process.cmd : undefined,
+        args: Array.isArray(process.args) ? process.args.map(String) : [],
+        envs: recordOfStrings(process.envs ?? process.environment),
+        cwd: typeof process.cwd === 'string' ? process.cwd : undefined,
+    };
+}
+function recordOfStrings(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, String(item)]));
+}

package/dist/connectionConfig.d.ts

@@ -0,0 +1,25 @@
+export declare const KEEPALIVE_PING_INTERVAL_SEC = 50;
+export declare const SESSION_OPERATION_REQUEST_TIMEOUT_MS = 150000;
+/** Connection options accepted by Watasu SDK entrypoints. */
+export interface ConnectionOpts {
+    apiKey?: string;
+    domain?: string;
+    apiUrl?: string;
+    dataPlaneDomain?: string;
+    requestTimeoutMs?: number;
+    headers?: Record<string, string>;
+    proxy?: unknown;
+}
+/** Resolved connection settings used by control-plane and data-plane clients. */
+export declare class ConnectionConfig {
+    readonly apiKey?: string;
+    readonly domain: string;
+    readonly apiUrl: string;
+    readonly dataPlaneDomain: string;
+    readonly requestTimeoutMs: number;
+    readonly headers: Record<string, string>;
+    readonly proxy?: unknown;
+    constructor(opts?: ConnectionOpts);
+    /** HTTP headers including the configured bearer token. */
+    get authHeaders(): Record<string, string>;
+}

package/dist/connectionConfig.js

@@ -0,0 +1,32 @@
+export const KEEPALIVE_PING_INTERVAL_SEC = 50;
+export const SESSION_OPERATION_REQUEST_TIMEOUT_MS = 150_000;
+/** Resolved connection settings used by control-plane and data-plane clients. */
+export class ConnectionConfig {
+    apiKey;
+    domain;
+    apiUrl;
+    dataPlaneDomain;
+    requestTimeoutMs;
+    headers;
+    proxy;
+    constructor(opts = {}) {
+        const env = typeof process !== 'undefined' ? process.env : {};
+        this.apiKey = opts.apiKey ?? env.WATASU_API_KEY;
+        this.domain = opts.domain ?? env.WATASU_DOMAIN ?? 'watasu.io';
+        this.apiUrl =
+            opts.apiUrl ?? env.WATASU_API_URL ?? `https://api.${this.domain}/v1`;
+        this.dataPlaneDomain =
+            opts.dataPlaneDomain ??
+                env.WATASU_DATA_PLANE_DOMAIN ??
+                'watasuhost.com';
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? 60_000;
+        this.headers = opts.headers ?? {};
+        this.proxy = opts.proxy;
+    }
+    /** HTTP headers including the configured bearer token. */
+    get authHeaders() {
+        return this.apiKey
+            ? { ...this.headers, Authorization: `Bearer ${this.apiKey}` }
+            : { ...this.headers };
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,34 @@
+export declare class SandboxError extends Error {
+    constructor(message?: string);
+}
+export declare class AuthenticationError extends SandboxError {
+    constructor(message?: string);
+}
+export declare class NotFoundError extends SandboxError {
+    constructor(message?: string);
+}
+export declare class TimeoutError extends SandboxError {
+    constructor(message?: string);
+}
+export declare class InvalidArgumentError extends SandboxError {
+    constructor(message?: string);
+}
+export declare class RateLimitError extends SandboxError {
+    constructor(message?: string);
+}
+export declare class NotEnoughSpaceError extends SandboxError {
+    constructor(message?: string);
+}
+export declare class FileNotFoundError extends NotFoundError {
+    constructor(message?: string);
+}
+export declare function unsupported(feature: string): never;
+export declare class NotImplementedError extends Error {
+    constructor(message: string);
+}
+export declare class ApiError extends SandboxError {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+export declare function errorFromResponse(status: number, payload: unknown): Error;

package/dist/errors.js

@@ -0,0 +1,99 @@
+export class SandboxError extends Error {
+    constructor(message = 'Sandbox error') {
+        super(message);
+        this.name = 'SandboxError';
+    }
+}
+export class AuthenticationError extends SandboxError {
+    constructor(message = 'Authentication failed') {
+        super(message);
+        this.name = 'AuthenticationError';
+    }
+}
+export class NotFoundError extends SandboxError {
+    constructor(message = 'Not found') {
+        super(message);
+        this.name = 'NotFoundError';
+    }
+}
+export class TimeoutError extends SandboxError {
+    constructor(message = 'Request timed out') {
+        super(message);
+        this.name = 'TimeoutError';
+    }
+}
+export class InvalidArgumentError extends SandboxError {
+    constructor(message = 'Invalid argument') {
+        super(message);
+        this.name = 'InvalidArgumentError';
+    }
+}
+export class RateLimitError extends SandboxError {
+    constructor(message = 'Rate limit exceeded') {
+        super(message);
+        this.name = 'RateLimitError';
+    }
+}
+export class NotEnoughSpaceError extends SandboxError {
+    constructor(message = 'Not enough space') {
+        super(message);
+        this.name = 'NotEnoughSpaceError';
+    }
+}
+export class FileNotFoundError extends NotFoundError {
+    constructor(message = 'File not found') {
+        super(message);
+        this.name = 'FileNotFoundError';
+    }
+}
+export function unsupported(feature) {
+    throw new NotImplementedError(`${feature} is not supported by Watasu yet`);
+}
+export class NotImplementedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotImplementedError';
+    }
+}
+export class ApiError extends SandboxError {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'ApiError';
+    }
+}
+export function errorFromResponse(status, payload) {
+    const body = asRecord(payload);
+    const code = stringValue(body.error);
+    const message = stringValue(body.message) ||
+        listMessage(body.errors) ||
+        code ||
+        `Request failed with status ${status}`;
+    if (status === 401 || status === 403)
+        return new AuthenticationError(message);
+    if (status === 404)
+        return new NotFoundError(message);
+    if (status === 408 || status === 504)
+        return new TimeoutError(message);
+    if (status === 422 || status === 400)
+        return new InvalidArgumentError(message);
+    if (status === 429)
+        return new RateLimitError(message);
+    if (code === 'not_enough_space')
+        return new NotEnoughSpaceError(message);
+    if (code === 'file_not_found')
+        return new FileNotFoundError(message);
+    return new ApiError(message, status, code);
+}
+function asRecord(value) {
+    return value && typeof value === 'object' ? value : {};
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function listMessage(value) {
+    return Array.isArray(value) ? value.map(String).join(', ') : undefined;
+}

package/dist/filesystem.d.ts

@@ -0,0 +1,65 @@
+import { DataPlaneClient } from './transport.js';
+export declare enum FileType {
+    /** Regular file. */
+    FILE = "file",
+    /** Directory. */
+    DIR = "dir",
+    /** Symbolic link. */
+    SYMLINK = "symlink"
+}
+/** Metadata for one sandbox filesystem entry. */
+export interface EntryInfo {
+    name: string;
+    type: FileType | string;
+    path: string;
+    size?: number;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+    mtime?: number;
+    metadata?: Record<string, string>;
+}
+export type WriteInfo = EntryInfo;
+/** Filesystem helper for a sandbox data-plane session. */
+export declare class Filesystem {
+    private readonly dataPlane;
+    constructor(dataPlane: DataPlaneClient);
+    /** Read a file as UTF-8 text, bytes, or a one-chunk async byte stream. */
+    read(path: string, opts?: {
+        format?: 'text' | 'bytes' | 'stream';
+        requestTimeoutMs?: number;
+        gzip?: boolean;
+    }): Promise<string | Uint8Array | AsyncIterable<Uint8Array>>;
+    /** Write UTF-8 text or bytes to a file. */
+    write(path: string, data: string | Uint8Array, opts?: {
+        requestTimeoutMs?: number;
+        gzip?: boolean;
+        metadata?: Record<string, string>;
+    }): Promise<WriteInfo>;
+    /** List directory entries below `path`. */
+    list(path: string, opts?: {
+        requestTimeoutMs?: number;
+        depth?: number;
+    }): Promise<EntryInfo[]>;
+    /** Return whether a file or directory exists at `path`. */
+    exists(path: string, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<boolean>;
+    /** Return stat metadata for `path`. */
+    getInfo(path: string, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<EntryInfo>;
+    /** Remove a file at `path`. */
+    remove(path: string, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<void>;
+    /** Move or rename a file. */
+    rename(oldPath: string, newPath: string, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<EntryInfo>;
+    /** Create a directory. */
+    makeDir(path: string, opts?: {
+        requestTimeoutMs?: number;
+    }): Promise<boolean>;
+    watchDir(): never;
+}

package/dist/filesystem.js

@@ -0,0 +1,98 @@
+import { withQuery } from './transport.js';
+import { FileNotFoundError, unsupported } from './errors.js';
+export var FileType;
+(function (FileType) {
+    /** Regular file. */
+    FileType["FILE"] = "file";
+    /** Directory. */
+    FileType["DIR"] = "dir";
+    /** Symbolic link. */
+    FileType["SYMLINK"] = "symlink";
+})(FileType || (FileType = {}));
+/** Filesystem helper for a sandbox data-plane session. */
+export class Filesystem {
+    dataPlane;
+    constructor(dataPlane) {
+        this.dataPlane = dataPlane;
+    }
+    /** Read a file as UTF-8 text, bytes, or a one-chunk async byte stream. */
+    async read(path, opts = {}) {
+        const bytes = await this.dataPlane.getBytes(withQuery('/runtime/v1/files', { path, gzip: opts.gzip }), opts);
+        if (opts.format === 'bytes')
+            return bytes;
+        if (opts.format === 'stream')
+            return (async function* () { yield bytes; })();
+        return new TextDecoder().decode(bytes);
+    }
+    /** Write UTF-8 text or bytes to a file. */
+    async write(path, data, opts = {}) {
+        const body = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        const payload = await this.dataPlane.putJson(withQuery('/runtime/v1/files', { path, gzip: opts.gzip }), body, opts);
+        return entryInfo(payload.file ?? payload);
+    }
+    /** List directory entries below `path`. */
+    async list(path, opts = {}) {
+        const payload = await this.dataPlane.getJson(withQuery('/runtime/v1/directories', { path, depth: opts.depth }), opts);
+        const entries = Array.isArray(payload.entries) ? payload.entries : [];
+        return entries.map(entryInfo);
+    }
+    /** Return whether a file or directory exists at `path`. */
+    async exists(path, opts = {}) {
+        try {
+            await this.getInfo(path, opts);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof FileNotFoundError)
+                return false;
+            throw error;
+        }
+    }
+    /** Return stat metadata for `path`. */
+    async getInfo(path, opts = {}) {
+        const payload = await this.dataPlane.getJson(withQuery('/runtime/v1/files/stat', { path }), opts);
+        return entryInfo(payload.file ?? payload.entry ?? payload);
+    }
+    /** Remove a file at `path`. */
+    async remove(path, opts = {}) {
+        await this.dataPlane.deleteJson(withQuery('/runtime/v1/files', { path }), opts);
+    }
+    /** Move or rename a file. */
+    async rename(oldPath, newPath, opts = {}) {
+        const payload = await this.dataPlane.postJson('/runtime/v1/files/move', {
+            ...opts,
+            json: { from_path: oldPath, to_path: newPath },
+        });
+        return entryInfo(payload.file ?? payload);
+    }
+    /** Create a directory. */
+    async makeDir(path, opts = {}) {
+        await this.dataPlane.postJson(withQuery('/runtime/v1/directories', { path }), opts);
+        return true;
+    }
+    watchDir() {
+        unsupported('sandbox.files.watchDir');
+    }
+}
+function entryInfo(value) {
+    const item = value && typeof value === 'object' ? value : {};
+    return {
+        name: String(item.name ?? ''),
+        type: String(item.type ?? FileType.FILE),
+        path: String(item.path ?? ''),
+        size: numberValue(item.bytes ?? item.size),
+        mode: numberValue(item.mode),
+        uid: numberValue(item.uid),
+        gid: numberValue(item.gid),
+        mtime: numberValue(item.mtime),
+        metadata: recordOfStrings(item.metadata),
+    };
+}
+function numberValue(value) {
+    return typeof value === 'number' ? value : undefined;
+}
+function recordOfStrings(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, String(item)]));
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { ApiError, AuthenticationError, FileNotFoundError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, NotImplementedError, RateLimitError, SandboxError, TimeoutError, } from './errors.js';
+export { ConnectionConfig, KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
+export { Sandbox } from './sandbox.js';
+export type { SandboxCreateOpts, SandboxConnectOpts, SandboxInfo } from './sandbox.js';
+export { CommandExitError, CommandHandle, Commands } from './commands.js';
+export type { CommandResult, CommandStartOpts, ProcessInfo } from './commands.js';
+export { FileType, Filesystem } from './filesystem.js';
+export type { EntryInfo, WriteInfo } from './filesystem.js';
+export { ProcessSocket, base64DecodeText, base64Encode } from './processSocket.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { ApiError, AuthenticationError, FileNotFoundError, InvalidArgumentError, NotEnoughSpaceError, NotFoundError, NotImplementedError, RateLimitError, SandboxError, TimeoutError, } from './errors.js';
+export { ConnectionConfig, KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
+export { Sandbox } from './sandbox.js';
+export { CommandExitError, CommandHandle, Commands } from './commands.js';
+export { FileType, Filesystem } from './filesystem.js';
+export { ProcessSocket, base64DecodeText, base64Encode } from './processSocket.js';

package/dist/processSocket.d.ts

@@ -0,0 +1,25 @@
+export type ProcessFrame = Record<string, unknown>;
+/** Streaming WebSocket connection to the sandbox process runtime. */
+export declare class ProcessSocket implements AsyncIterable<ProcessFrame> {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly path;
+    private readonly requestTimeoutMs;
+    private ws?;
+    private queue;
+    private waiters;
+    private closed;
+    private keepalive?;
+    constructor(baseUrl: string, token: string, path: string, requestTimeoutMs?: number);
+    connect(): Promise<this>;
+    sendJson(payload: ProcessFrame): void;
+    sendStdin(data: string | Uint8Array): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<ProcessFrame>;
+    private next;
+    private onMessage;
+    private finish;
+    private flushDone;
+}
+export declare function base64Encode(bytes: Uint8Array): string;
+export declare function base64DecodeText(value: unknown): string;

package/dist/processSocket.js

@@ -0,0 +1,143 @@
+import { Buffer } from 'node:buffer';
+import WebSocket from 'ws';
+import { KEEPALIVE_PING_INTERVAL_SEC } from './connectionConfig.js';
+import { SandboxError, TimeoutError } from './errors.js';
+/** Streaming WebSocket connection to the sandbox process runtime. */
+export class ProcessSocket {
+    baseUrl;
+    token;
+    path;
+    requestTimeoutMs;
+    ws;
+    queue = [];
+    waiters = [];
+    closed = false;
+    keepalive;
+    constructor(baseUrl, token, path, requestTimeoutMs = 60_000) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+        this.path = path;
+        this.requestTimeoutMs = requestTimeoutMs;
+    }
+    async connect() {
+        const ws = new WebSocket(wsUrl(this.baseUrl, this.path), {
+            headers: { Authorization: `Bearer ${this.token}` },
+        });
+        this.ws = ws;
+        ws.on('message', (data) => this.onMessage(data));
+        ws.on('close', () => this.finish());
+        ws.on('error', () => this.finish(new SandboxError('process websocket failed')));
+        await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => reject(new TimeoutError()), this.requestTimeoutMs);
+            ws.once('open', () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+            ws.once('error', () => {
+                clearTimeout(timeout);
+                reject(new SandboxError('process websocket failed to connect'));
+            });
+        });
+        this.keepalive = setInterval(() => {
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.ping('watasu-sdk');
+            }
+        }, KEEPALIVE_PING_INTERVAL_SEC * 1000);
+        return this;
+    }
+    sendJson(payload) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new SandboxError('process websocket is not connected');
+        }
+        this.ws.send(JSON.stringify(payload));
+    }
+    sendStdin(data) {
+        const raw = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        this.sendJson({ type: 'stdin', data: base64Encode(raw) });
+    }
+    close() {
+        this.closed = true;
+        if (this.keepalive)
+            clearInterval(this.keepalive);
+        this.ws?.close();
+        this.flushDone();
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.next(),
+        };
+    }
+    next() {
+        if (this.queue.length > 0) {
+            return Promise.resolve({ done: false, value: this.queue.shift() });
+        }
+        if (this.closed)
+            return Promise.resolve({ done: true, value: undefined });
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+    onMessage(message) {
+        const text = rawDataToText(message);
+        try {
+            const frame = JSON.parse(text);
+            if (frame.type === 'pong' || frame.type === 'ready')
+                return;
+            if (frame.type === 'error') {
+                this.finish(new SandboxError(String(frame.message ?? frame.code ?? 'process error')));
+                return;
+            }
+            const waiter = this.waiters.shift();
+            if (waiter)
+                waiter({ done: false, value: frame });
+            else
+                this.queue.push(frame);
+        }
+        catch (error) {
+            this.finish(error instanceof Error ? error : new SandboxError(String(error)));
+        }
+    }
+    finish(error) {
+        this.closed = true;
+        if (this.keepalive)
+            clearInterval(this.keepalive);
+        if (error) {
+            const frame = { type: 'error', message: error.message };
+            const waiter = this.waiters.shift();
+            if (waiter)
+                waiter({ done: false, value: frame });
+            else
+                this.queue.push(frame);
+        }
+        this.flushDone();
+    }
+    flushDone() {
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ done: true, value: undefined });
+        }
+    }
+}
+export function base64Encode(bytes) {
+    return Buffer.from(bytes).toString('base64');
+}
+export function base64DecodeText(value) {
+    if (typeof value !== 'string')
+        return String(value ?? '');
+    try {
+        return Buffer.from(value, 'base64').toString('utf8');
+    }
+    catch {
+        return value;
+    }
+}
+function rawDataToText(message) {
+    if (typeof message === 'string')
+        return message;
+    if (Array.isArray(message))
+        return Buffer.concat(message).toString('utf8');
+    if (message instanceof ArrayBuffer)
+        return Buffer.from(new Uint8Array(message)).toString('utf8');
+    return Buffer.from(message).toString('utf8');
+}
+function wsUrl(baseUrl, path) {
+    const url = new URL(path, baseUrl.replace(/^http/, 'ws'));
+    return url.toString();
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,91 @@
+import { Commands } from './commands.js';
+import { ConnectionConfig, ConnectionOpts } from './connectionConfig.js';
+import { ControlClient } from './transport.js';
+import { Filesystem } from './filesystem.js';
+export interface SandboxCreateOpts extends ConnectionOpts {
+    /** Template slug to create. Defaults to "base". */
+    template?: string;
+    /** Sandbox lifetime in milliseconds. Defaults to five minutes. */
+    timeoutMs?: number;
+    metadata?: Record<string, string>;
+    envs?: Record<string, string>;
+    secure?: boolean;
+    allowInternetAccess?: boolean;
+    templateVersionId?: number | string;
+    team?: string;
+    cpu?: number;
+    memoryMb?: number;
+    diskMb?: number;
+    networkClass?: string;
+    allowPackageRegistryAccess?: boolean;
+    exposedPorts?: unknown[];
+    mcp?: unknown;
+    volumeMounts?: unknown;
+}
+export interface SandboxConnectOpts extends ConnectionOpts {
+    /** Optional new sandbox lifetime in milliseconds. */
+    timeoutMs?: number;
+}
+export interface SandboxInfo {
+    sandboxId: string;
+    templateVersionId?: number;
+    state?: string;
+    metadata: Record<string, string>;
+    startedAt?: string;
+    endAt?: string;
+}
+/** 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";
+    files: Filesystem;
+    commands: Commands;
+    readonly sandboxId: string;
+    readonly pty: {
+        create: () => never;
+    };
+    readonly git: {
+        clone: () => never;
+    };
+    private readonly config;
+    private readonly control;
+    private dataPlane;
+    private sandbox;
+    constructor(opts: {
+        sandboxId: string;
+        connectionConfig: ConnectionConfig;
+        control?: ControlClient;
+        session: unknown;
+        sandbox?: Record<string, unknown>;
+        envs?: Record<string, 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>;
+    /** Refresh this sandbox's data-plane session in place. */
+    connect(opts?: SandboxConnectOpts): Promise<this>;
+    /** Destroy a sandbox by id. */
+    static kill(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
+    /** Destroy this sandbox. */
+    kill(): 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>;
+    /** 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. */
+    getInfo(): Promise<SandboxInfo>;
+    /** List sandboxes visible to the configured API key. */
+    static list(opts?: ConnectionOpts & {
+        team?: string;
+    }): Promise<SandboxInfo[]>;
+    /** Return the public hostname for an exposed sandbox port. */
+    getHost(port: number): Promise<string>;
+    pause(): never;
+    resume(): never;
+    createSnapshot(): never;
+    checkpoint(): never;
+    restore(): never;
+}

package/dist/sandbox.js

@@ -0,0 +1,204 @@
+import { Commands } from './commands.js';
+import { ConnectionConfig, SESSION_OPERATION_REQUEST_TIMEOUT_MS } from './connectionConfig.js';
+import { DataPlaneClient, ControlClient } from './transport.js';
+import { SandboxError, unsupported } from './errors.js';
+import { Filesystem } from './filesystem.js';
+/** 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';
+    files;
+    commands;
+    sandboxId;
+    pty = { create: () => unsupported('sandbox.pty') };
+    git = { clone: () => unsupported('sandbox.git') };
+    config;
+    control;
+    dataPlane;
+    sandbox;
+    constructor(opts) {
+        this.sandboxId = String(opts.sandboxId);
+        this.config = opts.connectionConfig;
+        this.control = opts.control ?? new ControlClient(this.config);
+        this.sandbox = opts.sandbox ?? {};
+        const dataPlane = dataPlaneFromSession(opts.session, this.config);
+        this.dataPlane = dataPlane;
+        this.files = new Filesystem(dataPlane);
+        this.commands = new Commands(dataPlane, this.config, opts.envs ?? {});
+    }
+    /** Create a sandbox and return it only after the API supplies a data-plane session. */
+    static async create(templateOrOpts, opts = {}) {
+        const template = typeof templateOrOpts === 'string'
+            ? templateOrOpts
+            : templateOrOpts?.template ?? Sandbox.defaultTemplate;
+        const sandboxOpts = typeof templateOrOpts === 'string' ? opts : templateOrOpts ?? {};
+        if (sandboxOpts.mcp !== undefined)
+            unsupported('mcp');
+        if (sandboxOpts.volumeMounts !== undefined)
+            unsupported('volumeMounts');
+        const config = new ConnectionConfig(sandboxOpts);
+        const control = new ControlClient(config);
+        const sandboxPayload = {
+            template,
+            timeout_seconds: Math.ceil((sandboxOpts.timeoutMs ?? 300_000) / 1000),
+            metadata: sandboxOpts.metadata ?? {},
+            allow_internet_access: sandboxOpts.allowInternetAccess ?? true,
+        };
+        putIfPresent(sandboxPayload, 'template_version_id', sandboxOpts.templateVersionId);
+        putIfPresent(sandboxPayload, 'team', sandboxOpts.team);
+        putIfPresent(sandboxPayload, 'cpu', sandboxOpts.cpu);
+        putIfPresent(sandboxPayload, 'memory_mb', sandboxOpts.memoryMb);
+        putIfPresent(sandboxPayload, 'disk_mb', sandboxOpts.diskMb);
+        putIfPresent(sandboxPayload, 'network_class', sandboxOpts.networkClass);
+        putIfPresent(sandboxPayload, 'allow_package_registry_access', sandboxOpts.allowPackageRegistryAccess);
+        putIfPresent(sandboxPayload, 'exposed_ports', sandboxOpts.exposedPorts);
+        const response = await control.post('/sandboxes', {
+            json: { sandbox: sandboxPayload },
+            requestTimeoutMs: sessionOperationRequestTimeout(config, sandboxOpts),
+        });
+        const sandbox = record(response.sandbox ?? response);
+        const sandboxId = sandbox.id ?? sandbox.sandbox_id;
+        if (sandboxId === undefined)
+            throw new SandboxError('create response did not include sandbox id');
+        return new Sandbox({
+            sandboxId: String(sandboxId),
+            connectionConfig: config,
+            control,
+            session: response.session,
+            sandbox,
+            envs: sandboxOpts.envs,
+        });
+    }
+    /** 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`, {
+            json: { connect: opts.timeoutMs ? { timeout_seconds: Math.ceil(opts.timeoutMs / 1000) } : {} },
+            requestTimeoutMs: sessionOperationRequestTimeout(config, opts),
+        });
+        return new Sandbox({
+            sandboxId,
+            connectionConfig: config,
+            control,
+            session: response.session,
+            sandbox: record(response.sandbox ?? info.sandbox ?? {}),
+        });
+    }
+    /** Refresh this sandbox's data-plane session in place. */
+    async connect(opts = {}) {
+        const response = await this.control.post(`/sandboxes/${this.sandboxId}/connect`, {
+            json: { connect: opts.timeoutMs ? { timeout_seconds: Math.ceil(opts.timeoutMs / 1000) } : {} },
+            requestTimeoutMs: sessionOperationRequestTimeout(this.config, opts),
+        });
+        this.sandbox = record(response.sandbox ?? this.sandbox);
+        const dataPlane = dataPlaneFromSession(response.session, this.config);
+        this.dataPlane = dataPlane;
+        this.files = new Filesystem(dataPlane);
+        this.commands = new Commands(dataPlane, this.config);
+        return this;
+    }
+    /** Destroy a sandbox by id. */
+    static async kill(sandboxId, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        await control.delete(`/sandboxes/${sandboxId}`);
+        return true;
+    }
+    /** Destroy this sandbox. */
+    async kill() {
+        await this.control.delete(`/sandboxes/${this.sandboxId}`);
+        return true;
+    }
+    /** Set a sandbox's lifetime by id. */
+    static async setTimeout(sandboxId, timeoutMs, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        await control.patch(`/sandboxes/${sandboxId}`, {
+            json: { sandbox: { timeout_seconds: Math.ceil(timeoutMs / 1000) } },
+        });
+    }
+    /** Set this sandbox's lifetime. */
+    async setTimeout(timeoutMs) {
+        await this.control.patch(`/sandboxes/${this.sandboxId}`, {
+            json: { sandbox: { timeout_seconds: Math.ceil(timeoutMs / 1000) } },
+        });
+    }
+    /** 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}`);
+        return sandboxInfo(record(payload.sandbox ?? payload));
+    }
+    /** Fetch the latest control-plane metadata for this sandbox. */
+    async getInfo() {
+        const payload = await this.control.get(`/sandboxes/${this.sandboxId}`);
+        return sandboxInfo(record(payload.sandbox ?? payload));
+    }
+    /** 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 the public hostname for an exposed sandbox port. */
+    async getHost(port) {
+        const payload = await this.control.get(`/sandboxes/${this.sandboxId}/ports/${port}`);
+        const portInfo = record(payload.sandbox_port ?? payload.port ?? payload);
+        const value = portInfo.host ?? portInfo.url;
+        if (typeof value === 'string')
+            return hostOnly(value);
+        const routeToken = this.sandbox.route_token;
+        if (typeof routeToken !== 'string')
+            throw new SandboxError('port response did not include host or url');
+        return `p${port}-${routeToken}.sandbox.${this.config.dataPlaneDomain}`;
+    }
+    pause() { unsupported('Sandbox.pause'); }
+    resume() { unsupported('Sandbox.resume'); }
+    createSnapshot() { unsupported('Sandbox.createSnapshot'); }
+    checkpoint() { unsupported('Sandbox.checkpoint'); }
+    restore() { unsupported('Sandbox.restore'); }
+}
+function dataPlaneFromSession(session, config) {
+    const item = record(session);
+    const token = item.token ?? item.access_token;
+    const url = item.data_plane_url;
+    if (!session)
+        throw new SandboxError('sandbox session is required for data-plane operations');
+    if (typeof token !== 'string' || typeof url !== 'string') {
+        throw new SandboxError('sandbox session did not include data_plane_url and token');
+    }
+    return new DataPlaneClient(url, token, config);
+}
+function sessionOperationRequestTimeout(config, opts) {
+    if (opts.requestTimeoutMs !== undefined)
+        return opts.requestTimeoutMs;
+    return Math.max(config.requestTimeoutMs, SESSION_OPERATION_REQUEST_TIMEOUT_MS);
+}
+function sandboxInfo(payload) {
+    return {
+        sandboxId: String(payload.id ?? payload.sandbox_id ?? ''),
+        templateVersionId: typeof payload.template_version_id === 'number' ? payload.template_version_id : undefined,
+        state: typeof payload.state === 'string' ? payload.state : undefined,
+        metadata: recordOfStrings(payload.metadata),
+        startedAt: typeof payload.created_at === 'string' ? payload.created_at : undefined,
+        endAt: typeof payload.deadline_at === 'string' ? payload.deadline_at : undefined,
+    };
+}
+function putIfPresent(target, key, value) {
+    if (value !== undefined && value !== null)
+        target[key] = value;
+}
+function record(value) {
+    return value && typeof value === 'object' ? value : {};
+}
+function recordOfStrings(value) {
+    if (!value || typeof value !== 'object')
+        return {};
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, String(item)]));
+}
+function hostOnly(value) {
+    if (value.includes('://'))
+        return new URL(value).host;
+    return value.split('/')[0];
+}

package/dist/transport.d.ts

@@ -0,0 +1,33 @@
+import { ConnectionConfig } from './connectionConfig.js';
+type JsonRecord = Record<string, unknown>;
+export declare class ControlClient {
+    private readonly config;
+    constructor(config: ConnectionConfig);
+    get(path: string, opts?: RequestOpts): Promise<JsonRecord>;
+    post(path: string, opts?: RequestOpts): Promise<JsonRecord>;
+    patch(path: string, opts?: RequestOpts): Promise<JsonRecord>;
+    delete(path: string, opts?: RequestOpts): Promise<JsonRecord>;
+    private request;
+}
+export declare class DataPlaneClient {
+    readonly baseUrl: string;
+    readonly token: string;
+    private readonly config;
+    constructor(baseUrl: string, token: string, config: ConnectionConfig);
+    getJson(path: string, opts?: RequestOpts): Promise<JsonRecord>;
+    postJson(path: string, opts?: RequestOpts): Promise<JsonRecord>;
+    deleteJson(path: string, opts?: RequestOpts): Promise<JsonRecord>;
+    getBytes(path: string, opts?: RequestOpts): Promise<Uint8Array>;
+    putJson(path: string, data: BodyInit | Uint8Array, opts?: RequestOpts): Promise<JsonRecord>;
+    raw(path: string, opts: RequestOpts): Promise<Response>;
+    private request;
+}
+export interface RequestOpts {
+    method?: string;
+    json?: unknown;
+    body?: BodyInit | Uint8Array;
+    headers?: Record<string, string>;
+    requestTimeoutMs?: number;
+}
+export declare function withQuery(path: string, params: Record<string, string | number | boolean | undefined>): string;
+export {};

package/dist/transport.js

@@ -0,0 +1,122 @@
+import { AuthenticationError, TimeoutError, errorFromResponse } from './errors.js';
+export class ControlClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    get(path, opts = {}) {
+        return this.request(path, { ...opts, method: 'GET' });
+    }
+    post(path, opts = {}) {
+        return this.request(path, { ...opts, method: 'POST' });
+    }
+    patch(path, opts = {}) {
+        return this.request(path, { ...opts, method: 'PATCH' });
+    }
+    delete(path, opts = {}) {
+        return this.request(path, { ...opts, method: 'DELETE' });
+    }
+    async request(path, opts) {
+        if (!this.config.apiKey) {
+            throw new AuthenticationError('WATASU_API_KEY is required');
+        }
+        const response = await fetchWithTimeout(joinUrl(this.config.apiUrl, path), {
+            method: opts.method,
+            headers: {
+                ...this.config.authHeaders,
+                ...(opts.json ? { 'content-type': 'application/json' } : {}),
+            },
+            body: opts.json ? JSON.stringify(opts.json) : undefined,
+        }, opts.requestTimeoutMs ?? this.config.requestTimeoutMs);
+        return parseJsonResponse(response);
+    }
+}
+export class DataPlaneClient {
+    baseUrl;
+    token;
+    config;
+    constructor(baseUrl, token, config) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+        this.config = config;
+    }
+    getJson(path, opts = {}) {
+        return this.request(path, { ...opts, method: 'GET' });
+    }
+    postJson(path, opts = {}) {
+        return this.request(path, { ...opts, method: 'POST' });
+    }
+    deleteJson(path, opts = {}) {
+        return this.request(path, { ...opts, method: 'DELETE' });
+    }
+    async getBytes(path, opts = {}) {
+        const response = await this.raw(path, { ...opts, method: 'GET' });
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    async putJson(path, data, opts = {}) {
+        return parseJsonResponse(await this.raw(path, {
+            ...opts,
+            method: 'PUT',
+            body: data,
+            headers: { 'content-type': 'application/octet-stream', ...(opts.headers ?? {}) },
+        }));
+    }
+    async raw(path, opts) {
+        const response = await fetchWithTimeout(joinUrl(this.baseUrl, path), {
+            method: opts.method,
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                ...(opts.json ? { 'content-type': 'application/json' } : {}),
+                ...(opts.headers ?? {}),
+            },
+            body: opts.json ? JSON.stringify(opts.json) : opts.body,
+        }, opts.requestTimeoutMs ?? this.config.requestTimeoutMs);
+        if (!response.ok) {
+            throw errorFromResponse(response.status, await readJsonOrText(response));
+        }
+        return response;
+    }
+    async request(path, opts) {
+        return parseJsonResponse(await this.raw(path, opts));
+    }
+}
+export function withQuery(path, params) {
+    const url = new URL(path, 'https://placeholder.local');
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            url.searchParams.set(key, String(value));
+    }
+    return `${url.pathname}${url.search}`;
+}
+async function parseJsonResponse(response) {
+    const payload = await readJsonOrText(response);
+    if (!response.ok) {
+        throw errorFromResponse(response.status, payload);
+    }
+    return payload && typeof payload === 'object' ? payload : {};
+}
+async function readJsonOrText(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { message: text };
+    }
+}
+function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    return fetch(url, { ...init, signal: controller.signal }).catch((error) => {
+        if (error?.name === 'AbortError')
+            throw new TimeoutError();
+        throw error;
+    }).finally(() => clearTimeout(timeout));
+}
+function joinUrl(base, path) {
+    const normalizedBase = base.replace(/\/+$/, '');
+    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+    return `${normalizedBase}${normalizedPath}`;
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@watasu/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT OR Apache-2.0",
+  "description": "TypeScript SDK for Watasu sandboxes",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.mjs"
+  },
+  "dependencies": {
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.3",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.7.0"
+  }
+}