exa-js 2.18.0 → 2.19.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
@@ -44,9 +44,11 @@ __export(index_exports, {
44
44
  AgentRunEventsClient: () => AgentRunEventsClient,
45
45
  AgentRunFailedError: () => AgentRunFailedError,
46
46
  AgentRunsClient: () => AgentRunsClient,
47
+ AnthropicTools: () => AnthropicTools,
47
48
  BetaClient: () => BetaClient,
48
49
  CreateEnrichmentParametersFormat: () => CreateEnrichmentParametersFormat,
49
50
  CreateImportParametersFormat: () => CreateImportParametersFormat,
51
+ DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION: () => DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION,
50
52
  EventType: () => EventType,
51
53
  EventsClient: () => EventsClient,
52
54
  Exa: () => Exa2,
@@ -62,8 +64,11 @@ __export(index_exports, {
62
64
  MonitorRunStatus: () => MonitorRunStatus,
63
65
  MonitorRunType: () => MonitorRunType,
64
66
  MonitorStatus: () => MonitorStatus,
67
+ OpenAIResponsesTools: () => OpenAIResponsesTools,
68
+ OpenAITools: () => OpenAITools,
65
69
  SearchMonitorRunsClient: () => SearchMonitorRunsClient,
66
70
  SearchMonitorsClient: () => SearchMonitorsClient,
71
+ ToolRegistry: () => ToolRegistry,
67
72
  UpdateMonitorStatus: () => UpdateMonitorStatus,
68
73
  WebhookStatus: () => WebhookStatus,
69
74
  WebsetEnrichmentFormat: () => WebsetEnrichmentFormat,
@@ -83,6 +88,7 @@ __export(index_exports, {
83
88
  WebsetStatus: () => WebsetStatus,
84
89
  WebsetWebhooksClient: () => WebsetWebhooksClient,
85
90
  WebsetsClient: () => WebsetsClient,
91
+ createWebSearchTool: () => createWebSearchTool,
86
92
  default: () => index_default
87
93
  });
88
94
  module.exports = __toCommonJS(index_exports);
@@ -91,7 +97,7 @@ var import_cross_fetch = __toESM(require("cross-fetch"));
91
97
  // package.json
92
98
  var package_default = {
93
99
  name: "exa-js",
94
- version: "2.18.0",
100
+ version: "2.19.0",
95
101
  description: "Exa SDK for Node.js and the browser",
96
102
  publishConfig: {
97
103
  access: "public"
@@ -132,6 +138,7 @@ var package_default = {
132
138
  },
133
139
  license: "MIT",
134
140
  devDependencies: {
141
+ "@anthropic-ai/sdk": "^0.115.0",
135
142
  "@types/node": "~22.14.0",
136
143
  "cross-env": "~7.0.3",
137
144
  "openapi-typescript": "~7.6.1",
@@ -563,6 +570,10 @@ var AgentMonitorsClient = class extends AgentMonitorsBaseClient {
563
570
  }
564
571
  };
565
572
 
573
+ // src/agent/types.ts
574
+ var AGENT_BETA_HEADER = "agent-2026-05-07";
575
+ var AGENT_MAX_EFFORT_BETA = "agent-max-effort-2026-07-27";
576
+
566
577
  // src/agent/client.ts
567
578
  var DEFAULT_AGENT_POLL_INTERVAL_MS = 1e3;
568
579
  var DEFAULT_AGENT_POLL_TIMEOUT_MS = 60 * 60 * 1e3;
@@ -904,6 +915,19 @@ var AgentBetaRunsClient = class extends AgentRunsClient {
904
915
  headersForBetas(options?.betas)
905
916
  );
906
917
  }
918
+ /**
919
+ * Stop a running Agent run, completing it early with the results
920
+ * gathered so far. Only supported for `max` effort runs.
921
+ */
922
+ async stop(runId, options) {
923
+ return this.request(
924
+ `/${runId}/stop`,
925
+ "POST",
926
+ void 0,
927
+ void 0,
928
+ headersForBetas(options?.betas ?? [AGENT_MAX_EFFORT_BETA])
929
+ );
930
+ }
907
931
  async delete(runId, options) {
908
932
  return this.request(
909
933
  `/${runId}`,
@@ -2387,9 +2411,355 @@ var WebsetsClient = class extends WebsetsBaseClient {
2387
2411
  }
2388
2412
  };
2389
2413
 
2390
- // src/agent/types.ts
2391
- var AGENT_BETA_HEADER = "agent-2026-05-07";
2392
- var AGENT_MAX_EFFORT_BETA = "agent-max-effort-2026-07-27";
2414
+ // src/tools/core.ts
2415
+ var import_zod2 = require("zod");
2416
+ var DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
2417
+ function formatSearchResponse(response) {
2418
+ const formatted = response.results.map((result) => {
2419
+ const lines = [
2420
+ `Title: ${result.title || "N/A"}`,
2421
+ `URL: ${result.url || "N/A"}`,
2422
+ `Published: ${result.publishedDate || "N/A"}`,
2423
+ `Author: ${result.author || "N/A"}`
2424
+ ];
2425
+ if (result.highlights && result.highlights.length > 0) {
2426
+ lines.push(`Highlights:
2427
+ ${result.highlights.join("\n")}`);
2428
+ } else if (result.text) {
2429
+ lines.push(`Text: ${result.text}`);
2430
+ }
2431
+ return lines.join("\n");
2432
+ }).join("\n\n---\n\n");
2433
+ return formatted || "No search results found.";
2434
+ }
2435
+ function registerTool(registry, tool) {
2436
+ registry.register(tool);
2437
+ return tool;
2438
+ }
2439
+ function createTool(registry, params) {
2440
+ const tool = {
2441
+ name: params.name,
2442
+ description: params.description,
2443
+ inputSchema: params.inputSchema,
2444
+ jsonSchema: params.jsonSchema,
2445
+ execute: params.execute,
2446
+ format: params.format,
2447
+ definition: params.definition,
2448
+ async run(args) {
2449
+ try {
2450
+ const parsed = params.inputSchema.parse(args);
2451
+ const result = await params.execute(parsed);
2452
+ return params.format(result);
2453
+ } catch (error) {
2454
+ const message = error instanceof Error ? error.message : String(error);
2455
+ return `Error: ${message}`;
2456
+ }
2457
+ }
2458
+ };
2459
+ return registerTool(registry, tool);
2460
+ }
2461
+ function createWebSearchTool(exa, registry, config = {}) {
2462
+ const {
2463
+ name = "web_search",
2464
+ description = DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION,
2465
+ ...searchOptions
2466
+ } = config;
2467
+ const inputSchema = import_zod2.z.object({
2468
+ query: import_zod2.z.string().describe(
2469
+ "Natural language search query. Should be a semantically rich description of the ideal page, not just keywords."
2470
+ )
2471
+ });
2472
+ const jsonSchema = zodToJsonSchema(inputSchema);
2473
+ delete jsonSchema.$schema;
2474
+ return createTool(registry, {
2475
+ name,
2476
+ description,
2477
+ inputSchema,
2478
+ jsonSchema,
2479
+ definition: {
2480
+ name,
2481
+ description,
2482
+ parameters: jsonSchema
2483
+ },
2484
+ execute: ({ query }) => {
2485
+ const options = {
2486
+ type: "auto",
2487
+ numResults: 10,
2488
+ contents: { highlights: true },
2489
+ ...searchOptions
2490
+ };
2491
+ return exa.search(query, options);
2492
+ },
2493
+ format: formatSearchResponse
2494
+ });
2495
+ }
2496
+ var ToolRegistry = class {
2497
+ constructor() {
2498
+ this.registry = /* @__PURE__ */ new Map();
2499
+ }
2500
+ register(tool) {
2501
+ this.registry.set(tool.name, tool);
2502
+ }
2503
+ resolve(tools) {
2504
+ return tools ? new Map(tools.map((tool) => [tool.name, tool])) : new Map(this.registry);
2505
+ }
2506
+ };
2507
+ function getTool(tools, name) {
2508
+ return tools.get(name);
2509
+ }
2510
+ function unknownToolError(name) {
2511
+ return `Error: unknown tool "${name}"`;
2512
+ }
2513
+
2514
+ // src/tools/anthropic.ts
2515
+ var AnthropicTools = class {
2516
+ constructor(exa, registry) {
2517
+ this.exa = exa;
2518
+ this.registry = registry;
2519
+ }
2520
+ /** Anthropic `web_search` tool. Defaults to `auto` + highlights. */
2521
+ webSearch(config) {
2522
+ return runnable(createWebSearchTool(this.exa, this.registry, config));
2523
+ }
2524
+ /**
2525
+ * Run the `tool_use` blocks in an assistant message and return the matching
2526
+ * `tool_result` blocks. Every `tool_use` block is answered so the follow-up
2527
+ * request never omits a required result: a block whose name doesn't match a
2528
+ * known tool gets an `Error: unknown tool "<name>"` result. When handling
2529
+ * some tools yourself, replace those error results with your own before
2530
+ * sending the next request.
2531
+ */
2532
+ async handleToolUse(message, options) {
2533
+ const tools = this.registry.resolve(options?.tools);
2534
+ const blocks = (message.content ?? []).filter(isAnthropicToolUse);
2535
+ return Promise.all(
2536
+ blocks.map(async (block) => {
2537
+ const tool = getTool(tools, block.name);
2538
+ return {
2539
+ type: "tool_result",
2540
+ tool_use_id: block.id,
2541
+ content: tool ? await tool.run(block.input) : unknownToolError(block.name)
2542
+ };
2543
+ })
2544
+ );
2545
+ }
2546
+ };
2547
+ function isAnthropicToolUse(value) {
2548
+ if (!value || typeof value !== "object") return false;
2549
+ const block = value;
2550
+ return block.type === "tool_use" && typeof block.id === "string" && typeof block.name === "string";
2551
+ }
2552
+ function runnable(tool) {
2553
+ const definition = {
2554
+ type: "custom",
2555
+ name: tool.name,
2556
+ description: tool.description,
2557
+ input_schema: tool.jsonSchema,
2558
+ parse: (input) => tool.inputSchema.parse(input),
2559
+ run: (args) => tool.run(args)
2560
+ };
2561
+ Object.defineProperties(definition, {
2562
+ parse: { enumerable: false },
2563
+ run: { enumerable: false }
2564
+ });
2565
+ Object.defineProperties(
2566
+ definition,
2567
+ Object.fromEntries(
2568
+ Object.entries(tool).filter(([key]) => !["name", "description"].includes(key)).map(([key, value]) => [
2569
+ key,
2570
+ { value, enumerable: false, configurable: true }
2571
+ ])
2572
+ )
2573
+ );
2574
+ Object.defineProperty(definition, "type", {
2575
+ value: "custom",
2576
+ enumerable: false,
2577
+ configurable: true
2578
+ });
2579
+ Object.defineProperty(definition, "definition", {
2580
+ value: {
2581
+ name: tool.name,
2582
+ description: tool.description,
2583
+ input_schema: tool.jsonSchema
2584
+ },
2585
+ enumerable: false
2586
+ });
2587
+ return definition;
2588
+ }
2589
+
2590
+ // src/tools/openai.ts
2591
+ function runnable2(tool) {
2592
+ const functionDefinition = {
2593
+ ...tool.definition,
2594
+ parse: (input) => JSON.parse(input),
2595
+ function: (args) => tool.run(args)
2596
+ };
2597
+ Object.defineProperties(functionDefinition, {
2598
+ parse: { enumerable: false },
2599
+ function: { enumerable: false }
2600
+ });
2601
+ const definition = {
2602
+ type: "function",
2603
+ function: functionDefinition
2604
+ };
2605
+ Object.defineProperties(
2606
+ definition,
2607
+ Object.fromEntries(
2608
+ Object.entries(tool).filter(([key]) => !["name", "description"].includes(key)).map(([key, value]) => [
2609
+ key,
2610
+ { value, enumerable: false, configurable: true }
2611
+ ])
2612
+ )
2613
+ );
2614
+ Object.defineProperties(definition, {
2615
+ name: {
2616
+ value: tool.name,
2617
+ enumerable: false,
2618
+ configurable: true
2619
+ },
2620
+ description: {
2621
+ value: tool.description,
2622
+ enumerable: false,
2623
+ configurable: true
2624
+ }
2625
+ });
2626
+ Object.defineProperty(definition, "definition", {
2627
+ value: {
2628
+ type: "function",
2629
+ function: {
2630
+ name: tool.name,
2631
+ description: tool.description,
2632
+ parameters: tool.jsonSchema
2633
+ }
2634
+ },
2635
+ enumerable: false,
2636
+ configurable: true
2637
+ });
2638
+ return definition;
2639
+ }
2640
+ var OpenAIResponsesTools = class {
2641
+ constructor(exa, registry, handleResponses) {
2642
+ this.exa = exa;
2643
+ this.registry = registry;
2644
+ this.handleResponses = handleResponses;
2645
+ }
2646
+ /** Responses API `web_search` tool. Defaults to `auto` + highlights. */
2647
+ webSearch(config) {
2648
+ return responsesRunnable(
2649
+ createWebSearchTool(this.exa, this.registry, config)
2650
+ );
2651
+ }
2652
+ /**
2653
+ * Run the function calls in a Responses API response (or output item array)
2654
+ * and return `function_call_output` items. Every function call is answered
2655
+ * so the follow-up request never omits a required output: a call whose name
2656
+ * doesn't match a known tool gets an `Error: unknown tool "<name>"` output.
2657
+ * When handling some tools yourself, replace those error outputs with your
2658
+ * own results before sending the next request.
2659
+ */
2660
+ async handleToolCalls(responseOrOutputItems, options) {
2661
+ return this.handleResponses(responseOrOutputItems, options);
2662
+ }
2663
+ };
2664
+ function responsesRunnable(tool) {
2665
+ const definition = {
2666
+ type: "function",
2667
+ name: tool.name,
2668
+ description: tool.description,
2669
+ parameters: tool.jsonSchema,
2670
+ strict: false
2671
+ };
2672
+ Object.defineProperties(
2673
+ definition,
2674
+ Object.fromEntries(
2675
+ Object.entries(tool).filter(([key]) => !["name", "description"].includes(key)).map(([key, value]) => [
2676
+ key,
2677
+ { value, enumerable: false, configurable: true }
2678
+ ])
2679
+ )
2680
+ );
2681
+ Object.defineProperty(definition, "definition", {
2682
+ value: {
2683
+ ...tool.definition,
2684
+ type: "function",
2685
+ parameters: tool.jsonSchema,
2686
+ strict: false
2687
+ },
2688
+ enumerable: false
2689
+ });
2690
+ return definition;
2691
+ }
2692
+ var OpenAITools = class {
2693
+ constructor(exa, registry) {
2694
+ this.exa = exa;
2695
+ this.registry = registry;
2696
+ this.responses = new OpenAIResponsesTools(
2697
+ exa,
2698
+ registry,
2699
+ (responseOrOutputItems, options) => this.handleResponsesToolCalls(responseOrOutputItems, options)
2700
+ );
2701
+ }
2702
+ /** Chat Completions `web_search` tool. Defaults to `auto` + highlights. */
2703
+ webSearch(config) {
2704
+ return runnable2(createWebSearchTool(this.exa, this.registry, config));
2705
+ }
2706
+ async handleToolCalls(assistantMessage, options) {
2707
+ if (isResponsesInput(assistantMessage)) {
2708
+ return this.handleResponsesToolCalls(assistantMessage, options);
2709
+ }
2710
+ return this.handleChatToolCalls(assistantMessage, options);
2711
+ }
2712
+ async handleChatToolCalls(assistantMessage, options) {
2713
+ const tools = this.registry.resolve(options?.tools);
2714
+ const calls = (assistantMessage.tool_calls ?? []).filter(isOpenAIToolCall);
2715
+ return Promise.all(
2716
+ calls.map(async (call) => {
2717
+ const tool = getTool(tools, call.function.name);
2718
+ return {
2719
+ role: "tool",
2720
+ tool_call_id: call.id,
2721
+ content: tool ? await tool.run(parseArguments(call.function.arguments)) : unknownToolError(call.function.name)
2722
+ };
2723
+ })
2724
+ );
2725
+ }
2726
+ async handleResponsesToolCalls(responseOrOutputItems, options) {
2727
+ const tools = this.registry.resolve(options?.tools);
2728
+ const rawItems = !Array.isArray(responseOrOutputItems) && "output" in responseOrOutputItems ? responseOrOutputItems.output ?? [] : responseOrOutputItems;
2729
+ const items = rawItems.filter(isResponsesFunctionCall);
2730
+ return Promise.all(
2731
+ items.map(async (call) => {
2732
+ const tool = getTool(tools, call.name);
2733
+ return {
2734
+ type: "function_call_output",
2735
+ call_id: call.call_id,
2736
+ output: tool ? await tool.run(parseArguments(call.arguments)) : unknownToolError(call.name)
2737
+ };
2738
+ })
2739
+ );
2740
+ }
2741
+ };
2742
+ function parseArguments(argumentsText) {
2743
+ try {
2744
+ return JSON.parse(argumentsText);
2745
+ } catch {
2746
+ return argumentsText;
2747
+ }
2748
+ }
2749
+ function isOpenAIToolCall(value) {
2750
+ if (!value || typeof value !== "object") return false;
2751
+ const call = value;
2752
+ return typeof call.id === "string" && !!call.function && typeof call.function.name === "string" && typeof call.function.arguments === "string";
2753
+ }
2754
+ function isResponsesFunctionCall(value) {
2755
+ if (!value || typeof value !== "object") return false;
2756
+ const call = value;
2757
+ return call.type === "function_call" && typeof call.call_id === "string" && typeof call.name === "string" && typeof call.arguments === "string";
2758
+ }
2759
+ function isResponsesInput(value) {
2760
+ if (Array.isArray(value)) return value.some(isResponsesFunctionCall);
2761
+ return "output" in value;
2762
+ }
2393
2763
 
2394
2764
  // src/index.ts
2395
2765
  var fetchImpl = typeof global !== "undefined" && global.fetch ? global.fetch : import_cross_fetch.default;
@@ -2412,6 +2782,39 @@ function truncateResponseBody(text) {
2412
2782
  return collapsed.length > NON_JSON_BODY_SNIPPET_LENGTH ? `${collapsed.slice(0, NON_JSON_BODY_SNIPPET_LENGTH)}\u2026` : collapsed;
2413
2783
  }
2414
2784
  var Exa2 = class {
2785
+ /**
2786
+ * Constructs the Exa API client.
2787
+ * @param {string} apiKey - The API key for authentication.
2788
+ * @param {string} [baseURL] - The base URL of the Exa API.
2789
+ */
2790
+ constructor(apiKey, baseURL = "https://api.exa.ai") {
2791
+ this.toolRegistry = new ToolRegistry();
2792
+ this.baseURL = baseURL;
2793
+ if (!apiKey) {
2794
+ apiKey = process.env.EXA_API_KEY;
2795
+ if (!apiKey) {
2796
+ throw new ExaError(
2797
+ "API key must be provided as an argument or as an environment variable (EXA_API_KEY)",
2798
+ 401 /* Unauthorized */
2799
+ );
2800
+ }
2801
+ }
2802
+ this.headers = new HeadersImpl({
2803
+ "x-api-key": apiKey,
2804
+ "Content-Type": "application/json",
2805
+ "User-Agent": `exa-node ${package_default.version}`
2806
+ });
2807
+ this.websets = new WebsetsClient(this);
2808
+ this.research = new ResearchClient(this);
2809
+ this.monitors = new SearchMonitorsClient(this);
2810
+ this.agent = new AgentClient(this);
2811
+ this.beta = new BetaClient(this.agent);
2812
+ this.tools = {
2813
+ webSearch: (options) => createWebSearchTool(this, this.toolRegistry, options)
2814
+ };
2815
+ this.openai = new OpenAITools(this, this.toolRegistry);
2816
+ this.anthropic = new AnthropicTools(this, this.toolRegistry);
2817
+ }
2415
2818
  /**
2416
2819
  * Helper method to separate out the contents-specific options from the rest.
2417
2820
  */
@@ -2476,33 +2879,6 @@ var Exa2 = class {
2476
2879
  }
2477
2880
  return { query, ...requestOptions };
2478
2881
  }
2479
- /**
2480
- * Constructs the Exa API client.
2481
- * @param {string} apiKey - The API key for authentication.
2482
- * @param {string} [baseURL] - The base URL of the Exa API.
2483
- */
2484
- constructor(apiKey, baseURL = "https://api.exa.ai") {
2485
- this.baseURL = baseURL;
2486
- if (!apiKey) {
2487
- apiKey = process.env.EXA_API_KEY;
2488
- if (!apiKey) {
2489
- throw new ExaError(
2490
- "API key must be provided as an argument or as an environment variable (EXA_API_KEY)",
2491
- 401 /* Unauthorized */
2492
- );
2493
- }
2494
- }
2495
- this.headers = new HeadersImpl({
2496
- "x-api-key": apiKey,
2497
- "Content-Type": "application/json",
2498
- "User-Agent": `exa-node ${package_default.version}`
2499
- });
2500
- this.websets = new WebsetsClient(this);
2501
- this.research = new ResearchClient(this);
2502
- this.monitors = new SearchMonitorsClient(this);
2503
- this.agent = new AgentClient(this);
2504
- this.beta = new BetaClient(this.agent);
2505
- }
2506
2882
  /**
2507
2883
  * Makes a request to the Exa API.
2508
2884
  * @param {string} endpoint - The API endpoint to call.
@@ -2963,9 +3339,11 @@ var index_default = Exa2;
2963
3339
  AgentRunEventsClient,
2964
3340
  AgentRunFailedError,
2965
3341
  AgentRunsClient,
3342
+ AnthropicTools,
2966
3343
  BetaClient,
2967
3344
  CreateEnrichmentParametersFormat,
2968
3345
  CreateImportParametersFormat,
3346
+ DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION,
2969
3347
  EventType,
2970
3348
  EventsClient,
2971
3349
  Exa,
@@ -2981,8 +3359,11 @@ var index_default = Exa2;
2981
3359
  MonitorRunStatus,
2982
3360
  MonitorRunType,
2983
3361
  MonitorStatus,
3362
+ OpenAIResponsesTools,
3363
+ OpenAITools,
2984
3364
  SearchMonitorRunsClient,
2985
3365
  SearchMonitorsClient,
3366
+ ToolRegistry,
2986
3367
  UpdateMonitorStatus,
2987
3368
  WebhookStatus,
2988
3369
  WebsetEnrichmentFormat,
@@ -3001,6 +3382,7 @@ var index_default = Exa2;
3001
3382
  WebsetSearchesClient,
3002
3383
  WebsetStatus,
3003
3384
  WebsetWebhooksClient,
3004
- WebsetsClient
3385
+ WebsetsClient,
3386
+ createWebSearchTool
3005
3387
  });
3006
3388
  //# sourceMappingURL=index.js.map