valyu-js 2.7.17 → 2.8.0

package/README.md

@@ -171,6 +171,57 @@ const result = await valyu.batch.waitForCompletion(batch.batch_id, {
 });
 ```
 
+### Workflows
+
+Templated DeepResearch starting points - curated by Valyu or created by your org - with typed `{variable}` placeholders and version history.
+
+```typescript
+// Browse curated workflows
+const catalog = await valyu.workflows.list({ scope: "valyu", vertical: "investment-banking" });
+for (const wf of catalog.workflows ?? []) {
+  console.log(`${wf.slug} - ${wf.title}`);
+}
+
+// Run one as a DeepResearch task
+const task = await valyu.deepresearch.create({
+  workflowId: "ib-company-profile",
+  workflowParams: { company: "NVIDIA (NVDA)" },
+});
+
+const result = await valyu.deepresearch.wait(task.deepresearch_id);
+console.log(result.output);
+```
+
+Create your own:
+
+```typescript
+await valyu.workflows.create({
+  slug: "weekly-competitor-scan",
+  title: "Weekly Competitor Scan",
+  version: {
+    prompt: "Summarize the week's most important developments at {company}.",
+    strategy: "Prioritize primary sources: filings, press releases, earnings calls.",
+    report_format: "Bullet-point briefing, grouped by theme.",
+    variables: [{ key: "company", label: "Company", required: true }],
+  },
+});
+```
+
+<details>
+<summary>All Workflows methods</summary>
+
+| Method | Description |
+|---|---|
+| `list(options?)` | List available workflows (filter by vertical, scope, tags, free text) |
+| `get(slug, version?)` | Get a workflow's full template |
+| `versions(slug)` | List a workflow's version history |
+| `preview(slug, options?)` | Resolve the template without creating a task |
+| `create(options)` | Create an org workflow |
+| `update(slug, options)` | Update metadata and/or publish a new version |
+| `delete(slug)` | Delete an org workflow |
+
+</details>
+
 ### Data Sources
 
 List available data sources programmatically.

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;
 }
@@ -324,6 +329,9 @@ interface DeepResearchCreateOptions {
     brandCollectionId?: string;
     metadata?: Record<string, string | number | boolean>;
     hitl?: HitlConfig;
+    workflowId?: string;
+    workflowParams?: Record<string, any>;
+    workflowVersion?: number;
 }
 interface HitlConfig {
     planningQuestions?: boolean;
@@ -418,6 +426,7 @@ interface DeepResearchCreateResponse {
     public?: boolean;
     webhook_secret?: string;
     message?: string;
+    workflow?: WorkflowRunInfo;
     error?: string;
 }
 interface DeepResearchStatusResponse {
@@ -717,6 +726,153 @@ interface DatasourcesCategoriesResponse {
     categories?: DatasourceCategory[];
     error?: string;
 }
+type WorkflowMode = "fast" | "standard" | "heavy" | "max";
+type WorkflowVariableType = "text" | "textarea" | "number" | "date" | "enum";
+interface WorkflowVariableValidation {
+    min_length?: number;
+    max_length?: number;
+    pattern?: string;
+    enum?: string[];
+}
+interface WorkflowVariable {
+    key: string;
+    label?: string;
+    type?: WorkflowVariableType;
+    required?: boolean;
+    placeholder?: string;
+    help?: string;
+    examples?: string[];
+    validation?: WorkflowVariableValidation;
+}
+interface WorkflowDeliverable {
+    type: string;
+    description?: string;
+}
+interface WorkflowTools {
+    code_execution?: boolean;
+    screenshots?: boolean;
+    browser_use?: boolean;
+    charts?: boolean;
+}
+interface Workflow {
+    slug: string;
+    version?: number;
+    vertical?: string | null;
+    tags?: string[];
+    title?: string;
+    subtitle?: string | null;
+    description?: string | null;
+    popular?: boolean;
+    recommended_mode?: WorkflowMode;
+    estimated_time?: string | null;
+    is_valyu?: boolean;
+    owner_org_id?: string | null;
+    variables?: WorkflowVariable[];
+    deliverables?: WorkflowDeliverable[];
+    created_at?: string;
+    updated_at?: string;
+    prompt?: string;
+    strategy?: string;
+    report_format?: string;
+    tools?: WorkflowTools;
+    changelog?: string | null;
+}
+interface WorkflowVersionSummary {
+    version: number;
+    recommended_mode?: WorkflowMode;
+    estimated_time?: string | null;
+    changelog?: string | null;
+    created_at?: string;
+    is_current?: boolean;
+}
+interface WorkflowRunInfo {
+    slug?: string;
+    version?: number;
+}
+interface ResolvedWorkflowTemplate {
+    input?: string;
+    research_strategy?: string;
+    report_format?: string;
+    deliverables?: WorkflowDeliverable[];
+    mode?: WorkflowMode;
+    tools?: WorkflowTools;
+}
+/** Template body for creating a workflow or publishing a new version. */
+interface WorkflowVersionInput {
+    prompt: string;
+    strategy: string;
+    report_format: string;
+    variables?: WorkflowVariable[];
+    deliverables?: WorkflowDeliverable[];
+    tools?: WorkflowTools;
+    recommended_mode?: WorkflowMode;
+    estimated_time?: string;
+    changelog?: string;
+}
+interface WorkflowsListOptions {
+    vertical?: string;
+    scope?: "valyu" | "org" | "all";
+    q?: string;
+    tags?: string[];
+    limit?: number;
+    expand?: boolean;
+}
+interface WorkflowCreateOptions {
+    slug: string;
+    title: string;
+    version: WorkflowVersionInput;
+    subtitle?: string;
+    description?: string;
+    vertical?: string;
+    tags?: string[];
+    icon?: string;
+}
+interface WorkflowUpdateOptions {
+    title?: string;
+    subtitle?: string;
+    description?: string;
+    vertical?: string;
+    tags?: string[];
+    icon?: string;
+    version?: WorkflowVersionInput;
+    setCurrent?: boolean;
+}
+interface WorkflowPreviewOptions {
+    workflowParams?: Record<string, any>;
+    workflowVersion?: number;
+}
+interface WorkflowsListResponse {
+    success: boolean;
+    workflows?: Workflow[];
+    total?: number;
+    next_cursor?: string | null;
+    verticals?: string[];
+    error?: string;
+}
+interface WorkflowResponse {
+    success: boolean;
+    workflow?: Workflow;
+    error?: string;
+}
+interface WorkflowVersionsResponse {
+    success: boolean;
+    slug?: string;
+    versions?: WorkflowVersionSummary[];
+    error?: string;
+}
+interface WorkflowPreviewResponse {
+    success: boolean;
+    workflow?: WorkflowRunInfo;
+    resolved?: ResolvedWorkflowTemplate;
+    estimated_credits?: number | null;
+    error?: string;
+}
+interface WorkflowDeleteResponse {
+    success: boolean;
+    slug?: string;
+    deleted_at?: string;
+    error?: string;
+}
 
 /**
  * Verify webhook signature for Contents API async completion notifications.
@@ -767,6 +923,15 @@ declare class Valyu {
         list: (options?: DatasourcesListOptions) => Promise<DatasourcesListResponse>;
         categories: () => Promise<DatasourcesCategoriesResponse>;
     };
+    workflows: {
+        list: (options?: WorkflowsListOptions) => Promise<WorkflowsListResponse>;
+        get: (slug: string, version?: number) => Promise<WorkflowResponse>;
+        versions: (slug: string) => Promise<WorkflowVersionsResponse>;
+        preview: (slug: string, options?: WorkflowPreviewOptions) => Promise<WorkflowPreviewResponse>;
+        create: (options: WorkflowCreateOptions) => Promise<WorkflowResponse>;
+        update: (slug: string, options: WorkflowUpdateOptions) => Promise<WorkflowResponse>;
+        delete: (slug: string) => Promise<WorkflowDeleteResponse>;
+    };
     constructor(apiKey?: string, baseUrl?: string);
     /**
      * Validates date format (YYYY-MM-DD)
@@ -806,6 +971,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 +990,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 +1017,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 +1092,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
@@ -1025,6 +1196,48 @@ declare class Valyu {
      * @returns Promise resolving to list of categories with their metadata
      */
     private _datasourcesCategories;
+    /** Extract the most descriptive error message from a Workflows API error. */
+    private workflowError;
+    /**
+     * Workflows: List workflows available to your org
+     * @param options - Filters: vertical, scope ("valyu" | "org" | "all"), q, tags, limit, expand
+     */
+    private _workflowsList;
+    /**
+     * 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)
+     */
+    private _workflowsGet;
+    /**
+     * Workflows: List a workflow's version history
+     * @param slug - Workflow slug
+     */
+    private _workflowsVersions;
+    /**
+     * Workflows: Resolve a workflow's template with params without creating a task
+     * @param slug - Workflow slug
+     * @param options - workflowParams (variable values) and optional workflowVersion
+     */
+    private _workflowsPreview;
+    /**
+     * Workflows: Create a new workflow for your org
+     * @param options - slug, title, version (template body), and optional metadata
+     */
+    private _workflowsCreate;
+    /**
+     * 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
+     */
+    private _workflowsUpdate;
+    /**
+     * Workflows: Delete a workflow owned by your org (soft delete)
+     * @param slug - Workflow slug
+     */
+    private _workflowsDelete;
 }
 
-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 DeepResearchCostBreakdown, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchGetAssetsOptions, type DeepResearchGetAssetsResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchRespondResponse, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchTools, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type HitlConfig, type ImageMetadata, type ImageType, type Interaction, type InteractionHistoryEntry, type InteractionType, 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, type ToolConfig, Valyu, type WaitOptions, verifyContentsWebhookSignature };
+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 DeepResearchCostBreakdown, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchGetAssetsOptions, type DeepResearchGetAssetsResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchRespondResponse, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchTools, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type HitlConfig, type ImageMetadata, type ImageType, type Interaction, type InteractionHistoryEntry, type InteractionType, type ListBatchTasksOptions, type ListBatchTasksResponse, type ListBatchesOptions, type ListBatchesResponse, type ListOptions, type MCPServerConfig, type Progress, type ResolvedWorkflowTemplate, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, type ToolConfig, Valyu, type WaitOptions, type Workflow, type WorkflowCreateOptions, type WorkflowDeleteResponse, type WorkflowDeliverable, type WorkflowMode, type WorkflowPreviewOptions, type WorkflowPreviewResponse, type WorkflowResponse, type WorkflowRunInfo, type WorkflowTools, type WorkflowUpdateOptions, type WorkflowVariable, type WorkflowVariableType, type WorkflowVariableValidation, type WorkflowVersionInput, type WorkflowVersionSummary, type WorkflowVersionsResponse, type WorkflowsListOptions, type WorkflowsListResponse, verifyContentsWebhookSignature };

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;
 }
@@ -324,6 +329,9 @@ interface DeepResearchCreateOptions {
     brandCollectionId?: string;
     metadata?: Record<string, string | number | boolean>;
     hitl?: HitlConfig;
+    workflowId?: string;
+    workflowParams?: Record<string, any>;
+    workflowVersion?: number;
 }
 interface HitlConfig {
     planningQuestions?: boolean;
@@ -418,6 +426,7 @@ interface DeepResearchCreateResponse {
     public?: boolean;
     webhook_secret?: string;
     message?: string;
+    workflow?: WorkflowRunInfo;
     error?: string;
 }
 interface DeepResearchStatusResponse {
@@ -717,6 +726,153 @@ interface DatasourcesCategoriesResponse {
     categories?: DatasourceCategory[];
     error?: string;
 }
+type WorkflowMode = "fast" | "standard" | "heavy" | "max";
+type WorkflowVariableType = "text" | "textarea" | "number" | "date" | "enum";
+interface WorkflowVariableValidation {
+    min_length?: number;
+    max_length?: number;
+    pattern?: string;
+    enum?: string[];
+}
+interface WorkflowVariable {
+    key: string;
+    label?: string;
+    type?: WorkflowVariableType;
+    required?: boolean;
+    placeholder?: string;
+    help?: string;
+    examples?: string[];
+    validation?: WorkflowVariableValidation;
+}
+interface WorkflowDeliverable {
+    type: string;
+    description?: string;
+}
+interface WorkflowTools {
+    code_execution?: boolean;
+    screenshots?: boolean;
+    browser_use?: boolean;
+    charts?: boolean;
+}
+interface Workflow {
+    slug: string;
+    version?: number;
+    vertical?: string | null;
+    tags?: string[];
+    title?: string;
+    subtitle?: string | null;
+    description?: string | null;
+    popular?: boolean;
+    recommended_mode?: WorkflowMode;
+    estimated_time?: string | null;
+    is_valyu?: boolean;
+    owner_org_id?: string | null;
+    variables?: WorkflowVariable[];
+    deliverables?: WorkflowDeliverable[];
+    created_at?: string;
+    updated_at?: string;
+    prompt?: string;
+    strategy?: string;
+    report_format?: string;
+    tools?: WorkflowTools;
+    changelog?: string | null;
+}
+interface WorkflowVersionSummary {
+    version: number;
+    recommended_mode?: WorkflowMode;
+    estimated_time?: string | null;
+    changelog?: string | null;
+    created_at?: string;
+    is_current?: boolean;
+}
+interface WorkflowRunInfo {
+    slug?: string;
+    version?: number;
+}
+interface ResolvedWorkflowTemplate {
+    input?: string;
+    research_strategy?: string;
+    report_format?: string;
+    deliverables?: WorkflowDeliverable[];
+    mode?: WorkflowMode;
+    tools?: WorkflowTools;
+}
+/** Template body for creating a workflow or publishing a new version. */
+interface WorkflowVersionInput {
+    prompt: string;
+    strategy: string;
+    report_format: string;
+    variables?: WorkflowVariable[];
+    deliverables?: WorkflowDeliverable[];
+    tools?: WorkflowTools;
+    recommended_mode?: WorkflowMode;
+    estimated_time?: string;
+    changelog?: string;
+}
+interface WorkflowsListOptions {
+    vertical?: string;
+    scope?: "valyu" | "org" | "all";
+    q?: string;
+    tags?: string[];
+    limit?: number;
+    expand?: boolean;
+}
+interface WorkflowCreateOptions {
+    slug: string;
+    title: string;
+    version: WorkflowVersionInput;
+    subtitle?: string;
+    description?: string;
+    vertical?: string;
+    tags?: string[];
+    icon?: string;
+}
+interface WorkflowUpdateOptions {
+    title?: string;
+    subtitle?: string;
+    description?: string;
+    vertical?: string;
+    tags?: string[];
+    icon?: string;
+    version?: WorkflowVersionInput;
+    setCurrent?: boolean;
+}
+interface WorkflowPreviewOptions {
+    workflowParams?: Record<string, any>;
+    workflowVersion?: number;
+}
+interface WorkflowsListResponse {
+    success: boolean;
+    workflows?: Workflow[];
+    total?: number;
+    next_cursor?: string | null;
+    verticals?: string[];
+    error?: string;
+}
+interface WorkflowResponse {
+    success: boolean;
+    workflow?: Workflow;
+    error?: string;
+}
+interface WorkflowVersionsResponse {
+    success: boolean;
+    slug?: string;
+    versions?: WorkflowVersionSummary[];
+    error?: string;
+}
+interface WorkflowPreviewResponse {
+    success: boolean;
+    workflow?: WorkflowRunInfo;
+    resolved?: ResolvedWorkflowTemplate;
+    estimated_credits?: number | null;
+    error?: string;
+}
+interface WorkflowDeleteResponse {
+    success: boolean;
+    slug?: string;
+    deleted_at?: string;
+    error?: string;
+}
 
 /**
  * Verify webhook signature for Contents API async completion notifications.
@@ -767,6 +923,15 @@ declare class Valyu {
         list: (options?: DatasourcesListOptions) => Promise<DatasourcesListResponse>;
         categories: () => Promise<DatasourcesCategoriesResponse>;
     };
+    workflows: {
+        list: (options?: WorkflowsListOptions) => Promise<WorkflowsListResponse>;
+        get: (slug: string, version?: number) => Promise<WorkflowResponse>;
+        versions: (slug: string) => Promise<WorkflowVersionsResponse>;
+        preview: (slug: string, options?: WorkflowPreviewOptions) => Promise<WorkflowPreviewResponse>;
+        create: (options: WorkflowCreateOptions) => Promise<WorkflowResponse>;
+        update: (slug: string, options: WorkflowUpdateOptions) => Promise<WorkflowResponse>;
+        delete: (slug: string) => Promise<WorkflowDeleteResponse>;
+    };
     constructor(apiKey?: string, baseUrl?: string);
     /**
      * Validates date format (YYYY-MM-DD)
@@ -806,6 +971,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 +990,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 +1017,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 +1092,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
@@ -1025,6 +1196,48 @@ declare class Valyu {
      * @returns Promise resolving to list of categories with their metadata
      */
     private _datasourcesCategories;
+    /** Extract the most descriptive error message from a Workflows API error. */
+    private workflowError;
+    /**
+     * Workflows: List workflows available to your org
+     * @param options - Filters: vertical, scope ("valyu" | "org" | "all"), q, tags, limit, expand
+     */
+    private _workflowsList;
+    /**
+     * 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)
+     */
+    private _workflowsGet;
+    /**
+     * Workflows: List a workflow's version history
+     * @param slug - Workflow slug
+     */
+    private _workflowsVersions;
+    /**
+     * Workflows: Resolve a workflow's template with params without creating a task
+     * @param slug - Workflow slug
+     * @param options - workflowParams (variable values) and optional workflowVersion
+     */
+    private _workflowsPreview;
+    /**
+     * Workflows: Create a new workflow for your org
+     * @param options - slug, title, version (template body), and optional metadata
+     */
+    private _workflowsCreate;
+    /**
+     * 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
+     */
+    private _workflowsUpdate;
+    /**
+     * Workflows: Delete a workflow owned by your org (soft delete)
+     * @param slug - Workflow slug
+     */
+    private _workflowsDelete;
 }
 
-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 DeepResearchCostBreakdown, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchGetAssetsOptions, type DeepResearchGetAssetsResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchRespondResponse, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchTools, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type HitlConfig, type ImageMetadata, type ImageType, type Interaction, type InteractionHistoryEntry, type InteractionType, 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, type ToolConfig, Valyu, type WaitOptions, verifyContentsWebhookSignature };
+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 DeepResearchCostBreakdown, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchGetAssetsOptions, type DeepResearchGetAssetsResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchRespondResponse, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchTools, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type HitlConfig, type ImageMetadata, type ImageType, type Interaction, type InteractionHistoryEntry, type InteractionType, type ListBatchTasksOptions, type ListBatchTasksResponse, type ListBatchesOptions, type ListBatchesResponse, type ListOptions, type MCPServerConfig, type Progress, type ResolvedWorkflowTemplate, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, type ToolConfig, Valyu, type WaitOptions, type Workflow, type WorkflowCreateOptions, type WorkflowDeleteResponse, type WorkflowDeliverable, type WorkflowMode, type WorkflowPreviewOptions, type WorkflowPreviewResponse, type WorkflowResponse, type WorkflowRunInfo, type WorkflowTools, type WorkflowUpdateOptions, type WorkflowVariable, type WorkflowVariableType, type WorkflowVariableValidation, type WorkflowVersionInput, type WorkflowVersionSummary, type WorkflowVersionsResponse, type WorkflowsListOptions, type WorkflowsListResponse, verifyContentsWebhookSignature };