@fayz-ai/core 0.8.0 → 0.8.2

package/package.json

@@ -3,7 +3,7 @@
   "fayz": {
     "status": "beta"
   },
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Fayz SDK core — data providers, entity system, plugin runtime, i18n, routing",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -52,6 +52,12 @@
       "import": "./dist/runtime/index.js",
       "require": "./dist/runtime/index.cjs"
     },
+    "./access": {
+      "source": "./src/access/index.ts",
+      "types": "./dist/access/index.d.ts",
+      "import": "./dist/access/index.js",
+      "require": "./dist/access/index.cjs"
+    },
     "./types": {
       "source": "./src/types/index.ts",
       "types": "./dist/types/index.d.ts",
@@ -82,7 +88,7 @@
   "dependencies": {
     "@supabase/supabase-js": "^2.45.0",
     "zustand": "^4.5.0",
-    "@fayz-ai/sdk": "^0.8.0"
+    "@fayz-ai/sdk": "^0.8.2"
   },
   "devDependencies": {
     "@types/react": "^18.3.0",
@@ -90,7 +96,9 @@
     "react": "^18.3.0",
     "react-dom": "^18.3.0",
     "tsup": "^8.2.0",
-    "typescript": "^5.5.0"
+    "typescript": "^5.5.0",
+    "vite": "^5.4.0",
+    "vitest": "2.1.9"
   },
   "license": "MIT",
   "keywords": [
@@ -104,10 +112,12 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup && tsc --emitDeclarationOnly --declaration --declarationMap --noEmit false",
+    "build": "node ./scripts/check-access-purity.mjs && tsup && tsc --emitDeclarationOnly --declaration --declarationMap --noEmit false",
     "check:manifest": "node ./scripts/check-manifest-contract.mjs",
+    "check:access": "node ./scripts/check-access-purity.mjs",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
     "clean": "rm -rf dist"
   }
 }

package/src/access/denial.ts

@@ -0,0 +1,33 @@
+import type { DenyReason } from './engine'
+
+// ---------------------------------------------------------------------------
+// The structured denial an AGENT surface returns instead of failing silently
+// (docs/ENTITLEMENTS.md § "Superfície de agentes de IA"). One shape for every
+// executor — FAB client-plane, the Fayz broker, and the pool RPCs (which emit
+// its jsonb mirror in their `denial` field) — so the model can explain the
+// denial and offer the upgrade path conversationally.
+// ---------------------------------------------------------------------------
+
+/** Where a denied tenant goes to upgrade — the conversational UpgradeModal. */
+export const UPGRADE_URL = '/settings/subscription'
+
+export interface AgentDenialLimit {
+  key: string
+  max: number
+  used: number
+}
+
+export interface AgentDenial {
+  allowed: false
+  reason: DenyReason
+  /** Present when `reason === 'limit'`. */
+  limit?: AgentDenialLimit
+  upgradeUrl: string
+}
+
+export type AgentGuardResult = { allowed: true } | AgentDenial
+
+/** Build a denial with the canonical upgrade URL attached. */
+export function agentDenial(reason: DenyReason, limit?: AgentDenialLimit): AgentDenial {
+  return { allowed: false, reason, ...(limit ? { limit } : {}), upgradeUrl: UPGRADE_URL }
+}

package/src/access/engine.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest'
+import type { PermissionProfile } from '../types/permissions'
+import { profileHasPermission, isOwnerProfile, resolveAccess } from './engine'
+import { agentDenial, UPGRADE_URL } from './denial'
+
+// The composition matrix (role × plan × limit math) is covered by
+// packages/saas/src/access/resolver.test.ts, which now runs against this
+// engine through the saas re-export — parity by construction. Here we cover
+// the pieces that are new or only reachable from core.
+
+const staff: PermissionProfile = { id: 'staff', name: 'Staff', grants: { clients: ['read'] } }
+
+describe('profileHasPermission', () => {
+  it('null profile is allow-all (catalog not hydrated yet)', () => {
+    expect(profileHasPermission(null, 'anything', 'delete')).toBe(true)
+  })
+
+  it('owner matches by id or (localized) name', () => {
+    expect(isOwnerProfile({ id: 'owner', name: 'Proprietário', grants: {} })).toBe(true)
+    expect(isOwnerProfile({ id: 'x', name: 'Owner', grants: {} })).toBe(true)
+    expect(isOwnerProfile(staff)).toBe(false)
+  })
+
+  it('manage satisfies any action; empty grant list denies actionless check', () => {
+    const manager: PermissionProfile = { id: 'm', name: 'M', grants: { clients: ['manage'], reports: [] } }
+    expect(profileHasPermission(manager, 'clients', 'delete')).toBe(true)
+    expect(profileHasPermission(manager, 'reports')).toBe(false)
+  })
+})
+
+describe('agentDenial', () => {
+  it('carries the canonical upgrade URL', () => {
+    expect(agentDenial('plan')).toEqual({ allowed: false, reason: 'plan', upgradeUrl: UPGRADE_URL })
+  })
+
+  it('carries limit details for limit denials', () => {
+    const d = agentDenial('limit', { key: 'clients', max: 100, used: 100 })
+    expect(d.limit).toEqual({ key: 'clients', max: 100, used: 100 })
+    expect(d.reason).toBe('limit')
+  })
+
+  it('shape matches what resolveAccess produces for the same reason', () => {
+    const decision = resolveAccess({ profile: staff, plan: null }, 'marketing')
+    expect(decision.allowed).toBe(false)
+    const d = agentDenial(decision.reason!)
+    expect(d.reason).toBe('role')
+  })
+})

package/src/access/engine.ts

@@ -0,0 +1,121 @@
+import type { PermissionProfile, PermissionAction } from '../types/permissions'
+import type { Plan } from '../types/billing'
+
+// ---------------------------------------------------------------------------
+// The access engine — the ONE implementation of the role × plan × limit
+// decision, shared by every runtime that gates anything:
+//
+//   - browser (saas AccessProvider / PermissionsProvider re-export from here)
+//   - headless client-plane (saas access/headless.ts)
+//   - the Fayz broker (server-side agent authorization imports this package)
+//
+// Hard constraint: this module (and everything under core/src/access) must stay
+// free of React, zustand and supabase — pure functions over plain data — so the
+// exact same code runs in Node/edge. Guarded by scripts/check-access-purity.mjs.
+// ---------------------------------------------------------------------------
+
+/** Why an access request was denied. `limit` only occurs on guarded writes. */
+export type DenyReason = 'role' | 'plan' | 'limit'
+
+export interface AccessDecision {
+  allowed: boolean
+  reason?: DenyReason
+}
+
+/** The minimal subject a decision needs — a projection of any richer session. */
+export interface AccessSubject {
+  /** Effective RBAC profile — the previewed role during impersonation. */
+  profile: PermissionProfile | null
+  /** The tenant's currently-active plan. */
+  plan: Plan | null
+}
+
+/**
+ * The org owner has every permission implicitly. Owner is represented by the
+ * canonical role id `owner` across adapters (see org/adapters/supabase.ts
+ * buildPermissionProfiles, which also grants owner all catalog perms, and the
+ * mock adapter's `owner` fallback). We match by id first, falling back to the
+ * (possibly localized) name for safety.
+ */
+export function isOwnerProfile(profile: PermissionProfile): boolean {
+  return profile.id === 'owner' || profile.name?.toLowerCase() === 'owner'
+}
+
+/**
+ * The single role-side permission check. The plan axis composes ON TOP of it in
+ * {@link resolveAccess} instead of reimplementing owner-bypass / `manage`
+ * semantics.
+ */
+export function profileHasPermission(
+  profile: PermissionProfile | null,
+  feature: string,
+  action?: string,
+): boolean {
+  if (!profile) return true
+
+  // Owner bypass: never lock the owner out, even if the RBAC catalog is empty
+  // or still loading. Because permission checks read the *effective* profile,
+  // an owner previewing a non-owner role correctly loses this bypass — the
+  // preview stays honest.
+  if (isOwnerProfile(profile)) return true
+
+  const actions = profile.grants[feature]
+  if (!actions) return false
+
+  if (!action) return actions.length > 0
+
+  return actions.includes(action) || actions.includes('manage')
+}
+
+/**
+ * Does the current plan entitle `feature`? A plan gates a feature ONLY with an
+ * explicit `false`; absent means "not gated by this plan" (allowed). This keeps
+ * entitlements additive and safe: a feature the plan has never heard of stays
+ * open rather than silently locking.
+ */
+export function isEntitledByPlan(plan: Plan | null, feature: string): boolean {
+  return plan?.entitlements?.features?.[feature] !== false
+}
+
+/**
+ * The single access decision: role FIRST, then plan.
+ *
+ * 1. Role — reuses `profileHasPermission` (owner bypass + `manage` semantics
+ *    live there, and impersonation composes for free because `profile` is the
+ *    previewed role). Denied → `{ allowed:false, reason:'role' }`.
+ * 2. Plan — even the owner does NOT bypass the plan: upgrading is the tenant's
+ *    decision, not a role power. Denied → `{ allowed:false, reason:'plan' }`.
+ */
+export function resolveAccess(
+  subject: AccessSubject,
+  feature: string,
+  action?: PermissionAction,
+): AccessDecision {
+  if (!profileHasPermission(subject.profile, feature, action)) {
+    return { allowed: false, reason: 'role' }
+  }
+  if (!isEntitledByPlan(subject.plan, feature)) {
+    return { allowed: false, reason: 'plan' }
+  }
+  return { allowed: true }
+}
+
+/**
+ * Pure numeric side of a limit: given the plan cap, whether a countable
+ * declaration exists, and the current usage, derive the limit math. Unlimited
+ * when there's no declaration to count, no cap on the plan, or the cap is `-1`.
+ */
+export function resolveLimit(params: { cap: number | undefined; hasDeclaration: boolean; used: number }): {
+  max: number
+  used: number
+  remaining: number
+  atLimit: boolean
+  unlimited: boolean
+} {
+  const { cap, hasDeclaration, used } = params
+  const unlimited = !hasDeclaration || cap === undefined || cap === -1
+  const max = unlimited ? Infinity : cap
+  const remaining = unlimited ? Infinity : Math.max(0, max - used)
+  const atLimit = !unlimited && used >= max
+  return { max, used, remaining, atLimit, unlimited }
+}

package/src/access/index.ts

@@ -0,0 +1,13 @@
+export {
+  isOwnerProfile,
+  profileHasPermission,
+  isEntitledByPlan,
+  resolveAccess,
+  resolveLimit,
+} from './engine'
+export type { DenyReason, AccessDecision, AccessSubject } from './engine'
+
+export { UPGRADE_URL, agentDenial } from './denial'
+export type { AgentDenial, AgentDenialLimit, AgentGuardResult } from './denial'
+
+export { mergeLimitDeclarations } from './limits'

package/src/access/limits.ts

@@ -0,0 +1,18 @@
+import type { LimitDeclaration } from '../types/entitlements'
+
+/**
+ * The 4-layer limit-declaration merge, extracted so the browser AccessProvider
+ * and the manifest derivation (`fayz manifest emit`) resolve the EXACT same
+ * final set: core built-ins < entity-derived < plugin `declaredLimits` < app
+ * overrides. Later layers win by key. Pure: pass the layers in, get the merge
+ * out — deriving a declaration FROM an entity stays at the call site.
+ */
+export function mergeLimitDeclarations(
+  ...layers: Array<LimitDeclaration[] | undefined>
+): LimitDeclaration[] {
+  const byKey = new Map<string, LimitDeclaration>()
+  for (const layer of layers) {
+    for (const decl of layer ?? []) byKey.set(decl.key, decl)
+  }
+  return Array.from(byKey.values())
+}

package/src/address/index.ts

@@ -0,0 +1,188 @@
+// ---------------------------------------------------------------------------
+// Postal code → address lookup (SDK-level — shared by any surface that collects
+// an address: storefront checkout, the SaaS address book, CRM, booking).
+//
+// Sits beside ./phone for the same reason: knowing that a Brazilian CEP is
+// eight digits, and that '01310100' means Avenida Paulista, is not a
+// storefront concern. It belongs wherever an address is typed.
+//
+// The lookup itself is behind an interface. ViaCEP is the default because it is
+// free, keyless and CORS-enabled, but it is a third party the merchant does not
+// control — so swapping it for an edge-function proxy (shared cache, no
+// third-party call from the shopper's browser) must be one line, not a rewrite.
+// ---------------------------------------------------------------------------
+
+/**
+ * An address as a postal service knows it: everything except the parts only the
+ * resident can supply (number, complement).
+ *
+ * Field names mirror ShippingAddressInput in @fayz-ai/shop so the value crosses
+ * from lookup to checkout to the order with no translation step in between.
+ */
+export interface PostalAddress {
+  postalCode: string
+  street: string
+  district: string
+  city: string
+  state: string
+  country: string
+  /** IBGE municipality code when the source provides one — useful for tax later. */
+  cityCode?: string
+}
+
+/** Where a postal code is resolved. Implementations must not throw for a
+ *  well-formed code that simply does not exist — that is `null`, not an error. */
+export interface PostalLookupProvider {
+  lookup(postalCode: string): Promise<PostalAddress | null>
+}
+
+/** Keep only digits. */
+export function normalizePostalCode(value: string): string {
+  return (value || '').replace(/\D/g, '')
+}
+
+/** '01310100' | '01310-100' -> '01310-100'. Partial input formats progressively. */
+export function formatPostalCode(value: string): string {
+  const digits = normalizePostalCode(value).slice(0, 8)
+  return digits.length > 5 ? `${digits.slice(0, 5)}-${digits.slice(5)}` : digits
+}
+
+/** A Brazilian CEP is exactly eight digits. */
+export function isValidPostalCode(value: string): boolean {
+  return normalizePostalCode(value).length === 8
+}
+
+// ---------------------------------------------------------------------------
+// Cache
+//
+// A CEP maps to the same street for years, so the second lookup of one should
+// never leave the browser. This also keeps a busy storefront well clear of
+// ViaCEP's per-IP rate limit. localStorage when there is a window, an in-memory
+// Map otherwise (SSR, tests, node) — never a hard failure over a cache miss.
+// ---------------------------------------------------------------------------
+
+const CACHE_KEY = 'fayz.postal.cache.v1'
+const memoryCache = new Map<string, PostalAddress>()
+
+function readCache(code: string): PostalAddress | undefined {
+  const hit = memoryCache.get(code)
+  if (hit) return hit
+  try {
+    const raw = globalThis.localStorage?.getItem(CACHE_KEY)
+    if (!raw) return undefined
+    const all = JSON.parse(raw) as Record<string, PostalAddress>
+    const stored = all[code]
+    if (stored) memoryCache.set(code, stored)
+    return stored
+  } catch {
+    return undefined
+  }
+}
+
+function writeCache(code: string, address: PostalAddress): void {
+  memoryCache.set(code, address)
+  try {
+    const store = globalThis.localStorage
+    if (!store) return
+    const raw = store.getItem(CACHE_KEY)
+    const all = raw ? (JSON.parse(raw) as Record<string, PostalAddress>) : {}
+    all[code] = address
+    store.setItem(CACHE_KEY, JSON.stringify(all))
+  } catch {
+    /* quota or private mode — the in-memory copy still stands for this session */
+  }
+}
+
+/** Drop the cache. Exposed for tests and for a "wrong address?" escape hatch. */
+export function clearPostalCache(): void {
+  memoryCache.clear()
+  try {
+    globalThis.localStorage?.removeItem(CACHE_KEY)
+  } catch {
+    /* ignore */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ViaCEP
+// ---------------------------------------------------------------------------
+
+interface ViaCepResponse {
+  cep?: string
+  logradouro?: string
+  bairro?: string
+  localidade?: string
+  uf?: string
+  ibge?: string
+  erro?: boolean | string
+}
+
+/**
+ * ViaCEP (https://viacep.com.br). Free, no key, CORS-enabled.
+ *
+ * The trap: an unknown CEP does NOT come back as 404. ViaCEP answers HTTP 200
+ * with `{"erro": true}` (and, on some deploys, the string "true"), so checking
+ * response.ok alone yields an address of empty strings that silently overwrites
+ * whatever the shopper had typed. Both shapes are treated as "not found".
+ */
+export function createViaCepProvider(options?: { fetcher?: typeof fetch }): PostalLookupProvider {
+  const fetcher = options?.fetcher ?? globalThis.fetch
+  return {
+    async lookup(postalCode: string): Promise<PostalAddress | null> {
+      const code = normalizePostalCode(postalCode)
+      if (code.length !== 8) return null
+
+      const response = await fetcher(`https://viacep.com.br/ws/${code}/json/`)
+      if (!response.ok) throw new Error(`Consulta de CEP falhou (${response.status})`)
+
+      const data = (await response.json()) as ViaCepResponse
+      if (data.erro === true || data.erro === 'true' || !data.localidade) return null
+
+      return {
+        postalCode: code,
+        street: data.logradouro ?? '',
+        district: data.bairro ?? '',
+        city: data.localidade,
+        state: (data.uf ?? '').toUpperCase(),
+        country: 'BR',
+        cityCode: data.ibge || undefined,
+      }
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Module-level resolver — same shape as setShopTenantResolver /
+// setShopAccessTokenResolver, so an app overrides the source once at boot
+// instead of threading a provider through every component that needs a CEP.
+// ---------------------------------------------------------------------------
+
+let _provider: PostalLookupProvider | null = null
+
+export function setPostalLookupProvider(provider: PostalLookupProvider | null): void {
+  _provider = provider
+}
+
+export function getPostalLookupProvider(): PostalLookupProvider {
+  if (!_provider) _provider = createViaCepProvider()
+  return _provider
+}
+
+/**
+ * Resolve a postal code to an address, through the cache.
+ *
+ * Returns null for a code that is malformed or does not exist; throws only when
+ * the lookup itself failed (offline, provider down), so a caller can tell
+ * "no such CEP" from "we could not check right now" and say the right thing.
+ */
+export async function lookupPostalCode(postalCode: string): Promise<PostalAddress | null> {
+  const code = normalizePostalCode(postalCode)
+  if (code.length !== 8) return null
+
+  const cached = readCache(code)
+  if (cached) return cached
+
+  const address = await getPostalLookupProvider().lookup(code)
+  if (address) writeCache(code, address)
+  return address
+}

package/src/data/count.test.ts

@@ -0,0 +1,152 @@
+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()
+  })
+})