lago-javascript-client 1.46.1 → 1.47.1

package/README.md

@@ -71,6 +71,44 @@ try {
 }
 ```
 
+### 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`:
+
+```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.
+
 ## Development
 
 Uses [dnt](https://github.com/denoland/dnt) to build and test for Deno and Node.

package/esm/logging_rate_limit_observer.d.ts

@@ -0,0 +1,33 @@
+import type { RateLimitInfoCallback } from "./rate_limit_fetch.js";
+/**
+ * Default usage thresholds (80%, 90%, 95%) at which the observer emits a log.
+ */
+export declare const DEFAULT_RATE_LIMIT_THRESHOLDS: readonly number[];
+/**
+ * Configuration for the LoggingRateLimitObserver.
+ */
+export interface LoggingRateLimitObserverOptions {
+    /** Usage fractions (0.0 - 1.0) that should produce a log line. */
+    thresholds?: readonly number[];
+    /**
+     * Function used to emit the log line. Defaults to `console.warn`.
+     * Useful when injecting a structured logger.
+     */
+    log?: (message: string) => void;
+}
+/**
+ * Returns a ready-to-use `onRateLimitInfo` callback that logs a warning each
+ * time rate limit usage crosses one of the configured thresholds.
+ *
+ * Example:
+ *
+ * ```ts
+ * import { Client } from "@getlago/lago-javascript-client";
+ * import { loggingRateLimitObserver } from "@getlago/lago-javascript-client";
+ *
+ * const client = Client(apiKey, {
+ *   rateLimitRetry: { onRateLimitInfo: loggingRateLimitObserver() },
+ * });
+ * ```
+ */
+export declare function loggingRateLimitObserver(options?: LoggingRateLimitObserverOptions): RateLimitInfoCallback;

package/esm/logging_rate_limit_observer.js

@@ -0,0 +1,43 @@
+import { rateLimitUsagePct } from "./rate_limit_headers.js";
+/**
+ * Default usage thresholds (80%, 90%, 95%) at which the observer emits a log.
+ */
+export const DEFAULT_RATE_LIMIT_THRESHOLDS = [
+    0.8,
+    0.9,
+    0.95,
+];
+/**
+ * Returns a ready-to-use `onRateLimitInfo` callback that logs a warning each
+ * time rate limit usage crosses one of the configured thresholds.
+ *
+ * Example:
+ *
+ * ```ts
+ * import { Client } from "@getlago/lago-javascript-client";
+ * import { loggingRateLimitObserver } from "@getlago/lago-javascript-client";
+ *
+ * const client = Client(apiKey, {
+ *   rateLimitRetry: { onRateLimitInfo: loggingRateLimitObserver() },
+ * });
+ * ```
+ */
+export function loggingRateLimitObserver(options = {}) {
+    const thresholds = [...(options.thresholds ?? DEFAULT_RATE_LIMIT_THRESHOLDS)]
+        .sort((a, b) => b - a); // descending
+    // deno-lint-ignore no-console
+    const log = options.log ?? ((m) => console.warn(m));
+    return function observe(info) {
+        const pct = rateLimitUsagePct(info);
+        if (pct === null)
+            return;
+        for (const threshold of thresholds) {
+            if (pct >= threshold) {
+                log(`Lago rate limit at ${(pct * 100).toFixed(0)}% (limit=${info.limit}, ` +
+                    `remaining=${info.remaining}, reset=${info.reset}s, ` +
+                    `${info.method} ${info.url})`);
+                return;
+            }
+        }
+    };
+}

package/esm/mod.d.ts

@@ -10,6 +10,8 @@ export declare const Client: (apiKey: string, apiConfig?: LagoClientConfig) => A
 type ExtractLagoError<E> = E extends (...args: any) => Promise<HttpResponse<infer T, infer P>> ? P : never;
 export declare function getLagoError<T>(error: any): Promise<ExtractLagoError<T>>;
 export { LagoRateLimitError } from "./rate_limit_error.js";
-export { parseRateLimitHeaders, type RateLimitHeaders } from "./rate_limit_headers.js";
-export { createRateLimitFetch, type RateLimitFetchConfig } from "./rate_limit_fetch.js";
+export { parseRateLimitHeaders, parseRateLimitInfo, type RateLimitHeaders, type RateLimitInfo, rateLimitUsagePct, } from "./rate_limit_headers.js";
+export { createRateLimitFetch, type RateLimitFetchConfig, type RateLimitInfoCallback, } from "./rate_limit_fetch.js";
+export { DEFAULT_RATE_LIMIT_THRESHOLDS, loggingRateLimitObserver, type LoggingRateLimitObserverOptions, } from "./logging_rate_limit_observer.js";
 export * from "./openapi/client.js";
+export type { LagoWebhookPayload, LagoWebhookPayloads, LagoWebhookType, WebhookOf, } from "./webhook_types.js";

package/esm/mod.js

@@ -39,6 +39,7 @@ export async function getLagoError(error) {
 }
 // Rate limit exports
 export { LagoRateLimitError } from "./rate_limit_error.js";
-export { parseRateLimitHeaders } from "./rate_limit_headers.js";
-export { createRateLimitFetch } from "./rate_limit_fetch.js";
+export { parseRateLimitHeaders, parseRateLimitInfo, rateLimitUsagePct, } from "./rate_limit_headers.js";
+export { createRateLimitFetch, } from "./rate_limit_fetch.js";
+export { DEFAULT_RATE_LIMIT_THRESHOLDS, loggingRateLimitObserver, } from "./logging_rate_limit_observer.js";
 export * from "./openapi/client.js";

package/esm/openapi/client.d.ts

@@ -8857,7 +8857,7 @@ export declare class HttpClient<SecurityDataType = unknown> {
 }
 /**
  * @title Lago API documentation
- * @version 1.45.0
+ * @version 1.45.2
  * @license AGPLv3 (https://github.com/getlago/lago-openapi/blob/main/LICENSE)
  * @baseUrl https://api.getlago.com/api/v1
  * @externalDocs https://github.com/getlago
@@ -10302,24 +10302,48 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
              * @example true
              */
             apply_taxes?: boolean;
+            /**
+             * Filter usage to a specific charge by its Lago ID (UUID). Replaces deprecated `filter_by_charge_id`.
+             * @format uuid
+             * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
+             */
+            charge_id?: string;
+            /**
+             * Filter usage to a specific charge by its code. Replaces deprecated `filter_by_charge_code`.
+             * @example "storage"
+             */
+            charge_code?: string;
+            /**
+             * Filter usage to a specific billable metric by its code.
+             * @example "storage"
+             */
+            billable_metric_code?: string;
+            /**
+             * Filter usage by pricing group. Pass key/value pairs as query parameters, e.g. `group[cloud]=aws`. Replaces deprecated `filter_by_group`.
+             * @example {"cloud":"aws"}
+             */
+            group?: Record<string, string>;
             /**
              * Filter usage to a specific charge by its Lago ID (UUID).
+             * @deprecated
              * @format uuid
              * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
              */
             filter_by_charge_id?: string;
             /**
              * Filter usage to a specific charge by its code.
+             * @deprecated
              * @example "storage"
              */
             filter_by_charge_code?: string;
             /**
              * Filter usage by pricing group. Pass key/value pairs as query parameters, e.g. `filter_by_group[cloud]=aws`.
+             * @deprecated
              * @example {"cloud":"aws"}
              */
             filter_by_group?: Record<string, string>;
             /**
-             * When `true`, returns usage since subscription start instead of the current billing period. Requires either `filter_by_charge_id`, `filter_by_charge_code`, or `filter_by_group` to be set.
+             * When `true`, returns usage since subscription start instead of the current billing period. Requires one of `charge_id`, `charge_code`, `group` (or their deprecated `filter_by_*` equivalents) to be set.
              * @default false
              * @example true
              */

package/esm/openapi/client.js

@@ -148,7 +148,7 @@ export class HttpClient {
 }
 /**
  * @title Lago API documentation
- * @version 1.45.0
+ * @version 1.45.2
  * @license AGPLv3 (https://github.com/getlago/lago-openapi/blob/main/LICENSE)
  * @baseUrl https://api.getlago.com/api/v1
  * @externalDocs https://github.com/getlago