@ocpp-debugkit/core 0.1.0

package/dist/parser.js

@@ -0,0 +1,282 @@
+/**
+ * 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 { bareArraySchema, rawOcppMessageSchema, traceEventInputSchema, traceSchema, } from './schemas.js';
+import { normalizeEvents } from './normalizer.js';
+// ---------------------------------------------------------------------------
+// Limits (ADR-0007, docs/trace-format-spec.md)
+// ---------------------------------------------------------------------------
+/** Maximum input size in bytes (10 MB). */
+export const MAX_INPUT_SIZE_BYTES = 10 * 1024 * 1024;
+/** Maximum number of events after parsing. */
+export const MAX_EVENT_COUNT = 10_000;
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+/** Error thrown when input exceeds size limits or has structural problems. */
+export class ParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ParseError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Input size validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate the input size before any parsing.
+ * @throws {ParseError} if the input exceeds the maximum size.
+ */
+function validateInputSize(input) {
+    const byteLength = Buffer.byteLength(input, 'utf8');
+    if (byteLength > MAX_INPUT_SIZE_BYTES) {
+        throw new ParseError(`Input size (${byteLength} bytes) exceeds the maximum allowed size ` +
+            `(${MAX_INPUT_SIZE_BYTES} bytes).`);
+    }
+}
+/**
+ * Validate the event count after parsing.
+ * @throws {ParseError} if the event count exceeds the maximum.
+ */
+function validateEventCount(events) {
+    if (events.length > MAX_EVENT_COUNT) {
+        throw new ParseError(`Event count (${events.length}) exceeds the maximum allowed count ` + `(${MAX_EVENT_COUNT}).`);
+    }
+}
+function detectFormat(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith('{')) {
+        // Could be JSON Object format or JSONL starting with an event object.
+        // JSONL has multiple lines; a JSON Object is a single JSON value.
+        // We check if the trimmed input contains a newline followed by another `{`
+        // that is NOT inside a string (simplified check: if the last non-whitespace
+        // character is `}`, and there's content after the first `}`... but that's
+        // complex. Simpler: try parsing as a single JSON value first, and if that
+        // fails, try JSONL.
+        return 'json-object';
+    }
+    if (trimmed.startsWith('[')) {
+        return 'bare-array';
+    }
+    // Default to JSONL for other cases (each line is a JSON object)
+    return 'jsonl';
+}
+// ---------------------------------------------------------------------------
+// JSONL parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse JSONL input: one event per line.
+ * Blank lines are ignored. Malformed lines produce warnings.
+ *
+ * @returns array of valid TraceEventInput and warnings for malformed lines.
+ */
+function parseJsonl(input) {
+    const lines = input.split('\n');
+    const events = [];
+    const warnings = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const trimmed = line.trim();
+        if (trimmed === '') {
+            continue; // Skip blank lines
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            const result = traceEventInputSchema.safeParse(parsed);
+            if (result.success) {
+                events.push(result.data);
+            }
+            else {
+                warnings.push({
+                    index: i,
+                    message: `Line ${i + 1}: invalid event structure — ${result.error.issues[0]?.message ?? 'unknown error'}`,
+                    rawInput: trimmed.slice(0, 200),
+                });
+            }
+        }
+        catch (e) {
+            warnings.push({
+                index: i,
+                message: `Line ${i + 1}: invalid JSON — ${e instanceof Error ? e.message : 'unknown error'}`,
+                rawInput: trimmed.slice(0, 200),
+            });
+        }
+    }
+    return { events, warnings };
+}
+// ---------------------------------------------------------------------------
+// Bare array parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse bare array format: `[ [2, "id", "Action", {...}], [3, "id", {...}], ... ]`
+ *
+ * Each element is a raw OCPP message. Direction is inferred; timestamp is null.
+ */
+function parseBareArray(input) {
+    const warnings = [];
+    try {
+        const parsed = JSON.parse(input);
+        const result = bareArraySchema.safeParse(parsed);
+        if (!result.success) {
+            throw new ParseError(`Invalid bare array format — ${result.error.issues[0]?.message ?? 'unknown error'}`);
+        }
+        // Convert raw messages to TraceEventInput (with null timestamp, no direction)
+        const events = result.data.map((message) => ({
+            timestamp: null,
+            direction: undefined,
+            message,
+        }));
+        return { events, warnings };
+    }
+    catch (e) {
+        if (e instanceof ParseError)
+            throw e;
+        throw new ParseError(`Invalid JSON in bare array format — ${e instanceof Error ? e.message : 'unknown error'}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// JSON Object parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse JSON Object format: `{ "traceId": ..., "metadata": ..., "events": [...] }`
+ *
+ * Also handles the case where the JSON Object contains an array of raw messages
+ * in the `events` field (degenerate — treated as bare messages without timestamp/direction).
+ */
+function parseJsonObject(input) {
+    let parsed;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch (e) {
+        throw new ParseError(`Invalid JSON — ${e instanceof Error ? e.message : 'unknown error'}`);
+    }
+    // If the parsed value is an array, treat it as a bare array (degenerate JSON Object)
+    if (Array.isArray(parsed)) {
+        return parseBareArray(input);
+    }
+    const result = traceSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new ParseError(`Invalid trace structure — ${result.error.issues[0]?.message ?? 'unknown error'}`);
+    }
+    const trace = result.data;
+    const warnings = [];
+    const events = [];
+    // Validate each event individually — malformed events are skipped with warnings
+    for (let i = 0; i < trace.events.length; i++) {
+        const eventInput = trace.events[i];
+        if (eventInput === undefined)
+            continue;
+        // Re-validate the individual message (the schema already validated the
+        // overall structure, but we want to catch edge cases in the message array)
+        const msgResult = rawOcppMessageSchema.safeParse(eventInput.message);
+        if (!msgResult.success) {
+            warnings.push({
+                index: i,
+                message: `Event ${i + 1}: invalid OCPP message — ${msgResult.error.issues[0]?.message ?? 'unknown error'}`,
+            });
+            continue;
+        }
+        events.push({
+            timestamp: eventInput.timestamp ?? null,
+            direction: eventInput.direction,
+            message: msgResult.data,
+        });
+    }
+    if (events.length === 0) {
+        throw new ParseError('Trace contains no valid events after parsing.');
+    }
+    return { events, warnings };
+}
+// ---------------------------------------------------------------------------
+// parseTrace()
+// ---------------------------------------------------------------------------
+/**
+ * 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 function parseTrace(input) {
+    // Validate input size
+    validateInputSize(input);
+    const trimmed = input.trim();
+    if (trimmed === '') {
+        throw new ParseError('Input is empty.');
+    }
+    // Detect format and parse accordingly
+    const format = detectFormat(trimmed);
+    let events;
+    let warnings;
+    if (format === 'bare-array') {
+        const result = parseBareArray(trimmed);
+        events = result.events;
+        warnings = result.warnings;
+    }
+    else if (format === 'jsonl') {
+        const result = parseJsonl(trimmed);
+        events = result.events;
+        warnings = result.warnings;
+    }
+    else {
+        // json-object — but it might actually be JSONL if JSON.parse fails
+        try {
+            const result = parseJsonObject(trimmed);
+            events = result.events;
+            warnings = result.warnings;
+        }
+        catch (e) {
+            if (e instanceof ParseError) {
+                // If JSON Object parsing fails, try JSONL as a fallback
+                // (input starts with `{` but might be JSONL with event objects)
+                const jsonlResult = parseJsonl(trimmed);
+                if (jsonlResult.events.length > 0) {
+                    events = jsonlResult.events;
+                    warnings = jsonlResult.warnings;
+                }
+                else {
+                    throw e;
+                }
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+    // Validate event count
+    validateEventCount(events);
+    if (events.length === 0) {
+        throw new ParseError('Trace contains no valid events.');
+    }
+    // Normalize events into canonical Event objects
+    const normalizedEvents = normalizeEvents(events);
+    return {
+        events: normalizedEvents,
+        warnings,
+    };
+}
+//# sourceMappingURL=parser.js.map

package/dist/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"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"}

package/dist/schemas.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Zod schemas for OCPP DebugKit trace input validation.
+ *
+ * These schemas validate untrusted input at the boundary (ADR-0007).
+ * They prevent prototype pollution and ensure structural correctness
+ * before any processing occurs.
+ *
+ * @see docs/trace-format-spec.md
+ * @see ADR-0002 (input trace formats)
+ * @see ADR-0003 (canonical event model)
+ * @see ADR-0007 (malformed trace handling)
+ */
+import { z } from 'zod';
+export declare const directionSchema: z.ZodEnum<{
+    CS_TO_CSMS: "CS_TO_CSMS";
+    CSMS_TO_CS: "CSMS_TO_CS";
+    UNKNOWN: "UNKNOWN";
+}>;
+export declare const messageTypeSchema: z.ZodEnum<{
+    Call: "Call";
+    CallResult: "CallResult";
+    CallError: "CallError";
+}>;
+/**
+ * Raw OCPP 1.6 JSON message array.
+ * - Call (2):        [2, UniqueId, Action, Payload]
+ * - CallResult (3):  [3, UniqueId, Payload]
+ * - CallError (4):   [4, UniqueId, ErrorCode, ErrorDescription, ErrorDetails]
+ *
+ * We validate the first two elements strictly (MessageTypeId + UniqueId)
+ * and accept arbitrary payload data.
+ */
+export declare const rawOcppMessageSchema: z.ZodTuple<[z.ZodNumber, z.ZodString], z.ZodUnknown>;
+export declare const traceEventInputSchema: z.ZodObject<{
+    timestamp: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+    direction: z.ZodOptional<z.ZodEnum<{
+        CS_TO_CSMS: "CS_TO_CSMS";
+        CSMS_TO_CS: "CSMS_TO_CS";
+        UNKNOWN: "UNKNOWN";
+    }>>;
+    message: z.ZodTuple<[z.ZodNumber, z.ZodString], z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const traceMetadataSchema: z.ZodObject<{
+    stationId: z.ZodOptional<z.ZodString>;
+    ocppVersion: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const traceSchema: z.ZodObject<{
+    traceId: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        stationId: z.ZodOptional<z.ZodString>;
+        ocppVersion: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    events: z.ZodArray<z.ZodObject<{
+        timestamp: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        direction: z.ZodOptional<z.ZodEnum<{
+            CS_TO_CSMS: "CS_TO_CSMS";
+            CSMS_TO_CS: "CSMS_TO_CS";
+            UNKNOWN: "UNKNOWN";
+        }>>;
+        message: z.ZodTuple<[z.ZodNumber, z.ZodString], z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const bareArraySchema: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodString], z.ZodUnknown>>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,eAAe;;;;EAAkD,CAAC;AAE/E,eAAO,MAAM,iBAAiB;;;;EAA8C,CAAC;AAE7E;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,sDAwB7B,CAAC;AAML,eAAO,MAAM,qBAAqB;;;;;;;;iBAIhC,CAAC;AAMH,eAAO,MAAM,mBAAmB;;;;;iBAK9B,CAAC;AAMH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;iBAItB,CAAC;AAMH,eAAO,MAAM,eAAe,kEAAuC,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,81 @@
+/**
+ * Zod schemas for OCPP DebugKit trace input validation.
+ *
+ * These schemas validate untrusted input at the boundary (ADR-0007).
+ * They prevent prototype pollution and ensure structural correctness
+ * before any processing occurs.
+ *
+ * @see docs/trace-format-spec.md
+ * @see ADR-0002 (input trace formats)
+ * @see ADR-0003 (canonical event model)
+ * @see ADR-0007 (malformed trace handling)
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+export const directionSchema = z.enum(['CS_TO_CSMS', 'CSMS_TO_CS', 'UNKNOWN']);
+export const messageTypeSchema = z.enum(['Call', 'CallResult', 'CallError']);
+/**
+ * Raw OCPP 1.6 JSON message array.
+ * - Call (2):        [2, UniqueId, Action, Payload]
+ * - CallResult (3):  [3, UniqueId, Payload]
+ * - CallError (4):   [4, UniqueId, ErrorCode, ErrorDescription, ErrorDetails]
+ *
+ * We validate the first two elements strictly (MessageTypeId + UniqueId)
+ * and accept arbitrary payload data.
+ */
+export const rawOcppMessageSchema = z
+    .tuple([z.number(), z.string()])
+    .rest(z.unknown())
+    .refine((msg) => msg[0] === 2 || msg[0] === 3 || msg[0] === 4, {
+    message: 'MessageTypeId must be 2 (Call), 3 (CallResult), or 4 (CallError)',
+})
+    .refine((msg) => (msg[0] === 2 ? msg.length >= 4 : true), {
+    message: 'Call message must have at least 4 elements: [2, UniqueId, Action, Payload]',
+})
+    .refine((msg) => (msg[0] === 3 ? msg.length >= 3 : true), {
+    message: 'CallResult message must have at least 3 elements: [3, UniqueId, Payload]',
+})
+    .refine((msg) => (msg[0] === 4 ? msg.length >= 5 : true), {
+    message: 'CallError message must have at least 5 elements: [4, UniqueId, ErrorCode, ErrorDescription, ErrorDetails]',
+})
+    .refine((msg) => (msg[0] === 2 ? typeof msg[2] === 'string' : true), {
+    message: 'Call message Action (index 2) must be a string',
+})
+    .refine((msg) => (msg[0] === 4 ? typeof msg[2] === 'string' : true), {
+    message: 'CallError ErrorCode (index 2) must be a string',
+})
+    .refine((msg) => (msg[0] === 4 ? typeof msg[3] === 'string' : true), {
+    message: 'CallError ErrorDescription (index 3) must be a string',
+});
+// ---------------------------------------------------------------------------
+// Trace Event Input (ADR-0002, ADR-0003)
+// ---------------------------------------------------------------------------
+export const traceEventInputSchema = z.object({
+    timestamp: z.union([z.string(), z.number()]).nullable().optional(),
+    direction: directionSchema.optional(),
+    message: rawOcppMessageSchema,
+});
+// ---------------------------------------------------------------------------
+// Trace Metadata (ADR-0002)
+// ---------------------------------------------------------------------------
+export const traceMetadataSchema = z.object({
+    stationId: z.string().optional(),
+    ocppVersion: z.string().optional(),
+    source: z.string().optional(),
+    description: z.string().optional(),
+});
+// ---------------------------------------------------------------------------
+// JSON Object Trace Format (ADR-0002)
+// ---------------------------------------------------------------------------
+export const traceSchema = z.object({
+    traceId: z.string().optional(),
+    metadata: traceMetadataSchema.optional(),
+    events: z.array(traceEventInputSchema).min(1, { message: 'events array must not be empty' }),
+});
+// ---------------------------------------------------------------------------
+// Bare Array Format (degenerate — array of raw OCPP messages)
+// ---------------------------------------------------------------------------
+export const bareArraySchema = z.array(rawOcppMessageSchema).min(1);
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"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"}

package/dist/summarizer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Session summarizer — produces overview statistics for a charging session.
+ *
+ * @see ADR-0003
+ */
+import type { Session, SessionSummary } from './types.js';
+/**
+ * Summarize a charging session with overview statistics.
+ *
+ * @param session - The session to summarize
+ * @param failureCount - Number of failures detected in this session
+ * @returns Summary statistics
+ */
+export declare function summarizeSession(session: Session, failureCount?: number): SessionSummary;
+/**
+ * Summarize all sessions in a trace.
+ *
+ * @param sessions - All sessions in the trace
+ * @param failures - All detected failures
+ * @returns Array of session summaries
+ */
+export declare function summarizeSessions(sessions: Session[], failures: {
+    eventIds: string[];
+}[]): SessionSummary[];
+//# sourceMappingURL=summarizer.d.ts.map

package/dist/summarizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizer.d.ts","sourceRoot":"","sources":["../src/summarizer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,SAAI,GAAG,cAAc,CAqBnF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,OAAO,EAAE,EACnB,QAAQ,EAAE;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,EAAE,GACjC,cAAc,EAAE,CAUlB"}

package/dist/summarizer.js

@@ -0,0 +1,47 @@
+/**
+ * Session summarizer — produces overview statistics for a charging session.
+ *
+ * @see ADR-0003
+ */
+/**
+ * Summarize a charging session with overview statistics.
+ *
+ * @param session - The session to summarize
+ * @param failureCount - Number of failures detected in this session
+ * @returns Summary statistics
+ */
+export function summarizeSession(session, failureCount = 0) {
+    const actionSequence = session.events
+        .filter((e) => e.messageType === 'Call' && e.action !== null)
+        .map((e) => e.action);
+    const durationMs = session.startTime !== null && session.endTime !== null
+        ? session.endTime - session.startTime
+        : null;
+    return {
+        sessionId: session.sessionId,
+        stationId: session.stationId,
+        connectorId: session.connectorId,
+        transactionId: session.transactionId,
+        status: session.status,
+        eventCount: session.events.length,
+        durationMs,
+        failureCount,
+        actionSequence,
+    };
+}
+/**
+ * Summarize all sessions in a trace.
+ *
+ * @param sessions - All sessions in the trace
+ * @param failures - All detected failures
+ * @returns Array of session summaries
+ */
+export function summarizeSessions(sessions, failures) {
+    return sessions.map((session) => {
+        // Count failures that belong to this session
+        const sessionEventIds = new Set(session.events.map((e) => e.id));
+        const failureCount = failures.filter((f) => f.eventIds.some((id) => sessionEventIds.has(id))).length;
+        return summarizeSession(session, failureCount);
+    });
+}
+//# sourceMappingURL=summarizer.js.map

package/dist/summarizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarizer.js","sourceRoot":"","sources":["../src/summarizer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,YAAY,GAAG,CAAC;IACjE,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM;SAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC;SAC5D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAgB,CAAC,CAAC;IAElC,MAAM,UAAU,GACd,OAAO,CAAC,SAAS,KAAK,IAAI,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI;QACpD,CAAC,CAAC,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,SAAS;QACrC,CAAC,CAAC,IAAI,CAAC;IAEX,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM;QACjC,UAAU;QACV,YAAY;QACZ,cAAc;KACf,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAmB,EACnB,QAAkC;IAElC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC9B,6CAA6C;QAC7C,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACjE,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACzC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CACjD,CAAC,MAAM,CAAC;QAET,OAAO,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/timeline.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Session timeline builder — correlates events into logical charging sessions.
+ *
+ * Session correlation strategy (ADR-0006):
+ * 1. Primary: transactionId (from StartTransaction response / StopTransaction)
+ * 2. Secondary: connectorId + stationId grouping
+ * 3. Events without a transaction are grouped by stationId + connectorId
+ *
+ * @see ADR-0006
+ */
+import type { Event, Session } from './types.js';
+/**
+ * Build session timelines from normalized events.
+ *
+ * Correlates events into logical charging sessions by:
+ * 1. Matching StartTransaction responses to find transactionIds
+ * 2. Grouping StopTransaction and MeterValues events by transactionId
+ * 3. Grouping StatusNotification events by connectorId + stationId
+ * 4. Events without a transaction are assigned to a "no-session" group
+ *
+ * Sessions are ordered by their first event's timestamp.
+ *
+ * @see ADR-0006
+ */
+export declare function buildSessionTimeline(events: Event[]): Session[];
+//# sourceMappingURL=timeline.d.ts.map

package/dist/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AA4FjD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,EAAE,CAgN/D"}