zatca-qr 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# سجل التغييرات
+
+## 1.0.0 — 2026-09-29
+
+الإصدار الأول.
+
+- `encodeZatcaTlv(data, { strict })` — ترميز TLV ثم Base64، مع ترتيب العلامات تصاعدياً.
+- `buildTlvBytes(data)` — الوصول إلى البايتات الخام للفحص والاختبار.
+- `decodeZatcaTlv(base64)` — فك الترميز إلى حقول مقروءة، مع تنبيهات للعلامات المكرّرة
+  والناقصة والخارجة عن المواصفة، وتسامح مع Base64 الآمن للروابط.
+- `validateZatcaInvoice(data)` — فحص المواصفة: الرقم الضريبي، الطابع الزمني، المبالغ،
+  حدود البايتات، واكتمال حقول مرحلة الربط.
+- `toZatcaAmount(value)` — تنسيق المبلغ بفاصلة نقطية وبمنزلتين.
+- دعم علامات مرحلة الربط 6 و7 و8 و9.
+- 38 اختباراً بلا أي تبعية، منها فيكتور مرجعي بفاتورة مبسّطة.
+- صفحة تجريبية عربية تعمل في المتصفح بلا خادم.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeIO — https://www.vibeio.dev
+
+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.en.md

@@ -0,0 +1,101 @@
+# zatca-qr
+
+**ZATCA (Saudi FATOORA) e-invoice QR payloads — zero dependencies, no server, tested against the specification.**
+
+[![CI](https://github.com/Exeerkit/zatca-qr/actions/workflows/ci.yml/badge.svg)](https://github.com/Exeerkit/zatca-qr/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![release](https://img.shields.io/github/v/release/exeerkit/zatca-qr)](https://github.com/exeerkit/zatca-qr/releases)
+
+> The Arabic-first README is the primary one: [README.md](README.md).
+
+## The problem
+
+Every tax invoice in Saudi Arabia must carry a QR payload built as a **TLV** sequence and then
+**Base64** encoded. The most common — and hardest to spot — bug is measuring field length in
+**characters** instead of **UTF-8 bytes**:
+
+| Seller name | Characters | UTF-8 bytes | Result |
+| --- | --- | --- | --- |
+| `Acme Saudi` | 10 | 10 | ✅ valid |
+| `شركة النخبة` | 10 | 20 | ❌ payload rejected |
+| `ش` × 128 | 128 | 256 | ❌ exceeds the 255-byte TLV limit |
+
+This library counts bytes correctly, decodes payloads for verification, and validates the invoice
+before you issue it.
+
+## Install
+
+```bash
+npm install github:exeerkit/zatca-qr   # available now, straight from the repository
+npm install zatca-qr                   # once the package is published to npm
+```
+
+Zero dependencies. ESM only. Runs in Node 18+, browsers, Cloudflare Workers, Deno and Bun.
+
+## Usage
+
+```ts
+import { encodeZatcaTlv, toZatcaAmount, validateZatcaInvoice } from 'zatca-qr'
+
+const invoice = {
+  sellerName: 'النخبة Trading Est.',
+  vatNumber: '300000000000003',        // 15 digits, starts and ends with 3
+  timestamp: new Date(),               // or an ISO 8601 string with a time zone
+  totalWithVat: toZatcaAmount(1150),   // '1150.00'
+  vatTotal: toZatcaAmount(150),        // '150.00'
+}
+
+const report = validateZatcaInvoice(invoice) // errors block, warnings inform
+const payload = encodeZatcaTlv(invoice, { strict: true }) // pass to any QR renderer
+```
+
+### Verify a payload you received
+
+```ts
+import { decodeZatcaTlv } from 'zatca-qr'
+
+const decoded = decodeZatcaTlv(payloadFromScanner)
+decoded.phase        // 1 or 2
+decoded.data         // { sellerName, vatNumber, timestamp, totalWithVat, vatTotal, ... }
+decoded.fields       // each field: tag, name, value, byteLength
+decoded.warnings     // duplicate tags, missing required tags, out-of-spec tags
+```
+
+## Tags
+
+| Tag | Field | Phase |
+| --- | --- | --- |
+| `1` | Seller name (UTF-8) | 1 (required) |
+| `2` | VAT registration number (15 digits) | 1 (required) |
+| `3` | Invoice timestamp (ISO 8601 with zone) | 1 (required) |
+| `4` | Invoice total including VAT (dot decimal) | 1 (required) |
+| `5` | VAT amount | 1 (required) |
+| `6` | Invoice XML hash (Base64 SHA-256) | 2 (optional) |
+| `7` | Digital signature (Base64 ECDSA) | 2 (optional) |
+| `8` | Public key (Base64) | 2 (optional) |
+| `9` | ZATCA stamp | after clearance only |
+
+## Phase 2: what this library does and does not do
+
+It packs and unpacks the payload. It does **not** hash your XML, sign anything, call the FATOORA
+platform, or manage CSID certificates — you supply `invoiceHash`, `signature` and `publicKey` from
+your own stack. Tags 6, 7 and 8 must be provided together; `stamp` is only accepted alongside them.
+
+## Try it
+
+```bash
+git clone https://github.com/exeerkit/zatca-qr
+cd zatca-qr
+python3 -m http.server 8080   # open http://localhost:8080/examples/demo.html
+node examples/node.mjs        # CLI example, nothing to install
+node --test             # 38 tests, zero dependencies
+```
+
+## References
+
+- [ZATCA detailed technical guideline (PDF)](https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/E-invoicing-Detailed-Technical-Guideline.pdf)
+- [ZATCA developers portal](https://zatca.gov.sa/en/E-Invoicing/SystemsDevelopers/Pages/default.aspx)
+
+## License
+
+MIT. Built by [VibeIO](https://www.vibeio.dev).

package/README.md

@@ -0,0 +1,222 @@
+<div dir="rtl" align="right">
+
+# zatca-qr
+
+**تولّد رمز QR لفواتير زاتكا السعودية وتقرأه. بدون مكتبات خارجية وبدون خادم.**
+
+[![CI](https://github.com/Exeerkit/zatca-qr/actions/workflows/ci.yml/badge.svg)](https://github.com/Exeerkit/zatca-qr/actions/workflows/ci.yml)
+![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![release](https://img.shields.io/github/v/release/exeerkit/zatca-qr)](https://github.com/exeerkit/zatca-qr/releases)
+
+</div>
+
+<div dir="rtl" align="right">
+
+## المشكلة
+
+في السعودية كل فاتورة ضريبية لازم يكون عليها رمز QR. الرمز مكتوب بصيغة اسمها **TLV** وبعدها
+**Base64**. إذا كان الرمز غلط، نظام المشتري يرفض الفاتورة.
+
+الخطأ المشهور هو حساب طول الحقل بعدد **الحروف**. لكن TLV يحسب الطول بعدد **البايتات**.
+الحرف العربي = بايتين. لذلك:
+
+| اسم البائع | عدد الحروف | عدد البايتات | النتيجة |
+| --- | --- | --- | --- |
+| `Acme Saudi` | 10 | 10 | ✅ سليم |
+| `شركة النخبة` | 10 | 20 | ❌ الرمز يُرفض |
+| `ش` × 128 | 128 | 256 | ❌ أكبر من حد TLV (255) |
+
+هذه المكتبة تحسب البايتات صح، وتقرأ الرمز لو وصلك من جهة ثانية، وتفحص الفاتورة قبل ما ترسلها.
+
+## التثبيت
+
+```bash
+npm install github:exeerkit/zatca-qr   # متاح الآن من المستودع
+npm install zatca-qr                   # بعد نشر الحزمة على npm
+```
+
+بدون أي مكتبة خارجية. تعمل في Node 18 وأحدث، وفي المتصفح، وفي Cloudflare Workers وDeno وBun.
+
+## الاستخدام
+
+```ts
+import { encodeZatcaTlv, toZatcaAmount, validateZatcaInvoice } from 'zatca-qr'
+
+const invoice = {
+  sellerName: 'مؤسسة النخبة التجارية',
+  vatNumber: '300000000000003',        // 15 رقماً، يبدأ بـ3 وينتهي بـ3
+  timestamp: new Date(),               // أو نص ISO 8601 مع منطقة زمنية
+  totalWithVat: toZatcaAmount(1150),   // يطلع '1150.00'
+  vatTotal: toZatcaAmount(150),        // يطلع '150.00'
+}
+
+// 1) افحص الفاتورة قبل الإرسال
+const report = validateZatcaInvoice(invoice)
+if (!report.valid) throw new Error(report.errors[0].message)
+
+// 2) خذ نص الرمز
+const payload = encodeZatcaTlv(invoice, { strict: true })
+
+// 3) حطه في أي مولد QR
+```
+
+### مع React
+
+```tsx
+import { QRCodeSVG } from 'qrcode.react'
+import { encodeZatcaTlv, type ZatcaInvoiceData } from 'zatca-qr'
+
+export function InvoiceQr({ invoice }: { invoice: ZatcaInvoiceData }) {
+  return <QRCodeSVG value={encodeZatcaTlv(invoice)} size={220} level="M" />
+}
+```
+
+### على Cloudflare Workers
+
+```ts
+import { encodeZatcaTlv } from 'zatca-qr'
+
+export default {
+  fetch(request: Request) {
+    const url = new URL(request.url)
+    const payload = encodeZatcaTlv({
+      sellerName: url.searchParams.get('seller') ?? '',
+      vatNumber: url.searchParams.get('vat') ?? '',
+      timestamp: new Date(),
+      totalWithVat: url.searchParams.get('total') ?? '0.00',
+      vatTotal: url.searchParams.get('vat_amount') ?? '0.00',
+    })
+    return Response.json({ qrPayloadBase64: payload })
+  },
+}
+```
+
+## اقرأ رمز وصل إليك
+
+تنفع لما تفحص رمز من نظام ثاني، أو تكتشف رمز مكتوب يدوي غلط.
+
+```ts
+import { decodeZatcaTlv } from 'zatca-qr'
+
+const decoded = decodeZatcaTlv(payloadFromScanner)
+console.log(decoded.phase)            // 1 أو 2
+console.log(decoded.data.sellerName)  // 'مؤسسة النخبة التجارية'
+console.log(decoded.fields)           // كل حقل مع طوله بالبايتات
+console.log(decoded.warnings)         // حقل مكرر؟ حقل ناقص؟ حقول غريبة؟
+```
+
+تقرأ المكتبة أيضاً Base64 الآمن للروابط، وترد الرموز الغريبة بدون ما تكسر الباقي.
+
+## جدول الحقول
+
+| الرقم | الحقل | النوع | المرحلة |
+| --- | --- | --- | --- |
+| `1` | اسم البائع | نص UTF-8 | الأولى (مطلوب) |
+| `2` | الرقم الضريبي | 15 رقماً يبدأ وينتهي بـ3 | الأولى (مطلوب) |
+| `3` | وقت الفاتورة | ISO 8601 مع منطقة زمنية | الأولى (مطلوب) |
+| `4` | الإجمالي مع الضريبة | رقم بفاصلة نقطية | الأولى (مطلوب) |
+| `5` | مبلغ الضريبة | رقم بفاصلة نقطية | الأولى (مطلوب) |
+| `6` | بصمة ملف الفاتورة | Base64 (SHA-256) | الثانية (اختياري) |
+| `7` | التوقيع الرقمي | Base64 (ECDSA) | الثانية (اختياري) |
+| `8` | المفتاح العام | Base64 | الثانية (اختياري) |
+| `9` | ختم الهيئة | Base64 | بعد الاعتماد فقط |
+
+## المرحلة الثانية: وش تسوي المكتبة وش ما تسوي
+
+**بصراحة:** المكتبة تغلّف الحمولة وتفكها فقط. ما تحسب لك بصمة الملف، وما توقّع، وما تتصل
+بهيئة الزكاة. البصمة والتوقيع تجيبهم من شهادتك (CSID) وتعطيها للمكتبة:
+
+```ts
+const payload = encodeZatcaTlv({
+  ...invoice,
+  invoiceHash,   // بصمة ملف الفاتورة XML
+  signature,     // التوقيع من شهادة CSID
+  publicKey,     // المفتاح العام من نفس الشهادة
+  // stamp تضيفه بعد اعتماد الهيئة
+})
+```
+
+قاعدة بسيطة: الحقول 6 و7 و8 تجي مع بعض. وختم الهيئة ما ينقبل بدونهم.
+
+## أخطاء ترفض الفاتورة
+
+| الغلط | الصح |
+| --- | --- |
+| وقت بدون منطقة (`2026-04-18 13:30`) | `2026-04-18T13:30:00+03:00` أو `...Z` |
+| فاصلة عربية (`1150,00`) أو فاصلة آلاف (`1,150.00`) | `1150.00` |
+| مبلغ بدون منزلتين (`115`) | `115.00` استخدم `toZatcaAmount` |
+| ترتيب الحقول غلط | المكتبة ترتبها صح دايم |
+| رقم ضريبي من 14 رقماً | 15 رقماً يبدأ وينتهي بـ3 |
+
+العملة في هذا الحقل ريال سعودي دايم، حتى لو الفاتورة بعملة ثانية في ملف XML.
+
+## جرّبها
+
+```bash
+git clone https://github.com/exeerkit/zatca-qr
+cd zatca-qr
+python3 -m http.server 8080
+# افتح http://localhost:8080/examples/demo.html
+```
+
+أو افتح النسخة الجاهزة: <https://exeerkit.github.io/zatca-qr/>
+
+صفحة عربية تولّد الرمز قدامك وتفككه بايت بايت، وكل شي يصير في متصفحك بدون ما يطلع حرف من
+جهازك.
+
+```bash
+node examples/node.mjs   # مثال سريع بدون تثبيت
+node --test        # 38 اختبار بدون مكتبات
+```
+
+## الاختبارات
+
+تشغل بدون أي تثبيت. فيها مثال جاهز لفاتورة بسيطة تحققنا منه بايت بايت (66 بايت):
+
+```text
+01 0A "Acme Saudi" 02 0F "300000000000003" 03 14 "2026-04-18T10:30:00Z" 04 06 "115.00" 05 05 "15.00"
+→ AQpBY21lIFNhdWRpAg8zMDAwMDAwMDAwMDAwMDMDFDIwMjYtMDQtMThUMTA6MzA6MDBaBAYxMTUuMDAFBTE1LjAw
+```
+
+وفيه كمان اختبارات لطول الحروف العربية، والرموز المقطوعة، وBase64 الغلط، والتطابق بين
+الملفات.
+
+## أسئلة متكررة
+
+**تكفي للمرحلة الثانية؟**
+لا. هي تغلّف وتفك الرمز. التوقيع والشهادات شيء ثاني تتعامل معه بنفسك.
+
+**ليش ESM فقط؟**
+عشان تشتغل في المتصفح مباشرة بدون أدوات بناء. لو تستخدم CommonJS استخدم `await import('zatca-qr')`.
+
+**ترسل بياناتي لخادم؟**
+لا. ما فيها أي اتصال بالنت أصلاً.
+
+**أقدر استخدمها في نظام تجاري؟**
+نعم، الرخصة MIT. والتأكد أن فاتورتك مطابقة هو مسؤوليتك، ولهذا موجود `validateZatcaInvoice`.
+
+## المراجع
+
+- [دليل زاتكا الفني (PDF)](https://zatca.gov.sa/en/E-Invoicing/Introduction/Guidelines/Documents/e-invoicing-detailed-technical-guideline.pdf)
+- [بوابة مطوري الهيئة](https://zatca.gov.sa/en/E-Invoicing/SystemsDevelopers/Pages/default.aspx)
+
+## الرخصة
+
+MIT. استخدمها كيف ما تبي.
+
+---
+
+</div>
+
+<div dir="rtl" align="right">
+
+## مين اللي سواها؟
+
+هذه المكتبة جزء صغير من قالب **[VibeIO](https://www.vibeio.dev)** لبناء تطبيقات SaaS عربية.
+القالب يجهز لك: دخول، فوترة، دفع، بريد، وملف `AGENTS.md` يوجه وكيلك الذكي.
+
+حطيناها مفتوحة المصدر لأن مشكلة رمز زاتكا تواجه كل مطور سعودي. إذا عجبك الكود هنا، الأصل
+كله في [vibeio.dev](https://www.vibeio.dev).
+
+</div>

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "zatca-qr",
+  "version": "1.0.0",
+  "description": "ZATCA (Saudi FATOORA) e-invoice QR: encode, decode and validate in TLV + Base64. Byte-accurate Arabic text, zero dependencies. مولّد وقارئ رمز فاتورة زاتكا.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test",
+    "demo": "node examples/node.mjs"
+  },
+  "keywords": [
+    "zatca",
+    "zatca-qr",
+    "fatoora",
+    "e-invoicing",
+    "saudi-arabia",
+    "vat",
+    "qr",
+    "qrcode",
+    "qr-decoder",
+    "tlv",
+    "base64",
+    "invoice",
+    "validate",
+    "arabic",
+    "rtl",
+    "ksa",
+    "tax"
+  ],
+  "author": "VibeIO <hello@vibeio.dev>",
+  "license": "MIT",
+  "homepage": "https://www.vibeio.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/exeerkit/zatca-qr.git"
+  },
+  "bugs": {
+    "url": "https://github.com/exeerkit/zatca-qr/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * تعريفات الأنواع — zatca-qr
+ * Types for the ZATCA e-invoice QR encoder/decoder.
+ */
+
+/** العلامات المعرَّفة في المواصفة. */
+export type ZatcaTag = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+
+/** حقول المرحلة الأولى: إلزامية على كل فاتورة ضريبية. */
+export interface ZatcaPhase1Fields {
+  /** اسم البائع كما في السجل التجاري (Tag 1) — عربي أو لاتيني. */
+  sellerName: string
+  /** الرقم الضريبي: 15 رقماً يبدأ وينتهي بـ3 (Tag 2). */
+  vatNumber: string
+  /** طابع زمني ISO 8601 مع منطقة زمنية، أو كائن Date (Tag 3). */
+  timestamp: string | Date
+  /** إجمالي الفاتورة شامل الضريبة (Tag 4). */
+  totalWithVat: string | number
+  /** إجمالي الضريبة (Tag 5). */
+  vatTotal: string | number
+}
+
+/**
+ * حقول مرحلة الربط: تُقدَّم الثلاثة الأولى معاً.
+ * المكتبة لا توقّع ولا تتصل بالهيئة، بل تنقل القيم التي ينتجها مخزنك (CSID).
+ */
+export interface ZatcaPhase2Fields {
+  /** Tag 6 — بصمة SHA-256 لملف الفاتورة XML بترميز Base64. */
+  invoiceHash?: string
+  /** Tag 7 — التوقيع الرقمي ECDSA بترميز Base64. */
+  signature?: string
+  /** Tag 8 — المفتاح العام للشهادة بترميز Base64. */
+  publicKey?: string
+  /** Tag 9 — ختم الهيئة، يُضاف بعد التخليص فقط. */
+  stamp?: string
+}
+
+export type ZatcaInvoiceData = ZatcaPhase1Fields & ZatcaPhase2Fields
+
+/** حقل واحد بعد فك ترميز TLV. */
+export interface ZatcaDecodedField {
+  tag: number
+  /** اسم الحقل المعروف، أو null للعلامات خارج المواصفة. */
+  name: string | null
+  value: string
+  byteLength: number
+}
+
+/** ملاحظة واحدة من الفحص: خطأ مانع أو تنبيه. */
+export interface ZatcaValidationIssue {
+  code: string
+  field: string | null
+  message: string
+}
+
+export interface ZatcaValidationResult {
+  valid: boolean
+  errors: ZatcaValidationIssue[]
+  warnings: ZatcaValidationIssue[]
+}
+
+export interface ZatcaDecodeWarning {
+  code: string
+  message: string
+}
+
+/** ناتج فك ترميز حمولة رمز QR. */
+export interface DecodedZatcaQr {
+  /** 2 إن كانت العلامات 6 و7 و8 موجودة، وإلا 1. */
+  phase: 1 | 2
+  fields: ZatcaDecodedField[]
+  unknown: ZatcaDecodedField[]
+  data: Record<string, string>
+  warnings: ZatcaDecodeWarning[]
+  byteLength: number
+}
+
+/** أرقام العلامات كما في المواصفة. */
+export declare const ZATCA_TAGS: Readonly<{
+  SELLER_NAME: 1
+  VAT_NUMBER: 2
+  TIMESTAMP: 3
+  TOTAL_WITH_VAT: 4
+  VAT_TOTAL: 5
+  INVOICE_HASH: 6
+  SIGNATURE: 7
+  PUBLIC_KEY: 8
+  STAMP: 9
+}>
+
+/** أسماء الحقول المقابلة لكل علامة. */
+export declare const ZATCA_TAG_NAMES: Readonly<Record<number, string>>
+
+/** خطأ المكتبة، يحمل رمزاً برمجياً في `code`. */
+export declare class ZatcaQrError extends Error {
+  readonly code: string
+  constructor(message: string, code?: string)
+}
+
+/** يبني بايتات TLV الخام. */
+export declare function buildTlvBytes(data: ZatcaInvoiceData): Uint8Array
+
+/** يرمّز البيانات إلى حمولة Base64 جاهزة لرمز QR. */
+export declare function encodeZatcaTlv(
+  data: ZatcaInvoiceData,
+  options?: { strict?: boolean },
+): string
+
+/** يفكّ ترميز حمولة Base64 إلى حقول مقروءة. */
+export declare function decodeZatcaTlv(base64: string): DecodedZatcaQr
+
+/** يفحص البيانات مقابل المواصفة ويفصل الأخطاء عن التنبيهات. */
+export declare function validateZatcaInvoice(data: ZatcaInvoiceData): ZatcaValidationResult
+
+/** ينسّق مبلغاً بفاصلة نقطية وبمنزلتين. */
+export declare function toZatcaAmount(value: number | string): string

package/src/index.js

@@ -0,0 +1,532 @@
+/**
+ * zatca-qr — رمز الاستجابة السريعة لفواتير هيئة الزكاة والضريبة والجمارك (ZATCA).
+ * ---------------------------------------------------------------------------
+ * مكتبة بلا أي تبعية، تُنتج وتقرأ حمولة رمز QR كما تفرضها الهيئة على كل فاتورة
+ * ضريبية في المملكة: تسلسل TLV ثم ترميز Base64.
+ *
+ * Zero-dependency ZATCA (Saudi FATOORA) e-invoice QR payloads.
+ * Encodes and decodes the TLV sequence mandated on every tax invoice in Saudi
+ * Arabia (Phase 1, with optional Phase 2 integration fields).
+ *
+ * Works in: Node 18+, browsers, Cloudflare Workers, Deno, Bun. ESM only.
+ */
+
+/**
+ * أرقام العلامات (Tags) كما تعرّفها مواصفة الهيئة.
+ * 1..5 إلزامية في المرحلة الأولى، و6..9 تُضاف في مرحلة الربط.
+ */
+export const ZATCA_TAGS = Object.freeze({
+  SELLER_NAME: 1,
+  VAT_NUMBER: 2,
+  TIMESTAMP: 3,
+  TOTAL_WITH_VAT: 4,
+  VAT_TOTAL: 5,
+  INVOICE_HASH: 6,
+  SIGNATURE: 7,
+  PUBLIC_KEY: 8,
+  STAMP: 9,
+})
+
+/** أسماء الحقول المقابلة لكل علامة (تُستخدم في فك الترميز). */
+export const ZATCA_TAG_NAMES = Object.freeze({
+  1: 'sellerName',
+  2: 'vatNumber',
+  3: 'timestamp',
+  4: 'totalWithVat',
+  5: 'vatTotal',
+  6: 'invoiceHash',
+  7: 'signature',
+  8: 'publicKey',
+  9: 'stamp',
+})
+
+/** أقصى طول لقيمة واحدة: بايت واحد للطول يعني 255 بايتاً كحد أعلى. */
+const MAX_FIELD_BYTES = 255
+
+/** الحقول الخمسة الإلزامية بترتيب علاماتها. */
+const REQUIRED_FIELDS = Object.freeze([
+  ['sellerName', ZATCA_TAGS.SELLER_NAME],
+  ['vatNumber', ZATCA_TAGS.VAT_NUMBER],
+  ['timestamp', ZATCA_TAGS.TIMESTAMP],
+  ['totalWithVat', ZATCA_TAGS.TOTAL_WITH_VAT],
+  ['vatTotal', ZATCA_TAGS.VAT_TOTAL],
+])
+
+/** حقول مرحلة الربط: الثلاثة الأولى تُضاف معاً أو لا تُضاف إطلاقاً. */
+const PHASE_2_REQUIRED_FIELDS = Object.freeze([
+  ['invoiceHash', ZATCA_TAGS.INVOICE_HASH],
+  ['signature', ZATCA_TAGS.SIGNATURE],
+  ['publicKey', ZATCA_TAGS.PUBLIC_KEY],
+])
+
+/** ختم الهيئة يُضاف بعد التخليص فقط، فيأتي وحده من غير إخوته. */
+const PHASE_2_OPTIONAL_FIELDS = Object.freeze([['stamp', ZATCA_TAGS.STAMP]])
+
+/** الرقم الضريبي السعودي: 15 رقماً يبدأ بـ3 وينتهي بـ3. */
+const VAT_NUMBER_PATTERN = /^3\d{13}3$/
+
+/** طابع زمني ISO 8601 مع منطقة زمنية صريحة (Z أو +03:00). */
+const ISO_WITH_ZONE_PATTERN =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/
+
+/** رقم عشري بفاصلة نقطية، بلا فواصل آلاف وبلا فاصلة عشرية عربية. */
+const PLAIN_DECIMAL_PATTERN = /^-?\d+(?:\.\d+)?$/
+
+/** حجم يُنبّه عنده: رموز QR الطويلة تفشل مع بعض الماسحات الميدانية. */
+const PAYLOAD_SIZE_WARNING_BYTES = 1000
+
+const textEncoder = new TextEncoder()
+const textDecoder = new TextDecoder()
+
+/** خطأ المكتبة الوحيد، يحمل رمزاً برمجياً لتفرّع المعالجة في تطبيقك. */
+export class ZatcaQrError extends Error {
+  /**
+   * @param {string} message وصف إنجليزي واضح للسبب.
+   * @param {string} [code] رمز الخطأ (FIELD_TOO_LONG، PHASE2_INCOMPLETE، ...).
+   */
+  constructor(message, code = 'ZATCA_QR_ERROR') {
+    super(message)
+    this.name = 'ZatcaQrError'
+    this.code = code
+  }
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                 أدوات داخلية                                */
+/* -------------------------------------------------------------------------- */
+
+/** الحقول التي يُقبل فيها الرقم مباشرة: المبالغ فقط. */
+const NUMERIC_FIELDS = new Set(['totalWithVat', 'vatTotal'])
+
+/**
+ * يحوّل قيمة حقل إلى النص الذي سيُشفَّر.
+ * التواريخ تتحول إلى ISO 8601 بـ UTC، وهو ما تقبله الهيئة دائماً.
+ * الأرقام تُقبل في حقلي المبالغ فقط، حتى لا يتحول اسم بائع بالخطأ إلى رقم.
+ */
+function toFieldText(field, value) {
+  if (value === undefined || value === null || value === '') {
+    throw new ZatcaQrError(`Field "${field}" is required.`, 'MISSING_FIELD')
+  }
+  if (value instanceof Date) {
+    if (Number.isNaN(value.getTime())) {
+      throw new ZatcaQrError(`Field "${field}" is an invalid Date.`, 'INVALID_FIELD')
+    }
+    return value.toISOString()
+  }
+  if (typeof value === 'number') {
+    if (!NUMERIC_FIELDS.has(field)) {
+      throw new ZatcaQrError(
+        `Field "${field}" must be a string, not a number.`,
+        'INVALID_FIELD',
+      )
+    }
+    if (!Number.isFinite(value)) {
+      throw new ZatcaQrError(
+        `Field "${field}" must be a finite number.`,
+        'INVALID_FIELD',
+      )
+    }
+    return String(value)
+  }
+  if (typeof value === 'string') return value
+  throw new ZatcaQrError(
+    `Field "${field}" must be a string${NUMERIC_FIELDS.has(field) ? ', number' : ''} or Date (got ${typeof value}).`,
+    'INVALID_FIELD',
+  )
+}
+
+/**
+ * يرمّز حقلاً واحداً بصيغة TLV: [Tag, Length, ...Value].
+ * الطول يُحسب بالبايتات لا بالأحرف — وهذا موضع الخطأ الأشهر مع النص العربي.
+ */
+function encodeField(tag, text) {
+  const valueBytes = textEncoder.encode(text)
+  if (valueBytes.length > MAX_FIELD_BYTES) {
+    throw new ZatcaQrError(
+      `Tag ${tag} is ${valueBytes.length} UTF-8 bytes long, but the TLV length byte allows at most ${MAX_FIELD_BYTES}.`,
+      'FIELD_TOO_LONG',
+    )
+  }
+  const field = new Uint8Array(2 + valueBytes.length)
+  field[0] = tag
+  field[1] = valueBytes.length
+  field.set(valueBytes, 2)
+  return field
+}
+
+/** يحوّل بايتات إلى Base64 (يعمل في المتصفح وNode معاً). */
+function bytesToBase64(bytes) {
+  let binary = ''
+  const chunkSize = 0x8000 // تقسيم لتفادي تجاوز حد وسائط String.fromCharCode
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize))
+  }
+  return btoa(binary)
+}
+
+/** يقرأ Base64 إلى بايتات، ويتسامح مع Base64 الآمن للروابط وبعض المسافات. */
+function base64ToBytes(base64) {
+  if (typeof base64 !== 'string') {
+    throw new ZatcaQrError('Payload must be a Base64 string.', 'INVALID_BASE64')
+  }
+  // نتسامح مع Base64 الآمن للروابط ومع الحشو المحذوف: بعض الماسحات تحذفهما.
+  const compact = base64
+    .replace(/\s+/g, '')
+    .replace(/-/g, '+')
+    .replace(/_/g, '/')
+  const body = compact.replace(/=+$/, '')
+  if (body.length === 0) {
+    throw new ZatcaQrError('Payload is empty.', 'INVALID_BASE64')
+  }
+  if (!/^[A-Za-z0-9+/]+$/.test(body)) {
+    throw new ZatcaQrError('Payload contains characters outside Base64.', 'INVALID_BASE64')
+  }
+  if (body.length % 4 === 1) {
+    throw new ZatcaQrError('Payload is not valid Base64 (impossible length).', 'INVALID_BASE64')
+  }
+  const normalized = body.padEnd(Math.ceil(body.length / 4) * 4, '=')
+  const binary = atob(normalized)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+/** يجمع حقول الفاتورة في قائمة [tag, text] مرتّبة تصاعدياً بالعلامة. */
+function collectFields(data) {
+  if (data === null || typeof data !== 'object') {
+    throw new ZatcaQrError('Invoice data must be an object.', 'INVALID_FIELD')
+  }
+
+  const entries = REQUIRED_FIELDS.map(([field, tag]) => [tag, toFieldText(field, data[field])])
+
+  const hasPhase2 = PHASE_2_REQUIRED_FIELDS.some(
+    ([field]) => data[field] !== undefined && data[field] !== null,
+  )
+  // ختم الهيئة بلا إخوته خطأ بنيوي: لا معنى لختم على فاتورة غير موقّعة.
+  const hasStampAlone =
+    data.stamp !== undefined && data.stamp !== null && !hasPhase2
+
+  if (hasStampAlone) {
+    throw new ZatcaQrError(
+      'Field "stamp" requires "invoiceHash", "signature" and "publicKey" as well.',
+      'PHASE2_INCOMPLETE',
+    )
+  }
+
+  if (hasPhase2) {
+    const missing = PHASE_2_REQUIRED_FIELDS.filter(
+      ([field]) => data[field] === undefined || data[field] === null || data[field] === '',
+    )
+    if (missing.length > 0) {
+      throw new ZatcaQrError(
+        `Phase 2 fields must be provided together; missing: ${missing
+          .map(([field]) => field)
+          .join(', ')}.`,
+        'PHASE2_INCOMPLETE',
+      )
+    }
+    for (const [field, tag] of PHASE_2_REQUIRED_FIELDS) {
+      entries.push([tag, toFieldText(field, data[field])])
+    }
+    if (data.stamp !== undefined && data.stamp !== null && data.stamp !== '') {
+      for (const [field, tag] of PHASE_2_OPTIONAL_FIELDS) {
+        entries.push([tag, toFieldText(field, data[field])])
+      }
+    }
+  }
+
+  return entries.sort((a, b) => a[0] - b[0])
+}
+
+/* -------------------------------------------------------------------------- */
+/*                              الواجهة العامة                                 */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * يبني بايتات TLV الخام من بيانات الفاتورة.
+ * تُفيد في الاختبارات وفي الفحص البايتي عند رفض الرمز من نظام محاسبي.
+ *
+ * @param {import('./index.d.ts').ZatcaInvoiceData} data
+ * @returns {Uint8Array}
+ */
+export function buildTlvBytes(data) {
+  const parts = collectFields(data).map(([tag, text]) => encodeField(tag, text))
+  const total = parts.reduce((sum, part) => sum + part.length, 0)
+  const buffer = new Uint8Array(total)
+  let offset = 0
+  for (const part of parts) {
+    buffer.set(part, offset)
+    offset += part.length
+  }
+  return buffer
+}
+
+/**
+ * الدالة الرئيسية: يحوّل بيانات الفاتورة إلى نص Base64 يُمرَّر لمولّد QR.
+ *
+ * @param {import('./index.d.ts').ZatcaInvoiceData} data
+ * @param {{ strict?: boolean }} [options] مع `strict` تُرفض الفاتورة إن خالفت
+ *   المواصفة (رقم ضريبي غير صحيح، طابع زمني بلا منطقة، فاصلة عشرية عربية...).
+ * @returns {string} حمولة Base64 جاهزة لرمز QR.
+ */
+export function encodeZatcaTlv(data, options = {}) {
+  if (options.strict === true) {
+    const { errors } = validateZatcaInvoice(data)
+    if (errors.length > 0) {
+      throw new ZatcaQrError(errors[0].message, errors[0].code)
+    }
+  }
+  return bytesToBase64(buildTlvBytes(data))
+}
+
+/**
+ * يفكّ ترميز حمولة Base64 إلى بايتات TLV ثم إلى حقول مقروءة.
+ * يتسامح مع العلامات غير المعروفة (يضعها في `unknown`) بدل أن يرفض الرمز.
+ *
+ * @param {string} base64 حمولة رمز QR.
+ * @returns {import('./index.d.ts').DecodedZatcaQr}
+ */
+export function decodeZatcaTlv(base64) {
+  const bytes = base64ToBytes(base64)
+  const fields = []
+  const unknown = []
+  const seen = new Set()
+  const warnings = []
+
+  let offset = 0
+  while (offset < bytes.length) {
+    if (offset + 2 > bytes.length) {
+      throw new ZatcaQrError(
+        `Truncated TLV: found ${bytes.length - offset} trailing byte(s) where a tag and length were expected.`,
+        'TRUNCATED_TLV',
+      )
+    }
+    const tag = bytes[offset]
+    const length = bytes[offset + 1]
+    const start = offset + 2
+    const end = start + length
+
+    if (end > bytes.length) {
+      throw new ZatcaQrError(
+        `Truncated TLV: tag ${tag} declares ${length} bytes but only ${bytes.length - start} remain.`,
+        'TRUNCATED_TLV',
+      )
+    }
+    if (tag === 0) {
+      throw new ZatcaQrError('Invalid TLV: tag 0 is not defined.', 'INVALID_TLV')
+    }
+    if (seen.has(tag)) {
+      warnings.push({
+        code: 'DUPLICATE_TAG',
+        message: `Tag ${tag} appears more than once; validators may reject the payload.`,
+      })
+    }
+    seen.add(tag)
+
+    const value = textDecoder.decode(bytes.subarray(start, end))
+    const name = ZATCA_TAG_NAMES[tag]
+    const field = { tag, name: name ?? null, value, byteLength: length }
+    if (name) fields.push(field)
+    else unknown.push(field)
+
+    offset = end
+  }
+
+  const data = {}
+  for (const field of fields) data[field.name] = field.value
+
+  const isPhase2 = [6, 7, 8].every((tag) => seen.has(tag))
+  for (const tag of [1, 2, 3, 4, 5]) {
+    if (!seen.has(tag)) {
+      warnings.push({
+        code: 'MISSING_REQUIRED_TAG',
+        message: `Tag ${tag} (${ZATCA_TAG_NAMES[tag]}) is missing; the payload is not a valid Phase 1 QR.`,
+      })
+    }
+  }
+  if (unknown.length > 0) {
+    warnings.push({
+      code: 'UNKNOWN_TAGS',
+      message: `Payload contains ${unknown.length} tag(s) outside the specification: ${unknown
+        .map((field) => field.tag)
+        .join(', ')}.`,
+    })
+  }
+
+  return { phase: isPhase2 ? 2 : 1, fields, unknown, data, warnings, byteLength: bytes.length }
+}
+
+/**
+ * يفحص البيانات مقابل المواصفة قبل الإصدار، ويفصل الأخطاء عن التنبيهات.
+ * الأخطاء تمنع الفاتورة من القبول، والتنبيهات تُصدر لكنها تستحق مراجعة.
+ *
+ * @param {import('./index.d.ts').ZatcaInvoiceData} data
+ * @returns {import('./index.d.ts').ZatcaValidationResult}
+ */
+export function validateZatcaInvoice(data) {
+  /** @type {import('./index.d.ts').ZatcaValidationIssue[]} */
+  const errors = []
+  /** @type {import('./index.d.ts').ZatcaValidationIssue[]} */
+  const warnings = []
+
+  if (data === null || typeof data !== 'object') {
+    errors.push({ code: 'INVALID_FIELD', field: null, message: 'Invoice data must be an object.' })
+    return { valid: false, errors, warnings }
+  }
+
+  for (const [field] of REQUIRED_FIELDS) {
+    const value = data[field]
+    if (value === undefined || value === null || value === '') {
+      errors.push({ code: 'MISSING_FIELD', field, message: `Field "${field}" is required.` })
+      continue
+    }
+    // الطول بالبايتات: 130 حرفاً عربياً = 260 بايتاً، وهذا يتجاوز حد TLV.
+    try {
+      const bytes = textEncoder.encode(toFieldText(field, value)).length
+      if (bytes > MAX_FIELD_BYTES) {
+        errors.push({
+          code: 'FIELD_TOO_LONG',
+          field,
+          message: `Field "${field}" is ${bytes} UTF-8 bytes long; the TLV limit is ${MAX_FIELD_BYTES}.`,
+        })
+      }
+    } catch (error) {
+      errors.push({ code: error.code ?? 'INVALID_FIELD', field, message: error.message })
+    }
+  }
+
+  const vatNumber = data.vatNumber
+  if (typeof vatNumber === 'string' && vatNumber !== '' && !VAT_NUMBER_PATTERN.test(vatNumber)) {
+    errors.push({
+      code: 'VAT_NUMBER_FORMAT',
+      field: 'vatNumber',
+      message:
+        'VAT number must be exactly 15 digits, starting and ending with 3 (e.g. 300000000000003).',
+    })
+  }
+
+  const timestamp = data.timestamp
+  if (timestamp instanceof Date) {
+    // toISOString يرمي استثناءً على تاريخ غير صحيح، لذلك نفحصه قبل الاستدعاء
+    if (Number.isNaN(timestamp.getTime())) {
+      errors.push({
+        code: 'TIMESTAMP_FORMAT',
+        field: 'timestamp',
+        message: 'Timestamp Date is invalid.',
+      })
+    }
+  } else if (
+    typeof timestamp === 'string' &&
+    timestamp !== '' &&
+    !ISO_WITH_ZONE_PATTERN.test(timestamp)
+  ) {
+    errors.push({
+      code: 'TIMESTAMP_FORMAT',
+      field: 'timestamp',
+      message:
+        'Timestamp must be ISO 8601 with an explicit time zone, e.g. 2026-04-18T10:30:00Z or 2026-04-18T13:30:00+03:00.',
+    })
+  }
+
+  for (const field of ['totalWithVat', 'vatTotal']) {
+    const value = data[field]
+    if (value === undefined || value === null || value === '') continue
+    if (typeof value !== 'string' && typeof value !== 'number') {
+      errors.push({
+        code: 'AMOUNT_FORMAT',
+        field,
+        message: `Field "${field}" must be a decimal amount as a string or a number (got ${
+          Array.isArray(value) ? 'array' : typeof value
+        }).`,
+      })
+      continue
+    }
+    const text = String(value).trim()
+    if (!PLAIN_DECIMAL_PATTERN.test(text)) {
+      errors.push({
+        code: 'AMOUNT_FORMAT',
+        field,
+        message: `Field "${field}" must use a dot decimal separator with no thousands separators (got "${text}").`,
+      })
+      continue
+    }
+    const decimals = text.includes('.') ? text.split('.')[1].length : 0
+    if (decimals !== 2) {
+      warnings.push({
+        code: 'AMOUNT_PRECISION',
+        field,
+        message: `Field "${field}" has ${decimals} decimal place(s); the specification examples use exactly 2.`,
+      })
+    }
+  }
+
+  const total = Number(data.totalWithVat)
+  const vat = Number(data.vatTotal)
+  if (Number.isFinite(total) && Number.isFinite(vat) && vat > total) {
+    warnings.push({
+      code: 'VAT_EXCEEDS_TOTAL',
+      field: 'vatTotal',
+      message: 'VAT amount is greater than the invoice total including VAT.',
+    })
+  }
+
+  const phase2Missing = PHASE_2_REQUIRED_FIELDS.filter(
+    ([field]) => data[field] === undefined || data[field] === null || data[field] === '',
+  )
+  const hasAnyPhase2 = PHASE_2_REQUIRED_FIELDS.some(
+    ([field]) => data[field] !== undefined && data[field] !== null && data[field] !== '',
+  )
+  if (hasAnyPhase2 && phase2Missing.length > 0) {
+    errors.push({
+      code: 'PHASE2_INCOMPLETE',
+      field: phase2Missing[0][0],
+      message: `Phase 2 fields must be provided together; missing: ${phase2Missing
+        .map(([field]) => field)
+        .join(', ')}.`,
+    })
+  }
+  if (
+    (data.stamp !== undefined && data.stamp !== null && data.stamp !== '') &&
+    phase2Missing.length > 0
+  ) {
+    errors.push({
+      code: 'PHASE2_INCOMPLETE',
+      field: 'stamp',
+      message: 'Field "stamp" requires "invoiceHash", "signature" and "publicKey" as well.',
+    })
+  }
+
+  if (errors.length === 0) {
+    const size = buildTlvBytes(data).length
+    if (size > PAYLOAD_SIZE_WARNING_BYTES) {
+      warnings.push({
+        code: 'PAYLOAD_TOO_LARGE',
+        field: null,
+        message: `TLV payload is ${size} bytes; long payloads can fail on field scanners.`,
+      })
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings }
+}
+
+/**
+ * ينسّق مبلغاً بالصيغة التي تتوقعها الهيئة: فاصلة نقطية وبمنزلتين.
+ * الأرقام تُقرَّب إلى منزلتين، والنصوص تُترك كما هي بعد إزالة الفراغات.
+ *
+ * @param {number|string} value
+ * @returns {string}
+ */
+export function toZatcaAmount(value) {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new ZatcaQrError('Amount must be a finite number.', 'AMOUNT_FORMAT')
+    }
+    return value.toFixed(2)
+  }
+  if (typeof value === 'string') return value.trim()
+  throw new ZatcaQrError(
+    `Amount must be a number or a string (got ${typeof value}).`,
+    'AMOUNT_FORMAT',
+  )
+}