docs: integration examples — 4 example projects

CURRENT_STATE.md

@@ -204,6 +204,7 @@ integration examples, and contributor onboarding.
 - ✅ Rich scenario assertions — 8 assertion types, `evaluateScenario()` (Issue #86)
 - ✅ Assert-based scenarios — 5 new scenarios (15 total) + `compareScenarioReports()` (Issue #87)
 - ✅ CLI: ci + anonymize + diff commands (Issue #88)
+- ✅ Integration examples — 4 example projects (Issue #89)
 
 ## What's Next
 

README.md

@@ -114,6 +114,14 @@ import { generateMarkdownReport } from '@ocpp-debugkit/toolkit/reporter';
 See the [Migration Guide](./docs/migration.md) if you are upgrading from the
 old multi-package layout.
 
+### Examples
+
+See the [`examples/`](./examples/) directory for integration examples:
+- `simple-trace/` — Parse, detect, and report
+- `simple-csms/` — CSMS validation mock
+- `simulator-output/` — JSONL processing + HTML report
+- `ci-example/` — GitHub Actions CI integration
+
 ### Web App
 
 Visit [ocppdebugkit.com/inspector](https://ocppdebugkit.com/inspector) to

eslint.config.js

@@ -24,6 +24,7 @@ export default tseslint.config(
       '**/coverage/**',
       '**/node_modules/**',
       '**/tests/external-fixture/**',
+      'examples/**',
     ],
   },
 );

examples/README.md

@@ -0,0 +1,23 @@
+# Examples
+
+Integration examples showing how to use `@ocpp-debugkit/toolkit` in your projects.
+
+## Available Examples
+
+| Directory | Description |
+|-----------|-------------|
+| [`simple-trace/`](./simple-trace/) | Parse a trace, detect failures, generate a Markdown report |
+| [`simple-csms/`](./simple-csms/) | Validate incoming traces (CSMS mock), check for failures |
+| [`simulator-output/`](./simulator-output/) | Process JSONL simulator output, generate HTML report |
+| [`ci-example/`](./ci-example/) | Use `ocpp-debugkit ci` in GitHub Actions workflows |
+
+## Running
+
+Each example is a standalone project. `cd` into the directory and run:
+
+```bash
+npm install
+npm start
+```
+
+All trace data is fully synthetic — no real station identifiers or personal data.

examples/ci-example/.github/workflows/ocpp-test.yml

@@ -0,0 +1,23 @@
+name: OCPP Scenario Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ocpp-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+
+      - name: Install OCPP DebugKit CLI
+        run: npm install -g @ocpp-debugkit/toolkit
+
+      - name: Run scenario tests
+        run: ocpp-debugkit ci --format json

examples/ci-example/README.md

@@ -0,0 +1,39 @@
+# CI Integration Example
+
+Demonstrates how to use `ocpp-debugkit ci` in a GitHub Actions workflow to
+run scenario tests as part of your CI pipeline.
+
+## Setup
+
+1. Install the CLI:
+   ```bash
+   npm install -g @ocpp-debugkit/toolkit
+   ```
+
+2. Create scenario files in `scenarios/` (JSON files with the scenario format).
+
+3. Add the workflow file to `.github/workflows/`.
+
+## Workflow
+
+The included workflow (`.github/workflows/ocpp-test.yml`) runs:
+```bash
+ocpp-debugkit ci --format json
+```
+
+It exits 0 if all scenarios pass, 1 if any fail. The JSON output can be
+parsed by CI tooling for dashboards or notifications.
+
+## Scenario File Format
+
+```json
+{
+  "name": "my-scenario",
+  "description": "Custom scenario for CI testing",
+  "trace": { ... },
+  "expectedFailures": ["FAILED_AUTHORIZATION"],
+  "assertions": [
+    { "type": "event_order", "params": { "actions": ["BootNotification", "Authorize"] } }
+  ]
+}
+```

examples/ci-example/scenarios/example-fail.json

@@ -0,0 +1,38 @@
+{
+  "name": "example-fail",
+  "description": "Example scenario that detects a failed authorization.",
+  "trace": {
+    "traceId": "ci-example-fail",
+    "metadata": {
+      "stationId": "CS-CI-EXAMPLE-002",
+      "ocppVersion": "1.6",
+      "source": "synthetic-example"
+    },
+    "events": [
+      {
+        "timestamp": "2024-01-15T09:00:00.000Z",
+        "direction": "CS_TO_CSMS",
+        "message": [2, "m1", "BootNotification", { "chargePointSerialNumber": "CS-CI-002" }]
+      },
+      {
+        "timestamp": "2024-01-15T09:00:00.500Z",
+        "direction": "CSMS_TO_CS",
+        "message": [3, "m1", { "status": "Accepted", "interval": 300 }]
+      },
+      {
+        "timestamp": "2024-01-15T09:00:01.000Z",
+        "direction": "CS_TO_CSMS",
+        "message": [2, "m2", "Authorize", { "idTag": "BAD-CI-TAG" }]
+      },
+      {
+        "timestamp": "2024-01-15T09:00:01.500Z",
+        "direction": "CSMS_TO_CS",
+        "message": [3, "m2", { "idTagInfo": { "status": "Invalid" } }]
+      }
+    ]
+  },
+  "expectedFailures": ["FAILED_AUTHORIZATION"],
+  "assertions": [
+    { "type": "failure_count", "params": { "code": "FAILED_AUTHORIZATION", "min": 1 } }
+  ]
+}

examples/ci-example/scenarios/example-pass.json

@@ -0,0 +1,39 @@
+{
+  "name": "example-pass",
+  "description": "Example scenario that should pass in CI.",
+  "trace": {
+    "traceId": "ci-example-pass",
+    "metadata": {
+      "stationId": "CS-CI-EXAMPLE-001",
+      "ocppVersion": "1.6",
+      "source": "synthetic-example"
+    },
+    "events": [
+      {
+        "timestamp": "2024-01-15T08:00:00.000Z",
+        "direction": "CS_TO_CSMS",
+        "message": [2, "m1", "BootNotification", { "chargePointSerialNumber": "CS-CI-001" }]
+      },
+      {
+        "timestamp": "2024-01-15T08:00:00.500Z",
+        "direction": "CSMS_TO_CS",
+        "message": [3, "m1", { "status": "Accepted", "interval": 300 }]
+      },
+      {
+        "timestamp": "2024-01-15T08:00:01.000Z",
+        "direction": "CS_TO_CSMS",
+        "message": [2, "m2", "Heartbeat", {}]
+      },
+      {
+        "timestamp": "2024-01-15T08:00:01.500Z",
+        "direction": "CSMS_TO_CS",
+        "message": [3, "m2", { "currentTime": "2024-01-15T08:00:01.500Z" }]
+      }
+    ]
+  },
+  "expectedFailures": [],
+  "assertions": [
+    { "type": "event_order", "params": { "actions": ["BootNotification", "Heartbeat"] } },
+    { "type": "no_failures", "params": {} }
+  ]
+}

examples/simple-csms/README.md

@@ -0,0 +1,18 @@
+# Simple CSMS Example
+
+Demonstrates how a CSMS mock could use @ocpp-debugkit/toolkit to validate
+incoming traces and check for failures.
+
+## Run
+
+```bash
+npm install
+npm start
+```
+
+## What it does
+
+1. Parses a trace with validation issues
+2. Validates each OCPP message structurally
+3. Detects failures
+4. Reports validation errors and detected failures

examples/simple-csms/index.js

@@ -0,0 +1,31 @@
+import {
+  parseTrace,
+  validateMessages,
+  detectFailures,
+  buildSessionTimeline,
+} from '@ocpp-debugkit/toolkit/core';
+import { readFileSync } from 'node:fs';
+
+const content = readFileSync('./sample-trace.json', 'utf8');
+const { events } = parseTrace(content);
+
+// Validate each message
+const validations = validateMessages(events);
+let invalidCount = 0;
+for (let i = 0; i < events.length; i++) {
+  const v = validations[i];
+  if (v && !v.valid) {
+    invalidCount++;
+    console.log(`Event ${i}: INVALID - ${v.errors.join(', ')}`);
+  }
+}
+console.log(`\n${events.length - invalidCount}/${events.length} messages valid`);
+
+// Detect failures
+const sessions = buildSessionTimeline(events);
+const failures = detectFailures(events, sessions);
+console.log(`\nDetected ${failures.length} failure(s):`);
+for (const f of failures) {
+  console.log(`  [${f.severity.toUpperCase()}] ${f.code}`);
+  console.log(`    ${f.description}`);
+}

examples/simple-csms/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "ocpp-debugkit-simple-csms-example",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@ocpp-debugkit/toolkit": "^0.2.1"
+  }
+}

examples/simple-csms/sample-trace.json

@@ -0,0 +1,43 @@
+{
+  "traceId": "example-csms-validation",
+  "metadata": {
+    "stationId": "CS-EXAMPLE-002",
+    "ocppVersion": "1.6",
+    "source": "synthetic-example"
+  },
+  "events": [
+    {
+      "timestamp": "2024-01-15T14:00:00.000Z",
+      "direction": "CS_TO_CSMS",
+      "message": [
+        2,
+        "msg-001",
+        "BootNotification",
+        {
+          "chargePointVendor": "ExampleVendor",
+          "chargePointModel": "EX-100",
+          "chargePointSerialNumber": "CS-EXAMPLE-002"
+        }
+      ]
+    },
+    {
+      "timestamp": "2024-01-15T14:00:00.500Z",
+      "direction": "CSMS_TO_CS",
+      "message": [
+        3,
+        "msg-001",
+        { "status": "Accepted", "interval": 300, "currentTime": "2024-01-15T14:00:00.500Z" }
+      ]
+    },
+    {
+      "timestamp": "2024-01-15T14:01:00.000Z",
+      "direction": "CS_TO_CSMS",
+      "message": [2, "msg-002", "Authorize", { "idTag": "BAD-EXAMPLE-TAG" }]
+    },
+    {
+      "timestamp": "2024-01-15T14:01:00.500Z",
+      "direction": "CSMS_TO_CS",
+      "message": [3, "msg-002", { "idTagInfo": { "status": "Invalid" } }]
+    }
+  ]
+}

examples/simple-trace/README.md

@@ -0,0 +1,19 @@
+# Simple Trace Example
+
+Demonstrates basic usage of @ocpp-debugkit/toolkit: parse a trace, detect
+failures, and generate a Markdown report.
+
+## Run
+
+```bash
+npm install
+npm start
+```
+
+## What it does
+
+1. Parses a synthetic OCPP trace file
+2. Builds session timeline
+3. Detects failures
+4. Prints a summary to stdout
+5. Generates a Markdown report

examples/simple-trace/index.js

@@ -0,0 +1,38 @@
+import {
+  parseTrace,
+  buildSessionTimeline,
+  detectFailures,
+  summarizeSessions,
+} from '@ocpp-debugkit/toolkit/core';
+import { generateMarkdownReport } from '@ocpp-debugkit/toolkit/reporter';
+import { readFileSync } from 'node:fs';
+
+// Parse the trace
+const content = readFileSync('./sample-trace.json', 'utf8');
+const { events, warnings } = parseTrace(content);
+
+console.log(`Parsed ${events.length} events (${warnings.length} warnings)`);
+
+// Build session timeline
+const sessions = buildSessionTimeline(events);
+console.log(`Found ${sessions.length} session(s)`);
+
+// Detect failures
+const failures = detectFailures(events, sessions);
+console.log(`Detected ${failures.length} failure(s)`);
+for (const f of failures) {
+  console.log(`  [${f.severity}] ${f.code}: ${f.description}`);
+}
+
+// Generate summary
+const summaries = summarizeSessions(sessions, failures);
+for (const s of summaries) {
+  console.log(
+    `  Session ${s.sessionId}: ${s.status}, ${s.eventCount} events, ${s.failureCount} failures`,
+  );
+}
+
+// Generate Markdown report
+const report = generateMarkdownReport({ events, sessions, failures, summaries, warnings });
+console.log('\n--- Markdown Report (first 500 chars) ---');
+console.log(report.slice(0, 500));

examples/simple-trace/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "ocpp-debugkit-simple-trace-example",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@ocpp-debugkit/toolkit": "^0.2.1"
+  }
+}