uae-einvoice-mcp 0.2.0

package/README.md

@@ -0,0 +1,83 @@
+# uae-einvoice-mcp
+
+MCP server for **UAE e-invoicing / PINT AE** — TRN/TIN validation, structural compliance, the **51-field mandatory checklist**, UBL XML stub generation, and mandate timeline helpers.
+
+Built with the MCP TypeScript SDK v2 (`@modelcontextprotocol/server`) over **stdio**. Free to run locally; no API keys required for v0.2.
+
+> Informational tooling only — not legal or tax advice, and not a substitute for Accredited Service Provider (ASP) XSD/Schematron validation or live FTA register checks.
+
+## Why this exists
+
+UAE e-invoicing (Peppol + PINT AE) forces ERP and finance teams to get dozens of mandatory fields, TIN vs TRN, and Peppol endpoint IDs right before an ASP will transmit anything. This server gives AI assistants a small, installable toolkit for those checks.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `lookup_business_trn` | Validates 15-digit TRN or 10-digit TIN format, UAE `1…` prefix, Peppol AE:TIN check digit, and returns `0235:<TIN>` |
+| `check_invoice_compliance` | Structural checks (parties, totals math, tax breakdown, lines) with errors/warnings/score |
+| `check_pint_ae_fields` | Full **51-field** mandatory matrix: present / missing / invalid / N/A + gaps |
+| `generate_pint_ae_xml` | Builds a UBL 2.1 PINT AE-shaped Invoice/CreditNote XML stub (optional `strict` mode) |
+| `get_einvoicing_requirements` | Mandate phases (large / SME / government), technical baseline, and next actions |
+
+## Requirements
+
+- Node.js **20+**
+
+## Install / run
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+Dev (TypeScript directly):
+
+```bash
+npm run dev
+```
+
+Self-check (no MCP client needed):
+
+```bash
+npm run selfcheck
+```
+
+### MCP Inspector
+
+```bash
+npm run inspector
+```
+
+Paste fixtures from `examples/compliant-invoice.json` or `examples/broken-invoice.json` into the tools.
+
+### Cursor / Claude Desktop (stdio)
+
+```json
+{
+  "mcpServers": {
+    "uae-einvoice": {
+      "command": "node",
+      "args": ["/absolute/path/to/uae-einvoice-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+## Suggested test flow
+
+1. `check_pint_ae_fields` with `examples/compliant-invoice.json`
+2. `generate_pint_ae_xml` with the same payload (`strict: true` should succeed)
+3. `generate_pint_ae_xml` with `examples/broken-invoice.json` and `strict: true` (should refuse)
+
+## Roadmap
+
+- [x] 51-field checklist + PINT AE XML stub generation
+- [ ] Deeper code-list coverage (UOM, exemption reason codes)
+- [ ] Optional HTTP + API-key transport for hosted / paid tier
+- [ ] Publish to npm and MCP directories
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod";
+import { checkPintAeFields } from "./lib/checklist.js";
+import { checkInvoiceCompliance } from "./lib/compliance.js";
+import { getEinvoicingRequirements } from "./lib/requirements.js";
+import { makeSampleTin, validateTaxId } from "./lib/trn.js";
+import { generatePintAeXml } from "./lib/xml.js";
+const partySchema = z
+    .object({
+    legalName: z.string().optional(),
+    tradeName: z.string().optional(),
+    trn: z.string().optional(),
+    tin: z.string().optional(),
+    countryCode: z.string().optional(),
+    addressLine: z.string().optional(),
+    cityOrEmirate: z.string().optional(),
+    postalZone: z.string().optional(),
+    contactName: z.string().optional(),
+    email: z.string().optional(),
+    phone: z.string().optional(),
+    peppolId: z.string().optional(),
+})
+    .optional();
+const invoiceDataSchema = z.object({
+    documentType: z
+        .enum(["tax_invoice", "commercial_invoice", "credit_note"])
+        .optional()
+        .describe("Defaults to tax_invoice"),
+    invoiceNumber: z.string().optional(),
+    issueDate: z.string().optional().describe("ISO date YYYY-MM-DD"),
+    dueDate: z.string().optional(),
+    currencyCode: z.string().optional().describe("Typically AED"),
+    taxCurrencyCode: z.string().optional(),
+    customizationId: z
+        .string()
+        .optional()
+        .describe("PINT AE CustomizationID, e.g. urn:peppol:pint:billing-1@ae-1"),
+    profileId: z.string().optional(),
+    typeCode: z.string().optional().describe("380 invoice / 381 credit note"),
+    buyerReference: z.string().optional(),
+    periodStart: z.string().optional(),
+    periodEnd: z.string().optional(),
+    taxPointDate: z.string().optional(),
+    billingReference: z.string().optional().describe("Original invoice id for credit notes"),
+    seller: partySchema,
+    buyer: partySchema,
+    lineNetTotal: z.number().optional(),
+    taxExclusiveTotal: z.number().optional(),
+    taxTotal: z.number().optional(),
+    taxTotalAed: z.number().optional(),
+    taxInclusiveTotal: z.number().optional(),
+    allowanceTotal: z.number().optional(),
+    chargeTotal: z.number().optional(),
+    prepaidAmount: z.number().optional(),
+    payableAmount: z.number().optional(),
+    taxBreakdown: z
+        .array(z.object({
+        taxableAmount: z.number().optional(),
+        taxAmount: z.number().optional(),
+        taxCategoryCode: z.string().optional(),
+        taxPercent: z.number().optional(),
+        exemptionReason: z.string().optional(),
+        exemptionReasonCode: z.string().optional(),
+    }))
+        .optional(),
+    lines: z
+        .array(z.object({
+        id: z.string().optional(),
+        name: z.string().optional(),
+        quantity: z.number().optional(),
+        unitCode: z.string().optional(),
+        netAmount: z.number().optional(),
+        unitPrice: z.number().optional(),
+        taxCategoryCode: z.string().optional(),
+        taxPercent: z.number().optional(),
+    }))
+        .optional(),
+});
+function textResult(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+}
+function createServer() {
+    const server = new McpServer({
+        name: "uae-einvoice-mcp",
+        version: "0.2.0",
+    });
+    server.registerTool("lookup_business_trn", {
+        description: "Validate a UAE Tax Registration Number (15-digit TRN) or Tax Identification Number (10-digit TIN): format, UAE country prefix, Peppol AE:TIN check digit, and derived Peppol participant ID (0235:TIN). Does not call the live FTA register.",
+        inputSchema: z.object({
+            taxId: z
+                .string()
+                .describe("15-digit TRN or 10-digit TIN (spaces/dashes allowed)"),
+        }),
+    }, async ({ taxId }) => {
+        const result = validateTaxId(taxId);
+        return textResult({
+            ...result,
+            note: "Local structural validation only. Confirm active registration on EmaraTax / FTA services before production use.",
+            exampleValidTinShape: makeSampleTin(),
+        });
+    });
+    server.registerTool("check_invoice_compliance", {
+        description: "Structural PINT AE / UAE e-invoicing checks (parties, tax IDs, totals arithmetic, tax breakdown, lines). Returns errors, warnings, a score, and derived Peppol IDs. Prefer check_pint_ae_fields for the full 51-field matrix.",
+        inputSchema: z.object({
+            invoiceData: invoiceDataSchema,
+        }),
+    }, async ({ invoiceData }) => textResult(checkInvoiceCompliance(invoiceData)));
+    server.registerTool("check_pint_ae_fields", {
+        description: "Evaluate invoice JSON against the 51-field UAE e-invoice / PINT AE mandatory field matrix. Returns per-field present/missing/invalid/not_applicable status, completion %, and gaps.",
+        inputSchema: z.object({
+            invoiceData: invoiceDataSchema,
+        }),
+    }, async ({ invoiceData }) => textResult(checkPintAeFields(invoiceData)));
+    server.registerTool("generate_pint_ae_xml", {
+        description: "Generate a UBL 2.1 PINT AE-shaped Invoice/CreditNote XML stub from invoice JSON. Runs the 51-field checklist first; with strict=true refuses to emit XML when mandatory applicable fields are incomplete.",
+        inputSchema: z.object({
+            invoiceData: invoiceDataSchema,
+            strict: z
+                .boolean()
+                .optional()
+                .describe("If true, do not generate XML when checklist has gaps (default false)"),
+        }),
+    }, async ({ invoiceData, strict }) => textResult(generatePintAeXml(invoiceData, { strict: strict ?? false })));
+    server.registerTool("get_einvoicing_requirements", {
+        description: "Return the UAE e-invoicing mandate timeline, technical baseline (PINT AE / Peppol / ASP), and next actions for a business segment (large, sme, government, or all). Optional annual revenue (AED) auto-selects large vs SME.",
+        inputSchema: z.object({
+            businessType: z
+                .enum(["large", "sme", "government", "all"])
+                .optional()
+                .describe("Defaults to all"),
+            annualRevenueAed: z
+                .number()
+                .nonnegative()
+                .optional()
+                .describe("If set with businessType all/omitted, selects large (≥50M) vs sme"),
+        }),
+    }, async ({ businessType, annualRevenueAed }) => textResult(getEinvoicingRequirements(businessType ?? "all", annualRevenueAed)));
+    return server;
+}
+serveStdio(createServer);

package/dist/lib/checklist.d.ts

@@ -0,0 +1,31 @@
+import { type FieldStatus } from "./fields.js";
+import type { InvoiceDataInput } from "./invoice-types.js";
+export interface FieldCheckResult {
+    id: number;
+    key: string;
+    name: string;
+    ublPath: string;
+    category: string;
+    requirement: string;
+    conditionNote?: string;
+    status: FieldStatus;
+    value?: string | number | boolean | null;
+    note?: string;
+    countsTowardMandatory: boolean;
+}
+export interface ChecklistResult {
+    documentType: string;
+    totalFields: 51;
+    mandatoryApplicable: number;
+    present: number;
+    missing: number;
+    invalid: number;
+    notApplicable: number;
+    complete: boolean;
+    completionPercent: number;
+    summary: string;
+    fields: FieldCheckResult[];
+    gaps: FieldCheckResult[];
+    disclaimer: string;
+}
+export declare function checkPintAeFields(invoice: InvoiceDataInput): ChecklistResult;

package/dist/lib/checklist.js

@@ -0,0 +1,92 @@
+import { PINT_AE_FIELDS } from "./fields.js";
+function countsTowardMandatory(requirement, status, isTaxDoc) {
+    if (status === "not_applicable")
+        return false;
+    if (requirement === "always")
+        return true;
+    if (requirement === "tax_doc")
+        return isTaxDoc;
+    // Conditional fields that are still applicable (present/missing/invalid)
+    return true;
+}
+export function checkPintAeFields(invoice) {
+    const documentType = invoice.documentType ?? "tax_invoice";
+    const isTaxDoc = documentType === "tax_invoice" || documentType === "credit_note";
+    const fields = PINT_AE_FIELDS.map((def) => {
+        const result = def.evaluate(invoice);
+        let status = result.status;
+        // Soften conditional "missing" into not_applicable when the condition
+        // evaluator already uses missing for "not provided" — for scoring we only
+        // treat always + tax_doc (+ conditional when marked missing but needed) as gaps.
+        // Conditional fields that evaluate to "missing" without an active condition
+        // are treated as not_applicable for completion % except when evaluator
+        // returned missing because the condition IS active (tax currency, exemption, etc.).
+        if (def.requirement === "conditional" && status === "missing") {
+            // Heuristic: if evaluate returned missing with a note saying Must/Required,
+            // keep as missing; otherwise treat optional-absent as not_applicable.
+            const active = Boolean(result.note) ||
+                def.key === "taxCurrencyCode" ||
+                def.key === "taxTotalAed" ||
+                def.key === "taxBreakdown.exemptionReasonCode";
+            // For most soft conditionals (due date, trade name, contact, allowance),
+            // absence is OK unless business data implies they are needed.
+            if (!active &&
+                [
+                    "dueDate",
+                    "buyerReference",
+                    "periodStart",
+                    "periodEnd",
+                    "taxPointDate",
+                    "seller.tradeName",
+                    "seller.contact",
+                    "buyer.tradeName",
+                    "buyer.contact",
+                    "allowanceTotal",
+                    "chargeTotal",
+                ].includes(def.key)) {
+                status = "not_applicable";
+            }
+        }
+        const mandatory = countsTowardMandatory(def.requirement, status, isTaxDoc);
+        return {
+            id: def.id,
+            key: def.key,
+            name: def.name,
+            ublPath: def.ublPath,
+            category: def.category,
+            requirement: def.requirement,
+            conditionNote: def.conditionNote,
+            status,
+            value: result.value,
+            note: result.note,
+            countsTowardMandatory: mandatory,
+        };
+    });
+    const applicable = fields.filter((f) => f.countsTowardMandatory);
+    const present = applicable.filter((f) => f.status === "present").length;
+    const missing = applicable.filter((f) => f.status === "missing").length;
+    const invalid = applicable.filter((f) => f.status === "invalid").length;
+    const notApplicable = fields.filter((f) => f.status === "not_applicable").length;
+    const complete = missing === 0 && invalid === 0 && applicable.length > 0;
+    const completionPercent = applicable.length === 0
+        ? 0
+        : Math.round((present / applicable.length) * 1000) / 10;
+    const gaps = applicable.filter((f) => f.status === "missing" || f.status === "invalid");
+    return {
+        documentType,
+        totalFields: 51,
+        mandatoryApplicable: applicable.length,
+        present,
+        missing,
+        invalid,
+        notApplicable,
+        complete,
+        completionPercent,
+        summary: complete
+            ? `All ${applicable.length} applicable mandatory fields present (${completionPercent}%).`
+            : `${gaps.length} gap(s) across ${applicable.length} applicable fields (${completionPercent}% complete).`,
+        fields,
+        gaps,
+        disclaimer: "Working model of the 51-field UAE e-invoice matrix for tooling/demo use. Verify against the official MoF mandatory-fields document before production.",
+    };
+}

package/dist/lib/compliance.d.ts

@@ -0,0 +1,23 @@
+import type { InvoiceDataInput, InvoiceDocumentType } from "./invoice-types.js";
+export type { InvoiceDataInput, InvoiceDocumentType, InvoiceLineInput, PartyInput, TaxBreakdownInput, } from "./invoice-types.js";
+export type FindingSeverity = "error" | "warning" | "info";
+export interface ComplianceFinding {
+    code: string;
+    severity: FindingSeverity;
+    field: string;
+    message: string;
+}
+export interface ComplianceResult {
+    compliant: boolean;
+    score: number;
+    summary: string;
+    documentType: InvoiceDocumentType;
+    findings: ComplianceFinding[];
+    derived: {
+        sellerTin: string | null;
+        sellerPeppolId: string | null;
+        buyerTin: string | null;
+        expectedCustomizationId: string;
+    };
+}
+export declare function checkInvoiceCompliance(invoice: InvoiceDataInput): ComplianceResult;

package/dist/lib/compliance.js

@@ -0,0 +1,202 @@
+import { validateTaxId } from "./trn.js";
+const EXPECTED_CUSTOMIZATION_ID = "urn:peppol:pint:billing-1@ae-1";
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TAX_CATEGORIES = new Set(["S", "Z", "E", "O", "AE", "G"]);
+function add(findings, severity, code, field, message) {
+    findings.push({ code, severity, field, message });
+}
+function resolveTin(party) {
+    const findings = [];
+    if (!party)
+        return { tin: null, findings };
+    const raw = party.tin ?? party.trn;
+    if (!raw)
+        return { tin: null, findings };
+    const result = validateTaxId(raw);
+    if (!result.valid) {
+        for (const err of result.errors) {
+            findings.push({
+                code: "TAX_ID_INVALID",
+                severity: "error",
+                field: party.tin ? "tin" : "trn",
+                message: err,
+            });
+        }
+    }
+    return { tin: result.tin, findings };
+}
+function approxEqual(a, b, epsilon = 0.02) {
+    return Math.abs(a - b) <= epsilon;
+}
+export function checkInvoiceCompliance(invoice) {
+    const findings = [];
+    const documentType = invoice.documentType ?? "tax_invoice";
+    const isTaxDoc = documentType === "tax_invoice" || documentType === "credit_note";
+    if (!invoice.invoiceNumber?.trim()) {
+        add(findings, "error", "INV_NUMBER_MISSING", "invoiceNumber", "Invoice number (cbc:ID) is required.");
+    }
+    if (!invoice.issueDate) {
+        add(findings, "error", "ISSUE_DATE_MISSING", "issueDate", "Issue date is required (YYYY-MM-DD).");
+    }
+    else if (!ISO_DATE.test(invoice.issueDate)) {
+        add(findings, "error", "ISSUE_DATE_FORMAT", "issueDate", "Issue date must be ISO format YYYY-MM-DD.");
+    }
+    if (!invoice.currencyCode) {
+        add(findings, "error", "CURRENCY_MISSING", "currencyCode", "DocumentCurrencyCode is required.");
+    }
+    else if (invoice.currencyCode !== "AED") {
+        add(findings, "warning", "CURRENCY_NOT_AED", "currencyCode", `Currency is ${invoice.currencyCode}; domestic UAE supplies typically use AED.`);
+    }
+    if (!invoice.customizationId) {
+        add(findings, "warning", "CUSTOMIZATION_MISSING", "customizationId", `Missing CustomizationID; expected ${EXPECTED_CUSTOMIZATION_ID}.`);
+    }
+    else if (invoice.customizationId !== EXPECTED_CUSTOMIZATION_ID) {
+        add(findings, "warning", "CUSTOMIZATION_UNEXPECTED", "customizationId", `CustomizationID is "${invoice.customizationId}"; current PINT AE docs commonly use ${EXPECTED_CUSTOMIZATION_ID}.`);
+    }
+    if (documentType === "credit_note" && invoice.typeCode && invoice.typeCode !== "381") {
+        add(findings, "warning", "TYPE_CODE_CREDIT", "typeCode", "Credit notes commonly use type code 381.");
+    }
+    if (documentType === "tax_invoice" && invoice.typeCode && invoice.typeCode !== "380") {
+        add(findings, "warning", "TYPE_CODE_INVOICE", "typeCode", "Tax invoices commonly use type code 380.");
+    }
+    if (documentType === "credit_note" && !invoice.billingReference?.trim()) {
+        add(findings, "warning", "CREDIT_REF_MISSING", "billingReference", "Credit notes should reference the original invoice number.");
+    }
+    if (!invoice.seller?.legalName?.trim()) {
+        add(findings, "error", "SELLER_NAME", "seller.legalName", "Seller legal name is mandatory.");
+    }
+    const sellerId = resolveTin(invoice.seller);
+    for (const f of sellerId.findings) {
+        findings.push({ ...f, field: `seller.${f.field}` });
+    }
+    if (!invoice.seller?.trn && !invoice.seller?.tin) {
+        add(findings, "error", "SELLER_TAX_ID", "seller.trn", "Seller TRN (15) or TIN (10) is required for PINT AE party tax scheme / endpoint.");
+    }
+    if (!invoice.seller?.countryCode) {
+        add(findings, "warning", "SELLER_COUNTRY", "seller.countryCode", "Seller country code should be present (AE for UAE).");
+    }
+    else if (invoice.seller.countryCode !== "AE") {
+        add(findings, "info", "SELLER_COUNTRY_FOREIGN", "seller.countryCode", "Seller country is not AE — confirm cross-border PINT AE rules with your ASP.");
+    }
+    if (!invoice.seller?.addressLine || !invoice.seller?.cityOrEmirate) {
+        add(findings, "warning", "SELLER_ADDRESS", "seller.addressLine", "Seller registered address (line + city/emirate) is expected.");
+    }
+    if (sellerId.tin && invoice.seller?.peppolId) {
+        const expected = `0235:${sellerId.tin}`;
+        const normalized = invoice.seller.peppolId.replace(/^iso6523-actorid-upis::/i, "");
+        if (normalized !== expected && normalized !== sellerId.tin) {
+            add(findings, "error", "SELLER_PEPPOL_MISMATCH", "seller.peppolId", `Seller Peppol ID should be ${expected} (scheme 0235 + TIN).`);
+        }
+    }
+    if (!invoice.buyer?.legalName?.trim()) {
+        add(findings, "error", "BUYER_NAME", "buyer.legalName", "Buyer legal name is mandatory.");
+    }
+    const buyerId = resolveTin(invoice.buyer);
+    for (const f of buyerId.findings) {
+        findings.push({ ...f, field: `buyer.${f.field}` });
+    }
+    if (isTaxDoc && !invoice.buyer?.trn && !invoice.buyer?.tin) {
+        add(findings, "warning", "BUYER_TAX_ID", "buyer.trn", "Buyer TRN/TIN missing — mandatory for B2B UAE tax invoices; optional only for limited B2C carve-outs.");
+    }
+    const requiredTotals = [
+        "taxExclusiveTotal",
+        "taxInclusiveTotal",
+        "payableAmount",
+    ];
+    for (const key of requiredTotals) {
+        if (typeof invoice[key] !== "number") {
+            add(findings, "error", "TOTAL_MISSING", key, `${key} is required.`);
+        }
+    }
+    if (isTaxDoc && typeof invoice.taxTotal !== "number") {
+        add(findings, "error", "TAX_TOTAL_MISSING", "taxTotal", "taxTotal is required on tax invoices / credit notes.");
+    }
+    if (typeof invoice.taxExclusiveTotal === "number" &&
+        typeof invoice.taxTotal === "number" &&
+        typeof invoice.taxInclusiveTotal === "number" &&
+        !approxEqual(invoice.taxExclusiveTotal + invoice.taxTotal, invoice.taxInclusiveTotal)) {
+        add(findings, "error", "TOTAL_ARITHMETIC", "taxInclusiveTotal", "taxExclusiveTotal + taxTotal should equal taxInclusiveTotal.");
+    }
+    if (isTaxDoc) {
+        if (!invoice.taxBreakdown?.length) {
+            add(findings, "error", "TAX_BREAKDOWN_MISSING", "taxBreakdown", "At least one tax breakdown (TaxSubtotal) is required for tax invoices.");
+        }
+        else {
+            let breakdownTax = 0;
+            for (const [i, row] of invoice.taxBreakdown.entries()) {
+                if (typeof row.taxableAmount !== "number" || typeof row.taxAmount !== "number") {
+                    add(findings, "error", "TAX_BREAKDOWN_AMOUNTS", `taxBreakdown[${i}]`, "Each tax breakdown needs taxableAmount and taxAmount.");
+                }
+                else {
+                    breakdownTax += row.taxAmount;
+                }
+                if (!row.taxCategoryCode) {
+                    add(findings, "error", "TAX_CATEGORY_MISSING", `taxBreakdown[${i}].taxCategoryCode`, "Tax category code is required (e.g. S, Z, E, O).");
+                }
+                else if (!TAX_CATEGORIES.has(row.taxCategoryCode)) {
+                    add(findings, "warning", "TAX_CATEGORY_UNCOMMON", `taxBreakdown[${i}].taxCategoryCode`, `Uncommon tax category "${row.taxCategoryCode}" — verify against PINT AE code list.`);
+                }
+                if (row.taxCategoryCode === "E" && !row.exemptionReason?.trim() && !row.exemptionReasonCode?.trim()) {
+                    add(findings, "warning", "EXEMPTION_REASON", `taxBreakdown[${i}].exemptionReason`, "Exemption reason is usually required for exempt (E) supplies.");
+                }
+            }
+            if (typeof invoice.taxTotal === "number" && !approxEqual(breakdownTax, invoice.taxTotal)) {
+                add(findings, "error", "TAX_BREAKDOWN_SUM", "taxTotal", "Sum of taxBreakdown.taxAmount should equal taxTotal.");
+            }
+        }
+    }
+    if (!invoice.lines?.length) {
+        add(findings, "error", "LINES_MISSING", "lines", "At least one invoice line is required.");
+    }
+    else {
+        let lineSum = 0;
+        for (const [i, line] of invoice.lines.entries()) {
+            if (!line.id) {
+                add(findings, "warning", "LINE_ID", `lines[${i}].id`, "Line identifier is recommended.");
+            }
+            if (!line.name?.trim()) {
+                add(findings, "error", "LINE_NAME", `lines[${i}].name`, "Line item name is required.");
+            }
+            if (typeof line.quantity !== "number") {
+                add(findings, "error", "LINE_QTY", `lines[${i}].quantity`, "Line quantity is required.");
+            }
+            if (!line.unitCode) {
+                add(findings, "warning", "LINE_UOM", `lines[${i}].unitCode`, "Unit of measure should use UN/ECE Rec 20 codes (e.g. EA, HUR).");
+            }
+            if (typeof line.netAmount !== "number") {
+                add(findings, "error", "LINE_NET", `lines[${i}].netAmount`, "Line net amount is required.");
+            }
+            else {
+                lineSum += line.netAmount;
+            }
+        }
+        if (typeof invoice.lineNetTotal === "number" && !approxEqual(lineSum, invoice.lineNetTotal)) {
+            add(findings, "error", "LINE_SUM", "lineNetTotal", "Sum of line net amounts should equal lineNetTotal.");
+        }
+        else if (typeof invoice.taxExclusiveTotal === "number" &&
+            typeof invoice.lineNetTotal !== "number" &&
+            !approxEqual(lineSum, invoice.taxExclusiveTotal)) {
+            add(findings, "warning", "LINE_SUM_VS_TOTAL", "taxExclusiveTotal", "Sum of line net amounts does not match taxExclusiveTotal.");
+        }
+    }
+    const errors = findings.filter((f) => f.severity === "error");
+    const warnings = findings.filter((f) => f.severity === "warning");
+    const score = Math.max(0, 100 - errors.length * 12 - warnings.length * 4);
+    const compliant = errors.length === 0;
+    const summary = compliant
+        ? `Structurally OK for a ${documentType.replace("_", " ")} at field-presence level (${warnings.length} warning(s)). Not a substitute for ASP XSD/Schematron validation.`
+        : `Not compliant: ${errors.length} error(s), ${warnings.length} warning(s). Fix errors before ASP submission.`;
+    return {
+        compliant,
+        score,
+        summary,
+        documentType,
+        findings,
+        derived: {
+            sellerTin: sellerId.tin,
+            sellerPeppolId: sellerId.tin ? `0235:${sellerId.tin}` : null,
+            buyerTin: buyerId.tin,
+            expectedCustomizationId: EXPECTED_CUSTOMIZATION_ID,
+        },
+    };
+}

package/dist/lib/fields.d.ts

@@ -0,0 +1,41 @@
+import type { InvoiceDataInput } from "./invoice-types.js";
+export type FieldCategory = "header" | "seller" | "buyer" | "tax" | "totals" | "lines";
+export type FieldRequirement = "always" | "tax_doc" | "conditional";
+export type FieldStatus = "present" | "missing" | "invalid" | "not_applicable";
+export interface PintFieldDef {
+    id: number;
+    key: string;
+    name: string;
+    ublPath: string;
+    category: FieldCategory;
+    requirement: FieldRequirement;
+    /** Human-readable when requirement is conditional */
+    conditionNote?: string;
+    evaluate: (invoice: InvoiceDataInput) => {
+        status: FieldStatus;
+        value?: string | number | boolean | null;
+        note?: string;
+    };
+}
+declare const EXPECTED_CUSTOMIZATION = "urn:peppol:pint:billing-1@ae-1";
+declare const EXPECTED_PROFILE = "urn:peppol:bis:billing";
+declare function partyTaxId(party: InvoiceDataInput["seller"]): {
+    trn: string | null;
+    tin: string | null;
+    valid: boolean;
+};
+declare function sellerEndpoint(invoice: InvoiceDataInput): {
+    scheme: string;
+    value: string;
+} | null;
+declare function buyerEndpoint(invoice: InvoiceDataInput): {
+    scheme: string;
+    value: string;
+} | null;
+/**
+ * Working model of the UAE Electronic Invoice Mandatory Fields (51 for tax invoices).
+ * Numbering follows commonly published field lists mapped to UBL 2.1 / PINT AE paths.
+ * Confirm against the latest MoF mandatory-fields PDF before production go-live.
+ */
+export declare const PINT_AE_FIELDS: PintFieldDef[];
+export { EXPECTED_CUSTOMIZATION, EXPECTED_PROFILE, sellerEndpoint, buyerEndpoint, partyTaxId };