@dealcrawl/sdk 2.11.0 → 2.12.0

package/README.md

@@ -6,6 +6,69 @@ Official TypeScript SDK for the DealCrawl web scraping and crawling API.
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+## What's New in v2.12.0 (January 2026) ✨
+
+### New Methods - 100% API Coverage
+
+All missing API endpoints now have SDK methods (completes the 87% → 100% alignment):
+
+**Status Resource (`client.status.*`)**
+
+- `getJobErrors(jobId, options?)` - Get job errors without loading full results (useful for debugging large crawls)
+
+**Data Resource (`client.data.*`)**
+
+- `getJob(jobId)` - Get full job details with result
+- `getJobResult(jobId)` - Get only the result of a completed job
+- `exportJob(jobId, format)` - Export job in multiple formats (json, markdown, llm, csv)
+
+**Webhooks Resource (`client.webhooks.*`)**
+
+- `rotateSecret(webhookId, options)` - Rotate webhook secret with grace period support
+- `getSecretStatus(webhookId)` - Check secret version and grace period status
+- `verifySignature(options)` - Verify webhook signature and replay protection
+
+### Examples
+
+```typescript
+// Get job errors for debugging
+const errors = await client.status.getJobErrors("job_abc123", { limit: 50 });
+
+// Export crawl results as Markdown
+const markdown = await client.data.exportJob("crawl_123", "markdown");
+
+// Rotate webhook secret with 24h grace period
+await client.webhooks.rotateSecret("webhook_abc", {
+  newSecret: "new-secure-key",
+  gracePeriodHours: 24
+});
+```
+
+---
+
+## What's New in v2.11.1 (January 2026) 🐛
+
+### Bug Fixes
+
+- **DataResource**: Fixed syntax error in `getDealsByCategory()` method (unclosed docstring + duplicate line)
+- **SDK-API Alignment**: Verified 87% endpoint coverage with detailed alignment report
+
+### Known Gaps
+
+The following API endpoints do not have SDK methods yet (see [API-SDK Alignment Report](../../docs/API-SDK-ALIGNMENT-REPORT.md)):
+
+- `GET /v1/status/:jobId/errors` - Get job errors
+- `GET /v1/data/jobs/:jobId` - Get full job details
+- `GET /v1/data/jobs/:jobId/result` - Get job result
+- `GET /v1/data/jobs/:jobId/export` - Export job in multiple formats
+- `POST /v1/webhooks/:id/rotate` - Rotate webhook secret
+- `GET /v1/webhooks/:id/secret-status` - Get webhook secret status
+- `POST /v1/webhooks/verify` - Verify webhook signature
+
+These methods will be added in a future release.
+
+---
+
 ## What's New in v2.11.0 (January 2026) 🎉
 
 ### Breaking Changes ⚠️

package/dist/index.d.mts

@@ -690,6 +690,22 @@ interface CancelJobResponse {
     jobId: string;
     message: string;
 }
+/** Job error entry */
+interface JobErrorEntry {
+    url?: string;
+    error: string;
+    timestamp?: string;
+}
+/** Job errors response */
+interface JobErrorsResponse {
+    data: JobErrorEntry[];
+    pagination: PaginationInfo;
+    meta?: {
+        jobId: string;
+        status?: JobStatus$1;
+        offset?: number;
+    };
+}
 /** Job summary in list */
 interface JobSummary {
     id: string;
@@ -769,6 +785,32 @@ interface ClientStatsResponse {
         }>;
     };
 }
+/** Full job details response */
+interface JobDetailsResponse {
+    id: string;
+    type: "scrape" | "crawl" | "dork" | "extract";
+    status: JobStatus$1;
+    input: Record<string, unknown>;
+    result?: unknown;
+    progress?: number;
+    error?: string;
+    dealsFound?: number;
+    avgDealScore?: number;
+    highestDealScore?: number;
+    checkpoint?: CheckpointInfo;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}
+/** Job result response */
+interface JobResultResponse {
+    jobId: string;
+    status: "completed";
+    result: unknown;
+    completedAt?: string;
+}
+/** Job export response (string for CSV/Markdown/LLM, object for JSON) */
+type JobExportResponse = string | Record<string, unknown>;
 /** Webhook in list */
 interface WebhookItem {
     id: string;
@@ -792,10 +834,17 @@ interface CreateWebhookResponse {
     minDealScore: number;
     active: boolean;
 }
-/** List webhooks response */
+/** List webhooks response (standardized list format) */
 interface ListWebhooksResponse {
-    webhooks: WebhookItem[];
-    count: number;
+    data: WebhookItem[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+        hasMore: boolean;
+    };
+    meta?: Record<string, unknown>;
 }
 /** Update webhook response */
 interface UpdateWebhookResponse {
@@ -817,6 +866,35 @@ interface TestWebhookResponse {
     responseTime?: number;
     error?: string;
 }
+/** Rotate webhook secret response */
+interface RotateSecretResponse {
+    success: boolean;
+    webhookId: string;
+    secretVersion: number;
+    previousSecretValidUntil: string;
+    gracePeriodHours: number;
+    message: string;
+}
+/** Webhook secret status response */
+interface SecretStatusResponse {
+    webhookId: string;
+    hasSecret: boolean;
+    secretVersion: number;
+    lastRotatedAt?: string;
+    gracePeriod?: {
+        active: boolean;
+        previousVersion: number;
+        expiresAt: string;
+    } | null;
+}
+/** Verify webhook signature response */
+interface VerifyWebhookResponse {
+    valid: boolean;
+    webhookId?: string;
+    message: string;
+    error?: string;
+    reason?: string;
+}
 /** API key info (safe, without secret) */
 interface ApiKeyInfo {
     id: string;
@@ -1415,7 +1493,7 @@ interface PriceRange {
 interface CrawlOptions {
     /** Starting URL for the crawl (required) */
     url: string;
-    /** Alias for url - Starting URL for the crawl */
+    /** @deprecated Use 'url' instead. Kept for backward compatibility. */
     startUrl?: string;
     /** Prompt to guide the crawl (optional) */
     prompt?: string;
@@ -1535,8 +1613,6 @@ interface DorkOptions {
     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 {
@@ -1612,19 +1688,25 @@ interface ExportDealsOptions {
     format?: ExportFormat;
     /** Minimum deal score */
     minScore?: number;
-    /** Maximum price */
-    maxPrice?: number;
     /** Filter by category */
     category?: string;
-    /** Include raw signals in export */
-    includeRawSignals?: boolean;
+    /** Filter by sync status to DealUp */
+    synced?: boolean;
+    /** Filter from date (ISO string) */
+    fromDate?: string;
+    /** Filter to date (ISO string) */
+    toDate?: string;
+    /** Maximum number of deals to export (default: 500, max: 1000) */
+    limit?: number;
 }
 /** 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;
+    /** Event types to subscribe to (array) */
+    events?: WebhookEvent[];
+    /** @deprecated Use 'events' array instead */
+    event?: WebhookEvent;
     /** URL to receive webhook notifications */
     url: string;
     /** Secret for signature verification */
@@ -2315,9 +2397,9 @@ declare class AuthResource {
      * and how many are currently active.
      *
      * Tier limits:
-     * - Free: 2 concurrent connections
-     * - Pro: 10 concurrent connections
-     * - Enterprise: 50 concurrent connections
+     * - Free: 10 concurrent connections
+     * - Pro: 50 concurrent connections
+     * - Enterprise: 200 concurrent connections
      *
      * @example
      * ```ts
@@ -2634,6 +2716,47 @@ declare class DataResource {
      * ```
      */
     getRecentJobs(limit?: number): Promise<ListJobsResponse>;
+    /**
+     * Get full job details with result
+     *
+     * @example
+     * ```ts
+     * const job = await client.data.getJob("job_abc123");
+     * console.log(job.result);
+     * console.log(job.dealsFound);
+     * ```
+     */
+    getJob(jobId: string): Promise<JobDetailsResponse>;
+    /**
+     * Get only the result of a completed job
+     *
+     * @example
+     * ```ts
+     * const result = await client.data.getJobResult("job_abc123");
+     * console.log(result.result);
+     * ```
+     */
+    getJobResult(jobId: string): Promise<JobResultResponse>;
+    /**
+     * Export job results in various formats
+     * Supports: json, markdown, llm, csv
+     *
+     * @example
+     * ```ts
+     * // Export as JSON
+     * const jsonData = await client.data.exportJob("job_abc123", "json");
+     *
+     * // Export as Markdown
+     * const markdown = await client.data.exportJob("job_abc123", "markdown");
+     *
+     * // Export as LLM-optimized format
+     * const llmText = await client.data.exportJob("job_abc123", "llm");
+     *
+     * // Export as CSV
+     * const csv = await client.data.exportJob("job_abc123", "csv");
+     * ```
+     */
+    exportJob(jobId: string, format?: "json" | "markdown" | "llm" | "csv"): Promise<JobExportResponse>;
     /**
      * List all deals
      *
@@ -2676,17 +2799,9 @@ declare class DataResource {
      * @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 });
-    }
-  
+     * ```
+     */
+    getDealsByCategory(category: string, options?: Omit<ListDealsOptions, "category">): Promise<ListDealsResponse>;
     /**
      * Get unsynced deals (not yet sent to DealUp)
      *
@@ -3221,7 +3336,9 @@ declare class KeysResource {
      */
     revokeAll(): Promise<{
         success: boolean;
-        count: number;
+        revokedCount: number;
+        message: string;
+        warning: string;
     }>;
     /**
      * Get active keys only
@@ -3532,6 +3649,24 @@ declare class StatusResource {
      * ```
      */
     getMetrics(jobId: string): Promise<JobMetricsResponse>;
+    /**
+     * Get errors from a job
+     * Useful for debugging large crawls without loading full results
+     *
+     * @example
+     * ```ts
+     * const errors = await client.status.getJobErrors("job_abc123", {
+     *   limit: 50,
+     *   offset: 0
+     * });
+     * console.log(errors.data);
+     * console.log(errors.pagination.total);
+     * ```
+     */
+    getJobErrors(jobId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<JobErrorsResponse>;
     /**
      * Cancel a pending or active job
      *
@@ -3696,6 +3831,65 @@ declare class WebhooksResource {
      * ```
      */
     getByEvent(event: CreateWebhookOptions["event"]): Promise<WebhookItem[]>;
+    /**
+     * Rotate webhook secret
+     * Rotates the secret while keeping the old one valid during grace period
+     *
+     * @example
+     * ```ts
+     * const result = await client.webhooks.rotateSecret("webhook_abc123", {
+     *   newSecret: "new-secure-secret-key",
+     *   gracePeriodHours: 24
+     * });
+     * console.log(result.secretVersion);
+     * console.log(result.previousSecretValidUntil);
+     * ```
+     */
+    rotateSecret(webhookId: string, options: {
+        newSecret: string;
+        gracePeriodHours?: number;
+    }): Promise<RotateSecretResponse>;
+    /**
+     * Get webhook secret rotation status
+     * Check current secret version and grace period status
+     *
+     * @example
+     * ```ts
+     * const status = await client.webhooks.getSecretStatus("webhook_abc123");
+     * console.log(status.secretVersion);
+     * if (status.gracePeriod?.active) {
+     *   console.log(`Grace period expires: ${status.gracePeriod.expiresAt}`);
+     * }
+     * ```
+     */
+    getSecretStatus(webhookId: string): Promise<SecretStatusResponse>;
+    /**
+     * Verify webhook signature and replay protection
+     * Validates signature, timestamp, and nonce from received webhook
+     *
+     * @example
+     * ```ts
+     * const isValid = await client.webhooks.verifySignature({
+     *   webhookId: "webhook_abc123",
+     *   payload: receivedPayload,
+     *   signature: headers["x-dealcrawl-signature"],
+     *   timestamp: parseInt(headers["x-dealcrawl-timestamp"]),
+     *   nonce: headers["x-dealcrawl-nonce"]
+     * });
+     * if (isValid.valid) {
+     *   console.log("Webhook is valid");
+     * } else {
+     *   console.log(`Invalid: ${isValid.error}`);
+     * }
+     * ```
+     */
+    verifySignature(options: {
+        webhookId: string;
+        payload: Record<string, unknown>;
+        signature: string;
+        timestamp: number;
+        nonce: string;
+    }): Promise<VerifyWebhookResponse>;
 }
 
 /**