exa-js 2.17.0 → 2.18.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.js CHANGED
@@ -32,8 +32,14 @@ var index_exports = {};
32
32
  __export(index_exports, {
33
33
  AGENT_BETA_HEADER: () => AGENT_BETA_HEADER,
34
34
  AGENT_MAX_EFFORT_BETA: () => AGENT_MAX_EFFORT_BETA,
35
+ AGENT_MONITORS_BETA_HEADER: () => AGENT_MONITORS_BETA_HEADER,
35
36
  AgentBetaClient: () => AgentBetaClient,
36
37
  AgentClient: () => AgentClient,
38
+ AgentMonitorChangesClient: () => AgentMonitorChangesClient,
39
+ AgentMonitorEntitiesClient: () => AgentMonitorEntitiesClient,
40
+ AgentMonitorSnapshotFailedError: () => AgentMonitorSnapshotFailedError,
41
+ AgentMonitorSnapshotsClient: () => AgentMonitorSnapshotsClient,
42
+ AgentMonitorsClient: () => AgentMonitorsClient,
37
43
  AgentRunCancelledError: () => AgentRunCancelledError,
38
44
  AgentRunEventsClient: () => AgentRunEventsClient,
39
45
  AgentRunFailedError: () => AgentRunFailedError,
@@ -85,7 +91,7 @@ var import_cross_fetch = __toESM(require("cross-fetch"));
85
91
  // package.json
86
92
  var package_default = {
87
93
  name: "exa-js",
88
- version: "2.17.0",
94
+ version: "2.18.0",
89
95
  description: "Exa SDK for Node.js and the browser",
90
96
  publishConfig: {
91
97
  access: "public"
@@ -188,13 +194,20 @@ var ExaError = class extends Error {
188
194
  * @param statusCode HTTP status code
189
195
  * @param timestamp ISO timestamp from API
190
196
  * @param path Path that caused the error
197
+ * @param envelope Structured fields from the API's error envelope
191
198
  */
192
- constructor(message, statusCode, timestamp, path) {
199
+ constructor(message, statusCode, timestamp, path, envelope) {
193
200
  super(message);
194
201
  this.name = "ExaError";
195
202
  this.statusCode = statusCode;
196
203
  this.timestamp = timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
197
204
  this.path = path;
205
+ if (envelope) {
206
+ this.type = envelope.type;
207
+ this.code = envelope.code;
208
+ this.detail = envelope.detail;
209
+ this.requestId = envelope.requestId;
210
+ }
198
211
  }
199
212
  };
200
213
 
@@ -242,6 +255,314 @@ var AgentBaseClient = class {
242
255
  }
243
256
  };
244
257
 
258
+ // src/agent/betas.ts
259
+ function headersForBetas(betas) {
260
+ const betaValues = betas?.filter(Boolean);
261
+ if (!betaValues?.length) return void 0;
262
+ return { "Exa-Beta": betaValues.join(",") };
263
+ }
264
+
265
+ // src/agent/monitors/types.ts
266
+ var AGENT_MONITORS_BETA_HEADER = "agent-monitors-2026-08-04";
267
+
268
+ // src/agent/monitors/base.ts
269
+ var AgentMonitorsBaseClient = class {
270
+ constructor(client) {
271
+ this.client = client;
272
+ }
273
+ async request(endpoint, betas, method = "POST", data, params, headers) {
274
+ if (!betas?.includes(AGENT_MONITORS_BETA_HEADER)) {
275
+ throw new ExaError(
276
+ `betas must include the Agent Monitors beta identifier ("${AGENT_MONITORS_BETA_HEADER}")`,
277
+ 400 /* BadRequest */
278
+ );
279
+ }
280
+ return this.client.request(
281
+ `/agent/monitors${endpoint}`,
282
+ method,
283
+ data,
284
+ params,
285
+ {
286
+ ...headersForBetas(betas),
287
+ ...headers
288
+ }
289
+ );
290
+ }
291
+ buildPaginationParams(pagination) {
292
+ const params = {};
293
+ if (!pagination) return params;
294
+ if (pagination.cursor) params.cursor = pagination.cursor;
295
+ if (pagination.limit) params.limit = pagination.limit;
296
+ if ("since" in pagination && pagination.since)
297
+ params.since = pagination.since;
298
+ return params;
299
+ }
300
+ };
301
+
302
+ // src/agent/monitors/client.ts
303
+ var DEFAULT_SNAPSHOT_POLL_INTERVAL_MS = 2e3;
304
+ var DEFAULT_SNAPSHOT_POLL_TIMEOUT_MS = 60 * 60 * 1e3;
305
+ var AgentMonitorSnapshotFailedError = class extends Error {
306
+ constructor(snapshot) {
307
+ super(snapshot.error ?? `Agent monitor snapshot ${snapshot.id} failed`);
308
+ this.name = "AgentMonitorSnapshotFailedError";
309
+ this.snapshot = snapshot;
310
+ }
311
+ };
312
+ var AgentMonitorEntitiesClient = class extends AgentMonitorsBaseClient {
313
+ /**
314
+ * Add entities to an existing Agent Monitor. Added entities are resolved
315
+ * and backfilled shortly after the request completes, then update on the
316
+ * monitor's regular refresh cadence.
317
+ */
318
+ async add(monitorId, params) {
319
+ const { betas, ...payload } = params;
320
+ return this.request(
321
+ `/${monitorId}/entities`,
322
+ betas,
323
+ "POST",
324
+ payload
325
+ );
326
+ }
327
+ /**
328
+ * Page an Agent Monitor's current entities and contents, optionally
329
+ * filtered by update time.
330
+ */
331
+ async list(monitorId, options) {
332
+ const { betas, ...pagination } = options;
333
+ const params = this.buildPaginationParams(pagination);
334
+ return this.request(
335
+ `/${monitorId}/entities`,
336
+ betas,
337
+ "GET",
338
+ void 0,
339
+ params
340
+ );
341
+ }
342
+ /**
343
+ * Iterate through all of a monitor's entities, handling pagination
344
+ * automatically.
345
+ */
346
+ async *listAll(monitorId, options) {
347
+ let cursor = options.cursor;
348
+ const { betas, ...pagination } = options;
349
+ const pageOptions = { ...pagination };
350
+ while (true) {
351
+ pageOptions.cursor = cursor;
352
+ const response = await this.list(monitorId, { ...pageOptions, betas });
353
+ for (const entityView of response.data) {
354
+ yield entityView;
355
+ }
356
+ if (!response.hasMore || !response.nextCursor) {
357
+ break;
358
+ }
359
+ cursor = response.nextCursor;
360
+ }
361
+ }
362
+ /**
363
+ * Collect all of a monitor's entities into an array.
364
+ */
365
+ async getAll(monitorId, options) {
366
+ const entities = [];
367
+ for await (const entityView of this.listAll(monitorId, options)) {
368
+ entities.push(entityView);
369
+ }
370
+ return entities;
371
+ }
372
+ };
373
+ var AgentMonitorChangesClient = class extends AgentMonitorsBaseClient {
374
+ /**
375
+ * Page an Agent Monitor's content change feed since a cursor or timestamp.
376
+ */
377
+ async list(monitorId, options) {
378
+ const { betas, ...pagination } = options;
379
+ const params = this.buildPaginationParams(pagination);
380
+ return this.request(
381
+ `/${monitorId}/changes`,
382
+ betas,
383
+ "GET",
384
+ void 0,
385
+ params
386
+ );
387
+ }
388
+ /**
389
+ * Iterate through a monitor's change feed, handling pagination
390
+ * automatically.
391
+ */
392
+ async *listAll(monitorId, options) {
393
+ let cursor = options.cursor;
394
+ const { betas, ...pagination } = options;
395
+ const pageOptions = { ...pagination };
396
+ while (true) {
397
+ pageOptions.cursor = cursor;
398
+ const response = await this.list(monitorId, { ...pageOptions, betas });
399
+ for (const change of response.data) {
400
+ yield change;
401
+ }
402
+ if (!response.hasMore || !response.nextCursor) {
403
+ break;
404
+ }
405
+ cursor = response.nextCursor;
406
+ }
407
+ }
408
+ /**
409
+ * Collect a monitor's change feed into an array.
410
+ */
411
+ async getAll(monitorId, options) {
412
+ const changes = [];
413
+ for await (const change of this.listAll(monitorId, options)) {
414
+ changes.push(change);
415
+ }
416
+ return changes;
417
+ }
418
+ };
419
+ var AgentMonitorSnapshotsClient = class extends AgentMonitorsBaseClient {
420
+ /**
421
+ * Start an async, stateless snapshot of entities × fields over an explicit
422
+ * past news window — no monitor is created. Returns a `running` job; poll
423
+ * with `get` (or use `createAndWait`) for the result.
424
+ */
425
+ async create(params) {
426
+ const { betas, ...payload } = params;
427
+ return this.request(
428
+ "/snapshot",
429
+ betas,
430
+ "POST",
431
+ payload
432
+ );
433
+ }
434
+ /**
435
+ * Poll a snapshot job for its status and, once completed, its result.
436
+ * Jobs expire and read as 404 after `expiresAt`.
437
+ */
438
+ async get(snapshotId, options) {
439
+ return this.request(
440
+ `/snapshot/${snapshotId}`,
441
+ options.betas,
442
+ "GET"
443
+ );
444
+ }
445
+ /**
446
+ * Poll a snapshot job until it reaches a terminal status.
447
+ */
448
+ async pollUntilFinished(snapshotId, options) {
449
+ const pollInterval = options.pollInterval ?? DEFAULT_SNAPSHOT_POLL_INTERVAL_MS;
450
+ const timeoutMs = options.timeoutMs ?? DEFAULT_SNAPSHOT_POLL_TIMEOUT_MS;
451
+ const startTime = Date.now();
452
+ while (true) {
453
+ const snapshot = await this.get(snapshotId, { betas: options.betas });
454
+ if (snapshot.status !== "running") {
455
+ return snapshot;
456
+ }
457
+ if (Date.now() - startTime > timeoutMs) {
458
+ throw new Error(
459
+ `Polling timeout: Agent monitor snapshot ${snapshotId} did not complete within ${timeoutMs}ms`
460
+ );
461
+ }
462
+ await new Promise((resolve) => setTimeout(resolve, pollInterval));
463
+ }
464
+ }
465
+ /**
466
+ * Start a snapshot and wait for its result. Throws
467
+ * AgentMonitorSnapshotFailedError if the snapshot fails.
468
+ */
469
+ async createAndWait(params, options) {
470
+ const snapshot = await this.create(params);
471
+ const terminalSnapshot = snapshot.status === "running" ? await this.pollUntilFinished(snapshot.id, {
472
+ ...options,
473
+ betas: params.betas
474
+ }) : snapshot;
475
+ if (terminalSnapshot.status === "failed") {
476
+ throw new AgentMonitorSnapshotFailedError(terminalSnapshot);
477
+ }
478
+ return terminalSnapshot;
479
+ }
480
+ };
481
+ var AgentMonitorsClient = class extends AgentMonitorsBaseClient {
482
+ constructor(client) {
483
+ super(client);
484
+ this.entities = new AgentMonitorEntitiesClient(client);
485
+ this.changes = new AgentMonitorChangesClient(client);
486
+ this.snapshots = new AgentMonitorSnapshotsClient(client);
487
+ }
488
+ /**
489
+ * Create an Agent Monitor from its entities, fields, and cadence.
490
+ * Creation is async: the monitor is returned with status `creating` and
491
+ * becomes `active` once its first refresh completes.
492
+ */
493
+ async create(params, options) {
494
+ const { betas, ...payload } = params;
495
+ const headers = options?.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : void 0;
496
+ return this.request(
497
+ "",
498
+ betas,
499
+ "POST",
500
+ payload,
501
+ void 0,
502
+ headers
503
+ );
504
+ }
505
+ /**
506
+ * Get an Agent Monitor by ID, including refresh progress.
507
+ */
508
+ async get(monitorId, options) {
509
+ return this.request(`/${monitorId}`, options.betas, "GET");
510
+ }
511
+ /**
512
+ * List the team's Agent Monitors.
513
+ */
514
+ async list(options) {
515
+ const { betas, ...pagination } = options;
516
+ const params = this.buildPaginationParams(pagination);
517
+ return this.request(
518
+ "",
519
+ betas,
520
+ "GET",
521
+ void 0,
522
+ params
523
+ );
524
+ }
525
+ /**
526
+ * Iterate through all Agent Monitors, handling pagination automatically.
527
+ */
528
+ async *listAll(options) {
529
+ let cursor = options.cursor;
530
+ const { betas, ...pagination } = options;
531
+ const pageOptions = { ...pagination };
532
+ while (true) {
533
+ pageOptions.cursor = cursor;
534
+ const response = await this.list({ ...pageOptions, betas });
535
+ for (const monitor of response.data) {
536
+ yield monitor;
537
+ }
538
+ if (!response.hasMore || !response.nextCursor) {
539
+ break;
540
+ }
541
+ cursor = response.nextCursor;
542
+ }
543
+ }
544
+ /**
545
+ * Collect all Agent Monitors into an array.
546
+ */
547
+ async getAll(options) {
548
+ const monitors = [];
549
+ for await (const monitor of this.listAll(options)) {
550
+ monitors.push(monitor);
551
+ }
552
+ return monitors;
553
+ }
554
+ /**
555
+ * Delete an Agent Monitor and stop its refreshes.
556
+ */
557
+ async delete(monitorId, options) {
558
+ return this.request(
559
+ `/${monitorId}`,
560
+ options.betas,
561
+ "DELETE"
562
+ );
563
+ }
564
+ };
565
+
245
566
  // src/agent/client.ts
246
567
  var DEFAULT_AGENT_POLL_INTERVAL_MS = 1e3;
247
568
  var DEFAULT_AGENT_POLL_TIMEOUT_MS = 60 * 60 * 1e3;
@@ -265,11 +586,6 @@ var AgentRunCancelledError = class extends Error {
265
586
  this.run = run;
266
587
  }
267
588
  };
268
- function headersForBetas(betas) {
269
- const betaValues = betas?.filter(Boolean);
270
- if (!betaValues?.length) return void 0;
271
- return { "Exa-Beta": betaValues.join(",") };
272
- }
273
589
  function isTerminalAgentRunStatus(status) {
274
590
  return TERMINAL_AGENT_RUN_STATUSES.has(status);
275
591
  }
@@ -644,6 +960,7 @@ var AgentBetaClient = class extends AgentClient {
644
960
  const client = clientOrAgent instanceof AgentClient ? clientOrAgent.client : clientOrAgent;
645
961
  super(client);
646
962
  this.runs = new AgentBetaRunsClient(client);
963
+ this.monitors = new AgentMonitorsClient(client);
647
964
  }
648
965
  };
649
966
  var BetaClient = class {
@@ -2248,15 +2565,27 @@ var Exa2 = class {
2248
2565
  if (!errorData.path) {
2249
2566
  errorData.path = endpoint;
2250
2567
  }
2251
- let message = errorData.error || "Unknown error";
2252
- if (errorData.message) {
2253
- message += (message.length > 0 ? ". " : "") + errorData.message;
2568
+ const envelope = typeof errorData.error === "object" && errorData.error !== null ? errorData.error : void 0;
2569
+ let message;
2570
+ if (envelope) {
2571
+ message = envelope.message || errorData.message || "Unknown error";
2572
+ } else {
2573
+ message = errorData.error || "Unknown error";
2574
+ if (errorData.message) {
2575
+ message += (message.length > 0 ? ". " : "") + errorData.message;
2576
+ }
2254
2577
  }
2255
2578
  throw new ExaError(
2256
2579
  message,
2257
2580
  response.status,
2258
2581
  errorData.timestamp,
2259
- errorData.path
2582
+ errorData.path,
2583
+ envelope ? {
2584
+ type: envelope.type,
2585
+ code: envelope.code,
2586
+ detail: envelope.detail,
2587
+ requestId: errorData.requestId ?? envelope.requestId
2588
+ } : errorData.requestId ? { requestId: errorData.requestId } : void 0
2260
2589
  );
2261
2590
  }
2262
2591
  const contentType = response.headers.get("content-type") || "";
@@ -2622,8 +2951,14 @@ var index_default = Exa2;
2622
2951
  0 && (module.exports = {
2623
2952
  AGENT_BETA_HEADER,
2624
2953
  AGENT_MAX_EFFORT_BETA,
2954
+ AGENT_MONITORS_BETA_HEADER,
2625
2955
  AgentBetaClient,
2626
2956
  AgentClient,
2957
+ AgentMonitorChangesClient,
2958
+ AgentMonitorEntitiesClient,
2959
+ AgentMonitorSnapshotFailedError,
2960
+ AgentMonitorSnapshotsClient,
2961
+ AgentMonitorsClient,
2627
2962
  AgentRunCancelledError,
2628
2963
  AgentRunEventsClient,
2629
2964
  AgentRunFailedError,