@fayz-ai/saas 0.8.1 → 0.8.2

package/src/crud/archetypes/PersonDetailTabs.tsx

@@ -3,6 +3,7 @@ import { Clock, FileText, CalendarDays } from 'lucide-react'
 import { Card, CardContent } from '@fayz-ai/ui'
 import { Badge } from '@fayz-ai/ui'
 import { ScheduleEditor } from './ScheduleEditor'
+import { AddressesTab } from './AddressesTab'
 import { useTranslation } from '@fayz-ai/core'
 import { usePluginRuntimeOptional as usePluginsOptional } from '@fayz-ai/core'
 import { getWidgetsForZone } from '@fayz-ai/core'
@@ -101,6 +102,10 @@ export function ScheduleTab({ item }: { item: any }) {
 
 export const PERSON_DETAIL_TABS = [
   { id: 'schedule', label: 'Schedule', icon: 'CalendarDays', component: ScheduleTab, visibleFor: ['staff'] },
+  // Core table (public.addresses), so every app with a person record gets this:
+  // delivery addresses for a client, pickup point for a supplier, home address
+  // for staff. Not shop-specific.
+  { id: 'addresses', label: 'Endereços', icon: 'MapPin', component: AddressesTab },
   { id: 'documents', label: 'Documents', icon: 'FileText', component: DocumentsTab },
   // Per-person financial statement — only shown when the financial plugin contributes
   // its widget (see requiresWidgetZone). Clients = paid invoices; staff = commissions.

package/src/crud/createCrudPage.tsx

@@ -59,6 +59,8 @@ export function createCrudPage<T extends { id: string }>(
     fields: entityDef.fields,
     source: 'app',
     archetype: entityDef.data?.archetype,
+    entityDef: entityDef as EntityDef,
+    mockData: options?.mockData as Array<{ id: string }> | undefined,
   })
 
   return GeneratedCrudPage

package/src/crud/index.ts

@@ -10,3 +10,9 @@ export { ImportWizard } from './ImportWizard'
 export type { ImportRowError } from './ImportWizard'
 export { exportToCSV } from './csv-export'
 export { RelationSelect, RelationCell, useRelationOptions, loadRelationOptions, invalidateRelationOptions } from './relation-field'
+// Link to another entity's detail page — used by detail tabs and by plugins
+// that reference a record from a different module (e.g. the order list linking
+// its customer).
+// PersonLink is intentionally NOT re-exported: plugin-reports already exports
+// a different component under that name and the collision breaks its build.
+export { EntityLink, registerEntityPath, getPersonPath } from './archetypes/EntityLink'

package/src/env.d.ts

@@ -8,6 +8,13 @@ interface ImportMetaEnv {
   /** Deployment-fixed canonical origin (e.g. https://beauty-saas.live.fayz.ai),
    *  injected by the container. Used to build invite/magic-link redirects. */
   readonly VITE_APP_URL?: string
+  /** Fayz project this app belongs to, injected by the container. */
+  readonly VITE_FAYZ_PROJECT_ID?: string
+  /** Fayz API base (e.g. https://fayz.ai/api), injected by the container. */
+  readonly VITE_FAYZ_API_BASE_URL?: string
+  /** Publishable key for the project's web agent channel. Present only once an
+   *  agent is enabled in Fayz — its absence is what leaves the assistant off. */
+  readonly VITE_FAYZ_AGENT_KEY?: string
 }
 
 interface ImportMeta {

package/src/index.ts

@@ -2,11 +2,13 @@
 // App factory (main entry point)
 // ---------------------------------------------------------------------------
 export { createFayzApp, AdminProviders } from './app/admin-app'
-export type { FayzAppConfig, AuthConfig, OrgConfig, ChatConfig, CustomPage, PageSection } from './app/config'
+export type { FayzAppConfig, AuthConfig, OrgConfig, ChatConfig, FayzBillingConfig, CustomPage, PageSection } from './app/config'
 
 // Native admin scaffold — manifest-first entry. Importing this registers the
 // 'admin' scaffold so renderApp(manifest) can resolve it.
 export { defineSaas, AdminScaffold } from './app/scaffold'
+export { deriveAgentContract } from './app/derive-contract'
+export type { DerivedAgentSections } from './app/derive-contract'
 export { AdminShell } from './app/AdminShell'
 export { LoginPage } from './app/LoginPage'
 export { navigateTo as adminNavigateTo, useAdminPath } from './app/routing'
@@ -40,8 +42,10 @@ export { WidgetSlot } from './plugins/WidgetSlot'
 export { useFieldRules } from './hooks/useFieldRules'
 
 export { createCrudPage } from './crud/createCrudPage'
+export { EntityLink, registerEntityPath, getPersonPath } from './crud/archetypes/EntityLink'
 // Client-orders archetype (used by beauty-saas client detail tab)
 export { ClientOrdersTab } from './shell/components/crud/archetypes/ClientOrdersTab'
+export type { ClientOrdersProvider, ClientOrdersQuery, ClientOrdersNavigator, ClientDocument, ClientDocumentStage, ClientOrdersStageFilter } from './shell/types/client-orders'
 export { createClientOrdersProvider } from './shell/lib/create-client-orders-provider'
 
 // ---------------------------------------------------------------------------
@@ -90,15 +94,53 @@ export {
   usePermissionsStore,
   PermissionsProvider,
   usePermission,
+  usePermissionOptional,
   useHasPermission,
   usePermissions,
 } from './permissions/index'
 export type { PermissionsStore, PermissionsProviderProps } from './permissions/index'
 
+// ---------------------------------------------------------------------------
+// Access engine — role × plan decision, quantity limits, upgrade modal store
+// ---------------------------------------------------------------------------
+export {
+  AccessProvider,
+  useAccess,
+  useAccessOptional,
+  useLimit,
+  useLimitGuard,
+  useModuleNavAccess,
+  resolveAccess,
+  isEntitledByPlan,
+  invalidateLimit,
+  useUpgradeModalStore,
+  getAccessSnapshot,
+  checkAccess,
+  guardLimit,
+  agentDenial,
+  UPGRADE_URL,
+} from './access/index'
+export type {
+  AccessProviderProps,
+  AccessApi,
+  AccessDecision,
+  AccessSession,
+  DenyReason,
+  LimitState,
+  UpgradeModalPayload,
+  UpgradeModalStore,
+  AgentDenial,
+  AgentDenialLimit,
+  AgentGuardResult,
+} from './access/index'
+
 // ---------------------------------------------------------------------------
 // Billing
 // ---------------------------------------------------------------------------
 export { useBillingStore } from './billing/index'
+export { EntitlementGate, LimitGate } from './shell/components/billing/gates'
+export { UpgradePrompt } from './shell/components/billing/UpgradePrompt'
+export type { UpgradePromptProps } from './shell/components/billing/UpgradePrompt'
 export type { BillingStore, BillingState, Subscription, Invoice } from './billing/index'
 
 // ---------------------------------------------------------------------------
@@ -168,8 +210,14 @@ export { formatCurrency, type CurrencyConfig } from './lib/currency'
 export { PluginRegistryManager } from './plugins/PluginRegistryManager'
 export { useModuleNavigation } from './hooks/useModuleNavigation'
 export { PersonLink } from './components/shared/PersonLink'
+export { ContactPicker } from './components/shared/ContactPicker'
+export type { ContactPickerProps, ContactPickerValue } from './components/shared/ContactPicker'
+export { createPerson } from './components/shared/create-person'
+export type { CreatePersonInput, CreatedPerson } from './components/shared/create-person'
 export { resolveEntityHref } from './lib/entity-routes'
 export { usePluginPrefs } from './hooks/usePluginPrefs'
+export { useTenantPluginSettings } from './shell/hooks/useTenantPluginSettings'
+export type { TenantPluginSettings } from './shell/hooks/useTenantPluginSettings'
 export { setScheduleBlockConfig, getScheduleBlockConfig, subscribeScheduleBlockConfig } from './lib/schedule-config'
 
 // Assistant chat store — lets apps drive the shell's chat panel imperatively

package/src/org/store.ts

@@ -62,7 +62,15 @@ export const useOrganizationStore = create<OrgStore>((set) => ({
   setLoading: (loading) => set({ loading }),
   reset: () => {
     setActiveTenantId(undefined)
-    persistOrgId(null)
+    // NOTE: do NOT clear the persisted org id here. The org providers call
+    // reset() whenever the auth store transiently reports `user === null` —
+    // which happens on every fresh load while the Supabase session hydrates
+    // asynchronously. Wiping 'fayz:current-org' at that moment drops a
+    // multi-org user's workspace selection BEFORE loadOrgs can read it back,
+    // so the app always falls to memberships[0] on reload (single-org users
+    // never noticed). The pin is a last-selected hint that's re-validated
+    // against the fresh membership list on load, so it's safe to keep across
+    // sign-out too (a mismatching pin just falls back to memberships[0]).
     set({ currentOrg: null, userOrgs: [], members: [], loading: false })
   },
 }))

package/src/permissions/context.tsx

@@ -1,24 +1,29 @@
 import * as React from 'react'
 import type { FeatureDeclaration, PermissionsConfig, PermissionProfile } from '@fayz-ai/core'
+import { usePluginRuntimeOptional } from '@fayz-ai/core'
 import { usePermissionsStore } from './store'
 
 // ---------------------------------------------------------------------------
 // Permission check helpers
 // ---------------------------------------------------------------------------
 
-function profileHasPermission(
-  profile: PermissionProfile | null,
-  feature: string,
-  action?: string,
-): boolean {
-  if (!profile) return true
+// The role-side check moved to @fayz-ai/core/access (single implementation for
+// browser, headless and the Fayz broker). Re-exported to keep call-sites stable.
+import { profileHasPermission } from '@fayz-ai/core/access'
+export { profileHasPermission }
 
-  const actions = profile.grants[feature]
-  if (!actions) return false
-
-  if (!action) return actions.length > 0
-
-  return actions.includes(action) || actions.includes('manage')
+/**
+ * Merge plugin-declared features with the app's own, deduped by id. The app's
+ * declaration wins on collision (it can override a plugin's label/actions).
+ */
+function mergeFeatures(
+  pluginFeatures: FeatureDeclaration[] | undefined,
+  appFeatures: FeatureDeclaration[] | undefined,
+): FeatureDeclaration[] {
+  const byId = new Map<string, FeatureDeclaration>()
+  for (const f of pluginFeatures ?? []) byId.set(f.id, f)
+  for (const f of appFeatures ?? []) byId.set(f.id, f) // app override wins
+  return Array.from(byId.values())
 }
 
 // ---------------------------------------------------------------------------
@@ -47,11 +52,20 @@ export function PermissionsProvider({ config, children }: PermissionsProviderPro
   const { setFeatures, startImpersonation, stopImpersonation, currentProfile, isImpersonating } =
     usePermissionsStore()
 
+  // Plugins declare their own permission features via `declaredFeatures`, which the
+  // plugin runtime aggregates into `pluginFeatures`. Merging them here is what makes
+  // a plugin "born compatible" — its features show up in the RBAC matrix and gate
+  // checks without the app re-declaring them. The app's own `config.features` wins
+  // on id collisions (app override), so an app can refine a plugin's declaration.
+  const runtime = usePluginRuntimeOptional()
+  const pluginFeatures = runtime?.pluginFeatures
+
   React.useEffect(() => {
-    if (config?.features) {
-      setFeatures(config.features)
+    const merged = mergeFeatures(pluginFeatures, config?.features)
+    if (merged.length > 0) {
+      setFeatures(merged)
     }
-  }, [config, setFeatures])
+  }, [config, pluginFeatures, setFeatures])
 
   function hasPermission(feature: string, action?: string): boolean {
     return profileHasPermission(currentProfile, feature, action)

package/src/shell/components/auth/ProtectedRoute.tsx

@@ -1,8 +1,16 @@
 import React from 'react'
 import { useAuth } from '../../hooks/useAuth'
-import { usePermission } from '../../hooks/usePermission'
+import { useTenantStore } from '../../stores/tenant.store'
 import type { MemberRole } from '../../types'
 
+const ROLE_HIERARCHY: Record<MemberRole, number> = {
+  owner: 5,
+  admin: 4,
+  manager: 3,
+  staff: 2,
+  viewer: 1,
+}
+
 interface ProtectedRouteProps {
   children?: React.ReactNode
   requiredRole?: MemberRole
@@ -16,7 +24,9 @@ function LoadingSkeleton() {
 
 export function ProtectedRoute({ children, requiredRole, fallback, onUnauthenticated }: ProtectedRouteProps) {
   const { user, loading, initialized } = useAuth()
-  const { requireRole } = usePermission()
+  const currentRole = useTenantStore((s) => s.currentRole)
+  const requireRole = (role: MemberRole): boolean =>
+    currentRole ? ROLE_HIERARCHY[currentRole] >= ROLE_HIERARCHY[role] : false
 
   React.useEffect(() => {
     if (initialized && !loading && !user && onUnauthenticated) {

package/src/shell/components/billing/SoftLimitBanner.tsx

@@ -0,0 +1,81 @@
+import * as React from 'react'
+import { AlertTriangle, X } from 'lucide-react'
+import { Button } from '@fayz-ai/ui'
+import { useTranslation } from '../../hooks/useTranslation'
+import { navigateTo } from '../../../app/routing'
+import { useLimit, type LimitInfo } from './access-contract'
+
+// ---------------------------------------------------------------------------
+// SoftLimitBanner — discreet, persistent notice at the top of the content when
+// a monitored limit is EXCEEDED (used > max), not merely reached. This is the
+// Notion-style soft-limit path: the public booking flow (storefront
+// createCustomer) never blocks the end client, so a tenant can overshoot its cap
+// — the admin sees this banner nudging an upgrade. Dismissable for the session.
+//
+// `keys` are the limit keys to monitor; the shell derives them from
+// `manifest.billing.softLimitKeys` (documented seam). Each key mounts a probe so
+// hooks stay unconditional even as the list is config-driven.
+// ---------------------------------------------------------------------------
+
+function LimitProbe({ limitKey, onReport }: { limitKey: string; onReport: (key: string, info: LimitInfo) => void }) {
+  const info = useLimit(limitKey)
+  React.useEffect(() => {
+    onReport(limitKey, info)
+  }, [limitKey, info, onReport])
+  return null
+}
+
+export function SoftLimitBanner({ keys }: { keys: string[] }) {
+  const { t } = useTranslation()
+  const tr = (key: string, fallback: string, params?: Record<string, string | number>) => {
+    let v = t(key)
+    if (!v || v === key) v = fallback
+    if (params) for (const [k, val] of Object.entries(params)) v = v.replace(`{${k}}`, String(val)).replace(`{{${k}}}`, String(val))
+    return v
+  }
+
+  const [over, setOver] = React.useState<Record<string, boolean>>({})
+  const [dismissed, setDismissed] = React.useState<Record<string, boolean>>({})
+
+  const report = React.useCallback((key: string, info: LimitInfo) => {
+    const isOver = !info.unlimited && !info.loading && info.used > info.max
+    setOver((prev) => {
+      if (isOver === Boolean(prev[key])) return prev
+      return { ...prev, [key]: isOver }
+    })
+  }, [])
+
+  // Stable key list (avoid remounting probes each render).
+  const monitored = React.useMemo(() => Array.from(new Set(keys)), [keys])
+
+  const activeKey = monitored.find((k) => over[k] && !dismissed[k])
+
+  return (
+    <>
+      {monitored.map((k) => (
+        <LimitProbe key={k} limitKey={k} onReport={report} />
+      ))}
+      {activeKey && (
+        <div className="mb-3 flex flex-wrap items-center gap-3 rounded-lg border border-amber-400/50 bg-amber-50/70 px-4 py-2.5 text-sm dark:bg-amber-950/25">
+          <AlertTriangle className="h-4 w-4 shrink-0 text-amber-600 dark:text-amber-400" />
+          <span className="min-w-0 flex-1 text-foreground">
+            {tr('banner.overLimit', "You've exceeded the {label} limit of your plan — upgrade to keep growing.", {
+              label: tr(`limit.label.${activeKey}`, activeKey),
+            })}
+          </span>
+          <Button size="sm" onClick={() => navigateTo('/settings/subscription')}>
+            {tr('upgrade.cta', 'View plans')}
+          </Button>
+          <button
+            type="button"
+            aria-label={tr('common.close', 'Close')}
+            className="rounded p-1 text-muted-foreground transition-colors hover:bg-amber-400/20 hover:text-foreground"
+            onClick={() => setDismissed((prev) => ({ ...prev, [activeKey]: true }))}
+          >
+            <X className="h-4 w-4" />
+          </button>
+        </div>
+      )}
+    </>
+  )
+}