ocpp-ws-io 2.1.15 → 2.2.1

package/dist/{types-BZXEmDQ1.d.ts → types-BHIHsj__.d.ts}

@@ -4735,6 +4735,16 @@ declare class OCPPClient<P extends OCPPProtocol = OCPPProtocol> extends OCPPClie
     sendRaw(message: string): void;
     reconfigure(options: Partial<ClientOptions>): void;
     protected _attachWebsocket(ws: WebSocket__default): void;
+    /**
+     * Build an enriched message event context from middleware context.
+     * Adds timestamp and optional latency metadata.
+     */
+    private _buildMessageEventContext;
+    /**
+     * Emit a message event with enriched payload (direction + context).
+     * Replaces separate call/callResult/callError events for unified observability.
+     */
+    private _emitMessageEvent;
     protected _onMessage(rawData: WebSocket__default.RawData, preParsed?: unknown): void;
     private _handleIncomingCall;
     private _handleCallResult;
@@ -4762,6 +4772,11 @@ declare class OCPPClient<P extends OCPPProtocol = OCPPProtocol> extends OCPPClie
     private _callWithRetry;
     /** Maximum bytes allowed in the ws send buffer before applying backpressure (512KB) */
     private static readonly _BACKPRESSURE_THRESHOLD;
+    /**
+     * Protected hook for plugins to intercept outbound messages before serialization.
+     * Return `false` to suppress the message transmission.
+     */
+    protected _invokeBeforeSend(_message: OCPPMessage): boolean | Promise<boolean>;
     /**
      * Wraps ws.send() with backpressure protection.
      * If bufferedAmount exceeds the threshold, waits for the buffer to drain
@@ -4826,6 +4841,8 @@ declare class WorkerPool {
 declare class OCPPServerClient extends OCPPClient {
     private _serverSession;
     private _serverHandshake;
+    /** Plugins passed from OCPPServer for hook execution */
+    private _serverPlugins;
     constructor(options: ClientOptions, context: {
         ws: WebSocket$1;
         handshake: HandshakeInfo;
@@ -4835,11 +4852,14 @@ declare class OCPPServerClient extends OCPPClient {
         adaptiveMultiplier?: () => number;
         /** Optional worker pool for off-thread JSON parsing */
         workerPool?: WorkerPool;
+        /** Plugins from the server for hook execution */
+        plugins?: OCPPPlugin[];
     });
     private _rateLimits;
     private _adaptiveMultiplier;
     private _workerPool;
     private _checkRateLimit;
+    protected _invokeBeforeSend(message: OCPPMessage): boolean | Promise<boolean>;
     private _attachServerWebsocket;
     private _handleRateLimitExceeded;
     /**
@@ -4899,6 +4919,7 @@ declare class OCPPServer extends OCPPServer_base {
     private _adaptiveLimiter;
     private _plugins;
     private _workerPool;
+    private _telemetryInterval;
     private readonly _nodeId;
     private _sessions;
     private _gcInterval;
@@ -4977,6 +4998,11 @@ declare class OCPPServer extends OCPPServer_base {
      * ```
      */
     plugin(...plugins: OCPPPlugin[]): this;
+    /**
+     * Starts the periodic telemetry push engine if configured.
+     * Pushes OCPPServerStats to all plugins implementing onTelemetry.
+     */
+    private _startTelemetryPush;
     /**
      * Registers middleware chain(s) as a wildcard/catch-all router.
      *
@@ -5621,6 +5647,15 @@ interface ServerOptionsBase {
      * (default: false)
      */
     compression?: boolean | CompressionOptions;
+    /**
+     * Telemetry configuration for plugin stats push.
+     * When configured and plugins implement `onTelemetry`, the server will
+     * push `OCPPServerStats` at the configured interval.
+     * - `{ pushIntervalMs: 10000 }` → push stats every 10s
+     * - `{ pushIntervalMs: 0 }` → disable periodic push
+     * (default: disabled)
+     */
+    telemetry?: TelemetryConfig;
 }
 /** When strictMode is enabled, protocols MUST be specified */
 interface StrictServerOptions extends ServerOptionsBase {
@@ -5633,6 +5668,13 @@ interface RelaxedServerOptions extends ServerOptionsBase {
     protocols?: AnyOCPPProtocol[];
 }
 type ServerOptions = StrictServerOptions | RelaxedServerOptions;
+interface TelemetryConfig {
+    /**
+     * Interval in ms to push server stats to plugins via `onTelemetry`.
+     * Set to 0 to disable. (default: 0 — disabled)
+     */
+    pushIntervalMs?: number;
+}
 interface OCPPServerStats {
     /** Number of currently connected WebSockets */
     connectedClients: number;
@@ -5669,6 +5711,30 @@ interface AuthAccept<TSession = Record<string, unknown>> {
     session?: TSession;
 }
 type AuthCallback<TSession = Record<string, unknown>> = (ctx: AuthContext<TSession>) => void | Promise<void>;
+/** Indicates whether a message is incoming (from peer) or outgoing (to peer) */
+type MessageDirection = "IN" | "OUT";
+/**
+ * Enriched context for message events, combining metadata from middleware
+ * and message flow tracking. Uses type intersection since MiddlewareContext is a union.
+ */
+type MessageEventContext = MiddlewareContext & {
+    /** Message timestamp (ISO 8601) */
+    timestamp: string;
+    /** Latency in milliseconds (only for responses/results) */
+    latencyMs?: number;
+};
+/**
+ * Enriched message event payload with direction and context.
+ * Replaces the simple OCPPMessage tuple for better observability.
+ */
+interface MessageEventPayload {
+    /** The raw OCPP message */
+    message: OCPPMessage;
+    /** Direction of the message: IN (from peer) or OUT (to peer) */
+    direction: MessageDirection;
+    /** Enriched context with metadata */
+    ctx: MessageEventContext;
+}
 interface ClientEvents {
     open: [{
         response: IncomingMessage;
@@ -5689,7 +5755,7 @@ interface ClientEvents {
         attempt: number;
         delay: number;
     }];
-    message: [OCPPMessage];
+    message: [MessageEventPayload];
     call: [OCPPCall];
     callResult: [OCPPCallResult];
     callError: [OCPPCallError];
@@ -5697,6 +5763,20 @@ interface ClientEvents {
         message: string;
         error: Error;
     }];
+    handlerError: [{
+        method: string;
+        error: Error;
+    }];
+    pongTimeout: [{
+        identity: string;
+    }];
+    backpressure: [{
+        identity: string;
+        bufferedAmount: number;
+    }];
+    rateLimitExceeded: [{
+        rawData: unknown;
+    }];
     ping: [];
     pong: [];
     strictValidationFailure: [{
@@ -5711,7 +5791,7 @@ interface ClientEvents {
  */
 interface SecurityEvent {
     /** Event type identifier */
-    type: "AUTH_FAILED" | "RATE_LIMIT_EXCEEDED" | "UPGRADE_ABORTED" | "CONNECTION_RATE_LIMIT" | "INVALID_PAYLOAD";
+    type: "AUTH_FAILED" | "RATE_LIMIT_EXCEEDED" | "UPGRADE_ABORTED" | "CONNECTION_RATE_LIMIT" | "INVALID_PAYLOAD" | "ANOMALY_RAPID_RECONNECT" | "ANOMALY_AUTH_BRUTE_FORCE" | "ANOMALY_MESSAGE_FUZZING" | "ANOMALY_IDENTITY_COLLISION";
     /** Station identity (if known) */
     identity?: string;
     /** Remote IP address */
@@ -5740,6 +5820,8 @@ interface ServerEvents {
     close: [];
     /** I3: Structured security event for SIEM/audit pipelines */
     securityEvent: [SecurityEvent];
+    /** Enriched message event with direction and context */
+    message: [MessageEventPayload];
     connection: [
         socket: WebSocket.WebSocket,
         request: node_http.IncomingMessage
@@ -5803,6 +5885,54 @@ interface OCPPPlugin {
     onDisconnect?(client: OCPPServerClient, code: number, reason: string): void;
     /** Called during server.close() for plugin cleanup */
     onClose?(): void | Promise<void>;
+    /**
+     * Called for every OCPP message (IN + OUT, CALL + CALLRESULT + CALLERROR).
+     * Provides unified observability over all message traffic.
+     */
+    onMessage?(client: OCPPServerClient, payload: MessageEventPayload): void | Promise<void>;
+    /**
+     * Called before a received message is parsed/routed.
+     * Return `false` to silently drop the message.
+     */
+    onBeforeReceive?(client: OCPPServerClient, rawData: unknown): undefined | boolean | Promise<undefined | boolean>;
+    /**
+     * Called before a message is transmitted on the wire.
+     * Return `false` to suppress the send.
+     */
+    onBeforeSend?(client: OCPPServerClient, message: OCPPMessage): undefined | boolean | Promise<undefined | boolean>;
+    /** WebSocket-level or protocol-level error */
+    onError?(client: OCPPServerClient, error: Error): void | Promise<void>;
+    /** Malformed / unparseable message received */
+    onBadMessage?(client: OCPPServerClient, rawMessage: string, error: Error): void | Promise<void>;
+    /** Schema validation failure (strictMode) */
+    onValidationFailure?(client: OCPPServerClient, message: unknown, error: Error): void | Promise<void>;
+    /** Message dropped or client disconnected due to rate limiting */
+    onRateLimitExceeded?(client: OCPPServerClient, rawData: unknown): void | Promise<void>;
+    /** User handler threw an error during CALL processing */
+    onHandlerError?(client: OCPPServerClient, method: string, error: Error): void | Promise<void>;
+    /** Structured security events (AUTH_FAILED, UPGRADE_ABORTED, etc.) */
+    onSecurityEvent?(event: SecurityEvent): void | Promise<void>;
+    /** Auth attempt failed — visible even when onConnection never fires */
+    onAuthFailed?(handshake: HandshakeInfo, code: number, reason: string): void | Promise<void>;
+    /** Existing client with same identity was evicted by a new connection */
+    onEviction?(evictedClient: OCPPServerClient, newClient: OCPPServerClient): void | Promise<void>;
+    /** Send buffer exceeded backpressure threshold (512KB — slow client) */
+    onBackpressure?(client: OCPPServerClient, bufferedAmount: number): void | Promise<void>;
+    /** Pong not received within timeout — dead peer detected */
+    onPongTimeout?(client: OCPPServerClient): void | Promise<void>;
+    /** Periodic server stats snapshot (opt-in via `telemetry.pushIntervalMs`) */
+    onTelemetry?(stats: OCPPServerStats, adapterMetrics?: Record<string, unknown>): void | Promise<void>;
+    /**
+     * Plugin contributes custom Prometheus metric lines to the /metrics endpoint.
+     * Return an array of Prometheus exposition format strings.
+     */
+    getCustomMetrics?(): string[] | Promise<string[]>;
+    /** Server options changed via server.reconfigure() */
+    onReconfigure?(newOptions: Partial<ServerOptions>, oldOptions: ServerOptions): void | Promise<void>;
+    /** TLS certificates hot-reloaded via server.updateTLS() */
+    onTLSUpdate?(tlsOpts: TLSOptions): void | Promise<void>;
+    /** Server entering CLOSING state — pre-shutdown hook (before clients are drained) */
+    onClosing?(): void | Promise<void>;
 }
 declare const NOREPLY: unique symbol;
 type MiddlewareContext = {
@@ -5827,6 +5957,17 @@ type MiddlewareContext = {
     messageId: string;
     error: OCPPCallError;
     method: string;
+} | {
+    type: "outgoing_result";
+    messageId: string;
+    method: string;
+    payload: unknown;
+} | {
+    type: "outgoing_error";
+    messageId: string;
+    method: string;
+    errorCode: string;
+    errorDescription: string;
 };
 
 interface BaseConnectionContext {
@@ -5849,4 +5990,4 @@ interface AuthContext<TSession = Record<string, unknown>> extends BaseConnection
 }
 type ConnectionMiddleware = (ctx: ConnectionContext) => Promise<void> | void;
 
-export { createRouter as $, type AuthCallback as A, type OCPPMessage as B, type ConnectionMiddleware as C, type OCPPMethodMap as D, type EventAdapterInterface as E, type OCPPProtocol as F, type OCPPProtocolKey as G, type HandlerContext as H, type OCPPRequestType as I, type OCPPResponseType as J, OCPPRouter as K, type LoggerLike as L, type MiddlewareFunction as M, NOREPLY as N, type OCPPPlugin as O, OCPPServer as P, OCPPServerClient as Q, type RateLimitOptions as R, type RouterConfig as S, SecurityProfile as T, type ServerEvents as U, Validator as V, type ServerOptions as W, type SessionData as X, type TLSOptions as Y, type TypedEventEmitter as Z, type WildcardHandler as _, type LoggingConfig as a, createValidator as a0, type MiddlewareContext as b, type AllMethodNames as c, type AnyOCPPProtocol as d, type AuthAccept as e, type CORSOptions as f, type CallHandler as g, type CallOptions as h, type ClientEvents as i, type ClientOptions as j, type CloseOptions as k, type CompressionOptions as l, type ConnectionContext as m, ConnectionState as n, type HandshakeInfo as o, type ListenOptions as p, MessageType as q, type MiddlewareNext as r, MiddlewareStack as s, type OCPP16Methods as t, type OCPP201Methods as u, type OCPP21Methods as v, type OCPPCall as w, type OCPPCallError as x, type OCPPCallResult as y, OCPPClient as z };
+export { type ServerOptions as $, type AuthCallback as A, type OCPPCallError as B, type ConnectionMiddleware as C, type OCPPCallResult as D, type EventAdapterInterface as E, OCPPClient as F, type OCPPMessage as G, type HandlerContext as H, type OCPPMethodMap as I, type OCPPProtocol as J, type OCPPProtocolKey as K, type LoggerLike as L, type MiddlewareFunction as M, NOREPLY as N, type OCPPPlugin as O, type OCPPRequestType as P, type OCPPResponseType as Q, OCPPRouter as R, OCPPServer as S, OCPPServerClient as T, type OCPPServerStats as U, Validator as V, type RateLimitOptions as W, type RouterConfig as X, type SecurityEvent as Y, SecurityProfile as Z, type ServerEvents as _, type LoggingConfig as a, type SessionData as a0, type TLSOptions as a1, type TelemetryConfig as a2, type TypedEventEmitter as a3, type WildcardHandler as a4, createRouter as a5, createValidator as a6, type MiddlewareContext as b, type AllMethodNames as c, type AnyOCPPProtocol as d, type AuthAccept as e, type CORSOptions as f, type CallHandler as g, type CallOptions as h, type ClientEvents as i, type ClientOptions as j, type CloseOptions as k, type CompressionOptions as l, type ConnectionContext as m, ConnectionState as n, type HandshakeInfo as o, type ListenOptions as p, type MessageDirection as q, type MessageEventContext as r, type MessageEventPayload as s, MessageType as t, type MiddlewareNext as u, MiddlewareStack as v, type OCPP16Methods as w, type OCPP201Methods as x, type OCPP21Methods as y, type OCPPCall as z };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ocpp-ws-io",
-  "version": "2.1.15",
-  "description": "Type-safe OCPP 1.6 & 2.0.1 WebSocket RPC client & server. Build EV charging CSMS platforms with Redis clustering, strict validation, and DDoS protection.",
+  "version": "2.2.1",
+  "description": "OCPP RPC WebSocket client and server for OCPP 1.6J, 2.0.1, and 2.1. Type-safe TypeScript toolkit for EV charging, CSMS backends, Redis scaling, and protocol validation.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rohittiwari-dev/ocpp-ws-io.git"
@@ -42,47 +42,51 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "bun run build"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "keywords": [
     "ocpp",
+    "ocpp-rpc",
     "ocpp-j",
     "ocpp1.6",
     "ocpp1.6j",
     "ocpp2.0.1",
+    "ocpp2.0.1j",
     "ocpp2.1",
     "websocket",
+    "ocpp-websocket",
     "rpc",
+    "websocket-rpc",
     "json-rpc",
+    "ocpp-client",
+    "ocpp-server",
+    "charge-point",
+    "charging-station",
     "ev-charging",
     "evse",
     "csms",
     "cpo",
     "emsp",
-    "charge-point",
-    "charging-station",
-    "charge-point-simulator",
-    "smart-charging",
-    "electric-vehicle",
-    "e-mobility",
-    "iso15118",
+    "wamp",
+    "rpc-server",
+    "rpc-client",
     "type-safe",
     "typescript",
+    "node",
     "nodejs",
     "redis",
+    "redis-pubsub",
     "clustering",
-    "pubsub",
     "browser",
     "simulator",
     "ocpp-simulator",
-    "nodejs-library",
     "testing-cli",
     "ocpp-testing",
     "ocpp-implementation",
-    "ocpp-docs"
+    "ocpp-protocol"
   ],
   "author": "Rohit Tiwari <rohit@rohittiwari.me>",
   "homepage": "https://ocpp-ws-io.rohittiwari.me",