@endora-commerce/mod-invoices 0.107.0 → 0.109.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/dist/admin/pages/InvoiceDetail.d.ts.map +1 -1
  2. package/dist/admin/pages/InvoiceDetail.js +3 -1
  3. package/dist/admin/pages/InvoiceDetail.js.map +1 -1
  4. package/dist/admin/templates/invoice-puck-config.d.ts.map +1 -1
  5. package/dist/admin/templates/invoice-puck-config.js +14 -2
  6. package/dist/admin/templates/invoice-puck-config.js.map +1 -1
  7. package/dist/backend/document/block-descriptions.d.ts.map +1 -1
  8. package/dist/backend/document/block-descriptions.js +2 -0
  9. package/dist/backend/document/block-descriptions.js.map +1 -1
  10. package/dist/backend/document/invoice-document-type.d.ts +6 -1
  11. package/dist/backend/document/invoice-document-type.d.ts.map +1 -1
  12. package/dist/backend/document/invoice-document-type.js +25 -1
  13. package/dist/backend/document/invoice-document-type.js.map +1 -1
  14. package/dist/backend/entities/invoice.entity.d.ts +13 -0
  15. package/dist/backend/entities/invoice.entity.d.ts.map +1 -1
  16. package/dist/backend/entities/invoice.entity.js +10 -0
  17. package/dist/backend/entities/invoice.entity.js.map +1 -1
  18. package/dist/backend/index.d.ts.map +1 -1
  19. package/dist/backend/index.js +53 -8
  20. package/dist/backend/index.js.map +1 -1
  21. package/dist/backend/invoices-prose.d.ts +63 -0
  22. package/dist/backend/invoices-prose.d.ts.map +1 -0
  23. package/dist/backend/invoices-prose.js +78 -0
  24. package/dist/backend/invoices-prose.js.map +1 -0
  25. package/dist/backend/pdf-components/sample.d.ts.map +1 -1
  26. package/dist/backend/pdf-components/sample.js +1 -0
  27. package/dist/backend/pdf-components/sample.js.map +1 -1
  28. package/dist/backend/pdf-components/sections.d.ts +29 -7
  29. package/dist/backend/pdf-components/sections.d.ts.map +1 -1
  30. package/dist/backend/pdf-components/sections.js +78 -38
  31. package/dist/backend/pdf-components/sections.js.map +1 -1
  32. package/dist/backend/pdf-components/tree-mapper.d.ts +3 -0
  33. package/dist/backend/pdf-components/tree-mapper.d.ts.map +1 -1
  34. package/dist/backend/pdf-components/tree-mapper.js +5 -5
  35. package/dist/backend/pdf-components/tree-mapper.js.map +1 -1
  36. package/dist/backend/plugin.d.ts +15 -1
  37. package/dist/backend/plugin.d.ts.map +1 -1
  38. package/dist/backend/plugin.js +3 -2
  39. package/dist/backend/plugin.js.map +1 -1
  40. package/dist/backend/seeds/generic-invoice-template.d.ts.map +1 -1
  41. package/dist/backend/seeds/generic-invoice-template.js +5 -0
  42. package/dist/backend/seeds/generic-invoice-template.js.map +1 -1
  43. package/dist/backend/services/auto-issue-reactor.d.ts.map +1 -1
  44. package/dist/backend/services/auto-issue-reactor.js +11 -0
  45. package/dist/backend/services/auto-issue-reactor.js.map +1 -1
  46. package/dist/backend/services/corrective-invoice.d.ts +90 -0
  47. package/dist/backend/services/corrective-invoice.d.ts.map +1 -1
  48. package/dist/backend/services/corrective-invoice.js +275 -63
  49. package/dist/backend/services/corrective-invoice.js.map +1 -1
  50. package/dist/backend/services/cross-module-context.d.ts +7 -0
  51. package/dist/backend/services/cross-module-context.d.ts.map +1 -1
  52. package/dist/backend/services/cross-module-context.js +19 -0
  53. package/dist/backend/services/cross-module-context.js.map +1 -1
  54. package/dist/backend/services/invoice-email-dispatch.d.ts +7 -0
  55. package/dist/backend/services/invoice-email-dispatch.d.ts.map +1 -1
  56. package/dist/backend/services/invoice-email-dispatch.js +10 -3
  57. package/dist/backend/services/invoice-email-dispatch.js.map +1 -1
  58. package/dist/backend/services/invoice-line-builder.d.ts +63 -13
  59. package/dist/backend/services/invoice-line-builder.d.ts.map +1 -1
  60. package/dist/backend/services/invoice-line-builder.js +79 -28
  61. package/dist/backend/services/invoice-line-builder.js.map +1 -1
  62. package/dist/backend/services/invoice-paid.d.ts +56 -0
  63. package/dist/backend/services/invoice-paid.d.ts.map +1 -0
  64. package/dist/backend/services/invoice-paid.js +74 -0
  65. package/dist/backend/services/invoice-paid.js.map +1 -0
  66. package/dist/backend/services/invoice-service.d.ts +43 -2
  67. package/dist/backend/services/invoice-service.d.ts.map +1 -1
  68. package/dist/backend/services/invoice-service.js +115 -56
  69. package/dist/backend/services/invoice-service.js.map +1 -1
  70. package/dist/manifest.d.ts +3 -1
  71. package/dist/manifest.d.ts.map +1 -1
  72. package/dist/manifest.js +34 -6
  73. package/dist/manifest.js.map +1 -1
  74. package/dist/migrations/20261024T145631_invoices_vat_summary.d.ts +18 -0
  75. package/dist/migrations/20261024T145631_invoices_vat_summary.d.ts.map +1 -0
  76. package/dist/migrations/20261024T145631_invoices_vat_summary.js +22 -0
  77. package/dist/migrations/20261024T145631_invoices_vat_summary.js.map +1 -0
  78. package/dist/migrations/index.d.ts +2 -1
  79. package/dist/migrations/index.d.ts.map +1 -1
  80. package/dist/migrations/index.js +3 -1
  81. package/dist/migrations/index.js.map +1 -1
  82. package/docs/invoices.md +45 -0
  83. package/i18n/en.json +38 -1
  84. package/i18n/pl.json +38 -1
  85. package/package.json +14 -14
package/docs/invoices.md CHANGED
@@ -25,6 +25,51 @@ dependency-light renderer, persists the bytes through the `assets` module,
25
25
  and writes the asset id back onto the Order. Failures emit
26
26
  `invoice.generation_failed.v1` for an admin retry queue.
27
27
 
28
+ ### Unit prices and line values
29
+
30
+ An invoice line carries the order line's **unit net price at up to four decimal places**
31
+ (`invoice_lines.unit_net_price`, `numeric(14,4)`), and its net value is the unit price × the
32
+ quantity rounded half-up to two places once — the order line's own net. The PDF's *Cena netto*
33
+ column shows the unit price with its significant places, up to four (0,0125), and two when the third
34
+ and fourth are zero; the value columns and the totals show two. A Polish invoice may state a unit
35
+ price this precisely: the VAT Act names the unit net price without fixing its decimal places.
36
+
37
+ ### What a VAT invoice records as paid, and when it is not issued
38
+
39
+ A VAT invoice records as paid what was received for the order and kept:
40
+ each captured payment attempt, less everything refunded. An order recorded as
41
+ paid with nothing captured (a confirmed bank transfer), or with `payments`
42
+ absent, was received in its stored total. An order on credit terms is unpaid by
43
+ arrangement when it is invoiced, and nothing of it is counted as paid.
44
+
45
+ Every refund counts once, whichever way it was made:
46
+
47
+ - a refund through the payment gateway, as `payments` recorded it;
48
+ - a return settled with a **refund by bank transfer** (any order not paid
49
+ through a gateway — the operator makes the transfer) or with a **credit to
50
+ the credit limit**, as the return recorded it. A refund still waiting for a
51
+ person to make it is not counted;
52
+ - an order an operator marked as **refunded** was refunded everything that was
53
+ received for it: its whole total when nothing was captured, and what was
54
+ captured otherwise — a refund settled by hand, for example after the gateway
55
+ reported an amount the payment could not record. The mark is never added to
56
+ refunds already recorded: a gateway refund on the payment counts once.
57
+
58
+ With the `returns` module switched off, only the refunds `payments` recorded
59
+ are deducted.
60
+
61
+ An order **refunded in full before it was invoiced** — the refunds equal what
62
+ was received and cover the whole order total — is not invoiced: there is no
63
+ sale left to document. Issuing answers `422 INVOICE_ORDER_REFUNDED` and draws
64
+ no number; automatic issuance skips the order and logs the reason. An order
65
+ refunded only in part is invoiced, with what was kept as paid.
66
+
67
+ The **amount due** is the gross less what was paid, and never negative. When
68
+ more was paid than the gross, the amount due is 0 and the invoice states the
69
+ difference as the **overpayment** (`overpayment` in the API, the
70
+ *Overpayment* row on the admin screen, *Nadpłata* on the PDF — the label is a
71
+ setting of the totals block, and the row can be hidden there).
72
+
28
73
  ## Entities
29
74
 
30
75
  `Invoice` (number, issued/dated timestamps, asset reference,
package/i18n/en.json CHANGED
@@ -15,6 +15,7 @@
15
15
  "errors.INVOICE_NUMBER_PATTERN_COLLIDES": "This numbering pattern can produce the same document number as another sales channel. Invoice numbers must be unique across the whole platform.",
16
16
  "errors.INVOICE_NUMBER_PATTERN_COLLIDES.other_channel": "This numbering pattern can produce the same document number as sales channel \"{channel}\". Invoice numbers are unique across the whole platform, so give this channel a pattern the other one cannot repeat — adding the channel token is the usual way.",
17
17
  "errors.INVOICE_NUMBER_PATTERN_COLLIDES.no_sequence_token": "This numbering pattern has no sequence token, so every document in this channel would be given the same number. The field description lists the tokens you can use.",
18
+ "errors.INVOICE_ORDER_REFUNDED": "This order's payments were refunded in full before it was invoiced, so there is no sale left to invoice. Nothing was issued.",
18
19
  "errors.INVOICE_NUMBER_ALREADY_ISSUED": "This document number is already in use. Invoice numbers are unique across the whole platform.",
19
20
  "errors.INVOICE_NUMBER_ALREADY_ISSUED.other_channel": "Invoice number {number} is already used by sales channel \"{channel}\". Give this channel its own numbering pattern before issuing again — nothing was issued.",
20
21
  "errors.INVOICE_NUMBER_ALREADY_ISSUED.same_channel": "Invoice number {number} has already been issued in this sales channel, so its numbering pattern is producing repeats — nothing was issued.",
@@ -41,5 +42,41 @@
41
42
  "blocks.invoiceFooter.description": "The legal footer printed at the bottom of the invoice.",
42
43
  "blocks.category.invoice": "Invoice sections",
43
44
  "documentTypes.invoice.label": "Invoice",
44
- "documentTypes.invoice.description": "The invoice PDF: downloaded by administrators and customers, and attached to the invoice e-mail."
45
+ "documentTypes.invoice.description": "The invoice PDF: downloaded by administrators and customers, and attached to the invoice e-mail.",
46
+ "pdf.title.invoice": "Invoice",
47
+ "pdf.title.proforma": "Proforma invoice",
48
+ "pdf.title.correction": "Corrective invoice",
49
+ "pdf.title.wz": "Goods dispatch note",
50
+ "pdf.title.numbered": "{title} No. {number}",
51
+ "pdf.label.ksefNumber": "KSeF number",
52
+ "pdf.label.issuedAt": "Issue date",
53
+ "pdf.label.saleDate": "Sale date",
54
+ "pdf.label.paymentDue": "Payment due",
55
+ "pdf.label.paymentMethod": "Payment method",
56
+ "pdf.label.seller": "Seller",
57
+ "pdf.label.buyer": "Buyer",
58
+ "pdf.label.taxId": "Tax ID",
59
+ "pdf.column.ordinal": "No.",
60
+ "pdf.column.name": "Name",
61
+ "pdf.column.unit": "Unit",
62
+ "pdf.column.quantity": "Qty",
63
+ "pdf.column.unitNet": "Net price",
64
+ "pdf.column.taxRate": "Rate",
65
+ "pdf.column.net": "Net value",
66
+ "pdf.column.gross": "Gross value",
67
+ "pdf.vat.rate": "VAT rate",
68
+ "pdf.vat.amount": "VAT amount",
69
+ "pdf.label.total": "Total",
70
+ "pdf.label.paid": "Paid",
71
+ "pdf.label.amountDue": "Amount due",
72
+ "pdf.label.overpayment": "Overpayment",
73
+ "pdf.label.inWords": "In words",
74
+ "pdf.footer.default": "Thank you for your business.\n{{var seller.legalName}} · Tax ID {{var seller.taxId}}",
75
+ "lines.item": "Item",
76
+ "lines.unit.piece": "pcs",
77
+ "lines.unit.service": "svc",
78
+ "lines.delivery": "Delivery",
79
+ "lines.paymentSurcharge": "Payment method surcharge",
80
+ "lines.discount": "Discount",
81
+ "actions.openInvoices.keywords": "invoices"
45
82
  }
package/i18n/pl.json CHANGED
@@ -15,6 +15,7 @@
15
15
  "errors.INVOICE_NUMBER_PATTERN_COLLIDES": "Ten wzorzec numeracji może wygenerować taki sam numer dokumentu jak inny kanał sprzedaży. Numery faktur muszą być unikalne w całej platformie.",
16
16
  "errors.INVOICE_NUMBER_PATTERN_COLLIDES.other_channel": "Ten wzorzec numeracji może wygenerować taki sam numer dokumentu jak kanał sprzedaży \"{channel}\". Numery faktur są unikalne w całej platformie, więc nadaj temu kanałowi wzorzec, którego tamten nie może powtórzyć — zwykle wystarczy dodać token kanału.",
17
17
  "errors.INVOICE_NUMBER_PATTERN_COLLIDES.no_sequence_token": "Ten wzorzec numeracji nie zawiera tokenu sekwencji, więc każdy dokument w tym kanale otrzymałby ten sam numer. Dostępne tokeny są wymienione w opisie pola.",
18
+ "errors.INVOICE_ORDER_REFUNDED": "Płatności za to zamówienie zostały w całości zwrócone przed wystawieniem faktury, więc nie ma sprzedaży do zafakturowania. Niczego nie wystawiono.",
18
19
  "errors.INVOICE_NUMBER_ALREADY_ISSUED": "Ten numer dokumentu jest już zajęty. Numery faktur są unikalne w całej platformie.",
19
20
  "errors.INVOICE_NUMBER_ALREADY_ISSUED.other_channel": "Numer faktury {number} jest już używany przez kanał sprzedaży \"{channel}\". Nadaj temu kanałowi własny wzorzec numeracji przed ponowną próbą — nic nie zostało wystawione.",
20
21
  "errors.INVOICE_NUMBER_ALREADY_ISSUED.same_channel": "Numer faktury {number} został już wystawiony w tym kanale sprzedaży, więc jego wzorzec numeracji generuje powtórzenia — nic nie zostało wystawione.",
@@ -41,5 +42,41 @@
41
42
  "blocks.invoiceFooter.description": "Stopka prawna drukowana na dole faktury.",
42
43
  "blocks.category.invoice": "Sekcje faktury",
43
44
  "documentTypes.invoice.label": "Faktura",
44
- "documentTypes.invoice.description": "PDF faktury: pobierany przez administratorów i klientów oraz dołączany do e-maila z fakturą."
45
+ "documentTypes.invoice.description": "PDF faktury: pobierany przez administratorów i klientów oraz dołączany do e-maila z fakturą.",
46
+ "pdf.title.invoice": "Faktura",
47
+ "pdf.title.proforma": "Faktura proforma",
48
+ "pdf.title.correction": "Faktura korygująca",
49
+ "pdf.title.wz": "Dokument WZ",
50
+ "pdf.title.numbered": "{title} nr {number}",
51
+ "pdf.label.ksefNumber": "Numer w KSeF",
52
+ "pdf.label.issuedAt": "Data wystawienia",
53
+ "pdf.label.saleDate": "Data sprzedaży",
54
+ "pdf.label.paymentDue": "Termin płatności",
55
+ "pdf.label.paymentMethod": "Metoda płatności",
56
+ "pdf.label.seller": "Sprzedawca",
57
+ "pdf.label.buyer": "Nabywca",
58
+ "pdf.label.taxId": "NIP",
59
+ "pdf.column.ordinal": "Lp",
60
+ "pdf.column.name": "Nazwa",
61
+ "pdf.column.unit": "Jedn.",
62
+ "pdf.column.quantity": "Ilość",
63
+ "pdf.column.unitNet": "Cena netto",
64
+ "pdf.column.taxRate": "Stawka",
65
+ "pdf.column.net": "Wartość netto",
66
+ "pdf.column.gross": "Wartość brutto",
67
+ "pdf.vat.rate": "Stawka VAT",
68
+ "pdf.vat.amount": "Kwota VAT",
69
+ "pdf.label.total": "Razem",
70
+ "pdf.label.paid": "Zapłacono",
71
+ "pdf.label.amountDue": "Do zapłaty",
72
+ "pdf.label.overpayment": "Nadpłata",
73
+ "pdf.label.inWords": "Słownie",
74
+ "pdf.footer.default": "Dziękujemy za współpracę.\n{{var seller.legalName}} · NIP {{var seller.taxId}}",
75
+ "lines.item": "Pozycja",
76
+ "lines.unit.piece": "szt.",
77
+ "lines.unit.service": "usł.",
78
+ "lines.delivery": "Dostawa",
79
+ "lines.paymentSurcharge": "Dopłata za metodę płatności",
80
+ "lines.discount": "Rabat",
81
+ "actions.openInvoices.keywords": "faktury"
45
82
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@endora-commerce/mod-invoices",
3
- "version": "0.107.0",
3
+ "version": "0.109.0",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "description": "Invoice generation, numbering, PDF templates, corrections, and email delivery.",
@@ -62,12 +62,12 @@
62
62
  "react": "^19",
63
63
  "react-router-dom": "^7",
64
64
  "zod": "^4",
65
- "@endora-commerce/admin-kit": "0.107.0",
66
- "@endora-commerce/contracts": "0.107.0",
67
- "@endora-commerce/email-components": "0.107.0",
68
- "@endora-commerce/page-builder-admin": "0.107.0",
69
- "@endora-commerce/page-builder-core": "0.107.0",
70
- "@endora-commerce/platform": "0.107.0"
65
+ "@endora-commerce/admin-kit": "0.109.0",
66
+ "@endora-commerce/contracts": "0.109.0",
67
+ "@endora-commerce/email-components": "0.109.0",
68
+ "@endora-commerce/page-builder-admin": "0.109.0",
69
+ "@endora-commerce/page-builder-core": "0.109.0",
70
+ "@endora-commerce/platform": "0.109.0"
71
71
  },
72
72
  "peerDependenciesMeta": {
73
73
  "@endora-commerce/admin-kit": {
@@ -106,15 +106,15 @@
106
106
  "typescript": "^5.9.3",
107
107
  "vitest": "^4.1.11",
108
108
  "zod": "^4.2.0",
109
- "@endora-commerce/admin-kit": "0.107.0",
110
- "@endora-commerce/contracts": "0.107.0",
111
- "@endora-commerce/email-components": "0.107.0",
112
- "@endora-commerce/page-builder-admin": "0.107.0",
113
- "@endora-commerce/page-builder-core": "0.107.0",
114
- "@endora-commerce/platform": "0.107.0"
109
+ "@endora-commerce/admin-kit": "0.109.0",
110
+ "@endora-commerce/contracts": "0.109.0",
111
+ "@endora-commerce/email-components": "0.109.0",
112
+ "@endora-commerce/page-builder-admin": "0.109.0",
113
+ "@endora-commerce/page-builder-core": "0.109.0",
114
+ "@endora-commerce/platform": "0.109.0"
115
115
  },
116
116
  "scripts": {
117
- "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.json",
117
+ "build": "node ../../../scripts/clean-package-dist.mjs --src src --out dist && tsc -p tsconfig.build.json && tsc -p tsconfig.ui.build.json",
118
118
  "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.ui.json --noEmit",
119
119
  "lint": "eslint src",
120
120
  "test": "vitest run"