@tailor-platform/erp-kit 0.3.0 → 0.4.0

package/src/modules/organization/db/site.ts

@@ -0,0 +1,44 @@
+import {
+  db,
+  type TailorAnyDBField,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { company } from "./company";
+
+export interface CreateSiteTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+}
+
+export function createSiteType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateSiteTypeParams<F>,
+) {
+  return db
+    .type("Site", {
+      name: db.string().description("Site display name"),
+      type: db
+        .string()
+        .description("Site type: OFFICE, WAREHOUSE, STORE, FACTORY, DISTRIBUTION_CENTER"),
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: company },
+          backward: "sites",
+        })
+        .description("Foreign key to Company"),
+      street: db.string().description("Site address street"),
+      city: db.string().description("Site address city"),
+      state: db.string({ optional: true }).description("Site address state/province"),
+      postalCode: db.string().description("Site address postal code"),
+      country: db.string().description("Site address country code"),
+      timezone: db.string().description("IANA timezone identifier"),
+      status: db.string().description("Site lifecycle status: ACTIVE, INACTIVE"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const site = createSiteType({});

package/src/modules/organization/docs/commands/ActivateCompany.md

@@ -0,0 +1,62 @@
+# ActivateCompany
+
+## Overview
+
+ActivateCompany transitions a company from DRAFT to ACTIVE status, making it available for transactional modules to reference. All required fields must be configured before activation: legal name, base currency, and registered address.
+
+This command supports the go-live workflow where companies are fully configured before becoming operational.
+
+## Business Rules
+
+- Company must exist
+- Company must be in DRAFT status
+- Legal name must be non-empty
+- Base currency must be assigned and reference a valid active Currency
+- Registered address fields (street, city, postalCode, country) must be populated; state/province is optional
+- After activation, base currency becomes immutable
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Company exists?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Company in DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Legal name set?}
+    F -->|No| G[Return error: MISSING_REQUIRED_FIELDS]
+    F -->|Yes| H{Base currency assigned?}
+    H -->|No| G
+    H -->|Yes| I{Currency valid and active?}
+    I -->|No| L[Return error: INVALID_BASE_CURRENCY]
+    I -->|Yes| J{Address complete?}
+    J -->|No| G
+    J -->|Yes| K[Set status: ACTIVE]
+    K --> M[Return activated company]
+```
+
+## External Dependencies
+
+- **primitives module — Currency**: The referenced base currency must exist and be in active status in the primitives module's Currency entity
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Specified company ID does not exist
+- **INVALID_STATE**: Company is not in DRAFT status
+- **MISSING_REQUIRED_FIELDS**: One or more required fields (legal name, base currency, address) are not set
+- **INVALID_BASE_CURRENCY**: The assigned base currency does not exist or is not in active status in the primitives module
+
+## Test Cases
+
+- activates DRAFT company with all required fields
+- throws when company does not exist
+- throws when company is already ACTIVE
+- throws when company is INACTIVE
+- throws when legal name is missing
+- throws when base currency is not assigned
+- throws when base currency references a non-existent Currency
+- throws when base currency references an inactive Currency
+- throws when address street is missing
+- throws when address city is missing
+- throws when address postalCode is missing
+- throws when address country is missing

package/src/modules/organization/docs/commands/CreateCompany.md

@@ -0,0 +1,49 @@
+# CreateCompany
+
+## Overview
+
+CreateCompany establishes a new legal entity in the system in DRAFT status. The command accepts the company's legal name, and optionally tax identification number, registration number, base currency, and registered address fields. Companies are created in DRAFT to allow configuration and review before activation.
+
+This command supports initial system setup and multi-company expansion scenarios.
+
+## Business Rules
+
+- Legal name is required and must be non-empty
+- Company is always created in DRAFT status
+- Base currency, if provided, must reference a valid active Currency from the primitives module
+- Tax identification number and registration number are optional at creation
+- Registered address fields are optional at creation (required before activation)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Validate legal name}
+    B -->|Empty| C[Return error: INVALID_LEGAL_NAME]
+    B -->|Valid| D{Base currency provided?}
+    D -->|Yes| E{Currency exists and active?}
+    E -->|No| F[Return error: CURRENCY_NOT_FOUND]
+    E -->|Yes| G[Create company record]
+    D -->|No| G
+    G --> H[Set status: DRAFT]
+    H --> I[Return created company]
+```
+
+## External Dependencies
+
+- [primitives::getCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validates that the referenced base currency exists and is active
+
+## Error Scenarios
+
+- **INVALID_LEGAL_NAME**: Legal name is empty or not provided
+- **CURRENCY_NOT_FOUND**: Referenced base currency does not exist or is inactive
+
+## Test Cases
+
+- creates company in DRAFT status
+- throws when legal name is empty
+- throws when referenced currency does not exist
+- throws when referenced currency is inactive
+- creates company without base currency
+- creates company with full address fields
+- passes custom fields through to insert

package/src/modules/organization/docs/commands/CreateDepartment.md

@@ -0,0 +1,62 @@
+# CreateDepartment
+
+## Overview
+
+CreateDepartment establishes a new department within a company in ACTIVE status. Each department has a unique code scoped to its company, a human-readable name, and an optional parent department reference for building organizational hierarchies.
+
+This command supports initial organizational structure setup and ongoing expansion of department trees.
+
+## Business Rules
+
+- Department code is required and must be non-empty
+- Department code must be unique within the same company
+- Department code is immutable after creation
+- Department name is required and must be non-empty
+- Company must exist and be referenced by companyId
+- Parent department, if provided, must exist and belong to the same company
+- Department is always created in ACTIVE status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Validate code and name}
+    B -->|Invalid| C[Return error: INVALID_CODE or INVALID_NAME]
+    B -->|Valid| D{Company exists?}
+    D -->|No| E[Return error: COMPANY_NOT_FOUND]
+    D -->|Yes| F{Code unique in company?}
+    F -->|No| G[Return error: DUPLICATE_CODE]
+    F -->|Yes| H{Parent department provided?}
+    H -->|Yes| I{Parent exists in same company?}
+    I -->|No| J[Return error: PARENT_NOT_FOUND]
+    I -->|Yes| K[Create department record]
+    H -->|No| K
+    K --> L[Set status: ACTIVE]
+    L --> M[Return created department]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_CODE**: Department code is empty or not provided
+- **INVALID_NAME**: Department name is empty or not provided
+- **COMPANY_NOT_FOUND**: Referenced company does not exist
+- **DUPLICATE_CODE**: Department with same code already exists in the same company
+- **PARENT_NOT_FOUND**: Referenced parent department does not exist or belongs to a different company
+
+## Test Cases
+
+- creates top-level department in ACTIVE status
+- creates department with parent department
+- throws when code is empty
+- throws when code is whitespace-only
+- throws when name is empty
+- throws when name is whitespace-only
+- throws when company does not exist
+- throws when code already exists in same company
+- allows same code in different companies
+- throws when parent department does not exist
+- throws when parent department belongs to different company

package/src/modules/organization/docs/commands/CreateSite.md

@@ -0,0 +1,74 @@
+# CreateSite
+
+## Overview
+
+CreateSite establishes a new physical facility for a company in ACTIVE status. Each site has a name, type classification, structured address, country, and timezone. Sites are created ready for operational use with no DRAFT state.
+
+This command supports facility registration for warehouses, offices, stores, factories, and distribution centers.
+
+## Business Rules
+
+- Site name is required and must be non-empty
+- Site name must be unique within the same company
+- Site type is required and must be one of: OFFICE, WAREHOUSE, STORE, FACTORY, DISTRIBUTION_CENTER
+- companyId is required and references an existing ACTIVE company
+- Structured address fields (street, city, postalCode, country) are required
+- State/province is optional
+- Country must be a valid country code
+- Timezone is required and must be a valid IANA timezone identifier
+- Site is always created in ACTIVE status
+- companyId is immutable after creation
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Validate name and type}
+    B -->|Invalid| C[Return error: INVALID_NAME or INVALID_TYPE]
+    B -->|Valid| D{Company exists and ACTIVE?}
+    D -->|No| E[Return error: COMPANY_NOT_FOUND or COMPANY_INACTIVE]
+    D -->|Yes| F{Name unique in company?}
+    F -->|No| G[Return error: DUPLICATE_NAME]
+    F -->|Yes| H{Address fields complete?}
+    H -->|No| I[Return error: MISSING_REQUIRED_FIELDS]
+    H -->|Yes| J{Valid country code?}
+    J -->|No| K[Return error: INVALID_COUNTRY]
+    J -->|Yes| L{Valid timezone?}
+    L -->|No| M[Return error: INVALID_TIMEZONE]
+    L -->|Yes| N[Create site record]
+    N --> O[Set status: ACTIVE]
+    O --> P[Return created site]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_NAME**: Site name is empty or not provided
+- **INVALID_TYPE**: Site type is not one of the allowed classifications
+- **COMPANY_NOT_FOUND**: Referenced company does not exist
+- **COMPANY_INACTIVE**: Referenced company is not in ACTIVE status
+- **DUPLICATE_NAME**: Site with same name already exists in the same company
+- **MISSING_REQUIRED_FIELDS**: One or more required address fields are missing
+- **INVALID_COUNTRY**: Country code is not a valid country code
+- **INVALID_TIMEZONE**: Timezone is not a valid IANA timezone identifier
+
+## Test Cases
+
+- creates site in ACTIVE status
+- throws when name is empty
+- throws when type is invalid
+- throws when company does not exist
+- throws when company is not ACTIVE
+- throws when site name already exists in same company
+- allows same site name in different companies
+- throws when address street is missing
+- throws when address city is missing
+- throws when address postalCode is missing
+- throws when address country is missing
+- creates site without state/province
+- creates site with state/province
+- throws when country code is invalid
+- throws when timezone is invalid

package/src/modules/organization/docs/commands/DeactivateCompany.md

@@ -0,0 +1,40 @@
+# DeactivateCompany
+
+## Overview
+
+DeactivateCompany transitions a company from ACTIVE to INACTIVE status. Inactive companies stop accepting new transactions while preserving all historical data. This supports scenarios where a legal entity ceases operations but records must be retained for audit and compliance.
+
+## Business Rules
+
+- Company must exist
+- Company must be in ACTIVE status
+- Deactivation does not affect existing historical transactions
+- The company record is preserved (not deleted)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Company exists?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Company in ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Set status: INACTIVE]
+    F --> G[Return deactivated company]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Specified company ID does not exist
+- **INVALID_STATE**: Company is not in ACTIVE status
+
+## Test Cases
+
+- deactivates ACTIVE company
+- throws when company does not exist
+- throws when company is in DRAFT status
+- throws when company is already INACTIVE

package/src/modules/organization/docs/commands/DeactivateDepartment.md

@@ -0,0 +1,44 @@
+# DeactivateDepartment
+
+## Overview
+
+DeactivateDepartment transitions a department from ACTIVE to INACTIVE status. A department cannot be deactivated while it has active sub-departments. Historical references to the department remain intact.
+
+## Business Rules
+
+- Department must exist
+- Department must be in ACTIVE status
+- Department must not have any active sub-departments
+- Deactivation does not affect historical records referencing this department
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Department exists?}
+    B -->|No| C[Return error: DEPARTMENT_NOT_FOUND]
+    B -->|Yes| D{Department in ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Has active sub-departments?}
+    F -->|Yes| G[Return error: HAS_ACTIVE_CHILDREN]
+    F -->|No| H[Set status: INACTIVE]
+    H --> I[Return deactivated department]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **DEPARTMENT_NOT_FOUND**: Specified department ID does not exist
+- **INVALID_STATE**: Department is not in ACTIVE status
+- **HAS_ACTIVE_CHILDREN**: Department has one or more active sub-departments
+
+## Test Cases
+
+- deactivates ACTIVE department with no sub-departments
+- deactivates ACTIVE department with only INACTIVE sub-departments
+- throws when department does not exist
+- throws when department is already INACTIVE
+- throws when department has active sub-departments

package/src/modules/organization/docs/commands/DeactivateSite.md

@@ -0,0 +1,38 @@
+# DeactivateSite
+
+## Overview
+
+DeactivateSite transitions a site from ACTIVE to INACTIVE status. Inactive sites prevent new inventory movements and order references while preserving all historical data. This supports facility closure scenarios.
+
+## Business Rules
+
+- Site must exist
+- Site must be in ACTIVE status
+- Deactivation does not delete or modify historical transactions referencing the site
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Site exists?}
+    B -->|No| C[Return error: SITE_NOT_FOUND]
+    B -->|Yes| D{Site in ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Set status: INACTIVE]
+    F --> G[Return deactivated site]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SITE_NOT_FOUND**: Specified site ID does not exist
+- **INVALID_STATE**: Site is not in ACTIVE status
+
+## Test Cases
+
+- deactivates ACTIVE site
+- throws when site does not exist
+- throws when site is already INACTIVE

package/src/modules/organization/docs/commands/DeleteCompany.md

@@ -0,0 +1,50 @@
+# DeleteCompany
+
+## Overview
+
+DeleteCompany permanently removes a company record from the system. Only companies in DRAFT status can be deleted — ACTIVE and INACTIVE companies are preserved for audit and legal compliance. This supports cleanup of incomplete company records that are no longer needed.
+
+## Business Rules
+
+- Company must exist
+- Company must be in DRAFT status
+- ACTIVE and INACTIVE companies cannot be deleted
+- Company must not have any existing departments
+- Company must not have any existing sites
+- Deletion is permanent (hard delete)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Company exists?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Company in DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Has departments?}
+    F -->|Yes| G[Return error: HAS_DEPARTMENTS]
+    F -->|No| H{Has sites?}
+    H -->|Yes| I[Return error: HAS_SITES]
+    H -->|No| J[Delete company record]
+    J --> K[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Specified company ID does not exist
+- **INVALID_STATE**: Company is not in DRAFT status (ACTIVE or INACTIVE companies cannot be deleted)
+- **HAS_DEPARTMENTS**: Company has existing departments that must be removed first
+- **HAS_SITES**: Company has existing sites that must be removed first
+
+## Test Cases
+
+- deletes DRAFT company
+- throws when company does not exist
+- throws when company is ACTIVE
+- throws when company is INACTIVE
+- throws when company has existing departments
+- throws when company has existing sites

package/src/modules/organization/docs/commands/ReactivateCompany.md

@@ -0,0 +1,39 @@
+# ReactivateCompany
+
+## Overview
+
+ReactivateCompany transitions a company from INACTIVE back to ACTIVE status, allowing new transactions to be recorded against it. This supports scenarios where a previously inactive legal entity resumes operations.
+
+## Business Rules
+
+- Company must exist
+- Company must be in INACTIVE status
+- Reactivation restores the company to ACTIVE, enabling new transactional references
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Company exists?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Company in INACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Set status: ACTIVE]
+    F --> G[Return reactivated company]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Specified company ID does not exist
+- **INVALID_STATE**: Company is not in INACTIVE status
+
+## Test Cases
+
+- reactivates INACTIVE company
+- throws when company does not exist
+- throws when company is in DRAFT status
+- throws when company is already ACTIVE

package/src/modules/organization/docs/commands/ReactivateDepartment.md

@@ -0,0 +1,37 @@
+# ReactivateDepartment
+
+## Overview
+
+ReactivateDepartment transitions a department from INACTIVE back to ACTIVE status, restoring it for new operational assignments. This supports scenarios where a previously deactivated department is needed again.
+
+## Business Rules
+
+- Department must exist
+- Department must be in INACTIVE status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Department exists?}
+    B -->|No| C[Return error: DEPARTMENT_NOT_FOUND]
+    B -->|Yes| D{Department in INACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Set status: ACTIVE]
+    F --> G[Return reactivated department]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **DEPARTMENT_NOT_FOUND**: Specified department ID does not exist
+- **INVALID_STATE**: Department is not in INACTIVE status
+
+## Test Cases
+
+- reactivates INACTIVE department
+- throws when department does not exist
+- throws when department is already ACTIVE

package/src/modules/organization/docs/commands/ReactivateSite.md

@@ -0,0 +1,37 @@
+# ReactivateSite
+
+## Overview
+
+ReactivateSite transitions a site from INACTIVE back to ACTIVE status, making it available again for inventory and shipping operations. This supports facility reopening scenarios such as seasonal demand.
+
+## Business Rules
+
+- Site must exist
+- Site must be in INACTIVE status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Site exists?}
+    B -->|No| C[Return error: SITE_NOT_FOUND]
+    B -->|Yes| D{Site in INACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Set status: ACTIVE]
+    F --> G[Return reactivated site]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SITE_NOT_FOUND**: Specified site ID does not exist
+- **INVALID_STATE**: Site is not in INACTIVE status
+
+## Test Cases
+
+- reactivates INACTIVE site
+- throws when site does not exist
+- throws when site is already ACTIVE

package/src/modules/organization/docs/commands/UpdateCompany.md

@@ -0,0 +1,58 @@
+# UpdateCompany
+
+## Overview
+
+UpdateCompany modifies fields on an existing company. Updatable fields include legal name, tax identification number, registration number, registered address fields, and base currency (only while in DRAFT status). Base currency becomes immutable after activation.
+
+This command supports company configuration during DRAFT setup and ongoing maintenance of company details.
+
+## Business Rules
+
+- Company must exist
+- Legal name, if provided, must be non-empty
+- Base currency can only be changed while company is in DRAFT status
+- Base currency, if provided, must reference a valid active Currency from the primitives module
+- Address fields can be updated in any status (DRAFT, ACTIVE, INACTIVE)
+- Tax ID and registration number can be updated in any status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Company exists?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Legal name provided and empty?}
+    D -->|Yes| E[Return error: INVALID_LEGAL_NAME]
+    D -->|No| F{Base currency change requested?}
+    F -->|Yes| G{Company in DRAFT?}
+    G -->|No| H[Return error: CURRENCY_IMMUTABLE]
+    G -->|Yes| I{Currency exists and active?}
+    I -->|No| J[Return error: CURRENCY_NOT_FOUND]
+    I -->|Yes| K[Update company record]
+    F -->|No| K
+    K --> L[Return updated company]
+```
+
+## External Dependencies
+
+- [primitives::getCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validates that the referenced base currency exists and is active
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Specified company ID does not exist
+- **INVALID_LEGAL_NAME**: Legal name is empty
+- **CURRENCY_IMMUTABLE**: Attempted to change base currency on a non-DRAFT company
+- **CURRENCY_NOT_FOUND**: Referenced base currency does not exist or is inactive
+
+## Test Cases
+
+- updates legal name on DRAFT company
+- updates address fields on ACTIVE company
+- updates tax ID and registration number
+- throws when company does not exist
+- throws when legal name is empty
+- throws when changing base currency on ACTIVE company
+- throws when changing base currency on INACTIVE company
+- throws when new base currency does not exist
+- throws when new base currency is inactive
+- updates base currency on DRAFT company