API Reference

import { OCPPClient } from "ocpp-ws-io";

const client = new OCPPClient(options: ClientOptions);

await client.connect();

// With manual idempotency key to prevent double execution on reconnections
const result = await client.call("ocpp1.6", "BootNotification", { ... }, { idempotencyKey: "unique-boot-123" });

const result = await client.safeCall(
  "ocpp1.6",
  "ClearCache",
  {},
  { timeoutMs: 15000 },
);

if (result === undefined) {
  client.logger.warn("Station failed to clear cache", { error });
}

// Version specific
client.handle("ocpp1.6", "Reset", ({ params }) => { ... });

// Generic
client.handle("Reset", ({ params }) => { ... });

// Catch-all
client.handle((method, { params }) => { ... });

// Graceful close (waits for pending calls, sends 1000 code)
await client.close({ code: 1000, reason: "Normal Closure" });

// Forceful immediate drop (useful during DDoS or severe errors)
await client.close({ force: true });

// Graceful WS close, but skips waiting for pending asynchronous RPC calls
await client.close({ awaitPending: false });

client.logger.info("Initializing updates", { pendingFiles: 4 });

import { OCPPServer } from "ocpp-ws-io";

const server = new OCPPServer(options?: ServerOptions);

server.auth((ctx) => {
  // ctx.handshake has .identity, .pathname, .headers, etc.
  ctx.accept({ session: { ... } }); // Attach session data to client
});

server.cors({
  allowedOrigins: ["https://dashboard.example.com"],
  allowedIPs: ["192.168.1.0/24", "10.0.0.5"],
  allowedSchemes: ["wss"],
});

server.on("client", (client) => {
  // client is an OCPPServerClient (extends OCPPClient)
  console.log(client.session); // Access session data
});

server.updateTLS({
  cert: fs.readFileSync("./certs/server.crt"),
  key: fs.readFileSync("./certs/server.key"),
});

server.on("securityEvent", (event) => {
  // event.type: "AUTH_FAILED" | "CONNECTION_RATE_LIMIT" | "UPGRADE_ABORTED"
  siem.log(event);
});

const result = await server.sendToClient(
  "CP-001",
  "ocpp1.6",
  "Reset",
  {
    type: "Soft",
  },
  { timeoutMs: 10000 },
);

const result = await server.safeSendToClient(
  "CP-001",
  "ocpp1.6",
  "UpdateFirmware",
  { location: "..." },
  { timeoutMs: 30000 },
);

if (result !== undefined) {
  console.log("Firmware update accepted");
}

const targets = ["CP-001", "CP-002", "CP-003", ...thousands];

await server.broadcastBatch(targets, "Reset", { type: "Hard" });

const telemetry = server.stats();

console.log(`Active Managed Sessions: ${telemetry.activeSessions}`);
console.log(`Active Raw WebSockets: ${telemetry.webSockets?.total}`);
console.log(
  `Pending Network Flushes: ${telemetry.webSockets?.bufferedAmount} bytes`,
);
console.log(`Memory Used: ${telemetry.memoryUsage.heapUsed} bytes`);
console.log(`Uptime: ${telemetry.uptimeSeconds}s`);
console.log(`PID: ${telemetry.pid}`);

const metrics = await server.adapterMetrics();
console.log("Redis Backlog:", metrics?.redisConsumerLag?.pendingMessages);

server.logger.warn("Unrecognized protocol attempted", { requested: "ocpp1.5" });

import { NOREPLY } from "ocpp-ws-io";

client.handle("StatusNotification", ({ params }) => {
  // Process the notification but don't send a response immediately
  return NOREPLY;
});

import { BrowserOCPPClient } from "ocpp-ws-io/browser";

const client = new BrowserOCPPClient(options: BrowserClientOptions);

await client.connect();

// Version-aware typed call
const result = await client.call("ocpp1.6", "BootNotification", { ... });
const { success } = await client.safeCall("ocpp1.6", "Heartbeat", {});
const { success } = await client.safeCall("ocpp1.6", "Heartbeat", {});

// Register handlers (version-specific, generic, wildcard)
client.handle("ocpp1.6", "Reset", ({ params }) => { ... });
client.handle("Reset", ({ params }) => { ... });
client.handle((method, { params }) => { ... });

// Close
await client.close();
await client.close({ force: true });
await client.close({ awaitPending: true });

// Runtime reconfiguration
client.reconfigure({ callTimeoutMs: 10000 });

// Handler removal
client.removeHandler("Reset");
client.removeHandler("ocpp1.6", "Reset");
client.removeAllHandlers();

// Raw message
client.sendRaw(JSON.stringify([2, "uuid", "Heartbeat", {}]));

client.logger.info("Retrying connection...");

client.logger.info("Retrying connection...");

client.on("open", (event) => {
  /* connected */
});
client.on("close", ({ code, reason }) => {
  /* disconnected */
});
client.on("error", (error) => {
  /* error */
});
client.on("connecting", ({ url }) => {
  /* attempting */
});
client.on("reconnect", ({ attempt, delay }) => {
  /* reconnecting */
});
client.on("message", (message) => {
  /* OCPP message */
});
client.on("call", (call) => {
  /* incoming call */
});
client.on("callResult", (result) => {
  /* result received */
});
client.on("callError", (error) => {
  /* error received */
});
client.on("badMessage", ({ message, error }) => {
  /* malformed */
});

import {
  // Base errors
  TimeoutError, // Call timeout
  UnexpectedHttpResponse, // Non-101 upgrade response
  WebsocketUpgradeError, // WebSocket upgrade failure

  // RPC errors (OCPP-J spec Section 4.3)
  RPCGenericError,
  RPCNotImplementedError,
  RPCNotSupportedError,
  RPCInternalError,
  RPCProtocolError,
  RPCSecurityError,
  RPCFormationViolationError,
  RPCPropertyConstraintViolationError,
  RPCOccurrenceConstraintViolationError,
  RPCTypeConstraintViolationError,
  RPCGenericTransportError,
} from "ocpp-ws-io";