exa-js 1.6.13 → 1.7.1

package/dist/index.d.ts

@@ -1644,24 +1644,28 @@ type SearchResponse<T extends ContentsOptions> = {
  * @property {boolean} [text] - Whether to include text in the source results. Default false.
  * @property {"exa" | "exa-pro"} [model] - The model to use for generating the answer. Default "exa".
  * @property {string} [systemPrompt] - A system prompt to guide the LLM's behavior when generating the answer.
+ * @property {Object} [outputSchema] - A JSON Schema specification for the structure you expect the output to take
  */
 type AnswerOptions = {
     stream?: boolean;
     text?: boolean;
     model?: "exa" | "exa-pro";
     systemPrompt?: string;
+    outputSchema?: Record<string, unknown>;
 };
 /**
  * Represents an answer response object from the /answer endpoint.
  * @typedef {Object} AnswerResponse
- * @property {string} answer - The generated answer text.
+ * @property {string | Object} answer - The generated answer text (or an object matching `outputSchema`, if provided)
  * @property {SearchResult<{}>[]} citations - The sources used to generate the answer.
+ * @property {CostDollars} [costDollars] - The cost breakdown for this request.
  * @property {string} [requestId] - Optional request ID for the answer.
  */
 type AnswerResponse = {
-    answer: string;
+    answer: string | Record<string, unknown>;
     citations: SearchResult<{}>[];
     requestId?: string;
+    costDollars?: CostDollars;
 };
 type AnswerStreamChunk = {
     /**
@@ -1690,6 +1694,28 @@ type AnswerStreamResponse = {
     answer?: string;
     citations?: SearchResult<{}>[];
 };
+/**
+ * Enum representing the status of a research task.
+ */
+declare enum ResearchStatus {
+    /** The research request has finished successfully. */
+    completed = "completed",
+    /** The research request failed. */
+    failed = "failed"
+}
+/**
+ * @typedef {Object} ResearchTaskResponse
+ * @property {string} id - The unique identifier of the research request.
+ * @property {ResearchStatus | string} status - The current status of the research request.
+ * @property {Record<string, any> | null} output - The structured output, if the research has completed.
+ * @property {SearchResult<{}>[]} citations - References used for the research.
+ */
+type ResearchTaskResponse = {
+    id: string;
+    status: ResearchStatus | string;
+    output: Record<string, any> | null;
+    citations: SearchResult<{}>[];
+};
 
 /**
  * The Exa class encapsulates the API's endpoints.
@@ -1804,8 +1830,45 @@ declare class Exa {
         text?: boolean;
         model?: "exa" | "exa-pro";
         systemPrompt?: string;
+        outputSchema?: Record<string, unknown>;
     }): AsyncGenerator<AnswerStreamChunk>;
     private processChunk;
+    /**
+     * Creates and runs a research task in a blocking manner.
+     *
+     * Both parameters are required and have fixed shapes:
+     * 1. `input`
+     *      `{ instructions: string }`
+     *     • `instructions` – High-level guidance that tells the research agent what to do.
+     * 2. `output`
+     *    defines the exact structure you expect back, and guides the research conducted by the agent.
+     *      `{ schema: JSONSchema }`.
+     *    The agent’s response will be validated against this schema.
+     *
+     * @param {{ instructions: string }} input   The research prompt.
+     * @param {{ schema: JSONSchema }}                output  The desired output schema.
+     * @returns {Promise<ResearchTaskResponse>}                     The research response.
+     *
+     * @example
+     * const response = await exa.researchTask(
+     *   { instructions: "I need a few key facts about honey pot ants." },
+     *   {
+     *     schema: {
+     *       type: "object",
+     *       required: ["scientificName", "primaryRegions"],
+     *       properties: {
+     *         scientificName: { type: "string" },
+     *         primaryRegions:  { type: "string" },
+     *       },
+     *     },
+     *   },
+     * );
+     */
+    researchTask(input: {
+        instructions: string;
+    }, output: {
+        schema: JSONSchema;
+    }): Promise<ResearchTaskResponse>;
 }
 
-export { AnswerOptions, AnswerResponse, AnswerStreamChunk, AnswerStreamResponse, BaseSearchOptions, ContentsOptions, ContentsResultComponent, CostDollars, CostDollarsContents, CostDollarsSeearch, CreateEnrichmentParameters, CreateEnrichmentParametersFormat, CreateWebhookParameters, CreateWebsetParameters, CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, Default, EnrichmentResult, Event, EventType, Exa, ExaError, ExtrasOptions, ExtrasResponse, FindSimilarOptions, GetWebsetResponse, HighlightsContentsOptions, HighlightsResponse, HttpStatusCode, JSONSchema, ListEventsResponse, ListWebhooksOptions, ListWebhooksResponse, ListWebsetItemResponse, ListWebsetsOptions, ListWebsetsResponse, LivecrawlOptions, RegularSearchOptions, SearchResponse, SearchResult, SubpagesResponse, SummaryContentsOptions, SummaryResponse, TextContentsOptions, TextResponse, UpdateWebhookParameters, UpdateWebsetRequest, Webhook, WebhookStatus, Webset, WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };
+export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchStatus, type ResearchTaskResponse, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };

package/dist/index.js

@@ -28,14 +28,15 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
   CreateEnrichmentParametersFormat: () => CreateEnrichmentParametersFormat,
   CreateWebsetSearchParametersBehaviour: () => CreateWebsetSearchParametersBehaviour,
   EventType: () => EventType,
   Exa: () => Exa2,
   ExaError: () => ExaError,
   HttpStatusCode: () => HttpStatusCode,
+  ResearchStatus: () => ResearchStatus,
   WebhookStatus: () => WebhookStatus,
   WebsetEnrichmentFormat: () => WebsetEnrichmentFormat,
   WebsetEnrichmentStatus: () => WebsetEnrichmentStatus,
@@ -49,9 +50,9 @@ __export(src_exports, {
   WebsetStatus: () => WebsetStatus,
   WebsetWebhooksClient: () => WebsetWebhooksClient,
   WebsetsClient: () => WebsetsClient,
-  default: () => src_default
+  default: () => index_default
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 var import_cross_fetch = __toESM(require("cross-fetch"));
 
 // src/errors.ts
@@ -111,12 +112,9 @@ var WebsetsBaseClient = class {
    */
   buildPaginationParams(pagination) {
     const params = {};
-    if (!pagination)
-      return params;
-    if (pagination.cursor)
-      params.cursor = pagination.cursor;
-    if (pagination.limit)
-      params.limit = pagination.limit;
+    if (!pagination) return params;
+    if (pagination.cursor) params.cursor = pagination.cursor;
+    if (pagination.limit) params.limit = pagination.limit;
     return params;
   }
 };
@@ -695,6 +693,11 @@ var WebsetsClient = class extends WebsetsBaseClient {
 // src/index.ts
 var fetchImpl = typeof global !== "undefined" && global.fetch ? global.fetch : import_cross_fetch.default;
 var HeadersImpl = typeof global !== "undefined" && global.Headers ? global.Headers : import_cross_fetch.Headers;
+var ResearchStatus = /* @__PURE__ */ ((ResearchStatus2) => {
+  ResearchStatus2["completed"] = "completed";
+  ResearchStatus2["failed"] = "failed";
+  return ResearchStatus2;
+})(ResearchStatus || {});
 var Exa2 = class {
   /**
    * Helper method to separate out the contents-specific options from the rest.
@@ -715,20 +718,14 @@ var Exa2 = class {
     if (text === void 0 && summary === void 0 && highlights === void 0 && extras === void 0) {
       contentsOptions.text = true;
     }
-    if (text !== void 0)
-      contentsOptions.text = text;
-    if (summary !== void 0)
-      contentsOptions.summary = summary;
-    if (highlights !== void 0)
-      contentsOptions.highlights = highlights;
-    if (subpages !== void 0)
-      contentsOptions.subpages = subpages;
+    if (text !== void 0) contentsOptions.text = text;
+    if (summary !== void 0) contentsOptions.summary = summary;
+    if (highlights !== void 0) contentsOptions.highlights = highlights;
+    if (subpages !== void 0) contentsOptions.subpages = subpages;
     if (subpageTarget !== void 0)
       contentsOptions.subpageTarget = subpageTarget;
-    if (extras !== void 0)
-      contentsOptions.extras = extras;
-    if (livecrawl !== void 0)
-      contentsOptions.livecrawl = livecrawl;
+    if (extras !== void 0) contentsOptions.extras = extras;
+    if (livecrawl !== void 0) contentsOptions.livecrawl = livecrawl;
     if (livecrawlTimeout !== void 0)
       contentsOptions.livecrawlTimeout = livecrawlTimeout;
     return {
@@ -918,7 +915,8 @@ var Exa2 = class {
       stream: false,
       text: options?.text ?? false,
       model: options?.model ?? "exa",
-      systemPrompt: options?.systemPrompt
+      systemPrompt: options?.systemPrompt,
+      outputSchema: options?.outputSchema
     };
     return await this.request("/answer", "POST", requestBody);
   }
@@ -947,7 +945,8 @@ var Exa2 = class {
       text: options?.text ?? false,
       stream: true,
       model: options?.model ?? "exa",
-      systemPrompt: options?.systemPrompt
+      systemPrompt: options?.systemPrompt,
+      outputSchema: options?.outputSchema
     };
     const response = await fetchImpl(this.baseURL + "/answer", {
       method: "POST",
@@ -971,14 +970,12 @@ var Exa2 = class {
     try {
       while (true) {
         const { done, value } = await reader.read();
-        if (done)
-          break;
+        if (done) break;
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split("\n");
         buffer = lines.pop() || "";
         for (const line of lines) {
-          if (!line.startsWith("data: "))
-            continue;
+          if (!line.startsWith("data: ")) continue;
           const jsonStr = line.replace(/^data:\s*/, "").trim();
           if (!jsonStr || jsonStr === "[DONE]") {
             continue;
@@ -1030,8 +1027,50 @@ var Exa2 = class {
     }
     return { content, citations };
   }
+  /**
+   * Creates and runs a research task in a blocking manner.
+   *
+   * Both parameters are required and have fixed shapes:
+   * 1. `input`
+   *      `{ instructions: string }`
+   *     • `instructions` – High-level guidance that tells the research agent what to do.
+   * 2. `output`
+   *    defines the exact structure you expect back, and guides the research conducted by the agent.
+   *      `{ schema: JSONSchema }`.
+   *    The agent’s response will be validated against this schema.
+   *
+   * @param {{ instructions: string }} input   The research prompt.
+   * @param {{ schema: JSONSchema }}                output  The desired output schema.
+   * @returns {Promise<ResearchTaskResponse>}                     The research response.
+   *
+   * @example
+   * const response = await exa.researchTask(
+   *   { instructions: "I need a few key facts about honey pot ants." },
+   *   {
+   *     schema: {
+   *       type: "object",
+   *       required: ["scientificName", "primaryRegions"],
+   *       properties: {
+   *         scientificName: { type: "string" },
+   *         primaryRegions:  { type: "string" },
+   *       },
+   *     },
+   *   },
+   * );
+   */
+  async researchTask(input, output) {
+    const body = {
+      input,
+      output
+    };
+    return await this.request(
+      "/research/tasks",
+      "POST",
+      body
+    );
+  }
 };
-var src_default = Exa2;
+var index_default = Exa2;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CreateEnrichmentParametersFormat,
@@ -1040,6 +1079,7 @@ var src_default = Exa2;
   Exa,
   ExaError,
   HttpStatusCode,
+  ResearchStatus,
   WebhookStatus,
   WebsetEnrichmentFormat,
   WebsetEnrichmentStatus,