ocpp-ws-io 2.1.7 → 2.1.8

package/dist/browser.d.mts

@@ -1,4 +1,10 @@
-import { IncomingMessage } from 'node:http';
+import * as node_http from 'node:http';
+import { Server, IncomingMessage } from 'node:http';
+import { Duplex } from 'node:stream';
+import * as WebSocket from 'ws';
+import WebSocket__default, { WebSocket as WebSocket$1 } from 'ws';
+import * as node_https from 'node:https';
+import { EventEmitter as EventEmitter$1 } from 'node:events';
 import { TLSSocket } from 'node:tls';
 import { LogEntry } from 'voltlog-io';
 import Ajv from 'ajv';
@@ -4425,6 +4431,95 @@ type OCPPResponseType$1<P extends keyof OCPPMethodMap, M extends string> = P ext
     response: infer R;
 } ? R : never : never : never;
 
+/**
+ * Compiled regex pattern for RegExp-based route fallback.
+ * Only used when a user registers a RegExp pattern (not string patterns).
+ * @internal
+ */
+interface CompiledRegexPattern {
+    regex: RegExp;
+    paramNames: string[];
+}
+declare const OCPPRouter_base: new () => TypedEventEmitter<ServerEvents>;
+/**
+ * OCPPRouter — An Express-like Connection dispatcher.
+ * Isolated handler for a specific set of matching URL route patterns.
+ *
+ * String patterns are matched via radix trie (O(k) lookup, managed by OCPPServer).
+ * RegExp patterns fall back to linear matching.
+ */
+declare class OCPPRouter extends OCPPRouter_base {
+    /** Raw registered patterns (strings and/or RegExp) for reference. */
+    patterns: Array<string | RegExp>;
+    /** Connection middlewares attached to this router. */
+    middlewares: ConnectionMiddleware[];
+    /** Auth callback for this route endpoint. */
+    authCallback: AuthCallback<unknown> | null;
+    /** Route-level CORS options. */
+    _routeCORS?: CORSOptions;
+    /** Route-level config overrides. */
+    _routeConfig?: RouterConfig;
+    /**
+     * Compiled RegExp patterns for fallback linear matching.
+     * Only populated when RegExp patterns are registered.
+     * @internal
+     */
+    _regexPatterns: CompiledRegexPattern[];
+    constructor(patterns?: Array<string | RegExp>, middlewares?: ConnectionMiddleware[]);
+    /**
+     * Appends URL paths or regular expressions to this router's match condition.
+     * String patterns are stored for trie insertion by OCPPServer.
+     * RegExp patterns are compiled for linear fallback matching.
+     */
+    route(...patterns: Array<string | RegExp>): this;
+    /**
+     * Appends connection middlewares to this router's execution chain.
+     */
+    use(...middlewares: ConnectionMiddleware[]): this;
+    /**
+     * Applies specific CORS rules to connections matching this router's paths.
+     */
+    cors(options: CORSOptions): this;
+    /**
+     * Overrides global connection settings (e.g. timeouts, protocols) for this router.
+     */
+    config(options: RouterConfig): this;
+    /**
+     * Registers an authentication and protocol-negotiation callback for this route endpoint.
+     */
+    auth<TSession = Record<string, unknown>>(callback: AuthCallback<TSession>): this;
+    /**
+     * Binds a version-specific OCPP message handler directly to all clients that match this route.
+     *
+     * @throws {Error} AT RUNTIME when a client connects, if a handler for this version and method is already registered for that client.
+     */
+    handle<V extends OCPPProtocol$1, M extends AllMethodNames$1<V>>(version: V, method: M, handler: (context: RouterHandlerContext<OCPPRequestType$1<V, M>>) => OCPPResponseType$1<V, M> | Promise<OCPPResponseType$1<V, M>>): this;
+    /**
+     * Binds a custom/extension message handler directly to all clients that match this route.
+     *
+     * @throws {Error} AT RUNTIME when a client connects, if a handler for this protocol and method is already registered for that client.
+     */
+    handle<S extends string>(version: S extends OCPPProtocol$1 ? never : S, method: string, handler: (context: RouterHandlerContext<Record<string, any>>) => any): this;
+    /**
+     * Binds a message handler directly to all clients that match this route using the default protocol.
+     *
+     * @throws {Error} AT RUNTIME when a client connects, if a handler for this method is already registered for that client.
+     */
+    handle<M extends AllMethodNames$1<OCPPProtocol$1>>(method: M, handler: (context: RouterHandlerContext<OCPPRequestType$1<OCPPProtocol$1, M>>) => OCPPResponseType$1<OCPPProtocol$1, M> | Promise<OCPPResponseType$1<OCPPProtocol$1, M>>): this;
+    /**
+     * Binds a custom/extension method not in the typed map.
+     *
+     * @throws {Error} AT RUNTIME when a client connects, if a handler for this method is already registered for that client.
+     */
+    handle(method: string, handler: (context: RouterHandlerContext<Record<string, any>>) => any): this;
+    /**
+     * Binds a wildcard handler to all clients that match this route.
+     *
+     * @throws {Error} AT RUNTIME when a client connects, if a wildcard handler is already registered for that client.
+     */
+    handle(handler: RouterWildcardHandler): this;
+}
+
 /**
  * Middleware handling for intercepting and modifying OCPP operations.
  *
@@ -4448,6 +4543,561 @@ declare class MiddlewareStack<TContext> {
     execute<TReturn = unknown>(context: TContext, runner: (context: TContext) => Promise<TReturn> | TReturn): Promise<TReturn>;
 }
 
+declare const OCPPClient_base: new () => TypedEventEmitter<ClientEvents>;
+/**
+ * OCPPClient — A typed WebSocket RPC client for OCPP communication.
+ *
+ * Supports all 3 OCPP Security Profiles:
+ * - Profile 1: Basic Auth over unsecured WS
+ * - Profile 2: TLS + Basic Auth
+ * - Profile 3: Mutual TLS (client certificates)
+ */
+declare class OCPPClient<P extends OCPPProtocol$1 = OCPPProtocol$1> extends OCPPClient_base {
+    static readonly CONNECTING: 0;
+    static readonly OPEN: 1;
+    static readonly CLOSING: 2;
+    static readonly CLOSED: 3;
+    protected _options: Required<Pick<ClientOptions, "identity" | "endpoint" | "callTimeoutMs" | "pingIntervalMs" | "deferPingsOnActivity" | "callConcurrency" | "maxBadMessages" | "respondWithDetailedErrors" | "reconnect" | "maxReconnects" | "backoffMin" | "backoffMax">> & ClientOptions;
+    protected _state: ConnectionState;
+    protected _ws: WebSocket__default | null;
+    protected _protocol: string | undefined;
+    protected _identity: string;
+    private _handlers;
+    private _wildcardHandler;
+    private _pendingCalls;
+    private _pendingResponses;
+    private _callQueue;
+    private _pingTimer;
+    private _pongTimer;
+    private _closePromise;
+    private _reconnectAttempt;
+    private _reconnectTimer;
+    private _badMessageCount;
+    private _lastActivity;
+    private _outboundBuffer;
+    private _offlineQueue;
+    private _middleware;
+    private _validators;
+    private _strictProtocols;
+    protected _handshake: unknown;
+    protected _logger: LoggerLike$1;
+    protected _exchangeLog: boolean;
+    protected _prettify: boolean;
+    constructor(options: ClientOptions);
+    /**
+     * Log an OCPP message exchange.
+     * - Default: "CALL → { method }" at debug level
+     * - exchangeLog: adds `direction` to meta
+     * - prettify + exchangeLog: renders styled line like "⚡ CP-101  →  BootNotification  [OUT]"
+     */
+    protected _logExchange(direction: "IN" | "OUT", type: "CALL" | "CALLRESULT" | "CALLERROR", method: string | undefined, meta: Record<string, unknown>): void;
+    /**
+     * Returns the underlying logger instance wrapper.
+     */
+    get log(): LoggerLikeNotOptional$1;
+    /**
+     * The unique client identity (Charge Point ID or Central System ID).
+     */
+    get identity(): string;
+    /**
+     * The connection endpoint URL.
+     */
+    get endpoint(): string;
+    /**
+     * The current configuration options for this client.
+     */
+    get options(): Readonly<ClientOptions>;
+    /**
+     * The negotiated OCPP protocol version, available after connection.
+     */
+    get protocol(): string | undefined;
+    /**
+     * The current WebSocket connection state.
+     */
+    get state(): ConnectionState;
+    /**
+     * The configured security profile.
+     */
+    get securityProfile(): SecurityProfile;
+    /**
+     * Connect to the OCPP endpoint via WebSocket.
+     * Throws an error if the connection attempt fails, or if already connected/connecting.
+     *
+     * @returns A promise that resolves to an object containing the HTTP response from the upgrade request.
+     */
+    connect(): Promise<{
+        response: node_http.IncomingMessage;
+    }>;
+    private _connectInternal;
+    /**
+     * Close the WebSocket connection.
+     * By default, it awaits any pending calls to finish before closing.
+     *
+     * @param options Configuration for closing the connection (code, reason, awaiting pending calls, force close).
+     * @returns A promise that resolves when the connection is fully closed.
+     */
+    close(options?: CloseOptions$1): Promise<{
+        code: number;
+        reason: string;
+    }>;
+    private _closeInternal;
+    /**
+     * Register a version-specific handler — `handle("ocpp1.6", "BootNotification", handler)`.
+     * This handler is only invoked when the active protocol matches the given version.
+     *
+     * @throws {Error} If a handler for this version and method is already registered on this client instance.
+     */
+    handle<V extends OCPPProtocol$1, M extends AllMethodNames$1<V>>(version: V, method: M, handler: (context: HandlerContext$1<OCPPRequestType$1<V, M>>) => OCPPResponseType$1<V, M> | Promise<OCPPResponseType$1<V, M>> | typeof NOREPLY): void;
+    /**
+     * Register a handler for a custom/extension protocol/method not in the typed OCPP method maps.
+     * `handle("my-protocol", "my-method", handler)`
+     *
+     * Note: This overload matches only if the protocol is NOT a known strict protocol of standard OCPP versions.
+     *
+     * @throws {Error} If a handler for this protocol and method is already registered on this client instance.
+     */
+    handle<S extends string>(version: S extends OCPPProtocol$1 ? never : S, method: string, handler: (context: HandlerContext$1<Record<string, any>>) => any): void;
+    /**
+     * Register a handler for the client's default protocol — `handle("BootNotification", handler)`.
+     * Uses the default protocol type parameter `P`.
+     *
+     * @throws {Error} If a handler for this method is already registered on this client instance.
+     */
+    handle<M extends AllMethodNames$1<P>>(method: M, handler: (context: HandlerContext$1<OCPPRequestType$1<P, M>>) => OCPPResponseType$1<P, M> | Promise<OCPPResponseType$1<P, M>> | typeof NOREPLY): void;
+    /**
+     * Register a handler for a custom/extension method not in the typed OCPP method maps.
+     *
+     * @throws {Error} If a handler for this method is already registered on this client instance.
+     */
+    handle(method: string, handler: (context: HandlerContext$1<Record<string, any>>) => any): void;
+    /**
+     * Register a wildcard handler for all unhandled methods.
+     *
+     * @throws {Error} If a wildcard handler is already registered on this client instance.
+     */
+    handle(handler: WildcardHandler$1): void;
+    /**
+     * Remove a registered handler for a specific method on the default protocol.
+     * @param method The method to remove the handler for.
+     */
+    removeHandler(method?: string): void;
+    /**
+     * Remove a registered handler for a specific version and method.
+     */
+    removeHandler(version: OCPPProtocol$1, method: string): void;
+    /**
+     * Remove all registered handlers for this client, including the wildcard handler.
+     */
+    removeAllHandlers(): void;
+    /**
+     * Register a middleware function to intercept calls and results.
+     * Middleware executes in the order registered.
+     */
+    use(middleware: MiddlewareFunction<MiddlewareContext>): void;
+    /**
+     * Call a version-specific typed method — `call("ocpp1.6", "BootNotification", {...})`.
+     * Provides full type inference for params and response based on the OCPP version.
+     */
+    call<V extends OCPPProtocol$1, M extends AllMethodNames$1<V>>(version: V, method: M, params: OCPPRequestType$1<V, M>, options?: CallOptions$1): Promise<OCPPResponseType$1<V, M>>;
+    /**
+     * Call a custom/extension protocol/method not in the typed OCPP method maps.
+     * `call("my-protocol", "my-method", params)`
+     *
+     * Note: This overload matches only if the protocol is NOT a known strict protocol of standard OCPP versions.
+     */
+    call<S extends string, TResult = any>(version: S extends OCPPProtocol$1 ? never : S, method: string, params: Record<string, any>, options?: CallOptions$1): Promise<TResult>;
+    /** Call a known typed method using the client's default protocol. */
+    call<M extends AllMethodNames$1<P>>(method: M, params: OCPPRequestType$1<P, M>, options?: CallOptions$1): Promise<OCPPResponseType$1<P, M>>;
+    /** Call a known typed method with explicit response type. */
+    call<TResult = unknown>(method: string, params?: Record<string, unknown>, options?: CallOptions$1): Promise<TResult>;
+    /**
+     * Version-specific safe call. Returns `undefined` on error instead of throwing.
+     */
+    safeCall<V extends OCPPProtocol$1, M extends AllMethodNames$1<V>>(version: V, method: M, params: OCPPRequestType$1<V, M>, options?: CallOptions$1): Promise<OCPPResponseType$1<V, M> | undefined>;
+    /**
+     * Custom/Extension safe call.
+     */
+    safeCall<S extends string, TResult = any>(version: S extends OCPPProtocol$1 ? never : S, method: string, params: Record<string, any>, options?: CallOptions$1): Promise<TResult | undefined>;
+    /** Default protocol safe call. */
+    safeCall<M extends AllMethodNames$1<P>>(method: M, params: OCPPRequestType$1<P, M>, options?: CallOptions$1): Promise<OCPPResponseType$1<P, M> | undefined>;
+    /** Explicit result safe call. */
+    safeCall<TResult = unknown>(method: string, params?: Record<string, unknown>, options?: CallOptions$1): Promise<TResult | undefined>;
+    private _sendCall;
+    /**
+     * Send a raw string message over the WebSocket (use with caution).
+     * Messages sent while CONNECTING are buffered and flushed on open.
+     */
+    sendRaw(message: string): void;
+    reconfigure(options: Partial<ClientOptions>): void;
+    protected _attachWebsocket(ws: WebSocket__default): void;
+    protected _onMessage(rawData: WebSocket__default.RawData, preParsed?: unknown): void;
+    private _handleIncomingCall;
+    private _handleCallResult;
+    private _handleCallError;
+    private _onBadMessage;
+    /**
+     * Reject all in-flight calls and clear pending state.
+     */
+    private _rejectPendingCalls;
+    private _onClose;
+    /** Errors that should stop reconnection immediately */
+    private static readonly _INTOLERABLE_ERRORS;
+    private _scheduleReconnect;
+    /**
+     * Atomically drains the offline queue and sends each message via _sendCall.
+     * Uses splice(0) to prevent re-entry bugs (double billing) if the connection
+     * drops again mid-flush — the queue is empty before any sends begin.
+     */
+    private _flushOfflineQueue;
+    /**
+     * Retry wrapper using Full Jitter exponential backoff.
+     * delay = random(0, min(retryMaxDelayMs, retryDelayMs * 2^attempt))
+     * Only retries on TimeoutError — all other errors propagate immediately.
+     */
+    private _callWithRetry;
+    /** Maximum bytes allowed in the ws send buffer before applying backpressure (512KB) */
+    private static readonly _BACKPRESSURE_THRESHOLD;
+    /**
+     * Wraps ws.send() with backpressure protection.
+     * If bufferedAmount exceeds the threshold, waits for the buffer to drain
+     * before sending. Prevents OOM on slow 2G/3G charger connections.
+     */
+    private _safeSend;
+    private _startPing;
+    private _stopPing;
+    private _recordActivity;
+    private _setupValidators;
+    private _validateOutbound;
+    private _validateInbound;
+    private _findValidator;
+    private _buildEndpoint;
+    private _buildWsOptions;
+    private _cleanup;
+}
+
+interface WorkerPoolOptions {
+    /** Number of worker threads (default: Math.max(2, cpus - 2)) */
+    poolSize?: number;
+    /** Max pending parse jobs before rejecting (default: 10000) */
+    maxQueueSize?: number;
+}
+interface ParseResult {
+    message: unknown;
+    validationError?: {
+        schemaId: string;
+        errors: string;
+    };
+}
+declare class WorkerPool {
+    private _workers;
+    private _nextWorker;
+    private _taskId;
+    private _pending;
+    private _maxQueueSize;
+    private _terminated;
+    constructor(options?: WorkerPoolOptions);
+    /** Number of worker threads in the pool */
+    get size(): number;
+    /** Number of pending (unresolved) parse tasks */
+    get pendingTasks(): number;
+    /**
+     * Send raw data to a worker for JSON parsing + optional validation.
+     * Uses round-robin worker selection.
+     */
+    parse(data: Buffer | string, schemaInfo?: {
+        protocol: string;
+        schemas: Record<string, unknown>;
+    }): Promise<ParseResult>;
+    /** Gracefully terminate all workers */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * OCPPServerClient — A server-side client representation.
+ *
+ * Created by OCPPServer when a charging station connects.
+ * Extends OCPPClient but is pre-connected (cannot call connect()).
+ */
+declare class OCPPServerClient extends OCPPClient {
+    private _serverSession;
+    private _serverHandshake;
+    constructor(options: ClientOptions, context: {
+        ws: WebSocket$1;
+        handshake: HandshakeInfo;
+        session: Record<string, any>;
+        protocol?: string;
+        /** Optional adaptive rate multiplier getter (from OCPPServer.AdaptiveLimiter) */
+        adaptiveMultiplier?: () => number;
+        /** Optional worker pool for off-thread JSON parsing */
+        workerPool?: WorkerPool;
+    });
+    private _rateLimits;
+    private _adaptiveMultiplier;
+    private _workerPool;
+    private _checkRateLimit;
+    private _attachServerWebsocket;
+    private _handleRateLimitExceeded;
+    /**
+     * Session data associated with this client connection.
+     */
+    get session(): Record<string, any>;
+    /**
+     * Handshake information from the initial connection.
+     */
+    get handshake(): HandshakeInfo;
+    /**
+     * Server clients cannot initiate connections.
+     * @throws Always throws — use OCPPClient for outbound connections.
+     */
+    connect(): Promise<never>;
+    /**
+     * Forcibly disconnects this charging station from the server.
+     * Useful for authentication revocation, administrative kicks, or clearing hung connections.
+     * By default, waits for pending calls to finish before closing (awaitPending: true).
+     *
+     * @example
+     * await client.close({ code: 1000, reason: "Admin revocation" });
+     */
+    close(options?: CloseOptions$1): Promise<{
+        code: number;
+        reason: string;
+    }>;
+}
+
+declare const OCPPServer_base: new () => TypedEventEmitter<ServerEvents>;
+/**
+ * OCPPServer — A typed WebSocket RPC server for OCPP communication.
+ *
+ * Supports all 3 OCPP Security Profiles:
+ * - Profile 1: Basic Auth over unsecured WS
+ * - Profile 2: TLS + Basic Auth (HTTPS server)
+ * - Profile 3: Mutual TLS (HTTPS server with requestCert)
+ */
+declare class OCPPServer extends OCPPServer_base {
+    private _options;
+    /** Radix trie for O(k) route matching (string patterns). */
+    private _trie;
+    /** Global middleware routers (server.use() with no patterns — catch-all). */
+    private _globalMiddlewareRouters;
+    /** Routers with RegExp patterns (fallback linear scan). */
+    private _regexRouters;
+    private _clients;
+    private _clientsByIdentity;
+    private _httpServers;
+    private _wss;
+    private _state;
+    private _adapter;
+    private _httpServerAbortControllers;
+    private _logger;
+    private _globalCORS?;
+    private _connectionBuckets;
+    private _adaptiveLimiter;
+    private _plugins;
+    private _workerPool;
+    private readonly _nodeId;
+    private _sessions;
+    private _gcInterval;
+    private readonly _sessionTimeoutMs;
+    constructor(options?: ServerOptions);
+    get log(): LoggerLikeNotOptional$1;
+    /**
+     * Returns a readonly set of all currently connected OCPPServerClient instances.
+     */
+    get clients(): ReadonlySet<OCPPServerClient>;
+    /**
+     * Returns the current server state (OPEN, CLOSING, CLOSED).
+     */
+    get state(): "OPEN" | "CLOSING" | "CLOSED";
+    /**
+     * Returns current node observability statistics
+     * (e.g. connected socket count, tracked memory sessions, and process CPU/Memory usage).
+     * Fully compatible with Loki/Prometheus node metric ingestion.
+     */
+    stats(): OCPPServerStats;
+    /**
+     * Returns observability statistics from the active Event Adapter (e.g. Redis).
+     * Useful for tracking consumer backlog and enabling Horizontal Pod Autoscaling.
+     */
+    adapterMetrics(): Promise<Record<string, unknown> | null>;
+    /**
+     * Synchronously returns the OCPPServerClient instance if the specific identity
+     * is connected to THIS local server node.
+     * Note: In a clustered environment, clients connected to other nodes will NOT be returned here.
+     *
+     * @param identity The client identity (username/station ID)
+     */
+    getLocalClient(identity: string): OCPPServerClient | undefined;
+    /**
+     * Synchronously checks if the specific identity is connected to THIS local server node.
+     * Note: In a clustered environment, this will return false if the client is connected to another node.
+     *
+     * @param identity The client identity (username/station ID)
+     */
+    hasLocalClient(identity: string): boolean;
+    /**
+     * Asynchronously checks if the specific identity is connected to the server.
+     * In a single-node setup, this checks the local connections.
+     * In a clustered setup (with a pub/sub adapter), this will also check the global presence registry
+     * to see if the client is connected to ANY node in the cluster.
+     *
+     * @param identity The client identity (username/station ID)
+     */
+    isClientConnected(identity: string): Promise<boolean>;
+    /**
+     * Applies global CORS rules to all incoming connections before routing.
+     */
+    cors(options: CORSOptions): this;
+    /**
+     * Registers a new routing dispatcher for multiplexing connections.
+     * `server.route("/api/:tenant").use(middleware).auth(cb).on("client", ...)`
+     */
+    route(...patterns: Array<string | RegExp>): OCPPRouter;
+    /**
+     * Attaches one or more standalone modular routers created via `createRouter()`.
+     * This is useful for separating route definitions across different files.
+     */
+    attachRouters(...routers: OCPPRouter[]): this;
+    /**
+     * Registers one or more plugins for server lifecycle hooks.
+     * Plugins are called in registration order for all lifecycle events.
+     *
+     * @example Single plugin
+     * ```ts
+     * server.plugin(metricsPlugin);
+     * ```
+     *
+     * @example Multiple plugins
+     * ```ts
+     * server.plugin(metricsPlugin, loggingPlugin, otelPlugin);
+     * ```
+     */
+    plugin(...plugins: OCPPPlugin[]): this;
+    /**
+     * Registers middleware chain(s) as a wildcard/catch-all router.
+     *
+     * @example
+     * ```ts
+     * server.use(myMiddleware).route("/api").on("client", ...);
+     * ```
+     */
+    use(...middlewares: ConnectionMiddleware[]): OCPPRouter;
+    /**
+     * Registers a top-level auth handler, returning a router to attach `.on()` or `.use()`.
+     */
+    auth<TSession = Record<string, unknown>>(callback: AuthCallback<TSession>): OCPPRouter;
+    /**
+     * Routes a router into the appropriate internal structure:
+     * - String patterns → radix trie (O(k) lookup)
+     * - RegExp patterns → linear fallback array
+     * - No patterns → global middleware (catch-all)
+     * @internal
+     */
+    private _registerRouter;
+    listen(port?: number, host?: string, options?: ListenOptions): Promise<Server>;
+    /**
+     * Hot-reloads the TLS certificate on all active HTTPS servers without
+     * dropping any existing WebSocket connections.
+     *
+     * **When to use:** Call this whenever your TLS certificate is renewed —
+     * for example, after a Let's Encrypt auto-renewal (every ~90 days).
+     * Without this, you would need to restart the Node.js process to pick up
+     * the new certificate, disconnecting all connected charging stations.
+     *
+     * **How to use:**
+     * ```ts
+     * server.updateTLS({ cert: newCert, key: newKey });
+     * ```
+     *
+     * **Optional:** Only relevant if you are terminating TLS directly in Node.js
+     * (i.e. `SecurityProfile.TLS_BASIC_AUTH` or `TLS_CLIENT_CERT`). If you are
+     * running behind a reverse proxy (Nginx, AWS ALB, etc.) that handles TLS,
+     * you do not need this method — just rotate the cert on the proxy.
+     *
+     * @throws If the server is not using a TLS Security Profile.
+     */
+    updateTLS(tlsOpts: TLSOptions): void;
+    get handleUpgrade(): (req: IncomingMessage, socket: Duplex, head: Buffer) => Promise<void>;
+    /**
+     * Core upgrade handler. Follows a strict pipeline:
+     *
+     * 1. Validate socket readyState & upgrade header
+     * 2. Parse URL → identity + endpoint
+     * 3. Enable TCP Keep-Alive
+     * 4. Parse & negotiate subprotocols
+     * 5. Parse Basic Auth (via modular parseBasicAuth)
+     * 6. Extract TLS client certificate (Profile 3)
+     * 7. Build HandshakeInfo
+     * 8. Run auth callback with AbortController + handshake timeout
+     * 9. Complete WebSocket upgrade
+     * 10. Create OCPPServerClient
+     */
+    private _handleUpgrade;
+    private _updateSessionActivity;
+    close(options?: CloseOptions$1): Promise<void>;
+    reconfigure(options: Partial<ServerOptions>): void;
+    /**
+     * Send a request to a specific client (local or remote).
+     *
+     * 1. Checks local clients.
+     * 2. Checks Presence Registry -> Unicast.
+     * 3. Fallback: Broadcast.
+     */
+    /**
+     * Send a request to a specific client (local or remote).
+     *
+     * 1. Checks local clients.
+     * 2. Checks Presence Registry -> Unicast.
+     * 3. Fallback: Error (Client not found).
+     */
+    sendToClient<V extends OCPPProtocol$1, M extends AllMethodNames$1<V>>(identity: string, version: V, method: M, params: OCPPRequestType$1<V, M>, options?: CallOptions$1): Promise<OCPPResponseType$1<V, M> | undefined>;
+    sendToClient<M extends AllMethodNames$1<any>>(identity: string, method: M, params: OCPPRequestType$1<any, M>, options?: CallOptions$1): Promise<OCPPResponseType$1<any, M> | undefined>;
+    sendToClient<_T = any>(identity: string, method: string, params: Record<string, any>, options?: CallOptions$1): Promise<any | undefined>;
+    safeSendToClient<V extends OCPPProtocol$1, M extends AllMethodNames$1<V>>(identity: string, version: V, method: M, params: OCPPRequestType$1<V, M>, options?: CallOptions$1): Promise<OCPPResponseType$1<V, M> | undefined>;
+    safeSendToClient<M extends AllMethodNames$1<any>>(identity: string, method: M, params: OCPPRequestType$1<any, M>, options?: CallOptions$1): Promise<OCPPResponseType$1<any, M> | undefined>;
+    safeSendToClient<_T = any>(identity: string, method: string, params: Record<string, any>, options?: CallOptions$1): Promise<any | undefined>;
+    /**
+     * Pipeline multiple calls to a single client into a concurrent batch.
+     * Useful for reconnection warm-up (e.g. GetConfiguration, ChangeAvailability, etc.)
+     * where sequential calls would add unnecessary round-trip latency.
+     *
+     * @param identity The client identity to send calls to
+     * @param calls Array of { method, params, options? } to execute concurrently
+     * @returns Array of results in the same order as the calls array.
+     *          Each element is the call result, or `undefined` if that individual call failed.
+     *
+     * @example
+     * ```ts
+     * const results = await server.sendBatch('CP-101', [
+     *   { method: 'GetConfiguration', params: { key: ['MeterInterval'] } },
+     *   { method: 'ChangeAvailability', params: { type: 'Operative' } },
+     *   { method: 'TriggerMessage', params: { requestedMessage: 'StatusNotification' } },
+     * ]);
+     * ```
+     */
+    sendBatch(identity: string, calls: Array<{
+        method: string;
+        params: Record<string, unknown>;
+        options?: CallOptions$1;
+    }>): Promise<Array<unknown | undefined>>;
+    setAdapter(adapter: EventAdapterInterface): Promise<void>;
+    private _onBroadcast;
+    private _onUnicast;
+    publish(channel: string, data: unknown): Promise<void>;
+    broadcast<V extends AllMethodNames$1<any>>(method: V, params: OCPPRequestType$1<any, V>): Promise<void>;
+    /**
+     * Send a specific method & params to a list of specific clients efficiently.
+     * This leverages adapter pipelining (e.g. Redis .pipeline()) to minimize network overhead
+     * when communicating with thousands of nodes simultaneously.
+     *
+     * @param identities Array of target client identities
+     * @param method The OCPP method to send
+     * @param params The request parameters
+     * @param options Call options
+     */
+    broadcastBatch<V extends AllMethodNames$1<any>>(identities: string[], method: V, params: OCPPRequestType$1<any, V>, options?: CallOptions$1): Promise<void>;
+    private _buildCompressionConfig;
+}
+
 interface ValidatorSchema {
     $schema?: string;
     $id?: string;
@@ -4482,6 +5132,20 @@ declare class Validator {
     hasSchema(schemaId: string): boolean;
 }
 
+/**
+ * Utility type that overlays typed `.on()`, `.off()`, `.emit()` etc.
+ * on top of Node.js EventEmitter. This is the foundation for type-safe
+ * event handling throughout the library.
+ */
+type TypedEventEmitter<TEvents extends Record<keyof TEvents, unknown[]>> = Omit<EventEmitter$1, "on" | "once" | "off" | "emit" | "removeListener" | "addListener" | "removeAllListeners"> & {
+    on<K extends keyof TEvents | (string & {})>(event: K, listener: K extends keyof TEvents ? (...args: TEvents[K]) => void : (...args: unknown[]) => void): TypedEventEmitter<TEvents>;
+    once<K extends keyof TEvents | (string & {})>(event: K, listener: K extends keyof TEvents ? (...args: TEvents[K]) => void : (...args: unknown[]) => void): TypedEventEmitter<TEvents>;
+    off<K extends keyof TEvents | (string & {})>(event: K, listener: K extends keyof TEvents ? (...args: TEvents[K]) => void : (...args: unknown[]) => void): TypedEventEmitter<TEvents>;
+    emit<K extends keyof TEvents | (string & {})>(event: K, ...args: K extends keyof TEvents ? TEvents[K] : unknown[]): boolean;
+    addListener<K extends keyof TEvents | (string & {})>(event: K, listener: K extends keyof TEvents ? (...args: TEvents[K]) => void : (...args: unknown[]) => void): TypedEventEmitter<TEvents>;
+    removeListener<K extends keyof TEvents | (string & {})>(event: K, listener: K extends keyof TEvents ? (...args: TEvents[K]) => void : (...args: unknown[]) => void): TypedEventEmitter<TEvents>;
+    removeAllListeners<K extends keyof TEvents | (string & {})>(event?: K): TypedEventEmitter<TEvents>;
+};
 type OCPPProtocol$1 = OCPPProtocolKey;
 type AnyOCPPProtocol$1 = OCPPProtocol$1 | (string & {});
 declare const ConnectionState: {
@@ -4517,6 +5181,18 @@ type OCPPCallError$1 = [
     Record<string, unknown>
 ];
 type OCPPMessage$1<T = unknown> = OCPPCall$1<T> | OCPPCallResult$1<T> | OCPPCallError$1;
+interface TLSOptions {
+    /** Server/client certificate (PEM) */
+    cert?: string | Buffer;
+    /** Private key (PEM) */
+    key?: string | Buffer;
+    /** CA certificate(s) for verification */
+    ca?: string | Buffer | Array<string | Buffer>;
+    /** Reject unauthorized certs (default: true) */
+    rejectUnauthorized?: boolean;
+    /** Passphrase for encrypted private key */
+    passphrase?: string;
+}
 interface HandlerContext$1<T = unknown> {
     /** Unique message ID */
     messageId: string;
@@ -4531,6 +5207,11 @@ interface HandlerContext$1<T = unknown> {
 }
 type CallHandler$1<TParams = unknown, TResult = unknown> = (context: HandlerContext$1<TParams>) => TResult | Promise<TResult>;
 type WildcardHandler$1 = (method: string, context: HandlerContext$1) => unknown | Promise<unknown>;
+interface RouterHandlerContext<T = unknown> extends HandlerContext$1<T> {
+    /** The specific server client that issued the message. */
+    client: OCPPServerClient;
+}
+type RouterWildcardHandler = (method: string, context: RouterHandlerContext) => unknown | Promise<unknown>;
 interface CallOptions$1 {
     /** Timeout in milliseconds for this specific call */
     timeoutMs?: number;
@@ -4678,6 +5359,297 @@ interface LoggingConfig$1 {
      */
     prettifyMetadata?: boolean;
 }
+interface ClientOptions {
+    /** Unique identity for this client (charging station ID) */
+    identity: string;
+    /** WebSocket endpoint URL (ws:// or wss://) */
+    endpoint: string;
+    /** OCPP Security Profile (default: NONE) */
+    securityProfile?: SecurityProfile;
+    /** Password for Basic Auth (Profile 1 & 2) */
+    password?: string | Buffer;
+    /** TLS options (Profile 2 & 3) */
+    tls?: TLSOptions;
+    /** OCPP subprotocols to negotiate */
+    protocols?: AnyOCPPProtocol$1[];
+    /** Additional WebSocket headers */
+    headers?: Record<string, string>;
+    /** Additional query parameters */
+    query?: Record<string, string>;
+    /** Enable automatic reconnection (default: true) */
+    reconnect?: boolean;
+    /** Maximum reconnection attempts (default: Infinity) */
+    maxReconnects?: number;
+    /** Back-off base delay in ms (default: 1000) */
+    backoffMin?: number;
+    /** Back-off max delay in ms (default: 30000) */
+    backoffMax?: number;
+    /** Call timeout in ms (default: 30000) */
+    callTimeoutMs?: number;
+    /** Ping interval in ms (default: 30000, 0 to disable) */
+    pingIntervalMs?: number;
+    /** Defer pings if activity detected (default: false) */
+    deferPingsOnActivity?: boolean;
+    /**
+     * Pong response timeout in ms. If no pong is received within this
+     * window after a ping, the connection is considered dead and terminated.
+     * (default: pingIntervalMs + 5000, 0 to disable)
+     */
+    pongTimeoutMs?: number;
+    /** Maximum concurrent outbound calls (default: 1) */
+    callConcurrency?: number;
+    /** Enable strict mode validation (default: false) */
+    strictMode?: boolean | OCPPProtocol$1[];
+    /** If defined, restricts strict mode validation ONLY to these methods */
+    strictModeMethods?: Array<AllMethodNames$1<OCPPProtocol$1>>;
+    /** Custom validators for strict mode */
+    strictModeValidators?: Validator[];
+    /** Max number of bad messages before closing (default: Infinity) */
+    maxBadMessages?: number;
+    /** Include error details in responses (default: false) */
+    respondWithDetailedErrors?: boolean;
+    /**
+     * Logging configuration.
+     * - `undefined` / not set → default voltlog-io with console (logging enabled)
+     * - `false` → logging disabled entirely
+     * - `LoggingConfig` → custom configuration
+     */
+    logging?: LoggingConfig$1 | false;
+    /** Rate Limiting configuration (Token Bucket) */
+    rateLimit?: RateLimitOptions;
+    /**
+     * If true, calls made while disconnected are queued in-memory
+     * and flushed automatically on reconnect. (default: false)
+     */
+    offlineQueue?: boolean;
+    /**
+     * Maximum number of messages to queue while offline.
+     * Oldest messages are dropped when exceeded. (default: 100)
+     */
+    offlineQueueMaxSize?: number;
+    /**
+     * Enable WebSocket `permessage-deflate` compression.
+     * Reduces bandwidth by ~80% for JSON payloads at the cost of ~0.2ms CPU per message.
+     * - `true` → sensible defaults (threshold: 1024, level: 6)
+     * - `object` → fine-tuned configuration
+     * (default: false)
+     */
+    compression?: boolean | CompressionOptions;
+}
+interface CompressionOptions {
+    /** Minimum payload size in bytes to compress (default: 1024) */
+    threshold?: number;
+    /** zlib compression level 1 (fastest) to 9 (smallest) (default: 6) */
+    level?: number;
+    /** zlib memory level 1–9 (default: 8) */
+    memLevel?: number;
+    /** Server does not retain deflate context between messages (default: true — saves ~120KB/conn) */
+    serverNoContextTakeover?: boolean;
+    /** Client does not retain deflate context between messages (default: true) */
+    clientNoContextTakeover?: boolean;
+}
+interface RateLimitOptions {
+    /** Maximum number of messages allowed within the window */
+    limit: number;
+    /** Window size in milliseconds */
+    windowMs: number;
+    /**
+     * Action to take when rate limit is exceeded.
+     * - 'disconnect': Terminate the socket immediately (hard enforce).
+     * - 'ignore': Drop the message entirely, letting the client back-off and retry.
+     * - Custom callback: Perform custom logging or logic when exceeded.
+     * (default: 'ignore')
+     */
+    onLimitExceeded?: "disconnect" | "ignore" | ((client: OCPPServerClient, rawData: unknown) => void | Promise<void>);
+    /**
+     * Specific limits applied purely to individual methods (e.g. Heartbeat, BootNotification).
+     * Note: The method must be parsed from the raw JSON payload to apply this.
+     */
+    methods?: Record<string, {
+        limit: number;
+        windowMs: number;
+    }>;
+    /**
+     * Enable adaptive rate limiting based on CPU/memory pressure.
+     * When enabled, the token refill rate is automatically reduced under
+     * high load and restored after a cooldown period. (default: false)
+     */
+    adaptive?: boolean;
+    /**
+     * CPU usage percent threshold to begin throttling.
+     * Applies only when `adaptive` is true. (default: 80)
+     */
+    cpuThresholdPercent?: number;
+    /**
+     * Heap usage percent threshold to begin throttling.
+     * Applies only when `adaptive` is true. (default: 85)
+     */
+    memThresholdPercent?: number;
+    /**
+     * Time (ms) both CPU and memory must stay below their thresholds
+     * before restoring the original rate. (default: 5000)
+     */
+    cooldownMs?: number;
+}
+interface RouterConfig {
+    /** Accepted OCPP subprotocols (e.g. ["ocpp1.6"]) */
+    protocols?: AnyOCPPProtocol$1[];
+    /** Call timeout in ms — overrides server default */
+    callTimeoutMs?: number;
+    /** Ping interval in ms — overrides server default */
+    pingIntervalMs?: number;
+    /** Defer pings if activity detected — overrides server default */
+    deferPingsOnActivity?: boolean;
+    /** Max concurrent outbound calls — overrides server default */
+    callConcurrency?: number;
+    /** Enable strict mode validation — overrides server default */
+    strictMode?: boolean | OCPPProtocol$1[];
+    /** If defined, restricts strict mode validation ONLY to these methods */
+    strictModeMethods?: Array<AllMethodNames$1<OCPPProtocol$1>>;
+    /** Rate Limiting configuration — overrides server default */
+    rateLimit?: RateLimitOptions;
+}
+interface CORSOptions {
+    /** Allowed IPv4, IPv6, or CIDR ranges (e.g. "10.0.0.0/8") */
+    allowedIPs?: string[];
+    /** Allowed Origin header values (e.g. "https://dashboard.example.com") */
+    allowedOrigins?: string[];
+    /** Allowed WebSocket protocol schemes */
+    allowedSchemes?: ("ws" | "wss")[];
+}
+interface ServerOptionsBase {
+    /** OCPP Security Profile (default: NONE) */
+    securityProfile?: SecurityProfile;
+    /** TLS options for HTTPS server (Profile 2 & 3) */
+    tls?: TLSOptions;
+    /** Call timeout in ms — inherited by server clients (default: 30000) */
+    callTimeoutMs?: number;
+    /** Ping interval in ms — inherited by server clients (default: 30000) */
+    pingIntervalMs?: number;
+    /** Defer pings if activity detected — inherited (default: false) */
+    deferPingsOnActivity?: boolean;
+    /** Max concurrent outbound calls — inherited (default: 1) */
+    callConcurrency?: number;
+    /** If defined, restricts strict mode validation ONLY to these methods */
+    strictModeMethods?: Array<AllMethodNames$1<OCPPProtocol$1>>;
+    /** Custom validators — inherited */
+    strictModeValidators?: Validator[];
+    /** Rate Limiting configuration — inherited */
+    rateLimit?: RateLimitOptions;
+    /** Max bad messages — inherited (default: Infinity) */
+    maxBadMessages?: number;
+    /** Include error details in responses — inherited (default: false) */
+    respondWithDetailedErrors?: boolean;
+    /**
+     * Session inactivity timeout in milliseconds before garbage collection.
+     * (default: 7200000 / 2 hours)
+     */
+    sessionTtlMs?: number;
+    /**
+     * Maximum time (ms) to wait for the auth callback to resolve during
+     * a WebSocket upgrade handshake. If the callback does not settle within
+     * this window, the socket is destroyed and an `upgradeAborted` event
+     * is emitted. Set to `0` to disable. (default: 30000)
+     */
+    handshakeTimeoutMs?: number;
+    /**
+     * Logging configuration — inherited by server clients.
+     * - `undefined` / not set → default voltlog-io with console
+     * - `false` → logging disabled
+     * - `LoggingConfig` → custom configuration
+     */
+    logging?: LoggingConfig$1 | false;
+    /**
+     * Connection-level rate limiting (per-IP) applied at the HTTP upgrade boundary,
+     * before any auth, TLS or JSON parsing occurs — blocks DDoS connection floods in ~1µs.
+     * - `limit`: Max upgrade requests per IP within `windowMs` (default: 20)
+     * - `windowMs`: Sliding window in ms (default: 10000)
+     */
+    connectionRateLimit?: {
+        limit: number;
+        windowMs: number;
+    };
+    /**
+     * Maximum number of inactive sessions to retain in the bounded LRU cache.
+     * Prevents OOM under DDoS or reconnection storms with transient identities.
+     * (default: 50000)
+     */
+    maxSessions?: number;
+    /**
+     * Enable the built-in HTTP health/metrics endpoint.
+     * When enabled, non-upgrade HTTP requests to `/health` return a JSON health check,
+     * and requests to `/metrics` return Prometheus-compatible text metrics.
+     * (default: false)
+     */
+    healthEndpoint?: boolean;
+    /**
+     * Maximum WebSocket payload size in bytes. Messages exceeding this limit
+     * are rejected at the transport layer before JSON parsing, preventing OOM
+     * from oversized or malicious payloads.
+     * (default: 65536 / 64KB — sufficient for any standard OCPP message)
+     */
+    maxPayloadBytes?: number;
+    /**
+     * Enable worker thread pool for JSON parsing (+ optional AJV validation).
+     * Offloads CPU-heavy work to worker threads, keeping the main event loop free.
+     * Recommended for 10k+ concurrent connections. (default: false)
+     *
+     * - `true` → uses default pool size: `Math.max(2, os.cpus() - 2)`
+     * - `{ poolSize, maxQueueSize }` → fine-tuned pool configuration
+     */
+    workerThreads?: boolean | {
+        poolSize?: number;
+        maxQueueSize?: number;
+    };
+    /**
+     * Enable WebSocket `permessage-deflate` compression.
+     * Reduces bandwidth by ~80% for JSON payloads at the cost of ~0.2ms CPU per message.
+     * - `true` → sensible defaults (threshold: 1024, level: 6)
+     * - `object` → fine-tuned configuration
+     * (default: false)
+     */
+    compression?: boolean | CompressionOptions;
+}
+/** When strictMode is enabled, protocols MUST be specified */
+interface StrictServerOptions extends ServerOptionsBase {
+    strictMode: true | OCPPProtocol$1[];
+    protocols: AnyOCPPProtocol$1[];
+}
+/** When strictMode is disabled or omitted, protocols are optional */
+interface RelaxedServerOptions extends ServerOptionsBase {
+    strictMode?: false;
+    protocols?: AnyOCPPProtocol$1[];
+}
+type ServerOptions = StrictServerOptions | RelaxedServerOptions;
+interface OCPPServerStats {
+    /** Number of currently connected WebSockets */
+    connectedClients: number;
+    /** Number of active memory sessions */
+    activeSessions: number;
+    /** Process uptime in seconds */
+    uptimeSeconds: number;
+    /** Process Memory Usage (bytes) */
+    memoryUsage: NodeJS.MemoryUsage;
+    /** Process CPU Time (microseconds) */
+    cpuUsage: NodeJS.CpuUsage;
+    /** Process ID */
+    pid: number;
+    /** Low-level WebSocket Server metrics */
+    webSockets?: {
+        /** Total active clients managed by the underlying ws server */
+        total: number;
+        /** Current messages waiting to be flushed to network (bytes) */
+        bufferedAmount: number;
+    };
+}
+interface ListenOptions {
+    /** Existing HTTP/HTTPS server to attach to */
+    server?: node_http.Server | node_https.Server;
+    /** Hostname to bind to */
+    host?: string;
+    /** Signal to abort the listen */
+    signal?: AbortSignal;
+}
 interface AuthAccept<TSession = Record<string, unknown>> {
     /** Subprotocol to use for this client */
     protocol?: string;
@@ -4685,6 +5657,141 @@ interface AuthAccept<TSession = Record<string, unknown>> {
     session?: TSession;
 }
 type AuthCallback<TSession = Record<string, unknown>> = (ctx: AuthContext<TSession>) => void | Promise<void>;
+interface ClientEvents {
+    open: [{
+        response: IncomingMessage;
+    }];
+    close: [{
+        code: number;
+        reason: string;
+    }];
+    disconnect: [{
+        code: number;
+        reason: string;
+    }];
+    error: [Error];
+    connecting: [{
+        url: string;
+    }];
+    reconnect: [{
+        attempt: number;
+        delay: number;
+    }];
+    message: [OCPPMessage$1];
+    call: [OCPPCall$1];
+    callResult: [OCPPCallResult$1];
+    callError: [OCPPCallError$1];
+    badMessage: [{
+        message: string;
+        error: Error;
+    }];
+    ping: [];
+    pong: [];
+    strictValidationFailure: [{
+        message: unknown;
+        error: Error;
+    }];
+}
+
+/**
+ * I3: Structured security event for SIEM integration.
+ * Emitted by the server for audit-relevant actions.
+ */
+interface SecurityEvent {
+    /** Event type identifier */
+    type: "AUTH_FAILED" | "RATE_LIMIT_EXCEEDED" | "UPGRADE_ABORTED" | "CONNECTION_RATE_LIMIT" | "INVALID_PAYLOAD";
+    /** Station identity (if known) */
+    identity?: string;
+    /** Remote IP address */
+    ip?: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Event-specific details */
+    details?: Record<string, unknown>;
+}
+interface ServerEvents {
+    client: [OCPPServerClient];
+    error: [Error];
+    upgradeError: [{
+        error: Error;
+        socket: Duplex;
+    }];
+    upgradeAborted: [
+        {
+            identity: string;
+            reason: string;
+            socket: Duplex;
+            request: IncomingMessage;
+        }
+    ];
+    closing: [];
+    close: [];
+    /** I3: Structured security event for SIEM/audit pipelines */
+    securityEvent: [SecurityEvent];
+    connection: [
+        socket: WebSocket.WebSocket,
+        request: node_http.IncomingMessage
+    ];
+    listening: [];
+    headers: [headers: string[], request: node_http.IncomingMessage];
+}
+interface EventAdapterInterface {
+    publish(channel: string, data: unknown): Promise<void>;
+    publishBatch?(messages: {
+        channel: string;
+        data: unknown;
+    }[]): Promise<void>;
+    subscribe(channel: string, handler: (data: unknown) => void): Promise<void>;
+    unsubscribe(channel: string): Promise<void>;
+    disconnect(): Promise<void>;
+    setPresence?(identity: string, nodeId: string, ttl: number): Promise<void>;
+    getPresence?(identity: string): Promise<string | null>;
+    getPresenceBatch?(identities: string[]): Promise<(string | null)[]>;
+    removePresence?(identity: string): Promise<void>;
+    /**
+     * Batch set multiple presence entries in a single pipeline.
+     * Reduces N network round-trips to 1 for bulk presence updates.
+     */
+    setPresenceBatch?(entries: {
+        identity: string;
+        nodeId: string;
+        ttl?: number;
+    }[]): Promise<void>;
+    metrics?(): Promise<Record<string, unknown>>;
+}
+/**
+ * Plugin interface for extending OCPPServer functionality.
+ *
+ * Plugins provide a unified way to hook into server lifecycle events
+ * without modifying core internals. Useful for:
+ * - Observability (OpenTelemetry, Prometheus)
+ * - Custom adapters and integrations
+ * - Auditing and compliance
+ *
+ * @example
+ * ```ts
+ * const myPlugin: OCPPPlugin = {
+ *   name: 'my-plugin',
+ *   onInit(server) { console.log('Plugin initialized'); },
+ *   onConnection(client) { console.log(`${client.identity} connected`); },
+ *   onDisconnect(client) { console.log(`${client.identity} disconnected`); },
+ *   onClose() { console.log('Server shutting down'); },
+ * };
+ * server.plugin(myPlugin);
+ * ```
+ */
+interface OCPPPlugin {
+    /** Unique plugin name (used for logging and deduplication) */
+    name: string;
+    /** Called when the plugin is registered via server.plugin(plugin) */
+    onInit?(server: OCPPServer): void | Promise<void>;
+    /** Called for each new client connection after auth succeeds */
+    onConnection?(client: OCPPServerClient): void | Promise<void>;
+    /** Called when a client disconnects */
+    onDisconnect?(client: OCPPServerClient, code: number, reason: string): void;
+    /** Called during server.close() for plugin cleanup */
+    onClose?(): void | Promise<void>;
+}
 declare const NOREPLY: unique symbol;
 type MiddlewareContext = {
     type: "incoming_call";
@@ -4735,6 +5842,26 @@ type ConnectionMiddleware = (ctx: ConnectionContext) => Promise<void> | void;
  * This provides immediate IDE autocomplete for the `ConnectionContext`.
  */
 declare function defineMiddleware(mw: ConnectionMiddleware): ConnectionMiddleware;
+/**
+ * Utility to define and strongly-type an `OCPPPlugin` object.
+ * Provides full IDE autocomplete for all lifecycle hooks.
+ *
+ * @example
+ * ```ts
+ * import { createPlugin } from 'ocpp-ws-io';
+ *
+ * const metricsPlugin = createPlugin({
+ *   name: 'metrics',
+ *   onInit(server)       { console.log('Metrics plugin ready'); },
+ *   onConnection(client) { metrics.gauge('connections').inc(); },
+ *   onDisconnect(client) { metrics.gauge('connections').dec(); },
+ *   onClose()            { metrics.flush(); },
+ * });
+ *
+ * server.plugin(metricsPlugin);
+ * ```
+ */
+declare function createPlugin(plugin: OCPPPlugin): OCPPPlugin;
 /**
  * Utility to define and strongly-type an RPC Middleware function.
  * This provides immediate IDE autocomplete for the `MiddlewareContext`
@@ -5054,4 +6181,4 @@ declare function createRPCError(code: string, message?: string, details?: Record
  */
 declare function getErrorPlainObject(err: Error): Record<string, unknown>;
 
-export { type AllMethodNames, type AnyOCPPProtocol, type BrowserClientEvents, type BrowserClientOptions, BrowserOCPPClient, type CallHandler, type CallOptions, type CloseOptions, ConnectionState, type HandlerContext, type LoggerLike, type LoggingConfig, MessageType, type MiddlewareFunction, type MiddlewareNext, MiddlewareStack, NOREPLY, type OCPPCall, type OCPPCallError, type OCPPCallResult, type OCPPMessage, type OCPPProtocol, type OCPPRequestType, type OCPPResponseType, type RPCError, RPCFormatViolationError, RPCFormationViolationError, RPCFrameworkError, RPCGenericError, RPCInternalError, RPCMessageTypeNotSupportedError, RPCNotImplementedError, RPCNotSupportedError, RPCOccurrenceConstraintViolationError, RPCPropertyConstraintViolationError, RPCProtocolError, RPCSecurityError, RPCTypeConstraintViolationError, TimeoutError, Validator, type ValidatorSchema, type WildcardHandler, combineAuth, createLoggingMiddleware, createRPCError, defineAuth, defineMiddleware, defineRpcMiddleware, getErrorPlainObject };
+export { type AllMethodNames, type AnyOCPPProtocol, type BrowserClientEvents, type BrowserClientOptions, BrowserOCPPClient, type CallHandler, type CallOptions, type CloseOptions, ConnectionState, type HandlerContext, type LoggerLike, type LoggingConfig, MessageType, type MiddlewareFunction, type MiddlewareNext, MiddlewareStack, NOREPLY, type OCPPCall, type OCPPCallError, type OCPPCallResult, type OCPPMessage, type OCPPProtocol, type OCPPRequestType, type OCPPResponseType, type RPCError, RPCFormatViolationError, RPCFormationViolationError, RPCFrameworkError, RPCGenericError, RPCInternalError, RPCMessageTypeNotSupportedError, RPCNotImplementedError, RPCNotSupportedError, RPCOccurrenceConstraintViolationError, RPCPropertyConstraintViolationError, RPCProtocolError, RPCSecurityError, RPCTypeConstraintViolationError, TimeoutError, Validator, type ValidatorSchema, type WildcardHandler, combineAuth, createLoggingMiddleware, createPlugin, createRPCError, defineAuth, defineMiddleware, defineRpcMiddleware, getErrorPlainObject };