@upcrawl/sdk 1.4.0 → 1.4.1

package/dist/index.d.ts

@@ -1,262 +1,283 @@
+import { z } from 'zod';
 import { AxiosInstance } from 'axios';
 
 /**
  * Upcrawl SDK Types
  * Type definitions for all API requests and responses
+ * Powered by Zod schemas — single source of truth for types, validation, and docs
  */
-interface UpcrawlConfig {
-    apiKey?: string;
-    baseUrl?: string;
-    timeout?: number;
-}
-interface SummaryQuery {
-    /** Query/instruction for content summarization */
-    query: string;
-}
-interface ScrapeOptions {
-    /** URL to scrape (required) */
-    url: string;
-    /** Output format: html or markdown. Defaults to "html" */
-    type?: 'html' | 'markdown';
-    /** Extract only main content (removes nav, ads, footers). Defaults to true */
-    onlyMainContent?: boolean;
-    /** Whether to extract page metadata */
-    extractMetadata?: boolean;
-    /** Summary query for LLM summarization */
-    summary?: SummaryQuery;
-    /** Custom timeout in milliseconds (1000-120000) */
-    timeoutMs?: number;
-    /** Wait strategy for page load */
-    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
-}
-interface ScrapeMetadata {
-    title?: string;
-    description?: string;
-    canonicalUrl?: string;
-    finalUrl?: string;
-    contentType?: string;
-    contentLength?: number;
-}
-interface ScrapeResponse {
-    /** Original URL that was scraped */
-    url: string;
-    /** Rendered HTML content (when type is html) */
-    html?: string | null;
-    /** Content converted to Markdown (when type is markdown) */
-    markdown?: string | null;
-    /** HTTP status code */
-    statusCode: number | null;
-    /** Whether scraping was successful */
-    success: boolean;
-    /** Error message if scraping failed */
-    error?: string;
-    /** ISO timestamp when scraping completed */
-    timestamp: string;
-    /** Time taken to load and render the page in milliseconds */
-    loadTimeMs: number;
-    /** Additional page metadata */
-    metadata?: ScrapeMetadata;
-    /** Number of retry attempts made */
-    retryCount: number;
-    /** Cost in USD for this scrape operation */
-    cost?: number;
-    /** Content after summarization (when summary query provided) */
-    content?: string | null;
-}
-interface BatchScrapeOptions {
-    /** Array of URLs to scrape (strings or detailed request objects) */
-    urls: (string | ScrapeOptions)[];
-    /** Output format: html or markdown */
-    type?: 'html' | 'markdown';
-    /** Extract only main content (removes nav, ads, footers) */
-    onlyMainContent?: boolean;
-    /** Summary query for LLM summarization */
-    summary?: SummaryQuery;
-    /** Global timeout for entire batch operation in milliseconds (10000-600000) */
-    batchTimeoutMs?: number;
-    /** Whether to stop on first error */
-    failFast?: boolean;
-}
-interface BatchScrapeResponse {
-    /** Array of scrape results */
-    results: ScrapeResponse[];
-    /** Total number of URLs processed */
-    total: number;
-    /** Number of successful scrapes */
-    successful: number;
-    /** Number of failed scrapes */
-    failed: number;
-    /** Total time taken for batch operation in milliseconds */
-    totalTimeMs: number;
-    /** Timestamp when batch operation completed */
-    timestamp: string;
-    /** Total cost in USD for all scrape operations */
-    cost?: number;
-}
-interface SearchOptions {
-    /** Array of search queries to execute (1-20) */
-    queries: string[];
-    /** Number of results per query (1-100). Defaults to 10 */
-    limit?: number;
-    /** Location for search (e.g., "IN", "US") */
-    location?: string;
-    /** Domains to include (will add site: to query) */
-    includeDomains?: string[];
-    /** Domains to exclude (will add -site: to query) */
-    excludeDomains?: string[];
-}
-interface SearchResultWeb {
-    /** URL of the search result */
-    url: string;
-    /** Title of the search result */
-    title: string;
-    /** Description/snippet of the search result */
-    description: string;
-}
-interface SearchResultItem {
-    /** The search query */
-    query: string;
-    /** Whether the search was successful */
-    success: boolean;
-    /** Parsed search result links */
-    results: SearchResultWeb[];
-    /** Error message if failed */
-    error?: string;
-    /** Time taken in milliseconds */
-    loadTimeMs?: number;
-    /** Cost in USD for this query */
-    cost?: number;
-}
-interface SearchResponse {
-    /** Array of search results per query */
-    results: SearchResultItem[];
-    /** Total number of queries */
-    total: number;
-    /** Number of successful searches */
-    successful: number;
-    /** Number of failed searches */
-    failed: number;
-    /** Total time in milliseconds */
-    totalTimeMs: number;
-    /** ISO timestamp */
-    timestamp: string;
-    /** Total cost in USD */
-    cost?: number;
-}
-interface PdfMargin {
-    top?: string;
-    right?: string;
-    bottom?: string;
-    left?: string;
-}
-interface GeneratePdfOptions {
-    /** Complete HTML content to convert to PDF (required) */
-    html: string;
-    /** Title used for the exported filename */
-    title?: string;
-    /** Page size. Defaults to "A4" */
-    pageSize?: 'A4' | 'Letter' | 'Legal';
-    /** Landscape orientation. Defaults to false */
-    landscape?: boolean;
-    /** Page margins (e.g., { top: '20mm', right: '20mm', bottom: '20mm', left: '20mm' }) */
-    margin?: PdfMargin;
-    /** Print background graphics and colors. Defaults to true */
-    printBackground?: boolean;
-    /** Skip waiting for chart rendering signal. Defaults to false */
-    skipChartWait?: boolean;
-    /** Timeout in milliseconds (5000-120000). Defaults to 30000 */
-    timeoutMs?: number;
-}
-interface GeneratePdfFromUrlOptions {
-    /** URL to navigate to and convert to PDF (required) */
-    url: string;
-    /** Title used for the exported filename */
-    title?: string;
-    /** Page size. Defaults to "A4" */
-    pageSize?: 'A4' | 'Letter' | 'Legal';
-    /** Landscape orientation. Defaults to false */
-    landscape?: boolean;
-    /** Page margins */
-    margin?: PdfMargin;
-    /** Print background graphics and colors. Defaults to true */
-    printBackground?: boolean;
-    /** Timeout in milliseconds (5000-120000). Defaults to 30000 */
-    timeoutMs?: number;
-}
-interface PdfResponse {
-    /** Whether PDF generation succeeded */
-    success: boolean;
-    /** Public URL of the generated PDF */
-    url?: string;
-    /** Generated filename */
-    filename?: string;
-    /** Blob storage path */
-    blobName?: string;
-    /** Error message on failure */
-    error?: string;
-    /** Total time taken in milliseconds */
-    durationMs: number;
-}
-interface ExecuteCodeOptions {
-    /** Code to execute (required) */
-    code: string;
-    /** Language runtime. Defaults to "python" */
-    language?: 'python';
-}
-interface ExecuteCodeResponse {
-    /** Standard output from the executed code */
-    stdout: string;
-    /** Standard error from the executed code */
-    stderr: string;
-    /** Process exit code (0 = success, 124 = timeout) */
-    exitCode: number;
-    /** Execution time in milliseconds */
-    executionTimeMs: number;
-    /** Whether execution was killed due to timeout */
-    timedOut: boolean;
-    /** Peak memory usage in megabytes */
-    memoryUsageMb?: number;
-    /** Error message if execution infrastructure failed */
-    error?: string;
-    /** Cost in USD for this execution */
-    cost?: number;
-}
-interface UpcrawlErrorResponse {
-    error: {
-        code: string;
-        message: string;
-    };
-    statusCode?: number;
-}
+
+declare const UpcrawlConfigSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type UpcrawlConfig = z.infer<typeof UpcrawlConfigSchema>;
+declare const SummaryQuerySchema: z.ZodObject<{
+    query: z.ZodString;
+}, z.core.$strip>;
+type SummaryQuery = z.infer<typeof SummaryQuerySchema>;
+declare const ScrapeOptionsSchema: z.ZodObject<{
+    url: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        html: "html";
+        markdown: "markdown";
+    }>>;
+    onlyMainContent: z.ZodOptional<z.ZodBoolean>;
+    extractMetadata: z.ZodOptional<z.ZodBoolean>;
+    summary: z.ZodOptional<z.ZodObject<{
+        query: z.ZodString;
+    }, z.core.$strip>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    waitUntil: z.ZodOptional<z.ZodEnum<{
+        load: "load";
+        domcontentloaded: "domcontentloaded";
+        networkidle: "networkidle";
+    }>>;
+}, z.core.$strip>;
+type ScrapeOptions = z.infer<typeof ScrapeOptionsSchema>;
+declare const ScrapeMetadataSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    canonicalUrl: z.ZodOptional<z.ZodString>;
+    finalUrl: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodOptional<z.ZodString>;
+    contentLength: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type ScrapeMetadata = z.infer<typeof ScrapeMetadataSchema>;
+declare const ScrapeResponseSchema: z.ZodObject<{
+    url: z.ZodString;
+    html: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    markdown: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    statusCode: z.ZodNullable<z.ZodNumber>;
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodString>;
+    timestamp: z.ZodString;
+    loadTimeMs: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        canonicalUrl: z.ZodOptional<z.ZodString>;
+        finalUrl: z.ZodOptional<z.ZodString>;
+        contentType: z.ZodOptional<z.ZodString>;
+        contentLength: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    retryCount: z.ZodNumber;
+    cost: z.ZodOptional<z.ZodNumber>;
+    content: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+type ScrapeResponse = z.infer<typeof ScrapeResponseSchema>;
+declare const BatchScrapeOptionsSchema: z.ZodObject<{
+    urls: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        url: z.ZodString;
+        type: z.ZodOptional<z.ZodEnum<{
+            html: "html";
+            markdown: "markdown";
+        }>>;
+        onlyMainContent: z.ZodOptional<z.ZodBoolean>;
+        extractMetadata: z.ZodOptional<z.ZodBoolean>;
+        summary: z.ZodOptional<z.ZodObject<{
+            query: z.ZodString;
+        }, z.core.$strip>>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        waitUntil: z.ZodOptional<z.ZodEnum<{
+            load: "load";
+            domcontentloaded: "domcontentloaded";
+            networkidle: "networkidle";
+        }>>;
+    }, z.core.$strip>]>>;
+    type: z.ZodOptional<z.ZodEnum<{
+        html: "html";
+        markdown: "markdown";
+    }>>;
+    onlyMainContent: z.ZodOptional<z.ZodBoolean>;
+    summary: z.ZodOptional<z.ZodObject<{
+        query: z.ZodString;
+    }, z.core.$strip>>;
+    batchTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    failFast: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type BatchScrapeOptions = z.infer<typeof BatchScrapeOptionsSchema>;
+declare const BatchScrapeResponseSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        html: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        markdown: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        statusCode: z.ZodNullable<z.ZodNumber>;
+        success: z.ZodBoolean;
+        error: z.ZodOptional<z.ZodString>;
+        timestamp: z.ZodString;
+        loadTimeMs: z.ZodNumber;
+        metadata: z.ZodOptional<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            canonicalUrl: z.ZodOptional<z.ZodString>;
+            finalUrl: z.ZodOptional<z.ZodString>;
+            contentType: z.ZodOptional<z.ZodString>;
+            contentLength: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        retryCount: z.ZodNumber;
+        cost: z.ZodOptional<z.ZodNumber>;
+        content: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    successful: z.ZodNumber;
+    failed: z.ZodNumber;
+    totalTimeMs: z.ZodNumber;
+    timestamp: z.ZodString;
+    cost: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type BatchScrapeResponse = z.infer<typeof BatchScrapeResponseSchema>;
+declare const SearchOptionsSchema: z.ZodObject<{
+    queries: z.ZodArray<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    location: z.ZodOptional<z.ZodString>;
+    includeDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    excludeDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type SearchOptions = z.infer<typeof SearchOptionsSchema>;
+declare const SearchResultWebSchema: z.ZodObject<{
+    url: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strip>;
+type SearchResultWeb = z.infer<typeof SearchResultWebSchema>;
+declare const SearchResultItemSchema: z.ZodObject<{
+    query: z.ZodString;
+    success: z.ZodBoolean;
+    results: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodString>;
+    loadTimeMs: z.ZodOptional<z.ZodNumber>;
+    cost: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type SearchResultItem = z.infer<typeof SearchResultItemSchema>;
+declare const SearchResponseSchema: z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        query: z.ZodString;
+        success: z.ZodBoolean;
+        results: z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            title: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>;
+        error: z.ZodOptional<z.ZodString>;
+        loadTimeMs: z.ZodOptional<z.ZodNumber>;
+        cost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    successful: z.ZodNumber;
+    failed: z.ZodNumber;
+    totalTimeMs: z.ZodNumber;
+    timestamp: z.ZodString;
+    cost: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type SearchResponse = z.infer<typeof SearchResponseSchema>;
+declare const PdfMarginSchema: z.ZodObject<{
+    top: z.ZodOptional<z.ZodString>;
+    right: z.ZodOptional<z.ZodString>;
+    bottom: z.ZodOptional<z.ZodString>;
+    left: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type PdfMargin = z.infer<typeof PdfMarginSchema>;
+declare const GeneratePdfOptionsSchema: z.ZodObject<{
+    html: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    pageSize: z.ZodOptional<z.ZodEnum<{
+        A4: "A4";
+        Letter: "Letter";
+        Legal: "Legal";
+    }>>;
+    landscape: z.ZodOptional<z.ZodBoolean>;
+    margin: z.ZodOptional<z.ZodObject<{
+        top: z.ZodOptional<z.ZodString>;
+        right: z.ZodOptional<z.ZodString>;
+        bottom: z.ZodOptional<z.ZodString>;
+        left: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    printBackground: z.ZodOptional<z.ZodBoolean>;
+    skipChartWait: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type GeneratePdfOptions = z.infer<typeof GeneratePdfOptionsSchema>;
+declare const GeneratePdfFromUrlOptionsSchema: z.ZodObject<{
+    url: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    pageSize: z.ZodOptional<z.ZodEnum<{
+        A4: "A4";
+        Letter: "Letter";
+        Legal: "Legal";
+    }>>;
+    landscape: z.ZodOptional<z.ZodBoolean>;
+    margin: z.ZodOptional<z.ZodObject<{
+        top: z.ZodOptional<z.ZodString>;
+        right: z.ZodOptional<z.ZodString>;
+        bottom: z.ZodOptional<z.ZodString>;
+        left: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    printBackground: z.ZodOptional<z.ZodBoolean>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type GeneratePdfFromUrlOptions = z.infer<typeof GeneratePdfFromUrlOptionsSchema>;
+declare const PdfResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    url: z.ZodOptional<z.ZodString>;
+    filename: z.ZodOptional<z.ZodString>;
+    blobName: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodNumber;
+}, z.core.$strip>;
+type PdfResponse = z.infer<typeof PdfResponseSchema>;
+declare const ExecuteCodeOptionsSchema: z.ZodObject<{
+    code: z.ZodString;
+    language: z.ZodOptional<z.ZodEnum<{
+        python: "python";
+    }>>;
+}, z.core.$strip>;
+type ExecuteCodeOptions = z.infer<typeof ExecuteCodeOptionsSchema>;
+declare const ExecuteCodeResponseSchema: z.ZodObject<{
+    stdout: z.ZodString;
+    stderr: z.ZodString;
+    exitCode: z.ZodNumber;
+    executionTimeMs: z.ZodNumber;
+    timedOut: z.ZodBoolean;
+    memoryUsageMb: z.ZodOptional<z.ZodNumber>;
+    error: z.ZodOptional<z.ZodString>;
+    cost: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type ExecuteCodeResponse = z.infer<typeof ExecuteCodeResponseSchema>;
+declare const UpcrawlErrorResponseSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+    statusCode: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type UpcrawlErrorResponse = z.infer<typeof UpcrawlErrorResponseSchema>;
 declare class UpcrawlError extends Error {
     readonly status: number;
     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;
-}
+declare const CreateBrowserSessionOptionsSchema: z.ZodObject<{
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    headless: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type CreateBrowserSessionOptions = z.infer<typeof CreateBrowserSessionOptionsSchema>;
+declare const BrowserSessionSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    wsEndpoint: z.ZodString;
+    vncUrl: z.ZodNullable<z.ZodString>;
+    affinityCookie: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodDate;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+}, z.core.$strip>;
+type BrowserSession = z.infer<typeof BrowserSessionSchema>;
 
 /**
  * Upcrawl Browser Namespace
@@ -640,4 +661,4 @@ declare const Upcrawl: {
     readonly UpcrawlError: typeof UpcrawlError;
 };
 
-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 };
+export { type BatchScrapeOptions, BatchScrapeOptionsSchema, type BatchScrapeResponse, BatchScrapeResponseSchema, Browser, type BrowserSession, BrowserSessionSchema, type CreateBrowserSessionOptions, CreateBrowserSessionOptionsSchema, type ExecuteCodeOptions, ExecuteCodeOptionsSchema, type ExecuteCodeResponse, ExecuteCodeResponseSchema, type GeneratePdfFromUrlOptions, GeneratePdfFromUrlOptionsSchema, type GeneratePdfOptions, GeneratePdfOptionsSchema, type PdfMargin, PdfMarginSchema, type PdfResponse, PdfResponseSchema, type ScrapeMetadata, ScrapeMetadataSchema, type ScrapeOptions, ScrapeOptionsSchema, type ScrapeResponse, ScrapeResponseSchema, type SearchOptions, SearchOptionsSchema, type SearchResponse, SearchResponseSchema, type SearchResultItem, SearchResultItemSchema, type SearchResultWeb, SearchResultWebSchema, type SummaryQuery, SummaryQuerySchema, type UpcrawlConfig, UpcrawlConfigSchema, UpcrawlError, type UpcrawlErrorResponse, UpcrawlErrorResponseSchema, batchScrape, configure, Upcrawl as default, executeCode, generatePdf, generatePdfFromUrl, getConfig, resetConfig, scrape, search, setApiKey, setBaseUrl, setTimeout };