@hyperbrowser/sdk 1.2.0 → 1.2.2

package/dist/types/index.d.ts

@@ -11,12 +11,13 @@ export { StartGeminiComputerUseTaskParams, StartGeminiComputerUseTaskResponse, G
 export { StartGrokComputerUseTaskParams, StartGrokComputerUseTaskResponse, GrokComputerUseTaskStatusResponse, GrokComputerUseTaskResponse, GrokComputerUseTaskData, GrokComputerUseStepResponse, GrokComputerUseApiKeys, GrokComputerUseTaskMetadata, } from "./agents/grok-computer-use";
 export { StartMetaComputerUseTaskParams, StartMetaComputerUseTaskResponse, MetaComputerUseTaskStatusResponse, MetaComputerUseTaskResponse, MetaComputerUseTaskData, MetaComputerUseStepResponse, MetaComputerUseStepError, MetaComputerUseStepIncompleteDetails, MetaComputerUseStepReasoning, MetaComputerUseApiKeys, MetaComputerUseTaskMetadata, } from "./agents/meta-computer-use";
 export { StartJevComputerUseTaskParams, StartJevComputerUseTaskResponse, JevComputerUseTaskStatusResponse, JevComputerUseTaskResponse, JevComputerUseTaskData, JevComputerUseStepResponse, JevComputerUseApiKeys, JevComputerUseTaskMetadata, } from "./agents/jev-computer-use";
-export { BasicResponse, BrowserMemorySize, SessionStatus, Session, SessionDetail, SessionGetParams, SessionListParams, SessionListResponse, ScreenConfig, CaptchaEvaluationPageResult, CaptchaEvaluationParams, CaptchaEvaluationResponse, CaptchaEvaluationTarget, CaptchaEvaluationType, CaptchaSolverType, CreateSessionParams, CreateSessionSnapshotResponse, GetSessionDownloadsUrlResponse, GetSessionVideoRecordingUrlResponse, GetSessionRecordingUrlResponse, ImageCaptchaParam, UploadFileResponse, UploadFileOptions, GetActiveSessionsCountResponse, SessionEventLogListParams, SessionEventLogListResponse, SessionEventLog, SessionProfile, SessionLaunchState, SessionCreditBreakdown, StartSessionFromSnapshotParams, UpdateSessionProfileParams, UpdateSessionProxyLocationParams, UpdateSessionProxyParams, UpdateSessionScreenParams, UpdateSessionSolveCaptchasParams, UpdateSessionSolveCaptchasResponse, } from "./session";
-export { SandboxStatus, SandboxRuntimeTarget, SandboxNetworkPolicy, SandboxNetworkPolicyPatch, SandboxNetworkUpdateResult, Sandbox, SandboxDetail, SandboxVolumeMountType, SandboxVolumeMount, SandboxListParams, SandboxListResponse, SandboxImageSource, SandboxImageSummary, SandboxImageListParams, SandboxImageListResponse, SandboxSnapshotStatus, SandboxSnapshotSummary, SandboxSnapshotListParams, SandboxSnapshotListResponse, SandboxSnapshotDeleteResult, SandboxImageDeleteResult, SandboxImageInit, SandboxImageBuildStatus, SandboxImageBuildInputFormat, SandboxImageBuildSourcePlatform, SandboxImageBuildUpload, SandboxImageBuild, SandboxBuildContextBundle, SandboxBuildContextMode, SandboxBuildContextManifest, SandboxDockerImageConfig, SandboxDockerImageLayer, SandboxDockerImageManifest, CreateSandboxImageBuildParams, ReuseSandboxDockerImageParams, CompleteSandboxImageBuildParams, SandboxImageBuildCreateResult, SandboxDockerImageReuseResult, SandboxImageBuildResolutionOutcome, SandboxImageBuildResolution, SandboxImageBuildWaitOptions, BuildSandboxImageFromDockerImageOptions, BuildSandboxImageFromDockerfileOptions, GetOrBuildSandboxImageOptions, SandboxImageBuildListParams, SandboxImageBuildListResponse, CreateSandboxParams, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxExposeParams, SandboxExposeResult, SandboxUnexposeResult, SandboxProcessStatus, SandboxExecParams, SandboxExecOptions, SandboxProcessSummary, SandboxProcessResult, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessWaitParams, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessOutputEvent, SandboxProcessExitEvent, 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 { BasicResponse, BrowserMemorySize, SessionStatus, Session, SessionDetail, SessionGetParams, SessionListParams, SessionListResponse, ScreenConfig, CaptchaEvaluationPageResult, CaptchaEvaluationParams, CaptchaEvaluationResponse, CaptchaEvaluationTarget, CaptchaEvaluationType, CaptchaSolverType, CreateSessionParams, CreateSessionSnapshotResponse, GetSessionDownloadsUrlResponse, GetSessionVideoRecordingUrlResponse, GetSessionRecordingUrlResponse, ImageCaptchaParam, UploadFileResponse, UploadFileOptions, GetActiveSessionsCountResponse, SessionEventLogListParams, SessionEventLogListResponse, SessionEventLog, SessionProfile, SessionLaunchState, SessionWebBotAuth, SessionCreditBreakdown, StartSessionFromSnapshotParams, WebBotAuthParams, ProxyRoute, UpdateSessionProfileParams, UpdateSessionProxyLocationParams, UpdateSessionProxyParams, UpdateSessionScreenParams, UpdateSessionSolveCaptchasParams, UpdateSessionSolveCaptchasResponse, } from "./session";
+export { SandboxStatus, SandboxRuntimeTarget, SandboxNetworkPolicy, SandboxNetworkPolicyPatch, SandboxNetworkUpdateResult, Sandbox, SandboxDetail, SandboxVolumeMountType, SandboxVolumeMount, SandboxSecretReference, SandboxSecrets, SandboxResolvedSecret, SandboxListParams, SandboxListResponse, SandboxImageSource, SandboxImageSummary, SandboxImageListParams, SandboxImageListResponse, SandboxSnapshotStatus, SandboxSnapshotSummary, SandboxSnapshotListParams, SandboxSnapshotListResponse, SandboxSnapshotDeleteResult, SandboxImageDeleteResult, SandboxImageInit, SandboxImageBuildStatus, SandboxImageBuildInputFormat, SandboxImageBuildSourcePlatform, SandboxImageBuildUpload, SandboxImageBuild, SandboxBuildContextBundle, SandboxBuildContextMode, SandboxBuildContextManifest, SandboxDockerImageConfig, SandboxDockerImageLayer, SandboxDockerImageManifest, CreateSandboxImageBuildParams, ReuseSandboxDockerImageParams, CompleteSandboxImageBuildParams, SandboxImageBuildCreateResult, SandboxDockerImageReuseResult, SandboxImageBuildResolutionOutcome, SandboxImageBuildResolution, SandboxImageBuildWaitOptions, BuildSandboxImageFromDockerImageOptions, BuildSandboxImageFromDockerfileOptions, GetOrBuildSandboxImageOptions, SandboxImageBuildListParams, SandboxImageBuildListResponse, CreateSandboxParams, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxExposeParams, SandboxExposeResult, SandboxUnexposeResult, SandboxProcessStatus, SandboxExecParams, SandboxExecOptions, SandboxProcessSummary, SandboxProcessResult, SandboxProcessListParams, SandboxProcessListResponse, SandboxProcessWaitParams, SandboxProcessSignal, SandboxProcessStdinParams, SandboxProcessOutputEvent, SandboxProcessExitEvent, 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 { CreateVolumeParams, Volume, VolumeListParams, VolumeListResponse, VolumeDeleteResult, } from "./volume";
+export { SecretValue, SecretsPublicKey, SecretsPublicKeyJwk, Secret, SecretVersion, SecretDetail, CreateSecretParams, UpdateSecretParams, SecretListParams, SecretListResponse, SecretDeleteResult, SecretVersionDeleteResult, } from "./secret";
 export { CreateProfileParams, ForkProfileParams, ProfileResponse, CreateProfileResponse, ProfileListParams, ProfileListResponse, } from "./profile";
 export { CreateExtensionParams, CreateExtensionResponse, ListExtensionsResponse, } from "./extension";
-export { ExtractJobStatus, BrowserUseTaskStatus, BrowserUseLlm, ClaudeComputerUseLlm, ClaudeComputerUseReasoningEffort, CuaLlm, CuaReasoningEffort, GeminiComputerUseLlm, GrokComputerUseLlm, GrokReasoningEffort, MetaComputerUseLlm, MetaReasoningEffort, JevComputerUseLlm, JevTextLlm, ScrapeScreenshotFormat, ScrapeJobStatus, CrawlJobStatus, Country, State, ISO639_1, OperatingSystem, Platform, ScrapeFormat, ScrapeWaitUntil, ScrapePageStatus, CrawlPageStatus, RecordingStatus, DownloadsStatus, HyperAgentLlm, HyperAgentTaskStatus, ClaudeComputerUseTaskStatus, CuaTaskStatus, GeminiComputerUseTaskStatus, GrokComputerUseTaskStatus, MetaComputerUseTaskStatus, JevComputerUseTaskStatus, SessionEventLogType, SessionRegion, BrowserUseVersion, HyperAgentVersion, } from "./constants";
+export { ExtractJobStatus, BrowserUseTaskStatus, BrowserUseLlm, ClaudeComputerUseLlm, ClaudeComputerUseReasoningEffort, CuaLlm, CuaReasoningEffort, GeminiComputerUseLlm, GeminiComputerUseReasoningEffort, GrokComputerUseLlm, GrokReasoningEffort, MetaComputerUseLlm, MetaReasoningEffort, JevComputerUseLlm, JevTextLlm, ScrapeScreenshotFormat, ScrapeJobStatus, CrawlJobStatus, Country, State, ISO639_1, OperatingSystem, Platform, ScrapeFormat, ScrapeWaitUntil, ScrapePageStatus, CrawlPageStatus, RecordingStatus, DownloadsStatus, HyperAgentLlm, HyperAgentTaskStatus, ClaudeComputerUseTaskStatus, CuaTaskStatus, GeminiComputerUseTaskStatus, GrokComputerUseTaskStatus, MetaComputerUseTaskStatus, JevComputerUseTaskStatus, SessionEventLogType, SessionRegion, BrowserUseVersion, HyperAgentVersion, } from "./constants";
 export { TeamCreditInfo } from "./team";
 export { ComputerAction, Coordinate, ClickActionParams, DragActionParams, PressKeysActionParams, MoveMouseActionParams, ScreenshotActionParams, CursorPositionActionParams, ScrollAtCursorActionParams, ScrollActionParams, TypeTextActionParams, ComputerActionParams, ComputerActionResponse, ComputerActionMouseButton, ComputerActionResponseData, HoldKeyActionParams, MouseDownActionParams, MouseUpActionParams, GetClipboardTextActionParams, PutSelectionTextActionParams, ComputerActionResponseDataClipboardText, ListWindowsActionParams, ComputerActionWindow, ComputerActionResponseDataListWindows, ComputerActionResponseDataCursorPosition, } from "./computer-action";
 export { FetchParams, FetchResponse, FetchResponseData, FetchStatus } from "./web/fetch";

package/dist/types/sandbox.d.ts

@@ -59,12 +59,34 @@ export interface Sandbox {
     network?: SandboxNetworkPolicy | null;
     runtime: SandboxRuntimeTarget;
     exposedPorts: SandboxExposeResult[];
+    /**
+     * Secrets were delivered into the sandbox, or it was restored from a
+     * snapshot that may hold them.
+     */
+    containsSecrets?: boolean;
 }
 export interface SandboxDetail extends Sandbox {
     token: string | null;
     tokenExpiresAt: string | null;
 }
 export type SandboxVolumeMountType = "rw" | "ro";
+/**
+ * A stored secret to deliver as an environment variable: its name, or
+ * `{ name, version }` to pin a version. The latest version is used otherwise.
+ */
+export type SandboxSecretReference = string | {
+    name: string;
+    version?: number | "latest";
+};
+/** Environment variable name to secret, at most 32 per process or sandbox. */
+export type SandboxSecrets = Record<string, SandboxSecretReference>;
+/** The secret version an environment variable received. */
+export interface SandboxResolvedSecret {
+    env: string;
+    name: string;
+    secretId: string;
+    version: number;
+}
 export interface SandboxVolumeMount {
     id: string;
     type?: SandboxVolumeMountType;
@@ -89,6 +111,7 @@ export type CreateSandboxParams = (SandboxCreateCommonParams & {
     cpu?: never;
     memoryMiB?: never;
     diskMiB?: never;
+    secrets?: never;
 }) | (SandboxCreateCommonParams & {
     snapshotName?: never;
     snapshotId?: never;
@@ -97,6 +120,12 @@ export type CreateSandboxParams = (SandboxCreateCommonParams & {
     cpu?: number;
     memoryMiB?: number;
     diskMiB?: number;
+    /**
+     * Secrets for the image's startup command only; requires the API key's
+     * `secrets.use` scope and is not supported with `runtimeClass:
+     * "gvisor-cpu"`. The sandbox is marked as containing secrets.
+     */
+    secrets?: SandboxSecrets;
 });
 export interface SandboxListParams {
     status?: SandboxStatus;
@@ -157,6 +186,8 @@ export interface SandboxSnapshotSummary {
     compatibilityTag?: string | null;
     metadata: Record<string, unknown>;
     uploaded: boolean;
+    /** The snapshot's memory may hold secrets. */
+    containsSecrets?: boolean;
     createdAt: string;
     updatedAt: string;
 }
@@ -409,6 +440,17 @@ export interface SandboxExecParams {
     timeoutMs?: number;
     timeoutSec?: number;
     runAs?: string;
+    /**
+     * Stored secrets to deliver as environment variables of this process only.
+     * The process is started through the control API, which has the sandbox
+     * service decrypt them; requires the API key's `secrets.use` scope. Anything
+     * running as the same user (or root) in the sandbox can read the process's
+     * environment, and the sandbox is marked as containing secrets.
+     *
+     * Output is read back from the process's retained output rather than the
+     * start stream, so `maxOutputBytes` does not apply.
+     */
+    secrets?: SandboxSecrets;
     /** @deprecated Ignored for process APIs. */
     useShell?: boolean;
 }

package/dist/types/secret.d.ts

@@ -0,0 +1,67 @@
+/** A secret value: a UTF-8 string or its raw bytes, used byte-for-byte. */
+export type SecretValue = string | Uint8Array;
+export interface SecretsPublicKeyJwk {
+    kty: string;
+    n: string;
+    e: string;
+}
+/** The platform key that secret values are encrypted to before upload. */
+export interface SecretsPublicKey {
+    kid: string;
+    alg: string;
+    enc: string;
+    jwk: SecretsPublicKeyJwk;
+}
+export interface Secret {
+    id: string;
+    name: string;
+    description: string;
+    /** Bound into every envelope for this secret; the SDK uses it when encrypting. */
+    encryptionContext: string;
+    /** Null until a value is stored. */
+    latestVersion: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SecretVersion {
+    version: number;
+    kid: string;
+    createdAt: string;
+}
+export interface SecretDetail extends Secret {
+    versions: SecretVersion[];
+}
+export interface CreateSecretParams {
+    /** 1-128 letters, digits, '_' or '-', starting with a letter or digit. */
+    name: string;
+    description?: string;
+    /**
+     * The first version's value. It is validated and the platform key is checked
+     * before the secret is created, then encrypted locally and uploaded.
+     */
+    value?: SecretValue;
+}
+export interface UpdateSecretParams {
+    description: string;
+}
+export interface SecretListParams {
+    search?: string;
+    page?: number;
+    /** At most 100. */
+    limit?: number;
+}
+export interface SecretListResponse {
+    secrets: Secret[];
+    totalCount: number;
+    page: number;
+    perPage: number;
+}
+export interface SecretDeleteResult {
+    deleted: boolean;
+    id: string;
+    name: string;
+}
+export interface SecretVersionDeleteResult {
+    deleted: boolean;
+    version: number;
+}

package/dist/types/secret.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/session.d.ts

@@ -9,8 +9,17 @@ export interface SessionProfile {
     id: string;
     persistChanges?: boolean;
 }
+/** How a session signs its requests with Web Bot Auth. */
+export interface SessionWebBotAuth {
+    /** The identity the session signs as, e.g. "https://www.hyperbrowser.ai". */
+    signatureAgent: string;
+    /** Present when signing is limited to these hostnames and their subdomains. */
+    onlyDomains?: string[];
+}
 export interface SessionLaunchState {
     enableWebMcp?: boolean;
+    /** Present only for a session that signs its requests with Web Bot Auth. */
+    webBotAuth?: SessionWebBotAuth;
     useUltraStealth?: boolean;
     useStealth?: boolean;
     useProxy?: boolean;
@@ -128,9 +137,44 @@ export interface CaptchaEvaluationResponse {
 export interface StartSessionFromSnapshotParams {
     snapshotId: string;
 }
+export interface WebBotAuthParams {
+    /**
+     * Sign only requests to these hostnames (e.g. "example.com") and their
+     * subdomains. No scheme, port or path; at most 50.
+     */
+    onlyDomains?: string[];
+}
+export interface ProxyRoute {
+    /**
+     * The hosts this route applies to: a hostname, "*.example.com" (subdomains,
+     * not example.com itself) or "*" (every host), or a list of them.
+     */
+    match: string | string[];
+    /**
+     * "direct" sends the traffic straight out of the browser's machine;
+     * "default" sends it through the session's proxy.
+     */
+    proxy: "direct" | "default";
+}
 export interface CreateSessionParams {
     /** Enable page-provided WebMCP tools. Defaults to false on the server. */
     enableWebMcp?: boolean;
+    /**
+     * Sign the session's requests with Web Bot Auth so websites can verify they
+     * come from Hyperbrowser. Pass `{ onlyDomains }` to sign only for those
+     * hosts. Requires Web Bot Auth to be enabled for your team; works for
+     * sessions and agent tasks, and cannot be combined with `useUltraStealth`
+     * or `startFromSnapshot`.
+     */
+    webBotAuth?: boolean | WebBotAuthParams;
+    /**
+     * Choose, per host, whether the session's traffic goes through its proxy or
+     * straight out. The first route that matches a host decides; hosts that no
+     * route matches use the proxy. Requires `useProxy` and proxy routes to be
+     * enabled for your team, only applies when creating a session, and cannot
+     * be combined with `allowInternetAccess: false`, `allowOut` or `denyOut`.
+     */
+    proxyRoutes?: ProxyRoute[];
     useUltraStealth?: boolean;
     useStealth?: boolean;
     useProxy?: boolean;

package/package.json

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