@dealcrawl/sdk 2.1.3 → 2.3.0

package/dist/index.d.ts

@@ -137,6 +137,15 @@ interface ScrapeResult {
     signals: Signal[];
     aiExtraction?: AIExtraction;
     dealExtraction?: ExtractedDeal;
+    /** Multiple deals extracted from list pages */
+    multipleDeals?: ExtractedDeal[];
+    /** Metadata for multi-deal extraction */
+    multiDealMetadata?: {
+        totalFound: number;
+        category?: string;
+        hasNextPage?: boolean;
+        extractionConfidence: number;
+    };
     dealScore?: DealScoreSummary;
     screenshot?: string;
     screenshotMetadata?: ScreenshotResult;
@@ -285,6 +294,120 @@ interface PaginationInfo {
 /** Scrape job creation response */
 interface ScrapeJobResponse extends JobResponse {
 }
+/** Individual batch scrape result item */
+interface BatchScrapeResultItem {
+    /** URL that was scraped */
+    url: string;
+    /** Reference ID if provided in request */
+    ref?: string;
+    /** Job ID created for this URL */
+    jobId: string;
+    /** Status of job creation */
+    status: "queued" | "failed";
+    /** Error message if job creation failed */
+    error?: string;
+}
+/** Batch scrape response */
+interface BatchScrapeResponse {
+    /** Batch ID for tracking */
+    batchId: string;
+    /** Total number of URLs in batch */
+    total: number;
+    /** Number of jobs successfully queued */
+    queued: number;
+    /** Number of jobs that failed to queue */
+    failed: number;
+    /** Individual results per URL */
+    results: BatchScrapeResultItem[];
+    /** Timestamp when batch was created */
+    createdAt: string;
+}
+/** Batch status response */
+interface BatchStatusResponse {
+    /** Batch ID */
+    batchId: string;
+    /** Total URLs in batch */
+    total: number;
+    /** Number queued */
+    queued: number;
+    /** Number failed */
+    failed: number;
+    /** Webhook URL if configured */
+    webhookUrl?: string;
+    /** Priority level */
+    priority: number;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Individual job statuses */
+    jobs: Array<{
+        id: string;
+        status: JobStatus;
+        result?: unknown;
+        error?: string;
+    }>;
+}
+/** Individual search result */
+interface SearchResultItem {
+    /** Result title */
+    title: string;
+    /** Result URL */
+    url: string;
+    /** Result description/snippet */
+    description: string;
+    /** Deal score if useDealScoring enabled (0-100) */
+    dealScore?: number;
+    /** Display URL */
+    displayUrl?: string;
+}
+/** Search job response data */
+interface SearchData {
+    /** Search results */
+    results: SearchResultItem[];
+    /** Total results found */
+    total: number;
+    /** Original query */
+    query: string;
+    /** AI-optimized query (if useAiOptimization=true) */
+    aiOptimizedQuery?: string;
+    /** Whether results were from cache */
+    cached: boolean;
+    /** Search duration in ms */
+    durationMs: number;
+    /** Job IDs for auto-scraped URLs */
+    scrapedJobIds?: string[];
+}
+/** Search job response */
+interface SearchJobResponse {
+    /** Success status */
+    success: boolean;
+    /** Search results data */
+    data: SearchData;
+    /** Response metadata */
+    meta: {
+        /** Search provider used */
+        provider: "serpapi" | "google";
+        /** Number of scrape jobs created */
+        scrapeJobsCreated: number;
+    };
+}
+/** Search API status response */
+interface SearchStatusResponse {
+    /** Whether search is available */
+    available: boolean;
+    /** Search provider */
+    provider: "serpapi" | "google" | "none";
+    /** Available features */
+    features: {
+        /** AI query optimization available */
+        aiOptimization: boolean;
+        /** Redis caching enabled */
+        caching: boolean;
+        /** Deal scoring enabled */
+        dealScoring: boolean;
+    };
+    /** Cache TTL */
+    cacheTtl: string;
+}
 /** Crawl job creation response */
 interface CrawlJobResponse extends JobResponse {
 }
@@ -514,19 +637,29 @@ interface TestWebhookResponse {
 interface ApiKeyInfo {
     id: string;
     name: string;
-    prefix: string;
+    /** Key prefix (e.g., "sk_dev_abc123") */
+    keyPrefix: string;
     scopes: string[];
     isActive: boolean;
-    expiresAt?: string;
-    lastUsedAt?: string;
+    expiresAt: string | null;
+    lastUsedAt: string | null;
     createdAt: string;
+    revokedAt: string | null;
+    revokedReason: string | null;
     usageCount: number;
-    ipAllowlist?: string[];
+    ipAllowlist: string[] | null;
 }
 /** Created API key (includes secret - only shown once) */
-interface CreatedApiKey extends ApiKeyInfo {
+interface CreatedApiKey {
+    id: string;
     /** The full API key - only returned on creation, never stored */
-    key: string;
+    rawKey: string;
+    /** Key prefix for identification */
+    keyPrefix: string;
+    name: string;
+    scopes: string[];
+    expiresAt: string | null;
+    createdAt: string;
 }
 /** List keys response */
 interface ListKeysResponse {
@@ -559,7 +692,9 @@ interface KeyStatsResponse {
         totalRequests: number;
         successfulRequests: number;
         failedRequests: number;
+        avgDurationMs: number;
         byEndpoint: Record<string, number>;
+        requestsByDay: Record<string, number>;
     };
 }
 /** Usage stats */
@@ -641,6 +776,69 @@ interface UpdatePreferencesResponse {
     success: boolean;
     preferences: ClientPreferences;
 }
+/** Agent job creation response */
+interface AgentJobResponse extends JobResponse {
+    /** Estimated completion time based on maxSteps */
+    estimatedTime?: string;
+}
+/** Agent step in execution trace */
+interface AgentStepResponse {
+    /** Step number (1-indexed) */
+    step: number;
+    /** Agent's reasoning before action */
+    thought: string;
+    /** Type of action taken */
+    actionType: string;
+    /** Action details */
+    action: Record<string, unknown>;
+    /** Whether the action succeeded */
+    result: "success" | "failed" | "skipped";
+    /** Duration of this step in ms */
+    durationMs: number;
+    /** Error message if failed */
+    error?: string;
+    /** Screenshot URL if captured */
+    screenshotUrl?: string;
+    /** Current URL after action */
+    currentUrl?: string;
+}
+/** Agent completion reason */
+type AgentCompletionReason = "goal_achieved" | "max_steps_reached" | "stuck" | "error" | "cancelled";
+/** Agent result (from completed job) */
+interface AgentResultResponse {
+    /** Extracted/collected data (matches provided schema if given) */
+    data: Record<string, unknown>;
+    /** Steps executed by the agent */
+    steps: AgentStepResponse[];
+    /** Final URL after all navigation */
+    finalUrl: string;
+    /** Credits/tokens used */
+    creditsUsed: number;
+    /** Total execution time in ms */
+    totalDurationMs: number;
+    /** Screenshots captured (if takeScreenshots enabled) */
+    screenshots?: string[];
+    /** Completion reason */
+    completionReason: AgentCompletionReason;
+    /** Agent metadata */
+    metadata: {
+        model: string;
+        stepsExecuted: number;
+        tokensUsed?: number;
+        timestamp: string;
+    };
+}
+/** Agent status response (extended from JobStatusResponse) */
+interface AgentStatusResponse extends JobStatusResponse {
+    /** Partial result with steps so far */
+    partialResult?: {
+        steps: AgentStepResponse[];
+        currentUrl?: string;
+        extractedData?: Record<string, unknown>;
+    };
+    /** Final result when completed */
+    result?: AgentResultResponse;
+}
 
 /**
  * Polling Utilities
@@ -727,6 +925,10 @@ interface ScrapeOptions {
     extractWithAI?: boolean;
     /** Extract deal-specific information (product, price, discount, urgency) */
     extractDeal?: boolean;
+    /** Extract MULTIPLE deals from list/category pages */
+    extractMultipleDeals?: boolean;
+    /** Maximum deals to extract from list pages (default: 20, max: 50) */
+    maxDeals?: number;
     /** Use advanced AI model (GPT-4o) for complex pages - higher cost, better quality */
     useAdvancedModel?: boolean;
     /** Minimum deal score threshold (0-100) - only returns deals above this score */
@@ -744,6 +946,118 @@ interface ScrapeOptions {
     /** Timeout in milliseconds (default: 30000, max: 120000) */
     timeout?: number;
 }
+/** Individual URL item for batch scraping */
+interface BatchScrapeItem {
+    /** URL to scrape */
+    url: string;
+    /** Optional reference ID for tracking */
+    ref?: string;
+    /** Override detectSignals for this URL */
+    detectSignals?: boolean;
+    /** Override extractWithAI for this URL */
+    extractWithAI?: boolean;
+    /** Override extractDeal for this URL */
+    extractDeal?: boolean;
+    /** Override screenshot for this URL */
+    screenshot?: ScreenshotOptions;
+    /** Override headers for this URL */
+    headers?: Record<string, string>;
+    /** Override timeout for this URL */
+    timeout?: number;
+}
+/** Default options applied to all URLs in a batch */
+interface BatchScrapeDefaults {
+    /** Don't save scrape results (zero data retention) */
+    noStore?: boolean;
+    /** Detect signals like prices, discounts, urgency */
+    detectSignals?: boolean;
+    /** Extract content using AI */
+    extractWithAI?: boolean;
+    /** Extract deal-specific information */
+    extractDeal?: boolean;
+    /** Extract multiple deals from list pages */
+    extractMultipleDeals?: boolean;
+    /** Maximum deals to extract (default: 20, max: 50) */
+    maxDeals?: number;
+    /** Use advanced AI model (higher cost, better quality) */
+    useAdvancedModel?: boolean;
+    /** Minimum deal score threshold (0-100) */
+    minDealScore?: number;
+    /** Screenshot configuration */
+    screenshot?: ScreenshotOptions;
+    /** HTML tags to exclude */
+    excludeTags?: string[];
+    /** CSS selectors to exclude */
+    excludeSelectors?: string[];
+    /** Only extract main content area */
+    onlyMainContent?: boolean;
+    /** Custom headers for requests */
+    headers?: Record<string, string>;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/** Options for batch scraping multiple URLs */
+interface BatchScrapeOptions {
+    /** Array of URLs to scrape (1-100) */
+    urls: BatchScrapeItem[];
+    /** Default options applied to all URLs */
+    defaults?: BatchScrapeDefaults;
+    /** Webhook URL for batch completion notification */
+    webhookUrl?: string;
+    /** Priority for batch jobs (1-10, higher = faster) */
+    priority?: number;
+    /** Delay between job submissions in ms (0-5000) */
+    delay?: number;
+}
+/** AI provider for search optimization */
+type SearchAiProvider = "openai" | "anthropic";
+/** AI model for search optimization */
+type SearchAiModel = "gpt-4o-mini" | "gpt-4o" | "gpt-4o-2024-11-20" | "o1-mini" | "o1-preview" | "claude-3-5-haiku-20241022" | "claude-3-5-sonnet-20241022" | "claude-3-5-sonnet-20240620" | "claude-3-opus-20240229";
+/** Date range filter for search */
+type SearchDateRange = "day" | "week" | "month" | "year" | "all";
+/** Search filters */
+interface SearchFilters {
+    /** Country code (e.g., 'fr', 'us') */
+    location?: string;
+    /** Language code (e.g., 'fr', 'en') */
+    language?: string;
+    /** Filter by date range */
+    dateRange?: SearchDateRange;
+    /** Exclude PDF files from results */
+    excludePdf?: boolean;
+    /** Limit to specific domain */
+    domain?: string;
+    /** Must contain these deal keywords (OR logic) */
+    dealKeywords?: string[];
+}
+/** Options for web search */
+interface SearchOptions {
+    /** Search query (required) */
+    query: string;
+    /** Maximum number of results (1-100, default: 10) */
+    maxResults?: number;
+    /** Auto-scrape top results */
+    autoScrape?: boolean;
+    /** Number of results to auto-scrape (1-10, default: 5) */
+    autoScrapeLimit?: number;
+    /** Use AI to optimize the search query */
+    useAiOptimization?: boolean;
+    /** AI provider for query optimization */
+    aiProvider?: SearchAiProvider;
+    /** AI model to use */
+    aiModel?: SearchAiModel;
+    /** Enable deal scoring for results (0-100) */
+    useDealScoring?: boolean;
+    /** Skip cache and force fresh search */
+    skipCache?: boolean;
+    /** Search filters */
+    filters?: SearchFilters;
+    /** Webhook for async notifications */
+    webhook?: {
+        url: string;
+        headers?: Record<string, string>;
+    };
+}
 /** Options for crawling a website */
 interface CrawlOptions {
     /** Starting URL for the crawl (required) */
@@ -946,7 +1260,15 @@ interface UpdateWebhookOptions {
  * API key scope - Must match @dealcrawl/shared/src/types/api-key.types.ts
  * These are the actual scopes enforced by the backend via requireScope() middleware
  */
-type ApiKeyScope = "scrape" | "crawl" | "dork" | "extract" | "status" | "data:read" | "data:export" | "keys:manage" | "webhooks:manage";
+type ApiKeyScope = "scrape" | "crawl" | "dork" | "extract" | "agent" | "status" | "data:read" | "data:export" | "keys:manage" | "webhooks:manage";
+/**
+ * All available scopes (for reference and validation)
+ */
+declare const ALL_API_KEY_SCOPES: ApiKeyScope[];
+/**
+ * Default scopes for new keys
+ */
+declare const DEFAULT_API_KEY_SCOPES: ApiKeyScope[];
 /** Options for creating an API key */
 interface CreateApiKeyOptions {
     /** Key name/description */
@@ -968,9 +1290,14 @@ interface ListApiKeysOptions {
     /** Include revoked keys */
     includeRevoked?: boolean;
 }
+/** Options for revoking an API key */
+interface RevokeApiKeyOptions {
+    /** Reason for revocation */
+    reason?: string;
+}
 /** Options for getting API key stats */
 interface GetApiKeyStatsOptions {
-    /** Number of days to get stats for (default: 30) */
+    /** Number of days to get stats for (default: 7, max: 30) */
     days?: number;
 }
 /** Product category */
@@ -986,6 +1313,111 @@ interface UpdatePreferencesOptions {
     /** Enable webhook notifications */
     webhookEnabled?: boolean;
 }
+/** LLM provider for agent */
+type AgentModel = "openai" | "anthropic";
+/** Browser action types */
+type AgentActionType = "click" | "scroll" | "write" | "wait" | "press" | "screenshot" | "hover" | "select";
+/** Base action interface */
+interface BaseAgentAction {
+    type: AgentActionType;
+    optional?: boolean;
+    retries?: number;
+    delayBefore?: number;
+}
+/** Click action */
+interface ClickAction extends BaseAgentAction {
+    type: "click";
+    selector: string;
+    waitAfter?: number;
+    button?: "left" | "right" | "middle";
+    clickCount?: number;
+    force?: boolean;
+}
+/** Scroll action */
+interface ScrollAction extends BaseAgentAction {
+    type: "scroll";
+    direction: "up" | "down" | "left" | "right" | "to-element";
+    selector?: string;
+    amount?: number;
+    smooth?: boolean;
+}
+/** Write action */
+interface WriteAction extends BaseAgentAction {
+    type: "write";
+    selector: string;
+    text: string;
+    clearFirst?: boolean;
+    pressEnter?: boolean;
+    typeDelay?: number;
+}
+/** Wait action */
+interface WaitAction extends BaseAgentAction {
+    type: "wait";
+    milliseconds?: number;
+    selector?: string;
+    condition?: "visible" | "hidden" | "attached" | "detached";
+    timeout?: number;
+}
+/** Press action */
+interface PressAction extends BaseAgentAction {
+    type: "press";
+    key: string;
+    modifiers?: Array<"Alt" | "Control" | "Meta" | "Shift">;
+}
+/** Screenshot action */
+interface ScreenshotAgentAction extends BaseAgentAction {
+    type: "screenshot";
+    fullPage?: boolean;
+    selector?: string;
+    format?: "png" | "jpeg";
+    quality?: number;
+    name?: string;
+}
+/** Hover action */
+interface HoverAction extends BaseAgentAction {
+    type: "hover";
+    selector: string;
+    duration?: number;
+}
+/** Select action */
+interface SelectAction extends BaseAgentAction {
+    type: "select";
+    selector: string;
+    value: string | string[];
+    byLabel?: boolean;
+}
+/** All agent action types */
+type AgentAction = ClickAction | ScrollAction | WriteAction | WaitAction | PressAction | ScreenshotAgentAction | HoverAction | SelectAction;
+/** Options for creating an AI agent job */
+interface AgentOptions {
+    /** Starting URL for the agent (required) */
+    url: string;
+    /** Additional URLs to process */
+    urls?: string[];
+    /** Natural language instructions for the agent (required, 10-2000 chars) */
+    prompt: string;
+    /** JSON Schema for structured output */
+    schema?: Record<string, unknown>;
+    /** Maximum number of steps (default: 10, max: 25) */
+    maxSteps?: number;
+    /** Preset actions to execute before agent reasoning */
+    actions?: AgentAction[];
+    /** LLM provider (default: openai) */
+    model?: AgentModel;
+    /** Per-step timeout in milliseconds (default: 30000, max: 60000) */
+    timeout?: number;
+    /** Extract only main content area (default: true) */
+    onlyMainContent?: boolean;
+    /** Take screenshots at each step (default: false) */
+    takeScreenshots?: boolean;
+    /** Custom headers for HTTP requests */
+    headers?: Record<string, string>;
+    /** Webhook for async notification */
+    webhook?: {
+        url: string;
+        headers?: Record<string, string>;
+    };
+}
 
 /**
  * Account Resource
@@ -1128,6 +1560,161 @@ declare class AccountResource {
     isPremium(): Promise<boolean>;
 }
 
+/**
+ * Agent Resource
+ * Handles AI agent operations for autonomous web navigation and data extraction
+ */
+
+/**
+ * Agent resource class
+ * Provides methods for creating and managing AI agent jobs
+ *
+ * The agent uses the ReAct pattern (Observation → Thought → Action → Evaluation)
+ * to navigate web pages and extract structured data based on natural language instructions.
+ *
+ * @example
+ * ```ts
+ * // Create an agent to search and extract product info
+ * const job = await client.agent.create({
+ *   url: "https://amazon.com",
+ *   prompt: "Search for wireless headphones under $50 and extract the top 5 results with name, price, and rating",
+ *   schema: {
+ *     type: "object",
+ *     properties: {
+ *       products: {
+ *         type: "array",
+ *         items: {
+ *           type: "object",
+ *           properties: {
+ *             name: { type: "string" },
+ *             price: { type: "number" },
+ *             rating: { type: "number" }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   },
+ *   maxSteps: 15
+ * });
+ *
+ * // Wait for result
+ * const result = await client.waitForResult(job.jobId);
+ * ```
+ */
+declare class AgentResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Create a new AI agent job
+     *
+     * @param options - Agent configuration options
+     * @returns Job creation response with jobId and status URL
+     *
+     * @example
+     * ```ts
+     * const job = await client.agent.create({
+     *   url: "https://booking.com",
+     *   prompt: "Find hotels in Paris for 2 adults, March 15-17, sort by price and extract the 3 cheapest options",
+     *   maxSteps: 20,
+     *   takeScreenshots: true
+     * });
+     * ```
+     */
+    create(options: AgentOptions): Promise<AgentJobResponse>;
+    /**
+     * Get the status of an agent job
+     *
+     * @param jobId - The job ID to check
+     * @returns Agent status with progress and partial results
+     *
+     * @example
+     * ```ts
+     * const status = await client.agent.getStatus(jobId);
+     * console.log(`Step ${status.partialResult?.steps.length}/${status.totalSteps}`);
+     * ```
+     */
+    getStatus(jobId: string): Promise<AgentStatusResponse>;
+    /**
+     * Create an agent with preset actions
+     * Useful for handling common scenarios like cookie consent, popups, etc.
+     *
+     * @example
+     * ```ts
+     * const job = await client.agent.withPresetActions(
+     *   "https://shop.com",
+     *   "Find the best discount and extract product details",
+     *   [
+     *     { type: "click", selector: "#accept-cookies" },
+     *     { type: "wait", milliseconds: 1000 }
+     *   ]
+     * );
+     * ```
+     */
+    withPresetActions(url: string, prompt: string, actions: AgentOptions["actions"], options?: Omit<AgentOptions, "url" | "prompt" | "actions">): Promise<AgentJobResponse>;
+    /**
+     * Create an agent with a JSON schema for structured output
+     * The agent will extract data matching the provided schema
+     *
+     * @example
+     * ```ts
+     * const job = await client.agent.withSchema(
+     *   "https://linkedin.com/company/example",
+     *   "Extract company information",
+     *   {
+     *     type: "object",
+     *     properties: {
+     *       name: { type: "string" },
+     *       employees: { type: "number" },
+     *       description: { type: "string" },
+     *       website: { type: "string" }
+     *     },
+     *     required: ["name"]
+     *   }
+     * );
+     * ```
+     */
+    withSchema(url: string, prompt: string, schema: Record<string, unknown>, options?: Omit<AgentOptions, "url" | "prompt" | "schema">): Promise<AgentJobResponse>;
+    /**
+     * Create an agent optimized for deal/product extraction
+     * Pre-configured for e-commerce scenarios
+     *
+     * @example
+     * ```ts
+     * const job = await client.agent.forDeals(
+     *   "https://slickdeals.net",
+     *   "Find the top 10 tech deals posted today"
+     * );
+     * ```
+     */
+    forDeals(url: string, prompt: string, options?: Omit<AgentOptions, "url" | "prompt" | "schema">): Promise<AgentJobResponse>;
+    /**
+     * Create an agent to fill and submit a form
+     * Useful for search forms, login forms, etc.
+     *
+     * @example
+     * ```ts
+     * const job = await client.agent.fillForm(
+     *   "https://kayak.com",
+     *   "Search for flights from Paris to New York on March 20, return March 27",
+     *   { takeScreenshots: true }
+     * );
+     * ```
+     */
+    fillForm(url: string, instructions: string, options?: Omit<AgentOptions, "url" | "prompt">): Promise<AgentJobResponse>;
+    /**
+     * Create an agent using Claude (Anthropic) instead of GPT
+     *
+     * @example
+     * ```ts
+     * const job = await client.agent.withClaude(
+     *   "https://complex-site.com",
+     *   "Navigate through the multi-step checkout process"
+     * );
+     * ```
+     */
+    withClaude(url: string, prompt: string, options?: Omit<AgentOptions, "url" | "prompt" | "model">): Promise<AgentJobResponse>;
+}
+
 /**
  * Crawl Resource
  * Handles website crawling operations
@@ -1665,10 +2252,16 @@ declare class KeysResource {
      *
      * @example
      * ```ts
+     * // Simple revoke
      * await client.keys.revoke("key_abc123");
+     *
+     * // With reason
+     * await client.keys.revoke("key_abc123", {
+     *   reason: "Key compromised"
+     * });
      * ```
      */
-    revoke(keyId: string): Promise<DeleteKeyResponse>;
+    revoke(keyId: string, options?: RevokeApiKeyOptions): Promise<DeleteKeyResponse>;
     /**
      * Revoke all API keys (except the current one)
      *
@@ -1705,7 +2298,7 @@ declare class KeysResource {
 
 /**
  * Scrape Resource
- * Handles single page scraping operations
+ * Handles single page and batch scraping operations
  */
 
 /**
@@ -1739,6 +2332,19 @@ declare class ScrapeResource {
      * ```
      */
     extractDeal(url: string, options?: Omit<ScrapeOptions, "url" | "extractDeal">): Promise<ScrapeJobResponse>;
+    /**
+     * Scrape a list page and extract multiple deals
+     * Use for category pages, deal lists, search results
+     *
+     * @example
+     * ```ts
+     * const job = await client.scrape.extractDeals(
+     *   "https://amazon.fr/deals",
+     *   { maxDeals: 30, useAdvancedModel: true }
+     * );
+     * ```
+     */
+    extractDeals(url: string, options?: Omit<ScrapeOptions, "url" | "extractMultipleDeals">): Promise<ScrapeJobResponse>;
     /**
      * Scrape a URL with screenshot capture
      * Convenience method for screenshot capture
@@ -1752,6 +2358,122 @@ declare class ScrapeResource {
      * ```
      */
     withScreenshot(url: string, screenshotOptions?: Omit<ScrapeOptions["screenshot"], "enabled">, options?: Omit<ScrapeOptions, "url" | "screenshot">): Promise<ScrapeJobResponse>;
+    /**
+     * Create a batch scrape job for multiple URLs
+     * Scrapes 1-100 URLs in a single request
+     *
+     * @example
+     * ```ts
+     * const batch = await client.scrape.batch({
+     *   urls: [
+     *     { url: "https://shop1.com/product1" },
+     *     { url: "https://shop2.com/deal", extractDeal: true }
+     *   ],
+     *   defaults: { detectSignals: true }
+     * });
+     * console.log(batch.batchId, batch.results);
+     * ```
+     */
+    batch(options: BatchScrapeOptions): Promise<BatchScrapeResponse>;
+    /**
+     * Get status of a batch scrape operation
+     *
+     * @example
+     * ```ts
+     * const status = await client.scrape.getBatchStatus(batchId);
+     * console.log(`Completed: ${status.completed}/${status.total}`);
+     * ```
+     */
+    getBatchStatus(batchId: string): Promise<BatchStatusResponse>;
+    /**
+     * Batch scrape with deal extraction enabled for all URLs
+     * Convenience method for deal-focused batch scraping
+     *
+     * @example
+     * ```ts
+     * const batch = await client.scrape.batchForDeals([
+     *   "https://shop1.com/sale",
+     *   "https://shop2.com/deals"
+     * ]);
+     * ```
+     */
+    batchForDeals(urls: string[], options?: Omit<BatchScrapeOptions, "urls">): Promise<BatchScrapeResponse>;
+}
+
+/**
+ * Search Resource
+ * Handles web search operations with AI optimization
+ */
+
+/**
+ * Search resource class
+ * Provides methods for web search with AI optimization
+ */
+declare class SearchResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Create a new search job
+     *
+     * @example
+     * ```ts
+     * const result = await client.search.create({
+     *   query: "laptop deals black friday",
+     *   maxResults: 20,
+     *   useDealScoring: true
+     * });
+     * ```
+     */
+    create(options: SearchOptions): Promise<SearchJobResponse>;
+    /**
+     * Search with AI query optimization
+     * Convenience method for AI-enhanced searches
+     *
+     * @example
+     * ```ts
+     * const result = await client.search.withAI("iphone discount", {
+     *   aiProvider: "openai",
+     *   aiModel: "gpt-4o-mini"
+     * });
+     * ```
+     */
+    withAI(query: string, options?: Omit<SearchOptions, "query" | "useAiOptimization">): Promise<SearchJobResponse>;
+    /**
+     * Search with deal scoring enabled
+     * Scores each result for deal relevance (0-100)
+     *
+     * @example
+     * ```ts
+     * const result = await client.search.forDeals("gaming laptop");
+     * ```
+     */
+    forDeals(query: string, options?: Omit<SearchOptions, "query" | "useDealScoring">): Promise<SearchJobResponse>;
+    /**
+     * Search and auto-scrape top results
+     * Creates scrape jobs for the best matching URLs
+     *
+     * @example
+     * ```ts
+     * const result = await client.search.andScrape("promo codes", {
+     *   autoScrapeLimit: 5
+     * });
+     * console.log(result.data.scrapedJobIds);
+     * ```
+     */
+    andScrape(query: string, options?: Omit<SearchOptions, "query" | "autoScrape">): Promise<SearchJobResponse>;
+    /**
+     * Check search API status
+     * Returns availability and features info
+     *
+     * @example
+     * ```ts
+     * const status = await client.search.getStatus();
+     * if (status.available) {
+     *   console.log(`Provider: ${status.provider}`);
+     * }
+     * ```
+     */
+    getStatus(): Promise<SearchStatusResponse>;
 }
 
 /**
@@ -2032,17 +2754,38 @@ declare class DealCrawl {
     /** Internal request context */
     private readonly ctx;
     /**
-     * Scrape resource - Single page scraping
+     * Scrape resource - Single page and batch scraping
      *
      * @example
      * ```ts
+     * // Single page
      * const job = await client.scrape.create({
      *   url: "https://example.com",
      *   extractDeal: true
      * });
+     *
+     * // Batch scraping
+     * const batch = await client.scrape.batch({
+     *   urls: [{ url: "https://shop1.com" }, { url: "https://shop2.com" }]
+     * });
      * ```
      */
     readonly scrape: ScrapeResource;
+    /**
+     * Search resource - Web search with AI optimization
+     *
+     * @example
+     * ```ts
+     * const result = await client.search.create({
+     *   query: "laptop deals",
+     *   useDealScoring: true
+     * });
+     *
+     * // With AI optimization
+     * const result = await client.search.withAI("iphone discount");
+     * ```
+     */
+    readonly search: SearchResource;
     /**
      * Crawl resource - Website crawling
      *
@@ -2084,6 +2827,29 @@ declare class DealCrawl {
      * ```
      */
     readonly dork: DorkResource;
+    /**
+     * Agent resource - AI-powered autonomous web navigation
+     *
+     * The agent uses ReAct pattern (Observation → Thought → Action → Evaluation)
+     * to navigate web pages and extract structured data based on natural language.
+     *
+     * @example
+     * ```ts
+     * const job = await client.agent.create({
+     *   url: "https://amazon.com",
+     *   prompt: "Search for wireless headphones under $50 and extract top 5 results",
+     *   maxSteps: 15
+     * });
+     *
+     * // With schema for structured output
+     * const job = await client.agent.withSchema(
+     *   "https://example.com",
+     *   "Extract product info",
+     *   { type: "object", properties: {...} }
+     * );
+     * ```
+     */
+    readonly agent: AgentResource;
     /**
      * Status resource - Job status management
      *
@@ -2249,6 +3015,35 @@ declare class DealCrawl {
      * ```
      */
     extractAndWait<T = unknown>(options: Parameters<ExtractResource["create"]>[0], waitOptions?: WaitOptions): Promise<WaitResult<T>>;
+    /**
+     * Search and return results directly
+     * Note: Search is synchronous, no waiting needed
+     *
+     * @example
+     * ```ts
+     * const result = await client.searchAndWait({
+     *   query: "gaming laptop deals",
+     *   useDealScoring: true
+     * });
+     * console.log(result.data.results);
+     * ```
+     */
+    searchAndWait(options: Parameters<SearchResource["create"]>[0]): Promise<ReturnType<SearchResource["create"]>>;
+    /**
+     * Create an agent job and wait for result
+     * Combines create and waitForResult
+     *
+     * @example
+     * ```ts
+     * const result = await client.agentAndWait({
+     *   url: "https://booking.com",
+     *   prompt: "Find hotels in Paris for March 15-17",
+     *   maxSteps: 20
+     * });
+     * console.log(result.data);
+     * ```
+     */
+    agentAndWait<T = unknown>(options: Parameters<AgentResource["create"]>[0], waitOptions?: WaitOptions): Promise<WaitResult<T>>;
 }
 
 /**
@@ -2332,4 +3127,4 @@ declare class DealCrawlError extends Error {
     }, retryAfter?: number | string | null): DealCrawlError;
 }
 
-export { type AccountInfoResponse, type AccountMetricsResponse, AccountResource, type ApiError, type ApiKeyInfo, type ApiKeyScope, type ApiResponse, type CancelJobResponse, type CheckpointInfo, type ClientPreferences, type ClientStatsResponse, type CrawlAnalysisResponse, type CrawlJobResponse, type CrawlOptions, type CrawlRecommendation, CrawlResource, type CrawlResult, type CrawlTemplate, type CrawlTemplateId, type CreateApiKeyOptions, type CreateKeyResponse, type CreateWebhookOptions, type CreateWebhookResponse, type CreatedApiKey, DEFAULT_CONFIG, DataResource, DealCrawl, type DealCrawlConfig, DealCrawlError, type DealDetails, type DealItem, type DealMetrics, type DealScoreSummary, type DealSummary, type DealUpMetrics, type DealUpMetricsResponse, type DeleteKeyResponse, type DeleteWebhookResponse, type DiscountSignal, type DorkJobResponse, type DorkOptions, DorkResource, type DorkResult, ERROR_CODES, type ErrorCode, type ExportDealsOptions, type ExportFormat, type ExportJobsOptions, type ExtractJobResponse, type ExtractModel, type ExtractOptions, ExtractResource, type ExtractedDeal, type GetApiKeyStatsOptions, type GetDealsOptions, type JobDealsResponse, type JobMetricsResponse, type JobResponse, type JobStatus, type JobStatusFilter, type JobStatusResponse, type JobSummary, type JobTypeFilter, type KeyStatsResponse, KeysResource, type ListApiKeysOptions, type ListDealsOptions, type ListDealsResponse, type ListJobsOptions, type ListJobsResponse, type ListKeysResponse, type ListWebhooksResponse, type PaginatedResponse, type PaginationInfo, type ParsedPage, type PreferencesResponse, type PriceSignal, type PricingInfo, type ProductCategory, type ProductInfo, type RateLimitInfo, type RecommendationsResponse, type RequestContext, type ResumeJobResponse, type RotateApiKeyOptions, type RotateKeyResponse, type ScrapeJobResponse, type ScrapeOptions, ScrapeResource, type ScrapeResult, type ScreenshotOptions, type Signal, type SortOrder, StatusResource, type TestWebhookResponse, type UpdatePreferencesOptions, type UpdatePreferencesResponse, type UpdateWebhookOptions, type UpdateWebhookResponse, type UsageStats, type WaitOptions, type WaitResult, type WebhookEvent, type WebhookItem, WebhooksResource, DealCrawl as default, pollUntil, waitForAll, waitForAny, waitForResult };
+export { ALL_API_KEY_SCOPES, type AccountInfoResponse, type AccountMetricsResponse, AccountResource, type AgentAction, type AgentActionType, type AgentCompletionReason, type AgentJobResponse, type AgentModel, type AgentOptions, AgentResource, type AgentResultResponse, type AgentStatusResponse, type AgentStepResponse, type ApiError, type ApiKeyInfo, type ApiKeyScope, type ApiResponse, type BatchScrapeDefaults, type BatchScrapeItem, type BatchScrapeOptions, type BatchScrapeResponse, type BatchScrapeResultItem, type BatchStatusResponse, type CancelJobResponse, type CheckpointInfo, type ClickAction, type ClientPreferences, type ClientStatsResponse, type CrawlAnalysisResponse, type CrawlJobResponse, type CrawlOptions, type CrawlRecommendation, CrawlResource, type CrawlResult, type CrawlTemplate, type CrawlTemplateId, type CreateApiKeyOptions, type CreateKeyResponse, type CreateWebhookOptions, type CreateWebhookResponse, type CreatedApiKey, DEFAULT_API_KEY_SCOPES, DEFAULT_CONFIG, DataResource, DealCrawl, type DealCrawlConfig, DealCrawlError, type DealDetails, type DealItem, type DealMetrics, type DealScoreSummary, type DealSummary, type DealUpMetrics, type DealUpMetricsResponse, type DeleteKeyResponse, type DeleteWebhookResponse, type DiscountSignal, type DorkJobResponse, type DorkOptions, DorkResource, type DorkResult, ERROR_CODES, type ErrorCode, type ExportDealsOptions, type ExportFormat, type ExportJobsOptions, type ExtractJobResponse, type ExtractModel, type ExtractOptions, ExtractResource, type ExtractedDeal, type GetApiKeyStatsOptions, type GetDealsOptions, type HoverAction, type JobDealsResponse, type JobMetricsResponse, type JobResponse, type JobStatus, type JobStatusFilter, type JobStatusResponse, type JobSummary, type JobTypeFilter, type KeyStatsResponse, KeysResource, type ListApiKeysOptions, type ListDealsOptions, type ListDealsResponse, type ListJobsOptions, type ListJobsResponse, type ListKeysResponse, type ListWebhooksResponse, type PaginatedResponse, type PaginationInfo, type ParsedPage, type PreferencesResponse, type PressAction, type PriceSignal, type PricingInfo, type ProductCategory, type ProductInfo, type RateLimitInfo, type RecommendationsResponse, type RequestContext, type ResumeJobResponse, type RevokeApiKeyOptions, type RotateApiKeyOptions, type RotateKeyResponse, type ScrapeJobResponse, type ScrapeOptions, ScrapeResource, type ScrapeResult, type ScreenshotAgentAction, type ScreenshotOptions, type ScrollAction, type SearchAiModel, type SearchAiProvider, type SearchData, type SearchDateRange, type SearchFilters, type SearchJobResponse, type SearchOptions, SearchResource, type SearchResultItem, type SearchStatusResponse, type SelectAction, type Signal, type SortOrder, StatusResource, type TestWebhookResponse, type UpdatePreferencesOptions, type UpdatePreferencesResponse, type UpdateWebhookOptions, type UpdateWebhookResponse, type UsageStats, type WaitAction, type WaitOptions, type WaitResult, type WebhookEvent, type WebhookItem, WebhooksResource, type WriteAction, DealCrawl as default, pollUntil, waitForAll, waitForAny, waitForResult };