The `metaphor-node` package serves as the official JavaScript/TypeScript SDK for programmatically interacting with the Metaphor search API. It provides a robust client for accessing Metaphor's core functionalities, which include executing targeted searches, identifying content similar to a given URL, and retrieving the full textual contents of documents using their unique identifiers. Designed primarily for Node.js environments, the SDK is fully typed with TypeScript, enhancing developer experience and compile-time safety. The package is actively maintained within its `1.x.x` series, with recent updates such as `v1.5.13` reflecting ongoing development and feature enhancements. Internally, it utilizes `cross-fetch` to ensure broad compatibility for HTTP requests across different JavaScript runtimes, abstracting the complexities of underlying fetch implementations. This SDK is crucial for developers looking to integrate advanced, intelligent search and content discovery capabilities into their server-side applications with a straightforward and idiomatic API.
npm install metaphor-nodeVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to install, initialize, and perform a basic search using the Metaphor Node.js SDK, including fetching content for a result. It highlights the use of environment variables for the API key and includes basic error handling for asynchronous operations.
Store your API key in a `.env` file or use a secure secret management system, loading it into `process.env` at runtime. E.g., `METAPHOR_API_KEY=your_key node your-app.js` or use `dotenv`.
For CommonJS, try `const Metaphor = require('metaphor-node').default;`. Consider migrating to ESM or using a transpiler like Babel if your project requires full ESM compatibility.Wrap all Metaphor SDK calls in `try...catch` blocks when using `async/await`, or use `.catch()` with Promises, to handle and log errors appropriately.
Ensure `new Metaphor(process.env.METAPHOR_API_KEY)` receives a valid API key string. Verify `process.env.METAPHOR_API_KEY` is correctly set and accessible in your environment.
Ensure your code is running in a Node.js environment or, if targeting the browser, bundle your application using a tool like Webpack or Rollup and provide appropriate polyfills for Node.js globals.
Double-check your `METAPHOR_API_KEY` for correctness. Ensure it has the necessary permissions for the API calls you are making.
Implement exponential backoff or other rate-limiting strategies in your application to reduce the frequency of API requests. Review Metaphor's API documentation for specific rate limit details.