@financica/ubl 0.15.1 → 0.17.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.
- package/CHANGELOG.md +168 -0
- package/README.md +20 -25
- package/dist/build/index.d.ts +122 -221
- package/dist/build/index.d.ts.map +1 -1
- package/dist/build/index.js +277 -232
- package/dist/build/index.js.map +1 -1
- package/dist/errors-C9YYJ1xR.js +33 -0
- package/dist/errors-C9YYJ1xR.js.map +1 -0
- package/dist/index.d.ts +31 -225
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +327 -260
- package/dist/index.js.map +1 -1
- package/dist/types-DossV2at.d.ts +389 -0
- package/dist/types-DossV2at.d.ts.map +1 -0
- package/package.json +16 -7
- package/src/attachments.ts +67 -0
- package/src/build/address.ts +63 -0
- package/src/build/attachment.ts +37 -0
- package/src/build/identifiers.ts +253 -0
- package/src/build/index.ts +79 -0
- package/src/build/numeric.ts +47 -0
- package/src/build/party.ts +129 -0
- package/src/build/tax-category.ts +153 -0
- package/src/build/tax-totals.ts +154 -0
- package/src/build/ubl/constants.ts +30 -0
- package/src/build/ubl/serialize.ts +437 -0
- package/src/build/utils.ts +14 -0
- package/src/build/xml.ts +84 -0
- package/src/errors.ts +31 -0
- package/src/index.ts +44 -0
- package/src/mlr.ts +156 -0
- package/src/normalize.ts +408 -0
- package/src/parser.ts +651 -0
- package/src/types.ts +398 -0
- package/src/xml-dom.ts +37 -0
package/src/build/xml.ts
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Minimal, dependency-free XML builder + serializer.
|
|
3
|
+
*
|
|
4
|
+
* UBL is order-sensitive (every element sequence is fixed by the schema), so
|
|
5
|
+
* children are always explicit, ordered arrays. There is no attribute or text
|
|
6
|
+
* coercion magic beyond escaping — the UBL layer is responsible for emitting
|
|
7
|
+
* elements in the right order.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
export type XmlAttrs = Record<string, string | number | null | undefined>;
|
|
11
|
+
|
|
12
|
+
export interface XmlElement {
|
|
13
|
+
name: string;
|
|
14
|
+
attrs?: XmlAttrs;
|
|
15
|
+
/** Leaf text content. Mutually exclusive with `children`. */
|
|
16
|
+
text?: string | number | null;
|
|
17
|
+
/** Child elements. Mutually exclusive with `text`. */
|
|
18
|
+
children?: XmlElement[];
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** Falsy children are dropped, so callers can write `cond && el(...)`. */
|
|
22
|
+
type ChildSpec = XmlElement | null | undefined | false;
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Build an XML element.
|
|
26
|
+
*
|
|
27
|
+
* el("cbc:ID", null, "INV-1") → <cbc:ID>INV-1</cbc:ID>
|
|
28
|
+
* el("cbc:Amount", { currencyID: "EUR" }, "10.00") → <cbc:Amount currencyID="EUR">10.00</cbc:Amount>
|
|
29
|
+
* el("cac:Party", null, [child, cond && child2]) → nested element
|
|
30
|
+
*/
|
|
31
|
+
export const el = (
|
|
32
|
+
name: string,
|
|
33
|
+
attrs?: XmlAttrs | null,
|
|
34
|
+
content?: string | number | null | ChildSpec[],
|
|
35
|
+
): XmlElement => {
|
|
36
|
+
if (Array.isArray(content)) {
|
|
37
|
+
return {
|
|
38
|
+
name,
|
|
39
|
+
...(attrs ? { attrs } : {}),
|
|
40
|
+
children: content.filter((c): c is XmlElement => Boolean(c)),
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
return {
|
|
44
|
+
name,
|
|
45
|
+
...(attrs ? { attrs } : {}),
|
|
46
|
+
...(content !== undefined ? { text: content } : {}),
|
|
47
|
+
};
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
const escapeText = (value: string): string =>
|
|
51
|
+
value.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">");
|
|
52
|
+
|
|
53
|
+
const escapeAttr = (value: string): string => escapeText(value).replace(/"/g, """);
|
|
54
|
+
|
|
55
|
+
const serializeAttrs = (attrs: XmlAttrs | undefined): string => {
|
|
56
|
+
if (!attrs) return "";
|
|
57
|
+
return Object.entries(attrs)
|
|
58
|
+
.filter(([, value]) => value !== null && value !== undefined)
|
|
59
|
+
.map(([key, value]) => ` ${key}="${escapeAttr(String(value))}"`)
|
|
60
|
+
.join("");
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
const serializeElement = (node: XmlElement, indentLevel: number): string => {
|
|
64
|
+
const pad = " ".repeat(indentLevel);
|
|
65
|
+
const attrs = serializeAttrs(node.attrs);
|
|
66
|
+
|
|
67
|
+
if (node.text !== undefined && node.text !== null) {
|
|
68
|
+
return `${pad}<${node.name}${attrs}>${escapeText(String(node.text))}</${node.name}>`;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
const children = node.children ?? [];
|
|
72
|
+
if (children.length === 0) {
|
|
73
|
+
return `${pad}<${node.name}${attrs}/>`;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const inner = children
|
|
77
|
+
.map((child) => serializeElement(child, indentLevel + 1))
|
|
78
|
+
.join("\n");
|
|
79
|
+
return `${pad}<${node.name}${attrs}>\n${inner}\n${pad}</${node.name}>`;
|
|
80
|
+
};
|
|
81
|
+
|
|
82
|
+
/** Serialize a root element into a UTF-8 XML document string. */
|
|
83
|
+
export const serializeDocument = (root: XmlElement): string =>
|
|
84
|
+
`<?xml version="1.0" encoding="UTF-8"?>\n${serializeElement(root, 0)}\n`;
|
package/src/errors.ts
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Thrown by the parse side of this package when input is broken: malformed
|
|
3
|
+
* XML, or a UBL document missing an element EN 16931 makes mandatory. A parser
|
|
4
|
+
* returns `null` instead when the input is well-formed but not the document
|
|
5
|
+
* type it parses.
|
|
6
|
+
*/
|
|
7
|
+
export class UblParseError extends Error {
|
|
8
|
+
override readonly cause?: unknown;
|
|
9
|
+
|
|
10
|
+
constructor(message: string, options?: { cause?: unknown }) {
|
|
11
|
+
super(message);
|
|
12
|
+
this.name = "UblParseError";
|
|
13
|
+
if (options && "cause" in options) this.cause = options.cause;
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Thrown by the build side when a model cannot be serialized: a field EN 16931
|
|
19
|
+
* / Peppol BIS Billing 3.0 makes mandatory on the wire is missing, or a build
|
|
20
|
+
* helper is handed input it cannot turn into one. The message names the BT /
|
|
21
|
+
* model field.
|
|
22
|
+
*/
|
|
23
|
+
export class UblBuildError extends Error {
|
|
24
|
+
override readonly cause?: unknown;
|
|
25
|
+
|
|
26
|
+
constructor(message: string, options?: { cause?: unknown }) {
|
|
27
|
+
super(message);
|
|
28
|
+
this.name = "UblBuildError";
|
|
29
|
+
if (options && "cause" in options) this.cause = options.cause;
|
|
30
|
+
}
|
|
31
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
export {
|
|
2
|
+
extractUblEmbeddedAttachments,
|
|
3
|
+
isPdfLikeAttachment,
|
|
4
|
+
type UblEmbeddedAttachment,
|
|
5
|
+
} from "./attachments.js";
|
|
6
|
+
export { UblBuildError, UblParseError } from "./errors.js";
|
|
7
|
+
export { parseUblInvoice } from "./parser.js";
|
|
8
|
+
export {
|
|
9
|
+
isPeppolMessageLevelResponse,
|
|
10
|
+
parsePeppolMessageLevelResponse,
|
|
11
|
+
PEPPOL_MLR_DOCUMENT_TYPE_VALUE,
|
|
12
|
+
PEPPOL_MLR_PROCESS_VALUE,
|
|
13
|
+
type PeppolMessageLevelResponse,
|
|
14
|
+
} from "./mlr.js";
|
|
15
|
+
export {
|
|
16
|
+
decodeXmlBytes,
|
|
17
|
+
normalizeCurrency,
|
|
18
|
+
normalizeUblResponse,
|
|
19
|
+
parseDate,
|
|
20
|
+
parseUblInvoiceDocument,
|
|
21
|
+
} from "./normalize.js";
|
|
22
|
+
export type {
|
|
23
|
+
InvoiceExtractionDTO,
|
|
24
|
+
UblAddress,
|
|
25
|
+
UblAllowanceCharge,
|
|
26
|
+
UblAttachment,
|
|
27
|
+
UblBillingReference,
|
|
28
|
+
UblCompanyId,
|
|
29
|
+
UblContact,
|
|
30
|
+
UblDelivery,
|
|
31
|
+
UblDocumentReference,
|
|
32
|
+
UblEndpoint,
|
|
33
|
+
UblInvoice,
|
|
34
|
+
UblInvoicePeriod,
|
|
35
|
+
UblItemProperty,
|
|
36
|
+
UblLine,
|
|
37
|
+
UblMonetaryTotal,
|
|
38
|
+
UblParty,
|
|
39
|
+
UblPartyIdentification,
|
|
40
|
+
UblPaymentMeans,
|
|
41
|
+
UblTaxCategory,
|
|
42
|
+
UblTaxSubtotal,
|
|
43
|
+
UblTaxTotal,
|
|
44
|
+
} from "./types.js";
|
package/src/mlr.ts
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
import type { Element } from "@xmldom/xmldom";
|
|
2
|
+
import { UblParseError } from "./errors.js";
|
|
3
|
+
import { CAC_NS, CBC_NS, parseXmlDocument } from "./xml-dom.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Peppol BIS MLR (Message Level Response) document-type identifier value
|
|
7
|
+
* (Peppol `busdox-docid-qns` scheme).
|
|
8
|
+
*/
|
|
9
|
+
export const PEPPOL_MLR_DOCUMENT_TYPE_VALUE =
|
|
10
|
+
"urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1";
|
|
11
|
+
|
|
12
|
+
/** Peppol BIS MLR process identifier value. */
|
|
13
|
+
export const PEPPOL_MLR_PROCESS_VALUE = "urn:fdc:peppol.eu:poacc:bis:mlr:3";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* A parsed Peppol Message Level Response (a UBL `ApplicationResponse`). Every
|
|
17
|
+
* field is optional: a given MLR may omit any of them, and an omitted field is
|
|
18
|
+
* an absent key.
|
|
19
|
+
*/
|
|
20
|
+
export interface PeppolMessageLevelResponse {
|
|
21
|
+
customizationId?: string | undefined;
|
|
22
|
+
profileId?: string | undefined;
|
|
23
|
+
responseId?: string | undefined;
|
|
24
|
+
issueDate?: string | undefined;
|
|
25
|
+
issueTime?: string | undefined;
|
|
26
|
+
referencedDocumentId?: string | undefined;
|
|
27
|
+
responseCode?: string | undefined;
|
|
28
|
+
description?: string | undefined;
|
|
29
|
+
/** Sender participant id as `schemeID:value` (e.g. `0208:0793904121`). */
|
|
30
|
+
senderIdentifier?: string | undefined;
|
|
31
|
+
/** Receiver participant id as `schemeID:value`. */
|
|
32
|
+
receiverIdentifier?: string | undefined;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
const trimmed = (value: string | null | undefined): string | undefined => {
|
|
36
|
+
const text = value?.trim();
|
|
37
|
+
return text ? text : undefined;
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
/** First descendant CBC element's trimmed text, or undefined. */
|
|
41
|
+
const cbcText = (parent: Element, tag: string): string | undefined =>
|
|
42
|
+
trimmed(parent.getElementsByTagNameNS(CBC_NS, tag)[0]?.textContent);
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* First direct-child CBC element's trimmed text, or null. Used for the
|
|
46
|
+
* top-level scalars so a nested `cbc:ID` (e.g. inside DocumentReference) cannot
|
|
47
|
+
* shadow the ApplicationResponse's own id.
|
|
48
|
+
*/
|
|
49
|
+
const cbcDirectText = (parent: Element, tag: string): string | undefined => {
|
|
50
|
+
for (let i = 0; i < parent.childNodes.length; i++) {
|
|
51
|
+
const node = parent.childNodes[i];
|
|
52
|
+
if (!node || node.nodeType !== 1) continue;
|
|
53
|
+
const el = node as Element;
|
|
54
|
+
if (el.namespaceURI === CBC_NS && el.localName === tag) {
|
|
55
|
+
return trimmed(el.textContent);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
return undefined;
|
|
59
|
+
};
|
|
60
|
+
|
|
61
|
+
/** First descendant CAC element, or null. */
|
|
62
|
+
const cacElement = (parent: Element, tag: string): Element | null =>
|
|
63
|
+
parent.getElementsByTagNameNS(CAC_NS, tag)[0] ?? null;
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* The Peppol participant identifier of a SenderParty / ReceiverParty, rendered
|
|
67
|
+
* as `schemeID:value` when the EndpointID carries a scheme and the value does
|
|
68
|
+
* not already include one, otherwise the raw value.
|
|
69
|
+
*/
|
|
70
|
+
const endpointIdentifier = (party: Element | null): string | undefined => {
|
|
71
|
+
if (!party) return undefined;
|
|
72
|
+
const endpoint = party.getElementsByTagNameNS(CBC_NS, "EndpointID")[0];
|
|
73
|
+
if (!endpoint) return undefined;
|
|
74
|
+
const id = trimmed(endpoint.textContent);
|
|
75
|
+
const scheme = endpoint.getAttribute("schemeID");
|
|
76
|
+
if (scheme && id && !id.includes(":")) return `${scheme}:${id}`;
|
|
77
|
+
return id;
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Locate the `ApplicationResponse` element, unwrapping a Standard Business
|
|
82
|
+
* Document (SBDH) envelope when present. Returns null when the XML contains no
|
|
83
|
+
* ApplicationResponse; throws {@link UblParseError} when it is malformed.
|
|
84
|
+
*/
|
|
85
|
+
const findApplicationResponse = (xml: string): Element | null => {
|
|
86
|
+
const doc = parseXmlDocument(xml);
|
|
87
|
+
const root = doc.documentElement;
|
|
88
|
+
if (!root) return null;
|
|
89
|
+
if (root.localName === "ApplicationResponse") return root;
|
|
90
|
+
const candidates = root.getElementsByTagName("*");
|
|
91
|
+
for (let i = 0; i < candidates.length; i++) {
|
|
92
|
+
const el = candidates[i];
|
|
93
|
+
if (el?.localName === "ApplicationResponse") return el;
|
|
94
|
+
}
|
|
95
|
+
return null;
|
|
96
|
+
};
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Whether an inbound document is a Peppol Message Level Response, identified by
|
|
100
|
+
* its document-type value, its process value, or by parsing the XML and finding
|
|
101
|
+
* an `ApplicationResponse` root (SBDH-wrapped or not).
|
|
102
|
+
*/
|
|
103
|
+
export const isPeppolMessageLevelResponse = (params: {
|
|
104
|
+
documentTypeValue?: string | null;
|
|
105
|
+
processValue?: string | null;
|
|
106
|
+
xml?: string | null;
|
|
107
|
+
}): boolean => {
|
|
108
|
+
if (trimmed(params.documentTypeValue) === PEPPOL_MLR_DOCUMENT_TYPE_VALUE) {
|
|
109
|
+
return true;
|
|
110
|
+
}
|
|
111
|
+
if (trimmed(params.processValue) === PEPPOL_MLR_PROCESS_VALUE) return true;
|
|
112
|
+
const xml = trimmed(params.xml);
|
|
113
|
+
if (!xml) return false;
|
|
114
|
+
try {
|
|
115
|
+
return findApplicationResponse(xml) !== null;
|
|
116
|
+
} catch (error) {
|
|
117
|
+
// A sniff answers "is this an MLR?"; malformed XML is simply "no".
|
|
118
|
+
if (error instanceof UblParseError) return false;
|
|
119
|
+
throw error;
|
|
120
|
+
}
|
|
121
|
+
};
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Parse a Peppol Message Level Response (UBL `ApplicationResponse`), unwrapping
|
|
125
|
+
* an SBDH envelope when present. Throws {@link UblParseError} when the XML is
|
|
126
|
+
* malformed or is not an ApplicationResponse.
|
|
127
|
+
*/
|
|
128
|
+
export const parsePeppolMessageLevelResponse = (
|
|
129
|
+
xml: string,
|
|
130
|
+
): PeppolMessageLevelResponse => {
|
|
131
|
+
const root = findApplicationResponse(xml);
|
|
132
|
+
if (!root) {
|
|
133
|
+
throw new UblParseError("Document is not a Peppol Message Level Response");
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
const documentResponse = cacElement(root, "DocumentResponse");
|
|
137
|
+
const response = documentResponse ? cacElement(documentResponse, "Response") : null;
|
|
138
|
+
const documentReference = documentResponse
|
|
139
|
+
? cacElement(documentResponse, "DocumentReference")
|
|
140
|
+
: null;
|
|
141
|
+
|
|
142
|
+
return {
|
|
143
|
+
customizationId: cbcDirectText(root, "CustomizationID"),
|
|
144
|
+
profileId: cbcDirectText(root, "ProfileID"),
|
|
145
|
+
responseId: cbcDirectText(root, "ID"),
|
|
146
|
+
issueDate: cbcDirectText(root, "IssueDate"),
|
|
147
|
+
issueTime: cbcDirectText(root, "IssueTime"),
|
|
148
|
+
referencedDocumentId: documentReference
|
|
149
|
+
? cbcText(documentReference, "ID")
|
|
150
|
+
: undefined,
|
|
151
|
+
responseCode: response ? cbcText(response, "ResponseCode") : undefined,
|
|
152
|
+
description: response ? cbcText(response, "Description") : undefined,
|
|
153
|
+
senderIdentifier: endpointIdentifier(cacElement(root, "SenderParty")),
|
|
154
|
+
receiverIdentifier: endpointIdentifier(cacElement(root, "ReceiverParty")),
|
|
155
|
+
};
|
|
156
|
+
};
|