@perrylink/dsh-einvoice 0.0.0-stage → 0.1.0-alpha.1

package/lib/adapters/ofd-zip-xml.js

@@ -0,0 +1,421 @@
+/** OFD (ZIP + XML) and standalone XML reader for SKU-04 S1. */
+import { unzipSync } from 'fflate';
+import { XMLParser } from 'fast-xml-parser';
+import { InvoiceError, amountToCents, normalizeDate, normalizeTaxId, } from '../core/invoice.js';
+export const PARSER_ID = 'ofd-zip-xml';
+export const PARSER_VERSION = 'ofd-zip-xml@1';
+const xmlParser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    removeNSPrefix: true,
+    parseTagValue: false,
+    trimValues: true,
+    processEntities: false,
+    allowBooleanAttributes: false,
+});
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asArray(value) {
+    if (value === undefined || value === null)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function asObject(value) {
+    if (Array.isArray(value))
+        return asObject(value[0]);
+    return isObject(value) ? value : undefined;
+}
+function scalar(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'string')
+        return value.trim();
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return value.map(scalar).join('');
+    if (isObject(value)) {
+        const text = value['#text'];
+        if (text !== undefined)
+            return scalar(text);
+    }
+    return '';
+}
+function child(node, key) {
+    return node ? asObject(node[key]) : undefined;
+}
+function textAt(node, ...path) {
+    let current = node;
+    for (const key of path) {
+        const currentObject = asObject(current);
+        if (!currentObject)
+            return '';
+        current = currentObject[key];
+    }
+    return scalar(current);
+}
+function unknownTopLevel(root, known) {
+    const knownSet = new Set(known);
+    const unknown = {};
+    for (const [key, value] of Object.entries(root)) {
+        if (!knownSet.has(key))
+            unknown[key] = value;
+    }
+    return unknown;
+}
+function parseXml(text) {
+    const parsed = xmlParser.parse(text);
+    if (!isObject(parsed))
+        throw new InvoiceError('E_INV_XML_SCHEMA_DRIFT', 'XML root is not an object', { needs_review: true });
+    return parsed;
+}
+const OLD_KNOWN = [
+    'DocID', 'InvoiceCode', 'InvoiceNo', 'TypeCode', 'IssueDate', 'InvoiceCheckCode',
+    'MachineNo', 'TaxControlCode', 'Buyer', 'Tpvn', 'Seller', 'TaxInclusiveTotalAmount',
+    'Note', 'InvoiceClerk', 'Payee', 'Checker', 'TaxTotalAmount', 'TaxExclusiveTotalAmount',
+    'GraphCode', 'InvoiceSIA1', 'InvoiceSIA2', 'Signature', 'GoodsInfos', '@_Version',
+];
+function parseOldInvoice(root) {
+    const buyer = child(root, 'Buyer');
+    const seller = child(root, 'Seller');
+    const buyerName = textAt(buyer, 'BuyerName');
+    const sellerName = textAt(seller, 'SellerName');
+    const buyerTaxId = normalizeTaxId(textAt(buyer, 'BuyerTaxID'));
+    const sellerTaxId = normalizeTaxId(textAt(seller, 'SellerTaxID'));
+    const issueDate = normalizeDate(textAt(root, 'IssueDate'));
+    const amountCents = amountToCents(textAt(root, 'TaxExclusiveTotalAmount'));
+    const taxCents = amountToCents(textAt(root, 'TaxTotalAmount'));
+    const totalCents = amountToCents(textAt(root, 'TaxInclusiveTotalAmount'));
+    const goodsInfo = asArray(child(root, 'GoodsInfos')?.GoodsInfo);
+    const lines = goodsInfo.map((raw, index) => {
+        const line = asObject(raw) ?? {};
+        const amount = textAt(line, 'Amount');
+        const tax = textAt(line, 'TaxAmount');
+        return {
+            line_no: index + 1,
+            description: textAt(line, 'Item'),
+            quantity: textAt(line, 'Quantity') || undefined,
+            unit_price_cents: textAt(line, 'Price') ? amountToCents(textAt(line, 'Price')) : undefined,
+            amount_cents: amount ? amountToCents(amount) : 0,
+            tax_rate: textAt(line, 'TaxScheme') || undefined,
+            tax_cents: tax ? amountToCents(tax) : undefined,
+        };
+    });
+    const unknown = unknownTopLevel(root, OLD_KNOWN);
+    for (const [key, value] of Object.entries(buyer ?? {})) {
+        if (!['BuyerName', 'BuyerTaxID'].includes(key))
+            unknown[`Buyer.${key}`] = value;
+    }
+    for (const [key, value] of Object.entries(seller ?? {})) {
+        if (!['SellerName', 'SellerTaxID'].includes(key))
+            unknown[`Seller.${key}`] = value;
+    }
+    return {
+        document_kind: 'ofd-old',
+        invoice_no: textAt(root, 'InvoiceNo'),
+        invoice_code: textAt(root, 'InvoiceCode') || undefined,
+        issue_date: issueDate,
+        buyer: { name: buyerName, tax_id: buyerTaxId },
+        seller: { name: sellerName, tax_id: sellerTaxId },
+        amount_cents: amountCents,
+        tax_cents: taxCents,
+        total_cents: totalCents,
+        currency: 'CNY',
+        lines,
+        confidence: 1,
+        field_evidence: {
+            invoice_no: 'Attachs/original_invoice.xml:InvoiceNo',
+            issue_date: 'Attachs/original_invoice.xml:IssueDate',
+            buyer_name: 'Attachs/original_invoice.xml:Buyer/BuyerName',
+            buyer_tax_id: 'Attachs/original_invoice.xml:Buyer/BuyerTaxID',
+            seller_name: 'Attachs/original_invoice.xml:Seller/SellerName',
+            seller_tax_id: 'Attachs/original_invoice.xml:Seller/SellerTaxID',
+            amount_cents: 'Attachs/original_invoice.xml:TaxExclusiveTotalAmount',
+            tax_cents: 'Attachs/original_invoice.xml:TaxTotalAmount',
+            total_cents: 'Attachs/original_invoice.xml:TaxInclusiveTotalAmount',
+        },
+        unknown_fields: unknown,
+        parser_version: PARSER_VERSION,
+        warnings: [],
+    };
+}
+function collectRefs(value, out = []) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectRefs(item, out);
+        return out;
+    }
+    if (!isObject(value))
+        return out;
+    for (const [key, childValue] of Object.entries(value)) {
+        if (key === 'ObjectRef') {
+            for (const item of asArray(childValue)) {
+                const text = scalar(item);
+                if (text)
+                    out.push(text);
+            }
+            continue;
+        }
+        collectRefs(childValue, out);
+    }
+    return out;
+}
+function collectTextCodes(value) {
+    if (Array.isArray(value))
+        return value.map(collectTextCodes).join('');
+    if (isObject(value)) {
+        if (value.TextCode !== undefined)
+            return collectTextCodes(value.TextCode);
+        if (value['#text'] !== undefined)
+            return scalar(value['#text']);
+    }
+    return scalar(value);
+}
+function collectTextObjects(value, out) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectTextObjects(item, out);
+        return;
+    }
+    if (!isObject(value))
+        return;
+    if (value.TextObject !== undefined) {
+        for (const raw of asArray(value.TextObject)) {
+            const object = asObject(raw);
+            if (!object)
+                continue;
+            const id = scalar(object['@_ID']);
+            if (!id)
+                continue;
+            out.set(id, collectTextCodes(object.TextCode));
+        }
+    }
+    for (const childValue of Object.values(value))
+        collectTextObjects(childValue, out);
+}
+const DIGITAL_KNOWN = [
+    'InvoiceNo', 'IssueDate', 'Buyer', 'Seller', 'TaxExclusiveTotalAmount', 'TaxTotalAmount',
+    'TaxInclusiveTotalAmount', 'InvoiceClerk', 'Item', 'TaxScheme', 'Amount', 'TaxAmount',
+    'Price', 'Quantity', 'Note', '@_version',
+];
+function digitalField(root, key, textMap) {
+    const raw = root[key];
+    if (raw === undefined || raw === null)
+        throw new InvoiceError('E_INV_FIELD_MISSING', `CustomTag field missing: ${key}`, { needs_review: true });
+    const refs = collectRefs(raw);
+    if (refs.length > 0) {
+        const resolved = refs.map((id) => textMap.get(id) ?? '').join('');
+        if (resolved)
+            return { value: resolved, evidence: `Tags/CustomTag.xml:${key} -> ${refs.map((id) => `#${id}`).join(',')}` };
+    }
+    const direct = scalar(raw);
+    if (direct)
+        return { value: direct, evidence: `Tags/CustomTag.xml:${key}` };
+    throw new InvoiceError('E_INV_FIELD_MISSING', `CustomTag field has no text: ${key}`, { needs_review: true });
+}
+function parseDigitalInvoice(root, textMap) {
+    const buyer = child(root, 'Buyer');
+    const seller = child(root, 'Seller');
+    const invoiceNo = digitalField(root, 'InvoiceNo', textMap);
+    const issueDate = digitalField(root, 'IssueDate', textMap);
+    const buyerName = buyer ? digitalField(buyer, 'BuyerName', textMap) : undefined;
+    const buyerTaxId = buyer ? digitalField(buyer, 'BuyerTaxID', textMap) : undefined;
+    const sellerName = seller ? digitalField(seller, 'SellerName', textMap) : undefined;
+    const sellerTaxId = seller ? digitalField(seller, 'SellerTaxID', textMap) : undefined;
+    const amount = digitalField(root, 'TaxExclusiveTotalAmount', textMap);
+    const tax = digitalField(root, 'TaxTotalAmount', textMap);
+    const total = digitalField(root, 'TaxInclusiveTotalAmount', textMap);
+    const itemRefs = collectRefs(root.Item);
+    const taxSchemeRefs = collectRefs(root.TaxScheme);
+    const amountRefs = collectRefs(root.Amount);
+    const taxAmountRefs = collectRefs(root.TaxAmount);
+    const priceRefs = collectRefs(root.Price);
+    const quantityRefs = collectRefs(root.Quantity);
+    const lines = itemRefs.map((id, index) => {
+        const description = textMap.get(id) ?? '';
+        const amountText = textMap.get(amountRefs[index] ?? '') ?? '';
+        const taxText = textMap.get(taxAmountRefs[index] ?? '') ?? '';
+        return {
+            line_no: index + 1,
+            description,
+            quantity: textMap.get(quantityRefs[index] ?? '') || undefined,
+            unit_price_cents: textMap.get(priceRefs[index] ?? '') ? amountToCents(textMap.get(priceRefs[index] ?? '') ?? '') : undefined,
+            amount_cents: amountText ? amountToCents(amountText) : 0,
+            tax_rate: textMap.get(taxSchemeRefs[index] ?? '') || undefined,
+            tax_cents: taxText ? amountToCents(taxText) : undefined,
+        };
+    });
+    return {
+        document_kind: 'ofd-digital',
+        invoice_no: invoiceNo.value,
+        issue_date: normalizeDate(issueDate.value),
+        buyer: {
+            name: buyerName?.value ?? '',
+            tax_id: normalizeTaxId(buyerTaxId?.value ?? ''),
+        },
+        seller: {
+            name: sellerName?.value ?? '',
+            tax_id: normalizeTaxId(sellerTaxId?.value ?? ''),
+        },
+        amount_cents: amountToCents(amount.value),
+        tax_cents: amountToCents(tax.value),
+        total_cents: amountToCents(total.value),
+        currency: 'CNY',
+        lines,
+        confidence: 1,
+        field_evidence: {
+            invoice_no: invoiceNo.evidence,
+            issue_date: issueDate.evidence,
+            buyer_name: buyerName?.evidence ?? '',
+            buyer_tax_id: buyerTaxId?.evidence ?? '',
+            seller_name: sellerName?.evidence ?? '',
+            seller_tax_id: sellerTaxId?.evidence ?? '',
+            amount_cents: amount.evidence,
+            tax_cents: tax.evidence,
+            total_cents: total.evidence,
+        },
+        unknown_fields: unknownTopLevel(root, DIGITAL_KNOWN),
+        parser_version: PARSER_VERSION,
+        warnings: [],
+    };
+}
+const GENERIC_KNOWN = [
+    'InvoiceNo', 'InvoiceIssueDate', 'IssueDate', 'InvoiceTypeName', 'Seller', 'Buyer',
+    'Items', 'Amount', 'TaxAmount', 'TotalAmount', 'InvoiceCode',
+];
+function parseGenericInvoice(root) {
+    const buyer = child(root, 'Buyer');
+    const seller = child(root, 'Seller');
+    const buyerName = textAt(buyer, 'Name') || textAt(buyer, 'BuyerName');
+    const sellerName = textAt(seller, 'Name') || textAt(seller, 'SellerName');
+    const buyerTaxId = textAt(buyer, 'TaxID') || textAt(buyer, 'BuyerTaxID');
+    const sellerTaxId = textAt(seller, 'TaxID') || textAt(seller, 'SellerTaxID');
+    const issueDate = textAt(root, 'InvoiceIssueDate') || textAt(root, 'IssueDate');
+    const items = asArray(child(root, 'Items')?.Item);
+    const lines = items.map((raw, index) => {
+        const line = asObject(raw) ?? {};
+        return {
+            line_no: index + 1,
+            description: textAt(line, 'Description') || textAt(line, 'Item'),
+            quantity: textAt(line, 'Quantity') || undefined,
+            unit_price_cents: textAt(line, 'UnitPrice') ? amountToCents(textAt(line, 'UnitPrice')) : undefined,
+            amount_cents: textAt(line, 'Amount') ? amountToCents(textAt(line, 'Amount')) : 0,
+            tax_rate: textAt(line, 'TaxRate') || undefined,
+            tax_cents: textAt(line, 'TaxAmount') ? amountToCents(textAt(line, 'TaxAmount')) : undefined,
+        };
+    });
+    return {
+        document_kind: 'xml',
+        invoice_no: textAt(root, 'InvoiceNo'),
+        invoice_code: textAt(root, 'InvoiceCode') || undefined,
+        issue_date: normalizeDate(issueDate),
+        buyer: { name: buyerName, tax_id: normalizeTaxId(buyerTaxId) },
+        seller: { name: sellerName, tax_id: normalizeTaxId(sellerTaxId) },
+        amount_cents: amountToCents(textAt(root, 'Amount')),
+        tax_cents: amountToCents(textAt(root, 'TaxAmount')),
+        total_cents: amountToCents(textAt(root, 'TotalAmount')),
+        currency: 'CNY',
+        lines,
+        confidence: 1,
+        field_evidence: {
+            invoice_no: 'XML:InvoiceNo',
+            issue_date: 'XML:InvoiceIssueDate',
+            buyer_name: 'XML:Buyer/Name',
+            buyer_tax_id: 'XML:Buyer/TaxID',
+            seller_name: 'XML:Seller/Name',
+            seller_tax_id: 'XML:Seller/TaxID',
+            amount_cents: 'XML:Amount',
+            tax_cents: 'XML:TaxAmount',
+            total_cents: 'XML:TotalAmount',
+        },
+        unknown_fields: unknownTopLevel(root, GENERIC_KNOWN),
+        parser_version: PARSER_VERSION,
+        warnings: [],
+    };
+}
+function decodeEntry(entries, name) {
+    const entry = entries[name];
+    if (!entry)
+        throw new InvoiceError('E_INV_OFD_UNSUPPORTED', `missing OFD part: ${name}`);
+    return new TextDecoder('utf-8', { fatal: false }).decode(entry);
+}
+function findEntry(entries, suffix) {
+    return Object.keys(entries).find((name) => name.endsWith(suffix));
+}
+function parseOfd(input) {
+    let count = 0;
+    let total = 0;
+    const entries = unzipSync(new Uint8Array(input.buffer), {
+        filter(file) {
+            count += 1;
+            total += Number(file.originalSize ?? file.size ?? 0);
+            if (count > 1000 || total > 100 * 1024 * 1024) {
+                throw new InvoiceError('E_INV_FILE_UNREADABLE', 'OFD archive exceeds safe entry/size limits');
+            }
+            return true;
+        },
+    });
+    if (!entries['OFD.xml'])
+        throw new InvoiceError('E_INV_OFD_UNSUPPORTED', 'missing OFD.xml');
+    const oldXmlName = findEntry(entries, 'Attachs/original_invoice.xml');
+    if (oldXmlName) {
+        const root = parseXml(decodeEntry(entries, oldXmlName));
+        const invoiceRoot = asObject(root.eInvoice) ?? asObject(root.Invoice) ?? root;
+        return parseOldInvoice(invoiceRoot);
+    }
+    const customTagName = findEntry(entries, 'Tags/CustomTag.xml');
+    if (customTagName) {
+        const textMap = new Map();
+        for (const name of Object.keys(entries)) {
+            if (/\/Pages\/.*\/Content\.xml$/i.test(name)) {
+                collectTextObjects(parseXml(decodeEntry(entries, name)), textMap);
+            }
+        }
+        const root = parseXml(decodeEntry(entries, customTagName));
+        const tagRoot = asObject(root.root) ?? root;
+        return parseDigitalInvoice(tagRoot, textMap);
+    }
+    for (const name of Object.keys(entries)) {
+        if (!name.endsWith('.xml'))
+            continue;
+        const text = decodeEntry(entries, name);
+        if (text.includes('<eInvoice') || text.includes('<Invoice')) {
+            const root = parseXml(text);
+            return parseGenericInvoice(asObject(root.eInvoice) ?? asObject(root.Invoice) ?? root);
+        }
+    }
+    throw new InvoiceError('E_INV_OFD_UNSUPPORTED', 'no recognized invoice XML in OFD');
+}
+function parseStandaloneXml(input) {
+    const text = input.buffer.toString('utf8');
+    if (text.length > 50 * 1024 * 1024)
+        throw new InvoiceError('E_INV_FILE_UNREADABLE', 'XML exceeds 50MB');
+    const root = parseXml(text);
+    const invoiceRoot = asObject(root.eInvoice) ?? asObject(root.Invoice) ?? root;
+    if (invoiceRoot.Buyer && invoiceRoot.InvoiceNo)
+        return parseGenericInvoice(invoiceRoot);
+    if (invoiceRoot.Buyer && invoiceRoot.IssueDate && !invoiceRoot.InvoiceIssueDate)
+        return parseOldInvoice(invoiceRoot);
+    return parseGenericInvoice(invoiceRoot);
+}
+export const ofdZipXmlParser = {
+    id: PARSER_ID,
+    version: PARSER_VERSION,
+    supports(input) {
+        if (input.buffer.length === 0)
+            return false;
+        const first = input.buffer.subarray(0, 2).toString('latin1');
+        if (first === 'PK')
+            return true;
+        const text = input.buffer.subarray(0, 64).toString('utf8').trimStart();
+        return text.startsWith('<');
+    },
+    parse(input) {
+        if (input.buffer.length === 0)
+            throw new InvoiceError('E_INV_FILE_UNREADABLE', 'empty file');
+        if (input.buffer.subarray(0, 2).toString('latin1') === 'PK')
+            return parseOfd(input);
+        return parseStandaloneXml(input);
+    },
+};

package/lib/core/invoice.d.ts

@@ -0,0 +1,57 @@
+/** Pure invoice domain helpers. No DSH/Cordis imports are allowed here. */
+export type InvoiceDocumentKind = 'ofd-old' | 'ofd-digital' | 'xml';
+export interface InvoiceParty {
+    name: string;
+    tax_id: string;
+}
+export interface InvoiceLine {
+    line_no: number;
+    description: string;
+    quantity?: string;
+    unit_price_cents?: number;
+    amount_cents: number;
+    tax_rate?: string;
+    tax_cents?: number;
+}
+export interface ParsedInvoice {
+    document_kind: InvoiceDocumentKind;
+    invoice_no: string;
+    invoice_code?: string;
+    issue_date: string;
+    buyer: InvoiceParty;
+    seller: InvoiceParty;
+    amount_cents: number;
+    tax_cents: number;
+    total_cents: number;
+    currency: 'CNY';
+    lines: InvoiceLine[];
+    confidence: number;
+    field_evidence: Record<string, string>;
+    unknown_fields: Record<string, unknown>;
+    parser_version: string;
+    warnings: string[];
+}
+export type InvoiceLifecycle = 'received' | 'parsed' | 'verified' | 'archived' | 'quarantined';
+export interface InvoiceErrorOptions {
+    retryable?: boolean;
+    needs_review?: boolean;
+    details?: Record<string, unknown>;
+}
+/** Project-convention error; DSH renders a thrown tool error as isError. */
+export declare class InvoiceError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly needs_review: boolean;
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, options?: InvoiceErrorOptions);
+}
+/** Parse a decimal amount (yuan) into integer cents without floating point. */
+export declare function amountToCents(raw: unknown): number;
+/** Normalize the common Chinese date spellings to YYYY-MM-DD. */
+export declare function normalizeDate(raw: unknown): string;
+/** Validate the shape of a PRC taxpayer id without claiming checksum validity. */
+export declare function normalizeTaxId(raw: unknown): string;
+export declare function invoicePeriod(issueDate: string): string;
+/** Ensure the eight published fields exist and are internally consistent. */
+export declare function assertEightFields(invoice: ParsedInvoice): void;
+export declare function canonicalJson(value: unknown): string;

package/lib/core/invoice.js

@@ -0,0 +1,118 @@
+/** Pure invoice domain helpers. No DSH/Cordis imports are allowed here. */
+/** Project-convention error; DSH renders a thrown tool error as isError. */
+export class InvoiceError extends Error {
+    code;
+    retryable;
+    needs_review;
+    details;
+    constructor(code, message, options = {}) {
+        super(`${code}: ${message}`);
+        this.name = 'InvoiceError';
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+        this.needs_review = options.needs_review ?? false;
+        this.details = options.details;
+    }
+}
+/** Parse a decimal amount (yuan) into integer cents without floating point. */
+export function amountToCents(raw) {
+    if (typeof raw === 'number') {
+        if (!Number.isFinite(raw))
+            throw new InvoiceError('E_INV_FIELD_MISSING', 'amount is not finite');
+        return Math.round(raw * 100);
+    }
+    if (typeof raw !== 'string')
+        throw new InvoiceError('E_INV_FIELD_MISSING', 'amount is not a string or number');
+    const cleaned = raw.replace(/[¥￥,\s，]/g, '').trim();
+    const match = /^(-?)(\d+)(?:\.(\d{1,2}))?$/.exec(cleaned);
+    if (!match)
+        throw new InvoiceError('E_INV_FIELD_MISSING', `amount is not a decimal: ${raw}`);
+    const sign = match[1] === '-' ? -1n : 1n;
+    const whole = BigInt(match[2] ?? '0');
+    const fraction = BigInt((match[3] ?? '').padEnd(2, '0'));
+    const cents = sign * (whole * 100n + fraction);
+    if (cents > BigInt(Number.MAX_SAFE_INTEGER) || cents < BigInt(Number.MIN_SAFE_INTEGER)) {
+        throw new InvoiceError('E_INV_FIELD_MISSING', 'amount exceeds safe integer cents');
+    }
+    return Number(cents);
+}
+/** Normalize the common Chinese date spellings to YYYY-MM-DD. */
+export function normalizeDate(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        throw new InvoiceError('E_INV_FIELD_MISSING', 'issue date is empty');
+    }
+    const value = raw.trim();
+    const compact = /^(\d{4})(\d{2})(\d{2})$/.exec(value);
+    const chinese = /^(\d{4})年(\d{1,2})月(\d{1,2})日$/.exec(value);
+    const dashed = /^(\d{4})[-/](\d{1,2})[-/](\d{1,2})$/.exec(value);
+    const match = dashed ?? chinese ?? compact;
+    if (!match)
+        throw new InvoiceError('E_INV_FIELD_MISSING', `unrecognized issue date: ${value}`);
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+        throw new InvoiceError('E_INV_FIELD_MISSING', `invalid issue date: ${value}`);
+    }
+    return `${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+/** Validate the shape of a PRC taxpayer id without claiming checksum validity. */
+export function normalizeTaxId(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '') {
+        throw new InvoiceError('E_INV_FIELD_MISSING', 'tax id is empty');
+    }
+    const value = raw.replace(/\s/g, '').toUpperCase();
+    if (!/^[0-9A-Z]{15,20}$/.test(value)) {
+        throw new InvoiceError('E_INV_FIELD_MISSING', `tax id has an unexpected shape: ${value.slice(0, 4)}…`);
+    }
+    return value;
+}
+export function invoicePeriod(issueDate) {
+    return issueDate.slice(0, 7);
+}
+/** Ensure the eight published fields exist and are internally consistent. */
+export function assertEightFields(invoice) {
+    const missing = [];
+    if (!invoice.invoice_no)
+        missing.push('invoice_no');
+    if (!invoice.issue_date)
+        missing.push('issue_date');
+    if (!invoice.buyer.name)
+        missing.push('buyer.name');
+    if (!invoice.buyer.tax_id)
+        missing.push('buyer.tax_id');
+    if (!invoice.seller.name)
+        missing.push('seller.name');
+    if (!invoice.seller.tax_id)
+        missing.push('seller.tax_id');
+    if (!Number.isInteger(invoice.amount_cents))
+        missing.push('amount_cents');
+    if (!Number.isInteger(invoice.tax_cents))
+        missing.push('tax_cents');
+    if (!Number.isInteger(invoice.total_cents))
+        missing.push('total_cents');
+    if (missing.length > 0) {
+        throw new InvoiceError('E_INV_FIELD_MISSING', `missing fields: ${missing.join(',')}`, { needs_review: true });
+    }
+    if (invoice.total_cents !== invoice.amount_cents + invoice.tax_cents) {
+        throw new InvoiceError('E_INV_XML_SCHEMA_DRIFT', 'total != amount + tax', {
+            needs_review: true,
+            details: {
+                amount_cents: invoice.amount_cents,
+                tax_cents: invoice.tax_cents,
+                total_cents: invoice.total_cents,
+            },
+        });
+    }
+}
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(',')}}`;
+}

package/lib/plugin/index.d.ts

@@ -0,0 +1,5 @@
+/** DSH Host entry for SKU-04 S1. */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "dsh-einvoice";
+export declare const inject: string[];
+export declare function apply(ctx: Context): Promise<void>;

package/lib/plugin/index.js

@@ -0,0 +1,18 @@
+/** DSH Host entry for SKU-04 S1. */
+import path from 'node:path';
+import { createTools } from './tools.js';
+import { openInvoiceTable } from './storage.js';
+export const name = 'dsh-einvoice';
+export const inject = ['tools', 'storageDomain'];
+export async function apply(ctx) {
+    const baseDir = process.env.DSH_EINVOICE_HOME ??
+        path.join(process.env.DSH_HOME ?? process.cwd(), 'storages', 'dsh-einvoice');
+    const roots = (process.env.DSH_EINVOICE_INPUT_ROOTS ?? process.cwd())
+        .split(path.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    const table = await openInvoiceTable(ctx);
+    for (const tool of createTools({ table, baseDir, inputRoots: roots })) {
+        ctx.tools.register(tool);
+    }
+}