@tailor-platform/erp-kit 0.2.2 → 0.4.0

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

@@ -0,0 +1,92 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  CompanyNotFoundError,
+  InvalidStateError,
+  MissingRequiredFieldsError,
+  InvalidBaseCurrencyError,
+} from "../lib/errors.generated";
+import type { PrimitivesQueries } from "../module";
+
+export interface ActivateCompanyInput {
+  companyId: string;
+}
+
+/**
+ * Function: 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.
+ */
+export async function run(
+  db: Transaction,
+  input: ActivateCompanyInput,
+  ctx: CommandContext,
+  primitivesQueries?: Pick<PrimitivesQueries, "getCurrency">,
+) {
+  const { companyId } = input;
+
+  // 1. Find company with forUpdate
+  const existing = await db
+    .selectFrom("Company")
+    .selectAll()
+    .where("id", "=", companyId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new CompanyNotFoundError(companyId));
+  }
+
+  // 2. Must be DRAFT
+  if (existing.status !== "DRAFT") {
+    return err(new InvalidStateError(companyId));
+  }
+
+  // 3. Check required fields
+  if (
+    !existing.legalName ||
+    (typeof existing.legalName === "string" && existing.legalName.trim() === "")
+  ) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+  if (!existing.baseCurrencyId) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+  if (!existing.street) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+  if (!existing.city) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+  if (!existing.postalCode) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+  if (!existing.country) {
+    return err(new MissingRequiredFieldsError(companyId));
+  }
+
+  // 4. Validate base currency exists and is active
+  if (primitivesQueries) {
+    const { currency } = (
+      await primitivesQueries.getCurrency(db, { id: existing.baseCurrencyId }, ctx)
+    ).value;
+    if (!currency?.isActive) {
+      return err(new InvalidBaseCurrencyError(companyId));
+    }
+  }
+
+  // 5. Set status ACTIVE
+  const company = await db
+    .updateTable("Company")
+    .set({
+      status: "ACTIVE",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", companyId)
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ company: company! });
+}

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

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

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

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { InvalidLegalNameError, CurrencyNotFoundError } from "../lib/errors.generated";
+import { draftCompany } from "../testing/fixtures";
+import { getCurrency } from "../../primitives/query/getCurrency.generated";
+import { run } from "./createCompany";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["organization:createCompany"],
+};
+
+describe("createCompany", () => {
+  it("creates company in DRAFT status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const activeCurrency = { id: "currency-usd", isActive: true };
+    const createdCompany = { ...draftCompany, id: "new-company-id" };
+    spies.select.mockReturnValueOnce(activeCurrency); // getCurrency lookup
+    spies.insert.mockReturnValue(createdCompany);
+
+    const result = await run(
+      db,
+      {
+        legalName: "Acme Corp",
+        baseCurrencyId: "currency-usd",
+      },
+      ctx,
+      { getCurrency },
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.company.status).toBe("DRAFT");
+    }
+  });
+
+  it("throws when legal name is empty", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, { legalName: "" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidLegalNameError);
+    }
+  });
+
+  it("throws when referenced currency does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // getCurrency lookup returns null
+
+    const result = await run(
+      db,
+      {
+        legalName: "Acme Corp",
+        baseCurrencyId: "nonexistent-currency",
+      },
+      ctx,
+      { getCurrency },
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CurrencyNotFoundError);
+    }
+  });
+
+  it("throws when referenced currency is inactive", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce({ id: "inactive-currency", isActive: false });
+
+    const result = await run(
+      db,
+      {
+        legalName: "Acme Corp",
+        baseCurrencyId: "inactive-currency",
+      },
+      ctx,
+      { getCurrency },
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CurrencyNotFoundError);
+    }
+  });
+
+  it("creates company without base currency", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdCompany = {
+      ...draftCompany,
+      id: "new-company-id",
+      baseCurrencyId: null,
+    };
+    spies.insert.mockReturnValue(createdCompany);
+
+    const result = await run(db, { legalName: "Acme Corp" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.company.status).toBe("DRAFT");
+    }
+  });
+
+  it("creates company with full address fields", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const activeCurrency = { id: "currency-usd", isActive: true };
+    const createdCompany = { ...draftCompany, id: "new-company-id" };
+    spies.select.mockReturnValueOnce(activeCurrency);
+    spies.insert.mockReturnValue(createdCompany);
+
+    const result = await run(
+      db,
+      {
+        legalName: "Acme Corp",
+        baseCurrencyId: "currency-usd",
+        taxId: "TAX-12345",
+        registrationNumber: "REG-67890",
+        street: "123 Main St",
+        city: "Tokyo",
+        state: "Tokyo",
+        postalCode: "100-0001",
+        country: "JP",
+      },
+      ctx,
+      { getCurrency },
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.company).toBeDefined();
+    }
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdCompany = { ...draftCompany, id: "new-company-id", customField: "value" };
+    spies.insert.mockReturnValue(createdCompany);
+
+    await run(
+      db,
+      {
+        legalName: "Acme Corp",
+        customField: "value",
+      },
+      ctx,
+    );
+
+    expect(spies.values).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ customField: "value" }),
+    );
+  });
+});

package/src/modules/organization/command/createCompany.ts

@@ -0,0 +1,80 @@
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { InvalidLegalNameError, CurrencyNotFoundError } from "../lib/errors.generated";
+import type { PrimitivesQueries } from "../module";
+
+export interface CreateCompanyInput {
+  legalName: string;
+  baseCurrencyId?: string;
+  taxId?: string;
+  registrationNumber?: string;
+  street?: string;
+  city?: string;
+  state?: string;
+  postalCode?: string;
+  country?: string;
+}
+
+/**
+ * Function: createCompany
+ *
+ * Establishes a new legal entity in the system in DRAFT status. Accepts the
+ * company's legal name, and optionally tax identification, registration number,
+ * base currency, and registered address fields.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: CreateCompanyInput & CF,
+  ctx: CommandContext,
+  primitivesQueries?: Pick<PrimitivesQueries, "getCurrency">,
+) {
+  const {
+    legalName,
+    baseCurrencyId,
+    taxId,
+    registrationNumber,
+    street,
+    city,
+    state,
+    postalCode,
+    country,
+    ...customFields
+  } = input;
+
+  // 1. Validate legalName non-empty
+  if (!legalName || legalName.trim() === "") {
+    return err(new InvalidLegalNameError(legalName ?? ""));
+  }
+
+  // 2. If baseCurrencyId provided, validate currency exists and is active
+  if (baseCurrencyId && primitivesQueries) {
+    const { currency } = (await primitivesQueries.getCurrency(db, { id: baseCurrencyId }, ctx))
+      .value;
+    if (!currency?.isActive) {
+      return err(new CurrencyNotFoundError(baseCurrencyId));
+    }
+  }
+
+  // 3. Insert with status DRAFT
+  const company = await db
+    .insertInto("Company")
+    .values({
+      ...(customFields as Record<string, unknown>),
+      legalName,
+      baseCurrencyId: baseCurrencyId ?? null,
+      taxId: taxId ?? null,
+      registrationNumber: registrationNumber ?? null,
+      street: street ?? null,
+      city: city ?? null,
+      state: state ?? null,
+      postalCode: postalCode ?? null,
+      country: country ?? null,
+      status: "DRAFT",
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ company: company! });
+}

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

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

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

@@ -0,0 +1,239 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  InvalidCodeError,
+  InvalidNameError,
+  CompanyNotFoundError,
+  DuplicateCodeError,
+  ParentNotFoundError,
+} from "../lib/errors.generated";
+import { activeCompany, activeDepartment, otherCompanyDepartment } from "../testing/fixtures";
+import { run } from "./createDepartment";
+
+describe("createDepartment", () => {
+  it("creates top-level department in ACTIVE status", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const created = {
+      id: "new-dept-id",
+      code: "HR",
+      name: "Human Resources",
+      companyId: activeCompany.id,
+      parentDepartmentId: null,
+      status: "ACTIVE",
+      createdAt: new Date(),
+      updatedAt: null,
+    };
+
+    spies.select
+      .mockReturnValueOnce(activeCompany) // find company
+      .mockReturnValueOnce(undefined); // no duplicate code
+    spies.insert.mockReturnValue(created);
+
+    const result = await run(db, {
+      code: "HR",
+      name: "Human Resources",
+      companyId: activeCompany.id,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.department.status).toBe("ACTIVE");
+      expect(result.value.department.parentDepartmentId).toBeNull();
+    }
+  });
+
+  it("creates department with parent department", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const created = {
+      id: "new-dept-id",
+      code: "ENG-FE",
+      name: "Frontend Engineering",
+      companyId: activeCompany.id,
+      parentDepartmentId: activeDepartment.id,
+      status: "ACTIVE",
+      createdAt: new Date(),
+      updatedAt: null,
+    };
+
+    spies.select
+      .mockReturnValueOnce(activeCompany) // find company
+      .mockReturnValueOnce(undefined) // no duplicate code
+      .mockReturnValueOnce(activeDepartment); // find parent
+    spies.insert.mockReturnValue(created);
+
+    const result = await run(db, {
+      code: "ENG-FE",
+      name: "Frontend Engineering",
+      companyId: activeCompany.id,
+      parentDepartmentId: activeDepartment.id,
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.department.parentDepartmentId).toBe(activeDepartment.id);
+    }
+  });
+
+  it("throws when code is empty", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, {
+      code: "",
+      name: "Human Resources",
+      companyId: activeCompany.id,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidCodeError);
+    }
+  });
+
+  it("throws when code is whitespace-only", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, {
+      code: "   ",
+      name: "Human Resources",
+      companyId: activeCompany.id,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidCodeError);
+    }
+  });
+
+  it("throws when name is empty", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, {
+      code: "HR",
+      name: "",
+      companyId: activeCompany.id,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNameError);
+    }
+  });
+
+  it("throws when name is whitespace-only", async () => {
+    const { db } = createMockDb<Transaction>();
+
+    const result = await run(db, {
+      code: "HR",
+      name: "   ",
+      companyId: activeCompany.id,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNameError);
+    }
+  });
+
+  it("throws when company does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValue(undefined); // company not found
+
+    const result = await run(db, {
+      code: "HR",
+      name: "Human Resources",
+      companyId: "nonexistent-company",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CompanyNotFoundError);
+    }
+  });
+
+  it("throws when code already exists in same company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(activeCompany) // find company
+      .mockReturnValueOnce(activeDepartment); // duplicate found
+
+    const result = await run(db, {
+      code: activeDepartment.code,
+      name: "Duplicate Department",
+      companyId: activeCompany.id,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateCodeError);
+    }
+  });
+
+  it("allows same code in different companies", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const otherCompany = { ...activeCompany, id: "company-3" };
+    const created = {
+      id: "new-dept-id",
+      code: "ENG",
+      name: "Engineering",
+      companyId: otherCompany.id,
+      parentDepartmentId: null,
+      status: "ACTIVE",
+      createdAt: new Date(),
+      updatedAt: null,
+    };
+
+    spies.select
+      .mockReturnValueOnce(otherCompany) // find company
+      .mockReturnValueOnce(undefined); // no duplicate in this company
+    spies.insert.mockReturnValue(created);
+
+    const result = await run(db, {
+      code: "ENG",
+      name: "Engineering",
+      companyId: otherCompany.id,
+    });
+
+    expect(result.ok).toBe(true);
+  });
+
+  it("throws when parent department does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(activeCompany) // find company
+      .mockReturnValueOnce(undefined) // no duplicate code
+      .mockReturnValueOnce(undefined); // parent not found
+
+    const result = await run(db, {
+      code: "HR-SUB",
+      name: "HR Sub-team",
+      companyId: activeCompany.id,
+      parentDepartmentId: "nonexistent-dept",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentNotFoundError);
+    }
+  });
+
+  it("throws when parent department belongs to different company", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(activeCompany) // find company
+      .mockReturnValueOnce(undefined) // no duplicate code
+      .mockReturnValueOnce(otherCompanyDepartment); // parent in different company
+
+    const result = await run(db, {
+      code: "HR-SUB",
+      name: "HR Sub-team",
+      companyId: activeCompany.id,
+      parentDepartmentId: otherCompanyDepartment.id,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentNotFoundError);
+    }
+  });
+});

package/src/modules/organization/command/createDepartment.ts

@@ -0,0 +1,98 @@
+import { ok, err } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  InvalidCodeError,
+  InvalidNameError,
+  CompanyNotFoundError,
+  DuplicateCodeError,
+  ParentNotFoundError,
+} from "../lib/errors.generated";
+
+export interface CreateDepartmentInput {
+  code: string;
+  name: string;
+  companyId: string;
+  parentDepartmentId?: string;
+}
+
+/**
+ * Function: createDepartment
+ *
+ * Creates a new department within a company, optionally nested under
+ * an existing parent department in the same company.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: CreateDepartmentInput & CF,
+) {
+  const { code, name, companyId, parentDepartmentId, ...customFields } = input;
+
+  // 1. Validate code non-empty
+  if (!code?.trim()) {
+    return err(new InvalidCodeError(code));
+  }
+
+  // 2. Validate name non-empty
+  if (!name?.trim()) {
+    return err(new InvalidNameError(name));
+  }
+
+  // 3. Find company by companyId
+  const company = await db
+    .selectFrom("Company")
+    .selectAll()
+    .where("id", "=", companyId)
+    .executeTakeFirst();
+
+  if (!company) {
+    return err(new CompanyNotFoundError(companyId));
+  }
+
+  // 4. Check code uniqueness in company
+  const existingDepartment = await db
+    .selectFrom("Department")
+    .selectAll()
+    .where("code", "=", code)
+    .where("companyId", "=", companyId)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (existingDepartment) {
+    return err(new DuplicateCodeError(code));
+  }
+
+  // 5. If parentDepartmentId provided, validate parent
+  if (parentDepartmentId) {
+    const parent = await db
+      .selectFrom("Department")
+      .selectAll()
+      .where("id", "=", parentDepartmentId)
+      .executeTakeFirst();
+
+    if (!parent) {
+      return err(new ParentNotFoundError(parentDepartmentId));
+    }
+
+    if (parent.companyId !== companyId) {
+      return err(new ParentNotFoundError(parentDepartmentId));
+    }
+  }
+
+  // 6. Insert with status ACTIVE
+  const department = await db
+    .insertInto("Department")
+    .values({
+      ...(customFields as Record<string, unknown>),
+      code,
+      name,
+      companyId,
+      parentDepartmentId: parentDepartmentId ?? null,
+      status: "ACTIVE",
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  return ok({ department: department! });
+}

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

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