@hyperbrowser/sdk 0.88.3 → 0.89.1

package/README.md

@@ -192,9 +192,11 @@ const main = async () => {
   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"],
+  const proc = await sandbox.processes.start(
+    "echo process-started && sleep 1 && echo process-finished",
+    {
+      runAs: "root",
+    }
   });
 
   for await (const event of proc.stream()) {

package/dist/sandbox/files.d.ts

@@ -51,7 +51,9 @@ export declare class SandboxFilesApi {
     private readonly transport;
     private readonly getConnectionInfo;
     private readonly runtimeProxyOverride?;
-    constructor(transport: RuntimeTransport, getConnectionInfo: () => Promise<RuntimeConnectionInfo>, runtimeProxyOverride?: string | undefined);
+    private readonly defaultRunAs?;
+    constructor(transport: RuntimeTransport, getConnectionInfo: () => Promise<RuntimeConnectionInfo>, runtimeProxyOverride?: string | undefined, defaultRunAs?: string | undefined);
+    withRunAs(runAs?: string): SandboxFilesApi;
     exists(path: string): Promise<boolean>;
     getInfo(path: string): Promise<SandboxFileInfo>;
     list(path: string, options?: SandboxFileListOptions): Promise<SandboxFileInfo[]>;
@@ -88,5 +90,7 @@ export declare class SandboxFilesApi {
     downloadUrl(path: string, options?: Omit<SandboxPresignFileParams, "path">): Promise<SandboxPresignedUrl>;
     private readWire;
     private writeSingle;
+    private withRunAsQuery;
+    private withRunAsBody;
 }
 export {};

package/dist/sandbox/files.js

@@ -248,10 +248,15 @@ class SandboxWatchDirHandle {
 }
 exports.SandboxWatchDirHandle = SandboxWatchDirHandle;
 class SandboxFilesApi {
-    constructor(transport, getConnectionInfo, runtimeProxyOverride) {
+    constructor(transport, getConnectionInfo, runtimeProxyOverride, defaultRunAs) {
         this.transport = transport;
         this.getConnectionInfo = getConnectionInfo;
         this.runtimeProxyOverride = runtimeProxyOverride;
+        this.defaultRunAs = defaultRunAs;
+    }
+    withRunAs(runAs) {
+        const normalized = runAs?.trim();
+        return new SandboxFilesApi(this.transport, this.getConnectionInfo, this.runtimeProxyOverride, normalized ? normalized : undefined);
     }
     async exists(path) {
         try {
@@ -269,17 +274,17 @@ class SandboxFilesApi {
         }
     }
     async getInfo(path) {
-        const response = await this.transport.requestJSON("/sandbox/files/stat", undefined, { path });
+        const response = await this.transport.requestJSON("/sandbox/files/stat", undefined, this.withRunAsQuery({ path }));
         return normalizeFileInfo(response.file);
     }
     async list(path, options = {}) {
         if (options.depth !== undefined && options.depth < 1) {
             throw new Error("depth should be at least one");
         }
-        const response = await this.transport.requestJSON("/sandbox/files", undefined, {
+        const response = await this.transport.requestJSON("/sandbox/files", undefined, this.withRunAsQuery({
             path,
             depth: options.depth ?? 1,
-        });
+        }));
         return response.entries.map(normalizeFileInfo);
     }
     async read(path, options = {}) {
@@ -332,7 +337,7 @@ class SandboxFilesApi {
         }));
         const response = await this.transport.requestJSON("/sandbox/files/write", {
             method: "POST",
-            body: JSON.stringify({ files: encodedFiles }),
+            body: this.withRunAsBody({ files: encodedFiles }),
             headers: {
                 "content-type": "application/json",
             },
@@ -351,7 +356,7 @@ class SandboxFilesApi {
         const response = await this.transport.requestJSON("/sandbox/files/upload", {
             method: "PUT",
             body,
-        }, { path });
+        }, this.withRunAsQuery({ path }));
         return {
             path: response.path,
             bytesWritten: response.bytesWritten,
@@ -359,13 +364,13 @@ class SandboxFilesApi {
     }
     async download(path) {
         return this.transport.requestBuffer("/sandbox/files/download", undefined, {
-            path,
+            ...this.withRunAsQuery({ path }),
         });
     }
     async makeDir(path, options = {}) {
         const response = await this.transport.requestJSON("/sandbox/files/mkdir", {
             method: "POST",
-            body: JSON.stringify({
+            body: this.withRunAsBody({
                 path,
                 parents: options.parents,
                 mode: options.mode,
@@ -379,7 +384,7 @@ class SandboxFilesApi {
     async rename(oldPath, newPath) {
         const response = await this.transport.requestJSON("/sandbox/files/move", {
             method: "POST",
-            body: JSON.stringify({
+            body: this.withRunAsBody({
                 from: oldPath,
                 to: newPath,
             }),
@@ -392,7 +397,7 @@ class SandboxFilesApi {
     async remove(path, options = {}) {
         await this.transport.requestJSON("/sandbox/files/delete", {
             method: "POST",
-            body: JSON.stringify({
+            body: this.withRunAsBody({
                 path,
                 recursive: options.recursive,
             }),
@@ -404,7 +409,7 @@ class SandboxFilesApi {
     async copy(params) {
         const response = await this.transport.requestJSON("/sandbox/files/copy", {
             method: "POST",
-            body: JSON.stringify({
+            body: this.withRunAsBody({
                 from: params.source,
                 to: params.destination,
                 recursive: params.recursive,
@@ -419,7 +424,7 @@ class SandboxFilesApi {
     async chmod(params) {
         await this.transport.requestJSON("/sandbox/files/chmod", {
             method: "POST",
-            body: JSON.stringify(params),
+            body: this.withRunAsBody(params),
             headers: {
                 "content-type": "application/json",
             },
@@ -428,7 +433,7 @@ class SandboxFilesApi {
     async chown(params) {
         await this.transport.requestJSON("/sandbox/files/chown", {
             method: "POST",
-            body: JSON.stringify(params),
+            body: this.withRunAsBody(params),
             headers: {
                 "content-type": "application/json",
             },
@@ -437,7 +442,7 @@ class SandboxFilesApi {
     async watchDir(path, onEvent, options = {}) {
         const response = await this.transport.requestJSON("/sandbox/files/watch", {
             method: "POST",
-            body: JSON.stringify({
+            body: this.withRunAsBody({
                 path,
                 recursive: options.recursive,
             }),
@@ -451,7 +456,7 @@ class SandboxFilesApi {
     async uploadUrl(path, options = {}) {
         return this.transport.requestJSON("/sandbox/files/presign-upload", {
             method: "POST",
-            body: JSON.stringify({
+            body: this.withRunAsBody({
                 path,
                 expiresInSeconds: options.expiresInSeconds,
                 oneTime: options.oneTime,
@@ -464,7 +469,7 @@ class SandboxFilesApi {
     async downloadUrl(path, options = {}) {
         return this.transport.requestJSON("/sandbox/files/presign-download", {
             method: "POST",
-            body: JSON.stringify({
+            body: this.withRunAsBody({
                 path,
                 expiresInSeconds: options.expiresInSeconds,
                 oneTime: options.oneTime,
@@ -477,7 +482,7 @@ class SandboxFilesApi {
     async readWire(path, options, encoding) {
         return this.transport.requestJSON("/sandbox/files/read", {
             method: "POST",
-            body: JSON.stringify({
+            body: this.withRunAsBody({
                 path,
                 offset: options.offset,
                 length: options.length,
@@ -491,7 +496,7 @@ class SandboxFilesApi {
     async writeSingle(path, data, encoding, options) {
         const response = await this.transport.requestJSON("/sandbox/files/write", {
             method: "POST",
-            body: JSON.stringify({
+            body: this.withRunAsBody({
                 path,
                 data,
                 encoding,
@@ -504,5 +509,23 @@ class SandboxFilesApi {
         });
         return normalizeWriteInfo(response.files[0]);
     }
+    withRunAsQuery(params) {
+        if (!this.defaultRunAs) {
+            return params;
+        }
+        return {
+            ...params,
+            runAs: this.defaultRunAs,
+        };
+    }
+    withRunAsBody(body) {
+        if (!this.defaultRunAs) {
+            return JSON.stringify(body);
+        }
+        return JSON.stringify({
+            ...body,
+            runAs: this.defaultRunAs,
+        });
+    }
 }
 exports.SandboxFilesApi = SandboxFilesApi;

package/dist/sandbox/process.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeTransport } from "./base";
-import { SandboxExecParams, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessResult, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessStreamEvent, SandboxProcessSummary, SandboxProcessWaitParams } from "../types/sandbox";
+import { SandboxExecParams, SandboxExecOptions, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessResult, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessStreamEvent, SandboxProcessSummary, SandboxProcessWaitParams } from "../types/sandbox";
 export declare class SandboxProcessHandle {
     private readonly transport;
     private summary;
@@ -18,7 +18,9 @@ export declare class SandboxProcessHandle {
 export declare class SandboxProcessesApi {
     private readonly transport;
     constructor(transport: RuntimeTransport);
+    exec(command: string, options?: SandboxExecOptions): Promise<SandboxProcessResult>;
     exec(input: SandboxExecParams): Promise<SandboxProcessResult>;
+    start(command: string, options?: SandboxExecOptions): Promise<SandboxProcessHandle>;
     start(input: SandboxExecParams): Promise<SandboxProcessHandle>;
     get(processId: string): Promise<SandboxProcessHandle>;
     list(params?: SandboxProcessListParams): Promise<SandboxProcessListResponse>;

package/dist/sandbox/process.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SandboxProcessesApi = exports.SandboxProcessHandle = void 0;
 const DEFAULT_PROCESS_KILL_WAIT_MS = 5000;
+const SHELL_SAFE_TOKEN_PATTERN = /^[A-Za-z0-9_@%+=:,./-]+$/;
 const normalizeProcessSummary = (process) => ({
     id: process.id,
     status: process.status,
@@ -50,15 +51,40 @@ const normalizeStreamEvent = (event) => {
     }
     return null;
 };
+const quoteShellToken = (token) => {
+    if (token.length === 0) {
+        return "''";
+    }
+    return SHELL_SAFE_TOKEN_PATTERN.test(token)
+        ? token
+        : `'${token.replace(/'/g, `'\"'\"'`)}'`;
+};
+const buildShellCommand = (command, args) => {
+    if (!args || args.length === 0) {
+        return command;
+    }
+    return [command, ...args].map((token) => quoteShellToken(token)).join(" ");
+};
+const normalizeLegacyProcessParams = (input) => ({
+    ...input,
+    command: buildShellCommand(input.command, input.args),
+    args: undefined,
+    useShell: undefined,
+});
 const buildProcessPayload = (input) => ({
     command: input.command,
-    args: input.args,
     cwd: input.cwd,
     env: input.env,
     timeoutMs: input.timeoutMs,
     timeout_sec: input.timeoutSec,
-    useShell: input.useShell,
+    runAs: input.runAs,
 });
+const normalizeExecParams = (input, options) => typeof input === "string"
+    ? normalizeLegacyProcessParams({
+        command: input,
+        ...options,
+    })
+    : normalizeLegacyProcessParams(input);
 const encodeStdinPayload = (input) => {
     if (input.data === undefined) {
         return {
@@ -184,20 +210,22 @@ class SandboxProcessesApi {
     constructor(transport) {
         this.transport = transport;
     }
-    async exec(input) {
+    async exec(input, options) {
+        const params = normalizeExecParams(input, options);
         const response = await this.transport.requestJSON("/sandbox/exec", {
             method: "POST",
-            body: JSON.stringify(buildProcessPayload(input)),
+            body: JSON.stringify(buildProcessPayload(params)),
             headers: {
                 "content-type": "application/json",
             },
         });
         return normalizeProcessResult(response.result);
     }
-    async start(input) {
+    async start(input, options) {
+        const params = normalizeExecParams(input, options);
         const response = await this.transport.requestJSON("/sandbox/processes", {
             method: "POST",
-            body: JSON.stringify(buildProcessPayload(input)),
+            body: JSON.stringify(buildProcessPayload(params)),
             headers: {
                 "content-type": "application/json",
             },

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, SandboxSnapshotListParams, SandboxSnapshotListResponse, SandboxUnexposeResult } from "../types/sandbox";
+import { CreateSandboxParams, SandboxDetail, SandboxExposeParams, SandboxExposeResult, SandboxExecParams, SandboxExecOptions, SandboxImageListResponse, SandboxListParams, SandboxListResponse, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxProcessResult, SandboxSnapshotListParams, SandboxSnapshotListResponse, SandboxUnexposeResult } from "../types/sandbox";
 import { BaseService } from "./base";
 export declare class SandboxHandle {
     private readonly service;
@@ -33,7 +33,8 @@ export declare class SandboxHandle {
     expose(params: SandboxExposeParams): Promise<SandboxExposeResult>;
     unexpose(port: number): Promise<SandboxUnexposeResult>;
     getExposedUrl(port: number): string;
-    exec(input: string | SandboxExecParams): Promise<SandboxProcessResult>;
+    exec(input: string, options?: SandboxExecOptions): Promise<SandboxProcessResult>;
+    exec(input: SandboxExecParams): Promise<SandboxProcessResult>;
     getProcess(processId: string): Promise<SandboxProcessHandle>;
     private hydrate;
     private resolveRuntimeConnection;

package/dist/services/sandboxes.js

@@ -161,13 +161,11 @@ class SandboxHandle {
     getExposedUrl(port) {
         return buildSandboxExposedUrl(this.runtime, port);
     }
-    async exec(input) {
-        const params = typeof input === "string"
-            ? {
-                command: input,
-            }
-            : input;
-        return this.processes.exec(params);
+    async exec(input, options) {
+        if (typeof input === "string") {
+            return this.processes.exec(input, options);
+        }
+        return this.processes.exec(input);
     }
     async getProcess(processId) {
         return this.processes.get(processId);

package/dist/types/crawl.d.ts

@@ -22,7 +22,7 @@ export interface CrawledPage {
     url: string;
     status: CrawlPageStatus;
     error?: string | null;
-    metadata?: Record<string, string | string[]>;
+    metadata?: Record<string, unknown>;
     markdown?: string;
     html?: string;
     links?: string[];

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, 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 { SandboxStatus, SandboxRuntimeTarget, Sandbox, SandboxDetail, SandboxListParams, SandboxListResponse, SandboxImageSummary, SandboxImageListResponse, SandboxSnapshotStatus, SandboxSnapshotSummary, SandboxSnapshotListParams, SandboxSnapshotListResponse, CreateSandboxParams, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxExposeParams, SandboxExposeResult, SandboxUnexposeResult, SandboxProcessStatus, SandboxExecParams, SandboxExecOptions, 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

@@ -138,13 +138,17 @@ export interface SandboxUnexposeResult {
 export type SandboxProcessStatus = "queued" | "running" | "exited" | "failed" | "killed" | "timed_out";
 export interface SandboxExecParams {
     command: string;
+    /** @deprecated Legacy compatibility only. Converted into a single shell command string. */
     args?: string[];
     cwd?: string;
     env?: Record<string, string>;
     timeoutMs?: number;
     timeoutSec?: number;
+    runAs?: string;
+    /** @deprecated Ignored for process APIs. Commands always execute via `/bin/sh -lc` server-side. */
     useShell?: boolean;
 }
+export type SandboxExecOptions = Omit<SandboxExecParams, "command">;
 export interface SandboxProcessSummary {
     id: string;
     status: SandboxProcessStatus;

package/dist/types/scrape.d.ts

@@ -35,7 +35,7 @@ export interface ScrapeJobStatusResponse {
     status: ScrapeJobStatus;
 }
 export interface ScrapeJobData {
-    metadata?: Record<string, string | string[]>;
+    metadata?: Record<string, unknown>;
     markdown?: string;
     html?: string;
     links?: string[];
@@ -56,7 +56,7 @@ export interface ScrapedPage {
     url: string;
     status: ScrapePageStatus;
     error?: string | null;
-    metadata?: Record<string, string | string[]>;
+    metadata?: Record<string, unknown>;
     markdown?: string;
     html?: string;
     links?: string[];

package/dist/types/web/common.d.ts

@@ -25,7 +25,7 @@ export interface PageData {
     url: string;
     status: PageStatus;
     error?: string;
-    metadata?: Record<string, string | string[]>;
+    metadata?: Record<string, unknown>;
     markdown?: string;
     html?: string;
     links?: string[];
@@ -62,7 +62,7 @@ export interface FetchOutputOptions {
 export interface FetchBrowserOptions {
     screen?: ScreenConfig;
     profileId?: string;
-    solveCaptchas?: string;
+    solveCaptchas?: boolean;
     location?: FetchBrowserLocationOptions;
 }
 export interface FetchNavigationOptions {

package/dist/types/web/fetch.d.ts

@@ -9,7 +9,7 @@ export interface FetchParams {
     cache?: FetchCacheOptions;
 }
 export interface FetchResponseData {
-    metadata?: Record<string, string | string[]>;
+    metadata?: Record<string, unknown>;
     html?: string;
     markdown?: string;
     links?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperbrowser/sdk",
-  "version": "0.88.3",
+  "version": "0.89.1",
   "description": "Node SDK for Hyperbrowser API",
   "author": "",
   "repository": {