# plugin-financial

`@fayz-ai/plugin-financial` · beta · Partial capability

Most vertical SaaS bolts on finance as an afterthought: a "total" field, a spreadsheet export, and a prayer. plugin-financial makes money a first-class part of the app. It models the full order-to-cash loop — receivables, payables, cash registers, statements, card reconciliation, and commission rules — as composable modules you toggle per business.

## Overview

The finance core: payables and receivables, cash registers, statements, commissions, cards and bank reconciliation. It mounts the `/financial` page, dashboard widgets and a per-person statement widget (the `person.detail.financial` zone). The `payables`, `receivables`, `cashRegisters`, `statements`, `commissions`, `cards` and `reconciliation` (opt-in, requires a banking connector) modules are toggled by config.

On the data side, **invoices are orders** (`saas_core.orders`, `kind='invoice_payable'`/`invoice_receivable'`), while the finance ledger lives in `financial_movements`. The plugin adds tables in `public` such as `payment_methods`, `payment_method_types`, `bank_accounts`, `cash_register_sessions`, `chart_of_accounts`, `card_brands` and `cost_centers` — eleven migrations covering the chart of accounts, card brands, order-to-cash, RLS, reconciliation and payment splits. Supabase provider with mock fallback.

For AI, it exposes `getRevenue`, `createInvoice` and `listPayables`. Status **beta / partial capability**.

## When to use it

- Track cash flow, payables and receivables.
- Issue and follow invoices tied to contacts.
- Reconcile a bank statement through a connector — opt-in module.

## Specs

- **Package:** `@fayz-ai/plugin-financial`
- **Version:** 0.2.0
- **Status:** beta
- **Capability:** Partial capability
- **Product type:** Management (Admin/SaaS)
- **Stable channel:** `^0.2.0`
- **Migrations:** 11 migration(s)
- **Factory:** `createFinancialPlugin()`

## Data model

Convention: plg_ + tenant_id + RLS.

- `plg_financial_payment_method_types` — name, transaction_type, is_active, allowed_account_types
- `plg_financial_payment_methods` — name, payment_method_type_id, is_active, discount_mode, discount_value, interest_mode
- `plg_financial_bank_accounts` — name, account_type, bank_name, account_number, agency_number, current_balance
- `plg_financial_cash_register_sessions` — bank_account_id, status, opened_at, opened_by_user_id, opened_by_name, opening_balance
- `plg_financial_movements` — invoice_id, direction, movement_kind, amount, paid_amount, status
- `plg_financial_chart_of_accounts` — code, name, node_type, parent_id, is_active
- `plg_financial_cost_centers` — code, name, is_active
- `plg_financial_card_brands` — name, is_active
- `sequences` — kind, current_value
- `plg_financial_nfe` — model, status, number, series, order_id, contact_id

## AI tools

| id | mode | description |
| --- | --- | --- |
| `financial.get-revenue` | read | Returns revenue for the business in a given period. |
| `financial.create-invoice` | persist | Creates a new invoice/payable for a contact. |
| `financial.mark-payment-received` | persist | Marks an order/appointment as paid: invoices it (with installments for credit card, e.g.  |
| `financial.list-payables` | read | Lists outstanding payables/bills. |

## Integrations

No hosted connector — external providers come in via the connector spine (`@fayz-ai/core`).

## Integrate

Add the plugin to surfaces.admin.plugins in your app's app.manifest.json and run the doctor to validate:

```json
{ "surfaces": { "admin": { "plugins": [ { "id": "financial", "enabled": true } ] } } }
```

```bash
npx fayz doctor
```