lago-javascript-client 1.45.0 → 1.46.0

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 {
@@ -10316,7 +10328,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.0",
   "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 {
@@ -10316,7 +10328,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;
+}