fix(errors): type server/auth errors and restore type compatibility

[workos-sdk-automation]

What's changed

• Add typed server error payload support via WorkOSErrorData on GenericServerException
• Add AuthenticationException plus auth error type guard for known authentication error codes
• Throw on unrecognized webhook event types in event deserialization
• Make WorkOSResponseError structurally compatible with WorkOSErrorData (index signature) to preserve strict TypeScript compatibility

Issues

Fixes #959
Fixes #864
Refs #1204
Refs #1310

[greptile-apps]

Greptile Summary

This PR adds typed error support for server and authentication errors: a new AuthenticationException (plus isAuthenticationErrorData type guard), a WorkOSErrorData interface on GenericServerException, and a forward-compatible default case in deserializeEvent that returns unknown events as raw data instead of undefined. An index signature is added to WorkOSResponseError to restore structural TypeScript compatibility with WorkOSErrorData.

Confidence Score: 5/5

Safe to merge; all remaining findings are P2 type-safety suggestions that do not affect runtime correctness.

The new AuthenticationException and its type guard are correctly implemented, the WorkOSErrorData/index-signature additions are backward-compatible, and the default case in deserializeEvent improves forward-compatibility over the previous implicit undefined return. The only open finding is a P2 concern that UnknownEvent is not added to the Event union, making the as Event cast in the serializer give callers an inaccurate static type, but this does not cause any runtime failure.

src/common/serializers/event.serializer.ts and src/common/interfaces/event.interface.ts — the UnknownEvent / Event union mismatch.

Important Files Changed

Filename	Overview
src/common/exceptions/authentication.exception.ts	New AuthenticationException class and isAuthenticationErrorData guard; guard checks only the error code (not presence of pending_authentication_token), which is correct and complete.
src/common/exceptions/generic-server.exception.ts	Adds WorkOSErrorData interface and exposes code on the exception; clean and backward-compatible change.
src/common/serializers/event.serializer.ts	Adds a default case that returns raw unknown events as UnknownEvent-shaped objects; the as Event cast is unsafe because UnknownEvent is not part of the Event union, giving callers an incorrect type.
src/common/interfaces/event.interface.ts	Defines UnknownEvent interface but does not add it to the Event union type, making the exported type effectively unused for narrowing.
src/workos.ts	Wires isAuthenticationErrorData / AuthenticationException into the default HTTP error handler; placement and ordering relative to OauthException / BadRequestException checks is correct.
src/common/exceptions/index.ts	Re-exports the new AuthenticationException and related types; no issues.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[HTTP Error Response] --> B{status code?}
    B -->|401| C[UnauthorizedException]
    B -->|404| D[NotFoundException]
    B -->|409| E[ConflictException]
    B -->|422| F[UnprocessableEntityException]
    B -->|429| G[RateLimitExceededException]
    B -->|default| H{error or error_description?}
    H -->|yes| I[OauthException]
    H -->|no| J{code && errors?}
    J -->|yes| K[BadRequestException]
    J -->|no| L{isAuthenticationErrorData?}
    L -->|yes - NEW| M[AuthenticationException with pendingAuthenticationToken]
    L -->|no| N[GenericServerException with code + rawData]

    O[Webhook EventResponse] --> P{event type known?}
    P -->|yes| Q[Deserialize to typed Event]
    P -->|default - NEW| R[Return UnknownEvent shape as Event cast]

Loading

_{Reviews (2): Last reviewed commit: "fix: address review comments on error ha..." | Re-trigger Greptile}