ocpp-protocol-proxy 0.1.1

package/README.md

@@ -0,0 +1,196 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rohittiwari-dev/ocpp-ws-io/main/assets/ocpp-protocol-proxy.png" alt="ocpp-protocol-proxy" width="420" />
+</p>
+
+
+**Transport-agnostic OCPP version translation proxy** — translate any OCPP version to any other, with pluggable middleware, stateful session management, and spec-compliant presets.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](../../LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+
+Part of the [ocpp-ws-io](https://ocpp-ws-io.rohittiwari.me) ecosystem.
+
+---
+
+## Why?
+
+Legacy OCPP 1.6 charge points can't speak to modern OCPP 2.1 central systems. Instead of rewriting firmware or maintaining dual-protocol backends, drop a translation proxy in between.
+
+```
+┌─────────┐     OCPP 1.6      ┌───────────┐     OCPP 2.1      ┌──────┐
+│  EVSE   │ ───────────────── │   PROXY   │ ───────────────── │ CSMS │
+│  (1.6)  │                   │ (translate)│                   │(2.1) │
+└─────────┘                   └───────────┘                   └──────┘
+```
+
+## Features
+
+- ⚡ **Any-to-any translation** — 1.6 ↔ 2.0.1 ↔ 2.1
+- 🔌 **Transport agnostic** — Core logic doesn't depend on WebSockets or Node.js
+- 🧩 **Modular presets** — Import only the OCPP profiles you need
+- 🔗 **Middleware pipeline** — Pre/post translation hooks for logging, validation, telemetry
+- 💾 **Stateful sessions** — UUID ↔ integer transaction ID mapping across messages
+- 📊 **Built-in telemetry** — Latency tracking middleware included
+- ✅ **All 28 OCPP 1.6 messages** — Complete Core + optional profiles mapped to 2.1
+
+## Install
+
+```bash
+npm install ocpp-protocol-proxy
+```
+
+## Quick Start
+
+### Basic Usage with Presets
+
+```typescript
+import { OCPPProtocolProxy, presets, OcppWsIoAdapter } from "ocpp-protocol-proxy";
+
+const proxy = new OCPPProtocolProxy({
+  upstreamEndpoint: "ws://your-csms:9000",
+  upstreamProtocol: "ocpp2.1",
+});
+
+// Load all OCPP 1.6 → 2.1 translation presets
+proxy.translate(presets.ocpp16_to_ocpp21);
+
+const adapter = new OcppWsIoAdapter({
+  port: 9001,
+  protocols: ["ocpp1.6"],
+});
+
+await proxy.listenOnAdapter(adapter);
+```
+
+### Custom Overrides
+
+Use presets as a base and override specific actions:
+
+```typescript
+proxy.translate({
+  upstream: {
+    ...presets.ocpp16_to_ocpp21.upstream,
+
+    // Override with custom business logic
+    "ocpp1.6:StartTransaction": async (params, ctx) => {
+      console.log(`Custom StartTx for ${ctx.identity}`, params);
+      return {
+        action: "TransactionEvent",
+        payload: { /* your custom 2.1 mapping */ },
+      };
+    },
+  },
+  downstream: { ...presets.ocpp16_to_ocpp21.downstream },
+  responses: { ...presets.ocpp16_to_ocpp21.responses },
+  errors: { ...presets.ocpp16_to_ocpp21.errors },
+});
+```
+
+## Selective Presets
+
+Import only the OCPP profiles you need for tree-shaking:
+
+```typescript
+import {
+  corePreset,
+  smartChargingPreset,
+  firmwarePreset,
+  reservationPreset,
+  localAuthPreset,
+} from "ocpp-protocol-proxy";
+```
+
+| Preset | Profile | Messages |
+|:---|:---|:---|
+| `corePreset` | Core (mandatory) | 16: Boot, Auth, Start/Stop Tx, MeterValues, StatusNotification, Reset, Unlock, TriggerMessage, and more |
+| `smartChargingPreset` | Smart Charging | SetChargingProfile, ClearChargingProfile, GetCompositeSchedule |
+| `firmwarePreset` | Firmware Mgmt | UpdateFirmware, FirmwareStatusNotification, GetLog→GetDiagnostics |
+| `reservationPreset` | Reservation | ReserveNow, CancelReservation |
+| `localAuthPreset` | Local Auth List | GetLocalListVersion, SendLocalList |
+
+## Middleware
+
+Intercept messages before or after translation:
+
+```typescript
+import type { ProxyMiddleware } from "ocpp-protocol-proxy";
+
+const logger: ProxyMiddleware = async (message, context, direction, phase) => {
+  console.log(`[${phase}] ${direction} — ${context.identity}`, message);
+  return undefined; // pass through unchanged
+};
+
+const proxy = new OCPPProtocolProxy({
+  upstreamEndpoint: "ws://csms:9000",
+  upstreamProtocol: "ocpp2.1",
+  middlewares: [logger],
+});
+```
+
+Middleware runs at 4 lifecycle points:
+| Phase | Direction | When |
+|:---|:---|:---|
+| `pre` | `upstream` | Before translating EVSE→CSMS calls |
+| `post` | `upstream` | After translating, before forwarding to CSMS |
+| `pre` | `response` | Before translating CSMS response back |
+| `post` | `response` | After translating, before returning to EVSE |
+
+## Custom Session Store
+
+The default `InMemorySessionStore` works for single-instance deployments. For clustered setups, implement `ISessionStore`:
+
+```typescript
+import type { ISessionStore } from "ocpp-protocol-proxy";
+
+class RedisSessionStore implements ISessionStore {
+  async set(identity: string, key: string, value: any) { /* ... */ }
+  async get<T>(identity: string, key: string): Promise<T | undefined> { /* ... */ }
+  async delete(identity: string, key: string) { /* ... */ }
+  async clear(identity: string) { /* ... */ }
+}
+```
+
+## Events
+
+```typescript
+proxy.on("connection", (identity, protocol) => { /* EVSE connected */ });
+proxy.on("disconnect", (identity) => { /* EVSE disconnected */ });
+proxy.on("translationError", (err, msg, ctx) => { /* translation failed */ });
+proxy.on("middlewareError", (err, msg, ctx) => { /* middleware threw */ });
+```
+
+## Architecture
+
+```
+src/
+├── core/
+│   ├── types.ts          # OCPPMessage, TranslationMap, ITransportAdapter
+│   ├── translator.ts     # Pure translation engine
+│   └── session.ts        # ISessionStore + InMemorySessionStore
+├── presets/
+│   ├── index.ts          # Merged preset + mergePresets utility
+│   ├── core.ts           # Core profile (16 messages)
+│   ├── smart-charging.ts # Smart Charging (3 messages)
+│   ├── firmware.ts       # Firmware Management (4 messages)
+│   ├── reservation.ts    # Reservation (2 messages)
+│   ├── local-auth.ts     # Local Auth List (2 messages)
+│   └── status-enums.ts   # StatusNotification enum mapping tables
+├── adapters/
+│   └── ocpp-ws-io.adapter.ts  # WebSocket adapter using ocpp-ws-io
+├── middlewares/
+│   └── telemetry.ts      # Latency tracking middleware
+├── proxy.ts              # OCPPProtocolProxy orchestrator
+└── index.ts              # Public API
+```
+
+## Related Packages
+
+| Package | Description |
+|:---|:---|
+| [ocpp-ws-io](https://npmjs.com/ocpp-ws-io) | Core OCPP WebSocket RPC client & server |
+| [ocpp-ws-cli](https://npmjs.com/ocpp-ws-cli) | CLI for simulation & testing |
+| [voltlog-io](https://npmjs.com/voltlog-io) | Structured logger |
+
+## License
+
+[MIT](../../LICENSE) © 2026 Rohit Tiwari

package/dist/index.d.ts

@@ -0,0 +1,251 @@
+import { OCPPClient } from 'ocpp-ws-io';
+import { EventEmitter } from 'node:events';
+
+/**
+ * A generic interface for storing session state per connection/identity
+ * across asynchronous OCPP messages.
+ * E.g., mapping a numeric 1.6 transactionId to a 2.1 UUID string.
+ */
+interface ISessionStore {
+    /**
+     * Set a key-value pair tied to a specific identity's session.
+     */
+    set(identity: string, key: string, value: any): Promise<void>;
+    /**
+     * Retrieve a value tied to a specific identity's session.
+     */
+    get<T = any>(identity: string, key: string): Promise<T | undefined>;
+    /**
+     * Delete a key tied to a specific identity's session.
+     */
+    delete(identity: string, key: string): Promise<void>;
+    /**
+     * Clear all session data for a specific identity (e.g. on disconnect).
+     */
+    clear(identity: string): Promise<void>;
+}
+declare class InMemorySessionStore implements ISessionStore {
+    private store;
+    set(identity: string, key: string, value: any): Promise<void>;
+    get<T = any>(identity: string, key: string): Promise<T | undefined>;
+    delete(identity: string, key: string): Promise<void>;
+    clear(identity: string): Promise<void>;
+}
+
+declare enum MessageType {
+    CALL = 2,
+    CALLRESULT = 3,
+    CALLERROR = 4
+}
+type OCPPMessage = {
+    type: MessageType.CALL;
+    messageId: string;
+    action: string;
+    payload: any;
+} | {
+    type: MessageType.CALLRESULT;
+    messageId: string;
+    payload: any;
+} | {
+    type: MessageType.CALLERROR;
+    messageId: string;
+    errorCode: string;
+    errorDescription: string;
+    errorDetails: any;
+};
+interface TranslationContext {
+    identity: string;
+    sourceProtocol: string;
+    targetProtocol: string;
+    session: ISessionStore;
+}
+type TranslationResult = {
+    action?: string;
+    payload: any;
+};
+type MiddlewarePhase = "pre" | "post";
+type MiddlewareDirection = "upstream" | "downstream" | "response" | "error";
+/**
+ * Middleware function signature.
+ * Return the (possibly mutated) message to pass it along,
+ * or return undefined to pass the original message unchanged.
+ */
+type ProxyMiddleware = (message: OCPPMessage, context: TranslationContext, direction: MiddlewareDirection, phase: MiddlewarePhase) => Promise<OCPPMessage | undefined>;
+type TranslationMap = {
+    /** EVSE -> CSMS call mappers, keyed by `sourceProtocol:Action` */
+    upstream: Record<string, (params: any, context: TranslationContext) => TranslationResult | Promise<TranslationResult>>;
+    /** CSMS -> EVSE call mappers, keyed by `targetProtocol:Action` */
+    downstream: Record<string, (params: any, context: TranslationContext) => TranslationResult | Promise<TranslationResult>>;
+    /** Response payload mappers, keyed by `targetProtocol:ActionResponse` */
+    responses?: Record<string, (params: any, context: TranslationContext) => any | Promise<any>>;
+    /** Error mappers, keyed by `sourceProtocol:Error` */
+    errors?: Record<string, (errorCode: string, errorDescription: string, errorDetails: any, context: TranslationContext) => {
+        errorCode: string;
+        errorDescription: string;
+        errorDetails: any;
+    } | Promise<{
+        errorCode: string;
+        errorDescription: string;
+        errorDetails: any;
+    }>>;
+};
+interface IConnection {
+    identity: string;
+    protocol: string;
+    send(message: OCPPMessage): Promise<OCPPMessage | undefined>;
+    onMessage(handler: (message: OCPPMessage) => Promise<OCPPMessage | undefined>): void;
+    onClose(handler: () => void): void;
+}
+interface ITransportAdapter {
+    listen(onConnection: (connection: IConnection) => void): Promise<void>;
+    close(): Promise<void>;
+}
+
+declare class OcppWsIoConnection implements IConnection {
+    private client;
+    identity: string;
+    protocol: string;
+    private messageHandler?;
+    constructor(client: OCPPClient);
+    private setupCatchAll;
+    send(message: OCPPMessage): Promise<OCPPMessage | undefined>;
+    onMessage(handler: (message: OCPPMessage) => Promise<OCPPMessage | undefined>): void;
+    onClose(handler: () => void): void;
+}
+interface WsAdapterOptions {
+    port: number;
+    protocols: string[];
+}
+declare class OcppWsIoAdapter implements ITransportAdapter {
+    private server;
+    private port;
+    private protocols;
+    httpServer?: any;
+    constructor(options: WsAdapterOptions);
+    listen(onConnection: (connection: IConnection) => void): Promise<void>;
+    close(): Promise<void>;
+}
+
+declare class OCPPTranslator {
+    private translationMap;
+    constructor(translationMap: TranslationMap);
+    updateMap(map: Partial<TranslationMap>): void;
+    translateUpstreamCall(message: Extract<OCPPMessage, {
+        type: MessageType.CALL;
+    }>, context: TranslationContext): Promise<Extract<OCPPMessage, {
+        type: MessageType.CALL;
+    }>>;
+    translateDownstreamCall(message: Extract<OCPPMessage, {
+        type: MessageType.CALL;
+    }>, context: TranslationContext): Promise<Extract<OCPPMessage, {
+        type: MessageType.CALL;
+    }>>;
+    translateCallResult(message: Extract<OCPPMessage, {
+        type: MessageType.CALLRESULT;
+    }>, originalAction: string, context: TranslationContext): Promise<Extract<OCPPMessage, {
+        type: MessageType.CALLRESULT;
+    }>>;
+    translateCallError(message: Extract<OCPPMessage, {
+        type: MessageType.CALLERROR;
+    }>, context: TranslationContext): Promise<Extract<OCPPMessage, {
+        type: MessageType.CALLERROR;
+    }>>;
+}
+
+/**
+ * Example built-in middleware that tracks translation latency.
+ * In production, push metrics to Datadog, Prometheus, or OpenTelemetry.
+ */
+declare const TelemetryMiddleware: ProxyMiddleware;
+
+/**
+ * Core profile preset — the only mandatory OCPP 1.6 profile.
+ * Covers all 16 Core messages.
+ */
+declare const corePreset: Partial<TranslationMap>;
+
+/**
+ * Firmware Management profile preset.
+ * Note: OCPP 2.1 renames GetDiagnostics→GetLog and
+ * DiagnosticsStatusNotification→LogStatusNotification.
+ */
+declare const firmwarePreset: Partial<TranslationMap>;
+
+/**
+ * Local Auth List Management profile preset.
+ */
+declare const localAuthPreset: Partial<TranslationMap>;
+
+/**
+ * Reservation profile preset.
+ */
+declare const reservationPreset: Partial<TranslationMap>;
+
+/**
+ * Smart Charging profile preset.
+ * Covers: SetChargingProfile, ClearChargingProfile, GetCompositeSchedule.
+ */
+declare const smartChargingPreset: Partial<TranslationMap>;
+
+/**
+ * OCPP 1.6 status → OCPP 2.1 connectorStatus enum mapping.
+ * Per OCPP 2.0.1 Part 2, Section K.10 — ConnectorStatusEnumType.
+ */
+declare const statusMap16to21: Record<string, string>;
+/**
+ * OCPP 2.1 connectorStatus → OCPP 1.6 status mapping (best-effort reverse).
+ * 2.1 has fewer granular statuses, so some information is lost.
+ */
+declare const statusMap21to16: Record<string, string>;
+/**
+ * OCPP 2.1 operationalStatus → OCPP 1.6 availability type mapping.
+ */
+declare const availabilityMap21to16: Record<string, string>;
+/**
+ * OCPP 1.6 availability type → OCPP 2.1 operationalStatus mapping.
+ */
+declare const availabilityMap16to21: Record<string, string>;
+
+/**
+ * Combined preset dictionary.
+ * `presets.ocpp16_to_ocpp21` includes ALL profiles merged.
+ *
+ * For selective use, import individual presets:
+ * ```ts
+ * import { corePreset, smartChargingPreset } from "ocpp-protocol-proxy";
+ * proxy.translate(corePreset);
+ * proxy.translate(smartChargingPreset);
+ * ```
+ */
+declare const presets: {
+    ocpp16_to_ocpp21: TranslationMap;
+};
+
+interface OCPPProtocolProxyOptions {
+    upstreamEndpoint: string;
+    upstreamProtocol: string;
+    sessionStore?: ISessionStore;
+    middlewares?: ProxyMiddleware[];
+}
+declare class OCPPProtocolProxy extends EventEmitter {
+    private options;
+    private translator;
+    private clients;
+    private sessionStore;
+    private adapters;
+    constructor(options: OCPPProtocolProxyOptions);
+    /** Register translation maps (can be called multiple times to layer presets). */
+    translate(map: Partial<TranslationMap>): void;
+    /** Start listening on a transport adapter (WS, HTTP, etc.). */
+    listenOnAdapter(adapter: ITransportAdapter): Promise<void>;
+    /**
+     * Execute all registered middlewares sequentially.
+     * If a middleware returns a message, it replaces the current message.
+     */
+    private executeMiddlewares;
+    private handleNewConnection;
+    /** Gracefully close all upstream connections and adapters. */
+    close(): Promise<void>;
+}
+
+export { type IConnection, type ISessionStore, type ITransportAdapter, InMemorySessionStore, MessageType, type MiddlewareDirection, type MiddlewarePhase, type OCPPMessage, OCPPProtocolProxy, type OCPPProtocolProxyOptions, OCPPTranslator, OcppWsIoAdapter, OcppWsIoConnection, type ProxyMiddleware, TelemetryMiddleware, type TranslationContext, type TranslationMap, type TranslationResult, type WsAdapterOptions, availabilityMap16to21, availabilityMap21to16, corePreset, firmwarePreset, localAuthPreset, presets, reservationPreset, smartChargingPreset, statusMap16to21, statusMap21to16 };

package/dist/index.js

@@ -0,0 +1,871 @@
+// src/core/types.ts
+var MessageType = /* @__PURE__ */ ((MessageType2) => {
+  MessageType2[MessageType2["CALL"] = 2] = "CALL";
+  MessageType2[MessageType2["CALLRESULT"] = 3] = "CALLRESULT";
+  MessageType2[MessageType2["CALLERROR"] = 4] = "CALLERROR";
+  return MessageType2;
+})(MessageType || {});
+
+// src/adapters/ocpp-ws-io.adapter.ts
+var OcppWsIoConnection = class {
+  constructor(client) {
+    this.client = client;
+    this.identity = client.identity;
+    this.protocol = client.protocol || "ocpp1.6";
+    this.setupCatchAll();
+  }
+  identity;
+  protocol;
+  messageHandler;
+  setupCatchAll() {
+    this.client.handle(async (action, ctx) => {
+      const incomingMessage = {
+        type: 2 /* CALL */,
+        messageId: ctx.messageId || `msg-${Date.now()}`,
+        action,
+        payload: ctx.params
+      };
+      if (!this.messageHandler) {
+        throw new Error("No message handler attached to connection");
+      }
+      const result = await this.messageHandler(incomingMessage);
+      if (result) {
+        if (result.type === 3 /* CALLRESULT */) {
+          return result.payload;
+        }
+        if (result.type === 4 /* CALLERROR */) {
+          const err = new Error(
+            result.errorDescription || "Unknown error occurred during proxy processing"
+          );
+          err.code = result.errorCode;
+          throw err;
+        }
+      }
+      return {};
+    });
+  }
+  async send(message) {
+    if (message.type === 2 /* CALL */) {
+      const rawResult = await this.client.call(message.action, message.payload);
+      return {
+        type: 3 /* CALLRESULT */,
+        messageId: message.messageId,
+        payload: rawResult
+      };
+    }
+    return void 0;
+  }
+  onMessage(handler) {
+    this.messageHandler = handler;
+  }
+  onClose(handler) {
+    this.client.on("close", handler);
+  }
+};
+var OcppWsIoAdapter = class {
+  server;
+  port;
+  protocols;
+  httpServer;
+  constructor(options) {
+    this.port = options.port;
+    this.protocols = options.protocols;
+  }
+  async listen(onConnection) {
+    const { OCPPServer } = await import("ocpp-ws-io");
+    this.server = new OCPPServer({ protocols: this.protocols });
+    this.server.on("client", (client) => {
+      const conn = new OcppWsIoConnection(client);
+      onConnection(conn);
+    });
+    this.httpServer = await this.server.listen(this.port);
+  }
+  async close() {
+    if (this.server) {
+      await this.server.close();
+    }
+  }
+};
+
+// src/core/session.ts
+var InMemorySessionStore = class {
+  // Map<identity, Map<key, value>>
+  store = /* @__PURE__ */ new Map();
+  async set(identity, key, value) {
+    if (!this.store.has(identity)) {
+      this.store.set(identity, /* @__PURE__ */ new Map());
+    }
+    this.store.get(identity).set(key, value);
+  }
+  async get(identity, key) {
+    const session = this.store.get(identity);
+    return session ? session.get(key) : void 0;
+  }
+  async delete(identity, key) {
+    const session = this.store.get(identity);
+    if (session) {
+      session.delete(key);
+    }
+  }
+  async clear(identity) {
+    this.store.delete(identity);
+  }
+};
+
+// src/core/translator.ts
+var OCPPTranslator = class {
+  constructor(translationMap) {
+    this.translationMap = translationMap;
+  }
+  updateMap(map) {
+    this.translationMap.upstream = {
+      ...this.translationMap.upstream,
+      ...map.upstream
+    };
+    this.translationMap.downstream = {
+      ...this.translationMap.downstream,
+      ...map.downstream
+    };
+    if (map.responses) {
+      this.translationMap.responses = {
+        ...this.translationMap.responses,
+        ...map.responses
+      };
+    }
+    if (map.errors) {
+      this.translationMap.errors = {
+        ...this.translationMap.errors,
+        ...map.errors
+      };
+    }
+  }
+  async translateUpstreamCall(message, context) {
+    const key = `${context.sourceProtocol}:${message.action}`;
+    const mapper = this.translationMap.upstream[key];
+    if (!mapper) {
+      return message;
+    }
+    const translated = await mapper(message.payload, context);
+    return {
+      type: 2 /* CALL */,
+      messageId: message.messageId,
+      action: translated.action || message.action,
+      payload: translated.payload
+    };
+  }
+  async translateDownstreamCall(message, context) {
+    const key = `${context.targetProtocol}:${message.action}`;
+    const mapper = this.translationMap.downstream[key];
+    if (!mapper) {
+      return message;
+    }
+    const translated = await mapper(message.payload, context);
+    return {
+      type: 2 /* CALL */,
+      messageId: message.messageId,
+      action: translated.action || message.action,
+      payload: translated.payload
+    };
+  }
+  async translateCallResult(message, originalAction, context) {
+    const responseKey = `${context.targetProtocol}:${originalAction}Response`;
+    const responseMapper = this.translationMap.responses?.[responseKey];
+    if (responseMapper) {
+      const translatedPayload = await responseMapper(message.payload, context);
+      return {
+        type: 3 /* CALLRESULT */,
+        messageId: message.messageId,
+        payload: translatedPayload
+      };
+    }
+    return message;
+  }
+  async translateCallError(message, context) {
+    const errorKey = `${context.sourceProtocol}:Error`;
+    const errorMapper = this.translationMap.errors?.[errorKey];
+    if (errorMapper) {
+      const translated = await errorMapper(
+        message.errorCode,
+        message.errorDescription,
+        message.errorDetails,
+        context
+      );
+      return {
+        type: 4 /* CALLERROR */,
+        messageId: message.messageId,
+        errorCode: translated.errorCode,
+        errorDescription: translated.errorDescription,
+        errorDetails: translated.errorDetails
+      };
+    }
+    return message;
+  }
+};
+
+// src/middlewares/telemetry.ts
+var TelemetryMiddleware = async (message, context, _direction, phase) => {
+  if (phase === "pre") {
+    await context.session.set(
+      context.identity,
+      `telemetryStart_${message.messageId}`,
+      Date.now()
+    );
+  } else if (phase === "post") {
+    const startTime = await context.session.get(
+      context.identity,
+      `telemetryStart_${message.messageId}`
+    );
+    if (startTime) {
+      const _latency = Date.now() - startTime;
+      await context.session.delete(
+        context.identity,
+        `telemetryStart_${message.messageId}`
+      );
+    }
+  }
+  return void 0;
+};
+
+// src/presets/core.ts
+import { randomUUID } from "crypto";
+
+// src/presets/status-enums.ts
+var statusMap16to21 = {
+  Available: "Available",
+  Preparing: "Occupied",
+  Charging: "Occupied",
+  SuspendedEVSE: "Occupied",
+  SuspendedEV: "Occupied",
+  Finishing: "Occupied",
+  Reserved: "Reserved",
+  Unavailable: "Unavailable",
+  Faulted: "Faulted"
+};
+var statusMap21to16 = {
+  Available: "Available",
+  Occupied: "Charging",
+  // Best guess — could be Preparing/SuspendedEV/etc.
+  Reserved: "Reserved",
+  Unavailable: "Unavailable",
+  Faulted: "Faulted"
+};
+var availabilityMap21to16 = {
+  Operative: "Available",
+  Inoperative: "Unavailable"
+};
+var availabilityMap16to21 = {
+  Available: "Operative",
+  Unavailable: "Inoperative"
+};
+
+// src/presets/core.ts
+var txIdCounter = 1;
+var corePreset = {
+  upstream: {
+    "ocpp1.6:BootNotification": (params) => ({
+      action: "BootNotification",
+      payload: {
+        reason: "PowerUp",
+        chargingStation: {
+          model: params.chargePointModel,
+          vendorName: params.chargePointVendor,
+          firmwareVersion: params.firmwareVersion,
+          serialNumber: params.chargePointSerialNumber
+        }
+      }
+    }),
+    "ocpp1.6:Heartbeat": () => ({
+      action: "Heartbeat",
+      payload: {}
+    }),
+    "ocpp1.6:StatusNotification": (params) => ({
+      action: "StatusNotification",
+      payload: {
+        timestamp: params.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+        connectorStatus: statusMap16to21[params.status] || params.status,
+        evseId: params.connectorId,
+        connectorId: params.connectorId
+      }
+    }),
+    "ocpp1.6:Authorize": (params) => ({
+      action: "Authorize",
+      payload: {
+        idToken: {
+          idToken: params.idTag,
+          type: "ISO14443"
+        }
+      }
+    }),
+    "ocpp1.6:StartTransaction": async (params, ctx) => {
+      const proxyGeneratedTxId = randomUUID();
+      await ctx.session.set(ctx.identity, "pendingStartTx", {
+        uuid: proxyGeneratedTxId,
+        connectorId: params.connectorId
+      });
+      return {
+        action: "TransactionEvent",
+        payload: {
+          eventType: "Started",
+          timestamp: params.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+          triggerReason: "Authorized",
+          seqNo: 0,
+          transactionInfo: {
+            transactionId: proxyGeneratedTxId
+          },
+          idToken: {
+            idToken: params.idTag,
+            type: "ISO14443"
+          },
+          evse: {
+            id: params.connectorId,
+            connectorId: params.connectorId
+          },
+          meterValue: [
+            {
+              timestamp: params.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+              sampledValue: [
+                {
+                  value: params.meterStart,
+                  measurand: "Energy.Active.Import.Register"
+                }
+              ]
+            }
+          ]
+        }
+      };
+    },
+    "ocpp1.6:StopTransaction": async (params, ctx) => {
+      const numericId = params.transactionId;
+      const uuid = await ctx.session.get(
+        ctx.identity,
+        `txId_int2uuid_${numericId}`
+      );
+      return {
+        action: "TransactionEvent",
+        payload: {
+          eventType: "Ended",
+          timestamp: params.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+          triggerReason: params.reason || "Local",
+          seqNo: 1,
+          transactionInfo: {
+            transactionId: uuid || randomUUID(),
+            stoppedReason: params.reason || "Local"
+          },
+          idToken: params.idTag ? {
+            idToken: params.idTag,
+            type: "ISO14443"
+          } : void 0,
+          meterValue: [
+            {
+              timestamp: params.timestamp || (/* @__PURE__ */ new Date()).toISOString(),
+              sampledValue: [
+                {
+                  value: params.meterStop,
+                  measurand: "Energy.Active.Import.Register"
+                }
+              ]
+            }
+          ]
+        }
+      };
+    },
+    "ocpp1.6:MeterValues": async (params, ctx) => {
+      const numericId = params.transactionId;
+      const uuid = numericId ? await ctx.session.get(
+        ctx.identity,
+        `txId_int2uuid_${numericId}`
+      ) : void 0;
+      return {
+        action: "TransactionEvent",
+        payload: {
+          eventType: "Updated",
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          triggerReason: "MeterValuePeriodic",
+          seqNo: 0,
+          transactionInfo: uuid ? { transactionId: uuid } : void 0,
+          evse: {
+            id: params.connectorId,
+            connectorId: params.connectorId
+          },
+          meterValue: (params.meterValue || []).map((mv) => ({
+            timestamp: mv.timestamp,
+            sampledValue: (mv.sampledValue || []).map((sv) => ({
+              value: sv.value,
+              measurand: sv.measurand || "Energy.Active.Import.Register",
+              unit: sv.unit,
+              context: sv.context,
+              location: sv.location
+            }))
+          }))
+        }
+      };
+    }
+  },
+  downstream: {
+    "ocpp2.1:RemoteStartTransaction": (params) => ({
+      action: "RemoteStartTransaction",
+      payload: {
+        connectorId: params.evseId || 1,
+        idTag: params.idToken?.idToken
+      }
+    }),
+    "ocpp2.1:RemoteStopTransaction": async (params, ctx) => {
+      const uuid = params.transactionId;
+      const numericId = uuid ? await ctx.session.get(ctx.identity, `txId_uuid2int_${uuid}`) : void 0;
+      return {
+        action: "RemoteStopTransaction",
+        payload: {
+          transactionId: numericId ?? 0
+        }
+      };
+    },
+    "ocpp2.1:ChangeAvailability": (params) => ({
+      action: "ChangeAvailability",
+      payload: {
+        connectorId: params.evse?.connectorId || params.evse?.id || 0,
+        type: params.operationalStatus === "Operative" ? "Operative" : "Inoperative"
+      }
+    }),
+    "ocpp2.1:Reset": (params) => ({
+      action: "Reset",
+      payload: {
+        type: params.type === "OnIdle" ? "Soft" : params.type
+      }
+    }),
+    "ocpp2.1:UnlockConnector": (params) => ({
+      action: "UnlockConnector",
+      payload: {
+        connectorId: params.connectorId || params.evseId || 1
+      }
+    }),
+    "ocpp2.1:TriggerMessage": (params) => ({
+      action: "TriggerMessage",
+      payload: {
+        requestedMessage: params.requestedMessage,
+        connectorId: params.evse?.connectorId || params.evse?.id
+      }
+    })
+  },
+  responses: {
+    "ocpp2.1:BootNotificationResponse": (params) => ({
+      currentTime: params.currentTime,
+      interval: params.interval,
+      status: params.status
+    }),
+    "ocpp2.1:HeartbeatResponse": (params) => ({
+      currentTime: params.currentTime
+    }),
+    "ocpp2.1:StatusNotificationResponse": () => ({}),
+    "ocpp2.1:AuthorizeResponse": (params) => ({
+      idTagInfo: {
+        status: params.idTokenInfo?.status || "Accepted"
+      }
+    }),
+    "ocpp2.1:TransactionEventResponse": async (params, ctx) => {
+      const pending = await ctx.session.get(ctx.identity, "pendingStartTx");
+      const numericTxId = txIdCounter++;
+      if (pending) {
+        await ctx.session.set(
+          ctx.identity,
+          `txId_int2uuid_${numericTxId}`,
+          pending.uuid
+        );
+        await ctx.session.set(
+          ctx.identity,
+          `txId_uuid2int_${pending.uuid}`,
+          numericTxId
+        );
+        await ctx.session.delete(ctx.identity, "pendingStartTx");
+      }
+      return {
+        idTagInfo: {
+          status: params.idTokenInfo?.status || "Accepted"
+        },
+        transactionId: numericTxId
+      };
+    }
+  },
+  errors: {
+    "ocpp2.1:Error": (errorCode, errorDescription, errorDetails) => {
+      const errorMap = {
+        SecurityError: "InternalError",
+        FormatViolation: "FormationViolation",
+        MessageTypeNotSupported: "NotSupported",
+        PropertyConstraintViolation: "PropertyConstraintViolation",
+        OccurrenceConstraintViolation: "OccurenceConstraintViolation",
+        TypeConstraintViolation: "TypeConstraintViolation",
+        GenericError: "GenericError",
+        NotImplemented: "NotImplemented",
+        NotSupported: "NotSupported",
+        ProtocolError: "ProtocolError",
+        RpcFrameworkError: "InternalError"
+      };
+      return {
+        errorCode: errorMap[errorCode] || "InternalError",
+        errorDescription,
+        errorDetails
+      };
+    }
+  }
+};
+
+// src/presets/firmware.ts
+var firmwarePreset = {
+  upstream: {
+    "ocpp1.6:FirmwareStatusNotification": (params) => ({
+      action: "FirmwareStatusNotification",
+      payload: {
+        status: params.status
+      }
+    }),
+    "ocpp1.6:DiagnosticsStatusNotification": (params) => ({
+      action: "LogStatusNotification",
+      payload: {
+        status: params.status === "Uploaded" ? "Uploaded" : params.status,
+        requestId: 0
+      }
+    })
+  },
+  downstream: {
+    "ocpp2.1:UpdateFirmware": (params) => ({
+      action: "UpdateFirmware",
+      payload: {
+        location: params.firmware?.location || params.location,
+        retrieveDate: params.firmware?.retrieveDateTime || params.retrieveDate,
+        retries: params.retries,
+        retryInterval: params.retryInterval
+      }
+    }),
+    "ocpp2.1:GetLog": (params) => ({
+      action: "GetDiagnostics",
+      payload: {
+        location: params.log?.remoteLocation || "",
+        startTime: params.log?.oldestTimestamp,
+        stopTime: params.log?.latestTimestamp,
+        retries: params.retries,
+        retryInterval: params.retryInterval
+      }
+    })
+  }
+};
+
+// src/presets/local-auth.ts
+var localAuthPreset = {
+  downstream: {
+    "ocpp2.1:GetLocalListVersion": () => ({
+      action: "GetLocalListVersion",
+      payload: {}
+    }),
+    "ocpp2.1:SendLocalList": (params) => ({
+      action: "SendLocalList",
+      payload: {
+        listVersion: params.versionNumber,
+        updateType: params.updateType,
+        localAuthorizationList: (params.localAuthorizationList || []).map(
+          (entry) => ({
+            idTag: entry.idToken?.idToken,
+            idTagInfo: entry.idTokenInfo ? {
+              status: entry.idTokenInfo.status,
+              expiryDate: entry.idTokenInfo.cacheExpiryDateTime
+            } : void 0
+          })
+        )
+      }
+    })
+  }
+};
+
+// src/presets/reservation.ts
+var reservationPreset = {
+  downstream: {
+    "ocpp2.1:ReserveNow": (params) => ({
+      action: "ReserveNow",
+      payload: {
+        connectorId: params.evseId || 0,
+        expiryDate: params.expiryDateTime,
+        idTag: params.idToken?.idToken,
+        reservationId: params.id
+      }
+    }),
+    "ocpp2.1:CancelReservation": (params) => ({
+      action: "CancelReservation",
+      payload: {
+        reservationId: params.reservationId
+      }
+    })
+  }
+};
+
+// src/presets/smart-charging.ts
+var smartChargingPreset = {
+  downstream: {
+    "ocpp2.1:SetChargingProfile": (params) => ({
+      action: "SetChargingProfile",
+      payload: {
+        connectorId: params.evseId,
+        csChargingProfiles: params.chargingProfile
+      }
+    }),
+    "ocpp2.1:ClearChargingProfile": (params) => ({
+      action: "ClearChargingProfile",
+      payload: {
+        id: params.chargingProfileId,
+        connectorId: params.chargingProfileCriteria?.evseId,
+        chargingProfilePurpose: params.chargingProfileCriteria?.chargingProfilePurpose,
+        stackLevel: params.chargingProfileCriteria?.stackLevel
+      }
+    }),
+    "ocpp2.1:GetCompositeSchedule": (params) => ({
+      action: "GetCompositeSchedule",
+      payload: {
+        connectorId: params.evseId,
+        duration: params.duration,
+        chargingRateUnit: params.chargingRateUnit
+      }
+    })
+  }
+};
+
+// src/presets/index.ts
+function mergePresets(...maps) {
+  const merged = {
+    upstream: {},
+    downstream: {},
+    responses: {},
+    errors: {}
+  };
+  for (const map of maps) {
+    if (map.upstream) Object.assign(merged.upstream, map.upstream);
+    if (map.downstream) Object.assign(merged.downstream, map.downstream);
+    if (map.responses) Object.assign(merged.responses, map.responses);
+    if (map.errors) Object.assign(merged.errors, map.errors);
+  }
+  return merged;
+}
+var presets = {
+  ocpp16_to_ocpp21: mergePresets(
+    corePreset,
+    smartChargingPreset,
+    firmwarePreset,
+    reservationPreset,
+    localAuthPreset
+  )
+};
+
+// src/proxy.ts
+import { EventEmitter } from "events";
+var OCPPProtocolProxy = class extends EventEmitter {
+  constructor(options) {
+    super();
+    this.options = options;
+    this.translator = new OCPPTranslator({ upstream: {}, downstream: {} });
+    this.sessionStore = options.sessionStore || new InMemorySessionStore();
+  }
+  translator;
+  clients = /* @__PURE__ */ new Map();
+  sessionStore;
+  adapters = [];
+  /** Register translation maps (can be called multiple times to layer presets). */
+  translate(map) {
+    this.translator.updateMap(map);
+  }
+  /** Start listening on a transport adapter (WS, HTTP, etc.). */
+  async listenOnAdapter(adapter) {
+    this.adapters.push(adapter);
+    await adapter.listen((connection) => this.handleNewConnection(connection));
+  }
+  /**
+   * Execute all registered middlewares sequentially.
+   * If a middleware returns a message, it replaces the current message.
+   */
+  async executeMiddlewares(message, context, direction, phase) {
+    let currentMsg = message;
+    for (const mw of this.options.middlewares || []) {
+      try {
+        const result = await mw(currentMsg, context, direction, phase);
+        if (result) {
+          currentMsg = result;
+        }
+      } catch (err) {
+        this.emit("middlewareError", err, currentMsg, context);
+      }
+    }
+    return currentMsg;
+  }
+  handleNewConnection(evseConnection) {
+    const identity = evseConnection.identity;
+    const sourceProtocol = evseConnection.protocol;
+    const targetProtocol = this.options.upstreamProtocol;
+    const context = {
+      identity,
+      sourceProtocol,
+      targetProtocol,
+      session: this.sessionStore
+    };
+    this.emit("connection", identity, sourceProtocol);
+    import("ocpp-ws-io").then(({ OCPPClient }) => {
+      const upstreamClient = new OCPPClient({
+        endpoint: this.options.upstreamEndpoint,
+        protocols: [targetProtocol],
+        identity,
+        strictMode: false
+      });
+      this.clients.set(identity, upstreamClient);
+      const connectionPromise = upstreamClient.connect();
+      evseConnection.onMessage(async (msg) => {
+        await connectionPromise;
+        if (msg.type === 2 /* CALL */) {
+          try {
+            const preMsg = await this.executeMiddlewares(
+              msg,
+              context,
+              "upstream",
+              "pre"
+            );
+            const translatedCall = await this.translator.translateUpstreamCall(
+              preMsg,
+              context
+            );
+            const postMsg = await this.executeMiddlewares(
+              translatedCall,
+              context,
+              "upstream",
+              "post"
+            );
+            const rawResponse = await upstreamClient.call(
+              postMsg.action,
+              postMsg.payload
+            );
+            const responseMsg = {
+              type: 3 /* CALLRESULT */,
+              messageId: msg.messageId,
+              payload: rawResponse
+            };
+            const preResMsg = await this.executeMiddlewares(
+              responseMsg,
+              context,
+              "response",
+              "pre"
+            );
+            const translatedResponse = await this.translator.translateCallResult(
+              preResMsg,
+              translatedCall.action,
+              context
+            );
+            return await this.executeMiddlewares(
+              translatedResponse,
+              context,
+              "response",
+              "post"
+            );
+          } catch (err) {
+            const errMessage = {
+              type: 4 /* CALLERROR */,
+              messageId: msg.messageId,
+              errorCode: err.code || "InternalError",
+              errorDescription: err.message,
+              errorDetails: {}
+            };
+            this.emit("translationError", err, msg, context);
+            return await this.executeMiddlewares(
+              errMessage,
+              context,
+              "error",
+              "post"
+            );
+          }
+        }
+        return void 0;
+      });
+      upstreamClient.handle(async (action, ctx) => {
+        const downstreamCall = {
+          type: 2 /* CALL */,
+          messageId: ctx.messageId || `csms-${Date.now()}`,
+          action,
+          payload: ctx.params
+        };
+        try {
+          const preMsg = await this.executeMiddlewares(
+            downstreamCall,
+            context,
+            "downstream",
+            "pre"
+          );
+          const translated = await this.translator.translateDownstreamCall(
+            preMsg,
+            context
+          );
+          const postMsg = await this.executeMiddlewares(
+            translated,
+            context,
+            "downstream",
+            "post"
+          );
+          const evseResponse = await evseConnection.send(postMsg);
+          if (evseResponse && evseResponse.type === 3 /* CALLRESULT */) {
+            const preResMsg = await this.executeMiddlewares(
+              evseResponse,
+              context,
+              "response",
+              "pre"
+            );
+            const mappedResponse = await this.translator.translateCallResult(
+              preResMsg,
+              downstreamCall.action,
+              context
+            );
+            const postResMsg = await this.executeMiddlewares(
+              mappedResponse,
+              context,
+              "response",
+              "post"
+            );
+            return postResMsg.payload;
+          }
+        } catch (err) {
+          this.emit("translationError", err, downstreamCall, context);
+          throw err;
+        }
+      });
+      evseConnection.onClose(() => {
+        upstreamClient.close();
+        this.sessionStore.clear(identity);
+        this.clients.delete(identity);
+        this.emit("disconnect", identity);
+      });
+    });
+  }
+  /** Gracefully close all upstream connections and adapters. */
+  async close() {
+    for (const client of this.clients.values()) {
+      try {
+        await client.close();
+      } catch {
+      }
+    }
+    this.clients.clear();
+    for (const adapter of this.adapters) {
+      await adapter.close();
+    }
+    this.adapters = [];
+  }
+};
+export {
+  InMemorySessionStore,
+  MessageType,
+  OCPPProtocolProxy,
+  OCPPTranslator,
+  OcppWsIoAdapter,
+  OcppWsIoConnection,
+  TelemetryMiddleware,
+  availabilityMap16to21,
+  availabilityMap21to16,
+  corePreset,
+  firmwarePreset,
+  localAuthPreset,
+  presets,
+  reservationPreset,
+  smartChargingPreset,
+  statusMap16to21,
+  statusMap21to16
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "ocpp-protocol-proxy",
+  "version": "0.1.1",
+  "description": "Transport-agnostic OCPP version translation proxy — translate any OCPP version to any other with pluggable middleware, stateful sessions, and spec-compliant presets.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./presets": {
+      "types": "./dist/presets/index.d.ts",
+      "import": "./dist/presets/index.mjs",
+      "require": "./dist/presets/index.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/ocpp-ws-io.adapter.d.ts",
+      "import": "./dist/adapters/ocpp-ws-io.adapter.mjs",
+      "require": "./dist/adapters/ocpp-ws-io.adapter.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ocpp",
+    "ocpp1.6",
+    "ocpp2.0.1",
+    "ocpp2.1",
+    "protocol-proxy",
+    "protocol-translation",
+    "ev-charging",
+    "csms",
+    "evse",
+    "charge-point",
+    "middleware",
+    "version-translation",
+    "electric-vehicle",
+    "e-mobility",
+    "typescript"
+  ],
+  "author": "Rohit Tiwari <rohit@rohittiwari.me>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rohittiwari-dev/ocpp-ws-io",
+    "directory": "packages/ocpp-protocol-proxy"
+  },
+  "bugs": {
+    "url": "https://github.com/rohittiwari-dev/ocpp-ws-io/issues"
+  },
+  "homepage": "https://ocpp-ws-io.rohittiwari.me/docs/protocol-proxy",
+  "dependencies": {
+    "ocpp-ws-io": "*"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.19.35",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}