@gravito/echo 3.0.0 → 3.1.0

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

@@ -0,0 +1,182 @@
+/**
+ * @gravito/core - OpenTelemetry 類型定義
+ *
+ * 定義 OpenTelemetry SDK 集成所需的類型與介面。
+ */
+/**
+ * Tracing（追蹤）導出器類型
+ */
+export type TracingExporter = 'jaeger' | 'otlp' | 'console' | 'none';
+/**
+ * Metrics（指標）導出器類型
+ */
+export type MetricsExporter = 'prometheus' | 'otlp' | 'console' | 'none';
+/**
+ * Tracing 配置選項
+ */
+export interface TracingConfig {
+    /** 是否啟用追蹤（預設：true） */
+    enabled?: boolean;
+    /** 導出器類型（預設：otlp） */
+    exporter?: TracingExporter;
+    /** Jaeger HTTP 端點（使用 jaeger 導出器時） */
+    jaegerEndpoint?: string;
+    /** OTLP 端點（使用 otlp 導出器時） */
+    otlpEndpoint?: string;
+    /** 採樣率（0-1，預設：1.0 = 100%） */
+    samplingRate?: number;
+    /** 是否啟用自動儀器化（預設：false） */
+    autoInstrumentation?: boolean;
+    /** Batch Span Processor 配置 */
+    batchConfig?: {
+        /** 最大批次大小（預設：512） */
+        maxExportBatchSize?: number;
+        /** 導出間隔（毫秒，預設：5000） */
+        scheduledDelayMillis?: number;
+        /** 導出超時（毫秒，預設：30000） */
+        exportTimeoutMillis?: number;
+        /** 最大隊列大小（預設：2048） */
+        maxQueueSize?: number;
+    };
+}
+/**
+ * Metrics 配置選項
+ */
+export interface MetricsConfig {
+    /** 是否啟用指標（預設：true） */
+    enabled?: boolean;
+    /** 導出器類型（預設：otlp） */
+    exporter?: MetricsExporter;
+    /** Prometheus 端口（使用 prometheus 導出器時，預設：9090） */
+    prometheusPort?: number;
+    /** Prometheus 端點路徑（預設：/metrics） */
+    prometheusEndpoint?: string;
+    /** OTLP 端點（使用 otlp 導出器時） */
+    otlpEndpoint?: string;
+    /** 導出間隔（毫秒，預設：60000） */
+    exportIntervalMillis?: number;
+}
+/**
+ * OpenTelemetry SDK 完整配置
+ */
+export interface OpenTelemetryConfig {
+    /** 是否啟用 OpenTelemetry（預設：true） */
+    enabled?: boolean;
+    /** 服務名稱（預設：gravito-app） */
+    serviceName?: string;
+    /** 服務版本（預設：1.0.0） */
+    serviceVersion?: string;
+    /** 環境名稱（預設：development） */
+    environment?: 'development' | 'staging' | 'production' | string;
+    /** 自定義 Resource Attributes */
+    resourceAttributes?: Record<string, string | number | boolean>;
+    /** Tracing 配置 */
+    tracing?: TracingConfig;
+    /** Metrics 配置 */
+    metrics?: MetricsConfig;
+    /** 是否在控制台輸出初始化日誌（預設：true） */
+    logInitialization?: boolean;
+}
+/**
+ * OpenTelemetry SDK 實例包裝
+ *
+ * 封裝初始化後的 SDK 實例與相關資源。
+ */
+export interface OpenTelemetrySDK {
+    /** SDK 是否已啟動 */
+    isStarted: boolean;
+    /** SDK 是否已關閉 */
+    isShutdown: boolean;
+    /** 服務名稱 */
+    serviceName: string;
+    /** 服務版本 */
+    serviceVersion: string;
+    /** Tracer Provider（如果啟用追蹤） */
+    tracerProvider: unknown | null;
+    /** Meter Provider（如果啟用指標） */
+    meterProvider: unknown | null;
+    /** 原始配置 */
+    config: OpenTelemetryConfig;
+    /** 關閉 SDK */
+    shutdown: () => Promise<void>;
+}
+/**
+ * 支援的 OpenTelemetry 環境變數
+ *
+ * 參考：https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
+ */
+export declare const OTEL_ENV_VARS: {
+    /** 服務名稱 */
+    readonly SERVICE_NAME: "OTEL_SERVICE_NAME";
+    /** 服務版本 */
+    readonly SERVICE_VERSION: "OTEL_SERVICE_VERSION";
+    /** 環境名稱 */
+    readonly DEPLOYMENT_ENVIRONMENT: "OTEL_DEPLOYMENT_ENVIRONMENT";
+    /** Resource Attributes */
+    readonly RESOURCE_ATTRIBUTES: "OTEL_RESOURCE_ATTRIBUTES";
+    /** OTLP 端點（通用） */
+    readonly OTLP_ENDPOINT: "OTEL_EXPORTER_OTLP_ENDPOINT";
+    /** OTLP Traces 端點 */
+    readonly OTLP_TRACES_ENDPOINT: "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";
+    /** OTLP Metrics 端點 */
+    readonly OTLP_METRICS_ENDPOINT: "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT";
+    /** 採樣器類型 */
+    readonly TRACES_SAMPLER: "OTEL_TRACES_SAMPLER";
+    /** 採樣率參數 */
+    readonly TRACES_SAMPLER_ARG: "OTEL_TRACES_SAMPLER_ARG";
+    /** 是否啟用 OpenTelemetry */
+    readonly GRAVITO_ENABLED: "GRAVITO_OTEL_ENABLED";
+    /** Jaeger 端點 */
+    readonly JAEGER_ENDPOINT: "JAEGER_ENDPOINT";
+    /** Prometheus 端口 */
+    readonly PROMETHEUS_PORT: "PROMETHEUS_PORT";
+};
+/**
+ * 完整的 BatchConfig 類型（所有屬性必填）
+ */
+export interface BatchConfigRequired {
+    maxExportBatchSize: number;
+    scheduledDelayMillis: number;
+    exportTimeoutMillis: number;
+    maxQueueSize: number;
+}
+/**
+ * 完整的 TracingConfig 類型（所有屬性必填）
+ */
+export interface TracingConfigRequired {
+    enabled: boolean;
+    exporter: TracingExporter;
+    jaegerEndpoint: string;
+    otlpEndpoint: string;
+    samplingRate: number;
+    autoInstrumentation: boolean;
+    batchConfig: BatchConfigRequired;
+}
+/**
+ * 完整的 MetricsConfig 類型（所有屬性必填）
+ */
+export interface MetricsConfigRequired {
+    enabled: boolean;
+    exporter: MetricsExporter;
+    prometheusPort: number;
+    prometheusEndpoint: string;
+    otlpEndpoint: string;
+    exportIntervalMillis: number;
+}
+/**
+ * 完整的 OpenTelemetryConfig 類型（所有屬性必填）
+ */
+export interface OpenTelemetryConfigRequired {
+    enabled: boolean;
+    serviceName: string;
+    serviceVersion: string;
+    environment: 'development' | 'staging' | 'production';
+    resourceAttributes: Record<string, string | number | boolean>;
+    tracing: TracingConfigRequired;
+    metrics: MetricsConfigRequired;
+    logInitialization: boolean;
+}
+/**
+ * 預設配置值
+ */
+export declare const DEFAULT_CONFIG: OpenTelemetryConfigRequired;

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

@@ -0,0 +1,316 @@
+/**
+ * @gravito/core - Dead Letter Queue Manager
+ *
+ * 管理失敗事件的持久化存儲
+ * 支持 CRUD、重新入隊、批量重試和統計功能
+ */
+import type { ConnectionContract } from '@gravito/atlas';
+import type { EventOptions } from '../events/EventOptions';
+import type { RetryPolicy } from './RetryPolicy';
+/**
+ * DLQ 事件的數據庫記錄
+ */
+export interface DLQRecord {
+    id: number;
+    dlq_id: string;
+    event_name: string;
+    event_payload: unknown;
+    event_options: unknown;
+    attempt_count: number;
+    max_retries: number;
+    next_retry_at: string | null;
+    last_error: unknown;
+    status: 'pending' | 'requeued' | 'resolved' | 'abandoned';
+    resolution_notes: string | null;
+    failed_at: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * DLQ 事件查詢過濾選項（for DeadLetterQueueManager）
+ */
+export interface DLQManagerFilter {
+    /** 按事件名稱篩選 */
+    eventName?: string;
+    /** 按狀態篩選 */
+    status?: 'pending' | 'requeued' | 'resolved' | 'abandoned';
+    /** 開始時間 */
+    from?: Date;
+    /** 結束時間 */
+    to?: Date;
+    /** 結果數量限制 */
+    limit?: number;
+    /** 分頁偏移 */
+    offset?: number;
+}
+/**
+ * DLQ 統計信息
+ */
+export interface DLQStats {
+    /** 事件總數 */
+    total: number;
+    /** 按事件名稱的統計 */
+    byEvent: Record<string, number>;
+    /** 按狀態的統計 */
+    byStatus: Record<string, number>;
+}
+/**
+ * Dead Letter Queue 管理器
+ *
+ * 負責管理失敗事件的持久化存儲，支持：
+ * - 自動將失敗事件移至 DLQ
+ * - 查詢和篩選 DLQ 事件
+ * - 重新入隊單個或批量事件
+ * - 標記事件為已解決或已放棄
+ * - 查看統計信息
+ *
+ * @example
+ * ```typescript
+ * const db = container.make('db') as ConnectionContract
+ * const dlqManager = new DeadLetterQueueManager(db)
+ *
+ * // 將失敗事件移至 DLQ
+ * const dlqId = await dlqManager.moveToDlq(
+ *   'order:created',
+ *   { orderId: '123' },
+ *   { retry: {...} },
+ *   error,
+ *   3
+ * )
+ *
+ * // 查詢 DLQ 事件
+ * const events = await dlqManager.list({ event: 'order:created', status: 'pending' })
+ *
+ * // 重新入隊
+ * await dlqManager.requeue(dlqId)
+ *
+ * // 批量重試
+ * const result = await dlqManager.retryBatch({ eventName: 'order:created' })
+ *
+ * // 統計
+ * const stats = await dlqManager.getStats()
+ * ```
+ */
+export declare class DeadLetterQueueManager {
+    private db;
+    private retryEngine;
+    constructor(db: ConnectionContract);
+    /**
+     * 將失敗事件移至死信隊列
+     *
+     * @param eventName - 事件名稱
+     * @param payload - 事件負載
+     * @param options - 事件選項
+     * @param error - 導致失敗的錯誤
+     * @param attemptCount - 當前嘗試次數
+     * @param retryPolicy - 重試策略配置
+     * @returns DLQ 記錄的 UUID
+     *
+     * @example
+     * ```typescript
+     * const dlqId = await dlqManager.moveToDlq(
+     *   'order:created',
+     *   { orderId: 'ORD-123' },
+     *   { retry: { maxRetries: 3, backoff: 'exponential' } },
+     *   new Error('Service unavailable'),
+     *   3,
+     *   { maxRetries: 3, backoff: 'exponential', initialDelayMs: 1000, maxDelayMs: 30000 }
+     * )
+     * ```
+     */
+    moveToDlq(eventName: string, payload: unknown, options: EventOptions, error: Error, attemptCount: number, retryPolicy?: RetryPolicy): Promise<string>;
+    /**
+     * 按 DLQ ID 獲取單個事件
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @returns DLQ 記錄，若不存在則返回 undefined
+     *
+     * @example
+     * ```typescript
+     * const event = await dlqManager.getById('550e8400-e29b-41d4-a716-446655440000')
+     * if (event) {
+     *   console.log(event.event_name, event.status)
+     * }
+     * ```
+     */
+    getById(dlqId: string): Promise<DLQRecord | undefined>;
+    /**
+     * 查詢 DLQ 事件
+     *
+     * @param filter - 查詢過濾條件
+     * @returns DLQ 記錄列表（按失敗時間倒序）
+     *
+     * @example
+     * ```typescript
+     * // 查詢特定事件的待處理事件
+     * const events = await dlqManager.list({
+     *   eventName: 'order:created',
+     *   status: 'pending',
+     *   limit: 50
+     * })
+     *
+     * // 查詢時間範圍內的所有失敗事件
+     * const eventsInRange = await dlqManager.list({
+     *   from: new Date('2026-02-01'),
+     *   to: new Date('2026-02-03'),
+     *   limit: 100
+     * })
+     * ```
+     */
+    list(filter?: DLQManagerFilter): Promise<DLQRecord[]>;
+    /**
+     * 重新入隊單個 DLQ 事件
+     *
+     * 重新入隊不會自動派發事件，而是標記狀態為 'requeued'
+     * 實際的事件派發應由調用者負責處理
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @throws 如果事件不存在
+     *
+     * @example
+     * ```typescript
+     * const event = await dlqManager.getById(dlqId)
+     * if (event) {
+     *   // 由調用者決定如何派發事件
+     *   await eventSystem.doActionAsync(
+     *     event.event_name,
+     *     event.event_payload,
+     *     event.event_options
+     *   )
+     *
+     *   // 標記為已重新入隊
+     *   await dlqManager.requeue(dlqId)
+     * }
+     * ```
+     */
+    requeue(dlqId: string): Promise<void>;
+    /**
+     * 批量重新入隊 DLQ 事件
+     *
+     * @param filter - 查詢過濾條件
+     * @returns 包含處理結果的統計對象
+     *
+     * @example
+     * ```typescript
+     * const result = await dlqManager.retryBatch({
+     *   eventName: 'order:created',
+     *   status: 'pending'
+     * })
+     *
+     * console.log(`Success: ${result.succeeded}, Failed: ${result.failed}`)
+     * ```
+     */
+    retryBatch(filter?: DLQManagerFilter): Promise<{
+        total: number;
+        succeeded: number;
+        failed: number;
+    }>;
+    /**
+     * 標記 DLQ 事件為已解決
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @param notes - 解決說明
+     *
+     * @example
+     * ```typescript
+     * await dlqManager.resolve(dlqId, 'Manual fix applied: Database issue resolved')
+     * ```
+     */
+    resolve(dlqId: string, notes?: string): Promise<void>;
+    /**
+     * 放棄 DLQ 事件（不再重試）
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @param reason - 放棄原因
+     *
+     * @example
+     * ```typescript
+     * await dlqManager.abandon(dlqId, 'Data corrupted, cannot recover')
+     * ```
+     */
+    abandon(dlqId: string, reason?: string): Promise<void>;
+    /**
+     * 更新 DLQ 事件狀態
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @param status - 新狀態
+     * @param notes - 狀態變更說明
+     * @throws 如果事件不存在
+     *
+     * @internal
+     */
+    updateStatus(dlqId: string, status: 'pending' | 'requeued' | 'resolved' | 'abandoned', notes?: string): Promise<void>;
+    /**
+     * 刪除單個 DLQ 事件
+     *
+     * @param dlqId - DLQ 事件的 UUID
+     * @returns true 如果刪除成功，false 如果事件不存在
+     *
+     * @example
+     * ```typescript
+     * const deleted = await dlqManager.deleteEntry(dlqId)
+     * if (deleted) {
+     *   console.log('Event deleted')
+     * }
+     * ```
+     */
+    deleteEntry(dlqId: string): Promise<boolean>;
+    /**
+     * 刪除多個 DLQ 事件
+     *
+     * @param dlqIds - DLQ 事件 UUID 列表
+     * @returns 刪除的事件數量
+     *
+     * @example
+     * ```typescript
+     * const deletedCount = await dlqManager.deleteEntries([id1, id2, id3])
+     * ```
+     */
+    deleteEntries(dlqIds: string[]): Promise<number>;
+    /**
+     * 獲取 DLQ 統計信息
+     *
+     * @returns 包含總數、按事件名稱和狀態的統計信息
+     *
+     * @example
+     * ```typescript
+     * const stats = await dlqManager.getStats()
+     *
+     * console.log(`Total events: ${stats.total}`)
+     * console.log('By event:', stats.byEvent)
+     * // Output: { 'order:created': 145, 'payment:succeeded': 23 }
+     *
+     * console.log('By status:', stats.byStatus)
+     * // Output: { pending: 120, requeued: 15, resolved: 8, abandoned: 2 }
+     * ```
+     */
+    getStats(): Promise<DLQStats>;
+    /**
+     * 獲取某個事件名稱的 DLQ 事件數
+     *
+     * @param eventName - 事件名稱
+     * @returns 事件數量
+     *
+     * @example
+     * ```typescript
+     * const count = await dlqManager.getCountByEvent('order:created')
+     * ```
+     */
+    getCountByEvent(eventName: string): Promise<number>;
+    /**
+     * 清空所有 DLQ 事件（慎用！）
+     *
+     * @param includeResolved - 是否包含已解決的事件
+     * @returns 清空的事件數量
+     *
+     * @example
+     * ```typescript
+     * // 只清空待處理的事件
+     * const count = await dlqManager.clear(false)
+     *
+     * // 清空所有事件（包括已解決和已放棄）
+     * const countAll = await dlqManager.clear(true)
+     * ```
+     */
+    clear(includeResolved?: boolean): Promise<number>;
+}

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;