chore: standardize protocol

Signed-off-by: Sebastian Krupinski <krupinski01@gmail.com>

src/stores/providersStore.ts

@@ -12,59 +12,60 @@ export const useProvidersStore = defineStore('mailProvidersStore', () => {
   // State
   const _providers = ref<Record<string, ProviderObject>>({})
   const transceiving = ref(false)
-  const error = ref<string | null>(null)
 
-  // Getters
+  /**
+   * Get count of providers in store
+   */
   const count = computed(() => Object.keys(_providers.value).length)
+
+  /**
+   * Check if any providers are present in store
+   */
   const has = computed(() => count.value > 0)
 
   /**
-   * Get providers as an array
-   * @returns Array of provider objects
+   * Get all providers present in store
    */
   const providers = computed(() => Object.values(_providers.value))
 
   /**
-   * Get a specific provider by identifier from cache
+   * Get a specific provider from store, with optional retrieval
+   * 
    * @param identifier - Provider identifier
+   * @param retrieve - Retrieve behavior: true = fetch if missing or refresh, false = cache only
+   * 
    * @returns Provider object or null
    */
-  function provider(identifier: string): ProviderObject | null {
+  function provider(identifier: string, retrieve: boolean = false): ProviderObject | null {
+    if (retrieve === true && !_providers.value[identifier]) {
+      console.debug(`[Mail Manager][Store] - Force fetching provider "${identifier}"`)
+      fetch(identifier)
+    }
+    
     return _providers.value[identifier] || null
   }
 
   // Actions
+
   /**
-   * Retrieve all or specific providers
+   * Retrieve all or specific providers, optionally filtered by source selector
+   * 
+   * @param request - list request parameters
+   * 
+   * @returns Promise with provider object list keyed by provider identifier
    */
   async function list(sources?: SourceSelector): Promise<Record<string, ProviderObject>> {
     transceiving.value = true
-    error.value = null
     try {
-      const response = await providerService.list({ sources })
+      const providers = await providerService.list({ sources })
 
-      console.debug('[Mail Manager](Store) - Successfully retrieved', Object.keys(response).length, 'providers')
+      // Merge retrieved providers into state
+      _providers.value = { ..._providers.value, ...providers }
 
-      _providers.value = response
-      return response
-    } catch (err: any) {
-      console.error('[Mail Manager](Store) - Failed to retrieve providers:', err)
-      error.value = err.message
-      throw err
-    } finally {
-      transceiving.value = false
-    }
-  }
-
-  /**
-   * Fetch a specific provider
-   */
-  async function fetch(identifier: string): Promise<ProviderObject> {
-    transceiving.value = true
-    try {
-      return await providerService.fetch({ identifier })
+      console.debug('[Mail Manager][Store] - Successfully retrieved', Object.keys(providers).length, 'providers')
+      return providers
     } catch (error: any) {
-      console.error('[Mail Manager](Store) - Failed to fetch provider:', error)
+      console.error('[Mail Manager][Store] - Failed to retrieve providers:', error)
       throw error
     } finally {
       transceiving.value = false
@@ -72,19 +73,53 @@ export const useProvidersStore = defineStore('mailProvidersStore', () => {
   }
 
   /**
-   * Check which providers exist/are available
+   * Retrieve a specific provider by identifier
+   * 
+   * @param identifier - provider identifier
+   * 
+   * @returns Promise with provider object
+   */
+  async function fetch(identifier: string): Promise<ProviderObject> {
+    transceiving.value = true
+    try {
+      const provider = await providerService.fetch({ identifier })
+
+      // Merge fetched provider into state
+      _providers.value[provider.identifier] = provider
+
+      console.debug('[Mail Manager][Store] - Successfully fetched provider:', provider.identifier)
+      return provider
+    } catch (error: any) {
+      console.error('[Mail Manager][Store] - Failed to fetch provider:', error)
+      throw error
+    } finally {
+      transceiving.value = false
+    }
+  }
+
+  /**
+   * Retrieve provider availability status for a given source selector
+   * 
+   * @param sources - source selector to check availability for
+   * 
+   * @returns Promise with provider availability status
    */
   async function extant(sources: SourceSelector) {
     transceiving.value = true
-    error.value = null
     try {
       const response = await providerService.extant({ sources })
-      console.debug('[Mail Manager](Store) - Successfully checked', sources ? Object.keys(sources).length : 0, 'providers')
+
+      Object.entries(response).forEach(([providerId, providerStatus]) => {
+        if (providerStatus === false) {
+          delete _providers.value[providerId]
+        }
+      })
+
+      console.debug('[Mail Manager][Store] - Successfully checked', sources ? Object.keys(sources).length : 0, 'providers')
       return response
-    } catch (err: any) {
-      console.error('[Mail Manager](Store) - Failed to check providers:', err)
-      error.value = err.message
-      throw err
+    } catch (error: any) {
+      console.error('[Mail Manager][Store] - Failed to check providers:', error)
+      throw error
     } finally {
       transceiving.value = false
     }
@@ -94,7 +129,6 @@ export const useProvidersStore = defineStore('mailProvidersStore', () => {
   return {
     // State
     transceiving: readonly(transceiving),
-    error: readonly(error),
     // computed
     count,
     has,