{
  "schema": "leumas.docs.page/1",
  "id": "adapter:domain/invoice",
  "slug": "adapters/domain/invoice",
  "kind": "capabilities",
  "bucket": "package",
  "title": "invoice (adapter system)",
  "name": "invoice",
  "eyebrow": "adapter system",
  "chip": null,
  "summary": "Invoice capability pack: build a full invoice object from line items with correct per-line and global tax/discount math, compute just the totals, roll invoice numbers ('INV-0006' → 'INV-0007'), apply...",
  "keywords": [
    "invoice",
    "inv-0006",
    "inv-0007",
    "money-true",
    "defer",
    "leumas invoice",
    "fees",
    "a-templates"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# invoice (adapter system)\n\nBilling capability pack — Studio-aligned, monetizable CRM tools. Pure JS, **zero deps**. The\nmoney-true core for quoting and billing: build invoices from line items, compute totals, roll invoice\nnumbers, apply late fees, and render a printable invoice.\n\n**Careful money math:** all arithmetic runs in **integer cents** internally, then converts back to\n2-decimal dollars on output — so totals never drift (`0.1 + 0.2 ≠ 0.3` can't bite here) even across\nmany line items. Per-line math (qty × unit → line discount → line tax) happens first; global\ntax/discount then fill in for lines that didn't specify their own, and a global discount is distributed\nproportionally so per-line tax stays fair.\n\n## Tools (`adapters`)\n\n| tool | args | result |\n|------|------|--------|\n| `build` | `{ lineItems:[{description,quantity,unitPrice,taxRate?,discount?}], currency='USD', taxRate?, discount?, notes?, from?, to?, invoiceNumber? }` | full invoice `{ invoiceNumber, currency, lineItems:[{...,lineTotal}], subtotal, discountTotal, taxTotal, total, ... }` |\n| `nextInvoiceNumber` | `{ last, prefix?, pad=4 }` | `{ next, number, prefix }` — e.g. `'INV-0006'` → `'INV-0007'` |\n| `totals` | `{ lineItems, taxRate?, discount? }` | `{ subtotal, discountTotal, taxTotal, total }` |\n| `applyLateFee` | `{ total, daysLate, dailyRate }` | `{ originalTotal, lateFee, total }` |\n| `toHtml` | `{ invoice }` | `{ html }` — a clean printable HTML invoice string |\n| `summary` | `{ invoice }` | `{ summary }` — one-line text summary |\n\n**Discount forms:** a bare number `< 1` is a percent fraction (`0.1` = 10%); a number `≥ 1` is a flat\ncash amount; or pass `{ type: 'percent'|'flat', value }` explicitly. `taxRate` is a decimal\n(`0.08` = 8%). A per-line `taxRate`/`discount` overrides the global one for that line.\n\n## Usage\n\n```js\nconst m = await import('./index.js');\nconst invoice = m.default.adapters;\n\nconst inv = invoice.build({\n  lineItems: [\n    { description: 'Design', quantity: 10, unitPrice: 100 },\n    { description: 'Hosting', quantity: 1, unitPrice: 50 },\n  ],\n  taxRate: 0.1,\n});\n// inv.subtotal = 1050, inv.taxTotal = 105, inv.total = 1155\n\ninvoice.nextInvoiceNumber({ last: 'INV-0006' }); // → { next: 'INV-0007', ... }\ninvoice.toHtml({ invoice: inv });                // → { html: '<div class=\"invoice\">…' }\n```\n\n## Rendering deferred to a-templates\n\n`toHtml` is a pure, dependency-free template literal — good enough to print or email. For **richer,\nbranded, themeable rendering** (logos, custom layouts, PDF pipelines) defer to the **a-templates**\nsystem rather than growing this pack. `invoice` stays the money-true data core; a-templates owns the\npresentation layer.\n\n## CRM fit\n\n`build`/`totals` are the billing core behind quoting and invoicing surfaces in Studio/Web;\n`nextInvoiceNumber` and `applyLateFee` handle the lifecycle. Gate/meter via `@leumas/auth` like any\nother adapter.\n\n## DRY boundary\n\n`finance` owns generic money math (loans, TVM, currency formatting, ROI). `invoice` owns\ndocument-shaped billing (line items, totals, numbering, HTML). No overlap.\n",
  "source": {
    "path": "shared/engines/adapters/domain/invoice/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 3328,
    "hash": "b03373a3e2f5f09f03e92b4b493aced15f8c03f5"
  },
  "urls": {
    "html": "/p/adapters/domain/invoice",
    "json": "/docs/adapters/domain/invoice.json",
    "md": "/docs/adapters/domain/invoice.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}