@gravito/echo 3.1.1 → 3.1.2

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

@@ -1,38 +0,0 @@
-/**
- * Stripe webhook provider.
- * @module @gravito/echo/providers
- */
-import type { WebhookVerificationResult } from '../types';
-import { BaseProvider } from './base/BaseProvider';
-/**
- * Stripe webhook provider.
- *
- * Verifies Stripe webhook signatures using their standard format.
- * @see {@link https://stripe.com/docs/webhooks/signatures | Stripe Webhook Signatures}
- *
- * @example
- * ```typescript
- * const provider = new StripeProvider();
- * const result = await provider.verify(body, headers, process.env.STRIPE_WEBHOOK_SECRET);
- * ```
- */
-export declare class StripeProvider extends BaseProvider {
-    readonly name = "stripe";
-    constructor(options?: {
-        tolerance?: number;
-    });
-    /**
-     * Verifies the Stripe webhook signature.
-     *
-     * @param payload - Raw request body.
-     * @param headers - Request headers.
-     * @param secret - Stripe webhook secret (signing secret).
-     * @returns Verification result.
-     * @throws Error if signature computation fails.
-     */
-    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
-    /**
-     * Extracts the event type from the Stripe payload.
-     */
-    parseEventType(payload: unknown): string | undefined;
-}

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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,67 +0,0 @@
-/**
- * @fileoverview Signature validation utilities
- *
- * Provides HMAC-based signature verification for webhook payloads.
- *
- * @module @gravito/echo/receive
- */
-/**
- * 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
- */
-export declare function timingSafeEqual(a: string, b: string): boolean;
-/**
- * Validate timestamp is within tolerance
- *
- * @param timestamp - Unix timestamp in seconds
- * @param tolerance - Tolerance in seconds (default: 300 = 5 minutes)
- */
-export declare function validateTimestamp(timestamp: number, tolerance?: number): boolean;
-/**
- * Parse Stripe-style signature header
- * Format: t=timestamp,v1=signature,v1=signature2
- */
-export declare function parseStripeSignature(header: string): {
-    timestamp: number;
-    signatures: string[];
-} | null;

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

@@ -1,185 +0,0 @@
-/**
- * @fileoverview Webhook Receiver
- *
- * Handles incoming webhooks with signature verification.
- *
- * @module @gravito/echo/receive
- */
-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;
-/**
- * WebhookReceiver orchestrates the end-to-end lifecycle of incoming webhooks.
- *
- * 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 Basic usage with Stripe
- * ```typescript
- * const receiver = new WebhookReceiver();
- *
- * // Register Stripe with its signing secret
- * receiver.registerProvider('stripe', 'whsec_...');
- *
- * // Listen for payment success events
- * receiver.on('stripe', 'payment_intent.succeeded', async (event) => {
- *   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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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>, context?: GravitoContext): Promise<WebhookVerificationResult & {
-        handled: boolean;
-        eventId?: string;
-    }>;
-    /**
-     * 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 {};

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

@@ -1,2 +0,0 @@
-export * from './SignatureValidator';
-export * from './WebhookReceiver';

package/dist/echo/src/send/WebhookDispatcher.d.ts

@@ -1,198 +0,0 @@
-/**
- * @fileoverview Webhook Dispatcher
- *
- * Reliably sends webhooks to external services with retry support.
- *
- * @module @gravito/echo/send
- */
-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';
-/**
- * WebhookDispatcher manages the secure and reliable delivery of events to external targets.
- *
- * 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 Dispatching a signed event
- * ```typescript
- * const dispatcher = new WebhookDispatcher({
- *   secret: 'app-outbound-secret',
- *   retry: { maxAttempts: 5 }
- * });
- *
- * const result = await dispatcher.dispatch({
- *   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);
-    /**
-     * 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>;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * Calculates the exponential backoff delay for the next attempt.
-     *
-     * @param attempt - The current attempt number.
-     * @returns Delay in milliseconds.
-     */
-    private calculateDelay;
-    /**
-     * 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;
-}

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

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