@fayz-ai/core 0.1.6

package/src/index.ts

@@ -0,0 +1,132 @@
+// Types
+export type { EntityArchetype, BaseEntity, PersonEntity, ProductEntity, ServiceEntity, OrderEntity, TransactionEntity, LocationEntity, ScheduleEntity, CategoryEntity } from './types/entities'
+export type { EntityDef, FieldDef, FieldType, FieldGroup, DetailTab, FormLayout, ComputedFieldValue } from './types/crud'
+export type { PluginManifest, PluginScope, PluginStatus, ResolvedPluginManifest, PluginRuntime, PluginRuntimeContext, PluginWidgetZone, PluginWidgetDefinition, PluginNavigationEntry, PluginSettingsTab, PluginRouteDefinition, PluginAITool, PluginRegistryDef, PluginMigration, VerticalId, ScaffoldType, TenantPluginBinding, DashboardWidgetDef, DashboardWidgetKind, DashboardSurface, DashboardLayoutConfig, ResolvedDashboardWidget } from './types/plugins'
+export { WidgetZone } from './types/plugins'
+export type { AuthAdapter, AuthUser, AuthSession, AuthProvider } from './types/auth'
+export type { OrgAdapter, Organization, OrgMember, OrgMembership, Location, Invite, CreateOrgOptions } from './types/org'
+export type { PermissionsConfig, FeatureDeclaration, PermissionAction, PermissionProfile } from './types/permissions'
+export type { Plan, BillingConfig } from './types/billing'
+export type { SaasTheme, ThemeConfig, ThemeBrand, ThemeRadius, ThemeMode } from './types/theme'
+export type { LocaleConfig } from './types/i18n'
+
+// Data providers
+export { createSupabaseProvider, setGlobalSupabaseClient, getSupabaseClientOptional } from './data/supabase'
+export { createFayzApiProvider } from './data/fayz-api'
+export { createMockProvider } from './data/mock'
+export { createArchetypeProvider } from './data/archetype'
+export { withCache } from './data/cached'
+export { resolveDataProvider } from './data/resolve'
+export { createSafeDataProvider } from './plugin/createSafeDataProvider'
+export type { DataProvider, CrudQuery, CrudResult, SupabaseProviderConfig, FayzApiProviderConfig } from './data/index'
+
+// Tenant context (runtime DI for the data layer)
+export { setActiveTenantId, getActiveTenantId } from './tenant'
+
+// Runtime broker helpers
+export { createFayzRuntimeClient, FayzRuntimeError } from './runtime'
+export type {
+  FayzRuntimeClientOptions,
+  FayzRuntimeEnvironment,
+  GoogleCalendarEvent,
+  GoogleCalendarEventInput,
+  GoogleCalendarEventTime,
+  ListGoogleCalendarEventsInput,
+  PluginOAuthExchangeInput,
+  PluginOAuthExchangeResponse,
+  RuntimePluginOAuthGrant,
+} from './runtime'
+
+// Shared utilities
+export { formatCurrency, formatDate, formatDateTime, getActiveLocale, getDefaultCurrency, setDefaultCurrency } from './lib/format'
+export { exportCSV, buildCSV, downloadCSV } from './lib/csv'
+export type { CSVColumn } from './lib/csv'
+export { globalCache, createCacheStore, stableKey, clearGlobalCache } from './lib/cache'
+export type { CacheStore } from './lib/cache'
+
+// Plugin system
+export { definePlugin, resolvePluginRuntime, getWidgetsForZone, getDashboardWidgets, PluginRuntimeProvider, usePluginRuntime, usePluginRuntimeOptional, PLUGIN_API_VERSION, resolvePluginComponent } from './plugin/runtime'
+export type { PluginEventDefinition, PluginQuickAction } from './types/plugins'
+
+// Event bus
+export { createEventBus, eventBus, useOnEvent } from './events'
+export type { EventBus, EventHandler } from './events'
+
+// Entity registry
+export { registerEntity, getEntityByKey, getAllEntities, clearEntityRegistry, deriveEntityKey } from './entity/registry'
+export type { RegisteredEntity } from './entity/registry'
+
+// Uniform registry (component / block / page / metric / scaffold / plugin)
+export {
+  Registry,
+  isCustomId,
+  componentRegistry,
+  blockRegistry,
+  pageRegistry,
+  scaffoldRegistry,
+  metricRegistry,
+  pluginRegistry,
+  registerComponent,
+  getComponent,
+  registerBlock,
+  getBlock,
+  listBlocks,
+  registerPage,
+  getPage,
+  registerScaffold,
+  getScaffold,
+  registerMetric,
+  getMetric,
+  listMetrics,
+  registerPlugin,
+  getPlugin,
+  listPlugins,
+  pluginFactoryRegistry,
+  registerPluginFactory,
+  getPluginFactory,
+  listPluginFactories,
+} from './registry'
+export type { PluginFactory } from './registry'
+export type {
+  JsonSchema,
+  RegistrySource,
+  RegistryMeta,
+  RegistryEntry,
+  MetricFormat,
+  MetricContext,
+  MetricValue,
+  MetricDefinition,
+} from './registry'
+
+// Block system (universal page primitive)
+export { BlockRenderer, renderBlocks, BlockChildren } from './blocks'
+export type { BlockNode, BlockComponentProps } from './blocks'
+
+// App manifest (the app, as data) + migration runner
+export {
+  CURRENT_MANIFEST_VERSION,
+  registerManifestMigration,
+  migrateManifest,
+  validateManifest,
+} from './manifest'
+export type {
+  AppManifest,
+  BackendProvider,
+  BackendRef,
+  SurfaceManifest,
+  PageManifest,
+  PluginRef,
+  ManifestMigration,
+} from './manifest'
+export { default as appManifestSchema } from './manifest/app-manifest.schema.json'
+
+// App entry points (manifest → running app)
+export { defineApp, renderApp, useManifest } from './app/render'
+export type { RenderAppOptions } from './app/render'
+
+// i18n
+export { I18nProvider, useI18nConfig, useTranslation, coreTranslations, mergeTranslations, registerTranslations, getCurrentLocale, setCurrentLocale, setLocaleStore } from './i18n/index'
+
+// Router
+export { hashRouterAdapter, windowRouterAdapter } from './router/index'
+export type { RouterAdapter } from './router/index'

package/src/lib/cache.ts

@@ -0,0 +1,118 @@
+// ---------------------------------------------------------------------------
+// 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 the global cache — called by the tenant accessor when the active
+ *  tenant changes (replaces the old org-store subscription). */
+export function clearGlobalCache(): void {
+  globalCache.clear()
+}

package/src/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/lib/format.ts

@@ -0,0 +1,58 @@
+import { getCurrentLocale } from '../i18n'
+
+// Currency inferred from the active locale unless the app sets one explicitly
+// via createSaasApp({ locale: { currency: 'BRL' } }).
+const CURRENCY_BY_LOCALE: Record<string, string> = {
+  'pt-BR': 'BRL',
+  'pt-PT': 'EUR',
+  en: 'USD',
+  'en-US': 'USD',
+  'en-GB': 'GBP',
+  es: 'EUR',
+}
+
+let _defaultCurrency: string | null = null
+
+export function setDefaultCurrency(code: string | undefined): void {
+  _defaultCurrency = code ?? null
+}
+
+export function getActiveLocale(): string {
+  try {
+    return getCurrentLocale() || 'en'
+  } catch {
+    return 'en'
+  }
+}
+
+export function getDefaultCurrency(): string {
+  if (_defaultCurrency) return _defaultCurrency
+  return CURRENCY_BY_LOCALE[getActiveLocale()] ?? 'USD'
+}
+
+export function formatCurrency(value: unknown, currency?: string): string {
+  const num = typeof value === 'number' ? value : parseFloat(String(value))
+  if (isNaN(num)) return String(value ?? '')
+  return new Intl.NumberFormat(getActiveLocale(), {
+    style: 'currency',
+    currency: currency ?? getDefaultCurrency(),
+  }).format(num)
+}
+
+export function formatDate(value: unknown): string {
+  if (!value) return ''
+  try {
+    return new Intl.DateTimeFormat(getActiveLocale(), { dateStyle: 'medium' }).format(new Date(value as string))
+  } catch {
+    return String(value)
+  }
+}
+
+export function formatDateTime(value: unknown): string {
+  if (!value) return ''
+  try {
+    return new Intl.DateTimeFormat(getActiveLocale(), { dateStyle: 'medium', timeStyle: 'short' }).format(new Date(value as string))
+  } catch {
+    return String(value)
+  }
+}

package/src/manifest/app-manifest.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://fayz.ai/schemas/app-manifest/v2.json",
+  "title": "Fayz AppManifest",
+  "description": "The canonical, JSON-serializable definition of a Fayz app. Code is referenced by registry id; never inlined.",
+  "type": "object",
+  "required": ["manifestVersion", "id", "name", "surfaces"],
+  "additionalProperties": false,
+  "properties": {
+    "manifestVersion": {
+      "type": "integer",
+      "const": 2,
+      "description": "Current AppManifest schema version. Older or newer versions require an explicit SDK migration before validation."
+    },
+    "id": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "name": { "type": "string", "minLength": 1 },
+    "backend": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider"],
+      "properties": {
+        "provider": { "enum": ["supabase", "fayz-api", "fayz-shop", "mock", "custom"] },
+        "projectRef": { "type": "string", "minLength": 1 },
+        "url": { "type": "string", "minLength": 1 },
+        "adapterId": { "type": "string", "minLength": 1 },
+        "options": { "type": "object" }
+      }
+    },
+    "locale": { "type": "object" },
+    "theme": { "type": "object" },
+    "permissions": { "type": "object" },
+    "billing": { "type": "object" },
+    "entities": { "type": "array", "items": { "type": "object" } },
+    "surfaces": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/surface" }
+    }
+  },
+  "$defs": {
+    "surface": {
+      "type": "object",
+      "required": ["scaffold"],
+      "additionalProperties": false,
+      "properties": {
+        "scaffold": { "type": "string", "minLength": 1 },
+        "options": { "type": "object" },
+        "plugins": { "type": "array", "items": { "$ref": "#/$defs/pluginRef" } },
+        "pages": { "type": "array", "items": { "$ref": "#/$defs/page" } }
+      }
+    },
+    "pluginRef": {
+      "type": "object",
+      "required": ["id"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "config": { "type": "object" },
+        "enabled": { "type": "boolean" }
+      }
+    },
+    "page": {
+      "type": "object",
+      "required": ["path"],
+      "additionalProperties": false,
+      "description": "Exactly one of blocks/entity/component must be set.",
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "label": { "type": "string" },
+        "icon": { "type": "string" },
+        "section": { "enum": ["main", "secondary", "settings"] },
+        "blocks": { "type": "array", "items": { "$ref": "#/$defs/block" } },
+        "entity": { "type": "string", "minLength": 1 },
+        "component": { "type": "string", "minLength": 1 },
+        "permission": {
+          "type": "object",
+          "required": ["feature", "action"],
+          "additionalProperties": false,
+          "properties": {
+            "feature": { "type": "string", "minLength": 1 },
+            "action": { "type": "string", "minLength": 1 }
+          }
+        }
+      },
+      "oneOf": [
+        { "required": ["blocks"] },
+        { "required": ["entity"] },
+        { "required": ["component"] }
+      ]
+    },
+    "block": {
+      "type": "object",
+      "required": ["type"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "id": { "type": "string" },
+        "props": { "type": "object" },
+        "children": { "type": "array", "items": { "$ref": "#/$defs/block" } }
+      }
+    }
+  }
+}