@deloryx/contracts-tracking

Shared wire-format schema for the Deloryx tracking platform.

• Source of truth: model/*.smithy — Smithy IDL describing the TrackingService and event payloads.
• Generated artifacts (committed):
  • codegen/typescript/ — TS types consumed by deloryx-js (browser library).
  • codegen/kotlin/com/deloryx/tracking/contracts/Events.kt — Kotlin data classes consumed by deloryx-backend-tracking-gateway.

Why Smithy?

The user asked for "something like Smithy" (AWS Smithy IDL) so a single schema generates both TypeScript (for the library) and Kotlin (for the Quarkus gateway). This guarantees the wire format on both sides cannot drift.

Regenerating after schema changes

# Pre-req: install Smithy CLI (https://smithy.io/2.0/guides/smithy-cli/index.html)
#   brew install smithy-cli           # macOS
#   curl -L https://github.com/smithy-lang/smithy/releases/latest/download/smithy-cli-linux-x86_64.zip ...

npm install
npm run build                # smithy build + quicktype TS + quicktype Kotlin

npm run verify-fresh runs the build and git diff --exit-code codegen to confirm no drift. CI gates PRs on this check — a PR that modifies model/*.smithy without regenerating codegen/* fails.

Current status

The Smithy → JSON Schema → quicktype codegen pipeline is scaffolded but not yet wired into CI. The committed codegen/typescript/ and codegen/kotlin/ files are hand-written to match the Smithy model and treated as the practical source of truth until Smithy CLI is part of the dev image.

When changing the schema today, edit BOTH:

1. model/*.smithy (the documented spec)
2. The corresponding codegen/typescript/index.ts and codegen/kotlin/.../Events.kt

When the codegen pipeline lands, only step 1 will be needed.

Consumer wiring

TypeScript library (deloryx-js/):

import { CaptureEnvelope, TrackingEvent, BUILTIN_EVENT_NAMES } from '@deloryx/contracts-tracking';

Resolves via npm workspace or a file:../deloryx-clients-tracking-contracts dependency.

Quarkus gateway (deloryx-backend-tracking-gateway/): For v0 the Kotlin file is copied directly into the gateway's source tree at build time via a Maven process-resources script. v1 will publish this as a proper Maven artifact com.deloryx:deloryx-clients-tracking-contracts-kotlin.