Docs

Contract-tested examples

How ATM keeps docs examples, local helpers, and lexicon contracts from drifting apart.

Compatible with the closed-beta ATM app APIs and versioned ATM event headers. Check atm-api-version on every webhook or XRPC receiver event.

What is checked

The docs should describe the contracts the runtime actually serves. ATM now generates the contract reference from local lexicons and checks that public ATM, attested.network, and Tickets NSIDs are represented in docs output.

Generated reference reads app/lexicons.
Docs check verifies all public contract NSIDs are present.
Example app names core checkout, webhook, ticket, and check-in flows.
Build fails if docs TSX stops compiling.

Local commands

shell

cd app
npm run docs:generate-reference
npm run docs:check
npm run typecheck
npm run build

Example coverage

Hosted checkout	Private envelope, strict initiate call, status polling, and redirect handling.
Webhooks	Raw-body signature verification, delivery id dedupe, redrive-safe fulfillment.
XRPC receiver	Service-auth receiver shape for AT Protocol-native apps.
Tickets	Availability, paid holds, free claims, issued tickets, verify, and check-in.

CI direction

The next CI hardening step is turning the example app snippets into importable fixtures so contract tests execute the same request builders shown in docs. Until then, the docs check keeps the generated reference and static pages honest.

Adding examples

Add the runnable helper under examples/atm-node-app or a future public example repo.
Add the matching docs snippet on the Examples or Tutorials page.
Include the expected auth type and common error codes.
Add the route NSID to generated reference if it is lexicon-backed.
Run docs:check before asking developers to copy the snippet.