@dealcrawl/sdk 2.5.0 → 2.6.0

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
@@ -3168,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
@@ -3217,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;
     /**
@@ -3232,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
      */
@@ -3247,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 };