exa-js 2.16.3 → 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 +83 -1
- package/dist/index.d.mts +454 -12
- package/dist/index.d.ts +454 -12
- package/dist/index.js +349 -11
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +342 -11
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/dist/index.js
CHANGED
|
@@ -31,8 +31,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
|
|
|
31
31
|
var index_exports = {};
|
|
32
32
|
__export(index_exports, {
|
|
33
33
|
AGENT_BETA_HEADER: () => AGENT_BETA_HEADER,
|
|
34
|
+
AGENT_MAX_EFFORT_BETA: () => AGENT_MAX_EFFORT_BETA,
|
|
35
|
+
AGENT_MONITORS_BETA_HEADER: () => AGENT_MONITORS_BETA_HEADER,
|
|
34
36
|
AgentBetaClient: () => AgentBetaClient,
|
|
35
37
|
AgentClient: () => AgentClient,
|
|
38
|
+
AgentMonitorChangesClient: () => AgentMonitorChangesClient,
|
|
39
|
+
AgentMonitorEntitiesClient: () => AgentMonitorEntitiesClient,
|
|
40
|
+
AgentMonitorSnapshotFailedError: () => AgentMonitorSnapshotFailedError,
|
|
41
|
+
AgentMonitorSnapshotsClient: () => AgentMonitorSnapshotsClient,
|
|
42
|
+
AgentMonitorsClient: () => AgentMonitorsClient,
|
|
36
43
|
AgentRunCancelledError: () => AgentRunCancelledError,
|
|
37
44
|
AgentRunEventsClient: () => AgentRunEventsClient,
|
|
38
45
|
AgentRunFailedError: () => AgentRunFailedError,
|
|
@@ -84,7 +91,7 @@ var import_cross_fetch = __toESM(require("cross-fetch"));
|
|
|
84
91
|
// package.json
|
|
85
92
|
var package_default = {
|
|
86
93
|
name: "exa-js",
|
|
87
|
-
version: "2.
|
|
94
|
+
version: "2.18.0",
|
|
88
95
|
description: "Exa SDK for Node.js and the browser",
|
|
89
96
|
publishConfig: {
|
|
90
97
|
access: "public"
|
|
@@ -187,13 +194,20 @@ var ExaError = class extends Error {
|
|
|
187
194
|
* @param statusCode HTTP status code
|
|
188
195
|
* @param timestamp ISO timestamp from API
|
|
189
196
|
* @param path Path that caused the error
|
|
197
|
+
* @param envelope Structured fields from the API's error envelope
|
|
190
198
|
*/
|
|
191
|
-
constructor(message, statusCode, timestamp, path) {
|
|
199
|
+
constructor(message, statusCode, timestamp, path, envelope) {
|
|
192
200
|
super(message);
|
|
193
201
|
this.name = "ExaError";
|
|
194
202
|
this.statusCode = statusCode;
|
|
195
203
|
this.timestamp = timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
|
|
196
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
|
+
}
|
|
197
211
|
}
|
|
198
212
|
};
|
|
199
213
|
|
|
@@ -241,6 +255,314 @@ var AgentBaseClient = class {
|
|
|
241
255
|
}
|
|
242
256
|
};
|
|
243
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
|
+
|
|
244
566
|
// src/agent/client.ts
|
|
245
567
|
var DEFAULT_AGENT_POLL_INTERVAL_MS = 1e3;
|
|
246
568
|
var DEFAULT_AGENT_POLL_TIMEOUT_MS = 60 * 60 * 1e3;
|
|
@@ -264,11 +586,6 @@ var AgentRunCancelledError = class extends Error {
|
|
|
264
586
|
this.run = run;
|
|
265
587
|
}
|
|
266
588
|
};
|
|
267
|
-
function headersForBetas(betas) {
|
|
268
|
-
const betaValues = betas?.filter(Boolean);
|
|
269
|
-
if (!betaValues?.length) return void 0;
|
|
270
|
-
return { "Exa-Beta": betaValues.join(",") };
|
|
271
|
-
}
|
|
272
589
|
function isTerminalAgentRunStatus(status) {
|
|
273
590
|
return TERMINAL_AGENT_RUN_STATUSES.has(status);
|
|
274
591
|
}
|
|
@@ -643,6 +960,7 @@ var AgentBetaClient = class extends AgentClient {
|
|
|
643
960
|
const client = clientOrAgent instanceof AgentClient ? clientOrAgent.client : clientOrAgent;
|
|
644
961
|
super(client);
|
|
645
962
|
this.runs = new AgentBetaRunsClient(client);
|
|
963
|
+
this.monitors = new AgentMonitorsClient(client);
|
|
646
964
|
}
|
|
647
965
|
};
|
|
648
966
|
var BetaClient = class {
|
|
@@ -2071,6 +2389,7 @@ var WebsetsClient = class extends WebsetsBaseClient {
|
|
|
2071
2389
|
|
|
2072
2390
|
// src/agent/types.ts
|
|
2073
2391
|
var AGENT_BETA_HEADER = "agent-2026-05-07";
|
|
2392
|
+
var AGENT_MAX_EFFORT_BETA = "agent-max-effort-2026-07-27";
|
|
2074
2393
|
|
|
2075
2394
|
// src/index.ts
|
|
2076
2395
|
var fetchImpl = typeof global !== "undefined" && global.fetch ? global.fetch : import_cross_fetch.default;
|
|
@@ -2246,15 +2565,27 @@ var Exa2 = class {
|
|
|
2246
2565
|
if (!errorData.path) {
|
|
2247
2566
|
errorData.path = endpoint;
|
|
2248
2567
|
}
|
|
2249
|
-
|
|
2250
|
-
|
|
2251
|
-
|
|
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
|
+
}
|
|
2252
2577
|
}
|
|
2253
2578
|
throw new ExaError(
|
|
2254
2579
|
message,
|
|
2255
2580
|
response.status,
|
|
2256
2581
|
errorData.timestamp,
|
|
2257
|
-
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
|
|
2258
2589
|
);
|
|
2259
2590
|
}
|
|
2260
2591
|
const contentType = response.headers.get("content-type") || "";
|
|
@@ -2619,8 +2950,15 @@ var index_default = Exa2;
|
|
|
2619
2950
|
// Annotate the CommonJS export names for ESM import in node:
|
|
2620
2951
|
0 && (module.exports = {
|
|
2621
2952
|
AGENT_BETA_HEADER,
|
|
2953
|
+
AGENT_MAX_EFFORT_BETA,
|
|
2954
|
+
AGENT_MONITORS_BETA_HEADER,
|
|
2622
2955
|
AgentBetaClient,
|
|
2623
2956
|
AgentClient,
|
|
2957
|
+
AgentMonitorChangesClient,
|
|
2958
|
+
AgentMonitorEntitiesClient,
|
|
2959
|
+
AgentMonitorSnapshotFailedError,
|
|
2960
|
+
AgentMonitorSnapshotsClient,
|
|
2961
|
+
AgentMonitorsClient,
|
|
2624
2962
|
AgentRunCancelledError,
|
|
2625
2963
|
AgentRunEventsClient,
|
|
2626
2964
|
AgentRunFailedError,
|