valyu-js 2.7.17 → 2.7.18

package/dist/index.d.mts

@@ -38,6 +38,7 @@ interface SearchOptions {
     category?: string;
     startDate?: string;
     endDate?: string;
+    historicalCache?: boolean;
     countryCode?: CountryCode;
     responseLength?: ResponseLength;
     fastMode?: boolean;
@@ -71,6 +72,9 @@ interface ContentsOptions {
     screenshot?: boolean;
     async?: boolean;
     webhookUrl?: string;
+    startDate?: string;
+    endDate?: string;
+    historicalCache?: boolean;
 }
 interface ContentResultBase {
     url: string;
@@ -281,6 +285,7 @@ interface DeepResearchSearchConfig {
     sourceBiases?: Record<string, number>;
     startDate?: string;
     endDate?: string;
+    historicalCache?: boolean;
     category?: string;
     countryCode?: CountryCode;
 }
@@ -806,6 +811,7 @@ declare class Valyu {
      * @param options.category - Category filter for search results
      * @param options.startDate - Start date filter (YYYY-MM-DD format)
      * @param options.endDate - End date filter (YYYY-MM-DD format)
+     * @param options.historicalCache - When true and a date range is set, return the newest cached snapshot inside the range instead of the latest crawl. No-op without a date range (default: false)
      * @param options.countryCode - Country code filter for search results
      * @param options.responseLength - Response content length: "short"/"medium"/"large"/"max" or integer character count
      * @param options.fastMode - Fast mode for quicker but shorter results (default: false)
@@ -824,6 +830,9 @@ declare class Valyu {
      * @param options.screenshot - Request page screenshots (default: false)
      * @param options.async - Force async processing (required for >10 URLs)
      * @param options.webhookUrl - HTTPS URL for completion notification (async only)
+     * @param options.startDate - Start date filter (YYYY-MM-DD format), inclusive
+     * @param options.endDate - End date filter (YYYY-MM-DD format), inclusive
+     * @param options.historicalCache - When true and a date range is set, return the newest cached snapshot inside the range instead of the latest crawl. No-op without a date range (default: false)
      * @returns Promise resolving to sync results or async job (when async: true or >10 URLs)
      */
     contents(urls: string[], options?: ContentsOptions): Promise<ContentsResponse | ContentsAsyncJobResponse>;
@@ -848,6 +857,7 @@ declare class Valyu {
      * @param options.search.excludedSources - Array of source types to exclude (e.g., ["web", "patent"])
      * @param options.search.startDate - Start date filter in ISO format (YYYY-MM-DD)
      * @param options.search.endDate - End date filter in ISO format (YYYY-MM-DD)
+     * @param options.search.historicalCache - When true and a date range is set, searches return the newest cached snapshot inside the range instead of the latest crawl. Locked for the whole research run — the agent cannot toggle it mid-research
      * @param options.search.category - Category filter for search results
      */
     private _deepresearchCreate;
@@ -922,6 +932,7 @@ declare class Valyu {
      * @param options.search.excludedSources - Array of source types to exclude (e.g., ["web", "patent"])
      * @param options.search.startDate - Start date filter in ISO format (YYYY-MM-DD)
      * @param options.search.endDate - End date filter in ISO format (YYYY-MM-DD)
+     * @param options.search.historicalCache - When true and a date range is set, searches return the newest cached snapshot inside the range instead of the latest crawl
      * @param options.search.category - Category filter for search results
      * @param options.webhookUrl - Optional HTTPS URL for completion notification
      * @param options.metadata - Optional metadata key-value pairs

package/dist/index.d.ts

@@ -38,6 +38,7 @@ interface SearchOptions {
     category?: string;
     startDate?: string;
     endDate?: string;
+    historicalCache?: boolean;
     countryCode?: CountryCode;
     responseLength?: ResponseLength;
     fastMode?: boolean;
@@ -71,6 +72,9 @@ interface ContentsOptions {
     screenshot?: boolean;
     async?: boolean;
     webhookUrl?: string;
+    startDate?: string;
+    endDate?: string;
+    historicalCache?: boolean;
 }
 interface ContentResultBase {
     url: string;
@@ -281,6 +285,7 @@ interface DeepResearchSearchConfig {
     sourceBiases?: Record<string, number>;
     startDate?: string;
     endDate?: string;
+    historicalCache?: boolean;
     category?: string;
     countryCode?: CountryCode;
 }
@@ -806,6 +811,7 @@ declare class Valyu {
      * @param options.category - Category filter for search results
      * @param options.startDate - Start date filter (YYYY-MM-DD format)
      * @param options.endDate - End date filter (YYYY-MM-DD format)
+     * @param options.historicalCache - When true and a date range is set, return the newest cached snapshot inside the range instead of the latest crawl. No-op without a date range (default: false)
      * @param options.countryCode - Country code filter for search results
      * @param options.responseLength - Response content length: "short"/"medium"/"large"/"max" or integer character count
      * @param options.fastMode - Fast mode for quicker but shorter results (default: false)
@@ -824,6 +830,9 @@ declare class Valyu {
      * @param options.screenshot - Request page screenshots (default: false)
      * @param options.async - Force async processing (required for >10 URLs)
      * @param options.webhookUrl - HTTPS URL for completion notification (async only)
+     * @param options.startDate - Start date filter (YYYY-MM-DD format), inclusive
+     * @param options.endDate - End date filter (YYYY-MM-DD format), inclusive
+     * @param options.historicalCache - When true and a date range is set, return the newest cached snapshot inside the range instead of the latest crawl. No-op without a date range (default: false)
      * @returns Promise resolving to sync results or async job (when async: true or >10 URLs)
      */
     contents(urls: string[], options?: ContentsOptions): Promise<ContentsResponse | ContentsAsyncJobResponse>;
@@ -848,6 +857,7 @@ declare class Valyu {
      * @param options.search.excludedSources - Array of source types to exclude (e.g., ["web", "patent"])
      * @param options.search.startDate - Start date filter in ISO format (YYYY-MM-DD)
      * @param options.search.endDate - End date filter in ISO format (YYYY-MM-DD)
+     * @param options.search.historicalCache - When true and a date range is set, searches return the newest cached snapshot inside the range instead of the latest crawl. Locked for the whole research run — the agent cannot toggle it mid-research
      * @param options.search.category - Category filter for search results
      */
     private _deepresearchCreate;
@@ -922,6 +932,7 @@ declare class Valyu {
      * @param options.search.excludedSources - Array of source types to exclude (e.g., ["web", "patent"])
      * @param options.search.startDate - Start date filter in ISO format (YYYY-MM-DD)
      * @param options.search.endDate - End date filter in ISO format (YYYY-MM-DD)
+     * @param options.search.historicalCache - When true and a date range is set, searches return the newest cached snapshot inside the range instead of the latest crawl
      * @param options.search.category - Category filter for search results
      * @param options.webhookUrl - Optional HTTPS URL for completion notification
      * @param options.metadata - Optional metadata key-value pairs

package/dist/index.js

@@ -213,6 +213,7 @@ var Valyu = class {
    * @param options.category - Category filter for search results
    * @param options.startDate - Start date filter (YYYY-MM-DD format)
    * @param options.endDate - End date filter (YYYY-MM-DD format)
+   * @param options.historicalCache - When true and a date range is set, return the newest cached snapshot inside the range instead of the latest crawl. No-op without a date range (default: false)
    * @param options.countryCode - Country code filter for search results
    * @param options.responseLength - Response content length: "short"/"medium"/"large"/"max" or integer character count
    * @param options.fastMode - Fast mode for quicker but shorter results (default: false)
@@ -368,6 +369,9 @@ var Valyu = class {
       if (options.endDate !== void 0) {
         payload.end_date = options.endDate;
       }
+      if (options.historicalCache !== void 0) {
+        payload.historical_cache = options.historicalCache;
+      }
       if (options.countryCode !== void 0) {
         payload.country_code = options.countryCode;
       }
@@ -423,6 +427,9 @@ var Valyu = class {
    * @param options.screenshot - Request page screenshots (default: false)
    * @param options.async - Force async processing (required for >10 URLs)
    * @param options.webhookUrl - HTTPS URL for completion notification (async only)
+   * @param options.startDate - Start date filter (YYYY-MM-DD format), inclusive
+   * @param options.endDate - End date filter (YYYY-MM-DD format), inclusive
+   * @param options.historicalCache - When true and a date range is set, return the newest cached snapshot inside the range instead of the latest crawl. No-op without a date range (default: false)
    * @returns Promise resolving to sync results or async job (when async: true or >10 URLs)
    */
   async contents(urls, options = {}) {
@@ -539,6 +546,15 @@ var Valyu = class {
       if (options.webhookUrl !== void 0) {
         payload.webhook_url = options.webhookUrl;
       }
+      if (options.startDate !== void 0) {
+        payload.start_date = options.startDate;
+      }
+      if (options.endDate !== void 0) {
+        payload.end_date = options.endDate;
+      }
+      if (options.historicalCache !== void 0) {
+        payload.historical_cache = options.historicalCache;
+      }
       const response = await this.client.post(`${this.baseUrl}/contents`, payload, {
         headers: this.headers
       });
@@ -634,6 +650,7 @@ var Valyu = class {
    * @param options.search.excludedSources - Array of source types to exclude (e.g., ["web", "patent"])
    * @param options.search.startDate - Start date filter in ISO format (YYYY-MM-DD)
    * @param options.search.endDate - End date filter in ISO format (YYYY-MM-DD)
+   * @param options.search.historicalCache - When true and a date range is set, searches return the newest cached snapshot inside the range instead of the latest crawl. Locked for the whole research run — the agent cannot toggle it mid-research
    * @param options.search.category - Category filter for search results
    */
   async _deepresearchCreate(options) {
@@ -707,6 +724,9 @@ var Valyu = class {
         if (options.search.endDate) {
           payload.search.end_date = options.search.endDate;
         }
+        if (options.search.historicalCache !== void 0) {
+          payload.search.historical_cache = options.search.historicalCache;
+        }
         if (options.search.category) {
           payload.search.category = options.search.category;
         }
@@ -1065,6 +1085,7 @@ var Valyu = class {
    * @param options.search.excludedSources - Array of source types to exclude (e.g., ["web", "patent"])
    * @param options.search.startDate - Start date filter in ISO format (YYYY-MM-DD)
    * @param options.search.endDate - End date filter in ISO format (YYYY-MM-DD)
+   * @param options.search.historicalCache - When true and a date range is set, searches return the newest cached snapshot inside the range instead of the latest crawl
    * @param options.search.category - Category filter for search results
    * @param options.webhookUrl - Optional HTTPS URL for completion notification
    * @param options.metadata - Optional metadata key-value pairs
@@ -1097,6 +1118,9 @@ var Valyu = class {
         if (options.search.endDate) {
           payload.search.end_date = options.search.endDate;
         }
+        if (options.search.historicalCache !== void 0) {
+          payload.search.historical_cache = options.search.historicalCache;
+        }
         if (options.search.category) {
           payload.search.category = options.search.category;
         }