exa-js 2.13.0 → 2.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -4,7 +4,7 @@ import fetch2, { Headers } from "cross-fetch";
4
4
  // package.json
5
5
  var package_default = {
6
6
  name: "exa-js",
7
- version: "2.13.0",
7
+ version: "2.15.0",
8
8
  description: "Exa SDK for Node.js and the browser",
9
9
  publishConfig: {
10
10
  access: "public"
@@ -134,34 +134,22 @@ var AgentBaseClient = class {
134
134
  constructor(client) {
135
135
  this.client = client;
136
136
  }
137
- async request(endpoint, betas, method = "POST", data, params, headers) {
138
- if (!betas?.length) {
139
- throw new Error("betas must include the Agent API beta identifier");
140
- }
137
+ async request(endpoint, method = "POST", data, params, headers) {
141
138
  return this.client.request(
142
139
  `/agent/runs${endpoint}`,
143
140
  method,
144
141
  data,
145
142
  params,
146
- {
147
- "Exa-Beta": betas.join(","),
148
- ...headers
149
- }
143
+ headers
150
144
  );
151
145
  }
152
- async rawRequest(endpoint, betas, method = "POST", data, params, headers) {
153
- if (!betas?.length) {
154
- throw new Error("betas must include the Agent API beta identifier");
155
- }
146
+ async rawRequest(endpoint, method = "POST", data, params, headers) {
156
147
  return this.client.rawRequest(
157
148
  `/agent/runs${endpoint}`,
158
149
  method,
159
150
  data,
160
151
  params,
161
- {
162
- "Exa-Beta": betas.join(","),
163
- ...headers
164
- }
152
+ headers
165
153
  );
166
154
  }
167
155
  buildPaginationParams(pagination) {
@@ -174,6 +162,23 @@ var AgentBaseClient = class {
174
162
  };
175
163
 
176
164
  // src/agent/client.ts
165
+ function headersForBetas(betas) {
166
+ const betaValues = betas?.filter(Boolean);
167
+ if (!betaValues?.length) return void 0;
168
+ return { "Exa-Beta": betaValues.join(",") };
169
+ }
170
+ function buildAgentRunPayload(params) {
171
+ const { stream, outputSchema, ...rest } = params;
172
+ let schema = outputSchema;
173
+ if (schema && isZodSchema(schema)) {
174
+ schema = zodToJsonSchema(schema);
175
+ }
176
+ const payload = { ...rest };
177
+ if (schema) {
178
+ payload.outputSchema = schema;
179
+ }
180
+ return { stream, payload };
181
+ }
177
182
  async function* streamAgentEvents(response) {
178
183
  if (!response.body) {
179
184
  throw new Error("No response body for SSE stream");
@@ -235,7 +240,6 @@ var AgentRunEventsClient = class extends AgentBaseClient {
235
240
  const params = this.buildPaginationParams(options);
236
241
  return this.request(
237
242
  `/${runId}/events`,
238
- options.betas,
239
243
  "GET",
240
244
  void 0,
241
245
  params
@@ -248,26 +252,11 @@ var AgentRunsClient = class extends AgentBaseClient {
248
252
  this.events = new AgentRunEventsClient(client);
249
253
  }
250
254
  async create(params) {
251
- const { stream, outputSchema, betas, ...rest } = params;
252
- let schema = outputSchema;
253
- if (schema && isZodSchema(schema)) {
254
- schema = zodToJsonSchema(schema);
255
- }
256
- const payload = { ...rest };
257
- if (schema) {
258
- payload.outputSchema = schema;
259
- }
255
+ const { stream, payload } = buildAgentRunPayload(params);
260
256
  if (stream) {
261
- const response = await this.rawRequest(
262
- "",
263
- betas,
264
- "POST",
265
- payload,
266
- void 0,
267
- {
268
- Accept: "text/event-stream"
269
- }
270
- );
257
+ const response = await this.rawRequest("", "POST", payload, void 0, {
258
+ Accept: "text/event-stream"
259
+ });
271
260
  if (!response.ok) {
272
261
  const message = await response.text();
273
262
  throw new ExaError(
@@ -279,33 +268,27 @@ var AgentRunsClient = class extends AgentBaseClient {
279
268
  }
280
269
  return streamAgentEvents(response);
281
270
  }
282
- return this.request("", betas, "POST", payload);
271
+ return this.request("", "POST", payload);
283
272
  }
284
273
  /**
285
274
  * Get an Agent run by ID.
286
275
  */
287
- async get(runId, options) {
288
- return this.request(`/${runId}`, options.betas, "GET");
276
+ async get(runId) {
277
+ return this.request(`/${runId}`, "GET");
289
278
  }
290
279
  /**
291
280
  * List Agent runs.
292
281
  */
293
282
  async list(options) {
294
283
  const params = this.buildPaginationParams(options);
295
- return this.request(
296
- "",
297
- options.betas,
298
- "GET",
299
- void 0,
300
- params
301
- );
284
+ return this.request("", "GET", void 0, params);
302
285
  }
303
286
  /**
304
287
  * Iterate through all Agent runs, handling pagination automatically.
305
288
  */
306
289
  async *listAll(options) {
307
290
  let cursor = void 0;
308
- const pageOptions = { ...options };
291
+ const pageOptions = options ? { ...options } : {};
309
292
  while (true) {
310
293
  pageOptions.cursor = cursor;
311
294
  const response = await this.list(pageOptions);
@@ -331,14 +314,14 @@ var AgentRunsClient = class extends AgentBaseClient {
331
314
  /**
332
315
  * Cancel a queued or running Agent run.
333
316
  */
334
- async cancel(runId, options) {
335
- return this.request(`/${runId}/cancel`, options.betas, "POST");
317
+ async cancel(runId) {
318
+ return this.request(`/${runId}/cancel`, "POST");
336
319
  }
337
320
  /**
338
321
  * Delete a stored Agent run.
339
322
  */
340
- async delete(runId, options) {
341
- return this.request(`/${runId}`, options.betas, "DELETE");
323
+ async delete(runId) {
324
+ return this.request(`/${runId}`, "DELETE");
342
325
  }
343
326
  /**
344
327
  * Poll an Agent run until it reaches a terminal status.
@@ -348,7 +331,7 @@ var AgentRunsClient = class extends AgentBaseClient {
348
331
  const timeoutMs = options?.timeoutMs ?? 60 * 60 * 1e3;
349
332
  const startTime = Date.now();
350
333
  while (true) {
351
- const run = await this.get(runId, { betas: options.betas });
334
+ const run = await this.get(runId);
352
335
  if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
353
336
  return run;
354
337
  }
@@ -361,14 +344,161 @@ var AgentRunsClient = class extends AgentBaseClient {
361
344
  }
362
345
  }
363
346
  };
364
- var AgentBetaClient = class {
347
+ var AgentClient = class {
365
348
  constructor(client) {
349
+ this.client = client;
366
350
  this.runs = new AgentRunsClient(client);
367
351
  }
368
352
  };
369
- var BetaClient = class {
353
+ var AgentBetaRunEventsClient = class extends AgentRunEventsClient {
354
+ /**
355
+ * List stored events for an Agent run.
356
+ *
357
+ * @deprecated Use exa.agent.runs.events instead.
358
+ */
359
+ async list(runId, options) {
360
+ const { betas, ...pagination } = options ?? {};
361
+ const params = this.buildPaginationParams(pagination);
362
+ return this.request(
363
+ `/${runId}/events`,
364
+ "GET",
365
+ void 0,
366
+ params,
367
+ headersForBetas(betas)
368
+ );
369
+ }
370
+ };
371
+ var AgentBetaRunsClient = class extends AgentRunsClient {
370
372
  constructor(client) {
371
- this.agent = new AgentBetaClient(client);
373
+ super(client);
374
+ this.events = new AgentBetaRunEventsClient(client);
375
+ }
376
+ async create(params) {
377
+ const { betas, ...createParams } = params;
378
+ const { stream, payload } = buildAgentRunPayload(
379
+ createParams
380
+ );
381
+ const headers = headersForBetas(betas);
382
+ if (stream) {
383
+ const response = await this.rawRequest("", "POST", payload, void 0, {
384
+ ...headers,
385
+ Accept: "text/event-stream"
386
+ });
387
+ if (!response.ok) {
388
+ const message = await response.text();
389
+ throw new ExaError(
390
+ message || `Request failed with status code ${response.status}`,
391
+ response.status,
392
+ (/* @__PURE__ */ new Date()).toISOString(),
393
+ "/agent/runs"
394
+ );
395
+ }
396
+ return streamAgentEvents(response);
397
+ }
398
+ return this.request(
399
+ "",
400
+ "POST",
401
+ payload,
402
+ void 0,
403
+ headers
404
+ );
405
+ }
406
+ async get(runId, options) {
407
+ return this.request(
408
+ `/${runId}`,
409
+ "GET",
410
+ void 0,
411
+ void 0,
412
+ headersForBetas(options?.betas)
413
+ );
414
+ }
415
+ async list(options) {
416
+ const { betas, ...pagination } = options ?? {};
417
+ const params = this.buildPaginationParams(pagination);
418
+ return this.request(
419
+ "",
420
+ "GET",
421
+ void 0,
422
+ params,
423
+ headersForBetas(betas)
424
+ );
425
+ }
426
+ async *listAll(options) {
427
+ let cursor = void 0;
428
+ const { betas, ...pagination } = options ?? {};
429
+ const pageOptions = { ...pagination };
430
+ while (true) {
431
+ pageOptions.cursor = cursor;
432
+ const response = await this.list({ ...pageOptions, betas });
433
+ for (const run of response.data) {
434
+ yield run;
435
+ }
436
+ if (!response.hasMore || !response.nextCursor) {
437
+ break;
438
+ }
439
+ cursor = response.nextCursor;
440
+ }
441
+ }
442
+ async getAll(options) {
443
+ const runs = [];
444
+ for await (const run of this.listAll(options)) {
445
+ runs.push(run);
446
+ }
447
+ return runs;
448
+ }
449
+ async cancel(runId, options) {
450
+ return this.request(
451
+ `/${runId}/cancel`,
452
+ "POST",
453
+ void 0,
454
+ void 0,
455
+ headersForBetas(options?.betas)
456
+ );
457
+ }
458
+ async delete(runId, options) {
459
+ return this.request(
460
+ `/${runId}`,
461
+ "DELETE",
462
+ void 0,
463
+ void 0,
464
+ headersForBetas(options?.betas)
465
+ );
466
+ }
467
+ async pollUntilFinished(runId, options) {
468
+ const pollInterval = options?.pollInterval ?? 1e3;
469
+ const timeoutMs = options?.timeoutMs ?? 60 * 60 * 1e3;
470
+ const startTime = Date.now();
471
+ const headers = headersForBetas(options?.betas);
472
+ while (true) {
473
+ const run = await this.request(
474
+ `/${runId}`,
475
+ "GET",
476
+ void 0,
477
+ void 0,
478
+ headers
479
+ );
480
+ if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
481
+ return run;
482
+ }
483
+ if (Date.now() - startTime > timeoutMs) {
484
+ throw new Error(
485
+ `Polling timeout: Agent run ${runId} did not complete within ${timeoutMs}ms`
486
+ );
487
+ }
488
+ await new Promise((resolve) => setTimeout(resolve, pollInterval));
489
+ }
490
+ }
491
+ };
492
+ var AgentBetaClient = class extends AgentClient {
493
+ constructor(clientOrAgent) {
494
+ const client = clientOrAgent instanceof AgentClient ? clientOrAgent.client : clientOrAgent;
495
+ super(client);
496
+ this.runs = new AgentBetaRunsClient(client);
497
+ }
498
+ };
499
+ var BetaClient = class {
500
+ constructor(clientOrAgent) {
501
+ this.agent = new AgentBetaClient(clientOrAgent);
372
502
  }
373
503
  };
374
504
 
@@ -1797,6 +1927,22 @@ var AGENT_BETA_HEADER = "agent-2026-05-07";
1797
1927
  var fetchImpl = typeof global !== "undefined" && global.fetch ? global.fetch : fetch2;
1798
1928
  var HeadersImpl = typeof global !== "undefined" && global.Headers ? global.Headers : Headers;
1799
1929
  var DEFAULT_MAX_CHARACTERS = 1e4;
1930
+ var NON_JSON_BODY_SNIPPET_LENGTH = 500;
1931
+ async function readResponseBody(response) {
1932
+ const text = await response.text();
1933
+ if (!text) {
1934
+ return { json: void 0, text };
1935
+ }
1936
+ try {
1937
+ return { json: JSON.parse(text), text };
1938
+ } catch {
1939
+ return { json: void 0, text };
1940
+ }
1941
+ }
1942
+ function truncateResponseBody(text) {
1943
+ const collapsed = text.replace(/\s+/g, " ").trim();
1944
+ return collapsed.length > NON_JSON_BODY_SNIPPET_LENGTH ? `${collapsed.slice(0, NON_JSON_BODY_SNIPPET_LENGTH)}\u2026` : collapsed;
1945
+ }
1800
1946
  var Exa2 = class {
1801
1947
  /**
1802
1948
  * Helper method to separate out the contents-specific options from the rest.
@@ -1886,7 +2032,8 @@ var Exa2 = class {
1886
2032
  this.websets = new WebsetsClient(this);
1887
2033
  this.research = new ResearchClient(this);
1888
2034
  this.monitors = new SearchMonitorsClient(this);
1889
- this.beta = new BetaClient(this);
2035
+ this.agent = new AgentClient(this);
2036
+ this.beta = new BetaClient(this.agent);
1890
2037
  }
1891
2038
  /**
1892
2039
  * Makes a request to the Exa API.
@@ -1929,7 +2076,18 @@ var Exa2 = class {
1929
2076
  body: body ? JSON.stringify(body) : void 0
1930
2077
  });
1931
2078
  if (!response.ok) {
1932
- const errorData = await response.json();
2079
+ const { json: json2, text: text2 } = await readResponseBody(response);
2080
+ if (!json2 || typeof json2 !== "object") {
2081
+ const snippet = truncateResponseBody(text2);
2082
+ const message2 = snippet ? `Request failed with status ${response.status}. Response body was not valid JSON: ${snippet}` : `Request failed with status ${response.status}.`;
2083
+ throw new ExaError(
2084
+ message2,
2085
+ response.status,
2086
+ (/* @__PURE__ */ new Date()).toISOString(),
2087
+ endpoint
2088
+ );
2089
+ }
2090
+ const errorData = json2;
1933
2091
  if (!errorData.statusCode) {
1934
2092
  errorData.statusCode = response.status;
1935
2093
  }
@@ -1954,7 +2112,16 @@ var Exa2 = class {
1954
2112
  if (contentType.includes("text/event-stream")) {
1955
2113
  return await this.parseSSEStream(response);
1956
2114
  }
1957
- return await response.json();
2115
+ const { json, text } = await readResponseBody(response);
2116
+ if (json === void 0 && text) {
2117
+ throw new ExaError(
2118
+ `Expected a JSON response but received a non-JSON body (status ${response.status}): ${truncateResponseBody(text)}`,
2119
+ response.status,
2120
+ (/* @__PURE__ */ new Date()).toISOString(),
2121
+ endpoint
2122
+ );
2123
+ }
2124
+ return json;
1958
2125
  }
1959
2126
  async rawRequest(endpoint, method = "POST", body, queryParams, headers) {
1960
2127
  let url = this.baseURL + endpoint;
@@ -2303,6 +2470,7 @@ var index_default = Exa2;
2303
2470
  export {
2304
2471
  AGENT_BETA_HEADER,
2305
2472
  AgentBetaClient,
2473
+ AgentClient,
2306
2474
  AgentRunEventsClient,
2307
2475
  AgentRunsClient,
2308
2476
  BetaClient,