@tailor-platform/erp-kit 0.3.0 → 0.4.1

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

@@ -0,0 +1,191 @@
+import { randomUUID } from "node:crypto";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  AccountGroupNotFoundError,
+  ChartOfAccountsArchivedError,
+  NameRequiredError,
+  InvalidNumberRangeError,
+  AccountsOutOfRangeError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface UpdateAccountGroupInput {
+  id: string;
+  name?: string;
+  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: updateAccountGroup
+ *
+ * Modifies the mutable fields (name, sort order, number range) of an existing
+ * account group. Code is immutable after creation.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdateAccountGroupInput & CF,
+  ctx: CommandContext,
+  auditCommands?: AuditCommands,
+) {
+  const { id, name, sortOrder, numberRangeStart, numberRangeEnd, ...customFields } = 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. Validate name if provided
+  if (name?.trim() === "") {
+    return err(new NameRequiredError(name));
+  }
+
+  // 4. Validate number range if changed
+  const newRangeStart =
+    numberRangeStart !== undefined ? numberRangeStart : existing.numberRangeStart;
+  const newRangeEnd = numberRangeEnd !== undefined ? numberRangeEnd : existing.numberRangeEnd;
+
+  // Both bounds must be provided together — one-sided ranges are invalid
+  if ((newRangeStart !== null) !== (newRangeEnd !== null)) {
+    return err(new InvalidNumberRangeError(`${newRangeStart ?? "null"}-${newRangeEnd ?? "null"}`));
+  }
+
+  if (newRangeStart !== null && newRangeEnd !== null) {
+    // Range must be valid: start < end
+    if (newRangeStart >= newRangeEnd) {
+      return err(new InvalidNumberRangeError(`${newRangeStart}-${newRangeEnd}`));
+    }
+
+    // Check overlap with other groups in the same CoA (excluding self)
+    if (numberRangeStart !== undefined || numberRangeEnd !== undefined) {
+      const existingGroups = await db
+        .selectFrom("AccountGroup")
+        .selectAll()
+        .where("chartOfAccountsId", "=", existing.chartOfAccountsId)
+        .execute();
+
+      for (const group of existingGroups) {
+        if (group.id === id) continue;
+        if (group.numberRangeStart !== null && group.numberRangeEnd !== null) {
+          if (newRangeStart <= group.numberRangeEnd && newRangeEnd >= group.numberRangeStart) {
+            return err(new InvalidNumberRangeError(`${newRangeStart}-${newRangeEnd}`));
+          }
+        }
+      }
+
+      // 5. Check existing accounts within the new range
+      const assignedAccounts = await db
+        .selectFrom("Account")
+        .selectAll()
+        .where("accountGroupId", "=", id)
+        .execute();
+
+      for (const account of assignedAccounts) {
+        const accountCode = parseInt(account.code, 10);
+        if (!isNaN(accountCode)) {
+          if (accountCode < newRangeStart || accountCode > newRangeEnd) {
+            return err(new AccountsOutOfRangeError(id));
+          }
+        }
+      }
+    }
+  }
+
+  // 6. Build update data
+  const updateData: Record<string, unknown> = {
+    ...customFields,
+    updatedAt: new Date(),
+  };
+
+  if (name !== undefined) updateData.name = name;
+  if (sortOrder !== undefined) updateData.sortOrder = sortOrder;
+  if (numberRangeStart !== undefined) updateData.numberRangeStart = numberRangeStart;
+  if (numberRangeEnd !== undefined) updateData.numberRangeEnd = numberRangeEnd;
+
+  const accountGroup = await db
+    .updateTable("AccountGroup")
+    .set(updateData)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  // 7. Emit audit event
+  if (auditCommands) {
+    const changes: { fieldName: string; oldValue?: unknown; newValue?: unknown }[] = [];
+    if (name !== undefined && name !== existing.name) {
+      changes.push({ fieldName: "name", oldValue: existing.name, newValue: name });
+    }
+    if (sortOrder !== undefined && sortOrder !== existing.sortOrder) {
+      changes.push({ fieldName: "sortOrder", oldValue: existing.sortOrder, newValue: sortOrder });
+    }
+    if (numberRangeStart !== undefined && numberRangeStart !== existing.numberRangeStart) {
+      changes.push({
+        fieldName: "numberRangeStart",
+        oldValue: existing.numberRangeStart,
+        newValue: numberRangeStart,
+      });
+    }
+    if (numberRangeEnd !== undefined && numberRangeEnd !== existing.numberRangeEnd) {
+      changes.push({
+        fieldName: "numberRangeEnd",
+        oldValue: existing.numberRangeEnd,
+        newValue: numberRangeEnd,
+      });
+    }
+
+    if (changes.length > 0) {
+      await auditCommands.logAuditEvent(
+        db,
+        {
+          eventId: randomUUID(),
+          actorType: "USER",
+          actorId: ctx.actorId,
+          entityType: "AccountGroup",
+          entityId: id,
+          operationType: "UPDATE",
+          companyId: coa!.companyId,
+          changes,
+        },
+        ctx,
+      );
+    }
+  }
+
+  return ok({ accountGroup: accountGroup! });
+}

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

@@ -0,0 +1,6 @@
+// @generated — do not edit
+import { permissions } from "../lib/permissions.generated";
+import { run } from "./updateChartOfAccounts";
+import { defineCommand } from "@tailor-platform/erp-kit/module";
+
+export const updateChartOfAccounts = defineCommand(permissions.updateChartOfAccounts, run);

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

@@ -0,0 +1,153 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ChartOfAccountsNotFoundError,
+  ChartOfAccountsArchivedError,
+  NameRequiredError,
+} from "../lib/errors.generated";
+import { baseDraftCoa, baseActiveCoa, baseArchivedCoa } from "../testing/fixtures";
+import { run, type AuditCommands } from "./updateChartOfAccounts";
+import type { CommandContext } from "@tailor-platform/erp-kit/module";
+
+const ctx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["coa-management:updateChartOfAccounts"],
+};
+
+describe("updateChartOfAccounts", () => {
+  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", name: "New Name" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ChartOfAccountsNotFoundError);
+    }
+  });
+
+  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, name: "New Name" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(ChartOfAccountsArchivedError);
+    }
+  });
+
+  it("returns error when name is empty", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseDraftCoa);
+
+    const result = await run(db, { id: baseDraftCoa.id, name: "" }, ctx);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toBeInstanceOf(NameRequiredError);
+    }
+  });
+
+  it("updates name of a DRAFT CoA", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedCoa = { ...baseDraftCoa, name: "Updated Name" };
+    spies.select.mockReturnValueOnce(baseDraftCoa);
+    spies.update.mockReturnValue(updatedCoa);
+
+    const result = await run(db, { id: baseDraftCoa.id, name: "Updated Name" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.chartOfAccounts.name).toBe("Updated Name");
+    }
+  });
+
+  it("updates description of an ACTIVE CoA", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedCoa = { ...baseActiveCoa, description: "Updated description" };
+    spies.select.mockReturnValueOnce(baseActiveCoa);
+    spies.update.mockReturnValue(updatedCoa);
+
+    const result = await run(db, { id: baseActiveCoa.id, description: "Updated description" }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.chartOfAccounts.description).toBe("Updated description");
+    }
+  });
+
+  it("clears description by setting to null", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedCoa = { ...baseActiveCoa, description: null };
+    spies.select.mockReturnValueOnce(baseActiveCoa);
+    spies.update.mockReturnValue(updatedCoa);
+
+    const result = await run(db, { id: baseActiveCoa.id, description: null }, ctx);
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.chartOfAccounts.description).toBeNull();
+    }
+  });
+
+  it("passes custom fields through to update", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedCoa = { ...baseDraftCoa, customField: "custom-value" };
+    spies.select.mockReturnValueOnce(baseDraftCoa);
+    spies.update.mockReturnValue(updatedCoa);
+
+    const result = await run(
+      db,
+      { id: baseDraftCoa.id, name: "Updated", customField: "custom-value" } as UpdateInput,
+      ctx,
+    );
+
+    expect(result.ok).toBe(true);
+    // Verify set spy was called with custom fields
+    expect(spies.set).toHaveBeenCalled();
+    const setData = spies.set.mock.calls[0][0] as Record<string, unknown>;
+    expect(setData.customField).toBe("custom-value");
+  });
+  it("emits audit event recording previous and new field values", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    const updatedCoa = { ...baseDraftCoa, name: "Updated Name" };
+    spies.select.mockReturnValueOnce(baseDraftCoa);
+    spies.update.mockReturnValue(updatedCoa);
+
+    const mockLogAuditEvent = vi.fn().mockResolvedValue({ ok: true, value: {} });
+    const auditCommands: AuditCommands = { logAuditEvent: mockLogAuditEvent };
+
+    const result = await run(db, { id: baseDraftCoa.id, name: "Updated Name" }, ctx, auditCommands);
+
+    expect(result.ok).toBe(true);
+    expect(mockLogAuditEvent).toHaveBeenCalledWith(
+      db,
+      expect.objectContaining({
+        entityType: "ChartOfAccounts",
+        entityId: baseDraftCoa.id,
+        operationType: "UPDATE",
+        companyId: baseDraftCoa.companyId,
+        actorType: "USER",
+        actorId: ctx.actorId,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        changes: expect.arrayContaining([
+          { fieldName: "name", oldValue: baseDraftCoa.name, newValue: "Updated Name" },
+        ]),
+      }),
+      ctx,
+    );
+  });
+});
+
+// Helper type for custom fields test
+interface UpdateInput {
+  id: string;
+  name?: string;
+  description?: string | null;
+  customField: string;
+  [key: string]: unknown;
+}

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

@@ -0,0 +1,133 @@
+import { randomUUID } from "node:crypto";
+import type { Transaction } from "../generated/kysely-tailordb";
+import {
+  ChartOfAccountsNotFoundError,
+  ChartOfAccountsArchivedError,
+  NameRequiredError,
+} from "../lib/errors.generated";
+import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export interface UpdateChartOfAccountsInput {
+  id: string;
+  name?: string;
+  description?: 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: updateChartOfAccounts
+ *
+ * Modifies the mutable fields (name, description) of an existing Chart of Accounts.
+ * Updates are permitted while the CoA is in DRAFT or ACTIVE status.
+ */
+export async function run<CF extends Record<string, unknown>>(
+  db: Transaction,
+  input: UpdateChartOfAccountsInput & CF,
+  ctx: CommandContext,
+  auditCommands?: AuditCommands,
+) {
+  const { id, name, description, ...customFields } = 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 not be ARCHIVED
+  if (existing.status === "ARCHIVED") {
+    return err(new ChartOfAccountsArchivedError(id));
+  }
+
+  // 3. Validate name if provided
+  if (name?.trim() === "") {
+    return err(new NameRequiredError(id));
+  }
+
+  // 4. Build update object
+  const RESERVED_KEYS = new Set([
+    "id",
+    "status",
+    "name",
+    "description",
+    "companyId",
+    "createdAt",
+    "updatedAt",
+  ]);
+  const safeCustomFields: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(customFields)) {
+    if (!RESERVED_KEYS.has(key)) {
+      safeCustomFields[key] = value;
+    }
+  }
+
+  const updateData: Record<string, unknown> = {
+    ...safeCustomFields,
+    updatedAt: new Date(),
+  };
+
+  if (name !== undefined) updateData.name = name;
+  if (description !== undefined) updateData.description = description;
+
+  const chartOfAccounts = await db
+    .updateTable("ChartOfAccounts")
+    .set(updateData)
+    .where("id", "=", id)
+    .returningAll()
+    .executeTakeFirst();
+
+  if (auditCommands) {
+    const changes: { fieldName: string; oldValue?: unknown; newValue?: unknown }[] = [];
+    if (name !== undefined && name !== existing.name) {
+      changes.push({ fieldName: "name", oldValue: existing.name, newValue: name });
+    }
+    if (description !== undefined && description !== existing.description) {
+      changes.push({
+        fieldName: "description",
+        oldValue: existing.description,
+        newValue: description,
+      });
+    }
+
+    if (changes.length > 0) {
+      await auditCommands.logAuditEvent(
+        db,
+        {
+          eventId: randomUUID(),
+          actorType: "USER",
+          actorId: ctx.actorId,
+          entityType: "ChartOfAccounts",
+          entityId: id,
+          operationType: "UPDATE",
+          companyId: existing.companyId,
+          changes,
+        },
+        ctx,
+      );
+    }
+  }
+
+  return ok({ chartOfAccounts: chartOfAccounts! });
+}

package/src/modules/coa-management/db/account.ts

@@ -0,0 +1,119 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { currency as currencyStub } from "../lib/_db_deps";
+import { chartOfAccounts as chartOfAccountsStub } from "./chartOfAccounts";
+import { accountGroup as accountGroupStub } from "./accountGroup";
+
+export const BASE_ACCOUNT_STATUSES = ["DRAFT", "ACTIVE", "INACTIVE"] as const;
+
+export const ACCOUNT_TYPES = ["ASSET", "LIABILITY", "EQUITY", "REVENUE", "EXPENSE"] as const;
+
+export const ACCOUNT_CLASSIFICATIONS = [
+  "REGULAR",
+  "RECEIVABLE",
+  "PAYABLE",
+  "BANK_CASH",
+  "FIXED_ASSET",
+  "RETAINED_EARNINGS",
+  "NON_POSTING",
+] as const;
+
+export interface CreateAccountTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  additionalStatuses?: string[];
+  chartOfAccountsType?: TailorAnyDBType;
+  accountGroupType?: TailorAnyDBType;
+  currencyType?: TailorAnyDBType;
+}
+
+export function createAccountType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateAccountTypeParams<F>,
+) {
+  const statuses = [...BASE_ACCOUNT_STATUSES, ...(params.additionalStatuses ?? [])] as [
+    string,
+    ...string[],
+  ];
+
+  return db
+    .type("Account", {
+      code: db.string().description("Structured numeric account code, unique within the CoA"),
+      name: db.string().description("Descriptive name of the GL account"),
+      accountType: db
+        .enum(["ASSET", "LIABILITY", "EQUITY", "REVENUE", "EXPENSE"])
+        .description("Account type: ASSET, LIABILITY, EQUITY, REVENUE, or EXPENSE"),
+      classification: db
+        .enum([
+          "REGULAR",
+          "RECEIVABLE",
+          "PAYABLE",
+          "BANK_CASH",
+          "FIXED_ASSET",
+          "RETAINED_EARNINGS",
+          "NON_POSTING",
+        ])
+        .description("Operational classification of the account"),
+      chartOfAccountsId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.chartOfAccountsType ?? chartOfAccountsStub },
+          backward: "accounts",
+        })
+        .description("Foreign key to the parent ChartOfAccounts"),
+      accountGroupId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountGroupType ?? accountGroupStub },
+          backward: "accounts",
+        })
+        .description("Optional foreign key to AccountGroup for hierarchical organization"),
+      currencyRestriction: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: params.currencyType ?? currencyStub },
+          backward: "accounts",
+        })
+        .description(
+          "Optional currency restriction; when set, only postings in this currency are accepted",
+        ),
+      reconciliation: db.bool().description("Whether this account requires reconciliation"),
+      defaultTaxCode: db
+        .string({ optional: true })
+        .description(
+          "Optional default tax code (free-text, future migration to validated reference)",
+        ),
+      tags: db
+        .string({ optional: true })
+        .description("Comma-separated string labels for categorization (e.g. 'tag1,tag2')"),
+      successorAccountId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: "self" },
+          backward: "predecessorAccounts",
+        })
+        .description("Optional successor account mapped during deactivation"),
+      hasPostedTransactions: db
+        .bool()
+        .description("Flag indicating whether the account has posted transactions"),
+      status: db.enum(statuses).description("Lifecycle status: DRAFT, ACTIVE, INACTIVE"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["chartOfAccountsId", "code"],
+      unique: true,
+      name: "account_coa_code_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const account = createAccountType({});

package/src/modules/coa-management/db/accountGroup.ts

@@ -0,0 +1,57 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { chartOfAccounts as chartOfAccountsStub } from "./chartOfAccounts";
+
+export interface CreateAccountGroupTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  chartOfAccountsType?: TailorAnyDBType;
+}
+
+export function createAccountGroupType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateAccountGroupTypeParams<F>,
+) {
+  return db
+    .type("AccountGroup", {
+      code: db.string().description("Unique group code within the CoA"),
+      name: db.string().description("Display name of the account group"),
+      chartOfAccountsId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.chartOfAccountsType ?? chartOfAccountsStub },
+          backward: "accountGroups",
+        })
+        .description("Foreign key to the parent ChartOfAccounts"),
+      parentAccountGroupId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: "self" },
+          backward: "childAccountGroups",
+        })
+        .description("Optional parent group for hierarchical nesting"),
+      sortOrder: db.int({ optional: true }).description("Display sequence among sibling groups"),
+      numberRangeStart: db
+        .int({ optional: true })
+        .description("Start of the allowed account number range (inclusive)"),
+      numberRangeEnd: db
+        .int({ optional: true })
+        .description("End of the allowed account number range (inclusive)"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["chartOfAccountsId", "code"],
+      unique: true,
+      name: "account_group_coa_code_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const accountGroup = createAccountGroupType({});