lago-javascript-client
Version:
Lago JavaScript API Client
161 lines (107 loc) • 4.94 kB
Markdown
This is a JavaScript wrapper for Lago API. Works in Cloudflare Workers, Deno, and Node.js. Generated from [the Lago OpenAPI document](https://swagger.getlago.com/#/).
[](https://badge.fury.io/js/lago-javascript-client)
[](https://spdx.org/licenses/MIT.html)
| Project | Release Badge |
|--------------------|-----------------------------------------------------------------------------------------------------|
| **Lago** | [](https://github.com/getlago/lago/releases) |
| **Lago JavaScript Client** | [](https://github.com/getlago/lago-javascript-client/releases) |
For npm users:
```bash
npm install lago-javascript-client
```
```typescript
// 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);
}
```
This SDK uses the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) and natively supported Node.js version >= 18. For other Node versions:
1. Ideally, run Node with the [`--experimental-fetch` flag](https://nodejs.org/docs/latest-v16.x/api/cli.html#--experimental-fetch)
1. Otherwise, polyfill the Fetch API by doing both:
1. [Patching globalThis](https://github.com/node-fetch/node-fetch#providing-global-access)
1. [Pass a Fetch instance](https://github.com/node-fetch/node-fetch#loading-and-configuring-the-module) to the Lago client
```typescript
import { Client } from 'lago-javascript-client';
import fetch from 'node-fetch';
const lagoClient = Client("api_key", { customFetch: fetch });
```
Check the [Lago API reference](https://doc.getlago.com/docs/api/intro)
Use the get `getLagoError<>()` utility function to extract the error object and TypeScript type:
```typescript
try {
const { data } = await lagoClient.billableMetrics.createBillableMetric(billableMetric);
} catch (error) {
const lagoError = await getLagoError<typeof lagoClient.billableMetrics.createBillableMetric>(error);
}
```
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`:
```typescript
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:
```typescript
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.
Uses [dnt](https://github.com/denoland/dnt) to build and test for Deno and Node.
Change the affected fields in `scripts/build_npm.ts` and commit to GitHub. GitHub Actions will build and deploy to npm.
Requires [Deno](https://deno.land/) and [Node.js >= 18](https://nodejs.org/en/)
```bash
deno task generate:openapi
```
```bash
deno task test
```
```bash
deno task build
```
```bash
deno task build
cd npm
npm publish
```
The Lago documentation is available at [doc.getlago.com](https://doc.getlago.com/docs/api/intro).
The contribution documentation is available [here](https://github.com/getlago/lago-javascript-client/blob/main/CONTRIBUTING.md)
Lago JavaScript client is distributed under [MIT license](LICENSE).