valyu-js 2.7.0 → 2.7.2

package/dist/index.d.mts

@@ -204,7 +204,7 @@ interface AlertEmailConfig {
     custom_url?: string;
 }
 type DeepResearchMode = "fast" | "standard" | "lite" | "heavy" | "max";
-type DeepResearchStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+type DeepResearchStatus = "queued" | "running" | "awaiting_input" | "paused" | "completed" | "failed" | "cancelled";
 type DeepResearchOutputFormat = "markdown" | "pdf" | "toon" | Record<string, any>;
 type DeepResearchOutputType = "markdown" | "json" | "toon";
 type ImageType = "chart" | "ai_generated";
@@ -281,6 +281,30 @@ interface DeepResearchCreateOptions {
     alertEmail?: string | AlertEmailConfig;
     brandCollectionId?: string;
     metadata?: Record<string, string | number | boolean>;
+    hitl?: HitlConfig;
+}
+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<string, any>;
+    created_at: number;
+    timeout_ms: number;
+    expected_response?: Record<string, any>;
+}
+interface InteractionHistoryEntry {
+    interaction_id: string;
+    type: InteractionType;
+    created_at: number;
+    responded_at?: number;
+    auto_continued: boolean;
+    response?: Record<string, any>;
 }
 interface Progress {
     current_step: number;
@@ -365,6 +389,9 @@ interface DeepResearchStatusResponse {
     usage?: DeepResearchUsage;
     batch_id?: string;
     batch_task_id?: string;
+    hitl_config?: Record<string, boolean>;
+    interaction?: Interaction;
+    hitl_history?: InteractionHistoryEntry[];
     error?: string;
 }
 interface DeepResearchTaskListItem {
@@ -414,10 +441,17 @@ interface DeepResearchGetAssetsResponse {
     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<Record<string, any> | null | undefined> | Record<string, any> | null | undefined;
 }
 interface StreamCallback {
     onMessage?: (message: any) => void;
@@ -649,6 +683,17 @@ declare class Valyu {
         delete: (taskId: string) => Promise<DeepResearchDeleteResponse>;
         togglePublic: (taskId: string, isPublic: boolean) => Promise<DeepResearchTogglePublicResponse>;
         getAssets: (taskId: string, assetId: string, options?: DeepResearchGetAssetsOptions) => Promise<DeepResearchGetAssetsResponse>;
+        respond: (taskId: string, interactionId: string, response: Record<string, any>) => Promise<DeepResearchRespondResponse>;
+        respondPlanningQuestions: (taskId: string, interactionId: string, answers: {
+            question: string;
+            answer: string;
+        }[]) => Promise<DeepResearchRespondResponse>;
+        approvePlan: (taskId: string, interactionId: string, modifications?: string) => Promise<DeepResearchRespondResponse>;
+        respondSourceReview: (taskId: string, interactionId: string, options?: {
+            includedDomains?: string[];
+            excludedDomains?: string[];
+        }) => Promise<DeepResearchRespondResponse>;
+        approveOutline: (taskId: string, interactionId: string, modifications?: string) => Promise<DeepResearchRespondResponse>;
     };
     batch: {
         create: (options?: CreateBatchOptions) => Promise<CreateBatchResponse>;
@@ -767,6 +812,29 @@ declare class Valyu {
      * 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
      */
@@ -900,4 +968,4 @@ declare class Valyu {
     private _datasourcesCategories;
 }
 
-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 DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchGetAssetsOptions, type DeepResearchGetAssetsResponse, 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 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, 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 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 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, Valyu, type WaitOptions, verifyContentsWebhookSignature };

package/dist/index.d.ts

@@ -204,7 +204,7 @@ interface AlertEmailConfig {
     custom_url?: string;
 }
 type DeepResearchMode = "fast" | "standard" | "lite" | "heavy" | "max";
-type DeepResearchStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+type DeepResearchStatus = "queued" | "running" | "awaiting_input" | "paused" | "completed" | "failed" | "cancelled";
 type DeepResearchOutputFormat = "markdown" | "pdf" | "toon" | Record<string, any>;
 type DeepResearchOutputType = "markdown" | "json" | "toon";
 type ImageType = "chart" | "ai_generated";
@@ -281,6 +281,30 @@ interface DeepResearchCreateOptions {
     alertEmail?: string | AlertEmailConfig;
     brandCollectionId?: string;
     metadata?: Record<string, string | number | boolean>;
+    hitl?: HitlConfig;
+}
+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<string, any>;
+    created_at: number;
+    timeout_ms: number;
+    expected_response?: Record<string, any>;
+}
+interface InteractionHistoryEntry {
+    interaction_id: string;
+    type: InteractionType;
+    created_at: number;
+    responded_at?: number;
+    auto_continued: boolean;
+    response?: Record<string, any>;
 }
 interface Progress {
     current_step: number;
@@ -365,6 +389,9 @@ interface DeepResearchStatusResponse {
     usage?: DeepResearchUsage;
     batch_id?: string;
     batch_task_id?: string;
+    hitl_config?: Record<string, boolean>;
+    interaction?: Interaction;
+    hitl_history?: InteractionHistoryEntry[];
     error?: string;
 }
 interface DeepResearchTaskListItem {
@@ -414,10 +441,17 @@ interface DeepResearchGetAssetsResponse {
     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<Record<string, any> | null | undefined> | Record<string, any> | null | undefined;
 }
 interface StreamCallback {
     onMessage?: (message: any) => void;
@@ -649,6 +683,17 @@ declare class Valyu {
         delete: (taskId: string) => Promise<DeepResearchDeleteResponse>;
         togglePublic: (taskId: string, isPublic: boolean) => Promise<DeepResearchTogglePublicResponse>;
         getAssets: (taskId: string, assetId: string, options?: DeepResearchGetAssetsOptions) => Promise<DeepResearchGetAssetsResponse>;
+        respond: (taskId: string, interactionId: string, response: Record<string, any>) => Promise<DeepResearchRespondResponse>;
+        respondPlanningQuestions: (taskId: string, interactionId: string, answers: {
+            question: string;
+            answer: string;
+        }[]) => Promise<DeepResearchRespondResponse>;
+        approvePlan: (taskId: string, interactionId: string, modifications?: string) => Promise<DeepResearchRespondResponse>;
+        respondSourceReview: (taskId: string, interactionId: string, options?: {
+            includedDomains?: string[];
+            excludedDomains?: string[];
+        }) => Promise<DeepResearchRespondResponse>;
+        approveOutline: (taskId: string, interactionId: string, modifications?: string) => Promise<DeepResearchRespondResponse>;
     };
     batch: {
         create: (options?: CreateBatchOptions) => Promise<CreateBatchResponse>;
@@ -767,6 +812,29 @@ declare class Valyu {
      * 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
      */
@@ -900,4 +968,4 @@ declare class Valyu {
     private _datasourcesCategories;
 }
 
-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 DeepResearchCreateOptions, type DeepResearchCreateResponse, type DeepResearchDeleteResponse, type DeepResearchGetAssetsOptions, type DeepResearchGetAssetsResponse, 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 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, 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 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 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, Valyu, type WaitOptions, verifyContentsWebhookSignature };

package/dist/index.js

@@ -97,7 +97,12 @@ var Valyu = class {
       cancel: this._deepresearchCancel.bind(this),
       delete: this._deepresearchDelete.bind(this),
       togglePublic: this._deepresearchTogglePublic.bind(this),
-      getAssets: this._deepresearchGetAssets.bind(this)
+      getAssets: this._deepresearchGetAssets.bind(this),
+      respond: this._deepresearchRespond.bind(this),
+      respondPlanningQuestions: this._deepresearchRespondPlanningQuestions.bind(this),
+      approvePlan: this._deepresearchApprovePlan.bind(this),
+      respondSourceReview: this._deepresearchRespondSourceReview.bind(this),
+      approveOutline: this._deepresearchApproveOutline.bind(this)
     };
     this.batch = {
       create: this._batchCreate.bind(this),
@@ -708,6 +713,17 @@ var Valyu = class {
         }
       }
       if (options.metadata) payload.metadata = options.metadata;
+      if (options.hitl) {
+        payload.hitl = {};
+        if (options.hitl.planningQuestions !== void 0)
+          payload.hitl.planning_questions = options.hitl.planningQuestions;
+        if (options.hitl.planReview !== void 0)
+          payload.hitl.plan_review = options.hitl.planReview;
+        if (options.hitl.sourceReview !== void 0)
+          payload.hitl.source_review = options.hitl.sourceReview;
+        if (options.hitl.outlineReview !== void 0)
+          payload.hitl.outline_review = options.hitl.outlineReview;
+      }
       const response = await import_axios.default.post(
         `${this.baseUrl}/deepresearch/tasks`,
         payload,
@@ -753,6 +769,19 @@ var Valyu = class {
       if (options.onProgress) {
         options.onProgress(status);
       }
+      if ((status.status === "awaiting_input" || status.status === "paused") && status.interaction) {
+        if (options.onInteraction) {
+          const response = await options.onInteraction(status.interaction);
+          if (response) {
+            await this._deepresearchRespond(
+              taskId,
+              status.interaction.interaction_id,
+              response
+            );
+            continue;
+          }
+        }
+      }
       if (status.status === "completed" || status.status === "failed" || status.status === "cancelled") {
         return status;
       }
@@ -854,6 +883,69 @@ var Valyu = class {
       };
     }
   }
+  /**
+   * 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
+   */
+  async _deepresearchRespond(taskId, interactionId, response) {
+    try {
+      const resp = await import_axios.default.post(
+        `${this.baseUrl}/deepresearch/tasks/${taskId}/respond`,
+        {
+          interaction_id: interactionId,
+          response
+        },
+        { headers: this.headers }
+      );
+      return { success: true, ...resp.data };
+    } catch (e) {
+      return {
+        success: false,
+        error: e.response?.data?.error || e.message
+      };
+    }
+  }
+  /**
+   * DeepResearch: Respond to a planning_questions checkpoint
+   */
+  async _deepresearchRespondPlanningQuestions(taskId, interactionId, answers) {
+    return this._deepresearchRespond(taskId, interactionId, {
+      answers
+    });
+  }
+  /**
+   * DeepResearch: Approve or request modifications to a plan_review checkpoint
+   */
+  async _deepresearchApprovePlan(taskId, interactionId, modifications) {
+    const response = { approved: true };
+    if (modifications) {
+      response.approved = false;
+      response.modifications = modifications;
+    }
+    return this._deepresearchRespond(taskId, interactionId, response);
+  }
+  /**
+   * DeepResearch: Respond to a source_review checkpoint
+   */
+  async _deepresearchRespondSourceReview(taskId, interactionId, options = {}) {
+    return this._deepresearchRespond(taskId, interactionId, {
+      included_domains: options.includedDomains || [],
+      excluded_domains: options.excludedDomains || []
+    });
+  }
+  /**
+   * DeepResearch: Approve or request modifications to an outline_review checkpoint
+   */
+  async _deepresearchApproveOutline(taskId, interactionId, modifications) {
+    const response = { approved: true };
+    if (modifications) {
+      response.approved = false;
+      response.modifications = modifications;
+    }
+    return this._deepresearchRespond(taskId, interactionId, response);
+  }
   /**
    * DeepResearch: Cancel task
    */