@gravito/echo 3.0.1 → 3.1.0

package/dist/core/src/reliability/RetryPolicy.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @gravito/core - Retry Policy
+ *
+ * 重試策略和退避算法的實現
+ * 支持指數和線性退避，包含 Jitter 防止雷鳴羊群
+ */
+/**
+ * 重試策略配置接口
+ *
+ * @example
+ * ```typescript
+ * const policy: RetryPolicy = {
+ *   maxRetries: 3,
+ *   backoff: 'exponential',
+ *   initialDelayMs: 1000,
+ *   maxDelayMs: 30000,
+ *   dlqAfterMaxRetries: true
+ * }
+ * ```
+ */
+export interface RetryPolicy {
+    /** 最大重試次數 */
+    maxRetries: number;
+    /** 退避策略：指數或線性 */
+    backoff: 'exponential' | 'linear';
+    /** 初始延遲時間（毫秒） */
+    initialDelayMs: number;
+    /** 最大延遲時間（毫秒） */
+    maxDelayMs: number;
+    /** 超過最大重試次數後是否發送到死信隊列 */
+    dlqAfterMaxRetries?: boolean;
+}
+/**
+ * 重試引擎
+ *
+ * 負責計算重試延遲、判斷是否應該重試等邏輯
+ *
+ * @example
+ * ```typescript
+ * const engine = new RetryEngine()
+ * const delay = engine.calculateDelay(1, policy)
+ * const shouldRetry = engine.shouldRetry(3, policy)
+ * ```
+ */
+export declare class RetryEngine {
+    /**
+     * 計算下次重試的延遲時間（毫秒）
+     *
+     * @param attemptCount - 當前嘗試次數（從 1 開始）
+     * @param policy - 重試策略配置
+     * @returns 延遲時間（毫秒）
+     *
+     * @description
+     * - 指數退避：delay = initialDelay * 2^(attemptCount - 1)
+     * - 線性退避：delay = initialDelay * attemptCount
+     * - 添加隨機抖動（Jitter），防止雷鳴羊群問題
+     * - 結果不超過 maxDelayMs
+     *
+     * @example
+     * ```typescript
+     * const policy: RetryPolicy = {
+     *   maxRetries: 3,
+     *   backoff: 'exponential',
+     *   initialDelayMs: 1000,
+     *   maxDelayMs: 30000
+     * }
+     *
+     * // 第 1 次重試：1000ms * 2^0 = 1000ms (加抖動)
+     * const delay1 = engine.calculateDelay(1, policy)  // ~1100ms
+     *
+     * // 第 2 次重試：1000ms * 2^1 = 2000ms (加抖動)
+     * const delay2 = engine.calculateDelay(2, policy)  // ~2200ms
+     *
+     * // 第 3 次重試：1000ms * 2^2 = 4000ms (加抖動)
+     * const delay3 = engine.calculateDelay(3, policy)  // ~4400ms
+     * ```
+     */
+    calculateDelay(attemptCount: number, policy: RetryPolicy): number;
+    /**
+     * 判斷是否應該重試
+     *
+     * @param attemptCount - 當前嘗試次數（從 1 開始）
+     * @param policy - 重試策略配置
+     * @returns 是否應該重試
+     *
+     * @description
+     * 當 attemptCount < maxRetries 時返回 true
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, ... }
+     *
+     * engine.shouldRetry(1, policy)  // true（1 < 3）
+     * engine.shouldRetry(3, policy)  // false（3 >= 3）
+     * engine.shouldRetry(4, policy)  // false（4 >= 3）
+     * ```
+     */
+    shouldRetry(attemptCount: number, policy: RetryPolicy): boolean;
+    /**
+     * 獲取退避時間（包含延遲計算和 Jitter）
+     *
+     * @param retryCount - 重試次數（從 0 開始）
+     * @param policy - 重試策略配置
+     * @returns 退避時間（毫秒）
+     *
+     * @description
+     * 這是 calculateDelay 的別名，但接收的是從 0 開始的重試計數
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     *
+     * // 第 0 次重試（第 1 次嘗試失敗）
+     * const time1 = engine.getBackoffTime(0, policy)  // ~1100ms
+     *
+     * // 第 1 次重試（第 2 次嘗試失敗）
+     * const time2 = engine.getBackoffTime(1, policy)  // ~2200ms
+     * ```
+     */
+    getBackoffTime(retryCount: number, policy: RetryPolicy): number;
+    /**
+     * 計算下次重試的絕對時間
+     *
+     * @param retryCount - 重試次數（從 0 開始）
+     * @param policy - 重試策略配置
+     * @param baseTime - 基礎時間戳（默認為當前時間）
+     * @returns 下次重試的時間戳（毫秒）
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     *
+     * const now = Date.now()
+     * const nextRetryTime = engine.getNextRetryTime(0, policy, now)
+     * // 返回大約 now + 1000 + jitter
+     * ```
+     */
+    getNextRetryTime(retryCount: number, policy: RetryPolicy, baseTime?: number): number;
+    /**
+     * 驗證重試策略配置
+     *
+     * @param policy - 重試策略配置
+     * @returns 是否有效
+     *
+     * @description
+     * 檢查配置是否合理：
+     * - maxRetries >= 0
+     * - initialDelayMs > 0
+     * - maxDelayMs >= initialDelayMs
+     *
+     * @example
+     * ```typescript
+     * const validPolicy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     * engine.isValidPolicy(validPolicy)  // true
+     *
+     * const invalidPolicy = { maxRetries: 3, initialDelayMs: 5000, maxDelayMs: 1000, backoff: 'exponential' }
+     * engine.isValidPolicy(invalidPolicy)  // false (maxDelayMs < initialDelayMs)
+     * ```
+     */
+    isValidPolicy(policy: RetryPolicy): boolean;
+    /**
+     * 獲取人類可讀的重試信息
+     *
+     * @param attemptCount - 當前嘗試次數（從 1 開始）
+     * @param policy - 重試策略配置
+     * @returns 描述性文本
+     *
+     * @example
+     * ```typescript
+     * const policy = { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoff: 'exponential' }
+     *
+     * engine.getRetryInfo(1, policy)  // "Retry 1 of 3, will retry in ~1100ms"
+     * engine.getRetryInfo(3, policy)  // "Retry 3 of 3 (final attempt), will retry in ~4400ms"
+     * engine.getRetryInfo(4, policy)  // "Max retries exceeded (4 >= 3)"
+     * ```
+     */
+    getRetryInfo(attemptCount: number, policy: RetryPolicy): string;
+}
+/**
+ * 創建默認的重試策略
+ *
+ * @returns 默認重試策略
+ *
+ * @description
+ * 默認配置：
+ * - 最多重試 3 次
+ * - 指數退避
+ * - 初始延遲 1 秒
+ * - 最大延遲 30 秒
+ * - 超過最大重試後發送 DLQ
+ *
+ * @example
+ * ```typescript
+ * const policy = getDefaultRetryPolicy()
+ * // { maxRetries: 3, backoff: 'exponential', initialDelayMs: 1000, maxDelayMs: 30000, dlqAfterMaxRetries: true }
+ * ```
+ */
+export declare function getDefaultRetryPolicy(): RetryPolicy;
+/**
+ * 為不同類型的操作獲取預設的重試策略
+ *
+ * @param type - 操作類型
+ * @returns 推薦的重試策略
+ *
+ * @example
+ * ```typescript
+ * // 外部 API 調用：更多重試，更長延遲
+ * const apiPolicy = getPresetRetryPolicy('external-api')
+ *
+ * // 數據庫操作：較少重試，短延遲
+ * const dbPolicy = getPresetRetryPolicy('database')
+ *
+ * // 消息隊列：適中重試
+ * const mqPolicy = getPresetRetryPolicy('message-queue')
+ * ```
+ */
+export declare function getPresetRetryPolicy(type: 'external-api' | 'database' | 'message-queue' | 'default'): RetryPolicy;

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

@@ -0,0 +1,6 @@
+/**
+ * Reliability and retry exports.
+ * @packageDocumentation
+ */
+export { DeadLetterQueueManager, type DLQManagerFilter, type DLQRecord, type DLQStats, } from './DeadLetterQueueManager';
+export { getDefaultRetryPolicy, getPresetRetryPolicy, RetryEngine, type RetryPolicy, } from './RetryPolicy';

package/dist/core/src/router/ControllerDispatcher.d.ts

@@ -0,0 +1,12 @@
+import type { GravitoHandler } from '../http/types';
+import type { PlanetCore } from '../PlanetCore';
+import type { ControllerClass } from '../Router';
+export declare class ControllerDispatcher {
+    private core;
+    private controllers;
+    constructor(core: PlanetCore);
+    /**
+     * Resolve Controller Instance and Method
+     */
+    resolve(CtrlClass: ControllerClass, methodName: string): GravitoHandler;
+}

package/dist/core/src/router/RequestValidator.d.ts

@@ -0,0 +1,20 @@
+import type { GravitoMiddleware } from '../http/types';
+import { type FormRequestClass } from '../Router';
+/**
+ * Handles validation of incoming requests using FormRequest classes.
+ * Provides mechanisms to detect and convert FormRequest classes into Gravito middleware.
+ */
+export declare class RequestValidator {
+    /**
+     * Check if a value is a FormRequest class.
+     * Optimized with Symbol check, prototype check, and caching.
+     * @internal
+     */
+    static isFormRequestClass(value: unknown): value is FormRequestClass;
+    /**
+     * Convert a FormRequest class to middleware.
+     * Uses instance caching to avoid re-instantiation on every request.
+     * @internal
+     */
+    static formRequestToMiddleware(RequestClass: FormRequestClass): GravitoMiddleware;
+}

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';