@teneo-protocol/sdk 1.0.0

package/dist/utils/rate-limiter.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Token Bucket Rate Limiter
+ * Prevents message flooding and ensures fair resource usage
+ *
+ * Uses the token bucket algorithm: tokens are added at a constant rate,
+ * and each operation consumes one token. When no tokens are available,
+ * operations must wait until tokens are replenished.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenBucketRateLimiter = exports.RateLimitError = void 0;
+/**
+ * Error thrown when rate limit is exceeded with tryConsume()
+ */
+class RateLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RateLimitError';
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, RateLimitError);
+        }
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * Token bucket rate limiter for controlling operation frequency
+ *
+ * @example
+ * ```typescript
+ * // Allow 10 messages per second with burst of 20
+ * const limiter = new TokenBucketRateLimiter(10, 20);
+ *
+ * // Non-blocking check
+ * if (limiter.tryConsume()) {
+ *   await sendMessage(msg);
+ * } else {
+ *   console.log('Rate limit exceeded');
+ * }
+ *
+ * // Blocking wait (auto-waits for token)
+ * await limiter.consume();
+ * await sendMessage(msg);
+ * ```
+ */
+class TokenBucketRateLimiter {
+    /**
+     * Creates a new token bucket rate limiter
+     *
+     * @param tokensPerSecond - Rate at which tokens are added (operations per second)
+     * @param maxBurst - Maximum tokens that can accumulate (burst capacity)
+     * @throws {Error} If tokensPerSecond or maxBurst is less than 1
+     *
+     * @example
+     * ```typescript
+     * // 10 ops/sec, burst up to 20
+     * const limiter = new TokenBucketRateLimiter(10, 20);
+     * ```
+     */
+    constructor(tokensPerSecond, maxBurst) {
+        this.tokensPerSecond = tokensPerSecond;
+        this.maxBurst = maxBurst;
+        if (tokensPerSecond < 1) {
+            throw new Error('TokenBucketRateLimiter tokensPerSecond must be at least 1');
+        }
+        if (maxBurst < 1) {
+            throw new Error('TokenBucketRateLimiter maxBurst must be at least 1');
+        }
+        this.tokens = maxBurst; // Start with full bucket
+        this.lastRefill = Date.now();
+        this.refillInterval = 1000 / tokensPerSecond; // ms between tokens
+    }
+    /**
+     * Try to consume one token without blocking
+     *
+     * @returns true if token was consumed, false if no tokens available
+     *
+     * @example
+     * ```typescript
+     * if (limiter.tryConsume()) {
+     *   // Proceed with operation
+     * } else {
+     *   // Rate limited - handle accordingly
+     * }
+     * ```
+     */
+    tryConsume() {
+        this.refill();
+        if (this.tokens >= 1) {
+            this.tokens -= 1;
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Consume one token, waiting if necessary until a token is available
+     *
+     * @param timeout - Optional max wait time in ms (default: no timeout)
+     * @returns Promise that resolves when token is consumed
+     * @throws {RateLimitError} If timeout is exceeded
+     *
+     * @example
+     * ```typescript
+     * // Wait indefinitely for token
+     * await limiter.consume();
+     *
+     * // Wait max 5 seconds
+     * try {
+     *   await limiter.consume(5000);
+     * } catch (error) {
+     *   console.log('Timeout waiting for rate limit');
+     * }
+     * ```
+     */
+    async consume(timeout) {
+        const startTime = Date.now();
+        while (true) {
+            if (this.tryConsume()) {
+                return;
+            }
+            // Check timeout
+            const elapsed = Date.now() - startTime;
+            if (timeout !== undefined && elapsed >= timeout) {
+                throw new RateLimitError(`Rate limit timeout: no token available after ${timeout}ms`);
+            }
+            // Calculate wait time until next token
+            // If timeout is specified, don't wait longer than remaining timeout
+            const baseWaitTime = Math.min(this.refillInterval, 100);
+            const waitTime = timeout !== undefined
+                ? Math.min(baseWaitTime, timeout - elapsed)
+                : baseWaitTime;
+            // If waitTime is very small or negative, check timeout immediately
+            if (waitTime <= 0) {
+                continue;
+            }
+            await this.sleep(waitTime);
+        }
+    }
+    /**
+     * Get the number of tokens currently available
+     * Refills tokens before returning count
+     *
+     * @returns Number of tokens available (may be fractional before consumption)
+     */
+    getAvailableTokens() {
+        this.refill();
+        return this.tokens;
+    }
+    /**
+     * Get rate limiter configuration
+     *
+     * @returns Configuration object with rate and burst capacity
+     */
+    getConfig() {
+        return {
+            tokensPerSecond: this.tokensPerSecond,
+            maxBurst: this.maxBurst
+        };
+    }
+    /**
+     * Reset the rate limiter to full capacity
+     * Useful for testing or manual reset scenarios
+     */
+    reset() {
+        this.tokens = this.maxBurst;
+        this.lastRefill = Date.now();
+    }
+    /**
+     * Refill tokens based on elapsed time since last refill
+     * Called automatically before token consumption
+     */
+    refill() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        if (elapsed > 0) {
+            // Calculate tokens to add based on elapsed time
+            const tokensToAdd = elapsed / this.refillInterval;
+            // Add tokens, capped at maxBurst
+            this.tokens = Math.min(this.tokens + tokensToAdd, this.maxBurst);
+            this.lastRefill = now;
+        }
+    }
+    /**
+     * Sleep helper for async waiting
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.TokenBucketRateLimiter = TokenBucketRateLimiter;
+//# sourceMappingURL=rate-limiter.js.map

package/dist/utils/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../src/utils/rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/utils/retry-policy.d.ts

@@ -0,0 +1,191 @@
+/**
+ * RetryPolicy - Configurable retry strategy for connection and webhook retries
+ * Supports exponential, linear, and constant backoff strategies
+ */
+import { z } from "zod";
+/**
+ * Retry strategy types
+ */
+export type RetryStrategyType = "exponential" | "linear" | "constant";
+/**
+ * Retry strategy configuration
+ */
+export interface RetryStrategy {
+    /** Strategy type: exponential, linear, or constant */
+    type: RetryStrategyType;
+    /** Base delay in milliseconds (first retry delay) */
+    baseDelay: number;
+    /** Maximum delay cap in milliseconds */
+    maxDelay: number;
+    /** Maximum number of retry attempts (0 = no retries) */
+    maxAttempts: number;
+    /** Add random jitter to prevent thundering herd */
+    jitter: boolean;
+    /** Backoff multiplier for exponential strategy (default: 2) */
+    backoffMultiplier?: number;
+}
+/**
+ * Zod schema for retry strategy validation
+ */
+export declare const RetryStrategySchema: z.ZodObject<{
+    type: z.ZodEnum<["exponential", "linear", "constant"]>;
+    baseDelay: z.ZodNumber;
+    maxDelay: z.ZodNumber;
+    maxAttempts: z.ZodNumber;
+    jitter: z.ZodBoolean;
+    backoffMultiplier: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    type: "exponential" | "linear" | "constant";
+    baseDelay: number;
+    maxDelay: number;
+    maxAttempts: number;
+    jitter: boolean;
+    backoffMultiplier?: number | undefined;
+}, {
+    type: "exponential" | "linear" | "constant";
+    baseDelay: number;
+    maxDelay: number;
+    maxAttempts: number;
+    jitter: boolean;
+    backoffMultiplier?: number | undefined;
+}>;
+/**
+ * RetryPolicy - Calculates retry delays and determines retry eligibility
+ *
+ * Supports three retry strategies:
+ * - **Exponential**: Delay increases exponentially (e.g., 1s, 2s, 4s, 8s, ...)
+ * - **Linear**: Delay increases linearly (e.g., 1s, 2s, 3s, 4s, ...)
+ * - **Constant**: Delay remains constant (e.g., 1s, 1s, 1s, 1s, ...)
+ *
+ * All strategies respect maxDelay cap and support optional jitter.
+ *
+ * @example
+ * ```typescript
+ * // Exponential backoff with default multiplier of 2
+ * const policy = RetryPolicy.exponential(1000, 60000, 10, true);
+ * console.log(policy.calculateDelay(1)); // ~1000ms
+ * console.log(policy.calculateDelay(2)); // ~2000ms
+ * console.log(policy.calculateDelay(3)); // ~4000ms
+ *
+ * // Linear backoff
+ * const policy = RetryPolicy.linear(2000, 30000, 5, false);
+ * console.log(policy.calculateDelay(1)); // 2000ms
+ * console.log(policy.calculateDelay(2)); // 4000ms
+ * console.log(policy.calculateDelay(3)); // 6000ms
+ *
+ * // Constant delay
+ * const policy = RetryPolicy.constant(5000, 3);
+ * console.log(policy.calculateDelay(1)); // 5000ms
+ * console.log(policy.calculateDelay(2)); // 5000ms
+ * console.log(policy.calculateDelay(3)); // 5000ms
+ * ```
+ */
+export declare class RetryPolicy {
+    private readonly strategy;
+    /**
+     * Creates a new retry policy with the specified strategy
+     *
+     * @param strategy - Retry strategy configuration
+     * @throws {z.ZodError} If strategy is invalid
+     */
+    constructor(strategy: RetryStrategy);
+    /**
+     * Calculates the retry delay for a given attempt number
+     *
+     * @param attempt - Attempt number (1-indexed: 1 = first retry)
+     * @returns Delay in milliseconds before next retry
+     *
+     * @example
+     * ```typescript
+     * const policy = RetryPolicy.exponential(1000, 60000, 10, true);
+     *
+     * // First retry after 1st failure
+     * policy.calculateDelay(1); // ~1000ms (+ jitter if enabled)
+     *
+     * // Second retry after 2nd failure
+     * policy.calculateDelay(2); // ~2000ms (+ jitter if enabled)
+     * ```
+     */
+    calculateDelay(attempt: number): number;
+    /**
+     * Determines if a retry should be attempted based on attempt count
+     *
+     * @param attempt - Current attempt number (1-indexed)
+     * @returns True if retry should be attempted, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const policy = RetryPolicy.exponential(1000, 60000, 3, false);
+     *
+     * policy.shouldRetry(1); // true
+     * policy.shouldRetry(2); // true
+     * policy.shouldRetry(3); // true
+     * policy.shouldRetry(4); // false - exceeded maxAttempts
+     * ```
+     */
+    shouldRetry(attempt: number): boolean;
+    /**
+     * Gets the retry strategy configuration
+     *
+     * @returns Copy of the retry strategy
+     */
+    getStrategy(): Readonly<RetryStrategy>;
+    /**
+     * Creates a retry policy with exponential backoff
+     *
+     * Delay formula: `min(baseDelay * multiplier^(attempt-1), maxDelay) + jitter`
+     *
+     * @param baseDelay - Initial delay in milliseconds
+     * @param maxDelay - Maximum delay cap in milliseconds
+     * @param maxAttempts - Maximum retry attempts
+     * @param jitter - Add random jitter (0-1000ms)
+     * @param backoffMultiplier - Exponential multiplier (default: 2)
+     * @returns RetryPolicy instance with exponential strategy
+     *
+     * @example
+     * ```typescript
+     * // Standard exponential backoff (2^n)
+     * const policy = RetryPolicy.exponential(1000, 60000, 10, true);
+     *
+     * // Faster exponential backoff (3^n)
+     * const aggressive = RetryPolicy.exponential(1000, 60000, 10, true, 3);
+     * ```
+     */
+    static exponential(baseDelay: number, maxDelay: number, maxAttempts: number, jitter: boolean, backoffMultiplier?: number): RetryPolicy;
+    /**
+     * Creates a retry policy with linear backoff
+     *
+     * Delay formula: `min(baseDelay * attempt, maxDelay) + jitter`
+     *
+     * @param baseDelay - Delay increment per attempt in milliseconds
+     * @param maxDelay - Maximum delay cap in milliseconds
+     * @param maxAttempts - Maximum retry attempts
+     * @param jitter - Add random jitter (0-1000ms)
+     * @returns RetryPolicy instance with linear strategy
+     *
+     * @example
+     * ```typescript
+     * // Linear backoff: 2s, 4s, 6s, 8s, ...
+     * const policy = RetryPolicy.linear(2000, 30000, 10, false);
+     * ```
+     */
+    static linear(baseDelay: number, maxDelay: number, maxAttempts: number, jitter: boolean): RetryPolicy;
+    /**
+     * Creates a retry policy with constant delay
+     *
+     * Delay formula: `baseDelay + jitter`
+     *
+     * @param delay - Constant delay in milliseconds
+     * @param maxAttempts - Maximum retry attempts
+     * @param jitter - Add random jitter (0-1000ms, default: false)
+     * @returns RetryPolicy instance with constant strategy
+     *
+     * @example
+     * ```typescript
+     * // Retry every 5 seconds, max 3 times
+     * const policy = RetryPolicy.constant(5000, 3);
+     * ```
+     */
+    static constant(delay: number, maxAttempts: number, jitter?: boolean): RetryPolicy;
+}
+//# sourceMappingURL=retry-policy.d.ts.map

package/dist/utils/retry-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.d.ts","sourceRoot":"","sources":["../../src/utils/retry-policy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,IAAI,EAAE,iBAAiB,CAAC;IACxB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,MAAM,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;EAO9B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IAEzC;;;;;OAKG;gBACS,QAAQ,EAAE,aAAa;IAUnC;;;;;;;;;;;;;;;;OAgBG;IACI,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAoC9C;;;;;;;;;;;;;;;OAeG;IACI,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI5C;;;;OAIG;IACI,WAAW,IAAI,QAAQ,CAAC,aAAa,CAAC;IAM7C;;;;;;;;;;;;;;;;;;;;OAoBG;WACW,WAAW,CACvB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO,EACf,iBAAiB,GAAE,MAAU,GAC5B,WAAW;IAWd;;;;;;;;;;;;;;;;OAgBG;WACW,MAAM,CAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO,GACd,WAAW;IAUd;;;;;;;;;;;;;;;OAeG;WACW,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAE,OAAe,GAAG,WAAW;CASjG"}

package/dist/utils/retry-policy.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * RetryPolicy - Configurable retry strategy for connection and webhook retries
+ * Supports exponential, linear, and constant backoff strategies
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RetryPolicy = exports.RetryStrategySchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Zod schema for retry strategy validation
+ */
+exports.RetryStrategySchema = zod_1.z.object({
+    type: zod_1.z.enum(["exponential", "linear", "constant"]),
+    baseDelay: zod_1.z.number().min(0).max(300000), // 0-5 minutes
+    maxDelay: zod_1.z.number().min(0).max(3600000), // 0-1 hour
+    maxAttempts: zod_1.z.number().min(0).max(1000),
+    jitter: zod_1.z.boolean(),
+    backoffMultiplier: zod_1.z.number().min(1).max(10).optional()
+});
+/**
+ * RetryPolicy - Calculates retry delays and determines retry eligibility
+ *
+ * Supports three retry strategies:
+ * - **Exponential**: Delay increases exponentially (e.g., 1s, 2s, 4s, 8s, ...)
+ * - **Linear**: Delay increases linearly (e.g., 1s, 2s, 3s, 4s, ...)
+ * - **Constant**: Delay remains constant (e.g., 1s, 1s, 1s, 1s, ...)
+ *
+ * All strategies respect maxDelay cap and support optional jitter.
+ *
+ * @example
+ * ```typescript
+ * // Exponential backoff with default multiplier of 2
+ * const policy = RetryPolicy.exponential(1000, 60000, 10, true);
+ * console.log(policy.calculateDelay(1)); // ~1000ms
+ * console.log(policy.calculateDelay(2)); // ~2000ms
+ * console.log(policy.calculateDelay(3)); // ~4000ms
+ *
+ * // Linear backoff
+ * const policy = RetryPolicy.linear(2000, 30000, 5, false);
+ * console.log(policy.calculateDelay(1)); // 2000ms
+ * console.log(policy.calculateDelay(2)); // 4000ms
+ * console.log(policy.calculateDelay(3)); // 6000ms
+ *
+ * // Constant delay
+ * const policy = RetryPolicy.constant(5000, 3);
+ * console.log(policy.calculateDelay(1)); // 5000ms
+ * console.log(policy.calculateDelay(2)); // 5000ms
+ * console.log(policy.calculateDelay(3)); // 5000ms
+ * ```
+ */
+class RetryPolicy {
+    /**
+     * Creates a new retry policy with the specified strategy
+     *
+     * @param strategy - Retry strategy configuration
+     * @throws {z.ZodError} If strategy is invalid
+     */
+    constructor(strategy) {
+        // Validate strategy with Zod
+        this.strategy = exports.RetryStrategySchema.parse(strategy);
+        // Additional validation: maxDelay must be >= baseDelay
+        if (this.strategy.maxDelay < this.strategy.baseDelay) {
+            throw new Error("maxDelay must be greater than or equal to baseDelay");
+        }
+    }
+    /**
+     * Calculates the retry delay for a given attempt number
+     *
+     * @param attempt - Attempt number (1-indexed: 1 = first retry)
+     * @returns Delay in milliseconds before next retry
+     *
+     * @example
+     * ```typescript
+     * const policy = RetryPolicy.exponential(1000, 60000, 10, true);
+     *
+     * // First retry after 1st failure
+     * policy.calculateDelay(1); // ~1000ms (+ jitter if enabled)
+     *
+     * // Second retry after 2nd failure
+     * policy.calculateDelay(2); // ~2000ms (+ jitter if enabled)
+     * ```
+     */
+    calculateDelay(attempt) {
+        // Validate attempt number
+        if (attempt < 1) {
+            throw new Error("Attempt number must be >= 1");
+        }
+        let delay;
+        switch (this.strategy.type) {
+            case "exponential": {
+                const multiplier = this.strategy.backoffMultiplier || 2;
+                delay = this.strategy.baseDelay * Math.pow(multiplier, attempt - 1);
+                break;
+            }
+            case "linear": {
+                delay = this.strategy.baseDelay * attempt;
+                break;
+            }
+            case "constant": {
+                delay = this.strategy.baseDelay;
+                break;
+            }
+        }
+        // Cap at maxDelay
+        delay = Math.min(delay, this.strategy.maxDelay);
+        // Add jitter if enabled
+        if (this.strategy.jitter) {
+            // Add random jitter between 0 and 1000ms
+            delay += Math.random() * 1000;
+        }
+        return Math.floor(delay);
+    }
+    /**
+     * Determines if a retry should be attempted based on attempt count
+     *
+     * @param attempt - Current attempt number (1-indexed)
+     * @returns True if retry should be attempted, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const policy = RetryPolicy.exponential(1000, 60000, 3, false);
+     *
+     * policy.shouldRetry(1); // true
+     * policy.shouldRetry(2); // true
+     * policy.shouldRetry(3); // true
+     * policy.shouldRetry(4); // false - exceeded maxAttempts
+     * ```
+     */
+    shouldRetry(attempt) {
+        return attempt <= this.strategy.maxAttempts;
+    }
+    /**
+     * Gets the retry strategy configuration
+     *
+     * @returns Copy of the retry strategy
+     */
+    getStrategy() {
+        return { ...this.strategy };
+    }
+    // Static factory methods for common patterns
+    /**
+     * Creates a retry policy with exponential backoff
+     *
+     * Delay formula: `min(baseDelay * multiplier^(attempt-1), maxDelay) + jitter`
+     *
+     * @param baseDelay - Initial delay in milliseconds
+     * @param maxDelay - Maximum delay cap in milliseconds
+     * @param maxAttempts - Maximum retry attempts
+     * @param jitter - Add random jitter (0-1000ms)
+     * @param backoffMultiplier - Exponential multiplier (default: 2)
+     * @returns RetryPolicy instance with exponential strategy
+     *
+     * @example
+     * ```typescript
+     * // Standard exponential backoff (2^n)
+     * const policy = RetryPolicy.exponential(1000, 60000, 10, true);
+     *
+     * // Faster exponential backoff (3^n)
+     * const aggressive = RetryPolicy.exponential(1000, 60000, 10, true, 3);
+     * ```
+     */
+    static exponential(baseDelay, maxDelay, maxAttempts, jitter, backoffMultiplier = 2) {
+        return new RetryPolicy({
+            type: "exponential",
+            baseDelay,
+            maxDelay,
+            maxAttempts,
+            jitter,
+            backoffMultiplier
+        });
+    }
+    /**
+     * Creates a retry policy with linear backoff
+     *
+     * Delay formula: `min(baseDelay * attempt, maxDelay) + jitter`
+     *
+     * @param baseDelay - Delay increment per attempt in milliseconds
+     * @param maxDelay - Maximum delay cap in milliseconds
+     * @param maxAttempts - Maximum retry attempts
+     * @param jitter - Add random jitter (0-1000ms)
+     * @returns RetryPolicy instance with linear strategy
+     *
+     * @example
+     * ```typescript
+     * // Linear backoff: 2s, 4s, 6s, 8s, ...
+     * const policy = RetryPolicy.linear(2000, 30000, 10, false);
+     * ```
+     */
+    static linear(baseDelay, maxDelay, maxAttempts, jitter) {
+        return new RetryPolicy({
+            type: "linear",
+            baseDelay,
+            maxDelay,
+            maxAttempts,
+            jitter
+        });
+    }
+    /**
+     * Creates a retry policy with constant delay
+     *
+     * Delay formula: `baseDelay + jitter`
+     *
+     * @param delay - Constant delay in milliseconds
+     * @param maxAttempts - Maximum retry attempts
+     * @param jitter - Add random jitter (0-1000ms, default: false)
+     * @returns RetryPolicy instance with constant strategy
+     *
+     * @example
+     * ```typescript
+     * // Retry every 5 seconds, max 3 times
+     * const policy = RetryPolicy.constant(5000, 3);
+     * ```
+     */
+    static constant(delay, maxAttempts, jitter = false) {
+        return new RetryPolicy({
+            type: "constant",
+            baseDelay: delay,
+            maxDelay: delay,
+            maxAttempts,
+            jitter
+        });
+    }
+}
+exports.RetryPolicy = RetryPolicy;
+//# sourceMappingURL=retry-policy.js.map

package/dist/utils/retry-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.js","sourceRoot":"","sources":["../../src/utils/retry-policy.ts"],"names":[],"mappings":"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"}