@dealcrawl/sdk 2.2.0 → 2.4.0

package/dist/index.d.mts

@@ -776,6 +776,82 @@ 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;
+}
+/** Schema generation response from /v1/agent/schema */
+interface SchemaGenerationResponse {
+    /** Generated JSON Schema for data extraction */
+    schema: Record<string, unknown>;
+    /** Refined prompt optimized for agent execution */
+    refinedPrompt: string;
+    /** Human-readable description of the schema */
+    schemaDescription: string;
+    /** Suggested follow-up questions if prompt was ambiguous */
+    suggestedQuestions?: string[];
+    /** Confidence score (0-1) in the generated schema */
+    confidence: number;
+}
 
 /**
  * Polling Utilities
@@ -1197,7 +1273,7 @@ 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)
  */
@@ -1250,6 +1326,131 @@ 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>;
+    };
+}
+/** Context for schema generation from conversation */
+interface SchemaGenerationContext {
+    /** Specific domains/topics mentioned (e.g., ['marketing', 'web development']) */
+    domains?: string[];
+    /** Types of data to extract (e.g., ['free courses', 'discounts']) */
+    dataTypes?: string[];
+    /** Preferred output format */
+    format?: "json" | "csv" | "table";
+    /** Additional clarifications from user */
+    clarifications?: string[];
+}
+/** Options for generating a JSON Schema from natural language */
+interface SchemaGenerationOptions {
+    /** Natural language description of what data to extract (required, 5-2000 chars) */
+    prompt: string;
+    /** Optional context from conversation to refine the schema */
+    context?: SchemaGenerationContext;
+    /** LLM provider for generation (default: openai) */
+    model?: AgentModel;
+}
 
 /**
  * Account Resource
@@ -1392,6 +1593,208 @@ 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>;
+    /**
+     * Generate a JSON Schema from a natural language prompt
+     *
+     * This is useful for building extraction schemas without manual JSON writing.
+     * The generated schema can be used with the main agent.create() method.
+     *
+     * @param options - Schema generation options
+     * @returns Generated schema with refined prompt and confidence score
+     *
+     * @example Basic usage:
+     * ```ts
+     * const result = await client.agent.generateSchema({
+     *   prompt: "Find the best student deals on Coursera for marketing courses"
+     * });
+     *
+     * console.log(result.schema);
+     * // { type: "object", properties: { courses: { ... } } }
+     *
+     * console.log(result.refinedPrompt);
+     * // "Extract student offers for marketing courses..."
+     *
+     * // Use the generated schema with an agent
+     * const job = await client.agent.create({
+     *   url: "https://coursera.org",
+     *   prompt: result.refinedPrompt,
+     *   schema: result.schema
+     * });
+     * ```
+     *
+     * @example With context from conversation:
+     * ```ts
+     * const result = await client.agent.generateSchema({
+     *   prompt: "Find student deals on online courses",
+     *   context: {
+     *     domains: ["marketing", "web development"],
+     *     dataTypes: ["free courses", "discounts"],
+     *     format: "json"
+     *   }
+     * });
+     *
+     * if (result.confidence < 0.7 && result.suggestedQuestions) {
+     *   // Ask user for clarification
+     *   console.log("Please clarify:", result.suggestedQuestions);
+     * }
+     * ```
+     */
+    generateSchema(options: SchemaGenerationOptions): Promise<SchemaGenerationResponse>;
+}
+
 /**
  * Crawl Resource
  * Handles website crawling operations
@@ -2504,6 +2907,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
      *
@@ -2683,6 +3109,21 @@ declare class DealCrawl {
      * ```
      */
     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>>;
 }
 
 /**
@@ -2766,4 +3207,4 @@ declare class DealCrawlError extends Error {
     }, retryAfter?: number | string | null): DealCrawlError;
 }
 
-export { ALL_API_KEY_SCOPES, type AccountInfoResponse, type AccountMetricsResponse, AccountResource, 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 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 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 RevokeApiKeyOptions, type RotateApiKeyOptions, type RotateKeyResponse, type ScrapeJobResponse, type ScrapeOptions, ScrapeResource, type ScrapeResult, type ScreenshotOptions, type SearchAiModel, type SearchAiProvider, type SearchData, type SearchDateRange, type SearchFilters, type SearchJobResponse, type SearchOptions, SearchResource, type SearchResultItem, type SearchStatusResponse, 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 };