@hyperbrowser/sdk 0.87.1 → 0.88.0

package/README.md

@@ -234,3 +234,77 @@ await sandbox.stop();
 ```
 
 `connect()` refreshes runtime auth and throws if the sandbox is no longer running.
+
+Create a sandbox with pre-exposed ports:
+
+```typescript
+const sandbox = await client.sandboxes.create({
+  imageName: "node",
+  exposedPorts: [{ port: 3000, auth: true }],
+});
+
+console.log(sandbox.exposedPorts[0].browserUrl);
+```
+
+List sandboxes with time-range and search filters:
+
+```typescript
+const sandboxes = await client.sandboxes.list({
+  status: "active",
+  start: Date.now() - 60 * 60 * 1000,
+  end: Date.now(),
+  search: "sbx_",
+  limit: 25,
+});
+```
+
+List snapshots for a specific image:
+
+```typescript
+const snapshots = await client.sandboxes.listSnapshots({
+  imageName: "node",
+  status: "created",
+  limit: 10,
+});
+```
+
+Expose and unexpose ports:
+
+```typescript
+const sandbox = await client.sandboxes.create({ imageName: "node" });
+
+const exposure = await sandbox.expose({ port: 8080, auth: true });
+console.log(exposure.url, exposure.browserUrl, exposure.browserUrlExpiresAt);
+
+await sandbox.unexpose(8080);
+```
+
+Write batch files with per-entry options:
+
+```typescript
+await sandbox.files.write([
+  {
+    path: "/tmp/hello.txt",
+    data: "hello",
+    append: true,
+    mode: "600",
+  },
+  {
+    path: "/tmp/payload.bin",
+    data: Buffer.from([1, 2, 3]).toString("base64"),
+    encoding: "base64",
+  },
+]);
+```
+
+Resume a PTY attach from a cursor:
+
+```typescript
+const terminal = await sandbox.terminal.create({
+  command: "bash",
+  rows: 24,
+  cols: 80,
+});
+
+const connection = await terminal.attach(10);
+```

package/dist/sandbox/files.js

@@ -86,42 +86,40 @@ const bufferFromReadableStream = async (stream) => {
     }
     return buffer_1.Buffer.concat(chunks);
 };
-const encodeWriteData = async (data) => {
+const encodeBufferData = (buffer, encoding) => {
+    if (encoding === "utf8") {
+        return {
+            data: buffer.toString("utf8"),
+            encoding,
+        };
+    }
+    return {
+        data: buffer.toString("base64"),
+        encoding,
+    };
+};
+const encodeWriteData = async (data, encoding) => {
     if (typeof data === "string") {
+        const resolvedEncoding = encoding ?? "utf8";
         return {
             data,
-            encoding: "utf8",
+            encoding: resolvedEncoding,
         };
     }
     if (buffer_1.Buffer.isBuffer(data)) {
-        return {
-            data: data.toString("base64"),
-            encoding: "base64",
-        };
+        return encodeBufferData(data, encoding ?? "base64");
     }
     if (data instanceof Uint8Array) {
-        return {
-            data: buffer_1.Buffer.from(data).toString("base64"),
-            encoding: "base64",
-        };
+        return encodeBufferData(buffer_1.Buffer.from(data), encoding ?? "base64");
     }
     if (data instanceof ArrayBuffer) {
-        return {
-            data: buffer_1.Buffer.from(data).toString("base64"),
-            encoding: "base64",
-        };
+        return encodeBufferData(buffer_1.Buffer.from(data), encoding ?? "base64");
     }
     if (data instanceof buffer_1.Blob) {
-        return {
-            data: buffer_1.Buffer.from(await data.arrayBuffer()).toString("base64"),
-            encoding: "base64",
-        };
+        return encodeBufferData(buffer_1.Buffer.from(await data.arrayBuffer()), encoding ?? "base64");
     }
     if (isReadableStreamLike(data)) {
-        return {
-            data: (await bufferFromReadableStream(data)).toString("base64"),
-            encoding: "base64",
-        };
+        return encodeBufferData(await bufferFromReadableStream(data), encoding ?? "base64");
     }
     throw new Error("Unsupported write data type");
 };
@@ -327,7 +325,9 @@ class SandboxFilesApi {
             }
             return {
                 path: file.path,
-                ...(await encodeWriteData(file.data)),
+                ...(await encodeWriteData(file.data, file.encoding)),
+                append: file.append,
+                mode: file.mode,
             };
         }));
         const response = await this.transport.requestJSON("/sandbox/files/write", {

package/dist/sandbox/terminal.d.ts

@@ -32,7 +32,7 @@ export declare class SandboxTerminalHandle {
     kill(signal: string): Promise<SandboxTerminalStatus>;
     kill(params: SandboxTerminalKillParams): Promise<SandboxTerminalStatus>;
     resize(rows: number, cols: number): Promise<SandboxTerminalStatus>;
-    attach(): Promise<SandboxTerminalConnection>;
+    attach(cursor?: number | string): Promise<SandboxTerminalConnection>;
 }
 export declare class SandboxTerminalApi {
     private readonly transport;

package/dist/sandbox/terminal.js

@@ -179,9 +179,15 @@ class SandboxTerminalHandle {
         this.status = normalizeTerminalStatus(response.pty);
         return this.current;
     }
-    async attach() {
+    async attach(cursor) {
         const connectionInfo = await this.getConnectionInfo();
-        const target = (0, ws_2.toWebSocketUrl)(connectionInfo.baseUrl, `/sandbox/pty/${this.id}/ws?sessionId=${encodeURIComponent(connectionInfo.sandboxId)}`, this.runtimeProxyOverride);
+        const query = new URLSearchParams({
+            sessionId: connectionInfo.sandboxId,
+        });
+        if (cursor !== undefined) {
+            query.set("cursor", String(cursor));
+        }
+        const target = (0, ws_2.toWebSocketUrl)(connectionInfo.baseUrl, `/sandbox/pty/${this.id}/ws?${query.toString()}`, this.runtimeProxyOverride);
         const headers = {
             Authorization: `Bearer ${connectionInfo.token}`,
         };

package/dist/services/sandboxes.d.ts

@@ -2,7 +2,7 @@ import { SandboxFilesApi } from "../sandbox/files";
 import { SandboxProcessHandle, SandboxProcessesApi } from "../sandbox/process";
 import { SandboxTerminalApi } from "../sandbox/terminal";
 import { BasicResponse } from "../types/session";
-import { CreateSandboxParams, SandboxDetail, SandboxExposeParams, SandboxExposeResult, SandboxExecParams, SandboxImageListResponse, SandboxListParams, SandboxListResponse, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxProcessResult, SandboxRuntimeTarget, SandboxSnapshotListParams, SandboxSnapshotListResponse } from "../types/sandbox";
+import { CreateSandboxParams, SandboxDetail, SandboxExposeParams, SandboxExposeResult, SandboxExecParams, SandboxImageListResponse, SandboxListParams, SandboxListResponse, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxProcessResult, SandboxSnapshotListParams, SandboxSnapshotListResponse, SandboxUnexposeResult } from "../types/sandbox";
 import { BaseService } from "./base";
 export declare class SandboxHandle {
     private readonly service;
@@ -20,6 +20,7 @@ export declare class SandboxHandle {
     get runtime(): SandboxDetail["runtime"];
     get tokenExpiresAt(): string | null;
     get sessionUrl(): string;
+    get exposedPorts(): SandboxExposeResult[];
     toJSON(): SandboxDetail;
     info(): Promise<SandboxDetail>;
     refresh(): Promise<SandboxHandle>;
@@ -27,6 +28,7 @@ export declare class SandboxHandle {
     stop(): Promise<BasicResponse>;
     createMemorySnapshot(params?: SandboxMemorySnapshotParams): Promise<SandboxMemorySnapshotResult>;
     expose(params: SandboxExposeParams): Promise<SandboxExposeResult>;
+    unexpose(port: number): Promise<SandboxUnexposeResult>;
     getExposedUrl(port: number): string;
     exec(input: string | SandboxExecParams): Promise<SandboxProcessResult>;
     getProcess(processId: string): Promise<SandboxProcessHandle>;
@@ -54,6 +56,7 @@ export declare class SandboxesService extends BaseService {
     getDetail(id: string): Promise<SandboxDetail>;
     attach(detail: SandboxDetail): SandboxHandle;
     createMemorySnapshot(id: string, params?: SandboxMemorySnapshotParams): Promise<SandboxMemorySnapshotResult>;
-    expose(id: string, params: SandboxExposeParams, runtime?: SandboxRuntimeTarget): Promise<SandboxExposeResult>;
+    expose(id: string, params: SandboxExposeParams): Promise<SandboxExposeResult>;
+    unexpose(id: string, port: number): Promise<SandboxUnexposeResult>;
     private createDetail;
 }

package/dist/services/sandboxes.js

@@ -9,10 +9,13 @@ const terminal_1 = require("../sandbox/terminal");
 const base_2 = require("./base");
 const RUNTIME_SESSION_REFRESH_BUFFER_MS = 60000;
 const buildSandboxExposedUrl = (runtime, port) => {
-    const url = new URL(runtime.baseUrl);
-    url.hostname = `${port}-${url.hostname}`;
-    return url.toString().replace(/\/$/, "");
+    const baseUrl = new URL(runtime.baseUrl);
+    const authority = baseUrl.port
+        ? `${port}-${runtime.host}:${baseUrl.port}`
+        : `${port}-${runtime.host}`;
+    return new URL("/", `${baseUrl.protocol}//${authority}`).toString();
 };
+const upsertExposedPort = (exposedPorts, updated) => [...exposedPorts.filter((entry) => entry.port !== updated.port), updated].sort((left, right) => left.port - right.port);
 class SandboxHandle {
     constructor(service, detail) {
         this.service = service;
@@ -42,6 +45,9 @@ class SandboxHandle {
     get sessionUrl() {
         return this.detail.sessionUrl;
     }
+    get exposedPorts() {
+        return (this.detail.exposedPorts ?? []).map((entry) => ({ ...entry }));
+    }
     toJSON() {
         return { ...this.detail };
     }
@@ -67,7 +73,20 @@ class SandboxHandle {
         return this.service.createMemorySnapshot(this.id, params);
     }
     async expose(params) {
-        return this.service.expose(this.id, params, this.runtime);
+        const exposure = await this.service.expose(this.id, params);
+        this.detail = {
+            ...this.detail,
+            exposedPorts: upsertExposedPort(this.detail.exposedPorts ?? [], exposure),
+        };
+        return exposure;
+    }
+    async unexpose(port) {
+        const response = await this.service.unexpose(this.id, port);
+        this.detail = {
+            ...this.detail,
+            exposedPorts: (this.detail.exposedPorts ?? []).filter((entry) => entry.port !== port),
+        };
+        return response;
     }
     getExposedUrl(port) {
         return buildSandboxExposedUrl(this.runtime, port);
@@ -198,6 +217,9 @@ class SandboxesService extends base_2.BaseService {
         try {
             return await this.request("/sandboxes", undefined, {
                 status: params.status,
+                start: params.start,
+                end: params.end,
+                search: params.search,
                 page: params.page,
                 limit: params.limit,
             });
@@ -224,6 +246,7 @@ class SandboxesService extends base_2.BaseService {
         try {
             return await this.request("/snapshots", undefined, {
                 status: params.status,
+                imageName: params.imageName,
                 limit: params.limit,
             });
         }
@@ -275,18 +298,12 @@ class SandboxesService extends base_2.BaseService {
             throw new client_1.HyperbrowserError(`Failed to create memory snapshot for sandbox ${id}`, undefined);
         }
     }
-    async expose(id, params, runtime) {
+    async expose(id, params) {
         try {
-            const response = await this.request(`/sandbox/${id}/expose`, {
+            return await this.request(`/sandbox/${id}/expose`, {
                 method: "POST",
                 body: JSON.stringify(params),
             });
-            const targetRuntime = runtime ?? (await this.getDetail(id)).runtime;
-            return {
-                port: response.port,
-                auth: response.auth,
-                url: buildSandboxExposedUrl(targetRuntime, response.port),
-            };
         }
         catch (error) {
             if (error instanceof client_1.HyperbrowserError) {
@@ -295,6 +312,20 @@ class SandboxesService extends base_2.BaseService {
             throw new client_1.HyperbrowserError(`Failed to expose port ${params.port} for sandbox ${id}`);
         }
     }
+    async unexpose(id, port) {
+        try {
+            return await this.request(`/sandbox/${id}/unexpose`, {
+                method: "POST",
+                body: JSON.stringify({ port }),
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError(`Failed to unexpose port ${port} for sandbox ${id}`);
+        }
+    }
     async createDetail(params) {
         try {
             return await this.request("/sandbox", {

package/dist/types/constants.d.ts

@@ -18,7 +18,7 @@ export declare const POLLING_ATTEMPTS = 5;
 export type BrowserUseVersion = "0.1.40" | "0.7.10" | "latest";
 export type BrowserUseLlm = "gpt-4o" | "gpt-4o-mini" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-5" | "gpt-5-mini" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-sonnet-4-20250514" | "claude-3-7-sonnet-20250219" | "claude-3-5-sonnet-20241022" | "claude-3-5-haiku-20241022" | "gemini-2.0-flash" | "gemini-2.5-flash";
 export type ClaudeComputerUseLlm = "claude-opus-4-5" | "claude-opus-4-6" | "claude-haiku-4-5-20251001" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-sonnet-4-20250514" | "claude-3-7-sonnet-20250219";
-export type CuaLlm = "computer-use-preview" | "gpt-5.4";
+export type CuaLlm = "computer-use-preview" | "gpt-5.4" | "gpt-5.4-mini";
 export type HyperAgentVersion = "0.8.0" | "1.1.0";
 export type HyperAgentLlm = "gpt-5.2" | "gpt-5.1" | "gpt-5" | "gpt-5-mini" | "gpt-4o" | "gpt-4o-mini" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "gemini-2.5-flash" | "gemini-3-flash-preview";
 export type GeminiComputerUseLlm = "gemini-2.5-computer-use-preview-10-2025";

package/dist/types/index.d.ts

@@ -8,7 +8,7 @@ export { StartCuaTaskParams, StartCuaTaskResponse, CuaTaskStatusResponse, CuaTas
 export { StartHyperAgentTaskParams, StartHyperAgentTaskResponse, HyperAgentTaskStatusResponse, HyperAgentTaskResponse, HyperAgentTaskData, HyperAgentStep, HyperAgentOutput, HyperAgentActionOutput, HyperAgentApiKeys, HyperAgentTaskMetadata, HyperAgentOutputV110, HyperAgentStepV110, } from "./agents/hyper-agent";
 export { StartGeminiComputerUseTaskParams, StartGeminiComputerUseTaskResponse, GeminiComputerUseTaskStatusResponse, GeminiComputerUseTaskResponse, GeminiComputerUseTaskData, GeminiComputerUseStepResponse, GeminiComputerUseApiKeys, GeminiComputerUseTaskMetadata, } from "./agents/gemini-computer-use";
 export { BasicResponse, SessionStatus, Session, SessionDetail, SessionGetParams, SessionListParams, SessionListResponse, ScreenConfig, CreateSessionParams, GetSessionDownloadsUrlResponse, GetSessionVideoRecordingUrlResponse, GetSessionRecordingUrlResponse, ImageCaptchaParam, UploadFileResponse, UploadFileOptions, GetActiveSessionsCountResponse, SessionEventLogListParams, SessionEventLogListResponse, SessionEventLog, SessionProfile, SessionLaunchState, SessionCreditBreakdown, UpdateSessionProfileParams, UpdateSessionProxyLocationParams, UpdateSessionProxyParams, } from "./session";
-export { SandboxStatus, SandboxRuntimeTarget, Sandbox, SandboxDetail, SandboxListParams, SandboxListResponse, SandboxImageSummary, SandboxImageListResponse, SandboxSnapshotStatus, SandboxSnapshotSummary, SandboxSnapshotListParams, SandboxSnapshotListResponse, CreateSandboxParams, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxExposeParams, SandboxExposeResult, SandboxProcessStatus, SandboxExecParams, SandboxProcessSummary, SandboxProcessResult, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessWaitParams, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessStreamEvent, SandboxFileType, SandboxFileInfo, SandboxFileWriteInfo, SandboxFileListOptions, SandboxFileReadFormat, SandboxFileReadOptions, SandboxFileWriteData, SandboxFileWriteEntry, SandboxFileTextWriteOptions, SandboxFileBytesWriteOptions, SandboxFileMakeDirOptions, SandboxFileCopyParams, SandboxFileChmodParams, SandboxFileChownParams, SandboxFileTransferResult, SandboxFileSystemEventType, SandboxFileSystemEvent, SandboxWatchDirOptions, SandboxPresignFileParams, SandboxPresignedUrl, SandboxTerminalCreateParams, SandboxTerminalOutputChunk, SandboxTerminalStatus, SandboxTerminalWaitParams, SandboxTerminalKillParams, SandboxTerminalEvent, } from "./sandbox";
+export { SandboxStatus, SandboxRuntimeTarget, Sandbox, SandboxDetail, SandboxListParams, SandboxListResponse, SandboxImageSummary, SandboxImageListResponse, SandboxSnapshotStatus, SandboxSnapshotSummary, SandboxSnapshotListParams, SandboxSnapshotListResponse, CreateSandboxParams, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxExposeParams, SandboxExposeResult, SandboxUnexposeResult, SandboxProcessStatus, SandboxExecParams, SandboxProcessSummary, SandboxProcessResult, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessWaitParams, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessStreamEvent, SandboxFileType, SandboxFileInfo, SandboxFileWriteInfo, SandboxFileListOptions, SandboxFileReadFormat, SandboxFileReadOptions, SandboxFileWriteData, SandboxFileWriteEntry, SandboxFileTextWriteOptions, SandboxFileBytesWriteOptions, SandboxFileMakeDirOptions, SandboxFileCopyParams, SandboxFileChmodParams, SandboxFileChownParams, SandboxFileTransferResult, SandboxFileSystemEventType, SandboxFileSystemEvent, SandboxWatchDirOptions, SandboxPresignFileParams, SandboxPresignedUrl, SandboxTerminalCreateParams, SandboxTerminalOutputChunk, SandboxTerminalStatus, SandboxTerminalWaitParams, SandboxTerminalKillParams, SandboxTerminalEvent, } from "./sandbox";
 export { CreateProfileParams, ProfileResponse, CreateProfileResponse, ProfileListParams, ProfileListResponse, } from "./profile";
 export { CreateExtensionParams, CreateExtensionResponse, ListExtensionsResponse, } from "./extension";
 export { ExtractJobStatus, BrowserUseTaskStatus, BrowserUseLlm, ClaudeComputerUseLlm, CuaLlm, GeminiComputerUseLlm, ScrapeScreenshotFormat, ScrapeJobStatus, CrawlJobStatus, Country, State, ISO639_1, OperatingSystem, Platform, ScrapeFormat, ScrapeWaitUntil, ScrapePageStatus, CrawlPageStatus, RecordingStatus, DownloadsStatus, HyperAgentLlm, HyperAgentTaskStatus, ClaudeComputerUseTaskStatus, CuaTaskStatus, GeminiComputerUseTaskStatus, SessionEventLogType, SessionRegion, BrowserUseVersion, HyperAgentVersion, } from "./constants";

package/dist/types/sandbox.d.ts

@@ -28,6 +28,7 @@ export interface Sandbox {
     duration: number;
     proxyBytesUsed: number;
     runtime: SandboxRuntimeTarget;
+    exposedPorts: SandboxExposeResult[];
 }
 export interface SandboxDetail extends Sandbox {
     token: string | null;
@@ -36,6 +37,7 @@ export interface SandboxDetail extends Sandbox {
 interface SandboxCreateCommonParams {
     region?: SessionRegion;
     enableRecording?: boolean;
+    exposedPorts?: SandboxExposeParams[];
     timeoutMinutes?: number;
 }
 export type CreateSandboxParams = (SandboxCreateCommonParams & {
@@ -51,6 +53,9 @@ export type CreateSandboxParams = (SandboxCreateCommonParams & {
 });
 export interface SandboxListParams {
     status?: SandboxStatus;
+    start?: number;
+    end?: number;
+    search?: string;
     page?: number;
     limit?: number;
 }
@@ -88,6 +93,7 @@ export interface SandboxSnapshotSummary {
 }
 export interface SandboxSnapshotListParams {
     status?: SandboxSnapshotStatus;
+    imageName?: string;
     limit?: number;
 }
 export interface SandboxSnapshotListResponse {
@@ -113,6 +119,12 @@ export interface SandboxExposeResult {
     port: number;
     auth: boolean;
     url: string;
+    browserUrl?: string;
+    browserUrlExpiresAt?: string | null;
+}
+export interface SandboxUnexposeResult {
+    port: number;
+    exposed: boolean;
 }
 export type SandboxProcessStatus = "queued" | "running" | "exited" | "failed" | "killed" | "timed_out";
 export interface SandboxExecParams {
@@ -206,6 +218,9 @@ export type SandboxFileWriteData = string | Uint8Array | Buffer | ArrayBuffer |
 export interface SandboxFileWriteEntry {
     path: string;
     data: SandboxFileWriteData;
+    encoding?: "utf8" | "base64";
+    append?: boolean;
+    mode?: string;
 }
 export interface SandboxFileTextWriteOptions {
     append?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperbrowser/sdk",
-  "version": "0.87.1",
+  "version": "0.88.0",
   "description": "Node SDK for Hyperbrowser API",
   "author": "",
   "main": "dist/index.js",