exa-js 1.5.13 → 1.7.0

package/dist/index.js

@@ -28,15 +28,677 @@ 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, {
-  default: () => src_default
+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,
+  WebsetEnrichmentsClient: () => WebsetEnrichmentsClient,
+  WebsetItemEvaluationSatisfied: () => WebsetItemEvaluationSatisfied,
+  WebsetItemSource: () => WebsetItemSource,
+  WebsetItemsClient: () => WebsetItemsClient,
+  WebsetSearchCanceledReason: () => WebsetSearchCanceledReason,
+  WebsetSearchStatus: () => WebsetSearchStatus,
+  WebsetSearchesClient: () => WebsetSearchesClient,
+  WebsetStatus: () => WebsetStatus,
+  WebsetWebhooksClient: () => WebsetWebhooksClient,
+  WebsetsClient: () => WebsetsClient,
+  default: () => index_default
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 var import_cross_fetch = __toESM(require("cross-fetch"));
+
+// src/errors.ts
+var HttpStatusCode = /* @__PURE__ */ ((HttpStatusCode2) => {
+  HttpStatusCode2[HttpStatusCode2["BadRequest"] = 400] = "BadRequest";
+  HttpStatusCode2[HttpStatusCode2["NotFound"] = 404] = "NotFound";
+  HttpStatusCode2[HttpStatusCode2["Unauthorized"] = 401] = "Unauthorized";
+  HttpStatusCode2[HttpStatusCode2["Forbidden"] = 403] = "Forbidden";
+  HttpStatusCode2[HttpStatusCode2["TooManyRequests"] = 429] = "TooManyRequests";
+  HttpStatusCode2[HttpStatusCode2["RequestTimeout"] = 408] = "RequestTimeout";
+  HttpStatusCode2[HttpStatusCode2["InternalServerError"] = 500] = "InternalServerError";
+  HttpStatusCode2[HttpStatusCode2["ServiceUnavailable"] = 503] = "ServiceUnavailable";
+  return HttpStatusCode2;
+})(HttpStatusCode || {});
+var ExaError = class extends Error {
+  /**
+   * Create a new ExaError
+   * @param message Error message
+   * @param statusCode HTTP status code
+   * @param timestamp ISO timestamp from API
+   * @param path Path that caused the error
+   */
+  constructor(message, statusCode, timestamp, path) {
+    super(message);
+    this.name = "ExaError";
+    this.statusCode = statusCode;
+    this.timestamp = timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
+    this.path = path;
+  }
+};
+
+// src/websets/base.ts
+var WebsetsBaseClient = class {
+  /**
+   * Initialize a new Websets base client
+   * @param client The Exa client instance
+   */
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Make a request to the Websets API
+   * @param endpoint The endpoint path
+   * @param method The HTTP method
+   * @param data Optional request body data
+   * @param params Optional query parameters
+   * @returns The response JSON
+   * @throws ExaError with API error details if the request fails
+   */
+  async request(endpoint, method = "POST", data, params) {
+    return this.client.request(`/websets${endpoint}`, method, data, params);
+  }
+  /**
+   * Helper to build pagination parameters
+   * @param pagination The pagination parameters
+   * @returns QueryParams object with pagination parameters
+   */
+  buildPaginationParams(pagination) {
+    const params = {};
+    if (!pagination) return params;
+    if (pagination.cursor) params.cursor = pagination.cursor;
+    if (pagination.limit) params.limit = pagination.limit;
+    return params;
+  }
+};
+
+// src/websets/enrichments.ts
+var WebsetEnrichmentsClient = class extends WebsetsBaseClient {
+  /**
+   * Create an Enrichment for a Webset
+   * @param websetId The ID of the Webset
+   * @param params The enrichment parameters
+   * @returns The created Webset Enrichment
+   */
+  async create(websetId, params) {
+    return this.request(
+      `/v0/websets/${websetId}/enrichments`,
+      "POST",
+      params
+    );
+  }
+  /**
+   * Get an Enrichment by ID
+   * @param websetId The ID of the Webset
+   * @param id The ID of the Enrichment
+   * @returns The Webset Enrichment
+   */
+  async get(websetId, id) {
+    return this.request(
+      `/v0/websets/${websetId}/enrichments/${id}`,
+      "GET"
+    );
+  }
+  /**
+   * Delete an Enrichment
+   * @param websetId The ID of the Webset
+   * @param id The ID of the Enrichment
+   * @returns The deleted Webset Enrichment
+   */
+  async delete(websetId, id) {
+    return this.request(
+      `/v0/websets/${websetId}/enrichments/${id}`,
+      "DELETE"
+    );
+  }
+  /**
+   * Cancel a running Enrichment
+   * @param websetId The ID of the Webset
+   * @param id The ID of the Enrichment
+   * @returns The canceled Webset Enrichment
+   */
+  async cancel(websetId, id) {
+    return this.request(
+      `/v0/websets/${websetId}/enrichments/${id}/cancel`,
+      "POST"
+    );
+  }
+};
+
+// src/websets/events.ts
+var EventsClient = class extends WebsetsBaseClient {
+  /**
+   * Initialize a new Events client
+   * @param client The Exa client instance
+   */
+  constructor(client) {
+    super(client);
+  }
+  /**
+   * List all Events
+   * @param options Optional filtering and pagination options
+   * @returns The list of Events
+   */
+  async list(options) {
+    const params = {
+      cursor: options?.cursor,
+      limit: options?.limit,
+      types: options?.types
+    };
+    return this.request(
+      "/v0/events",
+      "GET",
+      void 0,
+      params
+    );
+  }
+  /**
+   * Get an Event by ID
+   * @param id The ID of the Event
+   * @returns The Event
+   */
+  async get(id) {
+    return this.request(`/v0/events/${id}`, "GET");
+  }
+};
+
+// src/websets/items.ts
+var WebsetItemsClient = class extends WebsetsBaseClient {
+  /**
+   * List all Items for a Webset
+   * @param websetId The ID of the Webset
+   * @param params - Optional pagination parameters
+   * @returns A promise that resolves with the list of Items
+   */
+  list(websetId, params) {
+    const queryParams = this.buildPaginationParams(params);
+    return this.request(
+      `/v0/websets/${websetId}/items`,
+      "GET",
+      void 0,
+      queryParams
+    );
+  }
+  /**
+   * Iterate through all Items in a Webset, handling pagination automatically
+   * @param websetId The ID of the Webset
+   * @param options Pagination options
+   * @returns Async generator of Webset Items
+   */
+  async *listAll(websetId, options) {
+    let cursor = void 0;
+    const pageOptions = options ? { ...options } : {};
+    while (true) {
+      pageOptions.cursor = cursor;
+      const response = await this.list(websetId, pageOptions);
+      for (const item of response.data) {
+        yield item;
+      }
+      if (!response.hasMore || !response.nextCursor) {
+        break;
+      }
+      cursor = response.nextCursor;
+    }
+  }
+  /**
+   * Collect all items from a Webset into an array
+   * @param websetId The ID of the Webset
+   * @param options Pagination options
+   * @returns Promise resolving to an array of all Webset Items
+   */
+  async getAll(websetId, options) {
+    const items = [];
+    for await (const item of this.listAll(websetId, options)) {
+      items.push(item);
+    }
+    return items;
+  }
+  /**
+   * Get an Item by ID
+   * @param websetId The ID of the Webset
+   * @param id The ID of the Item
+   * @returns The Webset Item
+   */
+  async get(websetId, id) {
+    return this.request(
+      `/v0/websets/${websetId}/items/${id}`,
+      "GET"
+    );
+  }
+  /**
+   * Delete an Item
+   * @param websetId The ID of the Webset
+   * @param id The ID of the Item
+   * @returns The deleted Webset Item
+   */
+  async delete(websetId, id) {
+    return this.request(
+      `/v0/websets/${websetId}/items/${id}`,
+      "DELETE"
+    );
+  }
+};
+
+// src/websets/openapi.ts
+var CreateEnrichmentParametersFormat = /* @__PURE__ */ ((CreateEnrichmentParametersFormat2) => {
+  CreateEnrichmentParametersFormat2["text"] = "text";
+  CreateEnrichmentParametersFormat2["date"] = "date";
+  CreateEnrichmentParametersFormat2["number"] = "number";
+  CreateEnrichmentParametersFormat2["options"] = "options";
+  CreateEnrichmentParametersFormat2["email"] = "email";
+  CreateEnrichmentParametersFormat2["phone"] = "phone";
+  return CreateEnrichmentParametersFormat2;
+})(CreateEnrichmentParametersFormat || {});
+var CreateWebsetSearchParametersBehaviour = /* @__PURE__ */ ((CreateWebsetSearchParametersBehaviour2) => {
+  CreateWebsetSearchParametersBehaviour2["override"] = "override";
+  return CreateWebsetSearchParametersBehaviour2;
+})(CreateWebsetSearchParametersBehaviour || {});
+var EventType = /* @__PURE__ */ ((EventType2) => {
+  EventType2["webset_created"] = "webset.created";
+  EventType2["webset_deleted"] = "webset.deleted";
+  EventType2["webset_paused"] = "webset.paused";
+  EventType2["webset_idle"] = "webset.idle";
+  EventType2["webset_search_created"] = "webset.search.created";
+  EventType2["webset_search_canceled"] = "webset.search.canceled";
+  EventType2["webset_search_completed"] = "webset.search.completed";
+  EventType2["webset_search_updated"] = "webset.search.updated";
+  EventType2["webset_export_created"] = "webset.export.created";
+  EventType2["webset_export_completed"] = "webset.export.completed";
+  EventType2["webset_item_created"] = "webset.item.created";
+  EventType2["webset_item_enriched"] = "webset.item.enriched";
+  return EventType2;
+})(EventType || {});
+var WebhookStatus = /* @__PURE__ */ ((WebhookStatus2) => {
+  WebhookStatus2["active"] = "active";
+  WebhookStatus2["inactive"] = "inactive";
+  return WebhookStatus2;
+})(WebhookStatus || {});
+var WebsetStatus = /* @__PURE__ */ ((WebsetStatus2) => {
+  WebsetStatus2["idle"] = "idle";
+  WebsetStatus2["running"] = "running";
+  WebsetStatus2["paused"] = "paused";
+  return WebsetStatus2;
+})(WebsetStatus || {});
+var WebsetEnrichmentStatus = /* @__PURE__ */ ((WebsetEnrichmentStatus2) => {
+  WebsetEnrichmentStatus2["pending"] = "pending";
+  WebsetEnrichmentStatus2["canceled"] = "canceled";
+  WebsetEnrichmentStatus2["completed"] = "completed";
+  return WebsetEnrichmentStatus2;
+})(WebsetEnrichmentStatus || {});
+var WebsetEnrichmentFormat = /* @__PURE__ */ ((WebsetEnrichmentFormat2) => {
+  WebsetEnrichmentFormat2["text"] = "text";
+  WebsetEnrichmentFormat2["date"] = "date";
+  WebsetEnrichmentFormat2["number"] = "number";
+  WebsetEnrichmentFormat2["options"] = "options";
+  WebsetEnrichmentFormat2["email"] = "email";
+  WebsetEnrichmentFormat2["phone"] = "phone";
+  return WebsetEnrichmentFormat2;
+})(WebsetEnrichmentFormat || {});
+var WebsetItemSource = /* @__PURE__ */ ((WebsetItemSource2) => {
+  WebsetItemSource2["search"] = "search";
+  return WebsetItemSource2;
+})(WebsetItemSource || {});
+var WebsetItemEvaluationSatisfied = /* @__PURE__ */ ((WebsetItemEvaluationSatisfied2) => {
+  WebsetItemEvaluationSatisfied2["yes"] = "yes";
+  WebsetItemEvaluationSatisfied2["no"] = "no";
+  WebsetItemEvaluationSatisfied2["unclear"] = "unclear";
+  return WebsetItemEvaluationSatisfied2;
+})(WebsetItemEvaluationSatisfied || {});
+var WebsetSearchCanceledReason = /* @__PURE__ */ ((WebsetSearchCanceledReason2) => {
+  WebsetSearchCanceledReason2["webset_deleted"] = "webset_deleted";
+  WebsetSearchCanceledReason2["webset_canceled"] = "webset_canceled";
+  return WebsetSearchCanceledReason2;
+})(WebsetSearchCanceledReason || {});
+var WebsetSearchStatus = /* @__PURE__ */ ((WebsetSearchStatus2) => {
+  WebsetSearchStatus2["created"] = "created";
+  WebsetSearchStatus2["running"] = "running";
+  WebsetSearchStatus2["completed"] = "completed";
+  WebsetSearchStatus2["canceled"] = "canceled";
+  return WebsetSearchStatus2;
+})(WebsetSearchStatus || {});
+
+// src/websets/searches.ts
+var WebsetSearchesClient = class extends WebsetsBaseClient {
+  /**
+   * Create a new Search for the Webset
+   * @param websetId The ID of the Webset
+   * @param params The search parameters
+   * @returns The created Webset Search
+   */
+  async create(websetId, params) {
+    return this.request(
+      `/v0/websets/${websetId}/searches`,
+      "POST",
+      params
+    );
+  }
+  /**
+   * Get a Search by ID
+   * @param websetId The ID of the Webset
+   * @param id The ID of the Search
+   * @returns The Webset Search
+   */
+  async get(websetId, id) {
+    return this.request(
+      `/v0/websets/${websetId}/searches/${id}`,
+      "GET"
+    );
+  }
+  /**
+   * Cancel a running Search
+   * @param websetId The ID of the Webset
+   * @param id The ID of the Search
+   * @returns The canceled Webset Search
+   */
+  async cancel(websetId, id) {
+    return this.request(
+      `/v0/websets/${websetId}/searches/${id}/cancel`,
+      "POST"
+    );
+  }
+};
+
+// src/websets/webhooks.ts
+var WebsetWebhooksClient = class extends WebsetsBaseClient {
+  /**
+   * Create a Webhook
+   * @param params The webhook parameters
+   * @returns The created Webhook
+   */
+  async create(params) {
+    return this.request("/v0/webhooks", "POST", params);
+  }
+  /**
+   * Get a Webhook by ID
+   * @param id The ID of the Webhook
+   * @returns The Webhook
+   */
+  async get(id) {
+    return this.request(`/v0/webhooks/${id}`, "GET");
+  }
+  /**
+   * List all Webhooks
+   * @param options Pagination options
+   * @returns The list of Webhooks
+   */
+  async list(options) {
+    const params = this.buildPaginationParams(options);
+    return this.request(
+      "/v0/webhooks",
+      "GET",
+      void 0,
+      params
+    );
+  }
+  /**
+   * Iterate through all Webhooks, handling pagination automatically
+   * @param options Pagination options
+   * @returns Async generator of Webhooks
+   */
+  async *listAll(options) {
+    let cursor = void 0;
+    const pageOptions = options ? { ...options } : {};
+    while (true) {
+      pageOptions.cursor = cursor;
+      const response = await this.list(pageOptions);
+      for (const webhook of response.data) {
+        yield webhook;
+      }
+      if (!response.hasMore || !response.nextCursor) {
+        break;
+      }
+      cursor = response.nextCursor;
+    }
+  }
+  /**
+   * Collect all Webhooks into an array
+   * @param options Pagination options
+   * @returns Promise resolving to an array of all Webhooks
+   */
+  async getAll(options) {
+    const webhooks = [];
+    for await (const webhook of this.listAll(options)) {
+      webhooks.push(webhook);
+    }
+    return webhooks;
+  }
+  /**
+   * Update a Webhook
+   * @param id The ID of the Webhook
+   * @param params The webhook update parameters (events, metadata, url)
+   * @returns The updated Webhook
+   */
+  async update(id, params) {
+    return this.request(`/v0/webhooks/${id}`, "PATCH", params);
+  }
+  /**
+   * Delete a Webhook
+   * @param id The ID of the Webhook
+   * @returns The deleted Webhook
+   */
+  async delete(id) {
+    return this.request(`/v0/webhooks/${id}`, "DELETE");
+  }
+  /**
+   * List all attempts for a Webhook
+   * @param id The ID of the Webhook
+   * @param options Pagination and filtering options
+   * @returns The list of Webhook attempts
+   */
+  async listAttempts(id, options) {
+    const params = {
+      cursor: options?.cursor,
+      limit: options?.limit,
+      eventType: options?.eventType
+    };
+    return this.request(
+      `/v0/webhooks/${id}/attempts`,
+      "GET",
+      void 0,
+      params
+    );
+  }
+  /**
+   * Iterate through all attempts for a Webhook, handling pagination automatically
+   * @param id The ID of the Webhook
+   * @param options Pagination and filtering options
+   * @returns Async generator of Webhook attempts
+   */
+  async *listAllAttempts(id, options) {
+    let cursor = void 0;
+    const pageOptions = options ? { ...options } : {};
+    while (true) {
+      pageOptions.cursor = cursor;
+      const response = await this.listAttempts(id, pageOptions);
+      for (const attempt of response.data) {
+        yield attempt;
+      }
+      if (!response.hasMore || !response.nextCursor) {
+        break;
+      }
+      cursor = response.nextCursor;
+    }
+  }
+  /**
+   * Collect all attempts for a Webhook into an array
+   * @param id The ID of the Webhook
+   * @param options Pagination and filtering options
+   * @returns Promise resolving to an array of all Webhook attempts
+   */
+  async getAllAttempts(id, options) {
+    const attempts = [];
+    for await (const attempt of this.listAllAttempts(id, options)) {
+      attempts.push(attempt);
+    }
+    return attempts;
+  }
+};
+
+// src/websets/client.ts
+var WebsetsClient = class extends WebsetsBaseClient {
+  /**
+   * Initialize a new Websets client
+   * @param client The Exa client instance
+   */
+  constructor(client) {
+    super(client);
+    this.events = new EventsClient(client);
+    this.items = new WebsetItemsClient(client);
+    this.searches = new WebsetSearchesClient(client);
+    this.enrichments = new WebsetEnrichmentsClient(client);
+    this.webhooks = new WebsetWebhooksClient(client);
+  }
+  /**
+   * Create a new Webset
+   * @param params The Webset creation parameters
+   * @returns The created Webset
+   */
+  async create(params) {
+    return this.request("/v0/websets", "POST", params);
+  }
+  /**
+   * Get a Webset by ID
+   * @param id The ID of the Webset
+   * @param expand Optional array of relations to expand
+   * @returns The Webset
+   */
+  async get(id, expand) {
+    const params = {};
+    if (expand) {
+      params.expand = expand;
+    }
+    return this.request(
+      `/v0/websets/${id}`,
+      "GET",
+      void 0,
+      params
+    );
+  }
+  /**
+   * List all Websets
+   * @param options Pagination options (filtering by status is not supported by API)
+   * @returns The list of Websets
+   */
+  async list(options) {
+    const params = this.buildPaginationParams(options);
+    return this.request(
+      "/v0/websets",
+      "GET",
+      void 0,
+      params
+    );
+  }
+  /**
+   * Iterate through all Websets, handling pagination automatically
+   * @param options Pagination options
+   * @returns Async generator of Websets
+   */
+  async *listAll(options) {
+    let cursor = void 0;
+    const pageOptions = options ? { ...options } : {};
+    while (true) {
+      pageOptions.cursor = cursor;
+      const response = await this.list(pageOptions);
+      for (const webset of response.data) {
+        yield webset;
+      }
+      if (!response.hasMore || !response.nextCursor) {
+        break;
+      }
+      cursor = response.nextCursor;
+    }
+  }
+  /**
+   * Collect all Websets into an array
+   * @param options Pagination options
+   * @returns Promise resolving to an array of all Websets
+   */
+  async getAll(options) {
+    const websets = [];
+    for await (const webset of this.listAll(options)) {
+      websets.push(webset);
+    }
+    return websets;
+  }
+  /**
+   * Update a Webset
+   * @param id The ID of the Webset
+   * @param params The Webset update parameters
+   * @returns The updated Webset
+   */
+  async update(id, params) {
+    return this.request(`/v0/websets/${id}`, "POST", params);
+  }
+  /**
+   * Delete a Webset
+   * @param id The ID of the Webset
+   * @returns The deleted Webset
+   */
+  async delete(id) {
+    return this.request(`/v0/websets/${id}`, "DELETE");
+  }
+  /**
+   * Cancel a running Webset
+   * @param id The ID or external ID of the Webset
+   * @returns The canceled Webset (as returned by the API)
+   */
+  async cancel(id) {
+    return this.request(`/v0/websets/${id}/cancel`, "POST");
+  }
+  /**
+   * Wait until a Webset is idle
+   * @param id The ID of the Webset
+   * @param options Configuration options for timeout and polling
+   * @returns The Webset once it becomes idle
+   * @throws Error if the Webset does not become idle within the timeout
+   */
+  async waitUntilIdle(id, options) {
+    let timeout;
+    let pollInterval = 1e3;
+    let onPoll;
+    if (typeof options === "number") {
+      timeout = options;
+    } else if (options) {
+      timeout = options.timeout;
+      pollInterval = options.pollInterval || 1e3;
+      onPoll = options.onPoll;
+    }
+    const startTime = Date.now();
+    while (true) {
+      const webset = await this.get(id);
+      if (onPoll) {
+        onPoll(webset.status);
+      }
+      if (webset.status === "idle" /* idle */) {
+        return webset;
+      }
+      if (timeout && Date.now() - startTime > timeout) {
+        throw new ExaError(
+          `Webset ${id} did not reach idle state within ${timeout}ms. Current status: ${webset.status}`,
+          408 /* RequestTimeout */
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+  }
+};
+
+// 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 Exa = class {
+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.
    */
@@ -56,20 +718,14 @@ var Exa = 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 {
@@ -87,8 +743,9 @@ var Exa = class {
     if (!apiKey) {
       apiKey = process.env.EXASEARCH_API_KEY;
       if (!apiKey) {
-        throw new Error(
-          "API key must be provided as an argument or as an environment variable (EXASEARCH_API_KEY)"
+        throw new ExaError(
+          "API key must be provided as an argument or as an environment variable (EXASEARCH_API_KEY)",
+          401 /* Unauthorized */
         );
       }
     }
@@ -97,31 +754,61 @@ var Exa = class {
       "Content-Type": "application/json",
       "User-Agent": "exa-node 1.4.0"
     });
+    this.websets = new WebsetsClient(this);
   }
   /**
    * Makes a request to the Exa API.
    * @param {string} endpoint - The API endpoint to call.
    * @param {string} method - The HTTP method to use.
    * @param {any} [body] - The request body for POST requests.
+   * @param {Record<string, any>} [params] - The query parameters.
    * @returns {Promise<any>} The response from the API.
+   * @throws {ExaError} When any API request fails with structured error information
    */
-  async request(endpoint, method, body) {
-    const response = await fetchImpl(this.baseURL + endpoint, {
+  async request(endpoint, method, body, params) {
+    let url = this.baseURL + endpoint;
+    if (params && Object.keys(params).length > 0) {
+      const searchParams = new URLSearchParams();
+      for (const [key, value] of Object.entries(params)) {
+        if (Array.isArray(value)) {
+          for (const item of value) {
+            searchParams.append(key, item);
+          }
+        } else if (value !== void 0) {
+          searchParams.append(key, String(value));
+        }
+      }
+      url += `?${searchParams.toString()}`;
+    }
+    const response = await fetchImpl(url, {
       method,
       headers: this.headers,
       body: body ? JSON.stringify(body) : void 0
     });
     if (!response.ok) {
-      const message = (await response.json()).error;
-      throw new Error(
-        `Request failed with status ${response.status}. ${message}`
+      const errorData = await response.json();
+      if (!errorData.statusCode) {
+        errorData.statusCode = response.status;
+      }
+      if (!errorData.timestamp) {
+        errorData.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+      }
+      if (!errorData.path) {
+        errorData.path = endpoint;
+      }
+      const message = errorData.error || "Unknown error";
+      throw new ExaError(
+        message,
+        response.status,
+        errorData.timestamp,
+        errorData.path
       );
     }
     return await response.json();
   }
   /**
    * Performs a search with an Exa prompt-engineered query.
-   * 
+   *
    * @param {string} query - The query string.
    * @param {RegularSearchOptions} [options] - Additional search options
    * @returns {Promise<SearchResponse<{}>>} A list of relevant search results.
@@ -131,7 +818,7 @@ var Exa = class {
   }
   /**
    * Performs a search with an Exa prompt-engineered query and returns the contents of the documents.
-   * 
+   *
    * @param {string} query - The query string.
    * @param {RegularSearchOptions & T} [options] - Additional search + contents options
    * @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
@@ -175,7 +862,10 @@ var Exa = class {
    */
   async getContents(urls, options) {
     if (!urls || Array.isArray(urls) && urls.length === 0) {
-      throw new Error("Must provide at least one URL");
+      throw new ExaError(
+        "Must provide at least one URL",
+        400 /* BadRequest */
+      );
     }
     let requestUrls;
     if (typeof urls === "string") {
@@ -196,7 +886,7 @@ var Exa = class {
    * @param {string} query - The question or query to answer.
    * @param {AnswerOptions} [options] - Additional options for answer generation.
    * @returns {Promise<AnswerResponse>} The generated answer and source references.
-   * 
+   *
    * Example with systemPrompt:
    * ```ts
    * const answer = await exa.answer("What is quantum computing?", {
@@ -205,7 +895,7 @@ var Exa = class {
    *   systemPrompt: "Answer in a technical manner suitable for experts."
    * });
    * ```
-   * 
+   *
    * Note: For streaming responses, use the `streamAnswer` method:
    * ```ts
    * for await (const chunk of exa.streamAnswer(query)) {
@@ -215,8 +905,9 @@ var Exa = class {
    */
   async answer(query, options) {
     if (options?.stream) {
-      throw new Error(
-        "For streaming responses, please use streamAnswer() instead:\n\nfor await (const chunk of exa.streamAnswer(query)) {\n  // Handle chunks\n}"
+      throw new ExaError(
+        "For streaming responses, please use streamAnswer() instead:\n\nfor await (const chunk of exa.streamAnswer(query)) {\n  // Handle chunks\n}",
+        400 /* BadRequest */
       );
     }
     const requestBody = {
@@ -236,7 +927,7 @@ var Exa = class {
    *
    * Example usage:
    * ```ts
-   * for await (const chunk of exa.streamAnswer("What is quantum computing?", { 
+   * for await (const chunk of exa.streamAnswer("What is quantum computing?", {
    *   text: false,
    *   systemPrompt: "Answer in a concise manner suitable for beginners."
    * })) {
@@ -262,27 +953,27 @@ var Exa = class {
     });
     if (!response.ok) {
       const message = await response.text();
-      throw new Error(
-        `Request failed with status ${response.status}. ${message}`
-      );
+      throw new ExaError(message, response.status, (/* @__PURE__ */ new Date()).toISOString());
     }
     const reader = response.body?.getReader();
     if (!reader) {
-      throw new Error("No response body available for streaming.");
+      throw new ExaError(
+        "No response body available for streaming.",
+        500,
+        (/* @__PURE__ */ new Date()).toISOString()
+      );
     }
     const decoder = new TextDecoder();
     let buffer = "";
     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;
@@ -334,6 +1025,71 @@ var Exa = 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 = Exa;
+var index_default = Exa2;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CreateEnrichmentParametersFormat,
+  CreateWebsetSearchParametersBehaviour,
+  EventType,
+  Exa,
+  ExaError,
+  HttpStatusCode,
+  ResearchStatus,
+  WebhookStatus,
+  WebsetEnrichmentFormat,
+  WebsetEnrichmentStatus,
+  WebsetEnrichmentsClient,
+  WebsetItemEvaluationSatisfied,
+  WebsetItemSource,
+  WebsetItemsClient,
+  WebsetSearchCanceledReason,
+  WebsetSearchStatus,
+  WebsetSearchesClient,
+  WebsetStatus,
+  WebsetWebhooksClient,
+  WebsetsClient
+});
 //# sourceMappingURL=index.js.map