@fayz-ai/plugin-financial 0.1.1

package/src/migrations/005_seed_defaults.sql

@@ -0,0 +1,38 @@
+-- Financial plugin — seed: payment method types + card brands.
+-- These are the read-only "system" registries the plugin's UI assumes exist
+-- (PaymentModal, card selection). They live as registry seedData in TS but were
+-- never written to the DB, so a fresh tenant had none. This backfills them for
+-- every tenant that has none. Idempotent. Plugin-owned so every app gets them.
+
+DO $$
+DECLARE t_id uuid;
+BEGIN
+  FOR t_id IN (
+    SELECT id FROM saas_core.tenants
+    WHERE id NOT IN (SELECT DISTINCT tenant_id FROM public.payment_method_types)
+  )
+  LOOP
+    INSERT INTO public.payment_method_types (tenant_id, name, transaction_type) VALUES
+      (t_id, 'Cash', 'cash'),
+      (t_id, 'PIX', 'pix'),
+      (t_id, 'Credit Card', 'credit_card'),
+      (t_id, 'Debit Card', 'debit_card'),
+      (t_id, 'Bank Transfer', 'bank_transfer'),
+      (t_id, 'Check', 'check');
+  END LOOP;
+END $$;
+
+DO $$
+DECLARE t_id uuid;
+BEGIN
+  FOR t_id IN (
+    SELECT id FROM saas_core.tenants
+    WHERE id NOT IN (SELECT DISTINCT tenant_id FROM public.card_brands)
+  )
+  LOOP
+    INSERT INTO public.card_brands (tenant_id, name) VALUES
+      (t_id, 'Visa'), (t_id, 'Mastercard'), (t_id, 'American Express'),
+      (t_id, 'Elo'), (t_id, 'Hipercard'), (t_id, 'Diners Club'),
+      (t_id, 'Discover'), (t_id, 'JCB'), (t_id, 'Aura'), (t_id, 'Hiper');
+  END LOOP;
+END $$;

package/src/registries.ts

@@ -0,0 +1,305 @@
+import type { PluginRegistryDef } from '@fayz-ai/core'
+import type { EntityDef } from '@fayz-ai/core'
+
+// ---------------------------------------------------------------------------
+// Payment Method Types (seeded — Cash, PIX, Credit Card, etc.)
+// ---------------------------------------------------------------------------
+
+const paymentMethodTypeEntity: EntityDef = {
+  name: 'Payment Type',
+  namePlural: 'Payment Types',
+  icon: 'CreditCard',
+  displayField: 'name',
+  defaultSort: 'name',
+  fields: [
+    { key: 'name', label: 'Name', type: 'text', required: true, showInTable: true },
+    { key: 'transactionType', label: 'Transaction Type', type: 'select', options: ['cash', 'credit_card', 'debit_card', 'pix', 'bank_transfer', 'check', 'voucher'], showInTable: true, required: true },
+    { key: 'isActive', label: 'Active', type: 'boolean', showInTable: true, defaultValue: true },
+  ],
+  data: { table: 'payment_method_types', tenantScoped: true },
+}
+
+// ---------------------------------------------------------------------------
+// Payment Methods (user-created — e.g. "Visa 2x", "PIX Store")
+// ---------------------------------------------------------------------------
+
+const paymentMethodEntity: EntityDef = {
+  name: 'Payment Method',
+  namePlural: 'Payment Methods',
+  icon: 'CreditCard',
+  displayField: 'name',
+  defaultSort: 'name',
+  fields: [
+    { key: 'name', label: 'Name', type: 'text', required: true, showInTable: true },
+    { key: 'paymentMethodTypeId', label: 'Type', type: 'select', options: ['cash', 'credit_card', 'debit_card', 'pix', 'bank_transfer', 'check'], showInTable: true, required: true },
+    { key: 'discountValue', label: 'Discount %', type: 'number', showInTable: true },
+    { key: 'interestValue', label: 'Interest %', type: 'number', showInTable: true },
+    { key: 'minInstallments', label: 'Min Installments', type: 'number', defaultValue: 1 },
+    { key: 'maxInstallments', label: 'Max Installments', type: 'number', defaultValue: 1, showInTable: true },
+    { key: 'isActive', label: 'Active', type: 'boolean', showInTable: true, defaultValue: true },
+  ],
+  data: { table: 'payment_methods', tenantScoped: true },
+}
+
+// ---------------------------------------------------------------------------
+// Chart of Accounts (tree structure)
+// ---------------------------------------------------------------------------
+
+const chartOfAccountsEntity: EntityDef = {
+  name: 'Ledger Account',
+  namePlural: 'Chart of Accounts',
+  icon: 'BookOpen',
+  displayField: 'name',
+  defaultSort: 'code',
+  fields: [
+    { key: 'code', label: 'Code', type: 'text', required: true, showInTable: true },
+    { key: 'name', label: 'Name', type: 'text', required: true, showInTable: true },
+    { key: 'nodeType', label: 'Type', type: 'select', options: ['group', 'leaf'], showInTable: true, required: true, defaultValue: 'leaf' },
+    { key: 'parentId', label: 'Parent', type: 'text', showInTable: false },
+    { key: 'isActive', label: 'Active', type: 'boolean', showInTable: true, defaultValue: true },
+  ],
+  data: { table: 'chart_of_accounts', tenantScoped: true },
+}
+
+// ---------------------------------------------------------------------------
+// Cost Centers
+// ---------------------------------------------------------------------------
+
+const costCenterEntity: EntityDef = {
+  name: 'Cost Center',
+  namePlural: 'Cost Centers',
+  icon: 'Target',
+  displayField: 'name',
+  defaultSort: 'code',
+  fields: [
+    { key: 'code', label: 'Code', type: 'text', required: true, showInTable: true },
+    { key: 'name', label: 'Name', type: 'text', required: true, showInTable: true },
+    { key: 'isActive', label: 'Active', type: 'boolean', showInTable: true, defaultValue: true },
+  ],
+  data: { table: 'cost_centers', tenantScoped: true },
+}
+
+// ---------------------------------------------------------------------------
+// Bank Accounts (physical cash, bank, credit card, digital wallet)
+// ---------------------------------------------------------------------------
+
+const bankAccountEntity: EntityDef = {
+  name: 'Bank Account',
+  namePlural: 'Bank Accounts',
+  icon: 'Landmark',
+  displayField: 'name',
+  defaultSort: 'name',
+  fields: [
+    { key: 'name', label: 'Name', type: 'text', required: true, showInTable: true },
+    { key: 'accountType', label: 'Type', type: 'select', options: [
+      { label: 'Bank Account', value: 'bank_account' },
+      { label: 'Cash Register', value: 'cash_register' },
+      { label: 'Credit Card', value: 'credit_card' },
+      { label: 'Digital Wallet', value: 'digital_wallet' },
+    ], showInTable: true, required: true },
+    { key: 'bankName', label: 'Bank', type: 'text', showInTable: true },
+    { key: 'accountNumber', label: 'Account Number', type: 'text' },
+    { key: 'agencyNumber', label: 'Agency', type: 'text' },
+    { key: 'initialBalance', label: 'Initial Balance', type: 'currency', defaultValue: 0 },
+    { key: 'creditLimit', label: 'Credit Limit', type: 'currency' },
+    { key: 'closingDay', label: 'Closing Day', type: 'number' },
+    { key: 'dueDay', label: 'Due Day', type: 'number' },
+    { key: 'isActive', label: 'Active', type: 'boolean', showInTable: true, defaultValue: true },
+  ],
+  data: { table: 'bank_accounts', tenantScoped: true },
+}
+
+// ---------------------------------------------------------------------------
+// Card Brands (seeded)
+// ---------------------------------------------------------------------------
+
+const cardBrandEntity: EntityDef = {
+  name: 'Card Brand',
+  namePlural: 'Card Brands',
+  icon: 'CreditCard',
+  displayField: 'name',
+  defaultSort: 'name',
+  fields: [
+    { key: 'name', label: 'Name', type: 'text', required: true, showInTable: true },
+    { key: 'isActive', label: 'Active', type: 'boolean', showInTable: true, defaultValue: true },
+  ],
+  data: { table: 'card_brands', tenantScoped: true },
+}
+
+// ---------------------------------------------------------------------------
+// Commission Rules
+// ---------------------------------------------------------------------------
+
+const commissionRuleEntity: EntityDef = {
+  name: 'Commission Rule',
+  namePlural: 'Commission Rules',
+  icon: 'TrendingUp',
+  displayField: 'name',
+  defaultSort: 'priority',
+  defaultSortDir: 'desc',
+  fields: [
+    { key: 'name', label: 'Name', type: 'text', required: true, showInTable: true },
+    { key: 'priority', label: 'Priority', type: 'number', required: true, showInTable: true, defaultValue: 1 },
+    { key: 'valueType', label: 'Type', type: 'select', options: ['percentage', 'fixed'], required: true, showInTable: true, defaultValue: 'percentage' },
+    { key: 'value', label: 'Value', type: 'number', required: true, showInTable: true },
+    { key: 'description', label: 'Description', type: 'textarea' },
+    { key: 'isActive', label: 'Active', type: 'boolean', showInTable: true, defaultValue: true },
+  ],
+  data: { table: 'commission_rules', tenantScoped: true },
+}
+
+// ---------------------------------------------------------------------------
+// Price Tables
+// ---------------------------------------------------------------------------
+
+const priceTableEntity: EntityDef = {
+  name: 'Price Table',
+  namePlural: 'Price Tables',
+  icon: 'Tag',
+  displayField: 'description',
+  defaultSort: 'createdAt',
+  defaultSortDir: 'desc',
+  fields: [
+    { key: 'description', label: 'Description', type: 'text', required: true, showInTable: true },
+    { key: 'type', label: 'Type', type: 'select', options: ['sale', 'cost'], required: true, showInTable: true, defaultValue: 'sale' },
+    { key: 'validFrom', label: 'Valid From', type: 'date', showInTable: true },
+    { key: 'validUntil', label: 'Valid Until', type: 'date', showInTable: true },
+    { key: 'isActive', label: 'Active', type: 'boolean', showInTable: true, defaultValue: true },
+  ],
+  data: { table: 'price_tables', tenantScoped: true },
+}
+
+// ---------------------------------------------------------------------------
+// Price Variations
+// ---------------------------------------------------------------------------
+
+const priceVariationEntity: EntityDef = {
+  name: 'Price Variation',
+  namePlural: 'Price Variations',
+  icon: 'Percent',
+  displayField: 'name',
+  defaultSort: 'createdAt',
+  defaultSortDir: 'desc',
+  fields: [
+    { key: 'name', label: 'Name', type: 'text', required: true, showInTable: true },
+    { key: 'variationType', label: 'Type', type: 'select', options: ['discount', 'increase'], required: true, showInTable: true },
+    { key: 'valueType', label: 'Value Type', type: 'select', options: ['percentage', 'fixed'], required: true, showInTable: true },
+    { key: 'value', label: 'Value', type: 'number', required: true, showInTable: true },
+    { key: 'firstAppointmentOnly', label: 'First Appointment Only', type: 'boolean', defaultValue: false },
+    { key: 'isActive', label: 'Active', type: 'boolean', showInTable: true, defaultValue: true },
+  ],
+  data: { table: 'price_variations', tenantScoped: true },
+}
+
+// ---------------------------------------------------------------------------
+// Export all registries
+// ---------------------------------------------------------------------------
+
+export const financialRegistries: PluginRegistryDef[] = [
+  // --- Editable registries (user manages) ---
+  {
+    id: 'payment-methods',
+    entity: paymentMethodEntity,
+    icon: 'Wallet',
+    description: 'Configured payment methods with fees and installment rules',
+    display: 'table',
+  },
+  {
+    id: 'chart-of-accounts',
+    entity: chartOfAccountsEntity,
+    icon: 'BookOpen',
+    description: 'Hierarchical chart of accounts for categorizing transactions',
+    display: 'tree',
+    seedData: [
+      { id: 'coa-1', code: '1', name: 'Revenue', nodeType: 'group', isActive: true },
+      { id: 'coa-1.1', code: '1.1', name: 'Sales Revenue', nodeType: 'group', parentId: 'coa-1', isActive: true },
+      { id: 'coa-1.1.01', code: '1.1.01', name: 'Services', nodeType: 'leaf', parentId: 'coa-1.1', isActive: true },
+      { id: 'coa-1.1.02', code: '1.1.02', name: 'Products', nodeType: 'leaf', parentId: 'coa-1.1', isActive: true },
+      { id: 'coa-2', code: '2', name: 'Other Revenue', nodeType: 'group', isActive: true },
+      { id: 'coa-2.1', code: '2.1', name: 'Financial Income', nodeType: 'leaf', parentId: 'coa-2', isActive: true },
+      { id: 'coa-3', code: '3', name: 'Operational Costs', nodeType: 'group', isActive: true },
+      { id: 'coa-3.1', code: '3.1', name: 'Materials & Supplies', nodeType: 'group', parentId: 'coa-3', isActive: true },
+      { id: 'coa-3.1.01', code: '3.1.01', name: 'Raw Materials', nodeType: 'leaf', parentId: 'coa-3.1', isActive: true },
+      { id: 'coa-3.1.02', code: '3.1.02', name: 'Consumables', nodeType: 'leaf', parentId: 'coa-3.1', isActive: true },
+      { id: 'coa-4', code: '4', name: 'Expenses', nodeType: 'group', isActive: true },
+      { id: 'coa-4.1', code: '4.1', name: 'Rent', nodeType: 'leaf', parentId: 'coa-4', isActive: true },
+      { id: 'coa-4.2', code: '4.2', name: 'Utilities', nodeType: 'leaf', parentId: 'coa-4', isActive: true },
+      { id: 'coa-4.3', code: '4.3', name: 'Payroll', nodeType: 'leaf', parentId: 'coa-4', isActive: true },
+    ],
+  },
+  {
+    id: 'cost-centers',
+    entity: costCenterEntity,
+    icon: 'Target',
+    description: 'Cost centers for expense tracking and departmental budgets',
+    display: 'table',
+    seedData: [
+      { id: 'cc-001', code: '001', name: 'General', isActive: true },
+    ],
+  },
+  {
+    id: 'bank-accounts',
+    entity: bankAccountEntity,
+    icon: 'Landmark',
+    description: 'Bank accounts, cash registers, credit cards, and digital wallets',
+    display: 'table',
+  },
+  {
+    id: 'commission-rules',
+    entity: commissionRuleEntity,
+    icon: 'TrendingUp',
+    description: 'Commission rules for service and product revenue sharing',
+    display: 'table',
+  },
+  {
+    id: 'price-tables',
+    entity: priceTableEntity,
+    icon: 'Tag',
+    description: 'Price tables for sale and cost pricing',
+    display: 'table',
+  },
+  {
+    id: 'price-variations',
+    entity: priceVariationEntity,
+    icon: 'Percent',
+    description: 'Discount and surcharge rules for pricing',
+    display: 'table',
+  },
+  // --- Read-only registries (system / seeded data) ---
+  {
+    id: 'payment-method-types',
+    entity: paymentMethodTypeEntity,
+    icon: 'CreditCard',
+    description: 'System payment types (cash, card, PIX, etc.)',
+    display: 'table',
+    readOnly: true,
+    seedData: [
+      { id: 'pmt-cash', name: 'Cash', transactionType: 'cash', isActive: true },
+      { id: 'pmt-pix', name: 'PIX', transactionType: 'pix', isActive: true },
+      { id: 'pmt-credit', name: 'Credit Card', transactionType: 'credit_card', isActive: true },
+      { id: 'pmt-debit', name: 'Debit Card', transactionType: 'debit_card', isActive: true },
+      { id: 'pmt-transfer', name: 'Bank Transfer', transactionType: 'bank_transfer', isActive: true },
+      { id: 'pmt-check', name: 'Check', transactionType: 'check', isActive: true },
+    ],
+  },
+  {
+    id: 'card-brands',
+    entity: cardBrandEntity,
+    icon: 'CreditCard',
+    description: 'Credit and debit card brands',
+    display: 'table',
+    readOnly: true,
+    seedData: [
+      { id: 'cb-visa', name: 'Visa', isActive: true },
+      { id: 'cb-mastercard', name: 'Mastercard', isActive: true },
+      { id: 'cb-amex', name: 'American Express', isActive: true },
+      { id: 'cb-elo', name: 'Elo', isActive: true },
+      { id: 'cb-hipercard', name: 'Hipercard', isActive: true },
+      { id: 'cb-diners', name: 'Diners Club', isActive: true },
+      { id: 'cb-discover', name: 'Discover', isActive: true },
+      { id: 'cb-jcb', name: 'JCB', isActive: true },
+      { id: 'cb-aura', name: 'Aura', isActive: true },
+      { id: 'cb-hiper', name: 'Hiper', isActive: true },
+    ],
+  },
+]

package/src/store.ts

@@ -0,0 +1,221 @@
+import { createStore, type StoreApi } from 'zustand/vanilla'
+import { dedup } from '@fayz-ai/saas'
+import { toast } from '@fayz-ai/ui'
+import type { FinancialDataProvider } from './data/types'
+import type {
+  Invoice, FinancialMovement, BankAccount, CashSession,
+  PaymentMethod, PaymentMethodType, CardTransaction,
+  FinancialSummary, StatementEntry,
+  InvoiceQuery, MovementQuery, StatementQuery,
+  CreateInvoiceInput, PayMovementInput,
+  OpenCashSessionInput, CloseCashSessionInput,
+  DateRange,
+} from './types'
+
+// ---------------------------------------------------------------------------
+// Store state
+// ---------------------------------------------------------------------------
+
+export interface FinancialUIState {
+  // Data cache
+  invoices: Invoice[]
+  invoicesTotal: number
+  invoicesLoading: boolean
+  invoiceQuery: InvoiceQuery
+
+  movements: FinancialMovement[]
+  movementsTotal: number
+  movementsLoading: boolean
+
+  bankAccounts: BankAccount[]
+  bankAccountsLoading: boolean
+
+  cashSessions: CashSession[]
+  cashSessionsLoading: boolean
+
+  paymentMethods: PaymentMethod[]
+  paymentMethodTypes: PaymentMethodType[]
+
+  summary: FinancialSummary | null
+  summaryLoading: boolean
+
+  statementEntries: StatementEntry[]
+  statementLoading: boolean
+
+  cardTransactions: CardTransaction[]
+  cardsLoading: boolean
+
+  // Actions
+  fetchSummary(dateRange?: DateRange): Promise<void>
+  fetchInvoices(query: InvoiceQuery): Promise<void>
+  fetchBankAccounts(): Promise<void>
+  fetchCashSessions(bankAccountId?: string): Promise<void>
+  fetchPaymentMethods(): Promise<void>
+  fetchStatement(query: StatementQuery): Promise<void>
+  fetchCardTransactions(dateRange?: DateRange): Promise<void>
+  createInvoice(input: CreateInvoiceInput): Promise<Invoice>
+  payMovement(input: PayMovementInput): Promise<void>
+  cancelInvoice(invoiceId: string): Promise<void>
+  openCashSession(input: OpenCashSessionInput): Promise<CashSession>
+  closeCashSession(input: CloseCashSessionInput): Promise<CashSession>
+}
+
+// ---------------------------------------------------------------------------
+// Store factory
+// ---------------------------------------------------------------------------
+
+export function createFinancialStore(provider: FinancialDataProvider): StoreApi<FinancialUIState> {
+  return createStore<FinancialUIState>((set, get) => ({
+    invoices: [],
+    invoicesTotal: 0,
+    invoicesLoading: false,
+    invoiceQuery: {},
+
+    movements: [],
+    movementsTotal: 0,
+    movementsLoading: false,
+
+    bankAccounts: [],
+    bankAccountsLoading: false,
+
+    cashSessions: [],
+    cashSessionsLoading: false,
+
+    paymentMethods: [],
+    paymentMethodTypes: [],
+
+    summary: null,
+    summaryLoading: false,
+
+    statementEntries: [],
+    statementLoading: false,
+
+    cardTransactions: [],
+    cardsLoading: false,
+
+    async fetchSummary(dateRange) {
+      return dedup('fin:summary', async () => {
+        set({ summaryLoading: true })
+        const summary = await provider.getSummary(dateRange)
+        set({ summary, summaryLoading: false })
+      })
+    },
+
+    async fetchInvoices(query) {
+      return dedup('fin:invoices:' + JSON.stringify(query), async () => {
+        set({ invoicesLoading: true, invoiceQuery: query })
+        const result = await provider.getInvoices(query)
+        set({ invoices: result.data, invoicesTotal: result.total, invoicesLoading: false })
+      })
+    },
+
+    async fetchBankAccounts() {
+      return dedup('fin:bankAccounts', async () => {
+        set({ bankAccountsLoading: true })
+        const bankAccounts = await provider.getBankAccounts()
+        set({ bankAccounts, bankAccountsLoading: false })
+      })
+    },
+
+    async fetchCashSessions(bankAccountId) {
+      return dedup('fin:cashSessions:' + (bankAccountId ?? ''), async () => {
+        set({ cashSessionsLoading: true })
+        const cashSessions = await provider.getCashSessions(bankAccountId)
+        set({ cashSessions, cashSessionsLoading: false })
+      })
+    },
+
+    async fetchPaymentMethods() {
+      return dedup('fin:paymentMethods', async () => {
+        const [paymentMethods, paymentMethodTypes] = await Promise.all([
+          provider.getPaymentMethods(),
+          provider.getPaymentMethodTypes(),
+        ])
+        set({ paymentMethods, paymentMethodTypes })
+      })
+    },
+
+    async fetchStatement(query) {
+      return dedup('fin:statement:' + JSON.stringify(query), async () => {
+        set({ statementLoading: true })
+        const statementEntries = await provider.getStatement(query)
+        set({ statementEntries, statementLoading: false })
+      })
+    },
+
+    async fetchCardTransactions(dateRange) {
+      return dedup('fin:cards', async () => {
+        set({ cardsLoading: true })
+        const cardTransactions = await provider.getCardTransactions(dateRange)
+        set({ cardTransactions, cardsLoading: false })
+      })
+    },
+
+    async createInvoice(input) {
+      try {
+        const invoice = await provider.createInvoice(input)
+        const query = get().invoiceQuery
+        const result = await provider.getInvoices(query)
+        const summary = await provider.getSummary()
+        set({ invoices: result.data, invoicesTotal: result.total, summary })
+        toast.success('Invoice created')
+        return invoice
+      } catch (err: any) {
+        toast.error('Failed to create invoice', { description: err?.message })
+        throw err
+      }
+    },
+
+    async payMovement(input) {
+      try {
+        await provider.payMovement(input)
+        const query = get().invoiceQuery
+        const [result, summary] = await Promise.all([provider.getInvoices(query), provider.getSummary()])
+        set({ invoices: result.data, invoicesTotal: result.total, summary })
+        toast.success('Payment recorded')
+      } catch (err: any) {
+        toast.error('Failed to record payment', { description: err?.message })
+        throw err
+      }
+    },
+
+    async cancelInvoice(invoiceId) {
+      try {
+        await provider.cancelInvoice(invoiceId)
+        const query = get().invoiceQuery
+        const [result, summary] = await Promise.all([provider.getInvoices(query), provider.getSummary()])
+        set({ invoices: result.data, invoicesTotal: result.total, summary })
+        toast.success('Invoice cancelled')
+      } catch (err: any) {
+        toast.error('Failed to cancel invoice', { description: err?.message })
+        throw err
+      }
+    },
+
+    async openCashSession(input) {
+      try {
+        const session = await provider.openCashSession(input)
+        const cashSessions = await provider.getCashSessions()
+        set({ cashSessions })
+        toast.success('Cash session opened')
+        return session
+      } catch (err: any) {
+        toast.error('Failed to open session', { description: err?.message })
+        throw err
+      }
+    },
+
+    async closeCashSession(input) {
+      try {
+        const session = await provider.closeCashSession(input)
+        const cashSessions = await provider.getCashSessions()
+        set({ cashSessions })
+        toast.success('Cash session closed')
+        return session
+      } catch (err: any) {
+        toast.error('Failed to close session', { description: err?.message })
+        throw err
+      }
+    },
+  }))
+}