From d474bf5dceb0283591a219caafcb3d49bfc8b21e Mon Sep 17 00:00:00 2001
From: Okorie Chigozie Jehoshaphat <okoriechigozie99@gmail.com>
Date: Thu, 18 Jun 2026 08:02:52 +0100
Subject: [PATCH] Add optimistic updates for admin mutations  #22

---
 app/admin/members/page.tsx      |  66 +++++++++++++++++---
 app/admin/policies/page.tsx     |  61 ++++++++++++++++---
 lib/api/live.ts                 |  19 ++++--
 lib/api/optimistic.ts           |  50 ++++++++++++++++
 next-env.d.ts                   |   1 -
 package.json                    |   3 +-
 test/optimistic-updates.test.ts | 103 ++++++++++++++++++++++++++++++++
 test/tsconfig.json              |  17 ++++++
 tsconfig.json                   |  31 ++++++++--
 9 files changed, 322 insertions(+), 29 deletions(-)
 create mode 100644 lib/api/optimistic.ts
 create mode 100644 test/optimistic-updates.test.ts
 create mode 100644 test/tsconfig.json

diff --git a/app/admin/members/page.tsx b/app/admin/members/page.tsx
index 6d1ac4c..23e0f13 100644
--- a/app/admin/members/page.tsx
+++ b/app/admin/members/page.tsx
@@ -6,11 +6,22 @@ import { getApi, type MemberRow, type Role } from '@/lib/api'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
+import { Badge } from '@/components/ui/badge'
 import { useState } from 'react'
 import { AdminGuard } from '@/components/admin-guard'
 import { useSiweAuth } from '@/lib/wallet/providers'
 import { AuthError } from '@/lib/api/live'
 import { LoadingState, ErrorState, EmptyState, safeErrorMessage } from '@/components/ui/api-states'
+import { applyOptimisticRole } from '@/lib/api/optimistic'
+
+type AssignRoleInput = {
+  address: string
+  role: Role
+}
+
+type AssignRoleRollback = {
+  previousMembers?: MemberRow[]
+}
 
 function SessionExpiredBanner() {
   const { signIn, isSigningIn } = useSiweAuth()
@@ -49,6 +60,9 @@ export default function MembersPage() {
 
   const [addr, setAddr] = useState('')
   const [role, setRole] = useState<Role>('member')
+  const [pendingAssignment, setPendingAssignment] = useState<AssignRoleInput | null>(null)
+  const [successMessage, setSuccessMessage] = useState('')
+  const [rollbackMessage, setRollbackMessage] = useState('')
 
   const {
     mutate,
@@ -56,19 +70,40 @@ export default function MembersPage() {
     isError: mutateError,
     error: mutateErrorValue,
     reset: resetMutation
-  } = useMutation({
-    mutationFn: () => getApi(address, authSession?.token).assignRole(addr, role),
-    onSuccess: () => {
-      qc.invalidateQueries({ queryKey: ['members'] })
+  } = useMutation<void, unknown, AssignRoleInput, AssignRoleRollback>({
+    mutationFn: (input) =>
+      getApi(address, authSession?.token).assignRole(input.address, input.role),
+    onMutate: async (input) => {
+      await qc.cancelQueries({ queryKey: ['members'] })
+      const previousMembers = qc.getQueryData<MemberRow[]>(['members'])
+
+      setPendingAssignment(input)
+      setSuccessMessage('')
+      setRollbackMessage('')
       setSessionExpired(false)
+
+      qc.setQueryData<MemberRow[]>(['members'], (currentMembers) =>
+        applyOptimisticRole(currentMembers, input.address, input.role),
+      )
+
+      return { previousMembers }
+    },
+    onSuccess: (_data, input) => {
+      setSuccessMessage(`Role "${input.role}" saved for ${input.address}.`)
       setAddr('')
       resetMutation()
     },
-    onError: (err: unknown) => {
+    onError: (err: unknown, _input, context) => {
+      qc.setQueryData(['members'], context?.previousMembers)
+      setRollbackMessage(`Change reverted: ${safeErrorMessage(err)}`)
       if (err instanceof AuthError) {
         setSessionExpired(true)
       }
     },
+    onSettled: () => {
+      setPendingAssignment(null)
+      qc.invalidateQueries({ queryKey: ['members'] })
+    },
   })
 
   return (
@@ -100,17 +135,27 @@ export default function MembersPage() {
               </select>
               <Button
                 id="assign-role-btn"
-                onClick={() => mutate()}
+                onClick={() => mutate({ address: addr, role })}
                 disabled={!addr || isPending}
               >
                 {isPending ? 'Assigning…' : 'Assign'}
               </Button>
             </div>
+            {successMessage && (
+              <div className="text-sm text-green-700 dark:text-green-400" role="status">
+                {successMessage}
+              </div>
+            )}
+            {rollbackMessage && (
+              <div className="text-sm text-destructive" role="alert">
+                {rollbackMessage}
+              </div>
+            )}
             {mutateError && (
               <ErrorState
                 title="Failed to assign role"
                 message={safeErrorMessage(mutateErrorValue)}
-                onRetry={() => mutate()}
+                onRetry={() => mutate({ address: addr, role })}
               />
             )}
           </CardContent>
@@ -137,8 +182,11 @@ export default function MembersPage() {
                     className="flex items-center justify-between border rounded-md p-2"
                   >
                     <div className="text-sm">{m.address}</div>
-                    <div className="text-xs text-muted-foreground">
-                      Tier: {m.tier} • Roles: {m.roles.join(', ')}
+                    <div className="flex items-center gap-2 text-xs text-muted-foreground">
+                      <span>Tier: {m.tier} • Roles: {m.roles.join(', ')}</span>
+                      {pendingAssignment?.address.toLowerCase() === m.address.toLowerCase() && (
+                        <Badge variant="warning">Saving</Badge>
+                      )}
                     </div>
                   </div>
                 ))}
diff --git a/app/admin/policies/page.tsx b/app/admin/policies/page.tsx
index 10d35c7..97cd7ed 100644
--- a/app/admin/policies/page.tsx
+++ b/app/admin/policies/page.tsx
@@ -5,11 +5,17 @@ import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
 import { getApi, type AccessPolicy } from '@/lib/api'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { Button } from '@/components/ui/button'
+import { Badge } from '@/components/ui/badge'
 import { AdminGuard } from '@/components/admin-guard'
 import { useSiweAuth } from '@/lib/wallet/providers'
 import { AuthError } from '@/lib/api/live'
 import { useState } from 'react'
 import { LoadingState, ErrorState, EmptyState, safeErrorMessage } from '@/components/ui/api-states'
+import { applyOptimisticPolicy } from '@/lib/api/optimistic'
+
+type PolicyRollback = {
+  previousPolicies?: AccessPolicy[]
+}
 
 function SessionExpiredBanner() {
   const { signIn, isSigningIn } = useSiweAuth()
@@ -39,6 +45,9 @@ export default function PoliciesPage() {
   const { authSession } = useSiweAuth()
   const qc = useQueryClient()
   const [sessionExpired, setSessionExpired] = useState(false)
+  const [pendingPolicyId, setPendingPolicyId] = useState<string | null>(null)
+  const [successMessage, setSuccessMessage] = useState('')
+  const [rollbackMessage, setRollbackMessage] = useState('')
 
   const { data: policies, isLoading, isError, error, refetch } = useQuery<AccessPolicy[]>({
     queryKey: ['policies'],
@@ -48,23 +57,42 @@ export default function PoliciesPage() {
 
   const {
     mutate,
-    isPending,
     isError: mutateError,
     error: mutateErrorValue,
     reset: resetMutation
-  } = useMutation({
+  } = useMutation<void, unknown, AccessPolicy, PolicyRollback>({
     mutationFn: (p: AccessPolicy) =>
       getApi(address, authSession?.token).updatePolicy(p),
-    onSuccess: () => {
-      qc.invalidateQueries({ queryKey: ['policies'] })
+    onMutate: async (policy) => {
+      await qc.cancelQueries({ queryKey: ['policies'] })
+      const previousPolicies = qc.getQueryData<AccessPolicy[]>(['policies'])
+
+      setPendingPolicyId(policy.resourceId)
+      setSuccessMessage('')
+      setRollbackMessage('')
       setSessionExpired(false)
+
+      qc.setQueryData<AccessPolicy[]>(['policies'], (currentPolicies) =>
+        applyOptimisticPolicy(currentPolicies, policy),
+      )
+
+      return { previousPolicies }
+    },
+    onSuccess: (_data, policy) => {
+      setSuccessMessage(`Policy saved for ${policy.resourceId}.`)
       resetMutation()
     },
-    onError: (err: unknown) => {
+    onError: (err: unknown, _policy, context) => {
+      qc.setQueryData(['policies'], context?.previousPolicies)
+      setRollbackMessage(`Change reverted: ${safeErrorMessage(err)}`)
       if (err instanceof AuthError) {
         setSessionExpired(true)
       }
     },
+    onSettled: () => {
+      setPendingPolicyId(null)
+      qc.invalidateQueries({ queryKey: ['policies'] })
+    },
   })
 
   return (
@@ -90,13 +118,18 @@ export default function PoliciesPage() {
             ) : (
               policies.map((p) => (
                 <div key={p.resourceId} className="flex items-center gap-2">
-                  <div className="w-40 text-sm">{p.resourceId}</div>
+                  <div className="flex w-40 items-center gap-2 text-sm">
+                    <span>{p.resourceId}</span>
+                    {pendingPolicyId === p.resourceId && (
+                      <Badge variant="warning">Saving</Badge>
+                    )}
+                  </div>
                   <select
                     id={`policy-tier-${p.resourceId}`}
                     className="border rounded-md h-9 px-2 text-sm"
                     value={p.minTier ?? 'free'}
                     onChange={(e) => mutate({ ...p, minTier: e.target.value as AccessPolicy['minTier'] })}
-                    disabled={isPending}
+                    disabled={Boolean(pendingPolicyId)}
                   >
                     <option value="free">free</option>
                     <option value="standard">standard</option>
@@ -107,13 +140,23 @@ export default function PoliciesPage() {
                     variant="outline"
                     size="sm"
                     onClick={() => mutate({ ...p })}
-                    disabled={isPending}
+                    disabled={Boolean(pendingPolicyId)}
                   >
-                    {isPending ? 'Saving…' : 'Save'}
+                    {pendingPolicyId === p.resourceId ? 'Saving…' : 'Save'}
                   </Button>
                 </div>
               ))
             )}
+            {successMessage && (
+              <div className="text-sm text-green-700 dark:text-green-400" role="status">
+                {successMessage}
+              </div>
+            )}
+            {rollbackMessage && (
+              <div className="text-sm text-destructive" role="alert">
+                {rollbackMessage}
+              </div>
+            )}
             {mutateError && (
               <ErrorState
                 title="Failed to save policy"
diff --git a/lib/api/live.ts b/lib/api/live.ts
index 3942f22..e82e146 100644
--- a/lib/api/live.ts
+++ b/lib/api/live.ts
@@ -84,6 +84,10 @@ async function getJson<T>(path: string, init?: RequestInit): Promise<T> {
 // mapper becomes a no-op and can be removed without touching call sites.
 
 function mapCommunity(raw: BackendSession['community']): Community {
+  if (!raw) {
+    throw new ApiError(500, 'Invalid API response', 'Missing community')
+  }
+
   return {
     id: raw.id,
     name: raw.name,
@@ -92,9 +96,16 @@ function mapCommunity(raw: BackendSession['community']): Community {
   }
 }
 
+function requiredString(value: string | undefined, field: string): string {
+  if (!value) {
+    throw new ApiError(500, 'Invalid API response', `Missing ${field}`)
+  }
+  return value
+}
+
 function mapMembership(raw: BackendMember): Membership {
   return {
-    address: raw.address ?? raw.wallet_address,
+    address: requiredString(raw.address ?? raw.wallet_address, 'member address'),
     tier: raw.tier ?? raw.membership_tier ?? 'free',
     active: raw.active ?? raw.is_active ?? false,
     expiresAt: raw.expiresAt ?? raw.expires_at,
@@ -112,7 +123,7 @@ function mapMemberProfile(raw: BackendMember, address: string): MemberProfile {
 
 function mapMemberRow(raw: BackendMember): MemberRow {
   return {
-    address: raw.address ?? raw.wallet_address,
+    address: requiredString(raw.address ?? raw.wallet_address, 'member address'),
     roles: raw.roles ?? [],
     tier: raw.tier ?? raw.membership_tier ?? 'free',
     active: raw.active ?? raw.is_active ?? false,
@@ -122,7 +133,7 @@ function mapMemberRow(raw: BackendMember): MemberRow {
 function mapResource(raw: BackendResource): Resource {
   return {
     id: raw.id,
-    title: raw.title ?? raw.name,
+    title: raw.title ?? raw.name ?? raw.id,
     description: raw.description,
     minTier: raw.minTier ?? raw.min_tier,
     roles: raw.roles,
@@ -131,7 +142,7 @@ function mapResource(raw: BackendResource): Resource {
 
 function mapPolicy(raw: BackendPolicy): AccessPolicy {
   return {
-    resourceId: raw.resourceId ?? raw.resource_id,
+    resourceId: requiredString(raw.resourceId ?? raw.resource_id, 'policy resourceId'),
     minTier: raw.minTier ?? raw.min_tier,
     roles: raw.roles,
   }
diff --git a/lib/api/optimistic.ts b/lib/api/optimistic.ts
new file mode 100644
index 0000000..2fdfaad
--- /dev/null
+++ b/lib/api/optimistic.ts
@@ -0,0 +1,50 @@
+import type { AccessPolicy, MemberRow, Role } from './types'
+
+export function applyOptimisticRole(
+  members: MemberRow[] | undefined,
+  address: string,
+  role: Role,
+): MemberRow[] {
+  const currentMembers = members ?? []
+  const memberIndex = currentMembers.findIndex(
+    (member) => member.address.toLowerCase() === address.toLowerCase(),
+  )
+
+  if (memberIndex === -1) {
+    return [
+      ...currentMembers,
+      {
+        address,
+        roles: [role],
+        tier: 'free',
+        active: true,
+      },
+    ]
+  }
+
+  return currentMembers.map((member, index) => {
+    if (index !== memberIndex || member.roles.includes(role)) return member
+    return {
+      ...member,
+      roles: [...member.roles, role],
+    }
+  })
+}
+
+export function applyOptimisticPolicy(
+  policies: AccessPolicy[] | undefined,
+  policy: AccessPolicy,
+): AccessPolicy[] {
+  const currentPolicies = policies ?? []
+  const policyIndex = currentPolicies.findIndex(
+    (currentPolicy) => currentPolicy.resourceId === policy.resourceId,
+  )
+
+  if (policyIndex === -1) {
+    return [...currentPolicies, policy]
+  }
+
+  return currentPolicies.map((currentPolicy, index) =>
+    index === policyIndex ? policy : currentPolicy,
+  )
+}
diff --git a/next-env.d.ts b/next-env.d.ts
index fd36f94..4f11a03 100644
--- a/next-env.d.ts
+++ b/next-env.d.ts
@@ -1,6 +1,5 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-/// <reference types="next/navigation-types/compat/navigation" />
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/basic-features/typescript for more information.
diff --git a/package.json b/package.json
index f589b5c..71b9d41 100644
--- a/package.json
+++ b/package.json
@@ -13,6 +13,7 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
+    "test": "tsc -p test/tsconfig.json && node --test test-dist/test/*.test.js",
     "typecheck": "tsc --noEmit",
     "sync-types": "node scripts/sync-api-types.js --write",
     "check-types": "node scripts/sync-api-types.js --check"
@@ -42,4 +43,4 @@
     "eslint-config-next": "14.2.5",
     "typescript": "^5.4.5"
   }
-}
\ No newline at end of file
+}
diff --git a/test/optimistic-updates.test.ts b/test/optimistic-updates.test.ts
new file mode 100644
index 0000000..6c9cb71
--- /dev/null
+++ b/test/optimistic-updates.test.ts
@@ -0,0 +1,103 @@
+import { test } from 'node:test'
+import * as assert from 'node:assert/strict'
+import { applyOptimisticPolicy, applyOptimisticRole } from '../lib/api/optimistic'
+import type { AccessPolicy, MemberRow } from '../lib/api/types'
+
+test('applies a role assignment optimistically without losing the rollback snapshot', () => {
+  const previousMembers: MemberRow[] = [
+    {
+      address: '0xabc',
+      roles: ['member'],
+      tier: 'standard',
+      active: true,
+    },
+  ]
+
+  const optimisticMembers = applyOptimisticRole(previousMembers, '0xabc', 'moderator')
+
+  assert.deepEqual(optimisticMembers, [
+    {
+      address: '0xabc',
+      roles: ['member', 'moderator'],
+      tier: 'standard',
+      active: true,
+    },
+  ])
+  assert.deepEqual(previousMembers, [
+    {
+      address: '0xabc',
+      roles: ['member'],
+      tier: 'standard',
+      active: true,
+    },
+  ])
+})
+
+test('rolls back an optimistic role assignment by restoring the previous members', () => {
+  const previousMembers: MemberRow[] = [
+    {
+      address: '0xabc',
+      roles: ['member'],
+      tier: 'standard',
+      active: true,
+    },
+  ]
+  const optimisticMembers = applyOptimisticRole(previousMembers, '0xabc', 'admin')
+
+  assert.notDeepEqual(optimisticMembers, previousMembers)
+  assert.deepEqual(previousMembers, [
+    {
+      address: '0xabc',
+      roles: ['member'],
+      tier: 'standard',
+      active: true,
+    },
+  ])
+})
+
+test('adds a missing member optimistically for a role assignment', () => {
+  assert.deepEqual(applyOptimisticRole([], '0xdef', 'member'), [
+    {
+      address: '0xdef',
+      roles: ['member'],
+      tier: 'free',
+      active: true,
+    },
+  ])
+})
+
+test('applies a policy edit optimistically without mutating the rollback snapshot', () => {
+  const previousPolicies: AccessPolicy[] = [
+    { resourceId: 'alpha', minTier: 'standard' },
+    { resourceId: 'reports', minTier: 'pro' },
+  ]
+
+  const optimisticPolicies = applyOptimisticPolicy(previousPolicies, {
+    resourceId: 'alpha',
+    minTier: 'pro',
+  })
+
+  assert.deepEqual(optimisticPolicies, [
+    { resourceId: 'alpha', minTier: 'pro' },
+    { resourceId: 'reports', minTier: 'pro' },
+  ])
+  assert.deepEqual(previousPolicies, [
+    { resourceId: 'alpha', minTier: 'standard' },
+    { resourceId: 'reports', minTier: 'pro' },
+  ])
+})
+
+test('rolls back an optimistic policy edit by restoring the previous policies', () => {
+  const previousPolicies: AccessPolicy[] = [
+    { resourceId: 'alpha', minTier: 'standard' },
+  ]
+  const optimisticPolicies = applyOptimisticPolicy(previousPolicies, {
+    resourceId: 'alpha',
+    minTier: 'pro',
+  })
+
+  assert.notDeepEqual(optimisticPolicies, previousPolicies)
+  assert.deepEqual(previousPolicies, [
+    { resourceId: 'alpha', minTier: 'standard' },
+  ])
+})
diff --git a/test/tsconfig.json b/test/tsconfig.json
new file mode 100644
index 0000000..e19ed73
--- /dev/null
+++ b/test/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "noEmit": false,
+    "outDir": "../test-dist",
+    "rootDir": "..",
+    "incremental": false,
+    "jsx": "react-jsx"
+  },
+  "include": [
+    "../lib/api/optimistic.ts",
+    "../lib/api/types.ts",
+    "./*.test.ts"
+  ]
+}
diff --git a/tsconfig.json b/tsconfig.json
index 9905d94..6fe4463 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,7 +1,11 @@
 {
   "compilerOptions": {
     "target": "ES2020",
-    "lib": ["dom", "dom.iterable", "es2020"],
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "es2020"
+    ],
     "allowJs": false,
     "skipLibCheck": true,
     "strict": true,
@@ -14,10 +18,27 @@
     "incremental": true,
     "baseUrl": ".",
     "paths": {
-      "@/*": ["./*"]
+      "@/*": [
+        "./*"
+      ]
     },
-    "types": ["node"]
+    "types": [
+      "node"
+    ],
+    "esModuleInterop": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
   },
-  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
-  "exclude": ["node_modules"]
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
 }