exa-js 1.10.2 → 2.0.2

package/dist/index.d.mts

@@ -1549,14 +1549,16 @@ interface components {
             type: "person";
         };
         PreviewWebsetParameters: {
-            /** @description Entity used to inform the decomposition.
-             *
-             *     It is not required to provide it, we automatically detect the entity from all the information provided in the query. Only use this when you need more fine control. */
-            entity?: components["schemas"]["Entity"];
-            /** @description Natural language search query describing what you are looking for.
-             *
-             *     Be specific and descriptive about your requirements, characteristics, and any constraints that help narrow down the results. */
-            query: string;
+            search: {
+                /** @description Entity used to inform the decomposition.
+                 *
+                 *     It is not required to provide it, we automatically detect the entity from all the information provided in the query. Only use this when you need more fine control. */
+                entity?: components["schemas"]["Entity"];
+                /** @description Natural language search query describing what you are looking for.
+                 *
+                 *     Be specific and descriptive about your requirements, characteristics, and any constraints that help narrow down the results. */
+                query: string;
+            };
         };
         PreviewWebsetResponse: {
             /** @description Detected enrichments from the query. */
@@ -1734,6 +1736,12 @@ interface components {
             createdAt: string;
             /** @description The Enrichments to apply to the Webset Items. */
             enrichments: components["schemas"]["WebsetEnrichment"][];
+            /** @description The Excludes sources (existing imports or websets) that apply to all operations within this Webset. Any results found within these sources will be omitted across all search and import operations. */
+            excludes?: {
+                id: string;
+                /** @enum {string} */
+                source: WebsetExcludeSource;
+            }[];
             /** @description The external identifier for the webset */
             externalId: string | null;
             /** @description The unique identifier for the webset */
@@ -1762,8 +1770,6 @@ interface components {
              * @enum {string}
              */
             status: WebsetStatus;
-            /** @description The Streams for the Webset. */
-            streams: unknown[];
             /** @description The title of the webset */
             title: string | null;
             /**
@@ -2965,10 +2971,33 @@ declare class ExaError extends Error {
     constructor(message: string, statusCode: number, timestamp?: string, path?: string);
 }
 
-declare const isBeta = false;
 /**
- * Search options for performing a search query.
+ * Options for retrieving page contents
+ * @typedef {Object} ContentsOptions
+ * @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
+ * @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 {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.
+ * @property {ExtrasOptions} [extras] - Miscelleneous data derived from results
+ */
+type ContentsOptions = {
+    text?: TextContentsOptions | true;
+    summary?: SummaryContentsOptions | true;
+    livecrawl?: LivecrawlOptions;
+    context?: ContextOptions | true;
+    livecrawlTimeout?: number;
+    filterEmptyResults?: boolean;
+    subpages?: number;
+    subpageTarget?: string | string[];
+    extras?: ExtrasOptions;
+};
+/**
+ * Options for performing a search query
  * @typedef {Object} SearchOptions
+ * @property {ContentsOptions | boolean} [contents] - Options for retrieving page contents for each result returned. Default is { text: { maxCharacters: 10_000 } }.
  * @property {number} [numResults] - Number of search results to return. Default 10. Max 10 for basic plans.
  * @property {string[]} [includeDomains] - List of domains to include in the search.
  * @property {string[]} [excludeDomains] - List of domains to exclude in the search.
@@ -2983,6 +3012,7 @@ declare const isBeta = false;
  * @property {string} [userLocation] - The two-letter ISO country code of the user, e.g. US.
  */
 type BaseSearchOptions = {
+    contents?: ContentsOptions;
     numResults?: number;
     includeDomains?: string[];
     excludeDomains?: string[];
@@ -3020,31 +3050,6 @@ type ExtrasOptions = {
     links?: number;
     imageLinks?: number;
 };
-/**
- * Search options for performing a search query.
- * @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 {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 {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.
- * @property {ExtrasOptions} [extras] - Miscelleneous data derived from results
- */
-type ContentsOptions = {
-    text?: TextContentsOptions | true;
-    highlights?: HighlightsContentsOptions | true;
-    summary?: SummaryContentsOptions | true;
-    livecrawl?: LivecrawlOptions;
-    context?: ContextOptions | true;
-    livecrawlTimeout?: number;
-    filterEmptyResults?: boolean;
-    subpages?: number;
-    subpageTarget?: string | string[];
-    extras?: ExtrasOptions;
-} & (typeof isBeta extends true ? {} : {});
 /**
  * Options for livecrawling contents
  * @typedef {string} LivecrawlOptions
@@ -3060,20 +3065,6 @@ type TextContentsOptions = {
     maxCharacters?: number;
     includeHtmlTags?: boolean;
 };
-/**
- * Options for retrieving highlights from page.
- * NOTE: For search type "deep", these options will not be respected. Highlights will be generated with respect
- * 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.
- */
-type HighlightsContentsOptions = {
-    query?: string;
-    numSentences?: number;
-    highlightsPerUrl?: number;
-};
 /**
  * Options for retrieving summary from page.
  * @typedef {Object} SummaryContentsOptions
@@ -3104,15 +3095,6 @@ type ContextOptions = {
 type TextResponse = {
     text: string;
 };
-/**
- * @typedef {Object} HighlightsResponse
- * @property {string[]} highlights - The highlights as an array of strings.
- * @property {number[]} highlightScores - The corresponding scores as an array of floats, 0 to 1
- */
-type HighlightsResponse = {
-    highlights: string[];
-    highlightScores: number[];
-};
 /**
  * @typedef {Object} SummaryResponse
  * @property {string} summary - The generated summary of the page content.
@@ -3141,22 +3123,20 @@ type SubpagesResponse<T extends ContentsOptions> = {
 type Default<T extends {}, U> = [keyof T] extends [never] ? U : T;
 /**
  * @typedef {Object} ContentsResultComponent
- * Depending on 'ContentsOptions', this yields a combination of 'TextResponse', 'HighlightsResponse', 'SummaryResponse', or an empty object.
+ * Depending on 'ContentsOptions', this yields a combination of 'TextResponse', 'SummaryResponse', or an empty object.
  *
  * @template T - A type extending from 'ContentsOptions'.
  */
-type ContentsResultComponent<T extends ContentsOptions> = Default<(T["text"] extends object | true ? TextResponse : {}) & (T["highlights"] extends object | true ? HighlightsResponse : {}) & (T["summary"] extends object | true ? SummaryResponse : {}) & (T["subpages"] extends number ? SubpagesResponse<T> : {}) & (T["extras"] extends object ? ExtrasResponse : {}), TextResponse>;
+type ContentsResultComponent<T extends ContentsOptions> = (T["text"] extends object | true ? TextResponse : {}) & (T["summary"] extends object | true ? SummaryResponse : {}) & (T["subpages"] extends number ? SubpagesResponse<T> : {}) & (T["extras"] extends object ? ExtrasResponse : {});
 /**
  * Represents the cost breakdown related to contents retrieval. Fields are optional because
  * only non-zero costs are included.
  * @typedef {Object} CostDollarsContents
  * @property {number} [text] - The cost in dollars for retrieving text.
- * @property {number} [highlights] - The cost in dollars for retrieving highlights.
  * @property {number} [summary] - The cost in dollars for retrieving summary.
  */
 type CostDollarsContents = {
     text?: number;
-    highlights?: number;
     summary?: number;
 };
 /**
@@ -3209,7 +3189,6 @@ type SearchResult<T extends ContentsOptions> = {
  * @typedef {Object} SearchResponse
  * @property {Result[]} results - The list of search results.
  * @property {string} [context] - The context for the search.
- * @property {string} [autopromptString] - The autoprompt string, if applicable.
  * @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.
@@ -3217,7 +3196,6 @@ type SearchResult<T extends ContentsOptions> = {
 type SearchResponse<T extends ContentsOptions> = {
     results: SearchResult<T>[];
     context?: string;
-    autopromptString?: string;
     autoDate?: string;
     requestId: string;
     statuses?: Array<Status>;
@@ -3341,13 +3319,55 @@ declare class Exa {
     rawRequest(endpoint: string, method?: string, body?: Record<string, unknown>, queryParams?: Record<string, string | number | boolean | string[] | undefined>): Promise<Response>;
     /**
      * Performs a search with an Exa prompt-engineered query.
+     * By default, returns text contents. Use contents: false to opt-out.
+     *
+     * @param {string} query - The query string.
+     * @returns {Promise<SearchResponse<{ text: { maxCharacters: 10_000 } }>>} A list of relevant search results with text contents.
+     */
+    search(query: string): Promise<SearchResponse<{
+        text: {
+            maxCharacters: 10_000;
+        };
+    }>>;
+    /**
+     * Performs a search without contents.
+     *
+     * @param {string} query - The query string.
+     * @param {RegularSearchOptions & { contents: false }} options - Search options with contents explicitly disabled
+     * @returns {Promise<SearchResponse<{}>>} A list of relevant search results without contents.
+     */
+    search(query: string, options: RegularSearchOptions & {
+        contents: false | null | undefined;
+    }): Promise<SearchResponse<{}>>;
+    /**
+     * Performs a search with specific contents.
+     *
+     * @param {string} query - The query string.
+     * @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
+     * @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
+     */
+    search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & {
+        contents: T;
+    }): Promise<SearchResponse<T>>;
+    /**
+     * Performs a search with an Exa prompt-engineered query.
+     * When no contents option is specified, returns text contents by default.
      *
      * @param {string} query - The query string.
-     * @param {RegularSearchOptions} [options] - Additional search options
-     * @returns {Promise<SearchResponse<{}>>} A list of relevant search results.
+     * @param {Omit<RegularSearchOptions, 'contents'>} options - Search options without contents
+     * @returns {Promise<SearchResponse<{ text: true }>>} A list of relevant search results with text contents.
      */
-    search(query: string, options?: RegularSearchOptions): Promise<SearchResponse<{}>>;
+    search(query: string, options: Omit<RegularSearchOptions, "contents">): Promise<SearchResponse<{
+        text: true;
+    }>>;
     /**
+     * @deprecated Use `search()` instead. The search method now returns text contents by default.
+     *
+     * Migration examples:
+     * - `searchAndContents(query)` → `search(query)`
+     * - `searchAndContents(query, { text: true })` → `search(query, { contents: { text: true } })`
+     * - `searchAndContents(query, { summary: true })` → `search(query, { contents: { summary: true } })`
+     *
      * Performs a search with an Exa prompt-engineered query and returns the contents of the documents.
      *
      * @param {string} query - The query string.
@@ -3357,12 +3377,55 @@ declare class Exa {
     searchAndContents<T extends ContentsOptions>(query: string, options?: RegularSearchOptions & T): Promise<SearchResponse<T>>;
     /**
      * Finds similar links to the provided URL.
+     * By default, returns text contents. Use contents: false to opt-out.
+     *
+     * @param {string} url - The URL for which to find similar links.
+     * @returns {Promise<SearchResponse<{ text: { maxCharacters: 10_000 } }>>} A list of similar search results with text contents.
+     */
+    findSimilar(url: string): Promise<SearchResponse<{
+        text: {
+            maxCharacters: 10_000;
+        };
+    }>>;
+    /**
+     * Finds similar links to the provided URL without contents.
+     *
+     * @param {string} url - The URL for which to find similar links.
+     * @param {FindSimilarOptions & { contents: false }} options - Options with contents explicitly disabled
+     * @returns {Promise<SearchResponse<{}>>} A list of similar search results without contents.
+     */
+    findSimilar(url: string, options: FindSimilarOptions & {
+        contents: false | null | undefined;
+    }): Promise<SearchResponse<{}>>;
+    /**
+     * Finds similar links to the provided URL with specific contents.
+     *
+     * @param {string} url - The URL for which to find similar links.
+     * @param {FindSimilarOptions & { contents: T }} options - Options with specific contents
+     * @returns {Promise<SearchResponse<T>>} A list of similar search results with requested contents.
+     */
+    findSimilar<T extends ContentsOptions>(url: string, options: FindSimilarOptions & {
+        contents: T;
+    }): Promise<SearchResponse<T>>;
+    /**
+     * Finds similar links to the provided URL.
+     * When no contents option is specified, returns text contents by default.
+     *
      * @param {string} url - The URL for which to find similar links.
-     * @param {FindSimilarOptions} [options] - Additional options for finding similar links.
-     * @returns {Promise<SearchResponse<{}>>} A list of similar search results.
+     * @param {Omit<FindSimilarOptions, 'contents'>} options - Options without contents
+     * @returns {Promise<SearchResponse<{ text: true }>>} A list of similar search results with text contents.
      */
-    findSimilar(url: string, options?: FindSimilarOptions): Promise<SearchResponse<{}>>;
+    findSimilar(url: string, options: Omit<FindSimilarOptions, "contents">): Promise<SearchResponse<{
+        text: true;
+    }>>;
     /**
+     * @deprecated Use `findSimilar()` instead. The findSimilar method now returns text contents by default.
+     *
+     * Migration examples:
+     * - `findSimilarAndContents(url)` → `findSimilar(url)`
+     * - `findSimilarAndContents(url, { text: true })` → `findSimilar(url, { contents: { text: true } })`
+     * - `findSimilarAndContents(url, { summary: true })` → `findSimilar(url, { contents: { summary: true } })`
+     *
      * Finds similar links to the provided URL and returns the contents of the documents.
      * @param {string} url - The URL for which to find similar links.
      * @param {FindSimilarOptions & T} [options] - Additional options for finding similar links + contents.
@@ -3442,4 +3505,4 @@ declare class Exa {
     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 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 Event, EventType, EventsClient, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, 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 };