@hyperbrowser/sdk 0.93.0 → 1.0.0

package/dist/services/base.js

@@ -5,34 +5,38 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseService = void 0;
 const node_fetch_1 = __importDefault(require("node-fetch"));
-const client_1 = require("../client");
-const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
-const RETRYABLE_NETWORK_CODES = new Set([
-    "ECONNRESET",
-    "ECONNREFUSED",
-    "EAI_AGAIN",
-    "ETIMEDOUT",
-    "ESOCKETTIMEDOUT",
-]);
+const error_1 = require("../error");
+const retry_1 = require("../retry");
 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 BaseService {
     constructor(apiKey, baseUrl, timeout = 30000) {
         this.apiKey = apiKey;
         this.baseUrl = baseUrl;
         this.timeout = timeout;
     }
+    /** Transient GET failures (429/502/503/504, network errors) retry up to three attempts. */
     async request(path, init, params, fullUrl = false) {
+        const method = (init?.method ?? "GET").toUpperCase();
+        let failedAttempt = 1;
+        for (;;) {
+            try {
+                return await this.requestOnce(path, init, params, fullUrl);
+            }
+            catch (error) {
+                if (init?.signal?.aborted ||
+                    !(error instanceof error_1.HyperbrowserError) ||
+                    !(0, retry_1.shouldRetryGet)(method, error, failedAttempt)) {
+                    throw error;
+                }
+                await (0, retry_1.retryDelay)((0, retry_1.getRetryDelayMs)(failedAttempt), init?.signal ?? undefined);
+                failedAttempt += 1;
+            }
+        }
+    }
+    async requestOnce(path, init, params, fullUrl = false) {
+        let response;
         try {
             const url = new URL(fullUrl ? path : `${this.baseUrl}/api${path}`);
             if (params) {
@@ -52,7 +56,7 @@ class BaseService {
             const headerKeys = Object.keys(init?.headers || {});
             const contentTypeKey = headerKeys.find((key) => key.toLowerCase() === "content-type");
             const requestTimeout = init?.timeout ?? this.timeout;
-            const response = await (0, node_fetch_1.default)(url.toString(), {
+            response = await (0, node_fetch_1.default)(url.toString(), {
                 ...init,
                 timeout: requestTimeout,
                 headers: {
@@ -74,41 +78,53 @@ class BaseService {
                     errorMessage =
                         errorData.message || errorData.error || `HTTP error! status: ${response.status}`;
                 }
-                catch {
+                catch (error) {
+                    if (init?.signal?.aborted)
+                        throw error;
                     errorMessage = `HTTP error! status: ${response.status}`;
                 }
-                throw new client_1.HyperbrowserError(errorMessage, {
+                throw new error_1.HyperbrowserError(errorMessage, {
                     statusCode: response.status,
                     code: errorCode,
                     requestId: getRequestId(response),
-                    retryable: RETRYABLE_STATUS_CODES.has(response.status),
+                    retryable: retry_1.RETRYABLE_STATUS_CODES.has(response.status),
                     service: "control",
                     details: errorDetails,
+                    method: init?.method ?? "GET",
+                    path: (0, error_1.errorRequestPath)(path),
                 });
             }
-            if (response.headers.get("content-length") === "0") {
+            const text = await response.text();
+            if (!text)
                 return {};
-            }
             try {
-                return (await response.json());
+                return JSON.parse(text);
             }
-            catch {
-                throw new client_1.HyperbrowserError("Failed to parse JSON response", {
+            catch (cause) {
+                throw new error_1.HyperbrowserError("Failed to parse JSON response", {
                     statusCode: response.status,
                     requestId: getRequestId(response),
                     retryable: false,
                     service: "control",
+                    cause,
+                    method: init?.method ?? "GET",
+                    path: (0, error_1.errorRequestPath)(path),
                 });
             }
         }
         catch (error) {
-            if (error instanceof client_1.HyperbrowserError) {
+            if (error instanceof error_1.HyperbrowserError) {
                 throw error;
             }
-            throw new client_1.HyperbrowserError(error instanceof Error ? error.message : "Unknown error occurred", {
-                retryable: isRetryableNetworkError(error),
+            throw new error_1.HyperbrowserError((0, error_1.networkErrorMessage)(error, "Unknown error occurred"), {
+                code: init?.signal?.aborted ? "request_aborted" : undefined,
+                retryable: !init?.signal?.aborted && (0, retry_1.isRetryableNetworkError)(error),
+                method: init?.method ?? "GET",
+                path: (0, error_1.errorRequestPath)(path),
                 service: "control",
                 cause: error,
+                statusCode: response?.status,
+                requestId: response ? getRequestId(response) : undefined,
             });
         }
     }

package/dist/services/normalize.d.ts

@@ -0,0 +1,3 @@
+/** Nullable numeric wire values used by sandbox and volume endpoints. */
+export declare const optionalNumber: (value: unknown, integer?: boolean) => number | null | undefined;
+export declare const optionalInteger: (value: unknown) => number | null | undefined;

package/dist/services/normalize.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optionalInteger = exports.optionalNumber = void 0;
+const error_1 = require("../error");
+/** Nullable numeric wire values used by sandbox and volume endpoints. */
+const optionalNumber = (value, integer = false) => {
+    if (value === undefined || value === null)
+        return value;
+    if (typeof value === "string" && value.trim() === "")
+        return null;
+    const parsed = typeof value === "string" ? Number(value) : value;
+    if (typeof parsed !== "number" ||
+        !Number.isFinite(parsed) ||
+        (integer && !Number.isSafeInteger(parsed))) {
+        throw new error_1.HyperbrowserError("Invalid numeric value in API response", { service: "control" });
+    }
+    return parsed;
+};
+exports.optionalNumber = optionalNumber;
+const optionalInteger = (value) => (0, exports.optionalNumber)(value, true);
+exports.optionalInteger = optionalInteger;

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 { CompleteSandboxImageBuildParams, CreateSandboxImageBuildParams, CreateSandboxParams, SandboxDetail, SandboxExposeParams, SandboxExposeResult, SandboxExecParams, SandboxExecOptions, SandboxImageBuild, SandboxImageBuildCreateResult, SandboxImageBuildListParams, SandboxImageBuildListResponse, SandboxImageListParams, SandboxImageListResponse, SandboxListParams, SandboxListResponse, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxNetworkPolicyPatch, SandboxNetworkUpdateResult, SandboxProcessResult, SandboxImageDeleteResult, SandboxSnapshotDeleteResult, SandboxSnapshotListParams, SandboxSnapshotListResponse, SandboxSnapshotSummary, SandboxUnexposeResult } from "../types/sandbox";
+import { BuildSandboxImageFromDockerImageOptions, BuildSandboxImageFromDockerfileOptions, CompleteSandboxImageBuildParams, CreateSandboxImageBuildParams, CreateSandboxParams, StartSandboxFromSnapshotParams, SandboxRuntimeSession, SandboxRuntimeTarget, GetOrBuildSandboxImageOptions, ReuseSandboxDockerImageParams, SandboxDockerImageReuseResult, SandboxImageBuildResolution, SandboxImageBuildWaitOptions, SandboxImageSummary, SandboxDetail, SandboxExposeParams, SandboxExposeResult, SandboxExecParams, SandboxExecOptions, SandboxImageBuild, SandboxImageBuildCreateResult, SandboxImageBuildListParams, SandboxImageBuildListResponse, SandboxImageListParams, SandboxImageListResponse, SandboxListParams, SandboxListResponse, SandboxMemorySnapshotParams, SandboxMemorySnapshotResult, SandboxNetworkPolicyPatch, SandboxNetworkUpdateResult, SandboxProcessResult, SandboxImageDeleteResult, SandboxSnapshotDeleteResult, SandboxSnapshotListParams, SandboxSnapshotListResponse, SandboxSnapshotSummary, SandboxUnexposeResult } from "../types/sandbox";
 import { BaseService } from "./base";
 export declare class SandboxHandle {
     private readonly service;
@@ -44,6 +44,9 @@ export declare class SandboxHandle {
     private resolveRuntimeConnection;
     private resolveRuntimeSocketConnectionInfo;
     private isRuntimeSessionExpiring;
+    createRuntimeSession(options?: {
+        forceRefresh?: boolean;
+    }): Promise<SandboxRuntimeSession>;
     private ensureRuntimeSession;
     private applyRuntimeSession;
     private clearRuntimeSession;
@@ -55,6 +58,8 @@ export declare class SandboxesService extends BaseService {
     readonly runtimeProxyOverride?: string;
     constructor(apiKey: string, baseUrl: string, timeout: number, runtimeProxyOverride?: string);
     create(params: CreateSandboxParams): Promise<SandboxHandle>;
+    startFromSnapshot(params: StartSandboxFromSnapshotParams): Promise<SandboxHandle>;
+    getRuntimeSession(id: string): Promise<SandboxRuntimeSession>;
     get(id: string): Promise<SandboxHandle>;
     connect(id: string): Promise<SandboxHandle>;
     list(params?: SandboxListParams): Promise<SandboxListResponse>;
@@ -65,14 +70,46 @@ 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): Promise<SandboxExposeResult>;
+    expose(id: string, params: SandboxExposeParams, runtime?: SandboxRuntimeTarget): Promise<SandboxExposeResult>;
     getSnapshot(snapshot: string): Promise<SandboxSnapshotSummary>;
     deleteSnapshot(snapshot: string): Promise<SandboxSnapshotDeleteResult>;
     createImageBuild(params: CreateSandboxImageBuildParams): Promise<SandboxImageBuildCreateResult>;
-    getImageBuild(buildId: string): Promise<SandboxImageBuild>;
+    getImageBuild(buildId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<SandboxImageBuild>;
     listImageBuilds(params?: SandboxImageBuildListParams): Promise<SandboxImageBuildListResponse>;
     completeImageBuild(buildId: string, params: CompleteSandboxImageBuildParams): Promise<SandboxImageBuild>;
     cancelImageBuild(buildId: string): Promise<SandboxImageBuild>;
+    reuseDockerImage(params: ReuseSandboxDockerImageParams): Promise<SandboxDockerImageReuseResult>;
+    /** Find an exact ready team image, including revisions awaiting backup. */
+    findReadyImage(imageName: string): Promise<SandboxImageSummary | null>;
+    /** Poll an image build until it completes, rejecting on failure or timeout. */
+    waitForImageBuild(buildId: string, options?: SandboxImageBuildWaitOptions): Promise<SandboxImageBuild>;
+    /** Import a local Docker image as reusable layers, reusing exact cached imports. */
+    buildImageFromDockerImage(options: BuildSandboxImageFromDockerImageOptions): Promise<SandboxImageBuild>;
+    /**
+     * Build a Dockerfile into a sandbox image.
+     *
+     * Remote builds (default) upload only the effective build context and build
+     * on Hyperbrowser. `remote: false` builds with local Docker and imports the
+     * resulting image instead.
+     */
+    buildImageFromDockerfile(options: BuildSandboxImageFromDockerfileOptions): Promise<SandboxImageBuild>;
+    /**
+     * Reuse, join, or build content-derived remote Dockerfile/image inputs.
+     *
+     * Supply exactly one of `contextPath` or `dockerImage`. Names include source
+     * contents, platform and image initialization overrides. `forceBuild` skips
+     * ready-image lookup, but joins matching active builds and retains builder
+     * layer/artifact caches. Canceling polling never cancels the backend build.
+     * `waitTimeout` applies to this caller's polling, independently of uploads.
+     * This composes existing APIs; lookup plus creation is not server-atomic.
+     */
+    getOrBuildImage(options: GetOrBuildSandboxImageOptions): Promise<SandboxImageBuildResolution>;
+    private buildImageFromRemoteDockerfile;
+    /** Create a build, upload requested artifacts, complete it, and optionally wait. */
+    private submitImageBuild;
+    private completeImageBuildResilient;
     updateNetwork(id: string, policy: SandboxNetworkPolicyPatch): Promise<SandboxNetworkUpdateResult>;
     unexpose(id: string, port: number): Promise<SandboxUnexposeResult>;
     private createDetail;