@hyperbrowser/sdk 0.2.0 → 0.4.0

package/README.md

@@ -0,0 +1,48 @@
+# Hyperbrowser SDK
+
+A TypeScript/JavaScript SDK for interacting with the Hyperbrowser API.
+
+## Installation
+
+Hyperbrowser can be installed via npm by running:
+
+```bash
+npm install @hyperbrowser/sdk
+```
+
+## Usage
+
+```typescript
+import { connect } from "puppeteer-core";
+import Hyperbrowser from "hyperbrowser";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+const client = new Hyperbrowser({
+  apiKey: process.env.HYPERBROWSER_API_KEY,
+});
+
+(async () => {
+  const session = await client.createSession();
+
+  const browser = await connect({
+    browserWSEndpoint: session.wsEndpoint,
+    defaultViewport: null,
+  });
+
+  // Create a new page
+  const [page] = await browser.pages();
+
+  // Navigate to a website
+  console.log("Navigating to Hacker News...");
+  await page.goto("https://news.ycombinator.com/");
+  const pageTitle = await page.title();
+  console.log("Page title:", pageTitle);
+
+  await page.close();
+  await browser.close();
+  console.log("Session completed!");
+  await client.stopSession(session.id);
+})().catch((error) => console.error(error.message));
+```

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { Response } from "node-fetch";
 import { HyperbrowserConfig } from "./types/config";
-import { BasicResponse, SessionDetail, SessionListParams, SessionListResponse } from "./types/session";
+import { BasicResponse, CreateSessionParams, SessionDetail, SessionListParams, SessionListResponse } from "./types/session";
+import { ScrapeJobResponse, StartScrapeJobParams, StartScrapeJobResponse } from "./types/scrape";
 export declare class HyperbrowserError extends Error {
     statusCode?: number | undefined;
     response?: Response | undefined;
@@ -14,8 +15,9 @@ export declare class HyperbrowserClient {
     private request;
     /**
      * Create a new browser session
+     * @param params Configuration parameters for the new session
      */
-    createSession(): Promise<SessionDetail>;
+    createSession(params?: CreateSessionParams): Promise<SessionDetail>;
     /**
      * Get details of an existing session
      */
@@ -28,4 +30,6 @@ export declare class HyperbrowserClient {
      * List all sessions with optional filtering
      */
     listSessions(params?: SessionListParams): Promise<SessionListResponse>;
+    startScrapeJob(params: StartScrapeJobParams): Promise<StartScrapeJobResponse>;
+    getScrapeJob(id: string): Promise<ScrapeJobResponse>;
 }

package/dist/client.js

@@ -74,10 +74,14 @@ class HyperbrowserClient {
     }
     /**
      * Create a new browser session
+     * @param params Configuration parameters for the new session
      */
-    async createSession() {
+    async createSession(params) {
         try {
-            return await this.request("/session", { method: "POST" });
+            return await this.request("/session", {
+                method: "POST",
+                body: params ? JSON.stringify(params) : undefined,
+            });
         }
         catch (error) {
             if (error instanceof HyperbrowserError) {
@@ -133,5 +137,30 @@ class HyperbrowserClient {
             throw new HyperbrowserError("Failed to list sessions", undefined, undefined, error instanceof Error ? error : undefined);
         }
     }
+    async startScrapeJob(params) {
+        try {
+            return await this.request("/scrape", {
+                method: "POST",
+                body: JSON.stringify(params),
+            });
+        }
+        catch (error) {
+            if (error instanceof HyperbrowserError) {
+                throw error;
+            }
+            throw new HyperbrowserError("Failed to start scrape job", undefined, undefined, error instanceof Error ? error : undefined);
+        }
+    }
+    async getScrapeJob(id) {
+        try {
+            return await this.request(`/scrape/${id}`);
+        }
+        catch (error) {
+            if (error instanceof HyperbrowserError) {
+                throw error;
+            }
+            throw new HyperbrowserError(`Failed to get scrape job ${id}`, undefined, undefined, error instanceof Error ? error : undefined);
+        }
+    }
 }
 exports.HyperbrowserClient = HyperbrowserClient;

package/dist/types/constants.d.ts

@@ -0,0 +1,5 @@
+export type ScrapeJobStatus = "pending" | "running" | "completed" | "failed";
+export type Country = "AD" | "AE" | "AF" | "AL" | "AM" | "AO" | "AR" | "AT" | "AU" | "AW" | "AZ" | "BA" | "BD" | "BE" | "BG" | "BH" | "BJ" | "BO" | "BR" | "BS" | "BT" | "BY" | "BZ" | "CA" | "CF" | "CH" | "CI" | "CL" | "CM" | "CN" | "CO" | "CR" | "CU" | "CY" | "CZ" | "DE" | "DJ" | "DK" | "DM" | "EC" | "EE" | "EG" | "ES" | "ET" | "EU" | "FI" | "FJ" | "FR" | "GB" | "GE" | "GH" | "GM" | "GR" | "HK" | "HN" | "HR" | "HT" | "HU" | "ID" | "IE" | "IL" | "IN" | "IQ" | "IR" | "IS" | "IT" | "JM" | "JO" | "JP" | "KE" | "KH" | "KR" | "KW" | "KZ" | "LB" | "LI" | "LR" | "LT" | "LU" | "LV" | "MA" | "MC" | "MD" | "ME" | "MG" | "MK" | "ML" | "MM" | "MN" | "MR" | "MT" | "MU" | "MV" | "MX" | "MY" | "MZ" | "NG" | "NL" | "NO" | "NZ" | "OM" | "PA" | "PE" | "PH" | "PK" | "PL" | "PR" | "PT" | "PY" | "QA" | "RANDOM_COUNTRY" | "RO" | "RS" | "RU" | "SA" | "SC" | "SD" | "SE" | "SG" | "SI" | "SK" | "SN" | "SS" | "TD" | "TG" | "TH" | "TM" | "TN" | "TR" | "TT" | "TW" | "UA" | "UG" | "US" | "UY" | "UZ" | "VE" | "VG" | "VN" | "YE" | "ZA" | "ZM" | "ZW" | "ad" | "ae" | "af" | "al" | "am" | "ao" | "ar" | "at" | "au" | "aw" | "az" | "ba" | "bd" | "be" | "bg" | "bh" | "bj" | "bo" | "br" | "bs" | "bt" | "by" | "bz" | "ca" | "cf" | "ch" | "ci" | "cl" | "cm" | "cn" | "co" | "cr" | "cu" | "cy" | "cz" | "de" | "dj" | "dk" | "dm" | "ec" | "ee" | "eg" | "es" | "et" | "eu" | "fi" | "fj" | "fr" | "gb" | "ge" | "gh" | "gm" | "gr" | "hk" | "hn" | "hr" | "ht" | "hu" | "id" | "ie" | "il" | "in" | "iq" | "ir" | "is" | "it" | "jm" | "jo" | "jp" | "ke" | "kh" | "kr" | "kw" | "kz" | "lb" | "li" | "lr" | "lt" | "lu" | "lv" | "ma" | "mc" | "md" | "me" | "mg" | "mk" | "ml" | "mm" | "mn" | "mr" | "mt" | "mu" | "mv" | "mx" | "my" | "mz" | "ng" | "nl" | "no" | "nz" | "om" | "pa" | "pe" | "ph" | "pk" | "pl" | "pr" | "pt" | "py" | "qa" | "ro" | "rs" | "ru" | "sa" | "sc" | "sd" | "se" | "sg" | "si" | "sk" | "sn" | "ss" | "td" | "tg" | "th" | "tm" | "tn" | "tr" | "tt" | "tw" | "ua" | "ug" | "us" | "uy" | "uz" | "ve" | "vg" | "vn" | "ye" | "za" | "zm" | "zw";
+export type OperatingSystem = "windows" | "android" | "macos" | "linux" | "ios";
+export type Platform = "chrome" | "firefox" | "safari" | "edge";
+export type ISO639_1 = "aa" | "ab" | "ae" | "af" | "ak" | "am" | "an" | "ar" | "as" | "av" | "ay" | "az" | "ba" | "be" | "bg" | "bh" | "bi" | "bm" | "bn" | "bo" | "br" | "bs" | "ca" | "ce" | "ch" | "co" | "cr" | "cs" | "cu" | "cv" | "cy" | "da" | "de" | "dv" | "dz" | "ee" | "el" | "en" | "eo" | "es" | "et" | "eu" | "fa" | "ff" | "fi" | "fj" | "fo" | "fr" | "fy" | "ga" | "gd" | "gl" | "gn" | "gu" | "gv" | "ha" | "he" | "hi" | "ho" | "hr" | "ht" | "hu" | "hy" | "hz" | "ia" | "id" | "ie" | "ig" | "ii" | "ik" | "io" | "is" | "it" | "iu" | "ja" | "jv" | "ka" | "kg" | "ki" | "kj" | "kk" | "kl" | "km" | "kn" | "ko" | "kr" | "ks" | "ku" | "kv" | "kw" | "ky" | "la" | "lb" | "lg" | "li" | "ln" | "lo" | "lt" | "lu" | "lv" | "mg" | "mh" | "mi" | "mk" | "ml" | "mn" | "mo" | "mr" | "ms" | "mt" | "my" | "na" | "nb" | "nd" | "ne" | "ng" | "nl" | "nn" | "no" | "nr" | "nv" | "ny" | "oc" | "oj" | "om" | "or" | "os" | "pa" | "pi" | "pl" | "ps" | "pt" | "qu" | "rm" | "rn" | "ro" | "ru" | "rw" | "sa" | "sc" | "sd" | "se" | "sg" | "si" | "sk" | "sl" | "sm" | "sn" | "so" | "sq" | "sr" | "ss" | "st" | "su" | "sv" | "sw" | "ta" | "te" | "tg" | "th" | "ti" | "tk" | "tl" | "tn" | "to" | "tr" | "ts" | "tt" | "tw" | "ty" | "ug" | "uk" | "ur" | "uz" | "ve" | "vi" | "vo" | "wa" | "wo" | "xh" | "yi" | "yo" | "za" | "zh" | "zu";

package/dist/types/constants.js

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

package/dist/types/scrape.d.ts

@@ -0,0 +1,28 @@
+import { ScrapeJobStatus } from "./constants";
+export interface StartScrapeJobParams {
+    url: string;
+}
+export interface StartScrapeJobResponse {
+    jobId: string;
+}
+export interface ScrapeJobMetadata {
+    title: string;
+    description: string;
+    robots: string;
+    ogTitle: string;
+    ogDescription: string;
+    ogUrl: string;
+    ogImage: string;
+    ogLocaleAlternate: string[];
+    ogSiteName: string;
+    sourceURL: string;
+}
+export interface ScrapeJobData {
+    metadata: ScrapeJobMetadata;
+    markdown: string;
+}
+export interface ScrapeJobResponse {
+    status: ScrapeJobStatus;
+    data?: ScrapeJobData;
+    error?: string;
+}

package/dist/types/scrape.js

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

package/dist/types/session.d.ts

@@ -1,3 +1,4 @@
+import { Country, ISO639_1, OperatingSystem, Platform } from "./constants";
 export type SessionStatus = "active" | "closed" | "error";
 export interface BasicResponse {
     success: boolean;
@@ -25,3 +26,20 @@ export interface SessionListResponse {
     page: number;
     perPage: number;
 }
+export interface ScreenConfig {
+    maxWidth: number;
+    maxHeight: number;
+    minWidth: number;
+    minHeight: number;
+}
+export interface CreateSessionParams {
+    proxyServer?: string;
+    proxyServerPassword?: string;
+    proxyServerUsername?: string;
+    proxyCountry?: Country;
+    operatingSystems?: OperatingSystem[];
+    device?: ("desktop" | "mobile")[];
+    platform?: Platform[];
+    locales?: ISO639_1[];
+    screen?: ScreenConfig;
+}

package/package.json

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