@totemsdk/act-ocpp 0.0.0-stage → 0.1.1

package/dist/meter.js

@@ -0,0 +1,77 @@
+/**
+ * RFC-024 §5.7 — metering and settlement evidence.
+ *
+ * Meter values must come from the charger through the transport, never from the
+ * caller. The evidence digest is canonical so a settlement action can cite the
+ * charging operation id and prove which meter readings backed it.
+ */
+import { hashCanonical } from '@totemsdk/act-core';
+export function meterEvidenceDigest(evidence) {
+    return hashCanonical('TOTEM_ACT_OCPP_METER_EVIDENCE_V1', {
+        operationId: evidence.operationId,
+        connectorId: evidence.connectorId,
+        transactionId: evidence.transactionId,
+        energyWattHours: evidence.energyWattHours,
+        readings: evidence.readings
+            .map((reading) => ({
+            transactionId: reading.transactionId,
+            connectorId: reading.connectorId,
+            timestamp: reading.timestamp,
+            energyWattHours: reading.energyWattHours,
+            measurand: reading.measurand ?? null,
+        }))
+            .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp)),
+    });
+}
+function latestReading(readings) {
+    return readings
+        .slice()
+        .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp))
+        .at(-1);
+}
+/**
+ * Reconcile an accepted charging operation against the charger.
+ *
+ * - `confirmed` only when the charger reports the transaction ended (an energy
+ *   register alone is progress, not completion);
+ * - `running` while the transaction is active or meter values advance;
+ * - `unknown` when the charger cannot be read — the reservation must stay held.
+ */
+export async function reconcileChargingSession(transport, query) {
+    const readings = await transport.readMeterValues({
+        connectorId: query.connectorId,
+        transactionId: query.transactionId,
+    });
+    const scoped = readings.filter((reading) => reading.transactionId === query.transactionId);
+    const latest = latestReading(scoped);
+    let state = { status: 'unknown' };
+    if (transport.readTransactionState) {
+        state = await transport.readTransactionState({
+            connectorId: query.connectorId,
+            transactionId: query.transactionId,
+        });
+    }
+    const energyWattHours = state.energyWattHours ?? latest?.energyWattHours;
+    if (state.status === 'ended' && energyWattHours !== undefined) {
+        const base = {
+            operationId: query.operationId,
+            connectorId: query.connectorId,
+            transactionId: query.transactionId,
+            energyWattHours,
+            readings: scoped,
+        };
+        return {
+            status: 'confirmed',
+            energyWattHours,
+            evidence: { ...base, digest: meterEvidenceDigest(base) },
+        };
+    }
+    if (state.status === 'active' || scoped.length > 0) {
+        return {
+            status: 'running',
+            ...(energyWattHours !== undefined ? { energyWattHours } : {}),
+            detail: state.status === 'active' ? 'transaction active' : 'meter values observed',
+        };
+    }
+    return { status: 'unknown', detail: 'no transaction state or meter readback' };
+}

package/dist/profile.d.ts

@@ -0,0 +1,40 @@
+/**
+ * RFC-024 §5.4 / §5.9 — OCPP charging profile.
+ *
+ * Connectors are resources; the safe state is `stop session` (never leave an
+ * active transaction). Interlocks enforce the connector's declared physical
+ * ceiling before authorization, and the error taxonomy classifies OCPP status
+ * codes so a safety error is never retried.
+ */
+import { type DeviceErrorTaxonomy, type IndustrialProfile, type Interlock, type Resource, type ResourceId } from '@totemsdk/act-core';
+import type { OcppCapabilitySet } from './capabilities.js';
+import { OCPP_CORE_PROFILES } from './capabilities.js';
+export declare const OCPP_PROTOCOL = "ocpp";
+export interface ChargingConnector {
+    connectorId: number;
+    /** Physical ceiling at this connector, in W (decimal string). */
+    maxPowerWatts: string;
+    /** Contract/session energy ceiling, in Wh. */
+    maxEnergyWattHours?: string;
+    /** Maximum session duration, in seconds. */
+    maxSessionSeconds?: string;
+    phases?: 1 | 3;
+    connectorType?: string;
+}
+export declare function chargingResourceId(site: string, connectorId: number, asset?: string): ResourceId;
+export declare function chargingResource(site: string, connector: ChargingConnector): Resource;
+/** Interlocks that enforce a connector's declared ceiling before authorization. */
+export declare function chargingInterlocks(site: string, connector: ChargingConnector): Interlock[];
+/**
+ * OCPP status → device error classification (RFC-011 §4.7).
+ * Safety codes require a safe state and are never retried.
+ */
+export declare function ocppErrorTaxonomy(): DeviceErrorTaxonomy;
+export interface OcppProfileOptions {
+    site: string;
+    connectors: readonly ChargingConnector[];
+    capabilities?: OcppCapabilitySet;
+}
+/** Data-only charger profile (definitions are supplied by the adapter). */
+export declare function createOcppProfile(options: OcppProfileOptions): IndustrialProfile;
+export { OCPP_CORE_PROFILES };

package/dist/profile.js

@@ -0,0 +1,167 @@
+/**
+ * RFC-024 §5.4 / §5.9 — OCPP charging profile.
+ *
+ * Connectors are resources; the safe state is `stop session` (never leave an
+ * active transaction). Interlocks enforce the connector's declared physical
+ * ceiling before authorization, and the error taxonomy classifies OCPP status
+ * codes so a safety error is never retried.
+ */
+import { createDeviceErrorTaxonomy, } from '@totemsdk/act-core';
+import { OCPP_CORE_PROFILES } from './capabilities.js';
+export const OCPP_PROTOCOL = 'ocpp';
+export function chargingResourceId(site, connectorId, asset = `EVSE-${connectorId}`) {
+    return { site, area: 'charging', asset, point: 'connector' };
+}
+export function chargingResource(site, connector) {
+    const id = chargingResourceId(site, connector.connectorId);
+    return {
+        id,
+        kind: 'actuator',
+        addresses: [{ protocol: OCPP_PROTOCOL, endpoint: `connector:${connector.connectorId}` }],
+        // Never leave an active transaction: the safe state stops the session.
+        safeState: {
+            resourceId: id,
+            command: { action: 'charging:stopSession', connectorId: connector.connectorId },
+        },
+        metadata: {
+            connectorId: connector.connectorId,
+            maxPowerWatts: connector.maxPowerWatts,
+            ...(connector.maxEnergyWattHours !== undefined
+                ? { maxEnergyWattHours: connector.maxEnergyWattHours }
+                : {}),
+            ...(connector.maxSessionSeconds !== undefined
+                ? { maxSessionSeconds: connector.maxSessionSeconds }
+                : {}),
+            ...(connector.phases !== undefined ? { phases: connector.phases } : {}),
+            ...(connector.connectorType !== undefined ? { connectorType: connector.connectorType } : {}),
+        },
+    };
+}
+function numeric(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value))) {
+        return Number(value);
+    }
+    if (value && typeof value === 'object' && 'value' in value) {
+        return numeric(value.value);
+    }
+    return undefined;
+}
+/** Interlocks that enforce a connector's declared ceiling before authorization. */
+export function chargingInterlocks(site, connector) {
+    const id = chargingResourceId(site, connector.connectorId);
+    const safeState = {
+        resourceId: id,
+        command: { action: 'charging:stopSession', connectorId: connector.connectorId },
+    };
+    const interlocks = [
+        {
+            id: `ocpp:power-ceiling:${connector.connectorId}`,
+            kind: 'precondition',
+            resources: [id],
+            safeState,
+            evaluate({ parameters }) {
+                const requested = numeric(parameters.maxPowerWatts);
+                if (requested === undefined)
+                    return { satisfied: true };
+                const ceiling = Number(connector.maxPowerWatts);
+                return requested <= ceiling
+                    ? { satisfied: true }
+                    : { satisfied: false, reason: `requested ${requested} W exceeds connector ceiling ${ceiling} W` };
+            },
+        },
+    ];
+    if (connector.maxEnergyWattHours !== undefined) {
+        interlocks.push({
+            id: `ocpp:energy-ceiling:${connector.connectorId}`,
+            kind: 'precondition',
+            resources: [id],
+            safeState,
+            evaluate({ parameters }) {
+                const requested = numeric(parameters.maxEnergyWattHours);
+                if (requested === undefined)
+                    return { satisfied: true };
+                const ceiling = Number(connector.maxEnergyWattHours);
+                return requested <= ceiling
+                    ? { satisfied: true }
+                    : { satisfied: false, reason: `requested ${requested} Wh exceeds connector ceiling ${ceiling} Wh` };
+            },
+        });
+    }
+    if (connector.maxSessionSeconds !== undefined) {
+        interlocks.push({
+            id: `ocpp:duration-ceiling:${connector.connectorId}`,
+            kind: 'precondition',
+            resources: [id],
+            safeState,
+            evaluate({ parameters }) {
+                const requested = numeric(parameters.maxSessionSeconds);
+                if (requested === undefined)
+                    return { satisfied: true };
+                const ceiling = Number(connector.maxSessionSeconds);
+                return requested <= ceiling
+                    ? { satisfied: true }
+                    : { satisfied: false, reason: `requested ${requested} s exceeds connector ceiling ${ceiling} s` };
+            },
+        });
+    }
+    return interlocks;
+}
+/**
+ * OCPP status → device error classification (RFC-011 §4.7).
+ * Safety codes require a safe state and are never retried.
+ */
+export function ocppErrorTaxonomy() {
+    const taxonomy = createDeviceErrorTaxonomy();
+    const classes = {
+        // Charger/connector protection — never retry.
+        ConnectorLockFailure: 'safety',
+        EVCommunicationError: 'safety',
+        GroundFailure: 'safety',
+        HighTemperature: 'safety',
+        InternalError: 'safety',
+        OverCurrentFailure: 'safety',
+        OverVoltage: 'safety',
+        PowerMeterFailure: 'safety',
+        PowerSwitchFailure: 'safety',
+        ResetFailure: 'safety',
+        UnderVoltage: 'safety',
+        Faulted: 'safety',
+        // Occupancy/state — retrying the same command cannot succeed.
+        Occupied: 'permanent',
+        Reserved: 'permanent',
+        Unavailable: 'permanent',
+        NotSupported: 'permanent',
+        Rejected: 'permanent',
+        Invalid: 'permanent',
+        // Link/availability — a retry with the same operation id is safe.
+        Offline: 'transient',
+        Timeout: 'transient',
+        WeakSignal: 'transient',
+        // Identity — never retry without a new authorization.
+        InvalidIdTag: 'auth',
+        UnknownIdTag: 'auth',
+        AuthorizationFailed: 'auth',
+    };
+    for (const [code, classification] of Object.entries(classes)) {
+        taxonomy.register(OCPP_PROTOCOL, code, classification);
+    }
+    return taxonomy;
+}
+/** Data-only charger profile (definitions are supplied by the adapter). */
+export function createOcppProfile(options) {
+    const resources = options.connectors.map((connector) => chargingResource(options.site, connector));
+    const interlocks = options.connectors.flatMap((connector) => chargingInterlocks(options.site, connector));
+    return {
+        id: 'ocpp',
+        version: 1,
+        resources,
+        interlocks,
+        errorTaxonomy: ocppErrorTaxonomy(),
+        capabilities: ['industrial:action', 'industrial:read', 'transport:ocpp'],
+        recipes: [],
+        definitions: [],
+    };
+}
+export { OCPP_CORE_PROFILES };

package/dist/transport.d.ts

@@ -0,0 +1,104 @@
+/**
+ * RFC-024 §5.2 — OCPP transport port.
+ *
+ * The caller injects a transport that talks to a CSMS or a local charger stack.
+ * This package owns the governed operation semantics only: it never opens a
+ * socket and never implements an OCPP stack. A deployment can back the port
+ * with a CSMS client, a charger stack, or a simulator.
+ *
+ * Every operation is idempotent at the port boundary: the prepared command and
+ * the operation id are stable across retries (RFC-022 §5.1), so a transport may
+ * safely deduplicate a replayed request.
+ */
+export interface OcppResponse {
+    /** OCPP status (`Accepted`, `Rejected`, `Occupied`, `Faulted`, …). */
+    status?: string;
+    payload?: Record<string, unknown>;
+    errorCode?: string;
+    errorDescription?: string;
+}
+export interface OcppStartRequest {
+    connectorId: number;
+    idTag: string;
+    maxPowerWatts?: string;
+    maxEnergyWattHours?: string;
+    maxSessionSeconds?: string;
+}
+export interface OcppStopRequest {
+    connectorId: number;
+    transactionId: number;
+}
+export interface OcppChargingProfileRequest {
+    connectorId: number;
+    profileId: number;
+    maxPowerWatts: string;
+    maxEnergyWattHours?: string;
+    maxSessionSeconds?: string;
+}
+export interface OcppClearProfileRequest {
+    connectorId: number;
+    profileId?: number;
+}
+export interface OcppReserveRequest {
+    connectorId: number;
+    idTag: string;
+    reservationId: number;
+    expiresInSeconds: number;
+}
+export interface OcppMeterValue {
+    transactionId: number;
+    connectorId: number;
+    /** ISO-8601 timestamp from the charger. */
+    timestamp: string;
+    /** Cumulative energy register for the transaction, in Wh (decimal string). */
+    energyWattHours: string;
+    measurand?: string;
+}
+export type OcppTransactionEventType = 'Started' | 'Updated' | 'Ended';
+export interface OcppTransactionEvent {
+    transactionId: number;
+    connectorId: number;
+    eventType: OcppTransactionEventType;
+    timestamp: string;
+    energyWattHours?: string;
+}
+export interface OcppMeterQuery {
+    connectorId: number;
+    transactionId?: number;
+}
+export interface OcppTransactionState {
+    status: 'active' | 'ended' | 'unknown';
+    /** Final cumulative energy register, in Wh. */
+    energyWattHours?: string;
+    endedAt?: string;
+}
+/**
+ * Injected OCPP port. Implementations map these calls onto their CSMS/charger
+ * stack (RemoteStartTransaction, SetChargingProfile, ReserveNow, …).
+ */
+export interface OcppTransportPort {
+    remoteStartTransaction(request: OcppStartRequest): Promise<OcppResponse>;
+    remoteStopTransaction(request: OcppStopRequest): Promise<OcppResponse>;
+    /**
+     * Stop whatever session is active on a connector. Used as the connector's
+     * safe state, where the transaction id may not be known.
+     */
+    stopConnector?(connectorId: number): Promise<OcppResponse>;
+    setChargingProfile(request: OcppChargingProfileRequest): Promise<OcppResponse>;
+    clearChargingProfile(request: OcppClearProfileRequest): Promise<OcppResponse>;
+    reserveNow(request: OcppReserveRequest): Promise<OcppResponse>;
+    /** Readback path used for reconciliation; must originate from the charger. */
+    readMeterValues(query: OcppMeterQuery): Promise<OcppMeterValue[]>;
+    /** Charger/CSMS view of the transaction; required for definitive completion. */
+    readTransactionState?(query: OcppMeterQuery): Promise<OcppTransactionState>;
+    /** Optional push path for transaction events (Started/Updated/Ended). */
+    onTransactionEvent?(handler: (event: OcppTransactionEvent) => void): () => void;
+}
+/** Transport/OCPP rejection carrying the protocol code. */
+export declare class OcppTransportError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare const OCPP_ACCEPTED = "Accepted";
+/** Throw unless the response status is `Accepted`. */
+export declare function assertAccepted(response: OcppResponse, action: string): void;

package/dist/transport.js

@@ -0,0 +1,28 @@
+/**
+ * RFC-024 §5.2 — OCPP transport port.
+ *
+ * The caller injects a transport that talks to a CSMS or a local charger stack.
+ * This package owns the governed operation semantics only: it never opens a
+ * socket and never implements an OCPP stack. A deployment can back the port
+ * with a CSMS client, a charger stack, or a simulator.
+ *
+ * Every operation is idempotent at the port boundary: the prepared command and
+ * the operation id are stable across retries (RFC-022 §5.1), so a transport may
+ * safely deduplicate a replayed request.
+ */
+/** Transport/OCPP rejection carrying the protocol code. */
+export class OcppTransportError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'OcppTransportError';
+        this.code = code;
+    }
+}
+export const OCPP_ACCEPTED = 'Accepted';
+/** Throw unless the response status is `Accepted`. */
+export function assertAccepted(response, action) {
+    const status = response.status ?? OCPP_ACCEPTED;
+    if (status !== OCPP_ACCEPTED) {
+        throw new OcppTransportError(status, `${action} rejected with status '${status}'`);
+    }
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@totemsdk/act-ocpp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Governed OCPP EV-charging profile for Totem — bounded sessions, charging limits, reservations and meter evidence on the act-core runtime",
+  "main": "dist/cjs/index.js",
+  "types": "dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@totemsdk/act-core": "^0.6.0",
+    "@totemsdk/edge": "^1.6.0",
+    "@totemsdk/agent-policy": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^30.4.2",
+    "jest-environment-node": "^30.0.0",
+    "jest-runtime": "^30.5.2",
+    "ts-jest": "^29.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "author": "Totem SDK",
+  "homepage": "https://docs.totem.ing",
+  "bugs": {
+    "url": "https://github.com/Totem-Edge/totem-sdk/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Totem-Edge/totem-sdk.git",
+    "directory": "packages/act-ocpp"
+  },
+  "keywords": [
+    "totem",
+    "totemsdk",
+    "ocpp",
+    "ev",
+    "charging",
+    "industrial",
+    "governed-action",
+    "act-core"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'})+'\\n')\"",
+    "clean": "rm -rf dist",
+    "test": "jest --config ../../tests/jest/act-ocpp.cjs",
+    "test:integration": "node --test ../../tests/qualification/act-ocpp/integration.test.mjs",
+    "lint": "eslint src --max-warnings 0"
+  }
 }