@hyperbrowser/sdk 0.84.0 → 0.85.0

package/README.md

@@ -9,7 +9,9 @@ Hyperbrowser can be installed via npm by running:
 ```bash
 npm install @hyperbrowser/sdk
 ```
+
 or
+
 ```bash
 yarn add @hyperbrowser/sdk
 ```
@@ -17,6 +19,7 @@ yarn add @hyperbrowser/sdk
 ## Usage
 
 ### Playwright
+
 ```typescript
 import { chromium } from "playwright-core";
 import { Hyperbrowser } from "@hyperbrowser/sdk";
@@ -74,6 +77,7 @@ main();
 ```
 
 ### Puppeteer
+
 ```typescript
 import { connect } from "puppeteer-core";
 import { Hyperbrowser } from "@hyperbrowser/sdk";
@@ -131,3 +135,102 @@ const main = async () => {
 
 main();
 ```
+
+### Sandboxes
+
+For local sandbox development, you can explicitly route sandbox runtime traffic
+through a regional proxy override:
+
+```typescript
+const client = new Hyperbrowser({
+  apiKey: process.env.HYPERBROWSER_API_KEY,
+  runtimeProxyOverride: process.env.REGIONAL_PROXY_DEV_HOST,
+});
+```
+
+```typescript
+import { Hyperbrowser } from "@hyperbrowser/sdk";
+
+const client = new Hyperbrowser({
+  apiKey: process.env.HYPERBROWSER_API_KEY,
+});
+
+const main = async () => {
+  const sandbox = await client.sandboxes.create({
+    imageName: "ubuntu-24-node",
+    region: "us-west",
+  });
+
+  // Provide exactly one launch source:
+  // snapshotName or imageName.
+  // snapshotId requires snapshotName and imageId requires imageName.
+
+  const version = await sandbox.exec("node -v");
+  console.log(version.stdout.trim());
+
+  await sandbox.files.writeText("/tmp/hello.txt", "hello from sdk");
+
+  const content = await sandbox.files.readText("/tmp/hello.txt");
+  console.log(content);
+
+  const watch = await sandbox.files.watchDir(
+    "/tmp",
+    (event) => {
+      if (event.type === "write") {
+        console.log(event.name);
+      }
+    },
+    {
+      recursive: false,
+    }
+  );
+
+  await sandbox.files.writeText("/tmp/watch-demo.txt", "watch me");
+  await watch.stop();
+
+  const proc = await sandbox.processes.start({
+    command: "bash",
+    args: ["-lc", "echo process-started && sleep 1 && echo process-finished"],
+  });
+
+  for await (const event of proc.stream()) {
+    if (event.type === "stdout") {
+      process.stdout.write(event.data);
+    }
+  }
+
+  const terminal = await sandbox.terminal.create({
+    command: "bash",
+    cols: 120,
+    rows: 30,
+  });
+
+  const connection = await terminal.attach();
+  await connection.write("echo terminal-ok\n");
+
+  for await (const event of connection.events()) {
+    if (event.type === "output" && event.data.includes("terminal-ok")) {
+      break;
+    }
+  }
+
+  await connection.close();
+
+  const snapshot = await sandbox.createMemorySnapshot();
+  console.log(snapshot.snapshotId);
+
+  await sandbox.stop();
+};
+
+main().catch(console.error);
+```
+
+Reconnect an existing sandbox:
+
+```typescript
+const sandbox = await client.sandboxes.connect("sandbox-id");
+await sandbox.files.readText("/tmp/hello.txt");
+await sandbox.stop();
+```
+
+`connect()` refreshes runtime auth and throws if the sandbox is no longer running.

package/dist/client.d.ts

@@ -13,9 +13,26 @@ import { TeamService } from "./services/team";
 import { ComputerActionService } from "./services/computer-action";
 import { GeminiComputerUseService } from "./services/agents/gemini-computer-use";
 import { WebService } from "./services/web";
+import { SandboxesService } from "./services/sandboxes";
+export type HyperbrowserService = "control" | "runtime";
+export interface HyperbrowserErrorOptions {
+    statusCode?: number;
+    code?: string;
+    requestId?: string;
+    retryable?: boolean;
+    service?: HyperbrowserService;
+    details?: unknown;
+    cause?: unknown;
+}
 export declare class HyperbrowserError extends Error {
-    statusCode?: number | undefined;
-    constructor(message: string, statusCode?: number | undefined);
+    readonly statusCode?: number;
+    readonly code?: string;
+    readonly requestId?: string;
+    readonly retryable: boolean;
+    readonly service?: HyperbrowserService;
+    readonly details?: unknown;
+    readonly cause?: unknown;
+    constructor(message: string, options?: number | HyperbrowserErrorOptions);
 }
 export declare class HyperbrowserClient {
     readonly sessions: SessionsService;
@@ -34,5 +51,6 @@ export declare class HyperbrowserClient {
     };
     readonly team: TeamService;
     readonly computerAction: ComputerActionService;
+    readonly sandboxes: SandboxesService;
     constructor(config?: HyperbrowserConfig);
 }

package/dist/client.js

@@ -15,11 +15,19 @@ const team_1 = require("./services/team");
 const computer_action_1 = require("./services/computer-action");
 const gemini_computer_use_1 = require("./services/agents/gemini-computer-use");
 const web_1 = require("./services/web");
+const sandboxes_1 = require("./services/sandboxes");
 class HyperbrowserError extends Error {
-    constructor(message, statusCode) {
+    constructor(message, options = {}) {
         super(`[Hyperbrowser]: ${message}`);
-        this.statusCode = statusCode;
         this.name = "HyperbrowserError";
+        const normalized = typeof options === "number" ? { statusCode: options } : options;
+        this.statusCode = normalized.statusCode;
+        this.code = normalized.code;
+        this.requestId = normalized.requestId;
+        this.retryable = normalized.retryable ?? false;
+        this.service = normalized.service;
+        this.details = normalized.details;
+        this.cause = normalized.cause;
     }
 }
 exports.HyperbrowserError = HyperbrowserError;
@@ -28,6 +36,7 @@ class HyperbrowserClient {
         const apiKey = config.apiKey || process.env["HYPERBROWSER_API_KEY"];
         const baseUrl = config.baseUrl || "https://api.hyperbrowser.ai";
         const timeout = config.timeout || 30000;
+        const runtimeProxyOverride = config.runtimeProxyOverride?.trim() || undefined;
         if (!apiKey) {
             throw new HyperbrowserError("API key is required - either pass it in config or set HYPERBROWSER_API_KEY environment variable");
         }
@@ -40,6 +49,7 @@ class HyperbrowserClient {
         this.web = new web_1.WebService(apiKey, baseUrl, timeout);
         this.team = new team_1.TeamService(apiKey, baseUrl, timeout);
         this.computerAction = new computer_action_1.ComputerActionService(apiKey, baseUrl, timeout);
+        this.sandboxes = new sandboxes_1.SandboxesService(apiKey, baseUrl, timeout, runtimeProxyOverride);
         this.agents = {
             browserUse: new browser_use_1.BrowserUseService(apiKey, baseUrl, timeout),
             claudeComputerUse: new claude_computer_use_1.ClaudeComputerUseService(apiKey, baseUrl, timeout),

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { HyperbrowserClient } from "./client";
-export { HyperbrowserError } from "./client";
+import { HyperbrowserClient, HyperbrowserError } from "./client";
 export declare const Hyperbrowser: typeof HyperbrowserClient;
 export type Hyperbrowser = HyperbrowserClient;
+export { HyperbrowserClient, HyperbrowserError };
 export default HyperbrowserClient;

package/dist/index.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Hyperbrowser = exports.HyperbrowserError = void 0;
+exports.HyperbrowserError = exports.HyperbrowserClient = exports.Hyperbrowser = void 0;
 const client_1 = require("./client");
-var client_2 = require("./client");
-Object.defineProperty(exports, "HyperbrowserError", { enumerable: true, get: function () { return client_2.HyperbrowserError; } });
+Object.defineProperty(exports, "HyperbrowserClient", { enumerable: true, get: function () { return client_1.HyperbrowserClient; } });
+Object.defineProperty(exports, "HyperbrowserError", { enumerable: true, get: function () { return client_1.HyperbrowserError; } });
 // Export HyperbrowserClient as Hyperbrowser for named imports
 exports.Hyperbrowser = client_1.HyperbrowserClient;
 exports.default = client_1.HyperbrowserClient;
@@ -12,5 +12,6 @@ if (typeof module !== "undefined" && module.exports) {
     module.exports = client_1.HyperbrowserClient;
     module.exports.Hyperbrowser = client_1.HyperbrowserClient;
     module.exports.HyperbrowserClient = client_1.HyperbrowserClient;
+    module.exports.HyperbrowserError = client_1.HyperbrowserError;
     module.exports.default = client_1.HyperbrowserClient;
 }

package/dist/sandbox/base.d.ts

@@ -0,0 +1,28 @@
+import { RequestInit } from "node-fetch";
+export interface RuntimeConnection {
+    sandboxId: string;
+    baseUrl: string;
+    token: string;
+    directSessionHeader?: boolean;
+}
+export interface RuntimeSSEEvent {
+    event: string;
+    data: unknown;
+    id?: string;
+}
+type RuntimeParams = Record<string, string | number | boolean | undefined>;
+export declare class RuntimeTransport {
+    private readonly resolveConnection;
+    private readonly timeout;
+    private readonly runtimeProxyOverride?;
+    constructor(resolveConnection: (forceRefresh?: boolean) => Promise<RuntimeConnection>, timeout?: number, runtimeProxyOverride?: string | undefined);
+    requestJSON<T>(path: string, init?: RequestInit, params?: RuntimeParams): Promise<T>;
+    requestBuffer(path: string, init?: RequestInit, params?: RuntimeParams): Promise<Buffer>;
+    streamSSE(path: string, params?: RuntimeParams): AsyncGenerator<RuntimeSSEEvent>;
+    private fetchWithAuth;
+    private fetchForConnection;
+    private assertResponse;
+    private buildHeaders;
+    private normalizeBaseUrl;
+}
+export {};

package/dist/sandbox/base.js

@@ -0,0 +1,242 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeTransport = void 0;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const client_1 = require("../client");
+const ws_1 = require("./ws");
+const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
+const RETRYABLE_NETWORK_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "ESOCKETTIMEDOUT",
+]);
+const getRequestId = (response) => {
+    return response.headers.get("x-request-id") || response.headers.get("request-id") || undefined;
+};
+const isRetryableNetworkError = (error) => {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const networkError = error;
+    return (networkError.name === "AbortError" ||
+        networkError.type === "request-timeout" ||
+        (networkError.code ? RETRYABLE_NETWORK_CODES.has(networkError.code) : false));
+};
+class RuntimeTransport {
+    constructor(resolveConnection, timeout = 30000, runtimeProxyOverride) {
+        this.resolveConnection = resolveConnection;
+        this.timeout = timeout;
+        this.runtimeProxyOverride = runtimeProxyOverride;
+    }
+    async requestJSON(path, init, params) {
+        const response = await this.fetchWithAuth(path, init, params);
+        if (response.headers.get("content-length") === "0") {
+            return {};
+        }
+        try {
+            return (await response.json());
+        }
+        catch {
+            throw new client_1.HyperbrowserError("Failed to parse JSON response", {
+                statusCode: response.status,
+                requestId: getRequestId(response),
+                retryable: false,
+                service: "runtime",
+            });
+        }
+    }
+    async requestBuffer(path, init, params) {
+        const response = await this.fetchWithAuth(path, init, params);
+        return response.buffer();
+    }
+    async *streamSSE(path, params) {
+        const response = await this.fetchWithAuth(path, {
+            method: "GET",
+            headers: {
+                Accept: "text/event-stream",
+            },
+        }, params);
+        const body = response.body;
+        if (!body) {
+            return;
+        }
+        let buffer = "";
+        let eventName = "message";
+        let eventId;
+        let dataLines = [];
+        const flushEvent = () => {
+            if (dataLines.length === 0 && eventName === "message" && eventId === undefined) {
+                return null;
+            }
+            const rawData = dataLines.join("\n");
+            let data = rawData;
+            if (rawData) {
+                try {
+                    data = JSON.parse(rawData);
+                }
+                catch {
+                    data = rawData;
+                }
+            }
+            const event = {
+                event: eventName,
+                data,
+                id: eventId,
+            };
+            eventName = "message";
+            eventId = undefined;
+            dataLines = [];
+            return event;
+        };
+        for await (const chunk of body) {
+            buffer += Buffer.from(chunk).toString("utf8");
+            while (true) {
+                const newlineIndex = buffer.indexOf("\n");
+                if (newlineIndex === -1) {
+                    break;
+                }
+                let line = buffer.slice(0, newlineIndex);
+                buffer = buffer.slice(newlineIndex + 1);
+                if (line.endsWith("\r")) {
+                    line = line.slice(0, -1);
+                }
+                if (line === "") {
+                    const event = flushEvent();
+                    if (event) {
+                        yield event;
+                    }
+                    continue;
+                }
+                if (line.startsWith(":")) {
+                    continue;
+                }
+                const separator = line.indexOf(":");
+                const field = separator === -1 ? line : line.slice(0, separator);
+                const value = separator === -1 ? "" : line.slice(separator + 1).replace(/^ /, "");
+                switch (field) {
+                    case "event":
+                        eventName = value || "message";
+                        break;
+                    case "data":
+                        dataLines.push(value);
+                        break;
+                    case "id":
+                        eventId = value;
+                        break;
+                    default:
+                        break;
+                }
+            }
+        }
+        const trailing = flushEvent();
+        if (trailing) {
+            yield trailing;
+        }
+    }
+    async fetchWithAuth(path, init, params, allowRefresh = true) {
+        const connection = await this.resolveConnection(false);
+        const response = await this.fetchForConnection(connection, path, init, params);
+        if (response.status === 401 && allowRefresh) {
+            const refreshed = await this.resolveConnection(true);
+            const retryResponse = await this.fetchForConnection(refreshed, path, init, params);
+            return this.assertResponse(retryResponse);
+        }
+        return this.assertResponse(response);
+    }
+    async fetchForConnection(connection, path, init, params) {
+        const url = new URL(path, this.normalizeBaseUrl(connection.baseUrl));
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined) {
+                    url.searchParams.append(key, String(value));
+                }
+            }
+        }
+        const target = (0, ws_1.resolveRuntimeTransportTarget)(connection.baseUrl, `${url.pathname}${url.search}`, this.runtimeProxyOverride);
+        const headers = this.buildHeaders(connection, init?.headers, target.hostHeader);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            return await (0, node_fetch_1.default)(target.url, {
+                ...init,
+                headers,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError(error instanceof Error ? error.message : "Unknown runtime request error", {
+                retryable: isRetryableNetworkError(error),
+                service: "runtime",
+                cause: error,
+            });
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    async assertResponse(response) {
+        if (response.ok) {
+            return response;
+        }
+        let message = `Runtime request failed: ${response.status} ${response.statusText}`;
+        let details;
+        let code;
+        try {
+            const rawText = await response.text();
+            if (rawText) {
+                try {
+                    const parsed = JSON.parse(rawText);
+                    details = parsed;
+                    code = typeof parsed.code === "string" ? parsed.code : undefined;
+                    message = parsed.message || parsed.error || rawText;
+                }
+                catch {
+                    details = rawText;
+                    message = rawText;
+                }
+            }
+        }
+        catch {
+            // Keep the fallback message.
+        }
+        throw new client_1.HyperbrowserError(message, {
+            statusCode: response.status,
+            code,
+            requestId: getRequestId(response),
+            retryable: RETRYABLE_STATUS_CODES.has(response.status),
+            service: "runtime",
+            details,
+        });
+    }
+    buildHeaders(connection, rawHeaders, hostHeader) {
+        const headers = {
+            Authorization: `Bearer ${connection.token}`,
+        };
+        if (connection.directSessionHeader) {
+            headers["x-session-id"] = connection.sandboxId;
+        }
+        if (rawHeaders && typeof rawHeaders === "object" && !Array.isArray(rawHeaders)) {
+            for (const [key, value] of Object.entries(rawHeaders)) {
+                if (value !== undefined) {
+                    headers[key] = String(value);
+                }
+            }
+        }
+        if (hostHeader && headers.host === undefined && headers.Host === undefined) {
+            headers.Host = hostHeader;
+        }
+        return headers;
+    }
+    normalizeBaseUrl(baseUrl) {
+        return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+    }
+}
+exports.RuntimeTransport = RuntimeTransport;

package/dist/sandbox/files.d.ts

@@ -0,0 +1,92 @@
+import { Blob, Buffer } from "buffer";
+import { ReadableStream } from "node:stream/web";
+import { RuntimeTransport } from "./base";
+import { SandboxFileChmodParams, SandboxFileChownParams, SandboxFileCopyParams, SandboxFileInfo, SandboxFileListOptions, SandboxFileMakeDirOptions, SandboxFileReadOptions, SandboxFileSystemEvent, SandboxFileTransferResult, SandboxFileWriteData, SandboxFileWriteEntry, SandboxFileWriteInfo, SandboxFileBytesWriteOptions, SandboxFileTextWriteOptions, SandboxPresignFileParams, SandboxPresignedUrl, SandboxWatchDirOptions } from "../types/sandbox";
+interface RawFileWatchEvent {
+    seq: number;
+    path: string;
+    op: string;
+    timestamp: number;
+}
+interface RawFileWatchStatus {
+    id: string;
+    path: string;
+    recursive: boolean;
+    active: boolean;
+    error?: string;
+    createdAt: number;
+    stoppedAt?: number;
+    oldestSeq?: number;
+    lastSeq?: number;
+    eventCount?: number;
+}
+interface RuntimeConnectionInfo {
+    sandboxId: string;
+    baseUrl: string;
+    token: string;
+}
+declare class RuntimeFileWatchHandle {
+    private readonly transport;
+    private readonly getConnectionInfo;
+    private readonly status;
+    private readonly runtimeProxyOverride?;
+    constructor(transport: RuntimeTransport, getConnectionInfo: () => Promise<RuntimeConnectionInfo>, status: RawFileWatchStatus, runtimeProxyOverride?: string | undefined);
+    get id(): string;
+    get path(): string;
+    stop(): Promise<void>;
+    events(cursor?: number): AsyncGenerator<RawFileWatchEvent>;
+}
+export declare class SandboxWatchDirHandle {
+    private readonly watch;
+    private readonly onExit?;
+    private readonly runPromise;
+    private timeout?;
+    private stopRequested;
+    private exitNotified;
+    constructor(watch: RuntimeFileWatchHandle, onEvent: (event: SandboxFileSystemEvent) => void | Promise<void>, onExit?: ((error?: Error) => void | Promise<void>) | undefined, timeoutMs?: number);
+    stop(): Promise<void>;
+    private run;
+}
+export declare class SandboxFilesApi {
+    private readonly transport;
+    private readonly getConnectionInfo;
+    private readonly runtimeProxyOverride?;
+    constructor(transport: RuntimeTransport, getConnectionInfo: () => Promise<RuntimeConnectionInfo>, runtimeProxyOverride?: string | undefined);
+    exists(path: string): Promise<boolean>;
+    getInfo(path: string): Promise<SandboxFileInfo>;
+    list(path: string, options?: SandboxFileListOptions): Promise<SandboxFileInfo[]>;
+    read(path: string, options?: SandboxFileReadOptions & {
+        format?: "text";
+    }): Promise<string>;
+    read(path: string, options: SandboxFileReadOptions & {
+        format: "bytes";
+    }): Promise<Buffer>;
+    read(path: string, options: SandboxFileReadOptions & {
+        format: "blob";
+    }): Promise<Blob>;
+    read(path: string, options: SandboxFileReadOptions & {
+        format: "stream";
+    }): Promise<ReadableStream<Uint8Array>>;
+    readText(path: string, options?: Omit<SandboxFileReadOptions, "format">): Promise<string>;
+    readBytes(path: string, options?: Omit<SandboxFileReadOptions, "format">): Promise<Buffer>;
+    write(path: string, data: SandboxFileWriteData): Promise<SandboxFileWriteInfo>;
+    write(files: SandboxFileWriteEntry[]): Promise<SandboxFileWriteInfo[]>;
+    writeText(path: string, data: string, options?: SandboxFileTextWriteOptions): Promise<SandboxFileWriteInfo>;
+    writeBytes(path: string, data: Uint8Array, options?: SandboxFileBytesWriteOptions): Promise<SandboxFileWriteInfo>;
+    upload(path: string, data: Buffer | Uint8Array | string): Promise<SandboxFileTransferResult>;
+    download(path: string): Promise<Buffer>;
+    makeDir(path: string, options?: SandboxFileMakeDirOptions): Promise<boolean>;
+    rename(oldPath: string, newPath: string): Promise<SandboxFileInfo>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    copy(params: SandboxFileCopyParams): Promise<SandboxFileInfo>;
+    chmod(params: SandboxFileChmodParams): Promise<void>;
+    chown(params: SandboxFileChownParams): Promise<void>;
+    watchDir(path: string, onEvent: (event: SandboxFileSystemEvent) => void | Promise<void>, options?: SandboxWatchDirOptions): Promise<SandboxWatchDirHandle>;
+    uploadUrl(path: string, options?: Omit<SandboxPresignFileParams, "path">): Promise<SandboxPresignedUrl>;
+    downloadUrl(path: string, options?: Omit<SandboxPresignFileParams, "path">): Promise<SandboxPresignedUrl>;
+    private readWire;
+    private writeSingle;
+}
+export {};