Clearbit Node.js Client

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` in an ES Module context (`type: 'module'` in package.json or `.mjs` file).
  fix Change your file to a CommonJS context (e.g., `.js` file without `type: 'module'`) or use a bundler that transpiles CJS. This package is CJS-only.

• Error: Missing Clearbit API Key

  cause The API key was not provided during client initialization.
  fix Ensure `require('clearbit')('YOUR_API_KEY')` has a valid key string, or when using `new Client({ key: 'YOUR_API_KEY' })`, that the `key` property is set.

• TypeError: clearbit(...) is not a function

  cause You might be trying to call `clearbit()` after already initializing it once, or attempting to use `clearbit.Client` incorrectly.
  fix Ensure you are using `require('clearbit')(API_KEY)` for the initial factory function call, or `const Client = require('clearbit').Client; new Client({ key: API_KEY });` for the constructor.

• UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch().

  cause Failure to catch rejections from the API calls, especially `QueuedError` or `NotFoundError` if not explicitly handled.
  fix Always attach a `.catch()` block to your Promise chains or use `try...catch` with `async/await` to handle all possible errors, including Clearbit's custom error types.

Warnings

• breaking This package (`clearbit@1.3.5`) is abandoned and has not been updated in over eight years. It is highly recommended to avoid using it in new projects due to potential security vulnerabilities from outdated dependencies, lack of bug fixes, and compatibility issues with modern Node.js runtimes.
  Fix: Consider migrating to Clearbit's newer API versions directly via an HTTP client or seeking alternative, actively maintained libraries if available. Clearbit's API documentation should be consulted for direct integration options.
• gotcha The library is exclusively CommonJS (`require`) and does not support ES Modules (`import`) directly. Attempting to use `import` syntax will result in errors.
  Fix: Ensure your project is configured for CommonJS, or use a bundler that can transpile CommonJS to ESM if necessary. For modern Node.js, stick to `require()` or use a different library.
• gotcha Error handling relies on custom error classes (e.g., `Person.QueuedError`, `Company.NotFoundError`) which might not behave as expected or integrate seamlessly with standard `try/catch` blocks without explicit `instanceof` checks. This pattern is common in older Promise libraries like Bluebird, which may differ from native Promises.
  Fix: Always use `instanceof` to catch specific Clearbit errors, as demonstrated in the quickstart. Be aware that the Promise implementation might not be fully compliant with modern Promise A+ specifications, which could lead to unexpected behavior in complex asynchronous flows.
• gotcha The client is designed for synchronous API key initialization upon `require('clearbit')`, which can be problematic for dynamic API key management or serverless functions where environment variables might not be immediately available during module loading.
  Fix: Ensure `process.env.CLEARBIT_API_KEY` is set before the module is `require`d. For more dynamic scenarios, use `new Client({ key: 'api_key' })` after `const Client = require('clearbit').Client;` to instantiate with a runtime-provided key.

Install

• npm install clearbit npm
• yarn add clearbit yarn
• pnpm add clearbit pnpm

Imports

• clearbit
  wrong:

  import clearbit from 'clearbit';

  correct:

  const clearbit = require('clearbit')(process.env.CLEARBIT_API_KEY);

  The primary way to initialize the client in CommonJS. Direct ESM import is not supported.
• Client
  wrong:

  import { Client } from 'clearbit';

  correct:

  const Client = require('clearbit').Client;

  Accesses the Client constructor directly for alternative initialization. CommonJS only.
• Person
  wrong:

  const Person = require('clearbit').Person;

  correct:

  const { Person } = clearbit;

  API modules like Person, Company, etc., are accessed as properties of the initialized client instance, not directly from the package root.

Quickstart

Demonstrates initializing the Clearbit client using an API key from environment variables, and performing basic lookups for a person by email and a company by domain, including specific error handling for Clearbit's `QueuedError` and `NotFoundError`.

const clearbit = require('clearbit')(process.env.CLEARBIT_API_KEY ?? '');

if (!process.env.CLEARBIT_API_KEY) {
  console.error('ERROR: CLEARBIT_API_KEY environment variable is not set.');
  process.exit(1);
}

const Person = clearbit.Person;
const Company = clearbit.Company;

async function lookupData() {
  try {
    console.log('--- Looking up Person ---');
    const person = await Person.find({ email: 'alex@clearbit.com' });
    console.log('Person Name:', person.name.fullName);
    console.log('Person Title:', person.employment.title);
  } catch (err) {
    if (err instanceof Person.QueuedError) {
      console.log('Person lookup queued:', err.message);
    } else if (err instanceof Person.NotFoundError) {
      console.log('Person not found:', err.message);
    } else {
      console.error('Error looking up person:', err.message);
    }
  }

  try {
    console.log('\n--- Looking up Company ---');
    const company = await Company.find({ domain: 'clearbit.com' });
    console.log('Company Name:', company.name);
    console.log('Company Sector:', company.category.sector);
  } catch (err) {
    if (err instanceof Company.QueuedError) {
      console.log('Company lookup queued:', err.message);
    } else if (err instanceof Company.NotFoundError) {
      console.log('Company not found:', err.message);
    } else {
      console.error('Error looking up company:', err.message);
    }
  }
}

lookupData();