@gravito/echo 2.0.0 → 3.0.1

package/dist/core/src/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './HttpTester';
+export * from './TestResponse';

package/dist/core/src/types/events.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Event system type definitions.
+ */
+/**
+ * Listener interface.
+ *
+ * All event listeners must implement this interface.
+ */
+export interface Listener<TEvent extends Event = Event> {
+    /**
+     * Handle an event.
+     * @param event - Event instance
+     */
+    handle(event: TEvent): Promise<void> | void;
+}
+/**
+ * Marker interface for listeners that should be queued.
+ *
+ * Listeners implementing this interface can be dispatched asynchronously via a queue.
+ */
+export interface ShouldQueue {
+    /**
+     * Queue name (optional).
+     */
+    queue?: string;
+    /**
+     * Connection name (optional).
+     */
+    connection?: string;
+    /**
+     * Delay before execution (seconds).
+     */
+    delay?: number;
+}
+/**
+ * Marker interface for events that should be broadcast.
+ *
+ * Events implementing this interface can be automatically broadcast to clients.
+ */
+export interface ShouldBroadcast {
+    /**
+     * Define the broadcast channel.
+     * @returns Channel name or channel object
+     */
+    broadcastOn(): string | Channel;
+    /**
+     * Define broadcast payload (optional).
+     * If omitted, public event properties will be used.
+     * @returns Broadcast payload
+     */
+    broadcastWith?(): Record<string, unknown>;
+    /**
+     * Define the broadcast event name (optional).
+     * If omitted, the event class name will be used.
+     * @returns Event name
+     */
+    broadcastAs?(): string;
+}
+/**
+ * Channel interface.
+ */
+export interface Channel {
+    /**
+     * Channel name.
+     */
+    name: string;
+    /**
+     * Channel type.
+     */
+    type: 'public' | 'private' | 'presence';
+}
+/**
+ * Base event class.
+ *
+ * All events should extend this class.
+ */
+export declare abstract class Event {
+    /**
+     * Whether this event should be broadcast.
+     */
+    shouldBroadcast(): boolean;
+    /**
+     * Get broadcast channel.
+     */
+    getBroadcastChannel(): string | Channel | null;
+    /**
+     * Get broadcast payload.
+     */
+    getBroadcastData(): Record<string, unknown>;
+    /**
+     * Get broadcast event name.
+     */
+    getBroadcastEventName(): string;
+}

package/dist/echo/src/OrbitEcho.d.ts

@@ -0,0 +1,60 @@
+import type { GravitoOrbit, PlanetCore } from '@gravito/core';
+import { WebhookReceiver } from './receive/WebhookReceiver';
+import { WebhookDispatcher } from './send/WebhookDispatcher';
+import type { EchoConfig } from './types';
+/**
+ * OrbitEcho is the official webhook orchestration module for Gravito.
+ *
+ * It provides a secure way to receive incoming webhooks (e.g., from Stripe, GitHub)
+ * and a reliable way to dispatch outgoing webhooks to third-party services.
+ *
+ * @example
+ * ```typescript
+ * const echo = new OrbitEcho({
+ *   providers: {
+ *     stripe: { name: 'stripe', secret: 'whsec_...' }
+ *   }
+ * });
+ * core.addOrbit(echo);
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+export declare class OrbitEcho implements GravitoOrbit {
+    private receiver;
+    private dispatcher?;
+    private echoConfig;
+    /**
+     * Create a new OrbitEcho instance.
+     *
+     * @param config - The configuration object for providers and dispatcher.
+     */
+    constructor(config?: EchoConfig);
+    /**
+     * Install into PlanetCore
+     *
+     * Registers the OrbitEcho instance and its components into the service container.
+     *
+     * @param core - The PlanetCore instance.
+     */
+    install(core: PlanetCore): void;
+    /**
+     * Get webhook receiver
+     */
+    getReceiver(): WebhookReceiver;
+    /**
+     * Get webhook dispatcher
+     */
+    getDispatcher(): WebhookDispatcher | undefined;
+    /**
+     * Get configuration
+     */
+    getConfig(): EchoConfig;
+}
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Webhook receiver and dispatcher */
+        echo?: OrbitEcho;
+    }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview @gravito/echo - Enterprise Webhook Module
+ *
+ * Secure webhook receiving and reliable webhook sending for Gravito.
+ *
+ * @example Receiving webhooks
+ * ```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! }
+ *   }
+ * }))
+ *
+ * const receiver = core.container.make<WebhookReceiver>('echo.receiver')
+ * receiver.on('stripe', 'payment_intent.succeeded', async (event) => {
+ *   console.log('Payment:', event.payload)
+ * })
+ * ```
+ *
+ * @example Sending webhooks
+ * ```typescript
+ * import { WebhookDispatcher } from '@gravito/echo'
+ *
+ * const dispatcher = new WebhookDispatcher({
+ *   secret: 'my-secret'
+ * })
+ *
+ * await dispatcher.dispatch({
+ *   url: 'https://example.com/webhook',
+ *   event: 'order.created',
+ *   data: { orderId: 123 }
+ * })
+ * ```
+ *
+ * @module @gravito/echo
+ */
+export { OrbitEcho } from './OrbitEcho';
+export { GenericProvider } from './providers/GenericProvider';
+export { GitHubProvider } from './providers/GitHubProvider';
+export { StripeProvider } from './providers/StripeProvider';
+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';

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

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Generic webhook provider
+ *
+ * Simple HMAC-SHA256 signature verification.
+ *
+ * @module @gravito/echo/providers
+ */
+import type { WebhookProvider, WebhookVerificationResult } from '../types';
+/**
+ * Generic webhook provider using HMAC-SHA256
+ *
+ * Expected headers:
+ * - X-Webhook-Signature: HMAC-SHA256 hex signature
+ * - X-Webhook-Timestamp: Unix timestamp (optional)
+ *
+ * @example
+ * ```typescript
+ * const provider = new GenericProvider()
+ * const result = await provider.verify(body, headers, secret)
+ * ```
+ */
+export declare class GenericProvider implements WebhookProvider {
+    readonly name = "generic";
+    private signatureHeader;
+    private timestampHeader;
+    private tolerance;
+    constructor(options?: {
+        signatureHeader?: string;
+        timestampHeader?: string;
+        tolerance?: number;
+    });
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+    private getHeader;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview GitHub webhook provider
+ *
+ * Implements GitHub's webhook signature verification.
+ * @see https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
+ *
+ * @module @gravito/echo/providers
+ */
+import type { WebhookProvider, WebhookVerificationResult } from '../types';
+/**
+ * GitHub webhook provider
+ *
+ * Verifies GitHub webhook signatures using the X-Hub-Signature-256 header.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GitHubProvider()
+ * const result = await provider.verify(body, headers, process.env.GITHUB_WEBHOOK_SECRET)
+ * ```
+ */
+export declare class GitHubProvider implements WebhookProvider {
+    readonly name = "github";
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+    parseEventType(payload: unknown): string | undefined;
+    private getHeader;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Stripe webhook provider
+ *
+ * Implements Stripe's webhook signature verification.
+ * @see https://stripe.com/docs/webhooks/signatures
+ *
+ * @module @gravito/echo/providers
+ */
+import type { WebhookProvider, WebhookVerificationResult } from '../types';
+/**
+ * Stripe webhook provider
+ *
+ * Verifies Stripe webhook signatures using their standard format.
+ *
+ * @example
+ * ```typescript
+ * const provider = new StripeProvider()
+ * const result = await provider.verify(body, headers, process.env.STRIPE_WEBHOOK_SECRET)
+ * ```
+ */
+export declare class StripeProvider implements WebhookProvider {
+    readonly name = "stripe";
+    private tolerance;
+    constructor(options?: {
+        tolerance?: number;
+    });
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+    parseEventType(payload: unknown): string | undefined;
+    private getHeader;
+}

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

@@ -0,0 +1,3 @@
+export * from './GenericProvider';
+export * from './GitHubProvider';
+export * from './StripeProvider';

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

@@ -0,0 +1,34 @@
+/**
+ * @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>;
+/**
+ * Compute HMAC-SHA1 signature (for legacy providers)
+ */
+export declare function computeHmacSha1(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

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Webhook Receiver
+ *
+ * Handles incoming webhooks with signature verification.
+ *
+ * @module @gravito/echo/receive
+ */
+import type { WebhookHandler, WebhookProvider, WebhookVerificationResult } from '../types';
+type ProviderClass = new (options?: any) => WebhookProvider;
+/**
+ * Webhook Receiver
+ *
+ * Manages webhook providers and routes incoming webhooks to handlers.
+ *
+ * @example
+ * ```typescript
+ * const receiver = new WebhookReceiver()
+ *
+ * // Register provider
+ * receiver.registerProvider('stripe', process.env.STRIPE_WEBHOOK_SECRET!)
+ *
+ * // Register handler
+ * 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)
+ * ```
+ */
+export declare class WebhookReceiver {
+    private providers;
+    private handlers;
+    private globalHandlers;
+    constructor();
+    private providerTypes;
+    /**
+     * Register a custom provider type
+     */
+    registerProviderType(name: string, ProviderCls: ProviderClass): this;
+    /**
+     * Register a provider with its secret
+     */
+    registerProvider(name: string, secret: string, options?: {
+        type?: string;
+        tolerance?: number;
+    }): this;
+    /**
+     * Register an event handler
+     */
+    on<T = unknown>(providerName: string, eventType: string, handler: WebhookHandler<T>): this;
+    /**
+     * Register a handler for all events from a provider
+     */
+    onAll<T = unknown>(providerName: string, handler: WebhookHandler<T>): this;
+    /**
+     * Handle an incoming webhook
+     */
+    handle(providerName: string, body: string | Buffer, headers: Record<string, string | string[] | undefined>): Promise<WebhookVerificationResult & {
+        handled: boolean;
+    }>;
+    /**
+     * Verify a webhook without handling
+     */
+    verify(providerName: string, body: string | Buffer, headers: Record<string, string | string[] | undefined>): Promise<WebhookVerificationResult>;
+}
+export {};

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Webhook Dispatcher
+ *
+ * Reliably sends webhooks to external services with retry support.
+ *
+ * @module @gravito/echo/send
+ */
+import type { WebhookDeliveryResult, WebhookDispatcherConfig, WebhookPayload } from '../types';
+/**
+ * Webhook Dispatcher
+ *
+ * Sends webhooks with signature and retry support.
+ *
+ * @example
+ * ```typescript
+ * const dispatcher = new WebhookDispatcher({
+ *   secret: 'my-webhook-secret',
+ *   retry: { maxAttempts: 5 }
+ * })
+ *
+ * const result = await dispatcher.dispatch({
+ *   url: 'https://example.com/webhook',
+ *   event: 'order.created',
+ *   data: { orderId: 123 }
+ * })
+ * ```
+ */
+export declare class WebhookDispatcher {
+    private secret;
+    private retryConfig;
+    private timeout;
+    private userAgent;
+    constructor(config: WebhookDispatcherConfig);
+    /**
+     * Dispatch a webhook with retries
+     */
+    dispatch<T = unknown>(payload: WebhookPayload<T>): Promise<WebhookDeliveryResult>;
+    /**
+     * Attempt a single delivery
+     */
+    private attemptDelivery;
+    /**
+     * Check if we should retry based on result
+     */
+    private shouldRetry;
+    /**
+     * Calculate delay for exponential backoff
+     */
+    private calculateDelay;
+    /**
+     * Sleep helper
+     */
+    private sleep;
+}

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

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

package/dist/echo/src/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Core types for @gravito/echo webhook module
+ * @module @gravito/echo
+ */
+/**
+ * Configuration for a specific webhook provider (e.g., Stripe, GitHub).
+ * @public
+ */
+export interface WebhookProviderConfig {
+    /** The unique name of the provider */
+    name: string;
+    /** The shared secret used to verify incoming webhook signatures */
+    secret: string;
+    /** The name of the HTTP header containing the signature (e.g., 'stripe-signature') */
+    signatureHeader?: string;
+    /** Maximum allowed time drift in seconds for timestamp validation (default: 300) */
+    tolerance?: number;
+}
+/**
+ * The result of verifying an incoming webhook request.
+ * @public
+ */
+export interface WebhookVerificationResult {
+    /** True if the signature is valid and the timestamp is within tolerance */
+    valid: boolean;
+    /** Descriptive error message if the verification failed */
+    error?: string;
+    /** The parsed JSON payload from the request body */
+    payload?: unknown;
+    /** The specific event name extracted from the payload or headers */
+    eventType?: string;
+    /** The unique identifier for this webhook message, if provided by the source */
+    webhookId?: string;
+}
+/**
+ * Interface that all webhook provider implementations must follow.
+ * Providers handle the logic for specific services like Stripe or Shopify.
+ * @public
+ */
+export interface WebhookProvider {
+    /** Uniquely identifies the provider (e.g., 'stripe') */
+    readonly name: string;
+    /**
+     * Validates the integrity and authenticity of an incoming request.
+     *
+     * @param payload - The raw request body as a string or Buffer.
+     * @param headers - The incoming HTTP headers.
+     * @param secret - The secret key used for verification.
+     */
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+    /**
+     * Determines the event type from the validated payload.
+     * @param payload - The parsed JSON body.
+     */
+    parseEventType?(payload: unknown): string | undefined;
+}
+/**
+ * A callback function triggered when a valid webhook event is received.
+ * @public
+ */
+export type WebhookHandler<T = unknown> = (event: WebhookEvent<T>) => void | Promise<void>;
+/**
+ * Represents a normalized webhook event processed by Echo.
+ * Provides a consistent interface regardless of the source provider.
+ * @public
+ */
+export interface WebhookEvent<T = unknown> {
+    /** Name of the provider that sent the event */
+    provider: string;
+    /** The type of event (e.g., 'payment_intent.succeeded') */
+    type: string;
+    /** The parsed and type-safe data payload */
+    payload: T;
+    /** The original HTTP headers received with the request */
+    headers: Record<string, string | string[] | undefined>;
+    /** The raw, unparsed request body string */
+    rawBody: string;
+    /** The local system time when the webhook was received */
+    receivedAt: Date;
+    /** Unique ID for the event, if provided by the source */
+    id?: string;
+}
+/**
+ * Data structure for sending a webhook to an external service.
+ * @public
+ */
+export interface WebhookPayload<T = unknown> {
+    /** The destination URL where the webhook should be POSTed */
+    url: string;
+    /** The name of the event being dispatched */
+    event: string;
+    /** The data to be JSON-encoded and sent in the body */
+    data: T;
+    /** Optional unique identifier for this specific delivery attempt */
+    id?: string;
+    /** Optional timestamp representing when the event occurred */
+    timestamp?: Date;
+}
+/**
+ * Summary of a webhook delivery attempt.
+ * @public
+ */
+export interface WebhookDeliveryResult {
+    /** True if the destination returned a 2xx status code */
+    success: boolean;
+    /** The HTTP status code returned by the destination server */
+    statusCode?: number;
+    /** The raw response body from the destination server */
+    body?: string;
+    /** Error message if the request failed (e.g., network timeout) */
+    error?: string;
+    /** Which attempt number this was (starts at 1) */
+    attempt: number;
+    /** Total time elapsed for the request in milliseconds */
+    duration: number;
+    /** Timestamp when the delivery attempt was recorded */
+    deliveredAt: Date;
+}
+/**
+ * Strategy for retrying failed webhook deliveries with exponential backoff.
+ * @public
+ */
+export interface RetryConfig {
+    /** Maximum number of delivery attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay before the first retry in milliseconds (default: 1000) */
+    initialDelay?: number;
+    /** Multiplier for the delay between subsequent retries (default: 2) */
+    backoffMultiplier?: number;
+    /** Upper bound for the retry delay in milliseconds (default: 300,000) */
+    maxDelay?: number;
+    /** List of HTTP status codes that should trigger a retry (e.g., 502, 503) */
+    retryableStatuses?: number[];
+}
+/**
+ * Configuration for the outgoing webhook dispatcher.
+ * @public
+ */
+export interface WebhookDispatcherConfig {
+    /** Secret key used to sign outgoing webhook payloads for security */
+    secret: string;
+    /** Optional retry strategy for failed deliveries */
+    retry?: RetryConfig;
+    /** Maximum time in milliseconds to wait for a response (default: 30,000) */
+    timeout?: number;
+    /** Custom User-Agent header for the outgoing request */
+    userAgent?: string;
+}
+/**
+ * Full configuration for the OrbitEcho module.
+ * @public
+ */
+export interface EchoConfig {
+    /** Map of named provider configurations for receiving webhooks */
+    providers?: Record<string, WebhookProviderConfig>;
+    /** Settings for sending webhooks to other services */
+    dispatcher?: WebhookDispatcherConfig;
+    /**
+     * The URL prefix for the automatically generated webhook endpoints.
+     * (e.g., '/webhooks' will create '/webhooks/:provider')
+     * Default: '/webhooks'
+     */
+    basePath?: string;
+}

package/dist/index.js

@@ -434,7 +434,6 @@ class WebhookDispatcher {
 
 // src/OrbitEcho.ts
 class OrbitEcho {
-  static config = { singleton: true };
   receiver;
   dispatcher;
   echoConfig;
@@ -459,6 +458,11 @@ class OrbitEcho {
     if (this.dispatcher) {
       core.container.instance("echo.dispatcher", this.dispatcher);
     }
+    core.adapter.use("*", async (c, next) => {
+      c.set("echo", this);
+      return await next();
+    });
+    core.logger.info("[OrbitEcho] Webhook receiver and dispatcher registered");
   }
   getReceiver() {
     return this.receiver;
@@ -484,4 +488,4 @@ export {
   GenericProvider
 };
 
-//# debugId=B1111F963DAFCE1264756E2164756E21
+//# debugId=ECB32FF3DBDFBFDC64756E2164756E21