feat: add SessionError with userId and sessionId for debugging

Add custom error classes matching authkit-session pattern:
- AuthKitError base class with optional data field
- SessionError 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,235 @@
+import { AuthKitError, SessionError, 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', () => {
+    const originalError = new Error('Original error');
+    const error = new AuthKitError('Test error', originalError);
+
+    expect(error.cause).toBe(originalError);
+  });
+
+  it('creates error with data', () => {
+    const data = { userId: '123', action: 'login' };
+    const error = new AuthKitError('Test error', undefined, data);
+
+    expect(error.data).toEqual(data);
+  });
+
+  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('SessionError', () => {
+  it('creates error with correct name', () => {
+    const error = new SessionError('Session failed');
+
+    expect(error.name).toBe('SessionError');
+    expect(error.message).toBe('Session failed');
+    expect(error).toBeInstanceOf(AuthKitError);
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  it('creates error with cause', () => {
+    const originalError = new Error('Network error');
+    const error = new SessionError('Session failed', originalError);
+
+    expect(error.cause).toBe(originalError);
+  });
+
+  it('creates error with userId and sessionId', () => {
+    const error = new SessionError('Session failed', undefined, {
+      userId: 'user_123',
+      sessionId: 'session_456',
+    });
+
+    expect(error.userId).toBe('user_123');
+    expect(error.sessionId).toBe('session_456');
+  });
+
+  it('creates error with cause and context', () => {
+    const originalError = new Error('Network error');
+    const error = new SessionError('Session 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('creates error with partial context (userId only)', () => {
+    const error = new SessionError('Session failed', undefined, {
+      userId: 'user_123',
+    });
+
+    expect(error.userId).toBe('user_123');
+    expect(error.sessionId).toBeUndefined();
+  });
+
+  it('creates error with partial context (sessionId only)', () => {
+    const error = new SessionError('Session failed', undefined, {
+      sessionId: 'session_456',
+    });
+
+    expect(error.userId).toBeUndefined();
+    expect(error.sessionId).toBe('session_456');
+  });
+
+  it('has undefined properties when no context provided', () => {
+    const error = new SessionError('Session failed');
+
+    expect(error.userId).toBeUndefined();
+    expect(error.sessionId).toBeUndefined();
+  });
+});
+
+describe('error inheritance', () => {
+  it('maintains proper inheritance chain', () => {
+    const sessionError = new SessionError('test');
+
+    expect(sessionError).toBeInstanceOf(SessionError);
+    expect(sessionError).toBeInstanceOf(AuthKitError);
+    expect(sessionError).toBeInstanceOf(Error);
+  });
+
+  it('can be caught as AuthKitError', () => {
+    expect(() => {
+      throw new SessionError('test');
+    }).toThrow(AuthKitError);
+  });
+});
+
+describe('getSessionErrorContext', () => {
+  // Helper to create a valid JWT for testing
+  function createTestJwt(payload: Record<string, unknown>): string {
+    const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+    const payloadStr = btoa(JSON.stringify(payload));
+    const signature = 'test-signature';
+    return `${header}.${payloadStr}.${signature}`;
+  }
+
+  it('returns empty object for null session', () => {
+    const context = getSessionErrorContext(null);
+    expect(context).toEqual({});
+  });
+
+  it('returns empty object for undefined session', () => {
+    const context = getSessionErrorContext(undefined);
+    expect(context).toEqual({});
+  });
+
+  it('extracts userId from session.user.id', () => {
+    const session: Session = {
+      accessToken: createTestJwt({ sid: 'session_123' }),
+      refreshToken: 'refresh_token',
+      user: {
+        id: 'user_456',
+        email: '[email protected]',
+        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');
+  });
+
+  it('extracts sessionId from JWT sid claim', () => {
+    const session: Session = {
+      accessToken: createTestJwt({ sid: 'session_789' }),
+      refreshToken: 'refresh_token',
+      user: {
+        id: 'user_123',
+        email: '[email protected]',
+        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.sessionId).toBe('session_789');
+  });
+
+  it('extracts both userId and sessionId', () => {
+    const session: Session = {
+      accessToken: createTestJwt({ sid: 'session_abc' }),
+      refreshToken: 'refresh_token',
+      user: {
+        id: 'user_xyz',
+        email: '[email protected]',
+        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_xyz');
+    expect(context.sessionId).toBe('session_abc');
+  });
+
+  it('handles invalid JWT gracefully', () => {
+    const session: Session = {
+      accessToken: 'invalid-jwt',
+      refreshToken: 'refresh_token',
+      user: {
+        id: 'user_123',
+        email: '[email protected]',
+        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();
+  });
+
+  it('handles missing user gracefully', () => {
+    const session = {
+      accessToken: createTestJwt({ sid: 'session_123' }),
+      refreshToken: 'refresh_token',
+      user: undefined,
+    } as unknown as Session;
+
+    const context = getSessionErrorContext(session);
+    expect(context.userId).toBeUndefined();
+    expect(context.sessionId).toBe('session_123');
+  });
+});

src/errors.ts

@@ -0,0 +1,69 @@
+import type { Session } from './interfaces.js';
+import { decodeJwt } from './jwt.js';
+
+/**
+ * Base error class for AuthKit errors.
+ * Matches the pattern used in @workos-inc/authkit-session.
+ */
+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 SessionErrorContext {
+  userId?: string;
+  sessionId?: string;
+}
+
+/**
+ * Error class for session-related errors that includes user and session context.
+ * Useful for debugging authentication issues.
+ */
+export class SessionError extends AuthKitError {
+  readonly userId?: string;
+  readonly sessionId?: string;
+
+  constructor(message: string, cause?: unknown, context?: SessionErrorContext) {
+    super(message, cause);
+    this.name = 'SessionError';
+    this.userId = context?.userId;
+    this.sessionId = context?.sessionId;
+  }
+}
+
+/**
+ * Extracts error context (userId, sessionId) from a session.
+ * Safely handles missing or invalid data.
+ */
+export function getSessionErrorContext(session?: Session | null): SessionErrorContext {
+  if (!session) {
+    return {};
+  }
+
+  const context: SessionErrorContext = {};
+
+  // Extract userId from session.user.id
+  if (session.user?.id) {
+    context.userId = session.user.id;
+  }
+
+  // Extract sessionId from JWT sid claim
+  if (session.accessToken) {
+    try {
+      const { payload } = decodeJwt(session.accessToken);
+      if (payload.sid) {
+        context.sessionId = payload.sid;
+      }
+    } catch {
+      // Ignore JWT decode errors - just return without sessionId
+    }
+  }
+
+  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, SessionError } 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,
+  SessionError,
   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 { SessionError, 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 SessionError(
+      `Failed to refresh session: ${error instanceof Error ? error.message : String(error)}`,
+      error,
+      getSessionErrorContext(session),
+    );
   }
 
   const headersList = await headers();