exa-js 2.17.0 → 2.18.1

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.17.0",
7
+ version: "2.18.1",
8
8
  description: "Exa SDK for Node.js and the browser",
9
9
  publishConfig: {
10
10
  access: "public"
@@ -107,13 +107,20 @@ var ExaError = class extends Error {
107
107
  * @param statusCode HTTP status code
108
108
  * @param timestamp ISO timestamp from API
109
109
  * @param path Path that caused the error
110
+ * @param envelope Structured fields from the API's error envelope
110
111
  */
111
- constructor(message, statusCode, timestamp, path) {
112
+ constructor(message, statusCode, timestamp, path, envelope) {
112
113
  super(message);
113
114
  this.name = "ExaError";
114
115
  this.statusCode = statusCode;
115
116
  this.timestamp = timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
116
117
  this.path = path;
118
+ if (envelope) {
119
+ this.type = envelope.type;
120
+ this.code = envelope.code;
121
+ this.detail = envelope.detail;
122
+ this.requestId = envelope.requestId;
123
+ }
117
124
  }
118
125
  };
119
126
 
@@ -161,6 +168,314 @@ var AgentBaseClient = class {
161
168
  }
162
169
  };
163
170
 
171
+ // src/agent/betas.ts
172
+ function headersForBetas(betas) {
173
+ const betaValues = betas?.filter(Boolean);
174
+ if (!betaValues?.length) return void 0;
175
+ return { "Exa-Beta": betaValues.join(",") };
176
+ }
177
+
178
+ // src/agent/monitors/types.ts
179
+ var AGENT_MONITORS_BETA_HEADER = "agent-monitors-2026-08-04";
180
+
181
+ // src/agent/monitors/base.ts
182
+ var AgentMonitorsBaseClient = class {
183
+ constructor(client) {
184
+ this.client = client;
185
+ }
186
+ async request(endpoint, betas, method = "POST", data, params, headers) {
187
+ if (!betas?.includes(AGENT_MONITORS_BETA_HEADER)) {
188
+ throw new ExaError(
189
+ `betas must include the Agent Monitors beta identifier ("${AGENT_MONITORS_BETA_HEADER}")`,
190
+ 400 /* BadRequest */
191
+ );
192
+ }
193
+ return this.client.request(
194
+ `/agent/monitors${endpoint}`,
195
+ method,
196
+ data,
197
+ params,
198
+ {
199
+ ...headersForBetas(betas),
200
+ ...headers
201
+ }
202
+ );
203
+ }
204
+ buildPaginationParams(pagination) {
205
+ const params = {};
206
+ if (!pagination) return params;
207
+ if (pagination.cursor) params.cursor = pagination.cursor;
208
+ if (pagination.limit) params.limit = pagination.limit;
209
+ if ("since" in pagination && pagination.since)
210
+ params.since = pagination.since;
211
+ return params;
212
+ }
213
+ };
214
+
215
+ // src/agent/monitors/client.ts
216
+ var DEFAULT_SNAPSHOT_POLL_INTERVAL_MS = 2e3;
217
+ var DEFAULT_SNAPSHOT_POLL_TIMEOUT_MS = 60 * 60 * 1e3;
218
+ var AgentMonitorSnapshotFailedError = class extends Error {
219
+ constructor(snapshot) {
220
+ super(snapshot.error ?? `Agent monitor snapshot ${snapshot.id} failed`);
221
+ this.name = "AgentMonitorSnapshotFailedError";
222
+ this.snapshot = snapshot;
223
+ }
224
+ };
225
+ var AgentMonitorEntitiesClient = class extends AgentMonitorsBaseClient {
226
+ /**
227
+ * Add entities to an existing Agent Monitor. Added entities are resolved
228
+ * and backfilled shortly after the request completes, then update on the
229
+ * monitor's regular refresh cadence.
230
+ */
231
+ async add(monitorId, params) {
232
+ const { betas, ...payload } = params;
233
+ return this.request(
234
+ `/${monitorId}/entities`,
235
+ betas,
236
+ "POST",
237
+ payload
238
+ );
239
+ }
240
+ /**
241
+ * Page an Agent Monitor's current entities and contents, optionally
242
+ * filtered by update time.
243
+ */
244
+ async list(monitorId, options) {
245
+ const { betas, ...pagination } = options;
246
+ const params = this.buildPaginationParams(pagination);
247
+ return this.request(
248
+ `/${monitorId}/entities`,
249
+ betas,
250
+ "GET",
251
+ void 0,
252
+ params
253
+ );
254
+ }
255
+ /**
256
+ * Iterate through all of a monitor's entities, handling pagination
257
+ * automatically.
258
+ */
259
+ async *listAll(monitorId, options) {
260
+ let cursor = options.cursor;
261
+ const { betas, ...pagination } = options;
262
+ const pageOptions = { ...pagination };
263
+ while (true) {
264
+ pageOptions.cursor = cursor;
265
+ const response = await this.list(monitorId, { ...pageOptions, betas });
266
+ for (const entityView of response.data) {
267
+ yield entityView;
268
+ }
269
+ if (!response.hasMore || !response.nextCursor) {
270
+ break;
271
+ }
272
+ cursor = response.nextCursor;
273
+ }
274
+ }
275
+ /**
276
+ * Collect all of a monitor's entities into an array.
277
+ */
278
+ async getAll(monitorId, options) {
279
+ const entities = [];
280
+ for await (const entityView of this.listAll(monitorId, options)) {
281
+ entities.push(entityView);
282
+ }
283
+ return entities;
284
+ }
285
+ };
286
+ var AgentMonitorChangesClient = class extends AgentMonitorsBaseClient {
287
+ /**
288
+ * Page an Agent Monitor's content change feed since a cursor or timestamp.
289
+ */
290
+ async list(monitorId, options) {
291
+ const { betas, ...pagination } = options;
292
+ const params = this.buildPaginationParams(pagination);
293
+ return this.request(
294
+ `/${monitorId}/changes`,
295
+ betas,
296
+ "GET",
297
+ void 0,
298
+ params
299
+ );
300
+ }
301
+ /**
302
+ * Iterate through a monitor's change feed, handling pagination
303
+ * automatically.
304
+ */
305
+ async *listAll(monitorId, options) {
306
+ let cursor = options.cursor;
307
+ const { betas, ...pagination } = options;
308
+ const pageOptions = { ...pagination };
309
+ while (true) {
310
+ pageOptions.cursor = cursor;
311
+ const response = await this.list(monitorId, { ...pageOptions, betas });
312
+ for (const change of response.data) {
313
+ yield change;
314
+ }
315
+ if (!response.hasMore || !response.nextCursor) {
316
+ break;
317
+ }
318
+ cursor = response.nextCursor;
319
+ }
320
+ }
321
+ /**
322
+ * Collect a monitor's change feed into an array.
323
+ */
324
+ async getAll(monitorId, options) {
325
+ const changes = [];
326
+ for await (const change of this.listAll(monitorId, options)) {
327
+ changes.push(change);
328
+ }
329
+ return changes;
330
+ }
331
+ };
332
+ var AgentMonitorSnapshotsClient = class extends AgentMonitorsBaseClient {
333
+ /**
334
+ * Start an async, stateless snapshot of entities × fields over an explicit
335
+ * past news window — no monitor is created. Returns a `running` job; poll
336
+ * with `get` (or use `createAndWait`) for the result.
337
+ */
338
+ async create(params) {
339
+ const { betas, ...payload } = params;
340
+ return this.request(
341
+ "/snapshot",
342
+ betas,
343
+ "POST",
344
+ payload
345
+ );
346
+ }
347
+ /**
348
+ * Poll a snapshot job for its status and, once completed, its result.
349
+ * Jobs expire and read as 404 after `expiresAt`.
350
+ */
351
+ async get(snapshotId, options) {
352
+ return this.request(
353
+ `/snapshot/${snapshotId}`,
354
+ options.betas,
355
+ "GET"
356
+ );
357
+ }
358
+ /**
359
+ * Poll a snapshot job until it reaches a terminal status.
360
+ */
361
+ async pollUntilFinished(snapshotId, options) {
362
+ const pollInterval = options.pollInterval ?? DEFAULT_SNAPSHOT_POLL_INTERVAL_MS;
363
+ const timeoutMs = options.timeoutMs ?? DEFAULT_SNAPSHOT_POLL_TIMEOUT_MS;
364
+ const startTime = Date.now();
365
+ while (true) {
366
+ const snapshot = await this.get(snapshotId, { betas: options.betas });
367
+ if (snapshot.status !== "running") {
368
+ return snapshot;
369
+ }
370
+ if (Date.now() - startTime > timeoutMs) {
371
+ throw new Error(
372
+ `Polling timeout: Agent monitor snapshot ${snapshotId} did not complete within ${timeoutMs}ms`
373
+ );
374
+ }
375
+ await new Promise((resolve) => setTimeout(resolve, pollInterval));
376
+ }
377
+ }
378
+ /**
379
+ * Start a snapshot and wait for its result. Throws
380
+ * AgentMonitorSnapshotFailedError if the snapshot fails.
381
+ */
382
+ async createAndWait(params, options) {
383
+ const snapshot = await this.create(params);
384
+ const terminalSnapshot = snapshot.status === "running" ? await this.pollUntilFinished(snapshot.id, {
385
+ ...options,
386
+ betas: params.betas
387
+ }) : snapshot;
388
+ if (terminalSnapshot.status === "failed") {
389
+ throw new AgentMonitorSnapshotFailedError(terminalSnapshot);
390
+ }
391
+ return terminalSnapshot;
392
+ }
393
+ };
394
+ var AgentMonitorsClient = class extends AgentMonitorsBaseClient {
395
+ constructor(client) {
396
+ super(client);
397
+ this.entities = new AgentMonitorEntitiesClient(client);
398
+ this.changes = new AgentMonitorChangesClient(client);
399
+ this.snapshots = new AgentMonitorSnapshotsClient(client);
400
+ }
401
+ /**
402
+ * Create an Agent Monitor from its entities, fields, and cadence.
403
+ * Creation is async: the monitor is returned with status `creating` and
404
+ * becomes `active` once its first refresh completes.
405
+ */
406
+ async create(params, options) {
407
+ const { betas, ...payload } = params;
408
+ const headers = options?.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : void 0;
409
+ return this.request(
410
+ "",
411
+ betas,
412
+ "POST",
413
+ payload,
414
+ void 0,
415
+ headers
416
+ );
417
+ }
418
+ /**
419
+ * Get an Agent Monitor by ID, including refresh progress.
420
+ */
421
+ async get(monitorId, options) {
422
+ return this.request(`/${monitorId}`, options.betas, "GET");
423
+ }
424
+ /**
425
+ * List the team's Agent Monitors.
426
+ */
427
+ async list(options) {
428
+ const { betas, ...pagination } = options;
429
+ const params = this.buildPaginationParams(pagination);
430
+ return this.request(
431
+ "",
432
+ betas,
433
+ "GET",
434
+ void 0,
435
+ params
436
+ );
437
+ }
438
+ /**
439
+ * Iterate through all Agent Monitors, handling pagination automatically.
440
+ */
441
+ async *listAll(options) {
442
+ let cursor = options.cursor;
443
+ const { betas, ...pagination } = options;
444
+ const pageOptions = { ...pagination };
445
+ while (true) {
446
+ pageOptions.cursor = cursor;
447
+ const response = await this.list({ ...pageOptions, betas });
448
+ for (const monitor of response.data) {
449
+ yield monitor;
450
+ }
451
+ if (!response.hasMore || !response.nextCursor) {
452
+ break;
453
+ }
454
+ cursor = response.nextCursor;
455
+ }
456
+ }
457
+ /**
458
+ * Collect all Agent Monitors into an array.
459
+ */
460
+ async getAll(options) {
461
+ const monitors = [];
462
+ for await (const monitor of this.listAll(options)) {
463
+ monitors.push(monitor);
464
+ }
465
+ return monitors;
466
+ }
467
+ /**
468
+ * Delete an Agent Monitor and stop its refreshes.
469
+ */
470
+ async delete(monitorId, options) {
471
+ return this.request(
472
+ `/${monitorId}`,
473
+ options.betas,
474
+ "DELETE"
475
+ );
476
+ }
477
+ };
478
+
164
479
  // src/agent/client.ts
165
480
  var DEFAULT_AGENT_POLL_INTERVAL_MS = 1e3;
166
481
  var DEFAULT_AGENT_POLL_TIMEOUT_MS = 60 * 60 * 1e3;
@@ -184,11 +499,6 @@ var AgentRunCancelledError = class extends Error {
184
499
  this.run = run;
185
500
  }
186
501
  };
187
- function headersForBetas(betas) {
188
- const betaValues = betas?.filter(Boolean);
189
- if (!betaValues?.length) return void 0;
190
- return { "Exa-Beta": betaValues.join(",") };
191
- }
192
502
  function isTerminalAgentRunStatus(status) {
193
503
  return TERMINAL_AGENT_RUN_STATUSES.has(status);
194
504
  }
@@ -563,6 +873,7 @@ var AgentBetaClient = class extends AgentClient {
563
873
  const client = clientOrAgent instanceof AgentClient ? clientOrAgent.client : clientOrAgent;
564
874
  super(client);
565
875
  this.runs = new AgentBetaRunsClient(client);
876
+ this.monitors = new AgentMonitorsClient(client);
566
877
  }
567
878
  };
568
879
  var BetaClient = class {
@@ -2167,15 +2478,27 @@ var Exa2 = class {
2167
2478
  if (!errorData.path) {
2168
2479
  errorData.path = endpoint;
2169
2480
  }
2170
- let message = errorData.error || "Unknown error";
2171
- if (errorData.message) {
2172
- message += (message.length > 0 ? ". " : "") + errorData.message;
2481
+ const envelope = typeof errorData.error === "object" && errorData.error !== null ? errorData.error : void 0;
2482
+ let message;
2483
+ if (envelope) {
2484
+ message = envelope.message || errorData.message || "Unknown error";
2485
+ } else {
2486
+ message = errorData.error || "Unknown error";
2487
+ if (errorData.message) {
2488
+ message += (message.length > 0 ? ". " : "") + errorData.message;
2489
+ }
2173
2490
  }
2174
2491
  throw new ExaError(
2175
2492
  message,
2176
2493
  response.status,
2177
2494
  errorData.timestamp,
2178
- errorData.path
2495
+ errorData.path,
2496
+ envelope ? {
2497
+ type: envelope.type,
2498
+ code: envelope.code,
2499
+ detail: envelope.detail,
2500
+ requestId: errorData.requestId ?? envelope.requestId
2501
+ } : errorData.requestId ? { requestId: errorData.requestId } : void 0
2179
2502
  );
2180
2503
  }
2181
2504
  const contentType = response.headers.get("content-type") || "";
@@ -2540,8 +2863,14 @@ var index_default = Exa2;
2540
2863
  export {
2541
2864
  AGENT_BETA_HEADER,
2542
2865
  AGENT_MAX_EFFORT_BETA,
2866
+ AGENT_MONITORS_BETA_HEADER,
2543
2867
  AgentBetaClient,
2544
2868
  AgentClient,
2869
+ AgentMonitorChangesClient,
2870
+ AgentMonitorEntitiesClient,
2871
+ AgentMonitorSnapshotFailedError,
2872
+ AgentMonitorSnapshotsClient,
2873
+ AgentMonitorsClient,
2545
2874
  AgentRunCancelledError,
2546
2875
  AgentRunEventsClient,
2547
2876
  AgentRunFailedError,