@upcrawl/sdk 1.3.1 → 1.4.1

package/dist/index.js

@@ -30,7 +30,28 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BatchScrapeOptionsSchema: () => BatchScrapeOptionsSchema,
+  BatchScrapeResponseSchema: () => BatchScrapeResponseSchema,
+  Browser: () => Browser,
+  BrowserSessionSchema: () => BrowserSessionSchema,
+  CreateBrowserSessionOptionsSchema: () => CreateBrowserSessionOptionsSchema,
+  ExecuteCodeOptionsSchema: () => ExecuteCodeOptionsSchema,
+  ExecuteCodeResponseSchema: () => ExecuteCodeResponseSchema,
+  GeneratePdfFromUrlOptionsSchema: () => GeneratePdfFromUrlOptionsSchema,
+  GeneratePdfOptionsSchema: () => GeneratePdfOptionsSchema,
+  PdfMarginSchema: () => PdfMarginSchema,
+  PdfResponseSchema: () => PdfResponseSchema,
+  ScrapeMetadataSchema: () => ScrapeMetadataSchema,
+  ScrapeOptionsSchema: () => ScrapeOptionsSchema,
+  ScrapeResponseSchema: () => ScrapeResponseSchema,
+  SearchOptionsSchema: () => SearchOptionsSchema,
+  SearchResponseSchema: () => SearchResponseSchema,
+  SearchResultItemSchema: () => SearchResultItemSchema,
+  SearchResultWebSchema: () => SearchResultWebSchema,
+  SummaryQuerySchema: () => SummaryQuerySchema,
+  UpcrawlConfigSchema: () => UpcrawlConfigSchema,
   UpcrawlError: () => UpcrawlError,
+  UpcrawlErrorResponseSchema: () => UpcrawlErrorResponseSchema,
   batchScrape: () => batchScrape,
   configure: () => configure,
   default: () => index_default,
@@ -48,6 +69,146 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
+var import_zod = require("zod");
+var UpcrawlConfigSchema = import_zod.z.object({
+  apiKey: import_zod.z.string().optional().describe("Your Upcrawl API key"),
+  baseUrl: import_zod.z.string().optional().describe("Custom API base URL"),
+  timeout: import_zod.z.number().optional().describe("Request timeout in milliseconds")
+});
+var SummaryQuerySchema = import_zod.z.object({
+  query: import_zod.z.string().describe("Query/instruction for content summarization")
+});
+var ScrapeOptionsSchema = import_zod.z.object({
+  url: import_zod.z.string().url().describe("URL to scrape (required)"),
+  type: import_zod.z.enum(["html", "markdown"]).optional().describe('Output format: html or markdown. Defaults to "html"'),
+  onlyMainContent: import_zod.z.boolean().optional().describe("Extract only main content (removes nav, ads, footers). Defaults to true"),
+  extractMetadata: import_zod.z.boolean().optional().describe("Whether to extract page metadata"),
+  summary: SummaryQuerySchema.optional().describe("Summary query for LLM summarization"),
+  timeoutMs: import_zod.z.number().optional().describe("Custom timeout in milliseconds (1000-120000)"),
+  waitUntil: import_zod.z.enum(["load", "domcontentloaded", "networkidle"]).optional().describe("Wait strategy for page load")
+});
+var ScrapeMetadataSchema = import_zod.z.object({
+  title: import_zod.z.string().optional(),
+  description: import_zod.z.string().optional(),
+  canonicalUrl: import_zod.z.string().optional(),
+  finalUrl: import_zod.z.string().optional(),
+  contentType: import_zod.z.string().optional(),
+  contentLength: import_zod.z.number().optional()
+});
+var ScrapeResponseSchema = import_zod.z.object({
+  url: import_zod.z.string().describe("Original URL that was scraped"),
+  html: import_zod.z.string().nullable().optional().describe("Rendered HTML content (when type is html)"),
+  markdown: import_zod.z.string().nullable().optional().describe("Content converted to Markdown (when type is markdown)"),
+  statusCode: import_zod.z.number().nullable().describe("HTTP status code"),
+  success: import_zod.z.boolean().describe("Whether scraping was successful"),
+  error: import_zod.z.string().optional().describe("Error message if scraping failed"),
+  timestamp: import_zod.z.string().describe("ISO timestamp when scraping completed"),
+  loadTimeMs: import_zod.z.number().describe("Time taken to load and render the page in milliseconds"),
+  metadata: ScrapeMetadataSchema.optional().describe("Additional page metadata"),
+  retryCount: import_zod.z.number().describe("Number of retry attempts made"),
+  cost: import_zod.z.number().optional().describe("Cost in USD for this scrape operation"),
+  content: import_zod.z.string().nullable().optional().describe("Content after summarization (when summary query provided)")
+});
+var BatchScrapeOptionsSchema = import_zod.z.object({
+  urls: import_zod.z.array(import_zod.z.union([import_zod.z.string(), ScrapeOptionsSchema])).describe("Array of URLs to scrape (strings or detailed request objects)"),
+  type: import_zod.z.enum(["html", "markdown"]).optional().describe("Output format: html or markdown"),
+  onlyMainContent: import_zod.z.boolean().optional().describe("Extract only main content (removes nav, ads, footers)"),
+  summary: SummaryQuerySchema.optional().describe("Summary query for LLM summarization"),
+  batchTimeoutMs: import_zod.z.number().optional().describe("Global timeout for entire batch operation in milliseconds (10000-600000)"),
+  failFast: import_zod.z.boolean().optional().describe("Whether to stop on first error")
+});
+var BatchScrapeResponseSchema = import_zod.z.object({
+  results: import_zod.z.array(ScrapeResponseSchema).describe("Array of scrape results"),
+  total: import_zod.z.number().describe("Total number of URLs processed"),
+  successful: import_zod.z.number().describe("Number of successful scrapes"),
+  failed: import_zod.z.number().describe("Number of failed scrapes"),
+  totalTimeMs: import_zod.z.number().describe("Total time taken for batch operation in milliseconds"),
+  timestamp: import_zod.z.string().describe("Timestamp when batch operation completed"),
+  cost: import_zod.z.number().optional().describe("Total cost in USD for all scrape operations")
+});
+var SearchOptionsSchema = import_zod.z.object({
+  queries: import_zod.z.array(import_zod.z.string()).describe("Array of search queries to execute (1-20)"),
+  limit: import_zod.z.number().optional().describe("Number of results per query (1-100). Defaults to 10"),
+  location: import_zod.z.string().optional().describe('Location for search (e.g., "IN", "US")'),
+  includeDomains: import_zod.z.array(import_zod.z.string()).optional().describe("Domains to include (will add site: to query)"),
+  excludeDomains: import_zod.z.array(import_zod.z.string()).optional().describe("Domains to exclude (will add -site: to query)")
+});
+var SearchResultWebSchema = import_zod.z.object({
+  url: import_zod.z.string().describe("URL of the search result"),
+  title: import_zod.z.string().describe("Title of the search result"),
+  description: import_zod.z.string().describe("Description/snippet of the search result")
+});
+var SearchResultItemSchema = import_zod.z.object({
+  query: import_zod.z.string().describe("The search query"),
+  success: import_zod.z.boolean().describe("Whether the search was successful"),
+  results: import_zod.z.array(SearchResultWebSchema).describe("Parsed search result links"),
+  error: import_zod.z.string().optional().describe("Error message if failed"),
+  loadTimeMs: import_zod.z.number().optional().describe("Time taken in milliseconds"),
+  cost: import_zod.z.number().optional().describe("Cost in USD for this query")
+});
+var SearchResponseSchema = import_zod.z.object({
+  results: import_zod.z.array(SearchResultItemSchema).describe("Array of search results per query"),
+  total: import_zod.z.number().describe("Total number of queries"),
+  successful: import_zod.z.number().describe("Number of successful searches"),
+  failed: import_zod.z.number().describe("Number of failed searches"),
+  totalTimeMs: import_zod.z.number().describe("Total time in milliseconds"),
+  timestamp: import_zod.z.string().describe("ISO timestamp"),
+  cost: import_zod.z.number().optional().describe("Total cost in USD")
+});
+var PdfMarginSchema = import_zod.z.object({
+  top: import_zod.z.string().optional(),
+  right: import_zod.z.string().optional(),
+  bottom: import_zod.z.string().optional(),
+  left: import_zod.z.string().optional()
+});
+var GeneratePdfOptionsSchema = import_zod.z.object({
+  html: import_zod.z.string().describe("Complete HTML content to convert to PDF (required)"),
+  title: import_zod.z.string().optional().describe("Title used for the exported filename"),
+  pageSize: import_zod.z.enum(["A4", "Letter", "Legal"]).optional().describe('Page size. Defaults to "A4"'),
+  landscape: import_zod.z.boolean().optional().describe("Landscape orientation. Defaults to false"),
+  margin: PdfMarginSchema.optional().describe('Page margins (e.g., { top: "20mm", right: "20mm", bottom: "20mm", left: "20mm" })'),
+  printBackground: import_zod.z.boolean().optional().describe("Print background graphics and colors. Defaults to true"),
+  skipChartWait: import_zod.z.boolean().optional().describe("Skip waiting for chart rendering signal. Defaults to false"),
+  timeoutMs: import_zod.z.number().optional().describe("Timeout in milliseconds (5000-120000). Defaults to 30000")
+});
+var GeneratePdfFromUrlOptionsSchema = import_zod.z.object({
+  url: import_zod.z.string().url().describe("URL to navigate to and convert to PDF (required)"),
+  title: import_zod.z.string().optional().describe("Title used for the exported filename"),
+  pageSize: import_zod.z.enum(["A4", "Letter", "Legal"]).optional().describe('Page size. Defaults to "A4"'),
+  landscape: import_zod.z.boolean().optional().describe("Landscape orientation. Defaults to false"),
+  margin: PdfMarginSchema.optional().describe("Page margins"),
+  printBackground: import_zod.z.boolean().optional().describe("Print background graphics and colors. Defaults to true"),
+  timeoutMs: import_zod.z.number().optional().describe("Timeout in milliseconds (5000-120000). Defaults to 30000")
+});
+var PdfResponseSchema = import_zod.z.object({
+  success: import_zod.z.boolean().describe("Whether PDF generation succeeded"),
+  url: import_zod.z.string().optional().describe("Public URL of the generated PDF"),
+  filename: import_zod.z.string().optional().describe("Generated filename"),
+  blobName: import_zod.z.string().optional().describe("Blob storage path"),
+  error: import_zod.z.string().optional().describe("Error message on failure"),
+  durationMs: import_zod.z.number().describe("Total time taken in milliseconds")
+});
+var ExecuteCodeOptionsSchema = import_zod.z.object({
+  code: import_zod.z.string().describe("Code to execute (required)"),
+  language: import_zod.z.enum(["python"]).optional().describe('Language runtime. Defaults to "python"')
+});
+var ExecuteCodeResponseSchema = import_zod.z.object({
+  stdout: import_zod.z.string().describe("Standard output from the executed code"),
+  stderr: import_zod.z.string().describe("Standard error from the executed code"),
+  exitCode: import_zod.z.number().describe("Process exit code (0 = success, 124 = timeout)"),
+  executionTimeMs: import_zod.z.number().describe("Execution time in milliseconds"),
+  timedOut: import_zod.z.boolean().describe("Whether execution was killed due to timeout"),
+  memoryUsageMb: import_zod.z.number().optional().describe("Peak memory usage in megabytes"),
+  error: import_zod.z.string().optional().describe("Error message if execution infrastructure failed"),
+  cost: import_zod.z.number().optional().describe("Cost in USD for this execution")
+});
+var UpcrawlErrorResponseSchema = import_zod.z.object({
+  error: import_zod.z.object({
+    code: import_zod.z.string(),
+    message: import_zod.z.string()
+  }),
+  statusCode: import_zod.z.number().optional()
+});
 var UpcrawlError = class extends Error {
   constructor(message, status, code = "UNKNOWN_ERROR") {
     super(message);
@@ -56,6 +217,118 @@ var UpcrawlError = class extends Error {
     this.code = code;
   }
 };
+var CreateBrowserSessionOptionsSchema = import_zod.z.object({
+  width: import_zod.z.number().optional().describe("Browser viewport width (800-3840). Defaults to 1280"),
+  height: import_zod.z.number().optional().describe("Browser viewport height (600-2160). Defaults to 720"),
+  headless: import_zod.z.boolean().optional().describe("Run browser in headless mode. Defaults to true")
+});
+var BrowserSessionSchema = import_zod.z.object({
+  sessionId: import_zod.z.string().describe("Unique session identifier"),
+  wsEndpoint: import_zod.z.string().describe("WebSocket URL for connecting with Playwright/Puppeteer"),
+  vncUrl: import_zod.z.string().nullable().describe("VNC URL for viewing the browser (if available)"),
+  affinityCookie: import_zod.z.string().optional().describe("Affinity cookie for sticky session routing (format: SCRAPER_AFFINITY=xxx) - extracted from response headers"),
+  createdAt: import_zod.z.date().describe("Session creation timestamp"),
+  width: import_zod.z.number().describe("Browser viewport width"),
+  height: import_zod.z.number().describe("Browser viewport height")
+});
+
+// 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"));
@@ -279,6 +552,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,7 +577,28 @@ var Upcrawl = {
 var index_default = Upcrawl;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BatchScrapeOptionsSchema,
+  BatchScrapeResponseSchema,
+  Browser,
+  BrowserSessionSchema,
+  CreateBrowserSessionOptionsSchema,
+  ExecuteCodeOptionsSchema,
+  ExecuteCodeResponseSchema,
+  GeneratePdfFromUrlOptionsSchema,
+  GeneratePdfOptionsSchema,
+  PdfMarginSchema,
+  PdfResponseSchema,
+  ScrapeMetadataSchema,
+  ScrapeOptionsSchema,
+  ScrapeResponseSchema,
+  SearchOptionsSchema,
+  SearchResponseSchema,
+  SearchResultItemSchema,
+  SearchResultWebSchema,
+  SummaryQuerySchema,
+  UpcrawlConfigSchema,
   UpcrawlError,
+  UpcrawlErrorResponseSchema,
   batchScrape,
   configure,
   executeCode,

package/dist/index.mjs

@@ -1,4 +1,144 @@
 // src/types.ts
+import { z } from "zod";
+var UpcrawlConfigSchema = z.object({
+  apiKey: z.string().optional().describe("Your Upcrawl API key"),
+  baseUrl: z.string().optional().describe("Custom API base URL"),
+  timeout: z.number().optional().describe("Request timeout in milliseconds")
+});
+var SummaryQuerySchema = z.object({
+  query: z.string().describe("Query/instruction for content summarization")
+});
+var ScrapeOptionsSchema = z.object({
+  url: z.string().url().describe("URL to scrape (required)"),
+  type: z.enum(["html", "markdown"]).optional().describe('Output format: html or markdown. Defaults to "html"'),
+  onlyMainContent: z.boolean().optional().describe("Extract only main content (removes nav, ads, footers). Defaults to true"),
+  extractMetadata: z.boolean().optional().describe("Whether to extract page metadata"),
+  summary: SummaryQuerySchema.optional().describe("Summary query for LLM summarization"),
+  timeoutMs: z.number().optional().describe("Custom timeout in milliseconds (1000-120000)"),
+  waitUntil: z.enum(["load", "domcontentloaded", "networkidle"]).optional().describe("Wait strategy for page load")
+});
+var ScrapeMetadataSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  canonicalUrl: z.string().optional(),
+  finalUrl: z.string().optional(),
+  contentType: z.string().optional(),
+  contentLength: z.number().optional()
+});
+var ScrapeResponseSchema = z.object({
+  url: z.string().describe("Original URL that was scraped"),
+  html: z.string().nullable().optional().describe("Rendered HTML content (when type is html)"),
+  markdown: z.string().nullable().optional().describe("Content converted to Markdown (when type is markdown)"),
+  statusCode: z.number().nullable().describe("HTTP status code"),
+  success: z.boolean().describe("Whether scraping was successful"),
+  error: z.string().optional().describe("Error message if scraping failed"),
+  timestamp: z.string().describe("ISO timestamp when scraping completed"),
+  loadTimeMs: z.number().describe("Time taken to load and render the page in milliseconds"),
+  metadata: ScrapeMetadataSchema.optional().describe("Additional page metadata"),
+  retryCount: z.number().describe("Number of retry attempts made"),
+  cost: z.number().optional().describe("Cost in USD for this scrape operation"),
+  content: z.string().nullable().optional().describe("Content after summarization (when summary query provided)")
+});
+var BatchScrapeOptionsSchema = z.object({
+  urls: z.array(z.union([z.string(), ScrapeOptionsSchema])).describe("Array of URLs to scrape (strings or detailed request objects)"),
+  type: z.enum(["html", "markdown"]).optional().describe("Output format: html or markdown"),
+  onlyMainContent: z.boolean().optional().describe("Extract only main content (removes nav, ads, footers)"),
+  summary: SummaryQuerySchema.optional().describe("Summary query for LLM summarization"),
+  batchTimeoutMs: z.number().optional().describe("Global timeout for entire batch operation in milliseconds (10000-600000)"),
+  failFast: z.boolean().optional().describe("Whether to stop on first error")
+});
+var BatchScrapeResponseSchema = z.object({
+  results: z.array(ScrapeResponseSchema).describe("Array of scrape results"),
+  total: z.number().describe("Total number of URLs processed"),
+  successful: z.number().describe("Number of successful scrapes"),
+  failed: z.number().describe("Number of failed scrapes"),
+  totalTimeMs: z.number().describe("Total time taken for batch operation in milliseconds"),
+  timestamp: z.string().describe("Timestamp when batch operation completed"),
+  cost: z.number().optional().describe("Total cost in USD for all scrape operations")
+});
+var SearchOptionsSchema = z.object({
+  queries: z.array(z.string()).describe("Array of search queries to execute (1-20)"),
+  limit: z.number().optional().describe("Number of results per query (1-100). Defaults to 10"),
+  location: z.string().optional().describe('Location for search (e.g., "IN", "US")'),
+  includeDomains: z.array(z.string()).optional().describe("Domains to include (will add site: to query)"),
+  excludeDomains: z.array(z.string()).optional().describe("Domains to exclude (will add -site: to query)")
+});
+var SearchResultWebSchema = z.object({
+  url: z.string().describe("URL of the search result"),
+  title: z.string().describe("Title of the search result"),
+  description: z.string().describe("Description/snippet of the search result")
+});
+var SearchResultItemSchema = z.object({
+  query: z.string().describe("The search query"),
+  success: z.boolean().describe("Whether the search was successful"),
+  results: z.array(SearchResultWebSchema).describe("Parsed search result links"),
+  error: z.string().optional().describe("Error message if failed"),
+  loadTimeMs: z.number().optional().describe("Time taken in milliseconds"),
+  cost: z.number().optional().describe("Cost in USD for this query")
+});
+var SearchResponseSchema = z.object({
+  results: z.array(SearchResultItemSchema).describe("Array of search results per query"),
+  total: z.number().describe("Total number of queries"),
+  successful: z.number().describe("Number of successful searches"),
+  failed: z.number().describe("Number of failed searches"),
+  totalTimeMs: z.number().describe("Total time in milliseconds"),
+  timestamp: z.string().describe("ISO timestamp"),
+  cost: z.number().optional().describe("Total cost in USD")
+});
+var PdfMarginSchema = z.object({
+  top: z.string().optional(),
+  right: z.string().optional(),
+  bottom: z.string().optional(),
+  left: z.string().optional()
+});
+var GeneratePdfOptionsSchema = z.object({
+  html: z.string().describe("Complete HTML content to convert to PDF (required)"),
+  title: z.string().optional().describe("Title used for the exported filename"),
+  pageSize: z.enum(["A4", "Letter", "Legal"]).optional().describe('Page size. Defaults to "A4"'),
+  landscape: z.boolean().optional().describe("Landscape orientation. Defaults to false"),
+  margin: PdfMarginSchema.optional().describe('Page margins (e.g., { top: "20mm", right: "20mm", bottom: "20mm", left: "20mm" })'),
+  printBackground: z.boolean().optional().describe("Print background graphics and colors. Defaults to true"),
+  skipChartWait: z.boolean().optional().describe("Skip waiting for chart rendering signal. Defaults to false"),
+  timeoutMs: z.number().optional().describe("Timeout in milliseconds (5000-120000). Defaults to 30000")
+});
+var GeneratePdfFromUrlOptionsSchema = z.object({
+  url: z.string().url().describe("URL to navigate to and convert to PDF (required)"),
+  title: z.string().optional().describe("Title used for the exported filename"),
+  pageSize: z.enum(["A4", "Letter", "Legal"]).optional().describe('Page size. Defaults to "A4"'),
+  landscape: z.boolean().optional().describe("Landscape orientation. Defaults to false"),
+  margin: PdfMarginSchema.optional().describe("Page margins"),
+  printBackground: z.boolean().optional().describe("Print background graphics and colors. Defaults to true"),
+  timeoutMs: z.number().optional().describe("Timeout in milliseconds (5000-120000). Defaults to 30000")
+});
+var PdfResponseSchema = z.object({
+  success: z.boolean().describe("Whether PDF generation succeeded"),
+  url: z.string().optional().describe("Public URL of the generated PDF"),
+  filename: z.string().optional().describe("Generated filename"),
+  blobName: z.string().optional().describe("Blob storage path"),
+  error: z.string().optional().describe("Error message on failure"),
+  durationMs: z.number().describe("Total time taken in milliseconds")
+});
+var ExecuteCodeOptionsSchema = z.object({
+  code: z.string().describe("Code to execute (required)"),
+  language: z.enum(["python"]).optional().describe('Language runtime. Defaults to "python"')
+});
+var ExecuteCodeResponseSchema = z.object({
+  stdout: z.string().describe("Standard output from the executed code"),
+  stderr: z.string().describe("Standard error from the executed code"),
+  exitCode: z.number().describe("Process exit code (0 = success, 124 = timeout)"),
+  executionTimeMs: z.number().describe("Execution time in milliseconds"),
+  timedOut: z.boolean().describe("Whether execution was killed due to timeout"),
+  memoryUsageMb: z.number().optional().describe("Peak memory usage in megabytes"),
+  error: z.string().optional().describe("Error message if execution infrastructure failed"),
+  cost: z.number().optional().describe("Cost in USD for this execution")
+});
+var UpcrawlErrorResponseSchema = z.object({
+  error: z.object({
+    code: z.string(),
+    message: z.string()
+  }),
+  statusCode: z.number().optional()
+});
 var UpcrawlError = class extends Error {
   constructor(message, status, code = "UNKNOWN_ERROR") {
     super(message);
@@ -7,6 +147,118 @@ var UpcrawlError = class extends Error {
     this.code = code;
   }
 };
+var CreateBrowserSessionOptionsSchema = z.object({
+  width: z.number().optional().describe("Browser viewport width (800-3840). Defaults to 1280"),
+  height: z.number().optional().describe("Browser viewport height (600-2160). Defaults to 720"),
+  headless: z.boolean().optional().describe("Run browser in headless mode. Defaults to true")
+});
+var BrowserSessionSchema = z.object({
+  sessionId: z.string().describe("Unique session identifier"),
+  wsEndpoint: z.string().describe("WebSocket URL for connecting with Playwright/Puppeteer"),
+  vncUrl: z.string().nullable().describe("VNC URL for viewing the browser (if available)"),
+  affinityCookie: z.string().optional().describe("Affinity cookie for sticky session routing (format: SCRAPER_AFFINITY=xxx) - extracted from response headers"),
+  createdAt: z.date().describe("Session creation timestamp"),
+  width: z.number().describe("Browser viewport width"),
+  height: z.number().describe("Browser viewport height")
+});
+
+// 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";
@@ -230,6 +482,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,7 +506,28 @@ var Upcrawl = {
 };
 var index_default = Upcrawl;
 export {
+  BatchScrapeOptionsSchema,
+  BatchScrapeResponseSchema,
+  Browser,
+  BrowserSessionSchema,
+  CreateBrowserSessionOptionsSchema,
+  ExecuteCodeOptionsSchema,
+  ExecuteCodeResponseSchema,
+  GeneratePdfFromUrlOptionsSchema,
+  GeneratePdfOptionsSchema,
+  PdfMarginSchema,
+  PdfResponseSchema,
+  ScrapeMetadataSchema,
+  ScrapeOptionsSchema,
+  ScrapeResponseSchema,
+  SearchOptionsSchema,
+  SearchResponseSchema,
+  SearchResultItemSchema,
+  SearchResultWebSchema,
+  SummaryQuerySchema,
+  UpcrawlConfigSchema,
   UpcrawlError,
+  UpcrawlErrorResponseSchema,
   batchScrape,
   configure,
   index_default as default,