{"_id":"@asaidimu/erp-types","_rev":"9-b65df24ddcdec354ad1bed82641bfcc9","name":"@asaidimu/erp-types","dist-tags":{"latest":"3.4.0"},"versions":{"1.0.0":{"name":"@asaidimu/erp-types","version":"1.0.0","keywords":["typescript"],"author":{"name":"Saidimu","email":"47994458+asaidimu@users.noreply.github.com"},"license":"MIT","_id":"@asaidimu/erp-types@1.0.0","maintainers":[{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"}],"homepage":"https://github.com/asaidimu/erp-types#readme","bugs":{"url":"https://github.com/asaidimu/erp-types/issues"},"dist":{"shasum":"16a1393dd6e7478c8c38ff40ee023423226e652b","tarball":"https://registry.npmjs.org/@asaidimu/erp-types/-/erp-types-1.0.0.tgz","fileCount":7,"integrity":"sha512-L26NSemBDGehDxt9/7Q0Dq4OW5weA9efzZplNlxjiU1wtCwkQl0QU6ZoJlbF0psDfydLhZsJ6eSahTqEXW7jTA==","signatures":[{"sig":"MEYCIQDvmkkvlmrEAWknsO8ZncBsXs6o23nvZ16jREltNSBErwIhAPiA0aXY3E1Zss6zP/0oNhDEYilI2HbVftC4XKPLSE7m","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":138650},"main":"index.js","types":"index.d.ts","gitHead":"c813210e70b28c240e6174175e13d2826be018d0","_npmUser":{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"},"repository":{"url":"git+https://github.com/asaidimu/erp-types.git","type":"git"},"_npmVersion":"10.8.2","description":"Standard library of data model interfaces.","directories":{},"_nodeVersion":"20.19.0","dependencies":{},"publishConfig":{"tag":"latest","access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/erp-types_1.0.0_1742676667825_0.3651827182862841","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@asaidimu/erp-types","version":"1.0.1","keywords":["typescript"],"author":{"name":"Saidimu","email":"47994458+asaidimu@users.noreply.github.com"},"license":"MIT","_id":"@asaidimu/erp-types@1.0.1","maintainers":[{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"}],"homepage":"https://github.com/asaidimu/erp-types#readme","bugs":{"url":"https://github.com/asaidimu/erp-types/issues"},"dist":{"shasum":"937d38bf2fbd3434783f5c1989a9a024894f8255","tarball":"https://registry.npmjs.org/@asaidimu/erp-types/-/erp-types-1.0.1.tgz","fileCount":7,"integrity":"sha512-txcFgbxkBebm5OnHky+pSIAXZ9fvf+7NVad0CMg5Mkl/dPTcTJsf1XxXmWekvdQvilqOdLzO0kU+nRa5rPnfkg==","signatures":[{"sig":"MEUCIDXnOM6DshRaQnkH4AQxDz7nZi1Tq7sEw+DnvkE1CYMdAiEAx1aIqXVhdYWnJ96HTz48iBmO7viacaq45Z7IF7Hbnk4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":182165},"main":"index.js","types":"index.d.ts","gitHead":"2303b03ebebd6f842838170f7cda3ab82b309d40","_npmUser":{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"},"repository":{"url":"git+https://github.com/asaidimu/erp-types.git","type":"git"},"_npmVersion":"10.8.2","description":"Standard library of data model interfaces.","directories":{},"_nodeVersion":"20.19.0","dependencies":{},"publishConfig":{"tag":"latest","access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/erp-types_1.0.1_1743429125401_0.28539239438320574","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@asaidimu/erp-types","version":"2.0.0","keywords":["typescript"],"author":{"name":"Saidimu","email":"47994458+asaidimu@users.noreply.github.com"},"license":"MIT","_id":"@asaidimu/erp-types@2.0.0","maintainers":[{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"}],"homepage":"https://github.com/asaidimu/erp-types#readme","bugs":{"url":"https://github.com/asaidimu/erp-types/issues"},"dist":{"shasum":"740e32aea99f556e7dc7252a0aa773dcadfb6939","tarball":"https://registry.npmjs.org/@asaidimu/erp-types/-/erp-types-2.0.0.tgz","fileCount":7,"integrity":"sha512-rPa9KS9TMi8vGT04kaG/Kx4e970ySGZXhyeygXqegXKPtxFyWYkEzXO3iJ3l5c/KmrNQaUVhdwe2/VS9uBdTKg==","signatures":[{"sig":"MEUCIFVBMB+ThMHaZmfu9Z8+eS+rKm7NsqoTUwF9NYESyGfnAiEAgY04vK0xJL02hD/x36rla3N6ZD/mqg1R30OhlqWpqmw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":220532},"main":"index.js","types":"index.d.ts","gitHead":"1d86361d44181336e68bb18f5438f20b5f685e56","_npmUser":{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"},"repository":{"url":"git+https://github.com/asaidimu/erp-types.git","type":"git"},"_npmVersion":"10.8.2","description":"Standard library of data model interfaces.","directories":{},"_nodeVersion":"20.19.1","dependencies":{},"publishConfig":{"tag":"latest","access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/erp-types_2.0.0_1748005157477_0.6718086994052737","host":"s3://npm-registry-packages-npm-production"}},"3.0.0":{"name":"@asaidimu/erp-types","version":"3.0.0","keywords":["typescript"],"author":{"name":"Saidimu","email":"47994458+asaidimu@users.noreply.github.com"},"license":"MIT","_id":"@asaidimu/erp-types@3.0.0","maintainers":[{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"}],"homepage":"https://github.com/asaidimu/erp-types#readme","bugs":{"url":"https://github.com/asaidimu/erp-types/issues"},"dist":{"shasum":"09d74df823f324ab9730dd511f1ea3ac4d775c52","tarball":"https://registry.npmjs.org/@asaidimu/erp-types/-/erp-types-3.0.0.tgz","fileCount":11,"integrity":"sha512-a7g1STTTsBwtwg4r1E+KMOmDkxnuO4BfmIu0CiUSdgLB1tdkyKZdKh50KxK8lTHVeJdt3sHyIqIaRXH0JXAl7g==","signatures":[{"sig":"MEQCIF+rROMVZuWZB8GNZlpct3UidjMvZAowXWsI8yRl2M8YAiBpTpF8ty1mLAaG/uSFG+epVzARTRDxJlWjgi9q05EFuQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":600226},"main":"index.js","types":"index.d.ts","exports":{"./types":{"types":"./types/index.d.ts","import":"./types/index.js"},"./schema":{"types":"./schema/index.d.ts","import":"./schema/index.js"}},"gitHead":"2243a087bb32c6b72e13612765470ab52175a3cb","_npmUser":{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"},"repository":{"url":"git+https://github.com/asaidimu/erp-types.git","type":"git"},"_npmVersion":"10.8.2","description":"Standard library of data model interfaces.","directories":{},"_nodeVersion":"20.19.1","dependencies":{"@asaidimu/anansi":"^3.0.0"},"publishConfig":{"tag":"latest","access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/erp-types_3.0.0_1749473269049_0.6268677091909609","host":"s3://npm-registry-packages-npm-production"}},"3.0.1":{"name":"@asaidimu/erp-types","version":"3.0.1","keywords":["typescript"],"author":{"name":"Saidimu","email":"47994458+asaidimu@users.noreply.github.com"},"license":"MIT","_id":"@asaidimu/erp-types@3.0.1","maintainers":[{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"}],"homepage":"https://github.com/asaidimu/erp-types#readme","bugs":{"url":"https://github.com/asaidimu/erp-types/issues"},"dist":{"shasum":"a1af36807752d2b125c46276c5a90803e85db8e8","tarball":"https://registry.npmjs.org/@asaidimu/erp-types/-/erp-types-3.0.1.tgz","fileCount":11,"integrity":"sha512-ynMUDOMLwqdLJ96kyCSSI1tGmrkdnFsnwZfVgS8WS1ap+/YTs/dbxdGcaAlMJcLW+XRKfskyv8dVAm53lwraIQ==","signatures":[{"sig":"MEUCIEoM8XKfNKNNDJ/h78TwlYRtLS4pDk+p+iSE/oazm6XzAiEA2HKWJucSx+D2bK+BuzFJcKfbH+AdH7YtLQaTKZO4rT8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":597535},"main":"index.js","types":"index.d.ts","exports":{"./types":{"types":"./types/index.d.ts","import":"./types/index.js"},"./schema":{"types":"./schema/index.d.ts","import":"./schema/index.js"}},"gitHead":"8d3bc1c899ecdd7449a1f6e5b24c824df557c2e2","_npmUser":{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"},"repository":{"url":"git+https://github.com/asaidimu/erp-types.git","type":"git"},"_npmVersion":"10.8.2","description":"Standard library of data model interfaces.","directories":{},"_nodeVersion":"20.19.1","dependencies":{"@asaidimu/anansi":"^3.0.0"},"publishConfig":{"tag":"latest","access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/erp-types_3.0.1_1749475066291_0.7388747648739082","host":"s3://npm-registry-packages-npm-production"}},"3.1.0":{"name":"@asaidimu/erp-types","version":"3.1.0","keywords":["typescript"],"author":{"name":"Saidimu","email":"47994458+asaidimu@users.noreply.github.com"},"license":"MIT","_id":"@asaidimu/erp-types@3.1.0","maintainers":[{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"}],"homepage":"https://github.com/asaidimu/erp-types#readme","bugs":{"url":"https://github.com/asaidimu/erp-types/issues"},"dist":{"shasum":"364edd5ac9dbbcd9083348094aac4d133ada9d4d","tarball":"https://registry.npmjs.org/@asaidimu/erp-types/-/erp-types-3.1.0.tgz","fileCount":11,"integrity":"sha512-X58aWoRAITs+1+Gga/v7CLo/C8S9Tv3Vkp9KFmyW0ylhvKNAPEa+ke1HuDT+7VInOnEAyfh2Swke0pm2hxYD1w==","signatures":[{"sig":"MEYCIQCkr2JDsvO2qbWT6GLTcyQCx1/MNQmcrBLKaO2yhmmXcgIhAPj82k4tWi7P9ntrrFORweGQG0QRaTHq2yDhkquVqkaD","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":597713},"main":"index.js","types":"index.d.ts","exports":{"./types":{"types":"./types/index.d.ts","import":"./types/index.js"},"./schema":{"types":"./schema/index.d.ts","import":"./schema/index.js"}},"gitHead":"4c3335389dc09140165f0d3d0d29962fb3b4a961","_npmUser":{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"},"repository":{"url":"git+https://github.com/asaidimu/erp-types.git","type":"git"},"_npmVersion":"10.8.2","description":"Standard library of data model interfaces.","directories":{},"_nodeVersion":"20.19.4","dependencies":{"@asaidimu/anansi":"^3.0.0"},"publishConfig":{"tag":"latest","access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/erp-types_3.1.0_1756111446781_0.6199723098312877","host":"s3://npm-registry-packages-npm-production"}},"3.2.0":{"name":"@asaidimu/erp-types","version":"3.2.0","keywords":["typescript"],"author":{"name":"Saidimu","email":"47994458+asaidimu@users.noreply.github.com"},"license":"MIT","_id":"@asaidimu/erp-types@3.2.0","maintainers":[{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"}],"homepage":"https://github.com/asaidimu/erp-types#readme","bugs":{"url":"https://github.com/asaidimu/erp-types/issues"},"dist":{"shasum":"9c3726f0ae11481da04d2d7b9dfb936424db0201","tarball":"https://registry.npmjs.org/@asaidimu/erp-types/-/erp-types-3.2.0.tgz","fileCount":11,"integrity":"sha512-3hDi3y/3AHMGUOivlqDh+0dBgQsiss+L2STpdyiSRD/ktLfVPqCMLXeBBvz7gSlLi9XBGb5E250l1xn6eatHnQ==","signatures":[{"sig":"MEUCIQDhRhVomXmGrgNyf2lXma29SK+DV63DoQaCL3oSzK5AaAIgNke/BRY45fyPahXuihkAyVtF37t4ie7T2UcvD6AONL0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":598955},"main":"index.js","types":"index.d.ts","exports":{"./types":{"types":"./types/index.d.ts","import":"./types/index.js"},"./schema":{"types":"./schema/index.d.ts","import":"./schema/index.js"}},"gitHead":"eed0374e3fc8bf543472a1268c5321305084f43a","_npmUser":{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"},"repository":{"url":"git+https://github.com/asaidimu/erp-types.git","type":"git"},"_npmVersion":"10.8.2","description":"Standard library of data model interfaces.","directories":{},"_nodeVersion":"20.19.4","dependencies":{"@asaidimu/anansi":"^3.0.0"},"publishConfig":{"tag":"latest","access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/erp-types_3.2.0_1756188944221_0.44607942307363846","host":"s3://npm-registry-packages-npm-production"}},"3.3.0":{"name":"@asaidimu/erp-types","version":"3.3.0","keywords":["typescript"],"author":{"name":"Saidimu","email":"47994458+asaidimu@users.noreply.github.com"},"license":"MIT","_id":"@asaidimu/erp-types@3.3.0","maintainers":[{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"}],"homepage":"https://github.com/asaidimu/erp-types#readme","bugs":{"url":"https://github.com/asaidimu/erp-types/issues"},"dist":{"shasum":"04a62552250e30f0a577da43491bb6897db51b1a","tarball":"https://registry.npmjs.org/@asaidimu/erp-types/-/erp-types-3.3.0.tgz","fileCount":11,"integrity":"sha512-i1LPg1ImwBHX64QHWQ8on9sV1fiJAY+sb860x2FVlODf/9Wk8QykSOJD/eGfZwpi41CYOipKYTcOKt0D0CcI0Q==","signatures":[{"sig":"MEYCIQDRu6m7z+09/+v6xw38kUDbzUUTQKwptWidz3bUSkRtDwIhAJXdelKiONrl+x5Vgx7wn5VrBf05Z0vOh2rV6J/hJYk8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":617469},"main":"index.js","types":"index.d.ts","exports":{"./types":{"types":"./types/index.d.ts","import":"./types/index.js"},"./schema":{"types":"./schema/index.d.ts","import":"./schema/index.js"}},"gitHead":"844478ec2e255e0937657f8222f16535716ad844","_npmUser":{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"},"repository":{"url":"git+https://github.com/asaidimu/erp-types.git","type":"git"},"_npmVersion":"10.8.2","description":"Standard library of data model interfaces.","directories":{},"_nodeVersion":"20.19.4","dependencies":{"@asaidimu/anansi":"^3.0.0"},"publishConfig":{"tag":"latest","access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/erp-types_3.3.0_1756189359153_0.7998977519247519","host":"s3://npm-registry-packages-npm-production"}},"3.4.0":{"name":"@asaidimu/erp-types","version":"3.4.0","description":"Standard library of data model interfaces.","main":"index.js","types":"index.d.ts","exports":{"./types":{"import":"./types/index.js","types":"./types/index.d.ts"},"./schema":{"import":"./schema/index.js","types":"./schema/index.d.ts"}},"keywords":["typescript"],"author":{"name":"Saidimu","email":"47994458+asaidimu@users.noreply.github.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/asaidimu/erp-types.git"},"bugs":{"url":"https://github.com/asaidimu/erp-types/issues"},"homepage":"https://github.com/asaidimu/erp-types#readme","publishConfig":{"registry":"https://registry.npmjs.org/","tag":"latest","access":"public"},"dependencies":{"@asaidimu/anansi":"^3.0.0"},"_id":"@asaidimu/erp-types@3.4.0","gitHead":"6786f12600a32aeef81bb0cd9edd971d0f444fc7","_nodeVersion":"20.19.4","_npmVersion":"10.8.2","dist":{"integrity":"sha512-KqPOx0Z9KzaGQA5Za8e3vYVDjy4zPGU3U2sUgdco/ZkZnN+xUaZ+6YPO7uEk8UlQi7Zpo1SoWQEpOJbe/nynDg==","shasum":"c294c77a23700668b71c5625b58fb52f173158a5","tarball":"https://registry.npmjs.org/@asaidimu/erp-types/-/erp-types-3.4.0.tgz","fileCount":11,"unpackedSize":642069,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIF81kGnncbKfUcp24Aj1Ju4ofvsKSXMTtnOUgss4HrITAiEA5WebluSH2U/rK7hHz9nKYXDVuNlblponhMbaQHGaNow="}]},"_npmUser":{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"},"directories":{},"maintainers":[{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/erp-types_3.4.0_1756209581585_0.8101725300914184"},"_hasShrinkwrap":false}},"time":{"created":"2025-03-22T20:51:07.741Z","modified":"2025-08-26T11:59:42.069Z","1.0.0":"2025-03-22T20:51:08.073Z","1.0.1":"2025-03-31T13:52:05.597Z","2.0.0":"2025-05-23T12:59:17.682Z","3.0.0":"2025-06-09T12:47:49.271Z","3.0.1":"2025-06-09T13:17:46.490Z","3.1.0":"2025-08-25T08:44:06.976Z","3.2.0":"2025-08-26T06:15:44.403Z","3.3.0":"2025-08-26T06:22:39.330Z","3.4.0":"2025-08-26T11:59:41.873Z"},"bugs":{"url":"https://github.com/asaidimu/erp-types/issues"},"author":{"name":"Saidimu","email":"47994458+asaidimu@users.noreply.github.com"},"license":"MIT","homepage":"https://github.com/asaidimu/erp-types#readme","keywords":["typescript"],"repository":{"type":"git","url":"git+https://github.com/asaidimu/erp-types.git"},"description":"Standard library of data model interfaces.","maintainers":[{"name":"asaidimu","email":"lolokilesaidimu@gmail.com"}],"readme":"# @asaidimu/erp-types\n\n[![NPM Version](https://img.shields.io/npm/v/@asaidimu/erp-types.svg)](https://www.npmjs.com/package/@asaidimu/erp-types)\n[![License](https://img.shields.io/npm/l/@asaidimu/erp-types.svg)](https://github.com/asaidimu/erp-types/blob/main/LICENSE.md)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0.3%2B-blue.svg)](https://www.typescriptlang.org/)\n[![Built with Bun](https://img.shields.io/badge/Built%20with-Bun-black)](https://bun.sh/)\n[![Last Updated](https://img.shields.io/badge/Last%20Updated-March%202025-blue.svg)](CHANGELOG.md)\n\n## Table of Contents\n\n-   [Overview & Features](#overview--features)\n    -   [What is `@asaidimu/erp-types`?](#what-is-asaidimu-erp-types)\n    -   [Why Use These Types?](#why-use-these-types)\n    -   [Key Features](#key-features)\n    -   [Core Modules](#core-modules)\n    -   [System Design Principles](#system-design-principles)\n-   [Installation & Setup](#installation--setup)\n    -   [Prerequisites](#prerequisites)\n    -   [Installation Steps](#installation-steps)\n    -   [Verification](#verification)\n-   [Usage Documentation](#usage-documentation)\n    -   [Basic Usage Example](#basic-usage-example)\n    -   [Real-World Use Case: Managing a Small Retail Chain](#real-world-use-case-managing-a-small-retail-chain)\n    -   [Integration Tips](#integration-tips)\n    -   [Best Practices](#best-practices)\n    -   [Anti-Patterns to Avoid](#anti-patterns-to-avoid)\n-   [Project Architecture](#project-architecture)\n    -   [Directory Structure](#directory-structure)\n    -   [Core Components](#core-components)\n    -   [Data Flow](#data-flow)\n    -   [Extension Points](#extension-points)\n-   [Development & Contributing](#development--contributing)\n    -   [Development Setup](#development-setup)\n    -   [Available Scripts](#available-scripts)\n    -   [Testing](#testing)\n    -   [Contributing Guidelines](#contributing-guidelines)\n    -   [Issue Reporting](#issue-reporting)\n-   [Additional Information](#additional-information)\n    -   [Troubleshooting](#troubleshooting)\n    -   [FAQ](#faq)\n    -   [Changelog & Roadmap](#changelog--roadmap)\n    -   [License](#license)\n    -   [Acknowledgments](#acknowledgments)\n\n---\n\n## Overview & Features\n\n### What is `@asaidimu/erp-types`?\n\n`@asaidimu/erp-types` is a comprehensive, modular standard library of TypeScript data model interfaces for building robust and scalable Enterprise Resource Planning (ERP) systems. It provides flexible, type-safe definitions for core business domains, enabling developers to create consistent and interoperable applications across various industries, from manufacturing and retail to service industries and specialized sectors.\n\nThis library defines the *structure* of ERP data without imposing implementation details, allowing for diverse architectural choices (monolithic, microservices) and deployment options (web, mobile, desktop). Its design prioritizes flexibility, strong typing, and audit readiness, making it an ideal foundation for modern business management solutions.\n\nBeyond just TypeScript types, `@asaidimu/erp-types` also provides corresponding **`anansi` schema definitions**. These schemas offer a powerful layer for runtime data validation, documentation generation, and dynamic UI forms, ensuring that your application's data conforms to its defined structure not just at compile-time, but also at runtime.\n\n### Why Use These Types?\n\nERP systems are inherently complex, managing deeply interconnected business processes such as inventory tracking, financial auditing, human resources, and project execution. Without a unified and well-defined type system, development can quickly lead to:\n\n-   **Inconsistency**: Ad-hoc data structures result in mismatched APIs and brittle integrations between modules.\n-   **Errors**: Lack of type safety increases the likelihood of runtime bugs, such as misinterpreting stock units, mishandling transaction states, or incorrectly assigning roles.\n-   **Redundancy**: Developers often find themselves reinventing similar data structures across different parts of the system, leading to wasted effort and increased maintenance burden.\n\n`@asaidimu/erp-types` addresses these challenges by:\n\n-   **Standardizing**: Providing a reusable, canonical foundation for common ERP domains, significantly reducing duplication and promoting consistency.\n-   **Ensuring Safety**: Leveraging TypeScript's powerful type system to enforce strict type checks at compile-time, catching potential errors before they reach production. The accompanying `anansi` schemas provide a mechanism for robust runtime validation.\n-   **Enabling Flexibility**: Utilizing extensible generics and abstract interfaces to support both traditional business use cases (e.g., warehouse inventory) and highly unconventional or specialized scenarios (e.g., modeling \"nuts\" as a currency in a custom economy).\n\nIn essence, this library acts as a robust blueprint, ensuring that your ERP's data model is consistent, scalable, maintainable, and adaptable to evolving business needs.\n\n### Key Features\n\n*   **Comprehensive Coverage**: Includes TypeScript interfaces and `anansi` schema definitions for 12 core ERP domains, from Logistics and Finance to HR and Project Management.\n*   **Dual-Layer Type Safety**: Provides strong compile-time type checking with TypeScript and enables robust runtime data validation through `anansi` schema definitions.\n*   **Modular Design**: Each core module is independent, allowing for progressive adoption and deployment based on specific business requirements.\n*   **Extensibility**: Designed with open patterns and generics, making it easy to customize and extend types without modifying the core library.\n*   **Cross-Module Integration**: Provides consistent interfaces that facilitate seamless data flow and integration between different business functions.\n*   **Audit Readiness**: Supports comprehensive versioning and history tracking capabilities across various modules, crucial for compliance and accountability.\n*   **JSON Compatibility**: Types and schemas are aligned with JSON formats for straightforward data exchange, serialization, and storage in modern data systems.\n*   **Unconventional Use Case Support**: Generics and flexible data structures enable modeling diverse scenarios beyond traditional enterprise environments (e.g., a \"squirrel's nut-based economy\").\n\n### Core Modules\n\nThe library is structured into the following key domains, each offering a rich set of interfaces and schemas:\n\n1.  **Logistics Management**: Manages physical flow of goods, inventory, storage, and transportation.\n    *   **Key Components**: Product Management, Inventory Control, Storage Facility Management, Transport Management, Route Planning, Event Tracking.\n    *   **Use Cases**: Retail inventory, manufacturing supply chain, warehouse operations, fleet management.\n\n2.  **Financial Management**: Handles monetary aspects with flexible currency support.\n    *   **Key Components**: Transaction Processing, Account Management, Asset Tracking, Liability Management, Multi-currency Support, Financial History.\n    *   **Use Cases**: General ledger, accounts receivable/payable, asset management, financial reporting, budget tracking.\n\n3.  **Human Resources Management**: Manages employee data, compensation, and workforce planning.\n    *   **Key Components**: Employee Records, Payroll Processing, Benefits Administration, Time & Attendance, Performance Management, Recruitment, Training & Development.\n    *   **Use Cases**: Employee lifecycle, compensation, workforce analytics, compliance reporting.\n\n4.  **Customer Relationship Management (CRM)**: Manages customer interactions, sales processes, and service delivery.\n    *   **Key Components**: Contact Management, Sales Pipeline, Interaction History, Service Management, Marketing Integration, Contract Management.\n    *   **Use Cases**: Sales force automation, customer service, marketing campaign tracking, customer retention.\n\n5.  **Project Management**: Handles planning, execution, and monitoring of business initiatives.\n    *   **Key Components**: Project Planning, Resource Allocation, Task Management, Time Tracking, Budget Management, Milestone Tracking.\n    *   **Use Cases**: Product development, client engagements, internal initiatives, software development.\n\n6.  **Manufacturing & Production**: Manages creation of goods from raw materials to finished products.\n    *   **Key Components**: Bill of Materials, Production Planning, Work Orders, Machine Management, Quality Control, Production Reporting.\n    *   **Use Cases**: Discrete manufacturing, process manufacturing, job shop operations.\n\n7.  **Procurement Management**: Manages purchasing processes and supplier relationships.\n    *   **Key Components**: Requisition Management, Supplier Management, Purchase Order Processing, Receiving, Invoice Matching, Contract Management.\n    *   **Use Cases**: Strategic sourcing, supplier relationship management, purchase approval workflows.\n\n8.  **Document Management**: Handles creation, storage, and retrieval of business documents.\n    *   **Key Components**: Document Repository, Version Control, Access Control, Workflow Processing, Template Management, Retention Policies.\n    *   **Use Cases**: Contract management, policy documentation, technical documentation, legal compliance.\n\n9.  **Reporting & Analytics**: Provides business intelligence and data visualization capabilities.\n    *   **Key Components**: Dashboard Creation, Standard Reports, Custom Report Builder, Data Export, Alert System, Predictive Analytics.\n    *   **Use Cases**: Executive dashboards, operational reporting, financial analysis, sales performance tracking.\n\n10. **Integration Framework**: Enables communication between modules and external systems.\n    *   **Key Components**: API Management, Data Synchronization, Event Processing, External Connectors, Data Transformation, Message Queuing.\n    *   **Use Cases**: E-commerce platform integration, payment gateway connections, IoT device data collection.\n\n11. **User & Access Management**: Controls system security and access rights.\n    *   **Key Components**: User Authentication, Role-Based Access Control, Multi-factor Authentication, Single Sign-On, Session Management, Audit Logging.\n    *   **Use Cases**: Security compliance, departmental access restrictions, sensitive information protection.\n\n12. **Compliance & Governance**: Ensures adherence to regulations and internal policies.\n    *   **Key Components**: Regulatory Tracking, Policy Management, Audit Management, Risk Assessment, Compliance Reporting, Issue Management.\n    *   **Use Cases**: Industry-specific regulation compliance, financial reporting requirements, data protection standards.\n\n### System Design Principles\n\nThe library is built upon several foundational principles to ensure its robustness and adaptability:\n\n1.  **Flexibility First**: Utilizes generic types and extensive metadata support to adapt to diverse business contexts without requiring source code changes.\n2.  **Type Safety**: Employs strong typing with TypeScript to ensure reliable data handling and minimize runtime errors, providing compile-time guarantees. The inclusion of `anansi` schemas further enforces this at runtime.\n3.  **Modularity**: Designed with independent modules that can be adopted and deployed separately or as a unified system, promoting a microservices-friendly approach.\n4.  **Extensibility**: Follows open design patterns to easily accommodate future growth, custom data requirements, and domain-specific extensions.\n5.  **Cross-Module Integration**: Provides consistent interfaces that enable seamless data flow and interaction between different business functions.\n6.  **Audit Readiness**: Incorporates comprehensive versioning and history tracking capabilities across all modules, essential for compliance, debugging, and historical analysis.\n7.  **JSON Compatibility**: Ensures direct alignment with JSON schemas, facilitating easy data exchange, serialization, and storage in modern data systems.\n\n---\n\n## Installation & Setup\n\n### Prerequisites\n\nTo use `@asaidimu/erp-types` in your project, you'll need:\n\n*   **Node.js**: Version 14 or higher (recommended: LTS version).\n*   **TypeScript**: Version `5.0.3` or higher.\n*   **Bun**: (Optional, but recommended for development scripts) Version `1.0.0` or higher.\n\n### Installation Steps\n\nInstall the package using your preferred package manager:\n\n```bash\n# Using npm\nnpm install @asaidimu/erp-types\n\n# Using yarn\nyarn add @asaidimu/erp-types\n\n# Using bun\nbun add @asaidimu/erp-types\n```\n\n### Verification\n\nTo verify that the types are correctly installed and accessible in your project, create a simple TypeScript file (e.g., `test-types.ts`):\n\n```typescript\nimport { Person, ISOStringDate } from '@asaidimu/erp-types/types';\n\ninterface MyEmployeeData {\n  name: string;\n  employeeId: string;\n}\n\ninterface MyEmployeeMetadata {\n  hireDate: ISOStringDate;\n  department: string;\n}\n\n// Define a concrete type using the generic `Person` interface\ntype MyEmployee = Person<MyEmployeeData, 'hr-system', MyEmployeeMetadata>;\n\n// Instantiate an object conforming to the defined type\nconst employee: MyEmployee = {\n  id: \"EMP789\",\n  data: {\n    type: \"natural\", // 'natural' or 'artificial' as per Person type\n    name: \"Jane Doe\",\n    employeeId: \"A1B2C3D4\",\n  },\n  metadata: {\n    'data-role': 'hr-system', // Matches the DataRole generic argument\n    hireDate: \"2024-01-15T09:00:00Z\",\n    department: \"Sales\",\n  },\n};\n\nconsole.log(`Employee Name: ${employee.data.name}`);\nconsole.log(`Employee ID: ${employee.data.employeeId}`);\nconsole.log(`Hire Date: ${employee.metadata.hireDate}`);\n\n// This line would cause a TypeScript compilation error, demonstrating type safety:\n// employee.data.nonExistentField = \"value\";\n```\n\nCompile and run the file:\n\n```bash\n# Compile\nnpx tsc test-types.ts\n\n# Run (requires Node.js or Bun)\nnode test-types.js\n# Or with Bun:\nbun run test-types.ts\n```\n\nIf the compilation succeeds without errors and the script runs, the types are correctly integrated into your project.\n\n---\n\n## Usage Documentation\n\nThese types are designed to model ERP data declaratively, providing a strong structural foundation for your application. They do not include any runtime logic or validation, which should be handled by your application layer, optionally using the provided `anansi` schemas for robust runtime checks.\n\n### Basic Usage Example\n\nHere's how you might import and use a few basic types, specializing them for your domain:\n\n```typescript\nimport {\n  ISOStringDate,\n  Address,\n  Geolocation,\n  Currency,\n  Transaction,\n  Account,\n  Item,\n  Stock,\n  Facility,\n  DATA_ROLE_SALES, // Specific data role for sales transactions\n} from '@asaidimu/erp-types/types';\n\n// 1. Define custom data shapes for generic type parameters\n//    These interfaces hold your domain-specific properties.\ninterface MyProductData {\n  material: string;\n  size: \"S\" | \"M\" | \"L\" | \"XL\";\n}\n\ninterface MyProductMetadata {\n  supplierSKU: string;\n}\n\ninterface MyProductGroupMetadata {\n  collection: string;\n}\n\n// 2. Define concrete types by applying your custom shapes to the generic ERP interfaces\ntype ApparelProduct = Item<MyProductData, MyProductMetadata, MyProductGroupMetadata>;\n\ntype WarehouseMetadata = { managerId: string };\ntype WarehouseFacility = Facility<\"warehouse\", \"active\" | \"inactive\", { areaCode: string }, WarehouseMetadata>;\n\ntype WarehouseStock = Stock<\n  ApparelProduct,\n  \"available\" | \"reserved\" | \"defective\", // Custom stock states\n  \"warehouse\",                           // Custom facility category\n  \"active\" | \"inactive\",                 // Custom facility states\n  WarehouseMetadata,                     // Facility-specific metadata\n  { lastInspected: ISOStringDate }       // Stock-specific metadata\n>;\n\n// For a sales transaction, specify the medium, metadata shape, and data role.\ntype CashTransaction = Transaction<\"cash\" | \"card\", { customerId: string }, unknown, typeof DATA_ROLE_SALES>;\n\n\n// 3. Create instances of your specialized types\nconst usd: Currency = {\n  code: \"USD\",\n  symbol: \"$\",\n  precision: 2, // 'decimalPlaces' changed to 'precision' based on finance.ts\n};\n\nconst mainWarehouse: WarehouseFacility = {\n  id: \"WH-NYC-001\",\n  label: \"NYC Main Distribution Center\",\n  category: \"warehouse\",\n  status: \"active\",\n  area: { unit: \"sqm\", value: 50000 },\n  data: { floorAreaSqM: 50000 }, // 'floorAreaSqM' added to FacilityData\n  metadata: { managerId: \"EMP-007\" },\n  location: {\n    latitude: 40.7128,\n    longitude: -74.0060,\n    source: \"geocoded\" // 'source' is an enum in common.ts\n  }\n};\n\nconst blueTShirt: ApparelProduct = {\n  id: \"TSHIRT-BLUE-M\",\n  label: \"Blue T-Shirt\",\n  description: \"Cotton crew neck, medium size, blue color.\",\n  data: {\n    material: \"cotton\",\n    size: \"M\",\n  },\n  metadata: {\n    supplierSKU: \"SUP-A-TSHIRTM-BLUE\",\n  },\n  group: { // 'group' can be an object or ID. Here, demonstrating as an object.\n    id: \"GRP-TSHIRTS\",\n    label: \"T-Shirts\",\n    description: \"All t-shirts\",\n    metadata: {\n      collection: \"Summer 2025\",\n    },\n    parent: undefined // Optional parent group\n  },\n  type: \"fungible\", // 'fungible' or 'non-fungible'\n  tags: [\"apparel\", \"casual\"],\n};\n\nconst tShirtStock: WarehouseStock = {\n  id: \"STK-TSHIRT-001\",\n  product: blueTShirt, // Can reference the full product object\n  quantity: 250,\n  reserved: 10, // Optional reserved quantity\n  acquired: \"2025-03-01T10:00:00Z\",\n  storage: mainWarehouse, // Can reference the full facility object\n  state: \"available\",\n  batch: \"BATCH-2025-Q1-TSHIRTS\",\n  expires: \"2027-03-01T00:00:00Z\", // Example: if apparel had a shelf life\n  unit: \"pieces\",\n  metadata: {\n    lastInspected: \"2025-03-10T14:30:00Z\",\n  },\n};\n\nconst customerPayment: CashTransaction = {\n  id: \"TXN-SALES-9876\",\n  description: \"Customer purchase for 3 T-shirts\",\n  amount: 45.00,\n  type: \"credit\", // 'credit' or 'debit'\n  medium: \"card\", // Specific medium 'card'\n  currency: usd,\n  state: \"completed\", // Transaction state\n  metadata: { // Custom metadata for sales transactions\n    'data-role': DATA_ROLE_SALES, // Required data-role property as per schema\n    customerId: \"CUST-XYZ-123\",\n    transactionChannel: \"POS\",\n  },\n  group: { id: \"GRP-SALES\", label: \"Retail Sales\", description: \"All retail sales\" }, // Optional transaction group\n  recurrence: undefined, // Not a recurring transaction\n  gateway: { // Payment gateway details\n    id: \"GATEWAY-STRIPE-TXN-ABC\",\n    status: \"success\",\n    direction: \"in\", // 'in' or 'out'\n    response: { approvalCode: \"ABC123XYZ\" } // Example gateway response metadata\n  },\n};\n\nconsole.log(`Product: ${tShirtStock.product.label}`);\nconsole.log(`Stock Quantity: ${tShirtStock.quantity} ${tShirtStock.unit}`);\nconsole.log(`Transaction Amount: ${customerPayment.currency.symbol}${customerPayment.amount}`);\n```\n\n### Real-World Use Case: Managing a Small Retail Chain\n\nLet's illustrate how various modules seamlessly integrate using a scenario where you're building an ERP for a retail chain with two stores, tracking inventory, sales, employee shifts, and a restocking project.\n\n```typescript\nimport {\n  ISOStringDate,\n  Timespan,\n  Address,\n  Geolocation,\n  Currency,\n  Person,\n  WorkLog,\n  CareerShift,\n  OrganisationalUnit,\n  Item,\n  Facility,\n  Stock,\n  StockMovement,\n  Sale,\n  Project,\n  Task,\n  DATA_ROLE_REAL,\n  DATA_ROLE_SALES,\n} from '@asaidimu/erp-types/types';\n\n// 1. Define Domain-Specific Concrete Types for the Retail Chain\n//    These types specialize the generic ERP interfaces for our retail business context.\n\n// Logistics Module Types\ntype RetailProductData = { unit: string; packaging: string };\ntype RetailProductMetadata = { brand: string; seasonality: string };\ntype RetailProductGroupMetadata = { category: string; department: string };\ntype RetailProduct = Item<RetailProductData, RetailProductMetadata, RetailProductGroupMetadata>;\n\ntype StoreCategory = \"retail-store\" | \"warehouse-hub\" | \"returns-center\";\ntype StoreStatus = \"open\" | \"closed\" | \"under-renovation\";\ntype StoreFacilityData = { floorAreaSqM: number };\ntype StoreFacilityMetadata = { managerName: string; contactPhone: string };\ntype RetailFacility = Facility<StoreCategory, StoreStatus, StoreFacilityData, StoreFacilityMetadata>;\n\ntype StockState = \"available\" | \"reserved\" | \"sold\" | \"defective\" | \"in-transit\" | \"on-hold\";\ntype ProductStock = Stock<\n  RetailProduct,\n  StockState,\n  StoreCategory,\n  StoreStatus,\n  StoreFacilityMetadata,\n  { lastAuditDate: ISOStringDate }\n>;\n\ntype StockMovementType = \"sale\" | \"transfer-out\" | \"transfer-in\" | \"return\" | \"waste\" | \"restock\";\ntype ProductStockMovement = StockMovement<\n  StockState,\n  StockMovementType,\n  { orderId?: string; customerId?: string },\n  StoreCategory,\n  StoreStatus,\n  StoreFacilityMetadata\n>;\n\n// Finance Module Types (simplified for this example)\ntype RetailMedium = \"cash\" | \"card\" | \"mobile-payment\" | \"store-credit\";\ntype RetailAccountType = \"sales-revenue\" | \"operating-expenses\" | \"payroll\" | \"inventory-asset\";\ntype RetailAccountMetadata = { branchId: string; openedBy: string };\ntype RetailAccount = Account<RetailAccountType, RetailMedium, RetailAccountMetadata>;\n\n// Human Resources Module Types\ntype EmployeeRole = \"cashier\" | \"manager\" | \"stocker\" | \"security\";\ninterface EmployeePersonalInfo extends Record<string, unknown> { // Extend RealPersonData structure for specific HR data\n  bio: { name: { first: string; last: string; other?: string[] }; dateOfBirth: ISOStringDate; gender: string; placeOfBirth: Address<any, any>; appearance: any[] };\n  relationships: any[]; groups: any[]; affiliations: any[]; nationality: any[]; address: any; contact: any[]; history: any; personality: any;\n  employeeId: string;\n  currentRole: EmployeeRole;\n}\ntype EmployeeMetadata = { hireDate: ISOStringDate; departmentId: string; status: \"active\" | \"on-leave\" | \"terminated\" };\ntype RetailEmployee = Person<EmployeePersonalInfo, typeof DATA_ROLE_REAL, EmployeeMetadata>;\n\ntype ShiftLogData = { hoursWorked: number; shiftType: \"morning\" | \"afternoon\" | \"night\" };\ntype ShiftLogMetadata = { approvedByManagerId?: string; clockInLocation?: Geolocation };\ntype EmployeeShiftLog = WorkLog<ShiftLogData, ShiftLogMetadata>;\n\ntype OrgUnitData = { headId: string; budgetCode: string };\ntype OrgUnitMembershipData = { role: string; startDate: ISOStringDate };\ntype RetailOrgUnit = OrganisationalUnit<OrgUnitData, OrgUnitMembershipData, { locationId: string }>;\n\n// Sales Module Types\n// Re-using Party from sales.ts, which is a specialized Person.\ntype RetailPartyData =\n  | ({ type: \"natural\"; identity: { name: { first: string; last: string; other?: string[] }; }; nationality: { country: string; id?: { number: string; document?: string; }; }; occupation?: string; role?: string; organization?: string; }\n  | { type: \"artificial\"; name: string; industry: \"retail\" | \"distribution\"; incorporation: { type: \"LLC\" | \"Inc\"; number: string; date: string; country: string; document?: string; }; })\n  & { contact: { email: string; phone?: string; }; address: Address<any, any>; tax: { number: string; document?: string; }; accounts: (string | Account)[]; };\n\ntype RetailParty = Person<RetailPartyData, typeof DATA_ROLE_SALES>;\n\ntype RetailSaleMetadata = { salesChannel: \"in-store\" | \"online\"; registerId?: string };\ntype RetailSale = Sale<RetailSaleMetadata>;\n\n// Project Management Module Types\ntype RetailProjectMetadata = { customerPriority: \"high\" | \"medium\" | \"low\"; targetRevenue?: number };\ntype RestockTaskStatus = \"planned\" | \"picking\" | \"in-transit\" | \"received\" | \"cancelled\";\ntype RetailTask = Task<RestockTaskStatus, { requiredSkills: string[] }>;\ntype RetailProject = Project<RetailProjectMetadata>;\n\n\n// 2. Instantiate and Link Data in a Cohesive Scenario\n\n// Currencies\nconst USD: Currency = { code: \"USD\", symbol: \"$\", precision: 2 };\n\n// Facilities (Logistics)\nconst mainStore: RetailFacility = {\n  id: \"STORE-NYC-001\",\n  label: \"Flagship NYC Store\",\n  category: \"retail-store\",\n  status: \"open\",\n  area: { unit: \"sqm\", value: 1500 },\n  data: { floorAreaSqM: 1500 }, // Specific data for a store facility\n  metadata: { managerName: \"Alice Smith\", contactPhone: \"+12125551000\" },\n  location: { latitude: 40.748817, longitude: -73.985428, source: \"geocoded\" },\n};\n\nconst warehouse: RetailFacility = {\n  id: \"WH-NJ-001\",\n  label: \"New Jersey Regional Warehouse\",\n  category: \"warehouse-hub\",\n  status: \"active\",\n  area: { unit: \"sqm\", value: 10000 },\n  data: { floorAreaSqM: 10000 },\n  metadata: { managerName: \"Bob Johnson\", contactPhone: \"+12015552000\" },\n  location: { latitude: 40.7834, longitude: -74.0089, source: \"geocoded\" },\n};\n\n// Products (Logistics)\nconst summerDress: RetailProduct = {\n  id: \"DRS-SUMMER-RED-M\",\n  label: \"Summer Midi Dress (Red)\",\n  description: \"Lightweight red midi dress, 100% cotton.\",\n  data: { unit: \"pieces\", packaging: \"polybag\" },\n  metadata: { brand: \"FashionFlow\", seasonality: \"Summer\" },\n  group: { id: \"GRP-DRESSES\", label: \"Dresses\", description: \"All dress styles\", metadata: { category: \"Women's Apparel\", department: \"Clothing\" }, parent: undefined },\n  type: \"fungible\", // Though dresses could be non-fungible based on specific SKUs\n  tags: [\"new-arrival\", \"cotton\"],\n};\n\n// Stock (Logistics)\nconst storeDressStock: ProductStock = {\n  id: \"STOCK-DRS-001-NYC\",\n  product: summerDress, // Reference full product object\n  quantity: 25,\n  reserved: 5,\n  acquired: \"2025-03-25T10:00:00Z\",\n  storage: mainStore.id, // Reference facility by ID\n  state: \"available\",\n  batch: \"SS2025-BATCH-A\",\n  unit: \"pieces\",\n  expires: undefined,\n  metadata: { lastAuditDate: \"2025-04-01T15:00:00Z\" },\n};\n\nconst warehouseDressStock: ProductStock = {\n  id: \"STOCK-DRS-001-NJ\",\n  product: summerDress.id, // Reference product by ID string\n  quantity: 500,\n  acquired: \"2025-03-20T08:00:00Z\",\n  storage: warehouse, // Reference facility by object\n  state: \"available\",\n  batch: \"SS2025-BATCH-A\",\n  unit: \"pieces\",\n  expires: undefined,\n  metadata: { lastAuditDate: \"2025-04-01T09:00:00Z\" },\n};\n\n// Stock Movement (Logistics) - Transfer from warehouse to store\nconst transferMovement: ProductStockMovement = {\n  id: \"MVMT-TRANS-001\",\n  stock: warehouseDressStock.id, // The specific stock batch being moved\n  type: \"transfer-out\",\n  quantity: 100,\n  unit: \"pieces\",\n  source: warehouse.id,\n  destination: mainStore.id,\n  timestamp: \"2025-04-02T11:00:00Z\",\n  description: \"Transfer 100 summer dresses from NJ warehouse to NYC store for peak season.\",\n  metadata: { transferRequest: \"REQ-456\" }\n};\n\n// Financial Accounts (Finance)\nconst mainSalesAccount: RetailAccount = {\n  id: \"ACC-SALES-NYC\",\n  name: \"NYC Store Sales Revenue\",\n  type: \"sales-revenue\",\n  // Ledger and balance would be populated by actual transactions\n  ledger: {\n    \"cash\": [], \"card\": [], \"mobile-payment\": [], \"store-credit\": []\n  },\n  balance: { \"cash\": 0, \"card\": 0, \"mobile-payment\": 0, \"store-credit\": 0 },\n  currency: USD,\n  groups: undefined,\n  metadata: { branchId: mainStore.id, openedBy: \"finance-team\" },\n};\n\n// HR - Employee and Organizational Unit\nconst storeManager: RetailEmployee = {\n  id: \"EMP-SM-001\",\n  data: {\n    type: \"natural\",\n    bio: {\n      name: { first: \"Alice\", last: \"Smith\", other: [] },\n      dateOfBirth: \"1985-05-20T00:00:00Z\",\n      gender: \"Female\",\n      placeOfBirth: { country: \"USA\", metadata: {} },\n      appearance: []\n    },\n    currentRole: \"manager\",\n    employeeId: \"EMP-SM-001\",\n    address: {\n      residence: {\n        street: \"123 Main St\", city: \"New York\", state: \"NY\", postalCode: \"10001\", country: \"USA\",\n        residency: { start: \"2020-01-01T00:00:00Z\" }, priority: 1, metadata: {}\n      }, currentLocation: undefined\n    },\n    affiliations: [], contact: [], groups: [], history: { finance: { accounts: [], transactions: [], taxInfo: [], income: [], debts: [] }, health: { weight: [], height: [], medicalHistory: [], allergies: [], medications: [], surgeries: [] }, legal: [] },\n    nationality: [{ country: \"USA\", status: \"citizen\", ids: [] }], personality: {}, relationships: [],\n  },\n  metadata: {\n    'data-role': DATA_ROLE_REAL, // Required for Person metadata\n    hireDate: \"2020-01-01T09:00:00Z\",\n    departmentId: \"DEPT-NYC-MGT\",\n    status: \"active\"\n  },\n};\n\nconst salesDepartment: RetailOrgUnit = {\n  id: \"DEPT-NYC-SALES\",\n  name: \"NYC Sales Department\",\n  parent: mainStore.id, // Parent facility reference\n  members: [{ person: storeManager.id, role: \"Department Head\", startDate: \"2022-03-01T00:00:00Z\" }],\n  data: { headId: storeManager.id, budgetCode: \"SLS-NYC-BUDGET\" },\n  metadata: { locationId: mainStore.id },\n};\n\n// Sales - Parties\nconst supplierParty: RetailParty = {\n  id: \"PARTY-SUPP-FABRIC\",\n  data: {\n    type: \"artificial\",\n    name: \"Global Fabric Co.\",\n    industry: \"distribution\",\n    incorporation: { type: \"Inc\", number: \"INC98765\", date: \"2000-01-01T00:00:00Z\", country: \"USA\" },\n    contact: { email: \"info@globalfabric.com\", phone: \"+1800FABRIC\" },\n    address: { country: \"USA\", area: \"Los Angeles\", region: \"CA\", postalCode: \"90001\", metadata: {} },\n    tax: { number: \"TAXFABC001\", document: \"EIN-GFABC001\" },\n    accounts: [\"ACC-SUPP-FABRIC-001\"], // Assuming supplier has an account\n  },\n  metadata: { 'data-role': DATA_ROLE_SALES },\n};\n\nconst ourCompanyParty: RetailParty = {\n  id: \"PARTY-OUR-RETAIL\",\n  data: {\n    type: \"artificial\",\n    name: \"Our Retail Inc.\",\n    industry: \"retail\",\n    incorporation: { type: \"Inc\", number: \"INC12345\", date: \"2015-07-10T00:00:00Z\", country: \"USA\" },\n    contact: { email: \"purchasing@ourretail.com\", phone: \"+1888RETAIL\" },\n    address: { country: \"USA\", area: \"New York\", region: \"NY\", postalCode: \"10001\", metadata: {} },\n    tax: { number: \"TAXRETAIL001\", document: \"EIN-RETAIL001\" },\n    accounts: [mainSalesAccount.id],\n  },\n  metadata: { 'data-role': DATA_ROLE_SALES },\n};\n\n// Sales - Purchase Order (our company purchasing from supplier)\nconst purchaseOrder: PurchaseOrder = {\n  id: \"PO-2025-001\",\n  issuer: mainSalesAccount.id, // Our company's account issuing the PO\n  recipient: \"ACC-SUPP-FABRIC-001\", // Supplier's account\n  status: \"pending\",\n  date: \"2025-04-01T00:00:00Z\",\n  items: [{ description: \"Summer Dress (Red, M)\", quantity: 100, price: 15.00, total: 1500.00, metadata: { productId: summerDress.id } }],\n  deliveryDate: \"2025-04-15T00:00:00Z\",\n  terms: \"Net 30\",\n  notes: undefined, attachments: undefined, references: undefined,\n};\n\n// Sales - Customer Sale\nconst customerSale: RetailSale = {\n  id: \"SALE-CUST-001\",\n  state: \"completed\",\n  documents: {\n    invoices: [{\n      id: \"INV-CUST-001\", type: \"invoice\", issuer: mainSalesAccount.id, recipient: \"ACC-CUST-001\", status: \"completed\",\n      items: [{ description: \"Summer Midi Dress (Red)\", quantity: 1, price: 59.99, total: 59.99 }],\n      subtotal: 59.99, taxes: [{ id: \"TAX-SALES-001\", type: \"sales\", amount: 5.32, rate: 8.875, description: \"NYC Sales Tax\" }],\n      total: 65.31, currency: USD.code, date: \"2025-04-03T14:30:00Z\",\n      validity: undefined, terms: undefined, due: undefined, complete: undefined, notes: undefined, attachments: undefined, references: undefined,\n    }],\n    receipts: [], quotations: [], proformas: [], credits: [], orders: [], deliveries: [], returns: [], billsOfLading: []\n  },\n  buyer: { // Direct object for a casual customer (often just their `Party` data)\n    id: \"PARTY-CUST-JANE\",\n    data: {\n      type: \"natural\",\n      identity: { name: { first: \"Jane\", last: \"Doe\" } },\n      nationality: { country: \"USA\", id: undefined },\n      contact: { email: \"jane.doe@example.com\", phone: undefined },\n      address: { country: \"USA\", area: \"New York\", region: \"NY\", postalCode: \"10001\", geolocation: undefined, metadata: {} },\n      tax: { number: \"N/A\", document: undefined },\n      accounts: [\"ACC-CUST-001\"], // Fictional customer account\n      occupation: undefined, role: undefined, organization: undefined\n    },\n    metadata: { 'data-role': DATA_ROLE_SALES },\n  },\n  seller: ourCompanyParty.id,\n  created: \"2025-04-03T14:25:00Z\",\n  status: { payment: \"complete\", fulfillment: \"complete\" },\n  payments: [\"TXN-SALES-9876\"], // Assuming 'TXN-SALES-9876' is the transaction ID from the basic example\n  metadata: { salesChannel: \"in-store\", registerId: \"REG-01\" },\n  notes: undefined, attachments: undefined, modified: undefined, completed: undefined,\n};\n\n\n// Connections and implications:\n// - `storeDressStock.quantity` would implicitly decrease after `customerSale` is completed (handled by application logic).\n// - `mainSalesAccount.balance` would implicitly increase from the `customerSale`'s payment transaction.\n// - `purchaseOrder` from `ourCompanyParty` to `supplierParty` might trigger a `ProductStockMovement` for `warehouseDressStock`.\n// - `storeManager` is part of `salesDepartment` and their performance/shift logs (`EmployeeShiftLog`) are tracked in HR.\n```\n\n#### How This Fits Together\n\nThis example demonstrates the power of interlinked, generic types:\n\n*   **Logistics**: `ProductStock` tracks inventory (`summerDress`) in `RetailFacility` locations (`mainStore`, `warehouse`). `ProductStockMovement` logs the movement of stock between these facilities.\n*   **Finance**: `RetailAccount`s manage financial balances, and their ledger implicitly tracks `Transaction`s that result from sales or purchases.\n*   **Human Resources**: `RetailEmployee` (`storeManager`) is a `Person` with HR-specific metadata. They belong to an `OrganisationalUnit` (`salesDepartment`). `EmployeeShiftLog` tracks their time.\n*   **Sales**: `RetailSale` orchestrates the entire process, referencing `RetailParty` for buyer/seller, `TransactionDocument` for invoicing, and linking implicitly to `ProductStock` for inventory.\n*   **Generics in Action**: Notice how types like `Item`, `Stock`, `Facility`, `Person`, and `Sale` are specialized with domain-specific type arguments (e.g., `RetailProductData`, `StoreCategory`, `RetailMedium`) to fit the retail business context without changing the core library interfaces.\n\nThis interconnectedness, enforced by TypeScript at compile-time and supportable by `anansi` schemas at runtime, ensures data integrity and consistency across your ERP system.\n\n### Integration Tips\n\n*   **API Definitions**: Use these types directly to define your REST API request and response payloads. For example, a `POST /inventory/stock` endpoint could accept `ProductStock` as its body.\n*   **Database Schemas**: Map these TypeScript interfaces to your chosen database schemas (e.g., MongoDB documents, PostgreSQL tables). The JSON compatibility facilitates this.\n*   **Runtime Validation**: Complement TypeScript's compile-time checks with runtime validation using the provided `anansi` schemas. This ensures incoming data (e.g., from external APIs, user input) conforms to the expected structure and constraints (e.g., `quantity` must be positive).\n    ```typescript\n    import { getDefinition, validate } from '@asaidimu/anansi';\n    import { SaleSchema } from '@asaidimu/erp-types/schema'; // Import schema directly\n\n    // Get the Anansi schema definition for Sale\n    const saleDefinition = getDefinition(SaleSchema);\n\n    // Example: Validate an incoming sales object\n    const incomingSaleData = {\n      id: \"SALE-XYZ\",\n      state: \"completed\",\n      // ... rest of the sale data\n      status: { payment: \"complete\", fulfillment: \"complete\" },\n      buyer: { id: \"CUST-001\", data: { type: \"natural\", /* ... */ }, metadata: { 'data-role': 'sales' } },\n      seller: { id: \"OUR-BIZ\", data: { type: \"artificial\", /* ... */ }, metadata: { 'data-role': 'sales' } },\n      created: \"2025-01-01T10:00:00Z\",\n      payments: [\"TXN-123\"],\n      documents: { invoices: [] }\n    };\n\n    const validationResult = validate(saleDefinition, incomingSaleData);\n\n    if (validationResult.success) {\n      console.log(\"Data is valid:\", validationResult.data);\n    } else {\n      console.error(\"Validation errors:\", validationResult.errors);\n    }\n    ```\n*   **Domain-Driven Design**: Leverage the modularity to build your application around these domains. Each module (`src/finance.ts`, `src/logistics.ts`, etc.) can correspond to a microservice or a distinct component in a monolithic architecture.\n\n### Best Practices\n\n1.  **Declarative Typing**:\n    *   **Do**: Define named types for generic parameters (e.g., `type MyProductData = { unit: string }` then `Item<MyProductData, ...>`).\n    *   **Why**: Improves readability, reusability, and makes complex type signatures easier to manage.\n    *   **Don't**: Inline generic parameters directly (e.g., `Item<{ unit: string }, ...>`).\n\n2.  **Separation of Concerns**:\n    *   **Do**: Separate core data (`data`), optional context (`metadata`), and finite states (union types).\n    *   **Why**: Keeps concerns distinct, allowing `data` to hold essential properties, `metadata` for flexible extensions, and union types for strict state management.\n    *   **Don't**: Lump all properties into a single, un-categorized object.\n\n3.  **Thoughtful Union Types**:\n    *   **Do**: Use union types for finite, well-defined states or categories (e.g., `type StockStatus = \"available\" | \"sold\" | \"restocking\"`).\n    *   **Why**: Clarifies constraints, prevents invalid values, and improves code comprehension.\n    *   **Don't**: Rely on raw `string` types where a limited set of values is expected.\n\n4.  **Referencing by ID or Object**:\n    *   **Do**: Utilize the `string | Type` pattern (e.g., `storage: string | Facility`).\n    *   **Why**: Provides flexibility for API design (send just ID) and internal graph traversal (load full object).\n    *   **Don't**: Exclusively use `string` if you sometimes need to embed the full object, or exclusively use the full object if you only need the ID.\n\n### Anti-Patterns to Avoid\n\n*   **Ad-Hoc Generics**: Creating types like `const x: Stock<Item<{ unit: string }, { brand: string }>, ...>` is cumbersome and hinders reusability. Always define named types for your generic arguments.\n*   **Ignoring Union Types**: Allowing any `string` value where a specific set of statuses is expected (e.g., `status: string` instead of `status: \"active\" | \"inactive\"`).\n*   **Overloading Domains**: Adding fields that belong to another domain (e.g., `price` directly to `Stock` instead of `Transaction` or a separate `ProductPrice` interface). This violates modularity.\n*   **Mixing Runtime Logic with Types**: Never embed validation logic or business rules directly into these interfaces. They are purely for data structure definition.\n\n---\n\n## Project Architecture\n\nThis project does not implement a runtime application. Instead, it provides a structured collection of TypeScript interfaces and their corresponding `anansi` schema definitions that define the data models for an ERP system.\n\n### Core Components\n\nThe \"core components\" of this library are its **TypeScript interface definitions** and their corresponding **`anansi` schema definitions**, organized logically by business domain within the `src/` directory.\n\n*   **`src/types/`**: Contains pure TypeScript interfaces (`.ts` files), providing compile-time type safety and defining the structural contracts for all ERP data entities.\n*   **`src/schema/`**: Contains `anansi` schema definitions, which are JavaScript/TypeScript objects that formally describe the structure and constraints of the data. These are crucial for runtime validation, API documentation generation, and dynamic form rendering.\n*   **`common.ts` (in both `types` and `schema`)**: Holds fundamental, cross-cutting types and their schemas (e.g., `ISOStringDate`, `Address`, `Geolocation`, `Timespan`), ensuring consistency across multiple modules.\n*   **`index.ts` (root level)**: Serves as the public API, re-exporting all primary interfaces from `src/types` and all schema definitions from `src/schema`, making them easy to import from the `@asaidimu/erp-types` package.\n\n### Data Flow\n\nAs a types-only library, `@asaidimu/erp-types` does not define runtime data flow or application logic. Instead, it provides the **blueprint** for how data should be structured and how different entities relate to each other.\n\n*   **Cross-Module Referencing**: Types frequently reference entities from other modules using either their `id: string` or the full object (e.g., `person: string | Person<any, any>`). This pattern facilitates the creation of interconnected graphs of business data, where an entity in one domain (e.g., an `Employee` in HR) can be referenced in another (e.g., an `Assignment` in Project Management).\n*   **Generics for Flexibility**: Extensive use of generics (`<TData>`, `<TMetadata>`, `<TState>`) allows consumers to define specific data shapes for their unique business contexts while adhering to the library's core structure. This means the \"data flow\" is defined by your application's implementation, guided by these flexible type contracts.\n\nFor example, a `Sale` type in the `sales` module might implicitly \"flow\" data to `Account` types in the `finance` module (for revenue recording) and `Stock` types in the `logistics` module (for inventory reduction). The library dictates *what* that data looks like, but your application code handles *how* it is moved and processed.\n\n### Extension Points\n\nThe library is designed for maximum extensibility:\n\n*   **Named Generics**: By using named generic type parameters (e.g., `Person<PersonData, DataRole, PersonMetadata>`), consumers can inject their own specific data shapes without modifying the base interfaces. This allows for deep customization while retaining compatibility.\n*   **Metadata Fields**: Most core interfaces include a `metadata?: Record<string, unknown>` field (or similar generic types). This provides a flexible escape hatch for adding arbitrary, context-specific properties to any entity without extending the core type itself.\n*   **Union Types as Customization**: For fields like `type` or `status`, many interfaces use `string` or a default generic type (`TState extends string`). This allows developers to define union types (e.g., `type MyOrderStatus = \"pending\" | \"shipped\" | \"delivered\"`) in their own projects and pass them as generic arguments, tailoring the schema to their specific state machines.\n*   **`anansi` Schemas**: The modular nature of `anansi` schemas means you can extend or compose existing schemas to define more complex validation rules or to generate specialized forms/documentation without altering the core library.\n\nThis design philosophy means that rather than forking the library for minor adjustments, users can extend and specialize the types and their validation rules directly within their own codebase.\n\n---\n\n## Development & Contributing\n\nWe welcome contributions to `@asaidimu/erp-types`! Whether it's adding new modules, improving existing type definitions, or enhancing documentation, your input is valuable.\n\n### Development Setup\n\nTo set up the project for local development:\n\n1.  **Clone the repository:**\n    ```bash\n    git clone https://github.com/asaidimu/erp-types.git\n    cd erp-types\n    ```\n2.  **Install dependencies:**\n    This project uses `bun` for package management and scripts.\n    ```bash\n    bun install\n    ```\n    (If you don't have Bun, you can use `npm install`, but Bun is recommended for script execution speed.)\n\n### Available Scripts\n\nThe `package.json` defines several useful scripts for development:\n\n*   `bun ci`: Installs project dependencies.\n*   `bun clean`: Removes the `dist/` directory, cleaning up previous build artifacts.\n*   `bun prebuild`: Executes `bun clean` and then runs a custom `sync-package.ts` script (not provided, but implied to prepare `dist.package.json`).\n*   `bun build`: Compiles TypeScript files from `index.ts` to `dist/` in CommonJS and ES Module formats, and generates TypeScript declaration files (`.d.ts`). This command internally uses `tsup`.\n*   `bun postbuild`: Copies `README.md` and `LICENSE.md` to the `dist/` directory, and moves `dist.package.json` to `dist/package.json` for proper package publishing.\n\nTo build the project:\n\n```bash\nbun run build\n```\n\n### Testing\n\nThis library primarily consists of TypeScript interfaces and schema definitions, and its \"testing\" largely relies on:\n\n*   **TypeScript Compiler Checks**: The `bun run build` command (which internally uses `tsup` and `typescript`) will perform comprehensive type checking across all files, ensuring that all interfaces are correctly defined and used. Any type errors indicate a problem in the definitions.\n*   **ESLint**: The project uses ESLint with `@typescript-eslint/eslint-plugin` for code quality and consistency. While not explicitly defined as a separate `lint` script in `package.json`, running `eslint src/` would apply these checks to enforce style and identify potential issues.\n\nWe encourage contributors to ensure their changes pass TypeScript compilation without errors and adhere to the project's coding style and `eslint` rules.\n\n### Contributing Guidelines\n\nWe appreciate your contributions! Please follow these guidelines:\n\n1.  **Fork the Repository**: Start by forking the `asaidimu/erp-types` repository on GitHub.\n2.  **Create a Branch**: Create a new branch for your feature or bug fix (e.g., `feature/add-crm-types`, `fix/logistics-typo`).\n3.  **Code Changes**:\n    *   **Pure Types**: This library is strictly for TypeScript interfaces (`src/types`) and `anansi` schema definitions (`src/schema`). Do not add any runtime logic, utility functions, or data validation implementations directly into these files.\n    *   **Consistency**: Adhere to the existing coding style and naming conventions.\n    *   **Generics & Extensibility**: Favor using generics and `metadata` fields for flexible extensions rather than hardcoding specific values.\n    *   **Documentation**: Add JSDoc comments to new interfaces, types, properties, and schema definitions, explaining their purpose, usage, and any constraints.\n    *   **Atomic Commits**: Make small, focused commits with clear, descriptive messages following [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) (e.g., `feat(sales): add sales order interface`, `fix(logistics): correct typo in stock field`).\n4.  **Build & Verify**: Run `bun run build` to ensure your changes compile without errors.\n5.  **Submit a Pull Request**:\n    *   Open a Pull Request (PR) to the `main` branch of the original repository.\n    *   Provide a clear title and description for your PR, summarizing your changes and their purpose.\n    *   Reference any related issues (e.g., `Fixes #123`, `Closes #456`).\n\n### Issue Reporting\n\nIf you encounter any bugs, have feature requests, or suggestions for improvement, please open an issue on GitHub:\n\n*   **Report Bugs**: Provide a clear, concise description of the bug, steps to reproduce it, expected behavior, and your environment details (TypeScript version, Node.js/Bun version).\n*   **Request Features**: Describe the feature you'd like to see, explaining its use case and why it would be beneficial to the library.\n*   **General Questions**: Feel free to open an issue for questions about usage or design decisions.\n\nAll issues can be reported at the official GitHub repository: [https://github.com/asaidimu/erp-types/issues](https://github.com/asaidimu/erp-types/issues).\n\n---\n\n## Additional Information\n\n### Troubleshooting\n\n*   **TypeScript Errors**:\n    *   **`Type 'X' is not assignable to type 'Y'`**: This indicates a mismatch between your data structure and the expected interface. Double-check the generic parameters you're using.\n    *   **Missing Properties**: Ensure all `required` properties in an interface are provided.\n    *   **Excess Properties**: If you're encountering `Object literal may only specify known properties` errors, it means your object has properties not explicitly defined in the interface. Utilize `metadata` fields or extend interfaces if you need to add custom properties.\n    *   **Dependency Issues**: If `bun install` or `npm install` fails, clear your package manager cache (`bun cache clean` or `npm cache clean --force`) and try again.\n\n*   **Build Failures**:\n    *   Ensure TypeScript is installed globally or locally (`typescript` in `devDependencies`).\n    *   Check your `tsconfig.json` for correct paths and compiler options.\n    *   Verify that `tsup` is installed and correctly configured.\n\n### FAQ\n\n*   **Q: Can I use this library with JavaScript?**\n    A: While the library itself is written in TypeScript and provides type definitions, you can use it in a JavaScript project. However, you won't benefit from the compile-time type safety. Your IDE (if it supports TypeScript definitions) might still provide type hints. For runtime validation in JavaScript, you can leverage the `anansi` schemas.\n\n*   **Q: Does this library include any runtime logic or validation?**\n    A: No, `@asaidimu/erp-types` is primarily a collection of TypeScript interfaces. It defines data shapes, not behavior. While it provides `anansi` schemas for validation, you'll need to implement your own runtime logic, data processing, and business rules.\n\n*   **Q: How do I add custom fields to an existing type?**\n    A: Many interfaces include a `metadata?: Record<string, unknown>` field (or a more specific generic type for metadata). This is the recommended way to add custom, application-specific data without modifying the core library. If you need to add a fundamental, non-optional field to a core type, consider opening an issue or a pull request to discuss its inclusion in the library.\n\n*   **Q: Can I use this with frameworks like NestJS, Express, or React?**\n    A: Absolutely! These types are framework-agnostic. You can use them to define DTOs (Data Transfer Objects) in your NestJS/Express APIs, model state in React components, or define data structures for any part of your application. The `anansi` schemas can also be integrated into API middleware for request body validation.\n\n### Changelog & Roadmap\n\nFor a detailed history of changes and new features, please refer to the [CHANGELOG.md](CHANGELOG.md) file.\n\n**Future Extensions (Roadmap):**\n\nBased on the strategic vision, potential future extensions for this ERP type library include:\n\n1.  **Machine Learning Integration**: Predictive analytics models for inventory, sales forecasting, and resource planning.\n2.  **Blockchain Support**: Immutable transaction records for critical business processes, enhancing transparency and auditability.\n3.  **IoT Connectivity**: Direct integration with smart devices and sensors for real-time data collection in logistics and manufacturing.\n4.  **Augmented Reality (AR)**: Visual interfaces for warehouse management, maintenance, and field operations.\n5.  **Voice Interfaces**: Natural language processing capabilities for hands-free operation and improved user interaction.\n6.  **Containerized Deployment**: Enhanced types and considerations for microservice architectures with Kubernetes orchestration, facilitating cloud-native deployments.\n\n### License\n\nThis project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for full details.\n\n### Acknowledgments\n\nDeveloped by [asaidimu](https://github.com/asaidimu).\nInspired by the need for robust, flexible, and type-safe data models in enterprise systems.\n\n*Last Updated: March 2025*\n","readmeFilename":"README.md"}