@dealcrawl/sdk 2.11.1 → 2.12.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

@@ -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;
@@ -824,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;
@@ -2645,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
      *
@@ -3537,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
      *
@@ -3701,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>;
 }
 
 /**

package/dist/index.d.ts

@@ -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;
@@ -824,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;
@@ -2645,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
      *
@@ -3537,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
      *
@@ -3701,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>;
 }
 
 /**

package/dist/index.js

@@ -1637,6 +1637,75 @@ var DataResource = class {
       sortOrder: "desc"
     });
   }
+  /**
+   * Get full job details with result
+   *
+   * @example
+   * ```ts
+   * const job = await client.data.getJob("job_abc123");
+   * console.log(job.result);
+   * console.log(job.dealsFound);
+   * ```
+   */
+  async getJob(jobId) {
+    if (!jobId || !jobId.trim()) {
+      throw new Error("jobId is required and cannot be empty");
+    }
+    const result = await get(
+      this.ctx,
+      `/v1/data/jobs/${jobId}`
+    );
+    return result.data;
+  }
+  /**
+   * Get only the result of a completed job
+   *
+   * @example
+   * ```ts
+   * const result = await client.data.getJobResult("job_abc123");
+   * console.log(result.result);
+   * ```
+   */
+  async getJobResult(jobId) {
+    if (!jobId || !jobId.trim()) {
+      throw new Error("jobId is required and cannot be empty");
+    }
+    const result = await get(
+      this.ctx,
+      `/v1/data/jobs/${jobId}/result`
+    );
+    return result.data;
+  }
+  /**
+   * 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");
+   * ```
+   */
+  async exportJob(jobId, format = "json") {
+    if (!jobId || !jobId.trim()) {
+      throw new Error("jobId is required and cannot be empty");
+    }
+    const result = await get(
+      this.ctx,
+      `/v1/data/jobs/${jobId}/export`,
+      { format }
+    );
+    return result.data;
+  }
   // ============================================
   // DEALS
   // ============================================
@@ -3013,6 +3082,31 @@ var StatusResource = class {
     );
     return result.data;
   }
+  /**
+   * 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);
+   * ```
+   */
+  async getJobErrors(jobId, options) {
+    const result = await get(
+      this.ctx,
+      `/v1/status/${jobId}/errors`,
+      {
+        limit: options?.limit,
+        offset: options?.offset
+      }
+    );
+    return result.data;
+  }
   /**
    * Cancel a pending or active job
    *
@@ -3248,6 +3342,106 @@ var WebhooksResource = class {
     const all = await this.list();
     return all.data.filter((w) => w.event === event);
   }
+  /**
+   * 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);
+   * ```
+   */
+  async rotateSecret(webhookId, options) {
+    if (!webhookId || !webhookId.trim()) {
+      throw new Error("webhookId is required and cannot be empty");
+    }
+    if (!options.newSecret || options.newSecret.length < 16) {
+      throw new Error("newSecret must be at least 16 characters long");
+    }
+    const result = await post(
+      this.ctx,
+      `/v1/webhooks/${webhookId}/rotate`,
+      {
+        newSecret: options.newSecret,
+        gracePeriodHours: options.gracePeriodHours ?? 24
+      }
+    );
+    return result.data;
+  }
+  /**
+   * 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}`);
+   * }
+   * ```
+   */
+  async getSecretStatus(webhookId) {
+    if (!webhookId || !webhookId.trim()) {
+      throw new Error("webhookId is required and cannot be empty");
+    }
+    const result = await get(
+      this.ctx,
+      `/v1/webhooks/${webhookId}/secret-status`
+    );
+    return result.data;
+  }
+  /**
+   * 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}`);
+   * }
+   * ```
+   */
+  async verifySignature(options) {
+    if (!options.webhookId || !options.webhookId.trim()) {
+      throw new Error("webhookId is required and cannot be empty");
+    }
+    if (!options.signature) {
+      throw new Error("signature is required");
+    }
+    if (!options.timestamp || options.timestamp <= 0) {
+      throw new Error("timestamp is required and must be positive");
+    }
+    if (!options.nonce || !/^[0-9a-f]{32}$/i.test(options.nonce)) {
+      throw new Error("nonce must be a 32-character hex string");
+    }
+    const result = await post(
+      this.ctx,
+      "/v1/webhooks/verify",
+      {
+        webhookId: options.webhookId,
+        payload: options.payload,
+        signature: options.signature,
+        timestamp: options.timestamp,
+        nonce: options.nonce
+      }
+    );
+    return result.data;
+  }
 };
 
 // src/client.ts