|
|
Second v5.0.0 roadmap item: make the Local API's public JSON contract explicit,
documented, and regression-locked, so external consumers (Shortcuts, scripts,
integrations) have a stable surface with a defined compatibility promise.
- LocalAPIContract: new single source of truth for the wire-format version
("v1") and the canonical JSON encoder (ISO-8601 dates, sorted keys). Both the
success and error paths in LocalAPIService now route through it, so the format
can't drift between them, and the ad-hoc per-call-site encoders are gone.
- The response envelope and every payload struct are promoted from `private` to
internal so the contract is a first-class, testable part of the module. The
transport/handler internals (request parser, HTTP response, secret store)
stay private.
- Docs/local-api.md documents the base URL/auth, the envelope, the encoding
conventions (notably: absent optionals are omitted, not null), every endpoint
and its payload fields, the error codes, and the semantic-version-style
compatibility policy (additive changes keep v1; renames/removals/type changes
bump the version). Linked from the README.
- LocalAPIContractTests: 16 structure/"golden" tests pinning the envelope shape,
each payload's field names, the enum encodings, and the ISO-8601 date format.
They assert structure, not values, so ordinary behavior changes don't churn
them but a renamed or dropped field fails CI. Full unit suite: 52 passing.
|
