@gravito/echo 3.0.0 → 3.1.0

package/dist/index.js

@@ -1,4 +1,205 @@
 // @bun
+// src/dlq/MemoryDeadLetterQueue.ts
+class MemoryDeadLetterQueue {
+  queue = new Map;
+  async enqueue(event) {
+    const id = event.id ?? crypto.randomUUID();
+    this.queue.set(id, { ...event, id });
+    return id;
+  }
+  async peek(limit = 10) {
+    return Array.from(this.queue.values()).sort((a, b) => a.failedAt.getTime() - b.failedAt.getTime()).slice(0, limit);
+  }
+  async dequeue(id) {
+    this.queue.delete(id);
+  }
+  async size() {
+    return this.queue.size;
+  }
+  async clear() {
+    this.queue.clear();
+  }
+}
+// src/middleware/RequestBufferMiddleware.ts
+var DEFAULT_CONFIG = {
+  enabled: true,
+  maxBodySize: 10 * 1024 * 1024,
+  skipContentTypes: ["multipart/form-data", "application/octet-stream"]
+};
+
+class RequestBufferMiddleware {
+  config;
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+  handler() {
+    return async (c, next) => {
+      if (!this.config.enabled) {
+        return await next();
+      }
+      const contentType = c.req.header("content-type") ?? "";
+      if (this.config.skipContentTypes.some((type) => contentType.includes(type))) {
+        return await next();
+      }
+      const rawBody = await this.readRawBody(c);
+      const bodySize = typeof rawBody === "string" ? Buffer.byteLength(rawBody, "utf-8") : rawBody.length;
+      if (bodySize > this.config.maxBodySize) {
+        return c.json({ error: "Request body too large" }, 413);
+      }
+      const buffered = {
+        rawBody,
+        headers: c.req.header(),
+        bufferedAt: new Date
+      };
+      c.set("bufferedRequest", buffered);
+      return await next();
+    };
+  }
+  async readRawBody(c) {
+    const existing = c.get("bufferedRequest");
+    if (existing) {
+      return existing.rawBody;
+    }
+    const body = await c.req.text();
+    return body;
+  }
+}
+function createRequestBufferMiddleware(config) {
+  return new RequestBufferMiddleware(config).handler();
+}
+// src/observability/logging/ConsoleEchoLogger.ts
+class ConsoleEchoLogger {
+  formatContext(base, extra) {
+    return {
+      module: "echo",
+      timestamp: new Date().toISOString(),
+      ...base,
+      ...extra
+    };
+  }
+  debug(message, context) {
+    console.debug(JSON.stringify({
+      level: "debug",
+      message,
+      ...this.formatContext({}, context)
+    }));
+  }
+  info(message, context) {
+    console.info(JSON.stringify({
+      level: "info",
+      message,
+      ...this.formatContext({}, context)
+    }));
+  }
+  warn(message, context) {
+    console.warn(JSON.stringify({
+      level: "warn",
+      message,
+      ...this.formatContext({}, context)
+    }));
+  }
+  error(message, context) {
+    console.error(JSON.stringify({
+      level: "error",
+      message,
+      ...this.formatContext({}, context)
+    }));
+  }
+}
+// src/observability/metrics/MetricsProvider.ts
+var EchoMetrics = {
+  INCOMING_TOTAL: "echo_incoming_webhooks_total",
+  INCOMING_DURATION: "echo_incoming_duration_seconds",
+  INCOMING_VERIFICATION_FAILURES: "echo_incoming_verification_failures_total",
+  OUTGOING_TOTAL: "echo_outgoing_webhooks_total",
+  OUTGOING_DURATION: "echo_outgoing_duration_seconds",
+  OUTGOING_RETRIES: "echo_outgoing_retries_total",
+  OUTGOING_FAILURES: "echo_outgoing_failures_total",
+  DLQ_SIZE: "echo_dlq_size",
+  DLQ_ENQUEUED: "echo_dlq_enqueued_total",
+  DLQ_PROCESSED: "echo_dlq_processed_total"
+};
+// src/observability/metrics/NoopMetricsProvider.ts
+class NoopMetricsProvider {
+  increment() {}
+  histogram() {}
+  gauge() {}
+}
+// src/observability/metrics/PrometheusMetricsProvider.ts
+class PrometheusMetricsProvider {
+  counters = new Map;
+  histograms = new Map;
+  gauges = new Map;
+  increment(name, labels = {}) {
+    const key = this.buildKey(name, labels);
+    const counterMap = this.counters.get(name) ?? new Map;
+    counterMap.set(key, (counterMap.get(key) ?? 0) + 1);
+    this.counters.set(name, counterMap);
+  }
+  histogram(name, value, labels = {}) {
+    const key = this.buildKey(name, labels);
+    const values = this.histograms.get(key) ?? [];
+    values.push(value);
+    this.histograms.set(key, values);
+  }
+  gauge(name, value, labels = {}) {
+    const key = this.buildKey(name, labels);
+    this.gauges.set(key, value);
+  }
+  export() {
+    const lines = [];
+    for (const [name, counterMap] of this.counters) {
+      lines.push(`# TYPE ${name} counter`);
+      for (const [key, value] of counterMap) {
+        lines.push(`${key} ${value}`);
+      }
+    }
+    for (const [key, value] of this.gauges) {
+      lines.push(`${key} ${value}`);
+    }
+    return lines.join(`
+`);
+  }
+  buildKey(name, labels) {
+    if (Object.keys(labels).length === 0) {
+      return name;
+    }
+    const labelStr = Object.entries(labels).map(([k, v]) => `${k}="${v}"`).join(",");
+    return `${name}{${labelStr}}`;
+  }
+}
+// src/observability/tracing/NoopTracer.ts
+class NoopSpan {
+  setAttribute() {
+    return this;
+  }
+  setAttributes() {
+    return this;
+  }
+  addEvent() {
+    return this;
+  }
+  setStatus() {
+    return this;
+  }
+  end() {}
+}
+
+class NoopTracer {
+  startSpan() {
+    return new NoopSpan;
+  }
+  async withSpan(_name, fn) {
+    return fn(new NoopSpan);
+  }
+}
+// src/observability/tracing/Tracer.ts
+var SpanStatusCode;
+((SpanStatusCode2) => {
+  SpanStatusCode2[SpanStatusCode2["UNSET"] = 0] = "UNSET";
+  SpanStatusCode2[SpanStatusCode2["OK"] = 1] = "OK";
+  SpanStatusCode2[SpanStatusCode2["ERROR"] = 2] = "ERROR";
+})(SpanStatusCode ||= {});
 // src/receive/SignatureValidator.ts
 async function computeHmacSha256(payload, secret) {
   const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
@@ -6,12 +207,24 @@ async function computeHmacSha256(payload, secret) {
   const signature = await crypto.subtle.sign("HMAC", key, payloadBuffer);
   return Buffer.from(signature).toString("hex");
 }
+async function computeHmacSha256Base64(payload, secret) {
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const payloadBuffer = typeof payload === "string" ? new TextEncoder().encode(payload) : new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength);
+  const signature = await crypto.subtle.sign("HMAC", key, payloadBuffer);
+  return Buffer.from(signature).toString("base64");
+}
 async function computeHmacSha1(payload, secret) {
   const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"]);
   const payloadBuffer = typeof payload === "string" ? new TextEncoder().encode(payload) : new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength);
   const signature = await crypto.subtle.sign("HMAC", key, payloadBuffer);
   return Buffer.from(signature).toString("hex");
 }
+async function computeHmacSha1Base64(payload, secret) {
+  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-1" }, false, ["sign"]);
+  const payloadBuffer = typeof payload === "string" ? new TextEncoder().encode(payload) : new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength);
+  const signature = await crypto.subtle.sign("HMAC", key, payloadBuffer);
+  return Buffer.from(signature).toString("base64");
+}
 function timingSafeEqual(a, b) {
   if (a.length !== b.length) {
     return false;
@@ -46,106 +259,117 @@ function parseStripeSignature(header) {
   return { timestamp, signatures };
 }
 
+// src/providers/base/HeaderUtils.ts
+function getHeader(headers, name) {
+  const value = headers[name] ?? headers[name.toLowerCase()];
+  return Array.isArray(value) ? value[0] : value;
+}
+function hasHeader(headers, name) {
+  return getHeader(headers, name) !== undefined;
+}
+
+// src/providers/base/BaseProvider.ts
+class BaseProvider {
+  tolerance;
+  constructor(options = {}) {
+    this.tolerance = options.tolerance ?? 300;
+  }
+  getHeader(headers, name) {
+    return getHeader(headers, name);
+  }
+  hasHeader(headers, name) {
+    return hasHeader(headers, name);
+  }
+  createFailure(error) {
+    return { valid: false, error };
+  }
+  createSuccess(payload, options = {}) {
+    return {
+      valid: true,
+      payload,
+      eventType: options.eventType,
+      webhookId: options.webhookId
+    };
+  }
+  payloadToString(payload) {
+    return typeof payload === "string" ? payload : payload.toString("utf-8");
+  }
+  safeParseJson(str) {
+    try {
+      return { success: true, data: JSON.parse(str) };
+    } catch {
+      return { success: false, error: "Failed to parse webhook payload" };
+    }
+  }
+}
+
 // src/providers/GenericProvider.ts
-class GenericProvider {
+class GenericProvider extends BaseProvider {
   name = "generic";
   signatureHeader;
   timestampHeader;
-  tolerance;
   constructor(options = {}) {
+    super(options);
     this.signatureHeader = options.signatureHeader ?? "x-webhook-signature";
     this.timestampHeader = options.timestampHeader ?? "x-webhook-timestamp";
-    this.tolerance = options.tolerance ?? 300;
   }
   async verify(payload, headers, secret) {
     const signature = this.getHeader(headers, this.signatureHeader);
     if (!signature) {
-      return {
-        valid: false,
-        error: `Missing signature header: ${this.signatureHeader}`
-      };
+      return this.createFailure(`Missing signature header: ${this.signatureHeader}`);
     }
     const timestampStr = this.getHeader(headers, this.timestampHeader);
     if (timestampStr) {
       const timestamp = parseInt(timestampStr, 10);
       if (Number.isNaN(timestamp) || !validateTimestamp(timestamp, this.tolerance)) {
-        return {
-          valid: false,
-          error: "Timestamp validation failed"
-        };
+        return this.createFailure("Timestamp validation failed");
       }
     }
-    const payloadStr = typeof payload === "string" ? payload : payload.toString("utf-8");
+    const payloadStr = this.payloadToString(payload);
     const expectedSignature = await computeHmacSha256(payloadStr, secret);
     if (!timingSafeEqual(signature.toLowerCase(), expectedSignature.toLowerCase())) {
-      return {
-        valid: false,
-        error: "Signature verification failed"
-      };
+      return this.createFailure("Signature verification failed");
     }
-    try {
-      const parsed = JSON.parse(payloadStr);
-      return {
-        valid: true,
-        payload: parsed,
-        eventType: parsed.type ?? parsed.event ?? parsed.eventType,
-        webhookId: parsed.id ?? parsed.webhookId
-      };
-    } catch {
-      return {
-        valid: true,
-        payload: payloadStr
-      };
+    const parseResult = this.safeParseJson(payloadStr);
+    if (!parseResult.success) {
+      return this.createSuccess(payloadStr);
     }
-  }
-  getHeader(headers, name) {
-    const value = headers[name] ?? headers[name.toLowerCase()];
-    return Array.isArray(value) ? value[0] : value;
+    const parsed = parseResult.data;
+    return this.createSuccess(parsed, {
+      eventType: parsed.type ?? parsed.event ?? parsed.eventType,
+      webhookId: parsed.id ?? parsed.webhookId
+    });
   }
 }
 
 // src/providers/GitHubProvider.ts
-class GitHubProvider {
+class GitHubProvider extends BaseProvider {
   name = "github";
   async verify(payload, headers, secret) {
     const signature = this.getHeader(headers, "x-hub-signature-256");
     if (!signature) {
-      return {
-        valid: false,
-        error: "Missing X-Hub-Signature-256 header"
-      };
+      return this.createFailure("Missing X-Hub-Signature-256 header");
     }
     if (!signature.startsWith("sha256=")) {
-      return {
-        valid: false,
-        error: "Invalid signature format (expected sha256=...)"
-      };
+      return this.createFailure("Invalid signature format (expected sha256=...)");
     }
     const signatureValue = signature.slice(7);
-    const payloadStr = typeof payload === "string" ? payload : payload.toString("utf-8");
+    const payloadStr = this.payloadToString(payload);
     const expectedSignature = await computeHmacSha256(payloadStr, secret);
     if (!timingSafeEqual(signatureValue.toLowerCase(), expectedSignature.toLowerCase())) {
-      return {
-        valid: false,
-        error: "Signature verification failed"
-      };
+      return this.createFailure("Signature verification failed");
     }
-    try {
-      const event = JSON.parse(payloadStr);
-      const eventType = this.getHeader(headers, "x-github-event");
-      const deliveryId = this.getHeader(headers, "x-github-delivery");
-      return {
-        valid: true,
-        payload: event,
-        eventType: eventType ?? undefined,
-        webhookId: deliveryId ?? undefined
-      };
-    } catch {
-      return {
-        valid: false,
-        error: "Failed to parse webhook payload"
-      };
+    const parseResult = this.safeParseJson(payloadStr);
+    if (!parseResult.success) {
+      return this.createFailure("Failed to parse webhook payload");
     }
+    const event = parseResult.data;
+    const eventType = this.getHeader(headers, "x-github-event");
+    const deliveryId = this.getHeader(headers, "x-github-delivery");
+    return this.createSuccess(event, {
+      eventType: eventType ?? undefined,
+      webhookId: deliveryId ?? undefined
+    });
   }
   parseEventType(payload) {
     if (typeof payload === "object" && payload !== null && "action" in payload) {
@@ -153,65 +377,180 @@ class GitHubProvider {
     }
     return;
   }
-  getHeader(headers, name) {
-    const value = headers[name] ?? headers[name.toLowerCase()];
-    return Array.isArray(value) ? value[0] : value;
+}
+
+// src/providers/LinearProvider.ts
+class LinearProvider extends BaseProvider {
+  name = "linear";
+  async verify(payload, headers, secret) {
+    const signature = this.getHeader(headers, "linear-signature");
+    if (!signature) {
+      return this.createFailure("Missing Linear-Signature header");
+    }
+    const payloadStr = this.payloadToString(payload);
+    const expectedSignature = await computeHmacSha256(payloadStr, secret);
+    if (!timingSafeEqual(signature, expectedSignature)) {
+      return this.createFailure("Signature verification failed");
+    }
+    const parseResult = this.safeParseJson(payloadStr);
+    if (!parseResult.success) {
+      return this.createFailure(parseResult.error);
+    }
+    const data = parseResult.data;
+    return this.createSuccess(data, {
+      eventType: data.type ?? data.action,
+      webhookId: this.getHeader(headers, "linear-delivery")
+    });
+  }
+}
+
+// src/providers/PaddleProvider.ts
+class PaddleProvider extends BaseProvider {
+  name = "paddle";
+  async verify(payload, headers, secret) {
+    const signatureHeader = this.getHeader(headers, "paddle-signature");
+    if (!signatureHeader) {
+      return this.createFailure("Missing Paddle-Signature header");
+    }
+    const parsed = this.parsePaddleSignature(signatureHeader);
+    if (!parsed) {
+      return this.createFailure("Invalid Paddle-Signature format");
+    }
+    const { timestamp, signature } = parsed;
+    if (!validateTimestamp(timestamp, this.tolerance)) {
+      return this.createFailure(`Timestamp outside tolerance window (${this.tolerance}s)`);
+    }
+    const payloadStr = this.payloadToString(payload);
+    const signedPayload = `${timestamp}:${payloadStr}`;
+    const expectedSignature = await computeHmacSha256(signedPayload, secret);
+    if (!timingSafeEqual(signature, expectedSignature)) {
+      return this.createFailure("Signature verification failed");
+    }
+    const parseResult = this.safeParseJson(payloadStr);
+    if (!parseResult.success) {
+      return this.createFailure(parseResult.error);
+    }
+    const data = parseResult.data;
+    return this.createSuccess(data, {
+      eventType: data.event_type,
+      webhookId: data.event_id
+    });
+  }
+  parsePaddleSignature(header) {
+    const parts = header.split(";");
+    let timestamp;
+    let signature;
+    for (const part of parts) {
+      const [key, value] = part.split("=");
+      if (key === "ts" && value) {
+        timestamp = parseInt(value, 10);
+      } else if (key === "h1" && value) {
+        signature = value;
+      }
+    }
+    if (timestamp === undefined || !signature) {
+      return null;
+    }
+    return { timestamp, signature };
+  }
+}
+
+// src/providers/ShopifyProvider.ts
+class ShopifyProvider extends BaseProvider {
+  name = "shopify";
+  async verify(payload, headers, secret) {
+    const signature = this.getHeader(headers, "x-shopify-hmac-sha256");
+    if (!signature) {
+      return this.createFailure("Missing X-Shopify-Hmac-Sha256 header");
+    }
+    const payloadStr = this.payloadToString(payload);
+    const expectedSignature = await computeHmacSha256Base64(payloadStr, secret);
+    if (!timingSafeEqual(signature, expectedSignature)) {
+      return this.createFailure("Signature verification failed");
+    }
+    const parseResult = this.safeParseJson(payloadStr);
+    if (!parseResult.success) {
+      return this.createFailure(parseResult.error);
+    }
+    return this.createSuccess(parseResult.data, {
+      eventType: this.getHeader(headers, "x-shopify-topic"),
+      webhookId: this.getHeader(headers, "x-shopify-webhook-id")
+    });
+  }
+}
+
+// src/providers/SlackProvider.ts
+class SlackProvider extends BaseProvider {
+  name = "slack";
+  async verify(payload, headers, secret) {
+    const signature = this.getHeader(headers, "x-slack-signature");
+    const timestampStr = this.getHeader(headers, "x-slack-request-timestamp");
+    if (!signature) {
+      return this.createFailure("Missing X-Slack-Signature header");
+    }
+    if (!timestampStr) {
+      return this.createFailure("Missing X-Slack-Request-Timestamp header");
+    }
+    if (!signature.startsWith("v0=")) {
+      return this.createFailure("Invalid signature format (expected v0=...)");
+    }
+    const timestamp = parseInt(timestampStr, 10);
+    if (!validateTimestamp(timestamp, this.tolerance)) {
+      return this.createFailure(`Timestamp outside tolerance window (${this.tolerance}s)`);
+    }
+    const payloadStr = this.payloadToString(payload);
+    const sigBasestring = `v0:${timestamp}:${payloadStr}`;
+    const expectedSignature = await computeHmacSha256(sigBasestring, secret);
+    if (!timingSafeEqual(signature.slice(3), expectedSignature)) {
+      return this.createFailure("Signature verification failed");
+    }
+    const parseResult = this.safeParseJson(payloadStr);
+    if (!parseResult.success) {
+      return this.createFailure(parseResult.error);
+    }
+    const data = parseResult.data;
+    return this.createSuccess(data, {
+      eventType: data.type,
+      webhookId: data.event_id
+    });
   }
 }
 
 // src/providers/StripeProvider.ts
-class StripeProvider {
+class StripeProvider extends BaseProvider {
   name = "stripe";
-  tolerance;
   constructor(options = {}) {
-    this.tolerance = options.tolerance ?? 300;
+    super(options);
   }
   async verify(payload, headers, secret) {
     const signatureHeader = this.getHeader(headers, "stripe-signature");
     if (!signatureHeader) {
-      return {
-        valid: false,
-        error: "Missing Stripe-Signature header"
-      };
+      return this.createFailure("Missing Stripe-Signature header");
     }
     const parsed = parseStripeSignature(signatureHeader);
     if (!parsed) {
-      return {
-        valid: false,
-        error: "Invalid Stripe-Signature header format"
-      };
+      return this.createFailure("Invalid Stripe-Signature header format");
     }
     const { timestamp, signatures } = parsed;
     if (!validateTimestamp(timestamp, this.tolerance)) {
-      return {
-        valid: false,
-        error: `Timestamp outside tolerance window (${this.tolerance}s)`
-      };
+      return this.createFailure(`Timestamp outside tolerance window (${this.tolerance}s)`);
     }
-    const payloadStr = typeof payload === "string" ? payload : payload.toString("utf-8");
+    const payloadStr = this.payloadToString(payload);
     const signedPayload = `${timestamp}.${payloadStr}`;
     const expectedSignature = await computeHmacSha256(signedPayload, secret);
     const signatureValid = signatures.some((sig) => timingSafeEqual(sig.toLowerCase(), expectedSignature.toLowerCase()));
     if (!signatureValid) {
-      return {
-        valid: false,
-        error: "Signature verification failed"
-      };
+      return this.createFailure("Signature verification failed");
     }
-    try {
-      const event = JSON.parse(payloadStr);
-      return {
-        valid: true,
-        payload: event,
-        eventType: event.type,
-        webhookId: event.id
-      };
-    } catch {
-      return {
-        valid: false,
-        error: "Failed to parse webhook payload"
-      };
+    const parseResult = this.safeParseJson(payloadStr);
+    if (!parseResult.success) {
+      return this.createFailure("Failed to parse webhook payload");
     }
+    const event = parseResult.data;
+    return this.createSuccess(event, {
+      eventType: event.type,
+      webhookId: event.id
+    });
   }
   parseEventType(payload) {
     if (typeof payload === "object" && payload !== null && "type" in payload) {
@@ -219,9 +558,33 @@ class StripeProvider {
     }
     return;
   }
-  getHeader(headers, name) {
-    const value = headers[name] ?? headers[name.toLowerCase()];
-    return Array.isArray(value) ? value[0] : value;
+}
+
+// src/providers/TwilioProvider.ts
+class TwilioProvider extends BaseProvider {
+  name = "twilio";
+  baseUrl;
+  constructor(options = {}) {
+    super(options);
+    this.baseUrl = options.baseUrl;
+  }
+  async verify(payload, headers, secret) {
+    const signature = this.getHeader(headers, "x-twilio-signature");
+    if (!signature) {
+      return this.createFailure("Missing X-Twilio-Signature header");
+    }
+    const url = this.baseUrl ?? "";
+    const payloadStr = this.payloadToString(payload);
+    const params = new URLSearchParams(payloadStr);
+    const sortedParams = Array.from(params.entries()).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => `${key}${value}`).join("");
+    const signaturePayload = url + sortedParams;
+    const expectedSignature = await computeHmacSha1Base64(signaturePayload, secret);
+    if (!timingSafeEqual(signature, expectedSignature)) {
+      return this.createFailure("Signature verification failed");
+    }
+    return this.createSuccess(Object.fromEntries(params), {
+      eventType: params.get("EventType") ?? undefined
+    });
   }
 }
 
@@ -230,12 +593,42 @@ class WebhookReceiver {
   providers = new Map;
   handlers = new Map;
   globalHandlers = new Map;
+  store;
+  metrics = new NoopMetricsProvider;
+  tracer = new NoopTracer;
+  logger = new ConsoleEchoLogger;
+  keyRotationManager;
   constructor() {
     this.registerProviderType("generic", GenericProvider);
     this.registerProviderType("stripe", StripeProvider);
     this.registerProviderType("github", GitHubProvider);
+    this.registerProviderType("shopify", ShopifyProvider);
+    this.registerProviderType("twilio", TwilioProvider);
+    this.registerProviderType("slack", SlackProvider);
+    this.registerProviderType("paddle", PaddleProvider);
+    this.registerProviderType("linear", LinearProvider);
   }
   providerTypes = new Map;
+  setStore(store) {
+    this.store = store;
+    return this;
+  }
+  setMetrics(metrics) {
+    this.metrics = metrics;
+    return this;
+  }
+  setTracer(tracer) {
+    this.tracer = tracer;
+    return this;
+  }
+  setLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  setKeyRotationManager(manager) {
+    this.keyRotationManager = manager;
+    return this;
+  }
   registerProviderType(name, ProviderCls) {
     this.providerTypes.set(name, ProviderCls);
     return this;
@@ -250,11 +643,34 @@ class WebhookReceiver {
     this.providers.set(name, { provider, secret });
     return this;
   }
+  registerProviderWithRotation(name, keys, options) {
+    if (!this.keyRotationManager) {
+      throw new Error("KeyRotationManager must be set before using key rotation");
+    }
+    const type = options?.type ?? name;
+    const ProviderClass = this.providerTypes.get(type);
+    if (!ProviderClass) {
+      throw new Error(`Unknown provider type: ${type}`);
+    }
+    this.keyRotationManager.registerKeys(name, keys);
+    const primaryKey = this.keyRotationManager.getPrimaryKey(name);
+    if (!primaryKey) {
+      throw new Error(`No primary key found for provider ${name}`);
+    }
+    const provider = new ProviderClass({ tolerance: options?.tolerance });
+    this.providers.set(name, { provider, secret: primaryKey.key });
+    return this;
+  }
   on(providerName, eventType, handler) {
     if (!this.handlers.has(providerName)) {
       this.handlers.set(providerName, new Map);
     }
     const providerHandlers = this.handlers.get(providerName);
+    if (!providerHandlers) {
+      const newHandlers = new Map;
+      this.handlers.set(providerName, newHandlers);
+      return this.on(providerName, eventType, handler);
+    }
     if (!providerHandlers.has(eventType)) {
       providerHandlers.set(eventType, []);
     }
@@ -268,48 +684,186 @@ class WebhookReceiver {
     this.globalHandlers.get(providerName)?.push(handler);
     return this;
   }
-  async handle(providerName, body, headers) {
-    const config = this.providers.get(providerName);
-    if (!config) {
-      return {
-        valid: false,
-        error: `Provider not registered: ${providerName}`,
-        handled: false
-      };
-    }
-    const { provider, secret } = config;
-    const result = await provider.verify(body, headers, secret);
-    if (!result.valid) {
-      return { ...result, handled: false };
-    }
-    const event = {
-      provider: providerName,
-      type: result.eventType ?? "unknown",
-      payload: result.payload,
-      headers,
-      rawBody: typeof body === "string" ? body : body.toString("utf-8"),
-      receivedAt: new Date,
-      id: result.webhookId
-    };
-    let handled = false;
-    const providerHandlers = this.handlers.get(providerName);
-    if (providerHandlers) {
-      const eventHandlers = providerHandlers.get(event.type);
-      if (eventHandlers) {
-        for (const handler of eventHandlers) {
-          await handler(event);
-          handled = true;
+  async handle(providerName, body, headers, context) {
+    const buffered = context?.get("bufferedRequest");
+    const actualBody = buffered?.rawBody ?? body;
+    const actualHeaders = buffered?.headers ?? headers;
+    return this.tracer.withSpan("echo.receive_webhook", async (span) => {
+      const startTime = performance.now();
+      const labels = { provider: providerName };
+      span.setAttributes({
+        "echo.provider": providerName,
+        "echo.direction": "incoming",
+        "echo.buffered": buffered !== undefined
+      });
+      this.logger.debug("Webhook received", {
+        component: "receiver",
+        provider: providerName,
+        buffered: buffered !== undefined
+      });
+      try {
+        const config = this.providers.get(providerName);
+        if (!config) {
+          const error = `Provider not registered: ${providerName}`;
+          this.logger.warn("Webhook provider not registered", {
+            component: "receiver",
+            provider: providerName
+          });
+          span.setStatus({ code: 2 /* ERROR */, message: error });
+          return {
+            valid: false,
+            error,
+            handled: false
+          };
         }
+        const { provider, secret } = config;
+        span.addEvent("verification_start");
+        let result = {
+          valid: false,
+          error: "No verification performed"
+        };
+        if (this.keyRotationManager?.hasProvider(providerName)) {
+          const activeKeys = this.keyRotationManager.getActiveKeys(providerName);
+          let verified = false;
+          for (const keyEntry of activeKeys) {
+            const attemptResult = await provider.verify(actualBody, actualHeaders, keyEntry.key);
+            if (attemptResult.valid) {
+              result = attemptResult;
+              verified = true;
+              if (!keyEntry.isPrimary) {
+                this.logger.info("Webhook verified with non-primary key", {
+                  component: "receiver",
+                  provider: providerName,
+                  keyVersion: keyEntry.version
+                });
+              }
+              break;
+            }
+          }
+          if (!verified) {
+            result = {
+              valid: false,
+              error: "Signature verification failed with all active keys"
+            };
+          }
+        } else {
+          result = await provider.verify(actualBody, actualHeaders, secret);
+        }
+        if (!result.valid) {
+          span.setStatus({ code: 2 /* ERROR */, message: result.error });
+          span.setAttribute("echo.error", result.error ?? "unknown");
+          this.metrics.increment(EchoMetrics.INCOMING_VERIFICATION_FAILURES, {
+            provider: providerName,
+            error_type: this.categorizeError(result.error)
+          });
+          this.logger.warn("Webhook verification failed", {
+            component: "receiver",
+            provider: providerName,
+            error: result.error
+          });
+          return { ...result, handled: false };
+        }
+        span.addEvent("verification_success");
+        span.setAttributes({
+          "echo.event_type": result.eventType ?? "unknown",
+          "echo.webhook_id": result.webhookId ?? ""
+        });
+        this.logger.info("Webhook verified successfully", {
+          component: "receiver",
+          provider: providerName,
+          eventType: result.eventType,
+          webhookId: result.webhookId
+        });
+        labels.event_type = result.eventType;
+        labels.status = "success";
+        let eventId;
+        if (this.store) {
+          eventId = await this.store.saveIncomingEvent({
+            provider: providerName,
+            eventType: result.eventType ?? "unknown",
+            payload: result.payload,
+            headers: Object.fromEntries(Object.entries(actualHeaders).map(([k, v]) => [k, Array.isArray(v) ? v[0] : v])),
+            rawBody: typeof actualBody === "string" ? actualBody : actualBody.toString("utf-8"),
+            receivedAt: new Date,
+            status: "pending"
+          });
+        }
+        const event = {
+          provider: providerName,
+          type: result.eventType ?? "unknown",
+          payload: result.payload,
+          headers: actualHeaders,
+          rawBody: typeof actualBody === "string" ? actualBody : actualBody.toString("utf-8"),
+          receivedAt: new Date,
+          id: result.webhookId
+        };
+        try {
+          let handled = false;
+          let handlerCount = 0;
+          span.addEvent("handlers_start");
+          const providerHandlers = this.handlers.get(providerName);
+          if (providerHandlers) {
+            const eventHandlers = providerHandlers.get(event.type);
+            if (eventHandlers) {
+              for (const handler of eventHandlers) {
+                await handler(event);
+                handled = true;
+                handlerCount++;
+              }
+            }
+          }
+          const globalHandlers = this.globalHandlers.get(providerName);
+          if (globalHandlers) {
+            for (const handler of globalHandlers) {
+              await handler(event);
+              handled = true;
+              handlerCount++;
+            }
+          }
+          span.addEvent("handlers_complete", { handler_count: handlerCount });
+          if (this.store && eventId) {
+            await this.store.markProcessed(eventId);
+          }
+          this.logger.debug("Webhook processing complete", {
+            component: "receiver",
+            provider: providerName,
+            eventType: result.eventType,
+            handlersInvoked: handlerCount
+          });
+          span.setStatus({ code: 1 /* OK */ });
+          return { ...result, handled, eventId };
+        } catch (error) {
+          if (this.store && eventId) {
+            await this.store.markFailed(eventId, String(error));
+          }
+          throw error;
+        }
+      } catch (error) {
+        labels.status = "failure";
+        labels.error_type = error instanceof Error ? error.name : "unknown";
+        span.setStatus({ code: 2 /* ERROR */, message: String(error) });
+        throw error;
+      } finally {
+        const duration = (performance.now() - startTime) / 1000;
+        this.metrics.increment(EchoMetrics.INCOMING_TOTAL, labels);
+        this.metrics.histogram(EchoMetrics.INCOMING_DURATION, duration, labels);
       }
+    });
+  }
+  categorizeError(error) {
+    if (!error) {
+      return "unknown";
     }
-    const globalHandlers = this.globalHandlers.get(providerName);
-    if (globalHandlers) {
-      for (const handler of globalHandlers) {
-        await handler(event);
-        handled = true;
-      }
+    if (error.includes("Missing")) {
+      return "missing_header";
+    }
+    if (error.includes("Signature")) {
+      return "signature_invalid";
+    }
+    if (error.includes("Timestamp")) {
+      return "timestamp_invalid";
     }
-    return { ...result, handled };
+    return "other";
   }
   async verify(providerName, body, headers) {
     const config = this.providers.get(providerName);
@@ -323,6 +877,220 @@ class WebhookReceiver {
   }
 }
 
+// src/rotation/KeyRotationManager.ts
+var DEFAULT_CONFIG2 = {
+  enabled: false,
+  autoCleanup: true,
+  gracePeriod: 24 * 60 * 60 * 1000,
+  keyProvider: async () => [],
+  onRotate: () => {}
+};
+
+class KeyRotationManager {
+  providerKeys = new Map;
+  cleanupTimer;
+  config;
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_CONFIG2, ...config };
+    if (this.config.enabled && this.config.autoCleanup) {
+      this.startAutoCleanup();
+    }
+  }
+  registerKeys(providerName, keys) {
+    const primaryKeys = keys.filter((k) => k.isPrimary);
+    if (primaryKeys.length !== 1) {
+      throw new Error(`Provider ${providerName} must have exactly one primary key`);
+    }
+    const sorted = [...keys].sort((a, b) => b.activeFrom.getTime() - a.activeFrom.getTime());
+    this.providerKeys.set(providerName, sorted);
+  }
+  getActiveKeys(providerName) {
+    const keys = this.providerKeys.get(providerName) ?? [];
+    const now = new Date;
+    return keys.filter((key) => {
+      const isActive = key.activeFrom <= now;
+      const notExpired = !key.expiresAt || key.expiresAt > now;
+      return isActive && notExpired;
+    });
+  }
+  getPrimaryKey(providerName) {
+    const keys = this.getActiveKeys(providerName);
+    return keys.find((k) => k.isPrimary) ?? null;
+  }
+  async rotatePrimaryKey(providerName, newKey) {
+    const existingKeys = this.providerKeys.get(providerName) ?? [];
+    const updatedKeys = existingKeys.map((key) => ({
+      ...key,
+      isPrimary: false,
+      expiresAt: key.isPrimary ? new Date(Date.now() + this.config.gracePeriod) : key.expiresAt
+    }));
+    const primaryKey = {
+      ...newKey,
+      isPrimary: true
+    };
+    updatedKeys.unshift(primaryKey);
+    this.providerKeys.set(providerName, updatedKeys);
+    this.config.onRotate(providerName, primaryKey);
+  }
+  cleanupExpiredKeys() {
+    const now = new Date;
+    let cleaned = 0;
+    for (const [providerName, keys] of this.providerKeys.entries()) {
+      const active = keys.filter((key) => !key.expiresAt || key.expiresAt > now);
+      if (active.length !== keys.length) {
+        cleaned += keys.length - active.length;
+        this.providerKeys.set(providerName, active);
+      }
+    }
+    return cleaned;
+  }
+  startAutoCleanup() {
+    this.cleanupTimer = setInterval(() => {
+      const cleaned = this.cleanupExpiredKeys();
+      if (cleaned > 0) {
+        console.log(`[KeyRotationManager] Cleaned up ${cleaned} expired keys`);
+      }
+    }, 60 * 60 * 1000);
+  }
+  destroy() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+    }
+  }
+  getAllProviderKeys() {
+    return new Map(this.providerKeys);
+  }
+  hasProvider(providerName) {
+    return this.providerKeys.has(providerName);
+  }
+}
+
+// src/resilience/CircuitBreaker.ts
+var DEFAULT_CONFIG3 = {
+  enabled: true,
+  failureThreshold: 5,
+  successThreshold: 2,
+  windowSize: 60000,
+  openTimeout: 30000,
+  onOpen: () => {},
+  onHalfOpen: () => {},
+  onClose: () => {}
+};
+
+class CircuitBreaker {
+  name;
+  state = "CLOSED";
+  failures = 0;
+  successes = 0;
+  lastFailureAt;
+  lastSuccessAt;
+  openedAt;
+  halfOpenAttempts = 0;
+  config;
+  constructor(name, config = {}) {
+    this.name = name;
+    this.config = { ...DEFAULT_CONFIG3, ...config };
+  }
+  async execute(fn) {
+    if (!this.config.enabled) {
+      return await fn();
+    }
+    this.checkStateTransition();
+    if (this.state === "OPEN") {
+      throw new Error(`Circuit breaker is OPEN for ${this.name}`);
+    }
+    try {
+      const result = await fn();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+  onSuccess() {
+    this.lastSuccessAt = new Date;
+    this.successes++;
+    if (this.state === "HALF_OPEN") {
+      this.halfOpenAttempts++;
+      if (this.halfOpenAttempts >= this.config.successThreshold) {
+        this.transitionTo("CLOSED");
+        this.reset();
+      }
+    } else if (this.state === "CLOSED") {
+      this.failures = 0;
+    }
+  }
+  onFailure() {
+    this.lastFailureAt = new Date;
+    this.failures++;
+    if (this.state === "HALF_OPEN") {
+      this.transitionTo("OPEN");
+      this.openedAt = new Date;
+    } else if (this.state === "CLOSED") {
+      if (this.failures >= this.config.failureThreshold) {
+        this.transitionTo("OPEN");
+        this.openedAt = new Date;
+      }
+    }
+  }
+  checkStateTransition() {
+    if (this.state === "OPEN" && this.openedAt) {
+      const elapsed = Date.now() - this.openedAt.getTime();
+      if (elapsed >= this.config.openTimeout) {
+        this.transitionTo("HALF_OPEN");
+        this.halfOpenAttempts = 0;
+      }
+    }
+    if (this.lastFailureAt) {
+      const elapsed = Date.now() - this.lastFailureAt.getTime();
+      if (elapsed >= this.config.windowSize) {
+        this.failures = 0;
+      }
+    }
+  }
+  transitionTo(newState) {
+    this.state = newState;
+    switch (newState) {
+      case "OPEN":
+        this.config.onOpen(this.name);
+        break;
+      case "HALF_OPEN":
+        this.config.onHalfOpen(this.name);
+        break;
+      case "CLOSED":
+        this.config.onClose(this.name);
+        break;
+    }
+  }
+  reset() {
+    this.failures = 0;
+    this.successes = 0;
+    this.halfOpenAttempts = 0;
+    this.openedAt = undefined;
+  }
+  getMetrics() {
+    return {
+      state: this.state,
+      failures: this.failures,
+      successes: this.successes,
+      lastFailureAt: this.lastFailureAt,
+      lastSuccessAt: this.lastSuccessAt,
+      openedAt: this.openedAt
+    };
+  }
+  manualReset() {
+    this.transitionTo("CLOSED");
+    this.reset();
+  }
+  getState() {
+    return this.state;
+  }
+  getName() {
+    return this.name;
+  }
+}
+
 // src/send/WebhookDispatcher.ts
 var DEFAULT_RETRY_CONFIG = {
   maxAttempts: 3,
@@ -337,13 +1105,125 @@ class WebhookDispatcher {
   retryConfig;
   timeout;
   userAgent;
+  dlq;
+  metrics = new NoopMetricsProvider;
+  tracer = new NoopTracer;
+  logger;
+  circuitBreakers = new Map;
+  circuitBreakerConfig;
   constructor(config) {
     this.secret = config.secret;
     this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...config.retry };
     this.timeout = config.timeout ?? 30000;
     this.userAgent = config.userAgent ?? "Gravito-Echo/1.0";
+    this.circuitBreakerConfig = config.circuitBreaker;
+  }
+  setDeadLetterQueue(dlq) {
+    this.dlq = dlq;
+    return this;
+  }
+  setMetrics(metrics) {
+    this.metrics = metrics;
+    return this;
+  }
+  setTracer(tracer) {
+    this.tracer = tracer;
+    return this;
+  }
+  setLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  getCircuitBreaker(url) {
+    if (!this.circuitBreakerConfig?.enabled) {
+      return;
+    }
+    const host = new URL(url).host;
+    if (!this.circuitBreakers.has(host)) {
+      const breaker = new CircuitBreaker(host, {
+        ...this.circuitBreakerConfig,
+        onOpen: (name) => {
+          this.logger?.warn(`Circuit breaker OPEN for ${name}`, {
+            component: "dispatcher",
+            host: name
+          });
+          this.circuitBreakerConfig?.onOpen?.(name);
+        },
+        onHalfOpen: (name) => {
+          this.logger?.info(`Circuit breaker HALF_OPEN for ${name}`, {
+            component: "dispatcher",
+            host: name
+          });
+          this.circuitBreakerConfig?.onHalfOpen?.(name);
+        },
+        onClose: (name) => {
+          this.logger?.info(`Circuit breaker CLOSED for ${name}`, {
+            component: "dispatcher",
+            host: name
+          });
+          this.circuitBreakerConfig?.onClose?.(name);
+        }
+      });
+      this.circuitBreakers.set(host, breaker);
+    }
+    return this.circuitBreakers.get(host);
+  }
+  getCircuitBreakerMetrics(url) {
+    const host = new URL(url).host;
+    const breaker = this.circuitBreakers.get(host);
+    return breaker ? breaker.getMetrics() : null;
+  }
+  resetCircuitBreaker(url) {
+    const host = new URL(url).host;
+    const breaker = this.circuitBreakers.get(host);
+    breaker?.manualReset();
   }
   async dispatch(payload) {
+    return this.tracer.withSpan("echo.dispatch_webhook", async (span) => {
+      const startTime = performance.now();
+      const labels = { event_type: payload.event };
+      span.setAttributes({
+        "echo.direction": "outgoing",
+        "echo.event": payload.event,
+        "echo.url": payload.url,
+        "http.method": "POST",
+        "http.url": payload.url
+      });
+      const result = await this.dispatchInternal(payload);
+      const duration = (performance.now() - startTime) / 1000;
+      labels.status = result.success ? "success" : "failure";
+      labels.status_code = result.statusCode?.toString();
+      this.metrics.increment(EchoMetrics.OUTGOING_TOTAL, labels);
+      this.metrics.histogram(EchoMetrics.OUTGOING_DURATION, duration, labels);
+      if (result.attempt > 1) {
+        this.metrics.increment(EchoMetrics.OUTGOING_RETRIES, {
+          event_type: payload.event
+        });
+      }
+      span.setAttributes({
+        "echo.success": result.success,
+        "echo.attempt": result.attempt,
+        "echo.duration_ms": result.duration
+      });
+      if (result.statusCode) {
+        span.setAttribute("http.status_code", result.statusCode);
+      }
+      if (result.success) {
+        span.setStatus({ code: 1 /* OK */ });
+      } else {
+        span.setStatus({
+          code: 2 /* ERROR */,
+          message: result.error
+        });
+        this.metrics.increment(EchoMetrics.OUTGOING_FAILURES, {
+          event_type: payload.event,
+          error_type: this.categorizeError(result)
+        });
+      }
+      return result;
+    });
+  }
+  async dispatchInternal(payload) {
     let lastResult = null;
     for (let attempt = 1;attempt <= this.retryConfig.maxAttempts; attempt++) {
       const result = await this.attemptDelivery(payload, attempt);
@@ -359,63 +1239,167 @@ class WebhookDispatcher {
           continue;
         }
       }
-      return result;
+      break;
+    }
+    if (this.dlq && lastResult && !lastResult.success) {
+      await this.dlq.enqueue({
+        type: "outgoing",
+        originalEvent: {
+          url: payload.url,
+          event: payload.event,
+          payload: payload.data,
+          createdAt: new Date,
+          status: "failed",
+          attempts: []
+        },
+        failureReason: lastResult.error ?? "Unknown error",
+        failedAt: new Date,
+        retryCount: lastResult.attempt
+      });
+    }
+    if (!lastResult) {
+      throw new Error("No delivery attempts were made");
     }
     return lastResult;
   }
+  async dispatchBatch(payloads, options = {}) {
+    const concurrency = options.concurrency ?? 5;
+    const stopOnFirstFailure = options.stopOnFirstFailure ?? false;
+    const results = [];
+    let succeeded = 0;
+    let failed = 0;
+    let stopped = false;
+    for (let i = 0;i < payloads.length && !stopped; i += concurrency) {
+      const chunk = payloads.slice(i, i + concurrency);
+      const chunkResults = await Promise.all(chunk.map(async (payload) => {
+        if (stopped) {
+          return {
+            payload,
+            result: {
+              success: false,
+              attempt: 0,
+              duration: 0,
+              deliveredAt: new Date,
+              error: "Batch dispatch stopped"
+            }
+          };
+        }
+        const result = await this.dispatch(payload);
+        if (result.success) {
+          succeeded++;
+        } else {
+          failed++;
+          if (stopOnFirstFailure) {
+            stopped = true;
+          }
+        }
+        return { payload, result };
+      }));
+      results.push(...chunkResults);
+    }
+    return {
+      total: payloads.length,
+      succeeded,
+      failed,
+      results
+    };
+  }
+  async retryFromDlq(id) {
+    if (!this.dlq) {
+      return null;
+    }
+    const events = await this.dlq.peek(100);
+    const event = events.find((e) => e.id === id);
+    if (!event || event.type !== "outgoing") {
+      return null;
+    }
+    const outgoing = event.originalEvent;
+    const result = await this.dispatch({
+      url: outgoing.url,
+      event: outgoing.event,
+      data: outgoing.payload
+    });
+    if (result.success) {
+      await this.dlq.dequeue(id);
+    } else {
+      event.retryCount++;
+      event.lastRetryAt = new Date;
+    }
+    return result;
+  }
   async attemptDelivery(payload, attempt) {
-    const startTime = Date.now();
-    const timestamp = Math.floor(Date.now() / 1000);
-    const webhookId = payload.id ?? crypto.randomUUID();
-    try {
-      const body = JSON.stringify({
-        id: webhookId,
-        type: payload.event,
-        timestamp,
-        data: payload.data
-      });
-      const signedPayload = `${timestamp}.${body}`;
-      const signature = await computeHmacSha256(signedPayload, this.secret);
-      const controller = new AbortController;
-      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    const breaker = this.getCircuitBreaker(payload.url);
+    const deliveryFn = async () => {
+      const startTime = Date.now();
+      const timestamp = Math.floor(Date.now() / 1000);
+      const webhookId = payload.id ?? crypto.randomUUID();
       try {
-        const response = await fetch(payload.url, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/json",
-            "User-Agent": this.userAgent,
-            "X-Webhook-ID": webhookId,
-            "X-Webhook-Timestamp": String(timestamp),
-            "X-Webhook-Signature": `t=${timestamp},v1=${signature}`
-          },
-          body,
-          signal: controller.signal
+        const body = JSON.stringify({
+          id: webhookId,
+          type: payload.event,
+          timestamp,
+          data: payload.data
         });
-        clearTimeout(timeoutId);
+        const signedPayload = `${timestamp}.${body}`;
+        const signature = await computeHmacSha256(signedPayload, this.secret);
+        const controller = new AbortController;
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+          const response = await fetch(payload.url, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "User-Agent": this.userAgent,
+              "X-Webhook-ID": webhookId,
+              "X-Webhook-Timestamp": String(timestamp),
+              "X-Webhook-Signature": `t=${timestamp},v1=${signature}`
+            },
+            body,
+            signal: controller.signal
+          });
+          clearTimeout(timeoutId);
+          const duration = Date.now() - startTime;
+          const responseBody = await response.text();
+          return {
+            success: response.ok,
+            statusCode: response.status,
+            body: responseBody,
+            attempt,
+            duration,
+            deliveredAt: new Date,
+            error: response.ok ? undefined : `HTTP ${response.status}`
+          };
+        } finally {
+          clearTimeout(timeoutId);
+        }
+      } catch (error) {
         const duration = Date.now() - startTime;
-        const responseBody = await response.text();
         return {
-          success: response.ok,
-          statusCode: response.status,
-          body: responseBody,
+          success: false,
           attempt,
           duration,
           deliveredAt: new Date,
-          error: response.ok ? undefined : `HTTP ${response.status}`
+          error: error instanceof Error ? error.message : "Unknown error"
         };
-      } finally {
-        clearTimeout(timeoutId);
       }
-    } catch (error) {
-      const duration = Date.now() - startTime;
-      return {
-        success: false,
-        attempt,
-        duration,
-        deliveredAt: new Date,
-        error: error instanceof Error ? error.message : "Unknown error"
-      };
+    };
+    if (breaker) {
+      try {
+        return await breaker.execute(deliveryFn);
+      } catch (error) {
+        if (error instanceof Error && error.message.includes("Circuit breaker is OPEN")) {
+          return {
+            success: false,
+            attempt,
+            duration: 0,
+            deliveredAt: new Date,
+            error: error.message
+          };
+        }
+        throw error;
+      }
     }
+    return await deliveryFn();
   }
   shouldRetry(result) {
     if (!result.statusCode) {
@@ -427,6 +1411,18 @@ class WebhookDispatcher {
     const delay = this.retryConfig.initialDelay * this.retryConfig.backoffMultiplier ** (attempt - 1);
     return Math.min(delay, this.retryConfig.maxDelay);
   }
+  categorizeError(result) {
+    if (!result.statusCode) {
+      return "network_error";
+    }
+    if (result.statusCode >= 500) {
+      return "server_error";
+    }
+    if (result.statusCode >= 400) {
+      return "client_error";
+    }
+    return "other";
+  }
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
@@ -434,31 +1430,73 @@ class WebhookDispatcher {
 
 // src/OrbitEcho.ts
 class OrbitEcho {
-  static config = { singleton: true };
   receiver;
   dispatcher;
   echoConfig;
+  keyRotationManager;
   constructor(config = {}) {
     this.echoConfig = config;
     this.receiver = new WebhookReceiver;
+    if (config.keyRotation?.enabled) {
+      this.keyRotationManager = new KeyRotationManager(config.keyRotation);
+      this.receiver.setKeyRotationManager(this.keyRotationManager);
+    }
     if (config.providers) {
       for (const [name, providerConfig] of Object.entries(config.providers)) {
-        this.receiver.registerProvider(name, providerConfig.secret, {
-          type: providerConfig.name,
-          tolerance: providerConfig.tolerance
-        });
+        const rotationConfig = providerConfig;
+        if (rotationConfig.keys && rotationConfig.keys.length > 0 && this.keyRotationManager) {
+          this.receiver.registerProviderWithRotation(name, rotationConfig.keys, {
+            type: providerConfig.name,
+            tolerance: providerConfig.tolerance
+          });
+        } else {
+          this.receiver.registerProvider(name, providerConfig.secret, {
+            type: providerConfig.name,
+            tolerance: providerConfig.tolerance
+          });
+        }
       }
     }
     if (config.dispatcher) {
       this.dispatcher = new WebhookDispatcher(config.dispatcher);
+      if (config.deadLetterQueue) {
+        this.dispatcher.setDeadLetterQueue(config.deadLetterQueue);
+      }
+    }
+    if (config.store) {
+      this.receiver.setStore(config.store);
+    }
+    if (config.observability) {
+      const { metrics, tracer, logger } = config.observability;
+      if (metrics) {
+        this.receiver.setMetrics(metrics);
+        this.dispatcher?.setMetrics(metrics);
+      }
+      if (tracer) {
+        this.receiver.setTracer(tracer);
+        this.dispatcher?.setTracer(tracer);
+      }
+      if (logger) {
+        this.receiver.setLogger(logger);
+      }
     }
   }
   install(core) {
+    if (this.echoConfig.requestBuffer?.enabled !== false) {
+      const bufferMiddleware = createRequestBufferMiddleware(this.echoConfig.requestBuffer);
+      core.adapter.use("*", bufferMiddleware);
+      core.logger.info("[OrbitEcho] Request buffer middleware installed");
+    }
     core.container.instance("echo", this);
     core.container.instance("echo.receiver", this.receiver);
     if (this.dispatcher) {
       core.container.instance("echo.dispatcher", this.dispatcher);
     }
+    core.adapter.use("*", async (c, next) => {
+      c.set("echo", this);
+      return await next();
+    });
+    core.logger.info("[OrbitEcho] Webhook receiver and dispatcher registered");
   }
   getReceiver() {
     return this.receiver;
@@ -469,19 +1507,123 @@ class OrbitEcho {
   getConfig() {
     return this.echoConfig;
   }
+  getKeyRotationManager() {
+    return this.keyRotationManager;
+  }
+  async rotateProviderKey(providerName, newKey) {
+    if (!this.keyRotationManager) {
+      throw new Error("Key rotation is not enabled");
+    }
+    await this.keyRotationManager.rotatePrimaryKey(providerName, newKey);
+  }
+}
+// src/replay/WebhookReplayService.ts
+class WebhookReplayService {
+  store;
+  dispatcher;
+  constructor(store, dispatcher) {
+    this.store = store;
+    this.dispatcher = dispatcher;
+  }
+  async replay(options) {
+    const events = await this.store.queryEvents({
+      direction: "outgoing",
+      provider: options.provider,
+      eventType: options.eventType,
+      from: options.timeRange?.from,
+      to: options.timeRange?.to
+    });
+    const targetEvents = options.eventIds ? events.filter((e) => options.eventIds?.includes(e.id ?? "")) : events;
+    const result = {
+      total: targetEvents.length,
+      replayed: 0,
+      skipped: 0,
+      failed: 0,
+      events: []
+    };
+    for (const event of targetEvents) {
+      if (event.direction !== "outgoing") {
+        result.skipped++;
+        result.events.push({
+          eventId: event.id ?? "unknown",
+          status: "skipped",
+          error: "Not an outgoing event"
+        });
+        continue;
+      }
+      const outgoing = event;
+      if (options.dryRun) {
+        result.replayed++;
+        result.events.push({
+          eventId: event.id ?? "unknown",
+          status: "replayed"
+        });
+        continue;
+      }
+      try {
+        const dispatchResult = await this.dispatcher.dispatch({
+          url: options.targetUrl ?? outgoing.url,
+          event: outgoing.event,
+          data: outgoing.payload
+        });
+        if (dispatchResult.success) {
+          result.replayed++;
+          result.events.push({
+            eventId: event.id ?? "unknown",
+            status: "replayed",
+            result: dispatchResult
+          });
+        } else {
+          result.failed++;
+          result.events.push({
+            eventId: event.id ?? "unknown",
+            status: "failed",
+            result: dispatchResult,
+            error: dispatchResult.error
+          });
+        }
+      } catch (error) {
+        result.failed++;
+        result.events.push({
+          eventId: event.id ?? "unknown",
+          status: "failed",
+          error: String(error)
+        });
+      }
+    }
+    return result;
+  }
 }
 export {
   validateTimestamp,
   timingSafeEqual,
   parseStripeSignature,
+  createRequestBufferMiddleware,
   computeHmacSha256,
   computeHmacSha1,
+  WebhookReplayService,
   WebhookReceiver,
-  WebhookDispatcher,
+  TwilioProvider,
   StripeProvider,
+  SpanStatusCode,
+  SlackProvider,
+  ShopifyProvider,
+  RequestBufferMiddleware,
+  PrometheusMetricsProvider,
+  PaddleProvider,
   OrbitEcho,
+  NoopTracer,
+  NoopSpan,
+  NoopMetricsProvider,
+  MemoryDeadLetterQueue,
+  LinearProvider,
+  KeyRotationManager,
   GitHubProvider,
-  GenericProvider
+  GenericProvider,
+  EchoMetrics,
+  ConsoleEchoLogger,
+  CircuitBreaker,
+  BaseProvider
 };
 
-//# debugId=B1111F963DAFCE1264756E2164756E21
+//# debugId=58FA12C7769E147864756E2164756E21