User Management

User signs up via Clerk
    |
    v
Clerk fires "user.created" webhook
    |
    v
/api/webhooks/clerk/route.ts
    |--- Verify SVIX signature
    |--- Extract email, name from event data
    |--- prisma.user.upsert (idempotent)
    |--- Initialize: tier="free", credits=500, resetAt=+30 days
    |
    v
User exists in both Clerk and your database

export async function syncUserFromClerk(clerkId: string): Promise<User | null> {
  // Skip Clerk API in test environment (E2E tests, CI)
  // Test users are seeded in playwright/seed-test-data.ts
  if (!shouldUseClerk()) {
    console.log(`[TEST] Skipping Clerk sync for ${clerkId}`)
    return null
  }

  try {
    // Get user data from Clerk
    const clerkUser = await (await clerkClient()).users.getUser(clerkId)

    if (!clerkUser) {
      console.error(`Clerk user not found: ${clerkId}`)
      return null
    }

    // Extract email and name
    const email = clerkUser.emailAddresses[0]?.emailAddress || null
    const name =
      [clerkUser.firstName, clerkUser.lastName].filter(Boolean).join(' ') ||
      null

    // Upsert user in database
    const user = await prisma.user.upsert({
      where: { clerkId },
      update: {
        email,
        name,
      },
      create: {
        clerkId,
        email,
        name,
      },
    })

    console.log(`User ${clerkId} synced from Clerk`)
    return user
  } catch (error) {
    console.error('Error syncing user from Clerk:', error)
    return null
  }
}

export async function ensureUserExists(clerkId: string): Promise<User | null> {
  // ⚠️ CRITICAL: In E2E tests, return mock user to prevent database queries
  // MSW mocks handle all API responses in test environment
  // Note: Check NEXT_PUBLIC_CLERK_ENABLED instead of NODE_ENV because
  // the dev server runs with NODE_ENV=development even during tests
  if (process.env.NEXT_PUBLIC_CLERK_ENABLED === 'false') {
    return {
      id: 'test_user_id',
      clerkId,
      email: 'test@example.com',
      name: 'Test User',
      createdAt: new Date(),
      updatedAt: new Date(),
    } as User
  }

  try {
    // First try to get user from database using repository pattern
    let user = await userRepository.findByClerkId(clerkId)

    // If user doesn't exist or has no email, sync from Clerk
    if (!user || !user.email) {
      user = await syncUserFromClerk(clerkId)
    }

    return user
  } catch (error) {
    console.error('Error ensuring user exists:', error)
    return null
  }
}

'use client'

import { createContext, useContext } from 'react'

/**
 * Database User Context
 * Provides database user ID to all dashboard components
 * This avoids prop drilling and makes userId available everywhere
 */

interface DbUserContextValue {
  userId: string | null
}

const DbUserContext = createContext<DbUserContextValue | undefined>(undefined)

interface DbUserProviderProps {
  userId: string | null
  children: React.ReactNode
}

/**
 * DbUserProvider
 * Wraps dashboard layout to provide database user ID to all child components
 *
 * @example
 * // In layout:
 * <DbUserProvider userId={dbUserId}>
 *   <DashboardContent />
 * </DbUserProvider>
 */
export function DbUserProvider({ userId, children }: DbUserProviderProps) {
  return (
    <DbUserContext.Provider value={{ userId }}>
      {children}
    </DbUserContext.Provider>
  )
}

/**
 * useDbUser hook
 * Access database user ID from anywhere in the dashboard
 *
 * @throws Error if used outside DbUserProvider
 * @returns Database user ID or null
 *
 * @example
 * const { userId } = useDbUser()
 * if (!userId) return <div>Loading...</div>
 * return <CreditBalanceBadge userId={userId} />
 */
export function useDbUser(): DbUserContextValue {
  const context = useContext(DbUserContext)
  if (context === undefined) {
    throw new Error('useDbUser must be used within DbUserProvider')
  }
  return context
}

// src/app/(dashboard)/layout.tsx (simplified)
const dbUser = await userRepository.findByClerkId(clerkUserId)

return (
  <DbUserProvider userId={dbUser?.id || null}>
    {children}
  </DbUserProvider>
)

import { useDbUser } from '@/providers/db-user-provider'

function CreditBalance() {
  const { userId } = useDbUser()

  if (!userId) return <p>Loading...</p>

  // Use userId to fetch credits, billing, etc.
  return <CreditBalanceBadge userId={userId} />
}

import { useCurrentUser } from '@/lib/query/hooks/use-user'

function ProfileCard() {
  const { data: user, isLoading } = useCurrentUser()

  if (isLoading) return <Skeleton />
  return <p>{user?.name} ({user?.email})</p>
}

import { useUserTier } from '@/lib/query/hooks/use-user-tier'

function FeatureGate({ children }: { children: React.ReactNode }) {
  const { tier, isLoading } = useUserTier()

  if (isLoading) return <Skeleton />
  if (tier === 'free') return <UpgradePrompt />
  return <>{children}</>
}

import {
  useConditionalAuth,
  useConditionalUser,
} from '@/lib/auth/use-conditional-auth'

function AuthStatus() {
  const { isSignedIn, userId } = useConditionalAuth()
  const { user } = useConditionalUser()

  return isSignedIn
    ? <p>Signed in as {user?.firstName}</p>
    : <p>Not signed in</p>
}

import { UniversalUserButton } from '@/components/auth/universal-user-button'

function Header() {
  return (
    <nav>
      <UniversalUserButton />
    </nav>
  )
}

NEXT_PUBLIC_DEMO_MODE=true

// Mock hooks (identical interface to Clerk)
useTestAuth()   // { isLoaded: true, isSignedIn: true, userId: 'clerk_test_free_001', ... }
useTestUser()   // { isLoaded: true, isSignedIn: true, user: { id, email, firstName, ... } }
useTestClerk()  // { loaded: true, signOut, openSignIn, openSignUp, ... }

# .env.test (used during E2E test runs)
NEXT_PUBLIC_CLERK_ENABLED=false

// Example: Vitest mock for Clerk
vi.mock('@clerk/nextjs', () => ({
  useAuth: () => ({ isSignedIn: true, userId: 'test-user' }),
  useUser: () => ({ user: { firstName: 'Test' } }),
}))