exa-js 2.2.0 → 2.4.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 CHANGED
@@ -1,213 +1,145 @@
1
- # exa-js
1
+ # Exa JavaScript SDK
2
2
 
3
- Our official Javscript SDK. Uses `cross-fetch` under the hood.
3
+ [![npm version](https://img.shields.io/npm/v/exa-js.svg)](https://www.npmjs.com/package/exa-js)
4
4
 
5
- Note: This API is basically the same as `metaphor-node` but reflects new
6
- features associated with Metaphor's rename to Exa. New site is https://exa.ai
5
+ The official JavaScript SDK for [Exa](https://exa.ai), the web search API built for AI.
7
6
 
8
- https://www.npmjs.com/package/exa-js
7
+ [Documentation](https://docs.exa.ai)  |  [Dashboard](https://dashboard.exa.ai)
9
8
 
10
- ## Installation
9
+ ## Install
11
10
 
12
- ```
11
+ ```bash
13
12
  npm install exa-js
14
13
  ```
15
14
 
16
- ## Initialization
15
+ ## Quick Start
17
16
 
18
- ```js
17
+ ```ts
19
18
  import Exa from "exa-js";
20
19
 
21
20
  const exa = new Exa(process.env.EXA_API_KEY);
22
- ```
23
-
24
- ### Common commands
25
-
26
- ```js
27
- // Basic search
28
- const basicResults = await exa.search("This is a Exa query:");
29
-
30
- // Search with date filters
31
- const dateFilteredResults = await exa.search("This is a Exa query:", {
32
- startPublishedDate: "2019-01-01",
33
- endPublishedDate: "2019-01-31",
34
- });
35
-
36
- // Search with domain filters
37
- const domainFilteredResults = await exa.search("This is a Exa query:", {
38
- includeDomains: ["www.cnn.com", "www.nytimes.com"],
39
- });
40
-
41
- // Search and get text contents
42
- const searchAndTextResults = await exa.searchAndContents(
43
- "This is a Exa query:",
44
- { text: true }
45
- );
46
21
 
47
- // Search and get contents with contents options
48
- const searchAndCustomContentsResults = await exa.searchAndContents(
49
- "This is a Exa query:",
22
+ // Search the web
23
+ const result = await exa.search(
24
+ "blog post about artificial intelligence",
50
25
  {
51
- text: { maxCharacters: 3000 },
26
+ type: "auto",
27
+ contents: {
28
+ text: true
29
+ }
52
30
  }
53
31
  );
54
32
 
55
- // Find similar documents
56
- const similarResults = await exa.findSimilar("https://example.com");
57
-
58
- // Find similar excluding source domain
59
- const similarExcludingSourceResults = await exa.findSimilar(
60
- "https://example.com",
61
- { excludeSourceDomain: true }
62
- );
63
-
64
- // Find similar with contents
65
- const similarWithContentsResults = await exa.findSimilarAndContents(
66
- "https://example.com",
67
- { text: true }
33
+ // Find similar pages
34
+ const result = await exa.findSimilar(
35
+ "https://paulgraham.com/greatwork.html",
36
+ {
37
+ contents: {
38
+ text: true
39
+ }
40
+ }
68
41
  );
69
42
 
70
- // Get text contents
71
- const textContentsResults = await exa.getContents(["urls"], { text: true });
43
+ // Get answers with citations
44
+ const { answer } = await exa.answer("What is the capital of France?");
45
+ ```
72
46
 
73
- // Get contents with contents options
74
- const customContentsResults = await exa.getContents(["urls"], {
75
- text: { includeHtmlTags: true, maxCharacters: 3000 },
76
- });
47
+ ## Search
77
48
 
78
- // Get an answer to a question
79
- const answerResult = await exa.answer(
80
- "What is the population of New York City?"
81
- );
49
+ Find webpages using natural language queries.
82
50
 
83
- // Get an answer with streaming
84
- for await (const chunk of exa.streamAnswer(
85
- "What is the population of New York City?"
86
- )) {
87
- if (chunk.content) {
88
- process.stdout.write(chunk.content);
89
- }
90
- if (chunk.citations) {
91
- console.log("\nCitations:", chunk.citations);
51
+ ```ts
52
+ const result = await exa.search("interesting articles about space", {
53
+ numResults: 10,
54
+ includeDomains: ["nasa.gov", "space.com"],
55
+ startPublishedDate: "2024-01-01",
56
+ contents: {
57
+ text: true
92
58
  }
93
- }
94
-
95
- // Get an answer with output schema
96
- const answerResult = await exa.answer(
97
- "What is the population of New York City?",
98
- {
99
- outputSchema: {
100
- type: "object",
101
- required: ["answer"],
102
- additionalProperties: false,
103
- properties: {
104
- answer: {
105
- type: "number",
106
- },
107
- },
108
- },
109
- }
110
- );
59
+ });
111
60
  ```
112
61
 
113
- ### `exa.search(query: string, options?: SearchOptions): Promise<SearchResponse>`
62
+ ## Contents
114
63
 
115
- Performs a search on the Exa system with the given parameters.
64
+ Get clean text, highlights, or summaries from any URL.
116
65
 
117
- ```javascript
118
- const response = await exa.search("funny article about tech culture", {
119
- numResults: 5,
120
- includeDomains: ["nytimes.com", "wsj.com"],
121
- startPublishedDate: "2023-06-12",
66
+ ```ts
67
+ const { results } = await exa.getContents(["https://openai.com/research"], {
68
+ text: true,
69
+ highlights: true,
70
+ summary: true,
122
71
  });
123
72
  ```
124
73
 
125
- ### `exa.findSimilar(url: string, options?: FindSimilarOptions): Promise<SearchResponse>`
74
+ ## Find Similar
126
75
 
127
- Finds content similar to the specified URL.
76
+ Discover pages similar to a given URL.
128
77
 
129
- ```javascript
130
- const response = await exa.findSimilar(
131
- "https://waitbutwhy.com/2014/05/fermi-paradox.html",
78
+ ```ts
79
+ const result = await exa.findSimilar(
80
+ "https://paulgraham.com/greatwork.html",
132
81
  {
133
82
  numResults: 10,
83
+ excludeSourceDomain: true,
84
+ contents: {
85
+ text: true
86
+ }
134
87
  }
135
88
  );
136
89
  ```
137
90
 
138
- ### `exa.getContents(urls: string[] | Result[]): Promise<GetContentsResponse>`
91
+ ## Answer
139
92
 
140
- Retrieves the contents of the specified documents.
141
-
142
- ```javascript
143
- const response = await exa.getContents([
144
- "https://blog.samaltman.com/how-to-be-successful",
145
- ]);
93
+ ```ts
94
+ const response = await exa.answer("What caused the 2008 financial crisis?");
95
+ console.log(response.answer);
146
96
  ```
147
97
 
148
- ### `exa.answer(query: string, options?: AnswerOptions): Promise<AnswerResponse>`
149
-
150
- Generates an answer to a query using search results as context.
151
-
152
- ```javascript
153
- const response = await exa.answer("What is the population of New York City?", {
154
- text: true,
155
- });
156
- ```
157
-
158
- ### `exa.streamAnswer(query: string, options?: { text?: boolean }): AsyncGenerator<AnswerStreamChunk>`
159
-
160
- Streams an answer as it's being generated, yielding chunks of text and citations. This is useful for providing real-time updates in chat interfaces or displaying partial results as they become available.
161
-
162
- ```javascript
163
- // Basic streaming example
164
- for await (const chunk of exa.streamAnswer("What is quantum computing?")) {
98
+ ```ts
99
+ for await (const chunk of exa.streamAnswer("Explain quantum computing")) {
165
100
  if (chunk.content) {
166
101
  process.stdout.write(chunk.content);
167
102
  }
168
- if (chunk.citations) {
169
- console.log("\nCitations:", chunk.citations);
170
- }
171
- }
172
-
173
- for await (const chunk of exa.streamAnswer("What is quantum computing?", {
174
- text: true,
175
- })) {
176
103
  }
177
104
  ```
178
105
 
179
- Each chunk contains:
106
+ ## Research
180
107
 
181
- - `content`: A string containing the next piece of generated text
182
- - `citations`: An array of citation objects containing source information
108
+ Run autonomous research tasks that return structured data.
183
109
 
184
- ### `exa.research.createTask({ instructions, schema }: { instructions: string, output?: { schema?: object }}): Promise<{id: string}>`
110
+ ```ts
111
+ const { researchId } = await exa.research.create({
112
+ instructions: "Find the top 5 AI startups founded in 2024",
113
+ outputSchema: {
114
+ type: "object",
115
+ properties: {
116
+ startups: { type: "array", items: { type: "string" } },
117
+ },
118
+ },
119
+ });
120
+
121
+ const result = await exa.research.pollUntilFinished(researchId);
122
+ ```
185
123
 
186
- Exa's research agent can autonomously gather information and return a structured JSON object that conforms to a schema you provide.
124
+ ## TypeScript
187
125
 
188
- ```javascript
126
+ Full TypeScript support with types for all methods.
127
+
128
+ ```ts
189
129
  import Exa from "exa-js";
130
+ import type { SearchResponse, RegularSearchOptions } from "exa-js";
131
+ ```
190
132
 
191
- const exa = new Exa(process.env.EXA_API_KEY);
133
+ ## Links
192
134
 
193
- const schema = {
194
- type: "object",
195
- required: ["answer"],
196
- properties: {
197
- answer: { type: "string" },
198
- },
199
- additionalProperties: false,
200
- };
135
+ - [Documentation](https://docs.exa.ai)
136
+ - [API Reference](https://docs.exa.ai/reference)
137
+ - [Examples](./examples)
201
138
 
202
- const { id: taskId } = await exa.research.createTask({
203
- instructions: "In ≤3 sentences, explain quantum computing.",
204
- output: { schema },
205
- });
206
- const result = await exa.research.pollTask(taskId);
207
- ```
139
+ ## Contributing
208
140
 
209
- Use the `status` field to poll long-running tasks if needed.
141
+ Pull requests welcome! For major changes, open an issue first.
210
142
 
211
- # Contributing
143
+ ## License
212
144
 
213
- Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.
145
+ [MIT](LICENSE)
package/dist/index.d.mts CHANGED
@@ -2473,6 +2473,18 @@ declare class EventsClient extends WebsetsBaseClient {
2473
2473
  * @returns The Event
2474
2474
  */
2475
2475
  get(id: string): Promise<Event>;
2476
+ /**
2477
+ * Iterate through all Events, handling pagination automatically
2478
+ * @param options Filtering and pagination options
2479
+ * @returns Async generator of Events
2480
+ */
2481
+ listAll(options?: ListEventsOptions): AsyncGenerator<Event>;
2482
+ /**
2483
+ * Collect all Events into an array
2484
+ * @param options Filtering and pagination options
2485
+ * @returns Promise resolving to an array of all Events
2486
+ */
2487
+ getAll(options?: ListEventsOptions): Promise<Event[]>;
2476
2488
  }
2477
2489
 
2478
2490
  /**
@@ -2567,6 +2579,18 @@ declare class ImportsClient extends WebsetsBaseClient {
2567
2579
  * @throws Error if the Import does not complete within the timeout or fails
2568
2580
  */
2569
2581
  waitUntilCompleted(id: string, options?: WaitUntilCompletedOptions): Promise<Import>;
2582
+ /**
2583
+ * Iterate through all Imports, handling pagination automatically
2584
+ * @param options Pagination options
2585
+ * @returns Async generator of Imports
2586
+ */
2587
+ listAll(options?: PaginationParams): AsyncGenerator<Import>;
2588
+ /**
2589
+ * Collect all Imports into an array
2590
+ * @param options Pagination options
2591
+ * @returns Promise resolving to an array of all Imports
2592
+ */
2593
+ getAll(options?: PaginationParams): Promise<Import[]>;
2570
2594
  }
2571
2595
 
2572
2596
  /**
@@ -2695,6 +2719,18 @@ declare class WebsetMonitorsClient extends WebsetsBaseClient {
2695
2719
  * @returns The deleted Monitor
2696
2720
  */
2697
2721
  delete(id: string): Promise<Monitor>;
2722
+ /**
2723
+ * Iterate through all Monitors, handling pagination automatically
2724
+ * @param options Pagination and filtering options
2725
+ * @returns Async generator of Monitors
2726
+ */
2727
+ listAll(options?: ListMonitorsOptions): AsyncGenerator<Monitor>;
2728
+ /**
2729
+ * Collect all Monitors into an array
2730
+ * @param options Pagination and filtering options
2731
+ * @returns Promise resolving to an array of all Monitors
2732
+ */
2733
+ getAll(options?: ListMonitorsOptions): Promise<Monitor[]>;
2698
2734
  }
2699
2735
 
2700
2736
  /**
@@ -2994,11 +3030,9 @@ declare class ExaError extends Error {
2994
3030
  * Options for retrieving page contents
2995
3031
  * @typedef {Object} ContentsOptions
2996
3032
  * @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
2997
- * @property {HighlightsContentsOptions | boolean} [highlights] - Options for retrieving highlights. NOTE: For search type "deep", only "true" is allowed. "query", "numSentences" and "highlightsPerUrl" will not be respected.
3033
+ * @property {HighlightsContentsOptions | boolean} [highlights] - Options for retrieving highlights. NOTE: For search type "deep", only "true" is allowed. "query", "maxCharacters", "numSentences" and "highlightsPerUrl" will not be respected.
2998
3034
  * @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
2999
- * @property {LivecrawlOptions} [livecrawl] - Options for livecrawling contents. Default is "never" for neural/auto search, "fallback" for keyword search.
3000
- * @property {number} [livecrawlTimeout] - The timeout for livecrawling. Max and default is 10000ms.
3001
- * @property {number} [maxAgeHours] - Maximum age of indexed content in hours. If older, fetches with livecrawl. 0 = always livecrawl, -1 = never livecrawl (cache only). Cannot be used together with livecrawl.
3035
+ * @property {number} [maxAgeHours] - Maximum age of cached content in hours. If content is older, it will be fetched fresh. Special values: 0 = always fetch fresh content, -1 = never fetch fresh (use cached content only). Example: 168 = fetch fresh for pages older than 7 days.
3002
3036
  * @property {boolean} [filterEmptyResults] - If true, filters out results with no contents. Default is true.
3003
3037
  * @property {number} [subpages] - The number of subpages to return for each result, where each subpage is derived from an internal link for the result.
3004
3038
  * @property {string | string[]} [subpageTarget] - Text used to match/rank subpages in the returned subpage list. You could use "about" to get *about* page for websites. Note that this is a fuzzy matcher.
@@ -3009,6 +3043,7 @@ type ContentsOptions = {
3009
3043
  highlights?: HighlightsContentsOptions | true;
3010
3044
  summary?: SummaryContentsOptions | true;
3011
3045
  livecrawl?: LivecrawlOptions;
3046
+ /** @deprecated Use `highlights` or `text` instead. Will be removed in a future version. */
3012
3047
  context?: ContextOptions | true;
3013
3048
  livecrawlTimeout?: number;
3014
3049
  maxAgeHours?: number;
@@ -3060,14 +3095,15 @@ type BaseRegularSearchOptions = BaseSearchOptions & {
3060
3095
  useAutoprompt?: boolean;
3061
3096
  };
3062
3097
  /**
3063
- * Contents options for deep search - context is always returned and cannot be disabled
3098
+ * Contents options for deep search.
3099
+ * @deprecated The `context` field is deprecated. Use `highlights` or `text` instead.
3064
3100
  */
3065
3101
  type DeepContentsOptions = Omit<ContentsOptions, "context"> & {
3102
+ /** @deprecated Use `highlights` or `text` instead. Will be removed in a future version. */
3066
3103
  context?: Omit<ContextOptions, never> | true;
3067
3104
  };
3068
3105
  /**
3069
3106
  * Search options for deep search type, which supports additional queries.
3070
- * Note: context is always returned by the API for deep search and cannot be set to false.
3071
3107
  */
3072
3108
  type DeepSearchOptions = Omit<BaseRegularSearchOptions, "contents"> & {
3073
3109
  type: "deep";
@@ -3083,10 +3119,10 @@ type DeepSearchOptions = Omit<BaseRegularSearchOptions, "contents"> & {
3083
3119
  contents?: DeepContentsOptions;
3084
3120
  };
3085
3121
  /**
3086
- * Search options for non-deep search types (keyword, neural, auto, hybrid, fast)
3122
+ * Search options for non-deep search types (keyword, neural, auto, hybrid, fast, instant)
3087
3123
  */
3088
3124
  type NonDeepSearchOptions = BaseRegularSearchOptions & {
3089
- type?: "keyword" | "neural" | "auto" | "hybrid" | "fast";
3125
+ type?: "keyword" | "neural" | "auto" | "hybrid" | "fast" | "instant";
3090
3126
  };
3091
3127
  /**
3092
3128
  * Search options for performing a search query.
@@ -3126,9 +3162,9 @@ type SectionTag = "unspecified" | "header" | "navigation" | "banner" | "body" |
3126
3162
  * @typedef {Object} TextContentsOptions
3127
3163
  * @property {number} [maxCharacters] - The maximum number of characters to return.
3128
3164
  * @property {boolean} [includeHtmlTags] - If true, includes HTML tags in the returned text. Default: false
3129
- * @property {VerbosityOptions} [verbosity] - Controls verbosity level of returned content. Default: "compact". Requires livecrawl: "always".
3130
- * @property {SectionTag[]} [includeSections] - Only include content from these semantic sections. Requires livecrawl: "always".
3131
- * @property {SectionTag[]} [excludeSections] - Exclude content from these semantic sections. Requires livecrawl: "always".
3165
+ * @property {VerbosityOptions} [verbosity] - Controls verbosity level of returned content. Default: "compact". Requires maxAgeHours: 0.
3166
+ * @property {SectionTag[]} [includeSections] - Only include content from these semantic sections. Requires maxAgeHours: 0.
3167
+ * @property {SectionTag[]} [excludeSections] - Exclude content from these semantic sections. Requires maxAgeHours: 0.
3132
3168
  */
3133
3169
  type TextContentsOptions = {
3134
3170
  maxCharacters?: number;
@@ -3143,12 +3179,16 @@ type TextContentsOptions = {
3143
3179
  * to your initial query, and may vary in quantity and length.
3144
3180
  * @typedef {Object} HighlightsContentsOptions
3145
3181
  * @property {string} [query] - The query string to use for highlights search.
3146
- * @property {number} [numSentences] - The number of sentences to return for each highlight.
3147
- * @property {number} [highlightsPerUrl] - The number of highlights to return for each URL.
3182
+ * @property {number} [maxCharacters] - The maximum number of characters to return for highlights.
3183
+ * @property {number} [numSentences] - Deprecated. Use maxCharacters instead.
3184
+ * @property {number} [highlightsPerUrl] - Deprecated. Use maxCharacters instead.
3148
3185
  */
3149
3186
  type HighlightsContentsOptions = {
3150
3187
  query?: string;
3188
+ maxCharacters?: number;
3189
+ /** @deprecated Use maxCharacters instead */
3151
3190
  numSentences?: number;
3191
+ /** @deprecated Use maxCharacters instead */
3152
3192
  highlightsPerUrl?: number;
3153
3193
  };
3154
3194
  /**
@@ -3166,6 +3206,8 @@ type SummaryContentsOptions = {
3166
3206
  */
3167
3207
  type JSONSchema = Record<string, unknown>;
3168
3208
  /**
3209
+ * @deprecated Use `highlights` or `text` instead. The `context` option is deprecated and will be removed in a future version.
3210
+ *
3169
3211
  * Options for retrieving the context from a list of search results. The context is a string
3170
3212
  * representation of all the search results.
3171
3213
  * @typedef {Object} ContextOptions
@@ -3367,18 +3409,23 @@ type SearchResult<T extends ContentsOptions> = {
3367
3409
  * Represents a search response object.
3368
3410
  * @typedef {Object} SearchResponse
3369
3411
  * @property {Result[]} results - The list of search results.
3370
- * @property {string} [context] - The context for the search.
3412
+ * @property {string} [context] - Deprecated. The context for the search.
3371
3413
  * @property {string} [autoDate] - The autoprompt date, if applicable.
3372
3414
  * @property {string} requestId - The request ID for the search.
3373
3415
  * @property {CostDollars} [costDollars] - The cost breakdown for this request.
3416
+ * @property {string} [resolvedSearchType] - The resolved search type ('neural' or 'keyword') when using 'auto' search.
3417
+ * @property {number} [searchTime] - Time taken for the search in milliseconds.
3374
3418
  */
3375
3419
  type SearchResponse<T extends ContentsOptions> = {
3376
3420
  results: SearchResult<T>[];
3421
+ /** @deprecated Use `highlights` or `text` on individual results instead. Will be removed in a future version. */
3377
3422
  context?: string;
3378
3423
  autoDate?: string;
3379
3424
  requestId: string;
3380
3425
  statuses?: Array<Status>;
3381
3426
  costDollars?: CostDollars;
3427
+ resolvedSearchType?: string;
3428
+ searchTime?: number;
3382
3429
  };
3383
3430
  type Status = {
3384
3431
  id: string;
@@ -3654,6 +3701,7 @@ declare class Exa {
3654
3701
  model?: "exa" | "exa-pro";
3655
3702
  systemPrompt?: string;
3656
3703
  outputSchema: ZodSchema<T>;
3704
+ userLocation?: string;
3657
3705
  }): AsyncGenerator<AnswerStreamChunk>;
3658
3706
  /**
3659
3707
  * Stream an answer as an async generator
@@ -3679,6 +3727,7 @@ declare class Exa {
3679
3727
  model?: "exa" | "exa-pro";
3680
3728
  systemPrompt?: string;
3681
3729
  outputSchema?: Record<string, unknown>;
3730
+ userLocation?: string;
3682
3731
  }): AsyncGenerator<AnswerStreamChunk>;
3683
3732
  private processChunk;
3684
3733
  private parseSSEStream;