lago-javascript-client 1.46.1 → 1.47.0

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,7 @@ 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";

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

package/esm/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/esm/rate_limit_fetch.js

@@ -1,5 +1,5 @@
 import { LagoRateLimitError } from "./rate_limit_error.js";
-import { parseRateLimitHeaders, } from "./rate_limit_headers.js";
+import { parseRateLimitHeaders, parseRateLimitInfo, } from "./rate_limit_headers.js";
 /**
  * Creates a fetch wrapper that handles rate limiting with automatic retry
  * Compatible with both Node.js fetch and browser fetch APIs
@@ -8,6 +8,7 @@ export 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++) {
@@ -31,7 +32,12 @@ export 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) {
@@ -48,6 +54,35 @@ export function createRateLimitFetch(baseFetch, config = {}) {
         throw lastError;
     };
 }
+/**
+ * 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 = 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/esm/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/esm/rate_limit_headers.js

@@ -1,3 +1,14 @@
+/**
+ * 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 function rateLimitUsagePct(info) {
+    if (info.limit == null || info.remaining == null || info.limit <= 0) {
+        return null;
+    }
+    return 1 - info.remaining / info.limit;
+}
 /**
  * Extract rate limit information from response headers
  */
@@ -8,6 +19,19 @@ export function parseRateLimitHeaders(headers) {
         reset: parseHeaderAsNumber(headers, "x-ratelimit-reset"),
     };
 }
+/**
+ * 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 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 };
+}
 /**
  * Helper to parse a header value as a number
  */

package/package.json

@@ -3,7 +3,7 @@
   "main": "./script/mod.js",
   "name": "lago-javascript-client",
   "sideEffects": false,
-  "version": "v1.46.1",
+  "version": "v1.47.0",
   "description": "Lago JavaScript API Client",
   "repository": {
     "type": "git",

package/script/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/script/logging_rate_limit_observer.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loggingRateLimitObserver = exports.DEFAULT_RATE_LIMIT_THRESHOLDS = void 0;
+const rate_limit_headers_js_1 = require("./rate_limit_headers.js");
+/**
+ * Default usage thresholds (80%, 90%, 95%) at which the observer emits a log.
+ */
+exports.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() },
+ * });
+ * ```
+ */
+function loggingRateLimitObserver(options = {}) {
+    const thresholds = [...(options.thresholds ?? exports.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 = (0, rate_limit_headers_js_1.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;
+            }
+        }
+    };
+}
+exports.loggingRateLimitObserver = loggingRateLimitObserver;

package/script/mod.d.ts

@@ -10,6 +10,7 @@ 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";

package/script/mod.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createRateLimitFetch = exports.parseRateLimitHeaders = exports.LagoRateLimitError = exports.getLagoError = exports.Client = void 0;
+exports.loggingRateLimitObserver = exports.DEFAULT_RATE_LIMIT_THRESHOLDS = exports.createRateLimitFetch = exports.rateLimitUsagePct = exports.parseRateLimitInfo = exports.parseRateLimitHeaders = exports.LagoRateLimitError = exports.getLagoError = exports.Client = void 0;
 // deno-lint-ignore-file no-explicit-any
 const client_js_1 = require("./openapi/client.js");
 const rate_limit_fetch_js_1 = require("./rate_limit_fetch.js");
@@ -61,6 +61,11 @@ var rate_limit_error_js_1 = require("./rate_limit_error.js");
 Object.defineProperty(exports, "LagoRateLimitError", { enumerable: true, get: function () { return rate_limit_error_js_1.LagoRateLimitError; } });
 var rate_limit_headers_js_1 = require("./rate_limit_headers.js");
 Object.defineProperty(exports, "parseRateLimitHeaders", { enumerable: true, get: function () { return rate_limit_headers_js_1.parseRateLimitHeaders; } });
+Object.defineProperty(exports, "parseRateLimitInfo", { enumerable: true, get: function () { return rate_limit_headers_js_1.parseRateLimitInfo; } });
+Object.defineProperty(exports, "rateLimitUsagePct", { enumerable: true, get: function () { return rate_limit_headers_js_1.rateLimitUsagePct; } });
 var rate_limit_fetch_js_2 = require("./rate_limit_fetch.js");
 Object.defineProperty(exports, "createRateLimitFetch", { enumerable: true, get: function () { return rate_limit_fetch_js_2.createRateLimitFetch; } });
+var logging_rate_limit_observer_js_1 = require("./logging_rate_limit_observer.js");
+Object.defineProperty(exports, "DEFAULT_RATE_LIMIT_THRESHOLDS", { enumerable: true, get: function () { return logging_rate_limit_observer_js_1.DEFAULT_RATE_LIMIT_THRESHOLDS; } });
+Object.defineProperty(exports, "loggingRateLimitObserver", { enumerable: true, get: function () { return logging_rate_limit_observer_js_1.loggingRateLimitObserver; } });
 __exportStar(require("./openapi/client.js"), exports);

package/script/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/script/openapi/client.js

@@ -152,7 +152,7 @@ class HttpClient {
 exports.HttpClient = 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

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
  */