Kumiko 0.412: webhook contracts and generated HTTP API docs
Apps declare which events leave the system as webhooks, and personal access token scopes release them. kumiko api-docs writes the HTTP API reference and an OpenAPI 3.1 file from the same registry, and fails in CI when the docs fall behind the code.
A Kumiko app could already open its HTTP API to scripts and monitoring through personal access tokens. Framework 0.412 adds public contracts for the events an app sends out as webhooks, and writes the documentation for the API and the events from the code.
Webhook events now have public contracts. r.defineWebhookEvent declares one with a name, a description, a payload schema and a version, separate from the internal r.defineEvent, so an internal event cannot leave the app by accident. An entity can release its created, updated and deleted events with webhookEvents: true. Their payload is derived from the entity and leaves out personal fields, encrypted and write-only fields and the fields a feature excludes. A token scope lists the events it releases. If a scope names an event without a public contract, the app does not start.
The new command kumiko api-docs builds the developer documentation from the registry and the token scopes. It writes an openapi.json with only the handlers some scope reaches, an overview, a page about tokens, one reference page per scope and, once a scope lists events, an events.md with every webhook payload. The pages come in English, German, Spanish, French and Italian. Request, response and webhook examples are recorded in integration tests against the running app, so the examples in the docs are real responses.
With --check the command writes nothing and exits with 1 when a handler in a scope has no description, when a screen triggers a write that no scope covers, or when the committed docs differ from what the code produces. As a CI step, that keeps the published API docs in line with the release.
Delivery itself, meaning signing, retries and timeouts, stays in the app. The framework defines what an event may contain and documents it.