type SearchType = "web" | "proprietary" | "all" | "news"; type FeedbackSentiment = "very good" | "good" | "bad" | "very bad"; type DataType = "structured" | "unstructured"; type CountryCode = "ALL" | "AR" | "AU" | "AT" | "BE" | "BR" | "CA" | "CL" | "DK" | "FI" | "FR" | "DE" | "HK" | "IN" | "ID" | "IT" | "JP" | "KR" | "MY" | "MX" | "NL" | "NZ" | "NO" | "CN" | "PL" | "PT" | "PH" | "RU" | "SA" | "ZA" | "ES" | "SE" | "CH" | "TW" | "TR" | "GB" | "US"; type ResponseLength = "short" | "medium" | "large" | "max" | number; interface SearchResult { title: string; url: string; content: string | object | any[]; description?: string; source: string; source_type?: string; data_type?: DataType; date?: string; length: number; price: number; relevance_score?: number; publication_date?: string; id?: string; image_url?: Record; abstract?: string; doi?: string; citation?: string; citation_count?: number; authors?: string[]; references?: string; metadata?: Record; } interface SearchOptions { searchType?: SearchType; maxNumResults?: number; maxPrice?: number; isToolCall?: boolean; relevanceThreshold?: number; includedSources?: string[]; excludeSources?: string[]; sourceBiases?: Record; category?: string; startDate?: string; endDate?: string; historicalCache?: boolean; countryCode?: CountryCode; responseLength?: ResponseLength; fastMode?: boolean; urlOnly?: boolean; instructions?: string; } interface SearchResponse { success: boolean; error?: string; tx_id: string | null; query: string; results: SearchResult[]; results_by_source: { web: number; proprietary: number; }; total_deduction_dollars: number; total_characters: number; } interface FeedbackResponse { success: boolean; error?: string; } type ExtractEffort = "normal" | "high" | "auto"; type ContentResponseLength = "short" | "medium" | "large" | "max" | number; interface ContentsOptions { summary?: boolean | string | object; extractEffort?: ExtractEffort; responseLength?: ContentResponseLength; maxPriceDollars?: number; screenshot?: boolean; async?: boolean; webhookUrl?: string; startDate?: string; endDate?: string; historicalCache?: boolean; } interface ContentResultBase { url: string; status: "success" | "failed"; } interface ContentResultSuccess extends ContentResultBase { status: "success"; title: string; content: string | number; length: number; source: string; price?: number; description?: string; summary?: string | object; summary_success?: boolean; data_type?: string; image_url?: Record; 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; pollUrl?: string; webhookSecret?: string; txId: string; } interface ContentsResponse { success: boolean; error?: string | null; tx_id?: string; urls_requested?: number; urls_processed?: number; urls_failed?: number; results?: ContentResult[]; total_cost_dollars?: number; total_characters?: number; isProvisioning?: boolean; } interface AnswerOptions { structuredOutput?: Record; systemInstructions?: string; searchType?: SearchType; dataMaxPrice?: number; countryCode?: CountryCode; includedSources?: string[]; excludedSources?: string[]; startDate?: string; endDate?: string; fastMode?: boolean; streaming?: boolean; } interface SearchMetadata { tx_ids: string[]; number_of_results: number; total_characters: number; } interface AIUsage { input_tokens: number; output_tokens: number; } interface Cost { total_deduction_dollars: number; search_deduction_dollars: number; contents_deduction_dollars?: number; ai_deduction_dollars: number; } interface ExtractionMetadata { urls_requested: number; urls_processed: number; urls_failed: number; total_characters: number; response_length: string; extract_effort: string; } interface AnswerSearchResult { title: string; url: string; content: string | object | any[]; description?: string; source: string; source_type?: string; data_type?: DataType; date?: string; length: number; relevance_score?: number; image_url?: Record; abstract?: string; } interface AnswerSuccessResponse { success: true; tx_id: string; original_query: string; contents: string | Record; search_results: AnswerSearchResult[]; search_metadata: SearchMetadata; ai_usage: AIUsage; cost: Cost; extraction_metadata?: ExtractionMetadata; } interface AnswerErrorResponse { success: false; error: string; } type AnswerResponse = AnswerSuccessResponse | AnswerErrorResponse; type AnswerStreamChunkType = "search_results" | "content" | "metadata" | "done" | "error"; interface AnswerStreamChunk { type: AnswerStreamChunkType; search_results?: AnswerSearchResult[]; content?: string; finish_reason?: string; tx_id?: string; original_query?: string; contents?: string | Record; search_metadata?: SearchMetadata; ai_usage?: AIUsage; cost?: Cost; extraction_metadata?: ExtractionMetadata; error?: string; } interface AlertEmailConfig { email: string; custom_url?: string; } type DeepResearchMode = "fast" | "standard" | "lite" | "heavy" | "max"; type DeepResearchStatus = "queued" | "running" | "awaiting_input" | "paused" | "completed" | "failed" | "cancelled"; type DeepResearchOutputFormat = "markdown" | "pdf" | "toon" | Record; type DeepResearchOutputType = "markdown" | "json" | "toon"; type ImageType = "chart" | "ai_generated" | "screenshot"; type ChartType = "line" | "bar" | "area" | "pie" | "doughnut" | "radar" | "scatter" | "horizontalBar" | "heatmap" | "boxplot" | "stackedBar" | "stackedArea" | "histogram" | "waterfall" | "timeline" | "bubble"; interface FileAttachment { data: string; filename: string; mediaType: string; context?: string; } interface MCPServerConfig { url: string; name?: string; toolPrefix?: string; auth?: { type: "bearer" | "header" | "none"; token?: string; headers?: Record; }; allowedTools?: string[]; } type DeliverableType = "csv" | "xlsx" | "pptx" | "docx" | "pdf"; type DeliverableStatus = "completed" | "failed"; interface Deliverable { type: DeliverableType; description: string; columns?: string[]; includeHeaders?: boolean; sheetName?: string; slides?: number; template?: string; } interface DeliverableResult { id: string; request: string; type: DeliverableType | "unknown"; status: DeliverableStatus; title: string; description?: string; url: string; s3_key: string; row_count?: number; column_count?: number; error?: string; created_at: number; } interface DeepResearchSearchConfig { searchType?: "all" | "web" | "proprietary"; includedSources?: string[]; excludedSources?: string[]; sourceBiases?: Record; startDate?: string; endDate?: string; historicalCache?: boolean; category?: string; countryCode?: CountryCode; } /** * Per-tool configuration with optional call limit. * * max_calls can only be lowered, not raised above the system default. * Setting max_calls to 0 effectively disables the tool. */ interface ToolConfig { enabled?: boolean; max_calls?: number; } interface DeepResearchTools { code_execution?: boolean | ToolConfig; screenshots?: boolean | ToolConfig; browser_use?: boolean | ToolConfig; /** Enable chart/graph generation embedded in the final report (free, unlimited) */ charts?: boolean | ToolConfig; } interface DeepResearchCreateOptions { query?: string; input?: string; mode?: DeepResearchMode; model?: DeepResearchMode; outputFormats?: DeepResearchOutputFormat[]; strategy?: string; researchStrategy?: string; reportFormat?: string; search?: DeepResearchSearchConfig; urls?: string[]; files?: FileAttachment[]; deliverables?: (string | Deliverable)[]; mcpServers?: MCPServerConfig[]; /** @deprecated Use tools.code_execution instead */ codeExecution?: boolean; tools?: DeepResearchTools; previousReports?: string[]; webhookUrl?: string; alertEmail?: string | AlertEmailConfig; brandCollectionId?: string; metadata?: Record; hitl?: HitlConfig; workflowId?: string; workflowParams?: Record; workflowVersion?: number; } interface HitlConfig { planningQuestions?: boolean; planReview?: boolean; sourceReview?: boolean; outlineReview?: boolean; } type InteractionType = "planning_questions" | "plan_review" | "source_review" | "outline_review"; interface Interaction { interaction_id: string; type: InteractionType; data: Record; created_at: number; timeout_ms: number; expected_response?: Record; } interface InteractionHistoryEntry { interaction_id: string; type: InteractionType; created_at: number; responded_at?: number; auto_continued: boolean; response?: Record; } interface Progress { current_step: number; total_steps: number; } interface ChartDataPoint { x: string | number; y: number; y2?: number; z?: number; values?: number[]; } interface ChartDataSeries { name: string; data: ChartDataPoint[]; line_style?: "solid" | "dashed" | "dotted"; } interface ImageMetadata { image_id: string; image_type: ImageType; title: string; description?: string; image_url: string; created_at: number; chart_type?: ChartType; x_axis_label?: string; y_axis_label?: string; data_series?: ChartDataSeries[]; source_url?: string; captured_at?: number; } interface DeepResearchSource { title: string; url: string; snippet?: string; description?: string; source?: string; org_id?: string; price?: number; id?: string; doc_id?: number; doi?: string; category?: string; source_id?: number; word_count?: number; fragment?: string; } interface DeepResearchUsage { search_cost: number; contents_cost: number; ai_cost: number; compute_cost: number; total_cost: number; } interface DeepResearchCostBreakdown { task: number; screenshots?: number; code_execution?: number; deliverables?: number; } interface DeepResearchCreateResponse { success: boolean; deepresearch_id?: string; status?: DeepResearchStatus; mode?: DeepResearchMode; model?: DeepResearchMode; created_at?: string; metadata?: Record; public?: boolean; webhook_secret?: string; message?: string; workflow?: WorkflowRunInfo; error?: string; } interface DeepResearchStatusResponse { success: boolean; deepresearch_id?: string; status?: DeepResearchStatus; query?: string; mode?: DeepResearchMode; output_formats?: DeepResearchOutputFormat[]; created_at?: string; public?: boolean; progress?: Progress; messages?: any[]; completed_at?: string; output?: string | Record; output_type?: DeepResearchOutputType; title?: string; total_word_count?: number; pdf_url?: string; images?: ImageMetadata[]; deliverables?: DeliverableResult[]; sources?: DeepResearchSource[]; cost?: number; usage?: DeepResearchUsage; cost_breakdown?: DeepResearchCostBreakdown; tools?: DeepResearchTools; batch_id?: string; batch_task_id?: string; hitl_config?: Record; interaction?: Interaction; hitl_history?: InteractionHistoryEntry[]; error?: string; unreachable?: boolean; } interface DeepResearchTaskListItem { deepresearch_id: string; query: string; input?: string; title?: string; status: DeepResearchStatus; created_at: number; public?: boolean; } interface DeepResearchListResponse { success: boolean; data?: DeepResearchTaskListItem[]; error?: string; } interface DeepResearchUpdateResponse { success: boolean; message?: string; deepresearch_id?: string; error?: string; } interface DeepResearchCancelResponse { success: boolean; message?: string; deepresearch_id?: string; error?: string; } interface DeepResearchDeleteResponse { success: boolean; message?: string; deepresearch_id?: string; error?: string; } interface DeepResearchTogglePublicResponse { success: boolean; message?: string; deepresearch_id?: string; public?: boolean; error?: string; } interface DeepResearchGetAssetsOptions { token?: string; } interface DeepResearchGetAssetsResponse { success: boolean; data?: Buffer; contentType?: string; error?: string; } interface DeepResearchRespondResponse { success: boolean; status?: string; deepresearch_id?: string; error?: string; } interface WaitOptions { pollInterval?: number; maxWaitTime?: number; onProgress?: (status: DeepResearchStatusResponse) => void; onInteraction?: (interaction: Interaction) => Promise | null | undefined> | Record | null | undefined; } interface StreamCallback { onMessage?: (message: any) => void; onProgress?: (current: number, total: number) => void; onComplete?: (result: DeepResearchStatusResponse) => void; onError?: (error: Error) => void; } interface ListOptions { limit?: number; } type BatchStatus = "open" | "processing" | "completed" | "completed_with_errors" | "cancelled"; interface BatchCounts { total: number; queued: number; running: number; completed: number; failed: number; cancelled: number; } interface DeepResearchBatch { batch_id: string; organisation_id: string; api_key_id: string; credit_id: string; status: BatchStatus; mode: DeepResearchMode; name?: string; output_formats?: DeepResearchOutputFormat[]; search_params?: { search_type?: "all" | "web" | "proprietary"; included_sources?: string[]; excluded_sources?: string[]; start_date?: string; end_date?: string; category?: string; country_code?: CountryCode; }; created_at: string; completed_at?: string; counts: BatchCounts; cost: number; webhook_secret?: string; metadata?: Record; } interface CreateBatchOptions { name?: string; mode?: DeepResearchMode; model?: DeepResearchMode; outputFormats?: DeepResearchOutputFormat[]; search?: DeepResearchSearchConfig; webhookUrl?: string; metadata?: Record; } interface BatchTaskInput { id?: string; query?: string; input?: string; strategy?: string; researchStrategy?: string; reportFormat?: string; urls?: string[]; metadata?: Record; } interface AddBatchTasksOptions { tasks: BatchTaskInput[]; } interface CreateBatchResponse { success: boolean; batch_id?: string; status?: BatchStatus; mode?: DeepResearchMode; name?: string; output_formats?: DeepResearchOutputFormat[]; search_params?: { search_type?: "all" | "web" | "proprietary"; included_sources?: string[]; excluded_sources?: string[]; start_date?: string; end_date?: string; category?: string; country_code?: CountryCode; }; created_at?: string; completed_at?: string; counts?: BatchCounts; cost?: number; webhook_secret?: string; error?: string; } interface BatchStatusResponse { success: boolean; batch?: DeepResearchBatch; error?: string; } interface BatchTaskCreated { task_id?: string; deepresearch_id: string; status: string; } interface AddBatchTasksResponse { success: boolean; batch_id?: string; added?: number; tasks?: BatchTaskCreated[]; counts?: BatchCounts; error?: string; } interface BatchTaskListItem { deepresearch_id: string; task_id?: string; query: string; status: DeepResearchStatus; created_at: string; completed_at?: string; output_type?: string; output?: string | Record; sources?: any[]; images?: any[]; pdf_url?: string; deliverables?: any; error?: string; cost?: number; } interface BatchPagination { count: number; last_key?: string; has_more: boolean; } interface ListBatchTasksOptions { status?: DeepResearchStatus; limit?: number; lastKey?: string; includeOutput?: boolean; } interface ListBatchTasksResponse { success: boolean; batch_id?: string; tasks?: BatchTaskListItem[]; pagination?: BatchPagination; error?: string; } interface CancelBatchResponse { success: boolean; batch_id?: string; status?: BatchStatus; cancelled_count?: number; message?: string; error?: string; } interface ListBatchesOptions { limit?: number; } interface ListBatchesResponse { success: boolean; batches?: DeepResearchBatch[]; error?: string; } interface BatchWaitOptions { pollInterval?: number; maxWaitTime?: number; onProgress?: (batch: DeepResearchBatch) => void; } type DatasourceCategoryId = "research" | "healthcare" | "patents" | "markets" | "company" | "economic" | "predictions" | "transportation" | "legal" | "politics"; type DatasourceModality = "text" | "images" | "tabular"; interface DatasourcePricing { cpm: number; } interface DatasourceCoverage { start_date?: string | null; end_date?: string | null; } interface Datasource { id: string; name: string; description: string; category: DatasourceCategoryId; type: string; modality: DatasourceModality[]; topics: string[]; languages?: string[]; source?: string; example_queries: string[]; pricing: DatasourcePricing; response_schema?: Record; update_frequency?: string; size?: number; coverage?: DatasourceCoverage; } interface DatasourceCategory { id: string; name: string; description: string; dataset_count: number; } interface DatasourcesListOptions { category?: DatasourceCategoryId; } interface DatasourcesListResponse { success: boolean; datasources?: Datasource[]; error?: string; } interface DatasourcesCategoriesResponse { success: boolean; 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; 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. * 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; private client; deepresearch: { create: (options: DeepResearchCreateOptions) => Promise; status: (taskId: string) => Promise; wait: (taskId: string, options?: WaitOptions) => Promise; stream: (taskId: string, callback: StreamCallback) => Promise; list: (options: ListOptions) => Promise; update: (taskId: string, instruction: string) => Promise; cancel: (taskId: string) => Promise; delete: (taskId: string) => Promise; togglePublic: (taskId: string, isPublic: boolean) => Promise; getAssets: (taskId: string, assetId: string, options?: DeepResearchGetAssetsOptions) => Promise; respond: (taskId: string, interactionId: string, response: Record) => Promise; respondPlanningQuestions: (taskId: string, interactionId: string, answers: { question: string; answer: string; }[]) => Promise; approvePlan: (taskId: string, interactionId: string, modifications?: string) => Promise; respondSourceReview: (taskId: string, interactionId: string, options?: { includedDomains?: string[]; excludedDomains?: string[]; }) => Promise; approveOutline: (taskId: string, interactionId: string, modifications?: string) => Promise; }; batch: { create: (options?: CreateBatchOptions) => Promise; status: (batchId: string) => Promise; addTasks: (batchId: string, options: AddBatchTasksOptions) => Promise; listTasks: (batchId: string, options?: ListBatchTasksOptions) => Promise; cancel: (batchId: string) => Promise; list: (options?: ListBatchesOptions) => Promise; waitForCompletion: (batchId: string, options?: BatchWaitOptions) => Promise; }; datasources: { list: (options?: DatasourcesListOptions) => Promise; categories: () => Promise; }; workflows: { list: (options?: WorkflowsListOptions) => Promise; get: (slug: string, version?: number) => Promise; versions: (slug: string) => Promise; preview: (slug: string, options?: WorkflowPreviewOptions) => Promise; create: (options: WorkflowCreateOptions) => Promise; update: (slug: string, options: WorkflowUpdateOptions) => Promise; delete: (slug: string) => Promise; }; constructor(apiKey?: string, baseUrl?: string); /** * Validates date format (YYYY-MM-DD) */ private validateDateFormat; /** * Validates if a string is a valid URL */ private validateUrl; /** * Validates if a string is a valid domain (with optional path) */ private validateDomain; /** * Validates if a string is a valid dataset identifier (provider/datasetname) */ private validateDatasetId; /** * Validates source strings (domains, URLs, or dataset IDs) */ private validateSource; /** * Validates an array of source strings */ private validateSources; /** * Search for information using the Valyu DeepSearch API * @param query - The search query string * @param options - Search configuration options * @param options.searchType - Type of search: "web", "proprietary", "all", or "news" * @param options.maxNumResults - Maximum number of results (1-100) * @param options.maxPrice - Maximum price per thousand characters (CPM) * @param options.isToolCall - Whether this is a tool call * @param options.relevanceThreshold - Minimum relevance score (0-1) * @param options.includedSources - List of specific sources to include * @param options.excludeSources - List of URLs/domains to exclude from search results * @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) * @param options.urlOnly - Returns shortened snippets (default: false) * @returns Promise resolving to search results */ search(query: string, options?: SearchOptions): Promise; /** * Extract content from URLs with optional AI processing * @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) * @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; /** * 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; /** * 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 */ waitForJob(jobId: string, options?: ContentsJobWaitOptions): Promise; /** * DeepResearch: Create a new research task * @param options.search - Search configuration options * @param options.search.searchType - Type of search: "all", "web", or "proprietary" (default: "all") * @param options.search.includedSources - Array of source types to include (e.g., ["academic", "finance", "web"]) * @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; /** * DeepResearch: Get task status */ private _deepresearchStatus; /** * DeepResearch: Wait for task completion with polling */ private _deepresearchWait; /** * DeepResearch: Stream real-time updates */ private _deepresearchStream; /** * DeepResearch: List all tasks */ private _deepresearchList; /** * DeepResearch: Add follow-up instruction */ private _deepresearchUpdate; /** * DeepResearch: Respond to a HITL checkpoint * @param taskId - The task ID to respond to * @param interactionId - The interaction_id from the task's interaction field * @param response - Response data matching the checkpoint type */ private _deepresearchRespond; /** * DeepResearch: Respond to a planning_questions checkpoint */ private _deepresearchRespondPlanningQuestions; /** * DeepResearch: Approve or request modifications to a plan_review checkpoint */ private _deepresearchApprovePlan; /** * DeepResearch: Respond to a source_review checkpoint */ private _deepresearchRespondSourceReview; /** * DeepResearch: Approve or request modifications to an outline_review checkpoint */ private _deepresearchApproveOutline; /** * DeepResearch: Cancel task */ private _deepresearchCancel; /** * DeepResearch: Delete task */ private _deepresearchDelete; /** * DeepResearch: Toggle public flag */ private _deepresearchTogglePublic; /** * DeepResearch: Get task assets (images, deliverables, PDFs) */ private _deepresearchGetAssets; /** * Batch: Create a new batch * @param options - Batch configuration options * @param options.name - Optional name for the batch * @param options.model - DeepResearch mode: "fast", "standard", or "heavy" (default: "standard") * @param options.outputFormats - Output formats for tasks (default: ["markdown"]) * @param options.search - Search configuration for all tasks in batch * @param options.search.searchType - Type of search: "all", "web", or "proprietary" (default: "all") * @param options.search.includedSources - Array of source types to include (e.g., ["academic", "finance", "web"]) * @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 * @returns Promise resolving to batch creation response with batch_id and webhook_secret */ private _batchCreate; /** * Batch: Get batch status * @param batchId - The batch ID to query * @returns Promise resolving to batch status with counts and usage */ private _batchStatus; /** * Batch: Add tasks to a batch * @param batchId - The batch ID to add tasks to * @param options - Task configuration options * @param options.tasks - Array of task inputs (use 'query' field for each task) * @returns Promise resolving to response with added, tasks array, counts, and batch_id */ private _batchAddTasks; /** * Batch: List all tasks in a batch * @param batchId - The batch ID to query * @param options - Optional pagination and filtering options * @param options.status - Filter by status: "queued", "running", "completed", "failed", or "cancelled" * @param options.limit - Maximum number of tasks to return * @param options.lastKey - Pagination token from previous response * @returns Promise resolving to list of tasks with their status and pagination info */ private _batchListTasks; /** * Batch: Cancel a batch and all its pending tasks * @param batchId - The batch ID to cancel * @returns Promise resolving to cancellation confirmation */ private _batchCancel; /** * Batch: List all batches * @param options - Optional options * @param options.limit - Maximum number of batches to return * @returns Promise resolving to list of all batches */ private _batchList; /** * Batch: Wait for batch completion with polling * @param batchId - The batch ID to wait for * @param options - Wait configuration options * @param options.pollInterval - Polling interval in milliseconds (default: 10000) * @param options.maxWaitTime - Maximum wait time in milliseconds (default: 7200000) * @param options.onProgress - Callback for progress updates * @returns Promise resolving to final batch status */ private _batchWaitForCompletion; /** * Get AI-powered answers using the Valyu Answer API * @param query - The question or query string * @param options - Answer configuration options * @param options.structuredOutput - JSON Schema object for structured responses * @param options.systemInstructions - Custom system-level instructions (max 2000 chars) * @param options.searchType - Type of search: "web", "proprietary", "all", or "news" * @param options.dataMaxPrice - Maximum spend (USD) for data retrieval * @param options.countryCode - Country code filter for search results * @param options.includedSources - List of specific sources to include * @param options.excludedSources - List of URLs/domains to exclude from search results * @param options.startDate - Start date filter (YYYY-MM-DD format) * @param options.endDate - End date filter (YYYY-MM-DD format) * @param options.fastMode - Fast mode for quicker but shorter results (default: false) * @param options.streaming - Enable streaming mode (default: false) * @returns Promise resolving to answer response, or AsyncGenerator for streaming */ answer(query: string, options?: AnswerOptions): Promise>; /** * Validate answer parameters */ private validateAnswerParams; /** * Build payload for answer API */ private buildAnswerPayload; /** * Fetch answer (non-streaming mode) */ private fetchAnswer; /** * Stream answer using SSE */ private streamAnswer; /** * Create an error generator for streaming errors */ private createErrorGenerator; /** * Datasources: List all available datasources * @param options - Optional filter options * @param options.category - Filter by category (e.g., "research", "markets", "healthcare") * @returns Promise resolving to list of datasources with their metadata */ private _datasourcesList; /** * Datasources: Get all available categories * @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 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 };