@woodsportal/hubspot-kit 1.0.41 → 1.0.42-dev.0

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/login-email-storage.ts

@@ -0,0 +1,64 @@
+import { WP_STORAGE_KEYS } from 'woodsportal-client-sdk'
+
+const LOGIN_EMAIL_KEY = WP_STORAGE_KEYS.c.login.email
+
+function isValidEmail(value: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim())
+}
+
+export function extractLoginEmailFromPayload(
+  payload: Record<string, unknown> | null | undefined,
+): string | null {
+  if (!payload || typeof payload !== 'object') {
+    return null
+  }
+  const loggedInDetails = payload.loggedInDetails
+  if (loggedInDetails && typeof loggedInDetails === 'object') {
+    const email = (loggedInDetails as Record<string, unknown>).email
+    if (typeof email === 'string' && isValidEmail(email)) {
+      return email.trim().toLowerCase()
+    }
+  }
+  for (const key of ['email', 'username'] as const) {
+    const value = payload[key]
+    if (typeof value === 'string' && isValidEmail(value)) {
+      return value.trim().toLowerCase()
+    }
+  }
+  return null
+}
+
+export function captureLoginEmailBeforeSessionClear(
+  resolveLoggedInEmail?: () => string | null | undefined,
+): void {
+  if (getStoredLoginEmail()) {
+    return
+  }
+  const email = resolveLoggedInEmail?.()
+  if (email) {
+    setStoredLoginEmail(email)
+  }
+}
+
+export function getStoredLoginEmail(): string | null {
+  if (typeof window === 'undefined') {
+    return null
+  }
+  const stored = sessionStorage.getItem(LOGIN_EMAIL_KEY)?.trim().toLowerCase() ?? ''
+  return stored && isValidEmail(stored) ? stored : null
+}
+
+export function setStoredLoginEmail(email: string): void {
+  if (typeof window === 'undefined') {
+    return
+  }
+  const normalized = email.trim().toLowerCase()
+  if (!isValidEmail(normalized)) {
+    return
+  }
+  sessionStorage.setItem(LOGIN_EMAIL_KEY, normalized)
+}
+
+export function clearLoginPreAuthSession(): void {
+  // starter scaffold: no pre-login passkey state
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/login-session-bridge.ts

@@ -0,0 +1,74 @@
+import { api } from '@/integrations/woodsportal-sdk'
+import {
+  navigateAfterFullAuth,
+  navigateToMfaGate,
+  type AuthNavigationRouter,
+} from '@/features/auth/auth-navigation'
+import { clearMfaPendingState, storeMfaPendingContext } from '@/features/auth/mfa-pending-storage'
+import { resolvePostLoginPath } from '@/features/auth/resolve-post-login-path'
+import { AUTH_SESSION_CHANGED } from '@/features/auth/auth-session-events'
+import { signalSessionChanged, storeMfaPendingAccessToken } from 'woodsportal-client-sdk'
+import {
+  extractLoginEmailFromPayload,
+  setStoredLoginEmail,
+} from '@/features/auth/login-email-storage'
+
+function notifyAuthSessionChanged(): void {
+  if (typeof window === 'undefined') return
+  signalSessionChanged('login')
+  window.dispatchEvent(new CustomEvent(AUTH_SESSION_CHANGED))
+}
+
+type AuthRouter = AuthNavigationRouter
+
+function unwrapLoginPayload(
+  response: { data?: Record<string, unknown>; statusMsg?: string } | Record<string, unknown>,
+): Record<string, unknown> {
+  return (response?.data ?? response ?? {}) as Record<string, unknown>
+}
+
+export type HandleAuthLoginResponseOptions = {
+  clearPreHashQuery?: () => void
+  onSubscriptionType?: (subscriptionType: string) => void
+}
+
+export type HandleAuthLoginResponseResult =
+  | { success: false; reason: 'no_token' }
+  | { success: true; mfaRequired: true }
+  | { success: true; mfaRequired: false }
+
+export async function handleAuthLoginResponse(
+  response: { data?: Record<string, unknown>; statusMsg?: string } | Record<string, unknown>,
+  router: AuthRouter,
+  options: HandleAuthLoginResponseOptions = {},
+): Promise<HandleAuthLoginResponseResult> {
+  const data = unwrapLoginPayload(response)
+  const tokenData = (data.tokenData ?? {}) as { token?: string; expiresIn?: number }
+  const sessionToken = api.auth.session.getAccessToken()
+  const token = tokenData.token ?? sessionToken ?? undefined
+
+  if (!token) {
+    return { success: false, reason: 'no_token' }
+  }
+
+  const loginEmail = extractLoginEmailFromPayload(data)
+  if (loginEmail) {
+    setStoredLoginEmail(loginEmail)
+  }
+
+  if (data.twoFactorRequired === true) {
+    storeMfaPendingContext(data)
+    storeMfaPendingAccessToken('c', token, tokenData.expiresIn)
+    api.auth.session.setAccessToken(token, tokenData.expiresIn)
+    options.clearPreHashQuery?.()
+    notifyAuthSessionChanged()
+    navigateToMfaGate(router)
+    return { success: true, mfaRequired: true }
+  }
+
+  clearMfaPendingState()
+  options.clearPreHashQuery?.()
+  notifyAuthSessionChanged()
+  navigateAfterFullAuth(router, resolvePostLoginPath(router))
+  return { success: true, mfaRequired: false }
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/mfa-otp-utils.ts

@@ -0,0 +1,24 @@
+import type { MfaMethod } from '@/integrations/woodsportal-sdk'
+
+const OTP_DELIVERY_METHODS: MfaMethod[] = ['EMAIL_OTP', 'SMS_OTP']
+
+export const MFA_OTP_RESEND_COOLDOWN_MS = 30_000
+
+export function isOtpDeliveryMethod(method: MfaMethod): boolean {
+  return OTP_DELIVERY_METHODS.includes(method)
+}
+
+export function getResendSecondsLeft(cooldownUntil: number | null): number {
+  if (cooldownUntil == null) {
+    return 0
+  }
+  return Math.max(0, Math.ceil((cooldownUntil - Date.now()) / 1000))
+}
+
+export function normalizeOtpCode(value: string): string {
+  return value.replace(/\D/g, '').slice(0, 6)
+}
+
+export function isValidOtpCode(value: string): boolean {
+  return /^\d{6}$/.test(normalizeOtpCode(value))
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/mfa-pending-storage.ts

@@ -0,0 +1,108 @@
+import type { MfaMethod, MfaMethodOption } from '@/integrations/woodsportal-sdk'
+import { clearMfaPendingAccessToken, WP_STORAGE_KEYS } from 'woodsportal-client-sdk'
+
+const MFA_METHODS_KEY = WP_STORAGE_KEYS.c.mfa.methods
+const MFA_DEFAULT_METHOD_KEY = WP_STORAGE_KEYS.c.mfa.default
+const MFA_OTP_DELIVERY_KEY = WP_STORAGE_KEYS.c.mfa.otp
+const MFA_OTP_MASKED_KEY = WP_STORAGE_KEYS.c.mfa.otp
+const MFA_SCOPE_KEY = WP_STORAGE_KEYS.c.mfa.scope
+const MFA_PORTAL_ID_KEY = WP_STORAGE_KEYS.c.mfa.portalId
+const MFA_PORTAL_NAME_KEY = WP_STORAGE_KEYS.c.mfa.portalName
+const MFA_PORTAL_URL_KEY = WP_STORAGE_KEYS.c.mfa.portalUrl
+
+export type MfaPendingContext = {
+  methods: Array<MfaMethodOption>
+  defaultMethod: MfaMethod
+  otpDelivery?: string
+  otpDestination?: string
+  scopeKey?: string
+  portalId?: number
+  portalName?: string
+  portalUrl?: string
+}
+
+function readOptionalString(payload: Record<string, unknown>, key: string): string | undefined {
+  const value = payload[key]
+  if (value == null || value === '') {
+    return undefined
+  }
+  return String(value)
+}
+
+function readOptionalNumber(payload: Record<string, unknown>, key: string): number | undefined {
+  const value = payload[key]
+  if (value == null || value === '') {
+    return undefined
+  }
+  const parsed = Number(value)
+  return Number.isNaN(parsed) ? undefined : parsed
+}
+
+export function storeMfaPendingContext(payload: Record<string, unknown>): void {
+  sessionStorage.setItem(MFA_METHODS_KEY, JSON.stringify(payload.mfaMethods ?? []))
+  sessionStorage.setItem(MFA_DEFAULT_METHOD_KEY, String(payload.defaultMethod ?? 'EMAIL_OTP'))
+  const otpDestination =
+    typeof payload.otpDestination === 'string'
+      ? payload.otpDestination
+      : typeof payload.otpDestinationMasked === 'string'
+        ? payload.otpDestinationMasked
+        : undefined
+  if (payload.otpDelivery != null) {
+    sessionStorage.setItem(MFA_OTP_DELIVERY_KEY, String(payload.otpDelivery))
+  }
+  if (otpDestination != null) {
+    sessionStorage.setItem(MFA_OTP_MASKED_KEY, otpDestination)
+  }
+  const portalId = readOptionalNumber(payload, 'portalId')
+  if (readOptionalString(payload, 'scopeKey')) {
+    sessionStorage.setItem(MFA_SCOPE_KEY, readOptionalString(payload, 'scopeKey')!)
+  }
+  if (portalId != null) {
+    sessionStorage.setItem(MFA_PORTAL_ID_KEY, String(portalId))
+  }
+  if (readOptionalString(payload, 'portalName')) {
+    sessionStorage.setItem(MFA_PORTAL_NAME_KEY, readOptionalString(payload, 'portalName')!)
+  }
+  if (readOptionalString(payload, 'portalUrl')) {
+    sessionStorage.setItem(MFA_PORTAL_URL_KEY, readOptionalString(payload, 'portalUrl')!)
+  }
+}
+
+export function getMfaPendingContext(): MfaPendingContext | null {
+  const methodsRaw = sessionStorage.getItem(MFA_METHODS_KEY)
+  if (!methodsRaw) {
+    return null
+  }
+  let methods: Array<MfaMethodOption> = []
+  try {
+    methods = JSON.parse(methodsRaw) as Array<MfaMethodOption>
+  } catch {
+    methods = []
+  }
+  const defaultMethod = (sessionStorage.getItem(MFA_DEFAULT_METHOD_KEY) ?? 'EMAIL_OTP') as MfaMethod
+  const portalIdRaw = sessionStorage.getItem(MFA_PORTAL_ID_KEY)
+  const portalId =
+    portalIdRaw != null && portalIdRaw !== '' ? Number(portalIdRaw) : undefined
+  return {
+    methods,
+    defaultMethod,
+    otpDelivery: sessionStorage.getItem(MFA_OTP_DELIVERY_KEY) ?? undefined,
+    otpDestination: sessionStorage.getItem(MFA_OTP_MASKED_KEY) ?? undefined,
+    scopeKey: sessionStorage.getItem(MFA_SCOPE_KEY) ?? undefined,
+    portalId: portalId != null && !Number.isNaN(portalId) ? portalId : undefined,
+    portalName: sessionStorage.getItem(MFA_PORTAL_NAME_KEY) ?? undefined,
+    portalUrl: sessionStorage.getItem(MFA_PORTAL_URL_KEY) ?? undefined,
+  }
+}
+
+export function clearMfaPendingState(): void {
+  sessionStorage.removeItem(MFA_METHODS_KEY)
+  sessionStorage.removeItem(MFA_DEFAULT_METHOD_KEY)
+  sessionStorage.removeItem(MFA_OTP_DELIVERY_KEY)
+  sessionStorage.removeItem(MFA_OTP_MASKED_KEY)
+  sessionStorage.removeItem(MFA_SCOPE_KEY)
+  sessionStorage.removeItem(MFA_PORTAL_ID_KEY)
+  sessionStorage.removeItem(MFA_PORTAL_NAME_KEY)
+  sessionStorage.removeItem(MFA_PORTAL_URL_KEY)
+  clearMfaPendingAccessToken('c')
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/mfa-portal.ts

@@ -0,0 +1,45 @@
+import { env } from '@/env'
+import { getMfaPendingContext } from '@/features/auth/mfa-pending-storage'
+
+export type MfaPortalContext = {
+  portalId?: number
+  portalName?: string
+  portalUrl?: string
+  scopeKey?: string
+}
+
+function parsePortalId(value: unknown): number | undefined {
+  if (value == null || value === '') {
+    return undefined
+  }
+  const parsed = Number(value)
+  return Number.isNaN(parsed) ? undefined : parsed
+}
+
+export function resolveMfaPortalContext(): MfaPortalContext {
+  const pending = getMfaPendingContext()
+  if (pending?.portalId != null) {
+    return {
+      portalId: pending.portalId,
+      portalName: pending.portalName,
+      portalUrl: pending.portalUrl,
+      scopeKey: pending.scopeKey,
+    }
+  }
+  if (env.VITE_DEV_PORTAL_ID != null && env.VITE_DEV_PORTAL_ID !== '') {
+    return { portalId: parsePortalId(env.VITE_DEV_PORTAL_ID) }
+  }
+  const hubPortalId =
+    typeof window !== 'undefined'
+      ? (window as Window & { hubSpotData?: { portalId?: unknown } }).hubSpotData?.portalId
+      : undefined
+  const parsed = parsePortalId(hubPortalId)
+  if (parsed != null) {
+    return { portalId: parsed }
+  }
+  return {}
+}
+
+export function resolveMfaPortalId(): number | undefined {
+  return resolveMfaPortalContext().portalId
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/post-login-path.ts

@@ -0,0 +1,17 @@
+import { Routes } from '@/config/routes'
+import { normalizeRouterPath } from '@/utils/normalize-router-path'
+
+const AUTH_RETURN_PATHS = new Set<string>([
+  Routes.login,
+  Routes.twoFa,
+  Routes.unauthorized,
+  Routes.ssoLogin,
+])
+
+export function isBlockedPostLoginPath(path: string): boolean {
+  const normalized = normalizeRouterPath(path)
+  if (AUTH_RETURN_PATHS.has(normalized)) {
+    return true
+  }
+  return normalized.startsWith('/login')
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/resolve-auth-login-error-message.ts

@@ -0,0 +1,52 @@
+const GENERIC_AUTH_FAILED_MESSAGES = new Set([
+  'Authentication Failed',
+  'Invalid credentials provided.',
+])
+
+type LoginErrorPayload = {
+  errorCode?: unknown
+  errorMessage?: unknown
+  validationErrors?: unknown
+}
+
+function extractFirstValidationMessage(validationErrors: unknown): string | null {
+  if (validationErrors == null || typeof validationErrors !== 'object') {
+    return null
+  }
+  const first = Object.values(validationErrors as Record<string, unknown>)[0]
+  if (typeof first === 'string') {
+    return first
+  }
+  if (Array.isArray(first) && typeof first[0] === 'string') {
+    return first[0]
+  }
+  return null
+}
+
+export function resolveAuthLoginErrorMessage(error: unknown): string {
+  const fallback = 'Wrong email or password'
+  if (error == null || typeof error !== 'object') {
+    return fallback
+  }
+  const data = (error as { response?: { data?: LoginErrorPayload } }).response?.data
+  if (!data) {
+    return fallback
+  }
+  const validationMessage = extractFirstValidationMessage(data.validationErrors)
+  if (validationMessage) {
+    return validationMessage
+  }
+  const errorCode = typeof data.errorCode === 'string' ? data.errorCode : undefined
+  const errorMessage =
+    typeof data.errorMessage === 'string' ? data.errorMessage.trim() : ''
+  if (!errorMessage) {
+    return fallback
+  }
+  if (
+    errorCode === 'AUTHENTICATION_FAILED' &&
+    GENERIC_AUTH_FAILED_MESSAGES.has(errorMessage)
+  ) {
+    return fallback
+  }
+  return errorMessage
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/resolve-post-login-path.ts

@@ -0,0 +1,21 @@
+import { Routes } from '@/config/routes'
+import { isBlockedPostLoginPath } from '@/features/auth/post-login-path'
+import { normalizeRouterPath } from '@/utils/normalize-router-path'
+import type { SafeAuthRouter } from '@/utils/safe-router-navigation'
+
+export type PostLoginRouter = SafeAuthRouter & {
+  state: {
+    location?: {
+      search?: { r?: string; [key: string]: string | undefined }
+      pathname?: string
+    }
+  }
+}
+
+export function resolvePostLoginPath(router: PostLoginRouter): string {
+  const redirect = router.state.location?.search?.r
+  if (redirect && !isBlockedPostLoginPath(String(redirect))) {
+    return normalizeRouterPath(String(redirect))
+  }
+  return Routes.portal
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/sso-callback.ts

@@ -0,0 +1,120 @@
+import { Routes } from '@/config/routes'
+import { readHashPathname } from '@/features/auth/auth-route-paths'
+import { normalizeRouterPath } from '@/utils/normalize-router-path'
+
+export type SsoCallbackParams = {
+  code: string
+  state: string
+}
+
+export const SSO_CALLBACK_EXCHANGE_TIMEOUT_MS = 30_000
+
+const processedKeys = new Set<string>()
+
+export function buildSsoCallbackKey(code: string, state: string): string {
+  return `${code}:${state}`
+}
+
+export function normalizeOAuthQueryValue(value: unknown): string {
+  if (typeof value === 'string') {
+    return value.trim()
+  }
+  if (Array.isArray(value)) {
+    const first = value.find((entry) => typeof entry === 'string' && entry.trim())
+    return typeof first === 'string' ? first.trim() : ''
+  }
+  return ''
+}
+
+export function parseSsoCallbackParams(
+  routeSearch?: { code?: unknown; state?: unknown },
+): SsoCallbackParams {
+  const fromRoute = {
+    code: normalizeOAuthQueryValue(routeSearch?.code),
+    state: normalizeOAuthQueryValue(routeSearch?.state),
+  }
+  if (fromRoute.code && fromRoute.state) {
+    return fromRoute
+  }
+  if (typeof window === 'undefined') {
+    return { code: '', state: '' }
+  }
+  const hashPart = window.location.hash || ''
+  const queryFromHash = hashPart.includes('?') ? hashPart.split('?')[1] : ''
+  const searchParams = new URLSearchParams(queryFromHash || window.location.search)
+  return {
+    code: searchParams.get('code')?.trim() ?? '',
+    state: searchParams.get('state')?.trim() ?? '',
+  }
+}
+
+export function hasOAuthCallbackInUrl(routeSearch?: { code?: unknown; state?: unknown }): boolean {
+  const { code, state } = parseSsoCallbackParams(routeSearch)
+  return Boolean(code && state)
+}
+
+export function clearPreHashQueryParams(): void {
+  if (typeof window === 'undefined' || !window.location.search) {
+    return
+  }
+  window.history.replaceState(null, '', `${window.location.pathname}${window.location.hash}`)
+}
+
+export function isSsoCallbackAlreadyProcessed(key: string): boolean {
+  return processedKeys.has(key)
+}
+
+export function markSsoCallbackProcessed(key: string): void {
+  processedKeys.add(key)
+}
+
+export async function withSsoCallbackTimeout<T>(promise: Promise<T>): Promise<T> {
+  return Promise.race([
+    promise,
+    new Promise<T>((_, reject) => {
+      window.setTimeout(
+        () => reject(new Error('sso_callback_timeout')),
+        SSO_CALLBACK_EXCHANGE_TIMEOUT_MS,
+      )
+    }),
+  ])
+}
+
+const exchangeLocks = new Map<string, Promise<void>>()
+
+export async function runSharedSsoCallbackExchange(
+  key: string,
+  exchange: () => Promise<void>,
+): Promise<void> {
+  const existing = exchangeLocks.get(key)
+  if (existing) {
+    return existing
+  }
+  const run = exchange().finally(() => {
+    exchangeLocks.delete(key)
+  })
+  exchangeLocks.set(key, run)
+  return run
+}
+
+export function ensureSsoCallbackRoute(): boolean {
+  if (typeof window === 'undefined') {
+    return false
+  }
+  const { code, state } = parseSsoCallbackParams()
+  if (!code || !state) {
+    return false
+  }
+  const hashPath = readHashPathname()
+  if (normalizeRouterPath(hashPath) === Routes.ssoLogin) {
+    if (window.location.search) {
+      clearPreHashQueryParams()
+    }
+    return true
+  }
+  if (window.location.search) {
+    clearPreHashQueryParams()
+  }
+  window.location.hash = `#${Routes.ssoLogin}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(state)}`
+  return true
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/use-mfa-login-otp-flow.ts

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useState } from 'react'
+import { toast } from 'sonner'
+import type { MfaMethod } from '@/integrations/woodsportal-sdk'
+import { api } from '@/integrations/woodsportal-sdk'
+import { getMfaPendingContext } from '@/features/auth/mfa-pending-storage'
+import {
+  getResendSecondsLeft,
+  isValidOtpCode,
+  MFA_OTP_RESEND_COOLDOWN_MS,
+  normalizeOtpCode,
+} from '@/features/auth/mfa-otp-utils'
+import { resolveMfaPortalId } from '@/features/auth/mfa-portal'
+
+export function useMfaLoginOtpFlow() {
+  const pending = getMfaPendingContext()
+  const [method, setMethod] = useState<MfaMethod>(pending?.defaultMethod ?? 'EMAIL_OTP')
+  const [otp, setOtp] = useState('')
+  const [isSending, setIsSending] = useState(false)
+  const [isVerifying, setIsVerifying] = useState(false)
+  const [cooldownUntil, setCooldownUntil] = useState<number | null>(null)
+
+  const resendSecondsLeft = getResendSecondsLeft(cooldownUntil)
+
+  const sendOtp = useCallback(async () => {
+    if (resendSecondsLeft > 0) {
+      return
+    }
+    setIsSending(true)
+    try {
+      const portalId = resolveMfaPortalId()
+      const { sendOtp: send } = api.auth.mfa.sendOtp()
+      await send({ method, portalId })
+      setCooldownUntil(Date.now() + MFA_OTP_RESEND_COOLDOWN_MS)
+      toast.success('Verification code sent')
+    } catch {
+      toast.error('Could not send verification code')
+    } finally {
+      setIsSending(false)
+    }
+  }, [method, resendSecondsLeft])
+
+  useEffect(() => {
+    void sendOtp()
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- auto-send once on MFA gate mount
+  }, [])
+
+  const verifyOtp = async () => {
+    const code = normalizeOtpCode(otp)
+    if (!isValidOtpCode(code)) {
+      toast.error('Enter the 6-digit code')
+      return null
+    }
+    setIsVerifying(true)
+    try {
+      const portalId = resolveMfaPortalId()
+      const { verifyOtp: verify } = api.auth.mfa.verifyOtp()
+      return await verify({ method, otp: code, portalId })
+    } catch {
+      toast.error('Invalid or expired code')
+      return null
+    } finally {
+      setIsVerifying(false)
+    }
+  }
+
+  return {
+    method,
+    setMethod,
+    otp,
+    setOtp,
+    destination: pending?.otpDestination,
+    isSending,
+    isVerifying,
+    resendSecondsLeft,
+    sendOtp,
+    verifyOtp,
+  }
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/use-portal-session.ts

@@ -0,0 +1,25 @@
+import { useEffect, useMemo, useState } from 'react'
+import { AUTH_SESSION_CHANGED } from '@/features/auth/auth-session-events'
+import { isFullyAuthenticatedSession, isMfaPendingSession } from '@/features/auth/auth-session'
+
+function useAuthSessionRevision(): number {
+  const [revision, setRevision] = useState(0)
+  useEffect(() => {
+    const bump = () => setRevision((value) => value + 1)
+    window.addEventListener(AUTH_SESSION_CHANGED, bump)
+    return () => window.removeEventListener(AUTH_SESSION_CHANGED, bump)
+  }, [])
+  return revision
+}
+
+export { useAuthSessionRevision }
+
+export function usePortalSession(): boolean {
+  const revision = useAuthSessionRevision()
+  return useMemo(() => isFullyAuthenticatedSession(), [revision])
+}
+
+export function useIsMfaPendingSession(): boolean {
+  const revision = useAuthSessionRevision()
+  return useMemo(() => isMfaPendingSession(), [revision])
+}

package/examples/greenfield/module-hybrid-cdn-auth-full/src/features/auth/use-signed-in-email.ts

@@ -0,0 +1,55 @@
+import { useEffect, useState } from 'react'
+
+import { api } from '@/integrations/woodsportal-sdk'
+import { getStoredLoginEmail } from '@/features/auth/login-email-storage'
+import { usePortalSession } from '@/features/auth/use-portal-session'
+
+function readEmailFromProfile(data: unknown): string | null {
+  if (data == null || typeof data !== 'object') {
+    return null
+  }
+  const root = data as Record<string, unknown>
+  const profile = (root.data ?? root) as Record<string, unknown>
+  const email = profile.email
+  return typeof email === 'string' && email.trim() !== '' ? email.trim() : null
+}
+
+export function useSignedInEmail(): { email: string | null; isLoading: boolean } {
+  const isAuthenticated = usePortalSession()
+  const [email, setEmail] = useState<string | null>(() => getStoredLoginEmail())
+  const [isLoading, setIsLoading] = useState(false)
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      setEmail(null)
+      setIsLoading(false)
+      return
+    }
+
+    const stored = getStoredLoginEmail()
+    if (stored) {
+      setEmail(stored)
+      return
+    }
+
+    setIsLoading(true)
+    const { me } = api.auth.me({
+      onSuccess: (data) => {
+        setEmail(readEmailFromProfile(data) ?? getStoredLoginEmail())
+        setIsLoading(false)
+      },
+      onError: () => {
+        setEmail(getStoredLoginEmail())
+        setIsLoading(false)
+      },
+      onLoadingChange: (loading) => {
+        if (!loading) {
+          setIsLoading(false)
+        }
+      },
+    })
+    void me()
+  }, [isAuthenticated])
+
+  return { email, isLoading }
+}