@ocpp-debugkit/core 0.1.0

package/dist/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/normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../src/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"}

package/dist/normalizer.js

@@ -0,0 +1,289 @@
+/**
+ * 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)
+ */
+// ---------------------------------------------------------------------------
+// Direction inference (ADR-0004)
+// ---------------------------------------------------------------------------
+/**
+ * Actions initiated by the Charge Point (CS → CSMS).
+ * These are OCPP 1.6 actions sent FROM the station TO the CSMS.
+ */
+const CS_TO_CSMS_ACTIONS = new Set([
+    'BootNotification',
+    'Heartbeat',
+    'Authorize',
+    'StartTransaction',
+    'StopTransaction',
+    'StatusNotification',
+    'MeterValues',
+    'DataTransfer',
+    'DiagnosticsStatusNotification',
+    'FirmwareStatusNotification',
+    'SecurityEventNotification',
+    'SignCertificate',
+    'SignedFirmwareStatusNotification',
+    'LogStatusNotification',
+]);
+/**
+ * Actions initiated by the CSMS (CSMS → CS).
+ * These are OCPP 1.6 actions sent FROM the CSMS TO the station.
+ */
+const CSMS_TO_CS_ACTIONS = new Set([
+    'Reset',
+    'RemoteStartTransaction',
+    'RemoteStopTransaction',
+    'GetConfiguration',
+    'ChangeConfiguration',
+    'SetChargingProfile',
+    'ClearChargingProfile',
+    'ChangeAvailability',
+    'ReserveNow',
+    'CancelReservation',
+    'DataTransfer',
+    'GetLocalListVersion',
+    'SendLocalList',
+    'TriggerMessage',
+    'UnlockConnector',
+    'GetDiagnostics',
+    'UpdateFirmware',
+    'ExtendedTriggerMessage',
+    'GetLog',
+    'SignedUpdateFirmware',
+    'CertificateSigned',
+    'DeleteCertificate',
+    'GetInstalledCertificateIds',
+    'InstallCertificate',
+]);
+/**
+ * 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 function inferDirection(messageType, action) {
+    if (messageType === 'Call' && action !== null) {
+        if (CS_TO_CSMS_ACTIONS.has(action))
+            return 'CS_TO_CSMS';
+        if (CSMS_TO_CS_ACTIONS.has(action))
+            return 'CSMS_TO_CS';
+        return 'UNKNOWN';
+    }
+    // For CallResult/CallError, direction should be the reverse of the Call.
+    // We can't know for certain without matching — return UNKNOWN.
+    // The parser will resolve this after matching Calls to responses.
+    return 'UNKNOWN';
+}
+/**
+ * Determine the reverse direction for a response.
+ * Call CS→CSMS → Response CSMS→CS, and vice versa.
+ */
+export function reverseDirection(dir) {
+    switch (dir) {
+        case 'CS_TO_CSMS':
+            return 'CSMS_TO_CS';
+        case 'CSMS_TO_CS':
+            return 'CS_TO_CSMS';
+        case 'UNKNOWN':
+            return 'UNKNOWN';
+    }
+}
+// ---------------------------------------------------------------------------
+// Timestamp normalization (ADR-0005)
+// ---------------------------------------------------------------------------
+/**
+ * Threshold for distinguishing Unix epoch seconds from milliseconds.
+ * Values below 10^12 are treated as seconds; above as milliseconds.
+ * (10^12 = year ~33658 in ms, year ~2001 in s)
+ */
+const EPOCH_MS_THRESHOLD = 1e12;
+/**
+ * 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 function normalizeTimestamp(timestamp) {
+    if (timestamp === null || timestamp === undefined) {
+        return null;
+    }
+    if (typeof timestamp === 'number') {
+        if (!Number.isFinite(timestamp)) {
+            return null;
+        }
+        // Detect seconds vs milliseconds
+        return timestamp < EPOCH_MS_THRESHOLD ? Math.round(timestamp * 1000) : Math.round(timestamp);
+    }
+    if (typeof timestamp === 'string') {
+        const trimmed = timestamp.trim();
+        if (trimmed === '') {
+            return null;
+        }
+        // Try parsing as a number first (stringified epoch)
+        const asNum = Number(trimmed);
+        if (Number.isFinite(asNum)) {
+            return asNum < EPOCH_MS_THRESHOLD ? Math.round(asNum * 1000) : Math.round(asNum);
+        }
+        // Parse as ISO 8601
+        const parsed = Date.parse(trimmed);
+        if (Number.isNaN(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Message type classification
+// ---------------------------------------------------------------------------
+/**
+ * Classify the OCPP message type from the raw message array.
+ * - [2, ...] → 'Call'
+ * - [3, ...] → 'CallResult'
+ * - [4, ...] → 'CallError'
+ */
+export function classifyMessageType(message) {
+    const typeId = message[0];
+    switch (typeId) {
+        case 2:
+            return 'Call';
+        case 3:
+            return 'CallResult';
+        case 4:
+            return 'CallError';
+        default:
+            // Should not happen — schema validation prevents this
+            return 'Call';
+    }
+}
+/**
+ * Extract the action name from a Call message.
+ * Only Call messages have an action (at index 2).
+ */
+export function extractAction(message) {
+    if (message[0] === 2 && message.length >= 3) {
+        const action = message[2];
+        return typeof action === 'string' ? action : null;
+    }
+    return null;
+}
+/**
+ * Extract the payload from any message type.
+ * - Call: index 3
+ * - CallResult: index 2
+ * - CallError: index 4 (ErrorDetails)
+ */
+export function extractPayload(message) {
+    switch (message[0]) {
+        case 2:
+            return message[3] ?? null;
+        case 3:
+            return message[2] ?? null;
+        case 4:
+            return message[4] ?? null;
+        default:
+            return null;
+    }
+}
+/**
+ * Extract error code from a CallError message (index 2).
+ */
+export function extractErrorCode(message) {
+    if (message[0] === 4 && message.length >= 3) {
+        const code = message[2];
+        return typeof code === 'string' ? code : null;
+    }
+    return null;
+}
+/**
+ * Extract error description from a CallError message (index 3).
+ */
+export function extractErrorDescription(message) {
+    if (message[0] === 4 && message.length >= 4) {
+        const desc = message[3];
+        return typeof desc === 'string' ? desc : null;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// normalizeEvents()
+// ---------------------------------------------------------------------------
+/**
+ * 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 function normalizeEvents(inputs) {
+    // First pass: create events with best-effort direction
+    const events = inputs.map((input, index) => {
+        const message = input.message;
+        const messageType = classifyMessageType(message);
+        const action = extractAction(message);
+        // Use explicit direction, or infer from action for Call messages.
+        // An explicit direction (including 'UNKNOWN') is respected as-is.
+        // Only infer when direction is not provided at all (undefined).
+        let direction = input.direction;
+        if (direction === undefined && messageType === 'Call' && action !== null) {
+            direction = inferDirection(messageType, action);
+        }
+        if (direction === undefined) {
+            direction = 'UNKNOWN';
+        }
+        return {
+            id: `evt-${String(index + 1).padStart(4, '0')}`,
+            messageId: message[1],
+            timestamp: normalizeTimestamp(input.timestamp),
+            direction,
+            messageType,
+            action,
+            payload: extractPayload(message),
+            errorCode: extractErrorCode(message),
+            errorDescription: extractErrorDescription(message),
+            rawMessage: message,
+        };
+    });
+    // Second pass: resolve response directions by matching to their original Calls.
+    // Build a map of messageId → Call direction.
+    const callDirections = new Map();
+    for (const event of events) {
+        if (event.messageType === 'Call' && event.direction !== 'UNKNOWN') {
+            callDirections.set(event.messageId, event.direction);
+        }
+    }
+    // For CallResult/CallError with UNKNOWN direction, infer from the matched Call
+    for (const event of events) {
+        if (event.direction === 'UNKNOWN' && event.messageType !== 'Call') {
+            const callDir = callDirections.get(event.messageId);
+            if (callDir) {
+                event.direction = reverseDirection(callDir);
+            }
+        }
+    }
+    return events;
+}
+//# sourceMappingURL=normalizer.js.map

package/dist/normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.js","sourceRoot":"","sources":["../src/normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,8EAA8E;AAC9E,iCAAiC;AACjC,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,kBAAkB;IAClB,WAAW;IACX,WAAW;IACX,kBAAkB;IAClB,iBAAiB;IACjB,oBAAoB;IACpB,aAAa;IACb,cAAc;IACd,+BAA+B;IAC/B,4BAA4B;IAC5B,2BAA2B;IAC3B,iBAAiB;IACjB,kCAAkC;IAClC,uBAAuB;CACxB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,OAAO;IACP,wBAAwB;IACxB,uBAAuB;IACvB,kBAAkB;IAClB,qBAAqB;IACrB,oBAAoB;IACpB,sBAAsB;IACtB,oBAAoB;IACpB,YAAY;IACZ,mBAAmB;IACnB,cAAc;IACd,qBAAqB;IACrB,eAAe;IACf,gBAAgB;IAChB,iBAAiB;IACjB,gBAAgB;IAChB,gBAAgB;IAChB,wBAAwB;IACxB,QAAQ;IACR,sBAAsB;IACtB,mBAAmB;IACnB,mBAAmB;IACnB,4BAA4B;IAC5B,oBAAoB;CACrB,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,WAAwB,EAAE,MAAqB;IAC5E,IAAI,WAAW,KAAK,MAAM,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAC9C,IAAI,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO,YAAY,CAAC;QACxD,IAAI,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO,YAAY,CAAC;QACxD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,yEAAyE;IACzE,+DAA+D;IAC/D,kEAAkE;IAClE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAc;IAC7C,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,qCAAqC;AACrC,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAA6C;IAC9E,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,iCAAiC;QACjC,OAAO,SAAS,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/F,CAAC;IAED,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,oDAAoD;QACpD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9B,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACnF,CAAC;QACD,oBAAoB;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,8BAA8B;AAC9B,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAuB;IACzD,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1B,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,CAAC;YACJ,OAAO,MAAM,CAAC;QAChB,KAAK,CAAC;YACJ,OAAO,YAAY,CAAC;QACtB,KAAK,CAAC;YACJ,OAAO,WAAW,CAAC;QACrB;YACE,sDAAsD;YACtD,OAAO,MAAM,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAuB;IACnD,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAC1B,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAuB;IACpD,QAAQ,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACnB,KAAK,CAAC;YACJ,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QAC5B,KAAK,CAAC;YACJ,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QAC5B,KAAK,CAAC;YACJ,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QAC5B;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAuB;IACtD,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAuB;IAC7D,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACxB,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyB;IACvD,uDAAuD;IACvD,MAAM,MAAM,GAAY,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QAClD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,MAAM,WAAW,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QAEtC,kEAAkE;QAClE,kEAAkE;QAClE,gEAAgE;QAChE,IAAI,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QAChC,IAAI,SAAS,KAAK,SAAS,IAAI,WAAW,KAAK,MAAM,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACzE,SAAS,GAAG,cAAc,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,SAAS,GAAG,SAAS,CAAC;QACxB,CAAC;QAED,OAAO;YACL,EAAE,EAAE,OAAO,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;YAC/C,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;YACrB,SAAS,EAAE,kBAAkB,CAAC,KAAK,CAAC,SAAS,CAAC;YAC9C,SAAS;YACT,WAAW;YACX,MAAM;YACN,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC;YAChC,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC;YACpC,gBAAgB,EAAE,uBAAuB,CAAC,OAAO,CAAC;YAClD,UAAU,EAAE,OAAO;SACpB,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,gFAAgF;IAChF,6CAA6C;IAC7C,MAAM,cAAc,GAAG,IAAI,GAAG,EAAqB,CAAC;IACpD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,WAAW,KAAK,MAAM,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAClE,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,WAAW,KAAK,MAAM,EAAE,CAAC;YAClE,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YACpD,IAAI,OAAO,EAAE,CAAC;gBACZ,KAAK,CAAC,SAAS,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/parser.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Trace parser — accepts untrusted input in JSON Object, JSONL, or bare array
+ * format and produces normalized `Event` objects with warnings for malformed
+ * entries.
+ *
+ * Security:
+ * - Safe JSON parsing with try/catch
+ * - Input size limit (10 MB)
+ * - Event count limit (10,000)
+ * - Zod schema validation prevents prototype pollution
+ * - Malformed individual events are skipped with a `ParseWarning`
+ * - Structural errors (invalid JSON, missing events array) fail fast
+ *
+ * @see ADR-0002 (input trace formats)
+ * @see ADR-0007 (malformed trace handling)
+ * @see docs/trace-format-spec.md
+ */
+import type { ParseResult } from './types.js';
+/** Maximum input size in bytes (10 MB). */
+export declare const MAX_INPUT_SIZE_BYTES: number;
+/** Maximum number of events after parsing. */
+export declare const MAX_EVENT_COUNT = 10000;
+/** Error thrown when input exceeds size limits or has structural problems. */
+export declare class ParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Detect the trace format by examining the input string.
+ *
+ * - JSONL: multiple lines, first non-empty line starts with `{` and parses as JSON
+ * - JSON Object: starts with `{`
+ * - Bare Array: starts with `[`
+ *
+ * This function does NOT validate the full content — it just determines
+ * which parsing strategy to use.
+ */
+export type TraceFormat = 'json-object' | 'jsonl' | 'bare-array';
+/**
+ * Parse a trace from a raw string input.
+ *
+ * Accepts:
+ * - JSON Object format (metadata + events array)
+ * - JSONL format (one event per line)
+ * - Bare array format (array of raw OCPP message arrays)
+ *
+ * @param input - Raw trace string (untrusted)
+ * @returns ParseResult with normalized events and warnings for malformed entries
+ * @throws {ParseError} for structural errors (invalid JSON, missing events, size/count limits exceeded)
+ *
+ * @see ADR-0002, ADR-0007
+ */
+export declare function parseTrace(input: string): ParseResult;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,OAAO,KAAK,EAAS,WAAW,EAAiC,MAAM,YAAY,CAAC;AAMpF,2CAA2C;AAC3C,eAAO,MAAM,oBAAoB,QAAmB,CAAC;AAErD,8CAA8C;AAC9C,eAAO,MAAM,eAAe,QAAS,CAAC;AAMtC,8EAA8E;AAC9E,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAoCD;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,OAAO,GAAG,YAAY,CAAC;AAiLjE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CA4DrD"}