ezthrottle 1.1.1 → 1.4.0

package/dist/client.d.ts

@@ -54,5 +54,113 @@ export declare class EZThrottle {
     queueRequest({ url, webhookUrl, method, headers, body, metadata, retryAt }: QueueRequestParams): Promise<any>;
     request({ url, method, headers, body }: RequestParams): Promise<any>;
     queueAndWait({ url, webhookUrl, method, headers, body, metadata, retryAt, timeout, pollInterval, }: QueueAndWaitParams): Promise<any>;
+    /**
+     * Create or update webhook HMAC secrets for signature verification.
+     *
+     * @param primarySecret - Primary webhook secret (min 16 characters)
+     * @param secondarySecret - Optional secondary secret for rotation (min 16 characters)
+     * @returns Response with status and message
+     * @throws {Error} If secret creation fails
+     *
+     * @example
+     * ```typescript
+     * // Create primary secret
+     * await client.createWebhookSecret('your_secure_secret_here_min_16_chars');
+     *
+     * // Create with rotation support (primary + secondary)
+     * await client.createWebhookSecret(
+     *   'new_secret_after_rotation',
+     *   'old_secret_before_rotation'
+     * );
+     * ```
+     */
+    createWebhookSecret(primarySecret: string, secondarySecret?: string): Promise<any>;
+    /**
+     * Get webhook secrets (masked for security).
+     *
+     * @returns Object with masked secrets
+     * @throws {Error} If secrets not configured (404) or request fails
+     *
+     * @example
+     * ```typescript
+     * const secrets = await client.getWebhookSecret();
+     * console.log(secrets);
+     * // {
+     * //   customer_id: 'cust_XXX',
+     * //   primary_secret: 'your****ars',
+     * //   secondary_secret: 'opti****ars',
+     * //   has_secondary: true
+     * // }
+     * ```
+     */
+    getWebhookSecret(): Promise<any>;
+    /**
+     * Delete webhook secrets.
+     *
+     * @returns Response with status and message
+     * @throws {Error} If deletion fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.deleteWebhookSecret();
+     * console.log(result); // { status: 'ok', message: 'Webhook secrets deleted' }
+     * ```
+     */
+    deleteWebhookSecret(): Promise<any>;
+    /**
+     * Rotate webhook secret safely by promoting secondary to primary.
+     *
+     * @param newSecret - New webhook secret to set as primary
+     * @returns Response with status and message
+     *
+     * @example
+     * ```typescript
+     * // Step 1: Rotate (keeps old secret as backup)
+     * await client.rotateWebhookSecret('new_secret_min_16_chars');
+     *
+     * // Step 2: After verifying webhooks work with new secret
+     * // Remove old secret by setting only new one
+     * await client.createWebhookSecret('new_secret_min_16_chars');
+     * ```
+     */
+    /**
+     * Try to forward request to EZThrottle, fall back to callback if EZThrottle is unreachable.
+     *
+     * This makes EZThrottle a reliability LAYER, not a single point of failure.
+     * If EZThrottle is down, you just lose the extra reliability features and
+     * fall back to your existing solution.
+     *
+     * @param fallback - Callback function to execute if EZThrottle is unreachable
+     * @param options - Job options (same as submitJob)
+     * @returns Either EZThrottle job response or the fallback function's return value
+     *
+     * @example
+     * ```typescript
+     * // If EZThrottle is down, fall back to direct HTTP call
+     * const result = await client.forwardOrFallback(
+     *   async () => {
+     *     const response = await fetch('https://api.stripe.com/charges', {
+     *       method: 'POST',
+     *       headers: { 'Authorization': 'Bearer sk_live_...' },
+     *       body: JSON.stringify({ amount: 1000 })
+     *     });
+     *     return response.json();
+     *   },
+     *   {
+     *     url: 'https://api.stripe.com/charges',
+     *     method: 'POST',
+     *     headers: { 'Authorization': 'Bearer sk_live_...' },
+     *     body: JSON.stringify({ amount: 1000 }),
+     *     webhooks: [{ url: 'https://your-app.com/webhook' }]
+     *   }
+     * );
+     * ```
+     *
+     * Note: The fallback is ONLY called when EZThrottle itself is unreachable
+     * (connection errors, timeouts). It is NOT called for rate limiting or
+     * other EZThrottle errors - those indicate EZThrottle is working.
+     */
+    forwardOrFallback<T>(fallback: () => Promise<T>, options: SubmitJobParams): Promise<any | T>;
+    rotateWebhookSecret(newSecret: string): Promise<any>;
 }
 export {};

package/dist/client.js

@@ -173,5 +173,256 @@ class EZThrottle {
             checkResult();
         });
     }
+    // ============================================================================
+    // WEBHOOK SECRETS MANAGEMENT
+    // ============================================================================
+    /**
+     * Create or update webhook HMAC secrets for signature verification.
+     *
+     * @param primarySecret - Primary webhook secret (min 16 characters)
+     * @param secondarySecret - Optional secondary secret for rotation (min 16 characters)
+     * @returns Response with status and message
+     * @throws {Error} If secret creation fails
+     *
+     * @example
+     * ```typescript
+     * // Create primary secret
+     * await client.createWebhookSecret('your_secure_secret_here_min_16_chars');
+     *
+     * // Create with rotation support (primary + secondary)
+     * await client.createWebhookSecret(
+     *   'new_secret_after_rotation',
+     *   'old_secret_before_rotation'
+     * );
+     * ```
+     */
+    async createWebhookSecret(primarySecret, secondarySecret) {
+        if (primarySecret.length < 16) {
+            throw new Error('primarySecret must be at least 16 characters');
+        }
+        if (secondarySecret && secondarySecret.length < 16) {
+            throw new Error('secondarySecret must be at least 16 characters');
+        }
+        const payload = { primary_secret: primarySecret };
+        if (secondarySecret) {
+            payload.secondary_secret = secondarySecret;
+        }
+        const proxyPayload = {
+            scope: 'customer',
+            metric_name: '',
+            target_url: `${this.ezthrottleUrl}/api/v1/webhook-secrets`,
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(payload),
+        };
+        const response = await (0, node_fetch_1.default)(`${this.tracktagsUrl}/api/v1/proxy`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(proxyPayload),
+        });
+        if (response.status !== 200) {
+            const text = await response.text();
+            throw new errors_1.EZThrottleError(`Failed to create webhook secret: ${text}`);
+        }
+        const proxyResponse = await response.json();
+        if (proxyResponse.status !== 'allowed') {
+            throw new errors_1.EZThrottleError(`Request denied: ${proxyResponse.error || 'Unknown error'}`);
+        }
+        const forwarded = proxyResponse.forwarded_response || {};
+        return JSON.parse(forwarded.body || '{}');
+    }
+    /**
+     * Get webhook secrets (masked for security).
+     *
+     * @returns Object with masked secrets
+     * @throws {Error} If secrets not configured (404) or request fails
+     *
+     * @example
+     * ```typescript
+     * const secrets = await client.getWebhookSecret();
+     * console.log(secrets);
+     * // {
+     * //   customer_id: 'cust_XXX',
+     * //   primary_secret: 'your****ars',
+     * //   secondary_secret: 'opti****ars',
+     * //   has_secondary: true
+     * // }
+     * ```
+     */
+    async getWebhookSecret() {
+        const proxyPayload = {
+            scope: 'customer',
+            metric_name: '',
+            target_url: `${this.ezthrottleUrl}/api/v1/webhook-secrets`,
+            method: 'GET',
+            headers: {},
+            body: '',
+        };
+        const response = await (0, node_fetch_1.default)(`${this.tracktagsUrl}/api/v1/proxy`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(proxyPayload),
+        });
+        if (response.status !== 200) {
+            const text = await response.text();
+            throw new errors_1.EZThrottleError(`Failed to get webhook secret: ${text}`);
+        }
+        const proxyResponse = await response.json();
+        if (proxyResponse.status !== 'allowed') {
+            throw new errors_1.EZThrottleError(`Request denied: ${proxyResponse.error || 'Unknown error'}`);
+        }
+        const forwarded = proxyResponse.forwarded_response || {};
+        const statusCode = forwarded.status_code || 0;
+        if (statusCode === 404) {
+            throw new errors_1.EZThrottleError('No webhook secrets configured. Call createWebhookSecret() first.');
+        }
+        if (statusCode < 200 || statusCode >= 300) {
+            throw new errors_1.EZThrottleError(`Failed to get webhook secrets: ${forwarded.body}`);
+        }
+        return JSON.parse(forwarded.body || '{}');
+    }
+    /**
+     * Delete webhook secrets.
+     *
+     * @returns Response with status and message
+     * @throws {Error} If deletion fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.deleteWebhookSecret();
+     * console.log(result); // { status: 'ok', message: 'Webhook secrets deleted' }
+     * ```
+     */
+    async deleteWebhookSecret() {
+        const proxyPayload = {
+            scope: 'customer',
+            metric_name: '',
+            target_url: `${this.ezthrottleUrl}/api/v1/webhook-secrets`,
+            method: 'DELETE',
+            headers: {},
+            body: '',
+        };
+        const response = await (0, node_fetch_1.default)(`${this.tracktagsUrl}/api/v1/proxy`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(proxyPayload),
+        });
+        if (response.status !== 200) {
+            const text = await response.text();
+            throw new errors_1.EZThrottleError(`Failed to delete webhook secret: ${text}`);
+        }
+        const proxyResponse = await response.json();
+        if (proxyResponse.status !== 'allowed') {
+            throw new errors_1.EZThrottleError(`Request denied: ${proxyResponse.error || 'Unknown error'}`);
+        }
+        const forwarded = proxyResponse.forwarded_response || {};
+        return JSON.parse(forwarded.body || '{}');
+    }
+    /**
+     * Rotate webhook secret safely by promoting secondary to primary.
+     *
+     * @param newSecret - New webhook secret to set as primary
+     * @returns Response with status and message
+     *
+     * @example
+     * ```typescript
+     * // Step 1: Rotate (keeps old secret as backup)
+     * await client.rotateWebhookSecret('new_secret_min_16_chars');
+     *
+     * // Step 2: After verifying webhooks work with new secret
+     * // Remove old secret by setting only new one
+     * await client.createWebhookSecret('new_secret_min_16_chars');
+     * ```
+     */
+    /**
+     * Try to forward request to EZThrottle, fall back to callback if EZThrottle is unreachable.
+     *
+     * This makes EZThrottle a reliability LAYER, not a single point of failure.
+     * If EZThrottle is down, you just lose the extra reliability features and
+     * fall back to your existing solution.
+     *
+     * @param fallback - Callback function to execute if EZThrottle is unreachable
+     * @param options - Job options (same as submitJob)
+     * @returns Either EZThrottle job response or the fallback function's return value
+     *
+     * @example
+     * ```typescript
+     * // If EZThrottle is down, fall back to direct HTTP call
+     * const result = await client.forwardOrFallback(
+     *   async () => {
+     *     const response = await fetch('https://api.stripe.com/charges', {
+     *       method: 'POST',
+     *       headers: { 'Authorization': 'Bearer sk_live_...' },
+     *       body: JSON.stringify({ amount: 1000 })
+     *     });
+     *     return response.json();
+     *   },
+     *   {
+     *     url: 'https://api.stripe.com/charges',
+     *     method: 'POST',
+     *     headers: { 'Authorization': 'Bearer sk_live_...' },
+     *     body: JSON.stringify({ amount: 1000 }),
+     *     webhooks: [{ url: 'https://your-app.com/webhook' }]
+     *   }
+     * );
+     * ```
+     *
+     * Note: The fallback is ONLY called when EZThrottle itself is unreachable
+     * (connection errors, timeouts). It is NOT called for rate limiting or
+     * other EZThrottle errors - those indicate EZThrottle is working.
+     */
+    async forwardOrFallback(fallback, options) {
+        try {
+            return await this.submitJob(options);
+        }
+        catch (error) {
+            // Check if it's a network/connection error
+            if (error.code === 'ECONNREFUSED' ||
+                error.code === 'ENOTFOUND' ||
+                error.code === 'ETIMEDOUT' ||
+                error.code === 'ECONNRESET' ||
+                error.name === 'AbortError' ||
+                error.type === 'system') {
+                // EZThrottle is unreachable - use fallback
+                return fallback();
+            }
+            // Re-throw other errors (rate limiting, validation, etc.)
+            throw error;
+        }
+    }
+    async rotateWebhookSecret(newSecret) {
+        if (newSecret.length < 16) {
+            throw new Error('newSecret must be at least 16 characters');
+        }
+        try {
+            // Get current secret to use as secondary
+            const current = await this.getWebhookSecret();
+            const oldPrimary = current.primary_secret || '';
+            // If we have a masked secret, we can't use it as secondary
+            // In this case, just set the new secret without secondary
+            if (oldPrimary.includes('****')) {
+                return this.createWebhookSecret(newSecret);
+            }
+            // Set new as primary, old as secondary
+            return this.createWebhookSecret(newSecret, oldPrimary);
+        }
+        catch (error) {
+            if (error instanceof errors_1.EZThrottleError &&
+                error.message.includes('No webhook secrets configured')) {
+                // No existing secret, just create new one
+                return this.createWebhookSecret(newSecret);
+            }
+            throw error;
+        }
+    }
 }
 exports.EZThrottle = EZThrottle;

package/dist/forward.d.ts

@@ -0,0 +1,75 @@
+import { EZThrottle } from './client';
+import { StepType } from './stepType';
+import { WebhookConfig } from './types';
+/**
+ * ForwardRequest - Represents a request that should be forwarded to EZThrottle
+ *
+ * Use this with executeWithForwarding() to integrate EZThrottle into legacy code
+ * without rewriting error handling.
+ */
+export interface ForwardRequest {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    idempotentKey?: string;
+    metadata?: Record<string, any>;
+    webhooks?: WebhookConfig[];
+    regions?: string[];
+    fallbackOnError?: number[];
+    stepType?: StepType;
+}
+/**
+ * executeWithForwarding - Higher-order function that wraps legacy code to auto-forward errors
+ *
+ * This is the Node.js equivalent of Python's @auto_forward decorator.
+ *
+ * @example
+ * ```typescript
+ * // Legacy function that may throw ForwardRequest on errors
+ * async function processPayment(orderId: string): Promise<any> {
+ *   try {
+ *     const response = await fetch('https://api.stripe.com/charges', {...});
+ *     if (response.status === 429) {
+ *       // Return ForwardRequest to trigger auto-forwarding
+ *       return {
+ *         forward: {
+ *           url: 'https://api.stripe.com/charges',
+ *           method: 'POST',
+ *           idempotentKey: `order_${orderId}`,
+ *           webhooks: [{url: 'https://app.com/webhook', hasQuorumVote: true}]
+ *         }
+ *       };
+ *     }
+ *     return await response.json();
+ *   } catch (error) {
+ *     // Network error - forward to EZThrottle
+ *     return {
+ *       forward: {
+ *         url: 'https://api.stripe.com/charges',
+ *         method: 'POST',
+ *         idempotentKey: `order_${orderId}`
+ *       }
+ *     };
+ *   }
+ * }
+ *
+ * // Wrap with auto-forwarding
+ * const result = await executeWithForwarding(client, () => processPayment('order_123'));
+ * ```
+ */
+export declare function executeWithForwarding<T>(client: EZThrottle, fn: () => Promise<T | {
+    forward: ForwardRequest;
+}>): Promise<T | any>;
+/**
+ * withAutoForward - Decorator-style wrapper for async functions
+ *
+ * @example
+ * ```typescript
+ * const processPaymentWithForwarding = withAutoForward(client, processPayment);
+ * const result = await processPaymentWithForwarding('order_123');
+ * ```
+ */
+export declare function withAutoForward<TArgs extends any[], TReturn>(client: EZThrottle, fn: (...args: TArgs) => Promise<TReturn | {
+    forward: ForwardRequest;
+}>): (...args: TArgs) => Promise<TReturn | any>;

package/dist/forward.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWithForwarding = executeWithForwarding;
+exports.withAutoForward = withAutoForward;
+const step_1 = require("./step");
+const stepType_1 = require("./stepType");
+/**
+ * executeWithForwarding - Higher-order function that wraps legacy code to auto-forward errors
+ *
+ * This is the Node.js equivalent of Python's @auto_forward decorator.
+ *
+ * @example
+ * ```typescript
+ * // Legacy function that may throw ForwardRequest on errors
+ * async function processPayment(orderId: string): Promise<any> {
+ *   try {
+ *     const response = await fetch('https://api.stripe.com/charges', {...});
+ *     if (response.status === 429) {
+ *       // Return ForwardRequest to trigger auto-forwarding
+ *       return {
+ *         forward: {
+ *           url: 'https://api.stripe.com/charges',
+ *           method: 'POST',
+ *           idempotentKey: `order_${orderId}`,
+ *           webhooks: [{url: 'https://app.com/webhook', hasQuorumVote: true}]
+ *         }
+ *       };
+ *     }
+ *     return await response.json();
+ *   } catch (error) {
+ *     // Network error - forward to EZThrottle
+ *     return {
+ *       forward: {
+ *         url: 'https://api.stripe.com/charges',
+ *         method: 'POST',
+ *         idempotentKey: `order_${orderId}`
+ *       }
+ *     };
+ *   }
+ * }
+ *
+ * // Wrap with auto-forwarding
+ * const result = await executeWithForwarding(client, () => processPayment('order_123'));
+ * ```
+ */
+async function executeWithForwarding(client, fn) {
+    const result = await fn();
+    // Check if result contains a ForwardRequest
+    if (result && typeof result === 'object' && 'forward' in result) {
+        const forwardReq = result.forward;
+        // Auto-forward to EZThrottle
+        const step = new step_1.Step(client)
+            .url(forwardReq.url)
+            .method(forwardReq.method || 'GET');
+        if (forwardReq.headers) {
+            step.headers(forwardReq.headers);
+        }
+        if (forwardReq.body) {
+            step.body(forwardReq.body);
+        }
+        if (forwardReq.idempotentKey) {
+            step.idempotentKey(forwardReq.idempotentKey);
+        }
+        if (forwardReq.metadata) {
+            step.metadata(forwardReq.metadata);
+        }
+        if (forwardReq.webhooks) {
+            step.webhooks(forwardReq.webhooks);
+        }
+        if (forwardReq.regions) {
+            step.regions(forwardReq.regions);
+        }
+        // Set step type (default to FRUGAL if not specified)
+        if (forwardReq.stepType) {
+            step.type(forwardReq.stepType);
+        }
+        else {
+            step.type(stepType_1.StepType.FRUGAL);
+        }
+        // Set fallback on error codes if specified
+        if (forwardReq.fallbackOnError && forwardReq.fallbackOnError.length > 0) {
+            step.fallbackOnError(forwardReq.fallbackOnError);
+        }
+        return await step.execute();
+    }
+    return result;
+}
+/**
+ * withAutoForward - Decorator-style wrapper for async functions
+ *
+ * @example
+ * ```typescript
+ * const processPaymentWithForwarding = withAutoForward(client, processPayment);
+ * const result = await processPaymentWithForwarding('order_123');
+ * ```
+ */
+function withAutoForward(client, fn) {
+    return async (...args) => {
+        return executeWithForwarding(client, () => fn(...args));
+    };
+}

package/dist/index.d.ts

@@ -4,5 +4,8 @@ export { Step } from './step';
 export { StepType } from './stepType';
 export { IdempotentStrategy } from './idempotentStrategy';
 export * from './types';
+export { executeWithForwarding, withAutoForward } from './forward';
+export type { ForwardRequest } from './forward';
+export { verifyWebhookSignature, verifyWebhookSignatureStrict, tryVerifyWithSecrets, WebhookVerificationError, VerificationResult } from './webhookUtils';
 import { EZThrottle } from './client';
 export default EZThrottle;

package/dist/index.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.IdempotentStrategy = exports.StepType = exports.Step = exports.RateLimitError = exports.TimeoutError = exports.EZThrottleError = exports.EZThrottle = void 0;
+exports.WebhookVerificationError = exports.tryVerifyWithSecrets = exports.verifyWebhookSignatureStrict = exports.verifyWebhookSignature = exports.withAutoForward = exports.executeWithForwarding = exports.IdempotentStrategy = exports.StepType = exports.Step = exports.RateLimitError = exports.TimeoutError = exports.EZThrottleError = exports.EZThrottle = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "EZThrottle", { enumerable: true, get: function () { return client_1.EZThrottle; } });
 var errors_1 = require("./errors");
@@ -28,6 +28,14 @@ Object.defineProperty(exports, "StepType", { enumerable: true, get: function ()
 var idempotentStrategy_1 = require("./idempotentStrategy");
 Object.defineProperty(exports, "IdempotentStrategy", { enumerable: true, get: function () { return idempotentStrategy_1.IdempotentStrategy; } });
 __exportStar(require("./types"), exports);
+var forward_1 = require("./forward");
+Object.defineProperty(exports, "executeWithForwarding", { enumerable: true, get: function () { return forward_1.executeWithForwarding; } });
+Object.defineProperty(exports, "withAutoForward", { enumerable: true, get: function () { return forward_1.withAutoForward; } });
+var webhookUtils_1 = require("./webhookUtils");
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhookUtils_1.verifyWebhookSignature; } });
+Object.defineProperty(exports, "verifyWebhookSignatureStrict", { enumerable: true, get: function () { return webhookUtils_1.verifyWebhookSignatureStrict; } });
+Object.defineProperty(exports, "tryVerifyWithSecrets", { enumerable: true, get: function () { return webhookUtils_1.tryVerifyWithSecrets; } });
+Object.defineProperty(exports, "WebhookVerificationError", { enumerable: true, get: function () { return webhookUtils_1.WebhookVerificationError; } });
 // Default export for CommonJS compatibility
 const client_2 = require("./client");
 exports.default = client_2.EZThrottle;