Add userId and sessionId to TokenRefreshError

[nicknisi]

Summary

• Add userId and sessionId properties to TokenRefreshError for better debugging context when token refresh fails
• Export error classes (AuthKitError, SessionEncryptionError, TokenValidationError, TokenRefreshError) from package

When a token refresh fails (e.g., due to rate limiting), the error now includes the affected user and session:

TokenRefreshError: Failed to refresh tokens {
  userId: 'user_abc123',
  sessionId: 'sess_xyz789',
  cause: RateLimitExceededException...
}

This is backward compatible - no changes required by consuming packages.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR enhances TokenRefreshError with userId and sessionId properties to provide better debugging context when token refresh operations fail (e.g., due to rate limiting). The error classes are now also exported from the package for use by consuming libraries.

• Added userId and sessionId readonly properties to TokenRefreshError with an optional context parameter
• Updated refreshTokens method signature to accept context, passed through from validateAndRefresh
• Session ID is extracted from the JWT claims (sid field) even on expired tokens for error context
• Exported all error classes (AuthKitError, SessionEncryptionError, TokenValidationError, TokenRefreshError) from the package entry point
• Added comprehensive test coverage for all new functionality
• Fully backward compatible - no breaking changes for consumers

Confidence Score: 5/5

• This PR is safe to merge - clean, well-tested enhancement with no breaking changes
• The changes are minimal, well-tested, and backward compatible. The implementation correctly adds optional debugging context without affecting the core error handling flow. No sensitive data is exposed or logged inappropriately.
• No files require special attention

Important Files Changed

File Analysis

Filename	Score	Overview
src/core/errors.ts	5/5	Added userId and sessionId readonly properties to TokenRefreshError with proper typing and optional context parameter
src/core/AuthKitCore.ts	5/5	Updated refreshTokens to accept context parameter and validateAndRefresh to extract and pass userId/sessionId for error debugging
src/core/errors.spec.ts	5/5	Comprehensive tests added for new TokenRefreshError context properties covering all scenarios
src/index.ts	5/5	Exported error classes (AuthKitError, SessionEncryptionError, TokenValidationError, TokenRefreshError) from package

Sequence Diagram

sequenceDiagram
    participant Client
    participant AuthKitCore
    participant WorkOS API
    participant TokenRefreshError

    Client->>AuthKitCore: validateAndRefresh(session)
    AuthKitCore->>AuthKitCore: Extract sessionId from JWT claims
    AuthKitCore->>AuthKitCore: refreshTokens(refreshToken, orgId, {userId, sessionId})
    AuthKitCore->>WorkOS API: authenticateWithRefreshToken()
    
    alt Refresh Succeeds
        WorkOS API-->>AuthKitCore: New tokens + user
        AuthKitCore-->>Client: Refreshed session
    else Refresh Fails (e.g., rate limit)
        WorkOS API-->>AuthKitCore: Error
        AuthKitCore->>TokenRefreshError: new TokenRefreshError(msg, cause, {userId, sessionId})
        TokenRefreshError-->>AuthKitCore: Error with context
        AuthKitCore-->>Client: TokenRefreshError (includes userId, sessionId for debugging)
    end

Loading

[greptile-apps]

_{4 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[cmatheson]

thank you!