@gravito/echo 3.0.1 → 3.1.1

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

@@ -1,56 +1,111 @@
 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';
 /**
- * OrbitEcho is the official webhook orchestration module for Gravito.
+ * OrbitEcho is the official webhook orchestration module for the Gravito ecosystem.
  *
- * 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.
+ * 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
+ * import { PlanetCore } from '@gravito/core';
+ * import { OrbitEcho } from '@gravito/echo';
+ *
+ * const core = new PlanetCore();
  * const echo = new OrbitEcho({
  *   providers: {
- *     stripe: { name: 'stripe', secret: 'whsec_...' }
+ *     stripe: { name: 'stripe', secret: process.env.STRIPE_SECRET }
+ *   },
+ *   dispatcher: {
+ *     secret: process.env.APP_WEBHOOK_SECRET
  *   }
  * });
- * core.addOrbit(echo);
+ *
+ * core.install(echo);
  * ```
  *
  * @public
- * @since 3.0.0
  */
 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 active WebhookReceiver instance.
      */
     getReceiver(): WebhookReceiver;
     /**
-     * Get webhook dispatcher
+     * Retrieves the dispatcher instance for sending outgoing webhooks.
+     *
+     * @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 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 {

package/dist/echo/src/dlq/DeadLetterQueue.d.ts

@@ -0,0 +1,94 @@
+import type { IncomingWebhookRecord, OutgoingWebhookRecord } from '../storage/WebhookStore';
+/**
+ * Interface for a Dead Letter Queue (DLQ) implementation.
+ *
+ * A DLQ serves as a safety net for webhook events that have permanently failed
+ * all processing or delivery attempts. It enables manual inspection, diagnostic
+ * analysis, and eventual re-processing of high-value events that would otherwise
+ * be lost due to transient or permanent failures.
+ *
+ * @example Inspected failed events
+ * ```typescript
+ * const dlq: DeadLetterQueue = new MyPersistentDlq();
+ *
+ * // Retrieve recent failures for manual triage
+ * const failedEvents = await dlq.peek(10);
+ * for (const event of failedEvents) {
+ *   console.log(`Event ${event.id} failed after ${event.retryCount} attempts: ${event.failureReason}`);
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface DeadLetterQueue {
+    /**
+     * Appends a permanently failed event to the queue for later inspection.
+     *
+     * @param event - The dead letter event metadata and original record.
+     * @returns A promise resolving to a unique identifier for the event within the queue.
+     * @throws {Error} If the underlying storage fails to persist the event.
+     */
+    enqueue(event: DeadLetterEvent): Promise<string>;
+    /**
+     * Retrieves a snapshot of failed events from the queue without removing them.
+     *
+     * @param limit - Maximum number of events to retrieve (ordered by failure time).
+     * @returns A collection of dead letter events.
+     */
+    peek(limit?: number): Promise<DeadLetterEvent[]>;
+    /**
+     * Permanently removes an event from the queue after successful manual resolution.
+     *
+     * @param id - The unique identifier assigned during the `enqueue` process.
+     * @throws {Error} If the event ID is invalid or not found in the queue.
+     */
+    dequeue(id: string): Promise<void>;
+    /**
+     * Calculates the total number of events currently residing in the queue.
+     *
+     * @returns The total count of dead letter events.
+     */
+    size(): Promise<number>;
+    /**
+     * Removes all events from the queue, resetting it to an empty state.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Metadata and payload for a failed webhook event stored in the Dead Letter Queue.
+ *
+ * This structure captures the complete context of a failure, including the original
+ * data and the diagnostic reason for the final failure.
+ *
+ * @public
+ */
+export interface DeadLetterEvent {
+    /**
+     * A unique identifier for the entry within the DLQ storage.
+     */
+    id?: string;
+    /**
+     * Indicates whether the failure occurred during reception or dispatch.
+     */
+    type: 'incoming' | 'outgoing';
+    /**
+     * The complete original record of the webhook at the moment of failure.
+     */
+    originalEvent: IncomingWebhookRecord | OutgoingWebhookRecord;
+    /**
+     * A descriptive diagnostic message explaining why the event was sent to the DLQ.
+     */
+    failureReason: string;
+    /**
+     * The exact timestamp when the event reached its maximum retry limit or terminal error.
+     */
+    failedAt: Date;
+    /**
+     * The total number of automated attempts made before giving up on the event.
+     */
+    retryCount: number;
+    /**
+     * The timestamp of the final attempted processing or delivery action.
+     */
+    lastRetryAt?: Date;
+}

package/dist/echo/src/dlq/MemoryDeadLetterQueue.d.ts

@@ -0,0 +1,36 @@
+import type { DeadLetterEvent, DeadLetterQueue } from './DeadLetterQueue';
+/**
+ * An in-memory implementation of {@link DeadLetterQueue}.
+ * Suitable for development, testing, or small-scale applications where persistence is not required.
+ *
+ * @example
+ * ```typescript
+ * const dlq = new MemoryDeadLetterQueue();
+ * await dlq.enqueue(failedEvent);
+ * const size = await dlq.size();
+ * ```
+ */
+export declare class MemoryDeadLetterQueue implements DeadLetterQueue {
+    private queue;
+    /**
+     * Stores the event in an internal Map.
+     * Generates a UUID if the event does not have an ID.
+     */
+    enqueue(event: DeadLetterEvent): Promise<string>;
+    /**
+     * Returns events sorted by failure timestamp.
+     */
+    peek(limit?: number): Promise<DeadLetterEvent[]>;
+    /**
+     * Removes the event from the internal Map.
+     */
+    dequeue(id: string): Promise<void>;
+    /**
+     * Returns the number of items in the internal Map.
+     */
+    size(): Promise<number>;
+    /**
+     * Clears the internal Map.
+     */
+    clear(): Promise<void>;
+}

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

@@ -0,0 +1,2 @@
+export * from './DeadLetterQueue';
+export * from './MemoryDeadLetterQueue';

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

@@ -1,48 +1,64 @@
 /**
- * @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 { 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';
+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';

package/dist/echo/src/middleware/RequestBufferMiddleware.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Request Buffer Middleware
+ *
+ * 在驗證前緩存原始 Request Body，防止框架自動解析 JSON 導致簽章驗證失敗。
+ * 這個中介軟體會在請求處理鏈的早期階段攔截並緩存原始內容。
+ *
+ * @module @gravito/echo/middleware
+ * @since v1.1
+ */
+import type { GravitoContext } from '@gravito/core';
+import type { BufferedRequest, RequestBufferConfig } from '../types';
+/**
+ * Request Buffer 中介軟體類別
+ *
+ * 提供原始 Body 緩存功能，確保簽章驗證使用正確的未解析內容。
+ *
+ * @example
+ * ```typescript
+ * const middleware = new RequestBufferMiddleware({
+ *   maxBodySize: 5 * 1024 * 1024, // 5MB
+ * })
+ *
+ * core.adapter.use('*', middleware.handler())
+ * ```
+ */
+export declare class RequestBufferMiddleware {
+    private config;
+    constructor(config?: RequestBufferConfig);
+    /**
+     * 建立中介軟體處理函式
+     *
+     * @returns 中介軟體處理函式
+     */
+    handler(): (c: GravitoContext, next: () => Promise<Response | undefined>) => Promise<Response | undefined>;
+    /**
+     * 從請求中讀取原始 body
+     *
+     * @param c - Gravito Context
+     * @returns 原始 body（string 或 Buffer）
+     */
+    private readRawBody;
+}
+/**
+ * 便捷工廠函式，用於建立 Request Buffer 中介軟體
+ *
+ * @param config - 中介軟體配置
+ * @returns 中介軟體處理函式
+ *
+ * @example
+ * ```typescript
+ * core.adapter.use('*', createRequestBufferMiddleware({
+ *   maxBodySize: 5 * 1024 * 1024
+ * }))
+ * ```
+ */
+export declare function createRequestBufferMiddleware(config?: RequestBufferConfig): (c: GravitoContext, next: () => Promise<Response | undefined>) => Promise<Response | undefined>;
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Buffered request for signature verification */
+        bufferedRequest?: BufferedRequest;
+    }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Echo Middleware
+ *
+ * @module @gravito/echo/middleware
+ * @since v1.1
+ */
+export type { BufferedRequest, RequestBufferConfig } from '../types';
+export { createRequestBufferMiddleware, RequestBufferMiddleware } from './RequestBufferMiddleware';

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

@@ -0,0 +1,3 @@
+export * from './logging';
+export * from './metrics';
+export * from './tracing';

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>;
+}