@dealcrawl/sdk 2.1.1 → 2.1.3

package/dist/index.d.mts

@@ -0,0 +1,2335 @@
+/**
+ * Shared types for DealCrawl SDK
+ * These types are copied from @dealcrawl/shared to avoid bundling
+ * the entire shared package (which includes Redis, etc.)
+ */
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: ApiError;
+    meta?: ResponseMeta;
+}
+interface ApiError {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface ResponseMeta {
+    requestId: string;
+    timestamp: string;
+    duration?: number;
+}
+type JobStatus = "pending" | "active" | "completed" | "failed" | "delayed" | "paused";
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        hasMore: boolean;
+    };
+}
+interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    reset: number;
+}
+interface Signal {
+    type: string;
+    value: string;
+    confidence: number;
+    metadata?: Record<string, unknown>;
+}
+interface DealSignal extends Signal {
+    type: "price" | "original_price" | "discount" | "discount_amount" | "sale_indicator" | "deal_score" | "urgency_level" | "is_legit_deal";
+}
+interface PriceSignal extends DealSignal {
+    type: "price" | "original_price";
+    metadata: {
+        currency: string;
+        raw: string;
+        source: "json-ld" | "og-meta" | "microdata" | "regex" | "css-selector";
+    };
+}
+interface DiscountSignal extends DealSignal {
+    type: "discount" | "discount_amount";
+    metadata: {
+        percent?: number;
+        amount?: number;
+        currency?: string;
+        raw?: string;
+        calculated?: boolean;
+        source: string;
+    };
+}
+interface LinkMetadata {
+    total: number;
+    internal: string[];
+    external: string[];
+}
+interface ImageMetadata {
+    total: number;
+    urls: string[];
+}
+interface OpenGraphMetadata {
+    title?: string;
+    description?: string;
+    image?: string;
+    url?: string;
+    siteName?: string;
+    type?: string;
+    locale?: string;
+    localeAlternate?: string[];
+}
+interface ParsedPage {
+    url: string;
+    depth?: number;
+    title?: string;
+    description?: string;
+    content?: string;
+    language?: string;
+    /** @deprecated Use linksMetadata instead */
+    links?: string[];
+    linksMetadata?: LinkMetadata;
+    /** @deprecated Use imagesMetadata instead */
+    images?: string[];
+    imagesMetadata?: ImageMetadata;
+    openGraph?: OpenGraphMetadata;
+    metadata?: Record<string, unknown>;
+    statusCode?: number;
+    crawlDurationMs?: number;
+    signals?: Signal[];
+}
+interface DealScoreSummary {
+    score: number;
+    quality: "excellent" | "good" | "average" | "poor" | "very_poor";
+    recommendation: "highly_recommended" | "recommended" | "consider" | "skip";
+    breakdown: {
+        discount: number;
+        urgency: number;
+        legitimacy: number;
+        priceClarity: number;
+        productInfo: number;
+    };
+}
+interface ScreenshotResult {
+    url: string;
+    width: number;
+    height: number;
+    format: "png" | "jpeg" | "webp";
+    sizeBytes: number;
+}
+interface AIExtraction {
+    summary?: string;
+    entities?: Entity[];
+    sentiment?: "positive" | "negative" | "neutral";
+    topics?: string[];
+    raw?: Record<string, unknown>;
+}
+interface Entity {
+    type: "person" | "organization" | "location" | "product" | "other";
+    value: string;
+    confidence: number;
+}
+interface ScrapeResult {
+    url: string;
+    parsed: ParsedPage;
+    signals: Signal[];
+    aiExtraction?: AIExtraction;
+    dealExtraction?: ExtractedDeal;
+    dealScore?: DealScoreSummary;
+    screenshot?: string;
+    screenshotMetadata?: ScreenshotResult;
+    scrapedAt: string;
+}
+type UrgencyLevel = "none" | "low" | "medium" | "high" | "critical";
+interface ExtractedDeal {
+    id: string;
+    sourceUrl: string;
+    product: {
+        name: string;
+        brand?: string;
+        category?: string;
+        description?: string;
+        imageUrl?: string;
+        sku?: string;
+    };
+    pricing: {
+        currentPrice: number;
+        originalPrice?: number;
+        discountPercent?: number;
+        savedAmount?: number;
+        currency: string;
+        priceConfidence: number;
+    };
+    quality: {
+        dealScore: number;
+        urgencyLevel: UrgencyLevel;
+        isLegitDeal: boolean;
+        legitimacyScore: number;
+    };
+    merchant: string;
+    affiliateEligible?: boolean;
+    expiresAt?: string;
+    crawledAt: string;
+    rawSignals?: Signal[];
+}
+interface CrawlError {
+    url: string;
+    error: string;
+    timestamp: string;
+}
+interface CrawlStats {
+    totalUrlsDiscovered?: number;
+    urlsSkipped?: number;
+    avgDealScore?: number;
+    highValuePages?: number;
+    pagesScraped?: number;
+    totalPagesFound?: number;
+    linksFound?: number;
+    depth?: number;
+    errors?: number;
+}
+interface CrawlResult {
+    startUrl: string;
+    pagesFound: number;
+    pages: ParsedPage[];
+    crawledAt: string;
+    duration?: number;
+    errors?: CrawlError[];
+    stats?: CrawlStats;
+}
+interface DorkSearchResult {
+    url: string;
+    title: string;
+    snippet: string;
+    position: number;
+    metadata?: Record<string, unknown>;
+}
+interface DorkResult {
+    query: string;
+    site?: string;
+    results: DorkSearchResult[];
+    totalResults?: number;
+    searchedAt: string;
+}
+
+/**
+ * SDK Configuration options
+ */
+interface DealCrawlConfig {
+    /** API key for authentication (required) */
+    apiKey: string;
+    /** Base URL for the API (default: https://api.dealcrawl.dev) */
+    baseUrl?: string;
+    /** Default timeout for requests in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum number of retries for failed requests (default: 3) */
+    maxRetries?: number;
+    /** Delay between retries in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** Callback when rate limit is hit */
+    onRateLimit?: (info: RateLimitInfo) => void;
+}
+/**
+ * Internal request context passed to resources
+ */
+interface RequestContext {
+    /** Base URL for API requests */
+    baseUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Default timeout in milliseconds */
+    timeout: number;
+    /** Maximum number of retries */
+    maxRetries: number;
+    /** Delay between retries in milliseconds */
+    retryDelay: number;
+    /** Rate limit callback */
+    onRateLimit?: (info: RateLimitInfo) => void;
+}
+/**
+ * Default configuration values
+ */
+declare const DEFAULT_CONFIG: {
+    readonly baseUrl: "https://api.dealcrawl.dev";
+    readonly timeout: 30000;
+    readonly maxRetries: 3;
+    readonly retryDelay: 1000;
+};
+
+/**
+ * SDK Response Types
+ * Types for API responses
+ */
+
+/** Base job response from API */
+interface JobResponse {
+    /** Unique job identifier */
+    jobId: string;
+    /** Current job status */
+    status: JobStatus;
+    /** URL to check job status */
+    statusUrl: string;
+    /** Estimated time to completion */
+    estimatedTime?: string;
+}
+/** Pagination info */
+interface PaginationInfo {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+/** Scrape job creation response */
+interface ScrapeJobResponse extends JobResponse {
+}
+/** Crawl job creation response */
+interface CrawlJobResponse extends JobResponse {
+}
+/** Crawl analysis response */
+interface CrawlAnalysisResponse {
+    url: string;
+    domain: string;
+    recommendedTemplate?: string;
+    estimatedPages: number;
+    suggestedSettings: {
+        maxDepth: number;
+        maxPages: number;
+        delayMs: number;
+        excludePatterns: string[];
+    };
+    sitemapFound: boolean;
+    robotsTxtRules?: string[];
+}
+/** Extract job creation response */
+interface ExtractJobResponse extends JobResponse {
+}
+/** Dork job creation response */
+interface DorkJobResponse extends JobResponse {
+}
+/** Deal metrics from a job */
+interface DealMetrics {
+    totalDeals: number;
+    avgScore: number;
+    highestScore: number;
+    legitDeals: number;
+    categories: Record<string, number>;
+}
+/** Checkpoint info for resumable jobs */
+interface CheckpointInfo {
+    canResume: boolean;
+    lastProcessedUrl?: string;
+    urlsProcessed: number;
+    urlsRemaining: number;
+    savedAt: string;
+}
+/** Job status response */
+interface JobStatusResponse {
+    jobId: string;
+    status: JobStatus;
+    progress?: number;
+    createdAt: string;
+    completedAt?: string;
+    failedAt?: string;
+    priorityQueue?: string;
+    result?: unknown;
+    error?: string;
+    dealMetrics?: DealMetrics;
+    checkpoint?: CheckpointInfo;
+}
+/** Job deals response */
+interface JobDealsResponse {
+    jobId: string;
+    deals: DealSummary[];
+    count: number;
+    metrics?: DealMetrics;
+}
+/** Deal summary from status endpoint */
+interface DealSummary {
+    id: string;
+    sourceUrl: string;
+    productName: string;
+    currentPrice: number;
+    originalPrice?: number;
+    discountPercent?: number;
+    dealScore: number;
+    category?: string;
+    merchant?: string;
+}
+/** Job resume response */
+interface ResumeJobResponse {
+    success: boolean;
+    originalJobId: string;
+    newJobId: string;
+    message: string;
+}
+/** Job metrics response */
+interface JobMetricsResponse {
+    jobId: string;
+    status: JobStatus;
+    metrics: {
+        totalUrls: number;
+        successfulUrls: number;
+        failedUrls: number;
+        successRate: number;
+        avgProcessingTime?: number;
+    };
+}
+/** Cancel job response */
+interface CancelJobResponse {
+    success: boolean;
+    jobId: string;
+    message: string;
+}
+/** Job summary in list */
+interface JobSummary {
+    id: string;
+    type: "scrape" | "crawl" | "dork" | "extract";
+    status: JobStatus;
+    input: Record<string, unknown>;
+    dealsFound?: number;
+    avgDealScore?: number;
+    highestDealScore?: number;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}
+/** Jobs list response */
+interface ListJobsResponse {
+    data: JobSummary[];
+    pagination: PaginationInfo;
+}
+/** Product info in deal */
+interface ProductInfo {
+    name: string;
+    brand?: string;
+    category?: string;
+    description?: string;
+    imageUrl?: string;
+}
+/** Pricing info in deal */
+interface PricingInfo {
+    currentPrice: number;
+    originalPrice?: number;
+    discountPercent?: number;
+    currency: string;
+}
+/** Deal in list */
+interface DealItem {
+    id: string;
+    jobId: string;
+    sourceUrl: string;
+    product: ProductInfo;
+    pricing: PricingInfo;
+    dealScore: number;
+    urgencyLevel?: string;
+    isLegitDeal: boolean;
+    merchant?: string;
+    affiliateEligible?: boolean;
+    syncedToDealup: boolean;
+    dealupDealId?: string;
+    createdAt: string;
+}
+/** Deals list response */
+interface ListDealsResponse {
+    data: DealItem[];
+    pagination: PaginationInfo;
+}
+/** Full deal details */
+interface DealDetails extends DealItem {
+    rawSignals?: unknown;
+    aiExtraction?: unknown;
+    updatedAt: string;
+}
+/** Client stats response */
+interface ClientStatsResponse {
+    period: string;
+    totals: {
+        jobs: number;
+        deals: number;
+        scrapes: number;
+        crawls: number;
+        dorks: number;
+    };
+    performance: {
+        avgSuccessRate: number;
+        avgDealScore: number;
+        topCategories: Array<{
+            category: string;
+            count: number;
+        }>;
+    };
+}
+/** Webhook in list */
+interface WebhookItem {
+    id: string;
+    event: string;
+    url: string;
+    minDealScore: number;
+    categories?: string[];
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+    lastTriggeredAt?: string;
+    triggerCount: number;
+    failureCount: number;
+}
+/** Create webhook response */
+interface CreateWebhookResponse {
+    success: boolean;
+    webhookId: string;
+    event: string;
+    url: string;
+    minDealScore: number;
+    active: boolean;
+}
+/** List webhooks response */
+interface ListWebhooksResponse {
+    webhooks: WebhookItem[];
+    count: number;
+}
+/** Update webhook response */
+interface UpdateWebhookResponse {
+    success: boolean;
+    webhook: WebhookItem;
+}
+/** Delete webhook response */
+interface DeleteWebhookResponse {
+    success: boolean;
+    webhookId: string;
+    message: string;
+}
+/** Test webhook response */
+interface TestWebhookResponse {
+    success: boolean;
+    webhookId: string;
+    delivered: boolean;
+    statusCode?: number;
+    responseTime?: number;
+    error?: string;
+}
+/** API key info (safe, without secret) */
+interface ApiKeyInfo {
+    id: string;
+    name: string;
+    prefix: string;
+    scopes: string[];
+    isActive: boolean;
+    expiresAt?: string;
+    lastUsedAt?: string;
+    createdAt: string;
+    usageCount: number;
+    ipAllowlist?: string[];
+}
+/** Created API key (includes secret - only shown once) */
+interface CreatedApiKey extends ApiKeyInfo {
+    /** The full API key - only returned on creation, never stored */
+    key: string;
+}
+/** List keys response */
+interface ListKeysResponse {
+    keys: ApiKeyInfo[];
+    count: number;
+    activeCount: number;
+}
+/** Create key response */
+interface CreateKeyResponse extends CreatedApiKey {
+    warning: string;
+}
+/** Rotate key response */
+interface RotateKeyResponse {
+    oldKeyId: string;
+    oldKeyRevoked: boolean;
+    newKey: CreateKeyResponse;
+}
+/** Delete key response */
+interface DeleteKeyResponse {
+    success: boolean;
+    keyId: string;
+    message: string;
+}
+/** Key stats response */
+interface KeyStatsResponse {
+    keyId: string;
+    keyName: string;
+    period: string;
+    stats: {
+        totalRequests: number;
+        successfulRequests: number;
+        failedRequests: number;
+        byEndpoint: Record<string, number>;
+    };
+}
+/** Usage stats */
+interface UsageStats {
+    scrapes: {
+        used: number;
+        limit: number;
+    };
+    crawls: {
+        used: number;
+        limit: number;
+    };
+    dorks: {
+        used: number;
+        limit: number;
+    };
+    period: string;
+    resetAt: string;
+}
+/** Client preferences */
+interface ClientPreferences {
+    preferredCategories?: string[];
+    minDealScore?: number;
+    autoSync?: boolean;
+    webhookEnabled?: boolean;
+}
+/** Account info response */
+interface AccountInfoResponse {
+    id: string;
+    name: string;
+    tier: "free" | "pro" | "enterprise";
+    usage: UsageStats;
+    dealMetrics?: DealMetrics;
+    preferences: ClientPreferences;
+}
+/** Account metrics response */
+interface AccountMetricsResponse {
+    dealMetrics: DealMetrics;
+    categoryPerformance: Array<{
+        category: string;
+        totalDeals: number;
+        avgScore: number;
+        syncRate: number;
+    }>;
+}
+/** DealUp sync metrics */
+interface DealUpMetrics {
+    totalSynced: number;
+    pendingSync: number;
+    syncErrors: number;
+    lastSyncAt?: string;
+    clicksGenerated: number;
+    revenue?: number;
+}
+/** DealUp metrics response */
+interface DealUpMetricsResponse {
+    sync: DealUpMetrics;
+    tier: string;
+}
+/** Crawl recommendation */
+interface CrawlRecommendation {
+    url: string;
+    domain: string;
+    reason: string;
+    estimatedDeals: number;
+    confidence: number;
+}
+/** Recommendations response */
+interface RecommendationsResponse {
+    recommendations: CrawlRecommendation[];
+    count: number;
+}
+/** Preferences response */
+interface PreferencesResponse {
+    preferences: ClientPreferences;
+}
+/** Update preferences response */
+interface UpdatePreferencesResponse {
+    success: boolean;
+    preferences: ClientPreferences;
+}
+
+/**
+ * Polling Utilities
+ * Helpers for waiting on async job completion
+ */
+
+/** Options for waiting on a job */
+interface WaitOptions {
+    /** Polling interval in milliseconds (default: 2000) */
+    pollInterval?: number;
+    /** Maximum time to wait in milliseconds (default: 300000 = 5 minutes) */
+    timeout?: number;
+    /** Callback on each poll */
+    onProgress?: (status: JobStatusResponse) => void;
+    /** Callback on status change */
+    onStatusChange?: (newStatus: string, oldStatus: string) => void;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+/** Result of waiting for a job */
+interface WaitResult<T = unknown> {
+    /** Job ID */
+    jobId: string;
+    /** Final status */
+    status: "completed" | "failed";
+    /** Result data (if completed) */
+    result?: T;
+    /** Error message (if failed) */
+    error?: string;
+    /** Total time waited in ms */
+    waitTime: number;
+}
+/**
+ * Wait for a job to complete
+ * Polls the status endpoint until the job is done
+ */
+declare function waitForResult<T = unknown>(ctx: RequestContext, jobId: string, options?: WaitOptions): Promise<WaitResult<T>>;
+/**
+ * Wait for multiple jobs to complete
+ * Returns when all jobs are done (either completed or failed)
+ */
+declare function waitForAll<T = unknown>(ctx: RequestContext, jobIds: string[], options?: WaitOptions): Promise<WaitResult<T>[]>;
+/**
+ * Wait for any job to complete
+ * Returns as soon as one job finishes
+ */
+declare function waitForAny<T = unknown>(ctx: RequestContext, jobIds: string[], options?: WaitOptions): Promise<WaitResult<T>>;
+/**
+ * Poll with custom condition
+ * Generic polling utility
+ */
+declare function pollUntil<T>(fetchFn: () => Promise<T>, conditionFn: (data: T) => boolean, options?: {
+    pollInterval?: number;
+    timeout?: number;
+    signal?: AbortSignal;
+}): Promise<T>;
+
+/**
+ * SDK Request Options Types
+ * These types define the options for SDK methods
+ */
+/** Screenshot capture options */
+interface ScreenshotOptions {
+    /** Enable screenshot capture */
+    enabled: boolean;
+    /** Capture full page or viewport only (default: false) */
+    fullPage?: boolean;
+    /** Viewport width in pixels (default: 1280, min: 320, max: 3840) */
+    width?: number;
+    /** Viewport height in pixels (default: 720, min: 240, max: 2160) */
+    height?: number;
+    /** Image format (default: png) */
+    format?: "png" | "jpeg" | "webp";
+    /** JPEG/WebP quality 0-100 (default: 80, only for jpeg/webp) */
+    quality?: number;
+}
+/** Options for scraping a single page */
+interface ScrapeOptions {
+    /** URL to scrape (required) */
+    url: string;
+    /** Detect signals like prices, discounts, urgency (default: true) */
+    detectSignals?: boolean;
+    /** Extract content using AI */
+    extractWithAI?: boolean;
+    /** Extract deal-specific information (product, price, discount, urgency) */
+    extractDeal?: boolean;
+    /** 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 */
+    minDealScore?: number;
+    /** Screenshot configuration */
+    screenshot?: ScreenshotOptions;
+    /** HTML tags to exclude from content (e.g., ["nav", "footer", "aside", "script"]) */
+    excludeTags?: string[];
+    /** CSS selectors to exclude from content (e.g., [".sidebar", "#comments"]) */
+    excludeSelectors?: string[];
+    /** Only extract main content area (default: true) */
+    onlyMainContent?: boolean;
+    /** Custom headers for the request */
+    headers?: Record<string, string>;
+    /** Timeout in milliseconds (default: 30000, max: 120000) */
+    timeout?: number;
+}
+/** Options for crawling a website */
+interface CrawlOptions {
+    /** Starting URL for the crawl (required) */
+    url: string;
+    /** Alias for url - Starting URL for the crawl */
+    startUrl?: string;
+    /** Prompt to guide the crawl (optional) */
+    prompt?: string;
+    /** Maximum depth to crawl (default: 3, max: 5) */
+    maxDepth?: number;
+    /** Maximum pages to crawl (default: 100, max: 1000) */
+    maxPages?: number;
+    /** Delay between requests in ms (default: 1000, min: 100, max: 10000) */
+    delayMs?: number;
+    /** Detect signals on crawled pages (default: true) */
+    detectSignals?: boolean;
+    /** Extract content using AI */
+    extractWithAI?: boolean;
+    /** Extract deal-specific information from each page */
+    extractDeal?: boolean;
+    /** Minimum deal score threshold (0-100) */
+    minDealScore?: number;
+    /** Prioritize pages likely to contain deals (default: true) */
+    prioritizeDealPages?: boolean;
+    /** Follow links to external domains (default: false) */
+    followExternalLinks?: boolean;
+    /** List of allowed domains to crawl */
+    allowedDomains?: string[];
+    /** URL patterns to exclude from crawling */
+    excludePatterns?: string[];
+}
+/** Crawl template identifier */
+type CrawlTemplateId = "ecommerce" | "blog" | "docs" | "marketplace" | "custom";
+/** Crawl template definition */
+interface CrawlTemplate {
+    id: CrawlTemplateId;
+    name: string;
+    description: string;
+    defaultOptions: Partial<CrawlOptions>;
+}
+/** LLM model options for extraction */
+type ExtractModel = "gpt-4o-mini" | "gpt-4o" | "claude-3-haiku" | "claude-3-sonnet";
+/** Options for structured data extraction */
+interface ExtractOptions {
+    /** URL to extract data from (required) */
+    url: string;
+    /** JSON Schema for structured extraction */
+    schema?: Record<string, unknown>;
+    /** Natural language prompt for extraction */
+    prompt?: string;
+    /** Extract only main content or full page (default: true) */
+    onlyMainContent?: boolean;
+    /** HTML tags to exclude from content */
+    excludeTags?: string[];
+    /** CSS selectors to exclude from content */
+    excludeSelectors?: string[];
+    /** LLM model to use (default: gpt-4o-mini) */
+    model?: ExtractModel;
+    /** Temperature for LLM (0-1, default: 0.1) */
+    temperature?: number;
+    /** Webhook configuration for async notification */
+    webhook?: {
+        url: string;
+        headers?: Record<string, string>;
+    };
+    /** Custom headers for the scrape request */
+    headers?: Record<string, string>;
+    /** Timeout in milliseconds */
+    timeout?: number;
+}
+/** Options for Google Dork searches */
+interface DorkOptions {
+    /** Search query (required) */
+    query: string;
+    /** Limit search to specific site */
+    site?: string;
+    /** Search for specific file types */
+    fileType?: string;
+    /** Search for term in URL */
+    inUrl?: string;
+    /** Search for term in title */
+    inTitle?: string;
+    /** Maximum results to return (default: 10, max: 100) */
+    maxResults?: number;
+    /** Region code (2 letter ISO code) */
+    region?: string;
+}
+/** Options for getting job deals */
+interface GetDealsOptions {
+    /** Minimum deal score to filter by */
+    minScore?: number;
+    /** Maximum number of deals to return (default: 50, max: 100) */
+    limit?: number;
+}
+/** Job status filter options */
+type JobStatusFilter = "pending" | "active" | "completed" | "failed" | "delayed" | "paused";
+/** Job type filter options */
+type JobTypeFilter = "scrape" | "crawl" | "dork" | "extract";
+/** Sort order */
+type SortOrder = "asc" | "desc";
+/** Options for listing jobs */
+interface ListJobsOptions {
+    /** Page number (default: 1) */
+    page?: number;
+    /** Items per page (default: 20, max: 100) */
+    limit?: number;
+    /** Filter by job status */
+    status?: JobStatusFilter;
+    /** Filter by job type */
+    type?: JobTypeFilter;
+    /** Sort field */
+    sortBy?: "created_at" | "updated_at" | "status";
+    /** Sort order */
+    sortOrder?: SortOrder;
+    /** Filter from date (ISO string) */
+    fromDate?: string;
+    /** Filter to date (ISO string) */
+    toDate?: string;
+}
+/** Options for listing deals */
+interface ListDealsOptions {
+    /** Page number (default: 1) */
+    page?: number;
+    /** Items per page (default: 20, max: 100) */
+    limit?: number;
+    /** Minimum deal score */
+    minScore?: number;
+    /** Maximum price */
+    maxPrice?: number;
+    /** Filter by category */
+    category?: string;
+    /** Filter by merchant name */
+    merchant?: string;
+    /** Filter by sync status to DealUp */
+    synced?: boolean;
+    /** Sort field */
+    sortBy?: "deal_score" | "current_price" | "discount_percent" | "created_at";
+    /** Sort order */
+    sortOrder?: SortOrder;
+}
+/** Export format options */
+type ExportFormat = "json" | "csv";
+/** Options for exporting jobs */
+interface ExportJobsOptions {
+    /** Export format (default: json) */
+    format?: ExportFormat;
+    /** Filter by job status */
+    status?: JobStatusFilter;
+    /** Filter by job type */
+    type?: JobTypeFilter;
+    /** Filter from date (ISO string) */
+    fromDate?: string;
+    /** Filter to date (ISO string) */
+    toDate?: string;
+}
+/** Options for exporting deals */
+interface ExportDealsOptions {
+    /** Export format (default: json) */
+    format?: ExportFormat;
+    /** Minimum deal score */
+    minScore?: number;
+    /** Maximum price */
+    maxPrice?: number;
+    /** Filter by category */
+    category?: string;
+    /** Include raw signals in export */
+    includeRawSignals?: boolean;
+}
+/** Webhook event types */
+type WebhookEvent = "deal.found" | "deal.synced" | "crawl.completed" | "crawl.failed";
+/** Options for creating a webhook */
+interface CreateWebhookOptions {
+    /** Event type to subscribe to */
+    event: WebhookEvent;
+    /** URL to receive webhook notifications */
+    url: string;
+    /** Secret for signature verification */
+    secret?: string;
+    /** Only notify for deals above this score (default: 70) */
+    minDealScore?: number;
+    /** Filter by product categories */
+    categories?: string[];
+    /** Active status (default: true) */
+    active?: boolean;
+}
+/** Options for updating a webhook */
+interface UpdateWebhookOptions {
+    /** New URL */
+    url?: string;
+    /** New secret */
+    secret?: string;
+    /** New minimum deal score */
+    minDealScore?: number;
+    /** New categories filter */
+    categories?: string[];
+    /** Active status */
+    active?: boolean;
+}
+/**
+ * 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";
+/** Options for creating an API key */
+interface CreateApiKeyOptions {
+    /** Key name/description */
+    name: string;
+    /** Scopes for the key */
+    scopes?: ApiKeyScope[];
+    /** Days until expiration (optional) */
+    expiresInDays?: number;
+    /** IP allowlist (optional) */
+    ipAllowlist?: string[];
+}
+/** Options for rotating an API key */
+interface RotateApiKeyOptions {
+    /** New name for the rotated key */
+    newName?: string;
+}
+/** Options for listing API keys */
+interface ListApiKeysOptions {
+    /** Include revoked keys */
+    includeRevoked?: boolean;
+}
+/** Options for getting API key stats */
+interface GetApiKeyStatsOptions {
+    /** Number of days to get stats for (default: 30) */
+    days?: number;
+}
+/** Product category */
+type ProductCategory = "courses" | "software" | "physical" | "services" | "other";
+/** Options for updating preferences */
+interface UpdatePreferencesOptions {
+    /** Preferred product categories */
+    preferredCategories?: ProductCategory[];
+    /** Minimum deal score for notifications */
+    minDealScore?: number;
+    /** Auto-sync deals to DealUp */
+    autoSync?: boolean;
+    /** Enable webhook notifications */
+    webhookEnabled?: boolean;
+}
+
+/**
+ * Account Resource
+ * Handles account information and preferences
+ */
+
+/**
+ * Account resource class
+ * Provides methods for account information and preferences
+ */
+declare class AccountResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Get current account information
+     *
+     * @example
+     * ```ts
+     * const account = await client.account.get();
+     * console.log(account.name);
+     * console.log(account.tier);
+     * console.log(account.usage);
+     * ```
+     */
+    get(): Promise<AccountInfoResponse>;
+    /**
+     * Get detailed account metrics
+     *
+     * @example
+     * ```ts
+     * const metrics = await client.account.getMetrics();
+     * console.log(metrics.dealMetrics.totalDeals);
+     * console.log(metrics.categoryPerformance);
+     * ```
+     */
+    getMetrics(): Promise<AccountMetricsResponse>;
+    /**
+     * Get DealUp sync metrics (pro/enterprise only)
+     *
+     * @example
+     * ```ts
+     * const dealup = await client.account.getDealUpMetrics();
+     * console.log(dealup.sync.totalSynced);
+     * console.log(dealup.sync.clicksGenerated);
+     * ```
+     */
+    getDealUpMetrics(): Promise<DealUpMetricsResponse>;
+    /**
+     * Get crawl recommendations
+     * AI-suggested URLs to crawl based on past performance
+     *
+     * @example
+     * ```ts
+     * const recommendations = await client.account.getRecommendations();
+     * recommendations.recommendations.forEach(r => {
+     *   console.log(r.url, r.reason, r.estimatedDeals);
+     * });
+     * ```
+     */
+    getRecommendations(): Promise<RecommendationsResponse>;
+    /**
+     * Get current preferences
+     *
+     * @example
+     * ```ts
+     * const prefs = await client.account.getPreferences();
+     * console.log(prefs.preferences.minDealScore);
+     * console.log(prefs.preferences.autoSync);
+     * ```
+     */
+    getPreferences(): Promise<PreferencesResponse>;
+    /**
+     * Update account preferences
+     *
+     * @example
+     * ```ts
+     * const updated = await client.account.updatePreferences({
+     *   minDealScore: 70,
+     *   autoSync: true,
+     *   preferredCategories: ["software", "courses"]
+     * });
+     * ```
+     */
+    updatePreferences(options: UpdatePreferencesOptions): Promise<UpdatePreferencesResponse>;
+    /**
+     * Track a DealUp click (webhook endpoint)
+     * Used internally by DealUp to track click-through
+     *
+     * @example
+     * ```ts
+     * await client.account.trackClick("deal_abc123", "homepage");
+     * ```
+     */
+    trackClick(dealId: string, source?: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get remaining quota for a resource
+     *
+     * @example
+     * ```ts
+     * const remaining = await client.account.getRemainingQuota("scrapes");
+     * console.log(`${remaining} scrapes left this period`);
+     * ```
+     */
+    getRemainingQuota(resource: "scrapes" | "crawls" | "dorks"): Promise<number>;
+    /**
+     * Check if account has quota for a resource
+     *
+     * @example
+     * ```ts
+     * if (await client.account.hasQuota("crawls", 5)) {
+     *   // Safe to start 5 crawls
+     * }
+     * ```
+     */
+    hasQuota(resource: "scrapes" | "crawls" | "dorks", needed?: number): Promise<boolean>;
+    /**
+     * Get account tier
+     *
+     * @example
+     * ```ts
+     * const tier = await client.account.getTier();
+     * if (tier === "enterprise") {
+     *   // Enable advanced features
+     * }
+     * ```
+     */
+    getTier(): Promise<"free" | "pro" | "enterprise">;
+    /**
+     * Check if account is pro or enterprise tier
+     *
+     * @example
+     * ```ts
+     * if (await client.account.isPremium()) {
+     *   // Show premium features
+     * }
+     * ```
+     */
+    isPremium(): Promise<boolean>;
+}
+
+/**
+ * Crawl Resource
+ * Handles website crawling operations
+ */
+
+/**
+ * Crawl resource class
+ * Provides methods for website crawling
+ */
+declare class CrawlResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Create a new crawl job
+     *
+     * @example
+     * ```ts
+     * const job = await client.crawl.create({
+     *   url: "https://example.com",
+     *   maxDepth: 3,
+     *   maxPages: 100,
+     *   extractDeal: true
+     * });
+     * console.log(job.jobId);
+     * ```
+     */
+    create(options: CrawlOptions): Promise<CrawlJobResponse>;
+    /**
+     * Create a crawl job using a template
+     *
+     * @example
+     * ```ts
+     * const job = await client.crawl.withTemplate("ecommerce", {
+     *   url: "https://shop.example.com",
+     *   maxPages: 200 // Override template default
+     * });
+     * ```
+     */
+    withTemplate(templateId: CrawlTemplateId, options: CrawlOptions): Promise<CrawlJobResponse>;
+    /**
+     * List available crawl templates
+     *
+     * @example
+     * ```ts
+     * const templates = client.crawl.listTemplates();
+     * templates.forEach(t => console.log(t.name, t.description));
+     * ```
+     */
+    listTemplates(): CrawlTemplate[];
+    /**
+     * Get a specific template by ID
+     *
+     * @example
+     * ```ts
+     * const template = client.crawl.getTemplate("ecommerce");
+     * console.log(template.defaultOptions);
+     * ```
+     */
+    getTemplate(templateId: CrawlTemplateId): CrawlTemplate | undefined;
+    /**
+     * Analyze a URL before crawling
+     * Returns recommended settings based on site structure
+     *
+     * @example
+     * ```ts
+     * const analysis = await client.crawl.analyze("https://shop.example.com");
+     * console.log(analysis.recommendedTemplate);
+     * console.log(analysis.estimatedPages);
+     * ```
+     */
+    analyze(url: string): Promise<CrawlAnalysisResponse>;
+    /**
+     * Crawl a URL with deal extraction enabled
+     * Convenience method for e-commerce crawling
+     *
+     * @example
+     * ```ts
+     * const job = await client.crawl.forDeals("https://shop.example.com", {
+     *   minDealScore: 70
+     * });
+     * ```
+     */
+    forDeals(url: string, options?: Omit<CrawlOptions, "url" | "extractDeal" | "prioritizeDealPages">): Promise<CrawlJobResponse>;
+}
+
+/**
+ * Data Resource
+ * Handles data retrieval, listing, and export operations
+ */
+
+/**
+ * Data resource class
+ * Provides methods for accessing job and deal data
+ */
+declare class DataResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * List all jobs
+     *
+     * @example
+     * ```ts
+     * const jobs = await client.data.listJobs({
+     *   status: "completed",
+     *   type: "crawl",
+     *   page: 1,
+     *   limit: 20
+     * });
+     * console.log(jobs.data);
+     * console.log(jobs.pagination.total);
+     * ```
+     */
+    listJobs(options?: ListJobsOptions): Promise<ListJobsResponse>;
+    /**
+     * Get jobs by status
+     * Convenience method for filtering by status
+     *
+     * @example
+     * ```ts
+     * const activeJobs = await client.data.getJobsByStatus("active");
+     * ```
+     */
+    getJobsByStatus(status: ListJobsOptions["status"], options?: Omit<ListJobsOptions, "status">): Promise<ListJobsResponse>;
+    /**
+     * Get jobs by type
+     * Convenience method for filtering by type
+     *
+     * @example
+     * ```ts
+     * const crawlJobs = await client.data.getJobsByType("crawl");
+     * ```
+     */
+    getJobsByType(type: ListJobsOptions["type"], options?: Omit<ListJobsOptions, "type">): Promise<ListJobsResponse>;
+    /**
+     * Get recent jobs
+     * Convenience method for getting latest jobs
+     *
+     * @example
+     * ```ts
+     * const recentJobs = await client.data.getRecentJobs(10);
+     * ```
+     */
+    getRecentJobs(limit?: number): Promise<ListJobsResponse>;
+    /**
+     * List all deals
+     *
+     * @example
+     * ```ts
+     * const deals = await client.data.listDeals({
+     *   minScore: 70,
+     *   category: "electronics",
+     *   sortBy: "deal_score",
+     *   sortOrder: "desc"
+     * });
+     * ```
+     */
+    listDeals(options?: ListDealsOptions): Promise<ListDealsResponse>;
+    /**
+     * Get a single deal by ID
+     *
+     * @example
+     * ```ts
+     * const deal = await client.data.getDeal("deal_abc123");
+     * console.log(deal.product.name);
+     * console.log(deal.pricing.discountPercent);
+     * ```
+     */
+    getDeal(dealId: string): Promise<DealDetails>;
+    /**
+     * Get top deals by score
+     * Convenience method for finding best deals
+     *
+     * @example
+     * ```ts
+     * const topDeals = await client.data.getTopDeals(20, 80);
+     * ```
+     */
+    getTopDeals(limit?: number, minScore?: number): Promise<ListDealsResponse>;
+    /**
+     * Get deals by category
+     * Convenience method for filtering by category
+     *
+     * @example
+     * ```ts
+     * const electronicsDeals = await client.data.getDealsByCategory("electronics");
+    async getDealsByCategory(
+      category: string,
+      options?: Omit<ListDealsOptions, "category">
+    ): Promise<ListDealsResponse> {
+      if (!category || !category.trim()) {
+        throw new Error("category is required and cannot be empty");
+      }
+      return this.listDeals({ category, ...options });
+    }    return this.listDeals({ category, ...options });
+    }
+  
+    /**
+     * Get unsynced deals (not yet sent to DealUp)
+     *
+     * @example
+     * ```ts
+     * const unsyncedDeals = await client.data.getUnsyncedDeals();
+     * ```
+     */
+    getUnsyncedDeals(options?: Omit<ListDealsOptions, "synced">): Promise<ListDealsResponse>;
+    /**
+     * Export jobs data
+     *
+     * @example
+     * ```ts
+     * // Export as JSON
+     * const jsonData = await client.data.exportJobs({ format: "json" });
+     *
+     * // Export as CSV
+     * const csvData = await client.data.exportJobs({ format: "csv" });
+     * ```
+     */
+    exportJobs(options?: ExportJobsOptions): Promise<string | object[]>;
+    /**
+     * Export deals data
+     *
+     * @example
+     * ```ts
+     * // Export as JSON
+     * const jsonData = await client.data.exportDeals({ format: "json" });
+     *
+     * // Export as CSV with filters
+     * const csvData = await client.data.exportDeals({
+     *   format: "csv",
+     *   minScore: 70,
+     *   category: "software"
+     * });
+     * ```
+     */
+    exportDeals(options?: ExportDealsOptions): Promise<string | object[]>;
+    /**
+     * Get client statistics
+     *
+     * @example
+     * ```ts
+     * const stats = await client.data.getStats();
+     * console.log(stats.totals.deals);
+     * console.log(stats.performance.avgDealScore);
+     * ```
+     */
+    getStats(): Promise<ClientStatsResponse>;
+}
+
+/**
+ * Dork Resource
+ * Handles Google Dork search operations
+ */
+
+/**
+ * Dork resource class
+ * Provides methods for Google Dork searches
+ */
+declare class DorkResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Create a new dork search job
+     *
+     * @example
+     * ```ts
+     * const job = await client.dork.create({
+     *   query: "discount coupon",
+     *   site: "amazon.com",
+     *   maxResults: 20
+     * });
+     * console.log(job.jobId);
+     * ```
+     */
+    create(options: DorkOptions): Promise<DorkJobResponse>;
+    /**
+     * Search for deals on a specific site
+     * Convenience method for finding discount pages
+     *
+     * @example
+     * ```ts
+     * const job = await client.dork.findDeals("amazon.com", {
+     *   maxResults: 50
+     * });
+     * ```
+     */
+    findDeals(site: string, options?: Omit<DorkOptions, "query" | "site">): Promise<DorkJobResponse>;
+    /**
+     * Search for product pages on a site
+     * Looks for common product URL patterns
+     *
+     * @example
+     * ```ts
+     * const job = await client.dork.findProducts("shop.example.com", {
+     *   maxResults: 100
+     * });
+     * ```
+     */
+    findProducts(site: string, options?: Omit<DorkOptions, "query" | "site" | "inUrl">): Promise<DorkJobResponse>;
+    /**
+     * Search for PDFs on a site
+     * Useful for finding manuals, guides, datasheets
+     *
+     * @example
+     * ```ts
+     * const job = await client.dork.findPDFs("docs.example.com", "user guide");
+     * ```
+     */
+    findPDFs(site: string, query?: string, options?: Omit<DorkOptions, "query" | "site" | "fileType">): Promise<DorkJobResponse>;
+    /**
+     * Search with custom title filter
+     * Find pages with specific terms in title
+     *
+     * @example
+     * ```ts
+     * const job = await client.dork.inTitle("Black Friday", {
+     *   site: "bestbuy.com",
+     *   maxResults: 30
+     * });
+     * ```
+     */
+    inTitle(titleQuery: string, options?: Omit<DorkOptions, "inTitle">): Promise<DorkJobResponse>;
+    /**
+     * Search with custom URL filter
+     * Find pages with specific terms in URL
+     *
+     * @example
+     * ```ts
+     * const job = await client.dork.inUrl("clearance", {
+     *   site: "walmart.com"
+     * });
+     * ```
+     */
+    inUrl(urlQuery: string, options?: Omit<DorkOptions, "inUrl">): Promise<DorkJobResponse>;
+    /**
+     * Build a raw Google dork query string
+     * Useful for preview or debugging
+     *
+     * @example
+     * ```ts
+     * const query = client.dork.buildQuery({
+     *   query: "laptop deals",
+     *   site: "amazon.com",
+     *   inTitle: "discount"
+     * });
+     * // Returns: "laptop deals site:amazon.com intitle:discount"
+     * ```
+     */
+    buildQuery(options: DorkOptions): string;
+}
+
+/**
+ * Extract Resource
+ * Handles LLM-based structured data extraction
+ */
+
+/**
+ * Extract resource class
+ * Provides methods for structured data extraction using LLMs
+ */
+declare class ExtractResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Create a new extraction job
+     * Either schema or prompt must be provided
+     *
+     * @example
+     * ```ts
+     * // Schema-based extraction
+     * const job = await client.extract.create({
+     *   url: "https://example.com/product",
+     *   schema: {
+     *     type: "object",
+     *     properties: {
+     *       name: { type: "string" },
+     *       price: { type: "number" },
+     *       features: { type: "array", items: { type: "string" } }
+     *     }
+     *   }
+     * });
+     *
+     * // Prompt-based extraction
+     * const job = await client.extract.create({
+     *   url: "https://example.com/article",
+     *   prompt: "Extract the main points and author name"
+     * });
+     * ```
+     */
+    create(options: ExtractOptions): Promise<ExtractJobResponse>;
+    /**
+     * Extract data using a JSON Schema
+     * Convenience method for schema-based extraction
+     *
+     * @example
+     * ```ts
+     * const job = await client.extract.withSchema(
+     *   "https://example.com/product",
+     *   {
+     *     type: "object",
+     *     properties: {
+     *       name: { type: "string" },
+     *       price: { type: "number" }
+     *     }
+     *   }
+     * );
+     * ```
+     */
+    withSchema(url: string, schema: Record<string, unknown>, options?: Omit<ExtractOptions, "url" | "schema" | "prompt">): Promise<ExtractJobResponse>;
+    /**
+     * Extract data using a natural language prompt
+     * Convenience method for prompt-based extraction
+     *
+     * @example
+     * ```ts
+     * const job = await client.extract.withPrompt(
+     *   "https://example.com/article",
+     *   "Extract the article title, author, publication date, and a brief summary"
+     * );
+     * ```
+     */
+    withPrompt(url: string, prompt: string, options?: Omit<ExtractOptions, "url" | "schema" | "prompt">): Promise<ExtractJobResponse>;
+    /**
+     * Extract product information from a page
+     * Pre-built schema for common e-commerce use case
+     *
+     * @example
+     * ```ts
+     * const job = await client.extract.product("https://shop.example.com/item");
+     * ```
+     */
+    product(url: string, options?: Omit<ExtractOptions, "url" | "schema" | "prompt">): Promise<ExtractJobResponse>;
+    /**
+     * Extract article/blog post information
+     * Pre-built schema for content extraction
+     *
+     * @example
+     * ```ts
+     * const job = await client.extract.article("https://blog.example.com/post");
+     * ```
+     */
+    article(url: string, options?: Omit<ExtractOptions, "url" | "schema" | "prompt">): Promise<ExtractJobResponse>;
+    /**
+     * Extract contact information from a page
+     * Pre-built schema for contact page scraping
+     *
+     * @example
+     * ```ts
+     * const job = await client.extract.contact("https://example.com/contact");
+     * ```
+     */
+    contact(url: string, options?: Omit<ExtractOptions, "url" | "schema" | "prompt">): Promise<ExtractJobResponse>;
+}
+
+/**
+ * Keys Resource
+ * Handles API key management operations
+ */
+
+/**
+ * Keys resource class
+ * Provides methods for managing API keys
+ */
+declare class KeysResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * List all API keys
+     *
+     * @example
+     * ```ts
+     * const keys = await client.keys.list();
+     * keys.keys.forEach(k => {
+     *   console.log(k.name, k.prefix, k.isActive);
+     * });
+     * ```
+     */
+    list(options?: ListApiKeysOptions): Promise<ListKeysResponse>;
+    /**
+     * Create a new API key
+     *
+     * @example
+     * ```ts
+     * const newKey = await client.keys.create({
+     *   name: "Production Key",
+     *   scopes: ["scrape", "crawl", "status", "data:read"],
+     *   expiresInDays: 365
+     * });
+     *
+     * // IMPORTANT: Save this key immediately - it won't be shown again!
+     * console.log(newKey.key);
+     * ```
+     */
+    create(options: CreateApiKeyOptions): Promise<CreateKeyResponse>;
+    /**
+     * Get details of a specific key
+     *
+     * @example
+     * ```ts
+     * const key = await client.keys.get("key_abc123");
+     * console.log(key.scopes);
+     * console.log(key.lastUsedAt);
+     * ```
+     */
+    get(keyId: string): Promise<ApiKeyInfo>;
+    /**
+     * Get usage statistics for a key
+     *
+     * @example
+     * ```ts
+     * const stats = await client.keys.getStats("key_abc123", { days: 30 });
+     * console.log(stats.stats.totalRequests);
+     * console.log(stats.stats.byEndpoint);
+     * ```
+     */
+    getStats(keyId: string, options?: GetApiKeyStatsOptions): Promise<KeyStatsResponse>;
+    /**
+     * Rotate an API key (revoke old, create new)
+     *
+     * @example
+     * ```ts
+     * const rotated = await client.keys.rotate("key_abc123", {
+     *   newName: "Production Key v2"
+     * });
+     *
+     * // Old key is now invalid
+     * console.log(rotated.oldKeyRevoked); // true
+     *
+     * // Save new key immediately!
+     * console.log(rotated.newKey.key);
+     * ```
+     */
+    rotate(keyId: string, options?: RotateApiKeyOptions): Promise<RotateKeyResponse>;
+    /**
+     * Revoke (delete) an API key
+     *
+     * @example
+     * ```ts
+     * await client.keys.revoke("key_abc123");
+     * ```
+     */
+    revoke(keyId: string): Promise<DeleteKeyResponse>;
+    /**
+     * Revoke all API keys (except the current one)
+     *
+     * @example
+     * ```ts
+     * // Use with caution!
+     * const result = await client.keys.revokeAll();
+     * console.log(`Revoked ${result.count} keys`);
+     * ```
+     */
+    revokeAll(): Promise<{
+        success: boolean;
+        count: number;
+    }>;
+    /**
+     * Get active keys only
+     *
+     * @example
+     * ```ts
+     * const activeKeys = await client.keys.getActive();
+     * ```
+     */
+    getActive(): Promise<ApiKeyInfo[]>;
+    /**
+     * Check if a key is valid (active and not expired)
+     *
+     * @example
+     * ```ts
+     * const isValid = await client.keys.isValid("key_abc123");
+     * ```
+     */
+    isValid(keyId: string): Promise<boolean>;
+}
+
+/**
+ * Scrape Resource
+ * Handles single page scraping operations
+ */
+
+/**
+ * Scrape resource class
+ * Provides methods for single page scraping
+ */
+declare class ScrapeResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Create a new scrape job
+     *
+     * @example
+     * ```ts
+     * const job = await client.scrape.create({
+     *   url: "https://example.com/product",
+     *   extractDeal: true,
+     *   screenshot: { enabled: true, format: "webp" }
+     * });
+     * console.log(job.jobId);
+     * ```
+     */
+    create(options: ScrapeOptions): Promise<ScrapeJobResponse>;
+    /**
+     * Scrape a URL with deal extraction enabled
+     * Convenience method for common use case
+     *
+     * @example
+     * ```ts
+     * const job = await client.scrape.extractDeal("https://example.com/sale");
+     * ```
+     */
+    extractDeal(url: string, options?: Omit<ScrapeOptions, "url" | "extractDeal">): Promise<ScrapeJobResponse>;
+    /**
+     * Scrape a URL with screenshot capture
+     * Convenience method for screenshot capture
+     *
+     * @example
+     * ```ts
+     * const job = await client.scrape.withScreenshot("https://example.com", {
+     *   format: "webp",
+     *   fullPage: true
+     * });
+     * ```
+     */
+    withScreenshot(url: string, screenshotOptions?: Omit<ScrapeOptions["screenshot"], "enabled">, options?: Omit<ScrapeOptions, "url" | "screenshot">): Promise<ScrapeJobResponse>;
+}
+
+/**
+ * Status Resource
+ * Handles job status checking and management
+ */
+
+/**
+ * Status resource class
+ * Provides methods for checking and managing job status
+ */
+declare class StatusResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Get the status of a job
+     *
+     * @example
+     * ```ts
+     * const status = await client.status.get("job_abc123");
+     * console.log(status.status); // "completed"
+     * console.log(status.result);
+     * ```
+     */
+    get(jobId: string): Promise<JobStatusResponse>;
+    /**
+     * Get deals found by a job
+     *
+     * @example
+     * ```ts
+     * const deals = await client.status.getDeals("job_abc123", {
+     *   minScore: 70,
+     *   limit: 20
+     * });
+     * console.log(deals.deals);
+     * ```
+     */
+    getDeals(jobId: string, options?: GetDealsOptions): Promise<JobDealsResponse>;
+    /**
+     * Resume a paused or failed job from checkpoint
+     *
+     * @example
+     * ```ts
+     * const resumed = await client.status.resume("job_abc123");
+     * console.log(resumed.newJobId);
+     * ```
+     */
+    resume(jobId: string): Promise<ResumeJobResponse>;
+    /**
+     * Get detailed metrics for a job
+     *
+     * @example
+     * ```ts
+     * const metrics = await client.status.getMetrics("job_abc123");
+     * console.log(metrics.metrics.successRate);
+     * ```
+     */
+    getMetrics(jobId: string): Promise<JobMetricsResponse>;
+    /**
+     * Cancel a pending or active job
+     *
+     * @example
+     * ```ts
+     * const cancelled = await client.status.cancel("job_abc123");
+     * console.log(cancelled.success);
+     * ```
+     */
+    cancel(jobId: string): Promise<CancelJobResponse>;
+    /**
+     * Check if a job is complete
+     * Convenience method for polling
+     *
+     * @example
+     * ```ts
+     * const isComplete = await client.status.isComplete("job_abc123");
+     * ```
+     */
+    isComplete(jobId: string): Promise<boolean>;
+    /**
+     * Check if a job succeeded
+     * Convenience method for result checking
+     *
+     * @example
+     * ```ts
+     * const succeeded = await client.status.succeeded("job_abc123");
+     * ```
+     */
+    succeeded(jobId: string): Promise<boolean>;
+    /**
+     * Get the result of a completed job
+     * Throws if job is not complete
+     *
+     * @example
+     * ```ts
+     * const result = await client.status.getResult("job_abc123");
+     * ```
+     */
+    getResult<T = unknown>(jobId: string): Promise<T>;
+}
+
+/**
+ * Webhooks Resource
+ * Handles webhook CRUD operations
+ */
+
+/**
+ * Webhooks resource class
+ * Provides methods for managing webhooks
+ */
+declare class WebhooksResource {
+    private ctx;
+    constructor(ctx: RequestContext);
+    /**
+     * Create a new webhook
+     *
+     * @example
+     * ```ts
+     * const webhook = await client.webhooks.create({
+     *   event: "deal.found",
+     *   url: "https://my-server.com/webhooks/deals",
+     *   secret: "my-webhook-secret",
+     *   minDealScore: 70
+     * });
+     * console.log(webhook.webhookId);
+     * ```
+     */
+    create(options: CreateWebhookOptions): Promise<CreateWebhookResponse>;
+    /**
+     * List all webhooks
+     *
+     * @example
+     * ```ts
+     * const webhooks = await client.webhooks.list();
+     * webhooks.webhooks.forEach(w => {
+     *   console.log(w.event, w.url, w.active);
+     * });
+     * ```
+     */
+    list(): Promise<ListWebhooksResponse>;
+    /**
+     * Get a webhook by ID
+     *
+     * @example
+     * ```ts
+     * const webhook = await client.webhooks.get("webhook_abc123");
+     * console.log(webhook.event);
+     * ```
+     */
+    get(webhookId: string): Promise<WebhookItem>;
+    /**
+     * Update a webhook
+     *
+     * @example
+     * ```ts
+     * const updated = await client.webhooks.update("webhook_abc123", {
+     *   minDealScore: 80,
+     *   active: false
+     * });
+     * ```
+     */
+    update(webhookId: string, options: UpdateWebhookOptions): Promise<UpdateWebhookResponse>;
+    /**
+     * Delete a webhook
+     *
+     * @example
+     * ```ts
+     * await client.webhooks.delete("webhook_abc123");
+     * ```
+     */
+    delete(webhookId: string): Promise<DeleteWebhookResponse>;
+    /**
+     * Test a webhook by sending a test payload
+     *
+     * @example
+     * ```ts
+     * const result = await client.webhooks.test("webhook_abc123");
+     * if (result.delivered) {
+     *   console.log(`Delivered in ${result.responseTime}ms`);
+     * } else {
+     *   console.log(`Failed: ${result.error}`);
+     * }
+     * ```
+     */
+    test(webhookId: string): Promise<TestWebhookResponse>;
+    /**
+     * Enable a webhook
+     * Convenience method for activating a webhook
+     *
+     * @example
+     * ```ts
+     * await client.webhooks.enable("webhook_abc123");
+     * ```
+     */
+    enable(webhookId: string): Promise<UpdateWebhookResponse>;
+    /**
+     * Disable a webhook
+     * Convenience method for deactivating a webhook
+     *
+     * @example
+     * ```ts
+     * await client.webhooks.disable("webhook_abc123");
+     * ```
+     */
+    disable(webhookId: string): Promise<UpdateWebhookResponse>;
+    /**
+     * Get active webhooks only
+     *
+     * @example
+     * ```ts
+     * const active = await client.webhooks.getActive();
+     * ```
+     */
+    getActive(): Promise<WebhookItem[]>;
+    /**
+     * Get webhooks by event type
+     *
+     * @example
+     * ```ts
+     * const dealWebhooks = await client.webhooks.getByEvent("deal.found");
+     * ```
+     */
+    getByEvent(event: CreateWebhookOptions["event"]): Promise<WebhookItem[]>;
+}
+
+/**
+ * DealCrawl SDK Client
+ * Main entry point for the SDK
+ *
+ * @example
+ * ```ts
+ * import { DealCrawl } from "@dealcrawl/sdk";
+ *
+ * const client = new DealCrawl({ apiKey: "sk_xxx" });
+ *
+ * // Scrape a page
+ * const job = await client.scrape.create({
+ *   url: "https://example.com/product",
+ *   extractDeal: true
+ * });
+ *
+ * // Wait for result
+ * const result = await client.waitForResult(job.jobId);
+ * console.log(result);
+ * ```
+ */
+
+/**
+ * DealCrawl SDK Client
+ *
+ * Provides access to all DealCrawl API endpoints through
+ * organized resource classes following a Stripe-like pattern.
+ *
+ * @example
+ * ```ts
+ * const client = new DealCrawl({ apiKey: "sk_xxx" });
+ *
+ * // Core operations
+ * await client.scrape.create({ url: "..." });
+ * await client.crawl.create({ url: "...", maxPages: 100 });
+ * await client.extract.create({ url: "...", schema: {...} });
+ * await client.dork.create({ query: "..." });
+ *
+ * // Status & polling
+ * await client.status.get(jobId);
+ * await client.waitForResult(jobId);
+ *
+ * // Data access
+ * await client.data.listJobs();
+ * await client.data.listDeals();
+ *
+ * // Management
+ * await client.webhooks.create({...});
+ * await client.keys.create({...});
+ * await client.account.get();
+ * ```
+ */
+declare class DealCrawl {
+    /** Internal request context */
+    private readonly ctx;
+    /**
+     * Scrape resource - Single page scraping
+     *
+     * @example
+     * ```ts
+     * const job = await client.scrape.create({
+     *   url: "https://example.com",
+     *   extractDeal: true
+     * });
+     * ```
+     */
+    readonly scrape: ScrapeResource;
+    /**
+     * Crawl resource - Website crawling
+     *
+     * @example
+     * ```ts
+     * const job = await client.crawl.create({
+     *   url: "https://shop.example.com",
+     *   maxPages: 100
+     * });
+     *
+     * // With template
+     * const job = await client.crawl.withTemplate("ecommerce", {
+     *   url: "https://shop.example.com"
+     * });
+     * ```
+     */
+    readonly crawl: CrawlResource;
+    /**
+     * Extract resource - LLM-based structured data extraction
+     *
+     * @example
+     * ```ts
+     * const job = await client.extract.create({
+     *   url: "https://example.com/product",
+     *   schema: { type: "object", properties: {...} }
+     * });
+     * ```
+     */
+    readonly extract: ExtractResource;
+    /**
+     * Dork resource - Google Dork searches
+     *
+     * @example
+     * ```ts
+     * const job = await client.dork.create({
+     *   query: "discount coupon",
+     *   site: "amazon.com"
+     * });
+     * ```
+     */
+    readonly dork: DorkResource;
+    /**
+     * Status resource - Job status management
+     *
+     * @example
+     * ```ts
+     * const status = await client.status.get(jobId);
+     * const deals = await client.status.getDeals(jobId);
+     * await client.status.cancel(jobId);
+     * ```
+     */
+    readonly status: StatusResource;
+    /**
+     * Data resource - Jobs and deals data access
+     *
+     * @example
+     * ```ts
+     * const jobs = await client.data.listJobs();
+     * const deals = await client.data.listDeals({ minScore: 70 });
+     * const stats = await client.data.getStats();
+     * ```
+     */
+    readonly data: DataResource;
+    /**
+     * Webhooks resource - Webhook management
+     *
+     * @example
+     * ```ts
+     * await client.webhooks.create({
+     *   event: "deal.found",
+     *   url: "https://..."
+     * });
+     * ```
+     */
+    readonly webhooks: WebhooksResource;
+    /**
+     * Keys resource - API key management
+     *
+     * @example
+     * ```ts
+     * const newKey = await client.keys.create({
+     *   name: "Production",
+     *   scopes: ["scrape", "status"]
+     * });
+     * ```
+     */
+    readonly keys: KeysResource;
+    /**
+     * Account resource - Account info and preferences
+     *
+     * @example
+     * ```ts
+     * const account = await client.account.get();
+     * await client.account.updatePreferences({
+     *   minDealScore: 70
+     * });
+     * ```
+     */
+    readonly account: AccountResource;
+    /**
+     * Create a new DealCrawl client
+     *
+     * @param config - Client configuration
+     *
+     * @example
+     * ```ts
+     * // Minimal config
+     * const client = new DealCrawl({ apiKey: "sk_xxx" });
+     *
+     * // Full config
+     * const client = new DealCrawl({
+     *   apiKey: "sk_xxx",
+     *   baseUrl: "https://api.dealcrawl.dev",
+     *   timeout: 30000,
+     *   maxRetries: 3,
+     *   retryDelay: 1000,
+     *   onRateLimit: (info) => console.log("Rate limited!", info)
+     * });
+     * ```
+     */
+    constructor(config: DealCrawlConfig);
+    /**
+     * Wait for a job to complete
+     * Polls the status endpoint until the job finishes
+     *
+     * @example
+     * ```ts
+     * const job = await client.scrape.create({ url: "..." });
+     *
+     * // Simple wait
+     * const result = await client.waitForResult(job.jobId);
+     *
+     * // With options
+     * const result = await client.waitForResult(job.jobId, {
+     *   pollInterval: 1000,
+     *   timeout: 60000,
+     *   onProgress: (status) => console.log(status.progress)
+     * });
+     * ```
+     */
+    waitForResult<T = unknown>(jobId: string, options?: WaitOptions): Promise<WaitResult<T>>;
+    /**
+     * Wait for multiple jobs to complete
+     * Returns when all jobs are done
+     *
+     * @example
+     * ```ts
+     * const jobs = await Promise.all([
+     *   client.scrape.create({ url: "url1" }),
+     *   client.scrape.create({ url: "url2" }),
+     * ]);
+     *
+     * const results = await client.waitForAll(jobs.map(j => j.jobId));
+     * ```
+     */
+    waitForAll<T = unknown>(jobIds: string[], options?: WaitOptions): Promise<WaitResult<T>[]>;
+    /**
+     * Wait for any job to complete
+     * Returns as soon as one job finishes
+     *
+     * @example
+     * ```ts
+     * const jobIds = ["job1", "job2", "job3"];
+     * const firstResult = await client.waitForAny(jobIds);
+     * ```
+     */
+    waitForAny<T = unknown>(jobIds: string[], options?: WaitOptions): Promise<WaitResult<T>>;
+    /**
+     * Scrape a URL and wait for result
+     * Combines create and waitForResult
+     *
+     * @example
+     * ```ts
+     * const result = await client.scrapeAndWait({
+     *   url: "https://example.com",
+     *   extractDeal: true
+     * });
+     * ```
+     */
+    scrapeAndWait<T = unknown>(options: Parameters<ScrapeResource["create"]>[0], waitOptions?: WaitOptions): Promise<WaitResult<T>>;
+    /**
+     * Crawl a URL and wait for result
+     * Combines create and waitForResult
+     *
+     * @example
+     * ```ts
+     * const result = await client.crawlAndWait({
+     *   url: "https://shop.example.com",
+     *   maxPages: 50
+     * });
+     * ```
+     */
+    crawlAndWait<T = unknown>(options: Parameters<CrawlResource["create"]>[0], waitOptions?: WaitOptions): Promise<WaitResult<T>>;
+    /**
+     * Extract data and wait for result
+     * Combines create and waitForResult
+     *
+     * @example
+     * ```ts
+     * const result = await client.extractAndWait({
+     *   url: "https://example.com/product",
+     *   schema: { type: "object", properties: {...} }
+     * });
+     * ```
+     */
+    extractAndWait<T = unknown>(options: Parameters<ExtractResource["create"]>[0], waitOptions?: WaitOptions): Promise<WaitResult<T>>;
+}
+
+/**
+ * Error codes used by DealCrawl API
+ * Copied from @dealcrawl/shared to avoid bundling the entire package
+ */
+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";
+    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";
+    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";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly REDIS_ERROR: "REDIS_ERROR";
+    readonly DATABASE_ERROR: "DATABASE_ERROR";
+};
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * Custom error class for DealCrawl SDK
+ * Provides structured error handling with error codes
+ */
+declare class DealCrawlError extends Error {
+    /** Error code from ERROR_CODES */
+    readonly code: ErrorCode;
+    /** HTTP status code from the API response */
+    readonly statusCode: number;
+    /** Additional error details */
+    readonly details?: Record<string, unknown>;
+    /** Retry-After header value in seconds (for rate limiting) */
+    readonly retryAfter?: number;
+    constructor(options: {
+        code: ErrorCode;
+        message: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
+        retryAfter?: number;
+    });
+    /**
+     * Check if the error is retryable
+     * Rate limits and transient errors are retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Check if the error is due to authentication issues
+     */
+    isAuthError(): boolean;
+    /**
+     * Check if the error is due to rate limiting
+     */
+    isRateLimited(): boolean;
+    /**
+     * Check if the error is due to quota exceeded
+     */
+    isQuotaExceeded(): boolean;
+    /**
+     * Convert error to JSON-serializable object
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Create a DealCrawlError from an API error response
+     */
+    static fromResponse(statusCode: number, body: {
+        code?: string;
+        message?: string;
+        error?: string;
+        details?: Record<string, unknown>;
+        retryAfter?: number;
+    }, 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 };