autotel-subscribers 4.0.0

package/dist/middleware.cjs

@@ -0,0 +1,220 @@
+'use strict';
+
+// src/middleware.ts
+function applyMiddleware(subscriber, middlewares) {
+  const trackEvent = async (event) => {
+    switch (event.type) {
+      case "event": {
+        await subscriber.trackEvent(event.name, event.attributes);
+        break;
+      }
+      case "funnel": {
+        await subscriber.trackFunnelStep(event.funnel, event.step, event.attributes);
+        break;
+      }
+      case "outcome": {
+        await subscriber.trackOutcome(event.operation, event.outcome, event.attributes);
+        break;
+      }
+      case "value": {
+        await subscriber.trackValue(event.name, event.value, event.attributes);
+        break;
+      }
+    }
+  };
+  const reversedMiddlewares = middlewares.toReversed();
+  let chain = trackEvent;
+  for (const middleware of reversedMiddlewares) {
+    const next = chain;
+    chain = (event) => middleware(event, next);
+  }
+  return {
+    name: `${subscriber.name}(middleware)`,
+    version: subscriber.version,
+    async trackEvent(name, attributes) {
+      await chain({ type: "event", name, attributes });
+    },
+    async trackFunnelStep(funnel, step, attributes) {
+      await chain({ type: "funnel", funnel, step, attributes });
+    },
+    async trackOutcome(operation, outcome, attributes) {
+      await chain({ type: "outcome", operation, outcome, attributes });
+    },
+    async trackValue(name, value, attributes) {
+      await chain({ type: "value", name, value, attributes });
+    },
+    async shutdown() {
+      await subscriber.shutdown?.();
+    }
+  };
+}
+function retryMiddleware(options) {
+  const { maxRetries = 3, delayMs = 1e3, onRetry } = options;
+  return async (event, next) => {
+    let lastError;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        await next(event);
+        return;
+      } catch (error) {
+        lastError = error;
+        if (attempt < maxRetries) {
+          onRetry?.(attempt, lastError);
+          await new Promise((resolve) => setTimeout(resolve, delayMs * Math.pow(2, attempt - 1)));
+        }
+      }
+    }
+    throw lastError;
+  };
+}
+function samplingMiddleware(rate) {
+  if (rate < 0 || rate > 1) {
+    throw new Error("Sample rate must be between 0 and 1");
+  }
+  return async (event, next) => {
+    if (Math.random() < rate) {
+      await next(event);
+    }
+  };
+}
+function enrichmentMiddleware(enricher) {
+  return async (event, next) => {
+    const enriched = enricher(event);
+    await next(enriched);
+  };
+}
+function loggingMiddleware(options = {}) {
+  const { prefix = "[Events]", logAttributes = false } = options;
+  return async (event, next) => {
+    if (logAttributes) {
+      console.log(prefix, event.type, event);
+    } else {
+      const eventName = "name" in event ? event.name : `${event.funnel || event.operation}`;
+      console.log(prefix, event.type, eventName);
+    }
+    await next(event);
+  };
+}
+function filterMiddleware(predicate) {
+  return async (event, next) => {
+    if (predicate(event)) {
+      await next(event);
+    }
+  };
+}
+function transformMiddleware(transformer) {
+  return async (event, next) => {
+    const transformed = transformer(event);
+    await next(transformed);
+  };
+}
+function batchingMiddleware(options) {
+  const { batchSize = 100, flushInterval = 5e3 } = options;
+  const buffer = [];
+  let flushTimer = null;
+  const flush = async () => {
+    const batch = [...buffer];
+    buffer.length = 0;
+    await Promise.all(batch.map(({ event, next }) => next(event)));
+  };
+  const scheduleFlush = () => {
+    if (flushTimer) return;
+    flushTimer = setTimeout(() => {
+      flush().catch(console.error);
+      flushTimer = null;
+    }, flushInterval);
+  };
+  return async (event, next) => {
+    buffer.push({ event, next });
+    if (buffer.length >= batchSize) {
+      await flush();
+    } else {
+      scheduleFlush();
+    }
+  };
+}
+function rateLimitMiddleware(options) {
+  const { requestsPerSecond } = options;
+  const intervalMs = 1e3 / requestsPerSecond;
+  let lastCallTime = 0;
+  const queue = [];
+  let processing = false;
+  const processQueue = async () => {
+    if (processing) return;
+    processing = true;
+    while (queue.length > 0) {
+      const now = Date.now();
+      const timeSinceLastCall = now - lastCallTime;
+      if (timeSinceLastCall < intervalMs) {
+        await new Promise((resolve) => setTimeout(resolve, intervalMs - timeSinceLastCall));
+      }
+      const fn = queue.shift();
+      if (fn) {
+        lastCallTime = Date.now();
+        fn();
+      }
+    }
+    processing = false;
+  };
+  return async (event, next) => {
+    return new Promise((resolve, reject) => {
+      queue.push(() => {
+        next(event).then(resolve).catch(reject);
+      });
+      processQueue().catch(reject);
+    });
+  };
+}
+function circuitBreakerMiddleware(options) {
+  const { failureThreshold = 5, timeout = 6e4, onOpen, onClose } = options;
+  let failureCount = 0;
+  let lastFailureTime = 0;
+  let circuitOpen = false;
+  return async (event, next) => {
+    if (circuitOpen) {
+      const now = Date.now();
+      if (now - lastFailureTime > timeout) {
+        circuitOpen = false;
+        failureCount = 0;
+        onClose?.();
+      } else {
+        throw new Error("Circuit breaker is open");
+      }
+    }
+    try {
+      await next(event);
+      failureCount = 0;
+    } catch (error) {
+      failureCount++;
+      lastFailureTime = Date.now();
+      if (failureCount >= failureThreshold) {
+        circuitOpen = true;
+        onOpen?.();
+      }
+      throw error;
+    }
+  };
+}
+function timeoutMiddleware(options) {
+  const { timeoutMs } = options;
+  return async (event, next) => {
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error(`Timeout after ${timeoutMs}ms`)), timeoutMs);
+    });
+    await Promise.race([next(event), timeoutPromise]);
+  };
+}
+
+exports.applyMiddleware = applyMiddleware;
+exports.batchingMiddleware = batchingMiddleware;
+exports.circuitBreakerMiddleware = circuitBreakerMiddleware;
+exports.enrichmentMiddleware = enrichmentMiddleware;
+exports.filterMiddleware = filterMiddleware;
+exports.loggingMiddleware = loggingMiddleware;
+exports.rateLimitMiddleware = rateLimitMiddleware;
+exports.retryMiddleware = retryMiddleware;
+exports.samplingMiddleware = samplingMiddleware;
+exports.timeoutMiddleware = timeoutMiddleware;
+exports.transformMiddleware = transformMiddleware;
+//# sourceMappingURL=middleware.cjs.map
+//# sourceMappingURL=middleware.cjs.map

package/dist/middleware.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/middleware.ts"],"names":[],"mappings":"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","file":"middleware.cjs","sourcesContent":["/**\n * Middleware System for Events Subscribers\n *\n * Compose subscriber behaviors using middleware (like Redux/Express).\n * Add retry logic, sampling, enrichment, logging, and more without modifying subscriber code.\n *\n * @example\n * ```typescript\n * import { applyMiddleware, retryMiddleware, loggingMiddleware } from 'autotel-subscribers/middleware';\n *\n * const subscriber = applyMiddleware(\n *   new PostHogSubscriber({ apiKey: '...' }),\n *   [\n *     retryMiddleware({ maxRetries: 3 }),\n *     loggingMiddleware()\n *   ]\n * );\n * ```\n */\n\nimport type { EventSubscriber, EventAttributes, FunnelStatus, OutcomeStatus } from 'autotel/event-subscriber';\n\n/**\n * Unified event type for middleware\n */\nexport type EventsEvent =\n  | {\n      type: 'event';\n      name: string;\n      attributes?: EventAttributes;\n    }\n  | {\n      type: 'funnel';\n      funnel: string;\n      step: FunnelStatus;\n      attributes?: EventAttributes;\n    }\n  | {\n      type: 'outcome';\n      operation: string;\n      outcome: OutcomeStatus;\n      attributes?: EventAttributes;\n    }\n  | {\n      type: 'value';\n      name: string;\n      value: number;\n      attributes?: EventAttributes;\n    };\n\n/**\n * Middleware function signature.\n *\n * Like Express middleware: `(event, next) => Promise<void>`\n */\nexport type SubscriberMiddleware = (\n  event: EventsEvent,\n  next: (event: EventsEvent) => Promise<void>\n) => Promise<void>;\n\n/**\n * Apply middleware to an subscriber.\n *\n * Middleware is executed in order. Each middleware can:\n * - Transform the event before passing to next()\n * - Add side effects (logging, metrics)\n * - Skip calling next() (filtering)\n * - Handle errors\n *\n * @example\n * ```typescript\n * const subscriber = applyMiddleware(\n *   new WebhookSubscriber({ url: '...' }),\n *   [\n *     loggingMiddleware(),\n *     retryMiddleware({ maxRetries: 3 }),\n *     samplingMiddleware(0.1) // Only 10% of events\n *   ]\n * );\n * ```\n */\nexport function applyMiddleware(\n  subscriber: EventSubscriber,\n  middlewares: SubscriberMiddleware[]\n): EventSubscriber {\n  // Convert subscriber methods to event format\n  const trackEvent = async (event: EventsEvent): Promise<void> => {\n    switch (event.type) {\n      case 'event': {\n        await subscriber.trackEvent(event.name, event.attributes);\n        break;\n      }\n      case 'funnel': {\n        await subscriber.trackFunnelStep(event.funnel, event.step, event.attributes);\n        break;\n      }\n      case 'outcome': {\n        await subscriber.trackOutcome(event.operation, event.outcome, event.attributes);\n        break;\n      }\n      case 'value': {\n        await subscriber.trackValue(event.name, event.value, event.attributes);\n        break;\n      }\n    }\n  };\n\n  // Build middleware chain\n  type ChainFunction = (event: EventsEvent) => Promise<void>;\n  const reversedMiddlewares = middlewares.toReversed();\n  let chain: ChainFunction = trackEvent;\n  for (const middleware of reversedMiddlewares) {\n    const next = chain;\n    chain = (event: EventsEvent) => middleware(event, next);\n  }\n\n  // Wrap subscriber with middleware chain\n  return {\n    name: `${subscriber.name}(middleware)`,\n    version: subscriber.version,\n\n    async trackEvent(name: string, attributes?: EventAttributes): Promise<void> {\n      await chain({ type: 'event', name, attributes });\n    },\n\n    async trackFunnelStep(funnel: string, step: FunnelStatus, attributes?: EventAttributes): Promise<void> {\n      await chain({ type: 'funnel', funnel, step, attributes });\n    },\n\n    async trackOutcome(operation: string, outcome: OutcomeStatus, attributes?: EventAttributes): Promise<void> {\n      await chain({ type: 'outcome', operation, outcome, attributes });\n    },\n\n    async trackValue(name: string, value: number, attributes?: EventAttributes): Promise<void> {\n      await chain({ type: 'value', name, value, attributes });\n    },\n\n    async shutdown(): Promise<void> {\n      await subscriber.shutdown?.();\n    },\n  };\n}\n\n// ============================================================================\n// Built-in Middleware\n// ============================================================================\n\n/**\n * Retry failed requests with exponential backoff.\n *\n * @example\n * ```typescript\n * const subscriber = applyMiddleware(adapter, [\n *   retryMiddleware({ maxRetries: 3, delayMs: 1000 })\n * ]);\n * ```\n */\nexport function retryMiddleware(options: {\n  maxRetries?: number;\n  delayMs?: number;\n  onRetry?: (attempt: number, error: Error) => void;\n}): SubscriberMiddleware {\n  const { maxRetries = 3, delayMs = 1000, onRetry } = options;\n\n  return async (event, next) => {\n    let lastError: Error | undefined;\n\n    for (let attempt = 1; attempt <= maxRetries; attempt++) {\n      try {\n        await next(event);\n        return; // Success!\n      } catch (error) {\n        lastError = error as Error;\n\n        if (attempt < maxRetries) {\n          onRetry?.(attempt, lastError);\n          // Exponential backoff: 1s, 2s, 4s, 8s...\n          await new Promise((resolve) => setTimeout(resolve, delayMs * Math.pow(2, attempt - 1)));\n        }\n      }\n    }\n\n    throw lastError;\n  };\n}\n\n/**\n * Sample events (only send a percentage).\n *\n * @example\n * ```typescript\n * // Only send 10% of events (reduce costs)\n * const subscriber = applyMiddleware(adapter, [\n *   samplingMiddleware(0.1)\n * ]);\n * ```\n */\nexport function samplingMiddleware(rate: number): SubscriberMiddleware {\n  if (rate < 0 || rate > 1) {\n    throw new Error('Sample rate must be between 0 and 1');\n  }\n\n  return async (event, next) => {\n    if (Math.random() < rate) {\n      await next(event);\n    }\n    // Else: skip this event\n  };\n}\n\n/**\n * Enrich events with additional attributes.\n *\n * @example\n * ```typescript\n * const subscriber = applyMiddleware(adapter, [\n *   enrichmentMiddleware((event) => ({\n *     ...event,\n *     attributes: {\n *       ...event.attributes,\n *       environment: process.env.NODE_ENV,\n *       timestamp: Date.now()\n *     }\n *   }))\n * ]);\n * ```\n */\nexport function enrichmentMiddleware(\n  enricher: (event: EventsEvent) => EventsEvent\n): SubscriberMiddleware {\n  return async (event, next) => {\n    const enriched = enricher(event);\n    await next(enriched);\n  };\n}\n\n/**\n * Log events to console.\n *\n * @example\n * ```typescript\n * const subscriber = applyMiddleware(adapter, [\n *   loggingMiddleware({ prefix: '[Events]', logAttributes: true })\n * ]);\n * ```\n */\nexport function loggingMiddleware(options: {\n  prefix?: string;\n  logAttributes?: boolean;\n} = {}): SubscriberMiddleware {\n  const { prefix = '[Events]', logAttributes = false } = options;\n\n  return async (event, next) => {\n    if (logAttributes) {\n      console.log(prefix, event.type, event);\n    } else {\n      // Just log event type and name\n      const eventName = 'name' in event ? event.name : `${(event as any).funnel || (event as any).operation}`;\n      console.log(prefix, event.type, eventName);\n    }\n\n    await next(event);\n  };\n}\n\n/**\n * Filter events based on a predicate.\n *\n * @example\n * ```typescript\n * // Only send 'order' events\n * const subscriber = applyMiddleware(adapter, [\n *   filterMiddleware((event) =>\n *     event.type === 'event' && event.name.startsWith('order.')\n *   )\n * ]);\n * ```\n */\nexport function filterMiddleware(\n  predicate: (event: EventsEvent) => boolean\n): SubscriberMiddleware {\n  return async (event, next) => {\n    if (predicate(event)) {\n      await next(event);\n    }\n  };\n}\n\n/**\n * Transform events.\n *\n * @example\n * ```typescript\n * // Lowercase all event names\n * const subscriber = applyMiddleware(adapter, [\n *   transformMiddleware((event) => {\n *     if (event.type === 'event') {\n *       return { ...event, name: event.name.toLowerCase() };\n *     }\n *     return event;\n *   })\n * ]);\n * ```\n */\nexport function transformMiddleware(\n  transformer: (event: EventsEvent) => EventsEvent\n): SubscriberMiddleware {\n  return async (event, next) => {\n    const transformed = transformer(event);\n    await next(transformed);\n  };\n}\n\n/**\n * Batch events and flush periodically.\n *\n * @example\n * ```typescript\n * const subscriber = applyMiddleware(adapter, [\n *   batchingMiddleware({ batchSize: 100, flushInterval: 5000 })\n * ]);\n * ```\n */\nexport function batchingMiddleware(options: {\n  batchSize?: number;\n  flushInterval?: number;\n}): SubscriberMiddleware {\n  const { batchSize = 100, flushInterval = 5000 } = options;\n  const buffer: Array<{ event: EventsEvent; next: (event: EventsEvent) => Promise<void> }> = [];\n  let flushTimer: NodeJS.Timeout | null = null;\n\n  const flush = async () => {\n    const batch = [...buffer];\n    buffer.length = 0;\n\n    await Promise.all(batch.map(({ event, next }) => next(event)));\n  };\n\n  const scheduleFlush = () => {\n    if (flushTimer) return;\n    flushTimer = setTimeout(() => {\n      flush().catch(console.error);\n      flushTimer = null;\n    }, flushInterval);\n  };\n\n  return async (event, next) => {\n    buffer.push({ event, next });\n\n    if (buffer.length >= batchSize) {\n      await flush();\n    } else {\n      scheduleFlush();\n    }\n  };\n}\n\n/**\n * Rate limit events (throttle).\n *\n * @example\n * ```typescript\n * // Max 100 events per second\n * const subscriber = applyMiddleware(adapter, [\n *   rateLimitMiddleware({ requestsPerSecond: 100 })\n * ]);\n * ```\n */\nexport function rateLimitMiddleware(options: {\n  requestsPerSecond: number;\n}): SubscriberMiddleware {\n  const { requestsPerSecond } = options;\n  const intervalMs = 1000 / requestsPerSecond;\n  let lastCallTime = 0;\n  const queue: Array<() => void> = [];\n  let processing = false;\n\n  const processQueue = async () => {\n    if (processing) return;\n    processing = true;\n\n    while (queue.length > 0) {\n      const now = Date.now();\n      const timeSinceLastCall = now - lastCallTime;\n\n      if (timeSinceLastCall < intervalMs) {\n        await new Promise((resolve) => setTimeout(resolve, intervalMs - timeSinceLastCall));\n      }\n\n      const fn = queue.shift();\n      if (fn) {\n        lastCallTime = Date.now();\n        fn();\n      }\n    }\n\n    processing = false;\n  };\n\n  return async (event, next) => {\n    return new Promise<void>((resolve, reject) => {\n      queue.push(() => {\n        next(event).then(resolve).catch(reject);\n      });\n      processQueue().catch(reject);\n    });\n  };\n}\n\n/**\n * Circuit breaker pattern.\n *\n * Opens circuit after N failures, prevents further requests for a timeout period.\n *\n * @example\n * ```typescript\n * const subscriber = applyMiddleware(adapter, [\n *   circuitBreakerMiddleware({\n *     failureThreshold: 5,\n *     timeout: 60000 // 1 minute\n *   })\n * ]);\n * ```\n */\nexport function circuitBreakerMiddleware(options: {\n  failureThreshold?: number;\n  timeout?: number;\n  onOpen?: () => void;\n  onClose?: () => void;\n}): SubscriberMiddleware {\n  const { failureThreshold = 5, timeout = 60_000, onOpen, onClose } = options;\n  let failureCount = 0;\n  let lastFailureTime = 0;\n  let circuitOpen = false;\n\n  return async (event, next) => {\n    // Check if circuit should close\n    if (circuitOpen) {\n      const now = Date.now();\n      if (now - lastFailureTime > timeout) {\n        circuitOpen = false;\n        failureCount = 0;\n        onClose?.();\n      } else {\n        throw new Error('Circuit breaker is open');\n      }\n    }\n\n    try {\n      await next(event);\n      // Success resets failure count\n      failureCount = 0;\n    } catch (error) {\n      failureCount++;\n      lastFailureTime = Date.now();\n\n      if (failureCount >= failureThreshold) {\n        circuitOpen = true;\n        onOpen?.();\n      }\n\n      throw error;\n    }\n  };\n}\n\n/**\n * Add timeout to events.\n *\n * @example\n * ```typescript\n * const subscriber = applyMiddleware(adapter, [\n *   timeoutMiddleware({ timeoutMs: 5000 })\n * ]);\n * ```\n */\nexport function timeoutMiddleware(options: {\n  timeoutMs: number;\n}): SubscriberMiddleware {\n  const { timeoutMs } = options;\n\n  return async (event, next) => {\n    const timeoutPromise = new Promise<never>((_, reject) => {\n      setTimeout(() => reject(new Error(`Timeout after ${timeoutMs}ms`)), timeoutMs);\n    });\n\n    await Promise.race([next(event), timeoutPromise]);\n  };\n}\n"]}

package/dist/middleware.d.cts

@@ -0,0 +1,227 @@
+import { EventAttributes, FunnelStatus, OutcomeStatus, EventSubscriber } from 'autotel/event-subscriber';
+
+/**
+ * Middleware System for Events Subscribers
+ *
+ * Compose subscriber behaviors using middleware (like Redux/Express).
+ * Add retry logic, sampling, enrichment, logging, and more without modifying subscriber code.
+ *
+ * @example
+ * ```typescript
+ * import { applyMiddleware, retryMiddleware, loggingMiddleware } from 'autotel-subscribers/middleware';
+ *
+ * const subscriber = applyMiddleware(
+ *   new PostHogSubscriber({ apiKey: '...' }),
+ *   [
+ *     retryMiddleware({ maxRetries: 3 }),
+ *     loggingMiddleware()
+ *   ]
+ * );
+ * ```
+ */
+
+/**
+ * Unified event type for middleware
+ */
+type EventsEvent = {
+    type: 'event';
+    name: string;
+    attributes?: EventAttributes;
+} | {
+    type: 'funnel';
+    funnel: string;
+    step: FunnelStatus;
+    attributes?: EventAttributes;
+} | {
+    type: 'outcome';
+    operation: string;
+    outcome: OutcomeStatus;
+    attributes?: EventAttributes;
+} | {
+    type: 'value';
+    name: string;
+    value: number;
+    attributes?: EventAttributes;
+};
+/**
+ * Middleware function signature.
+ *
+ * Like Express middleware: `(event, next) => Promise<void>`
+ */
+type SubscriberMiddleware = (event: EventsEvent, next: (event: EventsEvent) => Promise<void>) => Promise<void>;
+/**
+ * Apply middleware to an subscriber.
+ *
+ * Middleware is executed in order. Each middleware can:
+ * - Transform the event before passing to next()
+ * - Add side effects (logging, metrics)
+ * - Skip calling next() (filtering)
+ * - Handle errors
+ *
+ * @example
+ * ```typescript
+ * const subscriber = applyMiddleware(
+ *   new WebhookSubscriber({ url: '...' }),
+ *   [
+ *     loggingMiddleware(),
+ *     retryMiddleware({ maxRetries: 3 }),
+ *     samplingMiddleware(0.1) // Only 10% of events
+ *   ]
+ * );
+ * ```
+ */
+declare function applyMiddleware(subscriber: EventSubscriber, middlewares: SubscriberMiddleware[]): EventSubscriber;
+/**
+ * Retry failed requests with exponential backoff.
+ *
+ * @example
+ * ```typescript
+ * const subscriber = applyMiddleware(adapter, [
+ *   retryMiddleware({ maxRetries: 3, delayMs: 1000 })
+ * ]);
+ * ```
+ */
+declare function retryMiddleware(options: {
+    maxRetries?: number;
+    delayMs?: number;
+    onRetry?: (attempt: number, error: Error) => void;
+}): SubscriberMiddleware;
+/**
+ * Sample events (only send a percentage).
+ *
+ * @example
+ * ```typescript
+ * // Only send 10% of events (reduce costs)
+ * const subscriber = applyMiddleware(adapter, [
+ *   samplingMiddleware(0.1)
+ * ]);
+ * ```
+ */
+declare function samplingMiddleware(rate: number): SubscriberMiddleware;
+/**
+ * Enrich events with additional attributes.
+ *
+ * @example
+ * ```typescript
+ * const subscriber = applyMiddleware(adapter, [
+ *   enrichmentMiddleware((event) => ({
+ *     ...event,
+ *     attributes: {
+ *       ...event.attributes,
+ *       environment: process.env.NODE_ENV,
+ *       timestamp: Date.now()
+ *     }
+ *   }))
+ * ]);
+ * ```
+ */
+declare function enrichmentMiddleware(enricher: (event: EventsEvent) => EventsEvent): SubscriberMiddleware;
+/**
+ * Log events to console.
+ *
+ * @example
+ * ```typescript
+ * const subscriber = applyMiddleware(adapter, [
+ *   loggingMiddleware({ prefix: '[Events]', logAttributes: true })
+ * ]);
+ * ```
+ */
+declare function loggingMiddleware(options?: {
+    prefix?: string;
+    logAttributes?: boolean;
+}): SubscriberMiddleware;
+/**
+ * Filter events based on a predicate.
+ *
+ * @example
+ * ```typescript
+ * // Only send 'order' events
+ * const subscriber = applyMiddleware(adapter, [
+ *   filterMiddleware((event) =>
+ *     event.type === 'event' && event.name.startsWith('order.')
+ *   )
+ * ]);
+ * ```
+ */
+declare function filterMiddleware(predicate: (event: EventsEvent) => boolean): SubscriberMiddleware;
+/**
+ * Transform events.
+ *
+ * @example
+ * ```typescript
+ * // Lowercase all event names
+ * const subscriber = applyMiddleware(adapter, [
+ *   transformMiddleware((event) => {
+ *     if (event.type === 'event') {
+ *       return { ...event, name: event.name.toLowerCase() };
+ *     }
+ *     return event;
+ *   })
+ * ]);
+ * ```
+ */
+declare function transformMiddleware(transformer: (event: EventsEvent) => EventsEvent): SubscriberMiddleware;
+/**
+ * Batch events and flush periodically.
+ *
+ * @example
+ * ```typescript
+ * const subscriber = applyMiddleware(adapter, [
+ *   batchingMiddleware({ batchSize: 100, flushInterval: 5000 })
+ * ]);
+ * ```
+ */
+declare function batchingMiddleware(options: {
+    batchSize?: number;
+    flushInterval?: number;
+}): SubscriberMiddleware;
+/**
+ * Rate limit events (throttle).
+ *
+ * @example
+ * ```typescript
+ * // Max 100 events per second
+ * const subscriber = applyMiddleware(adapter, [
+ *   rateLimitMiddleware({ requestsPerSecond: 100 })
+ * ]);
+ * ```
+ */
+declare function rateLimitMiddleware(options: {
+    requestsPerSecond: number;
+}): SubscriberMiddleware;
+/**
+ * Circuit breaker pattern.
+ *
+ * Opens circuit after N failures, prevents further requests for a timeout period.
+ *
+ * @example
+ * ```typescript
+ * const subscriber = applyMiddleware(adapter, [
+ *   circuitBreakerMiddleware({
+ *     failureThreshold: 5,
+ *     timeout: 60000 // 1 minute
+ *   })
+ * ]);
+ * ```
+ */
+declare function circuitBreakerMiddleware(options: {
+    failureThreshold?: number;
+    timeout?: number;
+    onOpen?: () => void;
+    onClose?: () => void;
+}): SubscriberMiddleware;
+/**
+ * Add timeout to events.
+ *
+ * @example
+ * ```typescript
+ * const subscriber = applyMiddleware(adapter, [
+ *   timeoutMiddleware({ timeoutMs: 5000 })
+ * ]);
+ * ```
+ */
+declare function timeoutMiddleware(options: {
+    timeoutMs: number;
+}): SubscriberMiddleware;
+
+export { type EventsEvent, type SubscriberMiddleware, applyMiddleware, batchingMiddleware, circuitBreakerMiddleware, enrichmentMiddleware, filterMiddleware, loggingMiddleware, rateLimitMiddleware, retryMiddleware, samplingMiddleware, timeoutMiddleware, transformMiddleware };