refinement phase 2

client/src/services/auth/hooks/useRoleHydration.ts

@@ -0,0 +1,28 @@
+import { useMe } from './useMe';
+import { toAppRoles } from '../routing';
+import type { Me } from '../types';
+import type { AppRole } from '@/constants';
+
+/**
+ * The resolved-vs-pending role state for a private route. The core refinement-phase-2 fix: a shell must
+ * distinguish **"/me hasn't resolved yet"** from **"the user has no nurse/admin role"** — conflating the
+ * two is what silently showed a nurse the customer app (a fresh `/me` in-flight fell through the
+ * `DEFAULT_ROLE = customer` fallback). This exposes that distinction so `RoleGuard` can render a neutral
+ * loading state while pending, an explicit error state when `/me` failed, and only route on a resolved
+ * role set.
+ *
+ * `error` fires only when `/me` has no data at all; a background refetch that fails while we still hold a
+ * cached identity keeps serving `ready` (don't downgrade a known nurse on a transient blip).
+ */
+export type RoleHydration =
+  | { status: 'loading' }
+  | { status: 'error'; retry: () => void; isRetrying: boolean }
+  | { status: 'ready'; me: Me; appRoles: AppRole[] };
+
+export function useRoleHydration(): RoleHydration {
+  const { data: me, isError, isFetching, refetch } = useMe();
+
+  if (me) return { status: 'ready', me, appRoles: toAppRoles(me.roles) };
+  if (isError) return { status: 'error', retry: () => void refetch(), isRetrying: isFetching };
+  return { status: 'loading' };
+}

client/src/services/auth/index.ts

@@ -5,3 +5,5 @@ export { useRefresh } from './hooks/useRefresh';
 export { useLogout } from './hooks/useLogout';
 export { useSelectRole } from './hooks/useSelectRole';
 export { useSessionRoleSync } from './hooks/useSessionRoleSync';
+export { useRoleHydration } from './hooks/useRoleHydration';
+export type { RoleHydration } from './hooks/useRoleHydration';