@fayz-ai/saas 0.1.6

package/src/shell/lib/api.ts

@@ -0,0 +1,67 @@
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+interface ApiOptions {
+  baseUrl?: string
+  headers?: Record<string, string>
+}
+
+interface RequestOptions {
+  headers?: Record<string, string>
+  signal?: AbortSignal
+}
+
+class ApiClient {
+  private baseUrl: string
+  private defaultHeaders: Record<string, string>
+
+  constructor(options: ApiOptions = {}) {
+    this.baseUrl = options.baseUrl || ''
+    this.defaultHeaders = {
+      'Content-Type': 'application/json',
+      ...options.headers,
+    }
+  }
+
+  setAuthToken(token: string) {
+    this.defaultHeaders['Authorization'] = `Bearer ${token}`
+  }
+
+  clearAuthToken() {
+    delete this.defaultHeaders['Authorization']
+  }
+
+  private async request<T>(method: HttpMethod, path: string, body?: unknown, options?: RequestOptions): Promise<T> {
+    const url = `${this.baseUrl}${path}`
+    const response = await fetch(url, {
+      method,
+      headers: { ...this.defaultHeaders, ...options?.headers },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: options?.signal,
+    })
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ message: response.statusText }))
+      throw new ApiError(response.status, error.message || response.statusText)
+    }
+
+    if (response.status === 204) return undefined as T
+    return response.json()
+  }
+
+  get<T>(path: string, options?: RequestOptions) { return this.request<T>('GET', path, undefined, options) }
+  post<T>(path: string, body?: unknown, options?: RequestOptions) { return this.request<T>('POST', path, body, options) }
+  put<T>(path: string, body?: unknown, options?: RequestOptions) { return this.request<T>('PUT', path, body, options) }
+  patch<T>(path: string, body?: unknown, options?: RequestOptions) { return this.request<T>('PATCH', path, body, options) }
+  delete<T>(path: string, options?: RequestOptions) { return this.request<T>('DELETE', path, undefined, options) }
+}
+
+export class ApiError extends Error {
+  constructor(public status: number, message: string) {
+    super(message)
+    this.name = 'ApiError'
+  }
+}
+
+export function createApiClient(options?: ApiOptions) {
+  return new ApiClient(options)
+}

package/src/shell/lib/apply-field-rules.ts

@@ -0,0 +1,14 @@
+import type { FieldDef, EntityFieldRules } from '../types/crud'
+
+/** Merge tenant field-rule overrides into static FieldDef[]. Pure & testable. */
+export function applyFieldRules(
+  fields: FieldDef[],
+  rules: EntityFieldRules | undefined,
+): FieldDef[] {
+  if (!rules) return fields
+  return fields.map((f) => {
+    const override = rules[f.key]
+    if (!override) return f
+    return { ...f, ...override }
+  })
+}

package/src/shell/lib/auth-adapters/mock.ts

@@ -0,0 +1,97 @@
+import type { AuthAdapter } from '../../types/auth-adapter'
+import type { AuthUser, AuthSession } from '../../types/auth'
+
+const STORAGE_KEY = 'saas-core:mock-auth'
+
+function createMockUser(email: string, fullName?: string): AuthUser {
+  return {
+    id: crypto.randomUUID(),
+    email,
+    fullName: fullName || email.split('@')[0],
+    providers: ['email'],
+    emailVerified: true,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  }
+}
+
+function createMockSession(user: AuthUser): AuthSession {
+  return {
+    accessToken: `mock-token-${user.id}`,
+    refreshToken: `mock-refresh-${user.id}`,
+    expiresAt: Math.floor(Date.now() / 1000) + 3600,
+    user,
+  }
+}
+
+export function createMockAuthAdapter(): AuthAdapter {
+  const listeners = new Set<(user: AuthUser | null) => void>()
+
+  function notifyListeners(user: AuthUser | null) {
+    for (const cb of listeners) cb(user)
+  }
+
+  function getStored(): { user: AuthUser; session: AuthSession } | null {
+    try {
+      const raw = localStorage.getItem(STORAGE_KEY)
+      if (!raw) return null
+      return JSON.parse(raw)
+    } catch {
+      return null
+    }
+  }
+
+  function setStored(data: { user: AuthUser; session: AuthSession } | null) {
+    if (data) {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(data))
+    } else {
+      localStorage.removeItem(STORAGE_KEY)
+    }
+  }
+
+  return {
+    async getSession() {
+      return getStored()
+    },
+
+    onAuthStateChange(cb) {
+      listeners.add(cb)
+      return () => { listeners.delete(cb) }
+    },
+
+    async signIn(email, password) {
+      void password // mock accepts any password
+      const user = createMockUser(email)
+      const session = createMockSession(user)
+      setStored({ user, session })
+      notifyListeners(user)
+      return session
+    },
+
+    async signUp(email, password, fullName) {
+      void password
+      const user = createMockUser(email, fullName)
+      const session = createMockSession(user)
+      setStored({ user, session })
+      notifyListeners(user)
+      return session
+    },
+
+    async signOut() {
+      setStored(null)
+      notifyListeners(null)
+    },
+
+    async signInWithOAuth(_provider) {
+      // Mock OAuth just signs in with a fake user
+      const user = createMockUser('oauth@example.com', 'OAuth User')
+      const session = createMockSession(user)
+      setStored({ user, session })
+      notifyListeners(user)
+    },
+
+    async resetPassword(_email) {
+      // No-op in mock
+    },
+  }
+}

package/src/shell/lib/auth-adapters/supabase.ts

@@ -0,0 +1,96 @@
+import type { AuthAdapter } from '../../types/auth-adapter'
+import type { AuthUser, AuthSession, AuthProvider } from '../../types/auth'
+import { getSupabaseClient } from '../supabase'
+
+function mapSupabaseUser(supabaseUser: any): AuthUser {
+  return {
+    id: supabaseUser.id,
+    email: supabaseUser.email ?? '',
+    fullName: supabaseUser.user_metadata?.full_name ?? supabaseUser.user_metadata?.name ?? '',
+    avatarUrl: supabaseUser.user_metadata?.avatar_url,
+    providers: (supabaseUser.app_metadata?.providers ?? [supabaseUser.app_metadata?.provider]).filter(Boolean) as AuthProvider[],
+    emailVerified: !!supabaseUser.email_confirmed_at,
+    createdAt: supabaseUser.created_at,
+    updatedAt: supabaseUser.updated_at ?? supabaseUser.created_at,
+  }
+}
+
+function mapSupabaseSession(session: any): AuthSession {
+  return {
+    accessToken: session.access_token,
+    refreshToken: session.refresh_token,
+    expiresAt: session.expires_at ?? Math.floor(Date.now() / 1000) + (session.expires_in ?? 3600),
+    user: mapSupabaseUser(session.user),
+  }
+}
+
+export function createSupabaseAuthAdapter(): AuthAdapter {
+  const supabase = getSupabaseClient()
+
+  return {
+    async getSession() {
+      const { data: { session } } = await supabase.auth.getSession()
+      if (!session) return null
+      const mapped = mapSupabaseSession(session)
+      return { user: mapped.user, session: mapped }
+    },
+
+    onAuthStateChange(cb) {
+      const { data: { subscription } } = supabase.auth.onAuthStateChange((_event, session) => {
+        cb(session ? mapSupabaseUser(session.user) : null)
+      })
+      return () => subscription.unsubscribe()
+    },
+
+    async signIn(email, password) {
+      const { data, error } = await supabase.auth.signInWithPassword({ email, password })
+      if (error) throw error
+      return mapSupabaseSession(data.session)
+    },
+
+    async signUp(email, password, fullName) {
+      const { data, error } = await supabase.auth.signUp({
+        email,
+        password,
+        options: { data: { full_name: fullName } },
+      })
+      if (error) throw error
+
+      // When email confirmation is enabled, session is null
+      if (!data.session) {
+        if (!data.user) throw new Error('Signup failed: no user returned')
+        // Return a partial session so the UI can show "check your email"
+        return {
+          accessToken: '',
+          refreshToken: '',
+          expiresAt: 0,
+          user: mapSupabaseUser(data.user),
+        }
+      }
+
+      return mapSupabaseSession(data.session)
+    },
+
+    async signOut() {
+      const { error } = await supabase.auth.signOut()
+      if (error) throw error
+    },
+
+    async signInWithOAuth(provider: AuthProvider) {
+      const { error } = await supabase.auth.signInWithOAuth({
+        provider: provider as 'google' | 'github' | 'apple',
+        options: {
+          redirectTo: typeof window !== 'undefined' ? `${window.location.origin}/auth/callback` : undefined,
+        },
+      })
+      if (error) throw error
+    },
+
+    async resetPassword(email) {
+      const { error } = await supabase.auth.resetPasswordForEmail(email, {
+        redirectTo: typeof window !== 'undefined' ? `${window.location.origin}/auth/reset-password` : undefined,
+      })
+      if (error) throw error
+    },
+  }
+}

package/src/shell/lib/auth-context.ts

@@ -0,0 +1,18 @@
+import { createContext, useContext } from 'react'
+import type { AuthAdapter } from '../types/auth-adapter'
+
+const AuthAdapterContext = createContext<AuthAdapter | null>(null)
+
+export const AuthAdapterProvider = AuthAdapterContext.Provider
+
+export function useAuthAdapter(): AuthAdapter {
+  const adapter = useContext(AuthAdapterContext)
+  if (!adapter) {
+    throw new Error('useAuthAdapter must be used within an AuthAdapterProvider')
+  }
+  return adapter
+}
+
+export function useAuthAdapterOptional(): AuthAdapter | null {
+  return useContext(AuthAdapterContext)
+}

package/src/shell/lib/cache.ts

@@ -0,0 +1,124 @@
+import { useOrganizationStore } from '../stores/organization.store'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface CacheEntry<T = unknown> {
+  data: T
+  expiresAt: number
+  lastAccess: number
+}
+
+export interface CacheStore {
+  get<T>(key: string): T | undefined
+  set<T>(key: string, data: T, ttl?: number): void
+  /** Clear all entries whose key starts with `prefix` */
+  invalidate(prefix: string): void
+  clear(): void
+  size(): number
+}
+
+export interface CacheConfig {
+  /** Default time-to-live in ms (default: 60 000 — 1 minute) */
+  defaultTTL?: number
+  /** Maximum cached entries before LRU eviction (default: 500) */
+  maxEntries?: number
+}
+
+// ---------------------------------------------------------------------------
+// Stable key helper — deterministic JSON for cache keys
+// ---------------------------------------------------------------------------
+
+function sortDeep(value: unknown): unknown {
+  if (value === null || value === undefined || typeof value !== 'object') return value
+  if (Array.isArray(value)) return value.map(sortDeep)
+  const sorted: Record<string, unknown> = {}
+  for (const k of Object.keys(value as Record<string, unknown>).sort()) {
+    sorted[k] = sortDeep((value as Record<string, unknown>)[k])
+  }
+  return sorted
+}
+
+export function stableKey(...parts: unknown[]): string {
+  return parts.map((p) => (typeof p === 'string' ? p : JSON.stringify(sortDeep(p)))).join(':')
+}
+
+// ---------------------------------------------------------------------------
+// CacheStore implementation
+// ---------------------------------------------------------------------------
+
+export function createCacheStore(config?: CacheConfig): CacheStore {
+  const defaultTTL = config?.defaultTTL ?? 60_000
+  const maxEntries = config?.maxEntries ?? 500
+  const entries = new Map<string, CacheEntry>()
+
+  function evictLRU() {
+    if (entries.size <= maxEntries) return
+    // Find the entry with the oldest lastAccess
+    let oldestKey: string | null = null
+    let oldestAccess = Infinity
+    for (const [key, entry] of entries) {
+      if (entry.lastAccess < oldestAccess) {
+        oldestAccess = entry.lastAccess
+        oldestKey = key
+      }
+    }
+    if (oldestKey) entries.delete(oldestKey)
+  }
+
+  return {
+    get<T>(key: string): T | undefined {
+      const entry = entries.get(key)
+      if (!entry) return undefined
+      if (Date.now() > entry.expiresAt) {
+        entries.delete(key)
+        return undefined
+      }
+      entry.lastAccess = Date.now()
+      return entry.data as T
+    },
+
+    set<T>(key: string, data: T, ttl?: number): void {
+      const now = Date.now()
+      entries.set(key, {
+        data,
+        expiresAt: now + (ttl ?? defaultTTL),
+        lastAccess: now,
+      })
+      evictLRU()
+    },
+
+    invalidate(prefix: string): void {
+      for (const key of entries.keys()) {
+        if (key.startsWith(prefix)) {
+          entries.delete(key)
+        }
+      }
+    },
+
+    clear(): void {
+      entries.clear()
+    },
+
+    size(): number {
+      return entries.size
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Global singleton — auto-flushes on tenant/org switch
+// ---------------------------------------------------------------------------
+
+export const globalCache = createCacheStore()
+
+// Flush cache when the active organization changes
+let lastOrgId: string | null | undefined
+useOrganizationStore.subscribe((state) => {
+  const orgId = state.currentOrg?.id ?? null
+  if (lastOrgId !== undefined && orgId !== lastOrgId) {
+    globalCache.clear()
+  }
+  lastOrgId = orgId
+})

package/src/shell/lib/cn.ts

@@ -0,0 +1 @@
+export { cn } from '@fayz-ai/ui'

package/src/shell/lib/core-ai-tools.ts

@@ -0,0 +1,90 @@
+import type { PluginAITool, PluginRegistryDef } from '../types/plugins'
+
+/**
+ * Core SaaS-level AI tools — always available, no plugin required.
+ */
+export const coreAITools: PluginAITool[] = [
+  {
+    id: 'core.business-summary',
+    name: 'getBusinessSummary',
+    description: 'Returns a summary of the current business: name, plan, vertical, team size, and key metrics.',
+    icon: 'Building2',
+    mode: 'read',
+    parameters: { type: 'object', properties: {}, required: [] },
+    category: 'Core',
+    suggestions: [
+      { label: "How's my business doing today?" },
+    ],
+  },
+  {
+    id: 'core.team-members',
+    name: 'getTeamMembers',
+    description: 'Lists team members for the current tenant with their roles and status.',
+    icon: 'Users',
+    mode: 'read',
+    parameters: {
+      type: 'object',
+      properties: {
+        role: { type: 'string', description: 'Filter by role: owner, admin, manager, staff, viewer' },
+      },
+    },
+    permission: { feature: 'team', action: 'read' },
+    category: 'Core',
+    suggestions: [
+      { label: 'Who is on my team?' },
+    ],
+  },
+  {
+    id: 'core.navigate',
+    name: 'navigateTo',
+    description: 'Helps the user find and navigate to a specific page or feature in the app.',
+    icon: 'Compass',
+    mode: 'read',
+    parameters: {
+      type: 'object',
+      properties: {
+        page: { type: 'string', description: 'Page name or feature the user is looking for' },
+      },
+      required: ['page'],
+    },
+    category: 'Core',
+  },
+]
+
+/**
+ * Auto-generates read tools from plugin registry definitions.
+ * Each registry gets a basic "list" tool so plugins get AI capabilities for free.
+ */
+export function generateRegistryTools(pluginId: string, registries: PluginRegistryDef[]): PluginAITool[] {
+  return registries
+    .filter((r) => !r.readOnly)
+    .map((registry) => {
+      const plural = registry.entity.namePlural ?? `${registry.entity.name}s`
+      return {
+        id: `${pluginId}.list-${registry.id}`,
+        name: `list${plural.replace(/\s+/g, '')}`,
+        description: `Lists all ${plural.toLowerCase()} for the current business.`,
+        icon: registry.icon ?? registry.entity.icon,
+        mode: 'read' as const,
+        parameters: {
+          type: 'object' as const,
+          properties: {
+            search: { type: 'string' as const, description: 'Search text' },
+          },
+        },
+        category: pluginId.charAt(0).toUpperCase() + pluginId.slice(1),
+      }
+    })
+}
+
+/**
+ * Formats a tool as a function signature: e.g. "getRevenue(period?)"
+ */
+export function formatToolSignature(tool: PluginAITool): string {
+  const params = tool.parameters?.properties
+    ? Object.entries(tool.parameters.properties)
+        .map(([key]) => tool.parameters?.required?.includes(key) ? key : `${key}?`)
+        .join(', ')
+    : ''
+  return `${tool.name}(${params})`
+}

package/src/shell/lib/create-client-orders-provider.ts

@@ -0,0 +1,105 @@
+// ---------------------------------------------------------------------------
+// Factory: creates a ClientOrdersProvider that queries saas_core.orders
+// for a given client (party_id). The UI keeps the historical "stage" language,
+// but current archetype schemas expose this lifecycle as orders.status.
+// ---------------------------------------------------------------------------
+
+import type { ClientOrdersProvider, ClientOrdersQuery, ClientDocument, ClientDocumentStage } from '../types/client-orders'
+import { getSupabaseClientOptional } from './supabase'
+
+const STAGE_FILTER_MAP: Record<string, string[]> = {
+  quoted: ['draft', 'quoted'],
+  booked: ['booked', 'scheduled', 'confirmed', 'in_progress', 'completed'],
+  invoiced: ['invoiced', 'partial', 'overdue'],
+  paid: ['paid'],
+}
+
+function mapOrderStatusToStage(status: string | null | undefined): ClientDocumentStage {
+  switch (status) {
+    case 'scheduled':
+    case 'confirmed':
+    case 'in_progress':
+      return 'booked'
+    case 'completed':
+      return 'completed'
+    case 'invoiced':
+    case 'paid':
+    case 'partial':
+    case 'overdue':
+    case 'cancelled':
+    case 'no_show':
+    case 'quoted':
+    case 'draft':
+      return status
+    default:
+      return 'draft'
+  }
+}
+
+export function createClientOrdersProvider(): ClientOrdersProvider {
+  return {
+    async getDocuments(query: ClientOrdersQuery): Promise<{ data: ClientDocument[]; total: number }> {
+      const supabase = getSupabaseClientOptional()
+      if (!supabase) return { data: [], total: 0 }
+
+      try {
+        let qb = supabase
+          .schema('saas_core')
+          .from('orders')
+          .select('id, kind, status, total, reference_number, notes, metadata, created_at', { count: 'exact' })
+          .eq('party_id', query.clientId)
+
+        // Filter by stage groups against the current schema's status column.
+        if (query.stages && query.stages.length > 0) {
+          const allStages = query.stages.flatMap((s) => STAGE_FILTER_MAP[s] ?? [s])
+          qb = qb.in('status', allStages)
+        }
+
+        qb = qb.order('created_at', { ascending: false })
+
+        const page = query.page ?? 1
+        const pageSize = query.pageSize ?? 50
+        qb = qb.range((page - 1) * pageSize, page * pageSize - 1)
+
+        const { data, count } = await qb
+        const orderIds = (data ?? []).map((row: any) => row.id).filter(Boolean)
+
+        const bookingStartsByOrderId = new Map<string, string>()
+        if (orderIds.length > 0) {
+          const { data: bookings } = await supabase
+            .schema('saas_core')
+            .from('bookings')
+            .select('order_id, starts_at')
+            .in('order_id', orderIds)
+
+          for (const booking of bookings ?? []) {
+            if (booking.order_id && booking.starts_at && !bookingStartsByOrderId.has(booking.order_id)) {
+              bookingStartsByOrderId.set(booking.order_id, booking.starts_at)
+            }
+          }
+        }
+
+        const results: ClientDocument[] = (data ?? []).map((row: any) => {
+          const meta = (row.metadata ?? {}) as Record<string, unknown>
+          const startsAt = bookingStartsByOrderId.get(row.id)
+          return {
+            id: row.id,
+            kind: row.kind as string,
+            stage: mapOrderStatusToStage(row.status as string | null | undefined),
+            referenceNumber: row.reference_number ?? undefined,
+            date: startsAt?.slice(0, 10) ?? (row.created_at as string)?.slice(0, 10) ?? '',
+            startsAt,
+            total: Number(row.total) || 0,
+            paidAmount: Number(meta.paidAmount) || 0,
+            description: (meta.itemsSummary as string) ?? (meta.serviceNames as string) ?? row.notes ?? undefined,
+            createdAt: row.created_at as string,
+          }
+        })
+
+        return { data: results, total: count ?? results.length }
+      } catch {
+        return { data: [], total: 0 }
+      }
+    },
+  }
+}

package/src/shell/lib/csv.ts

@@ -0,0 +1,54 @@
+/** Column descriptor for generic CSV export */
+export interface CSVColumn {
+  key: string
+  label: string
+  format?: (value: any, row: Record<string, any>) => string
+}
+
+export function escapeCSVField(value: unknown): string {
+  if (value == null) return ''
+  const str = String(value)
+  if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+    return `"${str.replace(/"/g, '""')}"`
+  }
+  return str
+}
+
+/** Build a CSV string from columns + rows. Each cell runs through `column.format` if provided, then escaping. */
+export function buildCSV(
+  columns: CSVColumn[],
+  rows: Record<string, any>[],
+): string {
+  const header = columns.map((c) => escapeCSVField(c.label)).join(',')
+  const body = rows.map((row) =>
+    columns
+      .map((col) => {
+        const raw = row[col.key]
+        const formatted = col.format ? col.format(raw, row) : raw
+        return escapeCSVField(formatted)
+      })
+      .join(','),
+  )
+  return [header, ...body].join('\n')
+}
+
+/** Trigger a CSV file download in the browser. */
+export function downloadCSV(csv: string, filename: string): void {
+  const bom = '\uFEFF'
+  const blob = new Blob([bom + csv], { type: 'text/csv;charset=utf-8;' })
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = filename.endsWith('.csv') ? filename : `${filename}.csv`
+  a.click()
+  URL.revokeObjectURL(url)
+}
+
+/** Convenience: build + download in one call. */
+export function exportCSV(
+  columns: CSVColumn[],
+  rows: Record<string, any>[],
+  filename: string,
+): void {
+  downloadCSV(buildCSV(columns, rows), filename)
+}

package/src/shell/lib/dedup.ts

@@ -0,0 +1,17 @@
+/**
+ * Request deduplication — prevents duplicate in-flight requests with the same key.
+ * If a request with the same key is already in-flight, returns the existing promise.
+ */
+const inflight = new Map<string, Promise<any>>()
+
+export function dedup<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const existing = inflight.get(key)
+  if (existing) return existing as Promise<T>
+
+  const promise = fn().finally(() => {
+    inflight.delete(key)
+  })
+
+  inflight.set(key, promise)
+  return promise
+}