@tailor-platform/erp-kit 0.6.0 → 0.7.0

package/src/modules/finance-ledger/query/listFiscalYears.ts

@@ -0,0 +1,45 @@
+import {
+  ok,
+  type ReadonlyDB,
+  type PaginationInput,
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+} from "@tailor-platform/erp-kit/module";
+import type { DB } from "../generated/kysely-tailordb";
+
+type FiscalYearOrderByField = "startDate" | "endDate" | "name" | "createdAt";
+
+export interface ListFiscalYearsInput extends PaginationInput<FiscalYearOrderByField> {
+  companyId: string;
+  startDate?: Date;
+  endDate?: Date;
+}
+
+/**
+ * Function: listFiscalYears
+ *
+ * Lists fiscal years for a company with optional date range filters.
+ */
+export async function run(db: ReadonlyDB<DB>, input: ListFiscalYearsInput) {
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "startDate";
+  const orderDirection = input.orderDirection ?? "asc";
+
+  let query = db.selectFrom("FiscalYear").selectAll().where("companyId", "=", input.companyId);
+
+  if (input.startDate) {
+    query = query.where("endDate", ">=", input.startDate);
+  }
+  if (input.endDate) {
+    query = query.where("startDate", "<=", input.endDate);
+  }
+
+  const results = await query
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+
+  return ok(buildPaginatedResult(results, limit));
+}

package/src/modules/finance-ledger/query/listJournalEntries.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+import { run } from "./listJournalEntries";
+
+export const listJournalEntries = defineQuery(run);

package/src/modules/finance-ledger/query/listJournalEntries.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseJournalEntry, postedJournalEntry } from "../testing/fixtures";
+import { run } from "./listJournalEntries";
+
+describe("listJournalEntries", () => {
+  it("returns all journal entries for a company", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseJournalEntry, postedJournalEntry]);
+
+    const result = await run(db, { companyId: "company-1" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseJournalEntry, postedJournalEntry]);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+
+  it("returns journal entries filtered by accounting period", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseJournalEntry]);
+
+    const result = await run(db, {
+      companyId: "company-1",
+      accountingPeriodId: "period-1",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseJournalEntry]);
+    }
+  });
+
+  it("returns journal entries filtered by journal type", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseJournalEntry]);
+
+    const result = await run(db, {
+      companyId: "company-1",
+      journalType: "MISCELLANEOUS",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseJournalEntry]);
+    }
+  });
+
+  it("returns journal entries filtered by status", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([postedJournalEntry]);
+
+    const result = await run(db, { companyId: "company-1", status: "POSTED" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([postedJournalEntry]);
+    }
+  });
+
+  it("returns journal entries filtered by date range", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseJournalEntry]);
+
+    const result = await run(db, {
+      companyId: "company-1",
+      startDate: new Date("2024-01-01"),
+      endDate: new Date("2024-01-31"),
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseJournalEntry]);
+    }
+  });
+
+  it("returns empty list when no journal entries match", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([]);
+
+    const result = await run(db, { companyId: "nonexistent" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([]);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+});

package/src/modules/finance-ledger/query/listJournalEntries.ts

@@ -0,0 +1,64 @@
+import {
+  ok,
+  type ReadonlyDB,
+  type PaginationInput,
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+} from "@tailor-platform/erp-kit/module";
+import type { JournalEntryJournalType, JournalEntryStatus } from "../generated/enums";
+import type { DB } from "../generated/kysely-tailordb";
+
+type JournalEntryOrderByField =
+  | "entryDate"
+  | "referenceNumber"
+  | "journalType"
+  | "status"
+  | "createdAt";
+
+export interface ListJournalEntriesInput extends PaginationInput<JournalEntryOrderByField> {
+  companyId: string;
+  accountingPeriodId?: string;
+  journalType?: string;
+  status?: string;
+  startDate?: Date;
+  endDate?: Date;
+}
+
+/**
+ * Function: listJournalEntries
+ *
+ * Lists journal entry headers for a company with optional filters for
+ * accounting period, journal type, status, and date range.
+ */
+export async function run(db: ReadonlyDB<DB>, input: ListJournalEntriesInput) {
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "entryDate";
+  const orderDirection = input.orderDirection ?? "desc";
+
+  let query = db.selectFrom("JournalEntry").selectAll().where("companyId", "=", input.companyId);
+
+  if (input.accountingPeriodId) {
+    query = query.where("accountingPeriodId", "=", input.accountingPeriodId);
+  }
+  if (input.journalType) {
+    query = query.where("journalType", "=", input.journalType as JournalEntryJournalType);
+  }
+  if (input.status) {
+    query = query.where("status", "=", input.status as JournalEntryStatus);
+  }
+  if (input.startDate) {
+    query = query.where("entryDate", ">=", input.startDate);
+  }
+  if (input.endDate) {
+    query = query.where("entryDate", "<=", input.endDate);
+  }
+
+  const results = await query
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+
+  return ok(buildPaginatedResult(results, limit));
+}

package/src/modules/finance-ledger/query/listPeriodCloses.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+import { run } from "./listPeriodCloses";
+
+export const listPeriodCloses = defineQuery(run);

package/src/modules/finance-ledger/query/listPeriodCloses.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { basePeriodClose, inProgressPeriodClose } from "../testing/fixtures";
+import { run } from "./listPeriodCloses";
+
+describe("listPeriodCloses", () => {
+  it("returns all period closes for a company", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([basePeriodClose, inProgressPeriodClose]);
+
+    const result = await run(db, { companyId: "company-1" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([basePeriodClose, inProgressPeriodClose]);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+
+  it("returns period closes filtered by fiscal year", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([basePeriodClose]);
+
+    const result = await run(db, {
+      companyId: "company-1",
+      fiscalYearId: "fiscal-year-1",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([basePeriodClose]);
+    }
+  });
+
+  it("returns period closes filtered by status", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([inProgressPeriodClose]);
+
+    const result = await run(db, {
+      companyId: "company-1",
+      status: "IN_PROGRESS",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([inProgressPeriodClose]);
+    }
+  });
+
+  it("returns empty list when no period closes match", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([]);
+
+    const result = await run(db, { companyId: "nonexistent" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([]);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+});

package/src/modules/finance-ledger/query/listPeriodCloses.ts

@@ -0,0 +1,64 @@
+import {
+  ok,
+  type ReadonlyDB,
+  type PaginationInput,
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+} from "@tailor-platform/erp-kit/module";
+import type { PeriodCloseStatus } from "../generated/enums";
+import type { DB } from "../generated/kysely-tailordb";
+
+type PeriodCloseOrderByField = "status" | "completionPercentage";
+
+export interface ListPeriodClosesInput extends PaginationInput<PeriodCloseOrderByField> {
+  companyId: string;
+  fiscalYearId?: string;
+  status?: string;
+}
+
+/**
+ * Function: listPeriodCloses
+ *
+ * Lists period close records for a company. Since PeriodClose doesn't have a
+ * direct companyId, a subquery through AccountingPeriod is used to filter by
+ * company and optionally by fiscal year. Results are sorted by the associated
+ * accounting period's startDate ascending by default.
+ */
+export async function run(db: ReadonlyDB<DB>, input: ListPeriodClosesInput) {
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderDirection = input.orderDirection ?? "asc";
+
+  let periodSubquery = db
+    .selectFrom("AccountingPeriod")
+    .select("id")
+    .where("companyId", "=", input.companyId);
+
+  if (input.fiscalYearId) {
+    periodSubquery = periodSubquery.where("fiscalYearId", "=", input.fiscalYearId);
+  }
+
+  let query = db
+    .selectFrom("PeriodClose")
+    .innerJoin("AccountingPeriod", "AccountingPeriod.id", "PeriodClose.accountingPeriodId")
+    .selectAll("PeriodClose")
+    .where("PeriodClose.accountingPeriodId", "in", periodSubquery);
+
+  if (input.status) {
+    query = query.where("PeriodClose.status", "=", input.status as PeriodCloseStatus);
+  }
+
+  // Default sort is by AccountingPeriod.startDate ascending per spec
+  if (input.orderBy) {
+    query = query.orderBy(`PeriodClose.${input.orderBy}` as never, orderDirection);
+  } else {
+    query = query.orderBy("AccountingPeriod.startDate", orderDirection);
+  }
+
+  const results = await query
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+
+  return ok(buildPaginatedResult(results, limit));
+}

package/src/modules/finance-ledger/query/listTrialBalances.generated.ts

@@ -0,0 +1,5 @@
+// @generated — do not edit
+import { defineQuery } from "@tailor-platform/erp-kit/module";
+import { run } from "./listTrialBalances";
+
+export const listTrialBalances = defineQuery(run);

package/src/modules/finance-ledger/query/listTrialBalances.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { createMockDb } from "../../../testing/index";
+import type { DB } from "../generated/kysely-tailordb";
+import { baseTrialBalance } from "../testing/fixtures";
+import { run } from "./listTrialBalances";
+
+describe("listTrialBalances", () => {
+  it("returns all trial balances for a company", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseTrialBalance]);
+
+    const result = await run(db, { companyId: "company-1" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseTrialBalance]);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+
+  it("returns trial balances filtered by accounting period", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseTrialBalance]);
+
+    const result = await run(db, {
+      companyId: "company-1",
+      accountingPeriodId: "period-1",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseTrialBalance]);
+    }
+  });
+
+  it("returns trial balances filtered by variant", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseTrialBalance]);
+
+    const result = await run(db, {
+      companyId: "company-1",
+      variant: "PRE_CLOSE",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseTrialBalance]);
+    }
+  });
+
+  it("returns trial balances filtered by fiscal year via subquery", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([baseTrialBalance]);
+
+    const result = await run(db, {
+      companyId: "company-1",
+      fiscalYearId: "fiscal-year-1",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([baseTrialBalance]);
+    }
+  });
+
+  it("returns empty list when no trial balances match", async () => {
+    const { db, spies } = createMockDb<DB>();
+    spies.select.mockReturnValue([]);
+
+    const result = await run(db, { companyId: "nonexistent" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.items).toEqual([]);
+      expect(result.value.hasNextPage).toBe(false);
+    }
+  });
+});

package/src/modules/finance-ledger/query/listTrialBalances.ts

@@ -0,0 +1,56 @@
+import {
+  ok,
+  type ReadonlyDB,
+  type PaginationInput,
+  buildPaginatedResult,
+  DEFAULT_PAGE_SIZE,
+} from "@tailor-platform/erp-kit/module";
+import type { TrialBalanceVariant } from "../generated/enums";
+import type { DB } from "../generated/kysely-tailordb";
+
+type TrialBalanceOrderByField = "generatedAt" | "variant" | "createdAt";
+
+export interface ListTrialBalancesInput extends PaginationInput<TrialBalanceOrderByField> {
+  companyId: string;
+  accountingPeriodId?: string;
+  variant?: string;
+  fiscalYearId?: string;
+}
+
+/**
+ * Function: listTrialBalances
+ *
+ * Lists trial balance headers for a company with optional filters for
+ * accounting period, variant, and fiscal year. When fiscalYearId is provided,
+ * a subquery finds accounting period IDs belonging to that fiscal year.
+ */
+export async function run(db: ReadonlyDB<DB>, input: ListTrialBalancesInput) {
+  const limit = input.limit ?? DEFAULT_PAGE_SIZE;
+  const offset = input.offset ?? 0;
+  const orderBy = input.orderBy ?? "generatedAt";
+  const orderDirection = input.orderDirection ?? "desc";
+
+  let query = db.selectFrom("TrialBalance").selectAll().where("companyId", "=", input.companyId);
+
+  if (input.accountingPeriodId) {
+    query = query.where("accountingPeriodId", "=", input.accountingPeriodId);
+  }
+  if (input.variant) {
+    query = query.where("variant", "=", input.variant as TrialBalanceVariant);
+  }
+  if (input.fiscalYearId) {
+    query = query.where(
+      "accountingPeriodId",
+      "in",
+      db.selectFrom("AccountingPeriod").select("id").where("fiscalYearId", "=", input.fiscalYearId),
+    );
+  }
+
+  const results = await query
+    .orderBy(orderBy, orderDirection)
+    .limit(limit + 1)
+    .offset(offset)
+    .execute();
+
+  return ok(buildPaginatedResult(results, limit));
+}

package/src/modules/finance-ledger/seed/index.ts

@@ -0,0 +1,19 @@
+// Export seed data maps here.
+// Use PascalCase names matching entity types — `erp-kit app generate seed`
+// discovers exports automatically and writes <ExportName>.jsonl files.
+//
+// Example:
+//
+//   import { uuidv5 } from "../../../shared/uuidv5";
+//   const NS = "erp-kit:<module-name>";
+//
+//   export const entityIds = {
+//     foo: uuidv5(NS, "entity:foo"),
+//   } as const;
+//
+//   const entities: Record<string, SeedRow> = {
+//     [entityIds.foo]: { name: "Foo", ... },
+//   };
+//
+//   // Re-export with PascalCase entity name
+//   export { entities as Entity };

package/src/modules/finance-ledger/tailor.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig, definePlugins } from "@tailor-platform/sdk";
+import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
+import { enumConstantsPlugin } from "@tailor-platform/sdk/plugin/enum-constants";
+
+export default defineConfig({
+  name: "finance-ledger",
+  db: { "main-db": { files: [`./db/*.ts`, `./lib/_db_deps.ts`] } },
+});
+
+export const plugins = definePlugins(
+  kyselyTypePlugin({ distPath: `./generated/kysely-tailordb.ts` }),
+  enumConstantsPlugin({ distPath: "./generated/enums.ts" }),
+);

package/src/modules/finance-ledger/tailor.d.ts

@@ -0,0 +1,13 @@
+// This file is auto-generated by @tailor-platform/sdk
+// Do not edit this file manually
+// Regenerated automatically when running 'tailor-sdk apply' or 'tailor-sdk generate'
+
+declare module "@tailor-platform/sdk" {
+  interface AttributeMap {}
+  interface AttributeList {
+    __tuple?: [];
+  }
+  interface Env {}
+}
+
+export {};

package/src/modules/finance-ledger/testing/commandTestUtils.ts

@@ -0,0 +1,35 @@
+import { expect } from "vitest";
+import { type CommandContext } from "@tailor-platform/erp-kit/module";
+
+export const commandCtx: CommandContext = {
+  actorId: "test-actor",
+  permissions: ["finance-ledger:*"],
+};
+
+interface OkResult<T> {
+  ok: true;
+  value: T;
+}
+
+interface ErrResult {
+  ok: false;
+  error: unknown;
+}
+
+export function expectErr(
+  result: OkResult<unknown> | ErrResult,
+  errorClass: abstract new (...args: never[]) => Error,
+) {
+  expect(result.ok).toBe(false);
+  if (!result.ok) {
+    expect(result.error).toBeInstanceOf(errorClass);
+  }
+}
+
+export function expectOk<T>(result: OkResult<T> | ErrResult) {
+  expect(result.ok).toBe(true);
+  if (!result.ok) {
+    throw result.error;
+  }
+  return result.value;
+}