valyu-js 2.7.17 → 2.8.0

package/dist/index.mjs

@@ -3,7 +3,7 @@ import { createHmac, timingSafeEqual } from "crypto";
 import http from "http";
 import https from "https";
 import axios from "axios";
-var SDK_VERSION = "2.7.17";
+var SDK_VERSION = "2.8.0";
 function normalizeContentsJobResponse(api) {
   return {
     success: api.success ?? true,
@@ -94,6 +94,15 @@ var Valyu = class {
       list: this._datasourcesList.bind(this),
       categories: this._datasourcesCategories.bind(this)
     };
+    this.workflows = {
+      list: this._workflowsList.bind(this),
+      get: this._workflowsGet.bind(this),
+      versions: this._workflowsVersions.bind(this),
+      preview: this._workflowsPreview.bind(this),
+      create: this._workflowsCreate.bind(this),
+      update: this._workflowsUpdate.bind(this),
+      delete: this._workflowsDelete.bind(this)
+    };
   }
   /**
    * Validates date format (YYYY-MM-DD)
@@ -178,6 +187,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)
@@ -333,6 +343,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;
       }
@@ -388,6 +401,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 = {}) {
@@ -504,6 +520,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
       });
@@ -599,11 +624,47 @@ 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) {
     try {
       const queryValue = options.query ?? options.input;
+      if (options.workflowId) {
+        if (queryValue || options.strategy || options.researchStrategy || options.reportFormat) {
+          return {
+            success: false,
+            error: "workflowId is mutually exclusive with query/input/researchStrategy/reportFormat - the workflow template supplies those fields"
+          };
+        }
+        const payload2 = {
+          workflow_id: options.workflowId
+        };
+        if (options.workflowParams !== void 0) {
+          payload2.workflow_params = options.workflowParams;
+        }
+        if (options.workflowVersion !== void 0) {
+          payload2.workflow_version = options.workflowVersion;
+        }
+        const explicitMode = options.mode ?? options.model;
+        if (explicitMode) payload2.mode = explicitMode;
+        if (options.outputFormats) payload2.output_formats = options.outputFormats;
+        if (options.tools) payload2.tools = options.tools;
+        if (options.webhookUrl) payload2.webhook_url = options.webhookUrl;
+        if (options.alertEmail) {
+          payload2.alert_email = typeof options.alertEmail === "string" ? options.alertEmail : {
+            email: options.alertEmail.email,
+            custom_url: options.alertEmail.custom_url
+          };
+        }
+        if (options.metadata) payload2.metadata = options.metadata;
+        const response2 = await this.client.post(
+          `${this.baseUrl}/deepresearch/tasks`,
+          payload2,
+          { headers: this.headers }
+        );
+        return { success: true, ...response2.data };
+      }
       if (!queryValue?.trim()) {
         return {
           success: false,
@@ -672,6 +733,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;
         }
@@ -1030,6 +1094,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
@@ -1062,6 +1127,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;
         }
@@ -1615,6 +1683,160 @@ var Valyu = class {
       };
     }
   }
+  /** Extract the most descriptive error message from a Workflows API error. */
+  workflowError(e) {
+    return e.response?.data?.message || e.response?.data?.error || e.message;
+  }
+  /**
+   * Workflows: List workflows available to your org
+   * @param options - Filters: vertical, scope ("valyu" | "org" | "all"), q, tags, limit, expand
+   */
+  async _workflowsList(options = {}) {
+    try {
+      const params = new URLSearchParams();
+      if (options.vertical) params.append("vertical", options.vertical);
+      if (options.scope) params.append("scope", options.scope);
+      if (options.q) params.append("q", options.q);
+      if (options.tags?.length) params.append("tags", options.tags.join(","));
+      if (options.limit !== void 0) {
+        params.append("limit", String(options.limit));
+      }
+      if (options.expand) params.append("expand", "true");
+      const url = `${this.baseUrl}/workflows${params.toString() ? `?${params.toString()}` : ""}`;
+      const response = await this.client.get(url, { headers: this.headers });
+      return { success: true, ...response.data };
+    } catch (e) {
+      return { success: false, error: this.workflowError(e) };
+    }
+  }
+  /**
+   * Workflows: Get a workflow's full detail, including its template
+   * @param slug - Workflow slug
+   * @param version - Specific version to fetch (defaults to the current version)
+   */
+  async _workflowsGet(slug, version) {
+    try {
+      const url = `${this.baseUrl}/workflows/${encodeURIComponent(slug)}${version !== void 0 ? `?version=${version}` : ""}`;
+      const response = await this.client.get(url, { headers: this.headers });
+      return { success: true, workflow: response.data };
+    } catch (e) {
+      return { success: false, error: this.workflowError(e) };
+    }
+  }
+  /**
+   * Workflows: List a workflow's version history
+   * @param slug - Workflow slug
+   */
+  async _workflowsVersions(slug) {
+    try {
+      const response = await this.client.get(
+        `${this.baseUrl}/workflows/${encodeURIComponent(slug)}/versions`,
+        { headers: this.headers }
+      );
+      return { success: true, ...response.data };
+    } catch (e) {
+      return { success: false, error: this.workflowError(e) };
+    }
+  }
+  /**
+   * Workflows: Resolve a workflow's template with params without creating a task
+   * @param slug - Workflow slug
+   * @param options - workflowParams (variable values) and optional workflowVersion
+   */
+  async _workflowsPreview(slug, options = {}) {
+    try {
+      const payload = {};
+      if (options.workflowParams !== void 0) {
+        payload.workflow_params = options.workflowParams;
+      }
+      if (options.workflowVersion !== void 0) {
+        payload.workflow_version = options.workflowVersion;
+      }
+      const response = await this.client.post(
+        `${this.baseUrl}/workflows/${encodeURIComponent(slug)}/preview`,
+        payload,
+        { headers: this.headers }
+      );
+      return { success: true, ...response.data };
+    } catch (e) {
+      return { success: false, error: this.workflowError(e) };
+    }
+  }
+  /**
+   * Workflows: Create a new workflow for your org
+   * @param options - slug, title, version (template body), and optional metadata
+   */
+  async _workflowsCreate(options) {
+    try {
+      const payload = {
+        slug: options.slug,
+        title: options.title,
+        version: options.version
+      };
+      if (options.subtitle !== void 0) payload.subtitle = options.subtitle;
+      if (options.description !== void 0) {
+        payload.description = options.description;
+      }
+      if (options.vertical !== void 0) payload.vertical = options.vertical;
+      if (options.tags !== void 0) payload.tags = options.tags;
+      if (options.icon !== void 0) payload.icon = options.icon;
+      const response = await this.client.post(
+        `${this.baseUrl}/workflows`,
+        payload,
+        { headers: this.headers }
+      );
+      return { success: true, workflow: response.data };
+    } catch (e) {
+      return { success: false, error: this.workflowError(e) };
+    }
+  }
+  /**
+   * Workflows: Update a workflow's metadata and/or publish a new template version.
+   * Only workflows owned by your org can be updated; versions are append-only
+   * (a version body requires a changelog).
+   * @param slug - Workflow slug
+   * @param options - Metadata fields and/or a new version body
+   */
+  async _workflowsUpdate(slug, options) {
+    try {
+      const payload = {};
+      if (options.title !== void 0) payload.title = options.title;
+      if (options.subtitle !== void 0) payload.subtitle = options.subtitle;
+      if (options.description !== void 0) {
+        payload.description = options.description;
+      }
+      if (options.vertical !== void 0) payload.vertical = options.vertical;
+      if (options.tags !== void 0) payload.tags = options.tags;
+      if (options.icon !== void 0) payload.icon = options.icon;
+      if (options.version !== void 0) payload.version = options.version;
+      if (options.setCurrent !== void 0) {
+        payload.set_current = options.setCurrent;
+      }
+      const response = await this.client.patch(
+        `${this.baseUrl}/workflows/${encodeURIComponent(slug)}`,
+        payload,
+        { headers: this.headers }
+      );
+      return { success: true, workflow: response.data };
+    } catch (e) {
+      return { success: false, error: this.workflowError(e) };
+    }
+  }
+  /**
+   * Workflows: Delete a workflow owned by your org (soft delete)
+   * @param slug - Workflow slug
+   */
+  async _workflowsDelete(slug) {
+    try {
+      const response = await this.client.delete(
+        `${this.baseUrl}/workflows/${encodeURIComponent(slug)}`,
+        { headers: this.headers }
+      );
+      return { success: true, ...response.data };
+    } catch (e) {
+      return { success: false, error: this.workflowError(e) };
+    }
+  }
 };
 export {
   Valyu,