ocpp-ws-io 2.2.0 → 2.2.1

package/dist/plugins.d.ts

@@ -1,4 +1,4 @@
-import { O as OCPPPlugin } from './types-BunMs45p.js';
+import { O as OCPPPlugin } from './types-BHIHsj__.js';
 import 'ws';
 import 'node:https';
 import 'node:http';
@@ -8,6 +8,176 @@ import 'node:tls';
 import 'voltlog-io';
 import 'ajv';
 
+/**
+ * Options for the async worker plugin.
+ */
+interface AsyncWorkerOptions {
+    /**
+     * Maximum number of concurrent tasks.
+     * @default 10
+     */
+    concurrency?: number;
+    /**
+     * Maximum queue depth. When exceeded, tasks are handled per `overflowStrategy`.
+     * @default 1000
+     */
+    maxQueueSize?: number;
+    /**
+     * What to do when queue is full.
+     * - `"drop-oldest"`: Remove oldest queued task (default)
+     * - `"drop-newest"`: Reject the incoming task
+     * @default "drop-oldest"
+     */
+    overflowStrategy?: "drop-oldest" | "drop-newest";
+    /**
+     * Error handler for failed tasks.
+     */
+    onError?: (error: Error, taskName: string) => void;
+    /**
+     * Logger for queue warnings (overflow, drain).
+     */
+    logger?: {
+        warn: (...args: unknown[]) => void;
+    };
+    /**
+     * Drain timeout during shutdown (ms).
+     * The worker will attempt to complete in-flight tasks before force-closing.
+     * @default 5000
+     */
+    drainTimeoutMs?: number;
+}
+/**
+ * Extended OCPPPlugin exposing `enqueue()`, `queueSize()`, and `activeCount()`.
+ */
+interface AsyncWorkerPlugin extends OCPPPlugin {
+    /**
+     * Enqueue a task for non-blocking background execution.
+     * Returns immediately — the task runs asynchronously.
+     * @returns `true` if enqueued, `false` if dropped due to overflow.
+     */
+    enqueue(taskName: string, fn: () => Promise<void>): boolean;
+    /** Current number of tasks waiting in the queue. */
+    queueSize(): number;
+    /** Number of currently executing tasks. */
+    activeCount(): number;
+    /** Total number of tasks dropped due to overflow since init. */
+    droppedCount(): number;
+}
+/**
+ * Background task queue for non-blocking plugin I/O.
+ *
+ * Provides a bounded, concurrent work queue that plugins can use to offload
+ * slow operations (MQTT publish, DB write, HTTP call) without blocking the
+ * OCPP message processing loop.
+ *
+ * @example
+ * ```ts
+ * import { asyncWorkerPlugin } from 'ocpp-ws-io/plugins';
+ *
+ * const worker = asyncWorkerPlugin({ concurrency: 20, maxQueueSize: 5000 });
+ * server.plugin(worker);
+ *
+ * // From any hook:
+ * worker.enqueue("db-write", async () => {
+ *   await db.insert({ ... });
+ * });
+ * ```
+ */
+declare function asyncWorkerPlugin(options?: AsyncWorkerOptions): AsyncWorkerPlugin;
+
+/**
+ * Minimal AMQP channel contract — compatible with `amqplib`.
+ * Users bring their own AMQP dependency; this plugin does not bundle one.
+ */
+interface AmqpChannelLike {
+    /** Publish a message to an exchange with a routing key. */
+    publish(exchange: string, routingKey: string, content: Buffer, options?: Record<string, unknown>): boolean;
+    /** Close the channel. */
+    close(): Promise<void> | void;
+}
+type AmqpEvent = "connect" | "disconnect" | "message" | "security" | "auth_failed" | "eviction";
+/**
+ * Options for the AMQP plugin.
+ */
+interface AmqpPluginOptions {
+    /**
+     * User-provided AMQP channel (from `amqplib`).
+     * The plugin does NOT manage connections — users provide a ready channel.
+     *
+     * @example
+     * ```ts
+     * const conn = await amqp.connect('amqp://localhost');
+     * const channel = await conn.createChannel();
+     * await channel.assertExchange('ocpp.events', 'topic', { durable: true });
+     * ```
+     */
+    channel: AmqpChannelLike;
+    /**
+     * Exchange to publish to.
+     * @default "ocpp.events"
+     */
+    exchange?: string;
+    /**
+     * Routing key pattern. `{event}` and `{identity}` are interpolated.
+     * @default "ocpp.{event}.{identity}"
+     */
+    routingKey?: string;
+    /**
+     * Which events to publish.
+     * @default ["connect", "disconnect", "message", "security"]
+     */
+    events?: AmqpEvent[];
+    /**
+     * AMQP publish options.
+     */
+    publishOptions?: {
+        /** Mark messages as persistent (survives broker restart). @default true */
+        persistent?: boolean;
+        /** Message priority (0-9). */
+        priority?: number;
+        /** Content type header. @default "application/json" */
+        contentType?: string;
+    };
+    /**
+     * Include full message payloads.
+     * @default false
+     */
+    includePayload?: boolean;
+    /**
+     * Optional async worker for non-blocking publishes.
+     */
+    worker?: AsyncWorkerPlugin;
+}
+/**
+ * Publishes OCPP events to an AMQP exchange (RabbitMQ, Azure Service Bus, etc).
+ *
+ * For enterprise integrations where guaranteed delivery and topic-based
+ * routing are critical. Uses AMQP `topic` exchange by default so consumers
+ * can subscribe to specific event patterns.
+ *
+ * @example
+ * ```ts
+ * import amqp from 'amqplib';
+ * import { amqpPlugin } from 'ocpp-ws-io/plugins';
+ *
+ * const conn = await amqp.connect('amqp://localhost');
+ * const channel = await conn.createChannel();
+ * await channel.assertExchange('ocpp.events', 'topic', { durable: true });
+ *
+ * server.plugin(amqpPlugin({
+ *   channel,
+ *   exchange: 'ocpp.events',
+ *   events: ['connect', 'disconnect', 'message', 'security'],
+ * }));
+ *
+ * // Consumer binds:
+ * // ocpp.connect.*     — all connection events
+ * // ocpp.message.CP-101 — messages from CP-101
+ * // ocpp.security.*    — all security events
+ * ```
+ */
+declare function amqpPlugin(options: AmqpPluginOptions): OCPPPlugin;
+
 /**
  * Options for the anomaly detection plugin.
  */
@@ -15,19 +185,38 @@ interface AnomalyPluginOptions {
     /**
      * Maximum number of connections from the same identity
      * within the sliding window before triggering an anomaly.
-     * Default: 5
+     * @default 5
      */
     reconnectThreshold?: number;
     /**
      * Sliding window duration in milliseconds.
-     * Default: 60_000 (1 minute)
+     * @default 60_000 (1 minute)
      */
     windowMs?: number;
+    /**
+     * Maximum auth failures from the same IP within the window
+     * before triggering a brute-force anomaly.
+     * @default 5
+     */
+    authFailureThreshold?: number;
+    /**
+     * Maximum bad messages from the same identity within the window
+     * before triggering a fuzzing anomaly.
+     * @default 10
+     */
+    badMessageThreshold?: number;
+    /**
+     * Maximum evictions for the same identity within the window
+     * before triggering an identity-collision anomaly.
+     * @default 3
+     */
+    evictionThreshold?: number;
 }
 /**
- * Detects anomalous connection patterns such as rapid reconnections
- * from the same identity. Emits `securityEvent` on the server with
- * type `ANOMALY_RAPID_RECONNECT`.
+ * Detects anomalous connection patterns: rapid reconnections, brute-force
+ * auth attempts, message fuzzing, and identity-stealing races.
+ *
+ * Emits `securityEvent` on the server with typed anomaly identifiers.
  *
  * @example
  * ```ts
@@ -35,6 +224,8 @@ interface AnomalyPluginOptions {
  *
  * server.plugin(anomalyPlugin({
  *   reconnectThreshold: 10,
+ *   authFailureThreshold: 5,
+ *   badMessageThreshold: 20,
  *   windowMs: 60_000,
  * }));
  *
@@ -47,22 +238,122 @@ interface AnomalyPluginOptions {
  */
 declare function anomalyPlugin(options?: AnomalyPluginOptions): OCPPPlugin;
 
+/**
+ * Options for the circuit-breaker plugin.
+ */
+interface CircuitBreakerOptions {
+    /**
+     * Number of consecutive failures before the circuit opens.
+     * @default 5
+     */
+    failureThreshold?: number;
+    /**
+     * Duration in ms the circuit stays OPEN before attempting a HALF_OPEN probe.
+     * @default 30000 (30 seconds)
+     */
+    resetTimeoutMs?: number;
+    /**
+     * Maximum number of concurrent outgoing calls per client.
+     * When exceeded, calls are rejected immediately (fail-fast).
+     * @default 20
+     */
+    maxConcurrent?: number;
+    /**
+     * Optional callback when a circuit state changes.
+     * Useful for alerting/metrics integrations.
+     */
+    onStateChange?: (identity: string, from: CircuitState, to: CircuitState) => void;
+    /**
+     * Optional logger. Falls back to silent no-op.
+     */
+    logger?: {
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    };
+}
+type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/**
+ * Circuit Breaker Plugin (Level 2: Lifecycle Controller)
+ *
+ * Implements per-client circuit breaker pattern for flapping or unreliable
+ * charging stations. Prevents a misbehaving client from degrading system
+ * performance by fast-failing calls to clients exhibiting repeated errors.
+ *
+ * **State Machine:**
+ * ```
+ *   CLOSED ─(failures ≥ threshold)─→ OPEN
+ *   OPEN ─(resetTimeout expires)─→ HALF_OPEN
+ *   HALF_OPEN ─(success)─→ CLOSED
+ *   HALF_OPEN ─(failure)─→ OPEN
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { circuitBreakerPlugin } from 'ocpp-ws-io/plugins';
+ *
+ * server.plugin(circuitBreakerPlugin({
+ *   failureThreshold: 3,
+ *   resetTimeoutMs: 15_000,
+ *   onStateChange: (id, from, to) => {
+ *     console.log(`Circuit ${id}: ${from} → ${to}`);
+ *   },
+ * }));
+ * ```
+ */
+declare function circuitBreakerPlugin(options?: CircuitBreakerOptions): OCPPPlugin;
+
 /**
  * Options for the connection guard plugin.
  */
 interface ConnectionGuardOptions {
-    /** Maximum allowed concurrent connections. */
+    /**
+     * Maximum number of concurrent WebSocket connections.
+     * New connections beyond this limit are immediately closed.
+     */
     maxConnections: number;
+    /**
+     * Close code sent when the limit is exceeded.
+     * @default 4029
+     */
+    closeCode?: number;
+    /**
+     * Close reason sent when the limit is exceeded.
+     * @default "Connection limit reached"
+     */
+    closeReason?: string;
+    /**
+     * Force-close clients that exceed pong timeout (dead peers).
+     * Reclaims connection slots held by unresponsive clients.
+     * @default true
+     */
+    forceCloseOnPongTimeout?: boolean;
+    /**
+     * Force-close clients experiencing backpressure (slow consumers).
+     * Useful for freeing slots when a client can't keep up.
+     * @default false
+     */
+    forceCloseOnBackpressure?: boolean;
+    /**
+     * Logger for guard events.
+     */
+    logger?: {
+        warn: (...args: unknown[]) => void;
+    };
 }
 /**
- * Enforces a hard limit on concurrent connections.
- * New connections exceeding the limit are force-closed with code 4001.
+ * Enforces a hard cap on concurrent WebSocket connections.
+ * Optionally reclaims slots from dead peers (pong timeout) and
+ * slow consumers (backpressure).
  *
  * @example
  * ```ts
  * import { connectionGuardPlugin } from 'ocpp-ws-io/plugins';
  *
- * server.plugin(connectionGuardPlugin({ maxConnections: 5000 }));
+ * server.plugin(connectionGuardPlugin({
+ *   maxConnections: 1000,
+ *   forceCloseOnPongTimeout: true,
+ *   forceCloseOnBackpressure: false, // only enable if you want aggressive slot reclaim
+ * }));
  * ```
  */
 declare function connectionGuardPlugin(options: ConnectionGuardOptions): OCPPPlugin;
@@ -81,6 +372,168 @@ declare function connectionGuardPlugin(options: ConnectionGuardOptions): OCPPPlu
  */
 declare function heartbeatPlugin(): OCPPPlugin;
 
+/**
+ * Minimal Kafka Producer contract — compatible with `kafkajs`.
+ * Users bring their own Kafka dependency; this plugin does not bundle one.
+ */
+interface KafkaProducerLike {
+    send(record: {
+        topic: string;
+        messages: Array<{
+            key?: string | Buffer;
+            value: string | Buffer;
+            headers?: Record<string, string | Buffer>;
+        }>;
+        acks?: number;
+        timeout?: number;
+        compression?: number;
+    }): Promise<unknown>;
+}
+type KafkaEvent = "connect" | "disconnect" | "message" | "security" | "auth_failed" | "eviction";
+/**
+ * Options for the Kafka plugin.
+ */
+interface KafkaPluginOptions {
+    /**
+     * User-provided Kafka Producer (e.g. from `kafkajs`).
+     * The plugin does NOT manage connections — users provide a ready producer.
+     */
+    producer: KafkaProducerLike;
+    /**
+     * Base topic to publish to.
+     * If `topicRouting` is true, this is a prefix.
+     * @default "ocpp.events"
+     */
+    topic?: string;
+    /**
+     * If true, route events to specific topics instead of all to `topic`.
+     * e.g., `ocpp.events.message`, `ocpp.events.security`
+     * @default false
+     */
+    topicRouting?: boolean;
+    /**
+     * Which events to publish.
+     * @default ["connect", "disconnect", "message", "security"]
+     */
+    events?: KafkaEvent[];
+    /**
+     * Include full message payloads for message events.
+     * @default false
+     */
+    includePayload?: boolean;
+    /**
+     * Optional async worker for non-blocking publishes.
+     * Highly recommended for Kafka.
+     */
+    worker?: AsyncWorkerPlugin;
+}
+/**
+ * Publishes OCPP events to an Apache Kafka topic.
+ *
+ * Designed for high-throughput edge environments where raw OCPP telemetry
+ * needs to be streamed into big data architectures (Data Lakes, ClickHouse)
+ * for analysis.
+ *
+ * @example
+ * ```ts
+ * import { Kafka } from 'kafkajs';
+ *
+ * const kafka = new Kafka({ clientId: 'ocpp', brokers: ['localhost:9092'] });
+ * const producer = kafka.producer();
+ * await producer.connect();
+ *
+ * server.plugin(kafkaPlugin({
+ *   producer,
+ *   topic: 'ocpp.telemetry',
+ *   includePayload: true
+ * }));
+ * ```
+ */
+declare function kafkaPlugin(options: KafkaPluginOptions): OCPPPlugin;
+
+/**
+ * Minimal Redis interface for the Deduplication plugin.
+ * Supports **both** ioredis positional-arg style and node-redis v4 options-object style.
+ *
+ * Users bring their own Redis client (e.g., ioredis, node-redis).
+ */
+interface DedupRedisLike {
+    /**
+     * Sets a key with NX + PX semantics.
+     *
+     * **ioredis style:** `set(key, value, "PX", ms, "NX")` → `Promise<"OK" | null>`
+     * **node-redis v4 style:** `set(key, value, { PX: ms, NX: true })` → `Promise<string | null>`
+     */
+    set(key: string, value: string, ...args: unknown[]): Promise<"OK" | string | null> | ("OK" | string | null);
+}
+interface MessageDedupOptions {
+    /**
+     * User-provided Redis instance.
+     * Compatible with both `ioredis` and `node-redis` (v4+).
+     */
+    redis: DedupRedisLike;
+    /**
+     * Time-to-Live for the deduplication cache in milliseconds.
+     * @default 300000 (5 minutes)
+     */
+    ttlMs?: number;
+    /**
+     * Prefix for Redis keys.
+     * @default "ocpp:dedup:"
+     */
+    prefix?: string;
+    /**
+     * Which Redis calling convention to use:
+     * - `"positional"` (ioredis): `set(key, val, "PX", ms, "NX")`
+     * - `"options"` (node-redis v4): `set(key, val, { PX: ms, NX: true })`
+     * @default "positional"
+     */
+    redisStyle?: "positional" | "options";
+    /**
+     * Optional logger. Falls back to silent no-op if not provided.
+     */
+    logger?: {
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    };
+}
+/**
+ * Message Deduplication Plugin (Level 3: Interceptor)
+ *
+ * Prevents processing of duplicate messages from edge devices. When a bad
+ * mobile network connection causes a charging station to send the SAME
+ * message multiple times, this plugin catches and drops the duplicates
+ * before the application logic processes them.
+ *
+ * It hooks into `onBeforeReceive` and returns `false` to block execution
+ * if a message with the identical unique MessageID is found in Redis.
+ *
+ * @example ioredis (default)
+ * ```ts
+ * import Redis from 'ioredis';
+ * const redis = new Redis();
+ *
+ * server.plugin(messageDedupPlugin({
+ *   redis,
+ *   ttlMs: 60 * 1000 // Remember messages for 1 minute
+ * }));
+ * ```
+ *
+ * @example node-redis v4
+ * ```ts
+ * import { createClient } from 'redis';
+ * const redis = createClient();
+ * await redis.connect();
+ *
+ * server.plugin(messageDedupPlugin({
+ *   redis,
+ *   redisStyle: 'options',
+ *   ttlMs: 60 * 1000,
+ * }));
+ * ```
+ */
+declare function messageDedupPlugin(options: MessageDedupOptions): OCPPPlugin;
+
 /**
  * Snapshot of tracked server metrics at a point in time.
  */
@@ -99,6 +552,36 @@ interface MetricsSnapshot {
     uptimeMs: number;
     /** ISO timestamp of this snapshot */
     timestamp: string;
+    /** Total inbound messages received */
+    totalMessagesIn: number;
+    /** Total outbound messages sent */
+    totalMessagesOut: number;
+    /** Total CALL messages */
+    totalCalls: number;
+    /** Total CALLRESULT messages */
+    totalCallResults: number;
+    /** Total CALLERROR messages */
+    totalCallErrors: number;
+    /** Total WebSocket/protocol errors */
+    totalErrors: number;
+    /** Total malformed/unparseable messages */
+    totalBadMessages: number;
+    /** Total user handler errors */
+    totalHandlerErrors: number;
+    /** Total rate limit hits */
+    totalRateLimitHits: number;
+    /** Total auth failures */
+    totalAuthFailures: number;
+    /** Total client evictions */
+    totalEvictions: number;
+    /** Total backpressure events */
+    totalBackpressureEvents: number;
+    /** Total pong timeouts (dead peers) */
+    totalPongTimeouts: number;
+    /** Total schema validation failures */
+    totalValidationFailures: number;
+    /** Total security events (from anomaly detector etc.) */
+    totalSecurityEvents: number;
 }
 /**
  * Options for the metrics plugin.
@@ -117,8 +600,12 @@ interface MetricsPlugin extends OCPPPlugin {
     getMetrics(): MetricsSnapshot;
 }
 /**
- * Tracks real-time server metrics: connection counters, peak, average duration.
+ * Tracks comprehensive real-time server metrics: connection counters, message
+ * throughput, error rates, security events, and peak values.
+ *
  * Access metrics anytime via `.getMetrics()` on the returned plugin instance.
+ * Automatically exports all counters to the Prometheus `/metrics` endpoint
+ * via `getCustomMetrics()`.
  *
  * @example
  * ```ts
@@ -126,7 +613,7 @@ interface MetricsPlugin extends OCPPPlugin {
  *
  * const metrics = metricsPlugin({
  *   intervalMs: 10_000,
- *   onSnapshot: (snap) => console.log(`Active: ${snap.activeConnections}`),
+ *   onSnapshot: (snap) => console.log(`Active: ${snap.activeConnections}, Msgs: ${snap.totalMessagesIn}`),
  * });
  * server.plugin(metrics);
  *
@@ -136,6 +623,107 @@ interface MetricsPlugin extends OCPPPlugin {
  */
 declare function metricsPlugin(options?: MetricsPluginOptions): MetricsPlugin;
 
+/**
+ * Minimal MQTT client contract — compatible with `mqtt.js`, `aedes`, etc.
+ * Users bring their own MQTT dependency; this plugin does not bundle one.
+ */
+interface MqttClientLike {
+    publish(topic: string, message: string | Buffer, opts?: {
+        qos?: number;
+        retain?: boolean;
+    }, callback?: (err?: Error) => void): unknown;
+    end(force?: boolean, callback?: () => void): void;
+    connected: boolean;
+}
+type MqttEvent = "connect" | "disconnect" | "message" | "security" | "error" | "auth_failed" | "eviction";
+/**
+ * Options for the MQTT plugin.
+ */
+interface MqttPluginOptions {
+    /**
+     * User-provided MQTT client instance (e.g., `mqtt.connect(...)`).
+     * The plugin does NOT install `mqtt` — users bring their own.
+     */
+    client: MqttClientLike;
+    /**
+     * Topic prefix for all published messages.
+     * Identity is appended: `{prefix}/{identity}/{event}`
+     * @default "ocpp"
+     */
+    topicPrefix?: string;
+    /**
+     * Which events to publish.
+     * @default ["connect", "disconnect", "message", "security"]
+     */
+    events?: MqttEvent[];
+    /**
+     * QoS level for published messages.
+     * - 0: at most once (fire-and-forget, fastest)
+     * - 1: at least once (with ack)
+     * - 2: exactly once (slowest)
+     * @default 0
+     */
+    qos?: 0 | 1 | 2;
+    /**
+     * Whether to publish full message payloads or just metadata.
+     * @default false
+     */
+    includePayload?: boolean;
+    /**
+     * Custom topic builder for full control over topic structure.
+     * If set, overrides `topicPrefix`.
+     */
+    topicBuilder?: (event: string, identity?: string) => string;
+    /**
+     * Transform the payload before publishing.
+     * Useful for filtering sensitive data or reformatting.
+     */
+    transform?: (payload: Record<string, unknown>) => Record<string, unknown>;
+    /**
+     * Optional async worker for non-blocking publishes.
+     * When provided, all publish calls are enqueued to the worker.
+     */
+    worker?: AsyncWorkerPlugin;
+}
+/**
+ * Publishes OCPP events to an MQTT broker.
+ *
+ * Essential for IoT-style architectures where charging stations, fleet
+ * management systems, and monitoring dashboards subscribe to live OCPP feeds.
+ *
+ * @example
+ * ```ts
+ * import mqtt from 'mqtt';
+ * import { mqttPlugin } from 'ocpp-ws-io/plugins';
+ *
+ * const client = mqtt.connect('mqtt://broker:1883');
+ *
+ * server.plugin(mqttPlugin({
+ *   client,
+ *   topicPrefix: 'ocpp/v1',
+ *   events: ['connect', 'disconnect', 'message'],
+ *   qos: 1,
+ * }));
+ * ```
+ *
+ * @example With async worker for non-blocking
+ * ```ts
+ * import { asyncWorkerPlugin, mqttPlugin } from 'ocpp-ws-io/plugins';
+ *
+ * const worker = asyncWorkerPlugin({ concurrency: 20 });
+ * server.plugin(worker, mqttPlugin({ client, worker }));
+ * ```
+ *
+ * @example Topic structure
+ * ```
+ * ocpp/CP-101/connect      → { identity, ip, protocol, timestamp }
+ * ocpp/CP-101/message/IN   → { method, messageType, timestamp }
+ * ocpp/CP-101/disconnect    → { code, reason, durationSec }
+ * ocpp/security             → { type, identity, ip, details }
+ * ```
+ */
+declare function mqttPlugin(options: MqttPluginOptions): OCPPPlugin;
+
 /**
  * Options for the OpenTelemetry plugin.
  */
@@ -149,17 +737,20 @@ interface OtelPluginOptions {
      */
     tracer?: {
         startSpan: (name: string, options?: Record<string, unknown>) => {
-            setAttribute: (key: string, value: string | number) => void;
+            setAttribute: (key: string, value: string | number | boolean) => void;
             setStatus: (status: {
                 code: number;
                 message?: string;
             }) => void;
+            addEvent: (name: string, attributes?: Record<string, unknown>) => void;
+            recordException: (error: Error) => void;
             end: () => void;
         };
     };
 }
 /**
- * OpenTelemetry integration — creates spans for connection lifecycle events.
+ * OpenTelemetry integration — creates spans for connection lifecycle,
+ * individual OCPP messages, errors, and security events.
  *
  * Requires `@opentelemetry/api` as an **optional peer dependency**.
  * If not installed or no tracer is provided, the plugin becomes a silent no-op.
@@ -182,40 +773,440 @@ interface OtelPluginOptions {
  */
 declare function otelPlugin(options?: OtelPluginOptions): OCPPPlugin;
 
+interface PiiRedactorOptions {
+    /**
+     * List of object keys that should be redacted.
+     * Matches ANY key in the payload recursively.
+     * @default ["idTag", "authorizationKey", "token", "password", "securityCode"]
+     */
+    sensitiveKeys?: string[];
+    /**
+     * The replacement string to use for redacted values.
+     * @default "***REDACTED***"
+     */
+    replacement?: string;
+    /**
+     * Enable/disable redaction for incoming messages.
+     * @default true
+     */
+    incoming?: boolean;
+    /**
+     * Enable/disable redaction for outgoing messages.
+     * @default true
+     */
+    outgoing?: boolean;
+}
+/**
+ * Redacts sensitive Personally Identifiable Information (PII) from message payloads.
+ *
+ * As a Level 4 (Middleware) plugin, this executes directly in the message processing chain.
+ * It recursively scans and masks sensitive fields (e.g., `idTag`, `password`) in both
+ * incoming and outgoing payloads. Because it mutates the payload inline, the redacted
+ * data will be what application handlers, downstream plugins, and observability tools see.
+ *
+ * @example
+ * ```ts
+ * server.plugin(piiRedactorPlugin({
+ *   sensitiveKeys: ['idTag', 'password', 'authorizationKey'],
+ *   replacement: '[HIDDEN]'
+ * }));
+ * ```
+ */
+declare function piiRedactorPlugin(options?: PiiRedactorOptions): OCPPPlugin;
+
+/**
+ * Destination for rate-limit alerts.
+ */
+interface AlertSink {
+    /** Send an alert payload. Returns a promise that resolves on success. */
+    send(payload: RateLimitAlert): void | Promise<void>;
+}
+interface RateLimitAlert {
+    /** The event type that triggered the alert */
+    eventType: "RATE_LIMIT_EXCEEDED" | "CONNECTION_RATE_LIMIT";
+    /** Station identity (if known) */
+    identity?: string;
+    /** Remote IP address */
+    ip?: string;
+    /** ISO 8601 timestamp of the event */
+    timestamp: string;
+    /** Number of times the event occurred in the current window */
+    count: number;
+    /** Window duration in ms */
+    windowMs: number;
+}
+interface RateLimitNotifierOptions {
+    /**
+     * Where to send alerts. Can be a webhook URL (string), a Kafka-like sink
+     * object, or any object with a `send(payload)` method.
+     *
+     * @example Webhook URL
+     * ```ts
+     * rateLimitNotifierPlugin({ sink: 'https://alerts.example.com/hook' })
+     * ```
+     *
+     * @example Custom sink
+     * ```ts
+     * rateLimitNotifierPlugin({
+     *   sink: {
+     *     send: (alert) => kafka.send({ topic: 'rate-limits', messages: [{ value: JSON.stringify(alert) }] })
+     *   }
+     * })
+     * ```
+     */
+    sink: string | AlertSink;
+    /**
+     * Minimum interval (ms) between alerts for the same identity.
+     * Prevents alert storms.
+     * @default 60000 (1 minute)
+     */
+    cooldownMs?: number;
+    /**
+     * Number of rate-limit events before an alert is sent.
+     * @default 1
+     */
+    threshold?: number;
+    /**
+     * Sliding window in ms to count rate limit events.
+     * @default 300000 (5 minutes)
+     */
+    windowMs?: number;
+    /**
+     * Custom HTTP headers for webhook sink.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Optional logger.
+     */
+    logger?: {
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    };
+}
+/**
+ * Rate Limit Notifier Plugin (Level 1: Passive Hook)
+ *
+ * Fires alerts to an external sink (webhook URL or custom sink) whenever a
+ * client exceeds the server's rate limit. Implements per-identity cooldown
+ * and threshold-based alerting to prevent alert storms.
+ *
+ * @example
+ * ```ts
+ * server.plugin(rateLimitNotifierPlugin({
+ *   sink: 'https://slack.example.com/webhook',
+ *   cooldownMs: 120_000,
+ *   threshold: 3,
+ * }));
+ * ```
+ */
+declare function rateLimitNotifierPlugin(options: RateLimitNotifierOptions): OCPPPlugin;
+
+/**
+ * Minimal Redis client contract — compatible with `ioredis` and `node-redis`.
+ * Users bring their own Redis dependency; this plugin does not bundle one.
+ */
+interface RedisClientLike {
+    /** Publish to a Pub/Sub channel. */
+    publish(channel: string, message: string): Promise<number> | unknown;
+    /** Append to a Redis Stream (optional — only needed for stream mode). */
+    xadd?(key: string, ...args: (string | number)[]): Promise<string | null> | unknown;
+    /** Graceful disconnect. */
+    quit?(): Promise<unknown> | unknown;
+    disconnect?(): void;
+}
+type RedisPubSubEvent = "connect" | "disconnect" | "message" | "security" | "auth_failed" | "eviction";
+/**
+ * Options for the Redis Pub/Sub plugin.
+ */
+interface RedisPubSubPluginOptions {
+    /**
+     * User-provided Redis client for publishing.
+     * Supports ioredis or node-redis compatible clients.
+     */
+    client: RedisClientLike;
+    /**
+     * Publishing mode:
+     * - `"pubsub"`: Uses PUBLISH to channels (real-time subscribers)
+     * - `"stream"`: Uses XADD to Redis Streams (persistent, consumer groups)
+     * @default "pubsub"
+     */
+    mode?: "pubsub" | "stream";
+    /**
+     * Channel/stream key prefix.
+     * @default "ocpp"
+     */
+    prefix?: string;
+    /**
+     * Which events to publish.
+     * @default ["connect", "disconnect", "message", "security"]
+     */
+    events?: RedisPubSubEvent[];
+    /**
+     * For stream mode: max stream length (MAXLEN ~approximate trimming).
+     * Older entries are trimmed automatically.
+     * @default 10000
+     */
+    maxStreamLength?: number;
+    /**
+     * Include full message payloads.
+     * @default false
+     */
+    includePayload?: boolean;
+    /**
+     * Custom serializer.
+     * @default JSON.stringify
+     */
+    serialize?: (data: Record<string, unknown>) => string;
+    /**
+     * Optional async worker for non-blocking publishes.
+     */
+    worker?: AsyncWorkerPlugin;
+}
+/**
+ * Publishes OCPP events to Redis Pub/Sub channels or Redis Streams.
+ *
+ * Ideal for microservice architectures where billing, analytics, and alerting
+ * services subscribe to OCPP feeds, or for durable event sourcing via Streams.
+ *
+ * @example Pub/Sub mode
+ * ```ts
+ * import Redis from 'ioredis';
+ * import { redisPubSubPlugin } from 'ocpp-ws-io/plugins';
+ *
+ * const redis = new Redis();
+ * server.plugin(redisPubSubPlugin({
+ *   client: redis,
+ *   mode: 'pubsub',
+ *   prefix: 'ocpp',
+ *   events: ['connect', 'disconnect', 'message'],
+ * }));
+ * // Subscribers: redis.subscribe('ocpp:connect')
+ * ```
+ *
+ * @example Stream mode (durable)
+ * ```ts
+ * server.plugin(redisPubSubPlugin({
+ *   client: redis,
+ *   mode: 'stream',
+ *   maxStreamLength: 50000,
+ * }));
+ * // Consumers: redis.xreadgroup('GROUP', 'mygroup', 'consumer1', ...)
+ * ```
+ */
+declare function redisPubSubPlugin(options: RedisPubSubPluginOptions): OCPPPlugin;
+
+interface ReplayRedisLike {
+    rpush(key: string, ...values: string[]): Promise<number>;
+    lpop(key: string): Promise<string | null>;
+}
+interface ReplayBufferOptions {
+    /** User-provided Redis instance */
+    redis: ReplayRedisLike;
+    /**
+     * Prefix for Redis keys
+     * @default "ocpp:replay:"
+     */
+    prefix?: string;
+    /**
+     * If true, queued messages will return a synthetic response to the caller
+     * immediately, rather than letting the caller timeout or fail.
+     * @default true
+     */
+    syntheticResponse?: boolean;
+    /**
+     * Maximum number of messages to flush concurrently on reconnection.
+     * Prevents overwhelming a freshly-connected client.
+     * @default 5
+     */
+    flushConcurrency?: number;
+    /**
+     * Delay in ms between each flush batch to avoid overwhelming the client.
+     * @default 200
+     */
+    flushDelayMs?: number;
+    /**
+     * Optional logger. Falls back to silent no-op if not provided.
+     */
+    logger?: {
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    };
+}
+/**
+ * Replay Buffer Plugin (Level 3: Interceptor)
+ *
+ * Provides a persistent, distributed offline queue for backend-initiated
+ * commands (like RemoteStopTransaction or UnlockConnector).
+ *
+ * If a call is made to an offline client, this plugin intercepts the error,
+ * queues the message in Redis, and automatically flushes the queue when the
+ * client reconnects (even if it reconnects to a different server node).
+ *
+ * @example
+ * ```ts
+ * server.plugin(replayBufferPlugin({
+ *   redis,
+ *   flushConcurrency: 3,
+ *   logger: pino(),
+ * }));
+ * ```
+ */
+declare function replayBufferPlugin(options: ReplayBufferOptions): OCPPPlugin;
+
+/**
+ * A transformation rule for a specific OCPP method/action.
+ */
+interface TransformRule {
+    /**
+     * The method name to match (e.g., "BootNotification", "StatusNotification").
+     * Supports exact match or wildcard "*" for all methods.
+     */
+    method: string;
+    /**
+     * Transform function for the payload.
+     * Receives the current payload and source/target versions.
+     * Must return the transformed payload.
+     */
+    transform: (payload: Record<string, unknown>, direction: "up" | "down") => Record<string, unknown>;
+}
+interface SchemaVersioningOptions {
+    /**
+     * Source OCPP version identifier (e.g., "ocpp1.6" or "ocpp2.0.1").
+     * This is the version used by the charging station (client).
+     */
+    sourceVersion: string;
+    /**
+     * Target OCPP version identifier (e.g., "ocpp2.0.1" or "ocpp1.6").
+     * This is the version the application handlers expect.
+     */
+    targetVersion: string;
+    /**
+     * Array of transformation rules for specific OCPP actions.
+     * Rules are checked in order; the first matching rule is applied.
+     */
+    rules: TransformRule[];
+    /**
+     * How to handle methods without a transform rule:
+     * - "passthrough": Forward as-is
+     * - "reject": Drop the message
+     * @default "passthrough"
+     */
+    unmatchedBehavior?: "passthrough" | "reject";
+    /**
+     * Optional: Only apply transformations when client protocol matches this version.
+     * If not set, applies to all clients.
+     */
+    applyWhen?: string;
+    /**
+     * Optional logger.
+     */
+    logger?: {
+        warn: (...args: unknown[]) => void;
+        debug?: (...args: unknown[]) => void;
+    };
+}
+/**
+ * Schema Versioning Plugin (Level 4: Middleware)
+ *
+ * Provides OCPP version transformation between 1.6 and 2.0.1 payloads.
+ * This plugin sits in the middleware chain and transforms message payloads
+ * between protocol versions, enabling a server to support mixed-version
+ * charging station fleets with unified application handlers.
+ *
+ * **Architecture:**
+ * ```
+ * Station (1.6) ──→ [Transform to 2.0.1] ──→ Application Handler
+ * Station (1.6) ←── [Transform to 1.6]   ←── Application Handler
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { schemaVersioningPlugin } from 'ocpp-ws-io/plugins';
+ *
+ * server.plugin(schemaVersioningPlugin({
+ *   sourceVersion: 'ocpp1.6',
+ *   targetVersion: 'ocpp2.0.1',
+ *   rules: [
+ *     {
+ *       method: 'BootNotification',
+ *       transform: (payload, direction) => {
+ *         if (direction === 'up') {
+ *           // 1.6 → 2.0.1: Wrap in chargingStation object
+ *           return {
+ *             chargingStation: {
+ *               model: payload.chargePointModel,
+ *               vendorName: payload.chargePointVendor,
+ *               serialNumber: payload.chargePointSerialNumber,
+ *               firmwareVersion: payload.firmwareVersion,
+ *             },
+ *             reason: 'PowerUp',
+ *           };
+ *         }
+ *         // 2.0.1 → 1.6: Flatten chargingStation
+ *         const cs = payload.chargingStation as Record<string, unknown> ?? {};
+ *         return {
+ *           chargePointModel: cs.model,
+ *           chargePointVendor: cs.vendorName,
+ *           chargePointSerialNumber: cs.serialNumber,
+ *           firmwareVersion: cs.firmwareVersion,
+ *         };
+ *       },
+ *     },
+ *   ],
+ * }));
+ * ```
+ */
+declare function schemaVersioningPlugin(options: SchemaVersioningOptions): OCPPPlugin;
+
 /**
  * Options for the session log plugin.
  */
 interface SessionLogOptions {
     /**
-     * Custom logger instance. Defaults to `console`.
-     * Must have `info` method.
+     * Logger instance. Must have at least `info` and `warn`.
+     * @default console
      */
     logger?: {
-        info: (msg: string, meta?: Record<string, unknown>) => void;
+        info: (...args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+        error?: (...args: unknown[]) => void;
     };
+    /**
+     * Logging verbosity level:
+     * - `"minimal"`: connect/disconnect only
+     * - `"standard"`: + errors, auth failures, evictions
+     * - `"verbose"`: + bad messages, security events
+     * @default "standard"
+     */
+    logLevel?: "minimal" | "standard" | "verbose";
 }
 /**
- * Logs connect/disconnect events with identity, IP, protocol, and connection duration.
+ * Structured session lifecycle logger.
+ *
+ * Logs connection events, errors, auth failures, and evictions at
+ * configurable verbosity levels.
  *
  * @example
  * ```ts
  * import { sessionLogPlugin } from 'ocpp-ws-io/plugins';
  *
- * server.plugin(sessionLogPlugin());
- * // => Connected: CP-101 from 192.168.1.1 via ocpp1.6
- * // => Disconnected: CP-101 after 3600s (code: 1000)
+ * server.plugin(sessionLogPlugin({
+ *   logLevel: 'verbose',
+ *   logger: pino(),
+ * }));
  * ```
  */
 declare function sessionLogPlugin(options?: SessionLogOptions): OCPPPlugin;
 
+type WebhookEvent = "init" | "connect" | "disconnect" | "close" | "security" | "auth_failed" | "eviction" | "closing";
 /**
  * Options for the webhook plugin.
  */
 interface WebhookPluginOptions {
     /** Webhook HTTP endpoint URL. */
     url: string;
-    /** Which lifecycle events to send (default: all). */
-    events?: Array<"init" | "connect" | "disconnect" | "close">;
+    /** Which lifecycle events to send (default: lifecycle events only). */
+    events?: WebhookEvent[];
     /** Custom HTTP headers to include (e.g. Authorization). */
     headers?: Record<string, string>;
     /** HMAC-SHA256 secret for signing payloads (sent as `X-Signature` header). */
@@ -226,7 +1217,7 @@ interface WebhookPluginOptions {
     retries?: number;
 }
 /**
- * Sends HTTP POST webhooks on server lifecycle events.
+ * Sends HTTP POST webhooks on server lifecycle and security events.
  * Uses Node.js built-in `fetch` (Node 18+).
  *
  * @example
@@ -236,11 +1227,11 @@ interface WebhookPluginOptions {
  * server.plugin(webhookPlugin({
  *   url: 'https://api.example.com/ocpp-events',
  *   secret: process.env.WEBHOOK_SECRET,
- *   events: ['connect', 'disconnect'],
+ *   events: ['connect', 'disconnect', 'security', 'auth_failed'],
  *   headers: { Authorization: 'Bearer token123' },
  * }));
  * ```
  */
 declare function webhookPlugin(options: WebhookPluginOptions): OCPPPlugin;
 
-export { type AnomalyPluginOptions, type ConnectionGuardOptions, type MetricsPlugin, type MetricsPluginOptions, type MetricsSnapshot, type OtelPluginOptions, type SessionLogOptions, type WebhookPluginOptions, anomalyPlugin, connectionGuardPlugin, heartbeatPlugin, metricsPlugin, otelPlugin, sessionLogPlugin, webhookPlugin };
+export { type AlertSink, type AmqpChannelLike, type AmqpPluginOptions, type AnomalyPluginOptions, type AsyncWorkerOptions, type AsyncWorkerPlugin, type CircuitBreakerOptions, type CircuitState, type ConnectionGuardOptions, type DedupRedisLike, type KafkaPluginOptions, type KafkaProducerLike, type MessageDedupOptions, type MetricsPlugin, type MetricsPluginOptions, type MetricsSnapshot, type MqttClientLike, type MqttPluginOptions, type OtelPluginOptions, type PiiRedactorOptions, type RateLimitAlert, type RateLimitNotifierOptions, type RedisClientLike, type RedisPubSubPluginOptions, type ReplayBufferOptions, type ReplayRedisLike, type SchemaVersioningOptions, type SessionLogOptions, type TransformRule, type WebhookPluginOptions, amqpPlugin, anomalyPlugin, asyncWorkerPlugin, circuitBreakerPlugin, connectionGuardPlugin, heartbeatPlugin, kafkaPlugin, messageDedupPlugin, metricsPlugin, mqttPlugin, otelPlugin, piiRedactorPlugin, rateLimitNotifierPlugin, redisPubSubPlugin, replayBufferPlugin, schemaVersioningPlugin, sessionLogPlugin, webhookPlugin };