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/README.md +71 -2
- package/dist/index.d.mts +442 -11
- package/dist/index.d.ts +442 -11
- package/dist/index.js +346 -11
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +340 -11
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
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.
|
|
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
|
-
|
|
2252
|
-
|
|
2253
|
-
|
|
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,
|