@dealcrawl/sdk 2.4.0 → 2.6.0

package/README.md

@@ -8,7 +8,7 @@ Official TypeScript SDK for the DealCrawl web scraping and crawling API.
 
 ## Features
 
-- 🚀 **Full API Coverage** - Access all 45 DealCrawl API endpoints
+- 🚀 **Full API Coverage** - Access all 50+ DealCrawl API endpoints
 - 📦 **Zero Dependencies** - Uses native `fetch`, works everywhere
 - 🔒 **Type-Safe** - Complete TypeScript definitions
 - ⚡ **Automatic Retries** - Built-in retry logic with exponential backoff
@@ -89,14 +89,20 @@ const job = await client.scrape.withScreenshot("https://example.com", {
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `url` | string | required | URL to scrape |
+| `noStore` | boolean | false | Zero Data Retention - don't save results (Pro/Enterprise) |
 | `detectSignals` | boolean | true | Detect prices, discounts, urgency |
 | `extractDeal` | boolean | false | Extract deal information |
+| `extractMultipleDeals` | boolean | false | Extract multiple deals from list pages |
+| `maxDeals` | number | 20 | Max deals to extract (max: 50) |
 | `extractWithAI` | boolean | false | Use AI for extraction |
 | `useAdvancedModel` | boolean | false | Use GPT-4o (higher cost) |
 | `minDealScore` | number | 0 | Minimum deal score (0-100) |
 | `screenshot` | object | - | Screenshot options |
 | `excludeTags` | string[] | - | HTML tags to exclude |
+| `excludeSelectors` | string[] | - | CSS selectors to exclude |
 | `onlyMainContent` | boolean | true | Extract main content only |
+| `headers` | object | - | Custom HTTP headers |
+| `timeout` | number | 30000 | Request timeout in ms (max: 120000) |
 
 ### Batch Scrape - Bulk URL Scraping (NEW)
 
@@ -215,6 +221,27 @@ console.log(analysis.estimatedPages);
 const job = await client.crawl.forDeals("https://shop.example.com", {
   minDealScore: 70,
 });
+
+// Advanced crawl with filtering
+const job = await client.crawl.create({
+  url: "https://marketplace.example.com",
+  maxDepth: 4,
+  maxPages: 500,
+  extractDeal: true,
+  minDealScore: 50,
+  categories: ["software", "courses"],
+  priceRange: { min: 0, max: 100 },
+  onlyHighQuality: true,
+  webhookUrl: "https://my-server.com/crawl-updates",
+  syncToDealup: true,
+});
+
+// Enterprise: priority queue override
+const job = await client.crawl.create({
+  url: "https://time-sensitive-deals.com",
+  priority: "high", // Enterprise only
+  onlyHighQuality: true,
+});
 ```
 
 **Available Templates:**
@@ -225,6 +252,28 @@ const job = await client.crawl.forDeals("https://shop.example.com", {
 - `docs` - Documentation sites
 - `custom` - No preset, use your own settings
 
+**Crawl Options:**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | string | required | Starting URL |
+| `maxDepth` | number | 3 | Max crawl depth (1-5) |
+| `maxPages` | number | 100 | Max pages to crawl (1-1000) |
+| `detectSignals` | boolean | true | Detect prices, discounts |
+| `extractDeal` | boolean | false | Extract deal info with AI |
+| `minDealScore` | number | 30 | Min deal score threshold (0-100) |
+| `categories` | array | - | Filter: courses, software, physical, services, other |
+| `priceRange` | object | - | Filter: { min, max } price |
+| `onlyHighQuality` | boolean | false | Only deals scoring 70+ |
+| `allowedMerchants` | string[] | - | Only these merchants |
+| `blockedMerchants` | string[] | - | Exclude these merchants |
+| `webhookUrl` | string | - | Real-time notifications URL |
+| `syncToDealup` | boolean | false | Auto-sync to DealUp |
+| `template` | string | - | Job template to use |
+| `useSmartRouting` | boolean | true | Auto-detect best settings |
+| `priority` | string | - | Queue priority (Enterprise only) |
+| `requireJS` | boolean | false | Force JavaScript rendering |
+| `bypassAntiBot` | boolean | false | Advanced anti-bot techniques |
+
 ### Extract - LLM-Based Extraction
 
 ```typescript
@@ -278,6 +327,101 @@ const query = client.dork.buildQuery({
 // Returns: "laptop deals site:amazon.com intitle:discount"
 ```
 
+### Agent - AI Autonomous Navigation (NEW)
+
+Create AI agents that can navigate websites, interact with elements, and extract structured data using natural language instructions.
+
+```typescript
+// Basic agent - navigate and extract data
+const job = await client.agent.create({
+  url: "https://amazon.com",
+  prompt: "Search for wireless headphones under $50 and extract the top 5 results",
+  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.agentAndWait({
+  url: "https://booking.com",
+  prompt: "Find hotels in Paris for 2 adults, March 15-17",
+  takeScreenshots: true,
+});
+
+// Generate schema from natural language (helper)
+const schemaResult = await client.agent.generateSchema({
+  prompt: "Find student deals on marketing courses with price and discount",
+});
+// Returns: { schema, refinedPrompt, confidence, suggestedQuestions? }
+
+// Use generated schema
+const job = await client.agent.create({
+  url: "https://coursera.org",
+  prompt: schemaResult.refinedPrompt,
+  schema: schemaResult.schema,
+});
+
+// Preset actions (handle popups, cookies, etc.)
+const job = await client.agent.withPresetActions(
+  "https://shop.com",
+  "Find the best discounts",
+  [
+    { type: "click", selector: "#accept-cookies" },
+    { type: "wait", milliseconds: 1000 },
+  ]
+);
+
+// Deal-focused agent with pre-built schema
+const job = await client.agent.forDeals(
+  "https://slickdeals.net",
+  "Find the top 10 tech deals posted today"
+);
+
+// Use Claude instead of GPT
+const job = await client.agent.withClaude(
+  "https://complex-site.com",
+  "Navigate the checkout process"
+);
+```
+
+**Agent Options:**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | string | required | Starting URL |
+| `prompt` | string | required | Natural language instructions (10-2000 chars) |
+| `schema` | object | - | JSON Schema for structured output |
+| `maxSteps` | number | 10 | Maximum navigation steps (max: 25) |
+| `actions` | array | - | Preset actions to execute first |
+| `model` | string | "openai" | LLM provider: "openai" or "anthropic" |
+| `timeout` | number | 30000 | Per-step timeout in ms (max: 60000) |
+| `takeScreenshots` | boolean | false | Capture screenshot at each step |
+| `onlyMainContent` | boolean | true | Extract main content only |
+
+**Action Types:**
+
+- `click` - Click an element
+- `scroll` - Scroll page or to element
+- `write` - Type text into input
+- `wait` - Wait for time or element
+- `press` - Press keyboard key
+- `screenshot` - Capture screenshot
+- `hover` - Hover over element
+- `select` - Select dropdown option
+
 ### Status - Job Management
 
 ```typescript
@@ -406,6 +550,7 @@ const stats = await client.keys.getStats(keyId, { days: 30 });
 | `crawl`           | `POST /v1/crawl`        | Create crawl jobs        |
 | `dork`            | `POST /v1/dork`         | Create dork searches     |
 | `extract`         | `POST /v1/extract`      | Create extraction jobs   |
+| `agent`           | `POST /v1/agent`        | Create AI agent jobs     |
 | `status`          | `GET /v1/status/:id`    | Read job status          |
 | `data:read`       | `GET /v1/data/*`        | Read jobs/deals          |
 | `data:export`     | `GET /v1/data/export`   | Export data              |
@@ -435,10 +580,13 @@ await client.keys.create({
     "crawl",
     "dork",
     "extract",
+    "agent",
+    "search",
     "status",
     "data:read",
     "data:export",
     "keys:manage",
+    "webhooks:manage",
   ],
 });
 ```
@@ -587,14 +735,27 @@ import type {
 
   // Request Options
   ScrapeOptions,
+  BatchScrapeOptions,
   CrawlOptions,
+  CrawlPriority,
+  CrawlCategory,
+  PriceRange,
+  SearchOptions,
   ExtractOptions,
   DorkOptions,
+  AgentOptions,
+  SchemaGenerationOptions,
 
   // Responses
   JobStatusResponse,
   ListDealsResponse,
   DealItem,
+  AgentJobResponse,
+  AgentStatusResponse,
+  AgentResultResponse,
+  SchemaGenerationResponse,
+  SearchJobResponse,
+  BatchScrapeResponse,
 
   // Re-exports from @dealcrawl/shared
   ScrapeResult,

package/dist/index.d.mts

@@ -81,6 +81,16 @@ interface OpenGraphMetadata {
     locale?: string;
     localeAlternate?: string[];
 }
+/** Type d'engine de scraping */
+type EngineType = "static" | "dynamic" | "stealth";
+/** Mode de sélection d'engine pour le crawl */
+type CrawlMode = "static" | "auto";
+/** Détails de sélection d'engine */
+interface EngineSelection {
+    engine: EngineType;
+    reason: string;
+    confidence: number;
+}
 interface ParsedPage {
     url: string;
     depth?: number;
@@ -99,6 +109,10 @@ interface ParsedPage {
     statusCode?: number;
     crawlDurationMs?: number;
     signals?: Signal[];
+    /** Engine used to fetch this page */
+    engine?: EngineType;
+    /** Engine selection details */
+    engineSelection?: EngineSelection;
 }
 interface DealScoreSummary {
     score: number;
@@ -222,6 +236,69 @@ interface DorkResult {
     totalResults?: number;
     searchedAt: string;
 }
+/** Source of extraction result */
+type FallbackSource = "primary" | "retry" | "heuristic" | "default";
+/** Result from fallback extraction */
+interface FallbackResult<T> {
+    /** Extracted data */
+    data: T;
+    /** Source of the extraction */
+    source: FallbackSource;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Metadata about the extraction process */
+    metadata: FallbackMetadata;
+}
+/** Metadata about fallback extraction */
+interface FallbackMetadata {
+    /** Total attempts made */
+    attempts: number;
+    /** Errors encountered during extraction */
+    errors: string[];
+    /** Time taken in milliseconds */
+    durationMs: number;
+    /** Fields that used default values */
+    defaultedFields?: string[];
+    /** Fields that were transformed */
+    transformedFields?: string[];
+}
+/** Configuration for fallback behavior */
+interface FallbackConfig {
+    /** Enable automatic retry (default: true) */
+    enableRetry?: boolean;
+    /** Maximum retry attempts (default: 2) */
+    maxRetries?: number;
+    /** Enable heuristic fallback (default: true) */
+    enableHeuristic?: boolean;
+    /** Enable default value fallback (default: true) */
+    enableDefault?: boolean;
+    /** Minimum confidence to accept result (default: 0.5) */
+    minConfidence?: number;
+}
+/** Validation result for extracted data */
+interface ValidationResult<T> {
+    /** Whether validation passed */
+    success: boolean;
+    /** Validated and transformed data */
+    data?: T;
+    /** Validation errors */
+    errors: ValidationError[];
+    /** Fields that received default values */
+    defaultedFields: string[];
+    /** Fields that were transformed */
+    transformedFields: string[];
+}
+/** Individual validation error */
+interface ValidationError {
+    /** Path to the field that failed validation */
+    path: string;
+    /** Error message */
+    message: string;
+    /** Expected value or type */
+    expected?: string;
+    /** Received value */
+    received?: unknown;
+}
 
 /**
  * SDK Configuration options
@@ -932,6 +1009,8 @@ interface ScreenshotOptions {
 interface ScrapeOptions {
     /** URL to scrape (required) */
     url: string;
+    /** Don't save scrape results - Zero Data Retention (Pro/Enterprise only) */
+    noStore?: boolean;
     /** Detect signals like prices, discounts, urgency (default: true) */
     detectSignals?: boolean;
     /** Extract content using AI */
@@ -1071,6 +1150,17 @@ interface SearchOptions {
         headers?: Record<string, string>;
     };
 }
+/** Crawl priority queue (enterprise only) */
+type CrawlPriority = "high" | "medium" | "low";
+/** Product category filter for crawls */
+type CrawlCategory = "courses" | "software" | "physical" | "services" | "other";
+/** Price range filter for crawls */
+interface PriceRange {
+    /** Minimum price */
+    min?: number;
+    /** Maximum price */
+    max?: number;
+}
 /** Options for crawling a website */
 interface CrawlOptions {
     /** Starting URL for the crawl (required) */
@@ -1091,7 +1181,7 @@ interface CrawlOptions {
     extractWithAI?: boolean;
     /** Extract deal-specific information from each page */
     extractDeal?: boolean;
-    /** Minimum deal score threshold (0-100) */
+    /** Minimum deal score threshold (0-100, default: 30) */
     minDealScore?: number;
     /** Prioritize pages likely to contain deals (default: true) */
     prioritizeDealPages?: boolean;
@@ -1101,6 +1191,34 @@ interface CrawlOptions {
     allowedDomains?: string[];
     /** URL patterns to exclude from crawling */
     excludePatterns?: string[];
+    /** Filter by product categories */
+    categories?: CrawlCategory[];
+    /** Filter by price range */
+    priceRange?: PriceRange;
+    /** Prefer static scraping (faster, default: true) */
+    preferStatic?: boolean;
+    /** Require JavaScript rendering for all pages */
+    requireJS?: boolean;
+    /** Use advanced anti-bot bypass techniques */
+    bypassAntiBot?: boolean;
+    /** Only return high-quality deals (score >= 70) */
+    onlyHighQuality?: boolean;
+    /** Only crawl pages from these merchants */
+    allowedMerchants?: string[];
+    /** Skip pages from these merchants */
+    blockedMerchants?: string[];
+    /** Webhook URL for real-time notifications */
+    webhookUrl?: string;
+    /** Auto-sync discovered deals to DealUp */
+    syncToDealup?: boolean;
+    /** Site-specific config name from registry */
+    siteConfig?: string;
+    /** Job template to use (ecommerce, blog, docs, marketplace, custom) */
+    template?: CrawlTemplateId;
+    /** Use smart job routing to auto-detect best settings (default: true) */
+    useSmartRouting?: boolean;
+    /** Priority queue override (Enterprise only) */
+    priority?: CrawlPriority;
 }
 /** Crawl template identifier */
 type CrawlTemplateId = "ecommerce" | "blog" | "docs" | "marketplace" | "custom";
@@ -1273,7 +1391,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" | "agent" | "status" | "data:read" | "data:export" | "keys:manage" | "webhooks:manage";
+type ApiKeyScope = "scrape" | "scrape:batch" | "search" | "crawl" | "dork" | "extract" | "agent" | "status" | "data:read" | "data:export" | "keys:manage" | "webhooks:manage";
 /**
  * All available scopes (for reference and validation)
  */
@@ -3127,33 +3245,162 @@ declare class DealCrawl {
 }
 
 /**
- * Error codes used by DealCrawl API
- * Copied from @dealcrawl/shared to avoid bundling the entire package
+ * Error codes used by DealCrawl API (SEC-005 compliant)
+ *
+ * Machine-readable error codes for API responses.
+ * These codes are stable identifiers that clients can programmatically handle.
+ *
+ * @see https://docs.dealcrawl.dev/api/errors for full documentation
  */
 declare const ERROR_CODES: {
-    readonly INVALID_API_KEY: "INVALID_API_KEY";
-    readonly MISSING_API_KEY: "MISSING_API_KEY";
-    readonly API_KEY_EXPIRED: "API_KEY_EXPIRED";
-    readonly ACCOUNT_SUSPENDED: "ACCOUNT_SUSPENDED";
+    /** Missing or invalid Authorization header */
+    readonly AUTH_MISSING_HEADER: "AUTH_MISSING_HEADER";
+    /** The provided API key is invalid or expired */
+    readonly AUTH_INVALID_API_KEY: "AUTH_INVALID_API_KEY";
+    /** Your API key has expired */
+    readonly AUTH_API_KEY_EXPIRED: "AUTH_API_KEY_EXPIRED";
+    /** Your API key has been revoked */
+    readonly AUTH_API_KEY_REVOKED: "AUTH_API_KEY_REVOKED";
+    /** API key does not have required permissions */
+    readonly AUTH_INSUFFICIENT_SCOPE: "AUTH_INSUFFICIENT_SCOPE";
+    /** Your account has been suspended */
+    readonly AUTH_ACCOUNT_SUSPENDED: "AUTH_ACCOUNT_SUSPENDED";
+    /** @deprecated Use AUTH_INVALID_API_KEY instead */
+    readonly INVALID_API_KEY: "AUTH_INVALID_API_KEY";
+    /** @deprecated Use AUTH_MISSING_HEADER instead */
+    readonly MISSING_API_KEY: "AUTH_MISSING_HEADER";
+    /** @deprecated Use AUTH_API_KEY_EXPIRED instead */
+    readonly API_KEY_EXPIRED: "AUTH_API_KEY_EXPIRED";
+    /** @deprecated Use AUTH_ACCOUNT_SUSPENDED instead */
+    readonly ACCOUNT_SUSPENDED: "AUTH_ACCOUNT_SUSPENDED";
+    /** Rate limit exceeded. Please try again later */
     readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
-    readonly QUOTA_EXCEEDED: "QUOTA_EXCEEDED";
-    readonly INVALID_URL: "INVALID_URL";
-    readonly INVALID_REQUEST: "INVALID_REQUEST";
-    readonly MISSING_REQUIRED_FIELD: "MISSING_REQUIRED_FIELD";
-    readonly JOB_NOT_FOUND: "JOB_NOT_FOUND";
-    readonly JOB_FAILED: "JOB_FAILED";
+    /** Monthly quota exceeded. Upgrade your plan for more */
+    readonly RATE_QUOTA_EXCEEDED: "RATE_QUOTA_EXCEEDED";
+    /** Concurrent job limit reached */
+    readonly RATE_CONCURRENT_LIMIT: "RATE_CONCURRENT_LIMIT";
+    /** @deprecated Use RATE_QUOTA_EXCEEDED instead */
+    readonly QUOTA_EXCEEDED: "RATE_QUOTA_EXCEEDED";
+    /** The provided input is invalid */
+    readonly VALID_INVALID_INPUT: "VALID_INVALID_INPUT";
+    /** Required field is missing */
+    readonly VALID_MISSING_FIELD: "VALID_MISSING_FIELD";
+    /** The provided URL is not valid */
+    readonly VALID_INVALID_URL: "VALID_INVALID_URL";
+    /** Invalid schema format */
+    readonly VALID_INVALID_SCHEMA: "VALID_INVALID_SCHEMA";
+    /** Invalid format */
+    readonly VALID_INVALID_FORMAT: "VALID_INVALID_FORMAT";
+    /** @deprecated Use VALID_INVALID_URL instead */
+    readonly INVALID_URL: "VALID_INVALID_URL";
+    /** @deprecated Use VALID_INVALID_INPUT instead */
+    readonly INVALID_REQUEST: "VALID_INVALID_INPUT";
+    /** @deprecated Use VALID_MISSING_FIELD instead */
+    readonly MISSING_REQUIRED_FIELD: "VALID_MISSING_FIELD";
+    /** The requested resource was not found */
+    readonly RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND";
+    /** Job not found */
+    readonly RESOURCE_JOB_NOT_FOUND: "RESOURCE_JOB_NOT_FOUND";
+    /** Webhook not found */
+    readonly RESOURCE_WEBHOOK_NOT_FOUND: "RESOURCE_WEBHOOK_NOT_FOUND";
+    /** API key not found */
+    readonly RESOURCE_KEY_NOT_FOUND: "RESOURCE_KEY_NOT_FOUND";
+    /** @deprecated Use RESOURCE_JOB_NOT_FOUND instead */
+    readonly JOB_NOT_FOUND: "RESOURCE_JOB_NOT_FOUND";
+    /** Failed to create job */
+    readonly JOB_CREATION_FAILED: "JOB_CREATION_FAILED";
+    /** Job timed out */
     readonly JOB_TIMEOUT: "JOB_TIMEOUT";
-    readonly FETCH_FAILED: "FETCH_FAILED";
-    readonly PARSE_FAILED: "PARSE_FAILED";
-    readonly BLOCKED_BY_ROBOTS: "BLOCKED_BY_ROBOTS";
-    readonly CAPTCHA_DETECTED: "CAPTCHA_DETECTED";
-    readonly SITE_UNREACHABLE: "SITE_UNREACHABLE";
+    /** Job processing failed */
+    readonly JOB_FAILED: "JOB_FAILED";
+    /** Job was cancelled */
+    readonly JOB_CANCELLED: "JOB_CANCELLED";
+    /** Failed to fetch URL */
+    readonly SCRAPE_FETCH_FAILED: "SCRAPE_FETCH_FAILED";
+    /** Failed to parse page content */
+    readonly SCRAPE_PARSE_FAILED: "SCRAPE_PARSE_FAILED";
+    /** URL is blocked by robots.txt */
+    readonly SCRAPE_BLOCKED_BY_ROBOTS: "SCRAPE_BLOCKED_BY_ROBOTS";
+    /** CAPTCHA detected on page */
+    readonly SCRAPE_CAPTCHA_DETECTED: "SCRAPE_CAPTCHA_DETECTED";
+    /** Site is unreachable */
+    readonly SCRAPE_SITE_UNREACHABLE: "SCRAPE_SITE_UNREACHABLE";
+    /** Scraping operation timed out */
+    readonly SCRAPE_TIMEOUT: "SCRAPE_TIMEOUT";
+    /** @deprecated Use SCRAPE_FETCH_FAILED instead */
+    readonly FETCH_FAILED: "SCRAPE_FETCH_FAILED";
+    /** @deprecated Use SCRAPE_PARSE_FAILED instead */
+    readonly PARSE_FAILED: "SCRAPE_PARSE_FAILED";
+    /** @deprecated Use SCRAPE_BLOCKED_BY_ROBOTS instead */
+    readonly BLOCKED_BY_ROBOTS: "SCRAPE_BLOCKED_BY_ROBOTS";
+    /** @deprecated Use SCRAPE_CAPTCHA_DETECTED instead */
+    readonly CAPTCHA_DETECTED: "SCRAPE_CAPTCHA_DETECTED";
+    /** @deprecated Use SCRAPE_SITE_UNREACHABLE instead */
+    readonly SITE_UNREACHABLE: "SCRAPE_SITE_UNREACHABLE";
+    /** A webhook with this event and URL already exists */
+    readonly WEBHOOK_ALREADY_EXISTS: "WEBHOOK_ALREADY_EXISTS";
+    /** Webhook URL is not valid or not publicly accessible */
+    readonly WEBHOOK_INVALID_URL: "WEBHOOK_INVALID_URL";
+    /** Webhook replay attack detected */
+    readonly WEBHOOK_REPLAY_DETECTED: "WEBHOOK_REPLAY_DETECTED";
+    /** Webhook request is too old */
+    readonly WEBHOOK_EXPIRED: "WEBHOOK_EXPIRED";
+    /** Webhook signature is invalid */
+    readonly WEBHOOK_INVALID_SIGNATURE: "WEBHOOK_INVALID_SIGNATURE";
+    /** AI extraction failed to process content */
+    readonly AI_EXTRACTION_FAILED: "AI_EXTRACTION_FAILED";
+    /** Failed to parse JSON from AI response */
+    readonly AI_JSON_PARSE_FAILED: "AI_JSON_PARSE_FAILED";
+    /** AI response did not match expected schema */
+    readonly AI_SCHEMA_VALIDATION_FAILED: "AI_SCHEMA_VALIDATION_FAILED";
+    /** No price information could be extracted */
+    readonly AI_NO_PRICE_FOUND: "AI_NO_PRICE_FOUND";
+    /** Extraction confidence is below acceptable threshold */
+    readonly AI_LOW_CONFIDENCE: "AI_LOW_CONFIDENCE";
+    /** Only partial data could be extracted */
+    readonly AI_PARTIAL_RESULT: "AI_PARTIAL_RESULT";
+    /** Fallback extraction was used */
+    readonly AI_FALLBACK_USED: "AI_FALLBACK_USED";
+    /** All fallback strategies failed */
+    readonly AI_FALLBACK_FAILED: "AI_FALLBACK_FAILED";
+    /** LLM provider rate limit exceeded */
+    readonly AI_PROVIDER_RATE_LIMIT: "AI_PROVIDER_RATE_LIMIT";
+    /** LLM provider authentication failed */
+    readonly AI_PROVIDER_AUTH_FAILED: "AI_PROVIDER_AUTH_FAILED";
+    /** LLM provider timeout */
+    readonly AI_PROVIDER_TIMEOUT: "AI_PROVIDER_TIMEOUT";
+    /** An internal server error occurred */
     readonly INTERNAL_ERROR: "INTERNAL_ERROR";
-    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
-    readonly REDIS_ERROR: "REDIS_ERROR";
+    /** Database operation failed */
     readonly DATABASE_ERROR: "DATABASE_ERROR";
+    /** Redis operation failed */
+    readonly REDIS_ERROR: "REDIS_ERROR";
+    /** External service error */
+    readonly EXTERNAL_SERVICE_ERROR: "EXTERNAL_SERVICE_ERROR";
+    /** Service is temporarily unavailable */
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
 };
 type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * Details for AI extraction errors
+ */
+interface ExtractionErrorDetails {
+    /** Fields that failed validation */
+    failedFields?: string[];
+    /** Fields that could not be extracted */
+    missingFields?: string[];
+    /** Validation errors from schema */
+    validationErrors?: Array<{
+        field: string;
+        message: string;
+    }>;
+    /** Extraction confidence score (0-1) */
+    confidence?: number;
+    /** Whether fallback was used */
+    fallbackUsed?: boolean;
+    /** Source of the extraction */
+    source?: "ai" | "heuristic" | "fallback";
+}
 /**
  * Custom error class for DealCrawl SDK
  * Provides structured error handling with error codes
@@ -3176,7 +3423,7 @@ declare class DealCrawlError extends Error {
     });
     /**
      * Check if the error is retryable
-     * Rate limits and transient errors are retryable
+     * Rate limits, transient errors, and AI provider issues are retryable
      */
     isRetryable(): boolean;
     /**
@@ -3191,6 +3438,54 @@ declare class DealCrawlError extends Error {
      * Check if the error is due to quota exceeded
      */
     isQuotaExceeded(): boolean;
+    /**
+     * Check if the error is due to AI extraction issues
+     */
+    isExtractionError(): boolean;
+    /**
+     * Check if result is partial (some data extracted but incomplete)
+     */
+    isPartialResult(): boolean;
+    /**
+     * Check if extraction failed due to schema validation
+     */
+    isSchemaValidationError(): boolean;
+    /**
+     * Check if the error is due to validation issues
+     */
+    isValidationError(): boolean;
+    /**
+     * Check if the error is due to scraping issues
+     */
+    isScrapeError(): boolean;
+    /**
+     * Check if the error is due to webhook issues
+     */
+    isWebhookError(): boolean;
+    /**
+     * Check if the error is a server error (5xx)
+     */
+    isServerError(): boolean;
+    /**
+     * Check if the error is a client error (4xx)
+     */
+    isClientError(): boolean;
+    /**
+     * Check if fallback was used during extraction
+     */
+    isFallbackUsed(): boolean;
+    /**
+     * Check if all fallback strategies failed
+     */
+    isFallbackFailed(): boolean;
+    /**
+     * Check if error is due to AI provider issues
+     */
+    isAIProviderError(): boolean;
+    /**
+     * Get extraction-specific error details
+     */
+    getExtractionDetails(): ExtractionErrorDetails | undefined;
     /**
      * Convert error to JSON-serializable object
      */
@@ -3206,5 +3501,13 @@ declare class DealCrawlError extends Error {
         retryAfter?: number;
     }, retryAfter?: number | string | null): DealCrawlError;
 }
+/**
+ * Human-readable error messages for all error codes
+ */
+declare const ERROR_MESSAGES: Record<ErrorCode, string>;
+/**
+ * Get human-readable message for error code
+ */
+declare function getErrorMessage(code: ErrorCode): string;
 
-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 };
+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 CrawlError, type CrawlJobResponse, type CrawlMode, type CrawlOptions, type CrawlRecommendation, CrawlResource, type CrawlResult, type CrawlStats, 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, ERROR_MESSAGES, type EngineSelection, type EngineType, type ErrorCode, type ExportDealsOptions, type ExportFormat, type ExportJobsOptions, type ExtractJobResponse, type ExtractModel, type ExtractOptions, ExtractResource, type ExtractedDeal, type ExtractionErrorDetails, type FallbackConfig, type FallbackMetadata, type FallbackResult, type FallbackSource, 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 ScreenshotResult, 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 UrgencyLevel, type UsageStats, type ValidationError, type ValidationResult, type WaitAction, type WaitOptions, type WaitResult, type WebhookEvent, type WebhookItem, WebhooksResource, type WriteAction, DealCrawl as default, getErrorMessage, pollUntil, waitForAll, waitForAny, waitForResult };