@gravito/echo 3.1.1 → 4.0.0

package/README.md

@@ -2,15 +2,30 @@
 
 > 📡 Enterprise-grade webhook handling for Gravito. Secure receiving and reliable sending.
 
-## Features
-
-- **Secure Receiving** - HMAC signature verification, timestamp validation
-- **Built-in Providers** - Stripe, GitHub, and generic provider support
-- **Reliable Sending** - Exponential backoff retry with configurable strategy
-- **Gravito Integration** - First-class OrbitEcho module for PlanetCore
-- **Request Buffering (v1.1)** - Prevents signature verification failures from framework auto-parsing
-- **Circuit Breaker (v1.1)** - Protects downstream services with automatic failure detection
-- **Key Rotation (v1.2)** - Zero-downtime key updates with multi-version support
+## ✨ Features
+
+- 🪐 **Galaxy-Ready Gateway**: The primary entry/exit point for external asynchronous communication.
+- 🛡️ **Secure Receiving**: HMAC signature verification, timestamp validation, and multi-key support.
+- 🔄 **Boundary Reliability**: Built-in **Circuit Breaker**, **Retry Scheduler**, and **DLQ** for outgoing hooks.
+- 📦 **Built-in Providers**: Native support for Stripe, GitHub, Shopify, Slack, and more.
+- ⚡ **Request Buffering**: Prevents signature failures by handling raw bodies before framework parsing.
+- 🔐 **Key Rotation**: Seamless, zero-downtime secret rotation for enterprise security.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Echo acts as the **Deep Space Radar Layer (Boundary Communication)**.
+
+- **External Stimuli**: Converts external world signals (Webhooks from Stripe, etc.) into internal `Signal` events that Satellites can react to.
+- **Outbound Pulse**: Provides a reliable way for internal Galaxy state changes to be broadcasted to the outside world (e.g., notifying a 3rd party logistics provider).
+- **Isolation Barrier**: Protects the core Galaxy from external failure ripples by utilizing circuit breakers on outgoing requests.
+
+```mermaid
+graph LR
+    World([External Service]) -- Webhook --> Echo{Echo Orbit}
+    Echo -->|Verified Signal| Sat[Satellite: Payment]
+    Sat -->|Internal Event| Stream[Stream Orbit]
+    Echo -.->|Circuit Breaker| World
+```
 
 ## Installation
 

package/dist/OrbitEcho.d.ts

@@ -1,99 +1,115 @@
-/**
- * @fileoverview OrbitEcho Module
- *
- * Gravito integration for webhook handling.
- *
- * @module @gravito/echo
- */
+import type { GravitoOrbit, PlanetCore } from '@gravito/core';
 import { WebhookReceiver } from './receive/WebhookReceiver';
+import { KeyRotationManager } from './rotation/KeyRotationManager';
 import { WebhookDispatcher } from './send/WebhookDispatcher';
-import type { EchoConfig } from './types';
+import type { EchoConfig, ProviderKeyEntry } from './types';
 /**
- * Simple module interface for PlanetCore integration
- */
-interface ModuleConfig {
-    singleton?: boolean;
-}
-/**
- * Minimal PlanetCore interface
- */
-interface PlanetCore {
-    container: {
-        instance<T>(key: string, value: T): void;
-    };
-    hooks: {
-        addAction(hook: string, callback: () => void | Promise<void>): void;
-    };
-    adapter: {
-        use(middleware: unknown): void;
-    };
-    router: {
-        post(path: string, handler: unknown): void;
-    };
-}
-/**
- * OrbitEcho - Gravito Webhook Module
+ * OrbitEcho is the official webhook orchestration module for the Gravito ecosystem.
  *
- * Provides secure webhook receiving and reliable webhook sending.
+ * It serves as a comprehensive hub for managing the entire webhook lifecycle,
+ * including secure reception, signature verification across multiple providers,
+ * persistent storage for auditing, and reliable outgoing dispatch with
+ * exponential backoff and circuit breaking.
  *
- * @example
+ * @example Basic integration with PlanetCore
  * ```typescript
- * const core = new PlanetCore()
+ * import { PlanetCore } from '@gravito/core';
+ * import { OrbitEcho } from '@gravito/echo';
  *
- * core.install(new OrbitEcho({
+ * const core = new PlanetCore();
+ * const echo = new OrbitEcho({
  *   providers: {
- *     stripe: { name: 'stripe', secret: process.env.STRIPE_WEBHOOK_SECRET! },
- *     github: { name: 'github', secret: process.env.GITHUB_WEBHOOK_SECRET! }
+ *     stripe: { name: 'stripe', secret: process.env.STRIPE_SECRET }
  *   },
  *   dispatcher: {
- *     secret: process.env.OUTGOING_WEBHOOK_SECRET!
+ *     secret: process.env.APP_WEBHOOK_SECRET
  *   }
- * }))
+ * });
  *
- * // Get receiver to add handlers
- * const receiver = core.container.make<WebhookReceiver>('echo.receiver')
- * receiver.on('stripe', 'payment_intent.succeeded', async (event) => {
- *   console.log('Payment received:', event.payload)
- * })
+ * core.install(echo);
  * ```
+ *
+ * @public
  */
-export declare class OrbitEcho {
-    static config: ModuleConfig;
+export declare class OrbitEcho implements GravitoOrbit {
     private receiver;
     private dispatcher?;
     private echoConfig;
+    private keyRotationManager?;
     /**
-     * Create a new OrbitEcho instance.
+     * Constructs a new OrbitEcho instance with the specified configuration.
      *
-     * @param config - The configuration object for providers and dispatcher.
+     * This constructor initializes the core receiver component, sets up key rotation
+     * orchestration if enabled, registers defined providers, and connects the
+     * observability stack (metrics, tracing, logging).
+     *
+     * @param config - The global configuration defining providers, dispatchers, and infrastructure.
      */
     constructor(config?: EchoConfig);
     /**
-     * Install into PlanetCore
+     * Integrates the Echo module into the Gravito application lifecycle.
      *
-     * Registers the OrbitEcho instance and its components into the service container.
+     * This method performs the following setup tasks:
+     * 1. Installs request buffering middleware (if enabled) to preserve raw bodies.
+     * 2. Binds Echo components to the service container (`echo`, `echo.receiver`).
+     * 3. Injects the Echo instance into the request context for easy access in handlers.
      *
-     * @param core - The PlanetCore instance.
+     * @param core - The PlanetCore instance managing the application.
+     * @throws {Error} If the core adapter is missing or improperly configured.
      */
     install(core: PlanetCore): void;
     /**
-     * Get webhook receiver
+     * Retrieves the underlying receiver instance for manual webhook processing.
+     *
+     * Use this when you need fine-grained control over how incoming webhooks
+     * are routed or verified outside of the standard middleware flow.
      *
-     * @returns The WebhookReceiver instance.
+     * @returns The active WebhookReceiver instance.
      */
     getReceiver(): WebhookReceiver;
     /**
-     * Get webhook dispatcher
+     * Retrieves the dispatcher instance for sending outgoing webhooks.
      *
-     * @returns The WebhookDispatcher instance, or undefined if not configured.
+     * @returns The configured WebhookDispatcher, or undefined if dispatch is disabled.
      */
     getDispatcher(): WebhookDispatcher | undefined;
     /**
-     * Get configuration
+     * Accesses the active configuration used by this OrbitEcho instance.
      *
-     * @returns The EchoConfig object.
+     * @returns The immutable EchoConfig object.
      */
     getConfig(): EchoConfig;
+    /**
+     * Retrieves the key rotation manager responsible for secret lifecycle.
+     *
+     * @returns The manager instance, or undefined if key rotation is disabled.
+     */
+    getKeyRotationManager(): KeyRotationManager | undefined;
+    /**
+     * Initiates a zero-downtime primary key rotation for a specific provider.
+     *
+     * This method promotes a new key to primary status while maintaining valid old keys
+     * for a grace period, ensuring that webhooks signed with either key are accepted
+     * during the transition.
+     *
+     * @param providerName - The identifier of the provider to update.
+     * @param newKey - Metadata and value for the replacement key.
+     * @throws {Error} If key rotation is not enabled in the global configuration.
+     *
+     * @example
+     * ```typescript
+     * await echo.rotateProviderKey('stripe', {
+     *   key: 'whsec_new_secret',
+     *   version: 'v2',
+     *   activeFrom: new Date()
+     * });
+     * ```
+     */
+    rotateProviderKey(providerName: string, newKey: Omit<ProviderKeyEntry, 'isPrimary'>): Promise<void>;
+}
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Webhook receiver and dispatcher */
+        echo?: OrbitEcho;
+    }
 }
-export {};
-//# sourceMappingURL=OrbitEcho.d.ts.map

package/dist/errors/EchoError.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Echo error types
+ *
+ * @module @gravito/echo/errors
+ */
+import { InfrastructureException, type InfrastructureExceptionOptions } from '@gravito/core';
+import type { EchoErrorCode } from './codes';
+/**
+ * Base error class for Echo module.
+ *
+ * Provides structured error handling with error codes and messages.
+ * Extends InfrastructureException for unified error handling across Gravito.
+ *
+ * @example
+ * ```typescript
+ * throw new EchoError('echo.unknown_provider', 'Unknown provider type: stripe')
+ * ```
+ * @public
+ */
+export declare class EchoError extends InfrastructureException {
+    /**
+     * Creates a new EchoError instance.
+     *
+     * @param code - The error code.
+     * @param message - The error message.
+     * @param options - Optional infrastructure exception options.
+     */
+    constructor(code: EchoErrorCode, message: string, options?: InfrastructureExceptionOptions);
+}

package/dist/errors/codes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Echo error codes
+ *
+ * Namespaced error codes for the Echo webhook module.
+ *
+ * @module @gravito/echo/errors
+ */
+/**
+ * Error codes for Echo module operations.
+ * Follows dot-separated namespace convention.
+ */
+export declare const EchoErrorCodes: {
+    readonly UNKNOWN_PROVIDER: "echo.unknown_provider";
+    readonly KEY_ROTATION_NOT_SET: "echo.key_rotation_not_set";
+    readonly NO_PRIMARY_KEY: "echo.no_primary_key";
+    readonly KEY_ROTATION_NOT_ENABLED: "echo.key_rotation_not_enabled";
+    readonly NO_DELIVERY_ATTEMPTS: "echo.no_delivery_attempts";
+    readonly INVALID_CONFIG: "echo.invalid_config";
+};
+export type EchoErrorCode = (typeof EchoErrorCodes)[keyof typeof EchoErrorCodes];

package/dist/index.d.ts

@@ -1,49 +1,67 @@
 /**
- * @fileoverview @gravito/echo - Enterprise Webhook Module
+ * @fileoverview \@gravito/echo - Enterprise Webhook Orchestration
  *
- * Secure webhook receiving and reliable webhook sending for Gravito.
+ * Echo provides a secure, reliable, and observable layer for handling webhooks
+ * in Gravito applications. It standardizes incoming webhook reception with
+ * signature verification and dynamic key rotation, while ensuring reliable
+ * outgoing delivery via exponential backoff and circuit breaking.
  *
- * @example Receiving webhooks
+ * @example Receiving webhooks from Stripe
  * ```typescript
  * import { OrbitEcho, WebhookReceiver } from '@gravito/echo'
  *
  * const core = new PlanetCore()
- *
  * core.install(new OrbitEcho({
  *   providers: {
- *     stripe: { name: 'stripe', secret: process.env.STRIPE_WEBHOOK_SECRET! }
+ *     stripe: { name: 'stripe', secret: process.env.STRIPE_SECRET! }
  *   }
  * }))
  *
  * const receiver = core.container.make<WebhookReceiver>('echo.receiver')
  * receiver.on('stripe', 'payment_intent.succeeded', async (event) => {
- *   console.log('Payment:', event.payload)
+ *   // Securely process validated payment
  * })
  * ```
  *
- * @example Sending webhooks
+ * @example Dispatching reliable outgoing webhooks
  * ```typescript
  * import { WebhookDispatcher } from '@gravito/echo'
  *
- * const dispatcher = new WebhookDispatcher({
- *   secret: 'my-secret'
- * })
- *
+ * const dispatcher = new WebhookDispatcher({ secret: 'app-secret' })
  * await dispatcher.dispatch({
- *   url: 'https://example.com/webhook',
+ *   url: 'https://consumer.com/hook',
  *   event: 'order.created',
- *   data: { orderId: 123 }
+ *   data: { id: 123 }
  * })
  * ```
  *
  * @module @gravito/echo
  */
+export type { DeadLetterEvent, DeadLetterQueue } from './dlq/DeadLetterQueue';
+export { EchoError } from './errors/EchoError';
+export { EchoErrorCodes } from './errors/codes';
+export type { EchoErrorCode } from './errors/codes';
+export { MemoryDeadLetterQueue } from './dlq/MemoryDeadLetterQueue';
+export { createRequestBufferMiddleware, RequestBufferMiddleware } from './middleware';
 export { OrbitEcho } from './OrbitEcho';
+export type { EchoLogEvent, EchoLogger } from './observability/logging';
+export { ConsoleEchoLogger } from './observability/logging';
+export type { MetricsProvider, WebhookMetricLabels } from './observability/metrics';
+export { EchoMetrics, NoopMetricsProvider, PrometheusMetricsProvider, } from './observability/metrics';
+export type { Span, SpanOptions, Tracer } from './observability/tracing';
+export { NoopSpan, NoopTracer, SpanStatusCode } from './observability/tracing';
+export { BaseProvider, type ProviderOptions } from './providers/base/BaseProvider';
 export { GenericProvider } from './providers/GenericProvider';
 export { GitHubProvider } from './providers/GitHubProvider';
+export { LinearProvider } from './providers/LinearProvider';
+export { PaddleProvider } from './providers/PaddleProvider';
+export { ShopifyProvider } from './providers/ShopifyProvider';
+export { SlackProvider } from './providers/SlackProvider';
 export { StripeProvider } from './providers/StripeProvider';
+export { TwilioProvider } from './providers/TwilioProvider';
 export { computeHmacSha1, computeHmacSha256, parseStripeSignature, timingSafeEqual, validateTimestamp, } from './receive/SignatureValidator';
 export { WebhookReceiver } from './receive/WebhookReceiver';
-export { WebhookDispatcher } from './send/WebhookDispatcher';
-export type { EchoConfig, RetryConfig, WebhookDeliveryResult, WebhookDispatcherConfig, WebhookEvent, WebhookHandler, WebhookPayload, WebhookProvider, WebhookProviderConfig, WebhookVerificationResult, } from './types';
-//# sourceMappingURL=index.d.ts.map
+export { WebhookReplayService } from './replay/WebhookReplayService';
+export { CircuitBreaker } from './resilience';
+export { KeyRotationManager } from './rotation';
+export type { BufferedRequest, CircuitBreakerConfig, CircuitBreakerMetrics, CircuitBreakerState, EchoConfig, EchoObservabilityConfig, KeyRotationConfig, ProviderKeyEntry, ReplayOptions, ReplayResult, RequestBufferConfig, RetryConfig, WebhookDeliveryResult, WebhookDispatcherConfig, WebhookEvent, WebhookHandler, WebhookPayload, WebhookProvider, WebhookProviderConfig, WebhookProviderConfigWithRotation, WebhookVerificationResult, } from './types';