Type-check main.d.ts in CI

[jstayton]

main.d.ts is the published types entry, but nothing verified it — npm test only runs node --test over the JS, so the declarations could drift from main.js without anything failing. AGENTS.md asks for the two to be kept in sync, which until now was a manual promise.

src/main.test-d.ts exercises the declared API at compile time and never runs; tsc failing to compile it is the failure. Each option's omission and each option's type get their own @ts-expect-error, one directive per property, so a single option drifting can't hide behind another. Those directives are load-bearing in both directions — if a declaration ever gets looser, the line stops erroring and tsc fails on the unused directive. That's what catches a widening to unknown or any.

To check the gate actually bites rather than just passing green, I mutated main.d.ts 18 ways: each of the four required options made optional, widened to unknown, and widened to any; leewayMinutes retyped and made required; the return type widened to boolean; an index signature admitting arbitrary keys; the error name widened off its literal; and the error class dropped from the namespace. All 18 fail the check.

An earlier revision of this PR claimed a six-mutation check passed clean. That was true but misleading — those six happened to be mutations the file already covered. Review correctly caught that url, secret, and header could turn optional, and that all four required options could widen, with zero diagnostics. Now fixed, and the mutation matrix covers the declared surface rather than a sample of it.

typescript is the only new dependency and it's dev-only, so the package stays zero-dependency at runtime. The type test is excluded from the tarball — npm pack --dry-run still lists just package.json, error.js, main.d.ts, and main.js.

On the filename: .test-d.ts rather than main.d.test.ts or main.test.d.ts, because TypeScript treats any .d.<something>.ts as a declaration file, which makes the helper body and the @ts-expect-error assertions illegal in an ambient context.

🤖 Generated with Claude Code