@gravito/echo 3.0.1 → 3.1.0

package/dist/echo/src/providers/base/BaseProvider.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Abstract base class for webhook providers.
+ * @module @gravito/echo/providers/base
+ */
+import type { WebhookProvider, WebhookVerificationResult } from '../../types';
+/**
+ * Configuration options for webhook providers.
+ */
+export interface ProviderOptions {
+    /**
+     * Maximum allowed age of the webhook request in seconds to prevent replay attacks.
+     * @defaultValue 300
+     */
+    tolerance?: number;
+}
+/**
+ * Base implementation for all webhook providers.
+ * Handles common header extraction, payload conversion, and result formatting.
+ *
+ * @example
+ * ```typescript
+ * class MyProvider extends BaseProvider {
+ *   readonly name = 'my-provider';
+ *   async verify(payload, headers, secret) {
+ *     // Implementation logic
+ *     return this.createSuccess(JSON.parse(payload));
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class BaseProvider implements WebhookProvider {
+    /** Unique identifier for the provider. */
+    abstract readonly name: string;
+    /** Time tolerance for timestamp validation. */
+    protected tolerance: number;
+    constructor(options?: ProviderOptions);
+    /**
+     * Verifies the authenticity of a webhook request.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Provider-specific secret key.
+     * @returns Verification result containing the parsed payload or error message.
+     * @throws Error if verification logic encounters an unrecoverable failure.
+     */
+    abstract verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+    /**
+     * Extracts the event type from the verified payload.
+     *
+     * @param payload - The parsed webhook payload.
+     * @returns The event type string if found.
+     */
+    parseEventType?(payload: unknown): string | undefined;
+    /**
+     * Retrieves a header value in a case-insensitive manner.
+     */
+    protected getHeader(headers: Record<string, string | string[] | undefined>, name: string): string | undefined;
+    /**
+     * Checks if a specific header exists.
+     */
+    protected hasHeader(headers: Record<string, string | string[] | undefined>, name: string): boolean;
+    /**
+     * Creates a failed verification result.
+     */
+    protected createFailure(error: string): WebhookVerificationResult;
+    /**
+     * Creates a successful verification result.
+     */
+    protected createSuccess(payload: unknown, options?: {
+        eventType?: string;
+        webhookId?: string;
+    }): WebhookVerificationResult;
+    /**
+     * Ensures the payload is a string.
+     */
+    protected payloadToString(payload: string | Buffer): string;
+    /**
+     * Safely parses a JSON string without throwing.
+     */
+    protected safeParseJson(str: string): {
+        success: true;
+        data: unknown;
+    } | {
+        success: false;
+        error: string;
+    };
+}

package/dist/echo/src/providers/base/HeaderUtils.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Utilities for handling webhook headers.
+ * @module @gravito/echo/providers/base
+ */
+/**
+ * Retrieves a header value from a headers object.
+ * Supports case-insensitive lookup by checking the original name and its lowercase version.
+ *
+ * @param headers - The headers object from the request.
+ * @param name - The name of the header to retrieve.
+ * @returns The first value of the header if found, otherwise undefined.
+ *
+ * @example
+ * ```typescript
+ * const sig = getHeader(headers, 'X-Webhook-Signature');
+ * ```
+ */
+export declare function getHeader(headers: Record<string, string | string[] | undefined>, name: string): string | undefined;
+/**
+ * Retrieves multiple header values at once.
+ *
+ * @param headers - The headers object from the request.
+ * @param names - An array of header names to retrieve.
+ * @returns A record mapping each requested name to its value or undefined.
+ */
+export declare function getHeaders(headers: Record<string, string | string[] | undefined>, names: string[]): Record<string, string | undefined>;
+/**
+ * Checks if a specific header exists in the headers object.
+ *
+ * @param headers - The headers object from the request.
+ * @param name - The name of the header to check.
+ * @returns True if the header exists and is not undefined.
+ */
+export declare function hasHeader(headers: Record<string, string | string[] | undefined>, name: string): boolean;

package/dist/echo/src/providers/index.d.ts

@@ -1,3 +1,14 @@
-export * from './GenericProvider';
-export * from './GitHubProvider';
-export * from './StripeProvider';
+/**
+ * Webhook providers for various services.
+ * @module @gravito/echo/providers
+ */
+export { BaseProvider, type ProviderOptions } from './base/BaseProvider';
+export { getHeader, getHeaders, hasHeader } from './base/HeaderUtils';
+export { GenericProvider } from './GenericProvider';
+export { GitHubProvider } from './GitHubProvider';
+export { LinearProvider } from './LinearProvider';
+export { PaddleProvider } from './PaddleProvider';
+export { ShopifyProvider } from './ShopifyProvider';
+export { SlackProvider } from './SlackProvider';
+export { StripeProvider } from './StripeProvider';
+export { TwilioProvider } from './TwilioProvider';

package/dist/echo/src/receive/SignatureValidator.d.ts

@@ -9,10 +9,43 @@
  * Compute HMAC-SHA256 signature
  */
 export declare function computeHmacSha256(payload: string | Buffer, secret: string): Promise<string>;
+/**
+ * Computes an HMAC-SHA256 signature and returns it as a base64 encoded string.
+ *
+ * Used by providers that require base64 encoding for their signatures (e.g., Shopify).
+ *
+ * @param payload - The raw data to sign.
+ * @param secret - The shared secret key.
+ * @returns The base64 encoded HMAC-SHA256 signature.
+ * @throws Error if the crypto operations fail.
+ *
+ * @example
+ * ```typescript
+ * const sig = await computeHmacSha256Base64('data', 'secret');
+ * ```
+ */
+export declare function computeHmacSha256Base64(payload: string | Buffer, secret: string): Promise<string>;
 /**
  * Compute HMAC-SHA1 signature (for legacy providers)
  */
 export declare function computeHmacSha1(payload: string | Buffer, secret: string): Promise<string>;
+/**
+ * Computes an HMAC-SHA1 signature and returns it as a base64 encoded string.
+ *
+ * Primarily used for legacy services or specific providers like Twilio that
+ * still rely on SHA1-based HMAC for their webhook verification.
+ *
+ * @param payload - The raw data to sign.
+ * @param secret - The shared secret key.
+ * @returns The base64 encoded HMAC-SHA1 signature.
+ * @throws Error if the crypto operations fail.
+ *
+ * @example
+ * ```typescript
+ * const sig = await computeHmacSha1Base64('data', 'secret');
+ * ```
+ */
+export declare function computeHmacSha1Base64(payload: string | Buffer, secret: string): Promise<string>;
 /**
  * Timing-safe string comparison to prevent timing attacks
  */

package/dist/echo/src/receive/WebhookReceiver.d.ts

@@ -5,62 +5,180 @@
  *
  * @module @gravito/echo/receive
  */
-import type { WebhookHandler, WebhookProvider, WebhookVerificationResult } from '../types';
-type ProviderClass = new (options?: any) => WebhookProvider;
+import type { GravitoContext } from '@gravito/core';
+import { type EchoLogger } from '../observability/logging';
+import { type MetricsProvider } from '../observability/metrics';
+import { type Tracer } from '../observability/tracing';
+import type { KeyRotationManager } from '../rotation/KeyRotationManager';
+import type { WebhookStore } from '../storage/WebhookStore';
+import type { ProviderKeyEntry, WebhookHandler, WebhookProvider, WebhookVerificationResult } from '../types';
+type ProviderClass = new (options?: Record<string, unknown>) => WebhookProvider;
 /**
- * Webhook Receiver
+ * WebhookReceiver orchestrates the end-to-end lifecycle of incoming webhooks.
  *
- * Manages webhook providers and routes incoming webhooks to handlers.
+ * It acts as the central intake for all incoming requests, managing provider-specific
+ * verification logic, multi-key rotation checks, persistent storage for auditing,
+ * and routing validated events to their respective application-level handlers.
  *
- * @example
+ * @example Basic usage with Stripe
  * ```typescript
- * const receiver = new WebhookReceiver()
+ * const receiver = new WebhookReceiver();
  *
- * // Register provider
- * receiver.registerProvider('stripe', process.env.STRIPE_WEBHOOK_SECRET!)
+ * // Register Stripe with its signing secret
+ * receiver.registerProvider('stripe', 'whsec_...');
  *
- * // Register handler
+ * // Listen for payment success events
  * receiver.on('stripe', 'payment_intent.succeeded', async (event) => {
- *   console.log('Payment received:', event.payload)
- * })
- *
- * // Handle incoming webhook
- * const result = await receiver.handle('stripe', body, headers)
+ *   const payment = event.payload;
+ *   await processPayment(payment.id);
+ * });
  * ```
+ *
+ * @public
  */
 export declare class WebhookReceiver {
     private providers;
     private handlers;
     private globalHandlers;
+    private store?;
+    private metrics;
+    private tracer;
+    private logger;
+    private keyRotationManager?;
+    /**
+     * Initializes the receiver and registers the suite of built-in providers.
+     * Built-in providers include Stripe, GitHub, Shopify, Twilio, Slack, and others.
+     */
     constructor();
     private providerTypes;
     /**
-     * Register a custom provider type
+     * Assigns a storage engine for persisting and auditing incoming webhook data.
+     *
+     * @param store - Implementation of the WebhookStore interface.
+     * @returns The current instance for method chaining.
+     */
+    setStore(store: WebhookStore): this;
+    /**
+     * Configures the metrics provider for performance and error monitoring.
+     *
+     * @param metrics - Implementation of the MetricsProvider interface.
+     * @returns The current instance for method chaining.
+     */
+    setMetrics(metrics: MetricsProvider): this;
+    /**
+     * Configures the tracer for end-to-end request observability.
+     *
+     * @param tracer - Implementation of the Tracer interface.
+     * @returns The current instance for method chaining.
+     */
+    setTracer(tracer: Tracer): this;
+    /**
+     * Configures the logger for diagnostic and security audit logging.
+     *
+     * @param logger - Implementation of the EchoLogger interface.
+     * @returns The current instance for method chaining.
+     */
+    setLogger(logger: EchoLogger): this;
+    /**
+     * Attaches a key rotation manager for handling dynamic secret updates.
+     *
+     * @param manager - Instance of KeyRotationManager.
+     * @returns The current instance for method chaining.
+     */
+    setKeyRotationManager(manager: KeyRotationManager): this;
+    /**
+     * Extends the receiver with a custom webhook provider implementation.
+     *
+     * Use this to add support for services not included in the built-in provider set.
+     *
+     * @param name - Unique identifier for the provider type (e.g., 'custom-crm').
+     * @param ProviderCls - Constructor for the class implementing WebhookProvider.
+     * @returns The current instance for method chaining.
      */
     registerProviderType(name: string, ProviderCls: ProviderClass): this;
     /**
-     * Register a provider with its secret
+     * Configures a named provider instance with its security credentials.
+     *
+     * @param name - Unique identifier for this provider instance (used in routing).
+     * @param secret - The shared secret used to verify incoming request signatures.
+     * @param options - Settings like the provider type and signature time tolerance.
+     * @returns The current instance for method chaining.
+     * @throws {Error} If the specified provider type has not been registered.
      */
     registerProvider(name: string, secret: string, options?: {
         type?: string;
         tolerance?: number;
     }): this;
     /**
-     * Register an event handler
+     * Registers a provider instance with support for multiple secrets and rotation.
+     *
+     * This is the preferred registration method for high-availability environments
+     * where zero-downtime key rotation is required.
+     *
+     * @param name - Unique identifier for this provider instance.
+     * @param keys - A list of valid keys (active and pending) for this provider.
+     * @param options - Settings like the provider type and signature time tolerance.
+     * @returns The current instance for method chaining.
+     * @throws {Error} If KeyRotationManager is not set or the provider type is unknown.
+     */
+    registerProviderWithRotation(name: string, keys: ProviderKeyEntry[], options?: {
+        type?: string;
+        tolerance?: number;
+    }): this;
+    /**
+     * Subscribes a handler function to a specific event type from a provider.
+     *
+     * @param providerName - The name of the registered provider instance.
+     * @param eventType - The exact semantic type of the event (e.g., 'order.placed').
+     * @param handler - The asynchronous function to execute when a matching event arrives.
+     * @returns The current instance for method chaining.
      */
     on<T = unknown>(providerName: string, eventType: string, handler: WebhookHandler<T>): this;
     /**
-     * Register a handler for all events from a provider
+     * Subscribes a catch-all handler for all valid events from a specific provider.
+     *
+     * @param providerName - The name of the registered provider instance.
+     * @param handler - Function to execute for every authenticated event from this provider.
+     * @returns The current instance for method chaining.
      */
     onAll<T = unknown>(providerName: string, handler: WebhookHandler<T>): this;
     /**
-     * Handle an incoming webhook
+     * Orchestrates the verification and asynchronous processing of an incoming webhook.
+     *
+     * This is the main entry point for requests. It performs the following:
+     * 1. Signature validation (supporting multi-key fallback if rotation is enabled).
+     * 2. Event persistence to storage for audit trails.
+     * 3. Execution of all matching event-specific and global handlers.
+     * 4. Automatic instrumentation for metrics and tracing.
+     *
+     * @param providerName - The name of the provider instance targeted by the request.
+     * @param body - The raw request body as received from the socket.
+     * @param headers - Complete set of HTTP headers for signature extraction.
+     * @param context - Optional Gravito context for accessing buffered requests.
+     * @returns Verification status, event metadata, and processing result.
+     * @throws {Error} If handler execution or event storage fails.
      */
-    handle(providerName: string, body: string | Buffer, headers: Record<string, string | string[] | undefined>): Promise<WebhookVerificationResult & {
+    handle(providerName: string, body: string | Buffer, headers: Record<string, string | string[] | undefined>, context?: GravitoContext): Promise<WebhookVerificationResult & {
         handled: boolean;
+        eventId?: string;
     }>;
     /**
-     * Verify a webhook without handling
+     * Internal utility to categorize verification errors for metrics reporting.
+     *
+     * @param error - The raw error message from the provider or rotation manager.
+     * @returns A semantic error category string (e.g., 'missing_header', 'signature_invalid').
+     */
+    private categorizeError;
+    /**
+     * Performs a standalone signature verification without triggering side-effects.
+     *
+     * This method verifies the authenticity of a webhook request without persisting it
+     * to storage or executing any registered handlers. Useful for pre-validation logic.
+     *
+     * @param providerName - The identifier of the provider instance to use for verification.
+     * @param body - The raw request body.
+     * @param headers - The incoming HTTP headers.
+     * @returns A promise resolving to the verification result.
      */
     verify(providerName: string, body: string | Buffer, headers: Record<string, string | string[] | undefined>): Promise<WebhookVerificationResult>;
 }

package/dist/echo/src/replay/WebhookReplayService.d.ts

@@ -0,0 +1,35 @@
+import type { WebhookDispatcher } from '../send/WebhookDispatcher';
+import type { WebhookStore } from '../storage/WebhookStore';
+import type { ReplayOptions, ReplayResult } from '../types';
+/**
+ * Service responsible for re-sending previously dispatched webhook events.
+ * This is useful for recovering from downstream outages or re-syncing data.
+ *
+ * @example
+ * ```typescript
+ * const replayService = new WebhookReplayService(store, dispatcher);
+ * const result = await replayService.replay({
+ *   timeRange: { from: new Date('2023-01-01'), to: new Date('2023-01-02') },
+ *   provider: 'stripe'
+ * });
+ * ```
+ */
+export declare class WebhookReplayService {
+    private store;
+    private dispatcher;
+    /**
+     * Creates an instance of WebhookReplayService.
+     *
+     * @param store - The storage backend to query historical events.
+     * @param dispatcher - The dispatcher used to re-send events.
+     */
+    constructor(store: WebhookStore, dispatcher: WebhookDispatcher);
+    /**
+     * Replays webhook events based on the provided options.
+     *
+     * @param options - Criteria for selecting events and execution mode (e.g., dry run).
+     * @returns A summary of the replay operation, including success and failure counts.
+     * @throws {Error} If the storage query fails.
+     */
+    replay(options: ReplayOptions): Promise<ReplayResult>;
+}

package/dist/echo/src/replay/index.d.ts

@@ -0,0 +1 @@
+export * from './WebhookReplayService';

package/dist/echo/src/resilience/CircuitBreaker.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Implementation of the Circuit Breaker pattern.
+ *
+ * Protects downstream services from cascading failures by monitoring error rates
+ * and temporarily "tripping" the circuit when thresholds are exceeded. This
+ * prevents unnecessary load on struggling services and allows them time to recover.
+ *
+ * @module @gravito/echo/resilience
+ * @since 1.1.0
+ */
+import type { CircuitBreakerConfig, CircuitBreakerMetrics, CircuitBreakerState } from '../types';
+/**
+ * State machine for managing downstream service availability via the Circuit Breaker pattern.
+ *
+ * This implementation tracks failures and successes to determine one of three states:
+ * - `CLOSED`: Healthy state. All requests are executed normally.
+ * - `OPEN`: Failing state. Trip thresholds exceeded; requests are rejected immediately to
+ *   prevent cascading failure and give the target system time to recover.
+ * - `HALF_OPEN`: Recovery phase. Allows a limited number of test requests to determine
+ *   if the downstream service has restored functionality.
+ *
+ * @example Protecting a fragile API call
+ * ```typescript
+ * const breaker = new CircuitBreaker('inventory-service', {
+ *   failureThreshold: 5,
+ *   openTimeout: 60000 // Stay open for 1 minute before testing recovery
+ * });
+ *
+ * try {
+ *   const stock = await breaker.execute(async () => {
+ *     return await apiClient.getInventory();
+ *   });
+ * } catch (error) {
+ *   if (error.message.includes('Circuit breaker is OPEN')) {
+ *     // Redirect to fallback or return cached data
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare class CircuitBreaker {
+    private readonly name;
+    private state;
+    private failures;
+    private successes;
+    private lastFailureAt?;
+    private lastSuccessAt?;
+    private openedAt?;
+    private halfOpenAttempts;
+    private config;
+    /**
+     * Constructs a new CircuitBreaker for a specific resource, host, or service.
+     *
+     * @param name - A semantic identifier for the target being protected.
+     * @param config - Policy settings for failure thresholds, recovery timeouts, and callbacks.
+     */
+    constructor(name: string, config?: CircuitBreakerConfig);
+    /**
+     * Executes an asynchronous operation within the safety window of the circuit breaker.
+     *
+     * This method will proactively check the circuit state. If the state is `OPEN`, it will
+     * throw an error immediately without invoking the provided function.
+     *
+     * @param fn - The asynchronous operation to be protected.
+     * @returns A promise resolving to the result of the protected operation.
+     * @throws {Error} If the circuit is currently `OPEN` or if the underlying operation fails.
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Records a successful operation and updates the state machine.
+     * In `HALF_OPEN` state, this contributes to the success threshold for closing the circuit.
+     */
+    private onSuccess;
+    /**
+     * Records a failed operation and determines if the circuit should trip to `OPEN`.
+     * Any failure in `HALF_OPEN` state immediately trips the circuit back to `OPEN`.
+     */
+    private onFailure;
+    /**
+     * Evaluates and performs automatic state transitions based on elapsed time and thresholds.
+     */
+    private checkStateTransition;
+    /**
+     * Transitions the circuit to a new state and executes configured lifecycle callbacks.
+     *
+     * @param newState - The target state to transition into.
+     */
+    private transitionTo;
+    /**
+     * Resets all internal counters and timers to their initial baseline state.
+     */
+    private reset;
+    /**
+     * Retrieves a snapshot of the current health and performance metrics of the circuit.
+     *
+     * @returns An object containing state, failure counts, and activity timestamps.
+     */
+    getMetrics(): CircuitBreakerMetrics;
+    /**
+     * Forcefully resets the circuit breaker to the `CLOSED` state.
+     * Useful for manual recovery scenarios after a service has been verified healthy.
+     */
+    manualReset(): void;
+    /**
+     * Returns the current operational state of the circuit breaker.
+     *
+     * @returns The current state identifier.
+     */
+    getState(): CircuitBreakerState;
+    /**
+     * Returns the semantic name assigned to this circuit breaker instance.
+     *
+     * @returns The name identifier.
+     */
+    getName(): string;
+}

package/dist/echo/src/resilience/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Echo Resilience
+ *
+ * 提供彈性與容錯機制
+ *
+ * @module @gravito/echo/resilience
+ * @since v1.1
+ */
+export type { CircuitBreakerConfig, CircuitBreakerMetrics, CircuitBreakerState } from '../types';
+export { CircuitBreaker } from './CircuitBreaker';

package/dist/echo/src/rotation/KeyRotationManager.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview Key Rotation Manager
+ *
+ * Manages the lifecycle of webhook provider secrets, including multi-version
+ * support, automatic cleanup, and grace periods for smooth transitions.
+ *
+ * @module @gravito/echo/rotation
+ * @since v1.2
+ */
+import type { KeyRotationConfig, ProviderKeyEntry } from '../types';
+/**
+ * KeyRotationManager orchestrates the lifecycle of webhook provider secrets.
+ *
+ * It provides a central hub for managing multiple concurrent versions of signing
+ * secrets, enabling zero-downtime rotation. By maintaining a set of "active"
+ * keys (including those in a grace period), it ensures that webhooks signed
+ * with either an old or new secret are successfully verified during transition.
+ *
+ * Key features:
+ * - Multi-version secret management.
+ * - Automatic background cleanup of expired keys.
+ * - Grace period support for smooth cut-overs.
+ * - Promotion of new primary keys.
+ *
+ * @example Managing zero-downtime rotation
+ * ```typescript
+ * const manager = new KeyRotationManager({
+ *   gracePeriod: 86400000, // 24 hours
+ *   autoCleanup: true,
+ * });
+ *
+ * // Register initial keys
+ * manager.registerKeys('stripe', [
+ *   {
+ *     key: 'whsec_primary',
+ *     version: 'v2',
+ *     isPrimary: true,
+ *     activeFrom: new Date(),
+ *   }
+ * ]);
+ *
+ * // Rotate to a new secret
+ * await manager.rotatePrimaryKey('stripe', {
+ *   key: 'whsec_new_secret',
+ *   version: 'v3',
+ *   activeFrom: new Date(),
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare class KeyRotationManager {
+    private providerKeys;
+    private cleanupTimer?;
+    private config;
+    /**
+     * Constructs a new KeyRotationManager with the specified policy.
+     *
+     * @param config - Configuration for auto-cleanup, grace periods, and rotation hooks.
+     */
+    constructor(config?: KeyRotationConfig);
+    /**
+     * Registers a collection of keys for a specific provider.
+     *
+     * Validation ensures that exactly one primary key is specified for the provider.
+     *
+     * @param providerName - Canonical name of the provider instance.
+     * @param keys - Array of valid key entries with metadata.
+     * @throws {Error} If no primary key is provided or if multiple primary keys are detected.
+     */
+    registerKeys(providerName: string, keys: ProviderKeyEntry[]): void;
+    /**
+     * Retrieves all currently valid keys for a provider to attempt verification.
+     *
+     * A key is considered active if the current time is after its `activeFrom` date
+     * and before its `expiresAt` date (if defined).
+     *
+     * @param providerName - Canonical name of the provider instance.
+     * @returns An array of currently active key entries.
+     */
+    getActiveKeys(providerName: string): ProviderKeyEntry[];
+    /**
+     * Retrieves the current primary key used for signature generation.
+     *
+     * @param providerName - Canonical name of the provider instance.
+     * @returns The primary key entry, or null if no active primary key exists.
+     */
+    getPrimaryKey(providerName: string): ProviderKeyEntry | null;
+    /**
+     * Promotes a new primary key for the provider and retires the old one.
+     *
+     * The previous primary key is automatically assigned an expiration date based on
+     * the configured `gracePeriod`, allowing it to remain valid for incoming requests
+     * that were signed before the rotation propagated.
+     *
+     * @param providerName - Canonical name of the provider instance.
+     * @param newKey - Metadata and secret for the new primary key.
+     */
+    rotatePrimaryKey(providerName: string, newKey: Omit<ProviderKeyEntry, 'isPrimary'>): Promise<void>;
+    /**
+     * Manually triggers a purge of all expired keys across all providers.
+     *
+     * @returns The total number of keys removed during this cycle.
+     */
+    cleanupExpiredKeys(): number;
+    /**
+     * Initializes the background timer for periodic key purging.
+     */
+    private startAutoCleanup;
+    /**
+     * Stops the auto-cleanup background process.
+     */
+    destroy(): void;
+    /**
+     * Provides a read-only snapshot of all keys across all providers.
+     *
+     * @returns A map of provider names to their complete key history.
+     */
+    getAllProviderKeys(): Map<string, ProviderKeyEntry[]>;
+    /**
+     * Checks if a specific provider has any keys registered in the manager.
+     *
+     * @param providerName - Canonical name of the provider instance.
+     * @returns True if the provider is tracked.
+     */
+    hasProvider(providerName: string): boolean;
+}