@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/src/modules/primitives/docs/features/uom-categories.md

@@ -0,0 +1,52 @@
+# UoM Categories
+
+## Overview
+
+UoM Categories organize units of measure into logical groupings where conversions are meaningful. Each category has a designated reference unit that serves as the base for all conversion calculations within that category. Units can only be converted to other units within the same category.
+
+This feature enables businesses to define their measurement standards while maintaining mathematical consistency across all unit conversions.
+
+## Business Purpose
+
+Organizations need to track quantities in various units depending on context - purchasing in bulk units, selling in retail units, and managing inventory in standardized units. UoM Categories ensure that:
+
+- Conversions only occur between compatible units (you cannot convert kilograms to liters)
+- A single source of truth exists for conversion factors via the reference unit
+- New units can be added without updating relationships to every other unit
+- Mathematical precision is maintained through a single conversion path
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Category] --> B{Has Reference Unit?}
+    B -->|No| C[Create Reference Unit]
+    C --> D[Set as Category Reference]
+    B -->|Yes| E[Add Additional Units]
+    D --> E
+    E --> F[Define Conversion Factor]
+    F --> G{More Units?}
+    G -->|Yes| E
+    G -->|No| H[Category Ready]
+    H --> I[Products Can Reference Units]
+```
+
+## Scenario Patterns
+
+- **Initial Setup**: Administrator creates standard categories (Unit, Weight, Volume, Length, Time) with reference units during system initialization
+- **Industry-Specific Units**: Manufacturing adds custom units like "Pallet" or "Roll" to the Unit category with appropriate conversion factors
+- **Regional Adaptation**: Business operating in multiple regions adds both metric and imperial units to Weight and Length categories
+- **Precision Requirements**: Pharmaceutical company creates units with high decimal precision for precise dosage tracking
+
+## Test Cases
+
+- Creating a category without a reference unit should fail or prompt for reference unit creation
+- Setting a reference unit should automatically set its conversion factor to 1.0
+- Deleting a reference unit should be prevented if other units exist in the category
+- Category names must be unique within the system
+- Deactivating a category should prevent new products from using its units
+
+## Reference Links
+
+- [Odoo Units of Measure Documentation](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/product_management/configure/uom.html)
+- [ISO 80000 Quantities and Units Standard](https://www.iso.org/standard/76921.html)

package/src/modules/primitives/docs/models/Currency.md

@@ -0,0 +1,45 @@
+# Currency
+
+## Description
+
+Currency defines a monetary unit available for use across the ERP system. Each currency contains the ISO 4217 code, display symbol, name, and decimal precision. One currency is designated as the base currency for the organization, serving as the default for reporting and consolidation.
+
+Examples: USD (US Dollar), EUR (Euro), JPY (Japanese Yen).
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: create
+    Active --> Inactive: deactivate
+    Inactive --> Active: activate
+    note right of Active: Base currency cannot be deactivated
+```
+
+### Command Definitions
+
+- [createCurrency](../commands/CreateCurrency.md)
+- [activateCurrency](../commands/ActivateCurrency.md)
+- [deactivateCurrency](../commands/DeactivateCurrency.md)
+- [setBaseCurrency](../commands/SetBaseCurrency.md)
+
+### Models
+
+- Currency
+
+### Invariants
+
+- ISO 4217 code must be unique across all currencies
+- Only one currency can be designated as base currency
+- Base currency cannot be deactivated
+
+### Relationships
+
+- **Referenced By Exchange Rates**: Currency is referenced as source or target in ExchangeRate records
+- **Referenced By Transactions**: Currency is used in sales, purchase, and accounting transactions

package/src/modules/primitives/docs/models/ExchangeRate.md

@@ -0,0 +1,33 @@
+# ExchangeRate
+
+## Description
+
+ExchangeRate maintains the conversion ratio between a currency pair with an effective date. Each rate record specifies the source currency, target currency, rate value, and the date from which it applies. The system uses these rates to convert monetary amounts for transactions, reporting, and consolidation.
+
+Rates are date-based to support historical accuracy - a transaction from last month uses last month's rate, not today's rate.
+
+## Domain Model Definitions
+
+### Model type
+
+AppendOnly
+
+### Command Definitions
+
+- [createExchangeRate](../commands/CreateExchangeRate.md)
+- [convertAmount](../commands/ConvertAmount.md)
+
+### Models
+
+- ExchangeRate
+
+### Invariants
+
+- Rate must be a positive decimal value
+- Source and target currencies must be different
+- Effective date is required for all rate records
+
+### Relationships
+
+- **Belongs To Source Currency**: Each rate has exactly one source currency
+- **Belongs To Target Currency**: Each rate has exactly one target currency

package/src/modules/primitives/docs/models/Unit.md

@@ -0,0 +1,46 @@
+# Unit
+
+## Description
+
+Unit defines an individual unit of measure with its symbol, display name, and conversion factor relative to its category's reference unit. Units support configurable rounding precision for business operations.
+
+Examples: kg (kilogram), lb (pound), ea (each), dz (dozen).
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: create
+    Active --> Inactive: deactivate
+    Inactive --> Active: activate
+    note right of Active: Reference unit cannot be deactivated
+```
+
+### Command Definitions
+
+- [createUnit](../commands/CreateUnit.md)
+- [activateUnit](../commands/ActivateUnit.md)
+- [deactivateUnit](../commands/DeactivateUnit.md)
+- [convertQuantity](../commands/ConvertQuantity.md)
+
+### Models
+
+- Unit
+
+### Invariants
+
+- Conversion factor must be a positive value
+- Reference unit has conversion factor of 1.0
+- Symbol must be unique within the category
+- Reference unit cannot be deactivated
+
+### Relationships
+
+- **Belongs To Category**: Each unit belongs to exactly one UoMCategory
+- **May Be Reference Unit**: A unit may be designated as its category's reference unit

package/src/modules/primitives/docs/models/UoMCategory.md

@@ -0,0 +1,44 @@
+# UoMCategory
+
+## Description
+
+UoMCategory organizes units of measure into logical groupings where conversions are meaningful. Each category has a designated reference unit that serves as the base for all conversion calculations within that category. Units can only be converted to other units within the same category.
+
+Examples: Unit, Weight, Volume, Length, Time.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: create
+    Active --> Inactive: deactivate
+    Inactive --> Active: activate
+```
+
+### Command Definitions
+
+- [createCategory](../commands/CreateCategory.md)
+- [activateCategory](../commands/ActivateCategory.md)
+- [deactivateCategory](../commands/DeactivateCategory.md)
+- [setReferenceUnit](../commands/SetReferenceUnit.md)
+
+### Models
+
+- UoMCategory
+
+### Invariants
+
+- Category name must be unique
+- Reference unit must belong to this category
+- Category cannot be deactivated while it has active units
+
+### Relationships
+
+- **Has Many Units**: A category contains multiple units (one-to-many)
+- **Has One Reference Unit**: Each category designates one unit as the reference unit for conversions

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

@@ -0,0 +1,95 @@
+import {
+  type ColumnType,
+  Kysely,
+  type KyselyConfig,
+  type Transaction as KyselyTransaction,
+  type Insertable as KyselyInsertable,
+  type Selectable as KyselySelectable,
+  type Updateable as KyselyUpdateable,
+} from "kysely";
+import { TailordbDialect } from "@tailor-platform/function-kysely-tailordb";
+
+type Timestamp = ColumnType<Date, Date | string, Date | string>;
+type Generated<T> =
+  T extends ColumnType<infer S, infer I, infer U>
+    ? ColumnType<S, I | undefined, U>
+    : ColumnType<T, T | undefined, T>;
+
+export interface Namespace {
+  "main-db": {
+    Currency: {
+      id: Generated<string>;
+      code: string;
+      name: string;
+      symbol: string;
+      decimalPlaces: number;
+      isBaseCurrency: boolean;
+      isActive: boolean;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    };
+
+    ExchangeRate: {
+      id: Generated<string>;
+      sourceCurrencyId: string;
+      targetCurrencyId: string;
+      rate: number;
+      effectiveDate: Timestamp;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    };
+
+    Unit: {
+      id: Generated<string>;
+      name: string;
+      symbol: string;
+      categoryId: string;
+      conversionFactor: number;
+      roundingPrecision: number;
+      isActive: boolean;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    };
+
+    UoMCategory: {
+      id: Generated<string>;
+      name: string;
+      description: string | null;
+      referenceUnitId: string | null;
+      isActive: boolean;
+      createdAt: Generated<Timestamp>;
+      updatedAt: Timestamp | null;
+    };
+  };
+}
+
+export function getDB<const N extends keyof Namespace>(
+  namespace: N,
+  kyselyConfig?: Omit<KyselyConfig, "dialect">,
+): Kysely<Namespace[N]> {
+  const client = new tailordb.Client({ namespace });
+  return new Kysely<Namespace[N]>({
+    dialect: new TailordbDialect(client),
+    ...kyselyConfig,
+  });
+}
+
+export type DB<N extends keyof Namespace = keyof Namespace> = ReturnType<typeof getDB<N>>;
+
+export type Transaction<K extends keyof Namespace | DB = keyof Namespace> =
+  K extends DB<infer N>
+    ? KyselyTransaction<Namespace[N]>
+    : K extends keyof Namespace
+      ? KyselyTransaction<Namespace[K]>
+      : never;
+
+type TableName = {
+  [N in keyof Namespace]: keyof Namespace[N];
+}[keyof Namespace];
+export type Table<T extends TableName> = {
+  [N in keyof Namespace]: T extends keyof Namespace[N] ? Namespace[N][T] : never;
+}[keyof Namespace];
+
+export type Insertable<T extends keyof Namespace[keyof Namespace]> = KyselyInsertable<Table<T>>;
+export type Selectable<T extends keyof Namespace[keyof Namespace]> = KyselySelectable<Table<T>>;
+export type Updateable<T extends keyof Namespace[keyof Namespace]> = KyselyUpdateable<Table<T>>;

package/src/modules/primitives/index.ts

@@ -0,0 +1,40 @@
+export { defineModule } from "./module";
+export { permissions, own, all } from "./permissions";
+
+// errors
+export {
+  UoMCategoryNotFoundError,
+  UnitNotFoundError,
+  IncompatibleUnitsError,
+  InactiveUnitError,
+  CurrencyNotFoundError,
+  InactiveCurrencyError,
+  ExchangeRateNotFoundError,
+  CannotDeactivateReferenceUnitError,
+  CategoryNotActiveError,
+  DuplicateUnitSymbolError,
+  InvalidConversionFactorError,
+  InvalidRoundingPrecisionError,
+  DuplicateCategoryNameError,
+  CategoryHasActiveUnitsError,
+  UnitNotInCategoryError,
+  InvalidISOCodeError,
+  DuplicateCurrencyCodeError,
+  InvalidDecimalPlacesError,
+  CannotDeactivateBaseCurrencyError,
+  CannotSetInactiveAsBaseCurrencyError,
+  SameCurrencyPairError,
+  InvalidExchangeRateError,
+} from "./lib/errors";
+
+// input types
+export { type ConvertQuantityInput } from "./command/convertQuantity";
+export { type ActivateCategoryInput } from "./command/activateCategory";
+export { type DeactivateCategoryInput } from "./command/deactivateCategory";
+export { type SetReferenceUnitInput } from "./command/setReferenceUnit";
+export { type ActivateUnitInput } from "./command/activateUnit";
+export { type DeactivateUnitInput } from "./command/deactivateUnit";
+export { type ConvertAmountInput } from "./command/convertAmount";
+export { type ActivateCurrencyInput } from "./command/activateCurrency";
+export { type DeactivateCurrencyInput } from "./command/deactivateCurrency";
+export { type SetBaseCurrencyInput } from "./command/setBaseCurrency";

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

@@ -0,0 +1,138 @@
+import { createDomainError } from "../../shared/internal";
+
+export const UoMCategoryNotFoundError = createDomainError(
+  "UoMCategoryNotFoundError",
+  "UOM_CATEGORY_NOT_FOUND",
+  (identifier: string) => `UoM category not found: ${identifier}`,
+);
+
+export const UnitNotFoundError = createDomainError(
+  "UnitNotFoundError",
+  "UNIT_NOT_FOUND",
+  (symbol: string) => `Unit not found: ${symbol}`,
+);
+
+export const IncompatibleUnitsError = createDomainError(
+  "IncompatibleUnitsError",
+  "INCOMPATIBLE_UNITS",
+  (sourceSymbol: string, targetSymbol: string) =>
+    `Cannot convert between incompatible units: ${sourceSymbol} and ${targetSymbol} belong to different categories`,
+);
+
+export const InactiveUnitError = createDomainError(
+  "InactiveUnitError",
+  "INACTIVE_UNIT",
+  (symbol: string) => `Unit is inactive: ${symbol}`,
+);
+
+export const CurrencyNotFoundError = createDomainError(
+  "CurrencyNotFoundError",
+  "CURRENCY_NOT_FOUND",
+  (code: string) => `Currency not found: ${code}`,
+);
+
+export const InactiveCurrencyError = createDomainError(
+  "InactiveCurrencyError",
+  "INACTIVE_CURRENCY",
+  (code: string) => `Currency is inactive: ${code}`,
+);
+
+export const ExchangeRateNotFoundError = createDomainError(
+  "ExchangeRateNotFoundError",
+  "EXCHANGE_RATE_NOT_FOUND",
+  (sourceCode: string, targetCode: string, date: string) =>
+    `No exchange rate found for ${sourceCode} to ${targetCode} on or before ${date}`,
+);
+
+export const CannotDeactivateReferenceUnitError = createDomainError(
+  "CannotDeactivateReferenceUnitError",
+  "CANNOT_DEACTIVATE_REFERENCE_UNIT",
+  (unitId: string) => `Cannot deactivate reference unit: ${unitId}. Change reference unit first.`,
+);
+
+export const CategoryNotActiveError = createDomainError(
+  "CategoryNotActiveError",
+  "CATEGORY_NOT_ACTIVE",
+  (categoryId: string) => `Category is not active: ${categoryId}`,
+);
+
+export const DuplicateUnitSymbolError = createDomainError(
+  "DuplicateUnitSymbolError",
+  "DUPLICATE_UNIT_SYMBOL",
+  (symbol: string, categoryId: string) =>
+    `Unit with symbol "${symbol}" already exists in category ${categoryId}`,
+);
+
+export const InvalidConversionFactorError = createDomainError(
+  "InvalidConversionFactorError",
+  "INVALID_CONVERSION_FACTOR",
+  (factor: number) => `Conversion factor must be positive: ${factor}`,
+);
+
+export const InvalidRoundingPrecisionError = createDomainError(
+  "InvalidRoundingPrecisionError",
+  "INVALID_ROUNDING_PRECISION",
+  (precision: number) => `Rounding precision must be non-negative: ${precision}`,
+);
+
+export const DuplicateCategoryNameError = createDomainError(
+  "DuplicateCategoryNameError",
+  "DUPLICATE_CATEGORY_NAME",
+  (name: string) => `Category with name "${name}" already exists`,
+);
+
+export const CategoryHasActiveUnitsError = createDomainError(
+  "CategoryHasActiveUnitsError",
+  "CATEGORY_HAS_ACTIVE_UNITS",
+  (categoryId: string) => `Cannot deactivate category ${categoryId}: has active units`,
+);
+
+export const UnitNotInCategoryError = createDomainError(
+  "UnitNotInCategoryError",
+  "UNIT_NOT_IN_CATEGORY",
+  (unitId: string, categoryId: string) =>
+    `Unit ${unitId} does not belong to category ${categoryId}`,
+);
+
+export const InvalidISOCodeError = createDomainError(
+  "InvalidISOCodeError",
+  "INVALID_ISO_CODE",
+  (code: string) => `Invalid ISO 4217 code: "${code}". Must be exactly 3 uppercase letters.`,
+);
+
+export const DuplicateCurrencyCodeError = createDomainError(
+  "DuplicateCurrencyCodeError",
+  "DUPLICATE_CURRENCY_CODE",
+  (code: string) => `Currency with code "${code}" already exists`,
+);
+
+export const InvalidDecimalPlacesError = createDomainError(
+  "InvalidDecimalPlacesError",
+  "INVALID_DECIMAL_PLACES",
+  (decimalPlaces: number) => `Decimal places must be between 0 and 4: ${decimalPlaces}`,
+);
+
+export const CannotDeactivateBaseCurrencyError = createDomainError(
+  "CannotDeactivateBaseCurrencyError",
+  "CANNOT_DEACTIVATE_BASE_CURRENCY",
+  (currencyId: string) =>
+    `Cannot deactivate base currency: ${currencyId}. Change base currency first.`,
+);
+
+export const CannotSetInactiveAsBaseCurrencyError = createDomainError(
+  "CannotSetInactiveAsBaseCurrencyError",
+  "CANNOT_SET_INACTIVE_AS_BASE_CURRENCY",
+  (currencyId: string) => `Cannot set inactive currency as base: ${currencyId}. Activate it first.`,
+);
+
+export const SameCurrencyPairError = createDomainError(
+  "SameCurrencyPairError",
+  "SAME_CURRENCY_PAIR",
+  (currencyId: string) => `Source and target currency cannot be the same: ${currencyId}`,
+);
+
+export const InvalidExchangeRateError = createDomainError(
+  "InvalidExchangeRateError",
+  "INVALID_EXCHANGE_RATE",
+  (rate: number) => `Exchange rate must be positive: ${rate}`,
+);

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

@@ -0,0 +1,20 @@
+import type { InferSchema, Selectable, Insertable, Updateable } from "../../shared/internal";
+import type { DB } from "../generated/kysely-tailordb";
+
+export type Schema = InferSchema<DB>;
+
+export type UoMCategory<T extends { UoMCategory: object }> = Selectable<T["UoMCategory"]>;
+export type UoMCategoryCreate<T extends { UoMCategory: object }> = Insertable<T["UoMCategory"]>;
+export type UoMCategoryUpdate<T extends { UoMCategory: object }> = Updateable<T["UoMCategory"]>;
+
+export type Unit<T extends { Unit: object }> = Selectable<T["Unit"]>;
+export type UnitCreate<T extends { Unit: object }> = Insertable<T["Unit"]>;
+export type UnitUpdate<T extends { Unit: object }> = Updateable<T["Unit"]>;
+
+export type Currency<T extends { Currency: object }> = Selectable<T["Currency"]>;
+export type CurrencyCreate<T extends { Currency: object }> = Insertable<T["Currency"]>;
+export type CurrencyUpdate<T extends { Currency: object }> = Updateable<T["Currency"]>;
+
+export type ExchangeRate<T extends { ExchangeRate: object }> = Selectable<T["ExchangeRate"]>;
+export type ExchangeRateCreate<T extends { ExchangeRate: object }> = Insertable<T["ExchangeRate"]>;
+export type ExchangeRateUpdate<T extends { ExchangeRate: object }> = Updateable<T["ExchangeRate"]>;

package/src/modules/primitives/module.ts

@@ -0,0 +1,66 @@
+import { type TailorAnyDBField } from "@tailor-platform/sdk";
+import { type EmptyFields, type FieldsToInsertable } from "../shared/internal";
+import { makeCreateCategory } from "./command/createCategory";
+import { makeCreateCurrency } from "./command/createCurrency";
+import { makeCreateUnit } from "./command/createUnit";
+import { makeCreateExchangeRate } from "./command/createExchangeRate";
+import { activateCategory } from "./command/activateCategory";
+import { deactivateCategory } from "./command/deactivateCategory";
+import { activateUnit } from "./command/activateUnit";
+import { deactivateUnit } from "./command/deactivateUnit";
+import { setReferenceUnit } from "./command/setReferenceUnit";
+import { convertQuantity } from "./command/convertQuantity";
+import { activateCurrency } from "./command/activateCurrency";
+import { deactivateCurrency } from "./command/deactivateCurrency";
+import { setBaseCurrency } from "./command/setBaseCurrency";
+import { convertAmount } from "./command/convertAmount";
+import { createUoMCategoryType, CreateUoMCategoryTypeParams } from "./db/uomCategory";
+import { createUnitType, CreateUnitTypeParams } from "./db/unit";
+import { createCurrencyType, CreateCurrencyTypeParams } from "./db/currency";
+import { createExchangeRateType, CreateExchangeRateTypeParams } from "./db/exchangeRate";
+
+export interface DefineModuleParams<
+  CatF extends Record<string, TailorAnyDBField>,
+  UnitF extends Record<string, TailorAnyDBField>,
+  CurF extends Record<string, TailorAnyDBField>,
+  ERF extends Record<string, TailorAnyDBField>,
+> {
+  uomCategory?: CreateUoMCategoryTypeParams<CatF>;
+  unit?: CreateUnitTypeParams<UnitF>;
+  currency?: CreateCurrencyTypeParams<CurF>;
+  exchangeRate?: CreateExchangeRateTypeParams<ERF>;
+}
+
+export const defineModule = <
+  const CatF extends Record<string, TailorAnyDBField> = EmptyFields,
+  const UnitF extends Record<string, TailorAnyDBField> = EmptyFields,
+  const CurF extends Record<string, TailorAnyDBField> = EmptyFields,
+  const ERF extends Record<string, TailorAnyDBField> = EmptyFields,
+>(
+  params: DefineModuleParams<CatF, UnitF, CurF, ERF>,
+) => {
+  const uomCategory = createUoMCategoryType(params.uomCategory ?? {});
+  const unit = createUnitType(params.unit ?? {});
+  const currency = createCurrencyType(params.currency ?? {});
+  const exchangeRate = createExchangeRateType(params.exchangeRate ?? {});
+
+  return {
+    db: { uomCategory, unit, currency, exchangeRate },
+    commands: {
+      createCategory: makeCreateCategory<FieldsToInsertable<CatF>, FieldsToInsertable<UnitF>>(),
+      createCurrency: makeCreateCurrency<FieldsToInsertable<CurF>>(),
+      createUnit: makeCreateUnit<FieldsToInsertable<UnitF>>(),
+      createExchangeRate: makeCreateExchangeRate<FieldsToInsertable<ERF>>(),
+      activateCategory,
+      deactivateCategory,
+      activateUnit,
+      deactivateUnit,
+      setReferenceUnit,
+      convertQuantity,
+      activateCurrency,
+      deactivateCurrency,
+      setBaseCurrency,
+      convertAmount,
+    },
+  };
+};

package/src/modules/primitives/permissions.ts

@@ -0,0 +1,18 @@
+import { definePermissions } from "../shared/internal";
+
+export const { permissions, own, all } = definePermissions("primitives", [
+  "convertQuantity",
+  "createCategory",
+  "activateCategory",
+  "deactivateCategory",
+  "setReferenceUnit",
+  "createUnit",
+  "activateUnit",
+  "deactivateUnit",
+  "convertAmount",
+  "createCurrency",
+  "activateCurrency",
+  "deactivateCurrency",
+  "setBaseCurrency",
+  "createExchangeRate",
+] as const);

package/src/modules/primitives/tailor.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
+
+export default defineConfig({
+  name: "primitives",
+  db: { "main-db": { files: [`./src/db/*.ts`] } },
+});
+
+export const generators = defineGenerators(
+  ["@tailor-platform/kysely-type", { distPath: `./src/generated/kysely-tailordb.ts` }],
+  ["@tailor-platform/enum-constants", { distPath: "./src/generated/enums.ts" }],
+);