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/README.md +71 -2
- package/dist/index.d.mts +457 -11
- package/dist/index.d.ts +457 -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.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.
|
|
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
|
-
|
|
2171
|
-
|
|
2172
|
-
|
|
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,
|