Declare rejection messages on the schemas and deprecate requiredKey

[ernysans]

Summary

requiredKey existed solely to work around a type-inference collapse caused by strictNullChecks being off. That flag is now on, the collapse is gone, and both call sites are migrated.

memberOf was not built — checking main first showed #11 already merged matchMember/requireMember, so building it would have been duplication. This is the other half of that follow-up.

The wrapper is genuinely obsolete — measured

Probed by asserting an empty object against a schema with a required union key:

	{} accepted?
old setting (strictNullChecks: false)	yes — 0 errors, key wrongly inferred optional
now, with wrapper	no — TS2739
now, without wrapper	no — TS2739

Negative control: a genuinely optional key produces 0 errors, so the probe isn't always-failing.

(My first attempt at this probe used as never, which suppresses the exact check being tested and returned a meaningless 0. Redone.)

But deleting it would have been a regression — this is the point of the PR

The wrapper also carried the rejection message. Removing it and stopping there:

case	with wrapper	bare removal
Block, bad value	Expected a string, number, object or array block value	Invalid input
Block, missing value	same descriptive message	Invalid input
Idempotency, bad body	Expected a response body string or null	expected string, received number

Zod reports a failed union as Invalid input because it cannot know which member the caller intended. And expected string is true of the inner schema but false of the field, which accepts null — it sends a caller looking for the wrong fix.

That's the "cleanup" trap: the obvious follow-up (delete the now-obsolete helper) passes every gate while quietly degrading what a caller sees.

The fix keeps both properties

Zod accepts the message on the schema itself:

z.union([...], {error: 'Expected a string, number, object or array block value'})
z.string({error: 'Expected a response body string or null'}).nullable()

Identical messages, key still inferred required, and the z.custom indirection is gone.

Message quality is now tested

Three tests assert the exact strings, because this is precisely what a future cleanup discards silently. Each was mutation-tested by removing the error parameter it guards:

• drop the union's error → 2 red (should name the accepted shapes …)
• drop the nullable's error → 1 red (should name null as accepted …)
• reverted → 922 passing

requiredKey is deprecated, not removed

It is a published export, and the inventory test asserting the public surface still lists it. Removing it would be a breaking change for any consumer that imported it. It is marked @deprecated naming the replacement, with the reasoning inline so the next reader doesn't re-derive it.

Consumer impact: none

parse, safeParse and Interface signatures are unchanged across all three affected files.

The Schema objects' own declared types change from ZodCustom<…> to ZodUnion<…> / ZodNullable<…> — which is what those schemas now are. The inferred output is identical, confirmed by compiling a real consumer against the built package under strict:

consumer compiles           errors = 0     (string | number | Record | unknown[] all accepted; body null accepted)
negative control (boolean)  TS2322: Type 'boolean' is not assignable to
                            type 'string | number | Record<string, unknown> | unknown[]'

The control both proves the probe works and shows the inferred union is unchanged.

(EventData.d.ts also shifts, since it embeds the block schema. Same character.)

Verification

npm run build       0        lib/ drift    0 files
npm test            0        922 passed, 18 files
npm run typecheck   0
npm run lint        0
private markers     0

Every .d.ts and .js in lib/ was diffed against main with comments stripped, and the comparison was itself controlled by injecting a declaration and confirming detection. No attribution trailers; single identity for author and committer.