ocpp-ws-io 1.0.0 → 1.0.1

package/README.md

@@ -11,9 +11,11 @@ Built with TypeScript from the ground up — supports OCPP 1.6, 2.0.1, and 2.1 w
 - 📐 **Strict Mode** — Optional schema validation using built-in OCPP JSON schemas
 - 🔁 **Auto-Reconnect** — Exponential backoff with configurable limits
 - 🧩 **Framework Agnostic** — Use standalone, or attach to Express, Fastify, NestJS, etc.
-- 📡 **Clustering** — Optional Redis adapter for multi-instance deployments
+- 📡 **Clustering** — Optional Redis adapter (supports `ioredis` & `node-redis`)
 - 🎯 **Type-Safe** — Auto-generated types for all OCPP 1.6, 2.0.1 & 2.1 methods with full request/response inference
+- 🛠️ **Schema-to-TS** — Built-in script to re-generate types from official JSON schemas
 - 🔀 **Version-Aware Handlers** — Register handlers per OCPP version with typed params, or use generic handlers with protocol context
+- 🌐 **Browser Client** — Zero-dependency browser WebSocket client via `ocpp-ws-io/browser`
 
 ## Installation
 
@@ -112,6 +114,39 @@ await server.listen(3000);
 console.log("OCPP Server listening on port 3000");
 ```
 
+### Browser Client
+
+For browser environments (React, Vue, Next.js client components, etc.), use `BrowserOCPPClient` from the `ocpp-ws-io/browser` subpath. Designed for **building charge point simulators, testing dashboards, and debugging tools** directly in the browser — zero Node.js dependencies.
+
+> **Note:** The browser client does not support all OCPP features (no Security Profiles, Strict Mode, TLS, Ping/Pong, or custom headers). For production use, use `OCPPClient` in Node.js.
+
+```typescript
+import { BrowserOCPPClient } from "ocpp-ws-io/browser";
+
+const client = new BrowserOCPPClient({
+  endpoint: "wss://csms.example.com/ocpp",
+  identity: "CP001",
+  protocols: ["ocpp1.6"],
+});
+
+// Same typed API as OCPPClient
+client.handle("Reset", ({ params }) => {
+  console.log("Reset type:", params.type);
+  return { status: "Accepted" };
+});
+
+await client.connect();
+
+const response = await client.call("ocpp1.6", "BootNotification", {
+  chargePointVendor: "VendorX",
+  chargePointModel: "ModelY",
+});
+
+console.log("Status:", response.status); // typed: "Accepted" | "Pending" | "Rejected"
+```
+
+> See [Browser Client](#browser-client-1) below for the full API reference, configuration options, and framework integration examples.
+
 ---
 
 ## Security Profiles
@@ -398,10 +433,11 @@ client.removeAllHandlers();
 ```typescript
 import type {
   OCPPProtocol, // "ocpp1.6" | "ocpp2.0.1" | "ocpp2.1"
+  OCPPProtocolKey, // keyof OCPPMethodMap — extensible via module augmentation
+  OCPPMethodMap, // Full method map interface
   AllMethodNames, // All method names for a given protocol
   OCPPRequestType, // Request type for a method, e.g. OCPPRequestType<"ocpp1.6", "Reset">
   OCPPResponseType, // Response type for a method
-  OCPPMethodMap, // Full method map for a protocol
 } from "ocpp-ws-io";
 
 // Example: Get all method names for OCPP 1.6
@@ -448,15 +484,82 @@ Custom validators:
 import { createValidator } from "ocpp-ws-io";
 import myCustomSchemas from "./my-schemas.json";
 
-const myValidator = createValidator("custom-protocol", myCustomSchemas);
+const myValidator = createValidator("vendor-proto", myCustomSchemas);
 
 const client = new OCPPClient({
-  protocols: ["custom-protocol"],
+  protocols: ["ocpp1.6", "vendor-proto"],
   strictMode: true,
-  strictModeValidators: [myValidator],
+  strictModeValidators: [myValidator], // adds to built-in validators
 });
 ```
 
+> **Tip:** Combine custom validators with module augmentation to get both runtime validation **and** compile-time type safety. See [Extending with Custom Protocols](#extending-with-custom-protocols) below.
+
+---
+
+## Extending with Custom Protocols
+
+`OCPPMethodMap` is a TypeScript **interface**, so you can extend it with your own protocols using [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation). This gives you full type safety for custom/vendor-specific protocols in `handle()`, `call()`, and `protocols`.
+
+### Step 1: Define Your Method Types
+
+```typescript
+// src/vendor-types.ts
+export interface MyVendorMethods {
+  VendorAction: {
+    request: { data: string; priority: number };
+    response: { status: "Accepted" | "Rejected" };
+  };
+  VendorQuery: {
+    request: { query: string };
+    response: { results: string[] };
+  };
+}
+```
+
+### Step 2: Augment OCPPMethodMap
+
+```typescript
+// src/ocpp-extensions.d.ts
+import type { MyVendorMethods } from "./vendor-types";
+
+declare module "ocpp-ws-io" {
+  interface OCPPMethodMap {
+    "vendor-proto": MyVendorMethods;
+  }
+}
+```
+
+### Step 3: Use Everywhere — Fully Typed
+
+```typescript
+import { OCPPClient, createValidator } from "ocpp-ws-io";
+import vendorSchemas from "./vendor-schemas.json";
+
+const vendorValidator = createValidator("vendor-proto", vendorSchemas);
+
+const client = new OCPPClient({
+  endpoint: "ws://localhost:3000",
+  identity: "CP001",
+  protocols: ["ocpp1.6", "vendor-proto"], // ✅ autocompletes
+  strictMode: true,
+  strictModeValidators: [vendorValidator],
+});
+
+// ✅ Fully typed handle
+client.handle("vendor-proto", "VendorAction", ({ params }) => {
+  console.log(params.data); // string
+  console.log(params.priority); // number
+  return { status: "Accepted" }; // typed response
+});
+
+// ✅ Fully typed call
+const res = await client.call("vendor-proto", "VendorQuery", {
+  query: "status",
+});
+console.log(res.results); // string[]
+```
+
 ---
 
 ## Clustering with Redis
@@ -472,9 +575,9 @@ const server = new OCPPServer({ protocols: ["ocpp2.0.1"] });
 
 server.setAdapter(
   new RedisAdapter({
-    pubClient: new Redis(),
-    subClient: new Redis(),
-    prefix: "ocpp:", // optional, default: 'ocpp-ws-io:'
+    pubClient: new Redis(process.env.REDIS_URL),
+    subClient: new Redis(process.env.REDIS_URL),
+    prefix: "ocpp-cluster:", // optional
   }),
 );
 
@@ -485,20 +588,27 @@ server.on("client", (client) => {
 await server.listen(3000);
 ```
 
-The adapter is generic — it works with `ioredis`, `redis` (node-redis), or any client implementing the `RedisLikeClient` interface.
+The adapter automatically detects and works with both `ioredis` and `node-redis` (v4+).
 
 ```typescript
 // With node-redis
 import { createClient } from "redis";
 
-const pub = createClient();
+const pub = createClient({ url: process.env.REDIS_URL });
 const sub = pub.duplicate();
-await pub.connect();
-await sub.connect();
+await Promise.all([pub.connect(), sub.connect()]);
 
 server.setAdapter(new RedisAdapter({ pubClient: pub, subClient: sub }));
 ```
 
+## Type Generation
+
+Re-generate TypeScript definitions from the latest OCPP JSON schemas:
+
+```bash
+npm run generate
+```
+
 ---
 
 ## API Reference
@@ -521,7 +631,7 @@ const client = new OCPPClient(options: ClientOptions);
 | --------------------------- | ------------------------ | ---------- | -------------------------------------------- |
 | `identity`                  | `string`                 | _required_ | Charging station ID                          |
 | `endpoint`                  | `string`                 | _required_ | WebSocket URL (`ws://` or `wss://`)          |
-| `protocols`                 | `string[]`               | `[]`       | OCPP subprotocols to negotiate               |
+| `protocols`                 | `OCPPProtocol[]`         | `[]`       | OCPP subprotocols to negotiate               |
 | `securityProfile`           | `SecurityProfile`        | `NONE`     | Security profile (0–3)                       |
 | `password`                  | `string \| Buffer`       | —          | Password for Basic Auth (Profile 1 & 2)      |
 | `tls`                       | `TLSOptions`             | —          | TLS/SSL options (Profile 2 & 3)              |
@@ -683,7 +793,7 @@ const server = new OCPPServer(options?: ServerOptions);
 
 | Option                      | Type                  | Default    | Description                               |
 | --------------------------- | --------------------- | ---------- | ----------------------------------------- |
-| `protocols`                 | `string[]`            | `[]`       | Accepted OCPP subprotocols                |
+| `protocols`                 | `OCPPProtocol[]`      | `[]`       | Accepted OCPP subprotocols                |
 | `securityProfile`           | `SecurityProfile`     | `NONE`     | Security profile for auto-created servers |
 | `tls`                       | `TLSOptions`          | —          | TLS options (Profile 2 & 3)               |
 | `callTimeoutMs`             | `number`              | `30000`    | Inherited by server clients               |
@@ -886,10 +996,11 @@ All types are exported for use in your application:
 import type {
   // OCPP protocol types (auto-generated)
   OCPPProtocol, // "ocpp1.6" | "ocpp2.0.1" | "ocpp2.1"
+  OCPPProtocolKey, // keyof OCPPMethodMap — extensible via module augmentation
   AllMethodNames, // Union of method names for a protocol
   OCPPRequestType, // Request type for a method + protocol
   OCPPResponseType, // Response type for a method + protocol
-  OCPPMethodMap, // Full method map for a protocol
+  OCPPMethodMap, // Full method map interface
 
   // OCPP message types
   OCPPCall,
@@ -931,9 +1042,246 @@ import type {
 
 ---
 
+## Browser Client
+
+`BrowserOCPPClient` is a lightweight OCPP WebSocket RPC client designed for **building charge point simulators, testing dashboards, and debugging tools** in the browser. It provides the same typed API as `OCPPClient` — without any Node.js dependencies.
+
+> **Note:** The browser client is designed for testing and simulating charge points — it does not support all OCPP features. Missing: Security Profiles (0–3), Strict Mode (schema validation), TLS/mTLS configuration, WebSocket Ping/Pong, and custom HTTP headers. For production charge point communication, use `OCPPClient` in a Node.js environment.
+
+```typescript
+import { BrowserOCPPClient } from "ocpp-ws-io/browser";
+```
+
+### Why a Separate Browser Client?
+
+`OCPPClient` depends on Node.js modules (`ws`, `node:crypto`, `node:events`, `node:net`). `BrowserOCPPClient` replaces all of these with browser-native APIs:
+
+| Feature           | `OCPPClient`           | `BrowserOCPPClient`        |
+| ----------------- | ---------------------- | -------------------------- |
+| WebSocket         | `ws` (Node.js)         | Native browser `WebSocket` |
+| Events            | `node:events`          | Custom `EventEmitter`      |
+| ID Generation     | `@paralleldrive/cuid2` | `@paralleldrive/cuid2`     |
+| Security Profiles | 0–3 (TLS, mTLS, certs) | N/A (handled by browser)   |
+| Custom Headers    | ✅ via `ws`            | ❌ browser limitation      |
+| Ping/Pong         | ✅                     | ❌ browser limitation      |
+| Type Safety       | ✅ Full                | ✅ Full (same types)       |
+| Reconnection      | ✅                     | ✅                         |
+| Strict Mode       | ✅                     | ❌                         |
+
+### Constructor
+
+```typescript
+const client = new BrowserOCPPClient(options: BrowserClientOptions);
+```
+
+**`BrowserClientOptions`**:
+
+| Option                      | Type                     | Default    | Description                            |
+| --------------------------- | ------------------------ | ---------- | -------------------------------------- |
+| `identity`                  | `string`                 | _required_ | Charging station ID                    |
+| `endpoint`                  | `string`                 | _required_ | WebSocket URL (`ws://` or `wss://`)    |
+| `protocols`                 | `string[]`               | `[]`       | OCPP subprotocols to negotiate         |
+| `query`                     | `Record<string, string>` | —          | Additional URL query parameters        |
+| `reconnect`                 | `boolean`                | `true`     | Auto-reconnect on disconnect           |
+| `maxReconnects`             | `number`                 | `Infinity` | Max reconnection attempts              |
+| `backoffMin`                | `number`                 | `1000`     | Initial reconnect delay (ms)           |
+| `backoffMax`                | `number`                 | `30000`    | Maximum reconnect delay (ms)           |
+| `callTimeoutMs`             | `number`                 | `30000`    | Default RPC call timeout (ms)          |
+| `callConcurrency`           | `number`                 | `1`        | Max concurrent outbound calls          |
+| `maxBadMessages`            | `number`                 | `Infinity` | Close after N consecutive bad messages |
+| `respondWithDetailedErrors` | `boolean`                | `false`    | Include error details in responses     |
+
+### Properties
+
+| Property          | Type                  | Description               |
+| ----------------- | --------------------- | ------------------------- |
+| `client.identity` | `string`              | Charging station identity |
+| `client.protocol` | `string \| undefined` | Negotiated subprotocol    |
+| `client.state`    | `ConnectionState`     | Current connection state  |
+
+### Static Constants
+
+```typescript
+BrowserOCPPClient.CONNECTING; // 0
+BrowserOCPPClient.OPEN; // 1
+BrowserOCPPClient.CLOSING; // 2
+BrowserOCPPClient.CLOSED; // 3
+```
+
+### Methods
+
+The API is identical to `OCPPClient` — all `call()`, `handle()`, `close()`, `sendRaw()`, `reconfigure()`, `removeHandler()`, and `removeAllHandlers()` methods work the same way with the same type signatures.
+
+```typescript
+// Connect
+await client.connect();
+
+// Version-aware typed call
+const result = await client.call("ocpp1.6", "BootNotification", {
+  chargePointVendor: "VendorX",
+  chargePointModel: "ModelY",
+});
+
+// Call with timeout and AbortSignal
+const controller = new AbortController();
+const res = await client.call(
+  "Heartbeat",
+  {},
+  {
+    timeoutMs: 5000,
+    signal: controller.signal,
+  },
+);
+
+// Register handlers (version-specific, generic, wildcard)
+client.handle("ocpp1.6", "Reset", ({ params }) => {
+  return { status: "Accepted" };
+});
+
+client.handle("StatusNotification", ({ params }) => {
+  return {};
+});
+
+client.handle((method, { params }) => {
+  console.log(`Unhandled: ${method}`);
+  return {};
+});
+
+// Close the connection
+await client.close();
+await client.close({ code: 1000, reason: "Normal" });
+await client.close({ awaitPending: true });
+await client.close({ force: true });
+
+// Reconfigure at runtime
+client.reconfigure({ callTimeoutMs: 10000, reconnect: false });
+```
+
+### Events
+
+```typescript
+client.on("open", (event) => {
+  /* connected */
+});
+client.on("close", ({ code, reason }) => {
+  /* disconnected */
+});
+client.on("error", (error) => {
+  /* error occurred */
+});
+client.on("connecting", ({ url }) => {
+  /* attempting connection */
+});
+client.on("reconnect", ({ attempt, delay }) => {
+  /* reconnecting */
+});
+client.on("message", (message) => {
+  /* any OCPP message */
+});
+client.on("call", (call) => {
+  /* incoming call */
+});
+client.on("callResult", (result) => {
+  /* call result received */
+});
+client.on("callError", (error) => {
+  /* call error received */
+});
+client.on("badMessage", ({ message, error }) => {
+  /* malformed message */
+});
+```
+
+### Framework Integration
+
+#### React
+
+```typescript
+import { useEffect, useRef, useState } from "react";
+import { BrowserOCPPClient } from "ocpp-ws-io/browser";
+
+function useOCPP(identity: string, endpoint: string) {
+  const clientRef = useRef<BrowserOCPPClient | null>(null);
+  const [connected, setConnected] = useState(false);
+
+  useEffect(() => {
+    const client = new BrowserOCPPClient({
+      identity,
+      endpoint,
+      protocols: ["ocpp1.6"],
+    });
+
+    client.on("open", () => setConnected(true));
+    client.on("close", () => setConnected(false));
+
+    client.connect();
+    clientRef.current = client;
+
+    return () => {
+      client.close();
+    };
+  }, [identity, endpoint]);
+
+  return { client: clientRef.current, connected };
+}
+```
+
+#### Next.js (Client Component)
+
+```typescript
+"use client";
+import { BrowserOCPPClient } from "ocpp-ws-io/browser";
+
+// ✅ Works in client components — no Node.js dependencies
+const client = new BrowserOCPPClient({
+  identity: "CP001",
+  endpoint: "wss://csms.example.com/ocpp",
+  protocols: ["ocpp1.6"],
+});
+```
+
+### Browser Exports
+
+All exports from `ocpp-ws-io/browser`:
+
+```typescript
+import {
+  // Client
+  BrowserOCPPClient,
+
+  // Error classes
+  RPCGenericError,
+  RPCNotImplementedError,
+  RPCNotSupportedError,
+  RPCInternalError,
+  RPCProtocolError,
+  RPCSecurityError,
+  RPCFormatViolationError,
+  RPCFormationViolationError,
+  RPCPropertyConstraintViolationError,
+  RPCOccurrenceConstraintViolationError,
+  RPCTypeConstraintViolationError,
+  RPCMessageTypeNotSupportedError,
+  RPCFrameworkError,
+  TimeoutError,
+
+  // Utilities
+  createRPCError,
+  getErrorPlainObject,
+
+  // Constants
+  ConnectionState,
+  MessageType,
+  NOREPLY,
+} from "ocpp-ws-io/browser";
+```
+
+---
+
 ## Requirements
 
-- **Node.js** ≥ 18.0.0
+- **Node.js** ≥ 18.0.0 (for `OCPPClient` and `OCPPServer`)
+- **Browser**: Any modern browser with `WebSocket` support (for `BrowserOCPPClient`)
 - **TypeScript** ≥ 5.0 (optional, but recommended)
 
 ## Inspired By

package/dist/adapters/redis.d.mts

@@ -1,4 +1,4 @@
-import { E as EventAdapterInterface } from '../types-CpxyZ6AL.mjs';
+import { E as EventAdapterInterface } from '../types-CJQYxOD8.mjs';
 import 'node:https';
 import 'node:http';
 import 'node:tls';
@@ -6,19 +6,16 @@ import 'node:stream';
 import 'node:events';
 import 'ajv';
 
-/**
- * Generic Redis-compatible client interface.
- * This works with both `ioredis` and the official `redis` package,
- * or any other client that implements these methods.
- */
 interface RedisLikeClient {
-    publish(channel: string, message: string): Promise<number | unknown>;
-    subscribe(channel: string, ...args: unknown[]): Promise<unknown>;
-    unsubscribe(channel: string, ...args: unknown[]): Promise<unknown>;
-    on(event: "message", callback: (channel: string, message: string) => void): unknown;
-    disconnect?(): Promise<void>;
-    quit?(): Promise<unknown>;
+    publish(channel: string, message: string): Promise<number | unknown | void>;
+    subscribe(channel: string, ...args: unknown[]): Promise<unknown | void>;
+    unsubscribe(channel: string, ...args: unknown[]): Promise<unknown | void>;
+    on?(event: "message", callback: (channel: string, message: string) => void): unknown;
+    disconnect?(): Promise<void> | void;
+    quit?(): Promise<unknown> | void;
+    isOpen?: boolean;
 }
+
 interface RedisAdapterOptions {
     /** Redis client for publishing */
     pubClient: RedisLikeClient;
@@ -30,45 +27,18 @@ interface RedisAdapterOptions {
 /**
  * Redis adapter for cross-process event distribution.
  *
- * This adapter is **generic** — it works with any Redis-compatible client
- * that implements the `RedisLikeClient` interface:
- * - `ioredis`
- * - `redis` (node-redis)
- * - Any custom implementation
- *
- * The user provides their own pub/sub client instances.
- * No Redis dependency is forced on the user.
- *
- * @example
- * ```typescript
- * // With ioredis
- * import Redis from 'ioredis';
- * const adapter = new RedisAdapter({
- *   pubClient: new Redis(),
- *   subClient: new Redis(),
- * });
- *
- * // With node-redis
- * import { createClient } from 'redis';
- * const pub = createClient();
- * const sub = pub.duplicate();
- * await pub.connect();
- * await sub.connect();
- * const adapter = new RedisAdapter({ pubClient: pub, subClient: sub });
- * ```
+ * Supports `ioredis` and `node-redis` (v4+).
  */
 declare class RedisAdapter implements EventAdapterInterface {
-    private _pub;
-    private _sub;
+    private _driver;
     private _prefix;
     private _handlers;
-    private _listening;
     constructor(options: RedisAdapterOptions);
-    private _setupSubscriber;
     publish(channel: string, data: unknown): Promise<void>;
     subscribe(channel: string, handler: (data: unknown) => void): Promise<void>;
     unsubscribe(channel: string): Promise<void>;
     disconnect(): Promise<void>;
+    private _handleMessage;
 }
 
-export { RedisAdapter, type RedisAdapterOptions, type RedisLikeClient };
+export { RedisAdapter, type RedisAdapterOptions };

package/dist/adapters/redis.d.ts

@@ -1,4 +1,4 @@
-import { E as EventAdapterInterface } from '../types-CpxyZ6AL.js';
+import { E as EventAdapterInterface } from '../types-CJQYxOD8.js';
 import 'node:https';
 import 'node:http';
 import 'node:tls';
@@ -6,19 +6,16 @@ import 'node:stream';
 import 'node:events';
 import 'ajv';
 
-/**
- * Generic Redis-compatible client interface.
- * This works with both `ioredis` and the official `redis` package,
- * or any other client that implements these methods.
- */
 interface RedisLikeClient {
-    publish(channel: string, message: string): Promise<number | unknown>;
-    subscribe(channel: string, ...args: unknown[]): Promise<unknown>;
-    unsubscribe(channel: string, ...args: unknown[]): Promise<unknown>;
-    on(event: "message", callback: (channel: string, message: string) => void): unknown;
-    disconnect?(): Promise<void>;
-    quit?(): Promise<unknown>;
+    publish(channel: string, message: string): Promise<number | unknown | void>;
+    subscribe(channel: string, ...args: unknown[]): Promise<unknown | void>;
+    unsubscribe(channel: string, ...args: unknown[]): Promise<unknown | void>;
+    on?(event: "message", callback: (channel: string, message: string) => void): unknown;
+    disconnect?(): Promise<void> | void;
+    quit?(): Promise<unknown> | void;
+    isOpen?: boolean;
 }
+
 interface RedisAdapterOptions {
     /** Redis client for publishing */
     pubClient: RedisLikeClient;
@@ -30,45 +27,18 @@ interface RedisAdapterOptions {
 /**
  * Redis adapter for cross-process event distribution.
  *
- * This adapter is **generic** — it works with any Redis-compatible client
- * that implements the `RedisLikeClient` interface:
- * - `ioredis`
- * - `redis` (node-redis)
- * - Any custom implementation
- *
- * The user provides their own pub/sub client instances.
- * No Redis dependency is forced on the user.
- *
- * @example
- * ```typescript
- * // With ioredis
- * import Redis from 'ioredis';
- * const adapter = new RedisAdapter({
- *   pubClient: new Redis(),
- *   subClient: new Redis(),
- * });
- *
- * // With node-redis
- * import { createClient } from 'redis';
- * const pub = createClient();
- * const sub = pub.duplicate();
- * await pub.connect();
- * await sub.connect();
- * const adapter = new RedisAdapter({ pubClient: pub, subClient: sub });
- * ```
+ * Supports `ioredis` and `node-redis` (v4+).
  */
 declare class RedisAdapter implements EventAdapterInterface {
-    private _pub;
-    private _sub;
+    private _driver;
     private _prefix;
     private _handlers;
-    private _listening;
     constructor(options: RedisAdapterOptions);
-    private _setupSubscriber;
     publish(channel: string, data: unknown): Promise<void>;
     subscribe(channel: string, handler: (data: unknown) => void): Promise<void>;
     unsubscribe(channel: string): Promise<void>;
     disconnect(): Promise<void>;
+    private _handleMessage;
 }
 
-export { RedisAdapter, type RedisAdapterOptions, type RedisLikeClient };
+export { RedisAdapter, type RedisAdapterOptions };