@fayz-ai/saas 0.8.0 → 0.8.2

package/src/app/admin-app.tsx

@@ -14,6 +14,7 @@ import {
   type AuthLayout,
   type AuthPluginOptions,
   type ResolvedAuthPlugin,
+  type LoginAmbassador,
 } from '@fayz-ai/plugin-auth'
 import { NavTransitionProvider } from '@fayz-ai/ui'
 import { createFayzSupabaseClient, getFayzSupabaseClientOptional } from '../supabase/client'
@@ -22,8 +23,10 @@ import { createSupabaseOrgAdapter } from '../org/adapters/supabase'
 import { createMockOrgAdapter } from '../org/adapters/mock'
 import { useOrganizationStore } from '../org/store'
 import { PermissionsProvider } from '../permissions/context'
+import { AccessProvider } from '../access/context'
 import { ToastProvider } from '../shell/components/notifications/ToastProvider'
 import { ChatFab, ChatPanel } from '../shell/components/chat'
+import { resolveFayzAgentConnection } from '../shell/lib/fayz-agent'
 import { useBillingStore } from '../billing/store'
 import type { Plan } from '@fayz-ai/core'
 import type { PlanConfig } from '../shell/types/billing'
@@ -58,6 +61,8 @@ function resolveAuthRuntime(config: FayzAppConfig): ResolvedAuthPlugin {
     logo: auth?.logo ?? auth?.loginLogo,
     tagline: auth?.tagline ?? auth?.loginTagline,
     description: auth?.description ?? auth?.loginDescription,
+    loginAmbassadors: auth?.loginAmbassadors,
+    loginAmbassadorsLabel: auth?.loginAmbassadorsLabel,
     oauth,
     routes: auth?.routes,
     supabase: {
@@ -76,6 +81,8 @@ export function getAuthShellProps(auth: FayzAppConfig['auth']): {
   loginDescription?: string
   loginLogo?: React.ReactNode
   loginLayout?: AuthLayout
+  loginAmbassadors?: LoginAmbassador[]
+  loginAmbassadorsLabel?: string
   showOAuth?: boolean
   oauthProviders?: Exclude<import('@fayz-ai/core').AuthProvider, 'email'>[]
 } {
@@ -87,6 +94,8 @@ export function getAuthShellProps(auth: FayzAppConfig['auth']): {
       loginDescription: auth.description,
       loginLogo: auth.logo,
       loginLayout: auth.layout,
+      loginAmbassadors: auth.loginAmbassadors,
+      loginAmbassadorsLabel: auth.loginAmbassadorsLabel,
       showOAuth: auth.oauth.enabled,
       oauthProviders: auth.oauth.providers,
     }
@@ -97,6 +106,8 @@ export function getAuthShellProps(auth: FayzAppConfig['auth']): {
     loginDescription: auth.description ?? auth.loginDescription,
     loginLogo: auth.logo ?? auth.loginLogo,
     loginLayout: auth.layout ?? auth.loginLayout,
+    loginAmbassadors: auth.loginAmbassadors,
+    loginAmbassadorsLabel: auth.loginAmbassadorsLabel,
     showOAuth: auth.oauth?.enabled ?? auth.showOAuth,
     oauthProviders: auth.oauth?.providers ?? auth.oauthProviders,
   }
@@ -157,9 +168,13 @@ function buildI18nConfig(config: FayzAppConfig): {
 
 function BillingInitializer({ config }: { config: FayzAppConfig }) {
   const setPlans = useBillingStore((s) => s.setPlans)
+  const setCheckout = useBillingStore((s) => s.setCheckout)
   React.useEffect(() => {
     if (config.billing?.plans) setPlans(config.billing.plans.map(normalizeBillingPlan))
-  }, [config.billing, setPlans])
+    // Seed the payment-gateway seam so the shell's Subscription page can route
+    // plan changes through it (Stripe/Pix) instead of a direct updateOrg.
+    setCheckout(config.billing?.onCheckout ?? null)
+  }, [config.billing, setPlans, setCheckout])
   return null
 }
 
@@ -174,6 +189,10 @@ function normalizeBillingPlan(plan: PlanConfig): Plan {
     features: plan.features,
     highlighted: plan.popular,
     stripePriceId: undefined,
+    // Preserve structured entitlements onto the runtime Plan — the access engine
+    // reads these to enforce feature gates + quantity caps. (Previously dropped
+    // here, leaving plan limits dead.)
+    entitlements: plan.entitlements,
   }
 }
 
@@ -210,6 +229,10 @@ function ThemeInitializer({ config }: { config: FayzAppConfig }) {
 
 export function AdminProviders({ config, children }: { config: FayzAppConfig; children: React.ReactNode }) {
   const currentOrg = useOrganizationStore((s) => s.currentOrg)
+  const hasFayzAgent = React.useMemo(
+    () => !!resolveFayzAgentConnection(config.chat?.agent),
+    [config.chat?.agent],
+  )
 
   // Resolve adapters / i18n once per config identity.
   const resolved = React.useMemo(() => {
@@ -261,20 +284,34 @@ export function AdminProviders({ config, children }: { config: FayzAppConfig; ch
       <OrgProvider adapter={resolved.orgAdapter} autoCreate={config.org?.autoCreate ?? true}>
         <PluginRuntimeProvider value={runtime}>
           <PermissionsProvider config={config.permissions}>
-            <I18nProvider value={resolved.i18n}>
-              <ThemeInitializer config={config} />
-              <BillingInitializer config={config} />
-              <ToastProvider />
+            <AccessProvider limitDeclarations={config.billing?.limitDeclarations}>
+              <I18nProvider value={resolved.i18n}>
+                <ThemeInitializer config={config} />
+                <BillingInitializer config={config} />
+                <ToastProvider />
               <NavTransitionProvider value={config.navTransition ?? 'slide'}>
                 {children}
               </NavTransitionProvider>
-              {config.chat?.enabled !== false && config.chat ? (
+              {/* The assistant also renders with no `chat` block at all — a
+                  project with a Fayz agent enabled injects its connection via
+                  env, so the app needs no config to light it up. */}
+              {config.chat?.enabled !== false && (config.chat || hasFayzAgent) ? (
                 <>
-                  <ChatFab apiEndpoint={config.chat.apiEndpoint} systemPrompt={config.chat.systemPrompt} />
-                  <ChatPanel title={config.chat.title} apiEndpoint={config.chat.apiEndpoint} systemPrompt={config.chat.systemPrompt} />
+                  <ChatFab
+                    apiEndpoint={config.chat?.apiEndpoint}
+                    systemPrompt={config.chat?.systemPrompt}
+                    agent={config.chat?.agent}
+                  />
+                  <ChatPanel
+                    title={config.chat?.title}
+                    apiEndpoint={config.chat?.apiEndpoint}
+                    systemPrompt={config.chat?.systemPrompt}
+                    agent={config.chat?.agent}
+                  />
                 </>
               ) : null}
-            </I18nProvider>
+              </I18nProvider>
+            </AccessProvider>
           </PermissionsProvider>
         </PluginRuntimeProvider>
       </OrgProvider>

package/src/app/config.ts

@@ -7,12 +7,17 @@ import type {
   ThemeMode,
   LocaleConfig,
   PermissionsConfig,
+  LimitDeclaration,
+  AgentDomainKnowledge,
+  AgentRpcDeclaration,
+  EntityDef,
 } from '@fayz-ai/core'
-import type { AuthPluginOptions, ResolvedAuthPlugin } from '@fayz-ai/plugin-auth'
+import type { AuthPluginOptions, ResolvedAuthPlugin, LoginAmbassador } from '@fayz-ai/plugin-auth'
 import type { BottomNavItem, MobileHeaderVariant } from '@fayz-ai/ui'
 import type { SaasTheme } from '../shell/config/theme/tokens'
 import type { CreateThemeOptions } from '../shell/config/theme/utils'
 import type { PlanConfig } from '../shell/types/billing'
+import type { FayzAgentConnectionConfig } from '../shell/lib/fayz-agent'
 
 // ---------------------------------------------------------------------------
 // Page registration
@@ -63,6 +68,12 @@ export interface AuthConfig {
   loginLayout?: 'split' | 'centered'
   loginTagline?: string
   loginDescription?: string
+  /** Product ambassadors shown as a small social-proof avatar strip above the
+   *  tagline on the split-login brand panel. Each needs a local `image` path;
+   *  degrades to nothing when omitted. */
+  loginAmbassadors?: LoginAmbassador[]
+  /** Optional microtext beside the ambassador strip, e.g. "+2 mil profissionais". */
+  loginAmbassadorsLabel?: string
   showOAuth?: boolean
   oauthProviders?: Exclude<AuthProvider, 'email'>[]
 }
@@ -81,14 +92,39 @@ export interface OrgConfig {
 export interface ChatConfig {
   enabled?: boolean
   title?: string
+  /** Extra guidance appended to the agent's own instructions. */
   systemPrompt?: string
+  /**
+   * Bring-your-own chat backend. Leave unset to use the Fayz agent configured
+   * for this project — the container injects the connection env, so no key or
+   * URL needs to live in app config.
+   */
   apiEndpoint?: string
+  /**
+   * Overrides for the Fayz agent connection, for apps built outside a Fayz
+   * container. `false` opts out of the Fayz agent entirely.
+   */
+  agent?: FayzAgentConnectionConfig | false
 }
 
 export interface FayzBillingConfig {
   plans: PlanConfig[]
   stripePublishableKey?: string
   portalUrl?: string
+  /**
+   * Payment-gateway seam. When defined, the shell's Subscription page calls this
+   * with the target plan id INSTEAD of writing `plan` straight onto the org — this
+   * is where Stripe Checkout / Pix / Mercado Pago plug in (create the intent,
+   * redirect, let the webhook persist the plan). Left undefined, changing plan is
+   * an optimistic `adapter.updateOrg(orgId, { plan })`.
+   */
+  onCheckout?: (planId: string) => Promise<void> | void
+  /**
+   * App-level limit declarations layered on top of the plugins' `declaredLimits`
+   * (app wins on key collision). Use to add limits for app-local tables the
+   * plugins don't know about, or to re-point a key at a different table.
+   */
+  limitDeclarations?: LimitDeclaration[]
 }
 
 // ---------------------------------------------------------------------------
@@ -185,4 +221,21 @@ export interface FayzAppConfig {
   // AI Chat
   // -------------------------------------------------------------------------
   chat?: ChatConfig
+
+  // -------------------------------------------------------------------------
+  // Agent contract (manifest v3) — app-level additions to the derived
+  // AgentContract: structured domain knowledge for the prompt, app-shipped
+  // pool RPCs, and the per-app server-plane flip. Everything else (entities,
+  // tools, features, limits) is DERIVED from what the app already declares.
+  // -------------------------------------------------------------------------
+  agentContract?: {
+    /** 'server' flips data tools to broker-side execution for this app. */
+    executionPlane?: 'client' | 'server'
+    knowledge?: AgentDomainKnowledge
+    /** RPCs the app itself ships (vertical-specific, e.g. pricing quote). */
+    rpcs?: AgentRpcDeclaration[]
+    /** App-level read-models for the agent's data primitives (same contract
+     *  as PluginManifest.queryEntities — stable ASCII keys). */
+    queryEntities?: Array<{ key: string; entity: EntityDef }>
+  }
 }

package/src/app/core-entities.ts

@@ -0,0 +1,110 @@
+import type { EntityDef } from '@fayz-ai/core'
+
+// ---------------------------------------------------------------------------
+// CORE_QUERY_ENTITIES — spine tables the agent may read and write even though
+// no app declares a CRUD page for them.
+//
+// The data primitives (createRecord / updateRecord / searchRecords / queryData)
+// build their entity enum from three sources: the app's registered CRUD
+// entities, plugin registries, and plugin `queryEntities`. A spine table that
+// lives inside a DETAIL TAB rather than on a page of its own belongs to none of
+// them — so the agent could not see it, and would answer "esses campos não
+// estão disponíveis" to a request the UI handles fine.
+//
+// These are declared here, merged in by deriveAgentContract and useAITools, so
+// EVERY app gets them without editing a single app config. They intentionally
+// produce NO route and NO nav item: the surface for an address is the person's
+// Endereços tab, not a top-level page.
+// ---------------------------------------------------------------------------
+
+/** public.addresses — @fayz-ai/db spine migration 017_core_addresses. */
+const addressEntity: EntityDef = {
+  name: 'Address',
+  namePlural: 'Addresses',
+  icon: 'MapPin',
+  data: {
+    table: 'addresses',
+    tenantScoped: true,
+    tenantIdColumn: 'tenant_id',
+    searchColumns: ['label', 'street', 'district', 'city', 'postal_code', 'recipient'],
+  },
+  fields: [
+    // owner_id/owner_type are how an address attaches to its person. They are
+    // required and described rather than hidden: the agent reaches this table
+    // from a record it already has in hand ("adiciona o endereço X pra ele"),
+    // so the id it must pass is the one it just searched for or created.
+    {
+      key: 'owner_id',
+      label: 'Owner record id',
+      type: 'text',
+      required: true,
+      hint: 'Id of the person (client, contact, supplier, staff…) this address belongs to.',
+    },
+    {
+      key: 'owner_type',
+      label: 'Owner kind',
+      type: 'select',
+      options: ['person', 'location', 'tenant'],
+      hint: "Defaults to 'person'. Only set it for an address that belongs to a business location or to the tenant itself.",
+    },
+    { key: 'label', label: 'Label', type: 'text', searchable: true, hint: 'Casa, Trabalho, Depósito…' },
+    {
+      key: 'kind',
+      label: 'Use',
+      type: 'select',
+      options: ['both', 'shipping', 'billing'],
+      hint: "Defaults to 'both'.",
+    },
+    { key: 'postal_code', label: 'Postal code', type: 'text', required: true, searchable: true, hint: 'CEP.' },
+    { key: 'street', label: 'Street', type: 'text', required: true, searchable: true },
+    { key: 'number', label: 'Number', type: 'text' },
+    { key: 'complement', label: 'Complement', type: 'text' },
+    { key: 'district', label: 'District', type: 'text', searchable: true, hint: 'Bairro.' },
+    { key: 'city', label: 'City', type: 'text', required: true, searchable: true },
+    { key: 'state', label: 'State', type: 'text', required: true, hint: 'Two-letter UF.' },
+    { key: 'country', label: 'Country', type: 'text', hint: "Defaults to 'BR'." },
+    { key: 'recipient', label: 'Recipient', type: 'text', searchable: true, hint: 'Who receives, if not the owner.' },
+    { key: 'phone', label: 'Phone', type: 'text' },
+    {
+      key: 'is_default',
+      label: 'Default address',
+      type: 'boolean',
+      hint: 'Only one default per owner and kind — clear the previous one before setting this.',
+    },
+  ],
+}
+
+export interface CoreQueryEntity {
+  key: string
+  entity: EntityDef
+  writable?: boolean
+  /**
+   * How this entity attaches to another record — appended to the descriptions
+   * of the data primitives that can act on it. These entities do NOT stand
+   * alone, and nothing in a flat enum of ~37 keys conveys that.
+   *
+   * Both directions matter, and each fails differently without it. On WRITE the
+   * model reaches for `updateRecord` on the parent, is told the fields do not
+   * exist, and then gives up or buries the data in a free-text column. On READ
+   * it searches the parent, finds no address on it, and confidently answers
+   * "this contact has no address registered" — a falsehood, since the row is
+   * one filtered query away.
+   *
+   * Stated here rather than inferred at failure time on purpose: guessing the
+   * intended entity from rejected FIELD NAMES points "add an address to this
+   * contact" at the business-locations table, which declares the same columns.
+   */
+  agentHint?: string
+}
+
+export const CORE_QUERY_ENTITIES: CoreQueryEntity[] = [
+  {
+    key: 'address',
+    entity: addressEntity,
+    writable: true,
+    agentHint:
+      '`address` holds the street address of a PERSON (client, contact, supplier, staff). A person record has NO street/city/postal_code fields of its own. ' +
+      "To read where someone lives, search `address` with filters {\"owner_id\": <the person's id>} — a person with no address field is not a person without an address. " +
+      "To record one, create an `address` with owner_id set to the person's id. Never write an address into a notes field.",
+  },
+]

package/src/app/derive-contract.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest'
+import type { PluginManifest, RegisteredEntity } from '@fayz-ai/core'
+import { deriveAgentContract } from './derive-contract'
+import type { FayzAppConfig } from './config'
+
+// ---------------------------------------------------------------------------
+// Fixtures — a minimal app: one CRUD entity with a limitKey, one plugin with a
+// persist tool bound to an RPC, a registry, declared features/limits/rpcs.
+// Entities are passed explicitly so the test never touches the global registry.
+// ---------------------------------------------------------------------------
+
+const clientEntity: RegisteredEntity = {
+  entityKey: 'person:customer',
+  label: 'Cliente',
+  labelPlural: 'Clientes',
+  source: 'app',
+  fields: [],
+  entityDef: {
+    name: 'Cliente',
+    namePlural: 'Clientes',
+    icon: 'User',
+    limitKey: 'clients',
+    fields: [
+      { key: 'name', label: 'Nome', type: 'text', required: true, searchable: true },
+      { key: 'status', label: 'Status', type: 'select', options: [{ label: 'Ativo', value: 'active' }, { label: 'Inativo', value: 'inactive' }] },
+      { key: 'origin_id', label: 'Origem', type: 'relation', relation: { table: 'categories' } },
+    ],
+    data: {
+      table: 'clients',
+      tenantIdColumn: 'tenant_id',
+      archetype: 'person',
+      archetypeKind: 'customer',
+      searchColumns: ['name', 'email'],
+    },
+  },
+}
+
+const agendaPlugin = {
+  id: 'agenda',
+  name: 'Agenda',
+  version: '1.0.0',
+  scope: 'vertical',
+  routes: [],
+  aiTools: [
+    {
+      id: 'agenda.create-appointment',
+      name: 'createAppointment',
+      description: 'Creates a new appointment.',
+      mode: 'persist',
+      limitKey: 'bookings_month',
+      permission: { feature: 'appointments', action: 'create' },
+      execution: { plane: 'server', kind: 'rpc', rpc: 'agent_agenda_create_appointment' },
+    },
+  ],
+  declaredFeatures: [{ id: 'appointments', label: 'Appointments' }],
+  declaredLimits: [{ key: 'bookings_month', label: 'Appointments/mo', table: 'appointments', period: 'month' }],
+  declaredRpcs: [
+    { name: 'agent_agenda_create_appointment', kind: 'write', description: 'Guarded appointment create.', audits: true },
+  ],
+  registries: [
+    {
+      id: 'cancellation-reasons',
+      entity: {
+        name: 'Motivo de cancelamento',
+        namePlural: 'Motivos de cancelamento',
+        icon: 'X',
+        fields: [{ key: 'label', label: 'Label', type: 'text' }],
+        data: { table: 'appointment_cancellation_reasons' },
+      },
+    },
+  ],
+} as unknown as PluginManifest
+
+const config = {
+  name: 'Test App',
+  plugins: [agendaPlugin],
+  permissions: { features: [{ id: 'clients', label: 'Clientes' }] },
+  billing: {
+    plans: [],
+    limitDeclarations: [{ key: 'clients', label: 'Clients (app override)', table: 'clients', kindFilter: 'customer' }],
+  },
+  chat: { title: 'Assistente Glow', systemPrompt: 'You are the salon assistant.' },
+  agentContract: {
+    knowledge: { businessRules: [{ id: 'cancel-window', description: 'Cancelations need 2h notice.' }] },
+    rpcs: [{ name: 'agent_beauty_quote_service_price', kind: 'read', description: 'Price quote.' }],
+  },
+} as unknown as FayzAppConfig
+
+describe('deriveAgentContract', () => {
+  const { agent, limitDeclarations } = deriveAgentContract(config, [clientEntity])
+
+  it('projects registered entities with data mapping and fields (no closures)', () => {
+    const client = agent.entities?.find((e) => e.key === 'person:customer')
+    expect(client).toBeDefined()
+    expect(client?.limitKey).toBe('clients')
+    expect(client?.data).toMatchObject({ table: 'clients', tenantIdColumn: 'tenant_id', archetypeKind: 'customer' })
+    expect(client?.fields.find((f) => f.key === 'status')?.options).toEqual(['active', 'inactive'])
+    expect(client?.fields.find((f) => f.key === 'origin_id')?.relationTable).toBe('categories')
+    expect(JSON.parse(JSON.stringify(client))).toEqual(client)
+  })
+
+  it('projects plugin registries as entities + registry index', () => {
+    expect(agent.registries).toEqual([
+      { pluginId: 'agenda', id: 'cancellation-reasons', entityKey: 'agenda:cancellation-reasons' },
+    ])
+    expect(agent.entities?.some((e) => e.key === 'agenda:cancellation-reasons')).toBe(true)
+  })
+
+  it('derives the two data primitives covering entities + registries', () => {
+    const search = agent.tools?.find((t) => t.name === 'searchRecords')
+    const query = agent.tools?.find((t) => t.name === 'queryData')
+    expect(search?.execution).toEqual({ plane: 'server', kind: 'entity_read', entity: '*' })
+    expect(query?.execution).toEqual({ plane: 'server', kind: 'entity_read', entity: '*' })
+    // The closed target enum lists both the CRUD entity and the registry key.
+    const searchEnum = (search?.parameters?.properties?.entity as { enum?: string[] })?.enum ?? []
+    expect(searchEnum).toContain('person:customer')
+    expect(searchEnum).toContain('agenda:cancellation-reasons')
+    // No per-entity tool remains — the catalog is primitives + declared tools.
+    expect(agent.tools?.some((t) => t.id.startsWith('entity.'))).toBe(false)
+  })
+
+  it('keeps plugin-authored execution and defaults persist tools to confirmation', () => {
+    const create = agent.tools?.find((t) => t.id === 'agenda.create-appointment')
+    expect(create?.execution).toEqual({ plane: 'server', kind: 'rpc', rpc: 'agent_agenda_create_appointment' })
+    expect(create?.requiresConfirmation).toBe(true)
+    expect(create?.limitKey).toBe('bookings_month')
+    expect(create?.pluginId).toBe('agenda')
+  })
+
+  it('marks core tools client-plane', () => {
+    const nav = agent.tools?.find((t) => t.name === 'navigateTo')
+    expect(nav?.execution).toEqual({ plane: 'client' })
+  })
+
+  it('resolves the 4-layer limit merge with app override winning', () => {
+    const clients = limitDeclarations.find((d) => d.key === 'clients')
+    expect(clients?.label).toBe('Clients (app override)')
+    expect(limitDeclarations.some((d) => d.key === 'users')).toBe(true)
+    expect(limitDeclarations.some((d) => d.key === 'bookings_month')).toBe(true)
+  })
+
+  it('collects plugin + app rpcs and app knowledge + persona', () => {
+    expect(agent.rpcs?.map((r) => r.name)).toEqual([
+      'agent_agenda_create_appointment',
+      'agent_beauty_quote_service_price',
+    ])
+    expect(agent.persona).toEqual({ name: 'Assistente Glow', systemPrompt: 'You are the salon assistant.' })
+    expect(agent.domainKnowledge?.businessRules?.[0]?.id).toBe('cancel-window')
+    expect(agent.declaredFeatures?.map((f) => f.id).sort()).toEqual(['appointments', 'clients'])
+  })
+
+  it('produces a JSON-stable agent section (serializable end to end)', () => {
+    expect(JSON.parse(JSON.stringify(agent))).toEqual(agent)
+  })
+})