Changelog

Contract history, version by version.

The public contract is backend/public_openapi.json (frozen by tools/audit/freeze_public_openapi.py, guarded by tools/audit/verify_public_openapi.py). Additive changes are listed under the current version; a BREAKING change requires a new ## <version> section here AND an info.version bump in backend/app/public_api/app.py — the verify gate refuses it otherwise. Published at shopcommander.com/developers/changelog.

1.0.0-rc.4

Pre-release change-feed truthfulness correction. No external consumers depended on RC.3.

• Removed the unimplemented shop.updated event from V1. Shop-profile reads should be cached conservatively and refreshed periodically.
• job.created now originates from every native and public job-construction path, not only the public add-job route.

1.0.0-rc.3

Pre-release bounded-response contract cleanup. No external consumers depended on RC.2.

• Job resources no longer embed unbounded parts or labor arrays in any response, including appointment conversion and add-job commands. Use the cursor-paginated job child collections instead.

1.0.0-rc.2

Pre-release reliability and bounded-read correction. No external consumers depended on RC.1.

• Webhook outbox persistence is mandatory and repeated updates are never suppressed; added job.created and task.updated.
• Webhook signing secrets are shown only on create/rotate. Previous-secret signatures expire after 24 hours.
• Removed unbounded embedded repair-order job expansion. Jobs, job parts, and job labor are cursor-paginated collections.
• Corrected event visibility pagination and rate-limit retry units.

1.0.0-rc.1

Pre-release contract reset. No external consumers depended on the earlier development artifact.

• Write no longer implies read; full-resource mutations require explicit read plus write/action scopes. Added pricing.read and explicit pricing/cost redaction.
• Repair orders expose one state; jobs expose decision_state plus execution_state. Removed redundant/internal state aliases and appointment source.
• Appointment-origin conversion moved to POST /appointments/{appointment_id}/repair-order.
• Added strict offset-aware instant parsing, presence-aware PATCH/null behavior, lifecycle/date filter names, and explicit webhook wildcard semantics.
• Consequential commands require transactional Idempotency-Key handling with encrypted seven-day replay and a thirty-day reuse tombstone.
• Added bearer security, scope, success/error, rate-limit and idempotency metadata to the OpenAPI document.

1.0

Initial V1 contract (docs/public-api-plan.md, phases P0–P4):

• API keys (sc_live_…) with shop-granted scopes; Bearer auth only.
• Reads: shop (+capabilities), customers, vehicles, appointments (+availability), repair orders, jobs, technicians, canned jobs, inventory items, invoices, payments, tasks, events.
• Writes: customers, vehicles, appointments (create/update/cancel/check-in), repair orders (create, add job), job execution actions, tasks, external references, webhook endpoints.
• Envelope conventions: typed prefixed ids, string-decimal money, UTC Z instants, opaque cursor pagination, one error envelope with workflow blockers, Idempotency-Key, expected_version, RateLimit-* headers.
• Webhooks: signed (ShopCommander-Signature: t=…,v1=…), at-least-once, thin payloads, curated event taxonomy.