@fayz-ai/core 0.9.0 → 0.11.0

package/src/data/archetype.ts

@@ -1,255 +0,0 @@
-import type { DataProvider, CrudQuery, CrudResult } from './types'
-import { getSupabaseClientOptional } from './supabase'
-import { applyRangeToQuery, isFilterObject, parseRangeFilter } from './filters'
-import type { EntityArchetype } from '../types/entities'
-
-// Archetypes that have a `kind` discriminator column
-const HAS_KIND = new Set<EntityArchetype>(['person', 'category', 'order', 'transaction', 'schedule', 'location'])
-
-const ARCHETYPE_CONFIG: Record<EntityArchetype, { table: string; fkColumn: string }> = {
-  person: { table: 'people', fkColumn: 'person_id' },
-  category: { table: 'categories', fkColumn: 'category_id' },
-  product: { table: 'products', fkColumn: 'product_id' },
-  service: { table: 'services', fkColumn: 'service_id' },
-  location: { table: 'locations', fkColumn: 'location_id' },
-  order: { table: 'orders', fkColumn: 'order_id' },
-  transaction: { table: 'transactions', fkColumn: 'transaction_id' },
-
-  schedule: { table: 'schedules', fkColumn: 'schedule_id' },
-}
-
-const ARCHETYPE_COLUMNS: Record<EntityArchetype, Set<string>> = {
-  person: new Set(['name', 'email', 'phone', 'document_number', 'avatar_url', 'date_of_birth', 'address', 'city', 'state', 'country', 'postal_code', 'tags', 'is_active', 'notes', 'metadata']),
-  category: new Set(['name', 'slug', 'parent_id', 'icon', 'color', 'sort_order', 'is_active', 'metadata']),
-  product: new Set(['name', 'description', 'sku', 'price', 'cost', 'currency', 'unit', 'image_url', 'stock', 'min_stock', 'status', 'is_active', 'tags', 'metadata', 'category_id']),
-  service: new Set(['name', 'description', 'price', 'cost', 'currency', 'duration_minutes', 'image_url', 'status', 'is_active', 'tags', 'metadata', 'category_id']),
-  location: new Set(['name', 'email', 'phone', 'address', 'city', 'state', 'country', 'postal_code', 'is_headquarters', 'is_active', 'tags', 'notes', 'metadata']),
-  order: new Set(['reference_number', 'status', 'party_id', 'assignee_id', 'location_id', 'subtotal', 'discount', 'tax', 'total', 'currency', 'due_at', 'completed_at', 'notes', 'tags', 'metadata']),
-  transaction: new Set(['order_id', 'party_id', 'amount', 'currency', 'payment_method', 'reference', 'status', 'transacted_at', 'notes', 'metadata']),
-
-  schedule: new Set(['assignee_id', 'location_id', 'day_of_week', 'specific_date', 'starts_at', 'ends_at', 'is_active', 'metadata']),
-}
-
-function camelToSnake(str: string): string {
-  return str.replace(/[A-Z]/g, (c) => '_' + c.toLowerCase())
-}
-
-function snakeToCamel(str: string): string {
-  return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase())
-}
-
-function mapRow<T>(row: Record<string, unknown>): T {
-  const result: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(row)) {
-    result[snakeToCamel(key)] = value
-  }
-  return result as T
-}
-
-export interface ArchetypeProviderConfig {
-  archetype: EntityArchetype
-  archetypeKind: string
-  projectTable: string
-  tenantId: () => string | undefined
-  searchColumns?: string[]
-}
-
-export function createArchetypeProvider<T extends { id: string }>(
-  config: ArchetypeProviderConfig,
-): DataProvider<T> {
-  const ac = ARCHETYPE_CONFIG[config.archetype]
-  const archetypeColumns = ARCHETYPE_COLUMNS[config.archetype]
-  const { fkColumn } = ac
-
-  function getClient() {
-    const supabase = getSupabaseClientOptional() as any
-    if (!supabase) throw new Error('Supabase client not available')
-    return supabase
-  }
-
-  // Core v1 lives in PUBLIC — the archetype base tables and the public extension
-  // tables share one client/schema. `coreClient()` is kept as a thin alias so the
-  // core/extension split below still reads clearly at each call site.
-  function coreClient() {
-    return getClient()
-  }
-
-  function splitFields(data: Record<string, unknown>): { archetypeData: Record<string, unknown>; projectData: Record<string, unknown> } {
-    const archetypeData: Record<string, unknown> = {}
-    const projectData: Record<string, unknown> = {}
-    for (const [key, value] of Object.entries(data)) {
-      if (['id', 'createdAt', 'updatedAt', 'tenantId', fkColumn].includes(key)) continue
-      const snakeKey = camelToSnake(key)
-      if (archetypeColumns.has(snakeKey)) {
-        archetypeData[snakeKey] = value
-      } else {
-        projectData[snakeKey] = value
-      }
-    }
-    return { archetypeData, projectData }
-  }
-
-  // View name convention: v_{shortName} — maps project table to its view
-  const VIEW_MAP: Record<string, string> = {
-    clients: 'v_clients',
-    staff_members: 'v_staff',
-  }
-  const viewName = VIEW_MAP[config.projectTable] ?? `v_${config.projectTable}`
-
-  // Pure-archetype entity: the project table IS the archetype base (e.g. a
-  // customers list configured with `table: 'people'`, no separate public
-  // extension table). Read/write public.<base> directly — there is no public
-  // extension row and no v_ view to join. Extension-table entities (clients,
-  // staff_members, …) are unaffected.
-  const isPure = config.projectTable === ac.table
-
-  return {
-    async list(query: CrudQuery): Promise<CrudResult<T>> {
-      const tenantId = config.tenantId()
-      if (!tenantId) return { data: [], total: 0 }
-
-      // Pure archetype → read public.<base> directly (filtered by kind);
-      // otherwise the v_ view (JOINs public extension with the public archetype).
-      // 'none' skips PostgREST's count aggregate entirely — see CrudQuery.countMode.
-      const countOpts = query.countMode === 'none' ? undefined : { count: 'exact' as const }
-      let q = isPure
-        ? coreClient().from(ac.table).select('*', countOpts).eq('tenant_id', tenantId)
-        : getClient().from(viewName).select('*', countOpts).eq('tenant_id', tenantId)
-
-      if (isPure && HAS_KIND.has(config.archetype)) {
-        q = q.eq('kind', config.archetypeKind)
-      }
-
-      // Faceted filters — equality, or real SQL bounds for a range object.
-      // Silently dropping them made every caller post-filter one page of rows,
-      // which reads as "no records match" whenever the match sits past it.
-      if (query.filters) {
-        for (const [key, val] of Object.entries(query.filters)) {
-          if (val == null || val === '') continue
-          const col = camelToSnake(key)
-          const range = parseRangeFilter(val)
-          if (range) {
-            q = applyRangeToQuery(q, col, range)
-            continue
-          }
-          if (isFilterObject(val)) {
-            throw new Error(
-              `[@fayz-ai/core] Filter "${key}" is an object with no recognised bound. ` +
-                'Use {from,to} / {gte,lte,gt,lt} for ranges, or a plain value for equality.',
-            )
-          }
-          q = q.eq(col, val)
-        }
-      }
-
-      // Search
-      if (query.search && config.searchColumns && config.searchColumns.length > 0) {
-        const term = `%${query.search}%`
-        const orClauses = config.searchColumns
-          .map((col) => camelToSnake(col))
-          .map((col) => `${col}.ilike.${term}`)
-        if (orClauses.length > 0) {
-          q = q.or(orClauses.join(','))
-        }
-      }
-
-      // Sort
-      if (query.sortBy) {
-        q = q.order(camelToSnake(query.sortBy), { ascending: query.sortDir !== 'desc' })
-      } else {
-        q = q.order('created_at', { ascending: false })
-      }
-
-      // Pagination
-      const page = query.page ?? 1
-      const pageSize = query.pageSize ?? 50
-      const from = (page - 1) * pageSize
-      q = q.range(from, from + pageSize - 1)
-
-      const { data, error, count } = await q
-      if (error) throw error
-
-      const rows = (data ?? []).map((row: Record<string, unknown>) => mapRow<T>(row))
-      return { data: rows, total: count ?? 0 }
-    },
-
-    async create(data) {
-      const tenantId = config.tenantId()
-      if (!tenantId) throw new Error('No tenant selected')
-
-      const { archetypeData, projectData } = splitFields(data as Record<string, unknown>)
-
-      // 1. Insert into archetype table
-      archetypeData.tenant_id = tenantId
-      if (HAS_KIND.has(config.archetype)) {
-        archetypeData.kind = config.archetypeKind
-      }
-
-      const { data: archetypeRow, error: archetypeError } = await coreClient()
-        .from(ac.table)
-        .insert(archetypeData)
-        .select()
-        .single()
-
-      if (archetypeError) throw archetypeError
-      const archetypeId = (archetypeRow as any).id
-
-      // 2. Insert into project table with archetype FK as PK.
-      //    Pure-archetype entities have no extension table — skip this step.
-      if (!isPure) {
-        projectData[fkColumn] = archetypeId
-        projectData.tenant_id = tenantId
-
-        const { error: projectError } = await getClient()
-          .from(config.projectTable)
-          .insert(projectData)
-
-        if (projectError) {
-          await coreClient().from(ac.table).delete().eq('id', archetypeId)
-          throw projectError
-        }
-      }
-
-      return { id: archetypeId, ...archetypeRow, ...(isPure ? {} : projectData) } as unknown as T
-    },
-
-    async update(id, data) {
-      const { archetypeData, projectData } = splitFields(data as Record<string, unknown>)
-
-      if (Object.keys(archetypeData).length > 0) {
-        const { error } = await coreClient()
-          .from(ac.table)
-          .update(archetypeData)
-          .eq('id', id)
-        if (error) throw error
-      }
-
-      if (!isPure && Object.keys(projectData).length > 0) {
-        const { error } = await getClient()
-          .from(config.projectTable)
-          .update(projectData)
-          .eq(fkColumn, id)
-        if (error) throw error
-      }
-
-      // Re-fetch (archetype only for pure entities; otherwise join the extension)
-      const { data: archetypeRow } = await coreClient().from(ac.table).select('*').eq('id', id).single()
-      if (isPure) {
-        return mapRow<T>({ ...archetypeRow, id } as Record<string, unknown>)
-      }
-      const { data: projectRow } = await getClient().from(config.projectTable).select('*').eq(fkColumn, id).single()
-
-      const flat = { ...archetypeRow, ...projectRow, id }
-      delete (flat as any)[fkColumn]
-      return mapRow<T>(flat as Record<string, unknown>)
-    },
-
-    async remove(id) {
-      const { error } = await coreClient()
-        .from(ac.table)
-        .delete()
-        .eq('id', id)
-      if (error) throw error
-    },
-  }
-}

package/src/data/bulk.ts

@@ -1,35 +0,0 @@
-import type { BulkWriteOptions, BulkWriteResult, DataProvider } from './types'
-
-/**
- * Write many rows through whatever the provider supports.
- *
- * `createMany` when it exists (one round-trip per chunk), otherwise a sequential
- * `create` loop. Callers never branch: a mock provider and a Supabase table
- * import the same way, only slower.
- *
- * Never all-or-nothing. A 900-row client list will contain a malformed phone
- * and a duplicate e-mail, and a single transaction would throw away the other
- * 898 — plus a statement that large risks the timeout. Failures are collected
- * with their row index so the caller can hand them back for correction.
- */
-export async function bulkCreate<T extends { id: string }>(
-  provider: DataProvider<T>,
-  rows: Array<Omit<T, 'id' | 'createdAt' | 'updatedAt' | 'tenantId'>>,
-  options?: BulkWriteOptions,
-): Promise<BulkWriteResult> {
-  if (!rows.length) return { created: 0, failed: [] }
-  if (provider.createMany) return provider.createMany(rows, options)
-
-  let created = 0
-  const failed: Array<{ index: number; message: string }> = []
-  for (let i = 0; i < rows.length; i++) {
-    try {
-      await provider.create(rows[i])
-      created += 1
-    } catch (error) {
-      failed.push({ index: i, message: error instanceof Error ? error.message : String(error) })
-    }
-    options?.onProgress?.(i + 1, rows.length)
-  }
-  return { created, failed }
-}

package/src/data/cached.ts

@@ -1,55 +0,0 @@
-import type { DataProvider, CrudQuery, CrudResult } from './types'
-import { globalCache, stableKey } from '../lib/cache'
-
-export interface ProviderCacheOptions {
-  /** Table/entity name — used as cache key namespace */
-  table: string
-  /** Dynamic tenant ID resolver */
-  tenantId: () => string | undefined
-  /** Override default TTL for this entity (ms) */
-  ttl?: number
-}
-
-/**
- * Wraps a DataProvider with transparent read caching + mutation invalidation.
- *
- * - `list()` results are cached by query params
- * - `create()`, `update()`, `remove()` invalidate all cached entries for the table
- */
-export function withCache<T extends { id: string }>(
-  provider: DataProvider<T>,
-  options: ProviderCacheOptions,
-): DataProvider<T> {
-  function prefix(): string {
-    return `${options.tenantId() ?? '_'}:${options.table}`
-  }
-
-  return {
-    async list(query: CrudQuery): Promise<CrudResult<T>> {
-      const key = `${prefix()}:${stableKey(query)}`
-      const cached = globalCache.get<CrudResult<T>>(key)
-      if (cached) return cached
-
-      const result = await provider.list(query)
-      globalCache.set(key, result, options.ttl)
-      return result
-    },
-
-    async create(data) {
-      const result = await provider.create(data)
-      globalCache.invalidate(prefix())
-      return result
-    },
-
-    async update(id, data) {
-      const result = await provider.update(id, data)
-      globalCache.invalidate(prefix())
-      return result
-    },
-
-    async remove(id) {
-      await provider.remove(id)
-      globalCache.invalidate(prefix())
-    },
-  }
-}

package/src/data/count.test.ts

@@ -1,152 +0,0 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest'
-import { countByTenant, invalidateCount } from './count'
-import { setGlobalSupabaseClient } from './supabase'
-import { setActiveTenantId } from '../tenant'
-
-// ---------------------------------------------------------------------------
-// Mock Supabase client — a thenable query builder that records .eq/.gte calls.
-// ---------------------------------------------------------------------------
-
-interface MockClient {
-  client: unknown
-  selectCalls: number
-  lastEq: Array<[string, unknown]>
-  lastGte: Array<[string, unknown]>
-  setCount: (n: number, error?: unknown) => void
-}
-
-function makeClient(initialCount = 0): MockClient {
-  const state = { count: initialCount as number, error: null as unknown }
-  const record: MockClient = {
-    client: null,
-    selectCalls: 0,
-    lastEq: [],
-    lastGte: [],
-    setCount: (n, error = null) => {
-      state.count = n
-      state.error = error
-    },
-  }
-
-  const query: Record<string, unknown> = {
-    eq: (col: string, val: unknown) => {
-      record.lastEq.push([col, val])
-      return query
-    },
-    gte: (col: string, val: unknown) => {
-      record.lastGte.push([col, val])
-      return query
-    },
-    then: (resolve: (r: { count: number; error: unknown }) => void) =>
-      resolve({ count: state.count, error: state.error }),
-  }
-
-  record.client = {
-    from: () => ({
-      select: (_cols: string, _opts: unknown) => {
-        record.selectCalls++
-        return query
-      },
-    }),
-  }
-  return record
-}
-
-describe('countByTenant', () => {
-  beforeEach(() => {
-    invalidateCount() // clear all cached counts
-    setGlobalSupabaseClient(null as unknown as object)
-    setActiveTenantId('tenant-1')
-  })
-
-  it('returns 0 in mock mode (no supabase client) — never blocks', async () => {
-    setGlobalSupabaseClient(null as unknown as object)
-    expect(await countByTenant('clients')).toBe(0)
-  })
-
-  it('returns 0 when no tenant is resolvable', async () => {
-    setActiveTenantId(undefined)
-    const m = makeClient(5)
-    setGlobalSupabaseClient(m.client as object)
-    expect(await countByTenant('clients')).toBe(0)
-  })
-
-  it('counts tenant-scoped rows via head:true', async () => {
-    const m = makeClient(42)
-    setGlobalSupabaseClient(m.client as object)
-    expect(await countByTenant('clients')).toBe(42)
-    expect(m.lastEq).toContainEqual(['tenant_id', 'tenant-1'])
-  })
-
-  it('caches within the TTL (second read does not hit the DB)', async () => {
-    const m = makeClient(10)
-    setGlobalSupabaseClient(m.client as object)
-    await countByTenant('clients')
-    await countByTenant('clients')
-    expect(m.selectCalls).toBe(1)
-  })
-
-  it('fresh:true bypasses the cache', async () => {
-    const m = makeClient(10)
-    setGlobalSupabaseClient(m.client as object)
-    await countByTenant('clients')
-    await countByTenant('clients', { fresh: true })
-    expect(m.selectCalls).toBe(2)
-  })
-
-  it('invalidateCount(table) drops the cached value', async () => {
-    const m = makeClient(10)
-    setGlobalSupabaseClient(m.client as object)
-    await countByTenant('clients')
-    invalidateCount('clients')
-    await countByTenant('clients')
-    expect(m.selectCalls).toBe(2)
-  })
-
-  it('separate keys (kind/period) are cached independently', async () => {
-    const m = makeClient(3)
-    setGlobalSupabaseClient(m.client as object)
-    await countByTenant('bookings', { period: 'month' })
-    await countByTenant('bookings', { period: 'total' })
-    expect(m.selectCalls).toBe(2)
-  })
-
-  it('applies kind filter and month window', async () => {
-    const m = makeClient(7)
-    setGlobalSupabaseClient(m.client as object)
-    await countByTenant('items', { kind: 'product', period: 'month' })
-    expect(m.lastEq).toContainEqual(['kind', 'product'])
-    expect(m.lastGte.some(([col]) => col === 'created_at')).toBe(true)
-  })
-
-  it('fails open (returns 0) when the query errors', async () => {
-    const m = makeClient(0)
-    m.setCount(0, new Error('boom'))
-    setGlobalSupabaseClient(m.client as object)
-    expect(await countByTenant('clients')).toBe(0)
-  })
-
-  it('fails open (returns 0) instead of hanging when the query never settles', async () => {
-    // A cold-boot query can be issued before the auth session is ready and then
-    // never resolve. The guard awaiting this must not hang the UI forever.
-    const client = {
-      from: () => ({
-        select: () => ({
-          eq: () => ({
-            eq: () => neverSettles,
-            gte: () => neverSettles,
-            then: neverSettles.then.bind(neverSettles),
-          }),
-        }),
-      }),
-    }
-    const neverSettles = { then: () => {} } as unknown as Promise<never>
-    setGlobalSupabaseClient(client as object)
-
-    vi.useFakeTimers()
-    const pending = countByTenant('clients', { fresh: true })
-    await vi.advanceTimersByTimeAsync(6_000)
-    await expect(pending).resolves.toBe(0)
-    vi.useRealTimers()
-  })
-})

package/src/data/count.ts

@@ -1,131 +0,0 @@
-import { getSupabaseClientOptional } from './supabase'
-import { getActiveTenantId } from '../tenant'
-
-/**
- * Tenant-scoped row counter — the single cheap `count(*)` helper the access
- * engine uses to resolve quantity limits. Uses Supabase's `head:true` count so
- * no rows are transferred. Results are cached briefly per tenant+table+filter to
- * survive the burst of reads a page does (nav badge + gate + list), and can be
- * force-invalidated by creates via {@link invalidateCount}.
- *
- * MOCK MODE NEVER BLOCKS: with no global Supabase client the count is `0`, so
- * limits always read as "well under cap" — offline/demo apps stay fully usable.
- */
-
-export interface CountByTenantOptions {
-  /** Optional `kind` column filter for multi-kind tables. */
-  kind?: string
-  /** `'month'` counts rows created since the 1st of the current month; `'total'` (default) counts all. */
-  period?: 'month' | 'total'
-  /** Tenant override; defaults to the active tenant (getActiveTenantId). */
-  tenantId?: string
-  /** Skip the short-lived cache and hit the DB (used by fresh guard checks). */
-  fresh?: boolean
-}
-
-const TTL_MS = 15_000
-
-interface CacheEntry {
-  value: number
-  expires: number
-}
-
-const cache = new Map<string, CacheEntry>()
-
-function cacheKey(table: string, tenantId: string, kind: string | undefined, period: string): string {
-  return `${tenantId}::${table}::${kind ?? ''}::${period}`
-}
-
-function startOfMonthISO(): string {
-  const now = new Date()
-  return new Date(now.getFullYear(), now.getMonth(), 1).toISOString()
-}
-
-/**
- * How long a usage count may take before we give up on it. Failing OPEN on an
- * error was always the policy (see below); a request that never settles is the
- * same failure with worse symptoms — a caller awaiting this (the create guards)
- * hangs forever, which reads to the user as a dead button. Observed on a cold
- * boot, where the query can be issued before the auth session is ready.
- */
-const COUNT_TIMEOUT_MS = 5_000
-
-/**
- * Count rows in `table` for the given (or active) tenant.
- * Returns 0 when no Supabase client is registered (mock mode).
- */
-export async function countByTenant(table: string, options: CountByTenantOptions = {}): Promise<number> {
-  const tenantId = options.tenantId ?? getActiveTenantId()
-  if (!tenantId) return 0
-
-  const period = options.period ?? 'total'
-  const key = cacheKey(table, tenantId, options.kind, period)
-
-  if (!options.fresh) {
-    const hit = cache.get(key)
-    if (hit && hit.expires > Date.now()) return hit.value
-  }
-
-  const client = getSupabaseClientOptional() as {
-    from: (t: string) => {
-      select: (columns: string, opts: { count: 'exact'; head: true }) => {
-        eq: (col: string, val: unknown) => unknown
-      }
-    }
-  } | null
-
-  // No client → mock/offline mode: never block.
-  if (!client) return 0
-
-  let query = client.from(table).select('*', { count: 'exact', head: true }).eq('tenant_id', tenantId) as {
-    eq: (col: string, val: unknown) => unknown
-    gte: (col: string, val: unknown) => unknown
-  }
-
-  if (options.kind) {
-    query = query.eq('kind', options.kind) as typeof query
-  }
-  if (period === 'month') {
-    query = query.gte('created_at', startOfMonthISO()) as typeof query
-  }
-
-  // On error OR timeout, fail OPEN (return 0) — a counting failure must never
-  // wall a tenant out of their own product, and must never hang the UI awaiting
-  // it. Enforcement's source of truth is the DB anyway.
-  let timer: ReturnType<typeof setTimeout> | undefined
-  const timeout = new Promise<{ count: null; error: unknown; timedOut: true }>((resolve) => {
-    timer = setTimeout(() => resolve({ count: null, error: 'timeout', timedOut: true }), COUNT_TIMEOUT_MS)
-  })
-  const settled = await Promise.race([
-    query as unknown as Promise<{ count: number | null; error: unknown }>,
-    timeout,
-  ])
-  if (timer) clearTimeout(timer)
-
-  const { count, error } = settled
-  const value = error ? 0 : count ?? 0
-
-  // A timed-out count is not a fact about the tenant — caching it would make one
-  // slow request suppress the guard for the whole TTL.
-  if (!(settled as { timedOut?: true }).timedOut) {
-    cache.set(key, { value, expires: Date.now() + TTL_MS })
-  }
-  return value
-}
-
-/**
- * Drop cached counts. Called by create handlers (via invalidateLimit) so the
- * next read reflects the row they just added.
- *
- * @param tenantOrKey Substring matched against cache keys (a tenant id, a table
- *   name, or any fragment). Omit to clear the entire cache.
- */
-export function invalidateCount(tenantOrKey?: string): void {
-  if (!tenantOrKey) {
-    cache.clear()
-    return
-  }
-  for (const key of cache.keys()) {
-    if (key.includes(tenantOrKey)) cache.delete(key)
-  }
-}