@tailor-platform/erp-kit 0.2.2 → 0.4.0

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

@@ -0,0 +1,154 @@
+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, InvalidStateTransitionError } from "../lib/errors.generated";
+import { baseDraftCoa, baseActiveCoa, baseArchivedCoa } from "../testing/fixtures";
+import { run, type AuditCommands } from "./deleteChartOfAccounts";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["coa-management:deleteChartOfAccounts"],
+};
+
+describe("deleteChartOfAccounts", () => {
+  it("returns error when CoA does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined);
+
+    const result = await run(db, { id: "nonexistent" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ChartOfAccountsNotFoundError);
+    }
+  });
+
+  it("returns error when CoA is ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveCoa);
+
+    const result = await run(db, { id: baseActiveCoa.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("returns error when CoA is ARCHIVED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseArchivedCoa);
+
+    const result = await run(db, { id: baseArchivedCoa.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("deletes a DRAFT CoA with no child records", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftCoa).mockReturnValueOnce([]).mockReturnValueOnce([]);
+
+    const result = await run(db, { id: baseDraftCoa.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.success).toBe(true);
+    }
+  });
+
+  it("deletes a DRAFT CoA and cascade-deletes all child Accounts", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseDraftCoa)
+      .mockReturnValueOnce([{ id: "a1" }])
+      .mockReturnValueOnce([]);
+    // delete spy is called 3 times: Accounts, AccountGroups, CoA
+
+    const result = await run(db, { id: baseDraftCoa.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.success).toBe(true);
+    }
+    // Verify delete was called (for Account, AccountGroup, and ChartOfAccounts)
+    expect(spies.delete).toHaveBeenCalled();
+  });
+
+  it("deletes a DRAFT CoA and cascade-deletes all child AccountGroups", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseDraftCoa)
+      .mockReturnValueOnce([])
+      .mockReturnValueOnce([{ id: "g1" }]);
+
+    const result = await run(db, { id: baseDraftCoa.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.success).toBe(true);
+    }
+    // The delete spy should have been called 3 times:
+    // once for Account, once for AccountGroup, once for ChartOfAccounts
+    expect(spies.delete).toHaveBeenCalledTimes(3);
+  });
+
+  it("emits audit events for each cascade-deleted Account and AccountGroup", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const accounts = [{ id: "account-1", code: "1100", name: "Cash" }];
+    const groups = [{ id: "group-1", code: "1000", name: "Assets" }];
+    spies.select
+      .mockReturnValueOnce(baseDraftCoa) // CoA lookup
+      .mockReturnValueOnce(accounts) // accounts query
+      .mockReturnValueOnce(groups); // groups query
+
+    const mockLogAuditEvent = vi.fn().mockResolvedValue({ ok: true, value: {} });
+    const auditCommands: AuditCommands = { logAuditEvent: mockLogAuditEvent };
+
+    const result = await run(db, { id: baseDraftCoa.id }, ctx, auditCommands);
+
+    expect(result.ok).toBe(true);
+    // Should emit: 1 for account + 1 for group + 1 for CoA = 3 audit events
+    expect(mockLogAuditEvent).toHaveBeenCalledTimes(3);
+    expect(mockLogAuditEvent).toHaveBeenCalledWith(
+      db,
+      expect.objectContaining({ entityType: "Account", operationType: "DELETE" }),
+      ctx,
+    );
+    expect(mockLogAuditEvent).toHaveBeenCalledWith(
+      db,
+      expect.objectContaining({ entityType: "AccountGroup", operationType: "DELETE" }),
+      ctx,
+    );
+  });
+
+  it("emits audit event recording CoA deletion and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseDraftCoa) // CoA lookup
+      .mockReturnValueOnce([]) // no accounts
+      .mockReturnValueOnce([]); // no groups
+
+    const mockLogAuditEvent = vi.fn().mockResolvedValue({ ok: true, value: {} });
+    const auditCommands: AuditCommands = { logAuditEvent: mockLogAuditEvent };
+
+    const result = await run(db, { id: baseDraftCoa.id }, ctx, auditCommands);
+
+    expect(result.ok).toBe(true);
+    expect(mockLogAuditEvent).toHaveBeenCalledWith(
+      db,
+      expect.objectContaining({
+        entityType: "ChartOfAccounts",
+        entityId: baseDraftCoa.id,
+        operationType: "DELETE",
+        companyId: baseDraftCoa.companyId,
+        actorType: "USER",
+        actorId: ctx.actorId,
+      }),
+      ctx,
+    );
+  });
+});

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

@@ -0,0 +1,133 @@
+import { randomUUID } from "node:crypto";
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import { ChartOfAccountsNotFoundError, InvalidStateTransitionError } from "../lib/errors.generated";
+
+export interface DeleteChartOfAccountsInput {
+  id: string;
+}
+
+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: deleteChartOfAccounts
+ *
+ * Permanently removes a Chart of Accounts that is still in DRAFT status.
+ * Cascade-deletes all child Account and AccountGroup records belonging to the CoA.
+ */
+export async function run(
+  db: Transaction,
+  input: DeleteChartOfAccountsInput,
+  ctx: CommandContext,
+  auditCommands?: AuditCommands,
+) {
+  const { id } = input;
+
+  // 1. Find CoA with forUpdate
+  const existing = await db
+    .selectFrom("ChartOfAccounts")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new ChartOfAccountsNotFoundError(id));
+  }
+
+  // 2. Must be DRAFT
+  if (existing.status !== "DRAFT") {
+    return err(new InvalidStateTransitionError(id));
+  }
+
+  // 3. Query child records before deleting (for audit)
+  const accounts = await db
+    .selectFrom("Account")
+    .selectAll()
+    .where("chartOfAccountsId", "=", id)
+    .execute();
+
+  const accountGroups = await db
+    .selectFrom("AccountGroup")
+    .selectAll()
+    .where("chartOfAccountsId", "=", id)
+    .execute();
+
+  // 4. Cascade-delete all child Accounts
+  await db.deleteFrom("Account").where("chartOfAccountsId", "=", id).execute();
+
+  // 5. Cascade-delete all child AccountGroups
+  await db.deleteFrom("AccountGroup").where("chartOfAccountsId", "=", id).execute();
+
+  // 6. Delete the CoA itself
+  await db.deleteFrom("ChartOfAccounts").where("id", "=", id).execute();
+
+  // 7. Emit audit events
+  if (auditCommands) {
+    for (const account of accounts) {
+      await auditCommands.logAuditEvent(
+        db,
+        {
+          eventId: randomUUID(),
+          actorType: "USER",
+          actorId: ctx.actorId,
+          entityType: "Account",
+          entityId: account.id,
+          operationType: "DELETE",
+          companyId: existing.companyId,
+          changes: [{ fieldName: "id", oldValue: account.id }],
+        },
+        ctx,
+      );
+    }
+
+    for (const group of accountGroups) {
+      await auditCommands.logAuditEvent(
+        db,
+        {
+          eventId: randomUUID(),
+          actorType: "USER",
+          actorId: ctx.actorId,
+          entityType: "AccountGroup",
+          entityId: group.id,
+          operationType: "DELETE",
+          companyId: existing.companyId,
+          changes: [{ fieldName: "id", oldValue: group.id }],
+        },
+        ctx,
+      );
+    }
+
+    await auditCommands.logAuditEvent(
+      db,
+      {
+        eventId: randomUUID(),
+        actorType: "USER",
+        actorId: ctx.actorId,
+        entityType: "ChartOfAccounts",
+        entityId: id,
+        operationType: "DELETE",
+        companyId: existing.companyId,
+        changes: [{ fieldName: "id", oldValue: id }],
+      },
+      ctx,
+    );
+  }
+
+  return ok({ success: true as const });
+}

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

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

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

@@ -0,0 +1,199 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountGroupNotFoundError,
+  ChartOfAccountsArchivedError,
+  ParentGroupNotFoundError,
+  CircularReferenceError,
+} from "../lib/errors.generated";
+import {
+  baseActiveCoa,
+  baseArchivedCoa,
+  baseRootGroup,
+  baseChildGroup,
+  baseGrandchildGroup,
+  baseGroupNoRange,
+} from "../testing/fixtures";
+import { run } from "./moveAccountGroup";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["coa-management:moveAccountGroup"],
+};
+
+describe("moveAccountGroup", () => {
+  it("returns error when group does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(undefined); // Group lookup
+
+    const result = await run(db, { id: "nonexistent", newParentAccountGroupId: null }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(AccountGroupNotFoundError);
+    }
+  });
+
+  it("returns error when parent CoA is ARCHIVED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const groupInArchivedCoa = { ...baseRootGroup, chartOfAccountsId: baseArchivedCoa.id };
+    spies.select
+      .mockReturnValueOnce(groupInArchivedCoa) // Group lookup
+      .mockReturnValueOnce(baseArchivedCoa); // CoA lookup
+
+    const result = await run(db, { id: groupInArchivedCoa.id, newParentAccountGroupId: null }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ChartOfAccountsArchivedError);
+    }
+  });
+
+  it("returns error when new parent does not exist", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseChildGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(undefined); // New parent not found
+
+    const result = await run(
+      db,
+      { id: baseChildGroup.id, newParentAccountGroupId: "nonexistent" },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentGroupNotFoundError);
+    }
+  });
+
+  it("returns error when new parent belongs to different CoA", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const parentInDifferentCoa = { ...baseGroupNoRange, chartOfAccountsId: "other-coa" };
+    spies.select
+      .mockReturnValueOnce(baseChildGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(parentInDifferentCoa); // New parent in different CoA
+
+    const result = await run(
+      db,
+      { id: baseChildGroup.id, newParentAccountGroupId: parentInDifferentCoa.id },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ParentGroupNotFoundError);
+    }
+  });
+
+  it("returns error when moving group under itself", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(
+      db,
+      { id: baseRootGroup.id, newParentAccountGroupId: baseRootGroup.id },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CircularReferenceError);
+    }
+  });
+
+  it("returns error when moving group under its descendant", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    // Scenario: move group-1 (root) under group-3 (grandchild of group-1)
+    // group-1 -> group-2 -> group-3
+    // Walk up from group-3's parent chain: group-3.parent = group-2, group-2.parent = group-1 (the group being moved)
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup (group-1)
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(baseGrandchildGroup) // New parent lookup (group-3)
+      .mockReturnValueOnce(baseChildGroup); // Walking up: group-3.parent = group-2, then group-2.parent = group-1 (circular!)
+
+    const result = await run(
+      db,
+      { id: baseRootGroup.id, newParentAccountGroupId: baseGrandchildGroup.id },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(CircularReferenceError);
+    }
+  });
+
+  it("moves group to different parent", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const movedGroup = { ...baseChildGroup, parentAccountGroupId: baseGroupNoRange.id };
+    spies.select
+      .mockReturnValueOnce(baseChildGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(baseGroupNoRange); // New parent lookup (root, no further ancestors)
+    spies.update.mockReturnValue(movedGroup);
+
+    const result = await run(
+      db,
+      { id: baseChildGroup.id, newParentAccountGroupId: baseGroupNoRange.id },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.accountGroup.parentAccountGroupId).toBe(baseGroupNoRange.id);
+      expect(result.value.previousParentAccountGroupId).toBe(baseRootGroup.id);
+    }
+  });
+
+  it("promotes group to root by setting parent to null", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const movedGroup = { ...baseChildGroup, parentAccountGroupId: null };
+    spies.select
+      .mockReturnValueOnce(baseChildGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+    spies.update.mockReturnValue(movedGroup);
+
+    const result = await run(db, { id: baseChildGroup.id, newParentAccountGroupId: null }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.accountGroup.parentAccountGroupId).toBeNull();
+      expect(result.value.previousParentAccountGroupId).toBe(baseRootGroup.id);
+    }
+  });
+
+  it("emits audit event recording previous and new parent references", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const movedGroup = { ...baseChildGroup, parentAccountGroupId: baseGroupNoRange.id };
+    spies.select
+      .mockReturnValueOnce(baseChildGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(baseGroupNoRange); // New parent lookup
+    spies.update.mockReturnValue(movedGroup);
+
+    const result = await run(
+      db,
+      { id: baseChildGroup.id, newParentAccountGroupId: baseGroupNoRange.id },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      // Return value contains previous and new parent for audit logging
+      expect(result.value.previousParentAccountGroupId).toBe(baseRootGroup.id);
+      expect(result.value.accountGroup.parentAccountGroupId).toBe(baseGroupNoRange.id);
+    }
+    expect(spies.update).toHaveBeenCalled();
+    expect(spies.set).toHaveBeenCalledWith(
+      expect.objectContaining({ parentAccountGroupId: baseGroupNoRange.id }),
+    );
+  });
+});

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

@@ -0,0 +1,145 @@
+import { randomUUID } from "node:crypto";
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountGroupNotFoundError,
+  ChartOfAccountsArchivedError,
+  ParentGroupNotFoundError,
+  CircularReferenceError,
+} from "../lib/errors.generated";
+
+export interface MoveAccountGroupInput {
+  id: string;
+  newParentAccountGroupId: string | 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: moveAccountGroup
+ *
+ * Reparents an account group by changing its parent reference within the same
+ * CoA. Moving to a null parent promotes the group to a root group.
+ */
+export async function run(
+  db: Transaction,
+  input: MoveAccountGroupInput,
+  ctx: CommandContext,
+  auditCommands?: AuditCommands,
+) {
+  const { id, newParentAccountGroupId } = input;
+
+  // 1. Find the group
+  const existing = await db
+    .selectFrom("AccountGroup")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!existing) {
+    return err(new AccountGroupNotFoundError(id));
+  }
+
+  // 2. Check parent CoA status
+  const coa = await db
+    .selectFrom("ChartOfAccounts")
+    .selectAll()
+    .where("id", "=", existing.chartOfAccountsId)
+    .executeTakeFirst();
+
+  if (coa!.status === "ARCHIVED") {
+    return err(new ChartOfAccountsArchivedError(existing.chartOfAccountsId));
+  }
+
+  // 3. If new parent specified, validate it
+  if (newParentAccountGroupId !== null) {
+    // Check self-reference
+    if (newParentAccountGroupId === id) {
+      return err(new CircularReferenceError(id));
+    }
+
+    const newParent = await db
+      .selectFrom("AccountGroup")
+      .selectAll()
+      .where("id", "=", newParentAccountGroupId)
+      .executeTakeFirst();
+
+    if (!newParent) {
+      return err(new ParentGroupNotFoundError(newParentAccountGroupId));
+    }
+
+    if (newParent.chartOfAccountsId !== existing.chartOfAccountsId) {
+      return err(new ParentGroupNotFoundError(newParentAccountGroupId));
+    }
+
+    // 4. Check for circular reference: walk up from newParent to root
+    let currentParentId = newParent.parentAccountGroupId;
+    while (currentParentId !== null) {
+      if (currentParentId === id) {
+        return err(new CircularReferenceError(id));
+      }
+      const ancestor = await db
+        .selectFrom("AccountGroup")
+        .selectAll()
+        .where("id", "=", currentParentId)
+        .executeTakeFirst();
+
+      if (!ancestor) break;
+      currentParentId = ancestor.parentAccountGroupId;
+    }
+  }
+
+  // 5. Update parent reference
+  const previousParentId = existing.parentAccountGroupId;
+  const accountGroup = await db
+    .updateTable("AccountGroup")
+    .set({
+      parentAccountGroupId: newParentAccountGroupId,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  // 6. Emit audit event
+  if (auditCommands) {
+    await auditCommands.logAuditEvent(
+      db,
+      {
+        eventId: randomUUID(),
+        actorType: "USER",
+        actorId: ctx.actorId,
+        entityType: "AccountGroup",
+        entityId: id,
+        operationType: "UPDATE",
+        companyId: coa!.companyId,
+        changes: [
+          {
+            fieldName: "parentAccountGroupId",
+            oldValue: existing.parentAccountGroupId,
+            newValue: newParentAccountGroupId,
+          },
+        ],
+      },
+      ctx,
+    );
+  }
+
+  return ok({ accountGroup: accountGroup!, previousParentAccountGroupId: previousParentId });
+}

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

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