Lago JavaScript API Client

Common errors

• ReferenceError: fetch is not defined

  cause Node.js version is older than 18, or the `--experimental-fetch` flag is not used, and no polyfill for `fetch` is provided.
  fix Upgrade Node.js to version 18 or higher, or install `node-fetch` and pass it as a `customFetch` option to the `Client` constructor. Alternatively, run Node.js with `node --experimental-fetch your-script.js`.

• TypeError: (0 , lago_javascript_client__WEBPACK_IMPORTED_MODULE_0__.Client) is not a function

  cause This error often occurs in environments where CommonJS `require()` is implicitly or explicitly trying to load an ES Module library that primarily uses named exports, or when bundlers mishandle the module type.
  fix Ensure you are using ES Module `import { Client } from 'lago-javascript-client';` syntax throughout your project. Verify your `tsconfig.json` (if TypeScript) and bundler configuration (`module` and `moduleResolution`) are set for `ESNext` or `NodeNext` to properly handle ESM.

Warnings

• breaking The Lago JavaScript Client relies on the Fetch API. Node.js versions prior to 18 do not support Fetch natively. Attempting to use the client without a polyfill or the `--experimental-fetch` flag will result in runtime errors.
  Fix: For Node.js < 18, either start Node.js with `--experimental-fetch` or install and pass `node-fetch` as a custom fetch implementation: `import fetch from 'node-fetch'; const lagoClient = Client('key', { customFetch: fetch });`
• gotcha The package is built with `dnt` to support multiple runtimes (Node.js, Deno, Cloudflare Workers). This means its primary module format is ESM. While some interoperability exists, mixing `require()` with this library can lead to unexpected behavior or require additional configuration.
  Fix: Always use ES Module `import` syntax (`import { Client } from 'lago-javascript-client';`) for consistency and full TypeScript support.
• deprecated The previous `lago-nodejs-client` package is deprecated in favor of `lago-javascript-client` which offers TypeScript support and broader runtime compatibility. Users of the old package should migrate.
  Fix: Update your `package.json` to `lago-javascript-client` and refactor imports and usage according to the new client's API.
• breaking The underlying Lago API, which this client wraps, has undergone significant changes in how 'groups' are handled, replaced by 'filters', and has made `external_subscription_id` mandatory for events. Several legacy API fields have also been deprecated. These changes will impact how you define and send billing data.
  Fix: Refer to the official Lago API documentation (doc.getlago.com) for the specific changes and update your data models and API calls accordingly, especially regarding billable metrics, plans, fees, customer usage, and events. Users were advised to update before July 9, 2024.

Install

• npm install lago-javascript-client npm
• yarn add lago-javascript-client yarn
• pnpm add lago-javascript-client pnpm

Imports

• Client
  wrong:

  const { Client } = require('lago-javascript-client');

  correct:

  import { Client } from 'lago-javascript-client';

  The library primarily uses ES Modules. While Node.js has some CJS-ESM interoperability, using `import` is the recommended and type-safe approach.
• getLagoError
  wrong:

  const { getLagoError } = require('lago-javascript-client');

  correct:

  import { getLagoError } from 'lago-javascript-client';

  Used for robust error handling and type extraction from API responses. Follows the ESM import pattern.
• Client

  import { Client } from 'https://deno.land/x/lago/mod.ts';

  For Deno environments, import directly from the Deno Land URL.

Quickstart

This quickstart demonstrates how to initialize the Lago client, configure it for Node.js compatibility (if needed), and perform an asynchronous API call to create a billable metric with proper error handling.

import { Client, getLagoError } from 'lago-javascript-client';
import fetch from 'node-fetch'; // Required for Node.js < 18 or without --experimental-fetch

// Initialize the client with your API key.
// For Node.js < 18, you might need to pass a custom fetch instance.
const lagoClient = Client(process.env.LAGO_API_KEY ?? '', { customFetch: fetch });

async function createBillableMetric() {
  const billableMetric = {
    billableMetric: {
      name: 'api_calls',
      code: 'api_calls',
      aggregation_type: 'count',
      description: 'Number of API calls made.'
    }
  };

  try {
    // Example: Creating a new billable metric
    const { data } = await lagoClient.billableMetrics.createBillableMetric(billableMetric);
    console.log('Successfully created billable metric:', data);
  } catch (error) {
    // Use getLagoError for structured error handling and type inference
    const lagoError = await getLagoError(error);
    console.error('Error creating billable metric:', lagoError.message, lagoError.response);
  }
}

createBillableMetric();