@fayz-ai/plugin-financial 0.1.6 → 0.2.0

package/src/data/supabase.ts

@@ -2,7 +2,7 @@ import type { FinancialDataProvider } from './types'
 import type {
   Invoice, InvoiceItem, FinancialMovement, BankAccount,
   CashSession, PaymentMethod, PaymentMethodType, ChartOfAccountsNode,
-  CardTransaction,
+  CostCenter, CardTransaction,
   CreateInvoiceInput, PayMovementInput, CreateTransferInput, TransferResult,
   OpenCashSessionInput, CloseCashSessionInput, CreateBankAccountInput,
   InvoiceQuery, MovementQuery, StatementQuery,
@@ -116,6 +116,24 @@ function round2(n: number): number {
   return Math.round(n * 100) / 100
 }
 
+async function findOrderIdsByItemMetadata(
+  core: any,
+  filters: { accountId?: string; costCenterId?: string },
+): Promise<string[] | undefined> {
+  if (!filters.accountId && !filters.costCenterId) return undefined
+
+  let qb = core.from('order_items').select('order_id')
+  if (filters.accountId) qb = qb.filter('metadata->>accountId', 'eq', filters.accountId)
+  if (filters.costCenterId) qb = qb.filter('metadata->>costCenterId', 'eq', filters.costCenterId)
+
+  const { data } = await qb
+  const ids: string[] = []
+  for (const row of (data ?? []) as Array<{ order_id?: unknown }>) {
+    if (typeof row.order_id === 'string' && row.order_id.length > 0) ids.push(row.order_id)
+  }
+  return Array.from(new Set(ids))
+}
+
 /** 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
@@ -151,6 +169,14 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
         const statuses = Array.isArray(query.status) ? query.status : [query.status]
         qb = qb.in('status', statuses)
       }
+      const itemScopedOrderIds = await findOrderIdsByItemMetadata(core, {
+        accountId: query.accountId,
+        costCenterId: query.costCenterId,
+      })
+      if (itemScopedOrderIds) {
+        if (itemScopedOrderIds.length === 0) return { data: [], total: 0 }
+        qb = qb.in('id', itemScopedOrderIds)
+      }
       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)
@@ -224,6 +250,8 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
           unitPrice: i.unitPrice ?? 0, totalAmount: i.total ?? 0,
           discount: i.discount ?? 0, surcharge: 0,
           referenceId: i.productId ?? i.serviceId,
+          accountId: i.metadata?.accountId,
+          costCenterId: i.metadata?.costCenterId,
           createdAt: i.createdAt,
         } as InvoiceItem
       })
@@ -263,7 +291,12 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
             discount: item.discount ?? 0,
             total: item.quantity * item.unitPrice - (item.discount ?? 0) + (item.surcharge ?? 0),
             sort_order: i,
-            metadata: { itemKind: item.itemKind, referenceId: item.referenceId },
+            metadata: {
+              itemKind: item.itemKind,
+              referenceId: item.referenceId,
+              accountId: item.accountId,
+              costCenterId: item.costCenterId,
+            },
           }))
         )
       }
@@ -547,6 +580,12 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       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')
+      return (data ?? []).map((r: any) => snakeToCamel(r) as unknown as CostCenter)
+    },
+
     // --- Card Transactions ---
     async getCardTransactions(dateRange?: DateRange): Promise<CardTransaction[]> {
       const { core, pub } = getClients()
@@ -709,7 +748,11 @@ export function createSupabaseFinancialProvider(): FinancialDataProvider {
       const overdueCredit = unpaidCredit.filter((m: any) => m.status === 'overdue' || m.due_date < today)
       const overdueDebit = unpaidDebit.filter((m: any) => m.status === 'overdue' || m.due_date < today)
 
-      const monthStart = today.slice(0, 7) + '-01'
+      // Monthly cash flow = a trailing 30-day rolling window (not calendar
+      // month-to-date, which reads empty in the first days of a month).
+      const monthAgo = new Date()
+      monthAgo.setDate(monthAgo.getDate() - 30)
+      const monthStart = monthAgo.toISOString().slice(0, 10)
       // 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)
 

package/src/data/types.ts

@@ -1,7 +1,7 @@
 import type {
   Invoice, InvoiceItem, FinancialMovement, BankAccount,
   CashSession, PaymentMethod, PaymentMethodType, ChartOfAccountsNode,
-  CardTransaction,
+  CostCenter, CardTransaction,
   CreateInvoiceInput, PayMovementInput, CreateTransferInput, TransferResult,
   OpenCashSessionInput, CloseCashSessionInput, CreateBankAccountInput,
   InvoiceQuery, MovementQuery, StatementQuery,
@@ -46,6 +46,7 @@ export interface FinancialDataProvider {
 
   // --- Chart of Accounts ---
   getChartOfAccounts(): Promise<ChartOfAccountsNode[]>
+  getCostCenters(): Promise<CostCenter[]>
 
   // --- Card Transactions ---
   getCardTransactions(dateRange?: DateRange): Promise<CardTransaction[]>

package/src/index.ts

@@ -1,5 +1,5 @@
 import React from 'react'
-import type { PluginManifest, PluginScope, VerticalId } from '@fayz-ai/core'
+import type { PluginManifest, PluginRegistryDef, PluginScope, VerticalId } from '@fayz-ai/core'
 import type { EntityLookupMap } from '@fayz-ai/saas'
 import { FinancialPage } from './FinancialPage'
 import { createFinancialDashboardWidgets } from './views/dashboardWidgets'
@@ -75,6 +75,13 @@ export interface FinancialPluginOptions {
     locale?: string
     symbol?: string
   }
+  /**
+   * Show the plugin's own quick-add affordances (the "New transaction" + "Send
+   * receipt" header buttons and, on mobile, the FAB). Opt-in (default: false) so
+   * hosts that already surface a "New" menu / global center-action don't render
+   * redundant controls. The shared quick-add sheet still opens via openQuickAdd().
+   */
+  quickAdd?: boolean
   navPosition?: number
   navSection?: 'main' | 'secondary'
   scope?: PluginScope
@@ -109,6 +116,9 @@ export interface FinancialPluginOptions {
   /** Contact/person lookup for "Pay to" / "Receive from" fields. Queries persons archetype. */
   contactLookup?: import('@fayz-ai/saas').EntityLookup
 
+  /** App-owned registries shown under /settings/financial Properties. */
+  settingsRegistries?: PluginRegistryDef[]
+
   /** Callback when user clicks a booking link on an invoice. Receives the order ID. */
   onBookingClick?: (orderId: string) => void
 }
@@ -162,6 +172,8 @@ function resolveConfig(options?: FinancialPluginOptions): ResolvedFinancialConfi
       // Opt-in: only shown when an app explicitly enables reconciliation (bank connector present).
       reconciliation: options?.modules?.reconciliation === true,
     },
+    // Opt-in: only render the plugin's own quick-add buttons/FAB when the host asks.
+    quickAdd: options?.quickAdd === true,
     labels: { ...DEFAULT_LABELS, ...options?.labels },
     currency: { ...DEFAULT_CURRENCY, ...options?.currency },
     itemTypes: options?.itemTypes ?? DEFAULT_ITEM_TYPES,
@@ -188,6 +200,7 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
   const provider = options?.dataProvider ?? createSafeFinancialProvider()
   const store = createFinancialStore(provider)
   const dashboardWidgets = createFinancialDashboardWidgets({ config, provider, store })
+  const registries = [...financialRegistries, ...(options?.settingsRegistries ?? [])]
 
   // Per-person statement tab (account_central-style): bound to this plugin's provider.
   const PersonStatementBound: React.FC<any> = (props) =>
@@ -195,7 +208,7 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
   PersonStatementBound.displayName = 'FinancialPersonStatement'
 
   const PageComponent: React.FC<any> = () =>
-    React.createElement(FinancialPage, { config, provider, store, registries: financialRegistries })
+    React.createElement(FinancialPage, { config, provider, store, registries })
 
   return {
     id: 'financial',
@@ -301,7 +314,7 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
         ],
       },
     ],
-    registries: financialRegistries,
+    registries,
     settings: [
       {
         id: 'financial',
@@ -313,7 +326,7 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
               title: 'Financial Settings',
               subtitle: 'Payment methods, accounts, and configurations',
               generalSettings: React.createElement(FinancialGeneralSettings),
-              registries: financialRegistries,
+              registries,
               hostPluginId: 'financial',
               routeBase: '/settings/financial',
             })
@@ -331,3 +344,10 @@ export function createFinancialPlugin(options?: FinancialPluginOptions): PluginM
 // Re-export types and factories for consumers
 export type { FinancialDataProvider } from './data/types'
 export type { ResolvedFinancialConfig } from './FinancialContext'
+// Seedable in-memory provider — apps pass a seed to render the module populated
+// (demo/dogfood data) instead of the empty onboarding state.
+export { createMockFinancialProvider } from './data/mock'
+export type { MockFinancialSeed, MockFinancialProviderOptions } from './data/mock'
+// FAY-1242: global quick-add trigger — apps wire this to a shell action (e.g.
+// the bottom-nav center "+") to open the transaction sheet from anywhere.
+export { openQuickAdd } from './quick-add'

package/src/locales/en.ts

@@ -1,7 +1,17 @@
 // financial.* — merged plugin-own + saas-core central i18n
 export const en: Record<string, string> = {
+  "financial.cards.addExpense": "Add expense",
+  "financial.cards.allBillsValue": "All bills value",
+  "financial.cards.availableLimit": "Available limit",
+  "financial.cards.currentBill": "Current bill",
+  "financial.cards.dueOn": "Due on the {{day}}",
   "financial.cards.installment": "Installment {{current}}/{{total}}",
+  "financial.cards.noCards": "No cards yet",
+  "financial.cards.noCardsHint": "Add a credit card in settings to track your bills here",
   "financial.cards.noTransactions": "No card transactions",
+  "financial.cards.tabClosed": "Closed",
+  "financial.cards.tabOpen": "Open",
+  "financial.cards.usedOfLimit": "{{percent}}% of limit used",
   "financial.cards.pending": "Pending",
   "financial.cards.received": "Received",
   "financial.cards.subtitle": "Credit and debit card transactions",
@@ -128,6 +138,10 @@ export const en: Record<string, string> = {
   "financial.nav.rules": "Rules",
   "financial.nav.statements": "Statements",
   "financial.nav.summary": "Summary",
+  "financial.invoice.filterAccount": "Chart account",
+  "financial.invoice.filterAllAccounts": "All accounts",
+  "financial.invoice.filterCostCenter": "Cost center",
+  "financial.invoice.filterAllCostCenters": "All cost centers",
   "financial.reconciliation.title": "Reconciliation",
   "financial.reconciliation.subtitle": "Match imported bank lines to your movements",
   "financial.reconciliation.pending": "{{count}} to reconcile",
@@ -242,6 +256,36 @@ export const en: Record<string, string> = {
   "financial.summary.totalBalance": "Total Balance",
   "financial.summary.transactionsAppear": "Transactions will appear here once recorded",
   "financial.summary.viewAll": "View all",
+  "financial.summary.today": "Today",
+  "financial.summary.yesterday": "Yesterday",
+  "financial.summary.transactionsTitle": "Transactions",
+  "financial.home.balance": "Balance",
+  "financial.home.inflow": "Income",
+  "financial.home.outflow": "Expenses",
+  "financial.home.showBalance": "Show balance",
+  "financial.home.hideBalance": "Hide balance",
+  "financial.home.upcomingBills": "Upcoming bills",
+  "financial.home.noBills": "No upcoming bills.",
+  "financial.home.dueToday": "Due today",
+  "financial.home.dueTomorrow": "Due tomorrow",
+  "financial.home.dueInDays": "Due in {{count}} days",
+  "financial.home.overdueDays": "Overdue by {{count}} days",
+  "financial.home.cards": "Cards",
+  "financial.home.currentBill": "Current bill",
+  "financial.home.availableLimit": "Available limit",
+  "financial.home.addCard": "New card",
+  "financial.home.bill": "Bill",
+  "financial.home.spendByCategory": "Spending by category",
+  "financial.home.noSpend": "No spending this month.",
+  "financial.home.category.groceries": "Groceries",
+  "financial.home.category.transport": "Transport",
+  "financial.home.category.subscriptions": "Subscriptions",
+  "financial.home.category.dining": "Dining",
+  "financial.home.category.home": "Home",
+  "financial.home.category.health": "Health",
+  "financial.home.category.leisure": "Leisure",
+  "financial.home.category.shopping": "Shopping",
+  "financial.home.category.other": "Other",
   "financial.quickActions.newPayable": "New Payable",
   "financial.quickActions.newPayableDesc": "Record an expense or bill to pay",
   "financial.quickActions.newReceivable": "New Receivable",
@@ -404,4 +448,35 @@ export const en: Record<string, string> = {
   "financial.transfer.failed": "Failed to record transfer",
   "financial.transfer.sameAccount": "Source and destination must differ",
   "financial.transfer.invalidAmount": "Amount must be greater than zero",
+  "financial.quickTx.title": "New transaction",
+  "financial.quickTx.close": "Close",
+  "financial.quickTx.newTransaction": "New transaction",
+  "financial.quickTx.expense": "Expense",
+  "financial.quickTx.income": "Income",
+  "financial.quickTx.transfer": "Transfer",
+  "financial.quickTx.paid": "Paid",
+  "financial.quickTx.received": "Received",
+  "financial.quickTx.yes": "Yes",
+  "financial.quickTx.no": "No",
+  "financial.quickTx.category": "Category",
+  "financial.quickTx.selectCategory": "No category",
+  "financial.quickTx.account": "Account",
+  "financial.quickTx.selectAccount": "Select account",
+  "financial.quickTx.fromAccount": "From account",
+  "financial.quickTx.toAccount": "To account",
+  "financial.quickTx.card": "Card",
+  "financial.quickTx.recurring": "Recurring",
+  "financial.quickTx.attachment": "Attachment",
+  "financial.quickTx.attachmentSoon": "Attachments coming soon",
+  "financial.quickTx.receipt": "Receipt",
+  "financial.quickTx.receiptCapture": "Snap or attach a receipt",
+  "financial.quickTx.receiptAttached": "Receipt attached",
+  "financial.quickTx.receiptReplace": "Replace",
+  "financial.quickTx.receiptRemove": "Remove receipt",
+  "financial.quickTx.receiptInvalid": "Please choose an image file",
+  "financial.quickTx.sendReceipt": "Send receipt",
+  "financial.quickTx.descriptionPlaceholder": "e.g. Groceries, Salary…",
+  "financial.quickTx.enterAmount": "Enter an amount",
+  "financial.quickTx.save": "Save",
+  "financial.quickTx.saving": "Saving…",
 }

package/src/locales/pt-BR.ts

@@ -1,7 +1,17 @@
 // financial.* — merged plugin-own + saas-core central i18n
 export const ptBR: Record<string, string> = {
+  "financial.cards.addExpense": "Adicionar despesa",
+  "financial.cards.allBillsValue": "Total das faturas",
+  "financial.cards.availableLimit": "Limite disponível",
+  "financial.cards.currentBill": "Fatura atual",
+  "financial.cards.dueOn": "Vence dia {{day}}",
   "financial.cards.installment": "Parcela {{current}}/{{total}}",
+  "financial.cards.noCards": "Nenhum cartão cadastrado",
+  "financial.cards.noCardsHint": "Adicione um cartão de crédito nas configurações para acompanhar suas faturas aqui",
   "financial.cards.noTransactions": "Nenhuma transação com cartão",
+  "financial.cards.tabClosed": "Fechados",
+  "financial.cards.tabOpen": "Abertos",
+  "financial.cards.usedOfLimit": "{{percent}}% do limite usado",
   "financial.cards.pending": "Pendente",
   "financial.cards.received": "Recebido",
   "financial.cards.subtitle": "Transações de cartão de crédito e débito",
@@ -128,6 +138,10 @@ export const ptBR: Record<string, string> = {
   "financial.nav.rules": "Regras",
   "financial.nav.statements": "Extratos",
   "financial.nav.summary": "Resumo",
+  "financial.invoice.filterAccount": "Plano de contas",
+  "financial.invoice.filterAllAccounts": "Todos os planos",
+  "financial.invoice.filterCostCenter": "Centro de custo",
+  "financial.invoice.filterAllCostCenters": "Todos os centros",
   "financial.reconciliation.title": "Conciliação",
   "financial.reconciliation.subtitle": "Concilie as linhas importadas do banco com seus lançamentos",
   "financial.reconciliation.pending": "{{count}} para conciliar",
@@ -242,6 +256,36 @@ export const ptBR: Record<string, string> = {
   "financial.summary.totalBalance": "Saldo Total",
   "financial.summary.transactionsAppear": "As transações aparecerão aqui após serem registradas",
   "financial.summary.viewAll": "Ver todos",
+  "financial.summary.today": "Hoje",
+  "financial.summary.yesterday": "Ontem",
+  "financial.summary.transactionsTitle": "Transações",
+  "financial.home.balance": "Saldo",
+  "financial.home.inflow": "Entradas",
+  "financial.home.outflow": "Saídas",
+  "financial.home.showBalance": "Mostrar saldo",
+  "financial.home.hideBalance": "Ocultar saldo",
+  "financial.home.upcomingBills": "Próximas contas",
+  "financial.home.noBills": "Nenhuma conta a vencer.",
+  "financial.home.dueToday": "Vence hoje",
+  "financial.home.dueTomorrow": "Vence amanhã",
+  "financial.home.dueInDays": "Vence em {{count}} dias",
+  "financial.home.overdueDays": "Venceu há {{count}} dias",
+  "financial.home.cards": "Cartões",
+  "financial.home.currentBill": "Fatura atual",
+  "financial.home.availableLimit": "Limite disponível",
+  "financial.home.addCard": "Novo cartão",
+  "financial.home.bill": "Conta",
+  "financial.home.spendByCategory": "Gastos por categoria",
+  "financial.home.noSpend": "Sem gastos neste mês.",
+  "financial.home.category.groceries": "Mercado",
+  "financial.home.category.transport": "Transporte",
+  "financial.home.category.subscriptions": "Assinaturas",
+  "financial.home.category.dining": "Alimentação",
+  "financial.home.category.home": "Casa",
+  "financial.home.category.health": "Saúde",
+  "financial.home.category.leisure": "Lazer",
+  "financial.home.category.shopping": "Compras",
+  "financial.home.category.other": "Outros",
   "financial.quickActions.newPayable": "Nova Conta a Pagar",
   "financial.quickActions.newPayableDesc": "Registrar uma despesa ou conta a pagar",
   "financial.quickActions.newReceivable": "Nova Conta a Receber",
@@ -404,4 +448,35 @@ export const ptBR: Record<string, string> = {
   "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",
+  "financial.quickTx.title": "Nova transação",
+  "financial.quickTx.close": "Fechar",
+  "financial.quickTx.newTransaction": "Nova transação",
+  "financial.quickTx.expense": "Despesa",
+  "financial.quickTx.income": "Receita",
+  "financial.quickTx.transfer": "Transferência",
+  "financial.quickTx.paid": "Pago",
+  "financial.quickTx.received": "Recebido",
+  "financial.quickTx.yes": "Sim",
+  "financial.quickTx.no": "Não",
+  "financial.quickTx.category": "Categoria",
+  "financial.quickTx.selectCategory": "Sem categoria",
+  "financial.quickTx.account": "Conta",
+  "financial.quickTx.selectAccount": "Selecione a conta",
+  "financial.quickTx.fromAccount": "Conta de origem",
+  "financial.quickTx.toAccount": "Conta de destino",
+  "financial.quickTx.card": "Cartão",
+  "financial.quickTx.recurring": "Recorrente",
+  "financial.quickTx.attachment": "Anexo",
+  "financial.quickTx.attachmentSoon": "Anexos em breve",
+  "financial.quickTx.receipt": "Recibo",
+  "financial.quickTx.receiptCapture": "Fotografar ou anexar recibo",
+  "financial.quickTx.receiptAttached": "Recibo anexado",
+  "financial.quickTx.receiptReplace": "Substituir",
+  "financial.quickTx.receiptRemove": "Remover recibo",
+  "financial.quickTx.receiptInvalid": "Escolha um arquivo de imagem",
+  "financial.quickTx.sendReceipt": "Enviar recibo",
+  "financial.quickTx.descriptionPlaceholder": "ex.: Mercado, Salário…",
+  "financial.quickTx.enterAmount": "Informe um valor",
+  "financial.quickTx.save": "Salvar",
+  "financial.quickTx.saving": "Salvando…",
 }

package/src/quick-add.ts

@@ -0,0 +1,58 @@
+// ---------------------------------------------------------------------------
+// Global quick-add trigger (FAY-1242).
+//
+// A tiny module-level store so a "log a transaction" request can be fired from
+// ANYWHERE in the app (e.g. the app shell's elevated center "+" bottom-nav
+// button) without a shared React context. The FinancialPage subscribes and
+// opens its QuickTransactionForm when a request arrives; the request is a
+// one-shot (consumed on read) so re-mounting /financial doesn't re-open it.
+//
+// Flow: center "+" → openQuickAdd() → navigate to /financial → FinancialPage
+// mounts, sees the pending request, opens the sheet. If already on /financial
+// the subscription fires and the sheet opens instantly.
+// ---------------------------------------------------------------------------
+
+import * as React from 'react'
+import type { QuickTransactionType } from './types'
+
+export interface QuickAddRequest {
+  type: QuickTransactionType
+  /** Foreground the receipt/attachment step + auto-open the picker. */
+  receipt: boolean
+}
+
+let pending: QuickAddRequest | null = null
+const listeners = new Set<() => void>()
+
+function emit() {
+  for (const l of listeners) l()
+}
+
+/** Fire a quick-add request from anywhere. Default = an expense. */
+export function openQuickAdd(type: QuickTransactionType = 'expense', receipt = false): void {
+  pending = { type, receipt }
+  emit()
+}
+
+/** Read + clear the pending request (one-shot). */
+export function consumeQuickAdd(): QuickAddRequest | null {
+  const req = pending
+  pending = null
+  return req
+}
+
+function subscribe(cb: () => void): () => void {
+  listeners.add(cb)
+  return () => {
+    listeners.delete(cb)
+  }
+}
+
+function getSnapshot(): QuickAddRequest | null {
+  return pending
+}
+
+/** React binding — returns the pending request (null when none). */
+export function usePendingQuickAdd(): QuickAddRequest | null {
+  return React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}

package/src/store.ts

@@ -9,6 +9,7 @@ import type {
   InvoiceQuery, MovementQuery, StatementQuery,
   CreateInvoiceInput, PayMovementInput, CreateTransferInput,
   OpenCashSessionInput, CloseCashSessionInput,
+  QuickTransactionInput,
   DateRange,
 } from './types'
 
@@ -55,6 +56,8 @@ export interface FinancialUIState {
   fetchStatement(query: StatementQuery): Promise<void>
   fetchCardTransactions(dateRange?: DateRange): Promise<void>
   createInvoice(input: CreateInvoiceInput): Promise<Invoice>
+  /** FAY-1225 "log money in a few taps": one call → the right provider plumbing + full surface refresh. */
+  createQuickTransaction(input: QuickTransactionInput): Promise<void>
   payMovement(input: PayMovementInput): Promise<void>
   createTransfer(input: CreateTransferInput): Promise<void>
   cancelInvoice(invoiceId: string): Promise<void>
@@ -169,6 +172,91 @@ export function createFinancialStore(provider: FinancialDataProvider): StoreApi<
       }
     },
 
+    async createQuickTransaction(input) {
+      try {
+        if (input.type === 'transfer') {
+          if (!input.bankAccountId || !input.toAccountId) {
+            throw new Error('Select source and destination accounts')
+          }
+          await provider.createTransfer({
+            fromAccountId: input.bankAccountId,
+            toAccountId: input.toAccountId,
+            amount: input.amount,
+            date: input.date,
+            notes: input.description?.trim() || undefined,
+          })
+        } else {
+          const direction: 'debit' | 'credit' = input.type === 'income' ? 'credit' : 'debit'
+          const desc = input.description?.trim() || (input.type === 'income' ? 'Receita' : 'Despesa')
+          // 1. The obligation (invoice + bill movement).
+          // Persist the recurring flag + the snapped-receipt data URL (FAY-1226)
+          // on the invoice metadata so the transaction feed can indicate/preview it.
+          const invoiceMeta: Record<string, unknown> = {}
+          if (input.recurring) invoiceMeta.recurring = true
+          if (input.receiptUrl) invoiceMeta.receiptUrl = input.receiptUrl
+          const invoice = await provider.createInvoice({
+            direction,
+            invoiceDate: input.date,
+            contactName: desc,
+            metadata: Object.keys(invoiceMeta).length > 0 ? invoiceMeta : undefined,
+            items: [{
+              itemKind: 'other',
+              description: desc,
+              quantity: 1,
+              unitPrice: input.amount,
+              accountId: input.categoryId,
+            }],
+            installments: [{
+              direction,
+              movementKind: 'bill',
+              amount: input.amount,
+              dueDate: input.date,
+              installmentNumber: 1,
+              bankAccountId: input.bankAccountId,
+              notes: desc,
+            }],
+          })
+          // 2. Settle it now when marked paid → a realized cash event that shows in
+          //    the statement/extract and feeds the monthly cash-flow KPIs.
+          if (input.paid) {
+            const movements = await provider.getMovements({ direction, status: 'pending' })
+            const bill = movements.data.find((m) => m.invoiceId === invoice.id && m.movementKind === 'bill')
+            if (bill) {
+              await provider.payMovement({
+                movementId: bill.id,
+                amount: input.amount,
+                paymentDate: input.date,
+                bankAccountId: input.bankAccountId,
+                notes: desc,
+              })
+            }
+          }
+        }
+        // Refresh every surface this store feeds: Home/Resumo KPIs (summary),
+        // the mobile transaction list (statement), balances, and the payables/
+        // receivables tables (invoices).
+        const invoiceQuery = get().invoiceQuery
+        const statementQuery = get().statementQuery
+        const [summary, bankAccounts, invoicesRes, statement] = await Promise.all([
+          provider.getSummary(),
+          provider.getBankAccounts(),
+          provider.getInvoices(invoiceQuery),
+          statementQuery ? provider.getStatement(statementQuery) : Promise.resolve(get().statement),
+        ])
+        set({
+          summary,
+          bankAccounts,
+          invoices: invoicesRes.data,
+          invoicesTotal: invoicesRes.total,
+          statement,
+        })
+        toast.success('Transaction saved')
+      } catch (err: any) {
+        toast.error('Failed to save transaction', { description: err?.message })
+        throw err
+      }
+    },
+
     async payMovement(input) {
       try {
         await provider.payMovement(input)

package/src/types.ts

@@ -199,6 +199,16 @@ export interface ChartOfAccountsNode {
   createdAt: string
 }
 
+export interface CostCenter {
+  id: string
+  code: string
+  name: string
+  isActive: boolean
+  tenantId: string
+  createdAt: string
+  updatedAt: string
+}
+
 export interface CardTransaction {
   id: string
   movementId: string
@@ -316,6 +326,8 @@ export interface InvoiceQuery {
   direction?: TransactionDirection
   status?: InvoiceStatus | InvoiceStatus[]
   contactId?: string
+  accountId?: string
+  costCenterId?: string
   dateRange?: DateRange
   search?: string
   page?: number
@@ -347,6 +359,39 @@ export interface CreateTransferInput {
   notes?: string
 }
 
+/**
+ * "Log money in a few taps" (FAY-1225). A single-transaction quick-add that the
+ * store expands into the right provider calls: expense/income → createInvoice
+ * (+ payMovement when marked paid); transfer → createTransfer. Keeps the
+ * Mobills-style form dumb — it only collects fields, the store does the plumbing.
+ */
+export type QuickTransactionType = 'expense' | 'income' | 'transfer'
+
+export interface QuickTransactionInput {
+  type: QuickTransactionType
+  /** Positive amount in the account currency */
+  amount: number
+  /** YYYY-MM-DD */
+  date: string
+  /** When true, the movement is settled immediately (creates a paid cash event). */
+  paid: boolean
+  description?: string
+  /** Chart-of-accounts / cost-center id (category chip) */
+  categoryId?: string
+  /** expense/income: bank account or card. transfer: source account. */
+  bankAccountId?: string
+  /** transfer: destination account */
+  toAccountId?: string
+  /** Marks the transaction as recurring (stored in metadata; UI affordance). */
+  recurring?: boolean
+  /**
+   * FAY-1226 "snap a receipt": a captured/attached receipt image as a data URL
+   * (mock mode has no Supabase bucket). Persisted on the created invoice's
+   * metadata so the transaction feed can show a 📎 indicator + preview.
+   */
+  receiptUrl?: string
+}
+
 export interface TransferResult {
   /** Shared correlation id stored in both legs' metadata */
   transferId: string