{"_id":"@dokhna-tech/zatca","_rev":"6-5243f5ce1f607db089368dbbbcedcd31","name":"@dokhna-tech/zatca","dist-tags":{"latest":"4.0.1"},"versions":{"2.0.0":{"name":"@dokhna-tech/zatca","version":"2.0.0","keywords":["zatca","saudi-arabia","e-invoicing","phase-2","ubl","fatoora"],"license":"BUSL-1.1","_id":"@dokhna-tech/zatca@2.0.0","maintainers":[{"name":"ameensom","email":"amin4mail@yahoo.com"}],"dist":{"shasum":"8c9ad6f8b313cba45ac49c0e724dc413761557bb","tarball":"https://registry.npmjs.org/@dokhna-tech/zatca/-/zatca-2.0.0.tgz","fileCount":19,"integrity":"sha512-vILPI/xcM2rBm7drZI0QI/oTBn9TDJro6ePkqojV/XrU3ZqwCFUwJDBTQMlAYrhPl5PuFelD9oAo7hbuwXKo5A==","signatures":[{"sig":"MEUCIQC1klxyYtHkaa1bfuUO3Bw/6vmv0Ib3yZspCTBZI8VxEgIgYci/wbb7uq5sNe1ZSBNkT9zNlkkKwrQBL/nKspPJS20=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2047303},"main":"./dist/index.cjs","type":"module","_from":"file:dokhna-tech-zatca-2.0.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./test-helpers":{"types":"./dist/test-helpers.d.ts","import":"./dist/test-helpers.js","require":"./dist/test-helpers.cjs"}},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"ameensom","email":"amin4mail@yahoo.com"},"_resolved":"/private/var/folders/14/y1m00gyx24b054fzqk4wb_2c0000gn/T/d85eb94df118eafcdc74506287ac838b/dokhna-tech-zatca-2.0.0.tgz","_integrity":"sha512-vILPI/xcM2rBm7drZI0QI/oTBn9TDJro6ePkqojV/XrU3ZqwCFUwJDBTQMlAYrhPl5PuFelD9oAo7hbuwXKo5A==","_npmVersion":"11.6.4","description":"Saudi Arabia ZATCA Phase 2 e-invoicing core library — XML build, signing, hashing, QR, and ZATCA API client.","directories":{},"_nodeVersion":"22.18.0","dependencies":{"zod":"^3.25.76","debug":"^4.3.7","xmldsigjs":"^2.6.1","@fidm/x509":"^1.2.1","@xmldom/xmldom":"^0.8.10","fast-xml-parser":"^5.7.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.6.0","@types/debug":"^4.1.12"},"peerDependencies":{"vitest":"^2.0.0 || ^3.0.0"},"peerDependenciesMeta":{"vitest":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/zatca_2.0.0_1778762264137_0.16942155773740142","host":"s3://npm-registry-packages-npm-production"}},"2.0.2":{"name":"@dokhna-tech/zatca","version":"2.0.2","keywords":["zatca","saudi-arabia","e-invoicing","phase-2","ubl","fatoora"],"license":"BUSL-1.1","_id":"@dokhna-tech/zatca@2.0.2","maintainers":[{"name":"ameensom","email":"amin4mail@yahoo.com"}],"dist":{"shasum":"ce06d502a80ea01d4037318bf87fbf1be3802084","tarball":"https://registry.npmjs.org/@dokhna-tech/zatca/-/zatca-2.0.2.tgz","fileCount":19,"integrity":"sha512-06QPMxK+z4SLYDzH0ZUIvw0yzJ/eOl6H3nA20iGF9YJUvWwYQVlqqIJe90etVEZAG5XOll2MTHKSlCBW6e4vMg==","signatures":[{"sig":"MEUCIQDS53a/WVz2hxkQGN13Y5E144+5s8GCMhm5h3sr9h3pTAIgPbWAw6qGYEDcNsgqjyp0S3Gzd9Ei5/yNvhx8s/FI0tM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2046616},"main":"./dist/index.cjs","type":"module","_from":"file:dokhna-tech-zatca-2.0.2.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./test-helpers":{"types":"./dist/test-helpers.d.ts","import":"./dist/test-helpers.js","require":"./dist/test-helpers.cjs"}},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"ameensom","email":"amin4mail@yahoo.com"},"_resolved":"/tmp/5e1b1270c28bfeafe567790ff513c499/dokhna-tech-zatca-2.0.2.tgz","_integrity":"sha512-06QPMxK+z4SLYDzH0ZUIvw0yzJ/eOl6H3nA20iGF9YJUvWwYQVlqqIJe90etVEZAG5XOll2MTHKSlCBW6e4vMg==","_npmVersion":"10.9.7","description":"Saudi Arabia ZATCA Phase 2 e-invoicing core library — XML build, signing, hashing, QR, and ZATCA API client.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.25.76","debug":"^4.3.7","xmldsigjs":"^2.6.1","@fidm/x509":"^1.2.1","@xmldom/xmldom":"^0.8.10","fast-xml-parser":"^5.7.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.6.0","@types/debug":"^4.1.12"},"peerDependencies":{"vitest":"^2.0.0 || ^3.0.0"},"peerDependenciesMeta":{"vitest":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/zatca_2.0.2_1778766203447_0.8450155584598564","host":"s3://npm-registry-packages-npm-production"}},"2.0.3":{"name":"@dokhna-tech/zatca","version":"2.0.3","keywords":["zatca","saudi-arabia","e-invoicing","phase-2","ubl","fatoora"],"license":"BUSL-1.1","_id":"@dokhna-tech/zatca@2.0.3","maintainers":[{"name":"ameensom","email":"amin4mail@yahoo.com"}],"homepage":"https://github.com/dokhna/dokhna-tech-zatca#readme","bugs":{"url":"https://github.com/dokhna/dokhna-tech-zatca/issues"},"dist":{"shasum":"39e9014b4987a47e020c5ad74b9df05bd6dc5760","tarball":"https://registry.npmjs.org/@dokhna-tech/zatca/-/zatca-2.0.3.tgz","fileCount":19,"integrity":"sha512-/PhFXcyCO7smExOSubnCdA4hiw0rH1xYqQnQKjW6+UKiypBYGcrLLFLGiDzUQYxkmPeVnam5lCblnMTOTs8SXA==","signatures":[{"sig":"MEUCIQDk1fTzySOUyfvZK5liJExyPiXkzBv0M1xChwCglW80ZgIgCQKA82lcOashGzra3k5LdVnhpJ1M08keAZzFXfKUef8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2048479},"main":"./dist/index.cjs","type":"module","_from":"file:dokhna-tech-zatca-2.0.3.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./test-helpers":{"types":"./dist/test-helpers.d.ts","import":"./dist/test-helpers.js","require":"./dist/test-helpers.cjs"}},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"ameensom","email":"amin4mail@yahoo.com"},"_resolved":"/tmp/aecc5932de219b9c4a561c24010f7e97/dokhna-tech-zatca-2.0.3.tgz","_integrity":"sha512-/PhFXcyCO7smExOSubnCdA4hiw0rH1xYqQnQKjW6+UKiypBYGcrLLFLGiDzUQYxkmPeVnam5lCblnMTOTs8SXA==","repository":{"url":"git+https://github.com/dokhna/dokhna-tech-zatca.git","type":"git","directory":"packages/core"},"_npmVersion":"10.9.7","description":"Saudi Arabia ZATCA Phase 2 e-invoicing core library — XML build, signing, hashing, QR, and ZATCA API client.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.25.76","debug":"^4.3.7","xmldsigjs":"^2.6.1","@fidm/x509":"^1.2.1","@xmldom/xmldom":"^0.8.10","fast-xml-parser":"^5.7.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.6.0","@types/debug":"^4.1.12"},"peerDependencies":{"vitest":"^2.0.0 || ^3.0.0"},"peerDependenciesMeta":{"vitest":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/zatca_2.0.3_1778781332687_0.20933065610337875","host":"s3://npm-registry-packages-npm-production"}},"2.0.4":{"name":"@dokhna-tech/zatca","version":"2.0.4","keywords":["zatca","saudi-arabia","e-invoicing","phase-2","ubl","fatoora"],"license":"BUSL-1.1","_id":"@dokhna-tech/zatca@2.0.4","maintainers":[{"name":"ameensom","email":"amin4mail@yahoo.com"}],"homepage":"https://github.com/dokhna/dokhna-tech-zatca#readme","bugs":{"url":"https://github.com/dokhna/dokhna-tech-zatca/issues"},"dist":{"shasum":"8ee20859f11f1244dd291dbc31add8e3c2ffdc88","tarball":"https://registry.npmjs.org/@dokhna-tech/zatca/-/zatca-2.0.4.tgz","fileCount":19,"integrity":"sha512-BagLdWqXuD+3cGl9l2PBPs9m27yeOVR/Fyfk6fS3BNPo2RUXesj869DbAFoAfS67DoYy+pgaq128dwKY8/Bcug==","signatures":[{"sig":"MEQCIA8Q9o1ODAQZYQLspMwYr4ED+PeKEVBR6kuXR6Yr44MrAiA60YT3UeicBPunGHeOjWne2e1ZncPcVRWKAUM2sSDKyg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2049936},"main":"./dist/index.cjs","type":"module","_from":"file:dokhna-tech-zatca-2.0.4.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.19.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./test-helpers":{"types":"./dist/test-helpers.d.ts","import":"./dist/test-helpers.js","require":"./dist/test-helpers.cjs"}},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"ameensom","email":"amin4mail@yahoo.com"},"_resolved":"/tmp/ca516683d244694dd0fde42bd3e66ebc/dokhna-tech-zatca-2.0.4.tgz","_integrity":"sha512-BagLdWqXuD+3cGl9l2PBPs9m27yeOVR/Fyfk6fS3BNPo2RUXesj869DbAFoAfS67DoYy+pgaq128dwKY8/Bcug==","repository":{"url":"git+https://github.com/dokhna/dokhna-tech-zatca.git","type":"git","directory":"packages/core"},"_npmVersion":"10.9.7","description":"Saudi Arabia ZATCA Phase 2 e-invoicing core library — XML build, signing, hashing, QR, and ZATCA API client.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.25.76","debug":"^4.3.7","xmldsigjs":"^2.6.1","@fidm/x509":"^1.2.1","@xmldom/xmldom":"^0.8.10","fast-xml-parser":"^5.7.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.6.0","@types/node":"^20.19.0","@types/debug":"^4.1.12"},"peerDependencies":{"vitest":"^2.0.0 || ^3.0.0 || ^4.0.0"},"peerDependenciesMeta":{"vitest":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/zatca_2.0.4_1778842975818_0.6963416526722381","host":"s3://npm-registry-packages-npm-production"}},"4.0.0":{"name":"@dokhna-tech/zatca","version":"4.0.0","keywords":["zatca","saudi-arabia","e-invoicing","phase-2","ubl","fatoora"],"license":"BUSL-1.1","_id":"@dokhna-tech/zatca@4.0.0","maintainers":[{"name":"ameensom","email":"amin4mail@yahoo.com"}],"homepage":"https://github.com/dokhna/dokhna-tech-zatca#readme","bugs":{"url":"https://github.com/dokhna/dokhna-tech-zatca/issues"},"dist":{"shasum":"0c3ce5bb64b64a42cb41f649e84876d4422c0e84","tarball":"https://registry.npmjs.org/@dokhna-tech/zatca/-/zatca-4.0.0.tgz","fileCount":19,"integrity":"sha512-3RciAhtLhKC3HTBsYnX1BNHddw+iWWD6MxUzssKrZBJC0Bgtg28G1D80OKvkLhbRss+ssCpVFlYfYkH3Vf+WUA==","signatures":[{"sig":"MEYCIQC7uvcLtoIUGDYzqA1duJPiQZ0ohflV9cz2kkjxgoqoUAIhAN8gd1OZvOcfTmeEW6UhCY/Vl1wzgeoWbdwDmkHw2Nzv","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2067799},"main":"./dist/index.cjs","type":"module","_from":"file:dokhna-tech-zatca-4.0.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.19.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./test-helpers":{"types":"./dist/test-helpers.d.ts","import":"./dist/test-helpers.js","require":"./dist/test-helpers.cjs"}},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"ameensom","email":"amin4mail@yahoo.com"},"_resolved":"/tmp/5bda1c09d84d0e44e7ceddbc85a0d617/dokhna-tech-zatca-4.0.0.tgz","_integrity":"sha512-3RciAhtLhKC3HTBsYnX1BNHddw+iWWD6MxUzssKrZBJC0Bgtg28G1D80OKvkLhbRss+ssCpVFlYfYkH3Vf+WUA==","repository":{"url":"git+https://github.com/dokhna/dokhna-tech-zatca.git","type":"git","directory":"packages/core"},"_npmVersion":"10.9.7","description":"Saudi Arabia ZATCA Phase 2 e-invoicing core library — XML build, signing, hashing, QR, and ZATCA API client.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.25.76","debug":"^4.3.7","xmldsigjs":"^2.6.1","@fidm/x509":"^1.2.1","@xmldom/xmldom":"^0.8.10","fast-xml-parser":"^5.7.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.6.0","@types/node":"^20.19.0","@types/debug":"^4.1.12"},"peerDependencies":{"vitest":"^2.0.0 || ^3.0.0 || ^4.0.0"},"peerDependenciesMeta":{"vitest":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/zatca_4.0.0_1779089788069_0.6701390324804912","host":"s3://npm-registry-packages-npm-production"}},"4.0.1":{"name":"@dokhna-tech/zatca","version":"4.0.1","description":"Saudi Arabia ZATCA Phase 2 e-invoicing core library — XML build, signing, hashing, QR, and ZATCA API client.","license":"BUSL-1.1","repository":{"type":"git","url":"git+https://github.com/dokhna/dokhna-tech-zatca.git","directory":"packages/core"},"homepage":"https://github.com/dokhna/dokhna-tech-zatca#readme","bugs":{"url":"https://github.com/dokhna/dokhna-tech-zatca/issues"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./test-helpers":{"types":"./dist/test-helpers.d.ts","import":"./dist/test-helpers.js","require":"./dist/test-helpers.cjs"}},"engines":{"node":">=20.19.0"},"publishConfig":{"access":"public"},"keywords":["zatca","saudi-arabia","e-invoicing","phase-2","ubl","fatoora"],"dependencies":{"@fidm/x509":"^1.2.1","@xmldom/xmldom":"^0.8.10","debug":"^4.3.7","fast-xml-parser":"^5.7.0","xmldsigjs":"^2.6.1","zod":"^3.25.76"},"devDependencies":{"@types/debug":"^4.1.12","@types/node":"^20.19.0","msw":"^2.6.0"},"peerDependencies":{"vitest":"^2.0.0 || ^3.0.0 || ^4.0.0"},"peerDependenciesMeta":{"vitest":{"optional":true}},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"vitest run","test:coverage":"vitest run --coverage"},"_id":"@dokhna-tech/zatca@4.0.1","_integrity":"sha512-znAiXdjlpU6PHYJ1fudbpZFWiWhwVcXXHL159ftvF2hLUR7IvOS4wC8mGw2TTAwhCHU0hl/gfEKVwZLWN+RWCg==","_resolved":"/tmp/ac8da71292f050940acd987db371ef46/dokhna-tech-zatca-4.0.1.tgz","_from":"file:dokhna-tech-zatca-4.0.1.tgz","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-znAiXdjlpU6PHYJ1fudbpZFWiWhwVcXXHL159ftvF2hLUR7IvOS4wC8mGw2TTAwhCHU0hl/gfEKVwZLWN+RWCg==","shasum":"eeb7799776f0300cb2fc7221dd2785806c02cace","tarball":"https://registry.npmjs.org/@dokhna-tech/zatca/-/zatca-4.0.1.tgz","fileCount":19,"unpackedSize":2077520,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCgwd/eN9jWzBwipIp7upJeCWJJ5EnvbnuKgtqVBeTSnwIhAL1jY0peVggv0RRBQna32XnO4qt3PHEjfKHnMXDtdUz7"}]},"_npmUser":{"name":"ameensom","email":"amin4mail@yahoo.com"},"directories":{},"maintainers":[{"name":"ameensom","email":"amin4mail@yahoo.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/zatca_4.0.1_1781527870955_0.3837831625134829"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-14T12:37:44.038Z","modified":"2026-06-15T12:51:11.290Z","2.0.0":"2026-05-14T12:37:44.332Z","2.0.2":"2026-05-14T13:43:23.667Z","2.0.3":"2026-05-14T17:55:32.867Z","2.0.4":"2026-05-15T11:02:55.992Z","4.0.0":"2026-05-18T07:36:28.243Z","4.0.1":"2026-06-15T12:51:11.126Z"},"bugs":{"url":"https://github.com/dokhna/dokhna-tech-zatca/issues"},"license":"BUSL-1.1","homepage":"https://github.com/dokhna/dokhna-tech-zatca#readme","keywords":["zatca","saudi-arabia","e-invoicing","phase-2","ubl","fatoora"],"repository":{"type":"git","url":"git+https://github.com/dokhna/dokhna-tech-zatca.git","directory":"packages/core"},"description":"Saudi Arabia ZATCA Phase 2 e-invoicing core library — XML build, signing, hashing, QR, and ZATCA API client.","maintainers":[{"name":"ameensom","email":"amin4mail@yahoo.com"}],"readme":"# @dokhna-tech/zatca\n\n[![CI](https://github.com/dokhna/dokhna-tech-zatca/actions/workflows/ci.yml/badge.svg)](https://github.com/dokhna/dokhna-tech-zatca/actions)\n[![npm](https://img.shields.io/npm/v/@dokhna-tech/zatca.svg)](https://www.npmjs.com/package/@dokhna-tech/zatca)\n[![license](https://img.shields.io/badge/license-BUSL--1.1-blue.svg)](https://github.com/dokhna/dokhna-tech-zatca/blob/main/LICENSE)\n\nA TypeScript-first ZATCA Phase 2 e-invoicing library for Saudi Arabia. Build, sign, hash, generate QR codes, and submit invoices to the ZATCA Fatoora system. Supports single-VAT and multi-VAT (multi-tenant SaaS) deployments with a bring-your-own storage adapter pattern.\n\n## Table of contents\n\n- [Why this library exists](#why-this-library-exists)\n- [Features](#features)\n- [Quickstart](#quickstart)\n- [Packages](#packages)\n- [Examples](#examples)\n- [Documentation](#documentation)\n- [Storage adapters](#storage-adapters)\n- [Multi-VAT / multi-tenant](#multi-vat--multi-tenant)\n- [Requirements](#requirements)\n- [License](#license)\n- [Contributing](#contributing)\n\n## Why this library exists\n\nWe tried several existing Node.js ZATCA Phase 2 packages on a real production system. Each had bugs that surfaced only against real ZATCA sandbox/production flows, and each had to be patched. We rewrote the integration from scratch and ran it against real Saudi Arabian invoices for months. This package is the extracted, decoupled, tested result — open-sourced for everyone with a paid commercial track for SaaS providers.\n\n## Features\n\n- Build and sign all six ZATCA Phase 2 invoice types (Simplified / Standard × Tax invoice / Credit note / Debit note).\n- Phase 1 (QR-only) fallback for pre-onboarding.\n- One-shot `onboard()` orchestrating key generation, CSR, compliance certificate, the six-scenario compliance test pack, and production CSID issuance.\n- Direct ZATCA Compliance, Clearance, and Reporting API clients with retry + structured error normalization.\n- Cancel and status-check APIs.\n- Certificate management helpers (verify, expiration, validity).\n- Pure functional API — no class hierarchy to learn.\n- BYO storage via a small `StorageAdapter` interface; reference adapters for MongoDB, PostgreSQL, in-memory.\n- Multi-tenant SaaS friendly — per-VAT-number certificate isolation and atomic hash-chain management.\n- Zero logging — the package writes nothing to stdout / stderr / disk. Errors are typed exceptions.\n\n## Quickstart\n\n```bash\npnpm add @dokhna-tech/zatca @dokhna-tech/zatca-storage-memory\n```\n\n```ts\nimport {\n  asCommercialRegistrationNumber,\n  asEGSUuid,\n  asVATNumber,\n  issueSimplifiedTaxInvoice,\n  type EGSUnitInfo,\n} from \"@dokhna-tech/zatca\";\nimport { createMemoryStorageAdapter } from \"@dokhna-tech/zatca-storage-memory\";\n\nconst storage = createMemoryStorageAdapter();\nconst vatNumber = asVATNumber(\"301234567890003\");\nconst egsUuid = asEGSUuid(\"00000000-0000-4000-8000-000000000001\");\n\nconst egsInfo: EGSUnitInfo = {\n  uuid: egsUuid,\n  customId: \"branch-01-pos-03\",\n  model: \"Acme POS v2\",\n  crnNumber: asCommercialRegistrationNumber(\"1010010101\"),\n  vatName: \"Acme Trading Co.\",\n  vatNumber,\n  branchName: \"Riyadh HQ\",\n  branchIndustry: \"Retail\",\n  location: {\n    cityName: \"Riyadh\",\n    citySubdivision: \"Olaya\",\n    street: \"King Fahd Road\",\n    plotIdentification: \"1234\",\n    building: \"5678\",\n    postalZone: \"12345\",\n  },\n};\n\nconst issued = await issueSimplifiedTaxInvoice({\n  egsInfo,\n  storage,\n  scope: { vatNumber, egsUuid },\n  signing: {\n    certificate: process.env[\"ZATCA_PRODUCTION_CERTIFICATE\"] ?? \"\",\n    privateKey: process.env[\"ZATCA_PRIVATE_KEY\"] ?? \"\",\n  },\n  input: {\n    kind: \"simplified-tax-invoice\",\n    issueDate: \"2026-05-13\",\n    issueTime: \"12:00:00\",\n    buyerName: \"Walk-in customer\",\n    lineItems: [\n      {\n        id: \"1\",\n        name: \"Coffee 250ml\",\n        quantity: 2,\n        taxExclusivePrice: 10,\n        vatPercent: 15,\n      },\n    ],\n  },\n});\n\n// issued.signedXml / .invoiceHash / .qrCode / .invoiceNumber / .sequence\n```\n\nTo get the certificate + key in the first place, run [`onboard()`](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/onboarding.md). For the full 15-minute path, see [`docs/getting-started.md`](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/getting-started.md).\n\n## Packages\n\n| Package                                                                                                                  | What it is                                                                                               |\n| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |\n| [`@dokhna-tech/zatca`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/packages/core)                              | Core: XML build, signing, QR, ZATCA API client, onboarding                                               |\n| [`@dokhna-tech/zatca-server`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/packages/server)                     | Standalone multi-tenant ZATCA service (Docker image + HTTP API + encrypted credential vault + audit log) |\n| [`@dokhna-tech/zatca-storage-memory`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/packages/storage-memory)     | In-memory adapter (testing/dev)                                                                          |\n| [`@dokhna-tech/zatca-storage-mongo`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/packages/storage-mongo)       | MongoDB adapter (Mongoose peer-dep)                                                                      |\n| [`@dokhna-tech/zatca-storage-postgres`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/packages/storage-postgres) | PostgreSQL adapter (pg peer-dep)                                                                         |\n\n### Looking for a turnkey deployment?\n\nDon't want to embed the SDK? `@dokhna-tech/zatca-server` ships as a Docker image you point at MongoDB or PostgreSQL and an HTTP API your back-office calls. Tenant onboarding, encrypted credential vault, audit log, and `/metrics` exposition are wired up. See [`examples/standalone-server/`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/examples/standalone-server) for a docker-compose + curl walkthrough.\n\n## Examples\n\nFour runnable example projects under [`examples/`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/examples):\n\n| Example                                                                                                    | Demonstrates                                                                                                                                                  |\n| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [`standalone-server/`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/examples/standalone-server)   | **Recommended** — boot `@dokhna-tech/zatca-server` via docker-compose (Mongo or Postgres) and onboard + issue via curl.                                       |\n| [`single-vat-express/`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/examples/single-vat-express) | Express server, one VAT, in-memory storage, full onboarding + issuance flow.                                                                                  |\n| [`multi-vat-saas/`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/examples/multi-vat-saas)         | Fastify server, multiple tenants, per-tenant scoping, MongoDB. Use when you want to embed the SDK in your own server instead of running the standalone image. |\n| [`byo-storage-prisma/`](https://github.com/dokhna/dokhna-tech-zatca/tree/main/examples/byo-storage-prisma) | Custom `StorageAdapter` against Prisma + SQLite.                                                                                                              |\n\nFrom the repo root:\n\n```bash\npnpm install\npnpm --filter @dokhna-tech-examples/single-vat-express start\n```\n\n## Documentation\n\n- [Getting started](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/getting-started.md) — 15-minute path to a signed invoice.\n- [Standalone server](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/standalone-server.md) — turnkey Docker deployment, when to choose it.\n- [Standalone server — HTTP API reference](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/standalone-server-api.md) — every route, body schema, error envelope.\n- [Standalone server — operations](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/standalone-server-operations.md) — env vars, vault rotation, audit, metrics, multi-replica caveats.\n- [Single VAT deployment](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/single-vat.md) — Express wire-up.\n- [Multi-VAT SaaS](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/multi-vat-saas.md) — per-tenant scoping, certificate isolation.\n- [Storage adapters](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/storage-adapters.md) — interface contract + custom adapter.\n- [Onboarding](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/onboarding.md) — CSR, OTP, compliance certs, production CSID. `onboard()` supports `sandbox`, `simulation`, and `production`; use `simulation` to rehearse and `production` (with a production Fatoora-portal OTP) to issue the live CSID. The six compliance scenarios run on every environment as part of CSID issuance.\n- [Compliance tests](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/compliance-tests.md) — `runComplianceTests` + interpreting results.\n- [Migration from an existing helper](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/migration-from-existing-helper.md) — function-by-function table.\n- [Troubleshooting](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/troubleshooting.md) — ZATCA error codes + Lambda OpenSSL recipe.\n- [Security](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/security.md) — secret classification, rotation, zero-logging policy.\n- [API reference](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/api-reference.md) — links to the TypeDoc-generated HTML at `docs/typedoc/index.html`.\n\nRegenerate the API reference with `pnpm docs:api`.\n\n## Storage adapters\n\nThis package does not lock you into a database. The `StorageAdapter` interface has five methods (atomic counter increment, previous-hash lookup, record invoice, load invoice, update status). We ship three reference implementations; writing your own takes ~80 lines. See [`docs/storage-adapters.md`](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/storage-adapters.md).\n\n## Multi-VAT / multi-tenant\n\nPass a `TenantScope = { vatNumber, egsUuid }` into every storage call. Counters and hash chains are scoped per-tenant. Certificates are passed as parameters, never read from a global. See [`docs/multi-vat-saas.md`](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/multi-vat-saas.md).\n\n## Requirements\n\n- Node.js 20+\n- pnpm 9+ (for monorepo development)\n- OpenSSL CLI installed in the runtime environment (used for CSR generation during EGS onboarding). See [troubleshooting.md](https://github.com/dokhna/dokhna-tech-zatca/blob/main/docs/troubleshooting.md#openssl-not-found) for Lambda / Alpine recipes.\n- TypeScript 5.6+ for consumers\n\n## License\n\nThis package is dual-licensed:\n\n- **Free for non-SaaS use** under the [Business Source License 1.1](https://github.com/dokhna/dokhna-tech-zatca/blob/main/LICENSE). On 2030-05-13 (four years from the first release), the license automatically converts to Apache License 2.0.\n- **Commercial license required for SaaS / multi-tenant production use.** See [`LICENSES/COMMERCIAL.md`](https://github.com/dokhna/dokhna-tech-zatca/blob/main/LICENSES/COMMERCIAL.md).\n\nIf you are unsure which applies to your use case, read the LICENSE file's \"Additional Use Grant\" section or contact `licensing@dokhna.tech`.\n\nThe BSL model is used by MariaDB, Sentry, CockroachDB, and Couchbase. It is a source-available license, not an OSI-approved open-source license, until the Change Date.\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](https://github.com/dokhna/dokhna-tech-zatca/blob/main/CONTRIBUTING.md). Security issues: see [`SECURITY.md`](https://github.com/dokhna/dokhna-tech-zatca/blob/main/SECURITY.md).\n","readmeFilename":"README.md"}