@hyperbrowser/sdk 0.81.2 → 0.82.1

package/dist/client.d.ts

@@ -12,6 +12,7 @@ import { HyperAgentService } from "./services/agents/hyper-agent";
 import { TeamService } from "./services/team";
 import { ComputerActionService } from "./services/computer-action";
 import { GeminiComputerUseService } from "./services/agents/gemini-computer-use";
+import { WebService } from "./services/web";
 export declare class HyperbrowserError extends Error {
     statusCode?: number | undefined;
     constructor(message: string, statusCode?: number | undefined);
@@ -23,6 +24,7 @@ export declare class HyperbrowserClient {
     readonly extract: ExtractService;
     readonly profiles: ProfilesService;
     readonly extensions: ExtensionService;
+    readonly web: WebService;
     readonly agents: {
         browserUse: BrowserUseService;
         claudeComputerUse: ClaudeComputerUseService;

package/dist/client.js

@@ -14,6 +14,7 @@ const hyper_agent_1 = require("./services/agents/hyper-agent");
 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");
 class HyperbrowserError extends Error {
     constructor(message, statusCode) {
         super(`[Hyperbrowser]: ${message}`);
@@ -36,6 +37,7 @@ class HyperbrowserClient {
         this.extract = new extract_1.ExtractService(apiKey, baseUrl, timeout);
         this.profiles = new profiles_1.ProfilesService(apiKey, baseUrl, timeout);
         this.extensions = new extensions_1.ExtensionService(apiKey, baseUrl, timeout);
+        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.agents = {

package/dist/services/web/batch-fetch.d.ts

@@ -0,0 +1,26 @@
+import { BatchFetchJobResponse, BatchFetchJobStatusResponse, GetBatchFetchJobParams, StartBatchFetchJobParams, StartBatchFetchJobResponse } from "../../types/web/batch-fetch";
+import { BaseService } from "../base";
+export declare class BatchFetchService extends BaseService {
+    /**
+     * Start a new batch fetch job
+     * @param params The parameters for the batch fetch job
+     */
+    start(params: StartBatchFetchJobParams): Promise<StartBatchFetchJobResponse>;
+    /**
+     * Get the status of a batch fetch job
+     * @param id The ID of the batch fetch job to get
+     */
+    getStatus(id: string): Promise<BatchFetchJobStatusResponse>;
+    /**
+     * Get the details of a batch fetch job
+     * @param id The ID of the batch fetch job to get
+     * @param params Optional parameters to filter the batch fetch job
+     */
+    get(id: string, params?: GetBatchFetchJobParams): Promise<BatchFetchJobResponse>;
+    /**
+     * Start a batch fetch job and wait for it to complete
+     * @param params The parameters for the batch fetch job
+     * @param returnAllPages Whether to return all pages in the batch fetch job response
+     */
+    startAndWait(params: StartBatchFetchJobParams, returnAllPages?: boolean): Promise<BatchFetchJobResponse>;
+}

package/dist/services/web/batch-fetch.js

@@ -0,0 +1,170 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchFetchService = void 0;
+const zod_to_json_schema_1 = __importDefault(require("zod-to-json-schema"));
+const zod_1 = require("zod");
+const base_1 = require("../base");
+const utils_1 = require("../../utils");
+const client_1 = require("../../client");
+const constants_1 = require("../../types/constants");
+const utils_2 = require("../../utils");
+class BatchFetchService extends base_1.BaseService {
+    /**
+     * Start a new batch fetch job
+     * @param params The parameters for the batch fetch job
+     */
+    async start(params) {
+        try {
+            if (params.outputs?.formats) {
+                for (const output of params.outputs.formats) {
+                    if (typeof output === "object" && "type" in output && output.type === "json") {
+                        const jsonOutput = output;
+                        if (jsonOutput.schema) {
+                            if ((0, utils_2.isZodSchema)(jsonOutput.schema)) {
+                                try {
+                                    output.schema = (0, zod_1.toJSONSchema)(jsonOutput.schema);
+                                }
+                                catch {
+                                    output.schema = (0, zod_to_json_schema_1.default)(jsonOutput.schema);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            return await this.request("/web/batch-fetch", {
+                method: "POST",
+                body: JSON.stringify(params),
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError("Failed to start batch fetch job", undefined);
+        }
+    }
+    /**
+     * Get the status of a batch fetch job
+     * @param id The ID of the batch fetch job to get
+     */
+    async getStatus(id) {
+        try {
+            return await this.request(`/web/batch-fetch/${id}/status`);
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError(`Failed to get batch fetch job ${id} status`, undefined);
+        }
+    }
+    /**
+     * Get the details of a batch fetch job
+     * @param id The ID of the batch fetch job to get
+     * @param params Optional parameters to filter the batch fetch job
+     */
+    async get(id, params) {
+        try {
+            return await this.request(`/web/batch-fetch/${id}`, undefined, {
+                page: params?.page,
+                batchSize: params?.batchSize,
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError(`Failed to get batch fetch job ${id}`, undefined);
+        }
+    }
+    /**
+     * Start a batch fetch job and wait for it to complete
+     * @param params The parameters for the batch fetch job
+     * @param returnAllPages Whether to return all pages in the batch fetch job response
+     */
+    async startAndWait(params, returnAllPages = true) {
+        const job = await this.start(params);
+        const jobId = job.jobId;
+        if (!jobId) {
+            throw new client_1.HyperbrowserError("Failed to start batch fetch job, could not get job ID");
+        }
+        let failures = 0;
+        let jobStatus = "pending";
+        while (true) {
+            try {
+                const { status } = await this.getStatus(jobId);
+                if (status === "completed" || status === "failed") {
+                    jobStatus = status;
+                    break;
+                }
+                failures = 0;
+            }
+            catch (error) {
+                failures++;
+                if (failures >= constants_1.POLLING_ATTEMPTS) {
+                    throw new client_1.HyperbrowserError(`Failed to poll batch fetch job ${jobId} after ${constants_1.POLLING_ATTEMPTS} attempts: ${error}`);
+                }
+            }
+            await (0, utils_1.sleep)(2000);
+        }
+        failures = 0;
+        if (!returnAllPages) {
+            while (true) {
+                try {
+                    return await this.get(jobId);
+                }
+                catch (error) {
+                    failures++;
+                    if (failures >= constants_1.POLLING_ATTEMPTS) {
+                        throw new client_1.HyperbrowserError(`Failed to get batch fetch job ${jobId} after ${constants_1.POLLING_ATTEMPTS} attempts: ${error}`);
+                    }
+                }
+                await (0, utils_1.sleep)(500);
+            }
+        }
+        failures = 0;
+        const jobResponse = {
+            jobId,
+            status: jobStatus,
+            data: [],
+            currentPageBatch: 0,
+            totalPageBatches: 0,
+            totalPages: 0,
+            batchSize: 100,
+        };
+        let firstCheck = true;
+        while (firstCheck || jobResponse.currentPageBatch < jobResponse.totalPageBatches) {
+            try {
+                const tmpJobResponse = await this.get(jobId, {
+                    page: jobResponse.currentPageBatch + 1,
+                    batchSize: 100,
+                });
+                if (tmpJobResponse.data) {
+                    jobResponse.data?.push(...tmpJobResponse.data);
+                }
+                if (tmpJobResponse.error) {
+                    jobResponse.error = tmpJobResponse.error;
+                }
+                jobResponse.currentPageBatch = tmpJobResponse.currentPageBatch;
+                jobResponse.totalPages = tmpJobResponse.totalPages;
+                jobResponse.totalPageBatches = tmpJobResponse.totalPageBatches;
+                jobResponse.batchSize = tmpJobResponse.batchSize;
+                failures = 0;
+                firstCheck = false;
+            }
+            catch (error) {
+                failures++;
+                if (failures >= constants_1.POLLING_ATTEMPTS) {
+                    throw new client_1.HyperbrowserError(`Failed to get batch page ${jobResponse.currentPageBatch + 1} for job ${jobId} after ${constants_1.POLLING_ATTEMPTS} attempts: ${error}`);
+                }
+            }
+            await (0, utils_1.sleep)(500);
+        }
+        return jobResponse;
+    }
+}
+exports.BatchFetchService = BatchFetchService;

package/dist/services/web/index.d.ts

@@ -0,0 +1,18 @@
+import { BaseService } from "../base";
+import { FetchParams, FetchResponse } from "../../types/web/fetch";
+import { WebSearchParams, WebSearchResponse } from "../../types/web/search";
+import { BatchFetchService } from "./batch-fetch";
+export declare class WebService extends BaseService {
+    readonly batchFetch: BatchFetchService;
+    constructor(apiKey: string, baseUrl: string, timeout: number);
+    /**
+     * Fetch a URL and extract content
+     * @param params The parameters for the fetch request
+     */
+    fetch(params: FetchParams): Promise<FetchResponse>;
+    /**
+     * Search the web
+     * @param params The parameters for the search request
+     */
+    search(params: WebSearchParams): Promise<WebSearchResponse>;
+}

package/dist/services/web/index.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebService = void 0;
+const zod_1 = require("zod");
+const zod_to_json_schema_1 = __importDefault(require("zod-to-json-schema"));
+const base_1 = require("../base");
+const client_1 = require("../../client");
+const utils_1 = require("../../utils");
+const batch_fetch_1 = require("./batch-fetch");
+class WebService extends base_1.BaseService {
+    constructor(apiKey, baseUrl, timeout) {
+        super(apiKey, baseUrl, timeout);
+        this.batchFetch = new batch_fetch_1.BatchFetchService(apiKey, baseUrl, timeout);
+    }
+    /**
+     * Fetch a URL and extract content
+     * @param params The parameters for the fetch request
+     */
+    async fetch(params) {
+        try {
+            // Handle JSON schema serialization if needed (similar to Python SDK)
+            if (params.outputs?.formats) {
+                for (const output of params.outputs.formats) {
+                    if (typeof output === "object" && "type" in output && output.type === "json") {
+                        const jsonOutput = output;
+                        if (jsonOutput.schema) {
+                            if ((0, utils_1.isZodSchema)(jsonOutput.schema)) {
+                                try {
+                                    output.schema = (0, zod_1.toJSONSchema)(jsonOutput.schema);
+                                }
+                                catch {
+                                    output.schema = (0, zod_to_json_schema_1.default)(jsonOutput.schema);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            return await this.request("/web/fetch", {
+                method: "POST",
+                body: JSON.stringify(params),
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError("Failed to fetch URL", undefined);
+        }
+    }
+    /**
+     * Search the web
+     * @param params The parameters for the search request
+     */
+    async search(params) {
+        try {
+            return await this.request("/web/search", {
+                method: "POST",
+                body: JSON.stringify(params),
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError("Failed to search web", undefined);
+        }
+    }
+}
+exports.WebService = WebService;

package/dist/types/index.d.ts

@@ -13,3 +13,7 @@ export { CreateExtensionParams, CreateExtensionResponse, ListExtensionsResponse,
 export { ExtractJobStatus, BrowserUseTaskStatus, BrowserUseLlm, ClaudeComputerUseLlm, 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";
 export { TeamCreditInfo } from "./team";
 export { ComputerAction, Coordinate, ClickActionParams, DragActionParams, PressKeysActionParams, MoveMouseActionParams, ScreenshotActionParams, ScrollActionParams, TypeTextActionParams, ComputerActionParams, ComputerActionResponse, ComputerActionMouseButton, ComputerActionResponseData, HoldKeyActionParams, MouseDownActionParams, MouseUpActionParams, GetClipboardTextActionParams, PutSelectionTextActionParams, ComputerActionResponseDataClipboardText, } from "./computer-action";
+export { FetchParams, FetchResponse, FetchResponseData, FetchStatus } from "./web/fetch";
+export { StartBatchFetchJobParams, GetBatchFetchJobParams, StartBatchFetchJobResponse, BatchFetchJobStatusResponse, BatchFetchJobResponse, BatchFetchJobStatus, } from "./web/batch-fetch";
+export { WebSearchParams, WebSearchResponse, WebSearchResponseData, WebSearchResultItem, WebSearchFilters, WebSearchLocation, WebSearchFiletype, WebSearchStatus, } from "./web/search";
+export { FetchStealthMode, FetchSanitizeMode, FetchWaitUntil, FetchScreenshotFormat, PageStatus, FetchOutputScreenshotOptions, FetchStorageStateOptions, FetchBrowserLocationOptions, PageData, FetchOutputMarkdown, FetchOutputHtml, FetchOutputLinks, FetchOutputScreenshot, FetchOutputJsonOptions, FetchOutputJson, FetchOutputFormat, FetchOutputOptions, FetchBrowserOptions, FetchNavigationOptions, FetchCacheOptions, } from "./web/common";

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

@@ -0,0 +1,30 @@
+import { FetchBrowserOptions, FetchCacheOptions, FetchNavigationOptions, FetchOutputOptions, FetchStealthMode, PageData } from "./common";
+export type BatchFetchJobStatus = "pending" | "running" | "completed" | "failed";
+export interface StartBatchFetchJobParams {
+    urls: string[];
+    stealth?: FetchStealthMode;
+    outputs?: FetchOutputOptions;
+    browser?: FetchBrowserOptions;
+    navigation?: FetchNavigationOptions;
+    cache?: FetchCacheOptions;
+}
+export interface GetBatchFetchJobParams {
+    page?: number;
+    batchSize?: number;
+}
+export interface StartBatchFetchJobResponse {
+    jobId: string;
+}
+export interface BatchFetchJobStatusResponse {
+    status: BatchFetchJobStatus;
+}
+export interface BatchFetchJobResponse {
+    jobId: string;
+    status: BatchFetchJobStatus;
+    error?: string;
+    data?: PageData[];
+    totalPages: number;
+    totalPageBatches: number;
+    currentPageBatch: number;
+    batchSize: number;
+}

package/dist/types/web/batch-fetch.js

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

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

@@ -0,0 +1,74 @@
+import { Country, State } from "../constants";
+import { ScreenConfig } from "../session";
+export type FetchStealthMode = "none" | "auto" | "ultra";
+export type FetchSanitizeMode = "none" | "basic" | "advanced";
+export type FetchWaitUntil = "load" | "domcontentloaded" | "networkidle";
+export type FetchScreenshotFormat = "jpeg" | "png" | "webp";
+export type PageStatus = "completed" | "failed" | "pending" | "running";
+export interface FetchOutputScreenshotOptions {
+    fullPage?: boolean;
+    format?: FetchScreenshotFormat;
+    cropToContent?: boolean;
+    cropToContentMaxHeight?: number;
+    cropToContentMinHeight?: number;
+}
+export interface FetchStorageStateOptions {
+    localStorage?: Record<string, string>;
+    sessionStorage?: Record<string, string>;
+}
+export interface FetchBrowserLocationOptions {
+    country?: Country;
+    state?: State;
+    city?: string;
+}
+export interface PageData {
+    url: string;
+    status: PageStatus;
+    error?: string;
+    metadata?: Record<string, string | string[]>;
+    markdown?: string;
+    html?: string;
+    links?: string[];
+    screenshot?: string;
+    json?: Record<string, any>;
+}
+export interface FetchOutputMarkdown {
+    type: "markdown";
+}
+export interface FetchOutputHtml {
+    type: "html";
+}
+export interface FetchOutputLinks {
+    type: "links";
+}
+export interface FetchOutputScreenshot extends FetchOutputScreenshotOptions {
+    type: "screenshot";
+}
+export interface FetchOutputJsonOptions {
+    schema?: any;
+}
+export interface FetchOutputJson extends FetchOutputJsonOptions {
+    type: "json";
+}
+export type FetchOutputFormat = FetchOutputMarkdown | FetchOutputHtml | FetchOutputLinks | FetchOutputScreenshot | FetchOutputJson | "markdown" | "html" | "links" | "screenshot";
+export interface FetchOutputOptions {
+    formats?: FetchOutputFormat[];
+    sanitize?: FetchSanitizeMode;
+    includeSelectors?: string[];
+    excludeSelectors?: string[];
+    storageState?: FetchStorageStateOptions;
+}
+export interface FetchBrowserOptions {
+    screen?: ScreenConfig;
+    profileId?: string;
+    solveCaptchas?: string;
+    location?: FetchBrowserLocationOptions;
+}
+export interface FetchNavigationOptions {
+    waitUntil?: FetchWaitUntil;
+    timeoutMs?: number;
+    waitFor?: number;
+}
+export interface FetchCacheOptions {
+    maxAgeSeconds?: number;
+}

package/dist/types/web/common.js

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

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

@@ -0,0 +1,24 @@
+import { FetchStealthMode, FetchOutputOptions, FetchBrowserOptions, FetchNavigationOptions, FetchCacheOptions } from "./common";
+export type FetchStatus = "completed" | "failed" | "pending" | "running";
+export interface FetchParams {
+    url: string;
+    stealth?: FetchStealthMode;
+    outputs?: FetchOutputOptions;
+    browser?: FetchBrowserOptions;
+    navigation?: FetchNavigationOptions;
+    cache?: FetchCacheOptions;
+}
+export interface FetchResponseData {
+    metadata?: Record<string, string | string[]>;
+    html?: string;
+    markdown?: string;
+    links?: string[];
+    screenshot?: string;
+    json?: Record<string, any>;
+}
+export interface FetchResponse {
+    jobId: string;
+    status: FetchStatus;
+    error?: string;
+    data?: FetchResponseData;
+}

package/dist/types/web/fetch.js

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

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

@@ -0,0 +1,41 @@
+import { Country, State } from "../constants";
+export type WebSearchFiletype = "pdf" | "doc" | "docx" | "xls" | "xlsx" | "ppt" | "pptx" | "html";
+export type WebSearchStatus = "completed" | "failed" | "pending" | "running";
+export interface WebSearchFilters {
+    exactPhrase?: boolean;
+    semanticPhrase?: boolean;
+    excludeTerms?: string[];
+    boostTerms?: string[];
+    filetype?: WebSearchFiletype;
+    site?: string;
+    excludeSite?: string;
+    intitle?: string;
+    inurl?: string;
+}
+export interface WebSearchLocation {
+    country?: Country;
+    state?: State;
+    city?: string;
+}
+export interface WebSearchParams {
+    query: string;
+    page?: number;
+    maxAgeSeconds?: number;
+    location?: WebSearchLocation;
+    filters?: WebSearchFilters;
+}
+export interface WebSearchResultItem {
+    title: string;
+    url: string;
+    description: string;
+}
+export interface WebSearchResponseData {
+    query: string;
+    results: WebSearchResultItem[];
+}
+export interface WebSearchResponse {
+    jobId: string;
+    status: WebSearchStatus;
+    error?: string;
+    data?: WebSearchResponseData;
+}

package/dist/types/web/search.js

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

package/package.json

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