lago-javascript-client 1.45.0 → 1.46.1

package/esm/mod.d.ts

@@ -1,5 +1,15 @@
 import { Api, ApiConfig, HttpResponse } from "./openapi/client.js";
-export declare const Client: (apiKey: string, apiConfig?: ApiConfig) => Api<unknown>;
+import type { RateLimitFetchConfig } from "./rate_limit_fetch.js";
+export interface LagoClientConfig extends ApiConfig {
+    /**
+     * Rate limit retry configuration
+     */
+    rateLimitRetry?: RateLimitFetchConfig;
+}
+export declare const Client: (apiKey: string, apiConfig?: LagoClientConfig) => Api<unknown>;
 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 * from "./openapi/client.js";

package/esm/mod.js

@@ -1,13 +1,20 @@
 // deno-lint-ignore-file no-explicit-any
 import { Api } from "./openapi/client.js";
+import { createRateLimitFetch } from "./rate_limit_fetch.js";
 export const Client = (apiKey, apiConfig) => {
+    const { rateLimitRetry, ...restConfig } = apiConfig ?? {};
+    // Create rate-limit-aware fetch if configured
+    const customFetch = rateLimitRetry
+        ? createRateLimitFetch((restConfig?.customFetch ?? globalThis.fetch), rateLimitRetry)
+        : restConfig?.customFetch;
     const api = new Api({
         securityWorker: (apiKey) => apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : {},
         // Cloudflare Workers doesn't support some options like credentials so need to override default
         baseApiParams: {
             redirect: "follow",
         },
-        ...apiConfig,
+        ...restConfig,
+        ...(customFetch && { customFetch }),
     });
     api.setSecurityData(apiKey);
     return api;
@@ -30,4 +37,8 @@ export async function getLagoError(error) {
     }
     throw new Error(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 * from "./openapi/client.js";

package/esm/openapi/client.d.ts

@@ -2226,6 +2226,16 @@ export interface FeeObject {
      * @example "0.0"
      */
     precise_coupons_amount_cents?: string;
+    /**
+     * The sub total of the fee excluding taxes, in cents.
+     * @example 100
+     */
+    sub_total_excluding_taxes_amount_cents: number;
+    /**
+     * The sub total of the fee excluding taxes, with precision.
+     * @example "100.0"
+     */
+    sub_total_excluding_taxes_precise_amount_cents: string;
     /** List of all unit amount details for calculating the fee. */
     amount_details?: FeeAmountDetails;
     /**
@@ -3837,18 +3847,20 @@ export interface AppliedInvoiceCustomSectionObject {
      * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
      */
     lago_id: string;
-    /**
-     * Unique identifier of the invoice custom section that was applied.
-     * @format uuid
-     * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
-     */
-    invoice_custom_section_id: string;
     /**
      * The date of the applied invoice custom section creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
      * @format date-time
      * @example "2023-07-06T14:35:58Z"
      */
     created_at: string;
+    /**
+     * Unique identifier of the invoice custom section that was applied.
+     * @deprecated
+     * @format uuid
+     * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
+     */
+    invoice_custom_section_id?: string;
+    invoice_custom_section: InvoiceCustomSectionObject;
 }
 /** Reference to a specific payment method for processing the payment. */
 export interface PaymentMethodReference {
@@ -4572,7 +4584,7 @@ export type AlertThresholdObject = AlertThresholdBaseObject & {
      */
     value: string;
 };
-export interface AlertObject {
+export interface WalletAlertObject {
     /**
      * Unique identifier of the alert, created by Lago.
      * @format uuid
@@ -4585,46 +4597,36 @@ export interface AlertObject {
      * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
      */
     lago_organization_id: string;
-    /**
-     * The subscription external unique identifier (provided by your own application).
-     * @example "sub_1234567890"
-     */
-    external_subscription_id: string | null;
-    /**
-     * The customer external unique identifier (provided by your own application).
-     * @example "cus_0987654321"
-     */
-    external_customer_id: string;
+    external_subscription_id: null;
     /**
      * Unique identifier of the wallet, created by Lago.
      * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
      */
-    lago_wallet_id?: string | null;
+    lago_wallet_id?: string;
     /**
      * The wallet external unique identifier (provided by your own application).
      * @example "wallet_code"
      */
-    wallet_code?: string | null;
-    /** The billable metric associated with the alert. Only for alerts based on a billable metric. */
-    billable_metric: BillableMetricObject;
+    wallet_code?: string;
+    billable_metric: null;
     /**
      * The type of alert.
-     * @example "billable_metric_current_usage_amount"
+     * @example "wallet_balance_amount"
      */
-    alert_type: "current_usage_amount" | "billable_metric_current_usage_amount" | "billable_metric_current_usage_units" | "lifetime_usage_amount";
+    alert_type: "wallet_balance_amount" | "wallet_credits_balance" | "wallet_ongoing_balance_amount" | "wallet_credits_ongoing_balance";
     /**
      * Unique code used to identify the alert.
-     * @example "storage_threshold_alert"
+     * @example "wallet_balance_alert"
      */
     code: string;
     /**
      * The name of the alert.
-     * @example "Storage Usage Alert"
+     * @example "Wallet Balance Alert"
      */
     name: string | null;
     /**
      * Indicates whether the alert is triggered when the monitored metric goes above or below the threshold.
-     * @example "increasing"
+     * @example "decreasing"
      */
     direction?: "increasing" | "decreasing";
     /**
@@ -4647,8 +4649,8 @@ export interface AlertObject {
      */
     created_at: string;
 }
-export interface Alerts {
-    alerts: AlertObject[];
+export interface WalletAlerts {
+    alerts: WalletAlertObject[];
     meta?: PaginationMeta;
 }
 export type AlertThresholdInput = AlertThresholdBaseObject & {
@@ -4678,7 +4680,7 @@ export interface WalletAlertCreateInput {
          * The type of alert.
          * @example "wallet_balance_amount"
          */
-        alert_type: "wallet_balance_amount" | "wallet_credits_balance";
+        alert_type: "wallet_balance_amount" | "wallet_credits_balance" | "wallet_ongoing_balance_amount" | "wallet_credits_ongoing_balance";
         /**
          * Unique code used to identify the alert.
          * @example "wallet_balance_alert"
@@ -4698,7 +4700,7 @@ export interface WalletAlertBatchCreateInput {
          * The type of alert.
          * @example "wallet_balance_amount"
          */
-        alert_type: "wallet_balance_amount" | "wallet_credits_balance";
+        alert_type: "wallet_balance_amount" | "wallet_credits_balance" | "wallet_ongoing_balance_amount" | "wallet_credits_ongoing_balance";
         /**
          * Unique code used to identify the alert.
          * @example "wallet_balance_alert"
@@ -4711,8 +4713,8 @@ export interface WalletAlertBatchCreateInput {
         name?: string | null;
     })[];
 }
-export interface Alert {
-    alert: AlertObject;
+export interface WalletAlert {
+    alert: WalletAlertObject;
 }
 export interface WalletAlertUpdateInput {
     alert: AlertBaseInput & {
@@ -7800,6 +7802,72 @@ export interface LifetimeUsageInput {
         external_historical_usage_amount_cents: number;
     };
 }
+export interface AlertObject {
+    /**
+     * Unique identifier of the alert, created by Lago.
+     * @format uuid
+     * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
+     */
+    lago_id: string;
+    /**
+     * Unique identifier of the organization, created by Lago.
+     * @format uuid
+     * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
+     */
+    lago_organization_id: string;
+    /**
+     * The subscription external unique identifier (provided by your own application).
+     * @example "sub_1234567890"
+     */
+    external_subscription_id: string | null;
+    lago_wallet_id?: null;
+    wallet_code?: null;
+    /** The billable metric associated with the alert. Only for alerts based on a billable metric. */
+    billable_metric: BillableMetricObject;
+    /**
+     * The type of alert.
+     * @example "billable_metric_current_usage_amount"
+     */
+    alert_type: "current_usage_amount" | "billable_metric_current_usage_amount" | "billable_metric_current_usage_units" | "lifetime_usage_amount";
+    /**
+     * Unique code used to identify the alert.
+     * @example "storage_threshold_alert"
+     */
+    code: string;
+    /**
+     * The name of the alert.
+     * @example "Storage Usage Alert"
+     */
+    name: string | null;
+    /**
+     * Indicates whether the alert is triggered when the monitored metric goes above or below the threshold.
+     * @example "increasing"
+     */
+    direction?: "increasing" | "decreasing";
+    /**
+     * When the system checked if this alert should be triggered, this value was retrieved and checked against the thresholds.
+     * @example 1000
+     */
+    previous_value: number;
+    /**
+     * The date and time in UTC (ISO 8601) when the system checked if this alert should be triggered. Null until it's processed for the first time.
+     * @format date-time
+     * @example "2025-05-19T10:04:21Z"
+     */
+    last_processed_at: string | null;
+    /** Array of thresholds associated with the alert. */
+    thresholds: AlertThresholdObject[];
+    /**
+     * The date and time in UTC (ISO 8601) when the alert was created.
+     * @format date-time
+     * @example "2025-03-20T10:00:00Z"
+     */
+    created_at: string;
+}
+export interface Alerts {
+    alerts: AlertObject[];
+    meta?: PaginationMeta;
+}
 export interface AlertCreateInput {
     alert: AlertBaseInput & {
         /**
@@ -7832,8 +7900,16 @@ export interface AlertBatchCreateInput {
          * @example "storage_threshold_alert"
          */
         code: string;
+        /**
+         * The code of the billable metric associated with the alert. Only for alerts based on a billable metric.
+         * @example "storage_usage"
+         */
+        billable_metric_code?: string | null;
     })[];
 }
+export interface Alert {
+    alert: AlertObject;
+}
 export interface AlertUpdateInput {
     alert: AlertBaseInput & {
         /**
@@ -10154,7 +10230,7 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request GET:/customers/{external_customer_id}/wallets/{wallet_code}/alerts
          * @secure
          */
-        getCustomerWalletAlerts: (externalCustomerId: string, walletCode: string, params?: RequestParams) => Promise<HttpResponse<Alerts, ApiErrorUnauthorized | ApiErrorNotFound>>;
+        getCustomerWalletAlerts: (externalCustomerId: string, walletCode: string, params?: RequestParams) => Promise<HttpResponse<WalletAlerts, ApiErrorUnauthorized | ApiErrorNotFound>>;
         /**
          * @description This endpoint allows you to create new alerts for a wallet. Send a single alert object wrapped in `alert` key to create one alert, or an array of alert objects wrapped in `alerts` key to create multiple alerts atomically.
          *
@@ -10164,7 +10240,7 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request POST:/customers/{external_customer_id}/wallets/{wallet_code}/alerts
          * @secure
          */
-        createCustomerWalletAlert: (externalCustomerId: string, walletCode: string, data: WalletAlertCreateInput | WalletAlertBatchCreateInput, params?: RequestParams) => Promise<HttpResponse<Alerts | Alert, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorBadRequest | ApiErrorNotFound>>;
+        createCustomerWalletAlert: (externalCustomerId: string, walletCode: string, data: WalletAlertCreateInput | WalletAlertBatchCreateInput, params?: RequestParams) => Promise<HttpResponse<WalletAlerts | WalletAlert, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorBadRequest | ApiErrorNotFound>>;
         /**
          * @description This endpoint allows you to delete all alerts for a wallet.
          *
@@ -10184,7 +10260,7 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request GET:/customers/{external_customer_id}/wallets/{wallet_code}/alerts/{code}
          * @secure
          */
-        getCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, params?: RequestParams) => Promise<HttpResponse<Alert, ApiErrorUnauthorized | ApiErrorNotFound>>;
+        getCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, params?: RequestParams) => Promise<HttpResponse<WalletAlert, ApiErrorUnauthorized | ApiErrorNotFound>>;
         /**
          * @description This endpoint allows you to update an existing alert for a wallet.
          *
@@ -10194,7 +10270,7 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request PUT:/customers/{external_customer_id}/wallets/{wallet_code}/alerts/{code}
          * @secure
          */
-        updateCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, data: WalletAlertUpdateInput, params?: RequestParams) => Promise<HttpResponse<Alert, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorBadRequest | ApiErrorNotFound>>;
+        updateCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, data: WalletAlertUpdateInput, params?: RequestParams) => Promise<HttpResponse<WalletAlert, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorBadRequest | ApiErrorNotFound>>;
         /**
          * @description This endpoint allows you to delete an existing alert for a wallet.
          *
@@ -10204,7 +10280,7 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request DELETE:/customers/{external_customer_id}/wallets/{wallet_code}/alerts/{code}
          * @secure
          */
-        deleteCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, params?: RequestParams) => Promise<HttpResponse<Alert, ApiErrorUnauthorized | ApiErrorNotFound>>;
+        deleteCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, params?: RequestParams) => Promise<HttpResponse<WalletAlert, ApiErrorUnauthorized | ApiErrorNotFound>>;
         /**
          * @description This endpoint enables the retrieval of the usage-based billing data for a customer within the current period.
          *
@@ -10316,7 +10392,9 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request POST:/customers/{external_customer_id}/checkout_url
          * @secure
          */
-        generateCustomerCheckoutUrl: (externalCustomerId: string, params?: RequestParams) => Promise<HttpResponse<CustomerCheckoutUrl, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorNotFound>>;
+        generateCustomerCheckoutUrl: (externalCustomerId: string, params?: RequestParams) => Promise<HttpResponse<{
+            customer: CustomerCheckoutUrl;
+        }, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorNotFound>>;
         /**
          * @description This endpoint retrieves all payment methods of a Customer.
          *

package/esm/rate_limit_error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Error class for rate limit (HTTP 429) responses
+ */
+export declare class LagoRateLimitError extends Error {
+    readonly limit: number;
+    readonly remaining: number;
+    readonly reset: number;
+    readonly retryAfter: number;
+    constructor(limit: number, remaining: number, reset: number);
+}

package/esm/rate_limit_error.js

@@ -0,0 +1,19 @@
+/**
+ * Error class for rate limit (HTTP 429) responses
+ */
+export class LagoRateLimitError extends Error {
+    limit;
+    remaining;
+    reset; // seconds until window resets
+    retryAfter; // milliseconds to wait before retrying
+    constructor(limit, remaining, reset) {
+        super(`Rate limit exceeded. Limit: ${limit}, Remaining: ${remaining}, Reset in: ${reset}s`);
+        this.name = "LagoRateLimitError";
+        this.limit = limit;
+        this.remaining = remaining;
+        this.reset = reset;
+        this.retryAfter = reset * 1000; // Convert seconds to milliseconds
+        // Maintain proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, LagoRateLimitError.prototype);
+    }
+}

package/esm/rate_limit_fetch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Configuration for rate limit fetch behavior
+ */
+export interface RateLimitFetchConfig {
+    /** Maximum number of retries on 429 (default: 3) */
+    maxRetries?: number;
+    /** Whether to automatically retry on rate limit (default: true) */
+    retryOnRateLimit?: boolean;
+    /** Maximum delay in milliseconds before a retry (default: 20000) */
+    maxRetryDelay?: number;
+}
+/**
+ * Creates a fetch wrapper that handles rate limiting with automatic retry
+ * Compatible with both Node.js fetch and browser fetch APIs
+ */
+export declare function createRateLimitFetch(baseFetch: typeof fetch, config?: RateLimitFetchConfig): typeof fetch;

package/esm/rate_limit_fetch.js

@@ -0,0 +1,76 @@
+import { LagoRateLimitError } from "./rate_limit_error.js";
+import { parseRateLimitHeaders, } 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
+ */
+export function createRateLimitFetch(baseFetch, config = {}) {
+    const maxRetries = config.maxRetries ?? 3;
+    const retryOnRateLimit = config.retryOnRateLimit ?? true;
+    const maxRetryDelay = config.maxRetryDelay ?? 20_000;
+    return async function rateLimitFetch(input, init) {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const response = await baseFetch(input, init);
+                // Handle 429 responses
+                if (response.status === 429) {
+                    const headers = parseRateLimitHeaders(response.headers);
+                    const limit = headers.limit ?? -1;
+                    const remaining = headers.remaining ?? 0;
+                    const reset = headers.reset ?? -1;
+                    const error = new LagoRateLimitError(limit, remaining, reset);
+                    if (!retryOnRateLimit) {
+                        throw error;
+                    }
+                    if (attempt === maxRetries) {
+                        throw error; // Max retries reached
+                    }
+                    // Wait before retry
+                    const waitMs = getWaitTime(error, attempt, maxRetryDelay);
+                    await sleep(waitMs);
+                    continue; // Retry
+                }
+                // Success or non-rate-limit error - return the response
+                return response;
+            }
+            catch (error) {
+                lastError = error;
+                if (!(error instanceof LagoRateLimitError)) {
+                    throw error; // Not a rate limit error, rethrow immediately
+                }
+                if (attempt === maxRetries) {
+                    throw error; // Max retries reached
+                }
+                // Will retry on next iteration
+            }
+        }
+        throw lastError;
+    };
+}
+/**
+ * Calculate wait time before retry
+ * Uses the exact reset time from headers if available, otherwise exponential backoff
+ */
+function getWaitTime(error, attempt, maxRetryDelay) {
+    let waitMs;
+    if (error.reset > 0) {
+        // Use the exact reset time from the header
+        waitMs = error.retryAfter;
+    }
+    else {
+        // Exponential backoff: 1s, 2s, 4s, 8s, etc.
+        waitMs = 1000 * Math.pow(2, attempt);
+    }
+    // Cap at maxRetryDelay
+    waitMs = Math.min(waitMs, maxRetryDelay);
+    // Add small jitter to prevent thundering herd (max 100ms)
+    const jitter = Math.random() * 100;
+    return waitMs + jitter;
+}
+/**
+ * Sleep for a specified number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/esm/rate_limit_headers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parses rate limit headers from HTTP responses
+ */
+export interface RateLimitHeaders {
+    limit: number | null;
+    remaining: number | null;
+    reset: number | null;
+}
+/**
+ * Extract rate limit information from response headers
+ */
+export declare function parseRateLimitHeaders(headers: Headers): RateLimitHeaders;

package/esm/rate_limit_headers.js

@@ -0,0 +1,20 @@
+/**
+ * Extract rate limit information from response headers
+ */
+export function parseRateLimitHeaders(headers) {
+    return {
+        limit: parseHeaderAsNumber(headers, "x-ratelimit-limit"),
+        remaining: parseHeaderAsNumber(headers, "x-ratelimit-remaining"),
+        reset: parseHeaderAsNumber(headers, "x-ratelimit-reset"),
+    };
+}
+/**
+ * Helper to parse a header value as a number
+ */
+function parseHeaderAsNumber(headers, headerName) {
+    const value = headers.get(headerName);
+    if (value === null)
+        return null;
+    const num = parseInt(value, 10);
+    return isNaN(num) ? null : num;
+}

package/package.json

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

package/script/mod.d.ts

@@ -1,5 +1,15 @@
 import { Api, ApiConfig, HttpResponse } from "./openapi/client.js";
-export declare const Client: (apiKey: string, apiConfig?: ApiConfig) => Api<unknown>;
+import type { RateLimitFetchConfig } from "./rate_limit_fetch.js";
+export interface LagoClientConfig extends ApiConfig {
+    /**
+     * Rate limit retry configuration
+     */
+    rateLimitRetry?: RateLimitFetchConfig;
+}
+export declare const Client: (apiKey: string, apiConfig?: LagoClientConfig) => Api<unknown>;
 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 * from "./openapi/client.js";

package/script/mod.js

@@ -14,17 +14,24 @@ 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.getLagoError = exports.Client = void 0;
+exports.createRateLimitFetch = 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");
 const Client = (apiKey, apiConfig) => {
+    const { rateLimitRetry, ...restConfig } = apiConfig ?? {};
+    // Create rate-limit-aware fetch if configured
+    const customFetch = rateLimitRetry
+        ? (0, rate_limit_fetch_js_1.createRateLimitFetch)((restConfig?.customFetch ?? globalThis.fetch), rateLimitRetry)
+        : restConfig?.customFetch;
     const api = new client_js_1.Api({
         securityWorker: (apiKey) => apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : {},
         // Cloudflare Workers doesn't support some options like credentials so need to override default
         baseApiParams: {
             redirect: "follow",
         },
-        ...apiConfig,
+        ...restConfig,
+        ...(customFetch && { customFetch }),
     });
     api.setSecurityData(apiKey);
     return api;
@@ -49,4 +56,11 @@ async function getLagoError(error) {
     throw new Error(error);
 }
 exports.getLagoError = getLagoError;
+// Rate limit exports
+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; } });
+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; } });
 __exportStar(require("./openapi/client.js"), exports);

package/script/openapi/client.d.ts

@@ -2226,6 +2226,16 @@ export interface FeeObject {
      * @example "0.0"
      */
     precise_coupons_amount_cents?: string;
+    /**
+     * The sub total of the fee excluding taxes, in cents.
+     * @example 100
+     */
+    sub_total_excluding_taxes_amount_cents: number;
+    /**
+     * The sub total of the fee excluding taxes, with precision.
+     * @example "100.0"
+     */
+    sub_total_excluding_taxes_precise_amount_cents: string;
     /** List of all unit amount details for calculating the fee. */
     amount_details?: FeeAmountDetails;
     /**
@@ -3837,18 +3847,20 @@ export interface AppliedInvoiceCustomSectionObject {
      * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
      */
     lago_id: string;
-    /**
-     * Unique identifier of the invoice custom section that was applied.
-     * @format uuid
-     * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
-     */
-    invoice_custom_section_id: string;
     /**
      * The date of the applied invoice custom section creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
      * @format date-time
      * @example "2023-07-06T14:35:58Z"
      */
     created_at: string;
+    /**
+     * Unique identifier of the invoice custom section that was applied.
+     * @deprecated
+     * @format uuid
+     * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
+     */
+    invoice_custom_section_id?: string;
+    invoice_custom_section: InvoiceCustomSectionObject;
 }
 /** Reference to a specific payment method for processing the payment. */
 export interface PaymentMethodReference {
@@ -4572,7 +4584,7 @@ export type AlertThresholdObject = AlertThresholdBaseObject & {
      */
     value: string;
 };
-export interface AlertObject {
+export interface WalletAlertObject {
     /**
      * Unique identifier of the alert, created by Lago.
      * @format uuid
@@ -4585,46 +4597,36 @@ export interface AlertObject {
      * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
      */
     lago_organization_id: string;
-    /**
-     * The subscription external unique identifier (provided by your own application).
-     * @example "sub_1234567890"
-     */
-    external_subscription_id: string | null;
-    /**
-     * The customer external unique identifier (provided by your own application).
-     * @example "cus_0987654321"
-     */
-    external_customer_id: string;
+    external_subscription_id: null;
     /**
      * Unique identifier of the wallet, created by Lago.
      * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
      */
-    lago_wallet_id?: string | null;
+    lago_wallet_id?: string;
     /**
      * The wallet external unique identifier (provided by your own application).
      * @example "wallet_code"
      */
-    wallet_code?: string | null;
-    /** The billable metric associated with the alert. Only for alerts based on a billable metric. */
-    billable_metric: BillableMetricObject;
+    wallet_code?: string;
+    billable_metric: null;
     /**
      * The type of alert.
-     * @example "billable_metric_current_usage_amount"
+     * @example "wallet_balance_amount"
      */
-    alert_type: "current_usage_amount" | "billable_metric_current_usage_amount" | "billable_metric_current_usage_units" | "lifetime_usage_amount";
+    alert_type: "wallet_balance_amount" | "wallet_credits_balance" | "wallet_ongoing_balance_amount" | "wallet_credits_ongoing_balance";
     /**
      * Unique code used to identify the alert.
-     * @example "storage_threshold_alert"
+     * @example "wallet_balance_alert"
      */
     code: string;
     /**
      * The name of the alert.
-     * @example "Storage Usage Alert"
+     * @example "Wallet Balance Alert"
      */
     name: string | null;
     /**
      * Indicates whether the alert is triggered when the monitored metric goes above or below the threshold.
-     * @example "increasing"
+     * @example "decreasing"
      */
     direction?: "increasing" | "decreasing";
     /**
@@ -4647,8 +4649,8 @@ export interface AlertObject {
      */
     created_at: string;
 }
-export interface Alerts {
-    alerts: AlertObject[];
+export interface WalletAlerts {
+    alerts: WalletAlertObject[];
     meta?: PaginationMeta;
 }
 export type AlertThresholdInput = AlertThresholdBaseObject & {
@@ -4678,7 +4680,7 @@ export interface WalletAlertCreateInput {
          * The type of alert.
          * @example "wallet_balance_amount"
          */
-        alert_type: "wallet_balance_amount" | "wallet_credits_balance";
+        alert_type: "wallet_balance_amount" | "wallet_credits_balance" | "wallet_ongoing_balance_amount" | "wallet_credits_ongoing_balance";
         /**
          * Unique code used to identify the alert.
          * @example "wallet_balance_alert"
@@ -4698,7 +4700,7 @@ export interface WalletAlertBatchCreateInput {
          * The type of alert.
          * @example "wallet_balance_amount"
          */
-        alert_type: "wallet_balance_amount" | "wallet_credits_balance";
+        alert_type: "wallet_balance_amount" | "wallet_credits_balance" | "wallet_ongoing_balance_amount" | "wallet_credits_ongoing_balance";
         /**
          * Unique code used to identify the alert.
          * @example "wallet_balance_alert"
@@ -4711,8 +4713,8 @@ export interface WalletAlertBatchCreateInput {
         name?: string | null;
     })[];
 }
-export interface Alert {
-    alert: AlertObject;
+export interface WalletAlert {
+    alert: WalletAlertObject;
 }
 export interface WalletAlertUpdateInput {
     alert: AlertBaseInput & {
@@ -7800,6 +7802,72 @@ export interface LifetimeUsageInput {
         external_historical_usage_amount_cents: number;
     };
 }
+export interface AlertObject {
+    /**
+     * Unique identifier of the alert, created by Lago.
+     * @format uuid
+     * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
+     */
+    lago_id: string;
+    /**
+     * Unique identifier of the organization, created by Lago.
+     * @format uuid
+     * @example "1a901a90-1a90-1a90-1a90-1a901a901a90"
+     */
+    lago_organization_id: string;
+    /**
+     * The subscription external unique identifier (provided by your own application).
+     * @example "sub_1234567890"
+     */
+    external_subscription_id: string | null;
+    lago_wallet_id?: null;
+    wallet_code?: null;
+    /** The billable metric associated with the alert. Only for alerts based on a billable metric. */
+    billable_metric: BillableMetricObject;
+    /**
+     * The type of alert.
+     * @example "billable_metric_current_usage_amount"
+     */
+    alert_type: "current_usage_amount" | "billable_metric_current_usage_amount" | "billable_metric_current_usage_units" | "lifetime_usage_amount";
+    /**
+     * Unique code used to identify the alert.
+     * @example "storage_threshold_alert"
+     */
+    code: string;
+    /**
+     * The name of the alert.
+     * @example "Storage Usage Alert"
+     */
+    name: string | null;
+    /**
+     * Indicates whether the alert is triggered when the monitored metric goes above or below the threshold.
+     * @example "increasing"
+     */
+    direction?: "increasing" | "decreasing";
+    /**
+     * When the system checked if this alert should be triggered, this value was retrieved and checked against the thresholds.
+     * @example 1000
+     */
+    previous_value: number;
+    /**
+     * The date and time in UTC (ISO 8601) when the system checked if this alert should be triggered. Null until it's processed for the first time.
+     * @format date-time
+     * @example "2025-05-19T10:04:21Z"
+     */
+    last_processed_at: string | null;
+    /** Array of thresholds associated with the alert. */
+    thresholds: AlertThresholdObject[];
+    /**
+     * The date and time in UTC (ISO 8601) when the alert was created.
+     * @format date-time
+     * @example "2025-03-20T10:00:00Z"
+     */
+    created_at: string;
+}
+export interface Alerts {
+    alerts: AlertObject[];
+    meta?: PaginationMeta;
+}
 export interface AlertCreateInput {
     alert: AlertBaseInput & {
         /**
@@ -7832,8 +7900,16 @@ export interface AlertBatchCreateInput {
          * @example "storage_threshold_alert"
          */
         code: string;
+        /**
+         * The code of the billable metric associated with the alert. Only for alerts based on a billable metric.
+         * @example "storage_usage"
+         */
+        billable_metric_code?: string | null;
     })[];
 }
+export interface Alert {
+    alert: AlertObject;
+}
 export interface AlertUpdateInput {
     alert: AlertBaseInput & {
         /**
@@ -10154,7 +10230,7 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request GET:/customers/{external_customer_id}/wallets/{wallet_code}/alerts
          * @secure
          */
-        getCustomerWalletAlerts: (externalCustomerId: string, walletCode: string, params?: RequestParams) => Promise<HttpResponse<Alerts, ApiErrorUnauthorized | ApiErrorNotFound>>;
+        getCustomerWalletAlerts: (externalCustomerId: string, walletCode: string, params?: RequestParams) => Promise<HttpResponse<WalletAlerts, ApiErrorUnauthorized | ApiErrorNotFound>>;
         /**
          * @description This endpoint allows you to create new alerts for a wallet. Send a single alert object wrapped in `alert` key to create one alert, or an array of alert objects wrapped in `alerts` key to create multiple alerts atomically.
          *
@@ -10164,7 +10240,7 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request POST:/customers/{external_customer_id}/wallets/{wallet_code}/alerts
          * @secure
          */
-        createCustomerWalletAlert: (externalCustomerId: string, walletCode: string, data: WalletAlertCreateInput | WalletAlertBatchCreateInput, params?: RequestParams) => Promise<HttpResponse<Alerts | Alert, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorBadRequest | ApiErrorNotFound>>;
+        createCustomerWalletAlert: (externalCustomerId: string, walletCode: string, data: WalletAlertCreateInput | WalletAlertBatchCreateInput, params?: RequestParams) => Promise<HttpResponse<WalletAlerts | WalletAlert, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorBadRequest | ApiErrorNotFound>>;
         /**
          * @description This endpoint allows you to delete all alerts for a wallet.
          *
@@ -10184,7 +10260,7 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request GET:/customers/{external_customer_id}/wallets/{wallet_code}/alerts/{code}
          * @secure
          */
-        getCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, params?: RequestParams) => Promise<HttpResponse<Alert, ApiErrorUnauthorized | ApiErrorNotFound>>;
+        getCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, params?: RequestParams) => Promise<HttpResponse<WalletAlert, ApiErrorUnauthorized | ApiErrorNotFound>>;
         /**
          * @description This endpoint allows you to update an existing alert for a wallet.
          *
@@ -10194,7 +10270,7 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request PUT:/customers/{external_customer_id}/wallets/{wallet_code}/alerts/{code}
          * @secure
          */
-        updateCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, data: WalletAlertUpdateInput, params?: RequestParams) => Promise<HttpResponse<Alert, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorBadRequest | ApiErrorNotFound>>;
+        updateCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, data: WalletAlertUpdateInput, params?: RequestParams) => Promise<HttpResponse<WalletAlert, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorBadRequest | ApiErrorNotFound>>;
         /**
          * @description This endpoint allows you to delete an existing alert for a wallet.
          *
@@ -10204,7 +10280,7 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request DELETE:/customers/{external_customer_id}/wallets/{wallet_code}/alerts/{code}
          * @secure
          */
-        deleteCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, params?: RequestParams) => Promise<HttpResponse<Alert, ApiErrorUnauthorized | ApiErrorNotFound>>;
+        deleteCustomerWalletAlert: (externalCustomerId: string, walletCode: string, code: string, params?: RequestParams) => Promise<HttpResponse<WalletAlert, ApiErrorUnauthorized | ApiErrorNotFound>>;
         /**
          * @description This endpoint enables the retrieval of the usage-based billing data for a customer within the current period.
          *
@@ -10316,7 +10392,9 @@ export declare class Api<SecurityDataType extends unknown> extends HttpClient<Se
          * @request POST:/customers/{external_customer_id}/checkout_url
          * @secure
          */
-        generateCustomerCheckoutUrl: (externalCustomerId: string, params?: RequestParams) => Promise<HttpResponse<CustomerCheckoutUrl, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorNotFound>>;
+        generateCustomerCheckoutUrl: (externalCustomerId: string, params?: RequestParams) => Promise<HttpResponse<{
+            customer: CustomerCheckoutUrl;
+        }, ApiErrorUnauthorized | ApiErrorUnprocessableEntity | ApiErrorNotFound>>;
         /**
          * @description This endpoint retrieves all payment methods of a Customer.
          *

package/script/rate_limit_error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Error class for rate limit (HTTP 429) responses
+ */
+export declare class LagoRateLimitError extends Error {
+    readonly limit: number;
+    readonly remaining: number;
+    readonly reset: number;
+    readonly retryAfter: number;
+    constructor(limit: number, remaining: number, reset: number);
+}

package/script/rate_limit_error.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LagoRateLimitError = void 0;
+/**
+ * Error class for rate limit (HTTP 429) responses
+ */
+class LagoRateLimitError extends Error {
+    limit;
+    remaining;
+    reset; // seconds until window resets
+    retryAfter; // milliseconds to wait before retrying
+    constructor(limit, remaining, reset) {
+        super(`Rate limit exceeded. Limit: ${limit}, Remaining: ${remaining}, Reset in: ${reset}s`);
+        this.name = "LagoRateLimitError";
+        this.limit = limit;
+        this.remaining = remaining;
+        this.reset = reset;
+        this.retryAfter = reset * 1000; // Convert seconds to milliseconds
+        // Maintain proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, LagoRateLimitError.prototype);
+    }
+}
+exports.LagoRateLimitError = LagoRateLimitError;

package/script/rate_limit_fetch.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Configuration for rate limit fetch behavior
+ */
+export interface RateLimitFetchConfig {
+    /** Maximum number of retries on 429 (default: 3) */
+    maxRetries?: number;
+    /** Whether to automatically retry on rate limit (default: true) */
+    retryOnRateLimit?: boolean;
+    /** Maximum delay in milliseconds before a retry (default: 20000) */
+    maxRetryDelay?: number;
+}
+/**
+ * Creates a fetch wrapper that handles rate limiting with automatic retry
+ * Compatible with both Node.js fetch and browser fetch APIs
+ */
+export declare function createRateLimitFetch(baseFetch: typeof fetch, config?: RateLimitFetchConfig): typeof fetch;

package/script/rate_limit_fetch.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRateLimitFetch = void 0;
+const rate_limit_error_js_1 = require("./rate_limit_error.js");
+const rate_limit_headers_js_1 = require("./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
+ */
+function createRateLimitFetch(baseFetch, config = {}) {
+    const maxRetries = config.maxRetries ?? 3;
+    const retryOnRateLimit = config.retryOnRateLimit ?? true;
+    const maxRetryDelay = config.maxRetryDelay ?? 20_000;
+    return async function rateLimitFetch(input, init) {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const response = await baseFetch(input, init);
+                // Handle 429 responses
+                if (response.status === 429) {
+                    const headers = (0, rate_limit_headers_js_1.parseRateLimitHeaders)(response.headers);
+                    const limit = headers.limit ?? -1;
+                    const remaining = headers.remaining ?? 0;
+                    const reset = headers.reset ?? -1;
+                    const error = new rate_limit_error_js_1.LagoRateLimitError(limit, remaining, reset);
+                    if (!retryOnRateLimit) {
+                        throw error;
+                    }
+                    if (attempt === maxRetries) {
+                        throw error; // Max retries reached
+                    }
+                    // Wait before retry
+                    const waitMs = getWaitTime(error, attempt, maxRetryDelay);
+                    await sleep(waitMs);
+                    continue; // Retry
+                }
+                // Success or non-rate-limit error - return the response
+                return response;
+            }
+            catch (error) {
+                lastError = error;
+                if (!(error instanceof rate_limit_error_js_1.LagoRateLimitError)) {
+                    throw error; // Not a rate limit error, rethrow immediately
+                }
+                if (attempt === maxRetries) {
+                    throw error; // Max retries reached
+                }
+                // Will retry on next iteration
+            }
+        }
+        throw lastError;
+    };
+}
+exports.createRateLimitFetch = createRateLimitFetch;
+/**
+ * Calculate wait time before retry
+ * Uses the exact reset time from headers if available, otherwise exponential backoff
+ */
+function getWaitTime(error, attempt, maxRetryDelay) {
+    let waitMs;
+    if (error.reset > 0) {
+        // Use the exact reset time from the header
+        waitMs = error.retryAfter;
+    }
+    else {
+        // Exponential backoff: 1s, 2s, 4s, 8s, etc.
+        waitMs = 1000 * Math.pow(2, attempt);
+    }
+    // Cap at maxRetryDelay
+    waitMs = Math.min(waitMs, maxRetryDelay);
+    // Add small jitter to prevent thundering herd (max 100ms)
+    const jitter = Math.random() * 100;
+    return waitMs + jitter;
+}
+/**
+ * Sleep for a specified number of milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/script/rate_limit_headers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Parses rate limit headers from HTTP responses
+ */
+export interface RateLimitHeaders {
+    limit: number | null;
+    remaining: number | null;
+    reset: number | null;
+}
+/**
+ * Extract rate limit information from response headers
+ */
+export declare function parseRateLimitHeaders(headers: Headers): RateLimitHeaders;

package/script/rate_limit_headers.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRateLimitHeaders = void 0;
+/**
+ * Extract rate limit information from response headers
+ */
+function parseRateLimitHeaders(headers) {
+    return {
+        limit: parseHeaderAsNumber(headers, "x-ratelimit-limit"),
+        remaining: parseHeaderAsNumber(headers, "x-ratelimit-remaining"),
+        reset: parseHeaderAsNumber(headers, "x-ratelimit-reset"),
+    };
+}
+exports.parseRateLimitHeaders = parseRateLimitHeaders;
+/**
+ * Helper to parse a header value as a number
+ */
+function parseHeaderAsNumber(headers, headerName) {
+    const value = headers.get(headerName);
+    if (value === null)
+        return null;
+    const num = parseInt(value, 10);
+    return isNaN(num) ? null : num;
+}