@veristone/nuxt-v-app 0.1.0

package/app/composables/useVCrud.ts

@@ -0,0 +1,647 @@
+/**
+ * useVCrud - Veristone CRUD Composable
+ * Optimized for V-App data flows.
+ * 
+ * Uses $fetch for mutations (POST, PUT, PATCH, DELETE) to avoid Nuxt's useFetch caching issues.
+ * Uses useVFetch only for initial data loading (SSR compatible).
+ */
+
+import { useVToast } from './useVToast'
+
+// --------------------------------------------
+// Route + cache helpers (V-app specific)
+// --------------------------------------------
+
+export const ROUTE_ID_PARAMS = ['id', 'slug', 'uuid', 'itemId', 'recordId'] as const
+
+export function looksLikeId(segment: string): boolean {
+  if (!segment) return false
+
+  // Common ID formats we see across services:
+  // - UUID v4 (and friends)
+  // - CUID
+  // - numeric IDs
+  // - "nanoid-like" strings
+  const isUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(segment)
+  const isCuid = /^c[a-z0-9]{24}$/i.test(segment)
+  const isMongoish = /^[a-z0-9]{24}$/i.test(segment)
+  const isNumeric = /^\d+$/.test(segment)
+  const isNanoish = /^[a-zA-Z0-9_-]{8,26}$/.test(segment)
+
+  return isUuid || isCuid || isMongoish || isNumeric || isNanoish
+}
+
+export function detectViewMode(currentRoute: ReturnType<typeof useRoute>): 'list' | 'detail' {
+  // 1) Explicit params: /resource/:id
+  for (const key of ROUTE_ID_PARAMS) {
+    if (currentRoute?.params?.[key]) return 'detail'
+  }
+
+  // 2) Any param that looks like an ID
+  for (const raw of Object.values(currentRoute?.params || {})) {
+    const val = Array.isArray(raw) ? raw[0] : raw
+    if (val && looksLikeId(String(val))) return 'detail'
+  }
+
+  // 3) Named routes like "users-id" etc
+  const maybeName = String(currentRoute?.name || '')
+  if (/(?:-|_)(id|slug|uuid)$/.test(maybeName) || /-(id|slug|uuid)-/.test(maybeName)) return 'detail'
+
+  // 4) Last path segment like /resource/123
+  const lastPiece = currentRoute?.path?.split('/').filter(Boolean).pop()
+  if (lastPiece && looksLikeId(lastPiece)) return 'detail'
+
+  return 'list'
+}
+
+export function extractCacheKey(endpoint: string): string {
+  // Keep cache keys stable between environments, but strip "noise" prefixes.
+  const ignore = new Set(['api', 'rest', 'v1', 'v2', 'v3'])
+  return (endpoint || '')
+    .split('/')
+    .filter(Boolean)
+    .filter(seg => !ignore.has(seg.toLowerCase()))
+    .join(':')
+}
+
+function getIdFromRoute(
+  currentRoute: ReturnType<typeof useRoute>,
+  paramKey: string
+): ComputedRef<string | number | undefined> {
+  return computed(() => {
+    const candidates = [paramKey, ...ROUTE_ID_PARAMS.filter(p => p !== paramKey)]
+
+    for (const name of candidates) {
+      const raw = currentRoute?.params?.[name]
+      if (!raw) continue
+      const val = Array.isArray(raw) ? raw[0] : raw
+      return val as any
+    }
+
+    for (const raw of Object.values(currentRoute?.params || {})) {
+      const val = Array.isArray(raw) ? raw[0] : raw
+      if (val && looksLikeId(String(val))) return val as any
+    }
+
+    return undefined
+  })
+}
+
+function getParentPath(currentRoute: ReturnType<typeof useRoute>): string {
+  const segments = (currentRoute?.path || '').split('/').filter(Boolean)
+  const actions = new Set(['edit', 'view', 'delete', 'new', 'create'])
+
+  while (segments.length > 0) {
+    const last = segments[segments.length - 1]
+    if (!last) break
+    if (actions.has(last.toLowerCase()) || looksLikeId(last)) segments.pop()
+    else break
+  }
+
+  return segments.length ? `/${segments.join('/')}` : '/'
+}
+
+function getResourcePath(currentRoute: ReturnType<typeof useRoute>): string {
+  // For V-app, the "resource" path is the non-detail location.
+  // Example: /clients/123/edit -> /clients
+  return getParentPath(currentRoute)
+}
+
+function constructUrl(endpoint: string, id?: string | number): string {
+  const base = endpoint.endsWith('/') ? endpoint.slice(0, -1) : endpoint
+  return id === undefined || id === null ? base : `${base}/${id}`
+}
+
+export interface VCrudSort {
+  column: string
+  direction: 'asc' | 'desc'
+}
+
+export interface VCrudOptions<T = any> {
+  idKey?: string
+  paramKey?: string
+  viewMode?: 'list' | 'detail'
+  immediate?: boolean
+  enableToast?: boolean
+  initialFilters?: Record<string, any>
+  initialSort?: VCrudSort | null
+  redirectPath?: string
+  onCreateSuccess?: 'refresh' | 'navigate' | ((item: T) => void)
+  onFetch?: (data: T | T[]) => void
+  onError?: (error: any) => void
+  onCreated?: (item: T) => void
+  onUpdated?: (item: T) => void
+  onDeleted?: () => void
+}
+
+export const useVCrud = <T = any>(endpoint: string, options: VCrudOptions<T> = {}) => {
+  const { success: showSuccess, error: showError } = useVToast()
+  const runtimeConfig = useRuntimeConfig()
+  const currentRoute = useRoute()
+  const router = useRouter()
+
+  const {
+    idKey = 'id',
+    paramKey = 'id',
+    viewMode: forcedViewMode,
+    immediate = true,
+    enableToast = true,
+    initialFilters = {},
+    initialSort = null,
+    redirectPath: redirectOverride,
+    onCreateSuccess = 'refresh',
+    onFetch,
+    onError,
+    onCreated,
+    onUpdated,
+    onDeleted,
+  } = options
+  
+  
+  // Renamed internal state for clarity
+  const isBusy = useState<boolean>(`v-crud-busy-${endpoint}`, () => false)
+  const lastError = useState<string | null>(`v-crud-error-${endpoint}`, () => null)
+
+  // Additional state for parity with useXCrud (kept as refs, not global useState)
+  const viewMode = computed(() => forcedViewMode || detectViewMode(currentRoute))
+  const isListView = computed(() => viewMode.value === 'list')
+  const isDetailView = computed(() => viewMode.value === 'detail')
+
+  const recordId = getIdFromRoute(currentRoute, paramKey)
+  const itemCount = ref(0)
+  const hasRecords = computed(() => itemCount.value > 0)
+
+  const isCreating = ref(false)
+  const isUpdating = ref(false)
+  const isDeleting = ref(false)
+
+  const filterValues = ref<Record<string, any>>({ ...initialFilters })
+  const searchTerm = ref('')
+  const sortConfig = ref<VCrudSort | null>(initialSort)
+
+  // Form state (useful for edit screens and drawer editors)
+  const formData = ref<Partial<T>>({}) as Ref<Partial<T>>
+  const originalFormData = ref<Partial<T>>({}) as Ref<Partial<T>>
+
+  const isFormDirty = computed(() => {
+    // Cheap deep-ish compare; good enough for typical form payloads.
+    return JSON.stringify(formData.value || {}) !== JSON.stringify(originalFormData.value || {})
+  })
+
+  const showDeleteModal = ref(false)
+
+  // Internal: keep the most recently fetched detail record for form sync
+  const detailData = ref<T | null>(null) as Ref<T | null>
+  const listData = ref<T[]>([]) as Ref<T[]>
+
+  const cacheKey = extractCacheKey(endpoint)
+  const cachePrefix = `vcrud:${cacheKey}`
+
+  const notifyOk = (title: string, message?: string) => {
+    if (!enableToast) return
+    showSuccess(title, message)
+  }
+
+  const notifyFail = (title: string, message?: string) => {
+    if (!enableToast) return
+    showError(title, message)
+  }
+
+  // Get auth token for mutations
+  const getAuthHeaders = () => {
+    return {
+      'Content-Type': 'application/json',
+      'X-Client-Version': 'v-app-1.0'
+    }
+  }
+
+  // Get base URL
+  const getBaseUrl = () => (runtimeConfig.public.apiUrl as string) || '/'
+
+  const getMutationHeaders = (body: any) => {
+    const headers = { ...getAuthHeaders() }
+    // If sending multipart, let fetch set boundary headers.
+    if (body instanceof FormData) {
+      delete (headers as any)['Content-Type']
+    }
+    return headers
+  }
+
+  // Internal helper for standardized error handling
+  const handleError = (action: string, err: any) => {
+    const message = err?.data?.message || err?.message || `${action} operation failed.`
+    console.error(`VCrud Error [${action}]:`, err)
+    lastError.value = message
+    if (onError) onError(err)
+    notifyFail(`${action} Failed`, message)
+    throw err
+  }
+
+  // Cache invalidation is opt-in per endpoint; we lean on Nuxt native primitives.
+  const clearCache = async () => {
+    clearNuxtData((key) => key.startsWith(cachePrefix))
+
+    // Refresh is best-effort: some keys may not exist in the current view.
+    try {
+      await refreshNuxtData(`${cachePrefix}:list`)
+    } catch {
+      // No-op
+    }
+    try {
+      await refreshNuxtData(`${cachePrefix}:detail`)
+    } catch {
+      // No-op
+    }
+  }
+
+  const syncFormData = (item: T) => {
+    formData.value = { ...(item as any) }
+    originalFormData.value = { ...(item as any) }
+  }
+
+  const resetFormData = () => {
+    formData.value = { ...(originalFormData.value as any) }
+  }
+
+  const clearFormData = () => {
+    formData.value = {} as Partial<T>
+    originalFormData.value = {} as Partial<T>
+  }
+
+  watch(detailData, (next) => {
+    if (!next) return
+    if (!isDetailView.value) return
+    syncFormData(next)
+  }, { immediate: true })
+
+  const applyFilter = (key: string, value: any) => {
+    filterValues.value[key] = value
+  }
+
+  const resetFilters = () => {
+    filterValues.value = { ...initialFilters }
+    searchTerm.value = ''
+  }
+
+  const applySorting = (column: string, direction: 'asc' | 'desc' = 'asc') => {
+    const current = sortConfig.value
+    if (current?.column === column) {
+      sortConfig.value = {
+        column,
+        direction: direction ?? (current.direction === 'asc' ? 'desc' : 'asc')
+      }
+      return
+    }
+    sortConfig.value = { column, direction }
+  }
+
+  const resetSorting = () => {
+    sortConfig.value = initialSort
+  }
+
+  const navigateBack = async () => {
+    const target = redirectOverride || getParentPath(currentRoute)
+    await navigateTo(target)
+  }
+
+  const navigateToEdit = async () => {
+    const id = recordId.value
+    if (!id) return
+    const base = getResourcePath(currentRoute)
+    await navigateTo(`${base}/${id}/edit`)
+  }
+
+  const openDeleteConfirm = () => {
+    showDeleteModal.value = true
+  }
+
+  const saveRecord = async () => {
+    const localId = (formData.value as any)?.[idKey] ?? recordId.value
+    if (localId !== undefined && localId !== null && String(localId) !== '') {
+      return await update(localId, formData.value)
+    }
+    return await create(formData.value)
+  }
+
+  // CREATE - Uses $fetch for post-mount compatibility
+  const create = async (payload: any) => {
+    isBusy.value = true
+    lastError.value = null
+    isCreating.value = true
+    
+    try {
+      const hasFile = payload instanceof FormData || Object.values(payload || {}).some((v: any) => v instanceof File || v instanceof FileList)
+      let body: any = payload
+
+      if (hasFile && !(payload instanceof FormData)) {
+        body = new FormData()
+        Object.entries(payload || {}).forEach(([k, v]: any) => {
+          if (v instanceof FileList) Array.from(v).forEach(f => body.append(k, f))
+          else if (v instanceof File) body.append(k, v)
+          else if (v !== undefined && v !== null) body.append(k, String(v))
+        })
+      }
+
+      const result = await $fetch<T>(`${getBaseUrl()}${constructUrl(endpoint)}`, {
+        method: 'POST',
+        headers: getMutationHeaders(body),
+        body
+      })
+
+      notifyOk('Success', 'Record created successfully.')
+      if (onCreated) onCreated(result)
+
+      // Post-create behavior stays simple and predictable for V-app.
+      if (onCreateSuccess === 'navigate') {
+        const newId = (result as any)?.[idKey]
+        if (newId !== undefined && newId !== null) {
+          const base = getResourcePath(currentRoute)
+          await navigateTo(`${base}/${newId}`)
+        }
+      } else if (typeof onCreateSuccess === 'function') {
+        onCreateSuccess(result)
+      } else {
+        // Default: refresh list if we're currently in list mode
+        if (isListView.value) {
+          await findAll()
+        }
+      }
+
+      await clearCache()
+      return result
+    } catch (err) {
+      handleError('Create', err)
+    } finally {
+      isCreating.value = false
+      isBusy.value = false
+    }
+  }
+
+  // READ (List) - Uses $fetch for consistent post-mount behavior
+  const findAll = async (params: Record<string, any> = {}) => {
+    isBusy.value = true
+    lastError.value = null
+
+    try {
+      const mergedParams: Record<string, any> = {
+        ...filterValues.value,
+        ...params,
+      }
+
+      if (searchTerm.value) mergedParams.search = searchTerm.value
+      if (sortConfig.value?.column) {
+        mergedParams.sort = sortConfig.value.column
+        mergedParams.order = sortConfig.value.direction
+      }
+
+      const response = await $fetch<any>(`${getBaseUrl()}${constructUrl(endpoint)}`, {
+        method: 'GET',
+        headers: getAuthHeaders(),
+        params: mergedParams
+      })
+
+      // Handle paginated responses: { data: [...], pagination: {...} }
+      // Return just the data array if response is paginated, otherwise return as-is
+      if (response && typeof response === 'object' && 'data' in response && Array.isArray(response.data)) {
+        const total = (response as any)?.pagination?.total ?? (response as any)?.total ?? (response as any)?.count
+        const data = response.data as T[]
+        listData.value = data
+        itemCount.value = typeof total === 'number' ? total : data.length
+        if (onFetch) onFetch(data)
+        return data
+      }
+
+      const data = response as T[]
+      listData.value = Array.isArray(data) ? data : []
+      itemCount.value = Array.isArray(data) ? data.length : 0
+      if (onFetch) onFetch(listData.value)
+      return data
+    } catch (err) {
+      handleError('Fetch', err)
+    } finally {
+      isBusy.value = false
+    }
+  }
+
+  // READ (Single) - Uses $fetch for consistent post-mount behavior
+  const findOne = async (id: string | number) => {
+    isBusy.value = true
+    lastError.value = null
+
+    try {
+      const result = await $fetch<T>(`${getBaseUrl()}${constructUrl(endpoint, id)}`, {
+        method: 'GET',
+        headers: getAuthHeaders()
+      })
+
+      detailData.value = result
+      syncFormData(result)
+      if (onFetch) onFetch(result)
+      return result
+    } catch (err) {
+      handleError('Fetch', err)
+    } finally {
+      isBusy.value = false
+    }
+  }
+
+  // UPDATE - Uses $fetch for post-mount compatibility
+  const update = async (id: string | number, payload: any) => {
+    isBusy.value = true
+    lastError.value = null
+    isUpdating.value = true
+
+    try {
+      const hasFile = payload instanceof FormData || Object.values(payload || {}).some((v: any) => v instanceof File || v instanceof FileList)
+      let body: any = payload
+
+      if (hasFile && !(payload instanceof FormData)) {
+        body = new FormData()
+        Object.entries(payload || {}).forEach(([k, v]: any) => {
+          if (v instanceof FileList) Array.from(v).forEach(f => body.append(k, f))
+          else if (v instanceof File) body.append(k, v)
+          else if (v !== undefined && v !== null) body.append(k, String(v))
+        })
+      }
+
+      const result = await $fetch<T>(`${getBaseUrl()}${constructUrl(endpoint, id)}`, {
+        method: 'PUT',
+        headers: getMutationHeaders(body),
+        body
+      })
+
+      detailData.value = result
+      notifyOk('Saved', 'Changes saved successfully.')
+      if (onUpdated) onUpdated(result)
+      await clearCache()
+      return result
+    } catch (err) {
+      handleError('Update', err)
+    } finally {
+      isUpdating.value = false
+      isBusy.value = false
+    }
+  }
+
+  // PATCH - Uses $fetch for post-mount compatibility
+  const patch = async (id: string | number, payload: any) => {
+    isBusy.value = true
+    lastError.value = null
+    isUpdating.value = true
+
+    try {
+      const hasFile = payload instanceof FormData || Object.values(payload || {}).some((v: any) => v instanceof File || v instanceof FileList)
+      let body: any = payload
+
+      if (hasFile && !(payload instanceof FormData)) {
+        body = new FormData()
+        Object.entries(payload || {}).forEach(([k, v]: any) => {
+          if (v instanceof FileList) Array.from(v).forEach(f => body.append(k, f))
+          else if (v instanceof File) body.append(k, v)
+          else if (v !== undefined && v !== null) body.append(k, String(v))
+        })
+      }
+
+      const result = await $fetch<T>(`${getBaseUrl()}${constructUrl(endpoint, id)}`, {
+        method: 'PATCH',
+        headers: getMutationHeaders(body),
+        body
+      })
+
+      detailData.value = result
+      notifyOk('Saved', 'Record updated.')
+      if (onUpdated) onUpdated(result)
+      await clearCache()
+      return result
+    } catch (err) {
+      handleError('Patch', err)
+    } finally {
+      isUpdating.value = false
+      isBusy.value = false
+    }
+  }
+
+  // DELETE - Uses $fetch for post-mount compatibility
+  const remove = async (id: string | number) => {
+    isBusy.value = true
+    lastError.value = null
+    isDeleting.value = true
+
+    try {
+      await $fetch(`${getBaseUrl()}${constructUrl(endpoint, id)}`, {
+        method: 'DELETE',
+        headers: getAuthHeaders()
+      })
+
+      notifyOk('Deleted', 'Record removed permanently.')
+      if (onDeleted) onDeleted()
+      showDeleteModal.value = false
+      detailData.value = null
+      await clearCache()
+
+      if (isDetailView.value) {
+        await navigateBack()
+      }
+
+      return true
+    } catch (err) {
+      handleError('Delete', err)
+    } finally {
+      isDeleting.value = false
+      isBusy.value = false
+    }
+  }
+
+  // BULK DELETE - Uses $fetch for post-mount compatibility
+  const bulkRemove = async (ids: (string | number)[]) => {
+    isBusy.value = true
+    lastError.value = null
+    isDeleting.value = true
+
+    try {
+      await $fetch(`${getBaseUrl()}${constructUrl(endpoint)}/bulk-delete`, {
+        method: 'DELETE',
+        headers: getAuthHeaders(),
+        body: { ids }
+      })
+
+      notifyOk('Batch Deleted', `${ids.length} records removed.`)
+      if (onDeleted) onDeleted()
+      await clearCache()
+      return true
+    } catch (err) {
+      handleError('Bulk Delete', err)
+    } finally {
+      isDeleting.value = false
+      isBusy.value = false
+    }
+  }
+
+  // Auto-refresh list view when list inputs change.
+  watch([filterValues, searchTerm, sortConfig], async () => {
+    if (!isListView.value) return
+    await findAll()
+  }, { deep: true })
+
+  // Auto-fetch detail data when route id changes.
+  watch(recordId, async (next) => {
+    if (!isDetailView.value) return
+    if (next === undefined || next === null || String(next) === '') return
+    await findOne(next)
+  })
+
+  // Initial fetch (keeps existing behavior: only fetch when called, unless opted in)
+  if (immediate) {
+    if (isListView.value) {
+      // Fire and forget to avoid blocking setup.
+      findAll().catch(() => {})
+    } else if (isDetailView.value && recordId.value !== undefined && recordId.value !== null) {
+      findOne(recordId.value).catch(() => {})
+    }
+  }
+
+  // Expose API with original names to maintain compatibility
+  return {
+    create,
+    findAll,
+    findOne,
+    update,
+    patch,
+    remove,
+    bulkRemove,
+    loading: isBusy, // Alias internal 'isBusy' to public 'loading'
+    errorState: lastError, // Alias internal 'lastError' to public 'errorState'
+
+    // New exports (useXCrud parity, V-app naming)
+    viewMode,
+    isListView,
+    isDetailView,
+    recordId,
+    itemCount,
+    hasRecords,
+    isCreating,
+    isUpdating,
+    isDeleting,
+    filterValues,
+    searchTerm,
+    sortConfig,
+    applyFilter,
+    applySorting,
+    resetFilters,
+    resetSorting,
+    formData,
+    isFormDirty,
+    resetFormData,
+    clearFormData,
+    navigateBack,
+    navigateToEdit,
+    openDeleteConfirm,
+    showDeleteModal,
+    saveRecord,
+    clearCache,
+
+    // Expose router bits for advanced flows without requiring imports
+    currentRoute,
+    router,
+  }
+}

package/app/composables/useVFetch.ts

@@ -0,0 +1,46 @@
+/**
+ * useVFetch - Veristone Authenticated Fetcher
+ * Integrates with Nuxt V Auth Stack.
+ */
+import type { UseFetchOptions } from 'nuxt/app'
+import { useVToast } from './useVToast'
+
+export async function useVFetch<T>(
+  endpoint: string,
+  opts: UseFetchOptions<T> = {},
+  actionLabel: string = 'API Request'
+) {
+  const { error: notifyError } = useVToast()
+  const runtimeConfig = useRuntimeConfig()
+
+  // Construct Base Config
+  const fetchConfig: UseFetchOptions<T> = {
+    baseURL: (runtimeConfig.public.apiUrl as string) || '/',
+    retry: 1,
+    retryStatusCodes: [408, 409, 429, 500, 502, 503, 504], // Extended retry codes
+    headers: {
+      'X-Client-Version': 'v-app-1.0',
+      ...opts.headers
+    },
+    
+    // Response Interceptor
+    onResponseError: async ({ response }) => {
+      const status = response.status
+      if (status === 401) {
+        notifyError('Authentication Required', 'This action requires authentication.')
+      } else if (status >= 500) {
+        console.error(`[VFetch] Server Error (${status}):`, response.statusText)
+        // notifyError('Server Error', 'Our services are experiencing issues.')
+      }
+    }
+  }
+
+  // Merge options, excluding headers which we handled above
+  const { headers, ...otherOpts } = opts
+  
+  // @ts-ignore - TypeScript has difficulty inferring the merged options type
+  return useFetch<T>(endpoint, {
+    ...fetchConfig,
+    ...otherOpts
+  })
+}