@gravito/echo 3.0.1 → 3.1.0

package/dist/echo/src/observability/logging/ConsoleEchoLogger.d.ts

@@ -0,0 +1,37 @@
+import type { EchoLogger } from './EchoLogger';
+/**
+ * A basic implementation of {@link EchoLogger} that outputs logs to the system console.
+ * Logs are formatted as JSON strings to facilitate integration with log aggregators.
+ *
+ * @example
+ * ```typescript
+ * const logger = new ConsoleEchoLogger();
+ * logger.info('Service started');
+ * ```
+ */
+export declare class ConsoleEchoLogger implements EchoLogger {
+    /**
+     * Enriches the log context with default module information and timestamps.
+     *
+     * @param base - The base context object.
+     * @param extra - Additional metadata to include.
+     * @returns A merged context object.
+     */
+    private formatContext;
+    /**
+     * Outputs a debug-level log entry.
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Outputs an info-level log entry.
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Outputs a warn-level log entry.
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Outputs an error-level log entry.
+     */
+    error(message: string, context?: Record<string, unknown>): void;
+}

package/dist/echo/src/observability/logging/EchoLogger.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Represents a structured log event within the Echo module.
+ * Used to ensure consistency across different logging implementations.
+ */
+export interface EchoLogEvent {
+    /** Severity level of the log entry. */
+    level: 'debug' | 'info' | 'warn' | 'error';
+    /** Human-readable message describing the event. */
+    message: string;
+    /** Contextual metadata for better traceability. */
+    context: {
+        /** Always 'echo' to identify the source module. */
+        module: 'echo';
+        /** The specific sub-component triggering the log. */
+        component: 'receiver' | 'dispatcher' | 'dlq' | 'replay';
+        [key: string]: unknown;
+    };
+}
+/**
+ * Defines the standard logging interface for the Echo module.
+ * Implementations should handle structured data for observability.
+ *
+ * @example
+ * ```typescript
+ * const logger: EchoLogger = new ConsoleEchoLogger();
+ * logger.info('Webhook received', { provider: 'stripe' });
+ * ```
+ */
+export interface EchoLogger {
+    /** Logs fine-grained informational events that are most useful to debug an application. */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /** Logs informational messages that highlight the progress of the application at coarse-grained level. */
+    info(message: string, context?: Record<string, unknown>): void;
+    /** Logs potentially harmful situations. */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /** Logs error events that might still allow the application to continue running. */
+    error(message: string, context?: Record<string, unknown>): void;
+}

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

@@ -0,0 +1,2 @@
+export * from './ConsoleEchoLogger';
+export * from './EchoLogger';

package/dist/echo/src/observability/metrics/MetricsProvider.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Defines the interface for collecting application metrics.
+ * Implementations can bridge to Prometheus, StatsD, or other monitoring systems.
+ *
+ * @example
+ * ```typescript
+ * const metrics: MetricsProvider = getMetrics();
+ * metrics.increment(EchoMetrics.INCOMING_TOTAL, { provider: 'stripe' });
+ * ```
+ */
+export interface MetricsProvider {
+    /**
+     * Increments a counter by 1.
+     * Counters are used for values that only increase (e.g., total requests).
+     */
+    increment(name: string, labels?: Record<string, string>): void;
+    /**
+     * Records a value in a histogram.
+     * Histograms are used to track the distribution of values (e.g., request latency).
+     */
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Sets a gauge to a specific value.
+     * Gauges are used for values that can go up and down (e.g., current queue size).
+     */
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+}
+/**
+ * Common labels used for webhook-related metrics.
+ */
+export interface WebhookMetricLabels {
+    /** The webhook provider name (e.g., 'stripe', 'github'). */
+    provider?: string;
+    /** The type of event received or sent. */
+    event_type?: string;
+    /** The outcome of the operation. */
+    status?: 'success' | 'failure';
+    /** The HTTP status code returned by the remote server. */
+    status_code?: string;
+    /** A category for the error if the operation failed. */
+    error_type?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Standard metric names used across the Echo module.
+ * Use these constants to ensure consistency in dashboards and alerts.
+ */
+export declare const EchoMetrics: {
+    /** Total number of incoming webhooks received. */
+    readonly INCOMING_TOTAL: "echo_incoming_webhooks_total";
+    /** Time taken to process an incoming webhook. */
+    readonly INCOMING_DURATION: "echo_incoming_duration_seconds";
+    /** Total number of incoming webhooks that failed signature verification. */
+    readonly INCOMING_VERIFICATION_FAILURES: "echo_incoming_verification_failures_total";
+    /** Total number of outgoing webhooks dispatched. */
+    readonly OUTGOING_TOTAL: "echo_outgoing_webhooks_total";
+    /** Time taken to deliver an outgoing webhook. */
+    readonly OUTGOING_DURATION: "echo_outgoing_duration_seconds";
+    /** Total number of retry attempts for outgoing webhooks. */
+    readonly OUTGOING_RETRIES: "echo_outgoing_retries_total";
+    /** Total number of outgoing webhooks that failed after all retries. */
+    readonly OUTGOING_FAILURES: "echo_outgoing_failures_total";
+    /** Current number of items in the Dead Letter Queue. */
+    readonly DLQ_SIZE: "echo_dlq_size";
+    /** Total number of items added to the DLQ. */
+    readonly DLQ_ENQUEUED: "echo_dlq_enqueued_total";
+    /** Total number of items successfully processed from the DLQ. */
+    readonly DLQ_PROCESSED: "echo_dlq_processed_total";
+};

package/dist/echo/src/observability/metrics/NoopMetricsProvider.d.ts

@@ -0,0 +1,17 @@
+import type { MetricsProvider } from './MetricsProvider';
+/**
+ * A non-operational implementation of {@link MetricsProvider}.
+ * Used as the default provider to ensure the application remains functional
+ * even if no monitoring system is configured.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new NoopMetricsProvider();
+ * metrics.increment('any_metric'); // Does nothing
+ * ```
+ */
+export declare class NoopMetricsProvider implements MetricsProvider {
+    increment(): void;
+    histogram(): void;
+    gauge(): void;
+}

package/dist/echo/src/observability/metrics/PrometheusMetricsProvider.d.ts

@@ -0,0 +1,39 @@
+import type { MetricsProvider } from './MetricsProvider';
+/**
+ * A Prometheus-compatible metrics provider.
+ * Collects and formats metrics in the Prometheus text-based format.
+ *
+ * @example
+ * ```typescript
+ * const provider = new PrometheusMetricsProvider();
+ * provider.increment('http_requests_total', { method: 'POST' });
+ * console.log(provider.export());
+ * ```
+ */
+export declare class PrometheusMetricsProvider implements MetricsProvider {
+    private counters;
+    private histograms;
+    private gauges;
+    /**
+     * Increments a counter for the given name and labels.
+     */
+    increment(name: string, labels?: Record<string, string>): void;
+    /**
+     * Records a value in a histogram for the given name and labels.
+     */
+    histogram(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Sets a gauge to a specific value for the given name and labels.
+     */
+    gauge(name: string, value: number, labels?: Record<string, string>): void;
+    /**
+     * Exports all collected metrics in Prometheus text format.
+     *
+     * @returns A string containing the formatted metrics.
+     */
+    export(): string;
+    /**
+     * Builds a Prometheus-compatible metric key with labels.
+     */
+    private buildKey;
+}

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

@@ -0,0 +1,3 @@
+export * from './MetricsProvider';
+export * from './NoopMetricsProvider';
+export * from './PrometheusMetricsProvider';

package/dist/echo/src/observability/tracing/NoopTracer.d.ts

@@ -0,0 +1,33 @@
+import type { Span, Tracer } from './Tracer';
+/**
+ * A non-operational implementation of {@link Span}.
+ * Used as a fallback when tracing is disabled to avoid null checks.
+ */
+export declare class NoopSpan implements Span {
+    setAttribute(): this;
+    setAttributes(): this;
+    addEvent(): this;
+    setStatus(): this;
+    end(): void;
+}
+/**
+ * A non-operational implementation of {@link Tracer}.
+ * Ensures the application can run without a tracing backend.
+ *
+ * @example
+ * ```typescript
+ * const tracer = new NoopTracer();
+ * const span = tracer.startSpan('test');
+ * span.end();
+ * ```
+ */
+export declare class NoopTracer implements Tracer {
+    /**
+     * Returns a {@link NoopSpan} that does nothing.
+     */
+    startSpan(): Span;
+    /**
+     * Executes the function with a {@link NoopSpan}.
+     */
+    withSpan<T>(_name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
+}

package/dist/echo/src/observability/tracing/Tracer.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Represents a single unit of work in a trace.
+ * Compatible with OpenTelemetry Span interface to allow seamless integration.
+ */
+export interface Span {
+    /**
+     * Sets a single attribute on the span.
+     * Attributes provide additional metadata for the operation.
+     */
+    setAttribute(key: string, value: string | number | boolean): this;
+    /**
+     * Sets multiple attributes on the span at once.
+     */
+    setAttributes(attributes: Record<string, string | number | boolean>): this;
+    /**
+     * Records a specific event that occurred during the span's lifetime.
+     */
+    addEvent(name: string, attributes?: Record<string, string | number>): this;
+    /**
+     * Sets the final status of the span.
+     */
+    setStatus(status: {
+        code: SpanStatusCode;
+        message?: string;
+    }): this;
+    /**
+     * Marks the end of the span, making it ready for export.
+     */
+    end(): void;
+}
+/**
+ * Standard status codes for a {@link Span}.
+ */
+export declare enum SpanStatusCode {
+    /** Default status. */
+    UNSET = 0,
+    /** Operation completed successfully. */
+    OK = 1,
+    /** Operation failed. */
+    ERROR = 2
+}
+/**
+ * Defines the tracing interface for the Echo module.
+ * Used to track the lifecycle of webhook requests and deliveries.
+ *
+ * @example
+ * ```typescript
+ * const tracer: Tracer = getTracer();
+ * await tracer.withSpan('process-webhook', async (span) => {
+ *   span.setAttribute('provider', 'stripe');
+ *   // ... logic
+ * });
+ * ```
+ */
+export interface Tracer {
+    /**
+     * Starts a new span without making it active.
+     * The caller is responsible for ending the span.
+     */
+    startSpan(name: string, options?: SpanOptions): Span;
+    /**
+     * Executes a function within the context of a new span.
+     * Automatically ends the span when the function completes.
+     */
+    withSpan<T>(name: string, fn: (span: Span) => T | Promise<T>): Promise<T>;
+}
+/**
+ * Configuration options for starting a new {@link Span}.
+ */
+export interface SpanOptions {
+    /** The relationship between the span and its neighbors. */
+    kind?: 'client' | 'server' | 'producer' | 'consumer' | 'internal';
+    /** Initial attributes to set on the span. */
+    attributes?: Record<string, string | number | boolean>;
+}

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

@@ -0,0 +1,2 @@
+export * from './NoopTracer';
+export * from './Tracer';

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

@@ -1,34 +1,53 @@
 /**
- * @fileoverview Generic webhook provider
- *
- * Simple HMAC-SHA256 signature verification.
- *
+ * Generic webhook provider.
  * @module @gravito/echo/providers
  */
-import type { WebhookProvider, WebhookVerificationResult } from '../types';
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider, type ProviderOptions } from './base/BaseProvider';
+/**
+ * Configuration options for the generic provider.
+ */
+export interface GenericProviderOptions extends ProviderOptions {
+    /**
+     * Custom header name for the signature.
+     * @defaultValue 'x-webhook-signature'
+     */
+    signatureHeader?: string;
+    /**
+     * Custom header name for the timestamp.
+     * @defaultValue 'x-webhook-timestamp'
+     */
+    timestampHeader?: string;
+}
 /**
- * Generic webhook provider using HMAC-SHA256
+ * Generic webhook provider using HMAC-SHA256 for signature verification.
  *
  * Expected headers:
- * - X-Webhook-Signature: HMAC-SHA256 hex signature
- * - X-Webhook-Timestamp: Unix timestamp (optional)
+ * - X-Webhook-Signature: HMAC-SHA256 hex signature.
+ * - X-Webhook-Timestamp: Unix timestamp (optional, used for replay protection).
  *
  * @example
  * ```typescript
- * const provider = new GenericProvider()
- * const result = await provider.verify(body, headers, secret)
+ * const provider = new GenericProvider({
+ *   signatureHeader: 'X-Custom-Sig',
+ *   tolerance: 600
+ * });
+ * const result = await provider.verify(body, headers, secret);
  * ```
  */
-export declare class GenericProvider implements WebhookProvider {
+export declare class GenericProvider extends BaseProvider {
     readonly name = "generic";
     private signatureHeader;
     private timestampHeader;
-    private tolerance;
-    constructor(options?: {
-        signatureHeader?: string;
-        timestampHeader?: string;
-        tolerance?: number;
-    });
+    constructor(options?: GenericProviderOptions);
+    /**
+     * Verifies the webhook using HMAC-SHA256.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Secret key for HMAC computation.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
     verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
-    private getHeader;
 }

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

@@ -1,26 +1,35 @@
 /**
- * @fileoverview GitHub webhook provider
- *
- * Implements GitHub's webhook signature verification.
- * @see https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
- *
+ * GitHub webhook provider.
  * @module @gravito/echo/providers
  */
-import type { WebhookProvider, WebhookVerificationResult } from '../types';
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
 /**
- * GitHub webhook provider
+ * GitHub webhook provider.
  *
- * Verifies GitHub webhook signatures using the X-Hub-Signature-256 header.
+ * Verifies GitHub webhook signatures using the `X-Hub-Signature-256` header.
+ * @see {@link https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries | GitHub Webhook Validation}
  *
  * @example
  * ```typescript
- * const provider = new GitHubProvider()
- * const result = await provider.verify(body, headers, process.env.GITHUB_WEBHOOK_SECRET)
+ * const provider = new GitHubProvider();
+ * const result = await provider.verify(body, headers, process.env.GITHUB_WEBHOOK_SECRET);
  * ```
  */
-export declare class GitHubProvider implements WebhookProvider {
+export declare class GitHubProvider extends BaseProvider {
     readonly name = "github";
+    /**
+     * Verifies the GitHub webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - GitHub webhook 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 action from the GitHub payload if available.
+     */
     parseEventType(payload: unknown): string | undefined;
-    private getHeader;
 }

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

@@ -0,0 +1,27 @@
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
+/**
+ * Linear webhook provider.
+ *
+ * Verifies Linear webhook signatures using the `Linear-Signature` header.
+ * @see {@link https://developers.linear.app/docs/graphql/webhooks#signature-verification | Linear Webhook Verification}
+ *
+ * @example
+ * ```typescript
+ * const provider = new LinearProvider();
+ * const result = await provider.verify(body, headers, process.env.LINEAR_WEBHOOK_SECRET);
+ * ```
+ */
+export declare class LinearProvider extends BaseProvider {
+    readonly name = "linear";
+    /**
+     * Verifies the Linear webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Linear webhook secret.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+}

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

@@ -0,0 +1,31 @@
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
+/**
+ * Paddle webhook provider.
+ *
+ * Verifies Paddle webhook signatures using the `Paddle-Signature` header.
+ * @see {@link https://developer.paddle.com/webhooks/signature-verification | Paddle Signature Verification}
+ *
+ * @example
+ * ```typescript
+ * const provider = new PaddleProvider();
+ * const result = await provider.verify(body, headers, process.env.PADDLE_WEBHOOK_SECRET);
+ * ```
+ */
+export declare class PaddleProvider extends BaseProvider {
+    readonly name = "paddle";
+    /**
+     * Verifies the Paddle webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Paddle webhook secret.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+    /**
+     * Parses the Paddle-Signature header into timestamp and signature components.
+     */
+    private parsePaddleSignature;
+}

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

@@ -0,0 +1,27 @@
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
+/**
+ * Shopify webhook provider.
+ *
+ * Verifies Shopify webhook signatures using the `X-Shopify-Hmac-Sha256` header.
+ * @see {@link https://shopify.dev/docs/apps/webhooks/configuration/https#verify-webhook | Shopify Webhook Verification}
+ *
+ * @example
+ * ```typescript
+ * const provider = new ShopifyProvider();
+ * const result = await provider.verify(body, headers, process.env.SHOPIFY_WEBHOOK_SECRET);
+ * ```
+ */
+export declare class ShopifyProvider extends BaseProvider {
+    readonly name = "shopify";
+    /**
+     * Verifies the Shopify webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Shopify webhook secret.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+}

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

@@ -0,0 +1,27 @@
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
+/**
+ * Slack webhook provider.
+ *
+ * Verifies Slack webhook signatures using the `X-Slack-Signature` and `X-Slack-Request-Timestamp` headers.
+ * @see {@link https://api.slack.com/authentication/verifying-requests-from-slack | Slack Request Verification}
+ *
+ * @example
+ * ```typescript
+ * const provider = new SlackProvider();
+ * const result = await provider.verify(body, headers, process.env.SLACK_SIGNING_SECRET);
+ * ```
+ */
+export declare class SlackProvider extends BaseProvider {
+    readonly name = "slack";
+    /**
+     * Verifies the Slack webhook signature.
+     *
+     * @param payload - Raw request body.
+     * @param headers - Request headers.
+     * @param secret - Slack 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>;
+}

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

@@ -1,30 +1,38 @@
 /**
- * @fileoverview Stripe webhook provider
- *
- * Implements Stripe's webhook signature verification.
- * @see https://stripe.com/docs/webhooks/signatures
- *
+ * Stripe webhook provider.
  * @module @gravito/echo/providers
  */
-import type { WebhookProvider, WebhookVerificationResult } from '../types';
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider } from './base/BaseProvider';
 /**
- * Stripe webhook provider
+ * 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)
+ * const provider = new StripeProvider();
+ * const result = await provider.verify(body, headers, process.env.STRIPE_WEBHOOK_SECRET);
  * ```
  */
-export declare class StripeProvider implements WebhookProvider {
+export declare class StripeProvider extends BaseProvider {
     readonly name = "stripe";
-    private tolerance;
     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;
-    private getHeader;
 }

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

@@ -0,0 +1,31 @@
+import type { WebhookVerificationResult } from '../types';
+import { BaseProvider, type ProviderOptions } from './base/BaseProvider';
+/**
+ * Twilio webhook provider.
+ *
+ * Verifies Twilio webhook signatures using the `X-Twilio-Signature` header.
+ * @see {@link https://www.twilio.com/docs/usage/security#validating-requests | Twilio Request Validation}
+ *
+ * @example
+ * ```typescript
+ * const provider = new TwilioProvider({ baseUrl: 'https://api.example.com/webhooks/twilio' });
+ * const result = await provider.verify(body, headers, process.env.TWILIO_AUTH_TOKEN);
+ * ```
+ */
+export declare class TwilioProvider extends BaseProvider {
+    readonly name = "twilio";
+    private baseUrl?;
+    constructor(options?: ProviderOptions & {
+        baseUrl?: string;
+    });
+    /**
+     * Verifies the Twilio webhook signature.
+     *
+     * @param payload - Raw request body (URL-encoded).
+     * @param headers - Request headers.
+     * @param secret - Twilio Auth Token.
+     * @returns Verification result.
+     * @throws Error if signature computation fails.
+     */
+    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
+}