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/dist/index.d.ts 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;
package/dist/index.js CHANGED
@@ -74,7 +74,7 @@ var import_cross_fetch = __toESM(require("cross-fetch"));
74
74
  // package.json
75
75
  var package_default = {
76
76
  name: "exa-js",
77
- version: "2.2.0",
77
+ version: "2.4.0",
78
78
  description: "Exa SDK for Node.js and the browser",
79
79
  publishConfig: {
80
80
  access: "public"
@@ -497,6 +497,38 @@ var EventsClient = class extends WebsetsBaseClient {
497
497
  async get(id) {
498
498
  return this.request(`/v0/events/${id}`, "GET");
499
499
  }
500
+ /**
501
+ * Iterate through all Events, handling pagination automatically
502
+ * @param options Filtering and pagination options
503
+ * @returns Async generator of Events
504
+ */
505
+ async *listAll(options) {
506
+ let cursor = void 0;
507
+ const pageOptions = options ? { ...options } : {};
508
+ while (true) {
509
+ pageOptions.cursor = cursor;
510
+ const response = await this.list(pageOptions);
511
+ for (const event of response.data) {
512
+ yield event;
513
+ }
514
+ if (!response.hasMore || !response.nextCursor) {
515
+ break;
516
+ }
517
+ cursor = response.nextCursor;
518
+ }
519
+ }
520
+ /**
521
+ * Collect all Events into an array
522
+ * @param options Filtering and pagination options
523
+ * @returns Promise resolving to an array of all Events
524
+ */
525
+ async getAll(options) {
526
+ const events = [];
527
+ for await (const event of this.listAll(options)) {
528
+ events.push(event);
529
+ }
530
+ return events;
531
+ }
500
532
  };
501
533
 
502
534
  // src/websets/openapi.ts
@@ -811,6 +843,38 @@ var ImportsClient = class extends WebsetsBaseClient {
811
843
  await new Promise((resolve) => setTimeout(resolve, pollInterval));
812
844
  }
813
845
  }
846
+ /**
847
+ * Iterate through all Imports, handling pagination automatically
848
+ * @param options Pagination options
849
+ * @returns Async generator of Imports
850
+ */
851
+ async *listAll(options) {
852
+ let cursor = void 0;
853
+ const pageOptions = options ? { ...options } : {};
854
+ while (true) {
855
+ pageOptions.cursor = cursor;
856
+ const response = await this.list(pageOptions);
857
+ for (const importItem of response.data) {
858
+ yield importItem;
859
+ }
860
+ if (!response.hasMore || !response.nextCursor) {
861
+ break;
862
+ }
863
+ cursor = response.nextCursor;
864
+ }
865
+ }
866
+ /**
867
+ * Collect all Imports into an array
868
+ * @param options Pagination options
869
+ * @returns Promise resolving to an array of all Imports
870
+ */
871
+ async getAll(options) {
872
+ const imports = [];
873
+ for await (const importItem of this.listAll(options)) {
874
+ imports.push(importItem);
875
+ }
876
+ return imports;
877
+ }
814
878
  };
815
879
 
816
880
  // src/websets/items.ts
@@ -979,6 +1043,38 @@ var WebsetMonitorsClient = class extends WebsetsBaseClient {
979
1043
  async delete(id) {
980
1044
  return this.request(`/v0/monitors/${id}`, "DELETE");
981
1045
  }
1046
+ /**
1047
+ * Iterate through all Monitors, handling pagination automatically
1048
+ * @param options Pagination and filtering options
1049
+ * @returns Async generator of Monitors
1050
+ */
1051
+ async *listAll(options) {
1052
+ let cursor = void 0;
1053
+ const pageOptions = options ? { ...options } : {};
1054
+ while (true) {
1055
+ pageOptions.cursor = cursor;
1056
+ const response = await this.list(pageOptions);
1057
+ for (const monitor of response.data) {
1058
+ yield monitor;
1059
+ }
1060
+ if (!response.hasMore || !response.nextCursor) {
1061
+ break;
1062
+ }
1063
+ cursor = response.nextCursor;
1064
+ }
1065
+ }
1066
+ /**
1067
+ * Collect all Monitors into an array
1068
+ * @param options Pagination and filtering options
1069
+ * @returns Promise resolving to an array of all Monitors
1070
+ */
1071
+ async getAll(options) {
1072
+ const monitors = [];
1073
+ for await (const monitor of this.listAll(options)) {
1074
+ monitors.push(monitor);
1075
+ }
1076
+ return monitors;
1077
+ }
982
1078
  };
983
1079
 
984
1080
  // src/websets/searches.ts
@@ -1646,7 +1742,8 @@ var Exa2 = class {
1646
1742
  stream: true,
1647
1743
  model: options?.model ?? "exa",
1648
1744
  systemPrompt: options?.systemPrompt,
1649
- outputSchema
1745
+ outputSchema,
1746
+ userLocation: options?.userLocation
1650
1747
  };
1651
1748
  const response = await fetchImpl(this.baseURL + "/answer", {
1652
1749
  method: "POST",