@hyperbrowser/sdk 0.18.0 → 0.20.0

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import { HyperbrowserConfig } from "./types/config";
+import { SessionsService } from "./services/sessions";
+import { ScrapeService } from "./services/scrape";
+import { CrawlService } from "./services/crawl";
+import { ProfilesService } from "./services/profiles";
+import { ExtensionService } from "./services/extensions";
+import { ExtractService } from "./services/extract";
+export declare class HyperbrowserError extends Error {
+    statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare class HyperbrowserClient {
+    readonly sessions: SessionsService;
+    readonly scrape: ScrapeService;
+    readonly crawl: CrawlService;
+    readonly extract: ExtractService;
+    readonly profiles: ProfilesService;
+    readonly extensions: ExtensionService;
+    constructor(config: HyperbrowserConfig);
+}

package/dist/client.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HyperbrowserClient = exports.HyperbrowserError = void 0;
+const sessions_1 = require("./services/sessions");
+const scrape_1 = require("./services/scrape");
+const crawl_1 = require("./services/crawl");
+const profiles_1 = require("./services/profiles");
+const extensions_1 = require("./services/extensions");
+const extract_1 = require("./services/extract");
+class HyperbrowserError extends Error {
+    constructor(message, statusCode) {
+        super(`[Hyperbrowser]: ${message}`);
+        this.statusCode = statusCode;
+        this.name = "HyperbrowserError";
+    }
+}
+exports.HyperbrowserError = HyperbrowserError;
+class HyperbrowserClient {
+    constructor(config) {
+        const apiKey = config.apiKey || process.env["HYPERBROWSER_API_KEY"];
+        const baseUrl = config.baseUrl || "https://app.hyperbrowser.ai";
+        const timeout = config.timeout || 30000;
+        if (!apiKey) {
+            throw new HyperbrowserError("API key is required - either pass it in config or set HYPERBROWSER_API_KEY environment variable");
+        }
+        this.sessions = new sessions_1.SessionsService(apiKey, baseUrl, timeout);
+        this.scrape = new scrape_1.ScrapeService(apiKey, baseUrl, timeout);
+        this.crawl = new crawl_1.CrawlService(apiKey, baseUrl, timeout);
+        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);
+    }
+}
+exports.HyperbrowserClient = HyperbrowserClient;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { HyperbrowserClient } from "./client";
+export { HyperbrowserError } from "./client";
+export declare const Hyperbrowser: typeof HyperbrowserClient;
+export default HyperbrowserClient;

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Hyperbrowser = exports.HyperbrowserError = void 0;
+const client_1 = require("./client");
+var client_2 = require("./client");
+Object.defineProperty(exports, "HyperbrowserError", { enumerable: true, get: function () { return client_2.HyperbrowserError; } });
+// Export HyperbrowserClient as Hyperbrowser for named imports
+exports.Hyperbrowser = client_1.HyperbrowserClient;
+exports.default = client_1.HyperbrowserClient;
+// For CommonJS compatibility
+if (typeof module !== "undefined" && module.exports) {
+    module.exports = client_1.HyperbrowserClient;
+    module.exports.Hyperbrowser = client_1.HyperbrowserClient;
+    module.exports.HyperbrowserClient = client_1.HyperbrowserClient;
+    module.exports.default = client_1.HyperbrowserClient;
+}

package/dist/services/base.d.ts

@@ -0,0 +1,8 @@
+import { RequestInit } from "node-fetch";
+export declare class BaseService {
+    protected readonly apiKey: string;
+    protected readonly baseUrl: string;
+    protected readonly timeout: number;
+    constructor(apiKey: string, baseUrl: string, timeout?: number);
+    protected request<T>(path: string, init?: RequestInit, params?: Record<string, string | number | undefined>): Promise<T>;
+}

package/dist/services/base.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseService = void 0;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+const client_1 = require("../client");
+class BaseService {
+    constructor(apiKey, baseUrl, timeout = 30000) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+        this.timeout = timeout;
+    }
+    async request(path, init, params) {
+        try {
+            const url = new URL(`${this.baseUrl}/api${path}`);
+            if (params) {
+                Object.entries(params).forEach(([key, value]) => {
+                    if (value !== undefined) {
+                        url.searchParams.append(key, value.toString());
+                    }
+                });
+            }
+            const headerKeys = Object.keys(init?.headers || {});
+            const contentTypeKey = headerKeys.find((key) => key.toLowerCase() === "content-type");
+            const response = await (0, node_fetch_1.default)(url.toString(), {
+                ...init,
+                timeout: this.timeout,
+                headers: {
+                    "x-api-key": this.apiKey,
+                    ...(contentTypeKey && init?.headers
+                        ? { "content-type": init.headers[contentTypeKey] }
+                        : { "content-type": "application/json" }),
+                    ...init?.headers,
+                },
+            });
+            if (!response.ok) {
+                let errorMessage;
+                try {
+                    const errorData = await response.json();
+                    errorMessage =
+                        errorData.message || errorData.error || `HTTP error! status: ${response.status}`;
+                }
+                catch {
+                    errorMessage = `HTTP error! status: ${response.status}`;
+                }
+                throw new client_1.HyperbrowserError(errorMessage, response.status);
+            }
+            if (response.headers.get("content-length") === "0") {
+                return {};
+            }
+            try {
+                return (await response.json());
+            }
+            catch {
+                throw new client_1.HyperbrowserError("Failed to parse JSON response", response.status);
+            }
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError(error instanceof Error ? error.message : "Unknown error occurred", undefined);
+        }
+    }
+}
+exports.BaseService = BaseService;

package/dist/services/crawl.d.ts

@@ -0,0 +1,21 @@
+import { CrawlJobResponse, GetCrawlJobParams, StartCrawlJobParams, StartCrawlJobResponse } from "../types/crawl";
+import { BaseService } from "./base";
+export declare class CrawlService extends BaseService {
+    /**
+     * Start a new crawl job
+     * @param params The parameters for the crawl job
+     */
+    start(params: StartCrawlJobParams): Promise<StartCrawlJobResponse>;
+    /**
+     * Get the status of a crawl job
+     * @param id The ID of the crawl job to get
+     * @param params Optional parameters to filter the crawl job
+     */
+    get(id: string, params?: GetCrawlJobParams): Promise<CrawlJobResponse>;
+    /**
+     * Start a crawl job and wait for it to complete
+     * @param params The parameters for the crawl job
+     * @param returnAllPages Whether to return all pages in the crawl job response
+     */
+    startAndWait(params: StartCrawlJobParams, returnAllPages?: boolean): Promise<CrawlJobResponse>;
+}

package/dist/services/crawl.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrawlService = void 0;
+const base_1 = require("./base");
+const utils_1 = require("../utils");
+const client_1 = require("../client");
+class CrawlService extends base_1.BaseService {
+    /**
+     * Start a new crawl job
+     * @param params The parameters for the crawl job
+     */
+    async start(params) {
+        try {
+            return await this.request("/crawl", {
+                method: "POST",
+                body: JSON.stringify(params),
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError("Failed to start crawl job", undefined);
+        }
+    }
+    /**
+     * Get the status of a crawl job
+     * @param id The ID of the crawl job to get
+     * @param params Optional parameters to filter the crawl job
+     */
+    async get(id, params) {
+        try {
+            return await this.request(`/crawl/${id}`, undefined, {
+                page: params?.page,
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError(`Failed to get crawl job ${id}`, undefined);
+        }
+    }
+    /**
+     * Start a crawl job and wait for it to complete
+     * @param params The parameters for the crawl job
+     * @param returnAllPages Whether to return all pages in the crawl 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 crawl job, could not get job ID");
+        }
+        let jobResponse;
+        while (true) {
+            jobResponse = await this.get(jobId);
+            if (jobResponse.status === "completed" || jobResponse.status === "failed") {
+                break;
+            }
+            await (0, utils_1.sleep)(2000);
+        }
+        if (!returnAllPages) {
+            return jobResponse;
+        }
+        while (jobResponse.currentPageBatch < jobResponse.totalPageBatches) {
+            const tmpJobResponse = await this.get(jobId, {
+                page: jobResponse.currentPageBatch + 1,
+            });
+            if (tmpJobResponse.data) {
+                jobResponse.data?.push(...tmpJobResponse.data);
+            }
+            jobResponse.currentPageBatch = tmpJobResponse.currentPageBatch;
+            jobResponse.totalCrawledPages = tmpJobResponse.totalCrawledPages;
+            jobResponse.totalPageBatches = tmpJobResponse.totalPageBatches;
+            jobResponse.batchSize = tmpJobResponse.batchSize;
+            await (0, utils_1.sleep)(500);
+        }
+        return jobResponse;
+    }
+}
+exports.CrawlService = CrawlService;

package/dist/services/extensions.d.ts

@@ -0,0 +1,13 @@
+import { CreateExtensionParams, CreateExtensionResponse, ListExtensionsResponse } from "../types/extension";
+import { BaseService } from "./base";
+export declare class ExtensionService extends BaseService {
+    /**
+     * Upload an extension to hyperbrowser
+     * @param params Configuration parameters for the new extension
+     */
+    create(params: CreateExtensionParams): Promise<CreateExtensionResponse>;
+    /**
+     * List all uploaded extensions for the account
+     */
+    list(): Promise<ListExtensionsResponse>;
+}

package/dist/services/extensions.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtensionService = void 0;
+const client_1 = require("../client");
+const base_1 = require("./base");
+const form_data_1 = __importDefault(require("form-data"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+async function checkFileExists(filePath) {
+    try {
+        await promises_1.default.access(filePath, promises_1.default.constants.R_OK);
+        const extension = node_path_1.default.extname(filePath);
+        if (extension !== ".zip") {
+            throw new client_1.HyperbrowserError("Extension file provided is not zipped", undefined);
+        }
+    }
+    catch (err) {
+        if (err instanceof client_1.HyperbrowserError) {
+            throw err;
+        }
+        throw new client_1.HyperbrowserError("Could not find extension file", undefined);
+    }
+}
+class ExtensionService extends base_1.BaseService {
+    /**
+     * Upload an extension to hyperbrowser
+     * @param params Configuration parameters for the new extension
+     */
+    async create(params) {
+        try {
+            await checkFileExists(params.filePath);
+            const form = new form_data_1.default();
+            form.append("file", await promises_1.default.readFile(params.filePath), {
+                filename: node_path_1.default.basename(params.filePath),
+                contentType: "application/zip",
+            });
+            if (params.name) {
+                form.append("name", params.name);
+            }
+            const response = await this.request("/extensions/add", {
+                method: "POST",
+                body: form,
+                headers: form.getHeaders(),
+            });
+            return response;
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError("Failed to upload extension", undefined);
+        }
+    }
+    /**
+     * List all uploaded extensions for the account
+     */
+    async list() {
+        try {
+            return await this.request("/extensions/list", { method: "GET" });
+        }
+        catch (err) {
+            if (err instanceof client_1.HyperbrowserError) {
+                throw err;
+            }
+            else {
+                throw new client_1.HyperbrowserError("Could not list extensions", undefined);
+            }
+        }
+    }
+}
+exports.ExtensionService = ExtensionService;

package/dist/services/extract.d.ts

@@ -0,0 +1,20 @@
+import { BaseService } from "./base";
+import { ExtractJobResponse, StartExtractJobResponse } from "../types/extract";
+import { StartExtractJobParams } from "../types/extract";
+export declare class ExtractService extends BaseService {
+    /**
+     * Start a new extract job
+     * @param params The parameters for the extract job
+     */
+    start(params: StartExtractJobParams): Promise<StartExtractJobResponse>;
+    /**
+     * Get the status of an extract job
+     * @param id The ID of the extract job to get
+     */
+    get(id: string): Promise<ExtractJobResponse>;
+    /**
+     * Start an extract job and wait for it to complete
+     * @param params The parameters for the extract job
+     */
+    startAndWait(params: StartExtractJobParams): Promise<ExtractJobResponse>;
+}

package/dist/services/extract.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExtractService = void 0;
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const base_1 = require("./base");
+const utils_1 = require("../utils");
+const client_1 = require("../client");
+const isZodSchema = (schema) => {
+    return (schema &&
+        typeof schema === "object" &&
+        "_def" in schema &&
+        "parse" in schema &&
+        typeof schema.parse === "function");
+};
+class ExtractService extends base_1.BaseService {
+    /**
+     * Start a new extract job
+     * @param params The parameters for the extract job
+     */
+    async start(params) {
+        try {
+            if (!params.schema && !params.prompt) {
+                throw new client_1.HyperbrowserError("Either schema or prompt must be provided");
+            }
+            if (params.schema) {
+                if (isZodSchema(params.schema)) {
+                    params.schema = (0, zod_to_json_schema_1.zodToJsonSchema)(params.schema);
+                }
+            }
+            return await this.request("/extract", {
+                method: "POST",
+                body: JSON.stringify(params),
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError("Failed to start extract job", undefined);
+        }
+    }
+    /**
+     * Get the status of an extract job
+     * @param id The ID of the extract job to get
+     */
+    async get(id) {
+        try {
+            return await this.request(`/extract/${id}`);
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError(`Failed to get extract job ${id}`, undefined);
+        }
+    }
+    /**
+     * Start an extract job and wait for it to complete
+     * @param params The parameters for the extract job
+     */
+    async startAndWait(params) {
+        const job = await this.start(params);
+        const jobId = job.jobId;
+        if (!jobId) {
+            throw new client_1.HyperbrowserError("Failed to start extract job, could not get job ID");
+        }
+        let jobResponse;
+        while (true) {
+            jobResponse = await this.get(jobId);
+            if (jobResponse.status === "completed" || jobResponse.status === "failed") {
+                break;
+            }
+            await (0, utils_1.sleep)(2000);
+        }
+        return jobResponse;
+    }
+}
+exports.ExtractService = ExtractService;

package/dist/services/profiles.d.ts

@@ -0,0 +1,19 @@
+import { BaseService } from "./base";
+import { ProfileResponse, CreateProfileResponse } from "../types/profile";
+import { BasicResponse } from "../types";
+export declare class ProfilesService extends BaseService {
+    /**
+     * Create a new profile
+     */
+    create(): Promise<CreateProfileResponse>;
+    /**
+     * Get details of an existing profile
+     * @param id The ID of the profile to get
+     */
+    get(id: string): Promise<ProfileResponse>;
+    /**
+     * Delete an existing profile
+     * @param id The ID of the profile to delete
+     */
+    delete(id: string): Promise<BasicResponse>;
+}

package/dist/services/profiles.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProfilesService = void 0;
+const base_1 = require("./base");
+const client_1 = require("../client");
+class ProfilesService extends base_1.BaseService {
+    /**
+     * Create a new profile
+     */
+    async create() {
+        try {
+            return await this.request("/profile", {
+                method: "POST",
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError("Failed to create profile", undefined);
+        }
+    }
+    /**
+     * Get details of an existing profile
+     * @param id The ID of the profile to get
+     */
+    async get(id) {
+        try {
+            return await this.request(`/profile/${id}`);
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError(`Failed to get profile ${id}`, undefined);
+        }
+    }
+    /**
+     * Delete an existing profile
+     * @param id The ID of the profile to delete
+     */
+    async delete(id) {
+        try {
+            return await this.request(`/profile/${id}`, {
+                method: "DELETE",
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError(`Failed to delete profile ${id}`, undefined);
+        }
+    }
+}
+exports.ProfilesService = ProfilesService;

package/dist/services/scrape.d.ts

@@ -0,0 +1,19 @@
+import { ScrapeJobResponse, StartScrapeJobParams, StartScrapeJobResponse } from "../types/scrape";
+import { BaseService } from "./base";
+export declare class ScrapeService extends BaseService {
+    /**
+     * Start a new scrape job
+     * @param params The parameters for the scrape job
+     */
+    start(params: StartScrapeJobParams): Promise<StartScrapeJobResponse>;
+    /**
+     * Get the status of a scrape job
+     * @param id The ID of the scrape job to get
+     */
+    get(id: string): Promise<ScrapeJobResponse>;
+    /**
+     * Start a scrape job and wait for it to complete
+     * @param params The parameters for the scrape job
+     */
+    startAndWait(params: StartScrapeJobParams): Promise<ScrapeJobResponse>;
+}

package/dist/services/scrape.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScrapeService = void 0;
+const base_1 = require("./base");
+const utils_1 = require("../utils");
+const client_1 = require("../client");
+class ScrapeService extends base_1.BaseService {
+    /**
+     * Start a new scrape job
+     * @param params The parameters for the scrape job
+     */
+    async start(params) {
+        try {
+            return await this.request("/scrape", {
+                method: "POST",
+                body: JSON.stringify(params),
+            });
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError("Failed to start scrape job", undefined);
+        }
+    }
+    /**
+     * Get the status of a scrape job
+     * @param id The ID of the scrape job to get
+     */
+    async get(id) {
+        try {
+            return await this.request(`/scrape/${id}`);
+        }
+        catch (error) {
+            if (error instanceof client_1.HyperbrowserError) {
+                throw error;
+            }
+            throw new client_1.HyperbrowserError(`Failed to get scrape job ${id}`, undefined);
+        }
+    }
+    /**
+     * Start a scrape job and wait for it to complete
+     * @param params The parameters for the scrape job
+     */
+    async startAndWait(params) {
+        const job = await this.start(params);
+        const jobId = job.jobId;
+        if (!jobId) {
+            throw new client_1.HyperbrowserError("Failed to start scrape job, could not get job ID");
+        }
+        let jobResponse;
+        while (true) {
+            jobResponse = await this.get(jobId);
+            if (jobResponse.status === "completed" || jobResponse.status === "failed") {
+                break;
+            }
+            await (0, utils_1.sleep)(2000);
+        }
+        return jobResponse;
+    }
+}
+exports.ScrapeService = ScrapeService;

package/dist/services/sessions.d.ts

@@ -0,0 +1,29 @@
+import { BasicResponse, CreateSessionParams, SessionDetail, SessionListParams, SessionListResponse, SessionRecording } from "../types/session";
+import { BaseService } from "./base";
+export declare class SessionsService extends BaseService {
+    /**
+     * Create a new browser session
+     * @param params Configuration parameters for the new session
+     */
+    create(params?: CreateSessionParams): Promise<SessionDetail>;
+    /**
+     * Get details of an existing session
+     * @param id The ID of the session to get
+     */
+    get(id: string): Promise<SessionDetail>;
+    /**
+     * Stop a running session
+     * @param id The ID of the session to stop
+     */
+    stop(id: string): Promise<BasicResponse>;
+    /**
+     * List all sessions with optional filtering
+     * @param params Optional parameters to filter the sessions
+     */
+    list(params?: SessionListParams): Promise<SessionListResponse>;
+    /**
+     * Get the recording of a session
+     * @param id The ID of the session to get the recording from
+     */
+    getRecording(id: string): Promise<SessionRecording[]>;
+}