feat: billing with Lago (#3927)

## Changes

- Send usage events to Lago
I kept the original implementation from Thomas that allows multiple
clients, which can be handy if we ever want to do some integration
tests.

- Only send metrics for paying accounts
Lago does not reject the events, but we just we to start small


## 🧪 Tests

- Go to Lago
- Create a customer and assign a plan with the external id = account_id
- Modify .env
```
LAGO_API_KEY=SHH
FLAG_USAGE_ENABLED=true
```
- Trigger an action
- ??
- Profit

---------

Co-authored-by: Samuel Bodin <[email protected]>

Author: TBonnin

Dockerfile

@@ -40,6 +40,7 @@ COPY packages/webhooks/package.json ./packages/webhooks/package.json
 COPY packages/fleet/package.json ./packages/fleet/package.json
 COPY packages/providers/package.json ./packages/providers/package.json
 COPY packages/runner-sdk/package.json ./packages/runner-sdk/package.json
+COPY packages/billing/package.json ./packages/billing/package.json
 COPY package*.json  ./
 
 # Install every dependencies

package-lock.json

@@ -0,0 +1,76 @@
+import { uuidv7 } from 'uuidv7';
+
+import { Err, Ok, flagHasUsage, networkError, report, retryFlexible } from '@nangohq/utils';
+
+import type { BillingClient, BillingIngestEvent, BillingMetric } from './types.js';
+import type { Result } from '@nangohq/utils';
+
+export class Billing {
+    constructor(private client: BillingClient) {
+        this.client = client;
+    }
+
+    async send(type: BillingMetric['type'], value: number, props: BillingMetric['properties']): Promise<Result<void>> {
+        return this.sendAll([{ type, value, properties: props }]);
+    }
+
+    async sendAll(events: BillingMetric[]): Promise<Result<void>> {
+        const mapped = events.flatMap((event) => {
+            if (event.value === 0) {
+                return [];
+            }
+
+            return [
+                {
+                    type: event.type,
+                    accountId: event.properties.accountId,
+                    idempotencyKey: event.properties.idempotencyKey || uuidv7(),
+                    timestamp: event.properties.timestamp || new Date(),
+                    properties: {
+                        count: event.value
+                    }
+                }
+            ];
+        });
+
+        return this.ingest(mapped);
+    }
+
+    // Note: Events are sent immediately
+    private async ingest(events: BillingIngestEvent[]): Promise<Result<void>> {
+        if (!flagHasUsage) {
+            return Ok(undefined);
+        }
+
+        try {
+            await retryFlexible(
+                async () => {
+                    await this.client.ingest(events);
+                },
+                {
+                    max: 3,
+                    onError: ({ err }) => {
+                        if (
+                            err instanceof TypeError &&
+                            err.cause &&
+                            typeof err.cause === 'object' &&
+                            'code' in err.cause &&
+                            networkError.includes(err.cause.code as string)
+                        ) {
+                            return { retry: true, reason: 'maybe_unreachable' };
+                        }
+                        if (err instanceof Response && err.status >= 500) {
+                            return { retry: true, reason: 'status_code' };
+                        }
+                        return { retry: false, reason: 'unknown' };
+                    }
+                }
+            );
+            return Ok(undefined);
+        } catch (err: unknown) {
+            const e = new Error(`Failed to send billing event`, { cause: err });
+            report(e);
+            return Err(e);
+        }
+    }
+}

packages/billing/lib/billing.ts

@@ -0,0 +1,31 @@
+import { Client as LagoClient } from 'lago-javascript-client';
+
+import { envs } from '../envs.js';
+
+import type { BillingClient, BillingIngestEvent } from '../types.js';
+import type { EventInput } from 'lago-javascript-client';
+
+const lagoClient = LagoClient(envs.LAGO_API_KEY || '');
+
+export const lago: BillingClient = {
+    ingest: async (events: BillingIngestEvent[]): Promise<void> => {
+        const batchSize = 100;
+        for (let i = 0; i < events.length; i += batchSize) {
+            // Any fail will bubble up on purpose
+            // getLagoError is useless and modifying the error
+            await lagoClient.events.createBatchEvents({
+                events: events.slice(i, i + batchSize).map(toLagoEvent)
+            });
+        }
+    }
+};
+
+function toLagoEvent(event: BillingIngestEvent): EventInput['event'] {
+    return {
+        code: event.type,
+        transaction_id: event.idempotencyKey,
+        external_subscription_id: event.accountId.toString(),
+        timestamp: event.timestamp.getTime(),
+        properties: event.properties
+    };
+}

packages/billing/lib/clients/lago.ts

@@ -0,0 +1,3 @@
+import { ENVS, parseEnvs } from '@nangohq/utils';
+
+export const envs = parseEnvs(ENVS);

packages/billing/lib/envs.ts

@@ -0,0 +1,6 @@
+import { Billing } from './billing.js';
+import { lago } from './clients/lago.js';
+
+export type { BillingIngestEvent, BillingMetric } from './types.js';
+
+export const billing = new Billing(lago);

packages/billing/lib/index.ts

@@ -0,0 +1,17 @@
+export interface BillingClient {
+    ingest: (events: BillingIngestEvent[]) => Promise<void>;
+}
+
+export interface BillingIngestEvent {
+    type: 'monthly_active_records' | 'billable_connections' | 'billable_actions';
+    idempotencyKey: string;
+    accountId: number;
+    timestamp: Date;
+    properties: Record<string, string | number>;
+}
+
+export interface BillingMetric {
+    type: BillingIngestEvent['type'];
+    value: number;
+    properties: { accountId: number; timestamp?: Date | undefined; idempotencyKey?: string | undefined };
+}

packages/billing/lib/types.ts

@@ -0,0 +1,23 @@
+{
+    "name": "@nangohq/billing",
+    "version": "1.0.0",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.js",
+    "private": true,
+    "scripts": {},
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/NangoHQ/nango.git",
+        "directory": "packages/billing"
+    },
+    "dependencies": {
+        "@nangohq/utils": "file:../utils",
+        "lago-javascript-client": "1.22.0",
+        "uuidv7": "1.0.2"
+    },
+    "devDependencies": {},
+    "files": [
+        "dist/**/*"
+    ]
+}

packages/billing/package.json

@@ -0,0 +1,13 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "rootDir": "lib",
+        "outDir": "dist"
+    },
+    "references": [
+        {
+            "path": "../utils"
+        }
+    ],
+    "include": ["lib/**/*", "../utils/lib/vitest.d.ts"]
+}

packages/billing/tsconfig.json

@@ -11,7 +11,7 @@
     "repository": {
         "type": "git",
         "url": "git+https://github.com/NangoHQ/nango.git",
-        "directory": "packages/logs"
+        "directory": "packages/kvstore"
     },
     "dependencies": {
         "@nangohq/utils": "file:../utils",