afrexai-invoice-engine

# Invoice Engine — Complete Invoicing & Accounts Receivable

A zero-dependency agent skill for end-to-end invoicing — from quote to payment to reporting.

## Quick Start

When the user says "create an invoice" or "bill [client]":

1. Check if client exists in memory (see Client Registry below)
2. If new client → run Client Onboarding
3. Generate invoice using the Invoice Builder
4. Present for review → finalize
5. Track in the Invoice Ledger

---

## 1. Client Registry

Maintain a YAML client database in your workspace:

```yaml
# clients.yaml
clients:
  - id: "CLI-001"
    name: "Acme Corp"
    contact: "Jane Smith"
    email: "jane@acme.com"
    address:
      line1: "123 Business Ave"
      line2: "Suite 400"
      city: "New York"
      state: "NY"
      zip: "10001"
      country: "US"
    tax_id: "US-EIN-12-3456789"
    payment_terms: "net-30"       # net-15, net-30, net-45, net-60, due-on-receipt, custom
    preferred_currency: "USD"
    default_tax_rate: 0           # 0 for B2B cross-border, local rate for domestic
    notes: "PO required for invoices > $5,000"
    created: "2026-01-15"
    lifetime_revenue: 12500.00
    invoices_sent: 3
    invoices_paid: 2
    avg_days_to_pay: 22
```

### Client Onboarding Checklist
When adding a new client, collect:
- [ ] Legal entity name (exactly as on their records)
- [ ] Billing contact name + email
- [ ] Billing address (full, with country)
- [ ] Tax ID / VAT number (if applicable)
- [ ] Preferred payment terms
- [ ] Currency preference
- [ ] Any PO or approval requirements
- [ ] Tax-exempt? (if so, get certificate reference)

---

## 2. Invoice Builder

### Invoice Number Format
```
[PREFIX]-[YEAR].[MONTH].[SEQUENCE]
Example: INV-2026.02.001
```

Configurable prefix per business line:
- `INV` = standard invoice
- `PRO` = proforma / quote
- `REC` = recurring invoice
- `CN` = credit note

### Invoice Template

When generating an invoice, structure it as:

```
╔══════════════════════════════════════════════════════════...

# Invoice Engine — Complete Invoicing & AR for AI Agents

Professional invoicing, payment tracking, overdue management, and financial reporting — all in one agent skill. Zero dependencies.

## Install

```bash
clawhub install afrexai-invoice-engine
```

## What It Does

- **Create invoices** from natural language ("invoice Acme for 20 hours at $250")
- **Client registry** with payment terms, tax handling, and history
- **Recurring billing** — auto-generate monthly/quarterly invoices
- **Overdue automation** — reminder schedule with email templates at +1, +7, +14, +30 days
- **Revenue dashboard** — collection rate, DSO, aging report, monthly trends
- **Quote-to-invoice pipeline** — proformas → accepted → invoice → paid
- **Multi-currency** — USD, GBP, EUR, BTC/Lightning
- **Credit notes & adjustments** — partial refunds, corrections, write-offs
- **Tax handling** — decision tree for domestic, cross-border, EU reverse charge, tax-exempt
- **Late fee calculation** — configurable rates with grace periods

## Quick Start

Just tell your agent:
- "Invoice [client] for [description]"
- "What's overdue?"
- "Revenue this month"
- "Set up recurring: [client] $3,500/month"

The skill handles numbering, tax logic, payment terms, and tracking automatically.

## Why This Over Others?

| Feature | Others | This Skill |
|---|---|---|
| Dependencies | Node.js + weasyprint | Zero |
| Client management | ❌ | Full registry + onboarding |
| Recurring billing | ❌ | Auto-generate on schedule |
| Overdue automation | ❌ | 5-stage reminder sequence |
| Revenue reporting | ❌ | Dashboard + aging + trends |
| Multi-currency | ❌ | USD/GBP/EUR/BTC |
| Quote pipeline | ❌ | Quote → Accept → Invoice |
| Tax handling | Basic | Decision tree by region |
| Credit notes | ❌ | Full adjustment workflow |
| Late fees | ❌ | Auto-calculate with caps |

## ⚡ Level Up

Get the full **AI Context Pack** for your industry — includes invoicing context PLUS market landscape, competitor analysis, compliance...