@fayz-ai/core 0.8.3 → 0.8.5

package/src/data/filters.test.ts

@@ -0,0 +1,70 @@
+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

@@ -0,0 +1,90 @@
+/**
+ * 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 +1,11 @@
 export { createSupabaseProvider, setGlobalSupabaseClient, getSupabaseClientOptional } from './supabase'
 export { countByTenant, invalidateCount } from './count'
 export type { CountByTenantOptions } from './count'
-export { getFayzCloudClient, FAYZ_CLOUD_URL, FAYZ_CLOUD_PUBLISHABLE_KEY } from './cloud'
 export { createFayzApiProvider } from './platform-api'
 export { createMockProvider } from './mock'
+export { bulkCreate } from './bulk'
 export { resolveDataProvider } from './resolve'
-export type { DataProvider, CrudQuery, CrudResult } from './types'
+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,5 +1,6 @@
 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[],
@@ -28,11 +29,16 @@ export function createMockProvider<T extends { id: string; [key: string]: unknow
         )
       }
 
-      // Faceted / dynamic filters (equality match per key).
+      // 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
-          filtered = filtered.filter((item) => item[key] === val)
+          const range = parseRangeFilter(val)
+          filtered = range
+            ? filtered.filter((item) => matchesRange(item[key], range))
+            : filtered.filter((item) => item[key] === val)
         }
       }
 

package/src/data/platform-api.ts

@@ -1,4 +1,5 @@
 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'
 
@@ -85,11 +86,19 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 
 function normalizeFilters(filters?: Record<string, unknown>): FayzApiTableFilter[] {
   if (!filters) return []
-  return Object.entries(filters).map(([column, raw]) => {
+  return Object.entries(filters).flatMap(([column, raw]): FayzApiTableFilter[] => {
     if (isRecord(raw) && isFilterOperator(raw.operator)) {
-      return { column, operator: raw.operator, value: raw.value }
+      return [{ column, operator: raw.operator, value: raw.value }]
     }
-    return { column, operator: 'eq', value: raw }
+    // 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 }]
   })
 }
 

package/src/data/refresh.ts

@@ -75,7 +75,17 @@ function flush(): void {
  */
 export function emitDataChanged(payload: DataChangedPayload = {}): void {
   if (payload.table) {
-    globalCache.invalidate(`${getActiveTenantId() ?? '_'}:${payload.table}`)
+    const tenant = getActiveTenantId() ?? '_'
+    // The base table and its read-model view are the SAME data under two cache
+    // namespaces (appointments / v_appointments). Invalidating only the one the
+    // writer names leaves the other serving a snapshot that predates the write
+    // — which is how the assistant kept reporting an empty agenda after a
+    // booking was created on the agenda screen.
+    const sibling = payload.table.startsWith('v_')
+      ? payload.table.slice(2)
+      : `v_${payload.table}`
+    globalCache.invalidate(`${tenant}:${payload.table}`)
+    globalCache.invalidate(`${tenant}:${sibling}`)
   } else {
     globalCache.clear()
   }

package/src/data/resolve.ts

@@ -19,6 +19,16 @@ import { getActiveTenantId } from '../tenant'
 export interface ResolveDataProviderOptions {
   backend?: BackendRef
   fayzApi?: Omit<FayzApiProviderConfig, 'entityKey' | 'table'>
+  /**
+   * Read through the shared TTL cache (default true).
+   *
+   * Callers that must observe writes made by ANOTHER surface pass false: the
+   * cache is only invalidated by writes that go through it, so a record created
+   * on the agenda screen stays invisible to the assistant for the rest of the
+   * TTL — which is how "o que tem na agenda hoje?" answered "nada" over a
+   * booking made seconds earlier.
+   */
+  cache?: boolean
   customProviders?: Record<string, <T extends { id: string }>(entityDef: EntityDef<T>, mockData?: T[]) => DataProvider<T>>
 }
 
@@ -77,9 +87,11 @@ export function resolveDataProvider<T extends { id: string }>(
       tenantId,
       ttl: entityDef.data.cacheTTL,
     }
+    const cached = <P extends DataProvider<T>>(p: P): DataProvider<T> =>
+      options.cache === false ? p : withCache(p, cacheOptions)
 
     if (entityDef.data.archetype && entityDef.data.archetypeKind && !entityDef.data.schema) {
-      return withCache(createArchetypeProvider<T>({
+      return cached(createArchetypeProvider<T>({
         archetype: entityDef.data.archetype,
         archetypeKind: entityDef.data.archetypeKind,
         projectTable: entityDef.data.table,
@@ -87,10 +99,10 @@ export function resolveDataProvider<T extends { id: string }>(
         searchColumns: entityDef.data.searchColumns ?? entityDef.fields
           .filter((field) => field.searchable)
           .map((field) => field.key),
-      }), cacheOptions)
+      }))
     }
 
-    return withCache(createSupabaseProvider<T>(entityDef.data.table, {
+    return cached(createSupabaseProvider<T>(entityDef.data.table, {
       schema: entityDef.data.schema,
       tenantId: entityDef.data.tenantScoped === false ? undefined : tenantId,
       tenantIdColumn: entityDef.data.tenantIdColumn,
@@ -101,7 +113,7 @@ export function resolveDataProvider<T extends { id: string }>(
       columnMap: entityDef.data.columnMap,
       filters: entityDef.data.filters,
       defaults: entityDef.data.defaults,
-    }), cacheOptions)
+    }))
   }
 
   if (entityDef.data?.table) {

package/src/data/supabase.ts

@@ -1,4 +1,5 @@
 import type { DataProvider, CrudQuery, CrudResult } from './types'
+import { applyRangeToQuery, isFilterObject, parseRangeFilter } from './filters'
 
 export interface SupabaseProviderConfig {
   schema?: string
@@ -96,11 +97,24 @@ export function createSupabaseProvider<T extends { id: string }>(
         }
       }
 
-      // Faceted / dynamic filters from the query (equality, mapped to columns).
+      // Faceted / dynamic filters from the query, mapped to columns. Equality
+      // by default; a range object ({from,to} / {gte,lt} / {$gte,$lt}) becomes
+      // real SQL bounds instead of an equality compare against "[object Object]".
       if (query.filters) {
         for (const [key, val] of Object.entries(query.filters)) {
           if (val == null || val === '') continue
           const col = columnMap?.[key] ?? 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 as { eq: (c: string, v: unknown) => unknown }).eq(col, val) as Record<string, unknown>
         }
       }
@@ -151,6 +165,51 @@ export function createSupabaseProvider<T extends { id: string }>(
       return mapRow<T>(created!, columnMap)
     },
 
+    async createMany(rows, options) {
+      const tenantId = resolveTenantId()
+      const size = Math.max(1, options?.chunkSize ?? 200)
+      const prepared = rows.map((r) => {
+        const row = mapEntity(r as Record<string, unknown>, columnMap)
+        if (tenantId) row[tenantIdCol] = tenantId
+        if (config?.defaults) {
+          for (const [col, val] of Object.entries(config.defaults)) {
+            if (row[col] === undefined) row[col] = val
+          }
+        }
+        return row
+      })
+
+      let created = 0
+      const failed: Array<{ index: number; message: string }> = []
+      for (let start = 0; start < prepared.length; start += size) {
+        const chunk = prepared.slice(start, start + size)
+        const { error } = (await (getClient().from(table) as {
+          insert: (r: unknown) => Promise<{ error: unknown }>
+        }).insert(chunk)) as { error: unknown }
+        if (!error) {
+          created += chunk.length
+        } else {
+          // One bad row rejects its whole chunk. Retrying it row by row keeps
+          // the other 199 — an import that loses 200 records over one malformed
+          // phone number is worse than no import.
+          const message = error instanceof Error ? error.message : String(error)
+          for (let i = 0; i < chunk.length; i++) {
+            const { error: rowError } = (await (getClient().from(table) as {
+              insert: (r: unknown) => Promise<{ error: unknown }>
+            }).insert(chunk[i])) as { error: unknown }
+            if (rowError) {
+              failed.push({
+                index: start + i,
+                message: rowError instanceof Error ? rowError.message : String(rowError ?? message),
+              })
+            } else created += 1
+          }
+        }
+        options?.onProgress?.(Math.min(start + chunk.length, prepared.length), prepared.length)
+      }
+      return { created, failed }
+    },
+
     async update(id, data) {
       const row = mapEntity(data as Record<string, unknown>, columnMap)
       const { data: updated, error } = (await (getClient().from(table) as {

package/src/data/types.ts

@@ -18,9 +18,33 @@ export interface CrudResult<T> {
   total: number
 }
 
+/** Outcome of a bulk write: what landed, and what did not and why. */
+export interface BulkWriteResult {
+  created: number
+  failed: Array<{ index: number; message: string }>
+}
+
+export interface BulkWriteOptions {
+  /** Rows per round-trip. Larger is fewer trips; too large trips statement timeouts. */
+  chunkSize?: number
+  onProgress?: (done: number, total: number) => void
+}
+
 export interface DataProvider<T extends { id: string } = { id: string }> {
   list(query: CrudQuery): Promise<CrudResult<T>>
   create(data: Omit<T, 'id' | 'createdAt' | 'updatedAt' | 'tenantId'>): Promise<T>
+  /**
+   * Write many rows in as few round-trips as the backend allows.
+   *
+   * Optional: `bulkCreate` falls back to looping `create` for providers that do
+   * not implement it, so a caller never has to branch. Importing a 900-row
+   * client list one INSERT at a time is 900 round-trips — the difference
+   * between a progress bar and a hung tab.
+   */
+  createMany?(
+    rows: Array<Omit<T, 'id' | 'createdAt' | 'updatedAt' | 'tenantId'>>,
+    options?: BulkWriteOptions,
+  ): Promise<BulkWriteResult>
   update(id: string, data: Partial<T>): Promise<T>
   remove(id: string): Promise<void>
 }

package/src/i18n/index.ts

@@ -1,5 +1,5 @@
 import * as React from 'react'
-import { shellTranslations } from './shell-translations'
+import { shellTranslationsEn } from './shell-translations.en'
 
 export interface I18nConfig {
   defaultLocale: string
@@ -63,16 +63,26 @@ export function setLocaleStore(store: LocaleStore): void {
   _localeStore = store
 }
 
+// Bumped when lazily-loaded translations register so subscribed components
+// re-render even though the locale string itself did not change.
+let _i18nVersion = 0
+function getI18nSnapshot(): string {
+  return `${_localeStore.locale} ${_i18nVersion}`
+}
+
 function useLocaleStore(): LocaleStore {
-  const locale = React.useSyncExternalStore(
+  const snapshot = React.useSyncExternalStore(
     (listener) => {
       _localeListeners.add(listener)
       return () => _localeListeners.delete(listener)
     },
-    getCurrentLocale,
-    getCurrentLocale,
+    getI18nSnapshot,
+    getI18nSnapshot,
   )
-  return React.useMemo(() => ({ locale, setLocale: setCurrentLocale }), [locale])
+  return React.useMemo(() => {
+    const locale = snapshot.slice(0, snapshot.indexOf(' '))
+    return { locale, setLocale: setCurrentLocale }
+  }, [snapshot])
 }
 
 export function getCurrentLocale(): string {
@@ -82,6 +92,9 @@ export function getCurrentLocale(): string {
 export function setCurrentLocale(locale: string): void {
   if (_localeStore.locale === locale) return
   _localeStore.setLocale(locale)
+  // Fire-and-forget: if the locale's shell translations are lazily split, load
+  // and register them; keys fall back to 'en' until the chunk arrives.
+  void preloadLocale(locale)
   _localeListeners.forEach((listener) => listener())
 }
 
@@ -157,6 +170,7 @@ export const coreTranslations: Record<string, Record<string, string>> = {
     'settings.company': 'Company',
     'settings.branding': 'Branding',
     'settings.security': 'Security',
+    'settings.sites': 'Sites',
     'settings.team': 'Team',
     'settings.billing': 'Billing',
     'settings.locations': 'Locations',
@@ -235,6 +249,7 @@ export const coreTranslations: Record<string, Record<string, string>> = {
     'settings.company': 'Empresa',
     'settings.branding': 'Identidade Visual',
     'settings.security': 'Segurança',
+    'settings.sites': 'Sites',
     'settings.team': 'Equipe',
     'settings.billing': 'Faturamento',
     'settings.locations': 'Localizações',
@@ -273,4 +288,41 @@ export function mergeTranslations(
 // the native CRUD engine, framework UI and de-bridged plugins resolve their
 // keys even under a host shell that does not mount @fayz-ai/core's I18nProvider.
 registerTranslations(coreTranslations)
-registerTranslations(shellTranslations)
+registerTranslations({ en: shellTranslationsEn })
+
+// ---------------------------------------------------------------------------
+// Lazy shell locales. Only 'en' (the fallback) ships eagerly; other locales
+// load on demand when the app switches to them (setCurrentLocale) or when the
+// app awaits preloadLocale before rendering. Keys resolve through the 'en'
+// fallback until the locale chunk arrives, then listeners re-render.
+// ---------------------------------------------------------------------------
+
+const _lazyShellLocales: Record<string, () => Promise<Record<string, string>>> = {
+  'pt-BR': () => import('./shell-translations.pt-br').then((m) => m.shellTranslationsPtBr),
+}
+const _loadedShellLocales = new Set<string>(['en'])
+const _pendingShellLocales = new Map<string, Promise<void>>()
+
+/**
+ * Ensure a lazily-split shell locale is loaded and registered. Resolves
+ * immediately for unknown/already-loaded locales. setCurrentLocale calls this
+ * fire-and-forget; apps that must avoid an English flash on first paint can
+ * `await preloadLocale('pt-BR')` before rendering.
+ */
+export function preloadLocale(locale: string): Promise<void> {
+  if (_loadedShellLocales.has(locale)) return Promise.resolve()
+  const loader = _lazyShellLocales[locale]
+  if (!loader) return Promise.resolve()
+  let pending = _pendingShellLocales.get(locale)
+  if (!pending) {
+    pending = loader().then((translations) => {
+      _loadedShellLocales.add(locale)
+      _pendingShellLocales.delete(locale)
+      registerTranslations({ [locale]: translations })
+      _i18nVersion++
+      _localeListeners.forEach((listener) => listener())
+    })
+    _pendingShellLocales.set(locale, pending)
+  }
+  return pending
+}