exa-js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2024 Hubert Yuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

package/README.md

@@ -0,0 +1 @@
+# exasearch

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+type BaseSearchOptions = {
+    numResults?: number;
+    includeDomains?: string[];
+    excludeDomains?: string[];
+    startCrawlDate?: string;
+    endCrawlDate?: string;
+    startPublishedDate?: string;
+    endPublishedDate?: string;
+    category?: string;
+};
+type RegularSearchOptions = BaseSearchOptions & {
+    useAutoprompt?: boolean;
+    type?: string;
+};
+type FindSimilarOptions = BaseSearchOptions & {
+    excludeSourceDomain?: boolean;
+};
+type ContentsOptions = {
+    text?: TextContentsOptions | boolean;
+    highlights?: HighlightsContentsOptions | boolean;
+};
+type TextContentsOptions = {
+    maxCharacters?: number;
+    includeHTMLTags?: boolean;
+};
+type HighlightsContentsOptions = {
+    query?: string;
+    numSentences?: number;
+    highlightsPerURL?: number;
+};
+type TextResponse = {
+    text: string;
+};
+type HighlightsResponse = {
+    highlights: string[];
+    highlightScores: number[];
+};
+type ContentsResultComponent<T extends ContentsOptions> = (T['text'] extends (object | true) ? TextResponse : {}) & (T['highlights'] extends (object | true) ? HighlightsResponse : {});
+type SearchResult<T extends ContentsOptions = {}> = {
+    title: string;
+    url: string;
+    publishedDate?: string;
+    author?: string;
+    score?: number;
+    id: string;
+} & ContentsResultComponent<T>;
+type SearchResponse<T extends ContentsOptions = {}> = {
+    results: SearchResult<T>[];
+    autopromptString?: string;
+};
+/**
+ * The Exa class encapsulates the API's endpoints.
+ */
+declare class Exa {
+    private baseURL;
+    private headers;
+    /**
+     * Constructs the Exa API client.
+     * @param {string} apiKey - The API key for authentication.
+     * @param {string} [baseURL] - The base URL of the Exa API.
+     */
+    constructor(apiKey?: string, baseURL?: string);
+    /**
+ * Makes a request to the Exa API.
+ * @param {string} endpoint - The API endpoint to call.
+ * @param {string} method - The HTTP method to use.
+ * @param {any} [body] - The request body for POST requests.
+ * @returns {Promise<any>} The response from the API.
+ */
+    private request;
+    /**
+     * Performs a search with a Exa prompt-engineered query.
+     * @param {string} query - The query string.
+     * @param {SearchOptions} [options] - Additional search options.
+     * @returns {Promise<SearchResponse>} A list of relevant search results.
+     */
+    search(query: string, options: RegularSearchOptions): Promise<SearchResponse>;
+    searchAndContents<T extends ContentsOptions>(query: string, options: RegularSearchOptions & T): Promise<SearchResponse<T>>;
+    /**
+     * Finds similar links to the provided URL.
+     * @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.
+     */
+    findSimilar(url: string, options?: FindSimilarOptions): Promise<SearchResponse>;
+    findSimilarAndContents<T extends ContentsOptions>(url: string, options: FindSimilarOptions & T): Promise<SearchResponse<T>>;
+    /**
+     * Retrieves contents of documents based on a list of document IDs.
+     * @param {string | string[] | SearchResult[]} ids - An array of document IDs.
+     * @param {ContentsOptions} [options] - Additional options for retrieving document contents.
+     * @returns {Promise<GetContentsResponse>} A list of document contents.
+     */
+    getContents<T extends ContentsOptions>(ids: string | string[] | SearchResult[], options?: T): Promise<SearchResponse<T>>;
+}
+
+export { BaseSearchOptions, ContentsOptions, FindSimilarOptions, HighlightsContentsOptions, RegularSearchOptions, SearchResponse, SearchResult, TextContentsOptions, Exa as default };

package/dist/index.js

@@ -0,0 +1,139 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  default: () => src_default
+});
+module.exports = __toCommonJS(src_exports);
+var import_cross_fetch = __toESM(require("cross-fetch"));
+var Exa = class {
+  /**
+   * Constructs the Exa API client.
+   * @param {string} apiKey - The API key for authentication.
+   * @param {string} [baseURL] - The base URL of the Exa API.
+   */
+  constructor(apiKey, baseURL = "https://api.exa.ai") {
+    this.baseURL = baseURL;
+    if (!apiKey) {
+      apiKey = process.env.EXASEARCH_API_KEY;
+      if (!apiKey) {
+        throw new Error("API key must be provided as an argument or as an environment variable (EXASEARCH_API_KEY)");
+      }
+    }
+    this.headers = new import_cross_fetch.Headers({
+      "x-api-key": apiKey,
+      "Content-Type": "application/json",
+      "User-Agent": "exa-node 1.0.27"
+    });
+  }
+  /**
+  * Makes a request to the Exa API.
+  * @param {string} endpoint - The API endpoint to call.
+  * @param {string} method - The HTTP method to use.
+  * @param {any} [body] - The request body for POST requests.
+  * @returns {Promise<any>} The response from the API.
+  */
+  async request(endpoint, method, body) {
+    const response = await (0, import_cross_fetch.default)(this.baseURL + endpoint, {
+      method,
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!response.ok) {
+      const message = (await response.json()).error;
+      throw new Error(
+        `Request failed with status ${response.status}. ${message}`
+      );
+    }
+    return await response.json();
+  }
+  /**
+   * Performs a search with a Exa prompt-engineered query.
+   * @param {string} query - The query string.
+   * @param {SearchOptions} [options] - Additional search options.
+   * @returns {Promise<SearchResponse>} A list of relevant search results.
+   */
+  async search(query, options) {
+    return await this.request("/search", "POST", { query, ...options });
+  }
+  async searchAndContents(query, options) {
+    const { text, highlights, ...rest } = options;
+    return await this.request("/search", "POST", {
+      query,
+      contents: {
+        ...text ? { text } : {},
+        ...highlights ? { highlights } : {}
+      },
+      ...rest
+    });
+  }
+  /**
+   * Finds similar links to the provided URL.
+   * @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.
+   */
+  async findSimilar(url, options) {
+    return await this.request("/findSimilar", "POST", { url, ...options });
+  }
+  async findSimilarAndContents(url, options) {
+    const { text, highlights, ...rest } = options;
+    return await this.request("/findSimilar", "POST", {
+      url,
+      contents: {
+        ...text ? { text } : {},
+        ...highlights ? { highlights } : {}
+      },
+      ...rest
+    });
+  }
+  /**
+   * Retrieves contents of documents based on a list of document IDs.
+   * @param {string | string[] | SearchResult[]} ids - An array of document IDs.
+   * @param {ContentsOptions} [options] - Additional options for retrieving document contents.
+   * @returns {Promise<GetContentsResponse>} A list of document contents.
+   */
+  async getContents(ids, options) {
+    if (ids.length === 0) {
+      throw new Error("Must provide at least one ID");
+    }
+    let requestIds;
+    if (typeof ids === "string") {
+      requestIds = [ids];
+    } else if (typeof ids[0] === "string") {
+      requestIds = ids;
+    } else {
+      requestIds = ids.map((result) => result.id);
+    }
+    return await this.request(`/contents`, "POST", { ids: requestIds, ...options });
+  }
+};
+var src_default = Exa;

package/dist/index.mjs

@@ -0,0 +1,108 @@
+// src/index.ts
+import fetch, { Headers } from "cross-fetch";
+var Exa = class {
+  /**
+   * Constructs the Exa API client.
+   * @param {string} apiKey - The API key for authentication.
+   * @param {string} [baseURL] - The base URL of the Exa API.
+   */
+  constructor(apiKey, baseURL = "https://api.exa.ai") {
+    this.baseURL = baseURL;
+    if (!apiKey) {
+      apiKey = process.env.EXASEARCH_API_KEY;
+      if (!apiKey) {
+        throw new Error("API key must be provided as an argument or as an environment variable (EXASEARCH_API_KEY)");
+      }
+    }
+    this.headers = new Headers({
+      "x-api-key": apiKey,
+      "Content-Type": "application/json",
+      "User-Agent": "exa-node 1.0.27"
+    });
+  }
+  /**
+  * Makes a request to the Exa API.
+  * @param {string} endpoint - The API endpoint to call.
+  * @param {string} method - The HTTP method to use.
+  * @param {any} [body] - The request body for POST requests.
+  * @returns {Promise<any>} The response from the API.
+  */
+  async request(endpoint, method, body) {
+    const response = await fetch(this.baseURL + endpoint, {
+      method,
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!response.ok) {
+      const message = (await response.json()).error;
+      throw new Error(
+        `Request failed with status ${response.status}. ${message}`
+      );
+    }
+    return await response.json();
+  }
+  /**
+   * Performs a search with a Exa prompt-engineered query.
+   * @param {string} query - The query string.
+   * @param {SearchOptions} [options] - Additional search options.
+   * @returns {Promise<SearchResponse>} A list of relevant search results.
+   */
+  async search(query, options) {
+    return await this.request("/search", "POST", { query, ...options });
+  }
+  async searchAndContents(query, options) {
+    const { text, highlights, ...rest } = options;
+    return await this.request("/search", "POST", {
+      query,
+      contents: {
+        ...text ? { text } : {},
+        ...highlights ? { highlights } : {}
+      },
+      ...rest
+    });
+  }
+  /**
+   * Finds similar links to the provided URL.
+   * @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.
+   */
+  async findSimilar(url, options) {
+    return await this.request("/findSimilar", "POST", { url, ...options });
+  }
+  async findSimilarAndContents(url, options) {
+    const { text, highlights, ...rest } = options;
+    return await this.request("/findSimilar", "POST", {
+      url,
+      contents: {
+        ...text ? { text } : {},
+        ...highlights ? { highlights } : {}
+      },
+      ...rest
+    });
+  }
+  /**
+   * Retrieves contents of documents based on a list of document IDs.
+   * @param {string | string[] | SearchResult[]} ids - An array of document IDs.
+   * @param {ContentsOptions} [options] - Additional options for retrieving document contents.
+   * @returns {Promise<GetContentsResponse>} A list of document contents.
+   */
+  async getContents(ids, options) {
+    if (ids.length === 0) {
+      throw new Error("Must provide at least one ID");
+    }
+    let requestIds;
+    if (typeof ids === "string") {
+      requestIds = [ids];
+    } else if (typeof ids[0] === "string") {
+      requestIds = ids;
+    } else {
+      requestIds = ids.map((result) => result.id);
+    }
+    return await this.request(`/contents`, "POST", { ids: requestIds, ...options });
+  }
+};
+var src_default = Exa;
+export {
+  src_default as default
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "exa-js",
+  "version": "1.0.0",
+  "description": "Exasearch SDK for Node.js and the browser",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "exports": {
+    "require": "./dist/index.js",
+    "import": "./dist/index.mjs"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build-fast": "tsup src/index.ts --format cjs,esm",
+    "build": "pnpm run build-fast --dts-resolve",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm run build"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "prettier": "2.8.4",
+    "tsup": "6.6.3",
+    "typescript": "4.9.5",
+    "vitest": "0.28.5"
+  },
+  "dependencies": {
+    "cross-fetch": "^4.0.0"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HubertY/exanodesdk.git"
+  },
+  "keywords": [
+    "exa",
+    "metaphor",
+    "search",
+    "AI",
+    "LLMs",
+    "RAG",
+    "retrieval",
+    "augmented",
+    "generation"
+  ],
+  "author": "jeffzwang",
+  "bugs": {
+    "url": "https://github.com/HubertY/exanodesdk/issues"
+  },
+  "homepage": "https://github.com/HubertY/exanodesdk#readme"
+}