@fayz-ai/plugin-financial 0.1.2 → 0.1.4

package/src/components/PersonStatementWidget.tsx

@@ -0,0 +1,133 @@
+import React, { useEffect, useMemo, useState } from 'react'
+import { Wallet } from 'lucide-react'
+import type { ColumnDef } from '@tanstack/react-table'
+import { DataTable } from '@fayz-ai/ui'
+import { useTranslation } from '@fayz-ai/core'
+import { formatCurrency, type ResolvedFinancialConfig } from '../FinancialContext'
+import type { FinancialDataProvider } from '../data/types'
+import type { Invoice } from '../types'
+
+const STATUS_STYLE: Record<string, string> = {
+  paid: 'bg-success/15 text-success',
+  partial: 'bg-warning/15 text-warning',
+  overdue: 'bg-destructive/15 text-destructive',
+  open: 'bg-muted text-muted-foreground',
+  cancelled: 'bg-muted text-muted-foreground line-through',
+}
+
+/**
+ * Per-person financial statement (account_central-style extract): every invoice where
+ * this person is the contact — a client paying receivables, or a professional receiving
+ * commissions/payables. Rendered as a tab on the person detail page via the
+ * `person.detail.financial` widget zone.
+ */
+export function PersonStatementWidget({ person, provider, config }: {
+  person: { id?: string; name?: string }
+  provider: FinancialDataProvider
+  config: ResolvedFinancialConfig
+}) {
+  const t = useTranslation()
+  const currency = config.currency
+  const [invoices, setInvoices] = useState<Invoice[]>([])
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    let alive = true
+    if (!person?.id) { setLoading(false); return }
+    setLoading(true)
+    provider.getInvoices({ contactId: person.id, pageSize: 200 })
+      .then((r) => { if (alive) { setInvoices(r.data); setLoading(false) } })
+      .catch(() => { if (alive) setLoading(false) })
+    return () => { alive = false }
+  }, [person?.id, provider])
+
+  const fmt = (n: number) => formatCurrency(n, currency)
+
+  const totals = useMemo(() => {
+    const active = invoices.filter((i) => i.status !== 'cancelled')
+    const billed = active.reduce((s, i) => s + (i.totalAmount ?? 0), 0)
+    const paid = active.reduce((s, i) => s + (i.paidAmount ?? 0), 0)
+    return { billed, paid, balance: billed - paid }
+  }, [invoices])
+
+  const openInvoice = (inv: Invoice) => {
+    const base = inv.direction === 'credit' ? 'receivables' : 'payables'
+    window.location.hash = `/financial/${base}/detail/${inv.id}`
+  }
+
+  const columns: ColumnDef<Invoice, any>[] = useMemo(() => [
+    {
+      id: 'date', header: t('financial.invoice.columnDate'),
+      cell: ({ row }) => <span className="text-muted-foreground text-xs">{row.original.invoiceDate}</span>,
+    },
+    {
+      id: 'description', header: t('financial.invoice.columnDescription'),
+      cell: ({ row }) => {
+        const inv = row.original
+        return (
+          <button onClick={() => openInvoice(inv)} className="text-left">
+            <span className="text-xs font-medium text-primary hover:underline">
+              {inv.itemsSummary || inv.contactName || t('financial.invoice.invoice')}
+            </span>
+            {inv.fiscalNumber && <span className="ml-1.5 text-[10px] text-muted-foreground font-mono">{inv.fiscalNumber}</span>}
+          </button>
+        )
+      },
+    },
+    {
+      id: 'amount', header: t('financial.invoice.columnAmount'),
+      cell: ({ row }) => (
+        <span className={`text-right block text-xs ${row.original.direction === 'credit' ? 'text-success' : 'text-destructive'}`}>
+          {fmt(row.original.totalAmount)}
+        </span>
+      ),
+    },
+    {
+      id: 'paid', header: t('financial.invoice.columnPaid'),
+      cell: ({ row }) => <span className="text-right block text-xs text-muted-foreground">{fmt(row.original.paidAmount)}</span>,
+    },
+    {
+      id: 'balance', header: t('financial.statements.columnBalance'),
+      cell: ({ row }) => <span className="text-right block text-xs font-medium">{fmt((row.original.totalAmount ?? 0) - (row.original.paidAmount ?? 0))}</span>,
+    },
+    {
+      id: 'status', header: t('financial.invoice.columnStatus'),
+      cell: ({ row }) => (
+        <span className={`inline-flex rounded-full px-1.5 py-0.5 text-[9px] font-medium capitalize ${STATUS_STYLE[row.original.status] ?? STATUS_STYLE.open}`}>
+          {row.original.status}
+        </span>
+      ),
+    },
+  ], [currency, t])
+
+  return (
+    <div className="space-y-3">
+      {/* Totals */}
+      <div className="grid grid-cols-3 gap-2">
+        <Stat label={t('financial.invoice.summaryTotal')} value={fmt(totals.billed)} />
+        <Stat label={t('financial.invoice.summaryPaid')} value={fmt(totals.paid)} positive />
+        <Stat label={t('financial.statements.columnBalance')} value={fmt(totals.balance)} accent />
+      </div>
+
+      {loading ? (
+        <DataTable columns={columns} data={[]} loading skeletonRows={5} compact />
+      ) : invoices.length === 0 ? (
+        <div className="flex flex-col items-center justify-center py-10 text-center rounded-lg border-2 border-dashed border-muted">
+          <Wallet className="h-7 w-7 text-muted-foreground mb-2" />
+          <p className="text-sm text-muted-foreground">{t('financial.person.empty')}</p>
+        </div>
+      ) : (
+        <DataTable columns={columns} data={invoices} compact />
+      )}
+    </div>
+  )
+}
+
+function Stat({ label, value, accent, positive }: { label: string; value: string; accent?: boolean; positive?: boolean }) {
+  return (
+    <div className={`rounded-lg border px-3 py-2 ${accent ? 'bg-muted/40' : 'bg-card'}`}>
+      <p className="text-[10px] font-medium text-muted-foreground uppercase truncate">{label}</p>
+      <p className={`text-sm font-semibold mt-0.5 ${positive ? 'text-success' : 'text-foreground'}`}>{value}</p>
+    </div>
+  )
+}

package/src/components/TransferModal.tsx

@@ -0,0 +1,150 @@
+import React, { useState, useEffect } from 'react'
+import { createPortal } from 'react-dom'
+import { X, ArrowRightLeft } from 'lucide-react'
+import { useFinancialConfig, useFinancialStore } from '../FinancialContext'
+import { useTranslation } from '@fayz-ai/core'
+import { CurrencyInput, DatePicker, Button } from '@fayz-ai/ui'
+
+export function TransferModal({ onClose, onDone, defaultFromId }: {
+  onClose: () => void
+  onDone: () => void
+  defaultFromId?: string
+}) {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const bankAccounts = useFinancialStore((s) => s.bankAccounts)
+  const createTransfer = useFinancialStore((s) => s.createTransfer)
+  const fetchBankAccounts = useFinancialStore((s) => s.fetchBankAccounts)
+
+  const [fromAccountId, setFromAccountId] = useState(defaultFromId ?? '')
+  const [toAccountId, setToAccountId] = useState('')
+  const [amount, setAmount] = useState(0)
+  const [date, setDate] = useState(new Date().toISOString().slice(0, 10))
+  const [notes, setNotes] = useState('')
+  const [saving, setSaving] = useState(false)
+  const [visible, setVisible] = useState(false)
+
+  useEffect(() => {
+    fetchBankAccounts()
+    requestAnimationFrame(() => setVisible(true))
+  }, [])
+
+  function handleClose() {
+    setVisible(false)
+    setTimeout(onClose, 200)
+  }
+
+  const sameAccount = !!fromAccountId && fromAccountId === toAccountId
+  const canSubmit = !!fromAccountId && !!toAccountId && !sameAccount && amount > 0 && !saving
+
+  // Enter anywhere in the modal submits (unless typing in a textarea / Shift+Enter).
+  function handleKeyDown(e: React.KeyboardEvent) {
+    if (e.key !== 'Enter' || e.shiftKey) return
+    if ((e.target as HTMLElement).tagName === 'TEXTAREA') return
+    e.preventDefault()
+    if (canSubmit) void handleSubmit()
+  }
+
+  async function handleSubmit() {
+    if (!canSubmit) return
+    setSaving(true)
+    try {
+      await createTransfer({ fromAccountId, toAccountId, amount, date, notes: notes || undefined })
+      setVisible(false)
+      setTimeout(onDone, 200)
+    } catch {
+      // toast handled by store
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const selectClass = 'w-full mt-1 rounded-input border border-input bg-card shadow-[inset_0_1px_0_rgb(0_0_0_/0.06)] px-3 py-2 text-sm'
+
+  return createPortal(
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center transition-colors duration-200"
+      style={{ backgroundColor: visible ? 'rgba(0,0,0,0.5)' : 'rgba(0,0,0,0)' }}
+      onClick={handleClose}
+    >
+      <div
+        className="w-full max-w-md rounded-modal border bg-card shadow-lg mx-4 transition-all duration-200 max-h-[90vh] overflow-y-auto"
+        style={{ opacity: visible ? 1 : 0, transform: visible ? 'scale(1) translateY(0)' : 'scale(0.95) translateY(8px)' }}
+        onClick={(e) => e.stopPropagation()}
+        onKeyDown={handleKeyDown}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 py-4 border-b">
+          <div className="flex items-center gap-2">
+            <ArrowRightLeft className="h-4 w-4 text-warning" />
+            <h3 className="text-base font-semibold">{t('financial.transfer.title')}</h3>
+          </div>
+          <button onClick={handleClose} className="p-1 text-muted-foreground hover:text-foreground transition-colors">
+            <X className="h-4 w-4" />
+          </button>
+        </div>
+
+        <div className="px-5 py-4 space-y-4">
+          <div className="grid grid-cols-2 gap-3">
+            <div>
+              <label className="text-xs font-medium text-muted-foreground">{t('financial.transfer.from')}</label>
+              <select value={fromAccountId} onChange={(e) => setFromAccountId(e.target.value)} className={selectClass}>
+                <option value="">{t('financial.transfer.selectAccount')}</option>
+                {bankAccounts.map((a) => <option key={a.id} value={a.id}>{a.name}</option>)}
+              </select>
+            </div>
+            <div>
+              <label className="text-xs font-medium text-muted-foreground">{t('financial.transfer.to')}</label>
+              <select value={toAccountId} onChange={(e) => setToAccountId(e.target.value)} className={selectClass}>
+                <option value="">{t('financial.transfer.selectAccount')}</option>
+                {bankAccounts.map((a) => <option key={a.id} value={a.id}>{a.name}</option>)}
+              </select>
+            </div>
+          </div>
+
+          {sameAccount && (
+            <p className="text-xs text-destructive">{t('financial.transfer.sameAccount')}</p>
+          )}
+
+          <div className="grid grid-cols-2 gap-3">
+            <CurrencyInput
+              label={t('financial.transfer.amount')}
+              value={amount}
+              onChange={setAmount}
+              symbol={currency.symbol}
+              locale={currency.locale}
+              currencyCode={currency.code}
+            />
+            <div>
+              <label className="text-xs font-medium text-muted-foreground">{t('financial.transfer.date')}</label>
+              <DatePicker value={date} onChange={setDate} className="mt-1" />
+            </div>
+          </div>
+
+          <div>
+            <label className="text-xs font-medium text-muted-foreground">{t('financial.transfer.notes')}</label>
+            <input
+              type="text"
+              value={notes}
+              onChange={(e) => setNotes(e.target.value)}
+              placeholder={t('financial.transfer.optionalNotes')}
+              className="w-full mt-1 rounded-input border border-input bg-card shadow-[inset_0_1px_0_rgb(0_0_0_/0.06)] px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-ring"
+            />
+          </div>
+        </div>
+
+        {/* Actions */}
+        <div className="flex justify-end gap-2 px-5 py-4 border-t">
+          <Button variant="outline" size="sm" onClick={handleClose}>
+            {t('financial.transfer.cancel')}
+          </Button>
+          <Button variant="default" size="sm" onClick={handleSubmit} disabled={!canSubmit}>
+            <ArrowRightLeft className="h-3.5 w-3.5" />
+            {saving ? t('financial.transfer.processing') : t('financial.transfer.submit')}
+          </Button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  )
+}

package/src/contract.test.ts

@@ -0,0 +1,58 @@
+// Integrity test for the shared plugin-contract assertions (@fayz-ai/core/testing).
+// Exercises the gate's rules with inline manifests (no UI import) so the tool
+// itself is proven: a conformant manifest passes; each malformed shape throws.
+// Real plugins call assertPluginManifestContract(theirManifest) in an env where
+// their UI bundle loads (app-level / jsdom). See PLUGIN_PATTERNS.md → integrity.
+import { describe, it, expect } from 'vitest'
+import { assertPluginManifestContract, PluginContractError } from '@fayz-ai/core/testing'
+import type { PluginManifest } from '@fayz-ai/core'
+
+const Dummy = () => null
+
+function manifest(overrides: Partial<PluginManifest> = {}): PluginManifest {
+  return {
+    id: 'demo', name: 'Demo', icon: 'Box', version: '1.0.0',
+    navigation: [{ section: 'main', label: 'Demo', route: '/demo', icon: 'Box' } as any],
+    routes: [{ path: '/demo', component: Dummy } as any],
+    ...overrides,
+  }
+}
+
+describe('assertPluginManifestContract', () => {
+  it('passes a conformant page plugin', () => {
+    expect(() => assertPluginManifestContract(manifest())).not.toThrow()
+  })
+
+  it('passes a settings-only plugin (nav/routes empty, one settings tab)', () => {
+    expect(() => assertPluginManifestContract(manifest({
+      navigation: [], routes: [],
+      settings: [{ id: 'demo', label: 'Demo', icon: 'Box', component: Dummy } as any],
+    }))).not.toThrow()
+  })
+
+  it('rejects a missing id', () => {
+    expect(() => assertPluginManifestContract(manifest({ id: '' }))).toThrow(PluginContractError)
+  })
+
+  it('rejects a nav entry pointing at an undeclared route', () => {
+    expect(() => assertPluginManifestContract(manifest({
+      navigation: [{ section: 'main', label: 'X', route: '/nowhere', icon: 'Box' } as any],
+    }))).toThrow(/no matching route/)
+  })
+
+  it('rejects duplicate route paths', () => {
+    expect(() => assertPluginManifestContract(manifest({
+      routes: [{ path: '/demo', component: Dummy } as any, { path: '/demo', component: Dummy } as any],
+    }))).toThrow(/duplicate route/)
+  })
+
+  it('rejects a settings tab without a component', () => {
+    expect(() => assertPluginManifestContract(manifest({
+      settings: [{ id: 'demo', label: 'Demo' } as any],
+    }))).toThrow(/component/)
+  })
+
+  it('rejects a plugin that contributes nothing mountable', () => {
+    expect(() => assertPluginManifestContract(manifest({ navigation: [], routes: [], settings: [] }))).toThrow(/nothing/)
+  })
+})

package/src/data/capability.test.ts

@@ -0,0 +1,90 @@
+// Capability + contract test for plugin-financial (Plugin Capability Contract).
+// Proves the data slice end-to-end against the mock provider — including the
+// ⚖️ reconciliation (conciliação) feature: import bank lines → list unreconciled
+// → suggest a match → reconcile → assert it leaves the pending set. Rows are
+// created manually (mock provider), which is exactly how a capability is proven
+// before/without a live backend. Mirrors plugins/plugin-tasks capability.test.ts.
+import { describe, it, expect } from 'vitest'
+import { createMockFinancialProvider } from './mock'
+
+describe('plugin-financial · invoice/movement slice (mock provider)', () => {
+  it('persists an invoice and its installment movements', async () => {
+    const provider = createMockFinancialProvider()
+    const invoice = await provider.createInvoice({
+      direction: 'credit',
+      invoiceDate: '2026-06-01',
+      contactName: 'Acme',
+      items: [{ itemKind: 'other', description: 'Consulting', quantity: 1, unitPrice: 300 }],
+      installments: [
+        { direction: 'credit', movementKind: 'bill', amount: 300, dueDate: '2026-06-10', installmentNumber: 1 },
+      ],
+    })
+    expect(invoice.id).toBeTruthy()
+    expect(invoice.totalAmount).toBe(300)
+
+    const movs = await provider.getMovements({ direction: 'credit' })
+    expect(movs.data.some((m) => m.invoiceId === invoice.id && m.amount === 300)).toBe(true)
+  })
+})
+
+describe('plugin-financial · ⚖️ reconciliation capability (mock provider)', () => {
+  it('imports bank lines idempotently', async () => {
+    const provider = createMockFinancialProvider()
+    const lines = [
+      { externalId: 'tx-1', externalSource: 'plugbank', direction: 'credit' as const, amount: 150, date: '2026-06-10', description: 'PIX recebido' },
+      { externalId: 'tx-2', externalSource: 'plugbank', direction: 'debit' as const, amount: 80, date: '2026-06-11', description: 'Tarifa' },
+    ]
+    const first = await provider.importBankTransactions!({ lines })
+    expect(first.imported).toBe(2)
+    expect(first.duplicates).toBe(0)
+
+    // Re-importing the same lines must not duplicate (idempotency by external id).
+    const second = await provider.importBankTransactions!({ lines })
+    expect(second.imported).toBe(0)
+    expect(second.duplicates).toBe(2)
+
+    const pending = await provider.getUnreconciled!()
+    expect(pending).toHaveLength(2)
+    expect(pending.every((m) => m.externalSource === 'plugbank' && !m.reconciledAt)).toBe(true)
+  })
+
+  it('suggests and matches an internal movement, leaving the pending set', async () => {
+    const provider = createMockFinancialProvider()
+    // An internal receivable the bank line should reconcile against.
+    await provider.createInvoice({
+      direction: 'credit',
+      invoiceDate: '2026-06-08',
+      contactName: 'Acme',
+      items: [{ itemKind: 'other', description: 'Service', quantity: 1, unitPrice: 150 }],
+      installments: [{ direction: 'credit', movementKind: 'bill', amount: 150, dueDate: '2026-06-10', installmentNumber: 1 }],
+    })
+    // The imported bank line (same amount, same direction, near date).
+    await provider.importBankTransactions!({
+      lines: [{ externalId: 'tx-1', externalSource: 'plugbank', direction: 'credit', amount: 150, date: '2026-06-10', description: 'PIX Acme' }],
+    })
+
+    const [bankLine] = await provider.getUnreconciled!()
+    expect(bankLine).toBeTruthy()
+
+    const candidates = await provider.suggestReconciliation!(bankLine.id)
+    expect(candidates.length).toBeGreaterThan(0)
+    expect(candidates[0].movement.amount).toBe(150)
+    expect(candidates[0].score).toBeGreaterThan(0.5)
+
+    await provider.reconcileMovement!({ bankMovementId: bankLine.id, matchedMovementId: candidates[0].movement.id })
+
+    // The line is gone from the pending set and both sides are marked reconciled.
+    const stillPending = await provider.getUnreconciled!()
+    expect(stillPending.some((m) => m.id === bankLine.id)).toBe(false)
+  })
+
+  it('accepts a bank line standalone when there is no internal counterpart', async () => {
+    const provider = createMockFinancialProvider()
+    await provider.importBankTransactions!({
+      lines: [{ externalId: 'tx-9', externalSource: 'plugbank', direction: 'debit', amount: 42, date: '2026-06-12', description: 'Taxa avulsa' }],
+    })
+    const [line] = await provider.getUnreconciled!()
+    await provider.reconcileMovement!({ bankMovementId: line.id }) // no match → accept standalone
+    expect(await provider.getUnreconciled!()).toHaveLength(0)
+  })
+})