refactor(db): split session context API into distinct handler and context functions

Previously, the session context API had confusing naming and overlapping
responsibilities:
- withSessionDb and withImpersonation did the same thing (confusing)
- withImpersonation had two overloads for different use cases (ambiguous)
- databaseType field was exposed but never used (bloat)

This refactor creates a clearer, more intentional API:

## API Changes

**Before:**
- withSessionDb(handler, options) - callback pattern
- withImpersonation() - get context OR callback pattern (overloaded)

**After:**
- withImpersonation(handler, options) - callback pattern for server actions
- getImpersonationContext(options) - context retrieval for components/routes

## New Function Purposes

**withImpersonation(handler, options)**
- Execute handler with session context
- Best for: Server actions, self-contained operations
- Usage: `return withImpersonation(async ({ db, userId }) => { ... })`

**getImpersonationContext(options)**
- Retrieve session context for use in outer scope
- Best for: Server components, API routes, complex flow control
- Usage: `const { db, userId } = await getImpersonationContext()`

## Type Changes

- SessionDbContext → SessionContext
- WithSessionDbOptions → SessionContextOptions
- Removed: databaseType field (unused)
- Removed: DatabaseType type (unused)
- Removed: getDatabaseType() function (unused)

## Benefits

✓ Clear naming convention (get* vs with*)
✓ Single responsibility per function
✓ More discoverable API (name indicates usage)
✓ Follows Next.js patterns (getServerSession, etc.)
✓ Removed unused code (databaseType)
✓ Better documentation with usage examples

## Files Changed: 68
- 52 files using withImpersonation (callback pattern)
- 54 files using getImpersonationContext (direct context)
- 2 core files updated (sessionContext.ts, helpers.ts)

Author: galo13eth

app/src/app/api/admin/impersonation-status/route.ts

@@ -10,13 +10,13 @@ import {
   isAdminUser,
   isImpersonationEnabled,
 } from "@/lib/auth/adminConfig"
-import { withImpersonation } from "@/lib/db/sessionContext"
+import { getImpersonationContext } from "@/lib/db/sessionContext"
 
 export const dynamic = 'force-dynamic'
 
 export async function GET() {
   try {
-    const { session, userId } = await withImpersonation()
+    const { session, userId } = await getImpersonationContext()
     const adminUserId = session?.user?.id
 
     if (!userId || !adminUserId) {

app/src/app/api/admin/search-users/route.ts

@@ -5,7 +5,7 @@
 
 import { NextRequest, NextResponse } from "next/server"
 import { isAdminUser, isImpersonationEnabled } from "@/lib/auth/adminConfig"
-import { withImpersonation } from "@/lib/db/sessionContext"
+import { getImpersonationContext } from "@/lib/db/sessionContext"
 import { impersonationService } from "@/lib/services/impersonationService"
 
 export const dynamic = 'force-dynamic'
@@ -19,7 +19,7 @@ export async function GET(request: NextRequest) {
       )
     }
 
-    const { session, userId } = await withImpersonation()
+    const { session, userId } = await getImpersonationContext()
     const adminUserId = session?.user?.id
     if (!userId || !adminUserId) {
       return NextResponse.json(

app/src/app/api/cron/kyc-emails/route.ts

@@ -1,6 +1,6 @@
 import { NextRequest } from "next/server"
 
-import { withImpersonation } from "@/lib/db/sessionContext"
+import { getImpersonationContext } from "@/lib/db/sessionContext"
 import { withCronObservability } from "@/lib/cron"
 import {
   sendKYBReminderEmail,
@@ -24,7 +24,7 @@ async function handleKYCEmailsCron(request: NextRequest) {
     errors: [] as string[],
   }
 
-  const { db } = await withImpersonation({ forceProd: true, session: null })
+  const { db } = await getImpersonationContext({ forceProd: true, session: null })
 
   try {
     console.log("🔍 Processing KYC reminder emails...")

app/src/app/api/kyc/verify/[token]/route.ts

@@ -2,14 +2,14 @@ import { NextRequest, NextResponse } from "next/server"
 
 import { verifyKYCToken, isKYCLinkExpired } from "@/lib/utils/kycToken"
 import { personaClient } from "@/lib/persona"
-import { withImpersonation } from "@/lib/db/sessionContext"
+import { getImpersonationContext } from "@/lib/db/sessionContext"
 
 export async function POST(
   request: NextRequest,
   { params }: { params: { token: string } },
 ) {
   try {
-    const { db } = await withImpersonation({ forceProd: true, session: null })
+    const { db } = await getImpersonationContext({ forceProd: true, session: null })
     const { token } = params
 
     // Verify and decode the token

app/src/app/api/projects/[projectId]/contracts/count/route.ts

@@ -1,7 +1,7 @@
 import { NextResponse } from "next/server"
 import { getAddress } from "viem"
 
-import { withImpersonation } from "@/lib/db/sessionContext"
+import { getImpersonationContext } from "@/lib/db/sessionContext"
 
 export const dynamic = "force-dynamic"
 export const revalidate = 0
@@ -10,7 +10,7 @@ export async function GET(
   request: Request,
   { params }: { params: { projectId: string } },
 ) {
-  const { db } = await withImpersonation()
+  const { db } = await getImpersonationContext()
   const { searchParams } = new URL(request.url)
   const deployer = searchParams.get("deployer")
 

app/src/app/api/projects/[projectId]/contracts/publish-progress/route.ts

@@ -3,7 +3,7 @@ import { NextResponse } from "next/server"
 import { getProjectContractsFresh } from "@/db/projects"
 import { getUnpublishedContractChanges } from "@/lib/actions/projects"
 import { verifyMembership } from "@/lib/actions/utils"
-import { withImpersonation } from "@/lib/db/sessionContext"
+import { getImpersonationContext } from "@/lib/db/sessionContext"
 
 export const dynamic = "force-dynamic"
 export const revalidate = 0
@@ -15,7 +15,7 @@ export async function GET(
   const { projectId } = params
 
   try {
-    const { db, userId } = await withImpersonation()
+    const { db, userId } = await getImpersonationContext()
 
     if (!userId) {
       return NextResponse.json({ error: "Unauthorized" }, { status: 401 })

app/src/app/api/sc/endorsements/eligibility/route.ts

@@ -1,10 +1,10 @@
 import { NextRequest, NextResponse } from "next/server"
 
-import { withImpersonation } from "@/lib/db/sessionContext"
+import { getImpersonationContext } from "@/lib/db/sessionContext"
 import { isTop100Delegate } from "@/lib/services/top100"
 
 export async function GET(req: NextRequest) {
-  const { db, userId } = await withImpersonation()
+  const { db, userId } = await getImpersonationContext()
   const { searchParams } = new URL(req.url)
   const roleId = Number(searchParams.get("roleId"))
 

app/src/app/api/sc/endorsements/me/route.ts

@@ -1,13 +1,13 @@
 import { NextRequest, NextResponse } from "next/server"
 
-import { withImpersonation } from "@/lib/db/sessionContext"
+import { getImpersonationContext } from "@/lib/db/sessionContext"
 import {
   getEndorsedNomineeIdsForAddressesByRole,
   hasEndorsed,
 } from "@/db/endorsements"
 
 export async function GET(req: NextRequest) {
-  const { db, userId } = await withImpersonation()
+  const { db, userId } = await getImpersonationContext()
   if (!userId) return new Response("Unauthorized", { status: 401 })
   const { searchParams } = new URL(req.url)
   const context = searchParams.get("context")

app/src/app/api/sc/endorsements/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from "next/server"
 import { z } from "zod"
 
-import { withImpersonation } from "@/lib/db/sessionContext"
+import { getImpersonationContext } from "@/lib/db/sessionContext"
 import {
   createEndorsement,
   deleteEndorsementsForAddresses,
@@ -18,7 +18,7 @@ const payloadSchema = z.object({
 })
 
 export async function POST(req: NextRequest) {
-  const { db, userId } = await withImpersonation()
+  const { db, userId } = await getImpersonationContext()
   if (!userId) return new Response("Unauthorized", { status: 401 })
 
   const json = await req.json().catch(() => null)
@@ -103,7 +103,7 @@ export async function POST(req: NextRequest) {
 }
 
 export async function GET(req: NextRequest) {
-  const { db } = await withImpersonation()
+  const { db } = await getImpersonationContext()
   const { searchParams } = new URL(req.url)
   const context = searchParams.get("context")
   const roleId = Number(searchParams.get("roleId"))
@@ -154,7 +154,7 @@ export async function GET(req: NextRequest) {
 }
 
 export async function DELETE(req: NextRequest) {
-  const { db, userId } = await withImpersonation()
+  const { db, userId } = await getImpersonationContext()
   if (!userId) return new Response("Unauthorized", { status: 401 })
 
   const { searchParams } = new URL(req.url)

app/src/app/api/sc/top100/route.ts

@@ -1,10 +1,10 @@
 import { NextResponse } from "next/server"
 
-import { withImpersonation } from "@/lib/db/sessionContext"
+import { getImpersonationContext } from "@/lib/db/sessionContext"
 import { isTop100Delegate } from "@/lib/services/top100"
 
 export async function GET() {
-  const { db, userId } = await withImpersonation()
+  const { db, userId } = await getImpersonationContext()
 
   if (!userId) {
     return NextResponse.json({ top100: false })