Typed Client & TanStack Query

┌────────────────────────────────┐
│  createAuthkitClient(opts?)    │  ← low-level typed fetch wrapper
│    client.admin.*              │
│    client.account.*            │
└──────────────┬─────────────────┘
               │  wrapped by
┌──────────────▼─────────────────┐
│  TanStack Query hooks          │  ← useUsersQueryOptions(), useMutation(…)
│  authkitKeys.*                 │  ← structured cache keys
└────────────────────────────────┘

pnpm add @adonis-agora/authkit-react @tanstack/react-query

function useResource<T>(url: string, csrfToken?: string): {
  data: T | null
  loading: boolean
  error: Error | null
  refetch: () => Promise<void>
}

function jsonRequest<T>(url: string, init?: RequestInit & { csrfToken?: string }): Promise<T>

import { useCallback } from 'react'
import { jsonRequest, useResource, useAuthkitConfig } from '@adonis-agora/authkit-react'

interface ApiKey {
  id: string
  label: string
  createdAt: string
}

export function useApiKeys() {
  const { csrfToken } = useAuthkitConfig()
  const { data, loading, error, refetch } = useResource<ApiKey[]>('/api/keys', csrfToken)

  const revoke = useCallback(
    async (id: string) => {
      await jsonRequest(`/api/keys/${encodeURIComponent(id)}`, {
        method: 'DELETE',
        csrfToken,
      })
      await refetch()
    },
    [csrfToken, refetch],
  )

  return { data, loading, error, actions: { refetch, revoke } }
}

import { QueryClientProvider } from '@tanstack/react-query'
import {
  createAuthkitQueryClient,
  AuthkitClientProvider,
} from '@adonis-agora/authkit-react'

const queryClient = createAuthkitQueryClient()

export default function AdminLayout({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <AuthkitClientProvider>
        {children}
      </AuthkitClientProvider>
    </QueryClientProvider>
  )
}

import { createAuthkitClient, AuthkitClientProvider } from '@adonis-agora/authkit-react'

const client = createAuthkitClient({ baseUrl: '/admin/api', csrfToken: 'test-token' })

<AuthkitClientProvider client={client}>
  <App />
</AuthkitClientProvider>

import { createAuthkitClient } from '@adonis-agora/authkit-react'

// Browser — reads window.__AUTHKIT__ automatically
const client = createAuthkitClient()

// Explicit (SSR, tests, custom topologies)
const client = createAuthkitClient({
  baseUrl: '/admin/api',       // default: window.__AUTHKIT__.endpoints.api
  accountBaseUrl: '/account/api', // default: '/account/api'
  csrfToken: 'my-token',
  fetch: customFetch,          // optional — inject a mock in tests
})

import { AuthkitClientError } from '@adonis-agora/authkit-react'

try {
  await client.admin.users.get('u_missing')
} catch (err) {
  if (err instanceof AuthkitClientError) {
    console.log(err.status)   // 404
    console.log(err.code)     // 'not_found' (from the error envelope)
    console.log(err.message)  // human-readable message
    console.log(err.body)     // raw JSON response
    console.log(err.isUnauthorized) // true when status === 401
  }
}

catch (err) {
  if (err instanceof AuthkitClientError && err.isUnauthorized) {
    window.location.href = '/auth/login'
  }
}

const { data } = useQuery(useUsersQueryOptions({ search: 'alice', page: 1 }))
// data.data — AdminUser[]
// data.meta — { page, size, total }

const m = useMutation(useCreateUserMutationOptions())

import { useState } from 'react'
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
import {
  authkitKeys,
  useUsersQueryOptions,
  useCreateUserMutationOptions,
  useDisableUserMutationOptions,
  useDeleteUserMutationOptions,
  AuthkitClientError,
} from '@adonis-agora/authkit-react'

export default function UsersPage() {
  const queryClient = useQueryClient()
  const [search, setSearch] = useState('')
  const [disablingId, setDisablingId] = useState<string | null>(null)

  // ── Queries ──────────────────────────────────────────────────────────────
  const { data, isLoading } = useQuery(useUsersQueryOptions({ search }))

  // ── Mutations ─────────────────────────────────────────────────────────────
  const createMutation = useMutation(useCreateUserMutationOptions())
  const disableMutation = useMutation(useDisableUserMutationOptions(disablingId ?? ''))
  const deleteMutation = useMutation(useDeleteUserMutationOptions(''))

  // ── Handlers ──────────────────────────────────────────────────────────────
  async function handleCreate(formData: { email: string; name?: string }) {
    try {
      await createMutation.mutateAsync(formData)
      queryClient.invalidateQueries({ queryKey: authkitKeys.admin.users() })
    } catch (err) {
      if (err instanceof AuthkitClientError) {
        alert(err.message)
      }
    }
  }

  async function handleDisable(id: string) {
    setDisablingId(id)
    try {
      await disableMutation.mutateAsync()
      // Invalidate both the list and the single-user query
      queryClient.invalidateQueries({ queryKey: authkitKeys.admin.users() })
      queryClient.invalidateQueries({ queryKey: authkitKeys.admin.user(id) })
    } finally {
      setDisablingId(null)
    }
  }

  // ── Render ────────────────────────────────────────────────────────────────
  if (isLoading) return <p>Loading…</p>

  return (
    <ul>
      {data?.users.map((u) => (
        <li key={u.id}>
          {u.email}
          <button onClick={() => handleDisable(u.id)}>Disable</button>
        </li>
      ))}
    </ul>
  )
}

import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
import {
  authkitKeys,
  useOrgQueryOptions,
  useAddOrgMemberMutationOptions,
  useCreateOrgInvitationMutationOptions,
  useRemoveOrgMemberMutationOptions,
  useUpdateOrgMemberRoleMutationOptions,
} from '@adonis-agora/authkit-react'

function MemberRow({ orgId, accountId, role }: { orgId: string; accountId: string; role: string }) {
  const queryClient = useQueryClient()
  const removeMember = useMutation(useRemoveOrgMemberMutationOptions(orgId, accountId))
  const updateRole = useMutation(useUpdateOrgMemberRoleMutationOptions(orgId, accountId))

  const refresh = () => queryClient.invalidateQueries({ queryKey: authkitKeys.admin.org(orgId) })

  return (
    <tr>
      <td>{accountId}</td>
      <td>
        <select
          value={role}
          onChange={async (e) => {
            await updateRole.mutateAsync(e.target.value)
            refresh()
          }}
        >
          <option value="member">member</option>
          <option value="admin">admin</option>
        </select>
      </td>
      <td>
        <button
          onClick={async () => {
            await removeMember.mutateAsync()
            refresh()
          }}
        >
          Remove
        </button>
      </td>
    </tr>
  )
}

function OrgMembers({ orgId }: { orgId: string }) {
  const queryClient = useQueryClient()
  const { data: org } = useQuery(useOrgQueryOptions(orgId)) // org.members, org.pendingInvitations
  const addMember = useMutation(useAddOrgMemberMutationOptions(orgId))
  const invite = useMutation(useCreateOrgInvitationMutationOptions(orgId))

  async function handleAdd(accountId: string) {
    await addMember.mutateAsync({ accountId, role: 'member' })
    queryClient.invalidateQueries({ queryKey: authkitKeys.admin.org(orgId) })
  }

  async function handleInvite(email: string) {
    const { invitation } = await invite.mutateAsync({ email, role: 'member' })
    queryClient.invalidateQueries({ queryKey: authkitKeys.admin.org(orgId) })
    return invitation
  }

  return (
    <table>
      <tbody>
        {org?.members.map((m) => (
          <MemberRow key={m.accountId} orgId={orgId} accountId={m.accountId} role={m.role} />
        ))}
      </tbody>
    </table>
  )
}

import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
import {
  authkitKeys,
  useKeysQueryOptions,
  useRotateKeysMutationOptions,
} from '@adonis-agora/authkit-react'

function KeysPanel() {
  const queryClient = useQueryClient()
  const { data } = useQuery(useKeysQueryOptions())
  const rotate = useMutation(useRotateKeysMutationOptions())

  async function handleRotate() {
    const result = await rotate.mutateAsync({ retire: false })
    console.log(result.newKid, result.retiredKids, result.keptKids)
    queryClient.invalidateQueries({ queryKey: authkitKeys.admin.keys() })
  }

  if (!data) return null

  return (
    <div>
      <p>Current key is {data.ageDays} days old.</p>
      <p>
        {data.policy.enabled
          ? `Rotates automatically every ${data.policy.maxAgeDays} days.`
          : 'Automatic rotation is off.'}
      </p>
      <button onClick={handleRotate} disabled={rotate.isPending}>
        Rotate now
      </button>
    </div>
  )
}

import { authkitKeys } from '@adonis-agora/authkit-react'

// Invalidate all admin data
queryClient.invalidateQueries({ queryKey: authkitKeys.admin.all })

// Invalidate the users list (all search params)
queryClient.invalidateQueries({ queryKey: authkitKeys.admin.users() })

// Invalidate a specific user + their sessions
queryClient.invalidateQueries({ queryKey: authkitKeys.admin.user(id) })
queryClient.invalidateQueries({ queryKey: authkitKeys.admin.userSessions(id) })

// Account data
queryClient.invalidateQueries({ queryKey: authkitKeys.account.me() })
queryClient.invalidateQueries({ queryKey: authkitKeys.account.sessions() })

authkitKeys.admin.all             // ['authkit', 'admin']
authkitKeys.admin.overview()      // ['authkit', 'admin', 'overview']
authkitKeys.admin.users(params?)  // ['authkit', 'admin', 'users', params]
authkitKeys.admin.user(id)        // ['authkit', 'admin', 'users', id]
authkitKeys.admin.userSessions(id)
authkitKeys.admin.sessions(accountId?)
authkitKeys.admin.clients()
authkitKeys.admin.client(id)
authkitKeys.admin.roles()
authkitKeys.admin.orgs()
authkitKeys.admin.org(id)
authkitKeys.admin.audit(params?)
authkitKeys.admin.settings(orgId?)  // ['authkit','admin','settings'] or [...,'settings', orgId]
authkitKeys.admin.impersonation(userId)
authkitKeys.admin.keys()            // ['authkit', 'admin', 'keys']

authkitKeys.account.all
authkitKeys.account.me()
authkitKeys.account.security()
authkitKeys.account.sessions()
authkitKeys.account.apps()
authkitKeys.account.mfa()
authkitKeys.account.passkeys()
authkitKeys.account.tokens()
authkitKeys.account.orgs()
authkitKeys.account.org(id)
authkitKeys.account.orgInvitations()

// Next.js server component or test
const client = createAuthkitClient({
  baseUrl: process.env.AUTHKIT_ADMIN_API_URL,
  accountBaseUrl: process.env.AUTHKIT_ACCOUNT_API_URL,
  csrfToken: 'test-csrf',
})

const client = createAuthkitClient({
  baseUrl: 'http://localhost:3333/admin/api',
  csrfToken: 'test',
  fetch: vi.fn().mockResolvedValue(
    new Response(JSON.stringify({ users: [], total: 0 }), { status: 200 })
  ),
})