@fayz-ai/plugin-financial 0.2.0 → 0.8.1

package/src/data/supabase.ts

@@ -11,6 +11,7 @@ import type {
 } from '../types'
 import { getSupabaseClientOptional, getActiveTenantId } from '@fayz-ai/core'
 import { getFinancialTenantId } from '../lib/tenant'
+import { T } from './tables'
 
 function getTenantId(): string | undefined {
   // Local override wins; else use the app's active tenant so writes pass RLS.
@@ -37,7 +38,9 @@ function camelToSnake(obj: Record<string, unknown>): Record<string, unknown> {
 function getClients() {
   const supabase = getSupabaseClientOptional() as any
   if (!supabase) throw new Error('Supabase not initialized')
-  return { core: supabase.schema('saas_core'), pub: supabase }
+  // Core tables now live in PUBLIC (legacy dedicated core schema is gone). Both
+  // handles are the single public client; `core` retained for call-site readability.
+  return { core: supabase, pub: supabase }
 }
 
 /** Map order stage to InvoiceStatus for the financial UI */
@@ -64,7 +67,7 @@ async function sweepOverdue() {
     const today = new Date().toISOString().slice(0, 10)
 
     // Mark overdue movements
-    const { data: overdueMovs } = await pub.from('financial_movements')
+    const { data: overdueMovs } = await pub.from(T.movements)
       .update({ status: 'overdue' })
       .in('status', ['pending', 'partial'])
       .lt('due_date', today)
@@ -74,7 +77,7 @@ async function sweepOverdue() {
     if (overdueMovs && overdueMovs.length > 0) {
       const invoiceIds = [...new Set(overdueMovs.map((m: any) => m.invoice_id).filter(Boolean))]
       for (const invId of invoiceIds) {
-        const { data: allMovs } = await pub.from('financial_movements')
+        const { data: allMovs } = await pub.from(T.movements)
           .select('status')
           .eq('invoice_id', invId)
           .eq('movement_kind', 'bill')
@@ -95,7 +98,7 @@ async function sweepOverdue() {
 // S2 (data-model refactor): paid amount, balance and status are DERIVED from the
 // append-only ledger via v_invoice_balances — the single source of truth — not
 // from stored order.stage / metadata.paidAmount (which drift). See
-// docs/data-model-refactor.md.
+// docs/DATA-MODEL.md.
 async function fetchInvoiceBalances(
   pub: any,
   ids: string[],
@@ -137,7 +140,7 @@ async function findOrderIdsByItemMetadata(
 /** Card/MDR fee percent for a configured payment method (0 when none / not a fee method). */
 async function getMethodFeePct(pub: any, paymentMethodId?: string): Promise<number> {
   if (!paymentMethodId) return 0
-  const { data } = await pub.from('payment_methods').select('discount_value').eq('id', paymentMethodId).single()
+  const { data } = await pub.from(T.paymentMethods).select('discount_value').eq('id', paymentMethodId).single()
   return Number(data?.discount_value) || 0
 }
 
@@ -179,7 +182,12 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       }
       if (query.contactId) qb = qb.eq('party_id', query.contactId)
       if (query.search) qb = qb.ilike('notes', `%${query.search}%`)
-      if (query.dateRange) qb = qb.gte('created_at', query.dateRange.from).lte('created_at', query.dateRange.to)
+      // `to` is a plain date from the UI filter — widen it to end-of-day so the
+      // last day of the range isn't cut off at midnight.
+      if (query.dateRange) {
+        const to = query.dateRange.to.length === 10 ? `${query.dateRange.to}T23:59:59.999` : query.dateRange.to
+        qb = qb.gte('created_at', query.dateRange.from).lte('created_at', to)
+      }
       const page = query.page ?? 1
       const pageSize = query.pageSize ?? 50
       qb = qb.range((page - 1) * pageSize, page * pageSize - 1).order('created_at', { ascending: false })
@@ -220,7 +228,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       const meta = data.metadata ?? {}
       // Paid amount + status are DERIVED from the ledger view (single source of truth).
       const balance = (await fetchInvoiceBalances(pub, [id])).get(id)
-      const { data: movs } = await pub.from('financial_movements')
+      const { data: movs } = await pub.from(T.movements)
         .select('paid_amount')
         .eq('invoice_id', id)
         .eq('movement_kind', 'bill')
@@ -303,7 +311,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
 
       // Create installment movements
       if (order && input.installments.length > 0) {
-        await pub.from('financial_movements').insert(
+        await pub.from(T.movements).insert(
           input.installments.map((inst, i) => ({
             tenant_id: tenantId, invoice_id: order.id,
             direction: input.direction, movement_kind: inst.movementKind,
@@ -335,13 +343,13 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
     async cancelInvoice(id: string): Promise<void> {
       const { core, pub } = getClients()
       await core.from('orders').update({ status: 'cancelled' }).eq('id', id)
-      await pub.from('financial_movements').update({ status: 'cancelled' }).eq('invoice_id', id).eq('status', 'pending')
+      await pub.from(T.movements).update({ status: 'cancelled' }).eq('invoice_id', id).eq('status', 'pending')
     },
 
     // --- Movements (public.financial_movements) ---
     async getMovements(query: MovementQuery): Promise<PaginatedResult<FinancialMovement>> {
       const { core, pub } = getClients()
-      let qb = pub.from('financial_movements').select('*', { count: 'exact' })
+      let qb = pub.from(T.movements).select('*', { count: 'exact' })
       if (query.direction) qb = qb.eq('direction', query.direction)
       if (query.status) {
         const statuses = Array.isArray(query.status) ? query.status : [query.status]
@@ -359,7 +367,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
 
     async payMovement(input: PayMovementInput): Promise<FinancialMovement> {
       const { core, pub } = getClients()
-      const { data: mov } = await pub.from('financial_movements').select('*').eq('id', input.movementId).single()
+      const { data: mov } = await pub.from(T.movements).select('*').eq('id', input.movementId).single()
       if (!mov) throw new Error('Movement not found')
       const tenantId = mov.tenant_id ?? getTenantId()
 
@@ -389,11 +397,11 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
         card_installments: input.cardInstallments ?? null,
         notes: input.notes ?? null,
       }
-      let { data, error } = await pub.from('financial_movements').insert(paymentRow).select().single()
+      let { data, error } = await pub.from(T.movements).insert(paymentRow).select().single()
       // Graceful fallback if the fee_amount migration hasn't been applied yet.
       if (error && /fee_amount/i.test(error.message ?? '')) {
         const { fee_amount, ...rest } = paymentRow
-        ;({ data, error } = await pub.from('financial_movements').insert(rest).select().single())
+        ;({ data, error } = await pub.from(T.movements).insert(rest).select().single())
       }
       if (error) throw error
 
@@ -404,13 +412,13 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       const billStatus = newPaid >= mov.amount ? 'paid' : 'partial'
       // Clear the bill's cash fields so it stops being a cash event (the payment row is now
       // the cash event) — prevents double-counting legacy in-place-paid bills.
-      await pub.from('financial_movements')
+      await pub.from(T.movements)
         .update({ paid_amount: newPaid, status: billStatus, payment_date: null, bank_account_id: null })
         .eq('id', mov.id)
 
       // 3. Update invoice (order) status based on its bills
       if (mov.invoice_id) {
-        const { data: allMovs } = await pub.from('financial_movements')
+        const { data: allMovs } = await pub.from(T.movements)
           .select('status, amount, paid_amount')
           .eq('invoice_id', mov.invoice_id)
           .eq('movement_kind', 'bill')
@@ -423,7 +431,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
         const { data: order } = await core.from('orders').select('metadata').eq('id', mov.invoice_id).single()
         const meta = (order?.metadata as any) ?? {}
         const invoiceStage = allPaid ? 'paid' : anyPaid ? 'partial' : 'invoiced'
-        // Only update financial order status. Agenda status lives on saas_core.bookings.
+        // Only update financial order status. Agenda status lives on public.appointments.
         await core.from('orders').update({
           status: invoiceStage,
           metadata: { ...meta, paidAmount: totalPaid },
@@ -435,7 +443,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
 
     async cancelMovement(id: string): Promise<void> {
       const { core, pub } = getClients()
-      await pub.from('financial_movements').update({ status: 'cancelled' }).eq('id', id)
+      await pub.from(T.movements).update({ status: 'cancelled' }).eq('id', id)
     },
 
     // --- Transfers (between accounts) ---
@@ -472,11 +480,11 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
           metadata: { transferId, transferRole: 'in', counterAccountId: input.fromAccountId },
         },
       ]
-      let { data, error } = await pub.from('financial_movements').insert(rowsToInsert).select('id, direction')
+      let { data, error } = await pub.from(T.movements).insert(rowsToInsert).select('id, direction')
       // Graceful fallback if the fee_amount migration hasn't been applied yet.
       if (error && /fee_amount/i.test(error.message ?? '')) {
         const stripped = rowsToInsert.map(({ fee_amount, ...rest }) => rest)
-        ;({ data, error } = await pub.from('financial_movements').insert(stripped).select('id, direction'))
+        ;({ data, error } = await pub.from(T.movements).insert(stripped).select('id, direction'))
       }
       if (error) throw error
       const rows = (data ?? []) as Array<{ id: string; direction: string }>
@@ -488,14 +496,14 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
     // --- Bank Accounts ---
     async getBankAccounts(): Promise<BankAccount[]> {
       const { core, pub } = getClients()
-      const { data } = await pub.from('bank_accounts').select('*').eq('is_active', true).order('name')
+      const { data } = await pub.from(T.bankAccounts).select('*').eq('is_active', true).order('name')
       return (data ?? []).map((r: any) => snakeToCamel(r) as unknown as BankAccount)
     },
 
     async createBankAccount(input: CreateBankAccountInput): Promise<BankAccount> {
       const { core, pub } = getClients()
       const tenantId = getTenantId()
-      const { data } = await pub.from('bank_accounts').insert({
+      const { data } = await pub.from(T.bankAccounts).insert({
         ...camelToSnake(input as any), tenant_id: tenantId, current_balance: input.initialBalance ?? 0,
       }).select().single()
       return snakeToCamel(data!) as unknown as BankAccount
@@ -505,14 +513,14 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       const { core, pub } = getClients()
       const row = camelToSnake(partial as any)
       delete row.id; delete row.tenant_id
-      const { data } = await pub.from('bank_accounts').update(row).eq('id', id).select().single()
+      const { data } = await pub.from(T.bankAccounts).update(row).eq('id', id).select().single()
       return snakeToCamel(data!) as unknown as BankAccount
     },
 
     // --- Cash Sessions ---
     async getCashSessions(bankAccountId?: string): Promise<CashSession[]> {
       const { core, pub } = getClients()
-      let qb = pub.from('cash_register_sessions').select('*')
+      let qb = pub.from(T.cashRegisterSessions).select('*')
       if (bankAccountId) qb = qb.eq('bank_account_id', bankAccountId)
       const { data } = await qb.order('opened_at', { ascending: false })
       return (data ?? []).map((r: any) => snakeToCamel(r) as unknown as CashSession)
@@ -520,14 +528,14 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
 
     async getOpenSession(bankAccountId: string): Promise<CashSession | null> {
       const { core, pub } = getClients()
-      const { data } = await pub.from('cash_register_sessions').select('*').eq('bank_account_id', bankAccountId).eq('status', 'open').single()
+      const { data } = await pub.from(T.cashRegisterSessions).select('*').eq('bank_account_id', bankAccountId).eq('status', 'open').single()
       return data ? snakeToCamel(data) as unknown as CashSession : null
     },
 
     async openCashSession(input: OpenCashSessionInput): Promise<CashSession> {
       const { core, pub } = getClients()
       const tenantId = getTenantId()
-      const { data } = await pub.from('cash_register_sessions').insert({
+      const { data } = await pub.from(T.cashRegisterSessions).insert({
         tenant_id: tenantId, bank_account_id: input.bankAccountId,
         status: 'open', opening_balance: input.openingBalance,
         opened_by_user_id: input.openedByUserId, opened_by_name: input.openedByName,
@@ -538,7 +546,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
 
     async closeCashSession(input: CloseCashSessionInput): Promise<CashSession> {
       const { core, pub } = getClients()
-      const { data } = await pub.from('cash_register_sessions').update({
+      const { data } = await pub.from(T.cashRegisterSessions).update({
         status: 'closed', closing_balance: input.closingBalance,
         closed_at: new Date().toISOString(),
         closed_by_user_id: input.closedByUserId, closed_by_name: input.closedByName,
@@ -549,8 +557,8 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
 
     async getCashSessionSummary(sessionId: string): Promise<CashSessionSummary> {
       const { core, pub } = getClients()
-      const session = (await pub.from('cash_register_sessions').select('*').eq('id', sessionId).single()).data
-      const { data: movs } = await pub.from('financial_movements').select('direction, paid_amount').eq('cash_session_id', sessionId).eq('status', 'paid')
+      const session = (await pub.from(T.cashRegisterSessions).select('*').eq('id', sessionId).single()).data
+      const { data: movs } = await pub.from(T.movements).select('direction, paid_amount').eq('cash_session_id', sessionId).eq('status', 'paid')
       const movements = movs ?? []
       return {
         session: snakeToCamel(session!) as unknown as CashSession,
@@ -563,26 +571,26 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
     // --- Payment Methods ---
     async getPaymentMethods(): Promise<PaymentMethod[]> {
       const { core, pub } = getClients()
-      const { data } = await pub.from('payment_methods').select('*').eq('is_active', true).order('name')
+      const { data } = await pub.from(T.paymentMethods).select('*').eq('is_active', true).order('name')
       return (data ?? []).map((r: any) => snakeToCamel(r) as unknown as PaymentMethod)
     },
 
     async getPaymentMethodTypes(): Promise<PaymentMethodType[]> {
       const { core, pub } = getClients()
-      const { data } = await pub.from('payment_method_types').select('*').eq('is_active', true).order('name')
+      const { data } = await pub.from(T.paymentMethodTypes).select('*').eq('is_active', true).order('name')
       return (data ?? []).map((r: any) => snakeToCamel(r) as unknown as PaymentMethodType)
     },
 
     // --- Chart of Accounts ---
     async getChartOfAccounts(): Promise<ChartOfAccountsNode[]> {
       const { core, pub } = getClients()
-      const { data } = await pub.from('chart_of_accounts').select('*').eq('is_active', true).order('code')
+      const { data } = await pub.from(T.chartOfAccounts).select('*').eq('is_active', true).order('code')
       return (data ?? []).map((r: any) => snakeToCamel(r) as unknown as ChartOfAccountsNode)
     },
 
     async getCostCenters(): Promise<CostCenter[]> {
       const { core, pub } = getClients()
-      const { data } = await pub.from('cost_centers').select('*').eq('is_active', true).order('code')
+      const { data } = await pub.from(T.costCenters).select('*').eq('is_active', true).order('code')
       return (data ?? []).map((r: any) => snakeToCamel(r) as unknown as CostCenter)
     },
 
@@ -604,7 +612,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
 
       // 1. Resolve in-scope accounts. No bankAccountId => consolidated: ALL realized cash
       // (including movements with no bank_account_id, e.g. cash/card payments not tied to an account).
-      const { data: acctRows } = await pub.from('bank_accounts').select('id, name, initial_balance, is_active')
+      const { data: acctRows } = await pub.from(T.bankAccounts).select('id, name, initial_balance, is_active')
       const allAccounts = (acctRows ?? []) as any[]
       const consolidated = !query.bankAccountId
       const scopeAccounts = consolidated
@@ -626,7 +634,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
 
       // 2. Opening balance = Σ initial_balance + prior net (payment_date < from).
       // Select '*' so this still works before the fee_amount migration lands (fee → 0).
-      const { data: priorRows } = await scopeFilter(pub.from('financial_movements')
+      const { data: priorRows } = await scopeFilter(pub.from(T.movements)
         .select('*')
         .neq('status', 'cancelled')
         .lt('payment_date', query.dateRange.from))
@@ -634,7 +642,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       const openingBalance = round2(initialSum + priorNet)
 
       // 3. In-range realized rows.
-      const { data: movs } = await scopeFilter(pub.from('financial_movements')
+      const { data: movs } = await scopeFilter(pub.from(T.movements)
         .select('*')
         .neq('status', 'cancelled')
         .gte('payment_date', query.dateRange.from).lte('payment_date', query.dateRange.to)
@@ -687,7 +695,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       // extract row can link to the internal transaction it was conciliated with.
       const matchedIds = [...new Set(entries.map((e) => e.movement.matchedMovementId).filter(Boolean))] as string[]
       if (matchedIds.length) {
-        const { data: matched } = await pub.from('financial_movements').select('id, invoice_id, notes').in('id', matchedIds)
+        const { data: matched } = await pub.from(T.movements).select('id, invoice_id, notes').in('id', matchedIds)
         const matchedById = new Map<string, any>((matched ?? []).map((m: any) => [m.id, m]))
         const matchedInvoiceIds = [...new Set((matched ?? []).map((m: any) => m.invoice_id).filter(Boolean))] as string[]
         const invById = new Map<string, any>()
@@ -711,7 +719,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       }
 
       // 6. Account current balance (ledger as-of-today).
-      const { data: todayRows } = await scopeFilter(pub.from('financial_movements')
+      const { data: todayRows } = await scopeFilter(pub.from(T.movements)
         .select('*')
         .neq('status', 'cancelled')
         .lte('payment_date', today))
@@ -735,10 +743,10 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       // Sweep overdue on first load (background, non-blocking)
       sweepOverdue()
       const { core, pub } = getClients()
-      const { data: accounts } = await pub.from('bank_accounts').select('current_balance').eq('is_active', true)
+      const { data: accounts } = await pub.from(T.bankAccounts).select('current_balance').eq('is_active', true)
       const totalBalance = (accounts ?? []).reduce((s: number, a: any) => s + (a.current_balance ?? 0), 0)
 
-      const { data: movs } = await pub.from('financial_movements').select('direction, movement_kind, amount, paid_amount, status, due_date, payment_date')
+      const { data: movs } = await pub.from(T.movements).select('direction, movement_kind, amount, paid_amount, status, due_date, payment_date')
       const allMovs = movs ?? []
       const unpaid = allMovs.filter((m: any) => ['pending', 'partial', 'overdue'].includes(m.status))
       const today = new Date().toISOString().slice(0, 10)
@@ -778,7 +786,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       const tenantId = getTenantId()
       let imported = 0, duplicates = 0
       for (const line of input.lines) {
-        const { error } = await pub.from('financial_movements').insert({
+        const { error } = await pub.from(T.movements).insert({
           tenant_id: tenantId,
           direction: line.direction,
           movement_kind: 'payment',
@@ -803,7 +811,7 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
 
     async getUnreconciled(query) {
       const { pub } = getClients()
-      let qb = pub.from('financial_movements').select('*')
+      let qb = pub.from(T.movements).select('*')
         .not('external_source', 'is', null)
         .is('reconciled_at', null)
       if (query?.bankAccountId) qb = qb.eq('bank_account_id', query.bankAccountId)
@@ -814,13 +822,13 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
 
     async suggestReconciliation(bankMovementId) {
       const { core, pub } = getClients()
-      const { data: line } = await pub.from('financial_movements').select('*').eq('id', bankMovementId).single()
+      const { data: line } = await pub.from(T.movements).select('*').eq('id', bankMovementId).single()
       if (!line) return []
       const amount = Number(line.amount) || 0
       const lineDate = line.payment_date ?? line.due_date
       // Candidates: app-native (non-imported), same direction, not reconciled, amount within ±2%.
       const tol = Math.max(0.01, round2(amount * 0.02))
-      const { data } = await pub.from('financial_movements').select('*')
+      const { data } = await pub.from(T.movements).select('*')
         .is('external_source', null)
         .is('reconciled_at', null)
         .eq('direction', line.direction)
@@ -857,22 +865,22 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
     async reconcileMovement(input) {
       const { pub } = getClients()
       const now = new Date().toISOString()
-      await pub.from('financial_movements').update({
+      await pub.from(T.movements).update({
         reconciled_at: now,
         matched_movement_id: input.matchedMovementId ?? null,
       }).eq('id', input.bankMovementId)
       if (input.matchedMovementId) {
         // The internal movement is now settled+reconciled by the bank line.
-        await pub.from('financial_movements').update({ reconciled_at: now }).eq('id', input.matchedMovementId)
+        await pub.from(T.movements).update({ reconciled_at: now }).eq('id', input.matchedMovementId)
       }
     },
 
     async unreconcileMovement(bankMovementId) {
       const { pub } = getClients()
-      const { data: line } = await pub.from('financial_movements').select('matched_movement_id').eq('id', bankMovementId).single()
-      await pub.from('financial_movements').update({ reconciled_at: null, matched_movement_id: null }).eq('id', bankMovementId)
+      const { data: line } = await pub.from(T.movements).select('matched_movement_id').eq('id', bankMovementId).single()
+      await pub.from(T.movements).update({ reconciled_at: null, matched_movement_id: null }).eq('id', bankMovementId)
       if (line?.matched_movement_id) {
-        await pub.from('financial_movements').update({ reconciled_at: null }).eq('id', line.matched_movement_id)
+        await pub.from(T.movements).update({ reconciled_at: null }).eq('id', line.matched_movement_id)
       }
     },
   }

package/src/data/tables.ts

@@ -0,0 +1,12 @@
+// Central physical-table-name registry for plugin-financial. Providers import T so
+// the plg_financial_* strings live in one place.
+export const T = {
+  movements: 'plg_financial_movements',
+  chartOfAccounts: 'plg_financial_chart_of_accounts',
+  bankAccounts: 'plg_financial_bank_accounts',
+  cardBrands: 'plg_financial_card_brands',
+  costCenters: 'plg_financial_cost_centers',
+  cashRegisterSessions: 'plg_financial_cash_register_sessions',
+  paymentMethods: 'plg_financial_payment_methods',
+  paymentMethodTypes: 'plg_financial_payment_method_types',
+} as const

package/src/index.ts

@@ -121,6 +121,22 @@ export interface FinancialPluginOptions {
 
   /** Callback when user clicks a booking link on an invoice. Receives the order ID. */
   onBookingClick?: (orderId: string) => void
+
+  /**
+   * Which internal-nav links this APP gates, as `nav item id → feature id`.
+   * Empty by default: the plugin ships no opinion about what is paid — packaging
+   * is the app's decision, declared alongside its `permissions.ts` (RBAC) and
+   * `billing.ts` (plan entitlements). An id absent from this map is never hidden
+   * and never gated, in the nav OR in the content.
+   *
+   * {@link FINANCIAL_NAV_FEATURES} is an opt-in preset of the `fin_*` ids used
+   * by the reference apps — spread the entries you actually want:
+   *
+   * ```ts
+   * navFeatureMap: { reconciliation: FINANCIAL_NAV_FEATURES.reconciliation }
+   * ```
+   */
+  navFeatureMap?: Record<string, string>
 }
 
 // ---------------------------------------------------------------------------
@@ -150,6 +166,23 @@ const DEFAULT_LABELS: FinancialPluginLabels = {
 
 const DEFAULT_CURRENCY = { code: 'BRL', locale: 'pt-BR', symbol: 'R$' }
 
+/**
+ * OPT-IN preset of feature ids for the financial sub-modules — a naming
+ * convention offered to apps, NOT a default. Nothing here is applied unless an
+ * app passes the entries it wants through `options.navFeatureMap`, because what
+ * is paid is a product decision that belongs to the app (its `permissions.ts` +
+ * `billing.ts`), never to the plugin.
+ */
+export const FINANCIAL_NAV_FEATURES = {
+  reconciliation: 'fin_reconciliation',
+  cards: 'fin_cards',
+  commissions: 'fin_commissions',
+  statements: 'fin_statements',
+  receivables: 'fin_receivables',
+  payables: 'fin_payables',
+  'cash-registers': 'fin_cash_registers',
+} as const satisfies Record<string, string>
+
 const DEFAULT_ITEM_TYPES: ItemTypeOption[] = [
   { value: 'service', label: 'Service', icon: 'Briefcase' },
   { value: 'product', label: 'Product', icon: 'Package' },
@@ -186,6 +219,7 @@ function resolveConfig(options?: FinancialPluginOptions): ResolvedFinancialConfi
     entityLookups: options?.entityLookups ?? {},
     contactLookup: options?.contactLookup,
     onBookingClick: options?.onBookingClick,
+    navFeatureMap: { ...options?.navFeatureMap },
   }
 }
 
@@ -225,6 +259,71 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
       ...(config.modules.payables ? [{ id: 'financial.payables', label: config.labels.payables, group: config.labels.pageTitle }] : []),
       ...(config.modules.commissions ? [{ id: 'financial.commissions', label: config.labels.commissions, group: config.labels.pageTitle }] : []),
     ],
+    // Recurring monthly quota — counts financial movement rows created this
+    // month (invoices write one per installment; quick transactions one, or two
+    // for a transfer).
+    declaredLimits: [
+      { key: 'movements_month', label: 'Financial movements this month', table: 'plg_financial_movements', period: 'month' },
+    ],
+    queryEntities: [
+      {
+        key: 'financial:invoices',
+        entity: {
+          name: 'Invoice',
+          namePlural: 'Invoices (receipts REC- / payables PAG-)',
+          icon: 'Receipt',
+          permission: { feature: 'financial', action: 'read' },
+          fields: [
+            { key: 'referenceNumber', label: 'Reference (REC-/PAG-)', type: 'text', searchable: true },
+            { key: 'flow', label: 'Flow (receivable/payable)', type: 'text' },
+            { key: 'amount', label: 'Amount', type: 'number' },
+            { key: 'paid', label: 'Paid', type: 'number' },
+            { key: 'balance', label: 'Balance', type: 'number' },
+            { key: 'status', label: 'Status', type: 'text' },
+            { key: 'createdAt', label: 'Created at', type: 'text' },
+          ],
+          data: {
+            table: 'v_invoice_balances',
+            tenantScoped: true,
+            searchColumns: ['reference_number'],
+          },
+        },
+      },
+      {
+        key: 'financial:movements',
+        entity: {
+          name: 'Financial movement',
+          namePlural: 'Financial movements (installment ledger)',
+          icon: 'Banknote',
+          permission: { feature: 'financial', action: 'read' },
+          fields: [
+            { key: 'direction', label: 'Direction', type: 'text' },
+            { key: 'movementKind', label: 'Kind (bill/payment)', type: 'text' },
+            { key: 'amount', label: 'Amount', type: 'number' },
+            { key: 'paidAmount', label: 'Paid amount', type: 'number' },
+            { key: 'status', label: 'Status', type: 'text' },
+            { key: 'dueDate', label: 'Due date', type: 'text' },
+            { key: 'paymentDate', label: 'Payment date', type: 'text' },
+            { key: 'installmentNumber', label: 'Installment', type: 'number' },
+            { key: 'cardInstallments', label: 'Card installments', type: 'number' },
+            { key: 'createdAt', label: 'Created at', type: 'text' },
+          ],
+          data: {
+            table: 'plg_financial_movements',
+            tenantScoped: true,
+          },
+        },
+      },
+    ],
+    declaredRpcs: [
+      {
+        name: 'agent_financial_mark_payment_received',
+        kind: 'write' as const,
+        description:
+          'Guarded settle: invoices the order via fn_invoice_from_order (installments for credit card) and marks the receivable paid, audited with the acting user.',
+        audits: true,
+      },
+    ],
     navigation: [
       {
         section: options?.navSection ?? 'main',
@@ -278,6 +377,7 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
         description: 'Creates a new invoice/payable for a contact.',
         icon: 'FileText',
         mode: 'persist' as const,
+        limitKey: 'movements_month',
         category: 'Finance',
         parameters: {
           type: 'object' as const,
@@ -293,6 +393,34 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
         ],
         permission: { feature: 'financial', action: 'create' as const },
       },
+      {
+        id: 'financial.mark-payment-received',
+        name: 'markPaymentReceived',
+        description:
+          'Marks an order/appointment as paid: invoices it (with installments for credit card, e.g. "cartão 2x") and settles the receivable. Resolve the booking or order id via search tools first.',
+        icon: 'BadgeDollarSign',
+        mode: 'persist' as const,
+        execution: { plane: 'server' as const, kind: 'rpc' as const, rpc: 'agent_financial_mark_payment_received' },
+        category: 'Finance',
+        parameters: {
+          type: 'object' as const,
+          properties: {
+            booking_id: { type: 'string' as const, description: 'Appointment id (alternative to order_id)' },
+            order_id: { type: 'string' as const, description: 'Order id' },
+            method: {
+              type: 'string' as const,
+              description: 'Payment method',
+              enum: ['cash', 'pix', 'credit_card', 'debit_card', 'transfer'],
+            },
+            installments: { type: 'number' as const, description: 'Credit-card installments (1-12), e.g. 2 for "cartão 2x"' },
+          },
+          required: ['method'],
+        },
+        suggestions: [
+          { label: 'Marcar o atendimento como pago no cartão em 2x' },
+        ],
+        permission: { feature: 'financial.receivables', action: 'update' as const },
+      },
       {
         id: 'financial.list-payables',
         name: 'listPayables',

package/src/locales/en.ts

@@ -142,6 +142,16 @@ export const en: Record<string, string> = {
   "financial.invoice.filterAllAccounts": "All accounts",
   "financial.invoice.filterCostCenter": "Cost center",
   "financial.invoice.filterAllCostCenters": "All cost centers",
+  "financial.invoice.filterPeriod": "Period",
+  "financial.invoice.filterAllPeriods": "All time",
+  "financial.invoice.filterThisMonth": "This month",
+  "financial.invoice.filterLastMonth": "Last month",
+  "financial.invoice.filterLast30": "Last 30 days",
+  "financial.invoice.filterThisYear": "This year",
+  "financial.invoice.filterCustom": "Custom",
+  "financial.invoice.filterFrom": "From",
+  "financial.invoice.filterTo": "To",
+  "financial.invoice.filterClear": "Clear",
   "financial.reconciliation.title": "Reconciliation",
   "financial.reconciliation.subtitle": "Match imported bank lines to your movements",
   "financial.reconciliation.pending": "{{count}} to reconcile",

package/src/locales/pt-BR.ts

@@ -142,6 +142,16 @@ export const ptBR: Record<string, string> = {
   "financial.invoice.filterAllAccounts": "Todos os planos",
   "financial.invoice.filterCostCenter": "Centro de custo",
   "financial.invoice.filterAllCostCenters": "Todos os centros",
+  "financial.invoice.filterPeriod": "Período",
+  "financial.invoice.filterAllPeriods": "Todo o período",
+  "financial.invoice.filterThisMonth": "Este mês",
+  "financial.invoice.filterLastMonth": "Mês passado",
+  "financial.invoice.filterLast30": "Últimos 30 dias",
+  "financial.invoice.filterThisYear": "Este ano",
+  "financial.invoice.filterCustom": "Personalizado",
+  "financial.invoice.filterFrom": "De",
+  "financial.invoice.filterTo": "Até",
+  "financial.invoice.filterClear": "Limpar",
   "financial.reconciliation.title": "Conciliação",
   "financial.reconciliation.subtitle": "Concilie as linhas importadas do banco com seus lançamentos",
   "financial.reconciliation.pending": "{{count}} para conciliar",

package/src/migrations/000_plg_rename.sql

@@ -0,0 +1,30 @@
+-- 000_plg_rename.sql — rename legacy financial tables to plg_financial_* for pools
+-- provisioned before the industry-pool rename. Guarded: fires only when the legacy
+-- name exists and the target does not, so fresh pools skip every branch.
+DO $$
+BEGIN
+  IF to_regclass('public.financial_movements') IS NOT NULL AND to_regclass('public.plg_financial_movements') IS NULL THEN
+    ALTER TABLE public.financial_movements RENAME TO plg_financial_movements;
+  END IF;
+  IF to_regclass('public.chart_of_accounts') IS NOT NULL AND to_regclass('public.plg_financial_chart_of_accounts') IS NULL THEN
+    ALTER TABLE public.chart_of_accounts RENAME TO plg_financial_chart_of_accounts;
+  END IF;
+  IF to_regclass('public.bank_accounts') IS NOT NULL AND to_regclass('public.plg_financial_bank_accounts') IS NULL THEN
+    ALTER TABLE public.bank_accounts RENAME TO plg_financial_bank_accounts;
+  END IF;
+  IF to_regclass('public.card_brands') IS NOT NULL AND to_regclass('public.plg_financial_card_brands') IS NULL THEN
+    ALTER TABLE public.card_brands RENAME TO plg_financial_card_brands;
+  END IF;
+  IF to_regclass('public.cost_centers') IS NOT NULL AND to_regclass('public.plg_financial_cost_centers') IS NULL THEN
+    ALTER TABLE public.cost_centers RENAME TO plg_financial_cost_centers;
+  END IF;
+  IF to_regclass('public.cash_register_sessions') IS NOT NULL AND to_regclass('public.plg_financial_cash_register_sessions') IS NULL THEN
+    ALTER TABLE public.cash_register_sessions RENAME TO plg_financial_cash_register_sessions;
+  END IF;
+  IF to_regclass('public.payment_methods') IS NOT NULL AND to_regclass('public.plg_financial_payment_methods') IS NULL THEN
+    ALTER TABLE public.payment_methods RENAME TO plg_financial_payment_methods;
+  END IF;
+  IF to_regclass('public.payment_method_types') IS NOT NULL AND to_regclass('public.plg_financial_payment_method_types') IS NULL THEN
+    ALTER TABLE public.payment_method_types RENAME TO plg_financial_payment_method_types;
+  END IF;
+END $$;