@fayz-ai/saas 0.1.6

package/src/shell/hooks/index.ts

@@ -0,0 +1,18 @@
+export { useAuth } from './useAuth'
+export { useTenant } from './useTenant'
+export { usePermission } from './usePermission'
+export { useLayout } from './useLayout'
+export { useBilling } from './useBilling'
+export { useNotifications } from './useNotifications'
+export { useTranslation } from './useTranslation'
+export { useFormatters } from './useFormatters'
+export { useChat } from './useChat'
+export { useAITools } from './useAITools'
+export type { ResolvedSuggestion, ResolvedToolGroup, ResolvedToolEntry } from './useAITools'
+export { usePlugins, usePluginsOptional, useWidgets } from './usePlugins'
+export { useTenantPlugins } from './useTenantPlugins'
+export { useModuleNavigation } from './useModuleNavigation'
+export type { NavDirection, DepthMap } from './useModuleNavigation'
+export { usePluginPrefs, getPluginPref, setPluginPref } from './usePluginPrefs'
+export type { PluginPrefs } from './usePluginPrefs'
+export { useFieldRules } from './useFieldRules'

package/src/shell/hooks/useAITools.ts

@@ -0,0 +1,139 @@
+import * as React from 'react'
+import { usePluginRuntimeOptional } from '../lib/plugins'
+import { coreAITools, generateRegistryTools, formatToolSignature } from '../lib/core-ai-tools'
+import type { PluginAITool, AIToolSuggestion } from '../types/plugins'
+
+export interface ResolvedSuggestion extends AIToolSuggestion {
+  toolId: string
+  category: string
+}
+
+export interface ResolvedToolEntry {
+  tool: PluginAITool
+  signature: string
+}
+
+export interface ResolvedToolGroup {
+  category: string
+  tools: ResolvedToolEntry[]
+}
+
+/**
+ * Detects which plugin "owns" the current page based on route matching.
+ * Returns the plugin ID or null for non-plugin pages (e.g. settings/general, dashboard).
+ */
+function detectActivePluginId(runtime: ReturnType<typeof usePluginRuntimeOptional>): string | null {
+  if (!runtime) return null
+  const path = runtime.context.currentPath
+
+  // Check each active plugin's routes for a match
+  for (const plugin of runtime.activePlugins) {
+    for (const route of plugin.routes) {
+      if (path === route.path || path.startsWith(`${route.path}/`)) {
+        return plugin.id
+      }
+    }
+  }
+
+  // Also match settings sub-pages: /settings/financial → financial
+  const settingsMatch = path.match(/^\/settings\/([^/]+)/)
+  if (settingsMatch) {
+    const tabId = settingsMatch[1]
+    if (runtime.activePlugins.some((p) => p.id === tabId)) {
+      return tabId
+    }
+  }
+
+  return null
+}
+
+export function useAITools(): {
+  tools: PluginAITool[]
+  suggestions: ResolvedSuggestion[]
+  /** Suggestions from the currently active plugin only (empty on non-plugin pages) */
+  contextualSuggestions: ResolvedSuggestion[]
+  toolGroups: ResolvedToolGroup[]
+} {
+  const runtime = usePluginRuntimeOptional()
+
+  return React.useMemo(() => {
+    const hasPermission = runtime?.context.hasPermission
+    const verticalId = runtime?.context.tenant?.verticalId
+    const activePluginId = detectActivePluginId(runtime)
+
+    // Collect all tools: core + plugin-declared + auto-generated from registries
+    const allTools: PluginAITool[] = [...coreAITools]
+
+    if (runtime) {
+      allTools.push(...runtime.aiTools)
+
+      // Auto-generate registry tools for active plugins
+      for (const [pluginId, registries] of runtime.registries) {
+        const autoTools = generateRegistryTools(pluginId, registries)
+        // Only add auto-tools that weren't explicitly declared
+        const declaredIds = new Set(runtime.aiTools.map((t) => t.id))
+        for (const tool of autoTools) {
+          if (!declaredIds.has(tool.id)) {
+            allTools.push(tool)
+          }
+        }
+      }
+    }
+
+    // Filter by permission
+    const tools = allTools.filter((tool) => {
+      if (!tool.permission) return true
+      if (!hasPermission) return true
+      return hasPermission(tool.permission)
+    })
+
+    // Flatten suggestions, filter by vertical
+    const allSuggestions: ResolvedSuggestion[] = []
+    for (const tool of tools) {
+      if (!tool.suggestions) continue
+      for (const suggestion of tool.suggestions) {
+        if (suggestion.verticalId && suggestion.verticalId !== verticalId) continue
+        allSuggestions.push({
+          ...suggestion,
+          toolId: tool.id,
+          category: tool.category ?? 'General',
+        })
+      }
+    }
+
+    // Prioritize suggestions from the active plugin's context
+    const contextualSuggestions = activePluginId
+      ? allSuggestions.filter((s) => s.toolId.startsWith(`${activePluginId}.`))
+      : []
+    let suggestions: ResolvedSuggestion[]
+    if (activePluginId) {
+      const others = allSuggestions.filter((s) => !s.toolId.startsWith(`${activePluginId}.`))
+      suggestions = [...contextualSuggestions, ...others]
+    } else {
+      suggestions = allSuggestions
+    }
+
+    // Group tools by category with signatures
+    const groupMap = new Map<string, ResolvedToolEntry[]>()
+    for (const tool of tools) {
+      const cat = tool.category ?? 'General'
+      if (!groupMap.has(cat)) groupMap.set(cat, [])
+      groupMap.get(cat)!.push({
+        tool,
+        signature: formatToolSignature(tool),
+      })
+    }
+
+    // Core first, then alphabetical
+    const toolGroups: ResolvedToolGroup[] = []
+    if (groupMap.has('Core')) {
+      toolGroups.push({ category: 'Core', tools: groupMap.get('Core')! })
+      groupMap.delete('Core')
+    }
+    for (const [category, groupTools] of [...groupMap.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      toolGroups.push({ category, tools: groupTools })
+    }
+
+    return { tools, suggestions, contextualSuggestions, toolGroups }
+  }, [runtime])
+}

package/src/shell/hooks/useAuth.ts

@@ -0,0 +1,109 @@
+import { useEffect, useCallback } from 'react'
+import { useAuthStore } from '../stores/auth.store'
+import { useAuthAdapterOptional } from '../lib/auth-context'
+import type { AuthProvider } from '../types'
+
+export function useAuth() {
+  const store = useAuthStore()
+  const adapter = useAuthAdapterOptional()
+
+  useEffect(() => {
+    if (!adapter) {
+      // No adapter configured — mark as initialized (no auth flow)
+      store.setInitialized(true)
+      store.setLoading(false)
+      return
+    }
+
+    adapter.getSession().then((result) => {
+      if (result) {
+        store.setSession(result.session)
+      } else {
+        store.setPendingEmailVerification(false)
+      }
+      store.setInitialized(true)
+      store.setLoading(false)
+    })
+
+    const unsubscribe = adapter.onAuthStateChange((user) => {
+      if (user) {
+        store.setUser(user)
+        store.setPendingEmailVerification(false)
+      } else {
+        store.setUser(null)
+        store.setSession(null)
+      }
+      store.setLoading(false)
+    })
+
+    return unsubscribe
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  const signIn = useCallback(async (email: string, password: string) => {
+    if (!adapter) throw new Error('No auth adapter configured')
+    store.setLoading(true)
+    try {
+      const session = await adapter.signIn(email, password)
+      store.setSession(session)
+      store.setPendingEmailVerification(false)
+    } finally {
+      store.setLoading(false)
+    }
+  }, [adapter, store])
+
+  const signUp = useCallback(async (email: string, password: string, fullName: string) => {
+    if (!adapter) throw new Error('No auth adapter configured')
+    store.setLoading(true)
+    try {
+      const session = await adapter.signUp(email, password, fullName)
+      const requiresEmailVerification = !session.accessToken
+      if (requiresEmailVerification) {
+        store.setSession(null)
+        store.setPendingEmailVerification(true)
+        return { requiresEmailVerification: true }
+      }
+
+      store.setSession(session)
+      store.setPendingEmailVerification(false)
+      return { requiresEmailVerification: false }
+    } finally {
+      store.setLoading(false)
+    }
+  }, [adapter, store])
+
+  const signOut = useCallback(async () => {
+    if (!adapter) throw new Error('No auth adapter configured')
+    store.setLoading(true)
+    try {
+      await adapter.signOut()
+      store.reset()
+      store.setInitialized(true)
+    } finally {
+      store.setLoading(false)
+    }
+  }, [adapter, store])
+
+  const signInWithOAuth = useCallback(async (provider: AuthProvider) => {
+    if (!adapter) throw new Error('No auth adapter configured')
+    await adapter.signInWithOAuth(provider)
+  }, [adapter])
+
+  const resetPassword = useCallback(async (email: string) => {
+    if (!adapter) throw new Error('No auth adapter configured')
+    await adapter.resetPassword(email)
+  }, [adapter])
+
+  return {
+    user: store.user,
+    session: store.session,
+    loading: store.loading,
+    initialized: store.initialized,
+    pendingEmailVerification: store.pendingEmailVerification,
+    signIn,
+    signUp,
+    signOut,
+    signInWithOAuth,
+    resetPassword,
+  }
+}

package/src/shell/hooks/useBilling.ts

@@ -0,0 +1,151 @@
+import { useCallback, useMemo } from 'react'
+import { useBillingStore } from '../stores/billing.store'
+import { getSupabaseClient } from '../lib/supabase'
+import type { PlanInterval } from '../types'
+
+export function useBilling() {
+  const store = useBillingStore()
+
+  const fetchPlans = useCallback(async () => {
+    store.setLoading(true)
+    try {
+      const supabase = getSupabaseClient()
+      const { data, error } = await supabase
+        .from('plans')
+        .select('*')
+        .order('prices->monthly', { ascending: true })
+
+      if (error) throw error
+      store.setPlans(data ?? [])
+    } catch (err) {
+      console.error('Failed to fetch plans:', err)
+    } finally {
+      store.setLoading(false)
+    }
+  }, [store])
+
+  const fetchSubscription = useCallback(async () => {
+    store.setLoading(true)
+    try {
+      const supabase = getSupabaseClient()
+      const { data, error } = await supabase
+        .from('subscriptions')
+        .select('*')
+        .single()
+
+      if (error && error.code !== 'PGRST116') throw error
+      store.setSubscription(data ?? null)
+    } catch (err) {
+      console.error('Failed to fetch subscription:', err)
+    } finally {
+      store.setLoading(false)
+    }
+  }, [store])
+
+  const fetchInvoices = useCallback(async () => {
+    store.setLoading(true)
+    try {
+      const supabase = getSupabaseClient()
+      const { data, error } = await supabase
+        .from('invoices')
+        .select('*')
+        .order('created_at', { ascending: false })
+
+      if (error) throw error
+      store.setInvoices(data ?? [])
+    } catch (err) {
+      console.error('Failed to fetch invoices:', err)
+    } finally {
+      store.setLoading(false)
+    }
+  }, [store])
+
+  const subscribe = useCallback(
+    async (planId: string, interval: PlanInterval) => {
+      store.setLoading(true)
+      try {
+        const supabase = getSupabaseClient()
+        const { data, error } = await supabase.functions.invoke(
+          'create-checkout',
+          { body: { planId, interval } }
+        )
+
+        if (error) throw error
+        if (data?.url) {
+          window.location.href = data.url
+        }
+      } catch (err) {
+        console.error('Failed to create checkout session:', err)
+        throw err
+      } finally {
+        store.setLoading(false)
+      }
+    },
+    [store]
+  )
+
+  const cancelSubscription = useCallback(async () => {
+    store.setLoading(true)
+    try {
+      const supabase = getSupabaseClient()
+      const { error } = await supabase.functions.invoke(
+        'cancel-subscription',
+        { body: {} }
+      )
+
+      if (error) throw error
+      await fetchSubscription()
+    } catch (err) {
+      console.error('Failed to cancel subscription:', err)
+      throw err
+    } finally {
+      store.setLoading(false)
+    }
+  }, [store, fetchSubscription])
+
+  const resumeSubscription = useCallback(async () => {
+    store.setLoading(true)
+    try {
+      const supabase = getSupabaseClient()
+      const { error } = await supabase.functions.invoke(
+        'resume-subscription',
+        { body: {} }
+      )
+
+      if (error) throw error
+      await fetchSubscription()
+    } catch (err) {
+      console.error('Failed to resume subscription:', err)
+      throw err
+    } finally {
+      store.setLoading(false)
+    }
+  }, [store, fetchSubscription])
+
+  return useMemo(
+    () => ({
+      subscription: store.subscription,
+      invoices: store.invoices,
+      plans: store.plans,
+      loading: store.loading,
+      fetchPlans,
+      fetchSubscription,
+      fetchInvoices,
+      subscribe,
+      cancelSubscription,
+      resumeSubscription,
+    }),
+    [
+      store.subscription,
+      store.invoices,
+      store.plans,
+      store.loading,
+      fetchPlans,
+      fetchSubscription,
+      fetchInvoices,
+      subscribe,
+      cancelSubscription,
+      resumeSubscription,
+    ]
+  )
+}

package/src/shell/hooks/useChat.ts

@@ -0,0 +1,84 @@
+import { useCallback } from 'react'
+import { useChatStore, type ChatMessage } from '../stores/chat.store'
+
+interface UseChatOptions {
+  apiEndpoint?: string
+  systemPrompt?: string
+}
+
+export function useChat(options?: UseChatOptions) {
+  const store = useChatStore()
+
+  const sendMessage = useCallback(
+    async (content: string) => {
+      const userMsg: ChatMessage = {
+        id: `msg-${Date.now()}`,
+        role: 'user',
+        content,
+        timestamp: new Date().toISOString(),
+      }
+      store.addMessage(userMsg)
+
+      const assistantMsg: ChatMessage = {
+        id: `msg-${Date.now() + 1}`,
+        role: 'assistant',
+        content: '',
+        timestamp: new Date().toISOString(),
+      }
+      store.addMessage(assistantMsg)
+      store.setStreaming(true)
+
+      if (!options?.apiEndpoint) {
+        // Mock response if no endpoint configured
+        setTimeout(() => {
+          store.updateLastAssistant(
+            "I'm your AI assistant. This is a demo response — connect an API endpoint to enable real conversations."
+          )
+          store.setStreaming(false)
+        }, 800)
+        return
+      }
+
+      try {
+        const response = await fetch(options.apiEndpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            messages: [
+              ...(options.systemPrompt
+                ? [{ role: 'system', content: options.systemPrompt }]
+                : []),
+              ...store.messages.map((m) => ({ role: m.role, content: m.content })),
+              { role: 'user', content },
+            ],
+          }),
+        })
+
+        if (!response.ok) {
+          store.updateLastAssistant('Sorry, something went wrong. Please try again.')
+          store.setStreaming(false)
+          return
+        }
+
+        const data = await response.json()
+        const text = data.choices?.[0]?.message?.content ?? data.content ?? 'No response.'
+        store.updateLastAssistant(text)
+      } catch {
+        store.updateLastAssistant('Sorry, I could not connect. Please try again later.')
+      } finally {
+        store.setStreaming(false)
+      }
+    },
+    [store, options?.apiEndpoint, options?.systemPrompt]
+  )
+
+  return {
+    messages: store.messages,
+    isOpen: store.isOpen,
+    isStreaming: store.isStreaming,
+    sendMessage,
+    toggleOpen: store.toggleOpen,
+    setOpen: store.setOpen,
+    reset: store.reset,
+  }
+}

package/src/shell/hooks/useFieldRules.ts

@@ -0,0 +1,19 @@
+import { useMemo } from 'react'
+import { useOrganizationStore } from '../stores/organization.store'
+import { applyFieldRules } from '../lib/apply-field-rules'
+import type { FieldDef, TenantFieldRules, EntityFieldRules } from '../types/crud'
+
+export function useFieldRules(entityKey: string) {
+  const settings = useOrganizationStore((s) => s.currentOrg?.settings)
+  const fieldRules = (settings as Record<string, unknown> | undefined)?.fieldRules as
+    | TenantFieldRules
+    | undefined
+
+  return useMemo(() => {
+    const rules: EntityFieldRules | undefined = fieldRules?.[entityKey]
+    return {
+      rules,
+      applyRules: (fields: FieldDef[]) => applyFieldRules(fields, rules),
+    }
+  }, [entityKey, fieldRules])
+}

package/src/shell/hooks/useFormatters.ts

@@ -0,0 +1,56 @@
+import { useMemo } from 'react'
+import { useLocaleStore } from '../stores/locale.store'
+
+export function useFormatters() {
+  const { locale } = useLocaleStore()
+
+  return useMemo(() => {
+    const resolvedLocale = locale || 'en'
+
+    const formatCurrency = (
+      amount: number,
+      currency = 'USD',
+      options?: Intl.NumberFormatOptions
+    ): string => {
+      return new Intl.NumberFormat(resolvedLocale, {
+        style: 'currency',
+        currency,
+        ...options,
+      }).format(amount)
+    }
+
+    const formatDate = (
+      date: Date | string,
+      options?: Intl.DateTimeFormatOptions
+    ): string => {
+      const d = typeof date === 'string' ? new Date(date) : date
+      return new Intl.DateTimeFormat(resolvedLocale, {
+        month: 'short',
+        day: 'numeric',
+        year: 'numeric',
+        ...options,
+      }).format(d)
+    }
+
+    const formatNumber = (
+      value: number,
+      options?: Intl.NumberFormatOptions
+    ): string => {
+      return new Intl.NumberFormat(resolvedLocale, options).format(value)
+    }
+
+    const formatRelativeTime = (date: Date | string): string => {
+      const d = typeof date === 'string' ? new Date(date) : date
+      const now = Date.now()
+      const diff = Math.floor((now - d.getTime()) / 1000)
+
+      if (diff < 60) return 'just now'
+      if (diff < 3600) return `${Math.floor(diff / 60)}m ago`
+      if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`
+      if (diff < 604800) return `${Math.floor(diff / 86400)}d ago`
+      return formatDate(d)
+    }
+
+    return { formatCurrency, formatDate, formatNumber, formatRelativeTime }
+  }, [locale])
+}

package/src/shell/hooks/useLayout.ts

@@ -0,0 +1,76 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useLayoutStore } from '../stores/layout.store'
+
+type Breakpoint = 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+
+const BREAKPOINTS: Record<Breakpoint, number> = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  '2xl': 1536,
+}
+
+function getBreakpoint(width: number): Breakpoint {
+  if (width >= BREAKPOINTS['2xl']) return '2xl'
+  if (width >= BREAKPOINTS.xl) return 'xl'
+  if (width >= BREAKPOINTS.lg) return 'lg'
+  if (width >= BREAKPOINTS.md) return 'md'
+  return 'sm'
+}
+
+export function useLayout() {
+  const store = useLayoutStore()
+  const [isMobile, setIsMobile] = useState(false)
+  const [currentBreakpoint, setCurrentBreakpoint] = useState<Breakpoint>('lg')
+
+  useEffect(() => {
+    // Track printing state to prevent layout thrashing during Ctrl+P.
+    // The print viewport is narrow, which would flip isMobile→true,
+    // causing component unmount/remount and losing loaded data.
+    let printing = false
+    const onBeforePrint = () => { printing = true }
+    const onAfterPrint = () => { printing = false }
+    window.addEventListener('beforeprint', onBeforePrint)
+    window.addEventListener('afterprint', onAfterPrint)
+
+    const mobileQuery = window.matchMedia('(max-width: 767px)')
+
+    const handleMobileChange = (e: MediaQueryListEvent | MediaQueryList) => {
+      if (!printing) setIsMobile(e.matches)
+    }
+
+    handleMobileChange(mobileQuery)
+    mobileQuery.addEventListener('change', handleMobileChange)
+
+    const handleResize = () => {
+      if (!printing) setCurrentBreakpoint(getBreakpoint(window.innerWidth))
+    }
+
+    handleResize()
+    window.addEventListener('resize', handleResize)
+
+    return () => {
+      mobileQuery.removeEventListener('change', handleMobileChange)
+      window.removeEventListener('resize', handleResize)
+      window.removeEventListener('beforeprint', onBeforePrint)
+      window.removeEventListener('afterprint', onAfterPrint)
+    }
+  }, [])
+
+  const closeMobileDrawer = useCallback(() => {
+    if (store.mobileDrawerOpen) {
+      store.toggleMobileDrawer()
+    }
+  }, [store])
+
+  return useMemo(
+    () => ({
+      ...store,
+      isMobile,
+      currentBreakpoint,
+      closeMobileDrawer,
+    }),
+    [store, isMobile, currentBreakpoint, closeMobileDrawer]
+  )
+}