Add generated TypeScript HEY SDK with safely gated npm releases
Give Node and TypeScript integrators a typed HEY client without maintaining their own HTTP and OAuth layer. This adds the complete 131-operation modeled API alongside Go and Rust; merging remains publication-safe because npm activation requires a separate reviewed change.
Review readiness: ✅ Yes
Risk: 🔴 High — the client handles credentials and private mail, generated contracts span three SDKs, and the release path introduces a future npm publishing authority.
Decision: Accept nullable recording categories in the generated Go API and coordinate the CLI adaptation when it upgrades; live npm activation remains deferred.
✅ Change — TypeScript gains the modeled HEY API while npm publication stays inactive
Before
Node integrator
└── HEY SDKs available in Go and Rust
└── ❌ Maintain a separate HTTP, OAuth and model client
After
Node ESM integrator
└── Typed @37signals/hey package
├── ✅ 131 generated operations and types ← CHANGED
├── OAuth, account scoping, pagination and safe retries
├── Lossless integer and bounded response handling
└── npm publication disabled pending provisioning
Smithy and OpenAPI drive generated methods, types, routes, retry policy and response representation. The runtime supports static and refreshable credentials, PKCE, acting senders, same-origin pagination, opt-in ETag revalidation, cancellation, typed JSON/HTML responses and model-governed replay.
✅ Evidence — the repository gate, supported Node matrix and package artifact pass
- ✅
typescript/VALIDATION.mdmaps acceptance criteria to repeatable checks. - ✅ Local
make check: TypeScript 518/518 tests; Go and Rust conformance 195/195 each; TypeScript conformance 191/191 applicable with four declared convenience-layer exclusions. - ✅ Node 22.12, 24 and 26 passed generation, build, tests, typechecks, version synchronization and isolated package smoke in the current-head Test run.
- ✅ Current-head Security, CodeQL and Code Quality runs pass; npm audit reports no vulnerabilities.
- ✅ A local HEY CLI build against this Go SDK passed its full check. Nineteen read-only operations across mail, calendars, recordings and both linked accounts passed against production; the critical time-track read covered both string and null categories. One permitted message to the signed-in user's own address was sent, found by exact subject and read back successfully.
- ➖ No visual artifact applies to this non-visual SDK and release-workflow feature.
⚠️ Scope — Node ESM and the shared modeled contract, with one disclosed Go source change
Included: Node 22.12+, 24 and 26; native ESM and Fetch/Web Crypto; generated operations/types/guards; OAuth; transport safety; conformance; npm packaging; gated release automation; shared nullable/discriminator/pagination metadata; and the rustls security lock update.
The shared recording model accepts direct and namespaced discriminator spellings. Rust helper predicates recognize both without changing signatures. Generated Go now exposes Recording.Category as *string, representing an uncategorized time track as nil instead of collapsing HEY's explicit null into an empty string. Omitted and null values both decode as nil; Go consumers adapt when they upgrade. Handwritten Go and Rust service signatures remain unchanged.
Deferred: CommonJS, browsers, Deno/Bun/React Native, persistent credential storage, streaming downloads and handwritten parsed/form convenience parity.
✅ Delivery — merge publishes nothing and disabled tags preserve Go/Rust releases
TYPESCRIPT_RELEASE.md defines provisioning, activation and rollback. .github/typescript-publish-enabled is false in this commit:
merge to main
└── no package publication
next v* tag while false
├── Go release proceeds
├── Rust release proceeds
├── TypeScript tests and packs without npm credentials
└── GitHub release waits only for Go and Rust
A later reviewed commit must provision the package and protected release-npm environment, replace the pending notice and enable the versioned flag. Invalid or unreadable activation state fails closed. No migrations, backfills, data writers, scheduled tasks or application credentials are introduced.
⚠️ Review decision — focus on credentials/replay and the shared Go model change
- Confirm that OAuth, credential refresh, cancellation, bounded error handling and model-governed retries preserve the intended safety boundary.
- Confirm the generated Go nullability change and coordinated CLI upgrade are acceptable alongside the inactive npm release boundary.
Live npm ownership, OIDC/provenance minting and installation from the public registry remain intentionally unverified until provisioning. No durable external issue or design exists; this PR body, the validation record and release runbook are the feature specification.
✅ Review path — runtime and shared contract first; every changed group is accounted for
- TypeScript runtime and tests — credentials, errors, retries, representations, security and public behavior.
- Smithy model, traits and Rust generator — nullable categories, discriminator aliases and pagination metadata; generated Go/Rust output and tests follow this group.
- Release workflow, activation state and publisher — immutable gating, artifact checks, version scripts and Go/Rust orchestration; related CI and Dependabot changes complete this group.
- TypeScript conformance runner — fixture inventory, fail-closed contract and explicit applicability boundary.
- TypeScript guide, repository guide, contributor/release documentation, pagination ADR and the two Rust lockfiles — supported environments, maintenance workflow and the incidental security update.
Origin: No external ticket or design exists; the PR description and checked-in validation/release documents are authoritative.