fix(cms): align points API error format and OpenAPI spec#77
Merged
kasparkallas merged 3 commits intoJul 10, 2026
Conversation
The three timestamp-validation errors on GET /points/events still returned
{ error } after the 2026-01-26 migration to { message } (reported by a
community member). They now return message as the primary field, with a
deprecated error duplicate kept temporarily for backward compatibility.
Also align the OpenAPI spec with actual runtime behavior:
- Document all three accepted POST /points/push request formats via
PushRequestBodySchema instead of only the single-event shape, and
register the batch schemas as components
- Prefer campaignId over the deprecated campaign field in all examples
- Add missing cappedPoints/uncappedPoints to stale response examples
- Broaden ApiError.invalid to unknown[] and document the missing field
returned by signed-balance-batch 404s
- Correct lastEventAt descriptions (processing time, not eventTime)
- Use the address-regex schema for events/push account fields, document
lenient timestamp parsing, machine-readable pagination defaults, and
lowercase-hex API key format
- Note that the push endpoint is for server-side use only
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
Add a Negative Points section to the API overview covering zero-clamped balances, the risk that users skip re-claiming a reduced balance on-chain, and the permissionless claim-on-behalf mitigation. Reference it from the push and signed-balance endpoint descriptions and the points field docs. Also do an editing pass on the embedded documentation: move API Basics above the TypeScript client guide, rename Rate Limits to Request Limits, show signature hashes with their exact encodePacked type encoding, make JSON examples valid JSON, and refresh stale example timestamps. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
kasparkallas
marked this pull request as ready for review
July 9, 2026 18:19
The per-event batch format in the points push OpenAPI spec typed its events as PushEvent, which advertises campaignId/campaign per event. The runtime validator only accepts eventName, account, points and uniqueId per event; campaign is read at the root level only, so the documented per-event campaign fields were silently ignored and would surface as dead fields in generated clients. Add a BatchPerEventItem doc schema matching the runtime shape and use it in BatchWithPerEventRequest. No runtime behavior change. Co-Authored-By: Claude Fable 5 <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.
Fixes the community-reported bug where
GET /points/eventsstill returned{ error }instead of the documented{ message }, and aligns the points OpenAPI spec with actual runtime behavior.The three timestamp-validation 400s on
/points/eventswere missed in the 2026-01-26 migration from{ error }to{ message }— the only remaining deviations in the points API. They now returnmessageas the primary field, with a deprecatederrorduplicate kept temporarily so existing consumers don't break; it can be dropped in a later cleanup.A follow-up audit of the whole points API surface (route handlers vs.
schemas.ts/registry.ts) found several spec/implementation mismatches, fixed here as documentation-only changes:POST /points/pushdocumented only the single-event body shape, while the runtime accepts three formats; the request body now uses the (previously defined but unwired)PushRequestBodySchemaunion, so generated clients accept batch payloadscampaignIdover the deprecatedcampaignfieldcappedPoints/uncappedPointsfieldsApiError.invalidbroadened to cover invalid campaign IDs (not just addresses); themissingfield on signed-balance-batch 404s is now documentedlastEventAtdescriptions corrected to reflect processing-time semantics (informational events excluded)account, lenient timestamp parsing documented, machine-readable pagination defaults, lowercase-hex API key format, server-side-only note on the push endpointDeliberately not changed (to avoid behavior changes): CORS still blocks
X-API-Keycross-origin (guardrail against embedding server keys in browsers), malformed JSON bodies still 500, and lenient integer/timestamp parsing is kept and documented rather than tightened.Verified by fetching the live
/points/openapi.jsonfrom a dev server and programmatically asserting all 20 expected spec changes, plus exercising the three fixed error responses end-to-end (400 + both keys).🤖 Generated with Claude Code