@quazardous/qdadm 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/api/apiClient.ts

@@ -0,0 +1,34 @@
+/**
+ * Kernel-level default API client (qdadm #1198)
+ *
+ * Apps already build an axios-compatible HttpClient (base URL + auth
+ * interceptors) for their ApiStorages. Registering it once on the kernel
+ * makes it available to composables/widgets that need ad-hoc API calls
+ * (useOptionsLookup endpoint mode, ScopeEditor), so relative endpoints
+ * get base URL + auth applied without per-call wiring:
+ *
+ *   new Kernel({ apiClient: myAxios })
+ */
+import { inject } from 'vue'
+import type { HttpClient } from '../entity/storage/ApiStorage'
+
+/** Injection key under which the kernel provides the default API client. */
+export const API_CLIENT_INJECTION_KEY = 'qdadmApiClient'
+
+/** Accepted forms of the kernel `apiClient` option. */
+export type ApiClientSource = HttpClient | (() => HttpClient)
+
+/** Resolve an ApiClientSource (direct instance or factory) to a client. */
+export function resolveApiClient(source: ApiClientSource | null | undefined): HttpClient | null {
+  if (!source) return null
+  return typeof source === 'function' ? source() : source
+}
+
+/**
+ * Inject the kernel-registered default API client, or null when none is
+ * registered. Must be called from a setup context (like any inject).
+ */
+export function useApiClient(): HttpClient | null {
+  const source = inject<ApiClientSource | null>(API_CLIENT_INJECTION_KEY, null)
+  return resolveApiClient(source)
+}

package/src/components/editors/ScopeEditor.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { ref, computed, onMounted, watch, inject } from 'vue'
+import type { HttpClient } from '../../entity/storage/ApiStorage'
 import AutoComplete from 'primevue/autocomplete'
 import Select from 'primevue/select'
 import Button from 'primevue/button'
@@ -43,8 +44,10 @@ const props = withDefaults(defineProps<Props>(), {
   defaultActions: null
 })
 
-// Get API adapter (optional)
+// Get API adapter (optional); the kernel default client (Kernel({ apiClient }))
+// serves as fallback so scope endpoints get base URL + auth without app wiring.
 const api = inject<ApiAdapter | null>('apiAdapter', null)
+const kernelApiClient = inject<HttpClient | (() => HttpClient) | null>('qdadmApiClient', null)
 
 // Get global scope config (optional) - allows app-level configuration
 const globalScopeConfig = inject<ScopeConfig>('scopeConfig', {})
@@ -178,8 +181,17 @@ function isRowComplete(row: ScopeRow): boolean {
 async function loadScopeDefinition(): Promise<void> {
   loading.value = true
   try {
-    if (!api) {
-      // No API adapter, use defaults
+    let data: ScopeDefinition | null = null
+    if (api) {
+      data = await api.request('GET', config.value.endpoint)
+    } else if (kernelApiClient) {
+      // Fallback: kernel default API client (base URL + auth applied)
+      const client = typeof kernelApiClient === 'function' ? kernelApiClient() : kernelApiClient
+      data = (await client.get<ScopeDefinition>(config.value.endpoint)).data
+    }
+
+    if (!data) {
+      // No API layer available, use defaults
       scopeDefinition.value = {
         resources: [...config.value.resources],
         actions: [...config.value.actions],
@@ -187,7 +199,6 @@ async function loadScopeDefinition(): Promise<void> {
       return
     }
 
-    const data = await api.request('GET', config.value.endpoint)
     scopeDefinition.value = {
       resources: data.resources || [...config.value.resources],
       actions: data.actions || [...config.value.actions],

package/src/composables/useOptionsLookup.ts

@@ -42,6 +42,7 @@
  */
 import { ref, onMounted, type Ref } from 'vue'
 import { useOrchestrator } from '../orchestrator/useOrchestrator.js'
+import { useApiClient } from '../api/apiClient'
 
 export interface OptionsLookupItem {
   label: string
@@ -66,11 +67,27 @@ export interface UseOptionsLookupConfig {
   entity?: string
   /** Extract distinct values from a specific field (entity mode only) */
   field?: string
-  /** Fetch options from a raw API endpoint */
+  /**
+   * Fetch options from an API endpoint.
+   *
+   * Routing (#1198): a **relative** endpoint goes through the kernel's
+   * default API client when one is registered (`Kernel({ apiClient })`) —
+   * base URL + auth applied, no per-call wiring. An **absolute** URL is
+   * fetched raw (escape hatch for third-party APIs, combine with `headers`).
+   * A relative endpoint with no registered client falls back to a raw fetch
+   * (legacy) with a console warning.
+   */
   endpoint?: string
+  /**
+   * Route the endpoint request through the named entity's storage
+   * (`storage.request('GET', endpoint)`) instead of the kernel client —
+   * explicit refinement for multi-API apps. Takes precedence over the
+   * kernel client.
+   */
+  via?: string
   /** When using endpoint: pick a sub-key from the response data */
   pick?: string
-  /** Extra headers for endpoint fetch (e.g. Authorization) */
+  /** Extra headers for the raw-fetch paths (e.g. Authorization) */
   headers?: Record<string, string> | (() => Record<string, string>)
   /** Static options (no fetch needed) */
   static?: unknown[]
@@ -164,10 +181,16 @@ export function useOptionsLookup(config: UseOptionsLookupConfig): UseOptionsLook
       : defaultDecode
   )
 
-  // Resolve orchestrator lazily (only if entity mode)
-  let getManager: ((name: string) => { list: (params?: Record<string, unknown>) => Promise<{ items: unknown[] }> }) | null = null
+  // Resolve orchestrator lazily (entity mode, or via:'entityName' routing)
+  type LookupManager = {
+    list: (params?: Record<string, unknown>) => Promise<{ items: unknown[] }>
+    storage?: {
+      request?: (method: string, path: string, options?: Record<string, unknown>) => Promise<unknown>
+    }
+  }
+  let getManager: ((name: string) => LookupManager) | null = null
 
-  if (config.entity) {
+  if (config.entity || config.via) {
     try {
       const orc = useOrchestrator()
       // Generic-vs-non-generic: getManager is parameterised by an
@@ -180,6 +203,105 @@ export function useOptionsLookup(config: UseOptionsLookupConfig): UseOptionsLook
     }
   }
 
+  // Kernel default API client (Kernel({ apiClient })) — used for relative
+  // endpoints so base URL + auth apply without per-call wiring (#1198).
+  let apiClient: ReturnType<typeof useApiClient> = null
+  if (config.endpoint) {
+    try {
+      apiClient = useApiClient()
+    } catch {
+      // Outside a setup/injection context
+    }
+  }
+
+  // Bare-relative warning: once per composable instance, not per load
+  let warnedBareRelative = false
+
+  function warnLookup(msg: string): void {
+    console.warn(`[qdadm] useOptionsLookup(endpoint: '${config.endpoint}'): ${msg}`)
+  }
+
+  /** Shared normalization for every endpoint path: unwrap data, pick, array-check. */
+  function normalizeEndpointPayload(json: unknown): unknown[] {
+    let data: unknown = (json as { data?: unknown })?.data ?? json
+    if (config.pick && typeof data === 'object' && data !== null && !Array.isArray(data)) {
+      data = (data as Record<string, unknown>)[config.pick]
+    }
+    if (!Array.isArray(data)) {
+      warnLookup('response contained no usable array (after data/pick unwrap) — check the endpoint payload shape')
+      return []
+    }
+    return data
+  }
+
+  /** Endpoint routing (#1198): via storage > relative→kernel client > raw fetch. */
+  async function loadFromEndpoint(): Promise<unknown[]> {
+    const endpoint = config.endpoint!
+    const isAbsolute = /^https?:\/\//i.test(endpoint)
+
+    // 1. via:'entityName' → that entity's storage (explicit refinement)
+    if (config.via && getManager) {
+      const storage = getManager(config.via)?.storage
+      if (storage?.request) {
+        try {
+          const json = await storage.request('GET', endpoint)
+          return normalizeEndpointPayload(json)
+        } catch (err) {
+          warnLookup(`request via '${config.via}' storage failed: ${err instanceof Error ? err.message : err}`)
+          throw err
+        }
+      }
+      warnLookup(`via: '${config.via}' has no storage.request() — falling back to the default routing`)
+    }
+
+    // 2. relative endpoint → kernel default API client (base URL + auth)
+    if (!isAbsolute && apiClient) {
+      try {
+        const { data } = await apiClient.get(endpoint)
+        return normalizeEndpointPayload(data)
+      } catch (err) {
+        warnLookup(`request through the kernel apiClient failed: ${err instanceof Error ? err.message : err}`)
+        throw err
+      }
+    }
+
+    // 3. raw fetch — absolute URL (escape hatch) or legacy relative call
+    if (!isAbsolute && !warnedBareRelative) {
+      warnedBareRelative = true
+      warnLookup(
+        'relative endpoint fetched bare — no API base URL or auth header applied. ' +
+        'Register Kernel({ apiClient }) (recommended), use via: \'entityName\', or pass an absolute URL + headers.'
+      )
+    }
+    const extraHeaders = typeof config.headers === 'function' ? config.headers() : config.headers
+    const response = await fetch(endpoint, {
+      credentials: 'include',
+      headers: { 'Accept': 'application/json', ...extraHeaders },
+    })
+    if (!response.ok) {
+      const authHint = response.status === 401 || response.status === 403
+        ? ' — missing auth? register Kernel({ apiClient }) or pass headers'
+        : ''
+      warnLookup(`HTTP ${response.status}${authHint}`)
+      throw new Error(`HTTP ${response.status}`)
+    }
+    const contentType = response.headers.get('content-type') || ''
+    if (!contentType.includes('json')) {
+      warnLookup(
+        `response is not JSON (content-type: '${contentType || 'unknown'}') — the relative URL likely resolved ` +
+        'to the app origin (HTML page). Register Kernel({ apiClient }) or use an absolute URL.'
+      )
+    }
+    let json: unknown
+    try {
+      json = await response.json()
+    } catch (err) {
+      warnLookup(`response body is not parseable JSON: ${err instanceof Error ? err.message : err}`)
+      throw err
+    }
+    return normalizeEndpointPayload(json)
+  }
+
   // Encoded strings cache for mapped mode (rebuilt on processItems)
   let encodedStrings: string[] = []
 
@@ -255,21 +377,7 @@ export function useOptionsLookup(config: UseOptionsLookupConfig): UseOptionsLook
           items = rawItems
         }
       } else if (config.endpoint) {
-        const extraHeaders = typeof config.headers === 'function' ? config.headers() : config.headers
-        const response = await fetch(config.endpoint, {
-          credentials: 'include',
-          headers: { 'Accept': 'application/json', ...extraHeaders },
-        })
-        if (!response.ok) throw new Error(`HTTP ${response.status}`)
-        const json = await response.json()
-
-        let data = json.data ?? json
-
-        if (config.pick && typeof data === 'object' && !Array.isArray(data)) {
-          data = (data as Record<string, unknown>)[config.pick]
-        }
-
-        items = Array.isArray(data) ? data : []
+        items = await loadFromEndpoint()
       }
 
       processItems(items)

package/src/index.ts

@@ -293,6 +293,12 @@ export {
   type OptionsLookupItem,
   type OptionsDisplayMode,
 } from './composables/useOptionsLookup'
+export {
+  useApiClient,
+  resolveApiClient,
+  API_CLIENT_INJECTION_KEY,
+  type ApiClientSource,
+} from './api/apiClient'
 export { useChildPage, type UseChildPageReturn } from './composables/useChildPage'
 export { useSidebarState, SIDEBAR_COLLAPSED_KEY } from './composables/useSidebarState'
 

package/src/kernel/Kernel.types.ts

@@ -11,6 +11,7 @@ import type { EntityManager } from '../entity/EntityManager'
 import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { RoleProvider } from '../security/RolesProvider'
 import type { I18nOptions } from '../i18n/types'
+import type { ApiClientSource } from '../api/apiClient'
 
 /**
  * Auth adapter interface (app-level authentication)
@@ -183,6 +184,14 @@ export interface KernelOptions {
   debug?: boolean
   onAuthExpired?: (payload: unknown) => void
   i18n?: I18nOptions
+  /**
+   * Default API HTTP client (axios-compatible `HttpClient`, or a factory),
+   * provided to composables/widgets as `qdadmApiClient`. Relative-endpoint
+   * lookups (`useOptionsLookup` endpoint mode, `ScopeEditor` fallback) route
+   * through it so the app's base URL + auth headers apply without per-call
+   * wiring. Typically the same client your ApiStorages use.
+   */
+  apiClient?: ApiClientSource
   /**
    * Existing Vue app to install qdadm onto. When provided, the Kernel
    * skips its own `createApp(WrappedRoot)` and reuses the supplied

package/src/kernel/Kernel.vue.ts

@@ -205,6 +205,12 @@ export function applyVueMethods(KernelClass: { prototype: any }): void {
     app.provide('qdadmActiveStack', this.activeStack)
     app.provide('qdadmStackHydrator', this.stackHydrator)
 
+    if (this.options.apiClient) {
+      // Default API client for composables/widgets (useOptionsLookup,
+      // ScopeEditor) — relative endpoints get base URL + auth (#1198).
+      app.provide('qdadmApiClient', this.options.apiClient)
+    }
+
     if (this.options.debug && typeof window !== 'undefined') {
       const self = this
       // Single namespaced surface for browser-console & agent introspection.