Contractkit

ContractKit contracts

.ck files under apps/api/data/contracts/ are the source of truth for every HTTP route in this repo. One .ck edit regenerates code in every place the table below lists. Never hand-edit any of them.

Everything below was checked against the installed toolchain: @contractkit/cli 0.11.5, @contractkit/core 0.31.0, @contractkit/plugin-typescript 0.38.12, @contractkit/prettier-plugin 0.14.10, @contractkit/plugin-docs 0.4.1, and plugin-kotlin 0.1.6, plugin-csharp 0.1.5 and plugin-swift 0.1.6. Behaviour here has changed under several of those releases, patch releases included, so check the version before trusting a claim that contradicts what you observe. The published packages ship src/ and a CHANGELOG.md, so the answer is usually in node_modules/@contractkit/<plugin>/ rather than in a guess.

The loop

1. Edit the .ck file (or add a new one under apps/api/data/contracts/<area>/).
2. Regenerate:

   pnpm build:contracts

3. Implement or update the service method the operation names.
4. Type-check both sides: pnpm --filter @deadair/api build and pnpm --filter @deadair/sdk build.

Add --force (pnpm --filter @deadair/api exec contractkit --force) when output looks stale: the CLI caches by file hash under .contractkit/cache. The cache is also fingerprinted with the contractkit package versions, so a dependency bump drops it on its own.

What one file generates

Given apps/api/data/contracts/<area>/<filename>.ck, per apps/api/contractkit.config.json:

The website pages come from @contractkit/plugin-docs's docusaurus target. index.md in that folder is written once and then left alone, so it is the one hand-edited file there. The pages are Markdown, which Prettier ignores here, but the _category_.json files and openapi.yaml are not, so they come out of the generator already in Prettier's form; if a version bump changes that, add them to the prettier --write roots in build:contracts. Both come from @contractkit/plugin-docs, which before 0.3.1 wrote a spec no YAML parser accepted, named SDK methods the SDK does not have, and left a file-level security floor off the pages: do not pin it below that.

{area} comes from the file's own options { keys: { area: ... } } block, so that key decides which module directory the types land in and which sdk.<area> namespace the client hangs off. Split contracts by convention: <area>.ck holds operation declarations, <area>.types.ck holds contract declarations.

The Kotlin output

A second plugin, @contractkit/plugin-kotlin, generates a Ktor client for the Android listener. Its config is three keys — baseDir, packageName, sdkName — and both scaffold and includeInternal are deliberately off: apps/android owns the Gradle file, and an operation(internal) has no business on a listener's phone. One model file per contract file, one client per operation file; there is no area/subarea nesting, so authentication.factor.ck becomes AuthenticationFactorClient rather than a member of an authentication namespace.

Nothing about the Kotlin output is checked by Prettier — it has no parser for .kt — so build:contracts re-formats only the three TypeScript roots and the Kotlin is committed exactly as emitted. It is compiled by apps/android's :sdk subproject and by nothing else.

Kotlin that does not compile is a generator bug, and it is fixed upstream in the ContractKit repository with a test and a changeset, never in the output. The generator's own README says its Kotlin had never been put through a toolchain, and the first attempt here found two: a /* in contract prose opened a nested comment that swallowed the rest of a file (Kotlin block comments NEST, so escaping */ alone is not enough), and a default against a named enum contract was emitted as its wire string rather than the enum member. Both are fixed in 0.1.1, and the floor this repo pins has moved well past it since. The C# and Swift SDKs follow the same rule: CI compiles each in its own job (dotnet build -warnaserror, swift build -Xswiftc -warnings-as-errors), and output that fails there goes upstream too.

The two hand-maintained edges

Codegen does not wire itself up. After adding a new .ck operation file:

• Register the router in routes.setup.ts. It is a hand-written import list; a generated router that is not in it is dead code.
• Make sure every service named in options { services: { ... } } exists and is registered in its module's DI container. The generated router calls ctx.container.get(SomeService) and then the method named in service:, so the method signature has to match the operation's params, query and body, in that order.

Auth: four distinct spellings

The security block maps to requirePolicy in the generated router, and the forms are not interchangeable:

Omitting the block is the trap. It reads like "no security" and is the opposite: a bare requirePolicy() gates on a session plus the MFA policy. That is exactly how /auth/login/link/redirect ended up 401-ing every magic-link click, and nothing in the toolchain warns about it. Always write the block, at some level of the cascade.

The cascade

security is legal in three places, and resolveSecurity in @contractkit/core resolves operation → route → file, nearest wins:

• inside the file-level options { } block, as the floor for every operation in the file
• on a route, as the floor for its verbs
• on a verb

Most files in this repo declare the floor once in options and override only where an operation genuinely differs. This means reading a single verb no longer tells you its security — check the options block too. Every floor carries a comment saying what it is and which operations override it.

Since core 0.26 there is a safe home for those comments: inside the security { } block, or on the line(s) directly above a security: key in a verb body. Both round-trip through the formatter and neither reaches generated documentation. That is the place to write the rationale.

The one position that still leaks is a comment run sitting directly above an operation with no blank line between: it becomes that route's description and surfaces on any verb that has none of its own. Leave a blank line and it is a standalone divider instead, kept verbatim and generated nowhere.

Choosing a policy

Only two application policies are registered: platform.view and platform.manage (apps/api/src/modules/policy/policy.mappings.ts). The convention, set by playout.ck and now followed by catalog, playlists and plugins:

• reads → platform.view, which both the listener and admin roles grant
• writes / operator actions → platform.manage, which only admin grants
• policy: none only where a role gate would be wrong. /auth/factors/* is the real case: you cannot require a role or MFA to enroll a first factor.

Prefer the strict end as a file floor where a file is mostly writes, as plugins.ck does. A route added without a block then inherits the tighter gate and gets reported as over-gated, rather than silently landing on the looser one.

Two live constraints:

• platform.edit exists in core.perm but is not in ServerPolicyMappings. Naming it in a .ck compiles clean and fails at runtime. Policy names are not checked by the contract compiler.
• The object-scoped plugin.* permissions (configure, enable, oauth) cannot be named in a contract. requirePolicy asserts with { session } only, so a policy has no object id to scope on. Using them needs a policy class first.

Syntax essentials

Full language reference: https://github.com/MaroonedSoftware/contractkit#dsl-language-reference. Read it before reaching for a construct that no file in this repo already uses. The .ck files in apps/api/data/contracts/ are the working examples; catalog/ is the most representative pair.

Cheat-sheet in reference.md.

Responses: several statuses, several mimes

Since plugin-typescript@0.31 / prettier-plugin@0.14, a status may declare more than one mime and an operation more than one status. Do not carry over the old workaround of declaring one lying mime and letting the client sniff.

• Several mimes on a status → the service returns a contentType alongside the body and the router sets ctx.type from it. render.ck's /segments/{id}/audio and art.ck's /art/{id} are the worked examples; both used to announce one type for four formats.
• Several statuses → the service returns a union discriminated on status, and the SDK returns a matching union rather than throwing.
• Which statuses the service must produce is derived from the declaration: a status is emitted if it has a block, or is 2xx. So 304: (bare) means "documented, something else produces it" — which is what both binary routes want, because the conditional-GET middleware produces it. 304: {} would mean the service returns it. 404(documented): { … } forces a block-carrying status back onto the throw path.
• No contract here declares a body on an error status, so the 0.31 behaviour change (error bodies now returned rather than thrown) does not apply to this repo. Check before adding one.