exa-js 2.1.1 → 2.3.0

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,10 +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 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.
@@ -3010,6 +3045,7 @@ type ContentsOptions = {
     livecrawl?: LivecrawlOptions;
     context?: ContextOptions | true;
     livecrawlTimeout?: number;
+    maxAgeHours?: number;
     filterEmptyResults?: boolean;
     subpages?: number;
     subpageTarget?: string | string[];
@@ -3041,7 +3077,7 @@ type BaseSearchOptions = {
     endCrawlDate?: string;
     startPublishedDate?: string;
     endPublishedDate?: string;
-    category?: "company" | "research paper" | "news" | "pdf" | "github" | "tweet" | "personal site" | "financial report" | "people";
+    category?: "company" | "research paper" | "news" | "pdf" | "tweet" | "personal site" | "financial report" | "people";
     includeText?: string[];
     excludeText?: string[];
     flags?: string[];
@@ -3108,15 +3144,32 @@ type ExtrasOptions = {
  * @typedef {string} LivecrawlOptions
  */
 type LivecrawlOptions = "never" | "fallback" | "always" | "auto" | "preferred";
+/**
+ * Verbosity levels for content filtering.
+ * - compact: Most concise output, main content only (default)
+ * - standard: Balanced content with more detail
+ * - full: Complete content including all sections
+ */
+type VerbosityOptions = "compact" | "standard" | "full";
+/**
+ * Section tags for semantic content filtering.
+ */
+type SectionTag = "unspecified" | "header" | "navigation" | "banner" | "body" | "sidebar" | "footer" | "metadata";
 /**
  * Options for retrieving text from page.
  * @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 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;
     includeHtmlTags?: boolean;
+    verbosity?: VerbosityOptions;
+    includeSections?: SectionTag[];
+    excludeSections?: SectionTag[];
 };
 /**
  * Options for retrieving highlights from page.
@@ -3124,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;
 };
 /**
@@ -3352,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>[];
@@ -3360,6 +3419,8 @@ type SearchResponse<T extends ContentsOptions> = {
     requestId: string;
     statuses?: Array<Status>;
     costDollars?: CostDollars;
+    resolvedSearchType?: string;
+    searchTime?: number;
 };
 type Status = {
     id: string;
@@ -3635,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
@@ -3660,9 +3722,10 @@ declare class Exa {
         model?: "exa" | "exa-pro";
         systemPrompt?: string;
         outputSchema?: Record<string, unknown>;
+        userLocation?: string;
     }): AsyncGenerator<AnswerStreamChunk>;
     private processChunk;
     private parseSSEStream;
 }
 
-export { type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, type Default, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type SearchResponse, type SearchResult, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateWebhookParameters, type UpdateWebsetRequest, type WaitUntilCompletedOptions, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };
+export { type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type ArticleEntity, type BaseSearchOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, type Default, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type SearchResponse, type SearchResult, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };

package/dist/index.js

@@ -74,7 +74,7 @@ var import_cross_fetch = __toESM(require("cross-fetch"));
 // package.json
 var package_default = {
   name: "exa-js",
-  version: "2.1.1",
+  version: "2.3.0",
   description: "Exa SDK for Node.js and the browser",
   publishConfig: {
     access: "public"
@@ -105,6 +105,7 @@ var package_default = {
     "generate:types:websets": "openapi-typescript https://raw.githubusercontent.com/exa-labs/openapi-spec/refs/heads/master/exa-websets-spec.yaml  --enum --root-types --alphabetize --root-types-no-schema-prefix --output ./src/websets/openapi.ts && npm run format:websets",
     format: 'prettier --write "src/**/*.ts" "examples/**/*.ts"',
     "format:websets": "prettier --write src/websets/openapi.ts",
+    "generate-docs": "npx tsx scripts/generate-docs.ts",
     "build:beta": "cross-env NPM_CONFIG_TAG=beta npm run build",
     "version:beta": "npm version prerelease --preid=beta",
     "version:stable": "npm version patch",
@@ -118,8 +119,10 @@ var package_default = {
     "cross-env": "~7.0.3",
     "openapi-typescript": "~7.6.1",
     prettier: "~3.5.3",
+    "ts-morph": "^27.0.2",
     "ts-node": "~10.9.2",
     tsup: "~8.4.0",
+    tsx: "^4.21.0",
     typescript: "~5.8.3",
     vitest: "~3.1.1"
   },
@@ -494,6 +497,38 @@ var EventsClient = class extends WebsetsBaseClient {
   async get(id) {
     return this.request(`/v0/events/${id}`, "GET");
   }
+  /**
+   * Iterate through all Events, handling pagination automatically
+   * @param options Filtering and pagination options
+   * @returns Async generator of Events
+   */
+  async *listAll(options) {
+    let cursor = void 0;
+    const pageOptions = options ? { ...options } : {};
+    while (true) {
+      pageOptions.cursor = cursor;
+      const response = await this.list(pageOptions);
+      for (const event of response.data) {
+        yield event;
+      }
+      if (!response.hasMore || !response.nextCursor) {
+        break;
+      }
+      cursor = response.nextCursor;
+    }
+  }
+  /**
+   * Collect all Events into an array
+   * @param options Filtering and pagination options
+   * @returns Promise resolving to an array of all Events
+   */
+  async getAll(options) {
+    const events = [];
+    for await (const event of this.listAll(options)) {
+      events.push(event);
+    }
+    return events;
+  }
 };
 
 // src/websets/openapi.ts
@@ -808,6 +843,38 @@ var ImportsClient = class extends WebsetsBaseClient {
       await new Promise((resolve) => setTimeout(resolve, pollInterval));
     }
   }
+  /**
+   * Iterate through all Imports, handling pagination automatically
+   * @param options Pagination options
+   * @returns Async generator of Imports
+   */
+  async *listAll(options) {
+    let cursor = void 0;
+    const pageOptions = options ? { ...options } : {};
+    while (true) {
+      pageOptions.cursor = cursor;
+      const response = await this.list(pageOptions);
+      for (const importItem of response.data) {
+        yield importItem;
+      }
+      if (!response.hasMore || !response.nextCursor) {
+        break;
+      }
+      cursor = response.nextCursor;
+    }
+  }
+  /**
+   * Collect all Imports into an array
+   * @param options Pagination options
+   * @returns Promise resolving to an array of all Imports
+   */
+  async getAll(options) {
+    const imports = [];
+    for await (const importItem of this.listAll(options)) {
+      imports.push(importItem);
+    }
+    return imports;
+  }
 };
 
 // src/websets/items.ts
@@ -976,6 +1043,38 @@ var WebsetMonitorsClient = class extends WebsetsBaseClient {
   async delete(id) {
     return this.request(`/v0/monitors/${id}`, "DELETE");
   }
+  /**
+   * Iterate through all Monitors, handling pagination automatically
+   * @param options Pagination and filtering options
+   * @returns Async generator of Monitors
+   */
+  async *listAll(options) {
+    let cursor = void 0;
+    const pageOptions = options ? { ...options } : {};
+    while (true) {
+      pageOptions.cursor = cursor;
+      const response = await this.list(pageOptions);
+      for (const monitor of response.data) {
+        yield monitor;
+      }
+      if (!response.hasMore || !response.nextCursor) {
+        break;
+      }
+      cursor = response.nextCursor;
+    }
+  }
+  /**
+   * Collect all Monitors into an array
+   * @param options Pagination and filtering options
+   * @returns Promise resolving to an array of all Monitors
+   */
+  async getAll(options) {
+    const monitors = [];
+    for await (const monitor of this.listAll(options)) {
+      monitors.push(monitor);
+    }
+    return monitors;
+  }
 };
 
 // src/websets/searches.ts
@@ -1351,6 +1450,7 @@ var Exa2 = class {
       extras,
       livecrawl,
       livecrawlTimeout,
+      maxAgeHours,
       context,
       ...rest
     } = options;
@@ -1377,6 +1477,7 @@ var Exa2 = class {
     if (livecrawl !== void 0) contentsOptions.livecrawl = livecrawl;
     if (livecrawlTimeout !== void 0)
       contentsOptions.livecrawlTimeout = livecrawlTimeout;
+    if (maxAgeHours !== void 0) contentsOptions.maxAgeHours = maxAgeHours;
     if (context !== void 0) contentsOptions.context = context;
     return {
       contentsOptions,
@@ -1641,7 +1742,8 @@ var Exa2 = class {
       stream: true,
       model: options?.model ?? "exa",
       systemPrompt: options?.systemPrompt,
-      outputSchema
+      outputSchema,
+      userLocation: options?.userLocation
     };
     const response = await fetchImpl(this.baseURL + "/answer", {
       method: "POST",