@fayz-ai/core 0.9.0 → 0.11.0

package/dist/testing/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAUD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAsD3E;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAiBlE"}

package/src/access/denial.ts

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

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

@@ -1,136 +0,0 @@
-import type { PermissionProfile, PermissionAction, SystemPermission } 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')
-}
-
-/**
- * The org-management side of a profile: managing team, billing, settings and
- * permissions themselves. Separate axis from `grants` — these gate the settings
- * tabs, not a feature's rows — and it follows the same owner bypass, so the one
- * person who can hand out access is never locked out of doing it.
- */
-export function profileHasSystemPermission(
-  profile: PermissionProfile | null,
-  permission: SystemPermission,
-): boolean {
-  if (!profile) return true
-  if (isOwnerProfile(profile)) return true
-  return profile.systemPermissions?.includes(permission) ?? false
-}
-
-/**
- * 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

@@ -1,14 +0,0 @@
-export {
-  isOwnerProfile,
-  profileHasPermission,
-  profileHasSystemPermission,
-  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

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

@@ -1,188 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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/app/render.tsx

@@ -1,69 +0,0 @@
-import * as React from 'react'
-import { getScaffold } from '../registry'
-import { migrateManifest, validateManifest, CURRENT_MANIFEST_VERSION } from '../manifest'
-import type { AppManifest } from '../manifest'
-
-// ---------------------------------------------------------------------------
-// defineApp / renderApp — the entry points that turn an AppManifest into a
-// running app. Scaffolds (admin, storefront, portal) self-register into the
-// scaffold registry when their package is imported, so core never depends on
-// them: a generated app imports the scaffold package(s) it needs, then calls
-// renderApp(manifest). createSaasApp / createStorefrontApp become sugar that
-// builds a manifest and hands it here.
-// ---------------------------------------------------------------------------
-
-const ManifestContext = React.createContext<AppManifest | null>(null)
-
-/** Access the active app manifest from any component under renderApp. */
-export function useManifest(): AppManifest | null {
-  return React.useContext(ManifestContext)
-}
-
-/** Stamp + validate a manifest authored in code (the sugar path). */
-export function defineApp(
-  manifest: Omit<AppManifest, 'manifestVersion'> & { manifestVersion?: number },
-): AppManifest {
-  const full = {
-    ...manifest,
-    manifestVersion: manifest.manifestVersion ?? CURRENT_MANIFEST_VERSION,
-  } as AppManifest
-  const problems = validateManifest(full)
-  if (problems.length) {
-    throw new Error(`Invalid AppManifest:\n - ${problems.join('\n - ')}`)
-  }
-  return full
-}
-
-export interface RenderAppOptions {
-  /** Which surface to mount; defaults to the first declared surface. */
-  surface?: string
-}
-
-/** Resolve, migrate and validate a manifest, then mount the scaffold for the
- *  chosen surface. Accepts a raw object (e.g. parsed app.manifest.json). */
-export function renderApp(
-  input: AppManifest | Record<string, unknown>,
-  opts: RenderAppOptions = {},
-): React.ReactElement {
-  const manifest = migrateManifest(input as Record<string, unknown>)
-  const problems = validateManifest(manifest)
-  if (problems.length) {
-    throw new Error(`Invalid AppManifest:\n - ${problems.join('\n - ')}`)
-  }
-  const surfaceName = opts.surface ?? Object.keys(manifest.surfaces)[0]
-  const surface = surfaceName ? manifest.surfaces[surfaceName] : undefined
-  if (!surface) {
-    throw new Error(`Surface "${surfaceName}" not found in manifest.`)
-  }
-  const Scaffold = getScaffold(surface.scaffold)
-  if (!Scaffold) {
-    throw new Error(
-      `Scaffold "${surface.scaffold}" is not registered. Call renderApp from the package that provides it (e.g. @fayz-ai/saas, @fayz-ai/portal, @fayz-ai/storefront) or call its register*Scaffold() first.`,
-    )
-  }
-  return React.createElement(
-    ManifestContext.Provider,
-    { value: manifest },
-    React.createElement(Scaffold, { manifest, surface: surfaceName }),
-  )
-}

package/src/blocks/index.tsx

@@ -1,68 +0,0 @@
-import * as React from 'react'
-import { getBlock } from '../registry'
-
-// ---------------------------------------------------------------------------
-// Block tree — the universal page primitive. A page (admin or storefront) is an
-// ordered tree of typed blocks. Block `type`s are resolved against the block
-// registry, so a page is pure data: `{ type, props, children }`. This
-// generalizes the storefront's HomeSection switch to every surface.
-// ---------------------------------------------------------------------------
-
-export interface BlockNode {
-  /** Registered block id, e.g. 'hero', 'products', 'kpi-grid', 'custom:foo'. */
-  type: string
-  /** Stable id for keys / editing; optional. */
-  id?: string
-  props?: Record<string, unknown>
-  children?: BlockNode[]
-}
-
-/** A block component receives its declared props plus the raw node (so a block
- *  can render its own children via <BlockChildren>). */
-export type BlockComponentProps = Record<string, unknown> & {
-  node?: BlockNode
-  children?: React.ReactNode
-}
-
-// Rendered in place of an unresolved block type. Unknown blocks are caught
-// ahead of production by `fayz doctor` / the conformance kit, so this visible
-// marker is a development aid rather than a production concern.
-function UnknownBlock({ type }: { type: string }): React.ReactElement | null {
-  return React.createElement(
-    'div',
-    {
-      style: {
-        border: '1px dashed #c026d3',
-        color: '#a21caf',
-        padding: '8px 12px',
-        font: '12px ui-monospace, monospace',
-        borderRadius: 6,
-      },
-    },
-    `Unknown block: "${type}"`,
-  )
-}
-
-export function BlockRenderer({ node }: { node: BlockNode }): React.ReactElement | null {
-  const Comp = getBlock(node.type)
-  const childEls = node.children?.length
-    ? node.children.map((child, i) =>
-        React.createElement(BlockRenderer, { key: child.id ?? `${child.type}-${i}`, node: child }),
-      )
-    : null
-  if (!Comp) return React.createElement(UnknownBlock, { type: node.type })
-  return React.createElement(Comp, { ...(node.props ?? {}), node }, childEls)
-}
-
-/** Render an ordered list of blocks (a page body). */
-export function renderBlocks(nodes: BlockNode[]): React.ReactNode {
-  return nodes.map((node, i) =>
-    React.createElement(BlockRenderer, { key: node.id ?? `${node.type}-${i}`, node }),
-  )
-}
-
-/** Convenience for block components that render their own children. */
-export function BlockChildren({ node }: { node?: BlockNode }): React.ReactNode {
-  if (!node?.children?.length) return null
-  return renderBlocks(node.children)
-}