@upcrawl/sdk 1.3.0 → 1.4.0

package/README.md

@@ -148,6 +148,41 @@ const result = await Upcrawl.generatePdfFromUrl({
 console.log(result.url); // Download URL for the PDF
 ```
 
+### Execute Code
+
+Run code in an isolated sandbox environment:
+
+```typescript
+const result = await Upcrawl.executeCode({
+  code: 'print("Hello, World!")',
+  language: 'python'
+});
+
+console.log(result.stdout);          // "Hello, World!\n"
+console.log(result.exitCode);        // 0
+console.log(result.executionTimeMs); // 95.23
+console.log(result.memoryUsageMb);   // 8.45
+```
+
+Each execution runs in its own isolated subprocess inside a Kata micro-VM with no network access. Code is cleaned up immediately after execution.
+
+```typescript
+// Multi-line code with imports
+const result = await Upcrawl.executeCode({
+  code: `
+import json
+data = {"name": "Upcrawl", "version": 1}
+print(json.dumps(data, indent=2))
+  `
+});
+
+console.log(result.stdout);
+// {
+//   "name": "Upcrawl",
+//   "version": 1
+// }
+```
+
 ### Domain Filtering
 
 Filter search results by domain:
@@ -249,7 +284,9 @@ import Upcrawl, {
   BatchScrapeOptions,
   BatchScrapeResponse,
   GeneratePdfOptions,
-  PdfResponse
+  PdfResponse,
+  ExecuteCodeOptions,
+  ExecuteCodeResponse
 } from '@upcrawl/sdk';
 
 const options: ScrapeOptions = {
@@ -275,6 +312,7 @@ const result: ScrapeResponse = await Upcrawl.scrape(options);
 | `Upcrawl.search(options)` | Search the web |
 | `Upcrawl.generatePdf(options)` | Generate PDF from HTML |
 | `Upcrawl.generatePdfFromUrl(options)` | Generate PDF from a URL |
+| `Upcrawl.executeCode(options)` | Execute code in an isolated sandbox |
 
 ### Scrape Options
 
@@ -323,6 +361,25 @@ const result: ScrapeResponse = await Upcrawl.scrape(options);
 | `printBackground` | `boolean` | Print background graphics |
 | `timeoutMs` | `number` | Timeout (5000-120000) |
 
+### Execute Code Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `code` | `string` | Code to execute (required) |
+| `language` | `'python'` | Language runtime (default: python) |
+
+### Execute Code Response
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `stdout` | `string` | Standard output |
+| `stderr` | `string` | Standard error |
+| `exitCode` | `number` | Exit code (0 = success, 124 = timeout) |
+| `executionTimeMs` | `number` | Execution time in milliseconds |
+| `timedOut` | `boolean` | Whether execution timed out |
+| `memoryUsageMb` | `number` | Peak memory usage in MB |
+| `cost` | `number` | Cost in USD |
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { AxiosInstance } from 'axios';
+
 /**
  * Upcrawl SDK Types
  * Type definitions for all API requests and responses
@@ -231,6 +233,96 @@ declare class UpcrawlError extends Error {
     readonly code: string;
     constructor(message: string, status: number, code?: string);
 }
+interface CreateBrowserSessionOptions {
+    /** Browser viewport width (800-3840). Defaults to 1280 */
+    width?: number;
+    /** Browser viewport height (600-2160). Defaults to 720 */
+    height?: number;
+    /** Run browser in headless mode. Defaults to true */
+    headless?: boolean;
+}
+interface BrowserSession {
+    /** Unique session identifier */
+    sessionId: string;
+    /** WebSocket URL for connecting with Playwright/Puppeteer */
+    wsEndpoint: string;
+    /** VNC URL for viewing the browser (if available) */
+    vncUrl: string | null;
+    /** Affinity cookie for sticky session routing (format: SCRAPER_AFFINITY=xxx) - extracted from response headers */
+    affinityCookie?: string;
+    /** Session creation timestamp */
+    createdAt: Date;
+    /** Browser viewport width */
+    width: number;
+    /** Browser viewport height */
+    height: number;
+}
+
+/**
+ * Upcrawl Browser Namespace
+ * Manage browser sessions for remote control with Playwright/Puppeteer
+ *
+ * @example
+ * ```typescript
+ * import Upcrawl from '@upcrawl/sdk';
+ * import playwright from 'playwright-core';
+ *
+ * const upcrawl = new Upcrawl('uc-your-api-key');
+ *
+ * // Create a browser session
+ * const session = await upcrawl.browser.create({
+ *   width: 1280,
+ *   height: 720,
+ *   headless: true
+ * });
+ *
+ * // Connect with Playwright
+ * const browser = await playwright.connect(session.wsEndpoint);
+ * const page = await browser.newPage();
+ * await page.goto('https://example.com');
+ *
+ * // Close the session when done
+ * await upcrawl.browser.close(session.sessionId);
+ * ```
+ */
+
+declare class Browser {
+    private createClient;
+    constructor(createClient: () => AxiosInstance);
+    /**
+     * Create a new browser session for remote control
+     * @param options - Session options including viewport size and headless mode
+     * @returns Promise with session details including WebSocket URL
+     *
+     * @example
+     * ```typescript
+     * const session = await upcrawl.browser.create({
+     *   width: 1280,
+     *   height: 720,
+     *   headless: true
+     * });
+     *
+     * console.log(session.wsEndpoint); // WebSocket URL for Playwright
+     * console.log(session.vncUrl);     // VNC URL for viewing (if available)
+     * ```
+     */
+    create(options?: CreateBrowserSessionOptions): Promise<BrowserSession>;
+    /**
+     * Close a browser session
+     * @param sessionId - The session ID to close
+     * @returns Promise that resolves when session is closed
+     *
+     * @example
+     * ```typescript
+     * await upcrawl.browser.close(session.sessionId);
+     * ```
+     */
+    close(sessionId: string): Promise<void>;
+    /**
+     * Handle API errors and convert to UpcrawlError
+     */
+    private handleError;
+}
 
 /**
  * Upcrawl API Client
@@ -525,10 +617,27 @@ declare const Upcrawl: {
      * @returns Promise with execution response (stdout, stderr, exit code, memory usage)
      */
     readonly executeCode: typeof executeCode;
+    /**
+     * Browser session management
+     * Create and manage browser sessions for remote control with Playwright/Puppeteer
+     *
+     * @example
+     * ```typescript
+     * const session = await Upcrawl.browser.create({
+     *   width: 1280,
+     *   height: 720,
+     *   headless: true
+     * });
+     *
+     * const browser = await playwright.connect(session.wsEndpoint);
+     * await upcrawl.browser.close(session.sessionId);
+     * ```
+     */
+    readonly browser: Browser;
     /**
      * Error class for Upcrawl API errors
      */
     readonly UpcrawlError: typeof UpcrawlError;
 };
 
-export { type BatchScrapeOptions, type BatchScrapeResponse, type ExecuteCodeOptions, type ExecuteCodeResponse, type GeneratePdfFromUrlOptions, type GeneratePdfOptions, type PdfMargin, type PdfResponse, type ScrapeMetadata, type ScrapeOptions, type ScrapeResponse, type SearchOptions, type SearchResponse, type SearchResultItem, type SearchResultWeb, type SummaryQuery, type UpcrawlConfig, UpcrawlError, type UpcrawlErrorResponse, batchScrape, configure, Upcrawl as default, executeCode, generatePdf, generatePdfFromUrl, getConfig, resetConfig, scrape, search, setApiKey, setBaseUrl, setTimeout };
+export { type BatchScrapeOptions, type BatchScrapeResponse, Browser, type BrowserSession, type CreateBrowserSessionOptions, type ExecuteCodeOptions, type ExecuteCodeResponse, type GeneratePdfFromUrlOptions, type GeneratePdfOptions, type PdfMargin, type PdfResponse, type ScrapeMetadata, type ScrapeOptions, type ScrapeResponse, type SearchOptions, type SearchResponse, type SearchResultItem, type SearchResultWeb, type SummaryQuery, type UpcrawlConfig, UpcrawlError, type UpcrawlErrorResponse, batchScrape, configure, Upcrawl as default, executeCode, generatePdf, generatePdfFromUrl, getConfig, resetConfig, scrape, search, setApiKey, setBaseUrl, setTimeout };

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { AxiosInstance } from 'axios';
+
 /**
  * Upcrawl SDK Types
  * Type definitions for all API requests and responses
@@ -231,6 +233,96 @@ declare class UpcrawlError extends Error {
     readonly code: string;
     constructor(message: string, status: number, code?: string);
 }
+interface CreateBrowserSessionOptions {
+    /** Browser viewport width (800-3840). Defaults to 1280 */
+    width?: number;
+    /** Browser viewport height (600-2160). Defaults to 720 */
+    height?: number;
+    /** Run browser in headless mode. Defaults to true */
+    headless?: boolean;
+}
+interface BrowserSession {
+    /** Unique session identifier */
+    sessionId: string;
+    /** WebSocket URL for connecting with Playwright/Puppeteer */
+    wsEndpoint: string;
+    /** VNC URL for viewing the browser (if available) */
+    vncUrl: string | null;
+    /** Affinity cookie for sticky session routing (format: SCRAPER_AFFINITY=xxx) - extracted from response headers */
+    affinityCookie?: string;
+    /** Session creation timestamp */
+    createdAt: Date;
+    /** Browser viewport width */
+    width: number;
+    /** Browser viewport height */
+    height: number;
+}
+
+/**
+ * Upcrawl Browser Namespace
+ * Manage browser sessions for remote control with Playwright/Puppeteer
+ *
+ * @example
+ * ```typescript
+ * import Upcrawl from '@upcrawl/sdk';
+ * import playwright from 'playwright-core';
+ *
+ * const upcrawl = new Upcrawl('uc-your-api-key');
+ *
+ * // Create a browser session
+ * const session = await upcrawl.browser.create({
+ *   width: 1280,
+ *   height: 720,
+ *   headless: true
+ * });
+ *
+ * // Connect with Playwright
+ * const browser = await playwright.connect(session.wsEndpoint);
+ * const page = await browser.newPage();
+ * await page.goto('https://example.com');
+ *
+ * // Close the session when done
+ * await upcrawl.browser.close(session.sessionId);
+ * ```
+ */
+
+declare class Browser {
+    private createClient;
+    constructor(createClient: () => AxiosInstance);
+    /**
+     * Create a new browser session for remote control
+     * @param options - Session options including viewport size and headless mode
+     * @returns Promise with session details including WebSocket URL
+     *
+     * @example
+     * ```typescript
+     * const session = await upcrawl.browser.create({
+     *   width: 1280,
+     *   height: 720,
+     *   headless: true
+     * });
+     *
+     * console.log(session.wsEndpoint); // WebSocket URL for Playwright
+     * console.log(session.vncUrl);     // VNC URL for viewing (if available)
+     * ```
+     */
+    create(options?: CreateBrowserSessionOptions): Promise<BrowserSession>;
+    /**
+     * Close a browser session
+     * @param sessionId - The session ID to close
+     * @returns Promise that resolves when session is closed
+     *
+     * @example
+     * ```typescript
+     * await upcrawl.browser.close(session.sessionId);
+     * ```
+     */
+    close(sessionId: string): Promise<void>;
+    /**
+     * Handle API errors and convert to UpcrawlError
+     */
+    private handleError;
+}
 
 /**
  * Upcrawl API Client
@@ -525,10 +617,27 @@ declare const Upcrawl: {
      * @returns Promise with execution response (stdout, stderr, exit code, memory usage)
      */
     readonly executeCode: typeof executeCode;
+    /**
+     * Browser session management
+     * Create and manage browser sessions for remote control with Playwright/Puppeteer
+     *
+     * @example
+     * ```typescript
+     * const session = await Upcrawl.browser.create({
+     *   width: 1280,
+     *   height: 720,
+     *   headless: true
+     * });
+     *
+     * const browser = await playwright.connect(session.wsEndpoint);
+     * await upcrawl.browser.close(session.sessionId);
+     * ```
+     */
+    readonly browser: Browser;
     /**
      * Error class for Upcrawl API errors
      */
     readonly UpcrawlError: typeof UpcrawlError;
 };
 
-export { type BatchScrapeOptions, type BatchScrapeResponse, type ExecuteCodeOptions, type ExecuteCodeResponse, type GeneratePdfFromUrlOptions, type GeneratePdfOptions, type PdfMargin, type PdfResponse, type ScrapeMetadata, type ScrapeOptions, type ScrapeResponse, type SearchOptions, type SearchResponse, type SearchResultItem, type SearchResultWeb, type SummaryQuery, type UpcrawlConfig, UpcrawlError, type UpcrawlErrorResponse, batchScrape, configure, Upcrawl as default, executeCode, generatePdf, generatePdfFromUrl, getConfig, resetConfig, scrape, search, setApiKey, setBaseUrl, setTimeout };
+export { type BatchScrapeOptions, type BatchScrapeResponse, Browser, type BrowserSession, type CreateBrowserSessionOptions, type ExecuteCodeOptions, type ExecuteCodeResponse, type GeneratePdfFromUrlOptions, type GeneratePdfOptions, type PdfMargin, type PdfResponse, type ScrapeMetadata, type ScrapeOptions, type ScrapeResponse, type SearchOptions, type SearchResponse, type SearchResultItem, type SearchResultWeb, type SummaryQuery, type UpcrawlConfig, UpcrawlError, type UpcrawlErrorResponse, batchScrape, configure, Upcrawl as default, executeCode, generatePdf, generatePdfFromUrl, getConfig, resetConfig, scrape, search, setApiKey, setBaseUrl, setTimeout };

package/dist/index.js

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  Browser: () => Browser,
   UpcrawlError: () => UpcrawlError,
   batchScrape: () => batchScrape,
   configure: () => configure,
@@ -57,6 +58,104 @@ var UpcrawlError = class extends Error {
   }
 };
 
+// src/browser.ts
+var Browser = class {
+  constructor(createClient2) {
+    this.createClient = createClient2;
+  }
+  /**
+   * Create a new browser session for remote control
+   * @param options - Session options including viewport size and headless mode
+   * @returns Promise with session details including WebSocket URL
+   *
+   * @example
+   * ```typescript
+   * const session = await upcrawl.browser.create({
+   *   width: 1280,
+   *   height: 720,
+   *   headless: true
+   * });
+   *
+   * console.log(session.wsEndpoint); // WebSocket URL for Playwright
+   * console.log(session.vncUrl);     // VNC URL for viewing (if available)
+   * ```
+   */
+  async create(options) {
+    try {
+      const client = this.createClient();
+      const response = await client.post("/browser/session", {
+        width: options?.width ?? 1280,
+        height: options?.height ?? 720,
+        headless: options?.headless ?? true
+      });
+      const setCookieHeaders = response.headers["set-cookie"] || [];
+      const affinityCookie = setCookieHeaders.map((c) => c.split(";")[0]).find((c) => c.startsWith("SCRAPER_AFFINITY="));
+      return {
+        sessionId: response.data.sessionId,
+        wsEndpoint: response.data.wsUrl,
+        vncUrl: response.data.vncUrl,
+        affinityCookie: affinityCookie || void 0,
+        createdAt: new Date(response.data.createdAt),
+        width: response.data.width,
+        height: response.data.height
+      };
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Close a browser session
+   * @param sessionId - The session ID to close
+   * @returns Promise that resolves when session is closed
+   *
+   * @example
+   * ```typescript
+   * await upcrawl.browser.close(session.sessionId);
+   * ```
+   */
+  async close(sessionId) {
+    try {
+      const client = this.createClient();
+      await client.delete(`/browser/session/${sessionId}`);
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Handle API errors and convert to UpcrawlError
+   */
+  handleError(error) {
+    if (error && typeof error === "object" && "response" in error) {
+      const axiosError = error;
+      const status = axiosError.response?.status || 500;
+      const data = axiosError.response?.data;
+      if (data?.error) {
+        throw new UpcrawlError(data.error.message || "Unknown error", status, data.error.code || "UNKNOWN_ERROR");
+      }
+      switch (status) {
+        case 401:
+          throw new UpcrawlError("Invalid or missing API key", 401, "UNAUTHORIZED");
+        case 404:
+          throw new UpcrawlError("Session not found", 404, "NOT_FOUND");
+        case 429:
+          throw new UpcrawlError("Rate limit exceeded", 429, "RATE_LIMIT_EXCEEDED");
+        case 503:
+          throw new UpcrawlError("No browser slots available", 503, "SERVICE_UNAVAILABLE");
+        default:
+          throw new UpcrawlError(axiosError.message || "An unknown error occurred", status, "UNKNOWN_ERROR");
+      }
+    }
+    if (error instanceof UpcrawlError) {
+      throw error;
+    }
+    throw new UpcrawlError(
+      error instanceof Error ? error.message : "An unknown error occurred",
+      500,
+      "UNKNOWN_ERROR"
+    );
+  }
+};
+
 // src/client.ts
 var import_axios = __toESM(require("axios"));
 var DEFAULT_BASE_URL = "https://api.upcrawl.dev/api/v1";
@@ -279,6 +378,23 @@ var Upcrawl = {
    * @returns Promise with execution response (stdout, stderr, exit code, memory usage)
    */
   executeCode,
+  /**
+   * Browser session management
+   * Create and manage browser sessions for remote control with Playwright/Puppeteer
+   *
+   * @example
+   * ```typescript
+   * const session = await Upcrawl.browser.create({
+   *   width: 1280,
+   *   height: 720,
+   *   headless: true
+   * });
+   *
+   * const browser = await playwright.connect(session.wsEndpoint);
+   * await upcrawl.browser.close(session.sessionId);
+   * ```
+   */
+  browser: new Browser(createClient),
   /**
    * Error class for Upcrawl API errors
    */
@@ -287,6 +403,7 @@ var Upcrawl = {
 var index_default = Upcrawl;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Browser,
   UpcrawlError,
   batchScrape,
   configure,

package/dist/index.mjs

@@ -8,6 +8,104 @@ var UpcrawlError = class extends Error {
   }
 };
 
+// src/browser.ts
+var Browser = class {
+  constructor(createClient2) {
+    this.createClient = createClient2;
+  }
+  /**
+   * Create a new browser session for remote control
+   * @param options - Session options including viewport size and headless mode
+   * @returns Promise with session details including WebSocket URL
+   *
+   * @example
+   * ```typescript
+   * const session = await upcrawl.browser.create({
+   *   width: 1280,
+   *   height: 720,
+   *   headless: true
+   * });
+   *
+   * console.log(session.wsEndpoint); // WebSocket URL for Playwright
+   * console.log(session.vncUrl);     // VNC URL for viewing (if available)
+   * ```
+   */
+  async create(options) {
+    try {
+      const client = this.createClient();
+      const response = await client.post("/browser/session", {
+        width: options?.width ?? 1280,
+        height: options?.height ?? 720,
+        headless: options?.headless ?? true
+      });
+      const setCookieHeaders = response.headers["set-cookie"] || [];
+      const affinityCookie = setCookieHeaders.map((c) => c.split(";")[0]).find((c) => c.startsWith("SCRAPER_AFFINITY="));
+      return {
+        sessionId: response.data.sessionId,
+        wsEndpoint: response.data.wsUrl,
+        vncUrl: response.data.vncUrl,
+        affinityCookie: affinityCookie || void 0,
+        createdAt: new Date(response.data.createdAt),
+        width: response.data.width,
+        height: response.data.height
+      };
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Close a browser session
+   * @param sessionId - The session ID to close
+   * @returns Promise that resolves when session is closed
+   *
+   * @example
+   * ```typescript
+   * await upcrawl.browser.close(session.sessionId);
+   * ```
+   */
+  async close(sessionId) {
+    try {
+      const client = this.createClient();
+      await client.delete(`/browser/session/${sessionId}`);
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Handle API errors and convert to UpcrawlError
+   */
+  handleError(error) {
+    if (error && typeof error === "object" && "response" in error) {
+      const axiosError = error;
+      const status = axiosError.response?.status || 500;
+      const data = axiosError.response?.data;
+      if (data?.error) {
+        throw new UpcrawlError(data.error.message || "Unknown error", status, data.error.code || "UNKNOWN_ERROR");
+      }
+      switch (status) {
+        case 401:
+          throw new UpcrawlError("Invalid or missing API key", 401, "UNAUTHORIZED");
+        case 404:
+          throw new UpcrawlError("Session not found", 404, "NOT_FOUND");
+        case 429:
+          throw new UpcrawlError("Rate limit exceeded", 429, "RATE_LIMIT_EXCEEDED");
+        case 503:
+          throw new UpcrawlError("No browser slots available", 503, "SERVICE_UNAVAILABLE");
+        default:
+          throw new UpcrawlError(axiosError.message || "An unknown error occurred", status, "UNKNOWN_ERROR");
+      }
+    }
+    if (error instanceof UpcrawlError) {
+      throw error;
+    }
+    throw new UpcrawlError(
+      error instanceof Error ? error.message : "An unknown error occurred",
+      500,
+      "UNKNOWN_ERROR"
+    );
+  }
+};
+
 // src/client.ts
 import axios from "axios";
 var DEFAULT_BASE_URL = "https://api.upcrawl.dev/api/v1";
@@ -230,6 +328,23 @@ var Upcrawl = {
    * @returns Promise with execution response (stdout, stderr, exit code, memory usage)
    */
   executeCode,
+  /**
+   * Browser session management
+   * Create and manage browser sessions for remote control with Playwright/Puppeteer
+   *
+   * @example
+   * ```typescript
+   * const session = await Upcrawl.browser.create({
+   *   width: 1280,
+   *   height: 720,
+   *   headless: true
+   * });
+   *
+   * const browser = await playwright.connect(session.wsEndpoint);
+   * await upcrawl.browser.close(session.sessionId);
+   * ```
+   */
+  browser: new Browser(createClient),
   /**
    * Error class for Upcrawl API errors
    */
@@ -237,6 +352,7 @@ var Upcrawl = {
 };
 var index_default = Upcrawl;
 export {
+  Browser,
   UpcrawlError,
   batchScrape,
   configure,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upcrawl/sdk",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -43,7 +43,8 @@
     "url": "https://github.com/upcrawl/upcrawl-js/issues"
   },
   "dependencies": {
-    "axios": "^1.6.0"
+    "axios": "^1.6.0",
+    "react-vnc": "^3.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",