@ekwo-ai/vat-consignment 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ekwo AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# `@ekwo-ai/vat-consignment`
+
+The Belgian **periodic VAT return** — the XML Intervat takes for the monthly
+or quarterly declaration — in TypeScript, with no dependencies.
+
+Give it the figures a declaration was filed with and it gives you the file, a
+name for it, and the list of what could not be put in it.
+
+```ts
+import { generateVatConsignment } from '@ekwo-ai/vat-consignment';
+
+const { file, filename, violations } = generateVatConsignment(boxes, {
+  declarant: { vatNumber: '0999999999', name: 'Demo', countryCode: 'BE' },
+  period: { year: 2026, quarter: 4 },
+});
+```
+
+`boxes` is a grid, what the grid holds, and an amount:
+
+```ts
+[
+  { box: '03', kind: 'base', amount: '10000.00' },
+  { box: '54', kind: 'tax', amount: '2100.00' },
+  { box: '71', kind: 'total', amount: '2100.00' },
+]
+```
+
+which is the row shape of `tax_filing_boxes` in
+[Ekwo OS](https://github.com/Ekwo-ai/ekwo-os) — the figures **as they were
+frozen at filing**. That is the input on purpose: what is deposited has to be
+what the declaration says, and a file that recomputes from the ledger can
+diverge from the filing it is meant to carry.
+
+## What it does
+
+- Writes one `VATConsignment` holding one `VATDeclaration`
+  (`generateVatConsignment`) or as many as it is given
+  (`generateVatConsignments`), **valid against the schema the administration
+  publishes** — checked in this package's own tests, instance by instance.
+- Writes the **representative** who files for the declarants, when there is
+  one. The schema repeats `VATDeclaration` and counts them in
+  `VATDeclarationsNbr`: it was drawn so that a firm deposits the returns of all
+  its clients in one file, in its own name. The block is optional and **every
+  field inside it is required**, so a representative is named entirely or
+  refused by exception — neither completed nor dropped, because a file that
+  silently loses its representative is sent under another authority than the
+  one that was meant. The state that issued its identifier is one of `ISSUERS`,
+  the schema's own list and not ISO's: Greece is `EL` there.
+- Numbers the returns of a consignment by position unless told otherwise,
+  refuses two under one number, and says on each violation which return it is
+  in.
+- Numbers every grid with two digits: `3` and `03` are the same grid, and the
+  form writes the second.
+- Leaves out a grid at zero. An absent grid reads as a zero, and a return that
+  writes out its thirty empty boxes is one nobody can read.
+- Writes a **nil return as a return**. The schema requires `Data` and at least
+  one `Amount` in it, and does not say which; so a period where nothing happened
+  says the one thing it has to say — that nothing is owed — on grid 71, which is
+  the grid that carries what is owed. A choice of this package, forced by the
+  schema and not specified by it (`NIL_GRID`).
+- Always writes `ClientListingNihil`, because the schema requires it on every
+  return, and defaults it to `NO` — the absence of a claim, not a claim that
+  there will be a listing.
+- Names the declaration it replaces, in `ReplacedVATDeclaration`, when it is a
+  corrective: pass `replacedDeclaration` the reference Intervat gave the first
+  one.
+- Writes amounts with two decimals and a point. The French-language pages of
+  the administration show examples with a comma; the schema does not, and the
+  validator refuses one.
+- Writes nothing for a field that was not given. A telephone number invented to
+  satisfy a validator travels to an administration as a telephone number — and
+  the schema, as it turns out, does not ask for one.
+
+## What comes back as a violation
+
+The rest of the file stays valid, because a return that refuses to exist over
+one unreadable figure helps nobody. Each of these is something the schema would
+have refused — the tests put each one back in the file and watch validation
+fail — which is what makes them violations of this format and not opinions of
+this package.
+
+| code | when |
+|---|---|
+| `unknown_grid` | the box is not one of the twenty-nine grids the schema lists (`GRIDS`) |
+| `grid_twice` | the same grid was given twice, as a base and as a tax |
+| `negative_amount` | the amount is below zero: every grid is a `PositiveAmount_Type` |
+| `amount_out_of_range` | the amount is more than the schema can hold |
+| `invalid_amount` | the amount is not a number |
+| `reference_too_long` | the declarant's reference is over fourteen characters — left out |
+| `invalid_phone` | the telephone number does not fit twenty digits — left out |
+
+`grid_twice` is the one thing this format cannot hold: it gives every grid a
+single value. A form that prints a base and a tax on the same line — the French
+CA3 does, on line 08 — has no representation here, and that is a fact about
+this file and not a defect of the figures.
+
+`negative_amount` is worth a sentence too. This form never lets a grid go below
+zero: what reduces a figure has a grid of its own — 48 and 49 for credit notes
+issued, 61 and 62 for regularisations. A negative figure reaching this package
+means the books netted something the form wants shown apart.
+
+Three things are refused by exception instead, because they make the whole file
+meaningless: a period that is neither a month nor a quarter, a declarant number
+the schema cannot hold, and a corrective that names what it replaces in any
+shape but the one Intervat uses.
+
+## What it does not do
+
+- **It does not deposit anything.** Uploading the file needs a certificate, an
+  authenticated session and somebody on call; that is the operated side of this
+  project and not a library.
+- **It does not decide what to ask for.** `Restitution` and `Payment` are
+  requests made to the administration, not consequences of the figures, so both
+  default to no and the caller says otherwise.
+- **It does not claim anything about the annual customer listing.** The element
+  is required, so it is written; `NO` unless the caller says otherwise.
+- **It does not know whether the representative holds a mandate** for each
+  declarant. That is a fact of the administration's records, not of the file;
+  a consignment without one is refused there, not here.
+- **It computes nothing.** No total is derived, no grid is filled from another:
+  the figures come in frozen and go out unchanged.
+
+## Sources
+
+- [Intervat](https://finances.belgium.be/fr/E-services/intervat) — the service
+  the file is deposited on, SPF Finances, and where its technical documentation
+  and XSD schemas are published.
+- Schema `NewTVA-in_v0_9.xsd`, namespaces
+  `http://www.minfin.fgov.be/VATConsignment` and
+  `http://www.minfin.fgov.be/InputCommon`.
+- Arrêté royal n° 1 du 29 décembre 1992 relatif aux mesures tendant à assurer
+  le paiement de la taxe sur la valeur ajoutée, **art. 18** — the form and its
+  frames; **art. 18, § 1er** — filed by the twentieth day of the month that
+  follows.
+- Code de la TVA, **art. 53, § 1er, alinéa 1er, 2°** — the obligation to file.
+
+## What is verified, and what is not
+
+**Verified**: every shape of file this package writes — a full return, a minimal
+one, a nil one, a corrective, one carrying every grid at once, one under a
+representative and one holding the returns of several declarants — validates
+against `NewTVA-in_v0_9.xsd` and the four schemas it imports, in
+`test/schema.test.ts`, with no network and no system tool. The list of grids in
+the source is compared with the enumeration of the schema, number for number,
+so it cannot drift from it; so is the list of states that issue a
+representative's identifier. A representative missing any one field is shown to
+be what the schema refuses. The schemas are kept unmodified under `test/xsd/`,
+with where each came from; the package ships none of them.
+
+The first version of this brick was written from a production filing and said
+here that the schema had not been read. Reading it found four defects the same
+day: `Data` and `ClientListingNihil` are required, every amount is a positive
+one, and the grids are a closed list.
+
+**Not verified**: what Intervat checks *beyond* the schema. The portal applies
+business controls of its own — arithmetic between grids, warnings to justify
+before signing — and those are rules of the form, not of the file. A return
+that is valid here can still be questioned there. `Justification` and
+`FileAttachment`, which the schema allows for exactly that, are not written by
+this package yet.
+
+## Licence
+
+MIT. See [`LICENSE`](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The Belgian periodic VAT return, as Intervat takes it.
+ *
+ * One XML document, `VATConsignment`, described by the schema the SPF Finances
+ * publishes as `NewTVA-in_v0_9.xsd`. Give it the figures a declaration was
+ * filed with — a grid, what the grid holds, an amount — and it writes the
+ * file, a name for it, and the list of what could not be put in it.
+ *
+ * The input is deliberately the **frozen** figures and not a computation: what
+ * is deposited has to be what the declaration says, and a file that recomputes
+ * can diverge from the filing it is supposed to carry.
+ *
+ * Sources are in the README. This package depends on nothing, reads no
+ * database and knows no accounting.
+ */
+import type { ConsignedReturn, ConsignmentOptions, FiledBox, ReturnPeriod, VatConsignment, VatConsignmentOptions } from './types.js';
+export type { Ask, ConsignedReturn, ConsignmentOptions, Declarant, FiledBox, Representative, ReturnPeriod, VatConsignment, VatConsignmentOptions, Violation, } from './types.js';
+/**
+ * The grids of the form, which the schema closes: `GridNumberCode` is an
+ * enumeration, and a number that is not in it is refused by the validator
+ * however plausible it looks. Read from `NewTVA-in_v0_9.xsd`; a test compares
+ * this list with the schema file itself, so it cannot drift from it.
+ */
+export declare const GRIDS: readonly string[];
+/**
+ * The states that can have issued a representative's identifier:
+ * `MSCountryCode`, which the schema closes too. It is the schema's list and
+ * not ISO's — Greece is `EL` in it, and `XI` and `XU` are there — and a test
+ * compares it with the schema file, code for code.
+ */
+export declare const ISSUERS: readonly string[];
+/**
+ * The grid a nil return is written on. The schema requires `Data` and at least
+ * one `Amount` in it, and does not say which: so a return where nothing
+ * happened says the one thing it has to say — that nothing is owed — on the
+ * grid that carries what is owed. A choice of this package, forced by the
+ * schema and not specified by it.
+ */
+export declare const NIL_GRID = "71";
+export declare class VatConsignmentError extends Error {
+    name: string;
+}
+/**
+ * Two decimals with a point. The French-language pages of the administration
+ * write their examples with a comma; the schema does not, and a comma is
+ * refused by the validator.
+ */
+export declare function formatAmount(value: string | number): string;
+/** `3` and `03` are the same grid; the form writes the second. */
+export declare function formatGrid(box: string): string;
+/**
+ * A name for the file.
+ *
+ * The administration imposes none: Intervat takes the file that is uploaded
+ * and names the deposit itself. So this is a name of ours, stable and
+ * readable, and a caller is free to choose another.
+ */
+export declare function vatConsignmentFileName(declarantVatNumber: string, period: ReturnPeriod): string;
+/**
+ * Writes a consignment: one file, as many returns as it is given, and the
+ * representative who files them when there is one.
+ *
+ * This is the shape the schema was drawn for — `VATDeclaration` repeats and
+ * `VATDeclarationsNbr` counts them — and it is how a firm deposits the returns
+ * of all its clients at once, in its own name.
+ *
+ * Refuses, by exception, what would make the file meaningless: no return at
+ * all, a return whose period or declarant cannot be written, a representative
+ * named by halves, two returns under one sequence number — the number is the
+ * only thing that tells them apart in one file. Everything that is wrong with
+ * one figure comes back in `violations`, carrying the sequence number of the
+ * return it is in, and leaves the rest of the file valid.
+ *
+ * **Not checked**: that the representative holds a mandate for each declarant.
+ * That is a fact of the administration's records and not of this file.
+ */
+export declare function generateVatConsignments(returns: ConsignedReturn[], consignment?: ConsignmentOptions): VatConsignment;
+/**
+ * Writes one return, filed by the declarant itself: a consignment of one.
+ *
+ * Refuses, by exception, what would make the whole file meaningless: a period
+ * that is neither a month nor a quarter, or a declarant number the schema
+ * cannot hold. Everything that is wrong with one figure comes back in
+ * `violations` and leaves the rest of the file valid — a return that refuses
+ * to exist over one unreadable grid helps nobody.
+ */
+export declare function generateVatConsignment(boxes: FiledBox[], options: VatConsignmentOptions): VatConsignment;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,QAAQ,EAER,YAAY,EACZ,cAAc,EACd,qBAAqB,EAEtB,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,GAAG,EACH,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,SAAS,GACV,MAAM,YAAY,CAAC;AAQpB;;;;;GAKG;AACH,eAAO,MAAM,KAAK,EAAE,SAAS,MAAM,EAIjC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE,SAAS,MAAM,EAInC,CAAC;AAoBH;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,OAAO,CAAC;AAE7B,qBAAa,mBAAoB,SAAQ,KAAK;IACnC,IAAI,SAAyB;CACvC;AAUD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAI3D;AAOD,kEAAkE;AAClE,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAyID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,kBAAkB,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CAS/F;AAkLD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,eAAe,EAAE,EAC1B,WAAW,GAAE,kBAAuB,GACnC,cAAc,CAiEhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,QAAQ,EAAE,EACjB,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAEhB"}

package/dist/index.js

@@ -0,0 +1,446 @@
+/**
+ * The Belgian periodic VAT return, as Intervat takes it.
+ *
+ * One XML document, `VATConsignment`, described by the schema the SPF Finances
+ * publishes as `NewTVA-in_v0_9.xsd`. Give it the figures a declaration was
+ * filed with — a grid, what the grid holds, an amount — and it writes the
+ * file, a name for it, and the list of what could not be put in it.
+ *
+ * The input is deliberately the **frozen** figures and not a computation: what
+ * is deposited has to be what the declaration says, and a file that recomputes
+ * can diverge from the filing it is supposed to carry.
+ *
+ * Sources are in the README. This package depends on nothing, reads no
+ * database and knows no accounting.
+ */
+const NS_RETURN = 'http://www.minfin.fgov.be/VATConsignment';
+const NS_COMMON = 'http://www.minfin.fgov.be/InputCommon';
+/** The schema's own pattern for the declarant's enterprise number. */
+const DECLARANT_NUMBER = /^[0-1][0-9][0-9]{8}$/;
+/**
+ * The grids of the form, which the schema closes: `GridNumberCode` is an
+ * enumeration, and a number that is not in it is refused by the validator
+ * however plausible it looks. Read from `NewTVA-in_v0_9.xsd`; a test compares
+ * this list with the schema file itself, so it cannot drift from it.
+ */
+export const GRIDS = Object.freeze([
+    '00', '01', '02', '03', '44', '45', '46', '47', '48', '49',
+    '54', '55', '56', '57', '59', '61', '62', '63', '64',
+    '71', '72', '81', '82', '83', '84', '85', '86', '87', '88',
+]);
+/**
+ * The states that can have issued a representative's identifier:
+ * `MSCountryCode`, which the schema closes too. It is the schema's list and
+ * not ISO's — Greece is `EL` in it, and `XI` and `XU` are there — and a test
+ * compares it with the schema file, code for code.
+ */
+export const ISSUERS = Object.freeze([
+    'AT', 'BG', 'CY', 'CZ', 'DK', 'EE', 'FI', 'FR', 'DE', 'EL', 'HU', 'IE', 'IT', 'LV', 'LT',
+    'LU', 'MT', 'NL', 'PL', 'PT', 'RO', 'SK', 'SI', 'ES', 'SE', 'GB', 'MC', 'HR', 'XI', 'XU',
+    'BE',
+]);
+/** `RepresentativeIDType_Type`. */
+const IDENTIFICATION_TYPES = ['NVAT', 'TIN', 'other'];
+/** `EMail_Type`, as the schema writes it. */
+const EMAIL = /^[^@]+@[^.]+\..+$/;
+/** `PositiveAmount_Type`: the largest figure a grid can hold. */
+const MAX_AMOUNT = 99_999_999_999.99;
+/** `DeclarantReference_Type`: a token of at most fourteen characters. */
+const MAX_REFERENCE = 14;
+/** `IntervatDeclarationReference_Type`, for the declaration a corrective replaces. */
+const DECLARATION_REFERENCE = /^[0-9]+-[0-9]{10}-[0-9]{6}$/;
+/** `PhoneNumber_Type` allows twenty characters; digits are what is written. */
+const MAX_PHONE = 20;
+/**
+ * The grid a nil return is written on. The schema requires `Data` and at least
+ * one `Amount` in it, and does not say which: so a return where nothing
+ * happened says the one thing it has to say — that nothing is owed — on the
+ * grid that carries what is owed. A choice of this package, forced by the
+ * schema and not specified by it.
+ */
+export const NIL_GRID = '71';
+export class VatConsignmentError extends Error {
+    name = 'VatConsignmentError';
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/**
+ * Two decimals with a point. The French-language pages of the administration
+ * write their examples with a comma; the schema does not, and a comma is
+ * refused by the validator.
+ */
+export function formatAmount(value) {
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n))
+        throw new VatConsignmentError(`invalid amount: ${String(value)}`);
+    return n.toFixed(2);
+}
+/** Letters and digits, upper case: what an administration compares. */
+function normalise(value) {
+    return value.replace(/[^A-Za-z0-9]/g, '').toUpperCase();
+}
+/** `3` and `03` are the same grid; the form writes the second. */
+export function formatGrid(box) {
+    return box.trim().padStart(2, '0');
+}
+function periodElement(period) {
+    const lines = [];
+    if (period.month !== undefined) {
+        lines.push(`      <ns2:Month>${String(period.month).padStart(2, '0')}</ns2:Month>`);
+    }
+    if (period.quarter !== undefined)
+        lines.push(`      <ns2:Quarter>${period.quarter}</ns2:Quarter>`);
+    lines.push(`      <ns2:Year>${period.year}</ns2:Year>`);
+    return lines.join('\n');
+}
+/**
+ * The declarant block. Its children live in the `InputCommon` namespace and
+ * not in the return's own, because the schema that declares them is a
+ * different one — a detail the validator is strict about and no example makes
+ * obvious.
+ *
+ * Nothing is filled in for an absent field. A telephone number invented to
+ * satisfy a validator travels to an administration as a telephone number.
+ */
+function declarantElement(options, vatNumber) {
+    const d = options.declarant;
+    const optional = [
+        ['Name', d.name],
+        ['Street', d.street],
+        ['PostCode', d.postCode],
+        ['City', d.city],
+        ['CountryCode', d.countryCode],
+        ['EmailAddress', d.emailAddress],
+        ['Phone', phoneOf(d.phone)],
+    ];
+    const lines = [`      <VATNumber>${vatNumber}</VATNumber>`];
+    for (const [tag, value] of optional) {
+        if (value !== undefined && value !== '') {
+            lines.push(`      <${tag}>${escapeXml(value)}</${tag}>`);
+        }
+    }
+    return lines.join('\n');
+}
+/** Digits only, and nothing at all where they would not fit the schema. */
+function phoneOf(phone) {
+    if (phone === undefined)
+        return undefined;
+    const digits = phone.replace(/[^0-9]/g, '');
+    return digits.length === 0 || digits.length > MAX_PHONE ? undefined : digits;
+}
+/**
+ * The grids of the file, from the figures the declaration was filed with.
+ *
+ * Five things are refused here rather than written out, and each of them
+ * comes back as a violation so that the rest of the return is still a return:
+ *
+ * - a grid the schema does not list — a box of another country's form, or a
+ *   number that merely looks like one of this form's;
+ * - **the same grid twice**, which is the one thing this format cannot hold:
+ *   it gives every grid a single value, and a form that prints a base and a
+ *   tax on one line — the French CA3 does — has no representation here;
+ * - an amount that is not a number;
+ * - **a negative amount**: every grid is a `PositiveAmount_Type`, because this
+ *   form keeps what reduces a figure on a grid of its own (48, 49, 61, 62)
+ *   rather than letting any grid go below zero;
+ * - an amount beyond what the schema can hold.
+ *
+ * A grid at zero is left out. The administration reads an absent grid as a
+ * zero, and a return that writes out its thirty empty boxes is a return
+ * nobody can read.
+ */
+function gridsOf(boxes) {
+    const violations = [];
+    const seen = new Map();
+    const grids = [];
+    for (const box of boxes) {
+        const grid = formatGrid(String(box.box ?? ''));
+        if (!GRIDS.includes(grid)) {
+            violations.push({
+                code: 'unknown_grid',
+                message: `${String(box.box)} is not a grid of this form: the schema lists the ones there are, and this is not among them`,
+                box: String(box.box),
+            });
+            continue;
+        }
+        const amount = Number(box.amount);
+        if (!Number.isFinite(amount)) {
+            violations.push({
+                code: 'invalid_amount',
+                message: `grid ${grid} carries ${String(box.amount)}, which is not an amount`,
+                box: grid,
+            });
+            continue;
+        }
+        if (amount < 0) {
+            violations.push({
+                code: 'negative_amount',
+                message: `grid ${grid} carries ${formatAmount(amount)}: no grid of this form goes below zero, and what reduces a figure has a grid of its own`,
+                box: grid,
+            });
+            continue;
+        }
+        if (amount > MAX_AMOUNT) {
+            violations.push({
+                code: 'amount_out_of_range',
+                message: `grid ${grid} carries ${formatAmount(amount)}, which is more than the schema can hold`,
+                box: grid,
+            });
+            continue;
+        }
+        const kind = box.kind ?? 'tax';
+        const already = seen.get(grid);
+        if (already !== undefined) {
+            violations.push({
+                code: 'grid_twice',
+                message: `grid ${grid} was given twice, as ${already} and as ${kind}: this form holds one figure per grid`,
+                box: grid,
+            });
+            continue;
+        }
+        seen.set(grid, kind);
+        if (Math.abs(amount) < 0.005)
+            continue;
+        grids.push({ grid, amount: formatAmount(amount) });
+    }
+    grids.sort((a, b) => Number(a.grid) - Number(b.grid));
+    return { grids, violations };
+}
+/**
+ * A name for the file.
+ *
+ * The administration imposes none: Intervat takes the file that is uploaded
+ * and names the deposit itself. So this is a name of ours, stable and
+ * readable, and a caller is free to choose another.
+ */
+export function vatConsignmentFileName(declarantVatNumber, period) {
+    const number = normalise(declarantVatNumber).replace(/^BE/, '');
+    const suffix = period.month !== undefined
+        ? `M${String(period.month).padStart(2, '0')}`
+        : period.quarter !== undefined
+            ? `Q${period.quarter}`
+            : 'Y';
+    return `VATConsignment-${number}-${period.year}${suffix}.xml`;
+}
+/**
+ * The representative block: the party that files for the declarants of the
+ * consignment, in its own name.
+ *
+ * The schema makes the block optional and every field in it required. So a
+ * representative that lacks one is refused by exception, and is neither
+ * completed nor left out: a field made up travels to an administration as a
+ * fact, and a consignment that silently drops its representative is a file
+ * sent under another authority than the one that was meant.
+ */
+function representativeElement(r) {
+    const missing = ['id', 'issuedBy', 'identificationType', 'name', 'street', 'postCode', 'city', 'countryCode', 'emailAddress', 'phone'].filter((field) => typeof r[field] !== 'string' || r[field].trim() === '');
+    if (missing.length > 0) {
+        throw new VatConsignmentError(`a representative is named entirely or not at all, and this one lacks: ${missing.join(', ')}`);
+    }
+    if (!ISSUERS.includes(r.issuedBy)) {
+        throw new VatConsignmentError(`the representative's identifier is issued by a state the schema lists, and ${r.issuedBy} is not one (Greece is EL there)`);
+    }
+    if (!IDENTIFICATION_TYPES.includes(r.identificationType)) {
+        throw new VatConsignmentError(`the representative's identifier is NVAT, TIN or other: ${String(r.identificationType)}`);
+    }
+    if (!EMAIL.test(r.emailAddress.trim())) {
+        throw new VatConsignmentError(`the representative's e-mail address is not one the schema takes: ${r.emailAddress}`);
+    }
+    const phone = phoneOf(r.phone);
+    if (phone === undefined) {
+        throw new VatConsignmentError(`the representative's telephone number does not fit the ${MAX_PHONE} digits the schema allows: ${r.phone}`);
+    }
+    const qualifier = r.identificationType === 'other' && r.otherQualifier !== undefined && r.otherQualifier !== ''
+        ? ` otherQlf="${escapeXml(r.otherQualifier)}"`
+        : '';
+    return [
+        '  <ns2:Representative>',
+        `    <RepresentativeID issuedBy="${r.issuedBy}" identificationType="${r.identificationType}"${qualifier}>${escapeXml(r.id.trim())}</RepresentativeID>`,
+        `    <Name>${escapeXml(r.name)}</Name>`,
+        `    <Street>${escapeXml(r.street)}</Street>`,
+        `    <PostCode>${escapeXml(r.postCode)}</PostCode>`,
+        `    <City>${escapeXml(r.city)}</City>`,
+        `    <CountryCode>${escapeXml(r.countryCode)}</CountryCode>`,
+        `    <EmailAddress>${escapeXml(r.emailAddress.trim())}</EmailAddress>`,
+        `    <Phone>${phone}</Phone>`,
+        '  </ns2:Representative>',
+    ].join('\n');
+}
+/** What would make one return meaningless: refused by exception, and its number cleaned. */
+function declarantNumberOf(options) {
+    const { period } = options;
+    const named = [period.month !== undefined, period.quarter !== undefined].filter(Boolean).length;
+    if (named !== 1) {
+        throw new VatConsignmentError('the period of a return is one month or one quarter: name exactly one of them');
+    }
+    if (period.month !== undefined && (period.month < 1 || period.month > 12)) {
+        throw new VatConsignmentError(`month out of range: ${period.month}`);
+    }
+    if (period.quarter !== undefined && (period.quarter < 1 || period.quarter > 4)) {
+        throw new VatConsignmentError(`quarter out of range: ${period.quarter}`);
+    }
+    if (!Number.isInteger(period.year) || period.year < 2000) {
+        throw new VatConsignmentError(`year out of range: ${period.year}`);
+    }
+    const declarantNumber = normalise(options.declarant.vatNumber).replace(/^BE/, '');
+    if (!DECLARANT_NUMBER.test(declarantNumber)) {
+        throw new VatConsignmentError(`the declarant's number is ten digits without its country prefix: ${options.declarant.vatNumber}`);
+    }
+    if (options.replacedDeclaration !== undefined &&
+        !DECLARATION_REFERENCE.test(options.replacedDeclaration)) {
+        throw new VatConsignmentError(`the declaration being replaced is named by the reference Intervat gave it, digits-ten digits-six digits: ${options.replacedDeclaration}`);
+    }
+    return declarantNumber;
+}
+/** One `VATDeclaration`, and what could not be put in it. */
+function declarationElement(boxes, options, declarantNumber, sequence) {
+    const { period } = options;
+    const { grids, violations } = gridsOf(boxes);
+    const ask = options.ask ?? {};
+    let declarantReference = options.declarantReference;
+    if (declarantReference !== undefined && declarantReference.length > MAX_REFERENCE) {
+        violations.push({
+            code: 'reference_too_long',
+            message: `the declarant's reference holds ${MAX_REFERENCE} characters at most, and ${declarantReference} is ${declarantReference.length}: left out`,
+        });
+        declarantReference = undefined;
+    }
+    if (options.declarant.phone !== undefined && phoneOf(options.declarant.phone) === undefined) {
+        violations.push({
+            code: 'invalid_phone',
+            message: `the telephone number does not fit the ${MAX_PHONE} digits the schema allows: left out`,
+        });
+    }
+    const parts = [];
+    const reference = declarantReference === undefined || declarantReference === ''
+        ? ''
+        : ` DeclarantReference="${escapeXml(declarantReference)}"`;
+    parts.push(`  <ns2:VATDeclaration SequenceNumber="${sequence}"${reference}>`);
+    if (options.replacedDeclaration !== undefined) {
+        parts.push(`    <ns2:ReplacedVATDeclaration>${options.replacedDeclaration}</ns2:ReplacedVATDeclaration>`);
+    }
+    parts.push('    <ns2:Declarant>');
+    parts.push(declarantElement(options, declarantNumber));
+    parts.push('    </ns2:Declarant>');
+    parts.push('    <ns2:Period>');
+    parts.push(periodElement(period));
+    parts.push('    </ns2:Period>');
+    // `Data` is required and so is one `Amount` inside it: a nil return is still
+    // a return, and it says that nothing is owed.
+    const written = grids.length > 0 ? grids : [{ grid: NIL_GRID, amount: formatAmount(0) }];
+    parts.push('    <ns2:Data>');
+    for (const { grid, amount } of written) {
+        parts.push(`      <ns2:Amount GridNumber="${grid}">${amount}</ns2:Amount>`);
+    }
+    parts.push('    </ns2:Data>');
+    // Required on every return. `NO` is the absence of a claim.
+    parts.push(`    <ns2:ClientListingNihil>${options.clientListingNihil === true ? 'YES' : 'NO'}</ns2:ClientListingNihil>`);
+    parts.push(`    <ns2:Ask Restitution="${ask.restitution ? 'YES' : 'NO'}" Payment="${ask.payment ? 'YES' : 'NO'}"/>`);
+    if (options.comment !== undefined && options.comment !== '') {
+        parts.push(`    <ns2:Comment>${escapeXml(options.comment)}</ns2:Comment>`);
+    }
+    parts.push('  </ns2:VATDeclaration>');
+    return { lines: parts, violations };
+}
+/**
+ * A name for a consignment of several returns: whose it is, the period when
+ * every return shares one, and how many it holds.
+ */
+function consignmentFileName(owner, periods, count) {
+    const first = periods[0];
+    const shared = periods.every((p) => p.year === first.year && p.month === first.month && p.quarter === first.quarter);
+    const stem = shared
+        ? vatConsignmentFileName(owner, first).replace(/\.xml$/, '')
+        : `VATConsignment-${normalise(owner).replace(/^BE/, '')}`;
+    return `${stem}-x${count}.xml`;
+}
+/**
+ * Writes a consignment: one file, as many returns as it is given, and the
+ * representative who files them when there is one.
+ *
+ * This is the shape the schema was drawn for — `VATDeclaration` repeats and
+ * `VATDeclarationsNbr` counts them — and it is how a firm deposits the returns
+ * of all its clients at once, in its own name.
+ *
+ * Refuses, by exception, what would make the file meaningless: no return at
+ * all, a return whose period or declarant cannot be written, a representative
+ * named by halves, two returns under one sequence number — the number is the
+ * only thing that tells them apart in one file. Everything that is wrong with
+ * one figure comes back in `violations`, carrying the sequence number of the
+ * return it is in, and leaves the rest of the file valid.
+ *
+ * **Not checked**: that the representative holds a mandate for each declarant.
+ * That is a fact of the administration's records and not of this file.
+ */
+export function generateVatConsignments(returns, consignment = {}) {
+    if (returns.length === 0) {
+        throw new VatConsignmentError('a consignment holds at least one return');
+    }
+    const several = returns.length > 1;
+    const violations = [];
+    const body = [];
+    const numbers = [];
+    const sequences = new Set();
+    returns.forEach(({ boxes, options }, index) => {
+        const sequence = options.sequenceNumber ?? index + 1;
+        if (!Number.isInteger(sequence) || sequence < 1) {
+            throw new VatConsignmentError(`a sequence number is a positive integer: ${sequence}`);
+        }
+        if (sequences.has(sequence)) {
+            throw new VatConsignmentError(`two returns of one consignment carry the sequence number ${sequence}, which is the only thing that tells them apart`);
+        }
+        sequences.add(sequence);
+        const declarantNumber = declarantNumberOf(options);
+        numbers.push(declarantNumber);
+        const written = declarationElement(boxes, options, declarantNumber, sequence);
+        body.push(...written.lines);
+        for (const violation of written.violations) {
+            violations.push(several ? { ...violation, declaration: sequence } : violation);
+        }
+    });
+    let representativeReference = consignment.representativeReference;
+    if (representativeReference !== undefined && representativeReference.length > MAX_REFERENCE) {
+        violations.push({
+            code: 'reference_too_long',
+            message: `the representative's reference holds ${MAX_REFERENCE} characters at most, and ${representativeReference} is ${representativeReference.length}: left out`,
+        });
+        representativeReference = undefined;
+    }
+    const parts = [];
+    parts.push('<?xml version="1.0" encoding="UTF-8"?>');
+    parts.push(`<ns2:VATConsignment xmlns:ns2="${NS_RETURN}" xmlns="${NS_COMMON}" VATDeclarationsNbr="${returns.length}">`);
+    if (consignment.representative !== undefined) {
+        parts.push(representativeElement(consignment.representative));
+    }
+    if (representativeReference !== undefined && representativeReference !== '') {
+        parts.push(`  <ns2:RepresentativeReference>${escapeXml(representativeReference)}</ns2:RepresentativeReference>`);
+    }
+    parts.push(...body);
+    parts.push('</ns2:VATConsignment>');
+    const periods = returns.map(({ options }) => options.period);
+    return {
+        file: `${parts.join('\n')}\n`,
+        filename: several
+            ? consignmentFileName(consignment.representative?.id ?? numbers[0], periods, returns.length)
+            : vatConsignmentFileName(numbers[0], periods[0]),
+        violations,
+    };
+}
+/**
+ * Writes one return, filed by the declarant itself: a consignment of one.
+ *
+ * Refuses, by exception, what would make the whole file meaningless: a period
+ * that is neither a month nor a quarter, or a declarant number the schema
+ * cannot hold. Everything that is wrong with one figure comes back in
+ * `violations` and leaves the rest of the file valid — a return that refuses
+ * to exist over one unreadable grid helps nobody.
+ */
+export function generateVatConsignment(boxes, options) {
+    return generateVatConsignments([{ boxes, options }]);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The shapes this package reads and returns.
+ *
+ * {@link FiledBox} is the row shape of `tax_filing_boxes` in
+ * [Ekwo OS](https://github.com/Ekwo-ai/ekwo-os) — the figures of a declaration
+ * as they were frozen at filing — declared here so that nothing is imported
+ * from it. Any book-keeping system that can produce a box, what the box holds
+ * and an amount can use this package; it reads no database and knows no
+ * accounting.
+ */
+/**
+ * One figure of a periodic VAT return: the grid it goes in, what it is, and
+ * how much.
+ */
+export interface FiledBox {
+    /**
+     * The grid, as the form numbers it: `00`, `03`, `54`, `71`. Written with its
+     * leading zero here or not, it goes out with one.
+     */
+    box: string;
+    /**
+     * What the figure is: `base`, `tax`, or `total` for one the form computes.
+     * This form gives every grid one value, so two kinds on one grid is a
+     * violation rather than a choice made here.
+     */
+    kind?: string | null;
+    /** The amount. A string keeps the cents. */
+    amount: string | number;
+}
+/** The party filing. */
+export interface Declarant {
+    /**
+     * The Belgian enterprise number of the declarant, ten digits and no `BE`.
+     * Anything else is refused rather than cleaned up.
+     */
+    vatNumber: string;
+    name?: string;
+    street?: string;
+    postCode?: string;
+    city?: string;
+    /** ISO 3166-1 alpha-2 of the declarant's address. */
+    countryCode?: string;
+    emailAddress?: string;
+    /** Digits only, country code included, as an administration stores it. */
+    phone?: string;
+}
+/**
+ * The period the return covers. Exactly one of `month` or `quarter`: a return
+ * is filed on one cadence or the other, and the form has one element for each.
+ */
+export interface ReturnPeriod {
+    year: number;
+    month?: number;
+    quarter?: number;
+}
+/**
+ * What the declarant asks the administration for, which is a request and not a
+ * consequence of the figures. Both default to no, because asking is a decision
+ * and a file that asks by itself is a file nobody meant to send.
+ */
+export interface Ask {
+    /** A refund of the credit this period ends on. */
+    restitution?: boolean;
+    /** The payment forms the administration sends out. */
+    payment?: boolean;
+}
+export interface VatConsignmentOptions {
+    declarant: Declarant;
+    period: ReturnPeriod;
+    /** Sequence number of this return inside the consignment. Default 1. */
+    sequenceNumber?: number;
+    /** The declarant's own reference for this filing, at most 14 characters. */
+    declarantReference?: string;
+    /**
+     * The Intervat reference of the declaration this one replaces, as the
+     * administration gave it back — `digits-ten digits-six digits`. A corrective
+     * sent without it is an original, so a malformed one is refused outright
+     * rather than left out.
+     */
+    replacedDeclaration?: string;
+    ask?: Ask;
+    /**
+     * Whether the annual listing of customers will be nil, which the form asks on
+     * the return of the last period of the year. The schema requires the element
+     * on every return, so it is always written, and it defaults to `NO` — which
+     * is the absence of a claim, not a claim that there will be a listing.
+     */
+    clientListingNihil?: boolean;
+    /** Free text the administration displays with the filing. */
+    comment?: string;
+}
+/**
+ * The party that files for others: an accounting firm, a fiduciary, anyone
+ * holding a mandate. The schema makes the whole block optional and **every
+ * field of it required** once it is there, so every field is required here:
+ * a representative is named entirely or not at all.
+ */
+export interface Representative {
+    /** The identifier, as the authority that issued it writes it. */
+    id: string;
+    /** The member state that issued the identifier: one of {@link ISSUERS}. */
+    issuedBy: string;
+    /** What the identifier is: a VAT number, a tax identification number, or something else. */
+    identificationType: 'NVAT' | 'TIN' | 'other';
+    /** What `other` is. Written only with that type. */
+    otherQualifier?: string;
+    name: string;
+    street: string;
+    postCode: string;
+    city: string;
+    /** ISO 3166-1 alpha-2 of the representative's address. */
+    countryCode: string;
+    emailAddress: string;
+    /** Digits are what is written; twenty at most. */
+    phone: string;
+}
+/** One return of a consignment that holds several. */
+export interface ConsignedReturn {
+    boxes: FiledBox[];
+    /**
+     * What {@link VatConsignmentOptions} says, for this return. A sequence
+     * number left out is the position of the return in the file, from 1.
+     */
+    options: VatConsignmentOptions;
+}
+/** What belongs to the consignment and not to any one return in it. */
+export interface ConsignmentOptions {
+    representative?: Representative;
+    /** The representative's own reference for this consignment, at most 14 characters. */
+    representativeReference?: string;
+}
+/** Something that does not add up, said in the terms of this format. */
+export interface Violation {
+    /** A stable token, for a caller that branches on it. */
+    code: string;
+    /** What is wrong, in a sentence. */
+    message: string;
+    /** The grid the trouble is on, where there is one. */
+    box?: string;
+    /**
+     * The sequence number of the return the trouble is in, when the consignment
+     * holds several. Absent on a consignment of one, where it would say nothing.
+     */
+    declaration?: number;
+}
+export interface VatConsignment {
+    /** The XML, as text. */
+    file: string;
+    /** A name for it. See the README: the administration imposes none. */
+    filename: string;
+    /** Everything that could not be put in the file, and why. */
+    violations: Violation[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * The shapes this package reads and returns.
+ *
+ * {@link FiledBox} is the row shape of `tax_filing_boxes` in
+ * [Ekwo OS](https://github.com/Ekwo-ai/ekwo-os) — the figures of a declaration
+ * as they were frozen at filing — declared here so that nothing is imported
+ * from it. Any book-keeping system that can produce a box, what the box holds
+ * and an amount can use this package; it reads no database and knows no
+ * accounting.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ekwo-ai/vat-consignment",
+  "version": "0.4.0",
+  "description": "The Belgian periodic VAT return for Intervat (VATConsignment XML, schema NewTVA-in v0.9) in TypeScript, from the figures a declaration was filed with. Zero dependencies.",
+  "keywords": [
+    "intervat",
+    "vatconsignment",
+    "vat-return",
+    "declaration-tva",
+    "tva",
+    "vat",
+    "belgium",
+    "spf-finances",
+    "xml"
+  ],
+  "license": "MIT",
+  "author": "Ekwo AI",
+  "homepage": "https://github.com/Ekwo-ai/ekwo-os/tree/main/packages/formats/vat-consignment#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ekwo-ai/ekwo-os.git",
+    "directory": "packages/formats/vat-consignment"
+  },
+  "bugs": {
+    "url": "https://github.com/Ekwo-ai/ekwo-os/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0",
+    "xmllint-wasm": "^5.3.0"
+  }
+}