[gjtorikian]

Description

UnknownEvent was declared in event.interface.ts but never added to the Event union, and deserializeEvent's default branch cast its result to Event. A consumer writing an exhaustive switch over event.event with an assertNever default therefore compiled clean and threw at runtime the first time the API shipped an event type the SDK did not know (#864, #1360, #1362, #1453, #1685 are all this failure). This was the second half of #1572, which was closed without it landing.

This PR:

• Adds UnknownEvent to Event and a parallel UnknownEventResponse to EventResponse.
• Exposes the known members as KnownEvent / KnownEventResponse; EventName is now KnownEvent['event'], so listEvents filters and webhook endpoint events keep their literal typing.
• Moves the deserializer's switch into deserializeKnownEvent, typed against KnownEvent, with deserializeEvent passing through anything it returns undefined for. The previous as Event cast is gone.
• Adds a runtime test for the pass-through and a type-level test (enforced by tsc) that a known case keeps its narrowed payload while default can no longer be assertNever'd.

Why UnknownEvent.data is never

TypeScript keeps a union member whose discriminant is string in every narrowed branch: in case 'user.created':, event is UserCreatedEvent | UnknownEvent. With the previously declared data: Record<string, unknown>, event.data would become User | Record<string, unknown> in every branch and event.data.email would be unknown, breaking essentially every consumer (and ~80 cases in the SDK's own serializer). never is absorbed by those unions, so known branches are unchanged. The payload is still passed through unchanged at runtime (snake_case keys, no deserialization) and, since never is assignable to anything, can be read by annotating it:

default: {
  const payload: Record<string, unknown> = event.data;
}

This is the only typing that preserves narrowed reads; there is no TypeScript type for "string except these literals".

Breaking changes

• Event['event'] is now string rather than the literal union. Code that used it as an EventName (for example indexing Record<EventName, Handler> with event.event) must narrow first or use EventName / KnownEvent['event'].
• A default branch of a switch over event.event is no longer narrowed, so assertNever(event) there fails to compile. That is the intended signal; handle the unknown case instead.
• Object literals typed as Event whose event is a union of literals (for example built inside a grouped case clause) are also matched against UnknownEvent by TypeScript's discriminated-union assignability and need an explicit known event type. The SDK's own serializer was adjusted for this; consumers that only read events are unaffected.

Note: the first half of #1572 (plumbing an AbortSignal through RequestOptions) did not land either; RequestOptions still has no signal. That is a separate change.

Fixes #1696

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

[greptile-apps]

Confidence Score: 4/5

[Medium impact] The change reaches event-list and webhook consumers of the shared event path.

The PR appears safe to merge, with a non-blocking improvement needed in the known-payload type test.

Findings

1.  Payload type check misses widening ▶

Fix with agent prompt

### Issue 1
src/events/events.spec.ts:1760-1761
The known-payload check does not prove that `email` remains a `string`: template interpolation also accepts `unknown`. If `event.data.email` becomes `unknown`, this assertion still compiles, leaving callers' typed reads unprotected. Assign it to a `string` variable, or call a string method, before returning it so the test catches the widening it promises to prevent.

```suggestion
          // The known payload type is intact: `data` is `User`, not a union.
          return `user:${event.data.email.toLowerCase()}`;
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds unknown event members to Event and EventResponse, while exposing known members through KnownEvent and KnownEventResponse.

• Callers can now see when an event name is unknown.

Acknowledged by gjtorikian: widening Event['event'], rejecting exhaustive defaults, requiring explicit known types for grouped object literals, and using data: never are intentional.

_{Reviews (1) · Last reviewed commit: "feat(events)!: Add UnknownEvent to the E..." · Reviewed by Greptile}

[greptile-apps]

Payload type check misses widening

The known-payload check does not prove that email remains a string: template interpolation also accepts unknown. If event.data.email becomes unknown, this assertion still compiles, leaving callers' typed reads unprotected. Assign it to a string variable, or call a string method, before returning it so the test catches the widening it promises to prevent.

Suggested change

	// The known payload type is intact: `data` is `User`, not a union.
	return `user:${event.data.email}`;
	// The known payload type is intact: `data` is `User`, not a union.
	return `user:${event.data.email.toLowerCase()}`;

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/events/events.spec.ts
Line: 1760-1761

Comment:
**Payload type check misses widening**

The known-payload check does not prove that `email` remains a `string`: template interpolation also accepts `unknown`. If `event.data.email` becomes `unknown`, this assertion still compiles, leaving callers' typed reads unprotected. Assign it to a `string` variable, or call a string method, before returning it so the test catches the widening it promises to prevent.

```suggestion
          // The known payload type is intact: `data` is `User`, not a union.
          return `user:${event.data.email.toLowerCase()}`;
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.