@tailor-platform/erp-kit 0.3.0 → 0.4.0

package/src/modules/organization/docs/queries/GetDepartment.md

@@ -0,0 +1,44 @@
+# GetDepartment
+
+## Overview
+
+GetDepartment retrieves a single department by its unique identifier or by its company-scoped code. Returns the full department record including status, code, name, company reference, and parent department reference, or null if no matching department exists.
+
+## Business Rules
+
+- Lookup by `id` performs an exact UUID match
+- Lookup by `code` + `companyId` performs a compound match (code is unique per company, not globally)
+- Returns the full department record including status, code, name, companyId, and parentDepartmentId
+- Does not filter by status — returns both ACTIVE and INACTIVE departments
+- Exactly one lookup mode must be used: `id` alone, or `code` + `companyId` together
+- Returns null when no matching department is found
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup request] --> B{Lookup by id or code?}
+    B -->|id| C[Query Department by id]
+    B -->|code + companyId| D[Query Department by code and companyId]
+    C --> E{Found?}
+    D --> E
+    E -->|Yes| F[Return department]
+    E -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- None (returns null when not found instead of throwing)
+
+## Test Cases
+
+- returns department when found by id
+- returns department when found by code and companyId
+- returns null when department not found by id
+- returns null when department not found by code
+- returns ACTIVE department
+- returns INACTIVE department

package/src/modules/organization/docs/queries/GetDepartmentChildren.md

@@ -0,0 +1,40 @@
+# GetDepartmentChildren
+
+## Overview
+
+GetDepartmentChildren retrieves the direct child departments of a given parent department. Returns a list of departments whose parentDepartmentId matches the specified department ID. This supports organizational tree navigation and hierarchy display.
+
+## Business Rules
+
+- Returns only direct children (one level deep), not the full subtree
+- Returns both ACTIVE and INACTIVE child departments by default
+- An optional `status` filter can restrict results to a specific status
+- Returns an empty list if the department has no children
+- The parent department itself is not included in the results
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive request with departmentId] --> B[Query departments where parentDepartmentId = departmentId]
+    B --> C{Status filter provided?}
+    C -->|Yes| D[Filter by status]
+    C -->|No| E[Return all children]
+    D --> E
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- None (returns empty list when no children found)
+
+## Test Cases
+
+- returns direct children of department
+- returns empty list when department has no children
+- filters children by ACTIVE status
+- filters children by INACTIVE status
+- does not return grandchildren

package/src/modules/organization/docs/queries/GetSite.md

@@ -0,0 +1,37 @@
+# GetSite
+
+## Overview
+
+GetSite retrieves a single site by its unique identifier. Returns the full site record including status, name, type, address, timezone, and company reference, or null if no matching site exists.
+
+## Business Rules
+
+- Lookup by `id` performs an exact UUID match
+- Returns the full site record including status, name, type, address fields, country, timezone, and companyId
+- Does not filter by status — returns both ACTIVE and INACTIVE sites
+- Returns null when no matching site is found
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup request] --> B[Query Site by id]
+    B --> C{Found?}
+    C -->|Yes| D[Return site]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- None (returns null when not found instead of throwing)
+
+## Test Cases
+
+- returns site when found by id
+- returns null when site not found
+- returns ACTIVE site
+- returns INACTIVE site

package/src/modules/organization/docs/queries/ListDepartmentsByCompany.md

@@ -0,0 +1,54 @@
+# ListDepartmentsByCompany
+
+## Overview
+
+ListDepartmentsByCompany retrieves departments belonging to a specific company with paginated results. Returns a paginated list of department records for the given companyId. This supports organizational structure display, department selection UIs, and operations that need to enumerate departments within a company.
+
+## Business Rules
+
+- companyId is required
+- Returns departments for the specified company regardless of status by default
+- Results are paginated using offset/limit (default page size applies)
+- An optional `status` filter can restrict results to ACTIVE or INACTIVE departments
+- An optional `parentDepartmentId` filter can restrict results to departments under a specific parent (null for top-level only)
+- Returns an empty list if the company has no departments
+- Results are ordered by department name by default; sortable by name, code, or createdAt
+- `hasNextPage` indicates whether more results exist beyond the current page
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive request with companyId] --> B[Query departments where companyId matches]
+    B --> C{Status filter provided?}
+    C -->|Yes| D[Filter by status]
+    C -->|No| E[Continue]
+    D --> E
+    E --> F{parentDepartmentId filter provided?}
+    F -->|Yes| G[Filter by parentDepartmentId]
+    F -->|No| H[Continue]
+    G --> H
+    H --> I[Order by name]
+    I --> I2[Apply limit+1 / offset pagination]
+    I2 --> J[Return paginated department list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- None (returns empty list when no departments found)
+
+## Test Cases
+
+- returns departments for a company
+- returns empty list when no departments exist
+- filters by status when provided
+- filters by parentDepartmentId when provided
+- filters root departments when parentDepartmentId is null
+- filters departments by INACTIVE status
+- returns departments ordered by name
+- returns hasNextPage true when more results exist
+- respects limit parameter

package/src/modules/organization/docs/queries/ListSitesByCompany.md

@@ -0,0 +1,54 @@
+# ListSitesByCompany
+
+## Overview
+
+ListSitesByCompany retrieves sites belonging to a specific company with paginated results. Returns a paginated list of site records for the given companyId. This supports multi-site operations where facilities for a company need to be displayed or processed.
+
+## Business Rules
+
+- companyId is required
+- Returns sites for the specified company regardless of status by default
+- Results are paginated using offset/limit (default page size applies)
+- An optional `status` filter can restrict results to ACTIVE or INACTIVE sites
+- An optional `type` filter can restrict results to a specific site type (e.g., OFFICE, WAREHOUSE, STORE, FACTORY, DISTRIBUTION_CENTER)
+- Returns an empty list if the company has no sites
+- Results are ordered by site name by default; sortable by name, type, or createdAt
+- `hasNextPage` indicates whether more results exist beyond the current page
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive request with companyId] --> B[Query sites where companyId matches]
+    B --> C{Status filter provided?}
+    C -->|Yes| D[Filter by status]
+    C -->|No| E[Continue]
+    D --> E
+    E --> F{Type filter provided?}
+    F -->|Yes| G[Filter by type]
+    F -->|No| H[Continue]
+    G --> H
+    H --> I[Order by name]
+    I --> I2[Apply limit+1 / offset pagination]
+    I2 --> J[Return paginated site list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- None (returns empty list when no sites found)
+
+## Test Cases
+
+- returns sites for a company
+- returns empty list when no sites exist
+- filters by status when provided
+- filters by type when provided
+- filters sites by INACTIVE status
+- combines status and type filters
+- returns sites ordered by name
+- returns hasNextPage true when more results exist
+- respects limit parameter

package/src/modules/organization/generated/kysely-tailordb.ts

@@ -0,0 +1,77 @@
+import {
+  createGetDB,
+  type Generated,
+  type Timestamp,
+  type NamespaceDB,
+  type NamespaceInsertable,
+  type NamespaceSelectable,
+  type NamespaceTable,
+  type NamespaceTableName,
+  type NamespaceTransaction,
+  type NamespaceUpdateable,
+} from "@tailor-platform/sdk/kysely";
+
+export interface Namespace {
+  "main-db": {
+    Company: {
+      id: Generated<string>;
+      legalName: string;
+      taxId: string | null;
+      registrationNumber: string | null;
+      baseCurrencyId: string | null;
+      street: string | null;
+      city: string | null;
+      state: string | null;
+      postalCode: string | null;
+      country: string | null;
+      status: string;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    Department: {
+      id: Generated<string>;
+      code: string;
+      name: string;
+      companyId: string;
+      parentDepartmentId: string | null;
+      status: string;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    Site: {
+      id: Generated<string>;
+      name: string;
+      type: string;
+      companyId: string;
+      street: string;
+      city: string;
+      state: string | null;
+      postalCode: string;
+      country: string;
+      timezone: string;
+      status: string;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    }
+
+    Currency: {
+      id: Generated<string>;
+    }
+  }
+}
+
+export const getDB = createGetDB<Namespace>();
+
+export type DB<N extends keyof Namespace = keyof Namespace> = NamespaceDB<Namespace, N>;
+
+export type Transaction<K extends keyof Namespace | DB = keyof Namespace> =
+  NamespaceTransaction<Namespace, K>;
+
+type TableName = NamespaceTableName<Namespace>;
+export type Table<T extends TableName> = NamespaceTable<Namespace, T>;
+
+export type Insertable<T extends TableName> = NamespaceInsertable<Namespace, T>;
+export type Selectable<T extends TableName> = NamespaceSelectable<Namespace, T>;
+export type Updateable<T extends TableName> = NamespaceUpdateable<Namespace, T>;

package/src/modules/organization/index.ts

@@ -0,0 +1,2 @@
+export { defineModule } from "./module";
+export { permissions, own, all } from "./lib/permissions.generated";

package/src/modules/organization/lib/_db_deps.ts

@@ -0,0 +1,10 @@
+import {
+  db,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+
+export const currency = db
+  .type("Currency", {})
+  .permission(unsafeAllowAllTypePermission)
+  .gqlPermission(unsafeAllowAllGqlPermission);

package/src/modules/organization/lib/errors.generated.ts

@@ -0,0 +1,117 @@
+// @generated — do not edit
+import { createDomainError } from "../../../shared";
+
+export const CompanyNotFoundError = createDomainError(
+  "CompanyNotFoundError", "ORGANIZATION_COMPANY_NOT_FOUND",
+  (identifier: string) => `Specified company ID does not exist: ${identifier}`,
+);
+
+export const InvalidStateError = createDomainError(
+  "InvalidStateError", "ORGANIZATION_INVALID_STATE",
+  (identifier: string) => `Entity is not in the expected status: ${identifier}`,
+);
+
+export const MissingRequiredFieldsError = createDomainError(
+  "MissingRequiredFieldsError", "ORGANIZATION_MISSING_REQUIRED_FIELDS",
+  (identifier: string) => `One or more required fields are not set: ${identifier}`,
+);
+
+export const InvalidBaseCurrencyError = createDomainError(
+  "InvalidBaseCurrencyError", "ORGANIZATION_INVALID_BASE_CURRENCY",
+  (identifier: string) => `The assigned base currency does not exist or is not in active status in the primitives module: ${identifier}`,
+);
+
+export const InvalidLegalNameError = createDomainError(
+  "InvalidLegalNameError", "ORGANIZATION_INVALID_LEGAL_NAME",
+  (identifier: string) => `Legal name is empty or not provided: ${identifier}`,
+);
+
+export const CurrencyNotFoundError = createDomainError(
+  "CurrencyNotFoundError", "ORGANIZATION_CURRENCY_NOT_FOUND",
+  (identifier: string) => `Referenced base currency does not exist or is inactive: ${identifier}`,
+);
+
+export const InvalidCodeError = createDomainError(
+  "InvalidCodeError", "ORGANIZATION_INVALID_CODE",
+  (identifier: string) => `Department code is empty or not provided: ${identifier}`,
+);
+
+export const InvalidNameError = createDomainError(
+  "InvalidNameError", "ORGANIZATION_INVALID_NAME",
+  (identifier: string) => `Name is empty or not provided: ${identifier}`,
+);
+
+export const DuplicateCodeError = createDomainError(
+  "DuplicateCodeError", "ORGANIZATION_DUPLICATE_CODE",
+  (identifier: string) => `Department with same code already exists in the same company: ${identifier}`,
+);
+
+export const ParentNotFoundError = createDomainError(
+  "ParentNotFoundError", "ORGANIZATION_PARENT_NOT_FOUND",
+  (identifier: string) => `Referenced parent department does not exist or belongs to a different company: ${identifier}`,
+);
+
+export const InvalidTypeError = createDomainError(
+  "InvalidTypeError", "ORGANIZATION_INVALID_TYPE",
+  (identifier: string) => `Site type is not one of the allowed classifications: ${identifier}`,
+);
+
+export const CompanyInactiveError = createDomainError(
+  "CompanyInactiveError", "ORGANIZATION_COMPANY_INACTIVE",
+  (identifier: string) => `Referenced company is not in ACTIVE status: ${identifier}`,
+);
+
+export const DuplicateNameError = createDomainError(
+  "DuplicateNameError", "ORGANIZATION_DUPLICATE_NAME",
+  (identifier: string) => `Site with same name already exists in the same company: ${identifier}`,
+);
+
+export const InvalidCountryError = createDomainError(
+  "InvalidCountryError", "ORGANIZATION_INVALID_COUNTRY",
+  (identifier: string) => `Country code is not a valid country code: ${identifier}`,
+);
+
+export const InvalidTimezoneError = createDomainError(
+  "InvalidTimezoneError", "ORGANIZATION_INVALID_TIMEZONE",
+  (identifier: string) => `Timezone is not a valid IANA timezone identifier: ${identifier}`,
+);
+
+export const DepartmentNotFoundError = createDomainError(
+  "DepartmentNotFoundError", "ORGANIZATION_DEPARTMENT_NOT_FOUND",
+  (identifier: string) => `Specified department ID does not exist: ${identifier}`,
+);
+
+export const HasActiveChildrenError = createDomainError(
+  "HasActiveChildrenError", "ORGANIZATION_HAS_ACTIVE_CHILDREN",
+  (identifier: string) => `Department has one or more active sub-departments: ${identifier}`,
+);
+
+export const SiteNotFoundError = createDomainError(
+  "SiteNotFoundError", "ORGANIZATION_SITE_NOT_FOUND",
+  (identifier: string) => `Specified site ID does not exist: ${identifier}`,
+);
+
+export const HasDepartmentsError = createDomainError(
+  "HasDepartmentsError", "ORGANIZATION_HAS_DEPARTMENTS",
+  (identifier: string) => `Company has existing departments that must be removed first: ${identifier}`,
+);
+
+export const HasSitesError = createDomainError(
+  "HasSitesError", "ORGANIZATION_HAS_SITES",
+  (identifier: string) => `Company has existing sites that must be removed first: ${identifier}`,
+);
+
+export const CurrencyImmutableError = createDomainError(
+  "CurrencyImmutableError", "ORGANIZATION_CURRENCY_IMMUTABLE",
+  (identifier: string) => `Attempted to change base currency on a non-DRAFT company: ${identifier}`,
+);
+
+export const SelfReferenceError = createDomainError(
+  "SelfReferenceError", "ORGANIZATION_SELF_REFERENCE",
+  (identifier: string) => `Department references itself as parent: ${identifier}`,
+);
+
+export const CircularReferenceError = createDomainError(
+  "CircularReferenceError", "ORGANIZATION_CIRCULAR_REFERENCE",
+  (identifier: string) => `Reparenting would create a circular hierarchy: ${identifier}`,
+);

package/src/modules/organization/lib/errors.ts

@@ -0,0 +1 @@
+// Hand-written domain error extensions (if needed)

package/src/modules/organization/lib/permissions.generated.ts

@@ -0,0 +1,19 @@
+// @generated — do not edit
+import { definePermissions } from "../../../shared";
+
+export const { permissions, own, all } = definePermissions("organization", [
+  "activateCompany",
+  "createCompany",
+  "createDepartment",
+  "createSite",
+  "deactivateCompany",
+  "deactivateDepartment",
+  "deactivateSite",
+  "deleteCompany",
+  "reactivateCompany",
+  "reactivateDepartment",
+  "reactivateSite",
+  "updateCompany",
+  "updateDepartment",
+  "updateSite",
+] as const);

package/src/modules/organization/lib/types.ts

@@ -0,0 +1,16 @@
+import type { InferSchema, Selectable, Insertable, Updateable } from "../../../shared";
+import type { DB } from "../generated/kysely-tailordb";
+
+export type Schema = InferSchema<DB>;
+
+export type Company<T extends { Company: object }> = Selectable<T["Company"]>;
+export type CompanyCreate<T extends { Company: object }> = Insertable<T["Company"]>;
+export type CompanyUpdate<T extends { Company: object }> = Updateable<T["Company"]>;
+
+export type Site<T extends { Site: object }> = Selectable<T["Site"]>;
+export type SiteCreate<T extends { Site: object }> = Insertable<T["Site"]>;
+export type SiteUpdate<T extends { Site: object }> = Updateable<T["Site"]>;
+
+export type Department<T extends { Department: object }> = Selectable<T["Department"]>;
+export type DepartmentCreate<T extends { Department: object }> = Insertable<T["Department"]>;
+export type DepartmentUpdate<T extends { Department: object }> = Updateable<T["Department"]>;

package/src/modules/organization/module.ts

@@ -0,0 +1,89 @@
+import { type TailorAnyDBField } from "@tailor-platform/sdk";
+import { type EmptyFields, type FieldsToInsertable } from "../../shared";
+import type { defineModule as definePrimitivesModule } from "../primitives";
+import { createCompany } from "./command/createCompany.generated";
+import { updateCompany } from "./command/updateCompany.generated";
+import { activateCompany } from "./command/activateCompany.generated";
+import { deactivateCompany } from "./command/deactivateCompany.generated";
+import { reactivateCompany } from "./command/reactivateCompany.generated";
+import { deleteCompany } from "./command/deleteCompany.generated";
+import { createSite } from "./command/createSite.generated";
+import { updateSite } from "./command/updateSite.generated";
+import { deactivateSite } from "./command/deactivateSite.generated";
+import { reactivateSite } from "./command/reactivateSite.generated";
+import { createDepartment } from "./command/createDepartment.generated";
+import { updateDepartment } from "./command/updateDepartment.generated";
+import { deactivateDepartment } from "./command/deactivateDepartment.generated";
+import { reactivateDepartment } from "./command/reactivateDepartment.generated";
+import { getCompany } from "./query/getCompany.generated";
+import { getDepartment } from "./query/getDepartment.generated";
+import { getDepartmentChildren } from "./query/getDepartmentChildren.generated";
+import { detectDepartmentCircularReference } from "./query/detectDepartmentCircularReference.generated";
+import { getSite } from "./query/getSite.generated";
+import { listDepartmentsByCompany } from "./query/listDepartmentsByCompany.generated";
+import { listSitesByCompany } from "./query/listSitesByCompany.generated";
+import { createCompanyType, type CreateCompanyTypeParams } from "./db/company";
+import { createSiteType, type CreateSiteTypeParams } from "./db/site";
+import { createDepartmentType, type CreateDepartmentTypeParams } from "./db/department";
+
+type PrimitivesModule = ReturnType<typeof definePrimitivesModule>;
+type PrimitivesDB = PrimitivesModule["db"];
+export type PrimitivesQueries = PrimitivesModule["queries"];
+
+export interface DefineModuleParams<
+  CF extends Record<string, TailorAnyDBField>,
+  SF extends Record<string, TailorAnyDBField>,
+  DF extends Record<string, TailorAnyDBField>,
+> {
+  company?: CreateCompanyTypeParams<CF>;
+  site?: CreateSiteTypeParams<SF>;
+  department?: CreateDepartmentTypeParams<DF>;
+  primitives: {
+    db: { currency: PrimitivesDB["currency"] };
+    queries: Pick<PrimitivesQueries, "getCurrency">;
+  };
+}
+
+export const defineModule = <
+  const CF extends Record<string, TailorAnyDBField> = EmptyFields,
+  const SF extends Record<string, TailorAnyDBField> = EmptyFields,
+  const DF extends Record<string, TailorAnyDBField> = EmptyFields,
+>(
+  params: DefineModuleParams<CF, SF, DF>,
+) => {
+  const company = createCompanyType({
+    ...params.company,
+    currencyType: params.primitives.db.currency,
+  });
+  const site = createSiteType(params.site ?? {});
+  const department = createDepartmentType(params.department ?? {});
+
+  return {
+    db: { company, site, department },
+    commands: {
+      createCompany: createCompany<FieldsToInsertable<CF>>(params.primitives.queries),
+      updateCompany: updateCompany<FieldsToInsertable<CF>>(params.primitives.queries),
+      activateCompany: activateCompany(params.primitives.queries),
+      deactivateCompany: deactivateCompany(),
+      reactivateCompany: reactivateCompany(),
+      deleteCompany: deleteCompany(),
+      createSite: createSite<FieldsToInsertable<SF>>(),
+      updateSite: updateSite<FieldsToInsertable<SF>>(),
+      deactivateSite: deactivateSite(),
+      reactivateSite: reactivateSite(),
+      createDepartment: createDepartment<FieldsToInsertable<DF>>(),
+      updateDepartment: updateDepartment<FieldsToInsertable<DF>>(),
+      deactivateDepartment: deactivateDepartment(),
+      reactivateDepartment: reactivateDepartment(),
+    },
+    queries: {
+      getCompany,
+      getDepartment,
+      getDepartmentChildren,
+      detectDepartmentCircularReference,
+      getSite,
+      listDepartmentsByCompany,
+      listSitesByCompany,
+    },
+  };
+};

package/src/modules/organization/permissions.ts

@@ -0,0 +1,3 @@
+import { definePermissions } from "../../shared";
+
+export const { permissions, own, all } = definePermissions("organization", [] as const);

package/src/modules/organization/query/detectDepartmentCircularReference.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "../../../shared";
+import { run } from "./detectDepartmentCircularReference";
+
+export const detectDepartmentCircularReference = defineQuery(run);