@open-charging-cloud/chargy-core 0.3.0 → 0.5.0

package/README.md

@@ -1,30 +1,107 @@
 # Chargy Core
 
-The ChargyCore TypeScript library shared between Chargy Desktop, Web & Mobile applications.
+Chargy Core is a transparency software library for the validation of secure and transparent e-mobility charging processes, as defined by the *German Calibration Law ("Eichrecht")* in combination with the [Alternative Fuels Infrastructure Regulation (AFIR)](https://transport.ec.europa.eu/transport-themes/clean-transport/alternative-fuels-sustainable-mobility-europe/alternative-fuels-infrastructure_en) and the new [Measuring instruments (MID)](https://single-market-economy.ec.europa.eu/single-market/goods/european-standards/harmonised-standards/measuring-instruments-mid_en) of the European Commission and the [European Digital Quality Infrastructure](https://www.qi-digital.de/en/). The software allows you to verify the cryptographic signatures of energy measurements within charge detail records and comes with a couple of useful extentions to simplify the entire process for endusers and operators.
+
+This software is written as a modern ESM TypeScript package with generated declaration files, providing shared core functionality for the Chargy Desktop, Web & Mobile applications.
+
+
+## Benefits of Chargy
+
+1. Chargy comes with __*meta data*__. True charging transparency is more than just signed smart meter values. Chargy allows you to group multiple signed smart meter values to entire charging sessions and to add additional meta data like EVSE information, geo coordinates, tariffs, ... within your backend in order to improve the user experience for the ev drivers.
+2. Chargy is __*secure*__. Chargy implements a public key infrastructure for managing certificates of smart meters, EVSEs, charging stations, charging station operators and e-mobility providers. By this the ev driver will always retrieve the correct public key to verify a charging process automatically and without complicated manual lookups in external databases.
+3. Chargy is __*Open Source*__. In contrast to other vendors in e-mobility, we belief that true transparency is only trustworthy if the entire process and the required software is open and reusable under a fair copyleft license (AGPL).
+4. Chargy is __*open for your contributions*__. We currently support adapters for the protocols of different charging station vendors like chargeIT mobility, ABL (OCMF), chargepoint. The certification at the Physikalisch-Technische Bundesanstalt (PTB) is provided by chargeIT mobility. If you want to add your protocol or a protocol adapter feel free to read the contributor license agreement and to send us a pull request.
+
+
+## Supported Charge Transparency Data Formats
+
+- Alfen
+- Bauer energy meters
+- EMH energy meters
+- Mennekes XML
+- OCMF v1.1 - v1.4
+- Porsche
+- chargeIT (2 versions)
+- chargepoint
+
 
 ## Usage
 
 ```ts
 import { Chargy } from "@open-charging-cloud/chargy-core";
-import { OCMF } from "@open-charging-cloud/chargy-core";
 ```
 
-The package is published as modern ESM and ships generated TypeScript declarations.
+
+## Runtime Architecture
+
+ChargyCore is consumed in different JavaScript runtimes. The browser-based Chargy WebApp and Electron renderer processes have Web APIs such as `DOMParser`, `Blob`, `TextEncoder`, `ImageData`, `DOMMatrix`, `Path2D`, and browser worker loading semantics. Node.js-based tests, command line tools, server-side verification, and build-time checks do not provide the same environment.
+
+For that reason the package ships two JavaScript builds behind one public import:
+
+```text
+dist/browser/index.js
+dist/node/index.js
+```
+
+The runtime-specific file is selected through conditional package exports in `package.json`. Browser bundlers should resolve the `browser` condition and receive `dist/browser/index.js`. Node.js resolves the `node` condition and receives `dist/node/index.js`.
+
+This split is especially important for PDF.js. Browser contexts should use the normal `pdfjs-dist` build, because the browser already provides the canvas and DOM APIs PDF.js expects. Node.js should use `pdfjs-dist/legacy/build/pdf.mjs`, because the legacy build contains Node-oriented setup for the missing canvas-related globals and avoids the modern browser-only assumptions.
+
+Keeping these paths separate has several advantages:
+
+- Browser bundles do not include the Node/legacy PDF.js path as an unused lazy chunk.
+- Node tests and CLI-style usage do not depend on browser-only PDF.js behavior.
+- Chargy apps do not need local Webpack aliases or test polyfills for ChargyCore internals.
+- Bundle checks can verify that the browser build only references browser PDF.js imports and the Node build only references legacy PDF.js imports.
+
+When adding runtime-sensitive dependencies, avoid branching on runtime inside shared source code if that would make bundlers see both implementations. Prefer a small adapter under `src/` and let the build or conditional exports select the runtime-specific implementation.
+
 
 ## Development
 
 ```bash
 npm install
 npm run typecheck
-npm test
+npm run lint
 npm run build
+npm run test:node
+npm run test:bundle
+npm run test:browser
+npm test
+npm run verify
 ```
 
 The build emits the package into `dist/`.
 
 
+### Expected Test Flow
+
+For code changes, use the full verification flow before publishing or handing a package to the Chargy apps:
+
+```bash
+npm run verify
+```
+
+`verify` runs the following checks:
+
+- `npm run typecheck`: validates the TypeScript sources and test/config TypeScript files.
+- `npm run lint`: runs the strict type-aware ESLint setup. Existing migration findings are warnings, new unused variables are errors.
+- `npm test`: runs all runtime checks:
+  - `npm run test:node`: runs the Chargy fixture tests in Vitest's Node environment and uses the Node PDF.js adapter.
+  - `npm run build`: creates both package builds.
+  - `npm run test:bundle`: checks the generated bundles so the browser build only references the browser PDF.js path and the Node build only references the legacy PDF.js path.
+  - `npm run test:browser`: imports `dist/browser/index.js` in headless Chromium via Vitest Browser Mode and verifies the public browser entry can be loaded and instantiated.
+- `npm run build`: recreates the final publishable `dist/` output.
+
+For dependency, build, export, PDF.js, or browser-facing changes, run the individual steps while iterating and finish with `npm run verify`. The browser test requires Playwright's Chromium browser; if it is missing locally, run:
+
+```bash
+npx playwright install chromium
+```
+
+
 ```bash
-npm version 0.3.0 --no-git-tag-version
+npm version 0.5.0 --no-git-tag-version
 npm run verify
 npm pack --dry-run
 npm pack

package/dist/BSMCrypt01.d.ts.map

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