@tailor-platform/erp-kit 0.3.0 → 0.4.0

package/src/modules/coa-management/query/listUnassignedAccounts.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseActiveAccount, baseDraftAccount } from "../testing/fixtures";
+import { run } from "./listUnassignedAccounts";
+
+describe("listUnassignedAccounts", () => {
+  it("returns unassigned active accounts in a CoA", async () => {
+    const unassignedAccount = { ...baseActiveAccount, accountGroupId: null };
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([unassignedAccount]);
+
+    const result = await run(db, { chartOfAccountsId: "coa-2" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([unassignedAccount]);
+    }
+  });
+
+  it("excludes accounts that are assigned to a group", async () => {
+    const { db, spies } = createMockDb<DB>();
+    // Only unassigned accounts returned by the query
+    spies.select.mockReturnValue([]);
+
+    const result = await run(db, { chartOfAccountsId: "coa-2" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([]);
+    }
+  });
+
+  it("excludes DRAFT accounts", async () => {
+    const { db, spies } = createMockDb<DB>();
+    // Query filters status = ACTIVE, so DRAFT accounts excluded
+    spies.select.mockReturnValue([]);
+
+    const result = await run(db, { chartOfAccountsId: "coa-2" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([]);
+    }
+  });
+
+  it("excludes INACTIVE accounts", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([]);
+
+    const result = await run(db, { chartOfAccountsId: "coa-2" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([]);
+    }
+  });
+
+  it("returns accounts sorted by code ascending", async () => {
+    const account1 = {
+      ...baseDraftAccount,
+      status: "ACTIVE" as const,
+      accountGroupId: null,
+      code: "1100",
+    };
+    const account2 = {
+      ...baseDraftAccount,
+      id: "account-6",
+      status: "ACTIVE" as const,
+      accountGroupId: null,
+      code: "1200",
+    };
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([account1, account2]);
+
+    const result = await run(db, { chartOfAccountsId: "coa-2" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([account1, account2]);
+    }
+  });
+
+  it("returns empty list when all active accounts are assigned", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([]);
+
+    const result = await run(db, { chartOfAccountsId: "coa-2" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([]);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+});

package/src/modules/coa-management/query/listUnassignedAccounts.ts

@@ -0,0 +1,39 @@
+import {
+  ok,
+  type ReadonlyDB,
+  type PaginationInput,
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+} from "../../../shared";
+import type { DB } from "../generated/kysely-tailordb";
+
+type UnassignedAccountOrderByField = "code" | "name" | "createdAt";
+
+export interface ListUnassignedAccountsInput extends PaginationInput<UnassignedAccountOrderByField> {
+  chartOfAccountsId: string;
+}
+
+/**
+ * Function: listUnassignedAccounts
+ *
+ * Lists active accounts within a CoA that are not assigned to any account group.
+ */
+export async function run(db: ReadonlyDB<DB>, input: ListUnassignedAccountsInput) {
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "code";
+  const orderDirection = input.orderDirection ?? "asc";
+
+  const accounts = await db
+    .selectFrom("Account")
+    .selectAll()
+    .where("chartOfAccountsId", "=", input.chartOfAccountsId)
+    .where("accountGroupId", "is", null)
+    .where("status", "=", "ACTIVE")
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+
+  return ok(buildPaginatedResult(accounts, limit));
+}

package/src/modules/coa-management/tailor.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig, definePlugins } from "@tailor-platform/sdk";
+import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
+import { enumConstantsPlugin } from "@tailor-platform/sdk/plugin/enum-constants";
+
+export default defineConfig({
+  name: "coa-management",
+  db: { "main-db": { files: [`./db/*.ts`, `./lib/_db_deps.ts`] } },
+});
+
+export const plugins = definePlugins(
+  kyselyTypePlugin({ distPath: `./generated/kysely-tailordb.ts` }),
+  enumConstantsPlugin({ distPath: "./generated/enums.ts" }),
+);

package/src/modules/coa-management/tailor.d.ts

@@ -0,0 +1,13 @@
+// This file is auto-generated by @tailor-platform/sdk
+// Do not edit this file manually
+// Regenerated automatically when running 'tailor-sdk apply' or 'tailor-sdk generate'
+
+declare module "@tailor-platform/sdk" {
+  interface AttributeMap {}
+  interface AttributeList {
+    __tuple?: [];
+  }
+  interface Env {}
+}
+
+export {};

package/src/modules/coa-management/testing/fixtures.ts

@@ -0,0 +1,201 @@
+import type { ChartOfAccounts, AccountGroup, Account, Schema } from "../lib/types";
+
+// ChartOfAccounts fixtures
+export const baseDraftCoa = {
+  id: "coa-1",
+  name: "Standard CoA",
+  description: "Standard chart of accounts",
+  companyId: "company-1",
+  baseCurrencyId: "currency-usd",
+  status: "DRAFT",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies ChartOfAccounts<Schema>;
+
+export const baseActiveCoa = {
+  id: "coa-2",
+  name: "Active CoA",
+  description: "Active chart of accounts",
+  companyId: "company-1",
+  baseCurrencyId: "currency-usd",
+  status: "ACTIVE",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies ChartOfAccounts<Schema>;
+
+export const baseArchivedCoa = {
+  id: "coa-3",
+  name: "Archived CoA",
+  description: "Archived chart of accounts",
+  companyId: "company-1",
+  baseCurrencyId: "currency-usd",
+  status: "ARCHIVED",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies ChartOfAccounts<Schema>;
+
+// AccountGroup fixtures
+export const baseRootGroup = {
+  id: "group-1",
+  code: "1000",
+  name: "Assets",
+  chartOfAccountsId: "coa-2",
+  parentAccountGroupId: null,
+  sortOrder: 1,
+  numberRangeStart: 1000,
+  numberRangeEnd: 1999,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AccountGroup<Schema>;
+
+export const baseChildGroup = {
+  id: "group-2",
+  code: "1100",
+  name: "Current Assets",
+  chartOfAccountsId: "coa-2",
+  parentAccountGroupId: "group-1",
+  sortOrder: 1,
+  numberRangeStart: 1100,
+  numberRangeEnd: 1199,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AccountGroup<Schema>;
+
+export const baseGrandchildGroup = {
+  id: "group-3",
+  code: "1110",
+  name: "Cash and Equivalents",
+  chartOfAccountsId: "coa-2",
+  parentAccountGroupId: "group-2",
+  sortOrder: 1,
+  numberRangeStart: 1110,
+  numberRangeEnd: 1119,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AccountGroup<Schema>;
+
+export const baseGroupNoRange = {
+  id: "group-4",
+  code: "2000",
+  name: "Liabilities",
+  chartOfAccountsId: "coa-2",
+  parentAccountGroupId: null,
+  sortOrder: 2,
+  numberRangeStart: null,
+  numberRangeEnd: null,
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies AccountGroup<Schema>;
+
+// Account fixtures
+export const baseDraftAccount = {
+  id: "account-1",
+  code: "1100",
+  name: "Cash",
+  accountType: "ASSET",
+  classification: "REGULAR",
+  chartOfAccountsId: "coa-2",
+  accountGroupId: null,
+  currencyRestriction: null,
+  reconciliation: false,
+  defaultTaxCode: null,
+  tags: null,
+  successorAccountId: null,
+  hasPostedTransactions: false,
+  status: "DRAFT",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Account<Schema>;
+
+export const baseActiveAccount = {
+  id: "account-2",
+  code: "1200",
+  name: "Accounts Receivable",
+  accountType: "ASSET",
+  classification: "RECEIVABLE",
+  chartOfAccountsId: "coa-2",
+  accountGroupId: "group-2",
+  currencyRestriction: null,
+  reconciliation: true,
+  defaultTaxCode: null,
+  tags: null,
+  successorAccountId: null,
+  hasPostedTransactions: false,
+  status: "ACTIVE",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Account<Schema>;
+
+export const baseInactiveAccount = {
+  id: "account-3",
+  code: "1300",
+  name: "Old Bank Account",
+  accountType: "ASSET",
+  classification: "BANK_CASH",
+  chartOfAccountsId: "coa-2",
+  accountGroupId: null,
+  currencyRestriction: null,
+  reconciliation: true,
+  defaultTaxCode: null,
+  tags: null,
+  successorAccountId: "account-2",
+  hasPostedTransactions: true,
+  status: "INACTIVE",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Account<Schema>;
+
+export const baseAccountWithPostedTransactions = {
+  id: "account-4",
+  code: "1400",
+  name: "Main Bank",
+  accountType: "ASSET",
+  classification: "BANK_CASH",
+  chartOfAccountsId: "coa-2",
+  accountGroupId: null,
+  currencyRestriction: null,
+  reconciliation: true,
+  defaultTaxCode: null,
+  tags: null,
+  successorAccountId: null,
+  hasPostedTransactions: true,
+  status: "ACTIVE",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Account<Schema>;
+
+export const baseRetainedEarningsAccount = {
+  id: "account-5",
+  code: "3100",
+  name: "Retained Earnings",
+  accountType: "EQUITY",
+  classification: "RETAINED_EARNINGS",
+  chartOfAccountsId: "coa-2",
+  accountGroupId: null,
+  currencyRestriction: null,
+  reconciliation: false,
+  defaultTaxCode: null,
+  tags: null,
+  successorAccountId: null,
+  hasPostedTransactions: false,
+  status: "ACTIVE",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+} as const satisfies Account<Schema>;
+
+// Company fixture (for cross-module validation)
+export const baseActiveCompany = {
+  id: "company-1",
+  legalName: "Test Corp",
+  baseCurrencyId: "currency-usd",
+  status: "ACTIVE",
+  taxId: null,
+  registrationNumber: null,
+  street: "123 Main St",
+  city: "New York",
+  state: "NY",
+  postalCode: "10001",
+  country: "US",
+  createdAt: new Date("2024-01-01T00:00:00.000Z"),
+  updatedAt: null,
+};

package/src/modules/item-management/README.md

@@ -29,7 +29,7 @@ Each item has its own lifecycle (DRAFT → ACTIVE ↔ INACTIVE), unique SKU iden
 - Sales price list and pricing rule management (pricing module)
 - Inventory tracking and stock levels (inventory module)
 - Lot and serial number management (inventory module)
-- Vendor/supplier management (supplier-management module)
+- Vendor/supplier management (business-partner module)
 - Bill of Materials (manufacturing module)
 - Product images and digital asset management
 

package/src/modules/organization/README.md

@@ -0,0 +1,57 @@
+# README
+
+## Overview
+
+The Organization module manages the foundational organizational structure of the ERP system — legal entities (companies), departments, and physical sites. It defines "who we are" and "where we operate" as the structural backbone that all transactional modules reference for scoping and context.
+
+Each company represents a legal entity with its own tax identity, registered address, and base currency assignment. Departments model the internal functional structure within a company, while sites represent the physical facilities (offices, warehouses, stores) where operations take place. Together, these entities provide the multi-company, multi-site foundation that downstream modules (accounting, sales, purchasing, inventory) depend on.
+
+## Key Features
+
+- **[Company Lifecycle](docs/features/company-lifecycle.md)**: Create and manage legal entities with lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE). Companies store legal name, tax ID, registration number, registered address, and base currency assignment. Fiscal calendar is owned by accounting
+- **[Department Management](docs/features/department-management.md)**: Create and manage departments within a company with self-referential hierarchy (parent department), unique code per company, and lifecycle state (ACTIVE/INACTIVE). Manager assignment is deferred to future HR/employee module
+- **[Site Management](docs/features/site-management.md)**: Manage physical sites/facilities owned by a company — offices, warehouses, stores, factories. Each site has a structured address, type classification, country, timezone, and lifecycle state. Warehouse storage layout (zones, bins, aisles) is owned by warehouse modules using separate `Warehouse`/`StorageLocation` entities
+
+## Module Scope
+
+### In Scope
+
+- Company/legal entity master data management (create, update, delete, status transitions)
+- Company lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE)
+- Tax identification number and registration number storage per company
+- Base currency assignment per company (currency master data owned by primitives module; organization stores only the company→currency reference)
+- Department CRUD with hierarchical parent-child structure
+- Department code uniqueness enforcement per company
+- Physical site management with structured addresses
+- Site type classification (office, warehouse, store, factory)
+- Site country and timezone assignment
+
+### Out of Scope
+
+- User account management and authentication (user-management module)
+- Employee profiles, HR attributes, and employment records (future HR/employee module)
+- Department manager assignment — requires employee/worker reference, not user ID (future HR/employee module)
+- Company-to-user membership and role mapping (future organization-membership or HR module)
+- Organizational hierarchy with multiple purposes and effective dates (future enhancement)
+- Business unit and division management for financial reporting (future accounting module)
+- Cost center and profit center management (future accounting module)
+- Fiscal calendar management — fiscal year, periods, cutoff dates (future accounting module)
+- Inter-company transaction configuration (future enhancement)
+- Warehouse storage layout — `Warehouse`/`StorageLocation` with zones, bins, aisles (future warehouse module; references organization `Site`)
+- Business partner addresses — billing, shipping (future business-partner module)
+
+### Scope Decision Rationale
+
+Organization is strictly scoped to **structural identity** — the legal, functional, and physical structure of the business. It answers "which legal entity?", "which department?", and "which site?" without owning any transactional or operational data.
+
+Company/legal entity is the root scoping entity. Nearly every transactional record in the ERP will carry a `companyId` referencing this module. This makes organization a foundational module that should remain stable and simple.
+
+Departments are included because they represent the internal functional structure that many modules reference (cost allocation, approval workflows, reporting). The self-referential hierarchy is sufficient for initial needs; a more flexible multi-purpose hierarchy system can be added later if required.
+
+Sites are included because physical facilities are referenced by inventory (stock holding), sales (ship-from), purchasing (delivery destination), and tax (jurisdiction). Organization owns the site identity and address; warehouse modules own the operational storage layout (`Warehouse`/`StorageLocation`) within a site.
+
+Employee/HR data is excluded because an employee is a business domain entity with its own lifecycle (hiring, termination, leave) that differs from organizational structure. A user account (user-management) is a login identity, an employee is an HR record, and a department membership is a structural assignment — these three concepts must remain separate. Consequently, department manager and company-to-user membership are also deferred: the manager of a department is an employee/worker, not a login identity, and membership requires an employee concept that this module does not own.
+
+## Module Dependencies
+
+- [primitives](../primitives/README.md) — Currency definitions for company base currency assignment

package/src/modules/organization/command/activateCompany.generated.ts

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { defineCommand } from "../../../shared";
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./activateCompany";
+
+export const activateCompany = defineCommand(permissions.activateCompany, run);

package/src/modules/organization/command/activateCompany.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  InvalidStateError,
+  MissingRequiredFieldsError,
+  InvalidBaseCurrencyError,
+} from "../lib/errors.generated";
+import {
+  draftCompany,
+  activeCompany,
+  inactiveCompany,
+  draftCompanyNoCurrency,
+} from "../testing/fixtures";
+import { getCurrency } from "../../primitives/query/getCurrency.generated";
+import { run } from "./activateCompany";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["organization:activateCompany"],
+};
+
+const deps = { getCurrency };
+
+describe("activateCompany", () => {
+  it("activates DRAFT company with all required fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const activatedCompany = { ...draftCompany, status: "ACTIVE" };
+    spies.select
+      .mockReturnValueOnce(draftCompany) // company lookup
+      .mockReturnValueOnce({ id: "currency-usd", isActive: true }); // getCurrency
+    spies.update.mockReturnValue(activatedCompany);
+
+    const result = await run(db, { companyId: draftCompany.id }, ctx, deps);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.company.status).toBe("ACTIVE");
+    }
+  });
+
+  it("throws when company does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { companyId: "nonexistent" }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CompanyNotFoundError);
+    }
+  });
+
+  it("throws when company is already ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(activeCompany);
+
+    const result = await run(db, { companyId: activeCompany.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("throws when company is INACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(inactiveCompany);
+
+    const result = await run(db, { companyId: inactiveCompany.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateError);
+    }
+  });
+
+  it("throws when legal name is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const companyNoLegalName = { ...draftCompany, legalName: "" };
+    spies.select.mockReturnValueOnce(companyNoLegalName);
+
+    const result = await run(db, { companyId: companyNoLegalName.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("throws when base currency is not assigned", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(draftCompanyNoCurrency);
+
+    const result = await run(db, { companyId: draftCompanyNoCurrency.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("throws when base currency references a non-existent Currency", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(draftCompany) // company lookup
+      .mockReturnValueOnce(undefined); // getCurrency returns null
+
+    const result = await run(db, { companyId: draftCompany.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidBaseCurrencyError);
+    }
+  });
+
+  it("throws when base currency references an inactive Currency", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(draftCompany) // company lookup
+      .mockReturnValueOnce({ id: "currency-usd", isActive: false }); // getCurrency inactive
+
+    const result = await run(db, { companyId: draftCompany.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidBaseCurrencyError);
+    }
+  });
+
+  it("throws when address street is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const companyNoStreet = { ...draftCompany, street: null };
+    spies.select.mockReturnValueOnce(companyNoStreet);
+
+    const result = await run(db, { companyId: companyNoStreet.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("throws when address city is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const companyNoCity = { ...draftCompany, city: null };
+    spies.select.mockReturnValueOnce(companyNoCity);
+
+    const result = await run(db, { companyId: companyNoCity.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("throws when address postalCode is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const companyNoPostalCode = { ...draftCompany, postalCode: null };
+    spies.select.mockReturnValueOnce(companyNoPostalCode);
+
+    const result = await run(db, { companyId: companyNoPostalCode.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+
+  it("throws when address country is missing", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const companyNoCountry = { ...draftCompany, country: null };
+    spies.select.mockReturnValueOnce(companyNoCountry);
+
+    const result = await run(db, { companyId: companyNoCountry.id }, ctx, deps);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(MissingRequiredFieldsError);
+    }
+  });
+});