@sbc-connect/nuxt-pay 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @sbc-connect/nuxt-pay
 
+## 0.5.0
+
+### Minor Changes
+
+- [#172](https://github.com/bcgov/connect-nuxt/pull/172) [`c9e5d05`](https://github.com/bcgov/connect-nuxt/commit/c9e5d0519aff914196c38242f3a827473261af38) Thanks [@deetz99](https://github.com/deetz99)! - Implement useConnectPayQuery query defintions, useConnectPayService cache abstraction and update usage in connect-fee store.
+
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [[`d91712d`](https://github.com/bcgov/connect-nuxt/commit/d91712db74c2e0c6b39f6fd38955fd60e82ce691)]:
+  - @sbc-connect/nuxt-auth@0.12.0
+
 ## 0.4.0
 
 ### Minor Changes

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 './pay'

package/app/services/pay/index.ts

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

package/app/services/pay/mutate.ts

@@ -0,0 +1 @@
+// TBD

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

@@ -0,0 +1,24 @@
+// https://pinia-colada.esm.dev/guide/query-keys.html
+
+/**
+ * IMPORTANT: Query Key Hierarchy
+ * * Our cache follows a strict hierarchy: ['connect', 'pay', accountId, ...rest].
+ * * 1. Account ID: The 'base' (accountId) 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 useConnectPayQueryKeys = () => {
+  const { currentAccount } = storeToRefs(useConnectAccountStore())
+
+  const base = () => ['connect', 'pay', currentAccount.value?.id] as const
+
+  const keys = {
+    fee: (entityType: string, code: string, params: { priority?: boolean, futureEffective?: boolean } = {}) =>
+      [...base(), 'fee', entityType, code, params] as const,
+    payAccount: (accountId: string | number) => [...base(), 'pay-account', accountId] as const
+  }
+
+  return { keys }
+}

package/app/services/pay/query.ts

@@ -0,0 +1,64 @@
+// 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 useConnectPayQuery = () => {
+  const { $payApi } = useNuxtApp()
+  const { keys } = useConnectPayQueryKeys()
+
+  function feeOptions(
+    entityType: string,
+    code: string,
+    params?: { priority?: boolean, futureEffective?: boolean },
+    options?: DefineOptions<ConnectFeeItem>) {
+    return defineQueryOptions({
+      query: () => $payApi<ConnectFeeItem>(`/fees/${entityType}/${code}`, { params }),
+      staleTime: DEFAULT_STALE_TIME,
+      ...options,
+      key: keys.fee(entityType, code, params)
+    })
+  }
+
+  function fee(
+    entityType: string,
+    code: string,
+    params?: { priority?: boolean, futureEffective?: boolean },
+    options?: QueryOptions<ConnectFeeItem>) {
+    return useQuery(() => feeOptions(entityType, code, params, options as DefineOptions<ConnectFeeItem>))
+  }
+
+  function payAccountOptions(
+    accountId: string | number,
+    options?: DefineOptions<ConnectPayAccount>) {
+    return defineQueryOptions({
+      query: () => $payApi<ConnectPayAccount>(`/accounts/${accountId}`),
+      staleTime: DEFAULT_STALE_TIME,
+      ...options,
+      key: keys.payAccount(accountId)
+    })
+  }
+
+  function payAccount(
+    accountId: string | number,
+    options?: QueryOptions<ConnectPayAccount>) {
+    return useQuery(() => payAccountOptions(accountId, options as DefineOptions<ConnectPayAccount>))
+  }
+
+  return {
+    feeOptions,
+    fee,
+    payAccountOptions,
+    payAccount
+  }
+}

package/app/services/pay/service.ts

@@ -0,0 +1,30 @@
+import { getCachedOrFetch } from '../helpers'
+
+export const useConnectPayService = () => {
+  const query = useConnectPayQuery()
+
+  /* GET Requests */
+
+  async function getFee(
+    entityType: string,
+    code: string,
+    params?: { priority?: boolean, futureEffective?: boolean },
+    force = false
+  ): Promise<ConnectFeeItem> {
+    const options = query.feeOptions(entityType, code, params)
+    return await getCachedOrFetch(options, force)
+  }
+
+  async function getPayAccount(
+    accountId: string | number,
+    force = false
+  ): Promise<ConnectPayAccount> {
+    const options = query.payAccountOptions(accountId)
+    return await getCachedOrFetch(options, force)
+  }
+
+  return {
+    getFee,
+    getPayAccount
+  }
+}

package/app/stores/connect-fee.ts

@@ -1,5 +1,5 @@
 export const useConnectFeeStore = defineStore('connect-pay-fee-store', () => {
-  const { $payApi } = useNuxtApp()
+  const service = useConnectPayService()
   const { t } = useNuxtApp().$i18n
   const { baseModal } = useConnectModal()
 
@@ -139,7 +139,7 @@ export const useConnectFeeStore = defineStore('connect-pay-fee-store', () => {
         priority: true,
         futureEffective: true
       }
-      return await $payApi<ConnectFeeItem>(`/fees/${entityType}/${code}`, { params })
+      return await service.getFee(entityType, code, params)
     } catch (error) {
       console.error('Error fetching Fee: ', error)
     }
@@ -226,13 +226,13 @@ export const useConnectFeeStore = defineStore('connect-pay-fee-store', () => {
     const accountId = useConnectAccountStore().currentAccount.id
     try {
       // get payment account
-      const res = await $payApi<ConnectPayAccount>(`/accounts/${accountId}`)
-      userPaymentAccount.value = res
+      userPaymentAccount.value = await service.getPayAccount(accountId)
+      const { cfsAccount } = userPaymentAccount.value
 
       // add options to allowedPaymentMethods
       let defaultMethod = userPaymentAccount.value.paymentMethod
       if (defaultMethod !== undefined) {
-        const accountNum = userPaymentAccount.value.cfsAccount?.bankAccountNumber ?? ''
+        const accountNum = cfsAccount?.bankAccountNumber ?? ''
         allowedPaymentMethods.value.push({
           label: t(`connect.payMethod.label.${defaultMethod}`, { account: accountNum }),
           value: defaultMethod
@@ -245,7 +245,7 @@ export const useConnectFeeStore = defineStore('connect-pay-fee-store', () => {
             value: ConnectPayMethod.DIRECT_PAY
           })
           // if pad in confirmation period then set default payment to CC
-          if (PAD_PENDING_STATES.includes(res.cfsAccount?.status)) {
+          if (PAD_PENDING_STATES.includes(cfsAccount?.status)) {
             defaultMethod = ConnectPayMethod.DIRECT_PAY
           }
         }

package/nuxt.config.ts

@@ -13,7 +13,7 @@ export default defineNuxtConfig({
   extends: ['@sbc-connect/nuxt-auth'],
 
   imports: {
-    dirs: ['interfaces', 'enums', 'stores']
+    dirs: ['interfaces', 'enums', 'stores', 'services']
   },
 
   alias: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sbc-connect/nuxt-pay",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "repository": "github:bcgov/connect-nuxt",
   "license": "BSD-3-Clause",
   "main": "./nuxt.config.ts",
@@ -11,12 +11,12 @@
     "nuxt": "4.4.6",
     "typescript": "6.0.3",
     "vue-tsc": "3.3.1",
-    "@sbc-connect/eslint-config": "0.0.8",
+    "@sbc-connect/playwright-config": "0.2.0",
     "@sbc-connect/vitest-config": "0.2.0",
-    "@sbc-connect/playwright-config": "0.2.0"
+    "@sbc-connect/eslint-config": "0.0.8"
   },
   "dependencies": {
-    "@sbc-connect/nuxt-auth": "0.11.1"
+    "@sbc-connect/nuxt-auth": "0.12.0"
   },
   "scripts": {
     "preinstall": "npx only-allow pnpm",
@@ -29,6 +29,7 @@
     "lint:fix": "eslint --fix .",
     "test": "pnpm run test:unit; pnpm run test:e2e",
     "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
     "test:unit:cov": "vitest --dir tests/unit --coverage",
     "test:e2e": "npx playwright test",
     "test:e2e:ui": "npx playwright test --ui",