@gravito/echo 3.1.1 → 3.1.2

package/dist/providers/index.d.ts

@@ -1,4 +1,14 @@
-export * from './GenericProvider';
-export * from './GitHubProvider';
-export * from './StripeProvider';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * 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/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
  */
@@ -32,4 +65,3 @@ export declare function parseStripeSignature(header: string): {
     timestamp: number;
     signatures: string[];
 } | null;
-//# sourceMappingURL=SignatureValidator.d.ts.map

package/dist/receive/WebhookReceiver.d.ts

@@ -5,64 +5,181 @@
  *
  * @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>;
 }
 export {};
-//# sourceMappingURL=WebhookReceiver.d.ts.map

package/dist/receive/index.d.ts

@@ -1,3 +1,2 @@
 export * from './SignatureValidator';
 export * from './WebhookReceiver';
-//# sourceMappingURL=index.d.ts.map

package/dist/send/WebhookDispatcher.d.ts

@@ -5,51 +5,194 @@
  *
  * @module @gravito/echo/send
  */
-import type { WebhookDeliveryResult, WebhookDispatcherConfig, WebhookPayload } from '../types';
+import type { DeadLetterQueue } from '../dlq/DeadLetterQueue';
+import type { EchoLogger } from '../observability/logging';
+import { type MetricsProvider } from '../observability/metrics';
+import { type Tracer } from '../observability/tracing';
+import type { BatchDispatchOptions, BatchDispatchResult, CircuitBreakerMetrics, WebhookDeliveryResult, WebhookDispatcherConfig, WebhookPayload } from '../types';
 /**
- * Webhook Dispatcher
+ * WebhookDispatcher manages the secure and reliable delivery of events to external targets.
  *
- * Sends webhooks with signature and retry support.
+ * It provides a robust engine for sending signed webhook payloads to third-party
+ * consumers, incorporating enterprise-grade reliability features such as:
+ * - Exponential backoff retries for transient network/server errors.
+ * - Per-host Circuit Breaking to prevent cascading failures.
+ * - Dead Letter Queue (DLQ) integration for capturing permanently failed events.
+ * - HMAC-SHA256 payload signing for authenticity.
  *
- * @example
+ * @example Dispatching a signed event
  * ```typescript
  * const dispatcher = new WebhookDispatcher({
- *   secret: 'my-webhook-secret',
+ *   secret: 'app-outbound-secret',
  *   retry: { maxAttempts: 5 }
- * })
+ * });
  *
  * const result = await dispatcher.dispatch({
- *   url: 'https://example.com/webhook',
- *   event: 'order.created',
- *   data: { orderId: 123 }
- * })
+ *   url: 'https://consumer.com/webhooks',
+ *   event: 'order.shipped',
+ *   data: { orderId: 'ORD-123' }
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Webhook delivered successfully');
+ * }
  * ```
+ *
+ * @public
  */
 export declare class WebhookDispatcher {
     private secret;
     private retryConfig;
     private timeout;
     private userAgent;
+    private dlq?;
+    private metrics;
+    private tracer;
+    private logger?;
+    private circuitBreakers;
+    private circuitBreakerConfig?;
+    /**
+     * Initializes the dispatcher with security and reliability policies.
+     *
+     * @param config - The configuration for payload signing, retry logic, and timeouts.
+     */
     constructor(config: WebhookDispatcherConfig);
     /**
-     * Dispatch a webhook with retries
+     * Attaches a Dead Letter Queue for capturing events that fail all delivery attempts.
+     *
+     * @param dlq - Implementation of the DeadLetterQueue interface.
+     * @returns The current instance for method chaining.
+     */
+    setDeadLetterQueue(dlq: DeadLetterQueue): this;
+    /**
+     * Configures the metrics provider for delivery and failure tracking.
+     *
+     * @param metrics - Implementation of the MetricsProvider interface.
+     * @returns The current instance for method chaining.
+     */
+    setMetrics(metrics: MetricsProvider): this;
+    /**
+     * Configures the distributed tracer for end-to-end request visibility.
+     *
+     * @param tracer - Implementation of the Tracer interface.
+     * @returns The current instance for method chaining.
+     */
+    setTracer(tracer: Tracer): this;
+    /**
+     * Configures the logger for diagnostic and delivery audit logging.
+     *
+     * @param logger - Implementation of the EchoLogger interface.
+     * @returns The current instance for method chaining.
+     */
+    setLogger(logger: EchoLogger): this;
+    /**
+     * Resolves or creates a dedicated circuit breaker instance for a specific host.
+     *
+     * Using per-host isolation ensures that an outage at one consumer does not
+     * block or slow down deliveries to other healthy consumers.
+     *
+     * @param url - Destination URL used to derive the target host.
+     * @returns The active circuit breaker instance, or undefined if disabled.
+     */
+    private getCircuitBreaker;
+    /**
+     * Retrieves the current health metrics for a specific target's circuit breaker.
+     *
+     * @param url - The target URL whose host metrics are requested.
+     * @returns Current metrics or null if circuit breaking is not active for the host.
+     */
+    getCircuitBreakerMetrics(url: string): CircuitBreakerMetrics | null;
+    /**
+     * Manually resets a tripped circuit breaker to its CLOSED state for a specific target.
+     *
+     * @param url - The target URL whose host circuit should be reset.
+     */
+    resetCircuitBreaker(url: string): void;
+    /**
+     * Executes the end-to-end delivery of a signed webhook event.
+     *
+     * This method performs the following:
+     * 1. Wraps the payload with an authenticity signature (HMAC-SHA256).
+     * 2. Checks the state of the target's circuit breaker.
+     * 3. Executes the HTTP POST request.
+     * 4. Manages the retry lifecycle if errors occur.
+     * 5. Enqueues failed events to the DLQ if configured.
+     *
+     * @param payload - Data and destination parameters for the dispatch.
+     * @returns Final delivery outcome including success status and attempt count.
+     * @throws {Error} If critical internal operations (like signing) fail.
      */
     dispatch<T = unknown>(payload: WebhookPayload<T>): Promise<WebhookDeliveryResult>;
     /**
-     * Attempt a single delivery
+     * Internal orchestration for the delivery retry loop.
+     *
+     * @param payload - The webhook payload.
+     * @returns Final delivery result after all retry attempts.
+     */
+    private dispatchInternal;
+    /**
+     * Dispatches a batch of webhooks concurrently using an optimized worker pool.
+     *
+     * This method balances high throughput with source/target resource constraints
+     * by allowing you to tune concurrency and error propagation policies.
+     *
+     * @param payloads - Collection of payloads to deliver.
+     * @param options - Tuning parameters for concurrency and failure handling.
+     * @returns A summary result of all dispatch attempts in the batch.
+     *
+     * @example Batch dispatch with concurrency control
+     * ```typescript
+     * const results = await dispatcher.dispatchBatch(payloads, {
+     *   concurrency: 10,
+     *   stopOnFirstFailure: false
+     * });
+     * console.log(`Batch complete. Succeeded: ${results.succeeded}, Failed: ${results.failed}`);
+     * ```
+     */
+    dispatchBatch<T = unknown>(payloads: WebhookPayload<T>[], options?: BatchDispatchOptions): Promise<BatchDispatchResult>;
+    /**
+     * Re-attempts the delivery of a previously failed event from the Dead Letter Queue.
+     *
+     * If the delivery succeeds, the event is automatically removed from the DLQ.
+     *
+     * @param id - The unique identifier of the event in the DLQ.
+     * @returns Result of the retry attempt, or null if the event ID is invalid.
+     */
+    retryFromDlq(id: string): Promise<WebhookDeliveryResult | null>;
+    /**
+     * Executes a single delivery attempt including signing and circuit breaker check.
+     *
+     * @param payload - The webhook payload.
+     * @param attempt - The current attempt number.
+     * @returns Detailed result of the single attempt.
      */
     private attemptDelivery;
     /**
-     * Check if we should retry based on result
+     * Internal logic to decide if an attempt should be retried.
+     *
+     * @param result - The delivery result to evaluate.
+     * @returns True if retry is eligible.
      */
     private shouldRetry;
     /**
-     * Calculate delay for exponential backoff
+     * Calculates the exponential backoff delay for the next attempt.
+     *
+     * @param attempt - The current attempt number.
+     * @returns Delay in milliseconds.
      */
     private calculateDelay;
     /**
-     * Sleep helper
+     * Standardized categorization of delivery errors for metrics.
+     *
+     * @param result - The delivery result to categorize.
+     * @returns Category string.
+     */
+    private categorizeError;
+    /**
+     * Utility for asynchronous sleep.
+     *
+     * @param ms - Duration to sleep in ms.
+     * @returns Promise that resolves after delay.
      */
     private sleep;
 }
-//# sourceMappingURL=WebhookDispatcher.d.ts.map

package/dist/send/index.d.ts

@@ -1,2 +1 @@
 export * from './WebhookDispatcher';
-//# sourceMappingURL=index.d.ts.map