@fayz-ai/plugin-financial 0.1.2 → 0.1.4

package/src/data/supabase.ts

@@ -3,11 +3,11 @@ import type {
   Invoice, InvoiceItem, FinancialMovement, BankAccount,
   CashSession, PaymentMethod, PaymentMethodType, ChartOfAccountsNode,
   CardTransaction,
-  CreateInvoiceInput, PayMovementInput,
+  CreateInvoiceInput, PayMovementInput, CreateTransferInput, TransferResult,
   OpenCashSessionInput, CloseCashSessionInput, CreateBankAccountInput,
   InvoiceQuery, MovementQuery, StatementQuery,
-  PaginatedResult, FinancialSummary, StatementEntry, CashSessionSummary,
-  DateRange,
+  PaginatedResult, FinancialSummary, StatementEntry, StatementResult, CashSessionSummary,
+  DateRange, ReconciliationCandidate,
 } from '../types'
 import { getSupabaseClientOptional, getActiveTenantId } from '@fayz-ai/core'
 import { getFinancialTenantId } from '../lib/tenant'
@@ -95,7 +95,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/dogfood-sprint/DATA-MODEL-REFACTOR.md.
+// docs/data-model-refactor.md.
 async function fetchInvoiceBalances(
   pub: any,
   ids: string[],
@@ -112,6 +112,25 @@ async function fetchInvoiceBalances(
   return map
 }
 
+function round2(n: number): number {
+  return Math.round(n * 100) / 100
+}
+
+/** 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()
+  return Number(data?.discount_value) || 0
+}
+
+/** Generate a correlation id; falls back when crypto.randomUUID is unavailable. */
+function genId(): string {
+  try {
+    if (typeof crypto !== 'undefined' && (crypto as any).randomUUID) return (crypto as any).randomUUID()
+  } catch { /* noop */ }
+  return 'tr-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 10)
+}
+
 export function createSupabaseFinancialProvider(): FinancialDataProvider {
   const provider: FinancialDataProvider = {
     // --- Invoices (orders at stage=invoiced/paid/partial/overdue/cancelled with direction) ---
@@ -309,18 +328,54 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       const { core, pub } = getClients()
       const { data: mov } = await pub.from('financial_movements').select('*').eq('id', input.movementId).single()
       if (!mov) throw new Error('Movement not found')
-      const newPaid = (mov.paid_amount ?? 0) + input.amount
-      const newStatus = newPaid >= mov.amount ? 'paid' : 'partial'
-      const updates: any = { paid_amount: newPaid, status: newStatus, payment_date: input.paymentDate }
-      if (input.paymentMethodId) updates.payment_method_id = input.paymentMethodId
-      if (input.paymentMethodTypeId) updates.payment_method_type_id = input.paymentMethodTypeId
-      if (input.bankAccountId) updates.bank_account_id = input.bankAccountId
-      if (input.cashSessionId) updates.cash_session_id = input.cashSessionId
-      if (input.cardBrand) updates.card_brand = input.cardBrand
-      if (input.cardInstallments) updates.card_installments = input.cardInstallments
-      const { data } = await pub.from('financial_movements').update(updates).eq('id', input.movementId).select().single()
-
-      // Update invoice (order) status based on all its movements
+      const tenantId = mov.tenant_id ?? getTenantId()
+
+      // Net card settlement: derive the processing/MDR fee (inflows only in v1).
+      const feePct = mov.direction === 'credit' ? await getMethodFeePct(pub, input.paymentMethodId) : 0
+      const thisFee = round2(input.amount * (feePct / 100))
+
+      // 1. Record the cash event as its OWN payment movement — NOT by mutating the
+      //    bill. Two payments on one installment → two distinct rows in the extract.
+      const paymentRow: any = {
+        tenant_id: tenantId,
+        invoice_id: mov.invoice_id,
+        direction: mov.direction,
+        movement_kind: 'payment',
+        amount: input.amount,
+        paid_amount: input.amount,
+        fee_amount: thisFee,
+        status: 'paid',
+        due_date: mov.due_date,
+        payment_date: input.paymentDate,
+        installment_number: mov.installment_number,
+        payment_method_id: input.paymentMethodId ?? null,
+        payment_method_type_id: input.paymentMethodTypeId ?? null,
+        bank_account_id: input.bankAccountId ?? null,
+        cash_session_id: input.cashSessionId ?? null,
+        card_brand: input.cardBrand ?? null,
+        card_installments: input.cardInstallments ?? null,
+        notes: input.notes ?? null,
+      }
+      let { data, error } = await pub.from('financial_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())
+      }
+      if (error) throw error
+
+      // 2. Update the bill (obligation) cache: cumulative paid + status. It stays a
+      //    pure obligation (no bank/method/date) — the cash lives on the payment row.
+      //    v_invoice_balances reads bill.paid_amount, so this keeps balances correct.
+      const newPaid = round2((mov.paid_amount ?? 0) + input.amount)
+      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')
+        .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')
           .select('status, amount, paid_amount')
@@ -350,6 +405,53 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       await pub.from('financial_movements').update({ status: 'cancelled' }).eq('id', id)
     },
 
+    // --- Transfers (between accounts) ---
+    async createTransfer(input: CreateTransferInput): Promise<TransferResult> {
+      const { pub } = getClients()
+      if (!input.fromAccountId || !input.toAccountId || input.fromAccountId === input.toAccountId) {
+        throw new Error('Source and destination accounts must differ')
+      }
+      if (!(input.amount > 0)) throw new Error('Amount must be greater than zero')
+      const tenantId = getTenantId()
+      const transferId = genId()
+      const base = {
+        tenant_id: tenantId,
+        movement_kind: 'transfer' as const,
+        amount: input.amount,
+        paid_amount: input.amount,
+        fee_amount: 0,
+        status: 'paid' as const,
+        due_date: input.date,
+        payment_date: input.date,
+        notes: input.notes ?? null,
+      }
+      const rowsToInsert = [
+        {
+          ...base,
+          direction: 'debit',
+          bank_account_id: input.fromAccountId,
+          metadata: { transferId, transferRole: 'out', counterAccountId: input.toAccountId },
+        },
+        {
+          ...base,
+          direction: 'credit',
+          bank_account_id: input.toAccountId,
+          metadata: { transferId, transferRole: 'in', counterAccountId: input.fromAccountId },
+        },
+      ]
+      let { data, error } = await pub.from('financial_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'))
+      }
+      if (error) throw error
+      const rows = (data ?? []) as Array<{ id: string; direction: string }>
+      const debitMovementId = rows.find((r) => r.direction === 'debit')?.id ?? ''
+      const creditMovementId = rows.find((r) => r.direction === 'credit')?.id ?? ''
+      return { transferId, debitMovementId, creditMovementId }
+    },
+
     // --- Bank Accounts ---
     async getBankAccounts(): Promise<BankAccount[]> {
       const { core, pub } = getClients()
@@ -451,23 +553,142 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       return [] // TODO: implement when card_transactions table exists
     },
 
-    // --- Statements ---
-    async getStatement(query: StatementQuery): Promise<StatementEntry[]> {
+    // --- Statements (ERP extract: opening balance + realized cash + per-row net/fee) ---
+    async getStatement(query: StatementQuery): Promise<StatementResult> {
       const { core, pub } = getClients()
-      const { data: movs } = await pub.from('financial_movements').select('*')
-        .eq('bank_account_id', query.bankAccountId).eq('status', 'paid')
+      const today = new Date().toISOString().slice(0, 10)
+      // The extract = actual cash events. A cash event is any non-cancelled movement with
+      // a payment_date: payment movements, transfers, and legacy in-place-paid bills (which
+      // still carry a payment_date until the split migration backfills them). Once a payment
+      // movement exists for a bill, payMovement clears the bill's payment_date, so a single
+      // cash amount is represented by exactly one row — no double counting, no migration needed.
+
+      // 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 allAccounts = (acctRows ?? []) as any[]
+      const consolidated = !query.bankAccountId
+      const scopeAccounts = consolidated
+        ? allAccounts.filter((a) => a.is_active)
+        : allAccounts.filter((a) => a.id === query.bankAccountId)
+      const accountIds = scopeAccounts.map((a) => a.id)
+      const accountNameById = new Map<string, string>(allAccounts.map((a) => [a.id, a.name]))
+      const initialSum = scopeAccounts.reduce((s, a) => s + (Number(a.initial_balance) || 0), 0)
+      // Only bail when a specific account was asked for and not found.
+      if (!consolidated && accountIds.length === 0) {
+        return { entries: [], openingBalance: 0, closingBalance: 0, totalCredits: 0, totalDebits: 0, totalFees: 0, net: 0, accountId: query.bankAccountId }
+      }
+      // Consolidated => no account filter (catches NULL-account movements too).
+      const scopeFilter = (qb: any) => consolidated ? qb : qb.in('bank_account_id', accountIds)
+
+      const netOf = (r: any) => r.direction === 'credit'
+        ? (Number(r.paid_amount) || 0) - (Number(r.fee_amount) || 0)
+        : -(Number(r.paid_amount) || 0)
+
+      // 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')
+        .select('*')
+        .neq('status', 'cancelled')
+        .lt('payment_date', query.dateRange.from))
+      const priorNet = (priorRows ?? []).reduce((s: number, r: any) => s + netOf(r), 0)
+      const openingBalance = round2(initialSum + priorNet)
+
+      // 3. In-range realized rows.
+      const { data: movs } = await scopeFilter(pub.from('financial_movements')
+        .select('*')
+        .neq('status', 'cancelled')
         .gte('payment_date', query.dateRange.from).lte('payment_date', query.dateRange.to)
-        .order('payment_date')
-
-      const { data: account } = await pub.from('bank_accounts').select('initial_balance').eq('id', query.bankAccountId).single()
-      let balance = account?.initial_balance ?? 0
+        .order('payment_date').order('created_at'))
+
+      // 4. Join invoices for descriptions.
+      const invoiceIds = [...new Set((movs ?? []).map((r: any) => r.invoice_id).filter(Boolean))]
+      const invoiceById = new Map<string, Invoice>()
+      if (invoiceIds.length) {
+        const { data: orders } = await core.from('orders').select('id, party_id, reference_number, metadata').in('id', invoiceIds)
+        for (const o of (orders ?? []) as any[]) {
+          invoiceById.set(o.id, { id: o.id, contactId: o.party_id, contactName: (o.metadata as any)?.contactName, fiscalNumber: o.reference_number } as Invoice)
+        }
+      }
 
-      return (movs ?? []).map((r: any) => {
-        const mov = snakeToCamel(r) as unknown as FinancialMovement
-        if (mov.direction === 'credit') balance += mov.paidAmount
-        else balance -= mov.paidAmount
-        return { movement: mov, runningBalance: balance }
+      // 5. Build entries with running NET balance.
+      let balance = openingBalance
+      let totalCredits = 0, totalDebits = 0, totalFees = 0
+      const entries: StatementEntry[] = (movs ?? []).map((r: any) => {
+        const movement = snakeToCamel(r) as unknown as FinancialMovement
+        const gross = Number(r.paid_amount) || 0
+        const isCredit = r.direction === 'credit'
+        const fee = isCredit ? (Number(r.fee_amount) || 0) : 0
+        const net = isCredit ? round2(gross - fee) : gross
+        const meta = (r.metadata ?? {}) as any
+        const isTransfer = r.movement_kind === 'transfer'
+        const entryKind: StatementEntry['entryKind'] = isTransfer
+          ? (meta.transferRole === 'in' ? 'transfer-in' : 'transfer-out')
+          : 'movement'
+        const counterAccountId = isTransfer ? meta.counterAccountId : undefined
+        if (isCredit) balance = round2(balance + net)
+        else balance = round2(balance - net)
+        // Exclude internal transfers from consolidated totals (they net to zero across accounts).
+        if (!(consolidated && isTransfer)) {
+          if (isCredit) totalCredits = round2(totalCredits + net)
+          else totalDebits = round2(totalDebits + net)
+          totalFees = round2(totalFees + fee)
+        }
+        return {
+          movement,
+          invoice: r.invoice_id ? invoiceById.get(r.invoice_id) : undefined,
+          runningBalance: balance,
+          gross, fee, net, entryKind,
+          counterAccountId,
+          counterAccountName: counterAccountId ? accountNameById.get(counterAccountId) : undefined,
+        }
       })
+
+      // 5b. Resolve the reconciliation counterpart for matched bank lines, so the
+      // 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 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>()
+        if (matchedInvoiceIds.length) {
+          const { data: orders } = await core.from('orders').select('id, reference_number, metadata').in('id', matchedInvoiceIds)
+          for (const o of (orders ?? []) as any[]) invById.set(o.id, o)
+        }
+        for (const e of entries) {
+          const mid = e.movement.matchedMovementId
+          const mm = mid ? matchedById.get(mid) : undefined
+          if (!mm) continue
+          const inv = mm.invoice_id ? invById.get(mm.invoice_id) : undefined
+          e.reconciledWith = {
+            movementId: mm.id,
+            description: mm.notes ?? undefined,
+            invoiceId: mm.invoice_id ?? undefined,
+            fiscalNumber: inv?.reference_number ?? undefined,
+            contactName: (inv?.metadata as any)?.contactName ?? undefined,
+          }
+        }
+      }
+
+      // 6. Account current balance (ledger as-of-today).
+      const { data: todayRows } = await scopeFilter(pub.from('financial_movements')
+        .select('*')
+        .neq('status', 'cancelled')
+        .lte('payment_date', today))
+      const accountCurrentBalance = round2(initialSum + (todayRows ?? []).reduce((s: number, r: any) => s + netOf(r), 0))
+
+      return {
+        entries,
+        openingBalance,
+        closingBalance: balance,
+        totalCredits,
+        totalDebits,
+        totalFees,
+        net: round2(totalCredits - totalDebits),
+        accountId: query.bankAccountId,
+        accountCurrentBalance,
+      }
     },
 
     // --- Summary ---
@@ -489,7 +710,8 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       const overdueDebit = unpaidDebit.filter((m: any) => m.status === 'overdue' || m.due_date < today)
 
       const monthStart = today.slice(0, 7) + '-01'
-      const monthPaid = allMovs.filter((m: any) => m.status === 'paid' && m.payment_date >= monthStart)
+      // Monthly cash flow = payment cash events (one row per payment), never bills.
+      const monthPaid = allMovs.filter((m: any) => m.movement_kind === 'payment' && m.payment_date >= monthStart)
 
       return {
         totalBalance,
@@ -503,6 +725,113 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
         overduePayableAmount: overdueDebit.reduce((s: number, m: any) => s + m.amount - m.paid_amount, 0),
       }
     },
+
+    // --- Reconciliation (conciliação) ---
+    // Imported bank-statement lines live in financial_movements tagged with
+    // (external_source, external_id), status='paid'. Reconciling links a line
+    // to the internal movement it settles (or accepts it standalone).
+    async importBankTransactions(input) {
+      const { pub } = getClients()
+      const tenantId = getTenantId()
+      let imported = 0, duplicates = 0
+      for (const line of input.lines) {
+        const { error } = await pub.from('financial_movements').insert({
+          tenant_id: tenantId,
+          direction: line.direction,
+          movement_kind: 'payment',
+          amount: line.amount,
+          paid_amount: line.amount,
+          status: 'paid',
+          due_date: line.date,
+          payment_date: line.date,
+          bank_account_id: line.bankAccountId ?? input.bankAccountId ?? null,
+          notes: line.description,
+          external_id: line.externalId,
+          external_source: line.externalSource,
+        })
+        if (error) {
+          // 23505 = unique violation on uq_financial_movements_external → already imported.
+          if ((error as any).code === '23505') duplicates++
+          else throw error
+        } else imported++
+      }
+      return { imported, duplicates }
+    },
+
+    async getUnreconciled(query) {
+      const { pub } = getClients()
+      let qb = pub.from('financial_movements').select('*')
+        .not('external_source', 'is', null)
+        .is('reconciled_at', null)
+      if (query?.bankAccountId) qb = qb.eq('bank_account_id', query.bankAccountId)
+      if (query?.dateRange) qb = qb.gte('payment_date', query.dateRange.from).lte('payment_date', query.dateRange.to)
+      const { data } = await qb.order('payment_date', { ascending: false })
+      return (data ?? []).map((r: any) => snakeToCamel(r) as unknown as FinancialMovement)
+    },
+
+    async suggestReconciliation(bankMovementId) {
+      const { core, pub } = getClients()
+      const { data: line } = await pub.from('financial_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('*')
+        .is('external_source', null)
+        .is('reconciled_at', null)
+        .eq('direction', line.direction)
+        .gte('amount', round2(amount - tol))
+        .lte('amount', round2(amount + tol))
+        .neq('id', bankMovementId)
+        .limit(25)
+      const candidates = ((data ?? []) as any[]).map((r) => {
+        const amtDiff = Math.abs((Number(r.amount) || 0) - amount)
+        const amtScore = amount > 0 ? Math.max(0, 1 - amtDiff / amount) : 0
+        const refDate = r.due_date ?? r.payment_date
+        const days = lineDate && refDate
+          ? Math.abs((new Date(lineDate).getTime() - new Date(refDate).getTime()) / 86400000)
+          : 30
+        const dateScore = Math.max(0, 1 - days / 30)
+        return {
+          movement: snakeToCamel(r) as unknown as FinancialMovement,
+          score: round2(0.7 * amtScore + 0.3 * dateScore),
+        } as ReconciliationCandidate
+      }).sort((a, b) => b.score - a.score)
+      // Attach invoice contact names for display.
+      const invoiceIds = [...new Set(candidates.map((c) => c.movement.invoiceId).filter(Boolean))] as string[]
+      if (invoiceIds.length) {
+        const { data: orders } = await core.from('orders').select('id, reference_number, metadata').in('id', invoiceIds)
+        const byId = new Map<string, any>((orders ?? []).map((o: any) => [o.id, o]))
+        for (const c of candidates) {
+          const o = c.movement.invoiceId ? byId.get(c.movement.invoiceId) : undefined
+          if (o) c.invoice = { id: o.id, contactName: (o.metadata as any)?.contactName, fiscalNumber: o.reference_number } as Invoice
+        }
+      }
+      return candidates
+    },
+
+    async reconcileMovement(input) {
+      const { pub } = getClients()
+      const now = new Date().toISOString()
+      await pub.from('financial_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)
+      }
+    },
+
+    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)
+      if (line?.matched_movement_id) {
+        await pub.from('financial_movements').update({ reconciled_at: null }).eq('id', line.matched_movement_id)
+      }
+    },
   }
 
   return provider

package/src/data/types.ts

@@ -2,11 +2,13 @@ import type {
   Invoice, InvoiceItem, FinancialMovement, BankAccount,
   CashSession, PaymentMethod, PaymentMethodType, ChartOfAccountsNode,
   CardTransaction,
-  CreateInvoiceInput, PayMovementInput,
+  CreateInvoiceInput, PayMovementInput, CreateTransferInput, TransferResult,
   OpenCashSessionInput, CloseCashSessionInput, CreateBankAccountInput,
   InvoiceQuery, MovementQuery, StatementQuery,
-  PaginatedResult, FinancialSummary, StatementEntry, CashSessionSummary,
+  PaginatedResult, FinancialSummary, StatementResult, CashSessionSummary,
   DateRange,
+  ImportBankTransactionsInput, ImportBankTransactionsResult,
+  UnreconciledQuery, ReconciliationCandidate, ReconcileInput,
 } from '../types'
 
 export interface FinancialDataProvider {
@@ -23,6 +25,9 @@ export interface FinancialDataProvider {
   payMovement(input: PayMovementInput): Promise<FinancialMovement>
   cancelMovement(id: string): Promise<void>
 
+  // --- Transfers (between accounts) ---
+  createTransfer(input: CreateTransferInput): Promise<TransferResult>
+
   // --- Bank Accounts ---
   getBankAccounts(): Promise<BankAccount[]>
   createBankAccount(data: CreateBankAccountInput): Promise<BankAccount>
@@ -46,8 +51,22 @@ export interface FinancialDataProvider {
   getCardTransactions(dateRange?: DateRange): Promise<CardTransaction[]>
 
   // --- Statements ---
-  getStatement(query: StatementQuery): Promise<StatementEntry[]>
+  getStatement(query: StatementQuery): Promise<StatementResult>
 
   // --- Summary / Dashboard ---
   getSummary(dateRange?: DateRange): Promise<FinancialSummary>
+
+  // --- Reconciliation (conciliação) ---
+  // Optional: implemented by providers that back the matching UI. A bank
+  // connector imports lines; the SDK ReconciliationView reads/matches them.
+  /** Upsert normalized bank-statement lines as movements (idempotent by external id). */
+  importBankTransactions?(input: ImportBankTransactionsInput): Promise<ImportBankTransactionsResult>
+  /** Imported lines not yet reconciled (externalSource set, reconciledAt null). */
+  getUnreconciled?(query?: UnreconciledQuery): Promise<FinancialMovement[]>
+  /** Internal-movement candidates to match a given imported line, ranked by score. */
+  suggestReconciliation?(bankMovementId: string): Promise<ReconciliationCandidate[]>
+  /** Reconcile: link to an internal movement, or accept the line standalone. */
+  reconcileMovement?(input: ReconcileInput): Promise<void>
+  /** Undo a reconciliation. */
+  unreconcileMovement?(bankMovementId: string): Promise<void>
 }

package/src/index.ts

@@ -24,6 +24,8 @@ export function createSafeFinancialProvider(): FinancialDataProvider {
 import { financialRegistries } from './registries'
 import { financialLocales } from './locales'
 import { FinancialGeneralSettings } from './components/FinancialGeneralSettings'
+import { PersonStatementWidget } from './components/PersonStatementWidget'
+import { PluginSettingsPanel } from '@fayz-ai/saas'
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -64,6 +66,8 @@ export interface FinancialPluginOptions {
     statements?: boolean
     commissions?: boolean
     cards?: boolean
+    /** Bank reconciliation (conciliação). Defaults off — enable with a bank connector. */
+    reconciliation?: boolean
   }
   labels?: Partial<FinancialPluginLabels>
   currency?: {
@@ -155,6 +159,8 @@ function resolveConfig(options?: FinancialPluginOptions): ResolvedFinancialConfi
       statements: options?.modules?.statements !== false,
       commissions: options?.modules?.commissions !== false,
       cards: options?.modules?.cards !== false,
+      // Opt-in: only shown when an app explicitly enables reconciliation (bank connector present).
+      reconciliation: options?.modules?.reconciliation === true,
     },
     labels: { ...DEFAULT_LABELS, ...options?.labels },
     currency: { ...DEFAULT_CURRENCY, ...options?.currency },
@@ -183,6 +189,11 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
   const store = createFinancialStore(provider)
   const dashboardWidgets = createFinancialDashboardWidgets({ config, provider, store })
 
+  // Per-person statement tab (account_central-style): bound to this plugin's provider.
+  const PersonStatementBound: React.FC<any> = (props) =>
+    React.createElement(PersonStatementWidget, { person: props.item, provider, config })
+  PersonStatementBound.displayName = 'FinancialPersonStatement'
+
   const PageComponent: React.FC<any> = () =>
     React.createElement(FinancialPage, { config, provider, store, registries: financialRegistries })
 
@@ -218,7 +229,15 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
         permission: { feature: 'financial', action: 'read' as const },
       },
     ],
-    widgets: [],
+    widgets: [
+      {
+        id: 'financial-person-statement',
+        zone: 'person.detail.financial',
+        component: PersonStatementBound as unknown as React.ComponentType<unknown>,
+        order: 0,
+        permission: { feature: 'financial', action: 'read' as const },
+      },
+    ],
     dashboardWidgets,
     aiTools: [
       {
@@ -290,7 +309,14 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
         icon: 'DollarSign',
         component: (() => {
           const FinancialSettingsTab: React.FC = () =>
-            React.createElement(FinancialGeneralSettings)
+            React.createElement(PluginSettingsPanel, {
+              title: 'Financial Settings',
+              subtitle: 'Payment methods, accounts, and configurations',
+              generalSettings: React.createElement(FinancialGeneralSettings),
+              registries: financialRegistries,
+              hostPluginId: 'financial',
+              routeBase: '/settings/financial',
+            })
           FinancialSettingsTab.displayName = 'FinancialSettingsTab'
           return FinancialSettingsTab as unknown as React.ComponentType<unknown>
         })(),