@taxora/sdk 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `@taxora/sdk` are documented here. Versions follow [SemVe
 
 ## [Unreleased]
 
+## [1.10.0] - 2026-11-03
+
+### Added
+
+- `ComplianceTax.rate()`, `zeroRated()`, `exempt()` and `reverseCharge()` build line taxes with the right category.
+- `calculateInvoiceTotals(lines, { expectedTotal })` checks your own total against the lines and reports `roundingDifference`.
+
+### Changed
+
+- `createTransaction()` refuses impossible input before the request: an unknown tax category, a category `E` tax
+  without its exemption code (`comment`), a percent outside 0–100, a currency or country code that is not letters
+  (currency, counterparty country and tax categories are upper-cased), a due date before the invoice date, a credit
+  note without `amendedNumber` (or `amendedNumber` without `isCreditNote`), a credit note reusing the number it corrects
+  and a corrected invoice dated after the credit note.
+
+### Added
+
+- **`eReporting.createCreditNote(original, input)`** — credit an invoice you sent through Taxora. Buyer, lines, amounts,
+  currency and the reference to the corrected invoice (number and date) are taken from `original`; partial credits pass
+  `invoiceLines`, `subtotal`, `taxAmount` and `total` together. Refused up front for invoices that were never sent
+  (`not_required`) and for credit notes.
+- **`eReporting.decideDelivery(country, id, scheme?)`** — `peppolLookup()` turned into an action
+  (`ComplianceDeliveryAction`: `einvoice`, `einvoice_pending`, `regular_invoice`) for a shop checkout.
+- **`calculateInvoiceTotals(lines)`** — subtotal, VAT and total of invoice lines, rounded the way the e-invoice is built,
+  so the header amounts of `createTransaction()` always match the lines.
+- **`ComplianceTaxCategory`** (`S`, `AA`, `AAA`, `K`, `G`, `AE`, `E`, `Z`) and `parseComplianceTaxCategory()`.
+- **`billing.getEInvoicingQuota(months?)`** — `GET /billing/einvoicing-quota` as `EInvoicingQuota` (documents included,
+  used, still free and what is due per month); `null` without e-invoicing.
+
 ## [1.9.0] — 2026-10-27
 
 ### Added

package/README.md

@@ -821,6 +821,41 @@ if (reach.isPending) {
 console.log(reach.status, reach.reachable, reach.documentTypes); // 'reachable' true [...]
 ```
 
+Or let the SDK turn the answer into an action (shop checkout, one call):
+
+```ts
+const decision = await client.eReporting.decideDelivery('NO', '974760673');
+switch (decision.action) {
+  case 'einvoice': // create the transaction, Taxora sends the e-invoice
+  case 'einvoice_pending': // no answer yet: create it anyway, Taxora asks again before sending
+    break;
+  case 'regular_invoice': // not on Peppol: send your usual invoice, nothing is billed
+    break;
+}
+```
+
+The SDK refuses input that cannot be right before any request: unknown tax categories
+(`ComplianceTaxCategory`: `S`, `AA`, `AAA`, `K`, `G`, `AE`, `E`, `Z`, any case), a category `E` line without its VATEX
+exemption code, currency and country codes that are not letters (they are upper-cased), a due date before the invoice
+date, and credit notes without (or invoices with) a corrected invoice. The API additionally checks that an e-invoice's
+`subtotal`, `taxAmount` and `total` match its lines — compute them from the lines:
+
+```ts
+import { calculateInvoiceTotals } from '@taxora/sdk';
+
+const { subtotal, taxAmount, total } = calculateInvoiceTotals(invoiceLines); // rounded like the e-invoice
+```
+
+Taxes without remembering category codes: `ComplianceTax.rate(25)` (category `S`, any rate above 0 %; in Norway 25/15/12 % are all `S`, for France's reduced rates pass `ComplianceTax.rate(10, 'TVA', 'AA')`), `zeroRated()` (`Z`),
+`exempt('VATEX-EU-132')` (`E`, code mandatory) and `reverseCharge()` (`AE`). The rate itself is yours to know; the API checks
+it against the country's catalogue. The tax name defaults to `VAT` (`ComplianceTax.rate(25, 'MVA')`).
+
+If your own system already shows the buyer a total, pass it as a safety net:
+`calculateInvoiceTotals(lines, { expectedTotal: 1249.99 })`. The totals always follow the lines, because the e-invoice is built
+from them. A difference up to 0.05 is reported as `roundingDifference`; anything larger throws, since then quantities, prices or
+rates are wrong. The invoice number is printed on the buyer's e-invoice and must be unique per enrollment (a different invoice
+with a used number answers `409 invoice_number_taken`).
+
 **4. Send an invoice** — Norway requires `transactionType: 'b2b_domestic_outbound'`, the buyer's
 organisation number (`counterpartyRegisterId`) and `counterpartyName` (enforced server-side, 422):
 
@@ -877,6 +912,21 @@ const creditNote = await client.eReporting.createTransaction({
 });
 console.log(creditNote.isCreditNote); // true
 
+// Shorter and harder to get wrong: credit an invoice you already sent. Buyer, lines, amounts,
+// currency and the reference to the corrected invoice are taken from it.
+const credit = await client.eReporting.createCreditNote(invoice, { creditNoteNumber: 'NO-2026-0001-CN' });
+
+// Partial credit: pass the credited lines and all amounts together.
+await client.eReporting.createCreditNote(invoice, {
+  creditNoteNumber: 'NO-2026-0001-CN2',
+  invoiceLines: [
+    { description: 'Consulting', quantity: 1, price: 1000, taxes: [{ name: 'MVA', percent: 25, category: 'S' }] },
+  ],
+  subtotal: 1000,
+  taxAmount: 250,
+  total: 1250,
+});
+
 // All Norwegian documents
 const noDocs = await client.eReporting.listTransactions({ country: 'NO' });
 ```
@@ -972,6 +1022,10 @@ for (const summary of page) {
 
 const september = await client.billing.getUsageSummaries('2026-09'); // with events; 404 for a period without usage
 console.log(september[0]?.events.length);
+
+// E-invoicing allowance: documents included per month, used, still free, what is due beyond it (null without e-invoicing)
+const quota = await client.billing.getEInvoicingQuota();
+console.log(quota?.current.freeRemaining, 'of', quota?.current.included, 'documents free this month');
 ```
 
 ---