@ocpp-debugkit/toolkit 0.2.0

package/dist/core/fixtures/index.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Synthetic trace fixtures for testing and development.
+ *
+ * All fixtures are fully synthetic — no real station identifiers, transaction
+ * IDs, idTag values, or personal data.
+ *
+ * @see docs/trace-format-spec.md
+ */
+import normalSession from '../__fixtures__/normal-session.js';
+import failedAuth from '../__fixtures__/failed-auth.js';
+import connectorFault from '../__fixtures__/connector-fault.js';
+export { normalSession, failedAuth, connectorFault };
+export declare const fixtures: {
+    readonly normalSession: {
+        traceId: string;
+        metadata: {
+            stationId: string;
+            ocppVersion: string;
+            source: string;
+            description: string;
+        };
+        events: ({
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                chargePointVendor: string;
+                chargePointModel: string;
+                chargePointSerialNumber: string;
+                firmwareVersion: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                currentTime: string;
+                interval: number;
+                status: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                connectorId: number;
+                status: string;
+                errorCode: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: {}[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                idTag: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                idTagInfo: {
+                    status: string;
+                    expiryDate: string;
+                    parentIdTag: string;
+                };
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                connectorId: number;
+                idTag: string;
+                meterStart: number;
+                timestamp: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                transactionId: number;
+                idTagInfo: {
+                    status: string;
+                };
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                connectorId: number;
+                transactionId: number;
+                meterValue: {
+                    timestamp: string;
+                    sampledValue: {
+                        value: string;
+                        measurand: string;
+                        unit: string;
+                    }[];
+                }[];
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                transactionId: number;
+                idTag: string;
+                meterStop: number;
+                timestamp: string;
+                reason: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                idTagInfo: {
+                    status: string;
+                };
+            })[];
+        })[];
+    };
+    readonly failedAuth: {
+        traceId: string;
+        metadata: {
+            stationId: string;
+            ocppVersion: string;
+            source: string;
+            description: string;
+        };
+        events: ({
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                chargePointVendor: string;
+                chargePointModel: string;
+                chargePointSerialNumber: string;
+                firmwareVersion: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                currentTime: string;
+                interval: number;
+                status: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                connectorId: number;
+                status: string;
+                errorCode: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: {}[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                idTag: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                idTagInfo: {
+                    status: string;
+                };
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                connectorId: number;
+                status: string;
+                errorCode: string;
+                info: string;
+            })[];
+        })[];
+    };
+    readonly connectorFault: {
+        traceId: string;
+        metadata: {
+            stationId: string;
+            ocppVersion: string;
+            source: string;
+            description: string;
+        };
+        events: ({
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                chargePointVendor: string;
+                chargePointModel: string;
+                chargePointSerialNumber: string;
+                firmwareVersion: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                currentTime: string;
+                interval: number;
+                status: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                connectorId: number;
+                status: string;
+                errorCode: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: {}[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                idTag: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                idTagInfo: {
+                    status: string;
+                    expiryDate: string;
+                };
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                connectorId: number;
+                idTag: string;
+                meterStart: number;
+                timestamp: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                transactionId: number;
+                idTagInfo: {
+                    status: string;
+                };
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                connectorId: number;
+                transactionId: number;
+                meterValue: {
+                    timestamp: string;
+                    sampledValue: {
+                        value: string;
+                        measurand: string;
+                        unit: string;
+                    }[];
+                }[];
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                connectorId: number;
+                status: string;
+                errorCode: string;
+                info: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                transactionId: number;
+                idTag: string;
+                meterStop: number;
+                timestamp: string;
+                reason: string;
+            })[];
+        } | {
+            timestamp: string;
+            direction: string;
+            message: (string | number | {
+                idTagInfo: {
+                    status: string;
+                };
+            })[];
+        })[];
+    };
+};
+export declare const fixtureNames: readonly ["normal-session", "failed-auth", "connector-fault"];
+//# sourceMappingURL=index.d.ts.map

package/dist/core/fixtures/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,aAAa,MAAM,mCAAmC,CAAC;AAC9D,OAAO,UAAU,MAAM,gCAAgC,CAAC;AACxD,OAAO,cAAc,MAAM,oCAAoC,CAAC;AAEhE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC;AAErD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAIX,CAAC;AAEX,eAAO,MAAM,YAAY,+DAAgE,CAAC"}

package/dist/core/fixtures/index.js

@@ -0,0 +1,19 @@
+/**
+ * Synthetic trace fixtures for testing and development.
+ *
+ * All fixtures are fully synthetic — no real station identifiers, transaction
+ * IDs, idTag values, or personal data.
+ *
+ * @see docs/trace-format-spec.md
+ */
+import normalSession from '../__fixtures__/normal-session.js';
+import failedAuth from '../__fixtures__/failed-auth.js';
+import connectorFault from '../__fixtures__/connector-fault.js';
+export { normalSession, failedAuth, connectorFault };
+export const fixtures = {
+    normalSession,
+    failedAuth,
+    connectorFault,
+};
+export const fixtureNames = ['normal-session', 'failed-auth', 'connector-fault'];
+//# sourceMappingURL=index.js.map

package/dist/core/fixtures/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,aAAa,MAAM,mCAAmC,CAAC;AAC9D,OAAO,UAAU,MAAM,gCAAgC,CAAC;AACxD,OAAO,cAAc,MAAM,oCAAoC,CAAC;AAEhE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC;AAErD,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,aAAa;IACb,UAAU;IACV,cAAc;CACN,CAAC;AAEX,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,gBAAgB,EAAE,aAAa,EAAE,iBAAiB,CAAU,CAAC"}

package/dist/core/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Barrel export for the @ocpp-debugkit/core package.
+ */
+export * from './types.js';
+export * from './schemas.js';
+export { parseTrace, ParseError, MAX_INPUT_SIZE_BYTES, MAX_EVENT_COUNT } from './parser.js';
+export type { TraceFormat } from './parser.js';
+export { normalizeEvents, normalizeTimestamp, inferDirection, reverseDirection, classifyMessageType, extractAction, extractPayload, extractErrorCode, extractErrorDescription, } from './normalizer.js';
+export { buildSessionTimeline } from './timeline.js';
+export { detectFailures } from './detection.js';
+export { summarizeSession, summarizeSessions } from './summarizer.js';
+export { validateMessage, validateMessages } from './validator.js';
+export * from './fixtures/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,cAAc,YAAY,CAAC;AAG3B,cAAc,cAAc,CAAC;AAG7B,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC5F,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG/C,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGtE,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAGnE,cAAc,qBAAqB,CAAC"}

package/dist/core/index.js

@@ -0,0 +1,22 @@
+/**
+ * Barrel export for the @ocpp-debugkit/core package.
+ */
+// Types
+export * from './types.js';
+// Schemas (Zod)
+export * from './schemas.js';
+// Parser
+export { parseTrace, ParseError, MAX_INPUT_SIZE_BYTES, MAX_EVENT_COUNT } from './parser.js';
+// Normalizer
+export { normalizeEvents, normalizeTimestamp, inferDirection, reverseDirection, classifyMessageType, extractAction, extractPayload, extractErrorCode, extractErrorDescription, } from './normalizer.js';
+// Timeline
+export { buildSessionTimeline } from './timeline.js';
+// Detection
+export { detectFailures } from './detection.js';
+// Summarizer
+export { summarizeSession, summarizeSessions } from './summarizer.js';
+// Validator
+export { validateMessage, validateMessages } from './validator.js';
+// Fixtures
+export * from './fixtures/index.js';
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,QAAQ;AACR,cAAc,YAAY,CAAC;AAE3B,gBAAgB;AAChB,cAAc,cAAc,CAAC;AAE7B,SAAS;AACT,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG5F,aAAa;AACb,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAEzB,WAAW;AACX,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD,YAAY;AACZ,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,aAAa;AACb,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtE,YAAY;AACZ,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEnE,WAAW;AACX,cAAc,qBAAqB,CAAC"}

package/dist/core/normalizer.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Event normalizer — transforms raw trace event inputs into canonical
+ * `Event` objects with classified message type, direction, and timestamps.
+ *
+ * @see ADR-0003 (canonical event model)
+ * @see ADR-0004 (message direction)
+ * @see ADR-0005 (timestamp normalization)
+ */
+import type { Direction, Event, MessageType, TraceEventInput, RawOcppMessage } from './types.js';
+/**
+ * Infer the direction of a Call message from its action name (ADR-0004).
+ * - If the action is known to be CS→CSMS, return 'CS_TO_CSMS'.
+ * - If the action is known to be CSMS→CS, return 'CSMS_TO_CS'.
+ * - If the action is not recognized, return 'UNKNOWN'.
+ *
+ * For CallResult/CallError, the direction is the reverse of the original Call.
+ * Since we don't have the original Call's direction here, we infer based on
+ * the matched Call's action. For responses without a matched Call, we use
+ * 'UNKNOWN'.
+ */
+export declare function inferDirection(messageType: MessageType, action: string | null): Direction;
+/**
+ * Determine the reverse direction for a response.
+ * Call CS→CSMS → Response CSMS→CS, and vice versa.
+ */
+export declare function reverseDirection(dir: Direction): Direction;
+/**
+ * Normalize a timestamp to epoch milliseconds.
+ *
+ * Accepts:
+ * - ISO 8601 strings (UTC or with offset)
+ * - Unix epoch in milliseconds (number >= 10^12)
+ * - Unix epoch in seconds (number < 10^12)
+ * - null/undefined → null
+ *
+ * @returns epoch milliseconds, or null if the timestamp is missing or invalid.
+ */
+export declare function normalizeTimestamp(timestamp: string | number | null | undefined): number | null;
+/**
+ * Classify the OCPP message type from the raw message array.
+ * - [2, ...] → 'Call'
+ * - [3, ...] → 'CallResult'
+ * - [4, ...] → 'CallError'
+ */
+export declare function classifyMessageType(message: RawOcppMessage): MessageType;
+/**
+ * Extract the action name from a Call message.
+ * Only Call messages have an action (at index 2).
+ */
+export declare function extractAction(message: RawOcppMessage): string | null;
+/**
+ * Extract the payload from any message type.
+ * - Call: index 3
+ * - CallResult: index 2
+ * - CallError: index 4 (ErrorDetails)
+ */
+export declare function extractPayload(message: RawOcppMessage): unknown;
+/**
+ * Extract error code from a CallError message (index 2).
+ */
+export declare function extractErrorCode(message: RawOcppMessage): string | null;
+/**
+ * Extract error description from a CallError message (index 3).
+ */
+export declare function extractErrorDescription(message: RawOcppMessage): string | null;
+/**
+ * Normalize an array of raw trace event inputs into canonical `Event` objects.
+ *
+ * This function:
+ * 1. Classifies the message type (Call/CallResult/CallError)
+ * 2. Extracts action, payload, error fields
+ * 3. Normalizes timestamps to epoch milliseconds
+ * 4. Resolves direction: uses explicit direction if provided, otherwise
+ *    infers from action name (for Calls) or from the matched Call (for responses)
+ * 5. Generates sequential event IDs
+ *
+ * Events are NOT reordered (ADR-0005). Out-of-order timestamps are preserved
+ * as-is; the caller can detect them after normalization.
+ *
+ * @see ADR-0003, ADR-0004, ADR-0005
+ */
+export declare function normalizeEvents(inputs: TraceEventInput[]): Event[];
+//# sourceMappingURL=normalizer.d.ts.map

package/dist/core/normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../src/core/normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA0DjG;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAUzF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,SAAS,CAS1D;AAaD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAgC/F;AAMD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,WAAW,CAaxE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAMpE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAW/D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAMvE;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAM9E;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,KAAK,EAAE,CAoDlE"}