@open-charging-cloud/chargy-core 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -7,6 +7,252 @@ While the version number is below 1.0.0, breaking changes are released in minor
 versions and are always listed first below.
 
 
+## [0.16.0] - 2026-09-08
+
+### Added
+
+- **A grid operator is a party to a charging session.** When the grid asks a
+  station to charge more slowly, the session's power drops for a reason that is
+  neither the car's nor the station's, and without the constraint and the key
+  it was signed with that dip is indistinguishable from a fault. `IGridOperator`
+  carries the identity and the keys to tell the two apart: a charging station
+  operator minus everything about charging infrastructure, because a grid
+  operator runs no pools, stations or tariffs. `@id` is all it requires. A live
+  link names one in `gridOperator`, a charge transparency record several in
+  `gridOperators` - a live link describes one ongoing session, a record may
+  span several grids.
+
+- **`signGridPowerConstraints` is the key usage a grid operator signs under.**
+  It joins `signCTRs` for whole records and `signMeterValues` /
+  `signEnergyMeterValues` for readings. A constraint is signed with every key
+  the operator holds for that usage, so a verifier supporting either algorithm
+  can check it.
+
+- **The OCMF-Test-01 series carries a power constraint.** It is now a five
+  minute session in 35 documents instead of a three minute one in twenty, and
+  the grid operator limits the charging power to 6 kW for one minute in the
+  middle of it. The constraint is a `legallyRelevantLogMessage` signed by
+  `DE*VEN` under `signGridPowerConstraints` with one ECDSA and one Ed25519 key,
+  the meter takes an extra reading where it begins and where it ends, the power
+  in between stays below the limit, and the charging periods are cut at both
+  ends of it - which is the whole point of the fixture: a dip in the curve with
+  a signed explanation next to it. The generator gained
+  `OCMF-Test-01__LRLMs.json`, the log messages whose times are relative to the
+  start reading, and `--log-messages` / `--no-log-messages` to steer them.
+
+- **Every optional property of the live link document may now be explicitly
+  `undefined`.**
+  Under `exactOptionalPropertyTypes` a bare `?:` means the property may be
+  omitted but not set to `undefined`, which made building a live link from
+  optional sources need a conditional per property. `description`, `timeSource`,
+  `chargingStationOperator`, `chargingStation`, `chargingSessionId`,
+  `eMobilityProvider`, `contract`, `warnings` and `signatureVerification` now
+  say `| undefined` like their neighbours already did.
+
+### Fixed
+
+- **The live link documentation described a format two releases old.** Every
+  one of these would have produced a document the current code turns away, and
+  the format documentation is where a producer looks first:
+
+  - The TOTP configuration was documented as `initialSharedSecret`, renamed to
+    `sharedSecret` in 0.15.0. `isTOTPConfig()` requires the new name, so a
+    transport copied from the documentation failed `isLiveTransport()` and was
+    dropped by a filtering reader without a word - the same failure 0.15.1
+    fixed in the fixtures, still sitting in the prose.
+  - Transports named their endpoint in `url`, removed in 0.15.0. A transport
+    copied from the documentation was well-formed and named no endpoint at all.
+  - The minimal document had no `created` and was described as the smallest
+    recognised live link. Since 0.15.0 it is not a live link at all:
+    recognition requires `@context`, `created` and `liveTransports`, and the
+    documentation still said `@context` alone decided it.
+  - Reading a document was described as filling in a missing `created`. It
+    stopped doing that in 0.15.0, because that timestamp recorded when the
+    document was *read*.
+  - The TOTP table listed two properties of seven and declared `timeStep`
+    required, which it is not; the paragraph below it said the format does not
+    specify a hash algorithm, digits or encoding, which it has since done in
+    `hashAlgorithm`, `totpLength` and `alphabet`.
+  - `refresh` was said to be validated by `IsAChargeTransparencyLiveLink()` and
+    the point-of-use guards to include an `isTransport`. Both are
+    `isLiveTransport()` now.
+
+### Changed
+
+- **The format documentation lists the properties a live link declares.** The
+  interfaces grew in 0.14.0 and 0.15.0 without the documentation following, so
+  `chargingSessionId`, `eMobilityProvider`, `chargingPeriods`,
+  `legallyRelevantLogMessages` and `supportMessages` appeared nowhere, while
+  nine properties that *are* declared were still listed as carried by the
+  fixtures and unvalidated. That section now holds what it says: `@id`,
+  `imageURLs` and the superseded `geoLocation` and `connector`.
+
+- **An operator's `contact`, `support` and `privacy` are optional.**
+  `IChargingStationOperator` had required all three since it was written, and
+  `IGridOperator` inherited that when it took its shape. No document in the
+  repository carries any of them, nothing validates them, and requiring them
+  forced anyone building an operator in TypeScript to invent three properties
+  the format's own fixtures do without.
+
+- **The fixtures write an operator's `name` as the `I18NString` it is typed
+  as.** The template said `"GraphDefined"` and `"Vanaheimr Electric"` where the
+  interfaces say a language-tag-to-string object, so the one document meant to
+  show the format did not follow it. It is `{ "en": ... }` now, and the series
+  is regenerated.
+
+- **`ILegallyRelevantLogMessage` names its `text` before its `data`.** The
+  message comes before the payload that qualifies it, the way `ISupportMessage`
+  already had it.
+
+- **`CTR_Format.md` lists `gridOperators`** among the top-level properties of a
+  charge transparency record.
+
+- **Two live link tests no longer spell out what the generator regenerates.**
+  One asserted `created` to be a fixed timestamp and one the meter values to
+  number twenty; both are properties of the moment the fixture was generated
+  and of the session parameters, so both broke the first time the series was
+  regenerated. They now compare `created` against what the document itself
+  states - which is the actual assertion, that reading neither fills in nor
+  replaces it - and count the OCMF documents rather than naming a number.
+
+
+## [0.15.1] - 2026-09-07
+
+### Fixed
+
+- **`isTOTPConfig()` rejected every TOTP configuration that named its hash
+  algorithm.** It asked for a number where `TOTPConfig.hashAlgorithm` is a
+  string, so a transport stating `"SHA-256"` was not a transport any more.
+  Nothing said so: `isLiveTransport()` simply returned false, and a reader
+  filtering its transports through it dropped that one without a word. Only
+  configurations leaving the property out were unaffected, which is why the
+  fixtures did not catch it.
+
+### Changed
+
+- **The OCMF-Test-01 series still spelled the TOTP secret the old way.** The
+  rename to `sharedSecret` reached the interfaces in 0.15.0 but not the
+  fixtures, so `isLiveTransport()` dropped the websocket and the httpSSE
+  transport of every document in it - the test data did not survive its own
+  type guard. The template says `sharedSecret` now, and the series and
+  `ChargeTransparencyLiveLink_1.json` are regenerated and re-signed from it.
+
+
+## [0.15.0] - 2026-09-07
+
+### Breaking
+
+- **A live link is recognised by the three things every one of them has.**
+  `IsAChargeTransparencyLiveLink()` requires the `@context`, a `created`
+  timestamp and a `liveTransports` array; a document missing any of them is not
+  a live link. Everything else stays unvalidated there - a malformed optional
+  field, and a broken transport most of all, must not turn a document into an
+  unrecognised one that then fails as an "unknown format". A transport is
+  judged where the transports are read, not where the document is identified.
+
+- **Reading a document no longer fills in a missing `created`.** It used to get
+  the current UTC time, which recorded when the document was *read*. In a
+  legally relevant document that is not what "created" means, and reading is
+  not creating. A live link states its own timestamp, and one that does not is
+  not a live link.
+
+- **A transport names its endpoints in `urls`, and only there.** The singular
+  `url` was the older spelling of the same thing, was never part of
+  `ILiveTransport`, and `isLiveTransport()` no longer looks at it. A transport
+  that carries only `url` is still recognised - an unknown property is not an
+  error - but it names no endpoint, so there is nothing to show and nothing to
+  poll. The fixtures, the format documentation and the tests all say `urls`.
+
+- **`Transport` is now `LiveTransports`, `ITransport` is `ILiveTransport`, and
+  `ITransportURL` is gone.** An entry of `urls` is either the URL itself or a
+  `chargyInterfaces.IURL` carrying it alongside a `priority` and a `weight`.
+  The type guard is `isLiveTransport()`; the top-level export keeps the name
+  `isTransport`, so a consumer importing it from the package index sees no
+  rename, while one reaching through the `ChargeTransparencyLiveLink` namespace
+  has to follow.
+
+- **`TOTPConfig` moved to `chargyInterfaces`, and `initialSharedSecret` is now
+  `sharedSecret`.** It also gained `validityTime`, `totpLength`, `alphabet`,
+  `timestamp` and `hashAlgorithm`, and `timeStep` became optional - the shape
+  the TOTP library actually takes. `isTOTPConfig()` validates it, and
+  `isLiveTransport()` calls it, so a transport still spelling the secret the
+  old way is dropped along with its TOTP.
+
+- **The top-level `IURL` is a different type now.** `chargyInterfaces.IURL` -
+  a `url` with an optional `priority` and `weight` - is what the name resolves
+  to when it is imported from the package index; the JSON-LD document with the
+  `@context` of `URLContext` is `SimpleURL.IURL` and is no longer re-exported
+  by name. The two guards keep them apart: `IsAURL()` judges the document,
+  `isURL()` the transport endpoint. Code importing `IURL` from the index keeps
+  compiling and means something else.
+
+- **`IChargeTransparencyLiveLink` lost `imageURLs`, `geoLocation` and
+  `connector`.** Images belong to whoever they show, so they hang off
+  `IChargingStationOperator`, `IChargingStation` and the other things that have
+  one; the position belongs to the charging station, and the connector to its
+  EVSE. A document keeps saying all of it, one level further in.
+
+- **`ILegallyRelevantLogMessage` moved from `IChargeTransparencyRecord` to
+  `chargyInterfaces`,** where a live link can reach it as easily as a record
+  can, and `isConnector()` moved to `chargyInterfaces` next to the `IConnector`
+  it validates. Both keep their names at the package index; only the
+  namespace-qualified paths change.
+
+### Added
+
+- **The interfaces name the quantities they carry.** A metrological value is
+  text - `"22 kW"`, `"(230.00 ±0.12) V, k=2"` - because resolution and
+  uncertainty are part of the reading and a number would drop both, so `Volt`,
+  `Ampere`, `Watt`, `WattHour`, `Ohm`, `Meter`, `Second` and `Kelvin` are
+  aliases of `MetrologicalText` rather than of `number`. `Timestamp`,
+  `CalendarDate`, `LocalTime`, `ISO8601Duration`, `DurationSeconds`, `Degrees`,
+  `LinkedDataContext`, `URL`, `UnitSymbol`, `DecimalScale` and
+  `MeasurementMagnitude` do the same for the values that were plain strings and
+  numbers before. They document meaning and do not validate syntax: parse at
+  the serialization boundary before doing arithmetic.
+
+- **A live link says what it is about, not only where to fetch it.** It may now
+  carry its `timeSource`, `lastUpdated`, `updates` and `docRefIdGeneration`,
+  the `chargingStationOperator`, `chargingStation`, `chargingSessionId`,
+  `eMobilityProvider` and `contract` of the session, its `signedMeterValues`,
+  `chargingPeriods`, `legallyRelevantLogMessages` and `supportMessages`, and
+  the `keyIdGeneration` its signatures are read under. Most of it was already
+  in the documents and read untyped; it is described now.
+
+- **`@context` may be a list.** A document can name an extension context
+  alongside this one, and is recognised as long as the list contains the live
+  link context.
+
+- **New shapes for what the documents already contained:**
+  `IDocumentSignature` - the signature `verifyDocumentSignatures()` consumes -,
+  `ISignedMeterValues`, `ITimeSource` with `ITimeServer`, `ISupportMessage`,
+  `ILocalController`, `ITemperatureSensor` and `IMetrologicalCable`, the cable
+  profile that states its length and resistance as quantity text without a
+  second unit field.
+
+- **The topology interfaces carry ids next to their objects.** A charging pool,
+  station, EVSE or energy meter can name what it belongs to and what belongs to
+  it by id - `chargingStationIds`, `EVSEIds`, `energyMeterIds`,
+  `chargingTariffIds`, `temperaturSensorIds` and the singular counterparts -
+  so a document may reference rather than nest. They also gained `imageURLs`,
+  an operator gained a `name`, an EVSE a `powerType` and a `maxPower`, and a
+  public key `keyUsage` and `encodings`.
+
+### Changed
+
+- **The OCMF-Test-01 fixture series is regenerated from its template and
+  re-signed,** which the changed transport of every document required.
+
+### Internal dependencies
+
+- @types/node 26.4.1, eslint 10.10.0, globals 17.12.0, playwright 1.63.0 and
+  typescript-eslint 8.69.0. The last of those extends
+  `no-meaningless-void-operator` to expressions that are not calls, which
+  caught the `void x;` idiom marking a parameter as deliberately unused. Those
+  parameters now carry the underscore prefix `argsIgnorePattern` already
+  covers, the way `_Context` always did.
+
+
 ## [0.14.4] - 2026-09-05
 
 ### Changed

package/README.md

@@ -185,7 +185,7 @@ npx playwright install chromium
 ## Publishing
 
 ```bash
-npm version 0.15.0 --no-git-tag-version
+npm version 0.16.0 --no-git-tag-version
 npm run verify
 npm pack --dry-run
 npm pack

package/dist/browser/index.js

@@ -2006,7 +2006,7 @@ function OIDInfo(data) {
   return "";
 }
 function isTOTPConfig(data) {
-  return isObject(data) && typeof data["sharedSecret"] === "string" && (data["timeStep"] === void 0 || typeof data["timeStep"] === "number") && (data["validityTime"] === void 0 || typeof data["validityTime"] === "number") && (data["totpLength"] === void 0 || typeof data["totpLength"] === "number") && (data["alphabet"] === void 0 || typeof data["alphabet"] === "string") && (data["timestamp"] === void 0 || typeof data["timestamp"] === "string") && (data["hashAlgorithm"] === void 0 || typeof data["hashAlgorithm"] === "number");
+  return isObject(data) && typeof data["sharedSecret"] === "string" && (data["timeStep"] === void 0 || typeof data["timeStep"] === "number") && (data["validityTime"] === void 0 || typeof data["validityTime"] === "number") && (data["totpLength"] === void 0 || typeof data["totpLength"] === "number") && (data["alphabet"] === void 0 || typeof data["alphabet"] === "string") && (data["timestamp"] === void 0 || typeof data["timestamp"] === "string") && (data["hashAlgorithm"] === void 0 || typeof data["hashAlgorithm"] === "string");
 }
 function isURL(data) {
   if (typeof data === "string")