exa-js 2.2.0 → 2.3.0

package/README.md

@@ -1,213 +1,145 @@
-# exa-js
+# Exa JavaScript SDK
 
-Our official Javscript SDK. Uses `cross-fetch` under the hood.
+[![npm version](https://img.shields.io/npm/v/exa-js.svg)](https://www.npmjs.com/package/exa-js)
 
-Note: This API is basically the same as `metaphor-node` but reflects new
-features associated with Metaphor's rename to Exa. New site is https://exa.ai
+The official JavaScript SDK for [Exa](https://exa.ai), the web search API built for AI.
 
-https://www.npmjs.com/package/exa-js
+[Documentation](https://docs.exa.ai)  |  [Dashboard](https://dashboard.exa.ai)
 
-## Installation
+## Install
 
-```
+```bash
 npm install exa-js
 ```
 
-## Initialization
+## Quick Start
 
-```js
+```ts
 import Exa from "exa-js";
 
 const exa = new Exa(process.env.EXA_API_KEY);
-```
-
-### Common commands
-
-```js
-// Basic search
-const basicResults = await exa.search("This is a Exa query:");
-
-// Search with date filters
-const dateFilteredResults = await exa.search("This is a Exa query:", {
-  startPublishedDate: "2019-01-01",
-  endPublishedDate: "2019-01-31",
-});
-
-// Search with domain filters
-const domainFilteredResults = await exa.search("This is a Exa query:", {
-  includeDomains: ["www.cnn.com", "www.nytimes.com"],
-});
-
-// Search and get text contents
-const searchAndTextResults = await exa.searchAndContents(
-  "This is a Exa query:",
-  { text: true }
-);
 
-// Search and get contents with contents options
-const searchAndCustomContentsResults = await exa.searchAndContents(
-  "This is a Exa query:",
+// Search the web
+const result = await exa.search(
+  "blog post about artificial intelligence",
   {
-    text: { maxCharacters: 3000 },
+    type: "auto",
+    contents: {
+      text: true
+    }
   }
 );
 
-// Find similar documents
-const similarResults = await exa.findSimilar("https://example.com");
-
-// Find similar excluding source domain
-const similarExcludingSourceResults = await exa.findSimilar(
-  "https://example.com",
-  { excludeSourceDomain: true }
-);
-
-// Find similar with contents
-const similarWithContentsResults = await exa.findSimilarAndContents(
-  "https://example.com",
-  { text: true }
+// Find similar pages
+const result = await exa.findSimilar(
+  "https://paulgraham.com/greatwork.html",
+  {
+    contents: {
+      text: true
+    }
+  }
 );
 
-// Get text contents
-const textContentsResults = await exa.getContents(["urls"], { text: true });
+// Get answers with citations
+const { answer } = await exa.answer("What is the capital of France?");
+```
 
-// Get contents with contents options
-const customContentsResults = await exa.getContents(["urls"], {
-  text: { includeHtmlTags: true, maxCharacters: 3000 },
-});
+## Search
 
-// Get an answer to a question
-const answerResult = await exa.answer(
-  "What is the population of New York City?"
-);
+Find webpages using natural language queries.
 
-// Get an answer with streaming
-for await (const chunk of exa.streamAnswer(
-  "What is the population of New York City?"
-)) {
-  if (chunk.content) {
-    process.stdout.write(chunk.content);
-  }
-  if (chunk.citations) {
-    console.log("\nCitations:", chunk.citations);
+```ts
+const result = await exa.search("interesting articles about space", {
+  numResults: 10,
+  includeDomains: ["nasa.gov", "space.com"],
+  startPublishedDate: "2024-01-01",
+  contents: {
+    text: true
   }
-}
-
-// Get an answer with output schema
-const answerResult = await exa.answer(
-  "What is the population of New York City?",
-  {
-    outputSchema: {
-      type: "object",
-      required: ["answer"],
-      additionalProperties: false,
-      properties: {
-        answer: {
-          type: "number",
-        },
-      },
-    },
-  }
-);
+});
 ```
 
-### `exa.search(query: string, options?: SearchOptions): Promise<SearchResponse>`
+## Contents
 
-Performs a search on the Exa system with the given parameters.
+Get clean text, highlights, or summaries from any URL.
 
-```javascript
-const response = await exa.search("funny article about tech culture", {
-  numResults: 5,
-  includeDomains: ["nytimes.com", "wsj.com"],
-  startPublishedDate: "2023-06-12",
+```ts
+const { results } = await exa.getContents(["https://openai.com/research"], {
+  text: true,
+  highlights: true,
+  summary: true,
 });
 ```
 
-### `exa.findSimilar(url: string, options?: FindSimilarOptions): Promise<SearchResponse>`
+## Find Similar
 
-Finds content similar to the specified URL.
+Discover pages similar to a given URL.
 
-```javascript
-const response = await exa.findSimilar(
-  "https://waitbutwhy.com/2014/05/fermi-paradox.html",
+```ts
+const result = await exa.findSimilar(
+  "https://paulgraham.com/greatwork.html",
   {
     numResults: 10,
+    excludeSourceDomain: true,
+    contents: {
+      text: true
+    }
   }
 );
 ```
 
-### `exa.getContents(urls: string[] | Result[]): Promise<GetContentsResponse>`
+## Answer
 
-Retrieves the contents of the specified documents.
-
-```javascript
-const response = await exa.getContents([
-  "https://blog.samaltman.com/how-to-be-successful",
-]);
+```ts
+const response = await exa.answer("What caused the 2008 financial crisis?");
+console.log(response.answer);
 ```
 
-### `exa.answer(query: string, options?: AnswerOptions): Promise<AnswerResponse>`
-
-Generates an answer to a query using search results as context.
-
-```javascript
-const response = await exa.answer("What is the population of New York City?", {
-  text: true,
-});
-```
-
-### `exa.streamAnswer(query: string, options?: { text?: boolean }): AsyncGenerator<AnswerStreamChunk>`
-
-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.
-
-```javascript
-// Basic streaming example
-for await (const chunk of exa.streamAnswer("What is quantum computing?")) {
+```ts
+for await (const chunk of exa.streamAnswer("Explain quantum computing")) {
   if (chunk.content) {
     process.stdout.write(chunk.content);
   }
-  if (chunk.citations) {
-    console.log("\nCitations:", chunk.citations);
-  }
-}
-
-for await (const chunk of exa.streamAnswer("What is quantum computing?", {
-  text: true,
-})) {
 }
 ```
 
-Each chunk contains:
+## Research
 
-- `content`: A string containing the next piece of generated text
-- `citations`: An array of citation objects containing source information
+Run autonomous research tasks that return structured data.
 
-### `exa.research.createTask({ instructions, schema }: { instructions: string, output?: { schema?: object }}): Promise<{id: string}>`
+```ts
+const { researchId } = await exa.research.create({
+  instructions: "Find the top 5 AI startups founded in 2024",
+  outputSchema: {
+    type: "object",
+    properties: {
+      startups: { type: "array", items: { type: "string" } },
+    },
+  },
+});
+
+const result = await exa.research.pollUntilFinished(researchId);
+```
 
-Exa's research agent can autonomously gather information and return a structured JSON object that conforms to a schema you provide.
+## TypeScript
 
-```javascript
+Full TypeScript support with types for all methods.
+
+```ts
 import Exa from "exa-js";
+import type { SearchResponse, RegularSearchOptions } from "exa-js";
+```
 
-const exa = new Exa(process.env.EXA_API_KEY);
+## Links
 
-const schema = {
-  type: "object",
-  required: ["answer"],
-  properties: {
-    answer: { type: "string" },
-  },
-  additionalProperties: false,
-};
+- [Documentation](https://docs.exa.ai)
+- [API Reference](https://docs.exa.ai/reference)
+- [Examples](./examples)
 
-const { id: taskId } = await exa.research.createTask({
-  instructions: "In ≤3 sentences, explain quantum computing.",
-  output: { schema },
-});
-const result = await exa.research.pollTask(taskId);
-```
+## Contributing
 
-Use the `status` field to poll long-running tasks if needed.
+Pull requests welcome! For major changes, open an issue first.
 
-# Contributing
+## License
 
-Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.
+[MIT](LICENSE)

package/dist/index.d.mts

@@ -2473,6 +2473,18 @@ declare class EventsClient extends WebsetsBaseClient {
      * @returns The Event
      */
     get(id: string): Promise<Event>;
+    /**
+     * Iterate through all Events, handling pagination automatically
+     * @param options Filtering and pagination options
+     * @returns Async generator of Events
+     */
+    listAll(options?: ListEventsOptions): AsyncGenerator<Event>;
+    /**
+     * Collect all Events into an array
+     * @param options Filtering and pagination options
+     * @returns Promise resolving to an array of all Events
+     */
+    getAll(options?: ListEventsOptions): Promise<Event[]>;
 }
 
 /**
@@ -2567,6 +2579,18 @@ declare class ImportsClient extends WebsetsBaseClient {
      * @throws Error if the Import does not complete within the timeout or fails
      */
     waitUntilCompleted(id: string, options?: WaitUntilCompletedOptions): Promise<Import>;
+    /**
+     * Iterate through all Imports, handling pagination automatically
+     * @param options Pagination options
+     * @returns Async generator of Imports
+     */
+    listAll(options?: PaginationParams): AsyncGenerator<Import>;
+    /**
+     * Collect all Imports into an array
+     * @param options Pagination options
+     * @returns Promise resolving to an array of all Imports
+     */
+    getAll(options?: PaginationParams): Promise<Import[]>;
 }
 
 /**
@@ -2695,6 +2719,18 @@ declare class WebsetMonitorsClient extends WebsetsBaseClient {
      * @returns The deleted Monitor
      */
     delete(id: string): Promise<Monitor>;
+    /**
+     * Iterate through all Monitors, handling pagination automatically
+     * @param options Pagination and filtering options
+     * @returns Async generator of Monitors
+     */
+    listAll(options?: ListMonitorsOptions): AsyncGenerator<Monitor>;
+    /**
+     * Collect all Monitors into an array
+     * @param options Pagination and filtering options
+     * @returns Promise resolving to an array of all Monitors
+     */
+    getAll(options?: ListMonitorsOptions): Promise<Monitor[]>;
 }
 
 /**
@@ -2994,11 +3030,9 @@ declare class ExaError extends Error {
  * Options for retrieving page contents
  * @typedef {Object} ContentsOptions
  * @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
- * @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.
+ * @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.
  * @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
- * @property {LivecrawlOptions} [livecrawl] - Options for livecrawling contents. Default is "never" for neural/auto search, "fallback" for keyword search.
- * @property {number} [livecrawlTimeout] - The timeout for livecrawling. Max and default is 10000ms.
- * @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.
+ * @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.
  * @property {boolean} [filterEmptyResults] - If true, filters out results with no contents. Default is true.
  * @property {number} [subpages] - The number of subpages to return for each result, where each subpage is derived from an internal link for the result.
  * @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.
@@ -3126,9 +3160,9 @@ type SectionTag = "unspecified" | "header" | "navigation" | "banner" | "body" |
  * @typedef {Object} TextContentsOptions
  * @property {number} [maxCharacters] - The maximum number of characters to return.
  * @property {boolean} [includeHtmlTags] - If true, includes HTML tags in the returned text. Default: false
- * @property {VerbosityOptions} [verbosity] - Controls verbosity level of returned content. Default: "compact". Requires livecrawl: "always".
- * @property {SectionTag[]} [includeSections] - Only include content from these semantic sections. Requires livecrawl: "always".
- * @property {SectionTag[]} [excludeSections] - Exclude content from these semantic sections. Requires livecrawl: "always".
+ * @property {VerbosityOptions} [verbosity] - Controls verbosity level of returned content. Default: "compact". Requires maxAgeHours: 0.
+ * @property {SectionTag[]} [includeSections] - Only include content from these semantic sections. Requires maxAgeHours: 0.
+ * @property {SectionTag[]} [excludeSections] - Exclude content from these semantic sections. Requires maxAgeHours: 0.
  */
 type TextContentsOptions = {
     maxCharacters?: number;
@@ -3143,12 +3177,16 @@ type TextContentsOptions = {
  * to your initial query, and may vary in quantity and length.
  * @typedef {Object} HighlightsContentsOptions
  * @property {string} [query] - The query string to use for highlights search.
- * @property {number} [numSentences] - The number of sentences to return for each highlight.
- * @property {number} [highlightsPerUrl] - The number of highlights to return for each URL.
+ * @property {number} [maxCharacters] - The maximum number of characters to return for highlights.
+ * @property {number} [numSentences] - Deprecated. Use maxCharacters instead.
+ * @property {number} [highlightsPerUrl] - Deprecated. Use maxCharacters instead.
  */
 type HighlightsContentsOptions = {
     query?: string;
+    maxCharacters?: number;
+    /** @deprecated Use maxCharacters instead */
     numSentences?: number;
+    /** @deprecated Use maxCharacters instead */
     highlightsPerUrl?: number;
 };
 /**
@@ -3371,6 +3409,8 @@ type SearchResult<T extends ContentsOptions> = {
  * @property {string} [autoDate] - The autoprompt date, if applicable.
  * @property {string} requestId - The request ID for the search.
  * @property {CostDollars} [costDollars] - The cost breakdown for this request.
+ * @property {string} [resolvedSearchType] - The resolved search type ('neural' or 'keyword') when using 'auto' search.
+ * @property {number} [searchTime] - Time taken for the search in milliseconds.
  */
 type SearchResponse<T extends ContentsOptions> = {
     results: SearchResult<T>[];
@@ -3379,6 +3419,8 @@ type SearchResponse<T extends ContentsOptions> = {
     requestId: string;
     statuses?: Array<Status>;
     costDollars?: CostDollars;
+    resolvedSearchType?: string;
+    searchTime?: number;
 };
 type Status = {
     id: string;
@@ -3654,6 +3696,7 @@ declare class Exa {
         model?: "exa" | "exa-pro";
         systemPrompt?: string;
         outputSchema: ZodSchema<T>;
+        userLocation?: string;
     }): AsyncGenerator<AnswerStreamChunk>;
     /**
      * Stream an answer as an async generator
@@ -3679,6 +3722,7 @@ declare class Exa {
         model?: "exa" | "exa-pro";
         systemPrompt?: string;
         outputSchema?: Record<string, unknown>;
+        userLocation?: string;
     }): AsyncGenerator<AnswerStreamChunk>;
     private processChunk;
     private parseSSEStream;

package/dist/index.d.ts

@@ -2473,6 +2473,18 @@ declare class EventsClient extends WebsetsBaseClient {
      * @returns The Event
      */
     get(id: string): Promise<Event>;
+    /**
+     * Iterate through all Events, handling pagination automatically
+     * @param options Filtering and pagination options
+     * @returns Async generator of Events
+     */
+    listAll(options?: ListEventsOptions): AsyncGenerator<Event>;
+    /**
+     * Collect all Events into an array
+     * @param options Filtering and pagination options
+     * @returns Promise resolving to an array of all Events
+     */
+    getAll(options?: ListEventsOptions): Promise<Event[]>;
 }
 
 /**
@@ -2567,6 +2579,18 @@ declare class ImportsClient extends WebsetsBaseClient {
      * @throws Error if the Import does not complete within the timeout or fails
      */
     waitUntilCompleted(id: string, options?: WaitUntilCompletedOptions): Promise<Import>;
+    /**
+     * Iterate through all Imports, handling pagination automatically
+     * @param options Pagination options
+     * @returns Async generator of Imports
+     */
+    listAll(options?: PaginationParams): AsyncGenerator<Import>;
+    /**
+     * Collect all Imports into an array
+     * @param options Pagination options
+     * @returns Promise resolving to an array of all Imports
+     */
+    getAll(options?: PaginationParams): Promise<Import[]>;
 }
 
 /**
@@ -2695,6 +2719,18 @@ declare class WebsetMonitorsClient extends WebsetsBaseClient {
      * @returns The deleted Monitor
      */
     delete(id: string): Promise<Monitor>;
+    /**
+     * Iterate through all Monitors, handling pagination automatically
+     * @param options Pagination and filtering options
+     * @returns Async generator of Monitors
+     */
+    listAll(options?: ListMonitorsOptions): AsyncGenerator<Monitor>;
+    /**
+     * Collect all Monitors into an array
+     * @param options Pagination and filtering options
+     * @returns Promise resolving to an array of all Monitors
+     */
+    getAll(options?: ListMonitorsOptions): Promise<Monitor[]>;
 }
 
 /**
@@ -2994,11 +3030,9 @@ declare class ExaError extends Error {
  * Options for retrieving page contents
  * @typedef {Object} ContentsOptions
  * @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
- * @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.
+ * @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.
  * @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
- * @property {LivecrawlOptions} [livecrawl] - Options for livecrawling contents. Default is "never" for neural/auto search, "fallback" for keyword search.
- * @property {number} [livecrawlTimeout] - The timeout for livecrawling. Max and default is 10000ms.
- * @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.
+ * @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.
  * @property {boolean} [filterEmptyResults] - If true, filters out results with no contents. Default is true.
  * @property {number} [subpages] - The number of subpages to return for each result, where each subpage is derived from an internal link for the result.
  * @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.
@@ -3126,9 +3160,9 @@ type SectionTag = "unspecified" | "header" | "navigation" | "banner" | "body" |
  * @typedef {Object} TextContentsOptions
  * @property {number} [maxCharacters] - The maximum number of characters to return.
  * @property {boolean} [includeHtmlTags] - If true, includes HTML tags in the returned text. Default: false
- * @property {VerbosityOptions} [verbosity] - Controls verbosity level of returned content. Default: "compact". Requires livecrawl: "always".
- * @property {SectionTag[]} [includeSections] - Only include content from these semantic sections. Requires livecrawl: "always".
- * @property {SectionTag[]} [excludeSections] - Exclude content from these semantic sections. Requires livecrawl: "always".
+ * @property {VerbosityOptions} [verbosity] - Controls verbosity level of returned content. Default: "compact". Requires maxAgeHours: 0.
+ * @property {SectionTag[]} [includeSections] - Only include content from these semantic sections. Requires maxAgeHours: 0.
+ * @property {SectionTag[]} [excludeSections] - Exclude content from these semantic sections. Requires maxAgeHours: 0.
  */
 type TextContentsOptions = {
     maxCharacters?: number;
@@ -3143,12 +3177,16 @@ type TextContentsOptions = {
  * to your initial query, and may vary in quantity and length.
  * @typedef {Object} HighlightsContentsOptions
  * @property {string} [query] - The query string to use for highlights search.
- * @property {number} [numSentences] - The number of sentences to return for each highlight.
- * @property {number} [highlightsPerUrl] - The number of highlights to return for each URL.
+ * @property {number} [maxCharacters] - The maximum number of characters to return for highlights.
+ * @property {number} [numSentences] - Deprecated. Use maxCharacters instead.
+ * @property {number} [highlightsPerUrl] - Deprecated. Use maxCharacters instead.
  */
 type HighlightsContentsOptions = {
     query?: string;
+    maxCharacters?: number;
+    /** @deprecated Use maxCharacters instead */
     numSentences?: number;
+    /** @deprecated Use maxCharacters instead */
     highlightsPerUrl?: number;
 };
 /**
@@ -3371,6 +3409,8 @@ type SearchResult<T extends ContentsOptions> = {
  * @property {string} [autoDate] - The autoprompt date, if applicable.
  * @property {string} requestId - The request ID for the search.
  * @property {CostDollars} [costDollars] - The cost breakdown for this request.
+ * @property {string} [resolvedSearchType] - The resolved search type ('neural' or 'keyword') when using 'auto' search.
+ * @property {number} [searchTime] - Time taken for the search in milliseconds.
  */
 type SearchResponse<T extends ContentsOptions> = {
     results: SearchResult<T>[];
@@ -3379,6 +3419,8 @@ type SearchResponse<T extends ContentsOptions> = {
     requestId: string;
     statuses?: Array<Status>;
     costDollars?: CostDollars;
+    resolvedSearchType?: string;
+    searchTime?: number;
 };
 type Status = {
     id: string;
@@ -3654,6 +3696,7 @@ declare class Exa {
         model?: "exa" | "exa-pro";
         systemPrompt?: string;
         outputSchema: ZodSchema<T>;
+        userLocation?: string;
     }): AsyncGenerator<AnswerStreamChunk>;
     /**
      * Stream an answer as an async generator
@@ -3679,6 +3722,7 @@ declare class Exa {
         model?: "exa" | "exa-pro";
         systemPrompt?: string;
         outputSchema?: Record<string, unknown>;
+        userLocation?: string;
     }): AsyncGenerator<AnswerStreamChunk>;
     private processChunk;
     private parseSSEStream;