@invompt/invoml 1.0.0-alpha.4

package/invoml-v1.0.schema.json

@@ -0,0 +1,258 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/invompt/InvoML/blob/main/invoml-v1.0.schema.json",
+  "title": "InvoML v1.0",
+  "description": "Invoice Markup Language v1.0 — compact invoice format for AI structured output",
+  "type": "object",
+  "required": ["$invoml", "meta", "items"],
+    "properties": {
+    "$invoml": { "type": "string", "const": "1.0", "description": "InvoML specification version. Must be \"1.0\"." },
+    "meta": {
+      "type": "object",
+      "description": "Document metadata — type, number, dates, currency, and tax configuration.",
+      "required": ["documentType", "number", "issueDate", "currency"],
+            "properties": {
+        "documentType": { "type": "string", "enum": ["invoice", "quote", "credit_note", "receipt"], "description": "The type of commercial document." },
+        "number": { "type": "string", "minLength": 1, "description": "Unique document identifier (e.g. INV-2026-001)." },
+        "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the document was issued (YYYY-MM-DD)." },
+        "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Payment due date (YYYY-MM-DD). Optional." },
+        "expiryDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Expiry date for quotes and estimates (YYYY-MM-DD). Optional." },
+        "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency code (e.g. USD, EUR, GBP)." },
+        "locale": { "type": "string", "description": "BCP 47 locale tag for number/date formatting (e.g. en-US, de-DE). Optional." },
+        "reference": { "type": "string", "description": "External reference such as a purchase order number. Optional." },
+        "creditNoteReference": { "type": "string", "description": "Invoice number this credit note references. Required when documentType is credit_note." },
+        "tax": {
+          "description": "Tax configuration. Either a simple single-rate tax or a full multi-category tax system.",
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Simple tax — a single label and rate applied to all items.",
+              "required": ["label", "rate"],
+                            "properties": {
+                "label": { "type": "string", "minLength": 1, "description": "Display name for the tax (e.g. VAT, GST, Sales Tax)." },
+                "rate": { "type": "number", "description": "Tax rate as a percentage (e.g. 10 for 10%)." },
+                "inclusive": { "type": "boolean", "description": "If true, item prices already include this tax." }
+              }
+            },
+            {
+              "type": "object",
+              "description": "Full tax — multiple categories with individual rates and behaviors.",
+              "required": ["categories"],
+                            "properties": {
+                "system": { "type": "string", "description": "Name of the tax system (e.g. GST, VAT). For display purposes." },
+                "compound": { "type": "boolean", "description": "If true, all tax categories apply to the full base (not split by line item category)." },
+                "inclusive": { "type": "boolean", "description": "If true, item prices already include tax. Tax is backed out during calculation." },
+                "categories": {
+                  "type": "array",
+                  "description": "List of tax categories. At least one must be marked as default.",
+                  "minItems": 1,
+                  "items": {
+                    "type": "object",
+                    "description": "A single tax category with its rate and behavior flags.",
+                    "required": ["id", "label", "rate"],
+                                        "properties": {
+                      "id": { "type": "string", "minLength": 1, "description": "Unique identifier for this category. Referenced by items via taxCategory." },
+                      "label": { "type": "string", "minLength": 1, "description": "Display name (e.g. Standard Rate, Reduced Rate, Exempt)." },
+                      "rate": { "type": "number", "description": "Tax rate as a percentage." },
+                      "default": { "type": "boolean", "description": "If true, items without an explicit taxCategory use this category." },
+                      "exempt": { "type": "boolean", "description": "If true, this category carries a 0% effective tax regardless of rate." },
+                      "reverseCharge": { "type": "boolean", "description": "If true, tax is reported but not collected. Buyer self-assesses." },
+                      "withholding": { "type": "boolean", "description": "If true, this tax is withheld by the buyer and remitted to the tax authority." },
+                      "inclusive": { "type": "boolean", "description": "Reserved. Inclusive tax is set at the top-level tax configuration, not per category." }
+                    }
+                  }
+                }
+              }
+            }
+          ]
+        }
+      },
+      "if": { "properties": { "documentType": { "const": "credit_note" } } },
+      "then": { "required": ["documentType", "number", "issueDate", "currency", "creditNoteReference"] }
+    },
+    "from": {
+      "type": "object",
+      "description": "The issuer (seller, freelancer, service provider). Use content for free-form Markdown or structured fields.",
+            "properties": {
+        "content": { "type": "string", "description": "Free-form text with Markdown formatting (bold, italic, lists, links). Contains the full party display text. Example: '**Acme Corp**\\n123 Main St\\nNew York, NY 10001'. If provided, structured fields below are ignored for rendering." },
+        "name": { "type": "string", "description": "Legal or business name." },
+        "address": { "type": "string", "description": "Full postal address." },
+        "taxId": { "type": "string", "description": "Tax identification number (VAT number, EIN, RUC, etc.)." },
+        "email": { "type": "string", "format": "email", "description": "Contact email address." },
+        "phone": { "type": "string", "description": "Contact phone number." },
+        "website": { "type": "string", "format": "uri", "description": "Website URL." },
+        "businessNumber": { "type": "string", "description": "Business registration number (ABN, SIRET, etc.)." },
+        "attention": { "type": "string", "description": "Attention line — name of a specific person." },
+        "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code." }
+      }
+    },
+    "to": {
+      "type": "object",
+      "description": "The recipient (buyer, client, customer).",
+            "properties": {
+        "content": { "type": "string", "description": "Free-form text with Markdown formatting (bold, italic, lists, links). Contains the full party display text. Example: '**Client LLC**\\n456 Oak Ave\\nSan Francisco, CA 94102'. If provided, structured fields below are ignored for rendering." },
+        "name": { "type": "string", "description": "Legal or business name." },
+        "address": { "type": "string", "description": "Full postal address." },
+        "taxId": { "type": "string", "description": "Tax identification number." },
+        "email": { "type": "string", "format": "email", "description": "Contact email address." },
+        "phone": { "type": "string", "description": "Contact phone number." },
+        "website": { "type": "string", "format": "uri", "description": "Website URL." },
+        "businessNumber": { "type": "string", "description": "Business registration number." },
+        "attention": { "type": "string", "description": "Attention line — name of a specific person." },
+        "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code." }
+      }
+    },
+    "items": {
+      "type": "array",
+      "description": "Line items on the document. At least one is required.",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "description": "A single line item.",
+        "required": ["description", "quantity", "unitPrice"],
+                "properties": {
+          "description": { "type": "string", "minLength": 1, "description": "Description of the good or service." },
+          "quantity": { "type": "number", "description": "Quantity (e.g. 10 hours, 3 units)." },
+          "unitPrice": { "type": "number", "description": "Price per unit before discounts." },
+          "unit": { "type": "string", "description": "Unit label (e.g. hours, units, kg). Optional." },
+          "discount": {
+            "description": "Line-level discount. Either a shorthand string (e.g. \"10%\" or \"50\") or a structured object. Omit this field entirely when no discount applies. Do not set to null.",
+            "oneOf": [
+              { "type": "string", "pattern": "^(\\d+(\\.\\d+)?%|\\d+(\\.\\d+)?)$", "description": "Shorthand: \"10%\" for percentage or \"50\" for fixed amount." },
+              {
+                "type": "object",
+                "description": "Structured discount with explicit type and value.",
+                "required": ["type", "value"],
+                                "properties": {
+                  "type": { "type": "string", "enum": ["percentage", "fixed"], "description": "Whether the discount is a percentage of the line total or a fixed amount." },
+                  "value": { "type": "number", "description": "The discount value (percentage points or currency amount)." }
+                }
+              }
+            ]
+          },
+          "taxCategory": { "type": "string", "description": "ID of the tax category this item belongs to. References a category in meta.tax.categories. Omit when using the default tax category. Do not set to null." },
+          "amount": { "type": "number", "description": "Computed by the runtime. Line total after line-level discount. Do not set manually." },
+          "taxAmount": { "type": "number", "description": "Computed by the runtime. Tax amount for this line. Do not set manually." }
+        }
+      }
+    },
+    "discounts": {
+      "type": "array",
+      "description": "Invoice-level discounts applied after the subtotal. Applied in order (cascading — each discount reduces the base for the next).",
+      "items": {
+        "type": "object",
+        "description": "An invoice-level discount.",
+        "required": ["type", "value"],
+                "properties": {
+          "type": { "type": "string", "enum": ["percentage", "fixed"], "description": "Whether the discount is a percentage or a fixed amount." },
+          "value": { "type": "number", "description": "The discount value." },
+          "label": { "type": "string", "description": "Display label (e.g. Early Payment Discount, Loyalty Discount). Optional." }
+        }
+      }
+    },
+    "payment": {
+      "type": "object",
+      "description": "Payment instructions. Use content for free-form Markdown or structured fields for specific payment methods.",
+            "properties": {
+        "title": { "type": "string", "description": "Custom title for the payment section." },
+        "content": { "type": "string", "description": "Free-form Markdown payment instructions. If provided, structured fields are ignored in rendering." },
+        "method": { "type": "string", "enum": ["bank-international", "bank-domestic", "crypto", "card", "other"], "description": "Payment method type." },
+        "beneficiary": { "type": "string", "description": "Name of the payment beneficiary." },
+        "bank": { "type": "string", "description": "Bank name." },
+        "iban": { "type": "string", "description": "International Bank Account Number." },
+        "swift": { "type": "string", "description": "SWIFT/BIC code." },
+        "routingNumber": { "type": "string", "description": "Bank routing number (US domestic transfers)." },
+        "accountNumber": { "type": "string", "description": "Bank account number." },
+        "cryptoAddress": { "type": "string", "description": "Cryptocurrency wallet address." },
+        "cryptoNetwork": { "type": "string", "description": "Cryptocurrency network (e.g. Bitcoin, Ethereum, Solana)." }
+      }
+    },
+    "sections": {
+      "type": "object",
+      "description": "Custom named sections for additional content (terms, scope of work, etc.). Keys must be alphanumeric with hyphens/underscores.",
+      "patternProperties": {
+        "^[a-zA-Z0-9_-]+$": {
+          "type": "object",
+          "description": "A custom content section.",
+          "required": ["title", "content"],
+                    "properties": {
+            "title": { "type": "string", "description": "Section heading." },
+            "content": { "type": "string", "description": "Section body in Markdown." }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "notes": { "type": "string", "description": "Free-form notes displayed at the bottom of the document." },
+    "style": {
+      "type": "object",
+      "description": "Presentation hints for renderers. Controls block ordering, visual arrangement, and appearance. Machine consumers MUST ignore this field.",
+      "properties": {
+        "template": { "type": "string", "description": "Named visual theme shorthand (e.g. professional, minimal, modern). Renderers may ignore unknown names." },
+        "order": {
+          "type": "array",
+          "description": "Explicit block rendering sequence. Blocks not listed are not rendered. Valid block names: header, from, to, items, totals, payment, notes, section:{key} (where {key} matches a key in sections). Example: [\"header\", \"from\", \"to\", \"items\", \"totals\", \"section:scope\", \"payment\", \"notes\"]",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "properties": {
+          "type": "object",
+          "description": "Document-level CSS-compatible style hints (e.g. font-family, --accent).",
+          "additionalProperties": { "type": "string" }
+        },
+        "blocks": {
+          "type": "object",
+          "description": "Per-block CSS-compatible style hints. Keys must be valid block names (header, from, to, items, totals, payment, notes) or section:{key} references.",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "totals": {
+      "type": "object",
+      "description": "Computed totals. Populated by the runtime after calculation. AI models should NOT set these fields.",
+            "properties": {
+        "subtotal": { "type": "number", "description": "Sum of all line item amounts before invoice-level discounts." },
+        "discountDetails": {
+          "type": "array",
+          "description": "Breakdown of each invoice-level discount applied.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "label": { "type": "string", "description": "Discount label." },
+              "amount": { "type": "number", "description": "Discount amount in currency." }
+            }
+          }
+        },
+        "afterDiscounts": { "type": "number", "description": "Subtotal minus all invoice-level discounts." },
+        "taxDetails": {
+          "type": "array",
+          "description": "Per-category tax breakdown.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "category": { "type": "string", "description": "Tax category ID." },
+              "label": { "type": "string", "description": "Tax category display label." },
+              "rate": { "type": "number", "description": "Tax rate as a percentage." },
+              "base": { "type": "number", "description": "Taxable base amount for this category." },
+              "amount": { "type": "number", "description": "Computed tax amount." },
+              "inclusive": { "type": "boolean", "description": "Whether this tax is already included in item prices." },
+              "withholding": { "type": "boolean", "description": "Whether this tax is withheld by the buyer and remitted to the tax authority." }
+            }
+          }
+        },
+        "taxTotal": { "type": "number", "description": "Total tax amount (excluding withholding)." },
+        "withholdingTotal": { "type": "number", "description": "Total withholding tax amount." },
+        "total": { "type": "number", "description": "Grand total: afterDiscounts + taxTotal - withholdingTotal (or afterDiscounts if inclusive)." },
+        "prepaidAmount": { "type": "number", "description": "Amount already paid. Deducted from total to compute amountDue." },
+        "amountDue": { "type": "number", "description": "Final amount owed: total - prepaidAmount." },
+        "currencySymbol": { "type": "string", "description": "Currency symbol for display (e.g. $, EUR, GBP). Set by the runtime." },
+        "locale": { "type": "string", "description": "Locale used for number formatting. Set by the runtime." }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@invompt/invoml",
+  "version": "1.0.0-alpha.4",
+  "description": "InvoML — Invoice Markup Language: parse, validate, calculate",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./invoml-v1.0.schema.json": "./invoml-v1.0.schema.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "invoml-v1.0.schema.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "invoml": "dist/cli/invoml.js"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "cli": "tsx cli/invoml.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/invompt/InvoML.git"
+  },
+  "homepage": "https://github.com/invompt/InvoML",
+  "bugs": {
+    "url": "https://github.com/invompt/InvoML/issues"
+  },
+  "keywords": [
+    "invoice",
+    "invoml",
+    "invoice-markup-language",
+    "ai",
+    "structured-output",
+    "json-schema",
+    "billing",
+    "tax"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "ajv-formats": "^3.0.0",
+    "decimal.js": "^10.5.0"
+  }
+}