@tailor-platform/erp-kit 0.2.2 → 0.4.0

package/src/modules/coa-management/command/createAccountGroup.test.ts

@@ -0,0 +1,494 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ChartOfAccountsNotFoundError,
+  ChartOfAccountsArchivedError,
+  CodeRequiredError,
+  DuplicateGroupCodeError,
+  NameRequiredError,
+  ParentGroupNotFoundError,
+  InvalidNumberRangeError,
+} from "../lib/errors.generated";
+import { baseActiveCoa, baseArchivedCoa, baseRootGroup, baseChildGroup } from "../testing/fixtures";
+import { run, type AuditCommands } from "./createAccountGroup";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["coa-management:createAccountGroup"],
+};
+
+describe("createAccountGroup", () => {
+  it("returns error when CoA does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // CoA lookup
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: "nonexistent",
+        code: "1000",
+        name: "Assets",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ChartOfAccountsNotFoundError);
+    }
+  });
+
+  it("returns error when parent CoA is ARCHIVED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseArchivedCoa); // CoA lookup
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseArchivedCoa.id,
+        code: "1000",
+        name: "Assets",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ChartOfAccountsArchivedError);
+    }
+  });
+
+  it("returns error when group code already exists in CoA", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(baseRootGroup); // Duplicate code check
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: baseRootGroup.code,
+        name: "Duplicate Code Group",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(DuplicateGroupCodeError);
+    }
+  });
+
+  it("returns error when group code is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "",
+        name: "Assets",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CodeRequiredError);
+    }
+
+    // Also rejects blank (whitespace-only) codes
+    const { db: db2, spies: spies2 } = createMockDb<Transaction>();
+    spies2.select.mockReturnValueOnce(baseActiveCoa);
+
+    const result2 = await run(
+      db2,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "   ",
+        name: "Assets",
+      },
+      ctx,
+    );
+
+    expect(result2.ok).toBe(false);
+    if (!result2.ok) {
+      expect(result2.error).toBeInstanceOf(CodeRequiredError);
+    }
+  });
+
+  it("returns error when name is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "3000",
+        name: "",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(NameRequiredError);
+    }
+  });
+
+  it("returns error when parent group does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined) // No duplicate code
+      .mockReturnValueOnce(undefined); // Parent group not found
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "3000",
+        name: "Revenue",
+        parentAccountGroupId: "nonexistent",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentGroupNotFoundError);
+    }
+  });
+
+  it("returns error when parent group belongs to different CoA", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const parentInDifferentCoa = { ...baseRootGroup, chartOfAccountsId: "other-coa" };
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined) // No duplicate code
+      .mockReturnValueOnce(parentInDifferentCoa); // Parent in different CoA
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "3000",
+        name: "Revenue",
+        parentAccountGroupId: parentInDifferentCoa.id,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentGroupNotFoundError);
+    }
+  });
+
+  it("returns error when number range is invalid", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined); // No duplicate code
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "3000",
+        name: "Revenue",
+        numberRangeStart: 3000,
+        numberRangeEnd: 2000,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNumberRangeError);
+    }
+  });
+
+  it("returns error when only numberRangeStart is provided", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined); // No duplicate code
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "3000",
+        name: "Revenue",
+        numberRangeStart: 3000,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNumberRangeError);
+    }
+  });
+
+  it("returns error when only numberRangeEnd is provided", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined); // No duplicate code
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "3000",
+        name: "Revenue",
+        numberRangeEnd: 3999,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNumberRangeError);
+    }
+  });
+
+  it("returns error when number range overlaps with existing group", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined) // No duplicate code
+      .mockReturnValueOnce([baseRootGroup]); // Existing groups with overlapping range
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "1500",
+        name: "Overlapping Range",
+        numberRangeStart: 1500,
+        numberRangeEnd: 2500,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidNumberRangeError);
+    }
+  });
+
+  it("creates a root group with no parent", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdGroup = {
+      ...baseRootGroup,
+      id: "new-group-id",
+      code: "3000",
+      name: "Revenue",
+      parentAccountGroupId: null,
+    };
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined); // No duplicate code
+    spies.insert.mockReturnValue(createdGroup);
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "3000",
+        name: "Revenue",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.accountGroup.code).toBe("3000");
+      expect(result.value.accountGroup.parentAccountGroupId).toBeNull();
+    }
+  });
+
+  it("creates a child group with valid parent", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdGroup = {
+      ...baseChildGroup,
+      id: "new-child-id",
+      code: "1200",
+      name: "Fixed Assets",
+      parentAccountGroupId: baseRootGroup.id,
+    };
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined) // No duplicate code
+      .mockReturnValueOnce(baseRootGroup); // Parent group lookup
+    spies.insert.mockReturnValue(createdGroup);
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "1200",
+        name: "Fixed Assets",
+        parentAccountGroupId: baseRootGroup.id,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.accountGroup.parentAccountGroupId).toBe(baseRootGroup.id);
+    }
+  });
+
+  it("creates a group with account number range", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdGroup = {
+      ...baseRootGroup,
+      id: "new-group-id",
+      code: "3000",
+      name: "Revenue",
+      numberRangeStart: 3000,
+      numberRangeEnd: 3999,
+    };
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined) // No duplicate code
+      .mockReturnValueOnce([]); // No overlapping groups
+    spies.insert.mockReturnValue(createdGroup);
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "3000",
+        name: "Revenue",
+        numberRangeStart: 3000,
+        numberRangeEnd: 3999,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.accountGroup.numberRangeStart).toBe(3000);
+      expect(result.value.accountGroup.numberRangeEnd).toBe(3999);
+    }
+  });
+
+  it("creates a group with sort order", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdGroup = {
+      ...baseRootGroup,
+      id: "new-group-id",
+      code: "3000",
+      name: "Revenue",
+      sortOrder: 5,
+    };
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined); // No duplicate code
+    spies.insert.mockReturnValue(createdGroup);
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "3000",
+        name: "Revenue",
+        sortOrder: 5,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.accountGroup.sortOrder).toBe(5);
+    }
+  });
+
+  it("emits audit event recording acting user, timestamp, CoA reference, group code, and initial field values", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdGroup = {
+      ...baseRootGroup,
+      id: "new-group-id",
+      code: "4000",
+      name: "Expenses",
+      createdAt: new Date(),
+    };
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined); // No duplicate code
+    spies.insert.mockReturnValue(createdGroup);
+
+    const mockLogAuditEvent = vi.fn().mockResolvedValue({ ok: true, value: {} });
+    const auditCommands: AuditCommands = { logAuditEvent: mockLogAuditEvent };
+
+    const result = await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "4000",
+        name: "Expenses",
+      },
+      ctx,
+      auditCommands,
+    );
+
+    expect(result.ok).toBe(true);
+    expect(mockLogAuditEvent).toHaveBeenCalledWith(
+      db,
+      expect.objectContaining({
+        entityType: "AccountGroup",
+        entityId: "new-group-id",
+        operationType: "CREATE",
+        companyId: baseActiveCoa.companyId,
+        actorType: "USER",
+        actorId: ctx.actorId,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        changes: expect.arrayContaining([
+          { fieldName: "chartOfAccountsId", newValue: baseActiveCoa.id },
+          { fieldName: "code", newValue: "4000" },
+          { fieldName: "name", newValue: "Expenses" },
+        ]),
+      }),
+      ctx,
+    );
+  });
+
+  it("passes custom fields through to insert", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const createdGroup = {
+      ...baseRootGroup,
+      id: "new-group-id",
+      customField: "custom-value",
+    };
+    spies.select
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined); // No duplicate code
+    spies.insert.mockReturnValue(createdGroup);
+
+    await run(
+      db,
+      {
+        chartOfAccountsId: baseActiveCoa.id,
+        code: "5000",
+        name: "Custom Group",
+        customField: "custom-value",
+      },
+      ctx,
+    );
+
+    expect(spies.values).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ customField: "custom-value" }),
+    );
+  });
+});

package/src/modules/coa-management/command/createAccountGroup.ts

@@ -0,0 +1,207 @@
+import { randomUUID } from "node:crypto";
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ChartOfAccountsNotFoundError,
+  ChartOfAccountsArchivedError,
+  CodeRequiredError,
+  DuplicateGroupCodeError,
+  NameRequiredError,
+  ParentGroupNotFoundError,
+  InvalidNumberRangeError,
+} from "../lib/errors.generated";
+
+export interface CreateAccountGroupInput {
+  chartOfAccountsId: string;
+  code: string;
+  name: string;
+  parentAccountGroupId?: string | null;
+  sortOrder?: number | null;
+  numberRangeStart?: number | null;
+  numberRangeEnd?: number | null;
+}
+
+export interface AuditCommands {
+  logAuditEvent: (
+    db: Transaction,
+    input: {
+      eventId: string;
+      actorType: string;
+      actorId: string;
+      entityType: string;
+      entityId: string;
+      operationType: string;
+      companyId?: string;
+      changes: { fieldName: string; oldValue?: unknown; newValue?: unknown }[];
+    },
+    ctx: CommandContext,
+  ) => Promise<{ ok: true; value: unknown }>;
+}
+
+/**
+ * Function: createAccountGroup
+ *
+ * Establishes a new account group within a Chart of Accounts. Groups organize
+ * GL accounts into logical categories and can be nested to form a multi-level
+ * tree hierarchy.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: CreateAccountGroupInput & CF,
+  ctx: CommandContext,
+  auditCommands?: AuditCommands,
+) {
+  const {
+    chartOfAccountsId,
+    code,
+    name,
+    parentAccountGroupId,
+    sortOrder,
+    numberRangeStart,
+    numberRangeEnd,
+    ...customFields
+  } = input;
+
+  // 1. Validate CoA exists
+  const coa = await db
+    .selectFrom("ChartOfAccounts")
+    .selectAll()
+    .where("id", "=", chartOfAccountsId)
+    .executeTakeFirst();
+
+  if (!coa) {
+    return err(new ChartOfAccountsNotFoundError(chartOfAccountsId));
+  }
+
+  // 2. Validate CoA is not ARCHIVED
+  if (coa.status === "ARCHIVED") {
+    return err(new ChartOfAccountsArchivedError(chartOfAccountsId));
+  }
+
+  // 3. Validate code is non-empty
+  if (!code || code.trim() === "") {
+    return err(new CodeRequiredError(code ?? ""));
+  }
+
+  // 4. Validate name is non-empty
+  if (!name || name.trim() === "") {
+    return err(new NameRequiredError(name ?? ""));
+  }
+
+  // 5. Validate code uniqueness within the CoA
+  const existingGroup = await db
+    .selectFrom("AccountGroup")
+    .selectAll()
+    .where("chartOfAccountsId", "=", chartOfAccountsId)
+    .where("code", "=", code)
+    .executeTakeFirst();
+
+  if (existingGroup) {
+    return err(new DuplicateGroupCodeError(code));
+  }
+
+  // 6. Validate parent group if provided
+  if (parentAccountGroupId) {
+    const parentGroup = await db
+      .selectFrom("AccountGroup")
+      .selectAll()
+      .where("id", "=", parentAccountGroupId)
+      .executeTakeFirst();
+
+    if (!parentGroup) {
+      return err(new ParentGroupNotFoundError(parentAccountGroupId));
+    }
+
+    if (parentGroup.chartOfAccountsId !== chartOfAccountsId) {
+      return err(new ParentGroupNotFoundError(parentAccountGroupId));
+    }
+  }
+
+  // 7. Validate number range
+  const rangeStart = numberRangeStart ?? null;
+  const rangeEnd = numberRangeEnd ?? null;
+
+  // Both bounds must be provided together — one-sided ranges are invalid
+  if ((rangeStart !== null) !== (rangeEnd !== null)) {
+    return err(new InvalidNumberRangeError(`${rangeStart ?? "null"}-${rangeEnd ?? "null"}`));
+  }
+
+  if (rangeStart !== null && rangeEnd !== null) {
+    // Range must be valid: start < end
+    if (rangeStart >= rangeEnd) {
+      return err(new InvalidNumberRangeError(`${rangeStart}-${rangeEnd}`));
+    }
+
+    // Check for overlap with existing groups in the same CoA
+    const existingGroups = await db
+      .selectFrom("AccountGroup")
+      .selectAll()
+      .where("chartOfAccountsId", "=", chartOfAccountsId)
+      .execute();
+
+    for (const group of existingGroups) {
+      if (group.numberRangeStart !== null && group.numberRangeEnd !== null) {
+        // Overlap: ranges overlap if one starts before the other ends and vice versa
+        if (rangeStart <= group.numberRangeEnd && rangeEnd >= group.numberRangeStart) {
+          return err(new InvalidNumberRangeError(`${rangeStart}-${rangeEnd}`));
+        }
+      }
+    }
+  }
+
+  // 8. Insert the account group
+  const accountGroup = await db
+    .insertInto("AccountGroup")
+    .values({
+      ...(customFields as Record<string, unknown>),
+      code,
+      name,
+      chartOfAccountsId,
+      parentAccountGroupId: parentAccountGroupId ?? null,
+      sortOrder: sortOrder ?? null,
+      numberRangeStart: rangeStart,
+      numberRangeEnd: rangeEnd,
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // 9. Emit audit event
+  if (auditCommands) {
+    const changes: { fieldName: string; oldValue?: unknown; newValue?: unknown }[] = [
+      { fieldName: "chartOfAccountsId", newValue: chartOfAccountsId },
+      { fieldName: "code", newValue: code },
+      { fieldName: "name", newValue: name },
+    ];
+    if (parentAccountGroupId) {
+      changes.push({ fieldName: "parentAccountGroupId", newValue: parentAccountGroupId });
+    }
+    if (sortOrder !== undefined && sortOrder !== null) {
+      changes.push({ fieldName: "sortOrder", newValue: sortOrder });
+    }
+    if (rangeStart !== null) {
+      changes.push({ fieldName: "numberRangeStart", newValue: rangeStart });
+    }
+    if (rangeEnd !== null) {
+      changes.push({ fieldName: "numberRangeEnd", newValue: rangeEnd });
+    }
+
+    await auditCommands.logAuditEvent(
+      db,
+      {
+        eventId: randomUUID(),
+        actorType: "USER",
+        actorId: ctx.actorId,
+        entityType: "AccountGroup",
+        entityId: accountGroup!.id,
+        operationType: "CREATE",
+        companyId: coa.companyId,
+        changes,
+      },
+      ctx,
+    );
+  }
+
+  return ok({ accountGroup: accountGroup! });
+}

package/src/modules/coa-management/command/createChartOfAccounts.generated.ts

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