@sbc-connect/nuxt-auth 0.11.0 → 0.12.0

package/app/plugins/connect-auth.client.ts

@@ -1,112 +1,126 @@
 import Keycloak from 'keycloak-js'
 import { ConnectModalSessionExpired } from '#components'
 
-export default defineNuxtPlugin(async () => {
-  const rtc = useRuntimeConfig().public
-
-  // define new keycloak
-  const keycloak = new Keycloak({
-    url: rtc.idpUrl,
-    realm: rtc.idpRealm,
-    clientId: rtc.idpClientid
-  })
-
-  const tokenRefreshInterval = rtc.tokenRefreshInterval ? Number(rtc.tokenRefreshInterval) : 30000
-  const tokenMinValidity = rtc.tokenMinValidity ? Number(rtc.tokenMinValidity) / 1000 : 120
-  const sessionInactivityTimeout = rtc.sessionInactivityTimeout ? Number(rtc.sessionInactivityTimeout) : 1800000
-
-  // Logout via Keycloak, redirecting to the login page with a return param preserving the user's current URL.
-  // The return value is double-encoded so it survives the Keycloak redirect decode
-  // without the original query params bleeding into the login page's query string.
-  function logoutWithReturn(kc: Keycloak) {
-    const localePath = useLocalePath()
-    const route = useRoute()
-    const loginPath = localePath('/auth/login')
-    const currentUrl = `${window.location.origin}${route.fullPath}`
-    const returnUrl = encodeURIComponent(encodeURIComponent(currentUrl))
-    const redirectUri = `${window.location.origin}${loginPath}?return=${returnUrl}`
-    kc.logout({ redirectUri })
-  }
+export default defineNuxtPlugin({
+  name: 'connect-auth',
+  order: -20,
+  parallel: true,
+  async setup(nuxtApp) {
+    const rtc = nuxtApp.$config.public
 
-  try {
-    // default behaviour when keycloak session expires
-    // try to update token - log out if token update fails
-    // callbacks must be registered before 'init'
-    // https://www.keycloak.org/securing-apps/javascript-adapter#_callback_events
-    keycloak.onTokenExpired = async () => {
-      try {
-        console.info('[Auth] Token expired, refreshing token...')
-        await keycloak.updateToken(tokenMinValidity)
-        console.info('[Auth] Token refreshed.')
-      } catch (error) {
-        console.error('[Auth] Failed to refresh token on expiration; logging out.', error)
-        logoutWithReturn(keycloak)
-      }
-    }
-
-    // init keycloak instance
-    await keycloak.init({
-      onLoad: 'check-sso',
-      responseMode: 'query',
-      pkceMethod: 'S256'
+    // define new keycloak
+    const keycloak = new Keycloak({
+      url: rtc.idpUrl,
+      realm: rtc.idpRealm,
+      clientId: rtc.idpClientid
     })
-  } catch (error) {
-    console.error('[Auth] Failed to initialize Keycloak adapter: ', error)
-  }
 
-  const { idle } = useIdle(sessionInactivityTimeout)
+    const tokenRefreshInterval = rtc.tokenRefreshInterval ? Number(rtc.tokenRefreshInterval) : 30000
+    const tokenMinValidity = rtc.tokenMinValidity ? Number(rtc.tokenMinValidity) / 1000 : 120
+    const sessionInactivityTimeout = rtc.sessionInactivityTimeout ? Number(rtc.sessionInactivityTimeout) : 1800000
 
-  // executed when user is authenticated and idle = true
-  async function sessionExpired() {
-    const overlay = useOverlay()
-    const modal = overlay.create(ConnectModalSessionExpired)
-    modal.open()
-  }
+    // Logout via Keycloak, redirecting to the login page with a return param preserving the user's current URL.
+    // The return value is double-encoded so it survives the Keycloak redirect decode
+    // without the original query params bleeding into the login page's query string.
+    function logoutWithReturn(kc: Keycloak) {
+      const localePath = useLocalePath()
+      const route = useRoute()
+      const loginPath = localePath('/auth/login')
+      const currentUrl = `${window.location.origin}${route.fullPath}`
+      const returnUrl = encodeURIComponent(encodeURIComponent(currentUrl))
+      const redirectUri = `${window.location.origin}${loginPath}?return=${returnUrl}`
+      kc.logout({ redirectUri })
+    }
 
-  // refresh token if expiring within <tokenMinValidity> - checks every <tokenRefreshInterval>
-  function scheduleRefreshToken() {
-    console.info('[Auth] Verifying token validity.')
+    try {
+    // callbacks must be registered before 'init'
+    // https://www.keycloak.org/securing-apps/javascript-adapter#_callback_events
 
-    setTimeout(async () => {
-      if (keycloak.isTokenExpired(tokenMinValidity)) {
-        console.info('[Auth] Token set to expire soon. Refreshing token...')
+      // default behaviour when keycloak session expires
+      // try to update token - log out if token update fails
+      keycloak.onTokenExpired = async () => {
         try {
+          console.info('[Auth] Token expired, refreshing token...')
           await keycloak.updateToken(tokenMinValidity)
           console.info('[Auth] Token refreshed.')
         } catch (error) {
-          console.error('[Auth] Failed to refresh token; logging out.', error)
+          console.error('[Auth] Failed to refresh token on expiration; logging out.', error)
           logoutWithReturn(keycloak)
         }
       }
 
-      scheduleRefreshToken()
-    }, tokenRefreshInterval)
-  }
+      keycloak.onAuthSuccess = async () => {
+        await nuxtApp.callHook('connect:auth:refresh', { token: keycloak.token })
+      }
 
-  // Watch for changes in authentication and idle state
-  // When the user is authenticated and not idle, start the refresh schedule
-  // Execute session expiry handling if user authenticated and inactive
-  watch(
-    [() => keycloak.authenticated, () => idle.value],
-    async ([isAuth, isIdle]) => {
-      if (isAuth) {
-        sessionStorage.removeItem(ConnectAuthStorageKey.CONNECT_SESSION_EXPIRED)
-        if (!isIdle) {
-          console.info('[Auth] Starting token refresh schedule.')
-          scheduleRefreshToken()
-        } else {
-          console.warn('[Auth] User session expired due to inactivity. Starting session expiry process.')
-          await sessionExpired()
-        }
+      keycloak.onAuthRefreshSuccess = async () => {
+        await nuxtApp.callHook('connect:auth:refresh', { token: keycloak.token })
       }
-    },
-    { immediate: true }
-  )
 
-  return {
-    provide: {
+      // init keycloak instance
+      await keycloak.init({
+        onLoad: 'check-sso',
+        responseMode: 'query',
+        pkceMethod: 'S256'
+      })
+    } catch (error) {
+      console.error('[Auth] Failed to initialize Keycloak adapter: ', error)
+    }
+
+    const { idle } = useIdle(sessionInactivityTimeout)
+
+    // executed when user is authenticated and idle = true
+    async function sessionExpired() {
+      const overlay = useOverlay()
+      const modal = overlay.create(ConnectModalSessionExpired)
+      modal.open()
+    }
+
+    // refresh token if expiring within <tokenMinValidity> - checks every <tokenRefreshInterval>
+    function scheduleRefreshToken() {
+      console.info('[Auth] Verifying token validity.')
+
+      setTimeout(async () => {
+        if (keycloak.isTokenExpired(tokenMinValidity)) {
+          console.info('[Auth] Token set to expire soon. Refreshing token...')
+          try {
+            await keycloak.updateToken(tokenMinValidity)
+            console.info('[Auth] Token refreshed.')
+          } catch (error) {
+            console.error('[Auth] Failed to refresh token; logging out.', error)
+            logoutWithReturn(keycloak)
+          }
+        }
+
+        scheduleRefreshToken()
+      }, tokenRefreshInterval)
+    }
+
+    // Watch for changes in authentication and idle state
+    // When the user is authenticated and not idle, start the refresh schedule
+    // Execute session expiry handling if user authenticated and inactive
+    watch(
+      [() => keycloak.authenticated, () => idle.value],
+      async ([isAuth, isIdle]) => {
+        if (isAuth) {
+          sessionStorage.removeItem(ConnectAuthStorageKey.CONNECT_SESSION_EXPIRED)
+          if (!isIdle) {
+            console.info('[Auth] Starting token refresh schedule.')
+            scheduleRefreshToken()
+          } else {
+            console.warn('[Auth] User session expired due to inactivity. Starting session expiry process.')
+            await sessionExpired()
+          }
+        }
+      },
+      { immediate: true }
+    )
+
+    return {
+      provide: {
       // provide global auth instance
-      connectAuth: keycloak
+        connectAuth: keycloak
+      }
     }
   }
 })

package/app/services/auth/index.ts

@@ -0,0 +1,4 @@
+export * from './mutate'
+export * from './query'
+export * from './query-keys'
+export * from './service'

package/app/services/auth/mutate.ts

@@ -0,0 +1,83 @@
+// https://pinia-colada.esm.dev/guide/mutations.html
+
+export const useConnectAuthMutation = () => {
+  const service = useConnectAuthService()
+  const { keys } = useConnectAuthQueryKeys()
+  const queryCache = useQueryCache()
+
+  /**
+   * Creates an account by POSTing the given payload to `/orgs`.
+   * @returns Object containing mutation state and `createAccount` function.
+   */
+  const createAccount = defineMutation({
+    mutation: (vars: {
+      payload: ConnectCreateAccount
+      silent?: boolean
+      successCb?: (createRes: ConnectAuthProfile) => Promise<unknown>
+    }) => service.createAccount(vars.payload),
+    onError: (_, _vars) => {
+      if (!_vars.silent) {
+        useConnectAuthModals().openCreateAccountModal()
+      }
+    },
+    onSuccess: async (_, _vars) => {
+      await queryCache.invalidateQueries({ key: keys.userSettings(), exact: true })
+      if (_vars.successCb) {
+        await _vars.successCb(_)
+      }
+    }
+  })
+
+  /**
+   * Updates a users contact by PUTing the given payload to `/users/contacts`.
+   * @returns Object containing mutation state and `updateUserContact` function.
+   */
+  const updateOrCreateUserContact = defineMutation({
+    mutation: (vars: {
+      payload: { email: string, phone: string, phoneExtension: string | undefined }
+      method?: 'POST' | 'PUT'
+      silent?: boolean
+      successCb?: () => Promise<unknown> | unknown
+      errorCb?: (error: unknown) => Promise<unknown> | unknown
+    }) => service.updateOrCreateUserContact(vars.payload, vars.method),
+    onError: async (error, _vars) => {
+      if (!_vars.silent) {
+        useConnectAuthModals().openUpdateUserContactModal()
+      }
+      if (_vars.errorCb) {
+        await _vars.errorCb(error)
+      }
+    },
+    onSuccess: async (_, _vars) => {
+      await queryCache.invalidateQueries({ key: keys.userProfile(), exact: true })
+      if (_vars.successCb) {
+        await _vars.successCb()
+      }
+    }
+  })
+
+  const updateTermsOfUse = defineMutation({
+    mutation: (vars: {
+      payload: { accepted: boolean, version: string }
+      silent?: boolean
+      successCb?: () => Promise<unknown> | unknown
+    }) => service.updateTermsOfUse(vars.payload),
+    onError: (_, _vars) => {
+      if (!_vars.silent) {
+        useConnectAuthModals().openPatchTosErrorModal()
+      }
+    },
+    onSuccess: async (_, _vars) => {
+      await queryCache.invalidateQueries({ key: keys.userProfile(), exact: true })
+      if (_vars.successCb) {
+        await _vars.successCb()
+      }
+    }
+  })
+
+  return {
+    createAccount,
+    updateOrCreateUserContact,
+    updateTermsOfUse
+  }
+}

package/app/services/auth/query-keys.ts

@@ -0,0 +1,26 @@
+// https://pinia-colada.esm.dev/guide/query-keys.html
+
+/**
+ * IMPORTANT: Query Key Hierarchy
+ * * Our cache follows a strict hierarchy: ['connect', 'auth', keycloakGuid, ...rest].
+ * * 1. GUID ISOLATION: The 'base' (keycloakGuid) MUST remain as the first dynamic segment.
+ * This allows us to invalidate an entire "folder" by targeting the parent key.
+ * * 2. ORDER: When updating keys, ensure the order of existing segments is preserved.
+ * Changing the order may break existing invalidation logic across the app.
+*/
+
+export const useConnectAuthQueryKeys = () => {
+  const { authUser } = useConnectAuth()
+  const { currentAccount } = storeToRefs(useConnectAccountStore())
+
+  const base = () => ['connect', 'auth', authUser.value?.keycloakGuid] as const
+
+  const keys = {
+    userProfile: () => [...base(), 'user-profile'] as const,
+    pendingApprovals: () => [...base(), 'org', currentAccount.value?.id, 'pending-approvals'] as const,
+    termsOfUse: () => [...base(), 'terms-of-use'] as const,
+    userSettings: () => [...base(), 'user-settings'] as const
+  }
+
+  return { keys }
+}

package/app/services/auth/query.ts

@@ -0,0 +1,87 @@
+// IMPORTANT: Query definitions are for GET requests only - for all other methods define a mutation in the ./mutate file
+// https://pinia-colada.esm.dev/guide/queries.html
+import { useQuery } from '@pinia/colada'
+import type { UseQueryOptions, DefineQueryOptions } from '@pinia/colada'
+
+type QueryOptions<T> = Omit<UseQueryOptions<T>, 'key' | 'query'> & {
+  query?: UseQueryOptions<T>['query']
+}
+
+type DefineOptions<TData, TError = Error> = Omit<DefineQueryOptions<TData, TError>, 'key' | 'query'> & {
+  query?: DefineQueryOptions<TData, TError>['query']
+}
+
+const DEFAULT_STALE_TIME = 60000
+
+export const useConnectAuthQuery = () => {
+  const { $authApi } = useNuxtApp()
+  const { keys } = useConnectAuthQueryKeys()
+
+  function pendingApprovalsOptions(options?: DefineOptions<{ count: number }>) {
+    const accountId = useConnectAccountStore().currentAccount?.id
+    const keycloakGuid = useConnectAuth().authUser.value?.keycloakGuid
+    return defineQueryOptions({
+      query: () => $authApi<{ count: number }>(`/users/${keycloakGuid}/org/${accountId}/notifications`),
+      staleTime: DEFAULT_STALE_TIME,
+      enabled: !!(accountId && keycloakGuid),
+      ...options,
+      key: keys.pendingApprovals()
+    })
+  }
+
+  function pendingApprovals(options?: QueryOptions<{ count: number }>) {
+    return useQuery(() => pendingApprovalsOptions(options as DefineOptions<{ count: number }>))
+  }
+
+  function termsOfUseOptions(options?: DefineOptions<ConnectTermsOfUse>) {
+    return defineQueryOptions({
+      query: () => $authApi<ConnectTermsOfUse>('/documents/termsofuse'),
+      staleTime: DEFAULT_STALE_TIME,
+      ...options,
+      key: keys.termsOfUse()
+    })
+  }
+
+  function termsOfUse(options?: QueryOptions<ConnectTermsOfUse>) {
+    return useQuery(() => termsOfUseOptions(options as DefineOptions<ConnectTermsOfUse>))
+  }
+
+  function userProfileOptions(options?: DefineOptions<ConnectAuthProfile>) {
+    return defineQueryOptions({
+      query: () => $authApi<ConnectAuthProfile>('/users/@me', { parseResponse: JSON.parse }),
+      staleTime: DEFAULT_STALE_TIME,
+      ...options,
+      key: keys.userProfile()
+    })
+  }
+
+  function userProfile(options?: QueryOptions<ConnectAuthProfile>) {
+    return useQuery(() => userProfileOptions(options as DefineOptions<ConnectAuthProfile>))
+  }
+
+  function userSettingsOptions(options?: DefineOptions<ConnectUserSettings[]>) {
+    const keycloakGuid = useConnectAuth().authUser.value?.keycloakGuid
+    return defineQueryOptions({
+      query: () => $authApi<ConnectUserSettings[]>(`/users/${keycloakGuid}/settings`),
+      staleTime: DEFAULT_STALE_TIME,
+      enabled: !!keycloakGuid,
+      ...options,
+      key: keys.userSettings()
+    })
+  }
+
+  function userSettings(options?: QueryOptions<ConnectUserSettings[]>) {
+    return useQuery(() => userSettingsOptions(options as DefineOptions<ConnectUserSettings[]>))
+  }
+
+  return {
+    pendingApprovalsOptions,
+    pendingApprovals,
+    termsOfUse,
+    termsOfUseOptions,
+    userProfileOptions,
+    userProfile,
+    userSettingsOptions,
+    userSettings
+  }
+}

package/app/services/auth/service.ts

@@ -0,0 +1,125 @@
+// IMPORTANT: This service is an abstraction layer for non-reactive contexts (stores, middleware, or sequential logic).
+// IMPORTANT: Pure GET requests bound to UI components should NOT be defined here;
+// define those using query options/composables directly.
+import { getCachedOrFetch } from '../helpers'
+
+/**
+ * AUTH SERVICE
+ *
+ * This service provides a way to execute auth requests while maintaining the cache layer
+ * outside of the reactive Vue lifecycle.
+ *
+ * * USE THIS SERVICE ONLY IF:
+ * - You are inside a pinia store and need to "await" data.
+ * - You are in a route guard/middleware and need to validate data before entry.
+ * - You need to await multiple API calls sequentially (promise.all/setup logic).
+ *
+ * * DO NOT USE THIS SERVICE IF:
+ * - You are inside a Vue Component.
+ * - You need to display "isLoading" or "error" states in the UI.
+ * - You want automatic background refetching and observer management.
+ *
+ * * COMPONENT USAGE:
+ * Always prefer queries or mutations directly in components.
+*/
+
+// Example:
+
+// Incorrect Component setup
+//
+// const service = useConnectAuthService()
+// const loading = ref(true)
+// const accounts = ref()
+// We have to manually manage everything
+// onMounted(async () => {
+//   try {
+//    accounts.value = await service.getUserAccounts()
+//   } catch (e) {
+//     ...handle error
+//   } finally {
+//     loading.value = false
+//   }
+// })
+
+// Correct Component setup
+// const query = useConnectAuthQuery()
+// One line handles loading, data, reactivity, and caching
+// const { data: userSettings, isLoading } = query.getUserSettings()
+
+export const useConnectAuthService = () => {
+  const query = useConnectAuthQuery()
+  const { $authApi } = useNuxtApp()
+
+  /* GET Requests */
+
+  async function getAuthUserProfile(force = false): Promise<ConnectAuthProfile> {
+    const options = query.userProfileOptions()
+    return await getCachedOrFetch(options, force)
+  }
+
+  async function getTermsOfUse(force = false): Promise<ConnectTermsOfUse> {
+    const options = query.termsOfUseOptions()
+    return await getCachedOrFetch(options, force)
+  }
+
+  async function getUserAccounts(force = false): Promise<ConnectAccount[]> {
+    const options = query.userSettingsOptions()
+    return await getCachedOrFetch(options, force)
+      .then(res => res?.filter(setting => setting.type === UserSettingsType.ACCOUNT)) as ConnectAccount[]
+  }
+
+  // Cache exception - do not cache to verify the account name accurately
+  async function verifyAccountName(accountName: string) {
+    return await $authApi.raw(`/orgs?validateName=true&name=${encodeURIComponent(accountName)}`)
+  }
+
+  /* POST, PUT, PATCH, DELETE Requests */
+
+  async function createAccount(payload: ConnectCreateAccount): Promise<ConnectAuthProfile> {
+    return $authApi<ConnectAuthProfile>('/orgs', {
+      method: 'POST',
+      body: payload
+    })
+  }
+
+  /** Update user information in AUTH with current token info */
+  async function updateAuthUserProfile(): Promise<ConnectAuthProfile> {
+    return await $authApi('/users', {
+      method: 'POST',
+      body: { isLogin: true }
+    })
+  }
+
+  async function updateOrCreateUserContact(
+    payload: { email: string, phone: string, phoneExtension: string | undefined },
+    method?: 'POST' | 'PUT'
+  ): Promise<ConnectAuthProfile> {
+    return $authApi<ConnectAuthProfile>('/users/contacts', {
+      method: method || 'PUT',
+      body: payload
+    })
+  }
+
+  async function updateTermsOfUse(payload: { accepted: boolean, version: string }): Promise<ConnectAuthProfile> {
+    return await $authApi<ConnectAuthProfile>('/users/@me', {
+      method: 'PATCH',
+      body: {
+        istermsaccepted: payload.accepted,
+        termsversion: payload.version
+      }
+    })
+  }
+
+  return {
+    /* GET Requests */
+    getAuthUserProfile,
+    getTermsOfUse,
+    getUserAccounts,
+    verifyAccountName,
+    /* POST, PUT, PATCH, DELETE Requests */
+    createAccount,
+    updateAuthUserProfile,
+    updateOrCreateUserContact,
+    updateTermsOfUse
+  }
+}

package/app/services/helpers/get-cached-or-fetch.ts

@@ -0,0 +1,43 @@
+import type { DefineQueryOptions } from '@pinia/colada'
+
+/**
+ * Resolves a query from the cache or fetches it from the network if necessary.
+ * * This utility ensures a cache entry exists and handles data fetching
+ * based on the current cache state and the `force` flag.
+ *
+ * @template TData - The expected shape of the data returned by the query.
+ * @template TError - The error type if the query fails. Defaults to `Error`.
+ * * @param options - The query definition object
+ * containing the key, query function, and cache settings (e.g., staleTime).
+ * @param [force=false] - When true, bypasses the cache and triggers
+ * a network call (cache.fetch). When false, returns cached data if fresh,
+ * or background refreshes if stale or in error state (cache.refresh).
+ * * @returns A promise that resolves to the query data.
+ * @throws throws the underlying network error if the fetch or refresh fails.
+ * * @example
+ * // uses cache if fresh
+ * const business = await getCachedOrFetch(businessOptions('BC123'));
+ * * // Forced fetch: ignores cache and hits API
+ * const freshData = await getCachedOrFetch(businessOptions('BC123'), true);
+*/
+export async function getCachedOrFetch<TData>(
+  options: DefineQueryOptions<TData>,
+  force = false
+): Promise<TData> {
+  const cache = useQueryCache()
+  // NB: Required to prevent calls within 1ms causing a promise to return before the cached response is complete.
+  // i.e. without below:
+  // -> Call 1 for BC1234567 data
+  // -> Call 2 for BC1234567 data within 1ms
+  // -> Call 1 is cancelled
+  // -> Promise returns with undefined response from Call 1 instead of awaiting Call 2
+  await new Promise(resolve => setTimeout(resolve, 1))
+  // Ensures a query entry is present in the cache.
+  // will create one if it doesn't exist
+  const entry = cache.ensure(options)
+  const result = force
+    ? await cache.fetch(entry)
+    : await cache.refresh(entry)
+
+  return result.data!
+}

package/app/services/helpers/index.ts

@@ -0,0 +1 @@
+export * from './get-cached-or-fetch'

package/app/services/index.ts

@@ -0,0 +1 @@
+export * from './auth'