@fayz-ai/saas 0.8.0 → 0.8.2

package/src/access/context.tsx

@@ -0,0 +1,228 @@
+import * as React from 'react'
+import type { LimitDeclaration, PermissionAction, Plan } from '@fayz-ai/core'
+import { countByTenant, usePluginRuntimeOptional, getAllEntities } from '@fayz-ai/core'
+import { useAuthStore } from '@fayz-ai/auth'
+import { useOrganizationStore } from '../org/store'
+import { usePermissionsStore } from '../permissions/store'
+import { useBillingStore } from '../billing/store'
+import { mergeLimitDeclarations } from '@fayz-ai/core/access'
+import { resolveAccess, isEntitledByPlan, resolveLimit } from './resolver'
+import { entityDerivedLimitDeclarations } from './limits-registry'
+import { setLimitRegistry, getLimitDeclaration, subscribeLimit, CORE_LIMIT_DECLARATIONS } from './limits-registry'
+import { useUpgradeModalStore } from './upgrade-modal-store'
+import type { AccessApi, AccessDecision, AccessSession, LimitState } from './types'
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+interface AccessContextValue extends AccessApi {
+  session: AccessSession
+}
+
+const AccessContext = React.createContext<AccessContextValue | null>(null)
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export interface AccessProviderProps {
+  children: React.ReactNode
+  /**
+   * App-level limit declarations layered ON TOP of the plugins' `declaredLimits`
+   * (app wins on key collision). Sourced from `config.billing.limitDeclarations`.
+   */
+  limitDeclarations?: LimitDeclaration[]
+}
+
+/**
+ * Assembles the reactive {@link AccessSession} from the singleton stores and
+ * exposes the composed access API (role × plan). Thin by design — mounts just
+ * inside PermissionsProvider so it can reuse the live permission profile and the
+ * plugin runtime. Also publishes the merged limit declarations to the module
+ * registry so `invalidateLimit` works from non-React create handlers.
+ */
+export function AccessProvider({ children, limitDeclarations }: AccessProviderProps) {
+  const user = useAuthStore((s) => s.user)
+  const org = useOrganizationStore((s) => s.currentOrg)
+  const profile = usePermissionsStore((s) => s.currentProfile)
+  const plans = useBillingStore((s) => s.plans)
+
+  const runtime = usePluginRuntimeOptional()
+  const pluginLimits = runtime?.pluginLimits
+
+  // Merge limit declarations by priority (later wins by key): shell built-ins
+  // (users/locations) < entity-derived < plugin `declaredLimits` < app
+  // overrides. Then publish to the module registry consumed by
+  // invalidateLimit / the limit hooks.
+  //
+  // Entity-derived: any registered CRUD entity carrying `limitKey` yields a
+  // declaration for free from its own data mapping (table + archetype kind) —
+  // this is what makes an app's `EntityDef.limitKey: 'clients'` enforceable
+  // with ZERO extra wiring (a cap without a countable binding is a dead cap).
+  React.useEffect(() => {
+    setLimitRegistry(
+      mergeLimitDeclarations(
+        CORE_LIMIT_DECLARATIONS,
+        entityDerivedLimitDeclarations(getAllEntities()),
+        pluginLimits,
+        limitDeclarations,
+      ),
+    )
+  }, [pluginLimits, limitDeclarations])
+
+  const plan: Plan | null = React.useMemo(
+    () => (org?.plan ? plans.find((p) => p.id === org.plan) ?? null : null),
+    [plans, org?.plan],
+  )
+
+  const session: AccessSession = React.useMemo(
+    () => ({ user, org, profile, plan }),
+    [user, org, profile, plan],
+  )
+
+  const value = React.useMemo<AccessContextValue>(
+    () => ({
+      session,
+      can: (feature, action) => resolveAccess(session, feature, action),
+      entitled: (feature) => isEntitledByPlan(session.plan, feature),
+    }),
+    [session],
+  )
+
+  return <AccessContext.Provider value={value}>{children}</AccessContext.Provider>
+}
+AccessProvider.displayName = 'AccessProvider'
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+const ALLOW_ALL: AccessApi = {
+  can: () => ({ allowed: true }),
+  entitled: () => true,
+}
+
+/**
+ * The composed access API. Throws outside <AccessProvider> — use
+ * {@link useAccessOptional} for SDK components that must degrade gracefully.
+ */
+export function useAccess(): AccessApi {
+  const ctx = React.useContext(AccessContext)
+  if (!ctx) throw new Error('useAccess must be used inside <AccessProvider>')
+  return { can: ctx.can, entitled: ctx.entitled }
+}
+
+/**
+ * Like {@link useAccess} but degrades to allow-all when no provider is mounted,
+ * so components stay usable under a bare host shell (gating is an enhancement).
+ */
+export function useAccessOptional(): AccessApi {
+  const ctx = React.useContext(AccessContext)
+  return ctx ? { can: ctx.can, entitled: ctx.entitled } : ALLOW_ALL
+}
+
+/** Internal: the live session (for hooks that need tenant/plan directly). */
+function useAccessSession(): AccessSession | null {
+  return React.useContext(AccessContext)?.session ?? null
+}
+
+// ---------------------------------------------------------------------------
+// Limits
+// ---------------------------------------------------------------------------
+
+function resolveCap(plan: Plan | null, key: string): number | undefined {
+  return plan?.entitlements?.limits?.[key]
+}
+
+/**
+ * Live usage of a quantity limit for the active tenant. Resolves the limit's
+ * declaration (plugin manifest or app override) → a tenant-scoped `count(*)`,
+ * capped by the current plan. No declaration or no cap (or `-1`) ⇒ unlimited.
+ * Re-fetches when the tenant, plan cap, or an `invalidateLimit(key)` fires.
+ */
+export function useLimit(key: string): LimitState {
+  const session = useAccessSession()
+  const tenantId = session?.org?.id
+  const cap = resolveCap(session?.plan ?? null, key)
+  const declaration = getLimitDeclaration(key)
+
+  const unlimited = !declaration || cap === undefined || cap === -1
+
+  const [used, setUsed] = React.useState(0)
+  const [loading, setLoading] = React.useState(!unlimited)
+  const [version, setVersion] = React.useState(0)
+
+  const refresh = React.useCallback(() => setVersion((v) => v + 1), [])
+
+  // Wake on external invalidation (a create/delete elsewhere).
+  React.useEffect(() => subscribeLimit(key, refresh), [key, refresh])
+
+  React.useEffect(() => {
+    if (unlimited || !declaration || !tenantId) {
+      setUsed(0)
+      setLoading(false)
+      return
+    }
+    let active = true
+    setLoading(true)
+    countByTenant(declaration.table, {
+      kind: declaration.kindFilter,
+      period: declaration.period,
+      tenantId,
+      fresh: version > 0,
+    })
+      .then((n) => {
+        if (active) {
+          setUsed(n)
+          setLoading(false)
+        }
+      })
+      .catch(() => {
+        if (active) setLoading(false)
+      })
+    return () => {
+      active = false
+    }
+  }, [unlimited, declaration, tenantId, version])
+
+  const bounds = resolveLimit({ cap, hasDeclaration: Boolean(declaration), used })
+
+  return { key, ...bounds, loading, refresh }
+}
+
+/**
+ * Imperative guard for create handlers: `await guard(n)` returns `'ok'` when
+ * adding `n` more rows stays within the cap, or `'blocked'` (and opens the global
+ * UpgradeModal) when it would exceed it. Always checks a FRESH count so it never
+ * relies on stale hook state.
+ */
+export function useLimitGuard(key: string): (n?: number) => Promise<'ok' | 'blocked'> {
+  const session = useAccessSession()
+  const tenantId = session?.org?.id
+  const plan = session?.plan ?? null
+  const openModal = useUpgradeModalStore((s) => s.open)
+
+  return React.useCallback(
+    async (n = 1) => {
+      const cap = resolveCap(plan, key)
+      const declaration = getLimitDeclaration(key)
+      // Unlimited / no declaration / no tenant ⇒ never block.
+      if (!declaration || cap === undefined || cap === -1 || !tenantId) return 'ok'
+
+      const used = await countByTenant(declaration.table, {
+        kind: declaration.kindFilter,
+        period: declaration.period,
+        tenantId,
+        fresh: true,
+      })
+
+      if (used + n > cap) {
+        openModal({ limitKey: key })
+        return 'blocked'
+      }
+      return 'ok'
+    },
+    [key, plan, tenantId, openModal],
+  )
+}

package/src/access/headless.ts

@@ -0,0 +1,71 @@
+import type { PermissionAction, Plan } from '@fayz-ai/core'
+import { countByTenant } from '@fayz-ai/core'
+import { resolveAccess, agentDenial, type AgentGuardResult } from '@fayz-ai/core/access'
+import { useAuthStore } from '@fayz-ai/auth'
+import { useOrganizationStore } from '../org/store'
+import { usePermissionsStore } from '../permissions/store'
+import { useBillingStore } from '../billing/store'
+import { getLimitDeclaration } from './limits-registry'
+import type { AccessSession } from './types'
+
+// ---------------------------------------------------------------------------
+// Headless access — the imperative counterpart of useAccess()/useLimitGuard()
+// for runtimes without React: the agent's client-plane tool executor, command
+// handlers, background sync. Reads the SAME singleton stores the providers
+// hydrate, and decides with the SAME engine (@fayz-ai/core/access), so a
+// decision here never diverges from what the UI shows.
+//
+// Denials come back as the structured AgentDenial (never a silent failure) so
+// an agent can explain the denial and offer the upgrade conversationally.
+// ---------------------------------------------------------------------------
+
+/**
+ * Snapshot of the live session assembled from the singleton stores — the same
+ * assembly AccessProvider does reactively. Values are as-hydrated: before
+ * AuthProvider/OrgProvider finish, fields are null (and decisions fail-open on
+ * profile, closed on nothing — same semantics as the providers).
+ */
+export function getAccessSnapshot(): AccessSession {
+  const user = useAuthStore.getState().user
+  const org = useOrganizationStore.getState().currentOrg
+  const profile = usePermissionsStore.getState().currentProfile
+  const plans = useBillingStore.getState().plans
+  const plan: Plan | null = org?.plan ? plans.find((p) => p.id === org.plan) ?? null : null
+  return { user, org, profile, plan }
+}
+
+/** Imperative role × plan check over the live snapshot. */
+export function checkAccess(feature: string, action?: PermissionAction): AgentGuardResult {
+  const session = getAccessSnapshot()
+  const decision = resolveAccess(session, feature, action)
+  if (decision.allowed) return { allowed: true }
+  return agentDenial(decision.reason ?? 'role')
+}
+
+/**
+ * Imperative plan-limit guard: would adding `n` rows exceed the cap for
+ * `key`? Counts FRESH (never trusts stale hook state), mirrors useLimitGuard.
+ * No declaration / no cap / `-1` / no tenant ⇒ allowed. Does NOT open the
+ * UpgradeModal — the caller decides how to surface the denial (an agent turns
+ * it into a conversational upgrade prompt).
+ */
+export async function guardLimit(key: string, n = 1): Promise<AgentGuardResult> {
+  const session = getAccessSnapshot()
+  const tenantId = session.org?.id
+  const cap = session.plan?.entitlements?.limits?.[key]
+  const declaration = getLimitDeclaration(key)
+
+  if (!declaration || cap === undefined || cap === -1 || !tenantId) return { allowed: true }
+
+  const used = await countByTenant(declaration.table, {
+    kind: declaration.kindFilter,
+    period: declaration.period,
+    tenantId,
+    fresh: true,
+  })
+
+  if (used + n > cap) {
+    return agentDenial('limit', { key, max: cap, used })
+  }
+  return { allowed: true }
+}

package/src/access/index.ts

@@ -0,0 +1,27 @@
+// Access engine — the single point of access decision composing RBAC role
+// (can?) × plan entitlements (entitled? how many?). See resolver.ts for the
+// pure composition and context.tsx for the reactive session wiring.
+
+export { AccessProvider, useAccess, useAccessOptional, useLimit, useLimitGuard } from './context'
+export type { AccessProviderProps } from './context'
+
+export { resolveAccess, isEntitledByPlan } from './resolver'
+
+export { getAccessSnapshot, checkAccess, guardLimit } from './headless'
+export { agentDenial, UPGRADE_URL } from '@fayz-ai/core/access'
+export type { AgentDenial, AgentDenialLimit, AgentGuardResult } from '@fayz-ai/core/access'
+
+export { invalidateLimit, setLimitRegistry, getLimitDeclaration, CORE_LIMIT_DECLARATIONS } from './limits-registry'
+
+export { useModuleNavAccess, applyNavAccess } from './module-nav'
+
+export { useUpgradeModalStore } from './upgrade-modal-store'
+export type { UpgradeModalPayload, UpgradeModalStore } from './upgrade-modal-store'
+
+export type {
+  AccessApi,
+  AccessDecision,
+  AccessSession,
+  DenyReason,
+  LimitState,
+} from './types'

package/src/access/limits-registry.ts

@@ -0,0 +1,86 @@
+import type { LimitDeclaration, RegisteredEntity } from '@fayz-ai/core'
+import { invalidateCount } from '@fayz-ai/core'
+
+/**
+ * Module-level registry bridging React (the provider that knows the declarations)
+ * and the plain `invalidateLimit(key)` function that create handlers call outside
+ * any component. The AccessProvider publishes the merged declarations here on
+ * mount; `useLimit`/`useLimitGuard` and `invalidateLimit` read from it.
+ */
+
+/**
+ * Shell built-in limit declarations. Unlike plugin/app limits (contributed via
+ * `PluginManifest.declaredLimits` / `billing.limitDeclarations`), these count
+ * core tenant tables that have no owning plugin: seats (`tenant_members`) and
+ * `locations`. Merged as the LOWEST-priority layer by the AccessProvider, so a
+ * plugin or app may still override a key (e.g. add a `kindFilter`).
+ */
+export const CORE_LIMIT_DECLARATIONS: LimitDeclaration[] = [
+  { key: 'users', label: 'Users', table: 'tenant_members' },
+  { key: 'locations', label: 'Locations', table: 'locations' },
+]
+
+/**
+ * Entity-derived layer of the limit merge: any registered CRUD entity carrying
+ * `limitKey` yields a declaration for free from its own data mapping (table +
+ * archetype kind) — a cap without a countable binding is a dead cap. Shared by
+ * the AccessProvider (live registry) and the manifest derivation (agent
+ * contract), so both resolve the identical layer.
+ */
+export function entityDerivedLimitDeclarations(entities: RegisteredEntity[]): LimitDeclaration[] {
+  const out: LimitDeclaration[] = []
+  for (const e of entities) {
+    const def = e.entityDef
+    if (def?.limitKey && def.data?.table) {
+      out.push({
+        key: def.limitKey,
+        label: e.labelPlural,
+        table: def.data.table,
+        kindFilter: def.data.archetypeKind,
+      })
+    }
+  }
+  return out
+}
+
+let registry = new Map<string, LimitDeclaration>()
+
+/** Called by AccessProvider whenever the merged limit declarations change. */
+export function setLimitRegistry(declarations: LimitDeclaration[]): void {
+  const next = new Map<string, LimitDeclaration>()
+  for (const decl of declarations) next.set(decl.key, decl)
+  registry = next
+}
+
+export function getLimitDeclaration(key: string): LimitDeclaration | undefined {
+  return registry.get(key)
+}
+
+// --- Invalidation pub/sub -------------------------------------------------
+// useLimit subscribes per key; invalidateLimit(key) drops the cached count for
+// the declaration's table and notifies subscribers to re-fetch.
+
+const listeners = new Map<string, Set<() => void>>()
+
+export function subscribeLimit(key: string, cb: () => void): () => void {
+  let set = listeners.get(key)
+  if (!set) {
+    set = new Set()
+    listeners.set(key, set)
+  }
+  set.add(cb)
+  return () => {
+    set?.delete(cb)
+    if (set && set.size === 0) listeners.delete(key)
+  }
+}
+
+/**
+ * Invalidate a limit after a create/delete so its next read is fresh, then wake
+ * any mounted `useLimit(key)`. Safe to call from plain handlers (no React).
+ */
+export function invalidateLimit(key: string): void {
+  const decl = registry.get(key)
+  if (decl) invalidateCount(decl.table)
+  listeners.get(key)?.forEach((cb) => cb())
+}

package/src/access/module-nav.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect } from 'vitest'
+import type { ModuleNavItem } from '@fayz-ai/ui'
+import { applyNavAccess } from './module-nav'
+import type { AccessApi } from './types'
+
+// ---------------------------------------------------------------------------
+// Fixtures — a fake AccessApi so the pure decoration is testable without React
+// or the live stores. `roleDenied` names features the role can't read;
+// `planDenied` names features the plan doesn't entitle.
+// ---------------------------------------------------------------------------
+
+function fakeAccess(opts: { roleDenied?: string[]; planDenied?: string[] }): AccessApi {
+  const roleDenied = new Set(opts.roleDenied ?? [])
+  const planDenied = new Set(opts.planDenied ?? [])
+  return {
+    can: (feature) =>
+      roleDenied.has(feature) ? { allowed: false, reason: 'role' } : { allowed: true },
+    entitled: (feature) => !planDenied.has(feature),
+  }
+}
+
+function item(id: string, feature?: string, children?: ModuleNavItem[]): ModuleNavItem {
+  return { id, label: id, feature, children }
+}
+
+// ---------------------------------------------------------------------------
+// applyNavAccess
+// ---------------------------------------------------------------------------
+
+describe('applyNavAccess', () => {
+  const known = new Set(['fin_reconciliation', 'fin_cards', 'fin_commissions'])
+
+  it('removes a link the role denies (declared feature)', () => {
+    const nav = [item('summary'), item('reconciliation', 'fin_reconciliation')]
+    const out = applyNavAccess(nav, fakeAccess({ roleDenied: ['fin_reconciliation'] }), known)
+    expect(out.map((i) => i.id)).toEqual(['summary'])
+  })
+
+  it('badges a plan-denied link premium but keeps it navigable', () => {
+    const nav = [item('reconciliation', 'fin_reconciliation')]
+    const out = applyNavAccess(nav, fakeAccess({ planDenied: ['fin_reconciliation'] }), known)
+    expect(out).toHaveLength(1)
+    expect(out[0].premium).toBe(true)
+  })
+
+  it('passes an ABSENT feature through untouched (default allow — no remove, no crown)', () => {
+    // `fin_ghost` isn't in the RBAC catalog → the role axis is skipped even
+    // though a bare `can` would report a role denial for it.
+    const nav = [item('ghost', 'fin_ghost')]
+    const out = applyNavAccess(nav, fakeAccess({ roleDenied: ['fin_ghost'] }), known)
+    expect(out).toHaveLength(1)
+    expect(out[0].premium).toBe(false)
+  })
+
+  it('leaves featureless links (and their id/onClick) untouched', () => {
+    const nav = [item('summary')]
+    const out = applyNavAccess(nav, fakeAccess({ roleDenied: ['x'], planDenied: ['y'] }), known)
+    expect(out).toEqual(nav)
+  })
+
+  it('recurses into children — removes role-denied, crowns plan-denied', () => {
+    const nav = [
+      item('cards', 'fin_cards', [
+        item('cards-overview'),
+        item('cards-secret', 'fin_reconciliation'), // role-denied child
+        item('cards-premium', 'fin_commissions'), // plan-denied child
+      ]),
+    ]
+    const out = applyNavAccess(
+      nav,
+      fakeAccess({ roleDenied: ['fin_reconciliation'], planDenied: ['fin_commissions'] }),
+      known,
+    )
+    const parent = out[0]
+    expect(parent.children!.map((c) => c.id)).toEqual(['cards-overview', 'cards-premium'])
+    expect(parent.children!.find((c) => c.id === 'cards-premium')!.premium).toBe(true)
+  })
+})

package/src/access/module-nav.ts

@@ -0,0 +1,82 @@
+import * as React from 'react'
+import type { ModuleNavItem } from '@fayz-ai/ui'
+import { usePermissionsStore } from '../permissions/store'
+import { useAccessOptional } from './context'
+import type { AccessApi } from './types'
+
+// ---------------------------------------------------------------------------
+// useModuleNavAccess — the LINK-side counterpart of EntitlementGate for a
+// plugin's INTERNAL navigation (ModulePage sub-nav). Mirrors the top-level
+// Sidebar/AdminShell rule so a premium sub-module link reads identically:
+//
+//   • role denies  (can(feature,'read').reason === 'role')  → REMOVE the link
+//   • plan denies  (entitled(feature) === false)            → keep, premium:true
+//                    (the click still navigates; the gated CONTENT shows the
+//                     UpgradePrompt via EntitlementGate)
+//   • otherwise                                             → keep as-is
+//
+// A feature id ABSENT from the RBAC catalog is treated as "default allow": the
+// role axis is skipped entirely for it (an undeclared feature can't be a role
+// denial), so apps that wire the plugin without declaring the sub-feature don't
+// lose the link. The plan axis is naturally safe already — `entitled` returns
+// true for any feature a plan never disables.
+//
+// Recursive over `children`. Degrades to allow-all when no <AccessProvider> is
+// mounted (bare host shell), exactly like `useAccessOptional`.
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure decoration used by {@link useModuleNavAccess}. Kept store-free so it is
+ * directly unit-testable: pass the composed {@link AccessApi} and the set of
+ * feature ids known to the RBAC catalog.
+ */
+export function applyNavAccess(
+  items: ModuleNavItem[],
+  access: AccessApi,
+  knownFeatures: Set<string>,
+): ModuleNavItem[] {
+  const decorate = (item: ModuleNavItem): ModuleNavItem | null => {
+    const children = item.children
+      ? item.children
+          .map(decorate)
+          .filter((c): c is ModuleNavItem => c !== null)
+      : undefined
+
+    if (!item.feature) {
+      return children ? { ...item, children } : item
+    }
+
+    // Role axis — only meaningful for a feature the RBAC catalog actually
+    // declares. An undeclared feature defaults to allow (never removed).
+    if (knownFeatures.has(item.feature)) {
+      const decision = access.can(item.feature, 'read')
+      if (!decision.allowed && decision.reason === 'role') return null
+    }
+
+    // Plan axis — `entitled` is `false` only on an explicit plan denial; absent
+    // features stay entitled, so no Crown appears for them.
+    const premium = access.entitled(item.feature) === false
+
+    return children ? { ...item, premium, children } : { ...item, premium }
+  }
+
+  return items.map(decorate).filter((i): i is ModuleNavItem => i !== null)
+}
+
+/**
+ * Resolve a plugin's internal nav against role × plan: hides role-denied links,
+ * badges plan-denied ones with a Crown (`premium`), and passes everything else
+ * through unchanged. Recursive over children.
+ */
+export function useModuleNavAccess(items: ModuleNavItem[]): ModuleNavItem[] {
+  const access = useAccessOptional()
+  const features = usePermissionsStore((s) => s.features)
+  const knownFeatures = React.useMemo(
+    () => new Set(features.map((f) => f.id)),
+    [features],
+  )
+  return React.useMemo(
+    () => applyNavAccess(items, access, knownFeatures),
+    [items, access, knownFeatures],
+  )
+}