@dealcrawl/sdk 2.11.1 → 2.13.0

package/README.md

@@ -6,6 +6,46 @@ 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

package/dist/index.d.mts

@@ -19,7 +19,20 @@ interface ResponseMeta {
     timestamp: string;
     duration?: number;
 }
-type JobStatus$1 = "pending" | "active" | "completed" | "failed" | "delayed" | "paused";
+/**
+ * Job status for API responses.
+ * Maps to BullMQ native states returned by job.getState().
+ *
+ * Status meanings:
+ * - `waiting`: Job in queue, waiting for a worker to pick it up
+ * - `active`: Job is currently being processed by a worker
+ * - `completed`: Job finished successfully
+ * - `failed`: Job failed (may have been retried)
+ * - `delayed`: Job scheduled for future execution
+ * - `paused`: Queue is paused (job will resume when queue unpauses)
+ * - `expired`: Job data has been cleaned up by retention policy
+ */
+type JobStatus$1 = "waiting" | "active" | "completed" | "failed" | "delayed" | "paused" | "expired";
 interface PaginatedResponse<T> {
     data: T[];
     pagination: {
@@ -153,7 +166,7 @@ interface AIExtraction {
     raw?: Record<string, unknown>;
 }
 interface Entity {
-    type: "person" | "organization" | "location" | "product" | "other";
+    type: "person" | "organization" | "location" | "product" | "brand" | "other";
     value: string;
     confidence: number;
 }
@@ -690,6 +703,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 +798,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;
@@ -824,6 +879,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;
@@ -2645,6 +2729,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
      *
@@ -3537,6 +3662,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
      *
@@ -3701,6 +3844,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>;
 }
 
 /**
@@ -4425,7 +4627,7 @@ declare function getErrorMessage(code: ErrorCode): string;
 /**
  * Primary job status - represents the main lifecycle stage
  */
-type JobStatus = "queued" | "scheduled" | "priority_queued" | "initializing" | "active" | "processing" | "extracting" | "uploading" | "finalizing" | "retrying" | "backing_off" | "paused" | "pausing" | "resuming" | "completed" | "partial" | "failed" | "timeout" | "cancelled" | "rejected" | "stale" | "zombie" | "stuck";
+type JobStatus = "queued" | "scheduled" | "priority_queued" | "initializing" | "active" | "processing" | "extracting" | "uploading" | "finalizing" | "retrying" | "backing_off" | "paused" | "pausing" | "resuming" | "completed" | "partial" | "failed" | "timeout" | "cancelled" | "rejected" | "stale" | "zombie" | "stuck" | "expiring" | "expired";
 /**
  * Sub-status provides granular detail within a primary status
  */

package/dist/index.d.ts

@@ -19,7 +19,20 @@ interface ResponseMeta {
     timestamp: string;
     duration?: number;
 }
-type JobStatus$1 = "pending" | "active" | "completed" | "failed" | "delayed" | "paused";
+/**
+ * Job status for API responses.
+ * Maps to BullMQ native states returned by job.getState().
+ *
+ * Status meanings:
+ * - `waiting`: Job in queue, waiting for a worker to pick it up
+ * - `active`: Job is currently being processed by a worker
+ * - `completed`: Job finished successfully
+ * - `failed`: Job failed (may have been retried)
+ * - `delayed`: Job scheduled for future execution
+ * - `paused`: Queue is paused (job will resume when queue unpauses)
+ * - `expired`: Job data has been cleaned up by retention policy
+ */
+type JobStatus$1 = "waiting" | "active" | "completed" | "failed" | "delayed" | "paused" | "expired";
 interface PaginatedResponse<T> {
     data: T[];
     pagination: {
@@ -153,7 +166,7 @@ interface AIExtraction {
     raw?: Record<string, unknown>;
 }
 interface Entity {
-    type: "person" | "organization" | "location" | "product" | "other";
+    type: "person" | "organization" | "location" | "product" | "brand" | "other";
     value: string;
     confidence: number;
 }
@@ -690,6 +703,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 +798,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;
@@ -824,6 +879,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;
@@ -2645,6 +2729,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
      *
@@ -3537,6 +3662,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
      *
@@ -3701,6 +3844,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>;
 }
 
 /**
@@ -4425,7 +4627,7 @@ declare function getErrorMessage(code: ErrorCode): string;
 /**
  * Primary job status - represents the main lifecycle stage
  */
-type JobStatus = "queued" | "scheduled" | "priority_queued" | "initializing" | "active" | "processing" | "extracting" | "uploading" | "finalizing" | "retrying" | "backing_off" | "paused" | "pausing" | "resuming" | "completed" | "partial" | "failed" | "timeout" | "cancelled" | "rejected" | "stale" | "zombie" | "stuck";
+type JobStatus = "queued" | "scheduled" | "priority_queued" | "initializing" | "active" | "processing" | "extracting" | "uploading" | "finalizing" | "retrying" | "backing_off" | "paused" | "pausing" | "resuming" | "completed" | "partial" | "failed" | "timeout" | "cancelled" | "rejected" | "stale" | "zombie" | "stuck" | "expiring" | "expired";
 /**
  * Sub-status provides granular detail within a primary status
  */