@endevops/peppol-schema 0.1.0-beta.7 → 0.1.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 (2) hide show
  1. package/README.md +70 -19
  2. package/package.json +18 -2
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @endevops/peppol-schema
2
2
 
3
- TypeScript library for PEPPOL schema validation and parsing.
3
+ TypeScript Effect Schema models for **PEPPOL BIS Billing 3.0** — decode, validate and encode **Invoice, Credit Note, Invoice Response and Message Level Response** XML, with generated PEPPOL code lists, Schematron rules and identifier validations (IBAN, GLN, VAT, fiscal codes).
4
4
 
5
5
  ## Install
6
6
 
@@ -8,26 +8,77 @@ TypeScript library for PEPPOL schema validation and parsing.
8
8
  pnpm add @endevops/peppol-schema
9
9
  ```
10
10
 
11
+ Requires `effect`, `fast-xml-parser` and `fast-xml-builder` as peer dependencies — pnpm installs them automatically unless you opt out.
12
+
11
13
  ## Usage
12
14
 
15
+ Decode any PEPPOL document from an XML string (dispatches on the root element; `ApplicationResponse` is split by `cbc:ProfileID`):
16
+
17
+ ```ts
18
+ import { Schema } from 'effect';
19
+ import { PeppolCreditNote, PeppolInvoice, PeppolInvoiceResponse, PeppolMessageLevelResponse, peppolDocumentSchema } from '@endevops/peppol-schema';
20
+
21
+ const doc = Schema.decodeUnknownSync(peppolDocumentSchema)(xmlString);
22
+ if (Schema.is(PeppolInvoice)(doc)) {
23
+ /* doc.invoiceLines … */
24
+ } else if (Schema.is(PeppolCreditNote)(doc)) {
25
+ /* doc.creditNoteLines … */
26
+ } else if (Schema.is(PeppolInvoiceResponse)(doc)) {
27
+ /* invoice response … */
28
+ } else if (Schema.is(PeppolMessageLevelResponse)(doc)) {
29
+ /* message-level response … */
30
+ }
31
+
32
+ // Round-trip back to XML:
33
+ const xml = Schema.encodeUnknownSync(peppolDocumentSchema)(doc);
34
+ ```
35
+
36
+ Run the Schematron rule set or a single rule:
37
+
38
+ ```ts
39
+ import { Effect } from 'effect';
40
+ import { Schematron, validateCenEn16931Br01 } from '@endevops/peppol-schema/schematron';
41
+
42
+ const program = Effect.gen(function* () {
43
+ yield* (yield* Schematron).run(doc); // fails with SchematronValidationError listing every failed rule
44
+ yield* validateCenEn16931Br01(doc); // or run one rule directly
45
+ }).pipe(Effect.provide(Schematron.layer));
46
+ ```
47
+
48
+ Validate identifiers:
49
+
13
50
  ```ts
14
- import { parseDocument } from '@endevops/peppol-schema';
15
- import { InvoiceSchema } from '@endevops/peppol-schema/schemas';
16
- import { validatePEPPOL } from '@endevops/peppol-schema/validations';
17
- import { InvoiceTypeCode } from '@endevops/peppol-schema/values';
51
+ import { checkPIVA, isValidGLN, isValidIBAN } from '@endevops/peppol-schema/validations';
52
+ import { invoiceTypeCodes } from '@endevops/peppol-schema/values';
53
+
54
+ isValidIBAN('IT60X0542811101000000123456'); // boolean
55
+ isValidGLN('7300010000001'); // { success: true } | { success: false; expected; actual }
56
+ checkPIVA('01234567890'); // 0 means valid
57
+ invoiceTypeCodes['380']; // 'Commercial invoice'
18
58
  ```
19
59
 
60
+ ## Features
61
+
62
+ - **4 document types**: Invoice, Credit Note, Invoice Response, Message Level Response (UBL 2.1, BIS Billing 3.0) with XML round-trip via `peppolDocumentSchema`
63
+ - **Effect Schema** models with typed decode/encode and `isPeppol*` type guards
64
+ - **Generated code lists** (`/values`): currencies, countries, tax schemes, UNCL, UNTDID, EAS, ICD etc. from OpenPEPPOL
65
+ - **Schematron rules** (`/schematron`): shared PEPPOL + CEN rules and per-country overlays (`de`, `dk`, `gr`, `is`, `it`, `nl`, `no`, `se`), runnable as an Effect service or one rule at a time
66
+ - **Identifier validations** (`/validations`): IBAN, GLN, MOD97/MOD11, Luhn, ABN, plus country checks (IT Partita IVA / Codice Fiscale, SE orgnr, GR TIN)
67
+ - **XML options** (`/xml`): `fast-xml-parser` / `fast-xml-builder` options tuned for PEPPOL
68
+ - **Translation generator CLI** (`/generate-translations`) for localized field labels
69
+
20
70
  ## Entry Points
21
71
 
22
- | Import path | Description |
23
- | ----------------------------------------------- | -------------------------------------------- |
24
- | `@endevops/peppol-schema` | Main exports (parser, types) |
25
- | `@endevops/peppol-schema/effect` | Effect Schema API |
26
- | `@endevops/peppol-schema/generate-translations` | CLI that generates translation files |
27
- | `@endevops/peppol-schema/schematron` | Schematron rules |
28
- | `@endevops/peppol-schema/validations` | PEPPOL validation rules |
29
- | `@endevops/peppol-schema/values` | Generated value enums from PEPPOL code lists |
30
- | `@endevops/peppol-schema/xml` | XML parser and builder options |
72
+ | Import path | Description |
73
+ | ------------------------------------------------ | -------------------------------------------------------- |
74
+ | `@endevops/peppol-schema` | Document schemas, `peppolDocumentSchema`, types |
75
+ | `@endevops/peppol-schema/generate-translations` | CLI that generates translation files |
76
+ | `@endevops/peppol-schema/schematron` | PEPPOL + CEN + per-country Schematron rules |
77
+ | `@endevops/peppol-schema/validations` | Identifier and checksum validation rules |
78
+ | `@endevops/peppol-schema/values` | Generated value maps from PEPPOL code lists |
79
+ | `@endevops/peppol-schema/xml` | XML parser and builder options |
80
+ | `@endevops/peppol-schema/constants` | Doctype ids, process ids, profile ids, transport profile |
81
+ | `@endevops/peppol-schema/invoice-response-codes` | Invoice Response status/reason codes |
31
82
 
32
83
  ## Development
33
84
 
@@ -35,9 +86,10 @@ import { InvoiceTypeCode } from '@endevops/peppol-schema/values';
35
86
  pnpm install
36
87
  pnpm build # Build with tsdown
37
88
  pnpm dev # Watch mode
38
- pnpm oxlint # Lint
39
- pnpm oxfmt . # Format
40
- pnpm vitest run # Test
89
+ pnpm lint # Lint (oxlint --type-aware)
90
+ pnpm format # Format (oxfmt)
91
+ pnpm test # Test (vitest run)
92
+ pnpm generate # Regenerate code lists (bun scripts/values.ts)
41
93
  tsc --noEmit # Typecheck
42
94
  ```
43
95
 
@@ -61,8 +113,7 @@ See [docs/versioning.md](docs/versioning.md) for the full strategy.
61
113
 
62
114
  ## Tech Stack
63
115
 
64
- - [Effect](https://effect.website/) - Typed effects & Schema decoders
65
- - [Zod v4](https://zod.dev/) - Runtime validation
116
+ - [Effect](https://effect.website/) - Typed effects & Schema models
66
117
  - [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) / [fast-xml-builder](https://github.com/NaturalIntelligence/fast-xml-builder) - XML parsing
67
118
  - [tsdown](https://tsdown.dev/) - Bundling (unbundled ESM)
68
119
  - [oxlint](https://oxc.rs/) / [oxfmt](https://oxc.rs/) - Linting & formatting
package/package.json CHANGED
@@ -1,8 +1,24 @@
1
1
  {
2
2
  "$schema": "https://raw.githubusercontent.com/SchemaStore/schemastore/refs/heads/master/src/schemas/json/package.json",
3
3
  "name": "@endevops/peppol-schema",
4
- "version": "0.1.0-beta.7",
5
- "description": "A simple example library built by tsdown",
4
+ "version": "0.1.0",
5
+ "description": "TypeScript Effect Schema models for PEPPOL BIS Billing 3.0 — decode, validate and encode Invoice, Credit Note, Invoice Response and Message Level Response XML, with generated code lists, Schematron rules and identifier validations",
6
+ "keywords": [
7
+ "bis-billing",
8
+ "credit-note",
9
+ "e-invoicing",
10
+ "e-procurement",
11
+ "effect",
12
+ "invoice",
13
+ "openpeppol",
14
+ "peppol",
15
+ "peppol-bis",
16
+ "schematron",
17
+ "typescript",
18
+ "ubl",
19
+ "validation",
20
+ "xml"
21
+ ],
6
22
  "license": "Apache-2.0",
7
23
  "contributors": [
8
24
  {