@fayz-ai/saas 0.1.6

package/src/org/store.ts

@@ -0,0 +1,70 @@
+import { create } from 'zustand'
+import { setActiveTenantId, type Organization, type OrgMember, type OrgMembership } from '@fayz-ai/core'
+
+const STORAGE_KEY = 'fayz:current-org'
+
+// ---------------------------------------------------------------------------
+// Persistence helpers
+// ---------------------------------------------------------------------------
+
+function getPersistedOrgId(): string | null {
+  try {
+    if (typeof localStorage === 'undefined') return null
+    return localStorage.getItem(STORAGE_KEY)
+  } catch {
+    return null
+  }
+}
+
+function persistOrgId(orgId: string | null): void {
+  try {
+    if (typeof localStorage === 'undefined') return
+    if (orgId) {
+      localStorage.setItem(STORAGE_KEY, orgId)
+    } else {
+      localStorage.removeItem(STORAGE_KEY)
+    }
+  } catch {
+    // ignore
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Store interface
+// ---------------------------------------------------------------------------
+
+export interface OrgStore {
+  currentOrg: Organization | null
+  userOrgs: OrgMembership[]
+  members: OrgMember[]
+  loading: boolean
+
+  setCurrentOrg: (org: Organization | null) => void
+  setUserOrgs: (orgs: OrgMembership[]) => void
+  setMembers: (members: OrgMember[]) => void
+  setLoading: (loading: boolean) => void
+  reset: () => void
+}
+
+export const useOrganizationStore = create<OrgStore>((set) => ({
+  currentOrg: null,
+  userOrgs: [],
+  members: [],
+  loading: false,
+
+  setCurrentOrg: (org) => {
+    setActiveTenantId(org?.id)
+    persistOrgId(org?.id ?? null)
+    set({ currentOrg: org })
+  },
+  setUserOrgs: (orgs) => set({ userOrgs: orgs }),
+  setMembers: (members) => set({ members }),
+  setLoading: (loading) => set({ loading }),
+  reset: () => {
+    setActiveTenantId(undefined)
+    persistOrgId(null)
+    set({ currentOrg: null, userOrgs: [], members: [], loading: false })
+  },
+}))
+
+export { getPersistedOrgId }

package/src/permissions/PermissionGate.tsx

@@ -0,0 +1,17 @@
+import * as React from 'react'
+import type { PermissionAction } from '@fayz-ai/core'
+import { usePermissionOptional } from './context'
+
+interface PermissionGateProps {
+  feature: string
+  action: PermissionAction
+  children: React.ReactNode
+  fallback?: React.ReactNode
+}
+
+/** Renders children only when the current user has the given feature+action. */
+export function PermissionGate({ feature, action, children, fallback }: PermissionGateProps) {
+  const can = usePermissionOptional()
+  if (!can(feature, action)) return <>{fallback ?? null}</>
+  return <>{children}</>
+}

package/src/permissions/context.tsx

@@ -0,0 +1,126 @@
+import * as React from 'react'
+import type { FeatureDeclaration, PermissionsConfig, PermissionProfile } 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
+
+  const actions = profile.grants[feature]
+  if (!actions) return false
+
+  if (!action) return actions.length > 0
+
+  return actions.includes(action) || actions.includes('manage')
+}
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+interface PermissionsContextValue {
+  hasPermission: (feature: string, action?: string) => boolean
+  canImpersonate: boolean
+  startImpersonation: (profile: PermissionProfile) => void
+  stopImpersonation: () => void
+}
+
+const PermissionsContext = React.createContext<PermissionsContextValue | null>(null)
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+export interface PermissionsProviderProps {
+  config?: PermissionsConfig
+  children: React.ReactNode
+}
+
+export function PermissionsProvider({ config, children }: PermissionsProviderProps) {
+  const { setFeatures, startImpersonation, stopImpersonation, currentProfile, isImpersonating } =
+    usePermissionsStore()
+
+  React.useEffect(() => {
+    if (config?.features) {
+      setFeatures(config.features)
+    }
+  }, [config, setFeatures])
+
+  function hasPermission(feature: string, action?: string): boolean {
+    return profileHasPermission(currentProfile, feature, action)
+  }
+
+  const value: PermissionsContextValue = {
+    hasPermission,
+    canImpersonate: !isImpersonating,
+    startImpersonation,
+    stopImpersonation,
+  }
+
+  return (
+    <PermissionsContext.Provider value={value}>
+      {children}
+    </PermissionsContext.Provider>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a function that checks whether the current user has a given
+ * permission. Throws if used outside <PermissionsProvider>.
+ */
+export function usePermission(): (feature: string, action?: string) => boolean {
+  const ctx = React.useContext(PermissionsContext)
+  if (!ctx) {
+    throw new Error('usePermission must be used inside <PermissionsProvider>')
+  }
+  return ctx.hasPermission
+}
+
+/**
+ * Like usePermission, but degrades to allow-all when no <PermissionsProvider>
+ * is mounted — so SDK components (e.g. the CRUD engine's PermissionGate) work
+ * under any host shell instead of throwing. Gating is an enhancement, not a
+ * hard requirement at the component level.
+ */
+export function usePermissionOptional(): (feature: string, action?: string) => boolean {
+  const ctx = React.useContext(PermissionsContext)
+  return ctx?.hasPermission ?? (() => true)
+}
+
+/**
+ * Convenience hook — returns true/false for a specific feature + action.
+ * Example: `const canEdit = useHasPermission('clients', 'write')`
+ */
+export function useHasPermission(feature: string, action?: string): boolean {
+  const ctx = React.useContext(PermissionsContext)
+  if (!ctx) {
+    throw new Error('useHasPermission must be used inside <PermissionsProvider>')
+  }
+  return ctx.hasPermission(feature, action)
+}
+
+/**
+ * Convenience hook that surfaces the full permissions context, including
+ * impersonation controls.
+ */
+export function usePermissions(): PermissionsContextValue {
+  const ctx = React.useContext(PermissionsContext)
+  if (!ctx) {
+    throw new Error('usePermissions must be used inside <PermissionsProvider>')
+  }
+  return ctx
+}
+
+// Re-export feature declarations for use in feature flag checks
+export type { FeatureDeclaration }

package/src/permissions/index.ts

@@ -0,0 +1,13 @@
+// Store
+export { usePermissionsStore } from './store'
+export type { PermissionsStore } from './store'
+
+// Context & hooks
+export {
+  PermissionsProvider,
+  usePermission,
+  usePermissionOptional,
+  useHasPermission,
+  usePermissions,
+} from './context'
+export type { PermissionsProviderProps, FeatureDeclaration } from './context'

package/src/permissions/store.ts

@@ -0,0 +1,68 @@
+import { create } from 'zustand'
+import type { FeatureDeclaration, PermissionProfile } from '@fayz-ai/core'
+
+// ---------------------------------------------------------------------------
+// Store interface
+// ---------------------------------------------------------------------------
+
+export interface PermissionsStore {
+  features: FeatureDeclaration[]
+  profiles: PermissionProfile[]
+  /** The effective profile used for permission checks (may be impersonated) */
+  currentProfile: PermissionProfile | null
+  /** The user's actual profile (preserved during impersonation) */
+  realProfile: PermissionProfile | null
+  /** The profile being previewed, if any */
+  impersonatedProfile: PermissionProfile | null
+  /** Whether impersonation is active */
+  isImpersonating: boolean
+
+  setFeatures: (features: FeatureDeclaration[]) => void
+  setProfiles: (profiles: PermissionProfile[]) => void
+  setCurrentProfile: (profile: PermissionProfile | null) => void
+  startImpersonation: (profile: PermissionProfile) => void
+  stopImpersonation: () => void
+  reset: () => void
+}
+
+export const usePermissionsStore = create<PermissionsStore>((set, get) => ({
+  features: [],
+  profiles: [],
+  currentProfile: null,
+  realProfile: null,
+  impersonatedProfile: null,
+  isImpersonating: false,
+
+  setFeatures: (features) => set({ features }),
+  setProfiles: (profiles) => set({ profiles }),
+  setCurrentProfile: (profile) =>
+    set({
+      currentProfile: profile,
+      realProfile: profile,
+      impersonatedProfile: null,
+      isImpersonating: false,
+    }),
+  startImpersonation: (profile) =>
+    set({
+      currentProfile: profile,
+      impersonatedProfile: profile,
+      isImpersonating: true,
+    }),
+  stopImpersonation: () => {
+    const { realProfile } = get()
+    set({
+      currentProfile: realProfile,
+      impersonatedProfile: null,
+      isImpersonating: false,
+    })
+  },
+  reset: () =>
+    set({
+      features: [],
+      profiles: [],
+      currentProfile: null,
+      realProfile: null,
+      impersonatedProfile: null,
+      isImpersonating: false,
+    }),
+}))

package/src/placeholder.ts

@@ -0,0 +1,32 @@
+import React from 'react'
+
+/**
+ * Page stub for modules that are planned but not built yet.
+ * Usage: { path: '/marketing', label: 'Marketing', icon: 'Megaphone', component: createPlaceholder('Marketing') }
+ */
+export function createPlaceholder(title: string, description?: string): React.FC {
+  return function PlaceholderPage() {
+    return React.createElement(
+      'div',
+      { className: 'mx-auto max-w-4xl' },
+      React.createElement('h1', { className: 'text-3xl font-bold text-foreground' }, title),
+      description
+        ? React.createElement('p', { className: 'mt-1 text-muted-foreground' }, description)
+        : null,
+      React.createElement(
+        'div',
+        { className: 'mt-8 flex items-center justify-center rounded-card border border-dashed border-border bg-card p-16' },
+        React.createElement(
+          'div',
+          { className: 'text-center' },
+          React.createElement('p', { className: 'text-lg font-medium text-muted-foreground' }, 'Coming Soon'),
+          React.createElement(
+            'p',
+            { className: 'mt-1 text-sm text-muted-foreground/70' },
+            'This module is being built as a plugin.',
+          ),
+        ),
+      ),
+    )
+  }
+}

package/src/plugins/ModuleActionBar.tsx

@@ -0,0 +1,57 @@
+import React from 'react'
+import { Settings } from 'lucide-react'
+import { Button } from '@fayz-ai/ui'
+import type { PluginQuickAction } from '@fayz-ai/core'
+import { QuickActionsButton } from './QuickActionsButton'
+
+/**
+ * ModuleActionBar — the single, standard top-right action area for every plugin
+ * module page. Pass it straight to `ModulePage`'s `headerAction` prop.
+ *
+ * Owns the two things every module's header repeated by hand:
+ *  - a primary "New" action (rendered via QuickActionsButton, which adapts its
+ *    variant to the layout: solid in `tabs` products, outline in `rail`),
+ *  - a settings gear that deep-links into the central Settings area.
+ *
+ * Plugins stop hand-rolling `<div className="flex gap-2">…gear…</div>` blocks:
+ *   headerAction={<ModuleActionBar quickActions={quickActions} settingsPath="/settings/crm" />}
+ */
+export function ModuleActionBar({
+  quickActions,
+  settingsPath,
+  settingsLabel,
+  leading,
+  trailing,
+}: {
+  /** Primary insert actions. Omit (or empty) to hide the New button. */
+  quickActions?: PluginQuickAction[]
+  /** Hash route to the central settings tab, e.g. '/settings/crm'. Omit to hide the gear. */
+  settingsPath?: string
+  /** Accessible title for the gear button. */
+  settingsLabel?: string
+  /** Optional extra controls rendered before the New button (e.g. a filter). */
+  leading?: React.ReactNode
+  /** Optional extra controls rendered after the gear. */
+  trailing?: React.ReactNode
+}) {
+  const hasQuickActions = !!quickActions && quickActions.length > 0
+  if (!hasQuickActions && !settingsPath && !leading && !trailing) return null
+
+  return (
+    <div className="flex items-center gap-2">
+      {leading}
+      {hasQuickActions && <QuickActionsButton actions={quickActions} />}
+      {settingsPath && (
+        <Button
+          variant="outline"
+          size="icon"
+          onClick={() => { window.location.hash = settingsPath }}
+          title={settingsLabel ?? 'Settings'}
+        >
+          <Settings className="h-4 w-4" />
+        </Button>
+      )}
+      {trailing}
+    </div>
+  )
+}

package/src/plugins/PluginRegistryManager.tsx

@@ -0,0 +1,110 @@
+import React, { useState, useMemo } from 'react'
+import type { PluginRegistryDef } from '@fayz-ai/core'
+import type { EntityDef } from '@fayz-ai/core'
+import { createCrudStore } from '../stores/createCrudStore'
+import { createMockProvider } from '@fayz-ai/core'
+import { CrudPage } from '../crud/CrudPage'
+import { cn } from '@fayz-ai/ui'
+import { ICON_MAP } from '@fayz-ai/ui'
+
+/**
+ * Internal CRUD view for a single registry.
+ * Manages its own store and uses a hash-based basePath for proper CRUD routing.
+ */
+function RegistryCrudView({ registry, basePath }: { registry: PluginRegistryDef; basePath: string }) {
+  const useStore = useMemo(() => {
+    const data = (registry.mockData ?? registry.seedData ?? []) as any[]
+    const provider = createMockProvider(registry.entity as EntityDef<any>, data)
+    return createCrudStore(provider)
+  }, [registry.id])
+
+  return (
+    <CrudPage
+      entityDef={registry.entity as EntityDef<any>}
+      useStore={useStore as any}
+      basePath={basePath}
+      display={registry.display === 'cards' ? 'cards' : 'table'}
+      readOnly={registry.readOnly}
+    />
+  )
+}
+
+/**
+ * Reusable tabbed CRUD manager for plugin registries.
+ * @param routeBase — hash route prefix for CRUD sub-routing (e.g. '/financial/settings')
+ */
+export function PluginRegistryManager({ registries, routeBase, className }: {
+  registries: PluginRegistryDef[]
+  /** Base route for CRUD navigation (e.g. '/financial/settings'). Each registry gets routeBase/registryId */
+  routeBase?: string
+  className?: string
+}) {
+  // Derive active tab from hash if routeBase provided, otherwise use state
+  const getTabFromHash = () => {
+    if (!routeBase) return registries[0]?.id ?? ''
+    const hash = window.location.hash.slice(1) || '/'
+    if (hash.startsWith(routeBase + '/')) {
+      const rest = hash.slice(routeBase.length + 1)
+      const tabId = rest.split('/')[0]
+      if (registries.find((r) => r.id === tabId)) return tabId
+    }
+    return registries[0]?.id ?? ''
+  }
+
+  const [activeTab, setActiveTab] = useState(getTabFromHash)
+
+  // Sync tab from hash changes
+  React.useEffect(() => {
+    if (!routeBase) return
+    const handler = () => setActiveTab(getTabFromHash())
+    window.addEventListener('hashchange', handler)
+    return () => window.removeEventListener('hashchange', handler)
+  }, [routeBase])
+
+  function switchTab(tabId: string) {
+    setActiveTab(tabId)
+    if (routeBase) {
+      window.location.hash = `${routeBase}/${tabId}`
+    }
+  }
+
+  if (registries.length === 0) return null
+
+  const activeRegistry = registries.find((r) => r.id === activeTab) ?? registries[0]
+  const crudBasePath = routeBase ? `${routeBase}/${activeRegistry.id}` : `/__registry/${activeRegistry.id}`
+
+  return (
+    <div className={cn('space-y-4', className)}>
+      {/* Tabs */}
+      <div className="flex gap-1 overflow-x-auto pb-1">
+        {registries.map((reg) => {
+          const Icon = reg.icon ? (ICON_MAP[reg.icon] ?? null) : null
+          const active = reg.id === activeTab
+          return (
+            <button
+              key={reg.id}
+              onClick={() => switchTab(reg.id)}
+              className={cn(
+                'flex items-center gap-1.5 whitespace-nowrap rounded-lg px-3 py-2 text-sm font-medium transition-colors shrink-0',
+                active
+                  ? 'bg-primary text-primary-foreground'
+                  : 'text-muted-foreground hover:text-foreground hover:bg-muted/50'
+              )}
+            >
+              {Icon && <Icon className="h-3.5 w-3.5" />}
+              {reg.entity.name}
+            </button>
+          )
+        })}
+      </div>
+
+      {/* Description */}
+      {activeRegistry?.description && (
+        <p className="text-xs text-muted-foreground">{activeRegistry.description}</p>
+      )}
+
+      {/* CRUD content — keyed so it remounts when switching tabs */}
+      {activeRegistry && <RegistryCrudView key={activeRegistry.id} registry={activeRegistry} basePath={crudBasePath} />}
+    </div>
+  )
+}

package/src/plugins/QuickActionsButton.tsx

@@ -0,0 +1,73 @@
+import React, { useState, useRef, useEffect } from 'react'
+import { Plus, X } from 'lucide-react'
+import { cn } from '@fayz-ai/ui'
+import { Button } from '@fayz-ai/ui'
+import { ICON_MAP } from '@fayz-ai/ui'
+import { useModuleLayout } from '@fayz-ai/ui'
+import type { PluginQuickAction } from '@fayz-ai/core'
+
+/**
+ * Quick actions button for plugin modules.
+ * Shows a "+" button that opens a popover with contextual insert actions.
+ * Reusable by any plugin.
+ */
+export function QuickActionsButton({ actions, className }: {
+  actions: PluginQuickAction[]
+  className?: string
+}) {
+  const [open, setOpen] = useState(false)
+  const ref = useRef<HTMLDivElement>(null)
+  // Solid primary in sidebar/tabs products (GHL-style), outline in topbar products.
+  const variant = useModuleLayout() === 'tabs' ? 'default' : 'outline'
+
+  useEffect(() => {
+    function handler(e: MouseEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false)
+    }
+    document.addEventListener('mousedown', handler)
+    return () => document.removeEventListener('mousedown', handler)
+  }, [])
+
+  if (actions.length === 0) return null
+
+  return (
+    <div ref={ref} className={cn('relative', className)}>
+      <Button
+        variant={variant}
+        size="sm"
+        onClick={() => setOpen(!open)}
+        className={cn(open && variant === 'outline' && 'bg-muted')}
+      >
+        <Plus className={cn('h-3.5 w-3.5 transition-transform duration-200', open && 'rotate-45')} />
+        <span>New</span>
+      </Button>
+
+      {open && (
+        <div className="fayz-glass-surface absolute top-full right-0 z-50 mt-2 w-64 rounded-xl border bg-popover shadow-lg overflow-hidden animate-in fade-in-0 zoom-in-95 origin-top-right">
+          <div className="p-1.5">
+            {actions.map((action) => {
+              const Icon = action.icon ? (ICON_MAP[action.icon] ?? Plus) : Plus
+              return (
+                <button
+                  key={action.id}
+                  onClick={() => { action.action(); setOpen(false) }}
+                  className="w-full flex items-center gap-3 rounded-lg px-3 py-2.5 text-left hover:bg-muted/50 transition-colors group"
+                >
+                  <div className="flex h-8 w-8 items-center justify-center rounded-lg bg-muted group-hover:bg-primary/10 transition-colors shrink-0">
+                    <Icon className="h-4 w-4 text-muted-foreground group-hover:text-primary transition-colors" />
+                  </div>
+                  <div className="min-w-0">
+                    <p className="text-sm font-medium">{action.label}</p>
+                    {action.description && (
+                      <p className="text-[10px] text-muted-foreground leading-tight">{action.description}</p>
+                    )}
+                  </div>
+                </button>
+              )
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/plugins/SettingsGroup.tsx

@@ -0,0 +1,100 @@
+import React from 'react'
+import { cn } from '@fayz-ai/ui'
+
+// ---------------------------------------------------------------------------
+// ToggleRow — a single setting with label, description, and checkbox
+// ---------------------------------------------------------------------------
+
+export function ToggleRow({ label, description, checked, onChange, disabled }: {
+  label: string
+  description?: string
+  checked: boolean
+  onChange: (checked: boolean) => void
+  disabled?: boolean
+}) {
+  return (
+    <label className={cn(
+      'flex items-center justify-between gap-4 py-3 cursor-pointer',
+      disabled && 'opacity-50 cursor-not-allowed',
+    )}>
+      <div className="min-w-0">
+        <p className="text-sm font-medium">{label}</p>
+        {description && <p className="text-xs text-muted-foreground mt-0.5">{description}</p>}
+      </div>
+      <button
+        type="button"
+        role="switch"
+        aria-checked={checked}
+        disabled={disabled}
+        onClick={() => !disabled && onChange(!checked)}
+        className={cn(
+          'relative inline-flex h-5 w-9 shrink-0 rounded-full transition-colors duration-200',
+          checked ? 'bg-primary' : 'bg-muted',
+          disabled && 'cursor-not-allowed',
+        )}
+      >
+        <span className={cn(
+          'inline-block h-4 w-4 rounded-full bg-white shadow-sm transition-transform duration-200 mt-0.5',
+          checked ? 'translate-x-4 ml-0.5' : 'translate-x-0.5',
+        )} />
+      </button>
+    </label>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// SelectRow — a single setting with label, description, and select dropdown
+// ---------------------------------------------------------------------------
+
+export function SelectRow({ label, description, value, options, onChange, disabled }: {
+  label: string
+  description?: string
+  value: string
+  options: { value: string; label: string }[]
+  onChange: (value: string) => void
+  disabled?: boolean
+}) {
+  return (
+    <label className={cn(
+      'flex items-center justify-between gap-4 py-3',
+      disabled && 'opacity-50 cursor-not-allowed',
+    )}>
+      <div className="min-w-0">
+        <p className="text-sm font-medium">{label}</p>
+        {description && <p className="text-xs text-muted-foreground mt-0.5">{description}</p>}
+      </div>
+      <select
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        disabled={disabled}
+        className="h-8 rounded-input border border-input  bg-card shadow-[inset_0_1px_0_rgb(0_0_0_/0.06)] px-2 text-sm"
+      >
+        {options.map((opt) => (
+          <option key={opt.value} value={opt.value}>{opt.label}</option>
+        ))}
+      </select>
+    </label>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// SettingsGroup — a bordered section with title and children
+// ---------------------------------------------------------------------------
+
+export function SettingsGroup({ title, description, children }: {
+  title: string
+  description?: string
+  children: React.ReactNode
+}) {
+  return (
+    <div>
+      <div className="px-1 pb-1 pt-4 first:pt-0">
+        <h3 className="text-sm font-semibold">{title}</h3>
+        {description && <p className="text-[10px] text-muted-foreground mt-0.5">{description}</p>}
+      </div>
+      <div className="rounded-lg border bg-card shadow-sm px-5 divide-y">
+        {children}
+      </div>
+    </div>
+  )
+}