@dealcrawl/sdk 2.1.3 → 2.2.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 */
@@ -727,6 +862,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 +883,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) */
@@ -947,6 +1198,14 @@ interface UpdateWebhookOptions {
  * 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";
+/**
+ * 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 +1227,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 */
@@ -1665,10 +1929,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 +1975,7 @@ declare class KeysResource {
 
 /**
  * Scrape Resource
- * Handles single page scraping operations
+ * Handles single page and batch scraping operations
  */
 
 /**
@@ -1739,6 +2009,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 +2035,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 +2431,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
      *
@@ -2249,6 +2669,20 @@ 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"]>>;
 }
 
 /**
@@ -2332,4 +2766,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 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 };