lago-javascript-client 1.46.1 → 1.47.1

package/script/openapi/webhooks.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/script/rate_limit_fetch.d.ts

@@ -1,3 +1,13 @@
+import { type RateLimitInfo } from "./rate_limit_headers.js";
+/**
+ * Callback invoked after every successful response with parsed rate limit
+ * headers. Use this to build observability around the rate limit (warn at
+ * thresholds, emit metrics, etc.).
+ *
+ * Errors thrown by the callback are caught and logged so they cannot break
+ * the underlying request flow.
+ */
+export type RateLimitInfoCallback = (info: RateLimitInfo) => void;
 /**
  * Configuration for rate limit fetch behavior
  */
@@ -8,6 +18,11 @@ export interface RateLimitFetchConfig {
     retryOnRateLimit?: boolean;
     /** Maximum delay in milliseconds before a retry (default: 20000) */
     maxRetryDelay?: number;
+    /**
+     * Optional callback invoked after every successful (non-429) response
+     * with parsed rate limit headers. See `RateLimitInfoCallback`.
+     */
+    onRateLimitInfo?: RateLimitInfoCallback;
 }
 /**
  * Creates a fetch wrapper that handles rate limiting with automatic retry

package/script/rate_limit_fetch.js

@@ -11,6 +11,7 @@ function createRateLimitFetch(baseFetch, config = {}) {
     const maxRetries = config.maxRetries ?? 3;
     const retryOnRateLimit = config.retryOnRateLimit ?? true;
     const maxRetryDelay = config.maxRetryDelay ?? 20_000;
+    const onRateLimitInfo = config.onRateLimitInfo;
     return async function rateLimitFetch(input, init) {
         let lastError;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -34,7 +35,12 @@ function createRateLimitFetch(baseFetch, config = {}) {
                     await sleep(waitMs);
                     continue; // Retry
                 }
-                // Success or non-rate-limit error - return the response
+                // Success: emit observability info. Non-2xx, non-429 responses are
+                // returned as-is without invoking the callback because their headers
+                // do not carry useful rate limit context.
+                if (onRateLimitInfo && response.ok) {
+                    emitRateLimitInfo(onRateLimitInfo, response, input, init);
+                }
                 return response;
             }
             catch (error) {
@@ -52,6 +58,35 @@ function createRateLimitFetch(baseFetch, config = {}) {
     };
 }
 exports.createRateLimitFetch = createRateLimitFetch;
+/**
+ * Invoke the configured callback with parsed rate limit info, swallowing any
+ * exception so a buggy observer cannot break the request.
+ */
+function emitRateLimitInfo(callback, response, input, init) {
+    try {
+        // Honor the method on a Request input when init.method is undefined
+        // (a valid fetch signature: fetch(new Request(url, { method: 'POST' }))).
+        const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+        const url = requestUrl(input);
+        const info = (0, rate_limit_headers_js_1.parseRateLimitInfo)(response.headers, method, url);
+        if (info === null)
+            return;
+        callback(info);
+    }
+    catch (err) {
+        // Never let observability break the request flow.
+        // deno-lint-ignore no-console
+        console.warn("Lago: onRateLimitInfo callback raised:", err);
+    }
+}
+function requestUrl(input) {
+    if (typeof input === "string")
+        return input;
+    if (input instanceof URL)
+        return input.toString();
+    // Request
+    return input.url;
+}
 /**
  * Calculate wait time before retry
  * Uses the exact reset time from headers if available, otherwise exponential backoff

package/script/rate_limit_headers.d.ts

@@ -6,7 +6,33 @@ export interface RateLimitHeaders {
     remaining: number | null;
     reset: number | null;
 }
+/**
+ * Parsed rate limit headers plus the request context they came from.
+ *
+ * Delivered to the `onRateLimitInfo` callback after every successful request
+ * so callers can build observability around the rate limit (warn at thresholds,
+ * emit metrics, etc.).
+ */
+export interface RateLimitInfo extends RateLimitHeaders {
+    /** HTTP method of the call (GET, POST, ...). */
+    method: string;
+    /** Request URL. */
+    url: string;
+}
+/**
+ * Returns the fraction of the rate limit currently used in [0.0, 1.0],
+ * or `null` when the headers aren't usable (missing limit, zero limit,
+ * missing remaining).
+ */
+export declare function rateLimitUsagePct(info: RateLimitHeaders): number | null;
 /**
  * Extract rate limit information from response headers
  */
 export declare function parseRateLimitHeaders(headers: Headers): RateLimitHeaders;
+/**
+ * Returns a `RateLimitInfo` (headers + request context), or `null` when no
+ * `x-ratelimit-*` headers are present (e.g. self-hosted Lago instance with
+ * limits disabled). Useful for skipping observability emission entirely when
+ * there's nothing to report.
+ */
+export declare function parseRateLimitInfo(headers: Headers, method: string, url: string): RateLimitInfo | null;

package/script/rate_limit_headers.js

@@ -1,6 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseRateLimitHeaders = void 0;
+exports.parseRateLimitInfo = exports.parseRateLimitHeaders = exports.rateLimitUsagePct = void 0;
+/**
+ * Returns the fraction of the rate limit currently used in [0.0, 1.0],
+ * or `null` when the headers aren't usable (missing limit, zero limit,
+ * missing remaining).
+ */
+function rateLimitUsagePct(info) {
+    if (info.limit == null || info.remaining == null || info.limit <= 0) {
+        return null;
+    }
+    return 1 - info.remaining / info.limit;
+}
+exports.rateLimitUsagePct = rateLimitUsagePct;
 /**
  * Extract rate limit information from response headers
  */
@@ -12,6 +24,20 @@ function parseRateLimitHeaders(headers) {
     };
 }
 exports.parseRateLimitHeaders = parseRateLimitHeaders;
+/**
+ * Returns a `RateLimitInfo` (headers + request context), or `null` when no
+ * `x-ratelimit-*` headers are present (e.g. self-hosted Lago instance with
+ * limits disabled). Useful for skipping observability emission entirely when
+ * there's nothing to report.
+ */
+function parseRateLimitInfo(headers, method, url) {
+    const parsed = parseRateLimitHeaders(headers);
+    if (parsed.limit == null && parsed.remaining == null && parsed.reset == null) {
+        return null;
+    }
+    return { ...parsed, method, url };
+}
+exports.parseRateLimitInfo = parseRateLimitInfo;
 /**
  * Helper to parse a header value as a number
  */

package/script/webhook_types.d.ts

@@ -0,0 +1,68 @@
+import type { webhooks } from "./openapi/webhooks.js";
+/** Extract the `application/json` body of a webhook's POST request. */
+type _PayloadOf<K extends keyof webhooks> = webhooks[K] extends {
+    post: {
+        requestBody?: {
+            content: {
+                "application/json": infer P;
+            };
+        };
+    };
+} ? P : never;
+/** Extract the `webhook_type` literal (e.g. `"alert.triggered"`) from a payload. */
+type _WebhookTypeOf<K extends keyof webhooks> = _PayloadOf<K> extends {
+    webhook_type: infer T;
+} ? T extends string ? T : never : never;
+/**
+ * Map of webhook event name to its typed payload.
+ *
+ * @example
+ * ```ts
+ * import type { LagoWebhookPayloads } from "lago-javascript-client";
+ *
+ * app.post("/webhooks", (req, res) => {
+ *   const event = req.body as LagoWebhookPayloads["alert.triggered"];
+ *   console.log(event.triggered_alert.external_customer_id);
+ * });
+ * ```
+ */
+export type LagoWebhookPayloads = {
+    [K in keyof webhooks as _WebhookTypeOf<K>]: _PayloadOf<K>;
+};
+/**
+ * Discriminated union of every webhook payload. Narrow with the `webhook_type`
+ * field in a `switch` to get a fully typed branch.
+ *
+ * @example
+ * ```ts
+ * import type { LagoWebhookPayload } from "lago-javascript-client";
+ *
+ * function handle(event: LagoWebhookPayload) {
+ *   switch (event.webhook_type) {
+ *     case "alert.triggered":
+ *       // event is narrowed; event.triggered_alert is fully typed
+ *       break;
+ *     case "invoice.created":
+ *       // event.invoice is fully typed
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type LagoWebhookPayload = LagoWebhookPayloads[keyof LagoWebhookPayloads];
+/**
+ * Union of every `webhook_type` string emitted by Lago, e.g.
+ * `"alert.triggered" | "invoice.created" | ...`.
+ */
+export type LagoWebhookType = keyof LagoWebhookPayloads;
+/**
+ * Helper to look up a single payload type by its `webhook_type` string.
+ *
+ * @example
+ * ```ts
+ * import type { WebhookOf } from "lago-javascript-client";
+ * type InvoiceCreated = WebhookOf<"invoice.created">;
+ * ```
+ */
+export type WebhookOf<T extends LagoWebhookType> = LagoWebhookPayloads[T];
+export {};

package/script/webhook_types.js

@@ -0,0 +1,24 @@
+"use strict";
+// User-facing TypeScript types for Lago webhook payloads.
+//
+// Backed by ./openapi/webhooks.ts, which is auto-generated from the Lago
+// OpenAPI 3.1 spec (`webhooks:` key) via `deno task generate:webhooks`.
+// This file is hand-written and is safe across regenerations.
+//
+// The generator output keys events by their snake_case operationId
+// (e.g. `alert_triggered`). We re-key here by the dotted `webhook_type`
+// literal (e.g. `alert.triggered`) so that the public API matches the
+// string customers actually see on the wire.
+//
+// Note on nested types: the payload types here are produced by
+// `openapi-typescript`, while the SDK's component exports (e.g.
+// `CustomerObject`, `InvoiceObjectExtended`) are produced by
+// `swagger-typescript-api`. The two generators interpret the same schema
+// slightly differently for nullable fields, so a value typed as
+// `LagoWebhookPayloads['customer.created']['customer']` is not always
+// structurally equal to `CustomerObject` from the main SDK exports. Both
+// are valid views of the same wire shape; the openapi-typescript view is
+// the more accurate one for what actually arrives over the network. If
+// you pass webhook objects into helpers typed with SDK components, a
+// narrowing cast may be required.
+Object.defineProperty(exports, "__esModule", { value: true });