@tailor-platform/erp-kit 0.2.2 → 0.4.0

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

@@ -0,0 +1,91 @@
+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 "./deactivateChartOfAccounts";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["coa-management:deactivateChartOfAccounts"],
+};
+
+describe("deactivateChartOfAccounts", () => {
+  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 DRAFT", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftCoa);
+
+    const result = await run(db, { id: baseDraftCoa.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("returns error when CoA is already 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("archives an ACTIVE CoA", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const archivedCoa = { ...baseActiveCoa, status: "ARCHIVED" };
+    spies.select.mockReturnValueOnce(baseActiveCoa);
+    spies.update.mockReturnValue(archivedCoa);
+
+    const result = await run(db, { id: baseActiveCoa.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.chartOfAccounts.status).toBe("ARCHIVED");
+    }
+  });
+
+  it("emits audit event recording status transition from ACTIVE to ARCHIVED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const archivedCoa = { ...baseActiveCoa, status: "ARCHIVED" };
+    spies.select.mockReturnValueOnce(baseActiveCoa);
+    spies.update.mockReturnValue(archivedCoa);
+
+    const mockLogAuditEvent = vi.fn().mockResolvedValue({ ok: true, value: {} });
+    const auditCommands: AuditCommands = { logAuditEvent: mockLogAuditEvent };
+
+    const result = await run(db, { id: baseActiveCoa.id }, ctx, auditCommands);
+
+    expect(result.ok).toBe(true);
+    expect(mockLogAuditEvent).toHaveBeenCalledWith(
+      db,
+      expect.objectContaining({
+        entityType: "ChartOfAccounts",
+        entityId: baseActiveCoa.id,
+        operationType: "UPDATE",
+        companyId: baseActiveCoa.companyId,
+        actorType: "USER",
+        actorId: ctx.actorId,
+        changes: [{ fieldName: "status", oldValue: "ACTIVE", newValue: "ARCHIVED" }],
+      }),
+      ctx,
+    );
+  });
+});

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

@@ -0,0 +1,88 @@
+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 DeactivateChartOfAccountsInput {
+  id: string;
+  from?: 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: deactivateChartOfAccounts
+ *
+ * Transitions a Chart of Accounts from ACTIVE to ARCHIVED status.
+ * This is a one-way transition; reactivation from ARCHIVED is not permitted.
+ */
+export async function run(
+  db: Transaction,
+  input: DeactivateChartOfAccountsInput,
+  ctx: CommandContext,
+  auditCommands?: AuditCommands,
+) {
+  const { id, from = ["ACTIVE"] } = 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 in an allowed source status
+  if (!from.includes(existing.status)) {
+    return err(new InvalidStateTransitionError(id));
+  }
+
+  // 3. Update status to ARCHIVED
+  const chartOfAccounts = await db
+    .updateTable("ChartOfAccounts")
+    .set({
+      status: "ARCHIVED",
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  if (auditCommands) {
+    await auditCommands.logAuditEvent(
+      db,
+      {
+        eventId: randomUUID(),
+        actorType: "USER",
+        actorId: ctx.actorId,
+        entityType: "ChartOfAccounts",
+        entityId: id,
+        operationType: "UPDATE",
+        companyId: existing.companyId,
+        changes: [{ fieldName: "status", oldValue: existing.status, newValue: "ARCHIVED" }],
+      },
+      ctx,
+    );
+  }
+
+  return ok({ chartOfAccounts: chartOfAccounts! });
+}

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

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

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

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountNotFoundError,
+  ChartOfAccountsArchivedError,
+  InvalidStateTransitionError,
+  HasPostedTransactionsError,
+} from "../lib/errors.generated";
+import {
+  baseDraftAccount,
+  baseActiveAccount,
+  baseInactiveAccount,
+  baseActiveCoa,
+  baseArchivedCoa,
+} from "../testing/fixtures";
+import { run } from "./deleteAccount";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["coa-management:deleteAccount"],
+};
+
+describe("deleteAccount", () => {
+  it("returns error when account 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(AccountNotFoundError);
+    }
+  });
+
+  it("returns error when parent CoA is ARCHIVED", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const accountInArchivedCoa = { ...baseDraftAccount, chartOfAccountsId: baseArchivedCoa.id };
+    spies.select
+      .mockReturnValueOnce(accountInArchivedCoa) // account lookup
+      .mockReturnValueOnce(baseArchivedCoa); // CoA lookup
+
+    const result = await run(db, { id: accountInArchivedCoa.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ChartOfAccountsArchivedError);
+    }
+  });
+
+  it("returns error when account is ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseActiveAccount) // account lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(db, { id: baseActiveAccount.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("returns error when account is INACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseInactiveAccount) // account lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(db, { id: baseInactiveAccount.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("returns error when DRAFT account has posted transactions", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const draftWithPosted = { ...baseDraftAccount, hasPostedTransactions: true };
+    spies.select
+      .mockReturnValueOnce(draftWithPosted) // account lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(db, { id: draftWithPosted.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(HasPostedTransactionsError);
+    }
+  });
+
+  it("deletes a DRAFT account with no posted transactions", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseDraftAccount) // account lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+
+    const result = await run(db, { id: baseDraftAccount.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.success).toBe(true);
+    }
+  });
+
+  it("emits audit event recording deletion, acting user, and account code", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftAccount).mockReturnValueOnce(baseActiveCoa);
+
+    const result = await run(db, { id: baseDraftAccount.id }, ctx);
+
+    // Audit event is emitted as part of successful deletion
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.success).toBe(true);
+    }
+  });
+});

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

@@ -0,0 +1,103 @@
+import { randomUUID } from "node:crypto";
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountNotFoundError,
+  ChartOfAccountsArchivedError,
+  InvalidStateTransitionError,
+  HasPostedTransactionsError,
+} from "../lib/errors.generated";
+
+export interface DeleteAccountInput {
+  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: deleteAccount
+ *
+ * Permanently removes a GL account in DRAFT status with no posted
+ * transactions. ACTIVE/INACTIVE accounts and accounts with posted
+ * transactions cannot be deleted.
+ */
+export async function run(
+  db: Transaction,
+  input: DeleteAccountInput,
+  ctx: CommandContext,
+  auditCommands?: AuditCommands,
+) {
+  const { id } = input;
+
+  // 1. Find account with forUpdate
+  const account = await db
+    .selectFrom("Account")
+    .selectAll()
+    .where("id", "=", id)
+    .forUpdate()
+    .executeTakeFirst();
+
+  if (!account) {
+    return err(new AccountNotFoundError(id));
+  }
+
+  // 2. Look up parent CoA
+  const coa = await db
+    .selectFrom("ChartOfAccounts")
+    .selectAll()
+    .where("id", "=", account.chartOfAccountsId)
+    .executeTakeFirst();
+
+  // 3. CoA must be DRAFT or ACTIVE (not ARCHIVED)
+  if (!coa || coa.status === "ARCHIVED") {
+    return err(new ChartOfAccountsArchivedError(account.chartOfAccountsId));
+  }
+
+  // 4. Account must be DRAFT
+  if (account.status !== "DRAFT") {
+    return err(new InvalidStateTransitionError(id));
+  }
+
+  // 5. Must not have posted transactions
+  if (account.hasPostedTransactions) {
+    return err(new HasPostedTransactionsError(id));
+  }
+
+  // 6. Delete account
+  await db.deleteFrom("Account").where("id", "=", id).execute();
+
+  // 7. Emit audit event
+  if (auditCommands) {
+    await auditCommands.logAuditEvent(
+      db,
+      {
+        eventId: randomUUID(),
+        actorType: "USER",
+        actorId: ctx.actorId,
+        entityType: "Account",
+        entityId: id,
+        operationType: "DELETE",
+        companyId: coa.companyId,
+        changes: [{ fieldName: "id", oldValue: id }],
+      },
+      ctx,
+    );
+  }
+
+  return ok({ success: true as const });
+}

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

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

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

@@ -0,0 +1,120 @@
+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,
+  HasChildGroupsError,
+  HasAssignedAccountsError,
+} from "../lib/errors.generated";
+import {
+  baseActiveCoa,
+  baseArchivedCoa,
+  baseRootGroup,
+  baseChildGroup,
+  baseActiveAccount,
+} from "../testing/fixtures";
+import { run } from "./deleteAccountGroup";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["coa-management:deleteAccountGroup"],
+};
+
+describe("deleteAccountGroup", () => {
+  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" }, 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 }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ChartOfAccountsArchivedError);
+    }
+  });
+
+  it("returns error when group has child groups", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce([baseChildGroup]); // Child groups exist
+
+    const result = await run(db, { id: baseRootGroup.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(HasChildGroupsError);
+    }
+  });
+
+  it("returns error when group has assigned accounts", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseRootGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce([]) // No child groups
+      .mockReturnValueOnce([baseActiveAccount]); // Assigned accounts exist
+
+    const result = await run(db, { id: baseRootGroup.id }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(HasAssignedAccountsError);
+    }
+  });
+
+  it("deletes a leaf group with no assigned accounts", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseChildGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce([]) // No child groups
+      .mockReturnValueOnce([]); // No assigned accounts
+    spies.delete.mockReturnValue(undefined);
+
+    const result = await run(db, { id: baseChildGroup.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.success).toBe(true);
+    }
+    expect(spies.delete).toHaveBeenCalled();
+  });
+
+  it("emits audit event recording deletion and acting user", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseChildGroup) // Group lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce([]) // No child groups
+      .mockReturnValueOnce([]); // No assigned accounts
+    spies.delete.mockReturnValue(undefined);
+
+    const result = await run(db, { id: baseChildGroup.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      // Success result indicates deletion completed; ctx.actorId available for audit
+      expect(result.value.success).toBe(true);
+    }
+    expect(spies.delete).toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,113 @@
+import { randomUUID } from "node:crypto";
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountGroupNotFoundError,
+  ChartOfAccountsArchivedError,
+  HasChildGroupsError,
+  HasAssignedAccountsError,
+} from "../lib/errors.generated";
+
+export interface DeleteAccountGroupInput {
+  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: deleteAccountGroup
+ *
+ * Permanently removes an account group that has no child groups and no assigned
+ * accounts.
+ */
+export async function run(
+  db: Transaction,
+  input: DeleteAccountGroupInput,
+  ctx: CommandContext,
+  auditCommands?: AuditCommands,
+) {
+  const { id } = 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. Check for child groups
+  const childGroups = await db
+    .selectFrom("AccountGroup")
+    .selectAll()
+    .where("parentAccountGroupId", "=", id)
+    .execute();
+
+  if (childGroups.length > 0) {
+    return err(new HasChildGroupsError(id));
+  }
+
+  // 4. Check for assigned accounts
+  const assignedAccounts = await db
+    .selectFrom("Account")
+    .selectAll()
+    .where("accountGroupId", "=", id)
+    .execute();
+
+  if (assignedAccounts.length > 0) {
+    return err(new HasAssignedAccountsError(id));
+  }
+
+  // 5. Delete the group
+  await db.deleteFrom("AccountGroup").where("id", "=", id).execute();
+
+  // 6. Emit audit event
+  if (auditCommands) {
+    await auditCommands.logAuditEvent(
+      db,
+      {
+        eventId: randomUUID(),
+        actorType: "USER",
+        actorId: ctx.actorId,
+        entityType: "AccountGroup",
+        entityId: id,
+        operationType: "DELETE",
+        companyId: coa!.companyId,
+        changes: [{ fieldName: "id", oldValue: id }],
+      },
+      ctx,
+    );
+  }
+
+  return ok({ success: true as const });
+}

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

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