@tailor-platform/erp-kit 0.3.0 → 0.4.0

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

@@ -0,0 +1,267 @@
+import { randomUUID } from "node:crypto";
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  NameRequiredError,
+  CompanyNotFoundError,
+  TemplateNotFoundError,
+  TemplateProviderNotConfiguredError,
+} from "../lib/errors.generated";
+
+export interface CreateChartOfAccountsInput {
+  name: string;
+  companyId: string;
+  description?: string | null;
+  templateId?: string;
+}
+
+export interface TemplateAccountGroup {
+  code: string;
+  name: string;
+  parentCode?: string | null;
+  sortOrder?: number | null;
+  numberRangeStart?: number | null;
+  numberRangeEnd?: number | null;
+}
+
+export interface TemplateAccount {
+  code: string;
+  name: string;
+  accountType: "ASSET" | "LIABILITY" | "EQUITY" | "REVENUE" | "EXPENSE";
+  classification:
+    | "REGULAR"
+    | "RECEIVABLE"
+    | "PAYABLE"
+    | "BANK_CASH"
+    | "FIXED_ASSET"
+    | "RETAINED_EARNINGS"
+    | "NON_POSTING";
+  groupCode?: string | null;
+  reconciliation?: boolean;
+  defaultTaxCode?: string | null;
+  tags?: string | null;
+}
+
+export interface TemplateSnapshot {
+  accountGroups: TemplateAccountGroup[];
+  accounts: TemplateAccount[];
+}
+
+export interface TemplateProvider {
+  resolveTemplate: (id: string) => Promise<TemplateSnapshot | 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 }>;
+}
+
+export interface OrganizationQueries {
+  getCompany: (
+    db: Transaction,
+    input: { id: string },
+    ctx: CommandContext,
+  ) => Promise<{
+    ok: true;
+    value: { company: { status: string; baseCurrencyId?: string | null } | null };
+  }>;
+}
+
+/**
+ * Function: createChartOfAccounts
+ *
+ * Establishes a new Chart of Accounts container in DRAFT status for a company.
+ * The CoA inherits its base currency from the parent company.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: CreateChartOfAccountsInput & CF,
+  ctx: CommandContext,
+  organizationQueries?: Pick<OrganizationQueries, "getCompany">,
+  templateProvider?: TemplateProvider,
+  auditCommands?: AuditCommands,
+) {
+  const { name, companyId, description, templateId, ...customFields } = input;
+
+  // 1. Validate company exists and is ACTIVE, and retrieve base currency
+  let baseCurrencyId: string;
+  if (organizationQueries) {
+    const { company } = (await organizationQueries.getCompany(db, { id: companyId }, ctx)).value;
+    if (company?.status !== "ACTIVE") {
+      return err(new CompanyNotFoundError(companyId));
+    }
+    // ACTIVE companies are guaranteed to have a base currency assigned
+    baseCurrencyId = company.baseCurrencyId ?? "";
+  } else {
+    // Fallback: check Company stub table directly
+    const company = await db
+      .selectFrom("Company")
+      .selectAll()
+      .where("id", "=", companyId)
+      .executeTakeFirst();
+
+    if (!company) {
+      return err(new CompanyNotFoundError(companyId));
+    }
+    baseCurrencyId = ((company as Record<string, unknown>).baseCurrencyId as string) ?? "";
+  }
+
+  // 2. Validate name non-empty
+  if (!name || name.trim() === "") {
+    return err(new NameRequiredError(name ?? ""));
+  }
+
+  // 3. Handle template
+  let template: TemplateSnapshot | null = null;
+  if (templateId) {
+    if (!templateProvider) {
+      return err(new TemplateProviderNotConfiguredError(templateId));
+    }
+    template = await templateProvider.resolveTemplate(templateId);
+    if (!template) {
+      return err(new TemplateNotFoundError(templateId));
+    }
+  }
+
+  // 4. Create CoA in DRAFT status with inherited base currency
+  const coa = await db
+    .insertInto("ChartOfAccounts")
+    .values({
+      ...(customFields as Record<string, unknown>),
+      name,
+      companyId,
+      baseCurrencyId,
+      description: description ?? null,
+      status: "DRAFT",
+      createdAt: new Date(),
+      updatedAt: null,
+    })
+    .returningAll()
+    .executeTakeFirst();
+
+  // 5. If template resolved, copy account groups and accounts
+  if (template && coa) {
+    const groupCodeToId: Record<string, string> = {};
+
+    // Topological sort: ensure parents are inserted before children
+    const sorted = topologicalSortGroups(template.accountGroups);
+
+    // Insert account groups (parents first, then children)
+    for (const group of sorted) {
+      const parentId = group.parentCode ? (groupCodeToId[group.parentCode] ?? null) : null;
+      const insertedGroup = await db
+        .insertInto("AccountGroup")
+        .values({
+          code: group.code,
+          name: group.name,
+          chartOfAccountsId: coa.id,
+          parentAccountGroupId: parentId,
+          sortOrder: group.sortOrder ?? null,
+          numberRangeStart: group.numberRangeStart ?? null,
+          numberRangeEnd: group.numberRangeEnd ?? null,
+          createdAt: new Date(),
+          updatedAt: null,
+        })
+        .returningAll()
+        .executeTakeFirst();
+
+      if (insertedGroup) {
+        groupCodeToId[group.code] = insertedGroup.id;
+      }
+    }
+
+    // Insert accounts
+    for (const account of template.accounts) {
+      const groupId = account.groupCode ? (groupCodeToId[account.groupCode] ?? null) : null;
+      await db
+        .insertInto("Account")
+        .values({
+          code: account.code,
+          name: account.name,
+          accountType: account.accountType,
+          classification: account.classification,
+          chartOfAccountsId: coa.id,
+          accountGroupId: groupId,
+          currencyRestriction: null,
+          reconciliation: account.reconciliation ?? false,
+          defaultTaxCode: account.defaultTaxCode ?? null,
+          tags: account.tags ?? null,
+          successorAccountId: null,
+          hasPostedTransactions: false,
+          status: "DRAFT",
+          createdAt: new Date(),
+          updatedAt: null,
+        })
+        .returningAll()
+        .executeTakeFirst();
+    }
+  }
+
+  // 6. Emit audit event
+  if (auditCommands) {
+    const changes: { fieldName: string; oldValue?: unknown; newValue?: unknown }[] = [
+      { fieldName: "name", newValue: name },
+      { fieldName: "companyId", newValue: companyId },
+      { fieldName: "baseCurrencyId", newValue: baseCurrencyId },
+      { fieldName: "status", newValue: "DRAFT" },
+    ];
+    if (description) {
+      changes.push({ fieldName: "description", newValue: description });
+    }
+    changes.push({
+      fieldName: "templateUsed",
+      newValue: templateId ? "template" : "blank",
+    });
+
+    await auditCommands.logAuditEvent(
+      db,
+      {
+        eventId: randomUUID(),
+        actorType: "USER",
+        actorId: ctx.actorId,
+        entityType: "ChartOfAccounts",
+        entityId: coa!.id,
+        operationType: "CREATE",
+        companyId,
+        changes,
+      },
+      ctx,
+    );
+  }
+
+  return ok({ chartOfAccounts: coa! });
+}
+
+function topologicalSortGroups(groups: TemplateAccountGroup[]): TemplateAccountGroup[] {
+  const byCode = new Map(groups.map((g) => [g.code, g]));
+  const sorted: TemplateAccountGroup[] = [];
+  const visited = new Set<string>();
+
+  function visit(group: TemplateAccountGroup) {
+    if (visited.has(group.code)) return;
+    visited.add(group.code);
+    if (group.parentCode) {
+      const parent = byCode.get(group.parentCode);
+      if (parent) visit(parent);
+    }
+    sorted.push(group);
+  }
+
+  for (const group of groups) {
+    visit(group);
+  }
+
+  return sorted;
+}

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

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

package/src/modules/coa-management/command/deactivateAccount.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 {
+  AccountNotFoundError,
+  ChartOfAccountsArchivedError,
+  InvalidStateTransitionError,
+  OpenBalancesExistError,
+  SuccessorNotActiveError,
+} from "../lib/errors.generated";
+import {
+  baseActiveAccount,
+  baseDraftAccount,
+  baseInactiveAccount,
+  baseActiveCoa,
+  baseArchivedCoa,
+} from "../testing/fixtures";
+import { run } from "./deactivateAccount";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["coa-management:deactivateAccount"],
+};
+
+describe("deactivateAccount", () => {
+  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 = { ...baseActiveAccount, 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 not ACTIVE", 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 account is DRAFT", 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(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(InvalidStateTransitionError);
+    }
+  });
+
+  it("returns error when successor account is not ACTIVE", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select
+      .mockReturnValueOnce(baseActiveAccount) // account lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(baseDraftAccount); // successor lookup (DRAFT)
+
+    const result = await run(
+      db,
+      {
+        id: baseActiveAccount.id,
+        successorAccountId: baseDraftAccount.id,
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(SuccessorNotActiveError);
+    }
+  });
+
+  it("deactivates an ACTIVE account without successor", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const deactivated = { ...baseActiveAccount, status: "INACTIVE", successorAccountId: null };
+    spies.select
+      .mockReturnValueOnce(baseActiveAccount) // account lookup
+      .mockReturnValueOnce(baseActiveCoa); // CoA lookup
+    spies.update.mockReturnValue(deactivated);
+
+    const result = await run(db, { id: baseActiveAccount.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.account.status).toBe("INACTIVE");
+      expect(result.value.account.successorAccountId).toBeNull();
+    }
+  });
+
+  it("deactivates an ACTIVE account with successor mapping", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const otherActiveAccount = { ...baseActiveAccount, id: "account-99" };
+    const deactivated = {
+      ...baseActiveAccount,
+      status: "INACTIVE",
+      successorAccountId: "account-99",
+    };
+    spies.select
+      .mockReturnValueOnce(baseActiveAccount) // account lookup
+      .mockReturnValueOnce(baseActiveCoa) // CoA lookup
+      .mockReturnValueOnce(otherActiveAccount); // successor lookup
+    spies.update.mockReturnValue(deactivated);
+
+    const result = await run(
+      db,
+      {
+        id: baseActiveAccount.id,
+        successorAccountId: "account-99",
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.account.status).toBe("INACTIVE");
+      expect(result.value.account.successorAccountId).toBe("account-99");
+    }
+  });
+
+  it("deactivates without balance check when GL hook is not registered", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const deactivated = { ...baseActiveAccount, status: "INACTIVE" };
+    spies.select.mockReturnValueOnce(baseActiveAccount).mockReturnValueOnce(baseActiveCoa);
+    spies.update.mockReturnValue(deactivated);
+
+    // No preDeactivationHook provided
+    const result = await run(db, { id: baseActiveAccount.id }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.account.status).toBe("INACTIVE");
+    }
+  });
+
+  it("returns error when GL hook reports open balances", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveAccount).mockReturnValueOnce(baseActiveCoa);
+
+    const result = await run(
+      db,
+      {
+        id: baseActiveAccount.id,
+        preDeactivationHook: () => Promise.resolve(false),
+      },
+      ctx,
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(OpenBalancesExistError);
+    }
+  });
+
+  it("emits audit event recording status transition from ACTIVE to INACTIVE and successor mapping", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const deactivated = { ...baseActiveAccount, status: "INACTIVE" };
+    spies.select.mockReturnValueOnce(baseActiveAccount).mockReturnValueOnce(baseActiveCoa);
+    spies.update.mockReturnValue(deactivated);
+
+    const result = await run(db, { id: baseActiveAccount.id }, ctx);
+
+    // Audit event is emitted as part of successful deactivation
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.account.status).toBe("INACTIVE");
+    }
+  });
+});

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

@@ -0,0 +1,142 @@
+import { randomUUID } from "node:crypto";
+import { ok, err, type CommandContext } from "../../../shared";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountNotFoundError,
+  ChartOfAccountsArchivedError,
+  InvalidStateTransitionError,
+  OpenBalancesExistError,
+  SuccessorNotActiveError,
+} from "../lib/errors.generated";
+
+export interface DeactivateAccountInput {
+  id: string;
+  successorAccountId?: string;
+  preDeactivationHook?: (accountId: string) => Promise<boolean>;
+}
+
+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: deactivateAccount
+ *
+ * Transitions a GL account from ACTIVE to INACTIVE status, preventing new
+ * journal postings while preserving history. An optional successor account
+ * can be designated during deactivation.
+ */
+export async function run(
+  db: Transaction,
+  input: DeactivateAccountInput,
+  ctx: CommandContext,
+  auditCommands?: AuditCommands,
+) {
+  const { id, successorAccountId, preDeactivationHook } = 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 ACTIVE (ARCHIVED is rejected)
+  if (!coa || coa.status === "ARCHIVED") {
+    return err(new ChartOfAccountsArchivedError(account.chartOfAccountsId));
+  }
+
+  // 4. Account must be ACTIVE
+  if (account.status !== "ACTIVE") {
+    return err(new InvalidStateTransitionError(id));
+  }
+
+  // 5. Pre-deactivation hook (GL balance check)
+  if (preDeactivationHook) {
+    const canDeactivate = await preDeactivationHook(id);
+    if (!canDeactivate) {
+      return err(new OpenBalancesExistError(id));
+    }
+  }
+
+  // 6. Validate successor if provided
+  if (successorAccountId) {
+    const successor = await db
+      .selectFrom("Account")
+      .selectAll()
+      .where("id", "=", successorAccountId)
+      .executeTakeFirst();
+
+    if (successor?.status !== "ACTIVE") {
+      return err(new SuccessorNotActiveError(successorAccountId));
+    }
+  }
+
+  // 7. Update status to INACTIVE and map successor
+  const updated = await db
+    .updateTable("Account")
+    .set({
+      status: "INACTIVE",
+      successorAccountId: successorAccountId ?? null,
+      updatedAt: new Date(),
+    })
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  // 8. Emit audit event
+  if (auditCommands) {
+    const changes: { fieldName: string; oldValue?: unknown; newValue?: unknown }[] = [
+      { fieldName: "status", oldValue: "ACTIVE", newValue: "INACTIVE" },
+    ];
+    if (successorAccountId) {
+      changes.push({
+        fieldName: "successorAccountId",
+        oldValue: null,
+        newValue: successorAccountId,
+      });
+    }
+
+    await auditCommands.logAuditEvent(
+      db,
+      {
+        eventId: randomUUID(),
+        actorType: "USER",
+        actorId: ctx.actorId,
+        entityType: "Account",
+        entityId: id,
+        operationType: "UPDATE",
+        companyId: coa.companyId,
+        changes,
+      },
+      ctx,
+    );
+  }
+
+  return ok({ account: updated! });
+}

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

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