exa-js 1.7.1 → 1.7.3

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,95 @@ 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 a research task.
+   *
+   * 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.
+   */
+  async getTask(id) {
+    return this.request(`/tasks/${id}`, "GET");
+  }
+  /**
+   * Poll a research task until completion or failure.
+   * Polls every 1 second with a maximum timeout of 10 minutes.
+   */
+  async pollTask(id) {
+    const pollingInterval = 1e3;
+    const maxPollingTime = 10 * 60 * 1e3;
+    const startTime = Date.now();
+    while (true) {
+      const task = await this.request(`/tasks/${id}`, "GET");
+      if (task.status === "completed" || task.status === "failed") {
+        return task;
+      }
+      if (Date.now() - startTime > maxPollingTime) {
+        throw new Error(
+          `Polling timeout: Task ${id} did not complete within 10 minutes`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollingInterval));
+    }
+  }
+};
+
+// src/research/types.ts
 var ResearchStatus = /* @__PURE__ */ ((ResearchStatus2) => {
+  ResearchStatus2["in_progress"] = "in_progress";
   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 +837,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 +887,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();
   }
   /**
@@ -1027,47 +1114,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;
@@ -1079,6 +1195,7 @@ var index_default = Exa2;
   Exa,
   ExaError,
   HttpStatusCode,
+  ResearchClient,
   ResearchStatus,
   WebhookStatus,
   WebsetEnrichmentFormat,