{
  "schema": "leumas.docs.page/1",
  "id": "adapter:domain/tax",
  "slug": "adapters/domain/tax",
  "kind": "capabilities",
  "bucket": "package",
  "title": "tax — tax / VAT rules, discounts & subscription proration",
  "name": "tax",
  "eyebrow": "tax / VAT rules, discounts & subscription proration",
  "chip": null,
  "summary": "Tax, VAT and pricing-rules capability pack: US state sales tax and international VAT/GST/consumption tax from a built-in reference rate table (salesTax, vat, listRates), add tax net-to-gross...",
  "keywords": [
    "tax",
    "international",
    "salestax",
    "listrates",
    "addtax",
    "leumas tax",
    "removetax",
    "tax-on-tax"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# tax — tax / VAT rules, discounts & subscription proration\n\nA **pure** Leumas2 domain adapter pack (zero npm deps, Node built-ins only). It is the reusable\n**rules engine** for consumption tax, discounts, and subscription proration. All money math runs\nthrough cent-accurate rounding to avoid IEEE-754 float drift, and results are plain JSON.\n\n## What it does\n\n| Tool | Purpose |\n|---|---|\n| `salesTax` | US state sales tax (or explicit rate) net → gross, from the built-in table |\n| `vat` | International VAT/GST; `inclusive:true` backs tax out of a gross amount |\n| `addTax` | net → gross given a rate |\n| `removeTax` | gross → net (back out the tax) |\n| `compoundTax` | stack multiple rates — `sequential` (tax-on-tax) or `parallel` (state+county+city) |\n| `discount` | apply ONE discount: `percent`, `fixed`, or `coupon` (with optional `min` floor) |\n| `tieredPrice` | graduated bracket pricing (`graduated`) or single-tier flat (`flat`) |\n| `volumeDiscount` | bulk per-unit discount by quantity `breaks` |\n| `proration` | prorate a mid-cycle subscription change by remaining-period fraction (`charge`/`credit`) |\n| `marginPrice` | cost-plus pricing — `margin` (% of price) or `markup` (% of cost) |\n| `listRates` | dump the reference rate table (`us` / `intl` / `coupons` / `all`) or one `region` |\n\n## Rate table\n\n`data/rates.json` is a static reference table: US 50 states + DC (combined state-level base sales\ntax), 30+ countries (standard national VAT/GST/consumption tax), and a small coupon catalog. Rates\nare decimal fractions (`0.0725` = 7.25%). These are **indicative reference values for estimation**,\nnot tax advice — for filing, use an authoritative source. Pass an explicit `rate` to bypass the table.\n\nRates accept either form: a decimal fraction (`0.2`) or a percent (`20`) — any value `> 1` is read as\na percent.\n\n## Usage\n\n```js\nimport tax from '@leumas/adapter-tax'; // or the registry: registry.run('tax', 'salesTax', {...})\n\ntax.adapters.salesTax({ amount: 100, region: 'CA' });\n// → { net: 100, rate: 0.0725, tax: 7.25, gross: 107.25, region: 'US-CA', regionName: 'California', taxType: 'sales' }\n\ntax.adapters.vat({ amount: 120, region: 'GB', inclusive: true });\n// → { inclusive: true, net: 100, tax: 20, gross: 120, rate: 0.2, ... }\n\ntax.adapters.compoundTax({ amount: 100, rates: [0.05, { rate: 0.07, label: 'PST' }], mode: 'sequential' });\n\ntax.adapters.discount({ amount: 80, coupon: 'SAVE20' });\n// → { original: 80, kind: 'coupon:percent', discount: 16, final: 64, ... }\n\ntax.adapters.tieredPrice({ quantity: 250, tiers: [{ upTo: 100, price: 1 }, { upTo: 200, price: 0.8 }, { upTo: null, price: 0.5 }] });\n\ntax.adapters.proration({ amount: 30, periodStart: '2026-01-01', periodEnd: '2026-02-01', changeDate: '2026-01-16', direction: 'charge' });\n\ntax.adapters.marginPrice({ cost: 70, marginPercent: 30, mode: 'margin' }); // → price 100\n```\n\nEvery tool takes ONE args object (maps 1:1 onto an HTTP POST body) and throws `TypeError`/`RangeError`\non bad input; unknown region/coupon lookups throw a `status: 404` error.\n\n## DRY boundary (respect it)\n\n- **finance** owns money-**over-time** math: compound interest, loan amortization, TVM / NPV / IRR.\n- **invoice** owns billing **documents**: line items → a rendered invoice, invoice numbers, late fees.\n- **tax** (this pack) owns tax **rules**, discount **rules**, and subscription **proration** — the\n  numbers you compute *before* they land in an invoice line or a finance model.\n\nWhere they touch (an invoice line carries a `taxRate`/`discount`), invoice does its own inline math;\nthis pack is the standalone engine you call to *derive* tax and discount figures — and a natural\ncompanion to **PassNode** for prorating plan/seat changes mid-cycle.\n",
  "source": {
    "path": "shared/engines/adapters/domain/tax/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 3976,
    "hash": "19f4c2c7df36771b7f9796657e6ec2f306f5d3f4"
  },
  "urls": {
    "html": "/p/adapters/domain/tax",
    "json": "/docs/adapters/domain/tax.json",
    "md": "/docs/adapters/domain/tax.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}