Lago JavaScript Client

This is a JavaScript wrapper for Lago API. Works in Cloudflare Workers, Deno, and Node.js. Generated from the Lago OpenAPI document.

Current Releases

Project	Release Badge
Lago
Lago JavaScript Client

Installation

For npm users:

npm install lago-javascript-client

// npm
import { Client, getLagoError } from 'lago-javascript-client';

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

const lagoClient = Client('__YOUR_API_KEY__');

try {
    const { data } = await lagoClient.billableMetrics.createBillableMetric(billableMetric);
} catch (error) {
    const lagoError = await getLagoError<typeof lagoClient.billableMetrics.createBillableMetric>(error);
}

Compatibility

This SDK uses the Fetch API and natively supported Node.js version >= 18. For other Node versions:

1. Ideally, run Node with the --experimental-fetch flag

2. Otherwise, polyfill the Fetch API by doing both:

   1. Patching globalThis

   2. Pass a Fetch instance to the Lago client

      import { Client } from 'lago-javascript-client';
      import fetch from 'node-fetch';
      
      const lagoClient = Client("api_key", { customFetch: fetch });

Usage

Check the Lago API reference

Error handling

Use the get getLagoError<>() utility function to extract the error object and TypeScript type:

try {
    const { data } = await lagoClient.billableMetrics.createBillableMetric(billableMetric);
} catch (error) {
    const lagoError = await getLagoError<typeof lagoClient.billableMetrics.createBillableMetric>(error);
}

Webhook payload types

The SDK exposes TypeScript types for every webhook event Lago emits. The types are generated from the OpenAPI spec, so they stay in sync with the API.

Indexed lookup by webhook_type:

import type { LagoWebhookPayloads } from 'lago-javascript-client';

app.post('/webhooks', (req, res) => {
    const event = req.body as LagoWebhookPayloads['alert.triggered'];
    // event.triggered_alert is fully typed
    console.log(event.triggered_alert.external_customer_id);
    res.sendStatus(200);
});

Discriminated union for handlers that cover multiple events:

import type { LagoWebhookPayload } from 'lago-javascript-client';

function handle(event: LagoWebhookPayload) {
    switch (event.webhook_type) {
        case 'alert.triggered':
            // event.triggered_alert is typed
            return event.triggered_alert;
        case 'invoice.created':
            // event.invoice is typed
            return event.invoice;
        case 'subscription.terminated':
            return event.subscription;
    }
}

A WebhookOf<T> helper is also exported for picking a single payload type by name, and LagoWebhookType gives the union of all event-type strings.

Development

Uses dnt to build and test for Deno and Node.

Release new version

Change the affected fields in scripts/build_npm.ts and commit to GitHub. GitHub Actions will build and deploy to npm.

Dependencies

Requires Deno and Node.js >= 18

Generate client from OpenAPI

deno task generate:openapi

Run tests

deno task test

Build

deno task build

Publish to npm

deno task build
cd npm
npm publish

Documentation

The Lago documentation is available at doc.getlago.com.

Contributing

The contribution documentation is available here

License

Lago JavaScript client is distributed under MIT license.