@invompt/invoml 1.0.0-alpha.4

package/dist/src/serializer.js

@@ -0,0 +1,181 @@
+// src/serializer.ts
+import { resolveOrder } from './style.js';
+import { getCurrencyDecimals } from './rounding.js';
+import { fmtNum } from './format.js';
+/** Serialize an InvoML document to a JSON string. Defaults to pretty-printed; pass `{ compact: true }` for minified output. */
+export function toJSON(doc, options = {}) {
+    return JSON.stringify(doc, null, options.compact ? undefined : 2);
+}
+/** Render an InvoML document (with computed totals in `doc.totals`) as a human-readable Markdown table. Follows the document's style.order or falls back to the default order. */
+export function toMarkdown(doc) {
+    const lines = [];
+    const currency = doc.meta.currency;
+    const dp = getCurrencyDecimals(currency);
+    const fmt = (n) => fmtNum(n, dp);
+    const order = resolveOrder(doc);
+    for (const block of order) {
+        renderBlock(block, doc, lines, currency, fmt);
+    }
+    return lines.join('\n');
+}
+function renderBlock(block, doc, lines, currency, fmt) {
+    if (block === 'header') {
+        const type = doc.meta.documentType.replaceAll('_', ' ').toUpperCase();
+        lines.push(`# ${type} ${doc.meta.number}`);
+        lines.push('');
+        lines.push(`**Date:** ${doc.meta.issueDate}`);
+        if (doc.meta.dueDate)
+            lines.push(`**Due:** ${doc.meta.dueDate}`);
+        lines.push(`**Currency:** ${currency}`);
+        if (doc.meta.reference)
+            lines.push(`**Reference:** ${doc.meta.reference}`);
+        lines.push('');
+    }
+    else if (block === 'from') {
+        renderParty('From', doc.from, lines);
+    }
+    else if (block === 'to') {
+        renderParty('To', doc.to, lines);
+    }
+    else if (block === 'items') {
+        renderItems(doc, lines, fmt);
+    }
+    else if (block === 'totals') {
+        renderTotals(doc.totals, lines, currency, fmt);
+    }
+    else if (block === 'payment') {
+        renderPayment(doc, lines);
+    }
+    else if (block === 'notes') {
+        if (doc.notes) {
+            lines.push('---');
+            lines.push('');
+            lines.push(`*${doc.notes}*`);
+            lines.push('');
+        }
+    }
+    else if (block.startsWith('section:')) {
+        const key = block.slice('section:'.length);
+        const section = doc.sections?.[key];
+        if (section) {
+            lines.push(`### ${section.title}`);
+            lines.push('');
+            lines.push(section.content);
+            lines.push('');
+        }
+    }
+}
+function renderParty(label, party, lines) {
+    if (!party)
+        return;
+    lines.push(`**${label}:**`);
+    if (party.content) {
+        lines.push(party.content);
+    }
+    else {
+        if (party.name)
+            lines.push(party.name);
+        if (party.address)
+            lines.push(party.address);
+        if (party.attention)
+            lines.push(`Attn: ${party.attention}`);
+        if (party.email)
+            lines.push(party.email);
+        if (party.phone)
+            lines.push(party.phone);
+        if (party.website)
+            lines.push(party.website);
+        if (party.taxId)
+            lines.push(`Tax ID: ${party.taxId}`);
+        if (party.businessNumber)
+            lines.push(`Business No: ${party.businessNumber}`);
+    }
+    lines.push('');
+}
+function formatDiscount(discount) {
+    if (typeof discount === 'string')
+        return discount;
+    if (discount.type === 'percentage')
+        return `${discount.value}%`;
+    return String(discount.value);
+}
+function renderItems(doc, lines, fmt) {
+    const hasUnit = doc.items.some(i => i.unit);
+    const hasDiscount = doc.items.some(i => i.discount);
+    const cols = ['Description', 'Qty'];
+    if (hasUnit)
+        cols.push('Unit');
+    cols.push('Unit Price');
+    if (hasDiscount)
+        cols.push('Discount');
+    cols.push('Amount');
+    lines.push('| ' + cols.join(' | ') + ' |');
+    lines.push('| ' + cols.map(() => '---').join(' | ') + ' |');
+    for (const item of doc.items) {
+        const row = [item.description, String(item.quantity)];
+        if (hasUnit)
+            row.push(item.unit ?? '');
+        row.push(fmt(item.unitPrice));
+        if (hasDiscount)
+            row.push(item.discount ? formatDiscount(item.discount) : '');
+        row.push(fmt(item.amount ?? item.quantity * item.unitPrice));
+        lines.push('| ' + row.join(' | ') + ' |');
+    }
+    lines.push('');
+}
+function renderTotals(totals, lines, currency, fmt) {
+    if (!totals)
+        return;
+    lines.push('| | |');
+    lines.push('| ---: | ---: |');
+    lines.push(`| **Subtotal** | ${fmt(totals.subtotal)} |`);
+    if (totals.discountDetails) {
+        for (const d of totals.discountDetails) {
+            lines.push(`| ${d.label ?? 'Discount'} | -${fmt(d.amount)} |`);
+        }
+        lines.push(`| After Discounts | ${fmt(totals.afterDiscounts)} |`);
+    }
+    if (totals.taxDetails) {
+        for (const t of totals.taxDetails) {
+            const suffix = t.inclusive ? ' (included)' : '';
+            lines.push(`| ${t.label ?? t.category}${suffix} | ${fmt(t.amount)} |`);
+        }
+    }
+    if (totals.withholdingTotal && totals.withholdingTotal > 0) {
+        lines.push(`| Withholding | -${fmt(totals.withholdingTotal)} |`);
+    }
+    lines.push(`| **Total (${currency})** | **${fmt(totals.total)}** |`);
+    if (totals.prepaidAmount && totals.prepaidAmount > 0) {
+        lines.push(`| Prepaid | -${fmt(totals.prepaidAmount)} |`);
+        lines.push(`| **Amount Due** | **${fmt(totals.amountDue)}** |`);
+    }
+    lines.push('');
+}
+function renderPayment(doc, lines) {
+    if (!doc.payment)
+        return;
+    lines.push('### Payment');
+    lines.push('');
+    if (doc.payment.content) {
+        lines.push(doc.payment.content);
+    }
+    else {
+        if (doc.payment.beneficiary)
+            lines.push(`**Beneficiary:** ${doc.payment.beneficiary}`);
+        if (doc.payment.bank)
+            lines.push(`**Bank:** ${doc.payment.bank}`);
+        if (doc.payment.iban)
+            lines.push(`**IBAN:** ${doc.payment.iban}`);
+        if (doc.payment.swift)
+            lines.push(`**SWIFT:** ${doc.payment.swift}`);
+        if (doc.payment.routingNumber)
+            lines.push(`**Routing:** ${doc.payment.routingNumber}`);
+        if (doc.payment.accountNumber)
+            lines.push(`**Account:** ${doc.payment.accountNumber}`);
+        if (doc.payment.cryptoAddress)
+            lines.push(`**Address:** ${doc.payment.cryptoAddress}`);
+        if (doc.payment.cryptoNetwork)
+            lines.push(`**Network:** ${doc.payment.cryptoNetwork}`);
+    }
+    lines.push('');
+}

package/dist/src/style.d.ts

@@ -0,0 +1,21 @@
+import type { InvoMLDocument, InvoMLStyle } from './types.js';
+export declare const RESERVED_BLOCK_NAMES: readonly ["header", "from", "to", "items", "totals", "payment", "notes"];
+export declare const DEFAULT_ORDER: string[];
+export interface StyleValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/** Resolve the effective block rendering order for a document.
+ *  If style.order is present, deduplicate it and return the result.
+ *  Otherwise build the canonical default order, inserting custom sections (sorted alphabetically)
+ *  after totals and before payment. */
+export declare function resolveOrder(doc: InvoMLDocument): string[];
+/** Validate a style object against the normative style rules. */
+export declare function validateStyle(style: InvoMLStyle, sectionNames?: string[]): StyleValidationResult;
+/** Resolve the full style object with defaults applied. */
+export declare function resolveStyle(doc: InvoMLDocument): {
+    order: string[];
+    properties: Record<string, string>;
+    blocks: Record<string, Record<string, string>>;
+};

package/dist/src/style.js

@@ -0,0 +1,70 @@
+// src/style.ts
+export const RESERVED_BLOCK_NAMES = ['header', 'from', 'to', 'items', 'totals', 'payment', 'notes'];
+export const DEFAULT_ORDER = ['header', 'from', 'to', 'items', 'totals', 'payment', 'notes'];
+/** Resolve the effective block rendering order for a document.
+ *  If style.order is present, deduplicate it and return the result.
+ *  Otherwise build the canonical default order, inserting custom sections (sorted alphabetically)
+ *  after totals and before payment. */
+export function resolveOrder(doc) {
+    if (doc.style?.order) {
+        // Deduplicate: each block name renders at most once (first occurrence wins)
+        const seen = new Set();
+        return doc.style.order.filter(b => {
+            if (seen.has(b))
+                return false;
+            seen.add(b);
+            return true;
+        });
+    }
+    const sectionNames = doc.sections ? Object.keys(doc.sections).sort() : [];
+    if (sectionNames.length === 0)
+        return DEFAULT_ORDER;
+    const result = [];
+    for (const block of DEFAULT_ORDER) {
+        result.push(block);
+        if (block === 'totals') {
+            for (const name of sectionNames) {
+                result.push(`section:${name}`);
+            }
+        }
+    }
+    return result;
+}
+/** Validate a style object against the normative style rules. */
+export function validateStyle(style, sectionNames) {
+    const errors = [];
+    const warnings = [];
+    if (style.order !== undefined) {
+        if (style.order.length === 0) {
+            errors.push('style.order must contain at least one entry');
+        }
+        else if (sectionNames !== undefined) {
+            for (const entry of style.order) {
+                if (entry.startsWith('section:')) {
+                    const key = entry.slice('section:'.length);
+                    if (!sectionNames.includes(key)) {
+                        errors.push(`style.order references unknown section "${key}"`);
+                    }
+                }
+            }
+        }
+    }
+    if (style.blocks) {
+        for (const key of Object.keys(style.blocks)) {
+            const isReserved = RESERVED_BLOCK_NAMES.includes(key);
+            const isSectionPattern = /^section:[a-zA-Z0-9_-]+$/.test(key);
+            if (!isReserved && !isSectionPattern) {
+                warnings.push(`style.blocks key "${key}" is not a reserved block name or section:<key> pattern`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+/** Resolve the full style object with defaults applied. */
+export function resolveStyle(doc) {
+    return {
+        order: resolveOrder(doc),
+        properties: doc.style?.properties ?? {},
+        blocks: doc.style?.blocks ?? {},
+    };
+}

package/dist/src/tax.d.ts

@@ -0,0 +1,3 @@
+import type { InvoMLTaxSimple, InvoMLTaxFull, InvoMLTaxCategory, InvoMLItem, ResolvedTaxConfig } from './types.js';
+export declare function resolveTaxConfig(tax: InvoMLTaxSimple | InvoMLTaxFull | undefined): ResolvedTaxConfig | null;
+export declare function resolveCategory(item: InvoMLItem, config: ResolvedTaxConfig): InvoMLTaxCategory;

package/dist/src/tax.js

@@ -0,0 +1,40 @@
+import { CalculationError } from './types.js';
+function isTaxFull(tax) {
+    return 'categories' in tax;
+}
+export function resolveTaxConfig(tax) {
+    if (!tax)
+        return null;
+    if (isTaxFull(tax)) {
+        return {
+            system: tax.system ?? 'vat',
+            categories: tax.categories,
+            compound: tax.compound ?? false,
+            inclusive: tax.inclusive ?? false,
+        };
+    }
+    const implicitId = tax.label.toLowerCase().replace(/ /g, '-');
+    return {
+        system: 'vat',
+        categories: [{
+                id: implicitId, label: tax.label, rate: tax.rate,
+                default: true, exempt: false, reverseCharge: false,
+                withholding: false, inclusive: tax.inclusive ?? false,
+            }],
+        compound: false,
+        inclusive: tax.inclusive ?? false,
+    };
+}
+export function resolveCategory(item, config) {
+    if (item.taxCategory) {
+        const match = config.categories.find(c => c.id === item.taxCategory);
+        if (!match)
+            throw new CalculationError('UNKNOWN_CATEGORY', `Unknown tax category '${item.taxCategory}'`);
+        return match;
+    }
+    const defaults = config.categories.filter(c => c.default);
+    if (defaults.length === 0) {
+        throw new CalculationError('NO_DEFAULT_CATEGORY', `Item '${item.description}' has no taxCategory and no default category is defined`);
+    }
+    return defaults[0];
+}

package/dist/src/types.d.ts

@@ -0,0 +1,132 @@
+export interface InvoMLDocument {
+    $invoml: '1.0';
+    meta: InvoMLMeta;
+    from?: InvoMLParty;
+    to?: InvoMLParty;
+    items: InvoMLItem[];
+    discounts?: InvoMLDiscount[];
+    payment?: InvoMLPayment;
+    sections?: Record<string, InvoMLSection>;
+    notes?: string;
+    totals?: InvoMLTotals;
+    style?: InvoMLStyle;
+}
+export interface InvoMLStyle {
+    template?: string;
+    order?: string[];
+    properties?: Record<string, string>;
+    blocks?: Record<string, Record<string, string>>;
+}
+export interface InvoMLMeta {
+    documentType: 'invoice' | 'quote' | 'credit_note' | 'receipt';
+    number: string;
+    issueDate: string;
+    currency: string;
+    dueDate?: string;
+    expiryDate?: string;
+    locale?: string;
+    reference?: string;
+    creditNoteReference?: string;
+    tax?: InvoMLTaxSimple | InvoMLTaxFull;
+}
+export interface InvoMLTaxSimple {
+    label: string;
+    rate: number;
+    inclusive?: boolean;
+}
+export interface InvoMLTaxFull {
+    system?: string;
+    compound?: boolean;
+    inclusive?: boolean;
+    categories: InvoMLTaxCategory[];
+}
+export interface InvoMLTaxCategory {
+    id: string;
+    label: string;
+    rate: number;
+    default?: boolean;
+    exempt?: boolean;
+    reverseCharge?: boolean;
+    withholding?: boolean;
+    inclusive?: boolean;
+}
+export interface InvoMLItem {
+    description: string;
+    quantity: number;
+    unitPrice: number;
+    unit?: string;
+    discount?: string | InvoMLDiscount;
+    taxCategory?: string;
+    amount?: number;
+    taxAmount?: number;
+}
+export interface InvoMLDiscount {
+    type: 'percentage' | 'fixed';
+    value: number;
+    label?: string;
+}
+export interface InvoMLParty {
+    content?: string;
+    name?: string;
+    address?: string;
+    taxId?: string;
+    email?: string;
+    phone?: string;
+    website?: string;
+    businessNumber?: string;
+    attention?: string;
+    countryCode?: string;
+}
+export interface InvoMLPayment {
+    title?: string;
+    content?: string;
+    method?: 'bank-international' | 'bank-domestic' | 'crypto' | 'card' | 'other';
+    beneficiary?: string;
+    bank?: string;
+    iban?: string;
+    swift?: string;
+    routingNumber?: string;
+    accountNumber?: string;
+    cryptoAddress?: string;
+    cryptoNetwork?: string;
+}
+export interface InvoMLSection {
+    title: string;
+    content: string;
+}
+export interface InvoMLTotals {
+    subtotal: number;
+    discountDetails?: {
+        label?: string;
+        amount: number;
+    }[];
+    afterDiscounts: number;
+    taxDetails?: InvoMLTaxDetail[];
+    taxTotal: number;
+    withholdingTotal?: number;
+    total: number;
+    prepaidAmount?: number;
+    amountDue: number;
+    currencySymbol?: string;
+    locale?: string;
+}
+export interface InvoMLTaxDetail {
+    category: string;
+    label?: string;
+    rate?: number;
+    base: number;
+    amount: number;
+    inclusive?: boolean;
+    withholding?: boolean;
+}
+/** Error class for calculation errors defined in SPEC Section 8.2. Includes a machine-readable `code` property. */
+export declare class CalculationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface ResolvedTaxConfig {
+    system: string;
+    categories: InvoMLTaxCategory[];
+    compound: boolean;
+    inclusive: boolean;
+}

package/dist/src/types.js

@@ -0,0 +1,10 @@
+// src/types.ts
+/** Error class for calculation errors defined in SPEC Section 8.2. Includes a machine-readable `code` property. */
+export class CalculationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'CalculationError';
+    }
+}