valyu-js 2.5.8 → 2.5.9

package/README.md

@@ -334,63 +334,94 @@ Each `SearchResult` contains:
 
 The `contents()` method extracts clean, structured content from web pages with optional AI-powered data extraction and summarization. It accepts an array of URLs as the first parameter, followed by optional configuration parameters.
 
+- **Sync mode** (≤10 URLs): Returns results immediately
+- **Async mode** (>10 URLs or `async: true`): Returns a job object; use `getContentsJob()` or `waitForJob()` to get results
+
 ```javascript
-valyu.contents(
-  urls, // Array of URLs to process (max 10)
-  {
-    summary: false, // AI processing: false, true, string, or JSON schema
-    extractEffort: "normal", // Extraction effort: "normal" or "high"
-    responseLength: "short", // Content length control
-    maxPriceDollars: null, // Maximum cost limit in USD
-  }
-);
+// Sync (≤10 URLs)
+const response = await valyu.contents(urls, { summary: true });
+
+// Async (11-50 URLs) - returns job, then poll or wait
+const job = await valyu.contents(urls, { async: true });
+const final = await valyu.waitForJob(job.jobId, { pollInterval: 5000 });
 ```
 
 ### Parameters
 
 | Parameter         | Type                          | Default    | Description                                                                                                                                  |
 | ----------------- | ----------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `urls`            | `string[]`                    | _required_ | Array of URLs to process (maximum 10 URLs per request)                                                                                       |
+| `urls`            | `string[]`                    | _required_ | Array of URLs to process (max 10 sync, max 50 with `async: true`)                                                                             |
 | `summary`         | `boolean \| string \| object` | `false`    | AI summary configuration: `false` (raw content), `true` (auto summary), string (custom instructions), or JSON schema (structured extraction) |
-| `extractEffort`   | `string`                      | `"normal"` | Extraction thoroughness: `"normal"` (fast) or `"high"` (more thorough but slower)                                                            |
+| `extractEffort`   | `string`                      | `"normal"` | Extraction thoroughness: `"normal"`, `"high"`, or `"auto"`                                                                                     |
 | `responseLength`  | `string \| number`            | `"short"`  | Content length per URL: `"short"` (25k chars), `"medium"` (50k), `"large"` (100k), `"max"` (no limit), or custom number                      |
 | `maxPriceDollars` | `number`                      | `null`     | Maximum cost limit in USD                                                                                                                    |
+| `screenshot`      | `boolean`                     | `false`    | Capture page screenshots                                                                                                                      |
+| `async`           | `boolean`                     | `false`    | Force async processing (required for >10 URLs)                                                                                               |
+| `webhookUrl`      | `string`                      | -          | HTTPS URL for completion notification (async only). Save `webhookSecret` for signature verification.                                          |
 
-### Contents Response Format
+### Contents Response Format (Sync)
 
-The contents method returns a `ContentsResponse` object with the following structure:
+When sync, returns `ContentsResponse`:
 
 ```javascript
 {
-    success: boolean,                           // Request success status
-    error: string | null,                       // Error message if any
-    tx_id: string,                              // Transaction ID for tracking
-    urls_requested: number,                     // Total URLs requested
-    urls_processed: number,                     // Successfully processed URLs
-    urls_failed: number,                        // Failed URL count
-    results: ContentResult[],                   // Array of processed results
-    total_cost_dollars: number,                 // Actual cost charged
-    total_characters: number                    // Total characters extracted
+    success: boolean,
+    tx_id: string,
+    urls_requested: number,
+    urls_processed: number,
+    urls_failed: number,
+    results: ContentResult[],
+    total_cost_dollars: number,
+    total_characters: number
 }
 ```
 
-Each `ContentResult` contains:
+### Contents Async Response
+
+When async, returns `ContentsAsyncJobResponse` with `jobId`. Use `getContentsJob(jobId)` or `waitForJob(jobId)` to get results.
 
 ```javascript
-{
-    url: string,                                // Source URL
-    title: string,                              // Page/document title
-    content: string | number,                   // Extracted content
-    length: number,                             // Content length in characters
-    source: string,                             // Data source identifier
-    summary?: string | object,                  // AI-generated summary (if enabled)
-    summary_success?: boolean,                  // Whether summary generation succeeded
-    data_type?: string,                         // Type of data extracted
-    image_url?: Record<string, string>,         // Extracted images
-    citation?: string                           // APA-style citation
+// Poll for status
+const status = await valyu.getContentsJob(jobId);
+
+// Or wait until complete (like DeepResearch wait)
+const final = await valyu.waitForJob(jobId, {
+  pollInterval: 5000,
+  maxWaitTime: 7200000,
+  onProgress: (s) => console.log(`${s.urlsProcessed}/${s.urlsTotal}`)
+});
+```
+
+### ContentResult (with status)
+
+Each result has a `status` field. Check before accessing success-only fields:
+
+```javascript
+for (const r of response.results) {
+  if (r.status === 'success') {
+    console.log(r.title, r.content);
+  } else {
+    console.log(`Failed: ${r.url} - ${r.error}`);
+  }
 }
 ```
 
+### Webhook Signature Verification
+
+When using `webhookUrl`, verify the `X-Webhook-Signature` header with the `webhookSecret` from job creation:
+
+```javascript
+const { verifyContentsWebhookSignature } = require('valyu-js');
+
+// In your webhook handler - use raw request body
+const isValid = verifyContentsWebhookSignature(
+  rawBody,           // Raw request body string
+  signatureHeader,   // X-Webhook-Signature
+  timestampHeader,   // X-Webhook-Timestamp
+  webhookSecret
+);
+```
+
 ## Examples
 
 ### Basic Search

package/dist/index.d.mts

@@ -59,22 +59,65 @@ interface ContentsOptions {
     responseLength?: ContentResponseLength;
     maxPriceDollars?: number;
     screenshot?: boolean;
+    async?: boolean;
+    webhookUrl?: string;
 }
-interface ContentResult {
+interface ContentResultBase {
     url: string;
+    status: "success" | "failed";
+}
+interface ContentResultSuccess extends ContentResultBase {
+    status: "success";
     title: string;
     content: string | number;
     length: number;
     source: string;
-    price: number;
+    price?: number;
     description?: string;
     summary?: string | object;
     summary_success?: boolean;
     data_type?: string;
     image_url?: Record<string, string>;
     screenshot_url?: string | null;
+    source_type?: string;
+    publication_date?: string;
     citation?: string;
 }
+interface ContentResultFailed extends ContentResultBase {
+    status: "failed";
+    error: string;
+}
+type ContentResult = ContentResultSuccess | ContentResultFailed;
+type ContentsJobStatus = "pending" | "processing" | "completed" | "partial" | "failed";
+interface ContentsJobWaitOptions {
+    pollInterval?: number;
+    maxWaitTime?: number;
+    onProgress?: (status: ContentsJobResponse) => void;
+}
+interface ContentsJobResponse {
+    success: boolean;
+    jobId: string;
+    status: ContentsJobStatus;
+    urlsTotal: number;
+    urlsProcessed: number;
+    urlsFailed: number;
+    createdAt: number;
+    updatedAt: number;
+    currentBatch?: number;
+    totalBatches?: number;
+    results?: ContentResult[];
+    actualCostDollars?: number;
+    error?: string;
+    webhookSecret?: string;
+}
+interface ContentsAsyncJobResponse {
+    success: boolean;
+    jobId: string;
+    status: "pending";
+    urlsTotal: number;
+    webhookSecret?: string;
+    txId: string;
+}
 interface ContentsResponse {
     success: boolean;
     error?: string | null;
@@ -576,6 +619,15 @@ interface DatasourcesCategoriesResponse {
     error?: string;
 }
 
+/**
+ * Verify webhook signature for Contents API async completion notifications.
+ * Use the raw request body (not parsed JSON) as payload.
+ * @param payload - Raw request body string
+ * @param signature - X-Webhook-Signature header value
+ * @param timestamp - X-Webhook-Timestamp header value
+ * @param secret - webhookSecret from job creation
+ */
+declare function verifyContentsWebhookSignature(payload: string, signature: string, timestamp: string, secret: string): boolean;
 declare class Valyu {
     private baseUrl;
     private headers;
@@ -652,16 +704,31 @@ declare class Valyu {
     search(query: string, options?: SearchOptions): Promise<SearchResponse>;
     /**
      * Extract content from URLs with optional AI processing
-     * @param urls - Array of URLs to process (max 10)
+     * @param urls - Array of URLs to process (max 10 sync, max 50 with async: true)
      * @param options - Content extraction configuration options
      * @param options.summary - AI summary configuration: false (raw), true (auto), string (custom), or JSON schema
      * @param options.extractEffort - Extraction thoroughness: "normal", "high", or "auto"
      * @param options.responseLength - Content length per URL
      * @param options.maxPriceDollars - Maximum cost limit in USD
      * @param options.screenshot - Request page screenshots (default: false)
-     * @returns Promise resolving to content extraction results
+     * @param options.async - Force async processing (required for >10 URLs)
+     * @param options.webhookUrl - HTTPS URL for completion notification (async only)
+     * @returns Promise resolving to sync results or async job (when async: true or >10 URLs)
+     */
+    contents(urls: string[], options?: ContentsOptions): Promise<ContentsResponse | ContentsAsyncJobResponse>;
+    /**
+     * Get async Contents job status and results
+     * @param jobId - Job ID from contents() async response
+     * @returns Promise resolving to job status
+     */
+    getContentsJob(jobId: string): Promise<ContentsJobResponse>;
+    /**
+     * Wait for async Contents job completion (polls until terminal state)
+     * @param jobId - Job ID from contents() async response
+     * @param options - Wait configuration (pollInterval, maxWaitTime, onProgress)
+     * @returns Promise resolving to final job status with results
      */
-    contents(urls: string[], options?: ContentsOptions): Promise<ContentsResponse>;
+    waitForJob(jobId: string, options?: ContentsJobWaitOptions): Promise<ContentsJobResponse>;
     /**
      * DeepResearch: Create a new research task
      * @param options.search - Search configuration options
@@ -826,4 +893,4 @@ declare class Valyu {
     private _datasourcesCategories;
 }
 
-export { type AIUsage, type AddBatchTasksOptions, type AddBatchTasksResponse, type AlertEmailConfig, type AnswerErrorResponse, type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamChunkType, type AnswerSuccessResponse, type BatchCounts, type BatchPagination, type BatchStatus, type BatchStatusResponse, type BatchTaskCreated, type BatchTaskInput, type BatchTaskListItem, type BatchWaitOptions, type CancelBatchResponse, type ChartDataPoint, type ChartDataSeries, type ChartType, type ContentResponseLength, type ContentResult, type ContentsOptions, type ContentsResponse, type Cost, type CountryCode, type CreateBatchOptions, type CreateBatchResponse, type Datasource, type DatasourceCategory, type DatasourceCategoryId, type DatasourceCoverage, type DatasourceModality, type DatasourcePricing, type DatasourcesCategoriesResponse, type DatasourcesListOptions, type DatasourcesListResponse, type DeepResearchBatch, type DeepResearchCancelResponse, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchGetAssetsOptions, type DeepResearchGetAssetsResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type ImageMetadata, type ImageType, type ListBatchTasksOptions, type ListBatchTasksResponse, type ListBatchesOptions, type ListBatchesResponse, type ListOptions, type MCPServerConfig, type Progress, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, Valyu, type WaitOptions };
+export { type AIUsage, type AddBatchTasksOptions, type AddBatchTasksResponse, type AlertEmailConfig, type AnswerErrorResponse, type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamChunkType, type AnswerSuccessResponse, type BatchCounts, type BatchPagination, type BatchStatus, type BatchStatusResponse, type BatchTaskCreated, type BatchTaskInput, type BatchTaskListItem, type BatchWaitOptions, type CancelBatchResponse, type ChartDataPoint, type ChartDataSeries, type ChartType, type ContentResponseLength, type ContentResult, type ContentResultFailed, type ContentResultSuccess, type ContentsAsyncJobResponse, type ContentsJobResponse, type ContentsJobStatus, type ContentsJobWaitOptions, type ContentsOptions, type ContentsResponse, type Cost, type CountryCode, type CreateBatchOptions, type CreateBatchResponse, type Datasource, type DatasourceCategory, type DatasourceCategoryId, type DatasourceCoverage, type DatasourceModality, type DatasourcePricing, type DatasourcesCategoriesResponse, type DatasourcesListOptions, type DatasourcesListResponse, type DeepResearchBatch, type DeepResearchCancelResponse, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchGetAssetsOptions, type DeepResearchGetAssetsResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type ImageMetadata, type ImageType, type ListBatchTasksOptions, type ListBatchTasksResponse, type ListBatchesOptions, type ListBatchesResponse, type ListOptions, type MCPServerConfig, type Progress, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, Valyu, type WaitOptions, verifyContentsWebhookSignature };

package/dist/index.d.ts

@@ -59,22 +59,65 @@ interface ContentsOptions {
     responseLength?: ContentResponseLength;
     maxPriceDollars?: number;
     screenshot?: boolean;
+    async?: boolean;
+    webhookUrl?: string;
 }
-interface ContentResult {
+interface ContentResultBase {
     url: string;
+    status: "success" | "failed";
+}
+interface ContentResultSuccess extends ContentResultBase {
+    status: "success";
     title: string;
     content: string | number;
     length: number;
     source: string;
-    price: number;
+    price?: number;
     description?: string;
     summary?: string | object;
     summary_success?: boolean;
     data_type?: string;
     image_url?: Record<string, string>;
     screenshot_url?: string | null;
+    source_type?: string;
+    publication_date?: string;
     citation?: string;
 }
+interface ContentResultFailed extends ContentResultBase {
+    status: "failed";
+    error: string;
+}
+type ContentResult = ContentResultSuccess | ContentResultFailed;
+type ContentsJobStatus = "pending" | "processing" | "completed" | "partial" | "failed";
+interface ContentsJobWaitOptions {
+    pollInterval?: number;
+    maxWaitTime?: number;
+    onProgress?: (status: ContentsJobResponse) => void;
+}
+interface ContentsJobResponse {
+    success: boolean;
+    jobId: string;
+    status: ContentsJobStatus;
+    urlsTotal: number;
+    urlsProcessed: number;
+    urlsFailed: number;
+    createdAt: number;
+    updatedAt: number;
+    currentBatch?: number;
+    totalBatches?: number;
+    results?: ContentResult[];
+    actualCostDollars?: number;
+    error?: string;
+    webhookSecret?: string;
+}
+interface ContentsAsyncJobResponse {
+    success: boolean;
+    jobId: string;
+    status: "pending";
+    urlsTotal: number;
+    webhookSecret?: string;
+    txId: string;
+}
 interface ContentsResponse {
     success: boolean;
     error?: string | null;
@@ -576,6 +619,15 @@ interface DatasourcesCategoriesResponse {
     error?: string;
 }
 
+/**
+ * Verify webhook signature for Contents API async completion notifications.
+ * Use the raw request body (not parsed JSON) as payload.
+ * @param payload - Raw request body string
+ * @param signature - X-Webhook-Signature header value
+ * @param timestamp - X-Webhook-Timestamp header value
+ * @param secret - webhookSecret from job creation
+ */
+declare function verifyContentsWebhookSignature(payload: string, signature: string, timestamp: string, secret: string): boolean;
 declare class Valyu {
     private baseUrl;
     private headers;
@@ -652,16 +704,31 @@ declare class Valyu {
     search(query: string, options?: SearchOptions): Promise<SearchResponse>;
     /**
      * Extract content from URLs with optional AI processing
-     * @param urls - Array of URLs to process (max 10)
+     * @param urls - Array of URLs to process (max 10 sync, max 50 with async: true)
      * @param options - Content extraction configuration options
      * @param options.summary - AI summary configuration: false (raw), true (auto), string (custom), or JSON schema
      * @param options.extractEffort - Extraction thoroughness: "normal", "high", or "auto"
      * @param options.responseLength - Content length per URL
      * @param options.maxPriceDollars - Maximum cost limit in USD
      * @param options.screenshot - Request page screenshots (default: false)
-     * @returns Promise resolving to content extraction results
+     * @param options.async - Force async processing (required for >10 URLs)
+     * @param options.webhookUrl - HTTPS URL for completion notification (async only)
+     * @returns Promise resolving to sync results or async job (when async: true or >10 URLs)
+     */
+    contents(urls: string[], options?: ContentsOptions): Promise<ContentsResponse | ContentsAsyncJobResponse>;
+    /**
+     * Get async Contents job status and results
+     * @param jobId - Job ID from contents() async response
+     * @returns Promise resolving to job status
+     */
+    getContentsJob(jobId: string): Promise<ContentsJobResponse>;
+    /**
+     * Wait for async Contents job completion (polls until terminal state)
+     * @param jobId - Job ID from contents() async response
+     * @param options - Wait configuration (pollInterval, maxWaitTime, onProgress)
+     * @returns Promise resolving to final job status with results
      */
-    contents(urls: string[], options?: ContentsOptions): Promise<ContentsResponse>;
+    waitForJob(jobId: string, options?: ContentsJobWaitOptions): Promise<ContentsJobResponse>;
     /**
      * DeepResearch: Create a new research task
      * @param options.search - Search configuration options
@@ -826,4 +893,4 @@ declare class Valyu {
     private _datasourcesCategories;
 }
 
-export { type AIUsage, type AddBatchTasksOptions, type AddBatchTasksResponse, type AlertEmailConfig, type AnswerErrorResponse, type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamChunkType, type AnswerSuccessResponse, type BatchCounts, type BatchPagination, type BatchStatus, type BatchStatusResponse, type BatchTaskCreated, type BatchTaskInput, type BatchTaskListItem, type BatchWaitOptions, type CancelBatchResponse, type ChartDataPoint, type ChartDataSeries, type ChartType, type ContentResponseLength, type ContentResult, type ContentsOptions, type ContentsResponse, type Cost, type CountryCode, type CreateBatchOptions, type CreateBatchResponse, type Datasource, type DatasourceCategory, type DatasourceCategoryId, type DatasourceCoverage, type DatasourceModality, type DatasourcePricing, type DatasourcesCategoriesResponse, type DatasourcesListOptions, type DatasourcesListResponse, type DeepResearchBatch, type DeepResearchCancelResponse, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchGetAssetsOptions, type DeepResearchGetAssetsResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type ImageMetadata, type ImageType, type ListBatchTasksOptions, type ListBatchTasksResponse, type ListBatchesOptions, type ListBatchesResponse, type ListOptions, type MCPServerConfig, type Progress, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, Valyu, type WaitOptions };
+export { type AIUsage, type AddBatchTasksOptions, type AddBatchTasksResponse, type AlertEmailConfig, type AnswerErrorResponse, type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamChunkType, type AnswerSuccessResponse, type BatchCounts, type BatchPagination, type BatchStatus, type BatchStatusResponse, type BatchTaskCreated, type BatchTaskInput, type BatchTaskListItem, type BatchWaitOptions, type CancelBatchResponse, type ChartDataPoint, type ChartDataSeries, type ChartType, type ContentResponseLength, type ContentResult, type ContentResultFailed, type ContentResultSuccess, type ContentsAsyncJobResponse, type ContentsJobResponse, type ContentsJobStatus, type ContentsJobWaitOptions, type ContentsOptions, type ContentsResponse, type Cost, type CountryCode, type CreateBatchOptions, type CreateBatchResponse, type Datasource, type DatasourceCategory, type DatasourceCategoryId, type DatasourceCoverage, type DatasourceModality, type DatasourcePricing, type DatasourcesCategoriesResponse, type DatasourcesListOptions, type DatasourcesListResponse, type DeepResearchBatch, type DeepResearchCancelResponse, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchGetAssetsOptions, type DeepResearchGetAssetsResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type ImageMetadata, type ImageType, type ListBatchTasksOptions, type ListBatchTasksResponse, type ListBatchesOptions, type ListBatchesResponse, type ListOptions, type MCPServerConfig, type Progress, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, Valyu, type WaitOptions, verifyContentsWebhookSignature };

package/dist/index.js

@@ -30,10 +30,49 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  Valyu: () => Valyu
+  Valyu: () => Valyu,
+  verifyContentsWebhookSignature: () => verifyContentsWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
+var import_crypto = require("crypto");
 var import_axios = __toESM(require("axios"));
+function normalizeContentsJobResponse(api) {
+  return {
+    success: api.success ?? true,
+    jobId: api.job_id ?? api.jobId,
+    status: api.status ?? "pending",
+    urlsTotal: api.urls_total ?? api.urlsTotal ?? 0,
+    urlsProcessed: api.urls_processed ?? api.urlsProcessed ?? 0,
+    urlsFailed: api.urls_failed ?? api.urlsFailed ?? 0,
+    createdAt: api.created_at ?? api.createdAt ?? 0,
+    updatedAt: api.updated_at ?? api.updatedAt ?? 0,
+    currentBatch: api.current_batch ?? api.currentBatch,
+    totalBatches: api.total_batches ?? api.totalBatches,
+    results: api.results,
+    actualCostDollars: api.actual_cost_dollars ?? api.actualCostDollars,
+    error: api.error,
+    webhookSecret: api.webhook_secret ?? api.webhookSecret
+  };
+}
+function normalizeContentsAsyncJobResponse(api) {
+  return {
+    success: api.success ?? true,
+    jobId: api.job_id ?? api.jobId,
+    status: "pending",
+    urlsTotal: api.urls_total ?? api.urlsTotal ?? 0,
+    webhookSecret: api.webhook_secret ?? api.webhookSecret,
+    txId: api.tx_id ?? api.txId ?? ""
+  };
+}
+function verifyContentsWebhookSignature(payload, signature, timestamp, secret) {
+  const expected = (0, import_crypto.createHmac)("sha256", secret).update(`${timestamp}.${payload}`).digest("hex");
+  const expectedSignature = `sha256=${expected}`;
+  if (signature.length !== expectedSignature.length) return false;
+  return (0, import_crypto.timingSafeEqual)(
+    Buffer.from(signature, "utf8"),
+    Buffer.from(expectedSignature, "utf8")
+  );
+}
 var Valyu = class {
   constructor(apiKey, baseUrl = "https://api.valyu.ai/v1") {
     if (!apiKey) {
@@ -351,14 +390,16 @@ var Valyu = class {
   }
   /**
    * Extract content from URLs with optional AI processing
-   * @param urls - Array of URLs to process (max 10)
+   * @param urls - Array of URLs to process (max 10 sync, max 50 with async: true)
    * @param options - Content extraction configuration options
    * @param options.summary - AI summary configuration: false (raw), true (auto), string (custom), or JSON schema
    * @param options.extractEffort - Extraction thoroughness: "normal", "high", or "auto"
    * @param options.responseLength - Content length per URL
    * @param options.maxPriceDollars - Maximum cost limit in USD
    * @param options.screenshot - Request page screenshots (default: false)
-   * @returns Promise resolving to content extraction results
+   * @param options.async - Force async processing (required for >10 URLs)
+   * @param options.webhookUrl - HTTPS URL for completion notification (async only)
+   * @returns Promise resolving to sync results or async job (when async: true or >10 URLs)
    */
   async contents(urls, options = {}) {
     try {
@@ -386,10 +427,23 @@ var Valyu = class {
           total_characters: 0
         };
       }
-      if (urls.length > 10) {
+      const isAsync = options.async === true || urls.length > 10;
+      if (urls.length > 10 && !options.async) {
         return {
           success: false,
-          error: "Maximum 10 URLs allowed per request",
+          error: "Requests with more than 10 URLs require async processing. Add async: true to the request.",
+          urls_requested: urls.length,
+          urls_processed: 0,
+          urls_failed: urls.length,
+          results: [],
+          total_cost_dollars: 0,
+          total_characters: 0
+        };
+      }
+      if (urls.length > 50) {
+        return {
+          success: false,
+          error: "Maximum 50 URLs allowed per request",
           urls_requested: urls.length,
           urls_processed: 0,
           urls_failed: urls.length,
@@ -455,6 +509,12 @@ var Valyu = class {
       if (options.screenshot !== void 0) {
         payload.screenshot = options.screenshot;
       }
+      if (isAsync) {
+        payload.async = true;
+      }
+      if (options.webhookUrl !== void 0) {
+        payload.webhook_url = options.webhookUrl;
+      }
       const response = await import_axios.default.post(`${this.baseUrl}/contents`, payload, {
         headers: this.headers
       });
@@ -470,6 +530,9 @@ var Valyu = class {
           total_characters: 0
         };
       }
+      if (response.status === 202) {
+        return normalizeContentsAsyncJobResponse(response.data);
+      }
       return response.data;
     } catch (e) {
       return {
@@ -484,6 +547,61 @@ var Valyu = class {
       };
     }
   }
+  /**
+   * Get async Contents job status and results
+   * @param jobId - Job ID from contents() async response
+   * @returns Promise resolving to job status
+   */
+  async getContentsJob(jobId) {
+    try {
+      const response = await import_axios.default.get(
+        `${this.baseUrl}/contents/jobs/${jobId}`,
+        { headers: this.headers }
+      );
+      return normalizeContentsJobResponse(response.data);
+    } catch (e) {
+      const errData = e.response?.data;
+      const status = e.response?.status;
+      return {
+        success: false,
+        jobId,
+        status: "failed",
+        urlsTotal: 0,
+        urlsProcessed: 0,
+        urlsFailed: 0,
+        createdAt: 0,
+        updatedAt: 0,
+        error: errData?.error || (status === 403 ? "Forbidden - you do not have access to this job" : status === 404 ? `Job ${jobId} not found` : e.message)
+      };
+    }
+  }
+  /**
+   * Wait for async Contents job completion (polls until terminal state)
+   * @param jobId - Job ID from contents() async response
+   * @param options - Wait configuration (pollInterval, maxWaitTime, onProgress)
+   * @returns Promise resolving to final job status with results
+   */
+  async waitForJob(jobId, options = {}) {
+    const pollInterval = options.pollInterval ?? 5e3;
+    const maxWaitTime = options.maxWaitTime ?? 72e5;
+    const startTime = Date.now();
+    while (true) {
+      const status = await this.getContentsJob(jobId);
+      if (!status.success && status.error) {
+        throw new Error(status.error);
+      }
+      if (options.onProgress) {
+        options.onProgress(status);
+      }
+      if (status.status === "completed" || status.status === "partial" || status.status === "failed") {
+        return status;
+      }
+      if (Date.now() - startTime > maxWaitTime) {
+        throw new Error("Maximum wait time exceeded");
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+  }
   /**
    * DeepResearch: Create a new research task
    * @param options.search - Search configuration options
@@ -1377,6 +1495,7 @@ var Valyu = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  Valyu
+  Valyu,
+  verifyContentsWebhookSignature
 });
 //# sourceMappingURL=index.js.map