feat: add TokenRefreshError with userId and sessionId for debugging

Add custom error classes matching authkit-session pattern:
- AuthKitError base class with optional data field
- TokenRefreshError with userId/sessionId context for debugging
- getSessionErrorContext helper to extract context from sessions

Update session refresh failure to include user/session context.

Author: nicknisi

src/errors.spec.ts

@@ -0,0 +1,109 @@
+import { AuthKitError, TokenRefreshError, getSessionErrorContext } from './errors.js';
+import type { Session } from './interfaces.js';
+import type { User } from '@workos-inc/node';
+
+describe('AuthKitError', () => {
+  it('creates error with message', () => {
+    const error = new AuthKitError('Test error');
+
+    expect(error.message).toBe('Test error');
+    expect(error.name).toBe('AuthKitError');
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  it('creates error with cause and data', () => {
+    const originalError = new Error('Original error');
+    const data = { userId: '123' };
+    const error = new AuthKitError('Test error', originalError, data);
+
+    expect(error.cause).toBe(originalError);
+    expect(error.data).toEqual(data);
+  });
+});
+
+describe('TokenRefreshError', () => {
+  it('creates error with correct name and inheritance', () => {
+    const error = new TokenRefreshError('Refresh failed');
+
+    expect(error.name).toBe('TokenRefreshError');
+    expect(error.message).toBe('Refresh failed');
+    expect(error).toBeInstanceOf(AuthKitError);
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  it('creates error with cause and context', () => {
+    const originalError = new Error('Network error');
+    const error = new TokenRefreshError('Refresh failed', originalError, {
+      userId: 'user_123',
+      sessionId: 'session_456',
+    });
+
+    expect(error.cause).toBe(originalError);
+    expect(error.userId).toBe('user_123');
+    expect(error.sessionId).toBe('session_456');
+  });
+
+  it('has undefined properties when no context provided', () => {
+    const error = new TokenRefreshError('Refresh failed');
+
+    expect(error.userId).toBeUndefined();
+    expect(error.sessionId).toBeUndefined();
+  });
+});
+
+describe('getSessionErrorContext', () => {
+  function createTestJwt(payload: Record<string, unknown>): string {
+    const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+    const payloadStr = btoa(JSON.stringify(payload));
+    return `${header}.${payloadStr}.test-signature`;
+  }
+
+  it('returns empty object for missing session', () => {
+    expect(getSessionErrorContext(null)).toEqual({});
+    expect(getSessionErrorContext(undefined)).toEqual({});
+  });
+
+  it('extracts userId and sessionId from session', () => {
+    const session: Session = {
+      accessToken: createTestJwt({ sid: 'session_123' }),
+      refreshToken: 'refresh_token',
+      user: {
+        id: 'user_456',
+        email: 'test@example.com',
+        emailVerified: true,
+        profilePictureUrl: null,
+        firstName: null,
+        lastName: null,
+        createdAt: '2024-01-01',
+        updatedAt: '2024-01-01',
+        object: 'user',
+      } as User,
+    };
+
+    const context = getSessionErrorContext(session);
+    expect(context.userId).toBe('user_456');
+    expect(context.sessionId).toBe('session_123');
+  });
+
+  it('handles invalid JWT gracefully', () => {
+    const session: Session = {
+      accessToken: 'invalid-jwt',
+      refreshToken: 'refresh_token',
+      user: {
+        id: 'user_123',
+        email: 'test@example.com',
+        emailVerified: true,
+        profilePictureUrl: null,
+        firstName: null,
+        lastName: null,
+        createdAt: '2024-01-01',
+        updatedAt: '2024-01-01',
+        object: 'user',
+      } as User,
+    };
+
+    const context = getSessionErrorContext(session);
+    expect(context.userId).toBe('user_123');
+    expect(context.sessionId).toBeUndefined();
+  });
+});

src/errors.ts

@@ -0,0 +1,55 @@
+import type { Session } from './interfaces.js';
+import { decodeJwt } from './jwt.js';
+
+export class AuthKitError extends Error {
+  data?: Record<string, unknown>;
+
+  constructor(message: string, cause?: unknown, data?: Record<string, unknown>) {
+    super(message);
+    this.name = 'AuthKitError';
+    this.cause = cause;
+    this.data = data;
+  }
+}
+
+export interface TokenRefreshErrorContext {
+  userId?: string;
+  sessionId?: string;
+}
+
+export class TokenRefreshError extends AuthKitError {
+  readonly userId?: string;
+  readonly sessionId?: string;
+
+  constructor(message: string, cause?: unknown, context?: TokenRefreshErrorContext) {
+    super(message, cause);
+    this.name = 'TokenRefreshError';
+    this.userId = context?.userId;
+    this.sessionId = context?.sessionId;
+  }
+}
+
+export function getSessionErrorContext(session?: Session | null): TokenRefreshErrorContext {
+  if (!session) {
+    return {};
+  }
+
+  const context: TokenRefreshErrorContext = {};
+
+  if (session.user?.id) {
+    context.userId = session.user.id;
+  }
+
+  if (session.accessToken) {
+    try {
+      const { payload } = decodeJwt(session.accessToken);
+      if (payload.sid) {
+        context.sessionId = payload.sid;
+      }
+    } catch {
+      // JWT decode can fail for malformed tokens
+    }
+  }
+
+  return context;
+}

src/index.ts

@@ -1,5 +1,6 @@
 import { getSignInUrl, getSignUpUrl, signOut, switchToOrganization } from './auth.js';
 import { handleAuth } from './authkit-callback-route.js';
+import { AuthKitError, TokenRefreshError } from './errors.js';
 import { authkit, authkitMiddleware } from './middleware.js';
 import { getTokenClaims, refreshSession, saveSession, withAuth } from './session.js';
 import { validateApiKey } from './validate-api-key.js';
@@ -8,6 +9,8 @@ import { getWorkOS } from './workos.js';
 export * from './interfaces.js';
 
 export {
+  AuthKitError,
+  TokenRefreshError,
   authkit,
   authkitMiddleware,
   getSignInUrl,

src/session.ts

@@ -7,6 +7,7 @@ import { redirect } from 'next/navigation';
 import { NextRequest, NextResponse } from 'next/server';
 import { getCookieOptions, getJwtCookie } from './cookie.js';
 import { WORKOS_CLIENT_ID, WORKOS_COOKIE_NAME, WORKOS_COOKIE_PASSWORD, WORKOS_REDIRECT_URI } from './env-variables.js';
+import { TokenRefreshError, getSessionErrorContext } from './errors.js';
 import { getAuthorizationUrl } from './get-authorization-url.js';
 import {
   AccessToken,
@@ -406,9 +407,11 @@ async function refreshSession({
       organizationId: nextOrganizationId ?? organizationIdFromAccessToken,
     });
   } catch (error) {
-    throw new Error(`Failed to refresh session: ${error instanceof Error ? error.message : String(error)}`, {
-      cause: error,
-    });
+    throw new TokenRefreshError(
+      `Failed to refresh session: ${error instanceof Error ? error.message : String(error)}`,
+      error,
+      getSessionErrorContext(session),
+    );
   }
 
   const headersList = await headers();