@fayz-ai/core 0.9.0 → 0.10.0

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)
-  }
-}

package/src/data/filters.test.ts

@@ -1,70 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { parseRangeFilter, isFilterObject, matchesRange, applyRangeToQuery } from './filters'
-
-describe('parseRangeFilter', () => {
-  it('reads the {from,to} dialect', () => {
-    expect(parseRangeFilter({ from: 1, to: 5 })).toEqual({ gte: 1, lte: 5 })
-  })
-
-  it('reads the Mongo dialect the models actually emit', () => {
-    // The exact filter that answered "não há compromissos hoje" over a booked day.
-    expect(
-      parseRangeFilter({ $gte: '2026-07-27T00:00:00Z', $lt: '2026-07-28T00:00:00Z' }),
-    ).toEqual({ gte: '2026-07-27T00:00:00Z', lt: '2026-07-28T00:00:00Z' })
-  })
-
-  it('reads bare comparison keys', () => {
-    expect(parseRangeFilter({ gte: 10, lt: 20 })).toEqual({ gte: 10, lt: 20 })
-  })
-
-  it('returns null for plain values, so they stay equality filters', () => {
-    expect(parseRangeFilter('open')).toBeNull()
-    expect(parseRangeFilter(3)).toBeNull()
-    expect(parseRangeFilter(null)).toBeNull()
-  })
-
-  it('returns null for an object with no recognised bound — never a silent match-nothing', () => {
-    expect(parseRangeFilter({ equals: 'open' })).toBeNull()
-    expect(isFilterObject({ equals: 'open' })).toBe(true)
-  })
-})
-
-describe('matchesRange', () => {
-  const day = { gte: '2026-07-27T00:00:00Z', lt: '2026-07-28T00:00:00Z' }
-
-  it('keeps a timestamp inside the window', () => {
-    expect(matchesRange('2026-07-27T18:00:00+00:00', day)).toBe(true)
-  })
-
-  it('drops the bounds it should', () => {
-    expect(matchesRange('2026-07-28T00:00:00Z', day)).toBe(false)
-    expect(matchesRange('2026-07-26T23:59:59Z', day)).toBe(false)
-  })
-
-  it('honours inclusive upper bounds', () => {
-    expect(matchesRange(5, { gte: 1, lte: 5 })).toBe(true)
-    expect(matchesRange(5, { gte: 1, lt: 5 })).toBe(false)
-  })
-
-  it('rejects values that are not comparable instead of letting them through', () => {
-    expect(matchesRange(null, day)).toBe(false)
-    expect(matchesRange('não é data', day)).toBe(false)
-  })
-})
-
-describe('applyRangeToQuery', () => {
-  it('emits one PostgREST call per bound', () => {
-    const calls: Array<[string, string, unknown]> = []
-    const builder = {
-      gte(c: string, v: unknown) { calls.push(['gte', c, v]); return this },
-      gt(c: string, v: unknown) { calls.push(['gt', c, v]); return this },
-      lte(c: string, v: unknown) { calls.push(['lte', c, v]); return this },
-      lt(c: string, v: unknown) { calls.push(['lt', c, v]); return this },
-    }
-    applyRangeToQuery(builder, 'starts_at', { gte: 'a', lt: 'b' })
-    expect(calls).toEqual([
-      ['gte', 'starts_at', 'a'],
-      ['lt', 'starts_at', 'b'],
-    ])
-  })
-})

package/src/data/filters.ts

@@ -1,90 +0,0 @@
-/**
- * ONE filter grammar, shared by the providers and by the agent's data tools.
- *
- * Models express ranges in whatever dialect they were trained on — `{from,to}`,
- * `{gte,lte}`, Mongo's `{$gte,$lt}`. When only some of those are recognised the
- * unrecognised one falls through to an equality compare against
- * "[object Object]", which matches nothing and reads as "there are no
- * appointments today" instead of "I did not understand that filter".
- */
-
-export interface RangeFilter {
-  gte?: unknown
-  gt?: unknown
-  lte?: unknown
-  lt?: unknown
-}
-
-const LOWER_INCLUSIVE = ['from', 'gte', 'start', 'after', 'since', 'min']
-const LOWER_EXCLUSIVE = ['gt']
-const UPPER_INCLUSIVE = ['to', 'lte', 'end', 'until', 'before', 'max']
-const UPPER_EXCLUSIVE = ['lt']
-
-function pick(source: Record<string, unknown>, names: string[]): unknown {
-  for (const name of names) {
-    if (source[name] !== undefined && source[name] !== null) return source[name]
-    const dollar = `$${name}`
-    if (source[dollar] !== undefined && source[dollar] !== null) return source[dollar]
-  }
-  return undefined
-}
-
-/**
- * Parse a filter value into a range, or return null when it is a plain
- * (equality) value. An object that looks like a filter but carries no
- * recognised bound returns `null` too — callers treat that as "invalid",
- * never as "matches nothing".
- */
-export function parseRangeFilter(value: unknown): RangeFilter | null {
-  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
-  const source = value as Record<string, unknown>
-  const range: RangeFilter = {}
-  const gte = pick(source, LOWER_INCLUSIVE)
-  const gt = pick(source, LOWER_EXCLUSIVE)
-  const lte = pick(source, UPPER_INCLUSIVE)
-  const lt = pick(source, UPPER_EXCLUSIVE)
-  if (gte !== undefined) range.gte = gte
-  if (gt !== undefined) range.gt = gt
-  if (lte !== undefined) range.lte = lte
-  if (lt !== undefined) range.lt = lt
-  return Object.keys(range).length ? range : null
-}
-
-/** True for any object value — including ones no bound could be read from. */
-export function isFilterObject(value: unknown): boolean {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function comparable(value: unknown): number {
-  if (typeof value === 'number') return value
-  if (value instanceof Date) return value.getTime()
-  const ts = Date.parse(String(value))
-  if (!Number.isNaN(ts)) return ts
-  return Number(value)
-}
-
-/** Client-side counterpart of the range a provider would push to SQL. */
-export function matchesRange(raw: unknown, range: RangeFilter): boolean {
-  const value = comparable(raw)
-  if (Number.isNaN(value)) return false
-  if (range.gte !== undefined && value < comparable(range.gte)) return false
-  if (range.gt !== undefined && value <= comparable(range.gt)) return false
-  if (range.lte !== undefined && value > comparable(range.lte)) return false
-  if (range.lt !== undefined && value >= comparable(range.lt)) return false
-  return true
-}
-
-/** Apply a range to a PostgREST query builder. */
-export function applyRangeToQuery<Q>(
-  query: Q,
-  column: string,
-  range: RangeFilter,
-): Q {
-  let q = query as Record<string, (c: string, v: unknown) => unknown>
-  for (const op of ['gte', 'gt', 'lte', 'lt'] as const) {
-    const bound = range[op]
-    if (bound === undefined) continue
-    q = q[op](column, bound) as Record<string, (c: string, v: unknown) => unknown>
-  }
-  return q as Q
-}

package/src/data/index.ts

@@ -1,11 +0,0 @@
-export { createSupabaseProvider, setGlobalSupabaseClient, getSupabaseClientOptional } from './supabase'
-export { countByTenant, invalidateCount } from './count'
-export type { CountByTenantOptions } from './count'
-export { createFayzApiProvider } from './platform-api'
-export { createMockProvider } from './mock'
-export { bulkCreate } from './bulk'
-export { resolveDataProvider } from './resolve'
-export type { DataProvider, CrudQuery, CrudResult, BulkWriteOptions, BulkWriteResult } from './types'
-export type { SupabaseProviderConfig } from './supabase'
-export type { FayzApiProviderConfig } from './platform-api'
-export type { ResolveDataProviderOptions } from './resolve'

package/src/data/mock.ts

@@ -1,90 +0,0 @@
-import type { DataProvider, CrudQuery, CrudResult } from './types'
-import type { EntityDef } from '../types/crud'
-import { matchesRange, parseRangeFilter } from './filters'
-
-export function createMockProvider<T extends { id: string; [key: string]: unknown }>(
-  entityDefOrSearchKeys: EntityDef<T> | string[],
-  initialData: T[] = [],
-): DataProvider<T> {
-  let items = [...initialData]
-
-  const searchableKeys = Array.isArray(entityDefOrSearchKeys)
-    ? entityDefOrSearchKeys
-    : entityDefOrSearchKeys.fields.filter((f) => f.searchable).map((f) => f.key)
-
-  const defaultSort = Array.isArray(entityDefOrSearchKeys) ? undefined : entityDefOrSearchKeys.defaultSort
-  const defaultSortDir = Array.isArray(entityDefOrSearchKeys) ? 'asc' : (entityDefOrSearchKeys.defaultSortDir ?? 'asc')
-
-  return {
-    async list(query: CrudQuery): Promise<CrudResult<T>> {
-      let filtered = [...items]
-
-      if (query.search && searchableKeys.length > 0) {
-        const term = query.search.toLowerCase()
-        filtered = filtered.filter((item) =>
-          searchableKeys.some((key) => {
-            const val = item[key]
-            return typeof val === 'string' && val.toLowerCase().includes(term)
-          }),
-        )
-      }
-
-      // Faceted / dynamic filters — same grammar the SQL providers speak, so a
-      // date window behaves identically on mock data instead of silently
-      // matching nothing (a range object is never `===` anything).
-      if (query.filters) {
-        for (const [key, val] of Object.entries(query.filters)) {
-          if (val == null || val === '') continue
-          const range = parseRangeFilter(val)
-          filtered = range
-            ? filtered.filter((item) => matchesRange(item[key], range))
-            : filtered.filter((item) => item[key] === val)
-        }
-      }
-
-      const sortBy = query.sortBy ?? defaultSort
-      const sortDir = query.sortDir ?? defaultSortDir
-      if (sortBy) {
-        filtered.sort((a, b) => {
-          const av = a[sortBy] ?? ''
-          const bv = b[sortBy] ?? ''
-          const cmp = typeof av === 'number' && typeof bv === 'number'
-            ? av - bv
-            : String(av).localeCompare(String(bv))
-          return sortDir === 'desc' ? -cmp : cmp
-        })
-      }
-
-      const total = filtered.length
-      const page = query.page ?? 1
-      const pageSize = query.pageSize ?? 50
-      const start = (page - 1) * pageSize
-      const data = filtered.slice(start, start + pageSize)
-      return { data, total }
-    },
-
-    async create(data) {
-      const now = new Date().toISOString()
-      const item = {
-        ...data,
-        id: crypto.randomUUID(),
-        tenantId: 'mock-tenant',
-        createdAt: now,
-        updatedAt: now,
-      } as unknown as T
-      items.unshift(item)
-      return item
-    },
-
-    async update(id, data) {
-      const idx = items.findIndex((i) => i.id === id)
-      if (idx === -1) throw new Error(`[@fayz-ai/core] Mock provider: item not found: ${id}`)
-      items[idx] = { ...items[idx], ...data, updatedAt: new Date().toISOString() }
-      return items[idx]!
-    },
-
-    async remove(id) {
-      items = items.filter((i) => i.id !== id)
-    },
-  }
-}

package/src/data/platform-api.ts

@@ -1,209 +0,0 @@
-import type { CrudQuery, CrudResult, DataProvider } from './types'
-import { parseRangeFilter } from './filters'
-
-type FayzApiFilterOperator = 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'like' | 'ilike' | 'is_null' | 'is_not_null'
-
-interface FayzApiTableFilter {
-  column: string
-  operator: FayzApiFilterOperator
-  value?: unknown
-}
-
-export interface FayzApiProviderConfig {
-  baseUrl?: string
-  projectId?: string
-  tenantId?: string | (() => string | undefined)
-  tenantIdColumn?: string | false
-  entityKey?: string
-  table?: string
-  schema?: string
-  idColumn?: string
-  searchColumns?: string[]
-  runtimeToken?: string | (() => string | undefined | Promise<string | undefined>)
-  headers?: () => HeadersInit | Promise<HeadersInit>
-  fetcher?: typeof fetch
-}
-
-function resolveTenantId(config?: FayzApiProviderConfig): string | undefined {
-  const tenantId = config?.tenantId
-  return typeof tenantId === 'function' ? tenantId() : tenantId
-}
-
-async function resolveRuntimeToken(config?: FayzApiProviderConfig): Promise<string | undefined> {
-  const runtimeToken = config?.runtimeToken
-  return typeof runtimeToken === 'function' ? runtimeToken() : runtimeToken
-}
-
-function trimTrailingSlash(value: string): string {
-  return value.replace(/\/+$/, '')
-}
-
-function appendQuery(
-  url: URL,
-  query: CrudQuery,
-  tenantId?: string,
-  tenantIdColumn = 'tenant_id',
-  searchColumns: string[] = [],
-): void {
-  const filters = normalizeFilters(query.filters)
-  if (query.search && searchColumns[0]) {
-    filters.push({ column: searchColumns[0], operator: 'ilike', value: `%${query.search}%` })
-  }
-  if (query.sortBy) url.searchParams.set('sortColumn', query.sortBy)
-  if (query.sortDir) url.searchParams.set('sortDirection', query.sortDir)
-  if (query.page != null) url.searchParams.set('page', String(query.page))
-  if (query.pageSize != null) url.searchParams.set('limit', String(query.pageSize))
-  if (tenantId) filters.push({ column: tenantIdColumn, operator: 'eq', value: tenantId })
-  if (filters.length > 0) url.searchParams.set('filters', JSON.stringify(filters))
-}
-
-async function parseResponse<T>(response: Response): Promise<T> {
-  if (!response.ok) {
-    const text = await response.text().catch(() => '')
-    throw new Error(`[@fayz-ai/core] Fayz API request failed (${response.status}): ${text || response.statusText}`)
-  }
-  return response.json() as Promise<T>
-}
-
-function isFilterOperator(value: unknown): value is FayzApiFilterOperator {
-  return typeof value === 'string' && [
-    'eq',
-    'neq',
-    'gt',
-    'lt',
-    'gte',
-    'lte',
-    'like',
-    'ilike',
-    'is_null',
-    'is_not_null',
-  ].includes(value)
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function normalizeFilters(filters?: Record<string, unknown>): FayzApiTableFilter[] {
-  if (!filters) return []
-  return Object.entries(filters).flatMap(([column, raw]): FayzApiTableFilter[] => {
-    if (isRecord(raw) && isFilterOperator(raw.operator)) {
-      return [{ column, operator: raw.operator, value: raw.value }]
-    }
-    // A range is TWO bounds on one column — sending it as a single `eq` filter
-    // compared the column against an object and matched nothing.
-    const range = parseRangeFilter(raw)
-    if (range) {
-      return (['gte', 'gt', 'lte', 'lt'] as const)
-        .filter((op) => range[op] !== undefined)
-        .map((op) => ({ column, operator: op, value: range[op] }))
-    }
-    return [{ column, operator: 'eq', value: raw }]
-  })
-}
-
-export function createFayzApiProvider<T extends { id: string }>(
-  entityOrTable: string,
-  config: FayzApiProviderConfig = {},
-): DataProvider<T> {
-  const fetcher = config.fetcher ?? fetch
-  const baseUrl = trimTrailingSlash(config.baseUrl ?? '')
-  const projectId = config.projectId
-  const table = config.table ?? entityOrTable
-  const idColumn = config.idColumn ?? 'id'
-
-  async function headers(runtimeToken?: string): Promise<HeadersInit> {
-    return {
-      'Content-Type': 'application/json',
-      ...(config.headers ? await config.headers() : {}),
-      ...(runtimeToken ? { Authorization: `Bearer ${runtimeToken}` } : {}),
-    }
-  }
-
-  function tableRowsUrl(runtime = false): URL {
-    const prefix = baseUrl || (typeof window !== 'undefined' ? window.location.origin : 'http://localhost')
-    const encodedProjectId = encodeURIComponent(projectId ?? 'current')
-    const encodedTable = encodeURIComponent(table)
-    const route = runtime
-      ? `/api/v1/runtime/projects/${encodedProjectId}/database/tables/${encodedTable}/rows`
-      : `/api/projects/${encodedProjectId}/database/tables/${encodedTable}/rows`
-    const url = new URL(route, prefix)
-    if (config.schema) url.searchParams.set('schema', config.schema)
-    return url
-  }
-
-  function withTenant(data: Record<string, unknown>, runtime = false): Record<string, unknown> {
-    if (runtime) return data
-    const tenantId = resolveTenantId(config)
-    if (!tenantId || config.tenantIdColumn === false) return data
-    return { ...data, [config.tenantIdColumn ?? 'tenant_id']: tenantId }
-  }
-
-  function primaryKeys(id: string): Record<string, unknown> {
-    return { [idColumn]: id }
-  }
-
-  async function listRows(query: CrudQuery): Promise<CrudResult<T>> {
-    const runtimeToken = await resolveRuntimeToken(config)
-    const runtime = Boolean(runtimeToken)
-    const url = tableRowsUrl(runtime)
-    appendQuery(
-      url,
-      query,
-      runtime || config.tenantIdColumn === false ? undefined : resolveTenantId(config),
-      config.tenantIdColumn || undefined,
-      config.searchColumns,
-    )
-    const result = await parseResponse<{ rows: T[]; total: number }>(await fetcher(url, { headers: await headers(runtimeToken) }))
-    return { data: result.rows, total: result.total }
-  }
-
-  async function assertTenantScopedRowExists(id: string, runtime = false): Promise<void> {
-    if (runtime) return
-    const tenantId = config.tenantIdColumn === false ? undefined : resolveTenantId(config)
-    if (!tenantId) return
-
-    const result = await listRows({ filters: { [idColumn]: id }, page: 1, pageSize: 1 })
-    if (result.data.length === 0) {
-      throw new Error(`[@fayz-ai/core] Row "${id}" was not found for the active tenant.`)
-    }
-  }
-
-  return {
-    async list(query: CrudQuery): Promise<CrudResult<T>> {
-      return listRows(query)
-    },
-
-    async create(data) {
-      const runtimeToken = await resolveRuntimeToken(config)
-      const runtime = Boolean(runtimeToken)
-      return parseResponse<T>(await fetcher(tableRowsUrl(runtime), {
-        method: 'POST',
-        headers: await headers(runtimeToken),
-        body: JSON.stringify(withTenant(data as Record<string, unknown>, runtime)),
-      }))
-    },
-
-    async update(id, data) {
-      const runtimeToken = await resolveRuntimeToken(config)
-      const runtime = Boolean(runtimeToken)
-      await assertTenantScopedRowExists(id, runtime)
-      return parseResponse<T>(await fetcher(tableRowsUrl(runtime), {
-        method: 'PATCH',
-        headers: await headers(runtimeToken),
-        body: JSON.stringify({ primaryKeys: primaryKeys(id), data }),
-      }))
-    },
-
-    async remove(id) {
-      const runtimeToken = await resolveRuntimeToken(config)
-      const runtime = Boolean(runtimeToken)
-      await assertTenantScopedRowExists(id, runtime)
-      await parseResponse<{ deletedCount: number }>(await fetcher(tableRowsUrl(runtime), {
-        method: 'DELETE',
-        headers: await headers(runtimeToken),
-        body: JSON.stringify({ rows: [primaryKeys(id)] }),
-      }))
-    },
-  }
-}