@watasu/sdk 0.1.4 → 0.1.6

package/README.md

@@ -26,4 +26,67 @@ await sbx.kill()
 `Sandbox.create` and `Sandbox.connect` return only after the Watasu API supplies
 a usable data-plane session. The SDK does not poll sandbox readiness.
 
+## Git, Watch, PTY, And Signed File URLs
+
+```ts
+const sbx = await Sandbox.create()
+
+await sbx.git.clone('https://github.com/acme/project.git', {
+  path: '/workspace/project',
+  branch: 'main',
+  depth: 1,
+})
+const status = await sbx.git.status('/workspace/project')
+await sbx.git.configureUser('Watasu Bot', 'bot@watasu.local', {
+  scope: 'local',
+  path: '/workspace/project',
+})
+await sbx.git.createBranch('/workspace/project', 'feature/docs')
+await sbx.git.add('/workspace/project', { files: ['README.md'] })
+await sbx.git.commit('/workspace/project', 'Update docs', {
+  authorName: 'Watasu Bot',
+  authorEmail: 'bot@watasu.local',
+})
+await sbx.git.push('/workspace/project', {
+  remote: 'origin',
+  branch: 'feature/docs',
+  setUpstream: true,
+})
+
+const watcher = await sbx.files.watchDir('/workspace/project', (event) => {
+  console.log(event.type, event.path)
+}, { recursive: true })
+
+const terminal = await sbx.pty.create({
+  cols: 100,
+  rows: 30,
+  onData: (data) => process.stdout.write(data),
+})
+await terminal.sendStdin('echo hello\n')
+
+const uploadUrl = await sbx.uploadUrl('/workspace/input.bin')
+const downloadUrl = await sbx.downloadUrl('/workspace/output.bin')
+
+watcher.stop()
+await terminal.kill()
+await sbx.kill()
+```
+
+## Metrics And Snapshots
+
+```ts
+import { Sandbox } from '@watasu/sdk'
+
+const sbx = await Sandbox.create()
+const metrics = await sbx.getMetrics()
+const snapshot = await sbx.createSnapshot({ name: 'ready' })
+const snapshots = await sbx.listSnapshots().nextItems()
+const restored = await sbx.restore({ snapshotId: snapshot.snapshotId })
+await sbx.deleteSnapshot(snapshot.snapshotId)
+await sbx.kill()
+```
+
+Watasu snapshots are backed by sandbox checkpoints. Use the returned
+`snapshotId` when restoring from a checkpoint.
+
 The SDK is ESM-first and ships TypeScript declarations.

package/dist/commands.d.ts

@@ -34,6 +34,7 @@ export interface CommandStartOpts {
     envs?: Record<string, string>;
     onStdout?: (data: string) => void | Promise<void>;
     onStderr?: (data: string) => void | Promise<void>;
+    onPty?: (data: Uint8Array) => void | Promise<void>;
     stdin?: boolean;
     timeoutMs?: number;
     requestTimeoutMs?: number;
@@ -46,11 +47,12 @@ export declare class CommandHandle implements Partial<CommandResult> {
     private readonly events;
     private readonly onStdout?;
     private readonly onStderr?;
+    private readonly onPty?;
     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);
+    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, onPty?: ((data: Uint8Array) => void | Promise<void>) | undefined);
     get stdout(): string;
     get stderr(): string;
     get exitCode(): number | undefined;
@@ -61,6 +63,11 @@ export declare class CommandHandle implements Partial<CommandResult> {
     kill(): Promise<boolean>;
     /** Send stdin bytes or text to the process. */
     sendStdin(data: string | Uint8Array): Promise<void>;
+    /** Resize the attached PTY stream when this handle was created as a PTY. */
+    resize(size: {
+        cols: number;
+        rows: number;
+    }): Promise<void>;
     /** Detach the local stream without killing the process. */
     disconnect(): void;
     private handleEvents;

package/dist/commands.js

@@ -1,4 +1,4 @@
-import { ProcessSocket, base64DecodeText } from './processSocket.js';
+import { ProcessSocket, base64DecodeBytes, 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 {
@@ -21,17 +21,19 @@ export class CommandHandle {
     events;
     onStdout;
     onStderr;
+    onPty;
     _stdout = '';
     _stderr = '';
     result;
     pending;
-    constructor(pid, socket, handleKill, events, onStdout, onStderr) {
+    constructor(pid, socket, handleKill, events, onStdout, onStderr, onPty) {
         this.pid = pid;
         this.socket = socket;
         this.handleKill = handleKill;
         this.events = events;
         this.onStdout = onStdout;
         this.onStderr = onStderr;
+        this.onPty = onPty;
         this.pending = this.handleEvents();
     }
     get stdout() { return this._stdout; }
@@ -55,6 +57,10 @@ export class CommandHandle {
     async sendStdin(data) {
         this.socket.sendStdin(data);
     }
+    /** Resize the attached PTY stream when this handle was created as a PTY. */
+    async resize(size) {
+        this.socket.sendJson({ type: 'resize', cols: size.cols, rows: size.rows });
+    }
     /** Detach the local stream without killing the process. */
     disconnect() {
         this.socket.close();
@@ -75,6 +81,12 @@ export class CommandHandle {
                     this._stderr += out;
                     await this.onStderr?.(out);
                 }
+                else if (type === 'pty') {
+                    const bytes = base64DecodeBytes(frame.data);
+                    const out = new TextDecoder().decode(bytes);
+                    this._stdout += out;
+                    await this.onPty?.(bytes);
+                }
                 else if (type === 'exit') {
                     this.result = {
                         exitCode: Number(frame.exit_code ?? frame.exitCode ?? 0),
@@ -140,7 +152,7 @@ export class Commands {
         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);
+        return new CommandHandle(actualPid, socket, () => this.kill(actualPid), socket, opts.onStdout, opts.onStderr, opts.onPty);
     }
     async start(cmd, opts) {
         const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, '/runtime/v1/process', opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
@@ -160,7 +172,7 @@ export class Commands {
         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);
+        return new CommandHandle(pid, socket, () => this.kill(pid), withFirst(first, socket), opts.onStdout, opts.onStderr, opts.onPty);
     }
 }
 async function nextStarted(events) {

package/dist/filesystem.d.ts

@@ -1,4 +1,5 @@
 import { DataPlaneClient } from './transport.js';
+import { ProcessFrame, ProcessSocket } from './processSocket.js';
 export declare enum FileType {
     /** Regular file. */
     FILE = "file",
@@ -20,6 +21,31 @@ export interface EntryInfo {
     metadata?: Record<string, string>;
 }
 export type WriteInfo = EntryInfo;
+export interface FilesystemEvent {
+    type: 'create' | 'write' | 'modify' | 'remove' | 'delete' | 'rename' | string;
+    path: string;
+    entry?: EntryInfo;
+    raw: Record<string, unknown>;
+}
+export interface WatchOpts {
+    recursive?: boolean;
+    includeEntry?: boolean;
+    requestTimeoutMs?: number;
+    onExit?: (error?: Error) => void | Promise<void>;
+}
+/** Live filesystem watcher. Call `stop()` to close the local watch stream. */
+export declare class WatchHandle {
+    private readonly socket;
+    private readonly done;
+    constructor(socket: ProcessSocket, events: AsyncIterable<ProcessFrame>, onEvent: (event: FilesystemEvent) => void | Promise<void>, onExit?: (error?: Error) => void | Promise<void>);
+    /** Stop watching the directory. */
+    stop(): void;
+    /** Alias for `stop`. */
+    close(): void;
+    /** Resolves when the watcher stream exits. */
+    wait(): Promise<void>;
+    private pump;
+}
 /** Filesystem helper for a sandbox data-plane session. */
 export declare class Filesystem {
     private readonly dataPlane;
@@ -61,5 +87,6 @@ export declare class Filesystem {
     makeDir(path: string, opts?: {
         requestTimeoutMs?: number;
     }): Promise<boolean>;
-    watchDir(): never;
+    /** Start watching a directory for filesystem events. */
+    watchDir(path: string, onEvent: (event: FilesystemEvent) => void | Promise<void>, opts?: WatchOpts): Promise<WatchHandle>;
 }

package/dist/filesystem.js

@@ -1,5 +1,6 @@
 import { withQuery } from './transport.js';
-import { FileNotFoundError, unsupported } from './errors.js';
+import { FileNotFoundError } from './errors.js';
+import { ProcessSocket } from './processSocket.js';
 export var FileType;
 (function (FileType) {
     /** Regular file. */
@@ -9,6 +10,46 @@ export var FileType;
     /** Symbolic link. */
     FileType["SYMLINK"] = "symlink";
 })(FileType || (FileType = {}));
+/** Live filesystem watcher. Call `stop()` to close the local watch stream. */
+export class WatchHandle {
+    socket;
+    done;
+    constructor(socket, events, onEvent, onExit) {
+        this.socket = socket;
+        this.done = this.pump(events, onEvent, onExit);
+    }
+    /** Stop watching the directory. */
+    stop() {
+        this.socket.close();
+    }
+    /** Alias for `stop`. */
+    close() {
+        this.stop();
+    }
+    /** Resolves when the watcher stream exits. */
+    wait() {
+        return this.done;
+    }
+    async pump(events, onEvent, onExit) {
+        let error;
+        try {
+            for await (const frame of events) {
+                if (frame.type !== 'events' || !Array.isArray(frame.events))
+                    continue;
+                for (const item of frame.events) {
+                    await onEvent(filesystemEvent(item));
+                }
+            }
+        }
+        catch (caught) {
+            error = caught instanceof Error ? caught : new Error(String(caught));
+            throw error;
+        }
+        finally {
+            await onExit?.(error);
+        }
+    }
+}
 /** Filesystem helper for a sandbox data-plane session. */
 export class Filesystem {
     dataPlane;
@@ -70,8 +111,10 @@ export class Filesystem {
         await this.dataPlane.postJson(withQuery('/runtime/v1/directories', { path }), opts);
         return true;
     }
-    watchDir() {
-        unsupported('sandbox.files.watchDir');
+    /** Start watching a directory for filesystem events. */
+    async watchDir(path, onEvent, opts = {}) {
+        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, withQuery('/runtime/v1/files/watch', { path, recursive: opts.recursive ?? false, include_entry: opts.includeEntry }), opts.requestTimeoutMs).connect();
+        return new WatchHandle(socket, socket, onEvent, opts.onExit);
     }
 }
 function entryInfo(value) {
@@ -96,3 +139,19 @@ function recordOfStrings(value) {
         return undefined;
     return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, String(item)]));
 }
+function filesystemEvent(value) {
+    const item = value && typeof value === 'object' ? value : {};
+    return {
+        type: normalizeEventType(String(item.type ?? 'modify')),
+        path: String(item.path ?? ''),
+        entry: item.file && typeof item.file === 'object' ? entryInfo(item.file) : undefined,
+        raw: item,
+    };
+}
+function normalizeEventType(value) {
+    if (value === 'delete')
+        return 'remove';
+    if (value === 'modify')
+        return 'write';
+    return value;
+}

package/dist/git.d.ts

@@ -0,0 +1,144 @@
+import { DataPlaneClient } from './transport.js';
+export interface GitCommandResult {
+    path?: string;
+    url?: string;
+    ref?: string;
+    branch?: string;
+    remote?: string;
+    name?: string;
+    value?: string;
+    branches?: string[];
+    currentBranch?: string;
+    stdout: string;
+    stderr: string;
+    command?: Record<string, unknown>;
+    raw: Record<string, unknown>;
+}
+export interface GitAuthOpts {
+    username?: string;
+    password?: string;
+    envs?: Record<string, string>;
+    timeout?: number;
+    timeoutMs?: number;
+    requestTimeoutMs?: number;
+}
+export interface GitCloneOpts extends GitAuthOpts {
+    path?: string;
+    branch?: string;
+    depth?: number;
+    recursive?: boolean;
+    submodules?: boolean;
+    dangerouslyStoreCredentials?: boolean;
+}
+export interface GitRequestOpts extends GitAuthOpts {
+}
+export interface GitPullOpts extends GitAuthOpts {
+    branch?: string;
+    remote?: string;
+}
+export interface GitPushOpts extends GitAuthOpts {
+    branch?: string;
+    remote?: string;
+    setUpstream?: boolean;
+}
+export interface GitCredentialOpts extends GitRequestOpts {
+    host?: string;
+    protocol?: string;
+}
+export interface GitConfigureUserOpts extends GitRequestOpts {
+    scope?: 'global' | 'local';
+    path?: string;
+}
+export interface GitBranchOpts extends GitRequestOpts {
+    force?: boolean;
+}
+export interface GitAddOpts extends GitRequestOpts {
+    files?: string[];
+}
+export interface GitCommitOpts extends GitRequestOpts {
+    authorName?: string;
+    authorEmail?: string;
+    allowEmpty?: boolean;
+}
+export interface GitRemoteAddOpts extends GitRequestOpts {
+    fetch?: boolean;
+    overwrite?: boolean;
+}
+export interface GitConfigOpts extends GitRequestOpts {
+    scope?: 'global' | 'local';
+    path?: string;
+}
+export interface GitBranches {
+    path?: string;
+    branches: string[];
+    currentBranch?: string;
+    result: GitCommandResult;
+}
+export interface GitFileStatus {
+    name: string;
+    status: string;
+    indexStatus: string;
+    workingTreeStatus: string;
+    staged: boolean;
+    renamedFrom?: string;
+}
+export interface GitStatus {
+    currentBranch?: string;
+    upstream?: string;
+    ahead: number;
+    behind: number;
+    detached: boolean;
+    fileStatus: GitFileStatus[];
+    isClean: boolean;
+    hasChanges: boolean;
+    hasStaged: boolean;
+    hasUntracked: boolean;
+    hasConflicts: boolean;
+    totalCount: number;
+    stagedCount: number;
+    unstagedCount: number;
+    untrackedCount: number;
+    conflictCount: number;
+    result: GitCommandResult;
+}
+/** Git helper backed by sandbox data-plane routes. */
+export declare class Git {
+    private readonly dataPlane;
+    constructor(dataPlane: DataPlaneClient);
+    /** Clone a repository into the sandbox. */
+    clone(url: string, opts?: GitCloneOpts): Promise<GitCommandResult>;
+    /** Store Git credentials in the sandbox credential helper. */
+    dangerouslyAuthenticate(opts: GitCredentialOpts & {
+        username: string;
+        password: string;
+    }): Promise<GitCommandResult>;
+    /** Configure Git author identity globally or for one repository. */
+    configureUser(name: string, email: string, opts?: GitConfigureUserOpts): Promise<GitCommandResult>;
+    /** Return parsed repository status for `path`. */
+    status(path: string, opts?: GitRequestOpts): Promise<GitStatus>;
+    /** Return branches and the current branch for `path`. */
+    branches(path: string, opts?: GitRequestOpts): Promise<GitBranches>;
+    /** Create and check out a new branch. */
+    createBranch(path: string, branch: string, opts?: GitRequestOpts): Promise<GitCommandResult>;
+    /** Delete a branch. */
+    deleteBranch(path: string, branch: string, opts?: GitBranchOpts): Promise<GitCommandResult>;
+    /** Stage files. Defaults to all files. */
+    add(path: string, opts?: GitAddOpts): Promise<GitCommandResult>;
+    /** Commit staged files. */
+    commit(path: string, message: string, opts?: GitCommitOpts): Promise<GitCommandResult>;
+    /** Pull the current branch with a fast-forward-only merge. */
+    pull(path: string, opts?: GitPullOpts): Promise<GitCommandResult>;
+    /** Push the current branch or a selected branch. */
+    push(path: string, opts?: GitPushOpts): Promise<GitCommandResult>;
+    /** Check out an arbitrary ref in a repository. */
+    checkout(path: string, ref: string, opts?: GitRequestOpts): Promise<GitCommandResult>;
+    /** Check out an existing branch in a repository. */
+    checkoutBranch(path: string, branch: string, opts?: GitRequestOpts): Promise<GitCommandResult>;
+    /** Add a remote. */
+    remoteAdd(path: string, name: string, url: string, opts?: GitRemoteAddOpts): Promise<GitCommandResult>;
+    /** Set a Git config value. */
+    setConfig(key: string, value: string, opts?: GitConfigOpts): Promise<GitCommandResult>;
+    /** Read a Git config value. */
+    getConfig(key: string, opts?: GitConfigOpts): Promise<string>;
+    private run;
+}

package/dist/git.js

@@ -0,0 +1,236 @@
+/** Git helper backed by sandbox data-plane routes. */
+export class Git {
+    dataPlane;
+    constructor(dataPlane) {
+        this.dataPlane = dataPlane;
+    }
+    /** Clone a repository into the sandbox. */
+    async clone(url, opts = {}) {
+        return this.run('/runtime/v1/git/clone', {
+            url,
+            ...gitOpts(opts),
+            ...pick(opts, ['path', 'branch', 'depth', 'recursive', 'submodules', 'username', 'password']),
+            dangerously_store_credentials: opts.dangerouslyStoreCredentials,
+        }, opts);
+    }
+    /** Store Git credentials in the sandbox credential helper. */
+    async dangerouslyAuthenticate(opts) {
+        return this.run('/runtime/v1/git/dangerously_authenticate', {
+            ...gitOpts(opts),
+            username: opts.username,
+            password: opts.password,
+            host: opts.host,
+            protocol: opts.protocol,
+        }, opts);
+    }
+    /** Configure Git author identity globally or for one repository. */
+    async configureUser(name, email, opts = {}) {
+        return this.run('/runtime/v1/git/configure_user', {
+            ...gitOpts(opts),
+            name,
+            email,
+            scope: opts.scope,
+            path: opts.path,
+        }, opts);
+    }
+    /** Return parsed repository status for `path`. */
+    async status(path, opts = {}) {
+        const result = await this.run('/runtime/v1/git/status', { path, ...gitOpts(opts) }, opts);
+        return parseGitStatus(result);
+    }
+    /** Return branches and the current branch for `path`. */
+    async branches(path, opts = {}) {
+        const result = await this.run('/runtime/v1/git/branches', { path, ...gitOpts(opts) }, opts);
+        return {
+            path: result.path,
+            branches: Array.isArray(result.raw.branches) ? result.raw.branches.map(String) : result.branches ?? [],
+            currentBranch: stringValue(result.raw.current_branch) ?? result.currentBranch,
+            result,
+        };
+    }
+    /** Create and check out a new branch. */
+    async createBranch(path, branch, opts = {}) {
+        return this.run('/runtime/v1/git/create_branch', { path, branch, ...gitOpts(opts) }, opts);
+    }
+    /** Delete a branch. */
+    async deleteBranch(path, branch, opts = {}) {
+        return this.run('/runtime/v1/git/delete_branch', { path, branch, force: opts.force, ...gitOpts(opts) }, opts);
+    }
+    /** Stage files. Defaults to all files. */
+    async add(path, opts = {}) {
+        return this.run('/runtime/v1/git/add', { path, files: opts.files, ...gitOpts(opts) }, opts);
+    }
+    /** Commit staged files. */
+    async commit(path, message, opts = {}) {
+        return this.run('/runtime/v1/git/commit', {
+            path,
+            message,
+            author_name: opts.authorName,
+            author_email: opts.authorEmail,
+            allow_empty: opts.allowEmpty,
+            ...gitOpts(opts),
+        }, opts);
+    }
+    /** Pull the current branch with a fast-forward-only merge. */
+    async pull(path, opts = {}) {
+        return this.run('/runtime/v1/git/pull', { path, ...gitOpts(opts), ...pick(opts, ['remote', 'branch', 'username', 'password']) }, opts);
+    }
+    /** Push the current branch or a selected branch. */
+    async push(path, opts = {}) {
+        return this.run('/runtime/v1/git/push', {
+            path,
+            ...gitOpts(opts),
+            ...pick(opts, ['remote', 'branch', 'username', 'password']),
+            set_upstream: opts.setUpstream,
+        }, opts);
+    }
+    /** Check out an arbitrary ref in a repository. */
+    async checkout(path, ref, opts = {}) {
+        return this.run('/runtime/v1/git/checkout', { path, ref, ...gitOpts(opts) }, opts);
+    }
+    /** Check out an existing branch in a repository. */
+    async checkoutBranch(path, branch, opts = {}) {
+        return this.checkout(path, branch, opts);
+    }
+    /** Add a remote. */
+    async remoteAdd(path, name, url, opts = {}) {
+        return this.run('/runtime/v1/git/remote_add', {
+            path,
+            name,
+            url,
+            fetch: opts.fetch,
+            overwrite: opts.overwrite,
+            ...gitOpts(opts),
+        }, opts);
+    }
+    /** Set a Git config value. */
+    async setConfig(key, value, opts = {}) {
+        return this.run('/runtime/v1/git/set_config', {
+            key,
+            value,
+            scope: opts.scope,
+            path: opts.path,
+            ...gitOpts(opts),
+        }, opts);
+    }
+    /** Read a Git config value. */
+    async getConfig(key, opts = {}) {
+        const result = await this.run('/runtime/v1/git/get_config', {
+            key,
+            scope: opts.scope,
+            path: opts.path,
+            ...gitOpts(opts),
+        }, opts);
+        return String(result.value ?? '');
+    }
+    async run(path, json, opts) {
+        const payload = await this.dataPlane.postJson(path, { json: compact(json), requestTimeoutMs: opts.requestTimeoutMs });
+        return gitResult(payload.git ?? payload);
+    }
+}
+function gitOpts(opts) {
+    return {
+        env_vars: opts.envs,
+        timeout_seconds: opts.timeout ?? (opts.timeoutMs === undefined ? undefined : Math.ceil(opts.timeoutMs / 1000)),
+    };
+}
+function pick(source, keys) {
+    const record = source;
+    return Object.fromEntries(keys.map((key) => [key, record[key]]));
+}
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+function gitResult(value) {
+    const item = value && typeof value === 'object' ? value : {};
+    return {
+        path: stringValue(item.path),
+        url: stringValue(item.url),
+        ref: stringValue(item.ref),
+        branch: stringValue(item.branch),
+        remote: stringValue(item.remote),
+        name: stringValue(item.name),
+        value: stringValue(item.value),
+        branches: Array.isArray(item.branches) ? item.branches.map(String) : undefined,
+        currentBranch: stringValue(item.current_branch),
+        stdout: String(item.stdout ?? ''),
+        stderr: String(item.stderr ?? ''),
+        command: item.command && typeof item.command === 'object' ? item.command : undefined,
+        raw: item,
+    };
+}
+function parseGitStatus(result) {
+    const fileStatus = [];
+    let currentBranch;
+    let upstream;
+    let ahead = 0;
+    let behind = 0;
+    let detached = false;
+    for (const line of result.stdout.split(/\r?\n/).filter(Boolean)) {
+        if (line.startsWith('## ')) {
+            const branchLine = line.slice(3);
+            detached = branchLine.includes('HEAD') && branchLine.includes('no branch');
+            const [branchPart, trackingPart] = branchLine.split('...');
+            currentBranch = branchPart?.replace(/\s+\[.*\]$/, '') || undefined;
+            if (trackingPart) {
+                const match = trackingPart.match(/^([^\s[]+)(?:\s+\[(.*)\])?/);
+                upstream = match?.[1];
+                const details = match?.[2] ?? '';
+                ahead = numberFrom(details, /ahead\s+(\d+)/);
+                behind = numberFrom(details, /behind\s+(\d+)/);
+            }
+            continue;
+        }
+        const indexStatus = line[0] ?? ' ';
+        const workingTreeStatus = line[1] ?? ' ';
+        const path = line.slice(3);
+        const [name, renamedFrom] = path.includes(' -> ') ? path.split(' -> ').reverse() : [path, undefined];
+        const status = statusName(indexStatus, workingTreeStatus);
+        fileStatus.push({ name, status, indexStatus, workingTreeStatus, staged: indexStatus !== ' ' && indexStatus !== '?', renamedFrom });
+    }
+    const stagedCount = fileStatus.filter((item) => item.staged).length;
+    const untrackedCount = fileStatus.filter((item) => item.status === 'untracked').length;
+    const conflictCount = fileStatus.filter((item) => item.status === 'conflict').length;
+    const totalCount = fileStatus.length;
+    return {
+        currentBranch,
+        upstream,
+        ahead,
+        behind,
+        detached,
+        fileStatus,
+        isClean: totalCount === 0,
+        hasChanges: totalCount > 0,
+        hasStaged: stagedCount > 0,
+        hasUntracked: untrackedCount > 0,
+        hasConflicts: conflictCount > 0,
+        totalCount,
+        stagedCount,
+        unstagedCount: totalCount - stagedCount,
+        untrackedCount,
+        conflictCount,
+        result,
+    };
+}
+function numberFrom(value, pattern) {
+    const match = value.match(pattern);
+    return match ? Number(match[1]) : 0;
+}
+function statusName(indexStatus, workingTreeStatus) {
+    if (indexStatus === '?' && workingTreeStatus === '?')
+        return 'untracked';
+    if (indexStatus === 'U' || workingTreeStatus === 'U' || indexStatus === 'A' && workingTreeStatus === 'A')
+        return 'conflict';
+    if (indexStatus === 'D' || workingTreeStatus === 'D')
+        return 'deleted';
+    if (indexStatus === 'R')
+        return 'renamed';
+    if (indexStatus === 'A')
+        return 'added';
+    if (indexStatus === 'M' || workingTreeStatus === 'M')
+        return 'modified';
+    return 'changed';
+}
+function stringValue(value) {
+    return typeof value === 'string' ? value : undefined;
+}

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 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 { Sandbox, SnapshotPaginator } from './sandbox.js';
+export type { CreateSnapshotOpts, RestoreSnapshotOpts, SandboxCreateOpts, SandboxConnectOpts, SandboxInfo, SandboxMetrics, SandboxUrlOpts, SnapshotInfo, FileUrlInfo, } 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';
+export { FileType, Filesystem, WatchHandle } from './filesystem.js';
+export type { EntryInfo, FilesystemEvent, WatchOpts, WriteInfo } from './filesystem.js';
+export { Git } from './git.js';
+export type { GitAddOpts, GitAuthOpts, GitBranches, GitBranchOpts, GitCloneOpts, GitCommandResult, GitConfigOpts, GitConfigureUserOpts, GitCredentialOpts, GitCommitOpts, GitFileStatus, GitPullOpts, GitPushOpts, GitRemoteAddOpts, GitRequestOpts, GitStatus, } from './git.js';
+export { Pty } from './pty.js';
+export type { PtyConnectOpts, PtyCreateOpts, PtySize } from './pty.js';
+export { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';

package/dist/index.js

@@ -1,6 +1,8 @@
 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 { Sandbox, SnapshotPaginator } from './sandbox.js';
 export { CommandExitError, CommandHandle, Commands } from './commands.js';
-export { FileType, Filesystem } from './filesystem.js';
-export { ProcessSocket, base64DecodeText, base64Encode } from './processSocket.js';
+export { FileType, Filesystem, WatchHandle } from './filesystem.js';
+export { Git } from './git.js';
+export { Pty } from './pty.js';
+export { ProcessSocket, base64DecodeBytes, base64DecodeText, base64Encode } from './processSocket.js';

package/dist/processSocket.d.ts

@@ -23,3 +23,4 @@ export declare class ProcessSocket implements AsyncIterable<ProcessFrame> {
 }
 export declare function base64Encode(bytes: Uint8Array): string;
 export declare function base64DecodeText(value: unknown): string;
+export declare function base64DecodeBytes(value: unknown): Uint8Array;

package/dist/processSocket.js

@@ -122,12 +122,17 @@ export function base64DecodeText(value) {
     if (typeof value !== 'string')
         return String(value ?? '');
     try {
-        return Buffer.from(value, 'base64').toString('utf8');
+        return Buffer.from(base64DecodeBytes(value)).toString('utf8');
     }
     catch {
         return value;
     }
 }
+export function base64DecodeBytes(value) {
+    if (typeof value !== 'string')
+        return new TextEncoder().encode(String(value ?? ''));
+    return new Uint8Array(Buffer.from(value, 'base64'));
+}
 function rawDataToText(message) {
     if (typeof message === 'string')
         return message;

package/dist/pty.d.ts

@@ -0,0 +1,33 @@
+import { CommandHandle, CommandStartOpts } from './commands.js';
+import { ConnectionConfig } from './connectionConfig.js';
+import { DataPlaneClient } from './transport.js';
+export interface PtySize {
+    cols: number;
+    rows: number;
+}
+export interface PtyCreateOpts extends Omit<CommandStartOpts, 'background' | 'onStdout' | 'onStderr'>, PtySize {
+    onData?: (data: Uint8Array) => void | Promise<void>;
+}
+export interface PtyConnectOpts {
+    onData?: (data: Uint8Array) => void | Promise<void>;
+    timeoutMs?: number;
+    requestTimeoutMs?: number;
+}
+/** PTY helper backed by the sandbox process WebSocket runtime. */
+export declare class Pty {
+    private readonly dataPlane;
+    private readonly config;
+    constructor(dataPlane: DataPlaneClient, config: ConnectionConfig);
+    /** Create an interactive shell PTY and return its live command handle. */
+    create(opts: PtyCreateOpts): Promise<CommandHandle>;
+    /** Connect to a running PTY by pid. */
+    connect(pid: number | string, opts?: PtyConnectOpts): Promise<CommandHandle>;
+    /** Send input bytes or text to a PTY. */
+    sendStdin(pid: number | string, data: string | Uint8Array, opts?: PtyConnectOpts): Promise<void>;
+    /** Alias for `sendStdin`. */
+    sendInput(pid: number | string, data: string | Uint8Array, opts?: PtyConnectOpts): Promise<void>;
+    /** Resize a running PTY. */
+    resize(pid: number | string, size: PtySize, opts?: PtyConnectOpts): Promise<void>;
+    /** Kill a running PTY. */
+    kill(pid: number | string): Promise<boolean>;
+}

package/dist/pty.js

@@ -0,0 +1,88 @@
+import { CommandHandle } from './commands.js';
+import { ProcessSocket } from './processSocket.js';
+import { SandboxError } from './errors.js';
+/** PTY helper backed by the sandbox process WebSocket runtime. */
+export class Pty {
+    dataPlane;
+    config;
+    constructor(dataPlane, config) {
+        this.dataPlane = dataPlane;
+        this.config = config;
+    }
+    /** Create an interactive shell PTY and return its live command handle. */
+    async create(opts) {
+        const socket = await new ProcessSocket(this.dataPlane.baseUrl, this.dataPlane.token, '/runtime/v1/process', opts.requestTimeoutMs ?? this.config.requestTimeoutMs).connect();
+        const envs = { TERM: 'xterm-256color', LANG: 'C.UTF-8', LC_ALL: 'C.UTF-8', ...(opts.envs ?? {}) };
+        socket.sendJson({
+            type: 'start',
+            cmd: '/bin/bash',
+            args: ['-i', '-l'],
+            cwd: opts.cwd,
+            user: opts.user,
+            environment: envs,
+            envs,
+            stdin: true,
+            pty: { cols: opts.cols, rows: opts.rows },
+            timeout_ms: opts.timeoutMs ?? 60_000,
+        });
+        const first = await nextStarted(socket);
+        const pid = framePid(first);
+        if (pid === undefined)
+            throw new SandboxError('PTY started frame did not include pid');
+        return new CommandHandle(pid, socket, () => this.kill(pid), withFirst(first, socket), undefined, undefined, opts.onData ?? opts.onPty);
+    }
+    /** Connect to a running PTY 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), withFirst(first, socket), undefined, undefined, opts.onData);
+    }
+    /** Send input bytes or text to a PTY. */
+    async sendStdin(pid, data, opts = {}) {
+        const handle = await this.connect(pid, opts);
+        try {
+            await handle.sendStdin(data);
+        }
+        finally {
+            handle.disconnect();
+        }
+    }
+    /** Alias for `sendStdin`. */
+    async sendInput(pid, data, opts = {}) {
+        return this.sendStdin(pid, data, opts);
+    }
+    /** Resize a running PTY. */
+    async resize(pid, size, opts = {}) {
+        const handle = await this.connect(pid, opts);
+        try {
+            await handle.resize(size);
+        }
+        finally {
+            handle.disconnect();
+        }
+    }
+    /** Kill a running PTY. */
+    async kill(pid) {
+        await this.dataPlane.postJson(`/runtime/v1/process/${pid}/signal`, {
+            json: { signal: 'SIGKILL' },
+        });
+        return true;
+    }
+}
+async function nextStarted(events) {
+    for await (const frame of events) {
+        if (frame.type === 'started')
+            return frame;
+    }
+    throw new SandboxError('PTY 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;
+}

package/dist/sandbox.d.ts

@@ -2,6 +2,8 @@ import { Commands } from './commands.js';
 import { ConnectionConfig, ConnectionOpts } from './connectionConfig.js';
 import { ControlClient } from './transport.js';
 import { Filesystem } from './filesystem.js';
+import { Git } from './git.js';
+import { Pty } from './pty.js';
 export interface SandboxCreateOpts extends ConnectionOpts {
     /** Template slug to create. Defaults to "base". */
     template?: string;
@@ -28,19 +30,66 @@ export interface SandboxInfo {
     startedAt?: string;
     endAt?: string;
 }
+export interface SandboxMetrics {
+    sandboxId?: string;
+    state?: string;
+    node?: string;
+    backend?: string;
+    cpuCount?: number;
+    memoryMb?: number;
+    raw: Record<string, unknown>;
+}
+export interface SnapshotInfo {
+    snapshotId: string;
+    sandboxId?: string;
+    name?: string;
+    status?: string;
+    sizeBytes?: number;
+    createdAt?: string;
+    expiresAt?: string;
+    raw: Record<string, unknown>;
+}
+export interface FileUrlInfo {
+    method: string;
+    path: string;
+    url: string;
+    expiresAt?: string;
+    raw: Record<string, unknown>;
+}
+export interface SandboxUrlOpts extends ConnectionOpts {
+    user?: string;
+    useSignatureExpiration?: number;
+    expiresInSeconds?: number;
+}
+export interface CreateSnapshotOpts extends ConnectionOpts {
+    name?: string;
+    metadata?: Record<string, string>;
+    expiresAt?: string;
+    quiesceMode?: string;
+}
+export interface RestoreSnapshotOpts extends ConnectionOpts {
+    checkpointId?: string | number;
+    snapshotId?: string | number;
+    timeout?: number;
+    timeoutMs?: number;
+}
+export declare class SnapshotPaginator {
+    private readonly loadItems;
+    private consumed;
+    hasNext: boolean;
+    nextToken: string | undefined;
+    constructor(loadItems: () => Promise<SnapshotInfo[]>);
+    nextItems(): Promise<SnapshotInfo[]>;
+}
 /** 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;
+    pty: Pty;
+    git: Git;
     readonly sandboxId: string;
-    readonly pty: {
-        create: () => never;
-    };
-    readonly git: {
-        clone: () => never;
-    };
     private readonly config;
     private readonly control;
     private readonly envs;
@@ -62,6 +111,16 @@ export declare class Sandbox {
     connect(opts?: SandboxConnectOpts): Promise<this>;
     /** Destroy a sandbox by id. */
     static kill(sandboxId: string, opts?: ConnectionOpts): Promise<boolean>;
+    /** Fetch sandbox metrics by id. */
+    static getMetrics(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxMetrics[]>;
+    /** Deprecated alias for `getInfo`. */
+    static getFullInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
+    /** Create a Watasu checkpoint using snapshot naming. */
+    static createSnapshot(sandboxId: string, opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
+    /** List checkpoints for one sandbox using snapshot naming. */
+    static listSnapshots(sandboxId: string, opts?: ConnectionOpts): SnapshotPaginator;
+    /** Delete a snapshot by id. Returns `false` when the snapshot does not exist. */
+    static deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<boolean>;
     /** Destroy this sandbox. */
     kill(): Promise<boolean>;
     /** Check if this sandbox is in a runtime-active lifecycle state. */
@@ -74,15 +133,36 @@ export declare class Sandbox {
     static getInfo(sandboxId: string, opts?: ConnectionOpts): Promise<SandboxInfo>;
     /** Fetch the latest control-plane metadata for this sandbox. */
     getInfo(): Promise<SandboxInfo>;
+    /** Fetch latest sandbox metrics. */
+    getMetrics(opts?: ConnectionOpts): Promise<SandboxMetrics[]>;
+    /** Create a Watasu checkpoint using snapshot naming. */
+    createSnapshot(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
+    /** Delete a snapshot by id. */
+    deleteSnapshot(snapshotId: string, opts?: ConnectionOpts): Promise<boolean>;
+    /** Watasu-native alias for `createSnapshot`. */
+    checkpoint(opts?: CreateSnapshotOpts): Promise<SnapshotInfo>;
+    /** List checkpoints for this sandbox using snapshot naming. */
+    listSnapshots(opts?: ConnectionOpts): SnapshotPaginator;
+    /** Restore a checkpoint into a new sandbox and return its control-plane info. */
+    restore(opts?: RestoreSnapshotOpts | string | number): Promise<SandboxInfo>;
     /** List sandboxes visible to the configured API key. */
     static list(opts?: ConnectionOpts & {
         team?: string;
     }): Promise<SandboxInfo[]>;
     /** Return the public hostname for an exposed sandbox port. */
     getHost(port: number): string;
+    /** Get a signed URL that accepts a POST upload for a sandbox file path. */
+    uploadUrl(path: string, opts?: SandboxUrlOpts): Promise<string>;
+    /** Get a signed URL that accepts a GET download for a sandbox file path. */
+    downloadUrl(path: string, opts?: SandboxUrlOpts): Promise<string>;
+    /** Get signed upload URL metadata for a sandbox file path. */
+    uploadUrlInfo(path: string, opts?: SandboxUrlOpts): Promise<FileUrlInfo>;
+    /** Get signed download URL metadata for a sandbox file path. */
+    downloadUrlInfo(path: string, opts?: SandboxUrlOpts): Promise<FileUrlInfo>;
+    updateNetwork(..._args: unknown[]): never;
     pause(): never;
+    betaPause(): never;
     resume(): never;
-    createSnapshot(): never;
-    checkpoint(): never;
-    restore(): never;
+    private fileUrl;
+    private configOptions;
 }

package/dist/sandbox.js

@@ -3,15 +3,33 @@ import { ConnectionConfig, SESSION_OPERATION_REQUEST_TIMEOUT_MS } from './connec
 import { DataPlaneClient, ControlClient } from './transport.js';
 import { NotFoundError, SandboxError, unsupported } from './errors.js';
 import { Filesystem } from './filesystem.js';
+import { Git } from './git.js';
+import { Pty } from './pty.js';
+export class SnapshotPaginator {
+    loadItems;
+    consumed = false;
+    hasNext = true;
+    nextToken;
+    constructor(loadItems) {
+        this.loadItems = loadItems;
+    }
+    async nextItems() {
+        if (this.consumed)
+            throw new SandboxError('No more snapshots to fetch');
+        this.consumed = true;
+        this.hasNext = false;
+        return this.loadItems();
+    }
+}
 /** 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;
+    pty;
+    git;
     sandboxId;
-    pty = { create: () => unsupported('sandbox.pty') };
-    git = { clone: () => unsupported('sandbox.git') };
     config;
     control;
     envs;
@@ -27,6 +45,8 @@ export class Sandbox {
         this.dataPlane = dataPlane;
         this.files = new Filesystem(dataPlane);
         this.commands = new Commands(dataPlane, this.config, this.envs);
+        this.pty = new Pty(dataPlane, this.config);
+        this.git = new Git(dataPlane);
     }
     /** Create a sandbox and return it only after the API supplies a data-plane session. */
     static async create(templateOrOpts, opts = {}) {
@@ -94,6 +114,8 @@ export class Sandbox {
         this.dataPlane = dataPlane;
         this.files = new Filesystem(dataPlane);
         this.commands = new Commands(dataPlane, this.config, this.envs);
+        this.pty = new Pty(dataPlane, this.config);
+        this.git = new Git(dataPlane);
         return this;
     }
     /** Destroy a sandbox by id. */
@@ -102,6 +124,53 @@ export class Sandbox {
         await control.delete(`/sandboxes/${sandboxId}`);
         return true;
     }
+    /** Fetch sandbox metrics by id. */
+    static async getMetrics(sandboxId, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        const payload = await control.get(`/sandboxes/${sandboxId}/metrics`, {
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return metricsList(payload.metrics ?? payload);
+    }
+    /** 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,
+        });
+        return snapshotInfo(record(payload.sandbox_checkpoint ?? payload.snapshot ?? payload));
+    }
+    /** List checkpoints for one sandbox using snapshot naming. */
+    static listSnapshots(sandboxId, opts = {}) {
+        return new SnapshotPaginator(async () => {
+            const control = new ControlClient(new ConnectionConfig(opts));
+            const payload = await control.get(`/sandboxes/${sandboxId}/checkpoints`, {
+                requestTimeoutMs: opts.requestTimeoutMs,
+            });
+            const snapshots = Array.isArray(payload.sandbox_checkpoints) ? payload.sandbox_checkpoints : [];
+            return snapshots.map((item) => snapshotInfo(record(item)));
+        });
+    }
+    /** Delete a snapshot by id. Returns `false` when the snapshot does not exist. */
+    static async deleteSnapshot(snapshotId, opts = {}) {
+        const control = new ControlClient(new ConnectionConfig(opts));
+        try {
+            await control.delete(`/sandbox_snapshots/${snapshotId}`, {
+                requestTimeoutMs: opts.requestTimeoutMs,
+            });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof NotFoundError)
+                return false;
+            throw error;
+        }
+    }
     /** Destroy this sandbox. */
     async kill() {
         await this.control.delete(`/sandboxes/${this.sandboxId}`);
@@ -146,6 +215,45 @@ export class Sandbox {
         const payload = await this.control.get(`/sandboxes/${this.sandboxId}`);
         return sandboxInfo(record(payload.sandbox ?? payload));
     }
+    /** Fetch latest sandbox metrics. */
+    async getMetrics(opts = {}) {
+        return Sandbox.getMetrics(this.sandboxId, { ...this.configOptions(), ...opts });
+    }
+    /** Create a Watasu checkpoint using snapshot naming. */
+    async createSnapshot(opts = {}) {
+        return Sandbox.createSnapshot(this.sandboxId, { ...this.configOptions(), ...opts });
+    }
+    /** Delete a snapshot by id. */
+    async deleteSnapshot(snapshotId, opts = {}) {
+        return Sandbox.deleteSnapshot(snapshotId, { ...this.configOptions(), ...opts });
+    }
+    /** Watasu-native alias for `createSnapshot`. */
+    async checkpoint(opts = {}) {
+        return this.createSnapshot(opts);
+    }
+    /** List checkpoints for this sandbox using snapshot naming. */
+    listSnapshots(opts = {}) {
+        return Sandbox.listSnapshots(this.sandboxId, { ...this.configOptions(), ...opts });
+    }
+    /** Restore a checkpoint into a new sandbox and return its control-plane info. */
+    async restore(opts = {}) {
+        const restoreOpts = typeof opts === 'string' || typeof opts === 'number'
+            ? { checkpointId: opts }
+            : opts;
+        const checkpointId = restoreOpts.checkpointId ?? restoreOpts.snapshotId;
+        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,
+        });
+        return sandboxInfo(record(response.sandbox ?? response));
+    }
     /** List sandboxes visible to the configured API key. */
     static async list(opts = {}) {
         const control = new ControlClient(new ConnectionConfig(opts));
@@ -162,11 +270,48 @@ export class Sandbox {
             throw new SandboxError('port response did not include host or url');
         return `p${port}-${routeToken}.sandbox.${this.config.dataPlaneDomain}`;
     }
+    /** Get a signed URL that accepts a POST upload for a sandbox file path. */
+    async uploadUrl(path, opts = {}) {
+        const fileUrl = await this.fileUrl('/upload_url', path, opts);
+        return fileUrl.url;
+    }
+    /** Get a signed URL that accepts a GET download for a sandbox file path. */
+    async downloadUrl(path, opts = {}) {
+        const fileUrl = await this.fileUrl('/download_url', path, opts);
+        return fileUrl.url;
+    }
+    /** Get signed upload URL metadata for a sandbox file path. */
+    async uploadUrlInfo(path, opts = {}) {
+        return this.fileUrl('/upload_url', path, opts);
+    }
+    /** Get signed download URL metadata for a sandbox file path. */
+    async downloadUrlInfo(path, opts = {}) {
+        return this.fileUrl('/download_url', path, opts);
+    }
+    updateNetwork(..._args) { unsupported('Sandbox.updateNetwork'); }
     pause() { unsupported('Sandbox.pause'); }
+    betaPause() { unsupported('Sandbox.betaPause'); }
     resume() { unsupported('Sandbox.resume'); }
-    createSnapshot() { unsupported('Sandbox.createSnapshot'); }
-    checkpoint() { unsupported('Sandbox.checkpoint'); }
-    restore() { unsupported('Sandbox.restore'); }
+    async fileUrl(route, path, opts) {
+        const payload = await this.control.post(`/sandboxes/${this.sandboxId}/files${route}`, {
+            json: compactRecord({
+                path,
+                user: opts.user,
+                use_signature_expiration: opts.useSignatureExpiration,
+                expires_in_seconds: opts.expiresInSeconds,
+            }),
+            requestTimeoutMs: opts.requestTimeoutMs,
+        });
+        return fileUrlInfo(record(payload.file_url ?? payload));
+    }
+    configOptions() {
+        return {
+            apiKey: this.config.apiKey,
+            apiUrl: this.config.apiUrl,
+            dataPlaneDomain: this.config.dataPlaneDomain,
+            requestTimeoutMs: this.config.requestTimeoutMs,
+        };
+    }
 }
 function dataPlaneFromSession(session, config) {
     const item = record(session);
@@ -179,6 +324,18 @@ function dataPlaneFromSession(session, config) {
     }
     return new DataPlaneClient(url, token, config);
 }
+function fileUrlInfo(payload) {
+    return {
+        method: String(payload.method ?? ''),
+        path: String(payload.path ?? ''),
+        url: String(payload.url ?? ''),
+        expiresAt: typeof payload.expires_at === 'string' ? payload.expires_at : typeof payload.expiresAt === 'string' ? payload.expiresAt : undefined,
+        raw: payload,
+    };
+}
+function compactRecord(payload) {
+    return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));
+}
 function sessionOperationRequestTimeout(config, opts) {
     if (opts.requestTimeoutMs !== undefined)
         return opts.requestTimeoutMs;
@@ -199,6 +356,55 @@ function sandboxInfo(payload) {
             : typeof payload.deadline_at === 'string' ? payload.deadline_at : undefined,
     };
 }
+function metricsList(value) {
+    if (Array.isArray(value))
+        return value.map((item) => metricsInfo(record(item)));
+    return [metricsInfo(record(value))];
+}
+function metricsInfo(value) {
+    return {
+        sandboxId: stringValue(value.sandbox_id ?? value.sandboxId),
+        state: stringValue(value.state),
+        node: stringValue(value.node),
+        backend: stringValue(value.backend),
+        cpuCount: numberValue(value.cpu_count ?? value.cpuCount),
+        memoryMb: numberValue(value.memory_mb ?? value.memoryMb),
+        raw: value,
+    };
+}
+function snapshotPayload(opts) {
+    const payload = {};
+    putIfPresent(payload, 'name', opts.name);
+    putIfPresent(payload, 'metadata', opts.metadata);
+    putIfPresent(payload, 'expires_at', opts.expiresAt);
+    putIfPresent(payload, 'quiesce_mode', opts.quiesceMode);
+    return payload;
+}
+function snapshotInfo(value) {
+    const id = value.snapshot_id ?? value.snapshotId ?? value.checkpoint_id ?? value.checkpointId ?? value.id;
+    if (id === undefined)
+        throw new SandboxError('snapshot response did not include id');
+    return {
+        snapshotId: String(id),
+        sandboxId: stringValue(value.sandbox_id ?? value.sandboxId),
+        name: stringValue(value.name),
+        status: stringValue(value.status),
+        sizeBytes: numberValue(value.size_bytes ?? value.sizeBytes),
+        createdAt: stringValue(value.created_at ?? value.createdAt),
+        expiresAt: stringValue(value.expires_at ?? value.expiresAt),
+        raw: value,
+    };
+}
+function stringValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return String(value);
+    return undefined;
+}
+function numberValue(value) {
+    return typeof value === 'number' ? value : undefined;
+}
 function templateSlug(value) {
     const template = record(value);
     return typeof template.slug === 'string' ? template.slug : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watasu/sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "license": "MIT OR Apache-2.0",
   "description": "TypeScript SDK for Watasu",
@@ -28,5 +28,10 @@
     "@types/node": "^24.0.3",
     "@types/ws": "^8.18.1",
     "typescript": "^5.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/watasuio/sdk.git",
+    "directory": "ts"
   }
 }