exa-js 1.7.0 → 1.7.2

package/dist/index.d.ts

@@ -5,11 +5,11 @@
 /**
  * Type for API query parameters
  */
-type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
+type QueryParams$1 = Record<string, string | number | boolean | string[] | undefined>;
 /**
  * Type for API request body
  */
-interface RequestBody {
+interface RequestBody$1 {
     [key: string]: unknown;
 }
 /**
@@ -44,13 +44,13 @@ declare class WebsetsBaseClient {
      * @returns The response JSON
      * @throws ExaError with API error details if the request fails
      */
-    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody, params?: QueryParams): Promise<T>;
+    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$1, params?: QueryParams$1): Promise<T>;
     /**
      * Helper to build pagination parameters
      * @param pagination The pagination parameters
      * @returns QueryParams object with pagination parameters
      */
-    protected buildPaginationParams(pagination?: PaginationParams): QueryParams;
+    protected buildPaginationParams(pagination?: PaginationParams): QueryParams$1;
 }
 
 interface components {
@@ -1340,6 +1340,93 @@ declare class WebsetsClient extends WebsetsBaseClient {
     } | number): Promise<Webset>;
 }
 
+/**
+ * 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"
+}
+/**
+ * Response object returned from the research API.
+ */
+type ResearchTaskResponse = {
+    /** Unique identifier for the task. */
+    id: string;
+    /** Current status (may include future enum values served by the API). */
+    status: ResearchStatus | string;
+    /** Structured output that follows the user-provided schema (null while running). */
+    output: Record<string, any> | null;
+    /**
+     * Citations collected while deriving each top-level field in `output`.
+     * The key is the field name, the value is the list of `SearchResult`s that
+     * were used to compute that field.
+     */
+    citations: Record<string, SearchResult<{}>[]>;
+};
+
+type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
+interface RequestBody {
+    [key: string]: unknown;
+}
+/**
+ * Base client class for all Research-related API clients
+ */
+declare class ResearchBaseClient {
+    protected client: Exa;
+    /**
+     * Initialize a new Research base client
+     * @param client The Exa client instance
+     */
+    constructor(client: Exa);
+    /**
+     * Make a request to the Research API (prefixes all paths with `/research`).
+     * @param endpoint The endpoint path, beginning with a slash (e.g. "/tasks").
+     * @param method The HTTP method. Defaults to "POST".
+     * @param data Optional request body
+     * @param params Optional query parameters
+     * @returns The parsed JSON response
+     */
+    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody, params?: QueryParams): Promise<T>;
+}
+
+/**
+ * Client for interacting with the Research Tasks API.
+ */
+declare class ResearchClient extends ResearchBaseClient {
+    constructor(client: Exa);
+    /**
+     * Create and run a research task (blocking call).
+     *
+     * 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 input  Object containing high-level research instructions.
+     * @param output Object containing the expected output schema.
+     * @returns The ResearchTaskResponse returned by the API.
+     */
+    createTask(input: {
+        instructions: string;
+    }, output: {
+        schema: JSONSchema;
+    }): Promise<ResearchTaskResponse>;
+    /**
+     * Retrieve a research task by ID.
+     *
+     * Not yet implemented server-side. Calling this will throw until the API is
+     * available.
+     */
+    getTask(): Promise<ResearchTaskResponse>;
+}
+
 /**
  * HTTP status codes
  */
@@ -1644,23 +1731,25 @@ 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;
@@ -1692,29 +1781,6 @@ 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.
  */
@@ -1725,6 +1791,10 @@ declare class Exa {
      * Websets API client
      */
     websets: WebsetsClient;
+    /**
+     * Research API client
+     */
+    research: ResearchClient;
     /**
      * Helper method to separate out the contents-specific options from the rest.
      */
@@ -1828,44 +1898,10 @@ 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>;
+    private parseSSEStream;
 }
 
-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 };
+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, ResearchClient, 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

@@ -36,6 +36,7 @@ __export(index_exports, {
   Exa: () => Exa2,
   ExaError: () => ExaError,
   HttpStatusCode: () => HttpStatusCode,
+  ResearchClient: () => ResearchClient,
   ResearchStatus: () => ResearchStatus,
   WebhookStatus: () => WebhookStatus,
   WebsetEnrichmentFormat: () => WebsetEnrichmentFormat,
@@ -690,14 +691,76 @@ 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;
+// src/research/base.ts
+var ResearchBaseClient = class {
+  /**
+   * Initialize a new Research base client
+   * @param client The Exa client instance
+   */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Make a request to the Research API (prefixes all paths with `/research`).
+   * @param endpoint The endpoint path, beginning with a slash (e.g. "/tasks").
+   * @param method The HTTP method. Defaults to "POST".
+   * @param data Optional request body
+   * @param params Optional query parameters
+   * @returns The parsed JSON response
+   */
+  async request(endpoint, method = "POST", data, params) {
+    return this.client.request(`/research${endpoint}`, method, data, params);
+  }
+};
+
+// src/research/client.ts
+var ResearchClient = class extends ResearchBaseClient {
+  constructor(client) {
+    super(client);
+  }
+  /**
+   * Create and run a research task (blocking call).
+   *
+   * 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 input  Object containing high-level research instructions.
+   * @param output Object containing the expected output schema.
+   * @returns The ResearchTaskResponse returned by the API.
+   */
+  async createTask(input, output) {
+    return this.request("/tasks", "POST", {
+      input,
+      output
+    });
+  }
+  /**
+   * Retrieve a research task by ID.
+   *
+   * Not yet implemented server-side. Calling this will throw until the API is
+   * available.
+   */
+  async getTask() {
+    throw new Error("getTask is not implemented yet.");
+  }
+};
+
+// src/research/types.ts
 var ResearchStatus = /* @__PURE__ */ ((ResearchStatus2) => {
   ResearchStatus2["completed"] = "completed";
   ResearchStatus2["failed"] = "failed";
   return ResearchStatus2;
 })(ResearchStatus || {});
+
+// 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 Exa2 = class {
   /**
    * Helper method to separate out the contents-specific options from the rest.
@@ -755,6 +818,7 @@ var Exa2 = class {
       "User-Agent": "exa-node 1.4.0"
     });
     this.websets = new WebsetsClient(this);
+    this.research = new ResearchClient(this);
   }
   /**
    * Makes a request to the Exa API.
@@ -804,6 +868,10 @@ var Exa2 = class {
         errorData.path
       );
     }
+    const contentType = response.headers.get("content-type") || "";
+    if (contentType.includes("text/event-stream")) {
+      return await this.parseSSEStream(response);
+    }
     return await response.json();
   }
   /**
@@ -915,7 +983,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);
   }
@@ -944,7 +1013,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",
@@ -1025,47 +1095,76 @@ 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
-    );
+  async parseSSEStream(response) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+      throw new ExaError(
+        "No response body available for streaming.",
+        500,
+        (/* @__PURE__ */ new Date()).toISOString()
+      );
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    return new Promise(async (resolve, reject) => {
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          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;
+            const jsonStr = line.replace(/^data:\s*/, "").trim();
+            if (!jsonStr || jsonStr === "[DONE]") {
+              continue;
+            }
+            let chunk;
+            try {
+              chunk = JSON.parse(jsonStr);
+            } catch {
+              continue;
+            }
+            switch (chunk.tag) {
+              case "complete":
+                reader.releaseLock();
+                resolve(chunk.data);
+                return;
+              case "error": {
+                const message = chunk.error?.message || "Unknown error";
+                reader.releaseLock();
+                reject(
+                  new ExaError(
+                    message,
+                    500 /* InternalServerError */,
+                    (/* @__PURE__ */ new Date()).toISOString()
+                  )
+                );
+                return;
+              }
+              // 'progress' and any other tags are ignored for the blocking variant
+              default:
+                break;
+            }
+          }
+        }
+        reject(
+          new ExaError(
+            "Stream ended without a completion event.",
+            500 /* InternalServerError */,
+            (/* @__PURE__ */ new Date()).toISOString()
+          )
+        );
+      } catch (err) {
+        reject(err);
+      } finally {
+        try {
+          reader.releaseLock();
+        } catch {
+        }
+      }
+    });
   }
 };
 var index_default = Exa2;
@@ -1077,6 +1176,7 @@ var index_default = Exa2;
   Exa,
   ExaError,
   HttpStatusCode,
+  ResearchClient,
   ResearchStatus,
   WebhookStatus,
   WebsetEnrichmentFormat,