@fayz-ai/plugin-financial 0.1.2 → 0.1.4

package/src/locales/en.ts

@@ -128,6 +128,21 @@ export const en: Record<string, string> = {
   "financial.nav.rules": "Rules",
   "financial.nav.statements": "Statements",
   "financial.nav.summary": "Summary",
+  "financial.reconciliation.title": "Reconciliation",
+  "financial.reconciliation.subtitle": "Match imported bank lines to your movements",
+  "financial.reconciliation.pending": "{{count}} to reconcile",
+  "financial.reconciliation.allDone": "All caught up",
+  "financial.reconciliation.empty": "Nothing to reconcile",
+  "financial.reconciliation.emptyHint": "Imported bank transactions will appear here for matching.",
+  "financial.reconciliation.bankLines": "Bank lines",
+  "financial.reconciliation.candidates": "Suggested matches",
+  "financial.reconciliation.selectLine": "Select a bank line to see suggested matches",
+  "financial.reconciliation.noCandidates": "No suggested matches for this line",
+  "financial.reconciliation.match": "Match",
+  "financial.reconciliation.accept": "Accept as new",
+  "financial.reconciliation.acceptHint": "No internal counterpart — keep as a standalone entry",
+  "financial.reconciliation.matchScore": "{{score}}% match",
+  "financial.reconciliation.refresh": "Refresh",
   "financial.onboarding.back": "Back",
   "financial.onboarding.configureHint": "You can configure this in detail from the Settings gear icon inside the Financial module.",
   "financial.onboarding.getStarted": "Get Started",
@@ -192,6 +207,8 @@ export const en: Record<string, string> = {
   "financial.settingsPage.title": "Financial Settings",
   "financial.payment.noMethods": "No payment methods configured.",
   "financial.payment.configureMethods": "Set up payment methods",
+  "financial.payment.noAccounts": "No compatible account. Create one in Settings.",
+  "financial.payment.configureAccounts": "Set up accounts",
   "financial.statements.account": "Account",
   "financial.statements.from": "From",
   "financial.statements.noTransactions": "No transactions in this period",
@@ -328,4 +345,63 @@ export const en: Record<string, string> = {
   "financial.movements.title": "Movements",
   "financial.bankAccounts.title": "Bank Accounts",
   "financial.settings.title": "Financial Settings",
+  // Settings registry tabs
+  "registry.payment-methods": "Payment Methods",
+  "registry.payment-methods.description": "Configured payment methods with fees and installment rules",
+  "registry.bank-accounts": "Accounts",
+  "registry.bank-accounts.description": "Bank accounts, cash registers, credit cards, and digital wallets",
+  "registry.chart-of-accounts": "Chart of Accounts",
+  "registry.chart-of-accounts.description": "Hierarchical chart of accounts for categorizing transactions",
+  "registry.cost-centers": "Cost Centers",
+  "registry.cost-centers.description": "Cost centers for expense tracking and departmental budgets",
+  "registry.commission-rules": "Commission Rules",
+  "registry.commission-rules.description": "Commission rules for service and product revenue sharing",
+  "registry.price-tables": "Price Tables",
+  "registry.price-tables.description": "Price tables for sale and cost pricing",
+  "registry.price-variations": "Price Variations",
+  "registry.price-variations.description": "Discount and surcharge rules for pricing",
+  "registry.payment-method-types": "Payment Types",
+  "registry.payment-method-types.description": "System payment types (cash, card, PIX, etc.)",
+  "registry.card-brands": "Card Brands",
+  "registry.card-brands.description": "Credit and debit card brands",
+  // Statements / extract
+  "financial.statements.columnDate": "Date",
+  "financial.statements.columnDescription": "Description",
+  "financial.statements.columnDebit": "Debit",
+  "financial.statements.columnCredit": "Credit",
+  "financial.statements.columnFee": "Fee",
+  "financial.statements.columnBalance": "Balance",
+  "financial.statements.columnMethod": "Method",
+  "financial.statements.columnDoc": "Document",
+  "financial.statements.installmentShort": "Inst. {{n}}",
+  "financial.statements.viewInvoice": "View invoice",
+  "financial.person.empty": "No financial activity for this contact yet",
+  "financial.statements.opening": "Opening balance",
+  "financial.statements.closing": "Closing balance",
+  "financial.statements.currentBalance": "Current balance",
+  "financial.statements.totalCredits": "Credits",
+  "financial.statements.totalDebits": "Debits",
+  "financial.statements.totalFees": "Fees",
+  "financial.statements.net": "Net",
+  "financial.statements.transfer": "Transfer",
+  "financial.statements.reconciled": "Reconciled with the bank statement",
+  "financial.statements.imported": "Imported from the bank · not reconciled",
+  "financial.statements.reconciledWith": "Reconciled with {{ref}}",
+  "financial.statements.newTransfer": "New Transfer",
+  // Transfer dialog
+  "financial.transfer.title": "Transfer Between Accounts",
+  "financial.transfer.from": "From account",
+  "financial.transfer.to": "To account",
+  "financial.transfer.amount": "Amount",
+  "financial.transfer.date": "Date",
+  "financial.transfer.notes": "Notes",
+  "financial.transfer.optionalNotes": "Optional notes...",
+  "financial.transfer.selectAccount": "Select account...",
+  "financial.transfer.submit": "Transfer",
+  "financial.transfer.processing": "Transferring...",
+  "financial.transfer.cancel": "Cancel",
+  "financial.transfer.created": "Transfer recorded",
+  "financial.transfer.failed": "Failed to record transfer",
+  "financial.transfer.sameAccount": "Source and destination must differ",
+  "financial.transfer.invalidAmount": "Amount must be greater than zero",
 }

package/src/locales/pt-BR.ts

@@ -128,6 +128,21 @@ export const ptBR: Record<string, string> = {
   "financial.nav.rules": "Regras",
   "financial.nav.statements": "Extratos",
   "financial.nav.summary": "Resumo",
+  "financial.reconciliation.title": "Conciliação",
+  "financial.reconciliation.subtitle": "Concilie as linhas importadas do banco com seus lançamentos",
+  "financial.reconciliation.pending": "{{count}} para conciliar",
+  "financial.reconciliation.allDone": "Tudo conciliado",
+  "financial.reconciliation.empty": "Nada para conciliar",
+  "financial.reconciliation.emptyHint": "As transações bancárias importadas aparecem aqui para conciliação.",
+  "financial.reconciliation.bankLines": "Linhas do banco",
+  "financial.reconciliation.candidates": "Correspondências sugeridas",
+  "financial.reconciliation.selectLine": "Selecione uma linha do banco para ver as sugestões",
+  "financial.reconciliation.noCandidates": "Nenhuma correspondência sugerida para esta linha",
+  "financial.reconciliation.match": "Conciliar",
+  "financial.reconciliation.accept": "Aceitar como novo",
+  "financial.reconciliation.acceptHint": "Sem contrapartida interna — manter como lançamento avulso",
+  "financial.reconciliation.matchScore": "{{score}}% compatível",
+  "financial.reconciliation.refresh": "Atualizar",
   "financial.onboarding.back": "Voltar",
   "financial.onboarding.configureHint": "Você pode configurar isso em detalhes pelo ícone de Configurações dentro do módulo Financeiro.",
   "financial.onboarding.getStarted": "Começar",
@@ -192,6 +207,8 @@ export const ptBR: Record<string, string> = {
   "financial.settingsPage.title": "Configurações Financeiras",
   "financial.payment.noMethods": "Nenhuma forma de pagamento configurada.",
   "financial.payment.configureMethods": "Configurar formas de pagamento",
+  "financial.payment.noAccounts": "Nenhuma conta compatível. Crie uma nas Configurações.",
+  "financial.payment.configureAccounts": "Configurar contas",
   "financial.statements.account": "Conta",
   "financial.statements.from": "De",
   "financial.statements.noTransactions": "Sem transações neste período",
@@ -328,4 +345,63 @@ export const ptBR: Record<string, string> = {
   "financial.movements.title": "Movimentações",
   "financial.bankAccounts.title": "Contas Bancárias",
   "financial.settings.title": "Configurações Financeiras",
+  // Abas de registros nas configurações
+  "registry.payment-methods": "Formas de Pagamento",
+  "registry.payment-methods.description": "Formas de pagamento configuradas com taxas e regras de parcelamento",
+  "registry.bank-accounts": "Contas",
+  "registry.bank-accounts.description": "Contas bancárias, caixas, cartões de crédito e carteiras digitais",
+  "registry.chart-of-accounts": "Plano de Contas",
+  "registry.chart-of-accounts.description": "Plano de contas hierárquico para categorizar transações",
+  "registry.cost-centers": "Centros de Custo",
+  "registry.cost-centers.description": "Centros de custo para controle de despesas e orçamentos por departamento",
+  "registry.commission-rules": "Regras de Comissão",
+  "registry.commission-rules.description": "Regras de comissão para serviços e produtos",
+  "registry.price-tables": "Tabelas de Preço",
+  "registry.price-tables.description": "Tabelas de preço de venda e custo",
+  "registry.price-variations": "Variações de Preço",
+  "registry.price-variations.description": "Regras de desconto e acréscimo de preços",
+  "registry.payment-method-types": "Tipos de Pagamento",
+  "registry.payment-method-types.description": "Tipos de pagamento do sistema (dinheiro, cartão, PIX, etc.)",
+  "registry.card-brands": "Bandeiras de Cartão",
+  "registry.card-brands.description": "Bandeiras de cartão de crédito e débito",
+  // Extrato
+  "financial.statements.columnDate": "Data",
+  "financial.statements.columnDescription": "Descrição",
+  "financial.statements.columnDebit": "Débito",
+  "financial.statements.columnCredit": "Crédito",
+  "financial.statements.columnFee": "Taxa",
+  "financial.statements.columnBalance": "Saldo",
+  "financial.statements.columnMethod": "Forma",
+  "financial.statements.columnDoc": "Documento",
+  "financial.statements.installmentShort": "Parc. {{n}}",
+  "financial.statements.viewInvoice": "Ver fatura",
+  "financial.person.empty": "Nenhuma atividade financeira para este contato ainda",
+  "financial.statements.opening": "Saldo inicial",
+  "financial.statements.closing": "Saldo final",
+  "financial.statements.currentBalance": "Saldo atual",
+  "financial.statements.totalCredits": "Créditos",
+  "financial.statements.totalDebits": "Débitos",
+  "financial.statements.totalFees": "Taxas",
+  "financial.statements.net": "Líquido",
+  "financial.statements.transfer": "Transferência",
+  "financial.statements.reconciled": "Conciliado com o extrato bancário",
+  "financial.statements.imported": "Importado do banco · não conciliado",
+  "financial.statements.reconciledWith": "Conciliado com {{ref}}",
+  "financial.statements.newTransfer": "Nova Transferência",
+  // Diálogo de transferência
+  "financial.transfer.title": "Transferência entre Contas",
+  "financial.transfer.from": "Conta de origem",
+  "financial.transfer.to": "Conta de destino",
+  "financial.transfer.amount": "Valor",
+  "financial.transfer.date": "Data",
+  "financial.transfer.notes": "Observações",
+  "financial.transfer.optionalNotes": "Observações opcionais...",
+  "financial.transfer.selectAccount": "Selecione a conta...",
+  "financial.transfer.submit": "Transferir",
+  "financial.transfer.processing": "Transferindo...",
+  "financial.transfer.cancel": "Cancelar",
+  "financial.transfer.created": "Transferência registrada",
+  "financial.transfer.failed": "Falha ao registrar transferência",
+  "financial.transfer.sameAccount": "Origem e destino devem ser diferentes",
+  "financial.transfer.invalidAmount": "O valor deve ser maior que zero",
 }

package/src/migrations/006_extract_fee_amount.sql

@@ -0,0 +1,20 @@
+-- ---------------------------------------------------------------------------
+-- Financial extract (extrato): net card settlement + transfers
+-- ---------------------------------------------------------------------------
+-- Adds the processing/MDR fee column used by the bank/cash account statement so
+-- the running balance reflects the NET cash that actually lands in the account.
+--   gross    = paid_amount (settles the receivable/payable)
+--   net cash = paid_amount - fee_amount  (credits only; v1 has no fee on debits)
+ALTER TABLE public.financial_movements
+  ADD COLUMN IF NOT EXISTS fee_amount numeric(14,2) NOT NULL DEFAULT 0;
+
+COMMENT ON COLUMN public.financial_movements.fee_amount IS
+  'Processing/MDR fee deducted at settlement. Net cash impact = paid_amount - fee_amount (credit). v1: same-day net, no D+N settlement-date modeling.';
+
+CREATE INDEX IF NOT EXISTS idx_financial_movements_statement
+  ON public.financial_movements (bank_account_id, payment_date)
+  WHERE status IN ('paid', 'partial');
+
+-- Transfers between accounts = a debit row (source) + credit row (destination),
+-- both status='paid', movement_kind='transfer', correlated via metadata jsonb:
+--   metadata->>'transferId' | 'transferRole' ('out'|'in') | 'counterAccountId'

package/src/migrations/006_rls_policies.sql

@@ -0,0 +1,37 @@
+-- Financial Plugin: RLS policies + grants for ALL base tables.
+--
+-- The base migrations (001/002/003) ENABLE row-level security but relied on an
+-- external `project_rls.sql` auto-detection step to create the actual policies.
+-- That step does not run in the Drizzle/companion pipeline, so every table
+-- except financial_movements was RLS-enabled with NO policy → all inserts denied
+-- ("new row violates row-level security policy"). This creates the canonical
+-- per-tenant policies idempotently. Re-running is a no-op (IF NOT EXISTS guards;
+-- financial_movements policies from 004 are skipped).
+--
+-- Canonical RLS form: tenant_id IN (SELECT public.user_tenant_ids()).
+
+DO $$
+DECLARE t text;
+BEGIN
+  FOR t IN SELECT unnest(ARRAY[
+    'payment_method_types','payment_methods','bank_accounts',
+    'cash_register_sessions','financial_movements',
+    'chart_of_accounts','cost_centers','card_brands'
+  ])
+  LOOP
+    EXECUTE format('ALTER TABLE public.%I ENABLE ROW LEVEL SECURITY', t);
+    EXECUTE format('GRANT SELECT, INSERT, UPDATE, DELETE ON public.%I TO authenticated', t);
+    IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname='public' AND tablename=t AND policyname=t||'_select') THEN
+      EXECUTE format('CREATE POLICY %I ON public.%I FOR SELECT TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids()))', t||'_select', t);
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname='public' AND tablename=t AND policyname=t||'_insert') THEN
+      EXECUTE format('CREATE POLICY %I ON public.%I FOR INSERT TO authenticated WITH CHECK (tenant_id IN (SELECT public.user_tenant_ids()))', t||'_insert', t);
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname='public' AND tablename=t AND policyname=t||'_update') THEN
+      EXECUTE format('CREATE POLICY %I ON public.%I FOR UPDATE TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids()))', t||'_update', t);
+    END IF;
+    IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname='public' AND tablename=t AND policyname=t||'_delete') THEN
+      EXECUTE format('CREATE POLICY %I ON public.%I FOR DELETE TO authenticated USING (tenant_id IN (SELECT public.user_tenant_ids()))', t||'_delete', t);
+    END IF;
+  END LOOP;
+END $$;

package/src/migrations/007_reconciliation.sql

@@ -0,0 +1,32 @@
+-- ---------------------------------------------------------------------------
+-- Reconciliation (conciliação): bank-statement lines ↔ internal movements
+-- ---------------------------------------------------------------------------
+-- An integration (e.g. open banking) imports bank-statement lines as
+-- financial_movements tagged with (external_source, external_id). The matching
+-- UI then links each imported line to the internal movement it settles, or
+-- accepts it standalone. These columns make a movement carry its bank-line
+-- identity and its reconciliation state.
+--   external_source / external_id : the bank line's provider + unique id
+--   reconciled_at                 : when the line was matched/accepted (NULL = pending)
+--   matched_movement_id           : the internal movement this line reconciles (NULL = standalone)
+ALTER TABLE public.financial_movements
+  ADD COLUMN IF NOT EXISTS external_id text,
+  ADD COLUMN IF NOT EXISTS external_source text,
+  ADD COLUMN IF NOT EXISTS reconciled_at timestamptz,
+  ADD COLUMN IF NOT EXISTS matched_movement_id uuid
+    REFERENCES public.financial_movements(id) ON DELETE SET NULL;
+
+COMMENT ON COLUMN public.financial_movements.external_source IS
+  'Provider of an imported bank-statement line (e.g. plugbank, inter). NULL for app-native movements.';
+COMMENT ON COLUMN public.financial_movements.external_id IS
+  'Provider-unique id of the imported bank line. Forms the import idempotency key with external_source.';
+
+-- Idempotency: a given bank line imports at most once per tenant.
+CREATE UNIQUE INDEX IF NOT EXISTS uq_financial_movements_external
+  ON public.financial_movements (tenant_id, external_source, external_id)
+  WHERE external_id IS NOT NULL AND external_source IS NOT NULL;
+
+-- Fast lookup of imported-but-unreconciled lines for the matching screen.
+CREATE INDEX IF NOT EXISTS idx_financial_movements_unreconciled
+  ON public.financial_movements (tenant_id, payment_date)
+  WHERE external_source IS NOT NULL AND reconciled_at IS NULL;

package/src/migrations/008_split_payment_movements.sql

@@ -0,0 +1,29 @@
+-- Split bill (obligation) vs payment (cash event).
+-- Each payment is now its own movement_kind='payment' row (one per cash event), so
+-- two payments on one installment show as two extract rows instead of one summed row.
+-- Bills stay pure obligations; v_invoice_balances already filters movement_kind='bill',
+-- so the new payment rows don't affect invoice balances. Backfill is idempotent.
+-- Requires fee_amount (006_extract_fee_amount.sql).
+
+INSERT INTO public.financial_movements
+  (tenant_id, invoice_id, direction, movement_kind, amount, paid_amount, fee_amount, status,
+   due_date, payment_date, installment_number, payment_method_id, payment_method_type_id,
+   bank_account_id, cash_session_id, card_brand, card_installments, notes, metadata)
+SELECT
+  b.tenant_id, b.invoice_id, b.direction, 'payment', b.paid_amount, b.paid_amount,
+  COALESCE(b.fee_amount, 0), 'paid',
+  b.due_date, COALESCE(b.payment_date, b.updated_at::date, CURRENT_DATE), b.installment_number,
+  b.payment_method_id, b.payment_method_type_id, b.bank_account_id, b.cash_session_id,
+  b.card_brand, b.card_installments, b.notes,
+  jsonb_build_object('backfilledFromBill', b.id)
+FROM public.financial_movements b
+WHERE b.movement_kind = 'bill' AND b.paid_amount > 0
+  AND NOT EXISTS (
+    SELECT 1 FROM public.financial_movements p
+    WHERE p.movement_kind = 'payment' AND p.metadata->>'backfilledFromBill' = b.id::text
+  );
+
+UPDATE public.financial_movements
+SET payment_date = NULL, bank_account_id = NULL, payment_method_id = NULL,
+    payment_method_type_id = NULL, cash_session_id = NULL, card_brand = NULL, card_installments = NULL
+WHERE movement_kind = 'bill';

package/src/registries.ts

@@ -31,7 +31,9 @@ const paymentMethodEntity: EntityDef = {
   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 },
+    // FK to the seeded payment_method_types catalog — load real ids at runtime
+    // (a static enum select would write the string into the uuid column).
+    { key: 'paymentMethodTypeId', label: 'Type', type: 'relation', relation: { table: 'payment_method_types', labelField: 'name' }, 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 },

package/src/store.ts

@@ -5,9 +5,9 @@ import type { FinancialDataProvider } from './data/types'
 import type {
   Invoice, FinancialMovement, BankAccount, CashSession,
   PaymentMethod, PaymentMethodType, CardTransaction,
-  FinancialSummary, StatementEntry,
+  FinancialSummary, StatementResult,
   InvoiceQuery, MovementQuery, StatementQuery,
-  CreateInvoiceInput, PayMovementInput,
+  CreateInvoiceInput, PayMovementInput, CreateTransferInput,
   OpenCashSessionInput, CloseCashSessionInput,
   DateRange,
 } from './types'
@@ -39,8 +39,9 @@ export interface FinancialUIState {
   summary: FinancialSummary | null
   summaryLoading: boolean
 
-  statementEntries: StatementEntry[]
+  statement: StatementResult | null
   statementLoading: boolean
+  statementQuery: StatementQuery | null
 
   cardTransactions: CardTransaction[]
   cardsLoading: boolean
@@ -55,6 +56,7 @@ export interface FinancialUIState {
   fetchCardTransactions(dateRange?: DateRange): Promise<void>
   createInvoice(input: CreateInvoiceInput): Promise<Invoice>
   payMovement(input: PayMovementInput): Promise<void>
+  createTransfer(input: CreateTransferInput): Promise<void>
   cancelInvoice(invoiceId: string): Promise<void>
   openCashSession(input: OpenCashSessionInput): Promise<CashSession>
   closeCashSession(input: CloseCashSessionInput): Promise<CashSession>
@@ -87,8 +89,9 @@ export function createFinancialStore(provider: FinancialDataProvider): StoreApi<
     summary: null,
     summaryLoading: false,
 
-    statementEntries: [],
+    statement: null,
     statementLoading: false,
+    statementQuery: null,
 
     cardTransactions: [],
     cardsLoading: false,
@@ -137,9 +140,9 @@ export function createFinancialStore(provider: FinancialDataProvider): StoreApi<
 
     async fetchStatement(query) {
       return dedup('fin:statement:' + JSON.stringify(query), async () => {
-        set({ statementLoading: true })
-        const statementEntries = await provider.getStatement(query)
-        set({ statementEntries, statementLoading: false })
+        set({ statementLoading: true, statementQuery: query })
+        const statement = await provider.getStatement(query)
+        set({ statement, statementLoading: false })
       })
     },
 
@@ -179,6 +182,23 @@ export function createFinancialStore(provider: FinancialDataProvider): StoreApi<
       }
     },
 
+    async createTransfer(input) {
+      try {
+        await provider.createTransfer(input)
+        const query = get().statementQuery
+        const [bankAccounts, summary, statement] = await Promise.all([
+          provider.getBankAccounts(),
+          provider.getSummary(),
+          query ? provider.getStatement(query) : Promise.resolve(get().statement),
+        ])
+        set({ bankAccounts, summary, statement })
+        toast.success('Transfer recorded')
+      } catch (err: any) {
+        toast.error('Failed to record transfer', { description: err?.message })
+        throw err
+      }
+    },
+
     async cancelInvoice(invoiceId) {
       try {
         await provider.cancelInvoice(invoiceId)

package/src/types.ts

@@ -100,10 +100,21 @@ export interface FinancialMovement {
   cashSessionId?: string
   cardBrand?: string
   cardInstallments?: number
+  /** Processing/MDR fee deducted at settlement (net cash = paidAmount - feeAmount for credits) */
+  feeAmount?: number
   debitAccountId?: string
   creditAccountId?: string
   notes?: string
   metadata?: Record<string, unknown>
+  // --- Reconciliation (conciliação) ---
+  /** Provider of an imported bank-statement line (set on imported movements only) */
+  externalSource?: string
+  /** Provider-unique id of the imported bank line (idempotency key with externalSource) */
+  externalId?: string
+  /** When this movement was reconciled — matched or accepted (undefined = pending) */
+  reconciledAt?: string
+  /** For an imported bank line: the internal movement it was matched to */
+  matchedMovementId?: string
   tenantId: string
   createdAt: string
   updatedAt: string
@@ -258,6 +269,8 @@ export interface PayMovementInput {
   cashSessionId?: string
   cardBrand?: string
   cardInstallments?: number
+  /** Free-text payment description / memo shown in the extract */
+  notes?: string
 }
 
 export interface OpenCashSessionInput {
@@ -320,10 +333,27 @@ export interface MovementQuery {
 }
 
 export interface StatementQuery {
-  bankAccountId: string
+  /** Omit (or pass undefined) for a consolidated "All accounts" statement */
+  bankAccountId?: string
   dateRange: DateRange
 }
 
+export interface CreateTransferInput {
+  fromAccountId: string
+  toAccountId: string
+  amount: number
+  /** YYYY-MM-DD — becomes payment_date on both ledger legs */
+  date: string
+  notes?: string
+}
+
+export interface TransferResult {
+  /** Shared correlation id stored in both legs' metadata */
+  transferId: string
+  debitMovementId: string
+  creditMovementId: string
+}
+
 export interface PaginatedResult<T> {
   data: T[]
   total: number
@@ -345,10 +375,53 @@ export interface FinancialSummary {
   overduePayableAmount: number
 }
 
+/** What a statement row represents — a normal movement or one leg of a transfer */
+export type StatementEntryKind = 'movement' | 'transfer-in' | 'transfer-out'
+
 export interface StatementEntry {
   movement: FinancialMovement
   invoice?: Invoice
+  /** NET cash running balance after this row */
   runningBalance: number
+  /** Amount that settled the receivable/payable (= paidAmount) */
+  gross: number
+  /** Processing/MDR fee deducted (>= 0) */
+  fee: number
+  /** Cash impact: gross - fee for credit; gross for debit */
+  net: number
+  entryKind: StatementEntryKind
+  /** For transfers: the other side's account */
+  counterAccountId?: string
+  counterAccountName?: string
+  /** When this row is a reconciled bank line, the internal movement it was matched to. */
+  reconciledWith?: {
+    movementId: string
+    description?: string
+    invoiceId?: string
+    fiscalNumber?: string
+    contactName?: string
+  }
+}
+
+/** Full statement result with header context (opening/closing balance + period totals) */
+export interface StatementResult {
+  entries: StatementEntry[]
+  /** Balance as of start-of-day dateFrom (excludes in-range rows) */
+  openingBalance: number
+  /** openingBalance + net of all in-range rows */
+  closingBalance: number
+  /** Sum of NET credits in range */
+  totalCredits: number
+  /** Sum of NET debits (cash out) in range */
+  totalDebits: number
+  /** Sum of fees in range */
+  totalFees: number
+  /** totalCredits - totalDebits */
+  net: number
+  /** Echo of the queried account; undefined for consolidated */
+  accountId?: string
+  /** Ledger-computed current balance of the selected account (as of today) */
+  accountCurrentBalance?: number
 }
 
 export interface CashSessionSummary {
@@ -357,3 +430,55 @@ export interface CashSessionSummary {
   totalInflow: number
   totalOutflow: number
 }
+
+// ============================================================
+// RECONCILIATION (conciliação)
+// ============================================================
+
+/** A normalized bank-statement line, ready to import as a financial movement. */
+export interface BankStatementLine {
+  /** Provider-unique transaction id (idempotency key with externalSource) */
+  externalId: string
+  /** Provider that produced the line (e.g. 'plugbank', 'inter') */
+  externalSource: string
+  /** credit = money in, debit = money out */
+  direction: TransactionDirection
+  amount: number
+  /** YYYY-MM-DD settlement date */
+  date: string
+  description: string
+  /** Account the line belongs to; falls back to the import's bankAccountId */
+  bankAccountId?: string
+}
+
+export interface ImportBankTransactionsInput {
+  /** Default account for lines that don't carry their own */
+  bankAccountId?: string
+  lines: BankStatementLine[]
+}
+
+export interface ImportBankTransactionsResult {
+  imported: number
+  /** Lines skipped because they were already imported (idempotency) */
+  duplicates: number
+}
+
+export interface UnreconciledQuery {
+  bankAccountId?: string
+  dateRange?: DateRange
+}
+
+/** A candidate internal movement to reconcile an imported bank line against. */
+export interface ReconciliationCandidate {
+  movement: FinancialMovement
+  invoice?: Invoice
+  /** 0..1 confidence from amount + date proximity */
+  score: number
+}
+
+export interface ReconcileInput {
+  /** The imported bank-line movement (externalSource set) */
+  bankMovementId: string
+  /** Internal movement to link; omit to accept the line standalone */
+  matchedMovementId?: string
+}