valyu-js 2.3.2 → 2.3.3

package/README.md

@@ -58,7 +58,7 @@ The `deepresearch` namespace provides access to Valyu's AI-powered research agen
 // Create a research task
 const task = await valyu.deepresearch.create({
     input: "What are the latest developments in quantum computing?",
-    model: "lite",                      // "lite" (fast, Haiku) or "heavy" (thorough, Sonnet)
+    model: "fast",                      // "fast" (Haiku) or "heavy" (thorough, Sonnet)
     outputFormats: ["markdown", "pdf"]  // Output formats
 });
 
@@ -94,7 +94,7 @@ console.log(result.pdf_url); // PDF download URL
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `input` | `string` | *required* | Research query or task description |
-| `model` | `"lite" \| "heavy"` | `"lite"` | Research model - lite (fast) or heavy (thorough) |
+| `model` | `"fast" \| "heavy"` | `"fast"` | Research model - fast or heavy (thorough) |
 | `outputFormats` | `("markdown" \| "pdf")[]` | `["markdown"]` | Output formats for the report |
 | `strategy` | `string` | - | Natural language research strategy |
 | `search` | `object` | - | Search configuration (type, sources) |
@@ -112,7 +112,7 @@ console.log(result.pdf_url); // PDF download URL
 ```javascript
 const task = await valyu.deepresearch.create({
     input: "Summarize recent AI safety research",
-    model: "lite"
+    model: "fast"
 });
 
 const result = await valyu.deepresearch.wait(task.deepresearch_id);
@@ -160,6 +160,86 @@ const task = await valyu.deepresearch.create({
 });
 ```
 
+### Batch API
+
+The `batch` namespace allows you to process multiple DeepResearch tasks efficiently. Perfect for running large-scale research operations.
+
+```javascript
+// Create a batch
+const batch = await valyu.batch.create({
+  name: "Q4 Research Batch",
+  model: "fast",                      // "fast", "standard", or "heavy"
+  outputFormats: ["markdown"]
+});
+
+// Add tasks to the batch
+await valyu.batch.addTasks(batch.batch_id, {
+  tasks: [
+    { input: "What are the latest AI developments?" },
+    { input: "Analyze climate change trends" },
+    { input: "Review quantum computing progress" }
+  ]
+});
+
+// Wait for completion
+const result = await valyu.batch.waitForCompletion(batch.batch_id, {
+  pollInterval: 10000,  // Check every 10 seconds
+  onProgress: (batch) => {
+    console.log(`Progress: ${batch.counts.completed}/${batch.counts.total}`);
+  }
+});
+
+console.log('Total cost:', result.usage.total_cost);
+```
+
+#### Batch Methods
+
+| Method | Description |
+|--------|-------------|
+| `create(options?)` | Create a new batch |
+| `status(batchId)` | Get batch status and task counts |
+| `addTasks(batchId, options)` | Add tasks to a batch |
+| `listTasks(batchId)` | List all tasks in a batch |
+| `list()` | List all batches |
+| `cancel(batchId)` | Cancel a batch and all pending tasks |
+| `waitForCompletion(batchId, options?)` | Wait for batch completion with polling |
+
+#### Batch Create Options
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `string` | - | Optional batch name |
+| `model` | `"fast" \| "standard" \| "heavy"` | `"standard"` | DeepResearch model for all tasks |
+| `outputFormats` | `("markdown" \| "pdf")[]` | `["markdown"]` | Output formats |
+| `search` | `object` | - | Search configuration for all tasks |
+| `webhookUrl` | `string` | - | HTTPS URL for completion webhook |
+| `metadata` | `object` | - | Custom metadata key-value pairs |
+
+#### Batch Status Response
+
+```javascript
+{
+  success: true,
+  batch: {
+    batch_id: "batch_xxx",
+    status: "processing",  // "open", "processing", "completed", "cancelled"
+    counts: {
+      total: 10,
+      queued: 3,
+      running: 2,
+      completed: 4,
+      failed: 1,
+      cancelled: 0
+    },
+    usage: {
+      search_cost: 0.05,
+      ai_cost: 0.15,
+      total_cost: 0.20
+    }
+  }
+}
+```
+
 ### Search Method
 
 The `search()` method is the core of the Valyu SDK. It accepts a query string as the first parameter, followed by optional configuration parameters.

package/dist/index.d.mts

@@ -352,6 +352,114 @@ interface ListOptions {
     apiKeyId: string;
     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 BatchUsage {
+    search_cost: number;
+    contents_cost: number;
+    ai_cost: number;
+    total_cost: number;
+}
+interface DeepResearchBatch {
+    batch_id: string;
+    organisation_id: string;
+    api_key_id: string;
+    credit_id: string;
+    name?: string;
+    status: BatchStatus;
+    model: DeepResearchMode;
+    output_formats?: DeepResearchOutputFormat[];
+    search_params?: {
+        search_type?: "all" | "web" | "proprietary";
+        included_sources?: string[];
+    };
+    counts: BatchCounts;
+    usage: BatchUsage;
+    webhook_url?: string;
+    webhook_secret?: string;
+    created_at: number;
+    updated_at: number;
+    completed_at?: number;
+    metadata?: Record<string, string | number | boolean>;
+}
+interface CreateBatchOptions {
+    name?: string;
+    model?: DeepResearchMode;
+    outputFormats?: DeepResearchOutputFormat[];
+    search?: {
+        searchType?: "all" | "web" | "proprietary";
+        includedSources?: string[];
+    };
+    webhookUrl?: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+interface BatchTaskInput {
+    id?: string;
+    input: string;
+    strategy?: string;
+    urls?: string[];
+    metadata?: Record<string, string | number | boolean>;
+}
+interface AddBatchTasksOptions {
+    tasks: BatchTaskInput[];
+}
+interface CreateBatchResponse {
+    success: boolean;
+    batch_id?: string;
+    status?: BatchStatus;
+    webhook_secret?: string;
+    error?: string;
+}
+interface BatchStatusResponse {
+    success: boolean;
+    batch?: DeepResearchBatch;
+    error?: string;
+}
+interface AddBatchTasksResponse {
+    success: boolean;
+    added_count?: number;
+    task_ids?: string[];
+    error?: string;
+}
+interface BatchTaskListItem {
+    deepresearch_id: string;
+    batch_id: string;
+    batch_task_id?: string;
+    query: string;
+    status: DeepResearchStatus;
+    created_at: number;
+    completed_at?: number;
+    error?: string;
+}
+interface ListBatchTasksResponse {
+    success: boolean;
+    tasks?: BatchTaskListItem[];
+    total_count?: number;
+    error?: string;
+}
+interface CancelBatchResponse {
+    success: boolean;
+    message?: string;
+    batch_id?: string;
+    error?: string;
+}
+interface ListBatchesResponse {
+    success: boolean;
+    batches?: DeepResearchBatch[];
+    error?: string;
+}
+interface BatchWaitOptions {
+    pollInterval?: number;
+    maxWaitTime?: number;
+    onProgress?: (batch: DeepResearchBatch) => void;
+}
 
 declare class Valyu {
     private baseUrl;
@@ -367,6 +475,15 @@ declare class Valyu {
         delete: (taskId: string) => Promise<DeepResearchDeleteResponse>;
         togglePublic: (taskId: string, isPublic: boolean) => Promise<DeepResearchTogglePublicResponse>;
     };
+    batch: {
+        create: (options?: CreateBatchOptions) => Promise<CreateBatchResponse>;
+        status: (batchId: string) => Promise<BatchStatusResponse>;
+        addTasks: (batchId: string, options: AddBatchTasksOptions) => Promise<AddBatchTasksResponse>;
+        listTasks: (batchId: string) => Promise<ListBatchTasksResponse>;
+        cancel: (batchId: string) => Promise<CancelBatchResponse>;
+        list: () => Promise<ListBatchesResponse>;
+        waitForCompletion: (batchId: string, options?: BatchWaitOptions) => Promise<DeepResearchBatch>;
+    };
     constructor(apiKey?: string, baseUrl?: string);
     /**
      * Validates date format (YYYY-MM-DD)
@@ -460,6 +577,59 @@ declare class Valyu {
      * DeepResearch: Toggle public flag
      */
     private _deepresearchTogglePublic;
+    /**
+     * 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.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
+     * @returns Promise resolving to response with added_count and task_ids
+     */
+    private _batchAddTasks;
+    /**
+     * Batch: List all tasks in a batch
+     * @param batchId - The batch ID to query
+     * @returns Promise resolving to list of tasks with their status
+     */
+    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
+     * @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
@@ -500,4 +670,4 @@ declare class Valyu {
     private createErrorGenerator;
 }
 
-export { type AIUsage, type AnswerErrorResponse, type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamChunkType, type AnswerSuccessResponse, type ChartDataPoint, type ChartDataSeries, type ChartType, type ContentResponseLength, type ContentResult, type ContentsOptions, type ContentsResponse, type Cost, type CountryCode, type DeepResearchCancelResponse, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type ImageMetadata, type ImageType, type ListOptions, type MCPServerConfig, type Progress, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, Valyu, type WaitOptions };
+export { type AIUsage, type AddBatchTasksOptions, type AddBatchTasksResponse, type AnswerErrorResponse, type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamChunkType, type AnswerSuccessResponse, type BatchCounts, type BatchStatus, type BatchStatusResponse, type BatchTaskInput, type BatchTaskListItem, type BatchUsage, type BatchWaitOptions, type CancelBatchResponse, type ChartDataPoint, type ChartDataSeries, type ChartType, type ContentResponseLength, type ContentResult, type ContentsOptions, type ContentsResponse, type Cost, type CountryCode, type CreateBatchOptions, type CreateBatchResponse, type DeepResearchBatch, type DeepResearchCancelResponse, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type ImageMetadata, type ImageType, type ListBatchTasksResponse, type ListBatchesResponse, type ListOptions, type MCPServerConfig, type Progress, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, Valyu, type WaitOptions };

package/dist/index.d.ts

@@ -352,6 +352,114 @@ interface ListOptions {
     apiKeyId: string;
     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 BatchUsage {
+    search_cost: number;
+    contents_cost: number;
+    ai_cost: number;
+    total_cost: number;
+}
+interface DeepResearchBatch {
+    batch_id: string;
+    organisation_id: string;
+    api_key_id: string;
+    credit_id: string;
+    name?: string;
+    status: BatchStatus;
+    model: DeepResearchMode;
+    output_formats?: DeepResearchOutputFormat[];
+    search_params?: {
+        search_type?: "all" | "web" | "proprietary";
+        included_sources?: string[];
+    };
+    counts: BatchCounts;
+    usage: BatchUsage;
+    webhook_url?: string;
+    webhook_secret?: string;
+    created_at: number;
+    updated_at: number;
+    completed_at?: number;
+    metadata?: Record<string, string | number | boolean>;
+}
+interface CreateBatchOptions {
+    name?: string;
+    model?: DeepResearchMode;
+    outputFormats?: DeepResearchOutputFormat[];
+    search?: {
+        searchType?: "all" | "web" | "proprietary";
+        includedSources?: string[];
+    };
+    webhookUrl?: string;
+    metadata?: Record<string, string | number | boolean>;
+}
+interface BatchTaskInput {
+    id?: string;
+    input: string;
+    strategy?: string;
+    urls?: string[];
+    metadata?: Record<string, string | number | boolean>;
+}
+interface AddBatchTasksOptions {
+    tasks: BatchTaskInput[];
+}
+interface CreateBatchResponse {
+    success: boolean;
+    batch_id?: string;
+    status?: BatchStatus;
+    webhook_secret?: string;
+    error?: string;
+}
+interface BatchStatusResponse {
+    success: boolean;
+    batch?: DeepResearchBatch;
+    error?: string;
+}
+interface AddBatchTasksResponse {
+    success: boolean;
+    added_count?: number;
+    task_ids?: string[];
+    error?: string;
+}
+interface BatchTaskListItem {
+    deepresearch_id: string;
+    batch_id: string;
+    batch_task_id?: string;
+    query: string;
+    status: DeepResearchStatus;
+    created_at: number;
+    completed_at?: number;
+    error?: string;
+}
+interface ListBatchTasksResponse {
+    success: boolean;
+    tasks?: BatchTaskListItem[];
+    total_count?: number;
+    error?: string;
+}
+interface CancelBatchResponse {
+    success: boolean;
+    message?: string;
+    batch_id?: string;
+    error?: string;
+}
+interface ListBatchesResponse {
+    success: boolean;
+    batches?: DeepResearchBatch[];
+    error?: string;
+}
+interface BatchWaitOptions {
+    pollInterval?: number;
+    maxWaitTime?: number;
+    onProgress?: (batch: DeepResearchBatch) => void;
+}
 
 declare class Valyu {
     private baseUrl;
@@ -367,6 +475,15 @@ declare class Valyu {
         delete: (taskId: string) => Promise<DeepResearchDeleteResponse>;
         togglePublic: (taskId: string, isPublic: boolean) => Promise<DeepResearchTogglePublicResponse>;
     };
+    batch: {
+        create: (options?: CreateBatchOptions) => Promise<CreateBatchResponse>;
+        status: (batchId: string) => Promise<BatchStatusResponse>;
+        addTasks: (batchId: string, options: AddBatchTasksOptions) => Promise<AddBatchTasksResponse>;
+        listTasks: (batchId: string) => Promise<ListBatchTasksResponse>;
+        cancel: (batchId: string) => Promise<CancelBatchResponse>;
+        list: () => Promise<ListBatchesResponse>;
+        waitForCompletion: (batchId: string, options?: BatchWaitOptions) => Promise<DeepResearchBatch>;
+    };
     constructor(apiKey?: string, baseUrl?: string);
     /**
      * Validates date format (YYYY-MM-DD)
@@ -460,6 +577,59 @@ declare class Valyu {
      * DeepResearch: Toggle public flag
      */
     private _deepresearchTogglePublic;
+    /**
+     * 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.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
+     * @returns Promise resolving to response with added_count and task_ids
+     */
+    private _batchAddTasks;
+    /**
+     * Batch: List all tasks in a batch
+     * @param batchId - The batch ID to query
+     * @returns Promise resolving to list of tasks with their status
+     */
+    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
+     * @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
@@ -500,4 +670,4 @@ declare class Valyu {
     private createErrorGenerator;
 }
 
-export { type AIUsage, type AnswerErrorResponse, type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamChunkType, type AnswerSuccessResponse, type ChartDataPoint, type ChartDataSeries, type ChartType, type ContentResponseLength, type ContentResult, type ContentsOptions, type ContentsResponse, type Cost, type CountryCode, type DeepResearchCancelResponse, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type ImageMetadata, type ImageType, type ListOptions, type MCPServerConfig, type Progress, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, Valyu, type WaitOptions };
+export { type AIUsage, type AddBatchTasksOptions, type AddBatchTasksResponse, type AnswerErrorResponse, type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamChunkType, type AnswerSuccessResponse, type BatchCounts, type BatchStatus, type BatchStatusResponse, type BatchTaskInput, type BatchTaskListItem, type BatchUsage, type BatchWaitOptions, type CancelBatchResponse, type ChartDataPoint, type ChartDataSeries, type ChartType, type ContentResponseLength, type ContentResult, type ContentsOptions, type ContentsResponse, type Cost, type CountryCode, type CreateBatchOptions, type CreateBatchResponse, type DeepResearchBatch, type DeepResearchCancelResponse, type DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchListResponse, type DeepResearchMode, type DeepResearchOutputFormat, type DeepResearchSearchConfig, type DeepResearchSource, type DeepResearchStatus, type DeepResearchStatusResponse, type DeepResearchTaskListItem, type DeepResearchTogglePublicResponse, type DeepResearchUpdateResponse, type DeepResearchUsage, type ExtractEffort, type ExtractionMetadata, type FeedbackResponse, type FeedbackSentiment, type FileAttachment, type ImageMetadata, type ImageType, type ListBatchTasksResponse, type ListBatchesResponse, type ListOptions, type MCPServerConfig, type Progress, type ResponseLength, type SearchMetadata, type SearchOptions, type SearchResponse, type SearchResult, type SearchType, type StreamCallback, Valyu, type WaitOptions };