feat: add raw_json to the verified event and reject unreadable payloads

[razor-x]

The two rules

1. Runtime does not explode on values the SDK does not recognize. This already held, because the package performs no runtime conversion — verify returns svix's parsed object. An event type this SDK predates comes back intact, with the caveat that it is typed as one of the 108 members it does know. That type-level gap is not addressed here; widening the union is inherently breaking and needs its own decision.

2. The webhook event carries the payload it was parsed from.

const event = webhook.verify(payload, headers)
JSON.parse(event.raw_json())['a_field_this_version_predates']

The generated SeamEvent types cover only the fields they were generated for, so a field Seam adds to an existing event is otherwise unreachable, and an event type this version predates is mistyped as one it knows. raw_json() is the escape hatch for both.

This is the true original string, not a re-serialization, since verify receives it.

It is attached with Object.defineProperty and enumerable: false. A spread would make it enumerable, and JSON.stringify(event) would then embed a second, escaped copy of the payload inside the payload — doubling its size and looking broken to anyone logging or persisting events that way. A test covers this.

Signed but unreadable payloads

verify blind-cast whatever svix returned:

return this.#webhook.verify(payload, normalizedHeaders) as SeamEvent

So a correctly signed body that is not an event reached the caller mistyped — an object with no event_type, a JSON array, and a bare null all came back as a SeamEvent, and a body that is not JSON leaked svix's internal SyntaxError.

These now raise SeamInvalidWebhookPayloadError, kept distinct from SeamWebhookVerificationError because the two call for opposite responses. A verification failure means the sender may not be Seam, so the right answer is an error status that makes it retry. An invalid payload means the sender is Seam and the body will never become readable, so retrying only repeats the failure. This matches the Python and PHP SDKs.

An unrecognized event_type is explicitly not in this category — it passes through, as rule 1 requires.

Tests

The package had one test, for the constructor; verify was never exercised at all. It now has 15 covering the real HMAC signing path — known and unrecognized events, bad signature, stale timestamp, the unreadable-payload matrix, and raw_json round-tripping.

100% coverage. tsc and lint clean.

🤖 Generated with Claude Code

https://claude.ai/code/session_01M2kJ4nGaM8imZCVMEKjmXA