@fayz-ai/saas 0.8.0 → 0.8.2

package/src/app/derive-contract.ts

@@ -0,0 +1,214 @@
+import type {
+  AgentContract,
+  AIToolContract,
+  EntityContract,
+  EntityDef,
+  FeatureDeclaration,
+  LimitDeclaration,
+  PluginAITool,
+  PluginManifest,
+  RegisteredEntity,
+} from '@fayz-ai/core'
+import { getAllEntities, deriveEntityKey } from '@fayz-ai/core'
+import { mergeLimitDeclarations } from '@fayz-ai/core/access'
+import { coreAITools, buildDataPrimitiveTools } from '../shell/lib/core-ai-tools'
+import { CORE_LIMIT_DECLARATIONS, entityDerivedLimitDeclarations } from './../access/limits-registry'
+import { CORE_QUERY_ENTITIES } from './core-entities'
+import type { FayzAppConfig } from './config'
+
+// ---------------------------------------------------------------------------
+// deriveAgentContract — FayzAppConfig → the manifest v3 `agent` section +
+// resolved `limitDeclarations`. This is the "capabilities are derived, never
+// configured" principle applied to the server side: everything the Fayz broker
+// needs to operate the app without a browser is PROJECTED from what the app
+// already declares (entities, plugins, permissions, billing), never re-typed.
+// Pure data out — safe to run at defineSaas time and in `fayz manifest emit`.
+// ---------------------------------------------------------------------------
+
+function projectEntity(key: string, label: string, labelPlural: string | undefined, def: EntityDef): EntityContract | null {
+  const data = def.data
+  if (!data?.table) return null
+  return {
+    key,
+    label,
+    ...(labelPlural ? { labelPlural } : {}),
+    ...(def.limitKey ? { limitKey: def.limitKey } : {}),
+    ...(def.permission ? { permission: def.permission } : {}),
+    data: {
+      table: data.table,
+      ...(data.schema ? { schema: data.schema } : {}),
+      ...(data.tenantScoped !== undefined ? { tenantScoped: data.tenantScoped } : {}),
+      ...(data.tenantIdColumn ? { tenantIdColumn: data.tenantIdColumn } : {}),
+      ...(data.searchColumns ? { searchColumns: data.searchColumns } : {}),
+      ...(data.selectColumns ? { selectColumns: data.selectColumns } : {}),
+      ...(data.columnMap ? { columnMap: data.columnMap } : {}),
+      ...(data.archetype ? { archetype: data.archetype } : {}),
+      ...(data.archetypeKind ? { archetypeKind: data.archetypeKind } : {}),
+      ...(data.filters ? { filters: data.filters } : {}),
+    },
+    fields: (def.fields ?? []).map((f) => ({
+      key: f.key,
+      label: f.label,
+      type: f.type,
+      ...(f.required ? { required: true } : {}),
+      ...(f.searchable ? { searchable: true } : {}),
+      // The hint is the only place a field says what it EXPECTS rather than
+      // what it is called — an owner id to look up, a default not to restate.
+      // Dropping it here is what left the agent guessing at write time.
+      ...(f.hint ? { hint: f.hint } : {}),
+      ...(Array.isArray(f.options) && f.options.length
+        ? { options: f.options.map((o) => (typeof o === 'string' ? o : o.value)) }
+        : {}),
+      ...(f.relation?.table ? { relationTable: f.relation.table } : {}),
+    })),
+  }
+}
+
+function projectTool(tool: PluginAITool, pluginId?: string): AIToolContract {
+  return {
+    id: tool.id,
+    name: tool.name,
+    description: tool.description,
+    mode: tool.mode,
+    ...(tool.parameters ? { parameters: tool.parameters } : {}),
+    ...(tool.permission ? { permission: tool.permission } : {}),
+    ...(tool.limitKey ? { limitKey: tool.limitKey } : {}),
+    ...(tool.execution ? { execution: tool.execution } : {}),
+    // Persist tools default to human confirmation — an agent never clicks a
+    // gated button, so the contract is where the guard is declared.
+    ...(tool.mode === 'persist' ? { requiresConfirmation: tool.requiresConfirmation ?? true } : {}),
+    ...(pluginId ? { pluginId } : {}),
+    ...(tool.category ? { category: tool.category } : {}),
+  }
+}
+
+/** Merge plugin-declared features with the app's own, app wins by id — the
+ *  same rule PermissionsProvider applies to the live matrix. */
+function mergeFeatureDeclarations(
+  plugins: PluginManifest[],
+  appFeatures: FeatureDeclaration[] | undefined,
+): FeatureDeclaration[] {
+  const byId = new Map<string, FeatureDeclaration>()
+  for (const plugin of plugins) {
+    for (const f of plugin.declaredFeatures ?? []) byId.set(f.id, f)
+  }
+  for (const f of appFeatures ?? []) byId.set(f.id, f)
+  return Array.from(byId.values())
+}
+
+export interface DerivedAgentSections {
+  agent: AgentContract
+  limitDeclarations: LimitDeclaration[]
+}
+
+export function deriveAgentContract(
+  config: FayzAppConfig,
+  entities: RegisteredEntity[] = getAllEntities(),
+): DerivedAgentSections {
+  const plugins = config.plugins ?? []
+
+  // --- Entities: registered CRUD entities + plugin registry entities --------
+  const entityContracts: EntityContract[] = []
+  for (const e of entities) {
+    if (!e.entityDef) continue
+    const projected = projectEntity(e.entityKey, e.label, e.labelPlural, e.entityDef)
+    if (projected) entityContracts.push(projected)
+  }
+  const registries: NonNullable<AgentContract['registries']> = []
+  for (const plugin of plugins) {
+    for (const registry of plugin.registries ?? []) {
+      const entityKey = `${plugin.id}:${registry.id}`
+      registries.push({
+        pluginId: plugin.id,
+        id: registry.id,
+        entityKey,
+        ...(registry.readOnly ? { readOnly: true } : {}),
+      })
+      const projected = projectEntity(
+        entityKey,
+        registry.entity.name,
+        registry.entity.namePlural,
+        registry.entity,
+      )
+      if (projected) entityContracts.push(projected)
+    }
+    for (const q of plugin.queryEntities ?? []) {
+      const projected = projectEntity(q.key, q.entity.name, q.entity.namePlural, q.entity)
+      if (projected) entityContracts.push(projected)
+    }
+  }
+  for (const q of config.agentContract?.queryEntities ?? []) {
+    const projected = projectEntity(q.key, q.entity.name, q.entity.namePlural, q.entity)
+    if (projected) entityContracts.push(projected)
+  }
+  // Spine tables whose surface is a detail TAB, not a page — no app declares
+  // them as CRUD entities, so without this the agent cannot see them at all.
+  for (const q of CORE_QUERY_ENTITIES) {
+    const projected = projectEntity(q.key, q.entity.name, q.entity.namePlural, q.entity)
+    if (projected) entityContracts.push(projected)
+  }
+
+  // --- Tools: core + derived reads + plugin-declared --------------------------
+  const tools: AIToolContract[] = []
+  // Core handlers run in the surface (org store / router) — client plane.
+  for (const tool of coreAITools) {
+    tools.push({ ...projectTool(tool), execution: { plane: 'client' } })
+  }
+  // The data primitives: one search + one aggregate over every entity/registry.
+  // `entity: '*'` = the target arrives as the call's `entity` argument; the
+  // executor resolves it against `agent.entities` and enforces that entity's
+  // own read permission.
+  const registryMap = new Map(plugins.map((p) => [p.id, p.registries ?? []]))
+  const queryEntities = [
+    ...plugins.flatMap((p) => p.queryEntities ?? []),
+    ...(config.agentContract?.queryEntities ?? []),
+    // CORE_QUERY_ENTITIES is NOT listed here — buildDataPrimitiveTools merges
+    // it in itself, for every caller. It is projected into `entityContracts`
+    // above because that list is what the server-plane executor resolves a
+    // tool call's `entity` argument against.
+  ]
+  for (const tool of buildDataPrimitiveTools({ entities, registries: registryMap, queryEntities })) {
+    tools.push({ ...projectTool(tool), execution: { plane: 'server', kind: 'entity_read', entity: '*' } })
+  }
+  // Plugin-authored tools keep their declared execution (persist tools bind to
+  // RPCs via `execution: { kind:'rpc' }`; absent ⇒ client-plane executor).
+  for (const plugin of plugins) {
+    for (const tool of plugin.aiTools ?? []) {
+      tools.push(projectTool(tool, plugin.id))
+    }
+  }
+
+  // --- Limits: the same 4-layer merge the AccessProvider publishes ----------
+  const limitDeclarations = mergeLimitDeclarations(
+    CORE_LIMIT_DECLARATIONS,
+    entityDerivedLimitDeclarations(entities),
+    plugins.flatMap((p) => p.declaredLimits ?? []),
+    config.billing?.limitDeclarations,
+  )
+
+  // --- RPCs: plugin-shipped + app-shipped ------------------------------------
+  const rpcs = [
+    ...plugins.flatMap((p) => p.declaredRpcs ?? []),
+    ...(config.agentContract?.rpcs ?? []),
+  ]
+
+  const agent: AgentContract = {
+    ...(config.chat?.title || config.chat?.systemPrompt
+      ? {
+          persona: {
+            ...(config.chat.title ? { name: config.chat.title } : {}),
+            ...(config.chat.systemPrompt ? { systemPrompt: config.chat.systemPrompt } : {}),
+          },
+        }
+      : {}),
+    executionPlane: config.agentContract?.executionPlane ?? 'client',
+    entities: entityContracts,
+    tools,
+    ...(registries.length ? { registries } : {}),
+    declaredFeatures: mergeFeatureDeclarations(plugins, config.permissions?.features),
+    ...(rpcs.length ? { rpcs } : {}),
+    ...(config.agentContract?.knowledge ? { domainKnowledge: config.agentContract.knowledge } : {}),
+  }
+
+  return { agent, limitDeclarations }
+}

package/src/app/scaffold.tsx

@@ -14,6 +14,7 @@ import type {
 } from '@fayz-ai/core'
 import { AdminProviders, getAuthShellProps } from './admin-app'
 import { AdminShell } from './AdminShell'
+import { deriveAgentContract } from './derive-contract'
 import type { FayzAppConfig, CustomPage } from './config'
 
 // ---------------------------------------------------------------------------
@@ -49,6 +50,7 @@ export function defineSaas(config: FayzAppConfig): AppManifest {
   const id = slug(config.name)
   const configRef = getLiveConfigRef(id)
   liveSaasConfigs.set(configRef, config)
+  const { agent, limitDeclarations } = deriveAgentContract(config)
   return defineApp({
     id,
     name: config.name,
@@ -59,6 +61,8 @@ export function defineSaas(config: FayzAppConfig): AppManifest {
     theme: config.theme as Record<string, unknown> | undefined,
     permissions: config.permissions,
     billing: config.billing as ManifestBillingConfig | undefined,
+    limitDeclarations,
+    agent,
     surfaces: {
       admin: {
         scaffold: 'admin',

package/src/archetype-lookup.ts

@@ -107,10 +107,13 @@ export function createArchetypeLookup(config: ArchetypeLookupConfig): EntityLook
       let qb = supabase
         .from(display.table)
         .select('*')
-        .eq('is_active', true)
         .order(display.labelField, { ascending: true })
         .limit(limit)
 
+      qb = config.archetype === 'service'
+        ? qb.or('is_active.eq.true,is_active.is.null')
+        : qb.eq('is_active', true)
+
       if (query) qb = qb.ilike(display.labelField, `%${query}%`)
       qb = applyKindFilter(qb)
 
@@ -127,10 +130,13 @@ export function createArchetypeLookup(config: ArchetypeLookupConfig): EntityLook
       let qb = supabase
         .from(display.table)
         .select('*')
-        .eq('is_active', true)
         .order(display.labelField, { ascending: true })
         .limit(limit)
 
+      qb = config.archetype === 'service'
+        ? qb.or('is_active.eq.true,is_active.is.null')
+        : qb.eq('is_active', true)
+
       qb = applyKindFilter(qb)
 
       const { data } = await qb

package/src/billing/index.ts

@@ -5,3 +5,5 @@ export type {
   Subscription,
   Invoice,
 } from './store'
+export { resolvePlanBadge } from './plan-badge'
+export type { PlanBadgeInfo } from './plan-badge'

package/src/billing/plan-badge.ts

@@ -0,0 +1,32 @@
+import type { Plan } from '@fayz-ai/core'
+
+export interface PlanBadgeInfo {
+  /** Display label, e.g. 'Free' or 'Pro'. */
+  label: string
+  /** Resolved plan id (falls back to the raw org.plan string). */
+  planId: string
+  /** Paid plan (price > 0) — drives the Crown icon + gold styling in the menus. */
+  paid: boolean
+}
+
+function capitalize(s: string): string {
+  return s ? s.charAt(0).toUpperCase() + s.slice(1) : s
+}
+
+/**
+ * Resolve an org's `plan` string against the configured billing plans into the
+ * badge shown next to the user in both menus. Falls back to a capitalized
+ * version of the raw string when the id isn't in config (defensive — e.g. a
+ * legacy 'free' tenant before billing was wired).
+ */
+export function resolvePlanBadge(
+  planId: string | undefined | null,
+  plans: Plan[],
+): PlanBadgeInfo {
+  const id = planId || 'free'
+  const match = plans.find((p) => p.id === id)
+  if (match) {
+    return { label: match.name, planId: match.id, paid: match.price > 0 }
+  }
+  return { label: capitalize(id), planId: id, paid: false }
+}

package/src/billing/store.ts

@@ -1,5 +1,5 @@
 import { create } from 'zustand'
-import type { Plan } from '@fayz-ai/core'
+import type { Plan, BillingCheckoutFn } from '@fayz-ai/core'
 
 // ---------------------------------------------------------------------------
 // Types
@@ -31,6 +31,10 @@ export interface BillingState {
   invoices: Invoice[]
   plans: Plan[]
   loading: boolean
+  /** Payment-gateway seam seeded from `config.billing.onCheckout` (see core
+   *  BillingConfig). When set, the Subscription page routes plan changes through
+   *  it instead of writing `plan` straight onto the org. */
+  checkout: BillingCheckoutFn | null
 }
 
 // ---------------------------------------------------------------------------
@@ -42,6 +46,7 @@ export interface BillingStore extends BillingState {
   setInvoices: (invoices: Invoice[]) => void
   setPlans: (plans: Plan[]) => void
   setLoading: (loading: boolean) => void
+  setCheckout: (checkout: BillingCheckoutFn | null) => void
   reset: () => void
 }
 
@@ -50,6 +55,7 @@ const initialState: BillingState = {
   invoices: [],
   plans: [],
   loading: false,
+  checkout: null,
 }
 
 export const useBillingStore = create<BillingStore>((set) => ({
@@ -58,5 +64,6 @@ export const useBillingStore = create<BillingStore>((set) => ({
   setInvoices: (invoices) => set({ invoices }),
   setPlans: (plans) => set({ plans }),
   setLoading: (loading) => set({ loading }),
+  setCheckout: (checkout) => set({ checkout }),
   reset: () => set(initialState),
 }))