{"id":11220,"library":"lago-javascript-client","title":"Lago JavaScript API Client","description":"The `lago-javascript-client` is an official JavaScript wrapper for interacting with the Lago API, providing a structured way to manage billing and invoicing operations. It is currently at version 1.45.0, with frequent minor releases indicated by the recent changelog, often involving version bumps. This client is notable for its broad compatibility, designed to function across various JavaScript runtimes including Node.js (specifically Node.js >= 18 for native support), Cloudflare Workers, and Deno. It is automatically generated from the Lago OpenAPI document, ensuring it stays synchronized with the API's latest specifications. A key architectural decision is its reliance on the Fetch API for HTTP requests, which means users on older Node.js environments (pre-18) must either enable `--experimental-fetch` or provide a custom Fetch implementation like `node-fetch`. The library also ships with TypeScript types, facilitating robust development and error handling using its `getLagoError` utility.","status":"active","version":"1.45.0","language":"javascript","source_language":"en","source_url":"https://github.com/getlago/lago-javascript-client","tags":["javascript","Lago","Node","API","Client","typescript"],"install":[{"cmd":"npm install lago-javascript-client","lang":"bash","label":"npm"},{"cmd":"yarn add lago-javascript-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add lago-javascript-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Polyfill for Fetch API on Node.js versions below 18 or without the `--experimental-fetch` flag enabled.","package":"node-fetch","optional":true}],"imports":[{"note":"The library primarily uses ES Modules. While Node.js has some CJS-ESM interoperability, using `import` is the recommended and type-safe approach.","wrong":"const { Client } = require('lago-javascript-client');","symbol":"Client","correct":"import { Client } from 'lago-javascript-client';"},{"note":"Used for robust error handling and type extraction from API responses. Follows the ESM import pattern.","wrong":"const { getLagoError } = require('lago-javascript-client');","symbol":"getLagoError","correct":"import { getLagoError } from 'lago-javascript-client';"},{"note":"For Deno environments, import directly from the Deno Land URL.","symbol":"Client","correct":"import { Client } from 'https://deno.land/x/lago/mod.ts';"}],"quickstart":{"code":"import { Client, getLagoError } from 'lago-javascript-client';\nimport fetch from 'node-fetch'; // Required for Node.js < 18 or without --experimental-fetch\n\n// Initialize the client with your API key.\n// For Node.js < 18, you might need to pass a custom fetch instance.\nconst lagoClient = Client(process.env.LAGO_API_KEY ?? '', { customFetch: fetch });\n\nasync function createBillableMetric() {\n  const billableMetric = {\n    billableMetric: {\n      name: 'api_calls',\n      code: 'api_calls',\n      aggregation_type: 'count',\n      description: 'Number of API calls made.'\n    }\n  };\n\n  try {\n    // Example: Creating a new billable metric\n    const { data } = await lagoClient.billableMetrics.createBillableMetric(billableMetric);\n    console.log('Successfully created billable metric:', data);\n  } catch (error) {\n    // Use getLagoError for structured error handling and type inference\n    const lagoError = await getLagoError(error);\n    console.error('Error creating billable metric:', lagoError.message, lagoError.response);\n  }\n}\n\ncreateBillableMetric();","lang":"typescript","description":"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."},"warnings":[{"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 });`","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Always use ES Module `import` syntax (`import { Client } from 'lago-javascript-client';`) for consistency and full TypeScript support.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update your `package.json` to `lago-javascript-client` and refactor imports and usage according to the new client's API.","message":"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.","severity":"deprecated","affected_versions":"<1.0.0 (lago-nodejs-client)"},{"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.","message":"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.","severity":"breaking","affected_versions":"N/A (API level)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`.","cause":"Node.js version is older than 18, or the `--experimental-fetch` flag is not used, and no polyfill for `fetch` is provided.","error":"ReferenceError: fetch is not defined"},{"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.","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.","error":"TypeError: (0 , lago_javascript_client__WEBPACK_IMPORTED_MODULE_0__.Client) is not a function"}],"ecosystem":"npm"}