docs(events): Shadow Update fields nullable + promote auto-gen schema files#2
Open
spk-ai wants to merge 2 commits into
Open
docs(events): Shadow Update fields nullable + promote auto-gen schema files#2spk-ai wants to merge 2 commits into
spk-ai wants to merge 2 commits into
Conversation
… files
Two related fixes after the recent b2c-api work:
1. **events-catalog.mdx — Shadow Update nullability.** Real AWS-delivered
`spk.iot.shadow@Shadow Update` events have `null` in fields the doc
previously typed as `string`. The b2c-api Zod schema was relaxed today
to match reality (PR #129 — SPK-API-V). Partner-facing types updated:
- `desiredState`: string → string\|null (null when no desired state set;
observed in ~50% of real events)
- `reportedState`: string → string\|null (null for never-reported)
- `metadata`: string → string\|null
- `version`: number → number\|null (null on first event)
- `partnerId`: already string\|null (no change)
Added explicit guidance: only `thingName` and `deltaState` are
guaranteed non-null; plan for null on every other field.
2. **events-webhooks.mdx — Schema & Code Generation section rewritten.**
The old section pointed at `eventbridge-schemas.yaml` with a "lags the
catalog" caveat. The repo now has TWO auto-generated JSON Schema files
regenerated on every b2c-api deploy:
- `event-schemas.json` ← `GET /schemas/events.json`
- `command-schemas.json` ← `GET /schemas/commands.json`
Both carry a `version` field (worker git SHA) for staleness detection.
Added paste-ready recipes for Pydantic v2, TypeScript, and any-language
via quicktype. Also called out that the Shadow Update envelope lives in
the catalog page (separate shape from spk.api events) and that the
API Reference tab covers the full OpenAPI surface.
No content change to event-type lists or other partner-facing docs — those
were refreshed last week and remain accurate.
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
CI publishDocs step keeps getting cancelled by sibling test() failure
(3dEye 429 rate-limit in camera-role acceptance tests). The deployed
b2c-api worker (version 32d654a1, nonprod) has the correct OpenAPI
including /cameras/my and /cameras/{id}/stream and updated CreateCameraRole
schema — but docs repo was 5 days stale.
Synced manually with the same jq sanitization + yq YAML conversion
publishDocs does. Will roll back to CI-driven once acceptance flakiness
is sorted.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two partner-facing docs catch up to recent b2c-api work:
events-catalog.mdxShadow Update nullability — real AWS payloads havenullindesiredState/reportedState/metadata/versionfields the doc typed asstring/number. Partners writing typed handlers would trip on this (the b2c-api Zod schema was relaxed today in PR #129 / SPK-API-V resolved). Updated field types + added explicit "plan for null" guidance.events-webhooks.mdxSchema & Code Generation — replaced the staleeventbridge-schemas.yamlsection with one promoting the auto-regeneratedevent-schemas.json+command-schemas.jsonfiles (already in this repo, refreshed by b2c-api CI on every deploy). Added paste-ready codegen recipes for Pydantic v2, TypeScript, and quicktype (any-language).Out of scope (separate work)
eventbridge-schemas.yamlfile (Mar 25) still references the deprecatedcustomer.eventssource. Not edited here — the new auto-generated files supersede it and the new docs section directs partners away from it.openapi.yamlis regenerated by b2c-api CI; not touched.api.spkey.co/schemas/events.json403 (CNAME cross-user, error 1014) is a CDN/DNS configuration issue, unrelated.Test plan
string\|null(escaped pipe) renders correctly