@accounter/server 0.0.9-alpha-20251231123714-6cdd9de71b4672d74ece5d34c438d162987b2c93 → 0.0.9-alpha-20251231171312-67d2850c6eacafb65d42d987f3d49dca3c0f8bdd

package/src/demo-fixtures/validators/types.ts

@@ -0,0 +1,83 @@
+/**
+ * TypeScript interfaces for ledger validation
+ *
+ * These types match the database schema from accounter_schema.ledger_records
+ * and provide context for comprehensive validation of demo data.
+ */
+
+/**
+ * Ledger record interface matching the database schema
+ *
+ * Numeric fields are typed as `string | null` because PostgreSQL returns
+ * numeric values as strings when queried via pg driver.
+ */
+export interface LedgerRecord {
+  id: string;
+  owner_id: string | null;
+  charge_id: string;
+
+  debit_entity1: string | null;
+  debit_foreign_amount1: string | null;
+  debit_local_amount1: string | null;
+
+  credit_entity1: string | null;
+  credit_foreign_amount1: string | null;
+  credit_local_amount1: string | null;
+
+  debit_entity2: string | null;
+  debit_foreign_amount2: string | null;
+  debit_local_amount2: string | null;
+
+  credit_entity2: string | null;
+  credit_foreign_amount2: string | null;
+  credit_local_amount2: string | null;
+
+  currency: string;
+  invoice_date: Date;
+  value_date: Date;
+  description: string | null;
+  reference1: string | null;
+  locked: boolean;
+}
+
+/**
+ * Validation context containing configuration for validation rules
+ *
+ * Used to pass contextual information to validator functions such as
+ * which use-case is being validated and what tolerance to use for
+ * balance comparisons.
+ */
+export interface ValidationContext {
+  /** Unique identifier of the use-case being validated */
+  useCaseId: string;
+
+  /** Default local currency (e.g., 'ILS') for foreign currency validation */
+  defaultCurrency: string;
+
+  /** Tolerance for floating-point balance comparisons (e.g., 0.01) */
+  tolerance: number;
+}
+
+/**
+ * Entity balance tracking for multi-record entity-level validation
+ *
+ * Aggregates debit and credit amounts across all ledger records
+ * for a specific financial entity to verify the entity's net
+ * position balances correctly.
+ */
+export interface EntityBalance {
+  /** Financial entity UUID */
+  entityId: string;
+
+  /** Total debit amount in local currency */
+  totalDebit: number;
+
+  /** Total credit amount in local currency */
+  totalCredit: number;
+
+  /** Net balance (totalDebit - totalCredit), should be ~0 */
+  netBalance: number;
+
+  /** Number of ledger records involving this entity */
+  recordCount: number;
+}

package/src/fixtures/fixture-spec.ts

@@ -0,0 +1,158 @@
+import type { LedgerRecord } from '../demo-fixtures/validators/types.js';
+import type { financial_account_type } from '../modules/financial-accounts/types.js';
+import type { CountryCode, Currency } from '../shared/enums.js';
+
+/**
+ * Tax Category Mapping for Financial Accounts
+ */
+export interface TaxCategoryMapping {
+  taxCategoryId: string;
+  currency: Currency;
+}
+
+/**
+ * Business Entity Fixture
+ */
+export interface BusinessFixture {
+  id: string;
+  name: string;
+  country: CountryCode;
+  canSettleWithReceipt: boolean;
+}
+
+/**
+ * Tax Category Fixture
+ */
+export interface TaxCategoryFixture {
+  id: string;
+  name: string;
+}
+
+/**
+ * Financial Account Fixture
+ */
+export interface FinancialAccountFixture {
+  id: string;
+  accountNumber: string;
+  type: financial_account_type; // 'BANK_ACCOUNT', 'CREDIT_CARD', etc.
+  currency: Currency;
+  taxCategoryMappings?: TaxCategoryMapping[];
+}
+
+/**
+ * Charge Fixture
+ */
+export interface ChargeFixture {
+  id: string;
+  ownerId: string; // Supports {{ADMIN_BUSINESS_ID}} placeholder
+  userDescription: string;
+}
+
+/**
+ * Transaction Fixture
+ */
+export interface TransactionFixture {
+  id: string;
+  chargeId: string;
+  businessId: string;
+  amount: string; // Decimal as string for precision
+  currency: Currency;
+  eventDate: string; // ISO date string
+  debitDate: string; // ISO date string
+  accountNumber: string;
+}
+
+/**
+ * Document Fixture
+ */
+export interface DocumentFixture {
+  id: string;
+  chargeId: string;
+  creditorId: string;
+  debtorId: string; // Supports {{ADMIN_BUSINESS_ID}} placeholder
+  serialNumber: string;
+  type: string; // 'INVOICE', 'RECEIPT', etc.
+  date: string; // ISO date string
+  totalAmount: string; // Decimal as string
+  currencyCode: Currency;
+}
+
+/**
+ * Tag Fixture (Optional)
+ */
+export interface TagFixture {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+/**
+ * Fixture Collection for a Use-Case
+ */
+export interface FixtureSpec {
+  businesses: BusinessFixture[];
+  taxCategories: TaxCategoryFixture[];
+  financialAccounts: FinancialAccountFixture[];
+  charges: ChargeFixture[];
+  transactions: TransactionFixture[];
+  documents: DocumentFixture[];
+  tags?: TagFixture[];
+}
+
+/**
+ * Use-Case Metadata
+ */
+export interface UseCaseMetadata {
+  author: string;
+  createdAt: string; // ISO date string
+  updatedAt: string; // ISO date string
+  volumeMultiplier?: number; // Optional: Create N instances (default 1)
+}
+
+/**
+ * Ledger Expectations for Validation
+ */
+export interface UseCaseExpectations {
+  ledgerRecordCount: number;
+  totalDebitILS?: string; // Decimal as string
+  totalCreditILS?: string; // Decimal as string
+}
+
+/**
+ * Use-Case Category
+ */
+export type UseCaseCategory = 'expenses' | 'income' | 'equity' | 'payroll' | 'other';
+
+/**
+ * Complete Use-Case Specification
+ */
+export interface UseCaseSpec {
+  id: string; // Unique slug: 'monthly-expense-foreign-currency'
+  name: string; // Display name: 'Monthly Expense (Foreign Currency)'
+  description: string; // Long-form explanation for docs
+  category: UseCaseCategory;
+  fixtures: FixtureSpec;
+  metadata: UseCaseMetadata;
+  expectations?: UseCaseExpectations;
+}
+
+/**
+ * Fixture Collection for a Use-Case
+ */
+export interface ExtendedFixtureSpec {
+  businesses: BusinessFixture[];
+  taxCategories: TaxCategoryFixture[];
+  financialAccounts: FinancialAccountFixture[];
+  charges: ChargeFixture[];
+  transactions: TransactionFixture[];
+  documents: DocumentFixture[];
+  meta?: {
+    id: string;
+    description?: string;
+    version?: string;
+    [key: string]: unknown;
+  };
+  tags?: TagFixture[];
+  expectations?: UseCaseExpectations & { ledger?: LedgerRecord[] };
+  placeholders?: Record<string, string>;
+}

package/src/modules/charges-matcher/__tests__/single-match-integration.test.ts

@@ -1,4 +1,10 @@
 import { describe, expect, it, vi } from 'vitest';
+
+// Mock merge-charges helper before importing providers that use it
+vi.mock('@modules/charges/helpers/merge-charges.helper.js', () => ({
+  mergeChargesExecutor: vi.fn(),
+}));
+
 import { createMockTransaction, createMockDocument } from './test-helpers.js';
 
 // Mock the module imports to avoid dependency issues

package/src/modules/ledger/__tests__/ledger-scenario-a.integration.test.ts

@@ -99,7 +99,8 @@ describe('Ledger Generation - Expense Scenario A', () => {
     try {
       await insertClient.query('BEGIN');
 
-      await insertFixture(insertClient, expenseScenarioA);
+      const adminContext = await buildAdminContextFromDb(insertClient);
+      await insertFixture(insertClient, expenseScenarioA, adminContext.defaultAdminBusinessId);
 
       const chargeId = makeUUID('charge', 'charge-office-supplies');
 
@@ -218,10 +219,11 @@ describe('Ledger Generation - Expense Scenario A', () => {
         `SELECT * FROM ${qualifyTable('charges')} WHERE id = $1`,
         [chargeId],
       );
+      const adminContext = await buildAdminContextFromDb(client);
       if (existingCharge.rows.length === 0) {
         // Reinsert fixture quickly
         await client.query('BEGIN');
-        await insertFixture(client, expenseScenarioA);
+        await insertFixture(client, expenseScenarioA, adminContext.defaultAdminBusinessId);
         await client.query('COMMIT');
       }
 
@@ -230,7 +232,6 @@ describe('Ledger Generation - Expense Scenario A', () => {
         [chargeId],
       );
       const charge = chargeResult.rows[0];
-      const adminContext = await buildAdminContextFromDb(client);
       const mockUser: UserType = {
         username: 'test-admin',
         userId: adminContext.defaultAdminBusinessId,

package/src/modules/ledger/__tests__/ledger-scenario-b.integration.test.ts

@@ -104,7 +104,10 @@ describe('Ledger Generation - Expense Scenario B (Foreign Currency)', () => {
     try {
       await insertClient.query('BEGIN');
 
-      await insertFixture(insertClient, expenseScenarioB);
+      // Build AdminContext from database
+      const adminContext = await buildAdminContextFromDb(insertClient);
+
+      await insertFixture(insertClient, expenseScenarioB, adminContext.defaultAdminBusinessId);
 
       const chargeId = makeUUID('charge', 'charge-consulting-services');
 
@@ -228,9 +231,10 @@ describe('Ledger Generation - Expense Scenario B (Foreign Currency)', () => {
         `SELECT * FROM ${qualifyTable('charges')} WHERE id = $1`,
         [chargeId],
       );
+      const adminContext = await buildAdminContextFromDb(client);
       if (existingCharge.rows.length === 0) {
         await client.query('BEGIN');
-        await insertFixture(client, expenseScenarioB);
+        await insertFixture(client, expenseScenarioB, adminContext.defaultAdminBusinessId);
         await client.query('COMMIT');
       }
 
@@ -239,7 +243,6 @@ describe('Ledger Generation - Expense Scenario B (Foreign Currency)', () => {
         [chargeId],
       );
       const charge = chargeResult.rows[0];
-      const adminContext = await buildAdminContextFromDb(client);
       const mockUser: UserType = {
         username: 'test-admin-usd',
         userId: adminContext.defaultAdminBusinessId,

package/src/shared/constants.ts

@@ -4,6 +4,8 @@ export const TIMELESS_DATE_REGEX =
 
 export const UUID_REGEX =
   /^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$/;
+export const UUID5_REGEX =
+  /^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-5[0-9a-fA-F]{3}\b-[89abAB][0-9a-fA-F]{3}\b-[0-9a-fA-F]{12}$/;
 
 export const DECREASED_VAT_RATIO = 2 / 3;
 

package/src/shared/helpers/misc.ts

@@ -1,4 +1,5 @@
 import { format } from 'date-fns';
+import { UUID_REGEX } from '../constants.js';
 import type { TimelessDateString } from '../types/index.js';
 
 function parseIntRound(v: number) {
@@ -38,9 +39,7 @@ export function isTimelessDateString(date: string): date is TimelessDateString {
 }
 
 export function isUUID(raw: string) {
-  const regexExp =
-    /^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$/gi;
-  return regexExp.test(raw);
+  return UUID_REGEX.test(raw);
 }
 
 function convertMonthNameToNumber(monthName: string): string | null {