@accounter/server 0.0.9-alpha-20251217093036-7168648b507d62946aa287af4ea690b73b077b2d → 0.0.9-alpha-20251217131153-65f961a4072436d7f1042ea8ea4d96534cb3650e

package/src/modules/charges-matcher/README.md

@@ -152,8 +152,7 @@ A charge is considered unmatched if it has:
 - ≥1 transactions AND 0 accounting documents, OR
 - 0 transactions AND ≥1 accounting documents
 
-**Note**: PROFORMA, OTHER, and UNPROCESSED document types don't count toward matched/unmatched
-status.
+**Note**: OTHER, and UNPROCESSED document types don't count toward matched/unmatched status.
 
 ### Matched Charge
 
@@ -163,7 +162,7 @@ A charge is considered matched if it has:
 
 ### Accounting Documents
 
-Documents with types: INVOICE, CREDIT_INVOICE, RECEIPT, INVOICE_RECEIPT
+Documents with types: INVOICE, CREDIT_INVOICE, RECEIPT, INVOICE_RECEIPT, PROFORMA
 
 ### Confidence Score
 
@@ -175,6 +174,18 @@ confidence = (amount × 0.4) + (currency × 0.2) + (business × 0.3) + (date ×
 
 Where each component score is between 0.0 and 1.0.
 
+**Date Component Enhancement (v3.0 - Gentle Scoring):**
+
+The date confidence uses "gentle scoring" for eligible client invoices:
+
+- **Gentle Eligible:** Client same-business matches with OPEN INVOICE/PROFORMA documents dated on or
+  before the transaction date (within 365 days) receive near-maximum confidence (~1.00) with a
+  microscopic preference for earlier invoices
+- **Standard:** All other scenarios use linear degradation from 1.0 (same day) to 0.0 (30+ days)
+- **Tie-Breaker:** When scores are equal under gentle mode, earlier invoices are preferred
+
+This ensures recurring client payments match to the earliest eligible open invoice.
+
 ### Auto-Match Threshold
 
 Charges are automatically matched only when:

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

@@ -20,6 +20,10 @@ vi.mock('../../transactions/providers/transactions.provider.js', () => ({
   TransactionsProvider: class {},
 }));
 
+vi.mock('../../financial-entities/providers/clients.provider.js', () => ({
+  ClientsProvider: class {},
+}));
+
 vi.mock('../../charges/helpers/merge-charges.helper.js', () => ({
   mergeChargesExecutor: vi.fn(),
 }));
@@ -28,6 +32,43 @@ vi.mock('../../../shared/helpers/index.js', () => ({
   dateToTimelessDateString: (date: Date) => date.toISOString().split('T')[0],
 }));
 
+const getMockInjector = (mockChargesProvider?: {
+    getChargesByFilters: (filters: any) => Promise<any[]>;
+  },
+  mockTransactionsProvider?: {
+    transactionsByChargeIDLoader: { load: (id: string) => Promise<any[]>;
+  }},
+  mockDocumentsProvider?: {
+    getDocumentsByChargeIdLoader: { load: (id: string) => Promise<any[]>; };
+}
+) => ({
+  get: vi.fn((token: {name: string}) => {
+    if (token.name === 'ChargesProvider') return mockChargesProvider ?? {
+      getChargesByFilters: vi.fn(() => Promise.resolve([])),
+    };
+    if (token.name === 'TransactionsProvider') return mockTransactionsProvider ?? {
+      transactionsByChargeIDLoader: {
+        load: vi.fn(() => Promise.resolve([])),
+      },
+    };
+    if (token.name === 'DocumentsProvider') return mockDocumentsProvider ?? {
+      getDocumentsByChargeIdLoader: {
+        load: vi.fn(() => Promise.resolve([])),
+      },
+    };
+    if (token.name === 'ClientsProvider')
+      return {
+        getClientByIdLoader: {
+          load: (businessId: string) => {
+            const isRegisteredClient = businessId.startsWith('client-');
+            return Promise.resolve(isRegisteredClient ? { id: businessId } : null);
+          },
+        },
+      };
+    return null;
+  }),
+}) as Injector;
+
 // Import after mocking
 const { ChargesMatcherProvider } = await import('../providers/charges-matcher.provider.js');
 const { mergeChargesExecutor } = await import(
@@ -56,30 +97,7 @@ describe('ChargesMatcherProvider - Auto-Match Integration', () => {
 
   describe('autoMatchCharges', () => {
     it('should return 0 matches when database is empty', async () => {
-      const mockChargesProvider = {
-        getChargesByFilters: vi.fn(() => Promise.resolve([])),
-      };
-
-      const mockTransactionsProvider = {
-        transactionsByChargeIDLoader: {
-          load: vi.fn(() => Promise.resolve([])),
-        },
-      };
-
-      const mockDocumentsProvider = {
-        getDocumentsByChargeIdLoader: {
-          load: vi.fn(() => Promise.resolve([])),
-        },
-      };
-
-      const mockInjector = {
-        get: vi.fn((token: any) => {
-          if (token.name === 'ChargesProvider') return mockChargesProvider;
-          if (token.name === 'TransactionsProvider') return mockTransactionsProvider;
-          if (token.name === 'DocumentsProvider') return mockDocumentsProvider;
-          return null;
-        }),
-      } as unknown as Injector;
+      const mockInjector = getMockInjector()
 
       const provider = new ChargesMatcherProvider();
       const result = await provider.autoMatchCharges({
@@ -102,26 +120,7 @@ describe('ChargesMatcherProvider - Auto-Match Integration', () => {
         ),
       };
 
-      const mockTransactionsProvider = {
-        transactionsByChargeIDLoader: {
-          load: vi.fn(() => Promise.resolve([createMockTransaction()])),
-        },
-      };
-
-      const mockDocumentsProvider = {
-        getDocumentsByChargeIdLoader: {
-          load: vi.fn(() => Promise.resolve([createMockDocument()])),
-        },
-      };
-
-      const mockInjector = {
-        get: vi.fn((token: any) => {
-          if (token.name === 'ChargesProvider') return mockChargesProvider;
-          if (token.name === 'TransactionsProvider') return mockTransactionsProvider;
-          if (token.name === 'DocumentsProvider') return mockDocumentsProvider;
-          return null;
-        }),
-      } as unknown as Injector;
+      const mockInjector = getMockInjector(mockChargesProvider)
 
       const provider = new ChargesMatcherProvider();
       const result = await provider.autoMatchCharges({
@@ -183,14 +182,7 @@ describe('ChargesMatcherProvider - Auto-Match Integration', () => {
         },
       };
 
-      const mockInjector = {
-        get: vi.fn((token: any) => {
-          if (token.name === 'ChargesProvider') return mockChargesProvider;
-          if (token.name === 'TransactionsProvider') return mockTransactionsProvider;
-          if (token.name === 'DocumentsProvider') return mockDocumentsProvider;
-          return null;
-        }),
-      } as unknown as Injector;
+      const mockInjector = getMockInjector(mockChargesProvider, mockTransactionsProvider, mockDocumentsProvider);
 
       const provider = new ChargesMatcherProvider();
       const result = await provider.autoMatchCharges({
@@ -269,14 +261,7 @@ describe('ChargesMatcherProvider - Auto-Match Integration', () => {
         },
       };
 
-      const mockInjector = {
-        get: vi.fn((token: any) => {
-          if (token.name === 'ChargesProvider') return mockChargesProvider;
-          if (token.name === 'TransactionsProvider') return mockTransactionsProvider;
-          if (token.name === 'DocumentsProvider') return mockDocumentsProvider;
-          return null;
-        }),
-      } as unknown as Injector;
+      const mockInjector = getMockInjector(mockChargesProvider, mockTransactionsProvider, mockDocumentsProvider);
 
       const provider = new ChargesMatcherProvider();
       const result = await provider.autoMatchCharges( {
@@ -347,14 +332,7 @@ describe('ChargesMatcherProvider - Auto-Match Integration', () => {
         },
       };
 
-      const mockInjector = {
-        get: vi.fn((token: any) => {
-          if (token.name === 'ChargesProvider') return mockChargesProvider;
-          if (token.name === 'TransactionsProvider') return mockTransactionsProvider;
-          if (token.name === 'DocumentsProvider') return mockDocumentsProvider;
-          return null;
-        }),
-      } as unknown as Injector;
+      const mockInjector = getMockInjector(mockChargesProvider, mockTransactionsProvider, mockDocumentsProvider);
 
       const provider = new ChargesMatcherProvider();
       const result = await provider.autoMatchCharges({
@@ -434,14 +412,7 @@ describe('ChargesMatcherProvider - Auto-Match Integration', () => {
       });
       (mergeChargesExecutor as any).mockImplementationOnce(() => Promise.resolve());
 
-      const mockInjector = {
-        get: vi.fn((token: any) => {
-          if (token.name === 'ChargesProvider') return mockChargesProvider;
-          if (token.name === 'TransactionsProvider') return mockTransactionsProvider;
-          if (token.name === 'DocumentsProvider') return mockDocumentsProvider;
-          return null;
-        }),
-      } as unknown as Injector;
+      const mockInjector = getMockInjector(mockChargesProvider, mockTransactionsProvider, mockDocumentsProvider);
 
       const provider = new ChargesMatcherProvider();
       const result = await provider.autoMatchCharges( {
@@ -493,14 +464,7 @@ describe('ChargesMatcherProvider - Auto-Match Integration', () => {
         },
       };
 
-      const mockInjector = {
-        get: vi.fn((token: any) => {
-          if (token.name === 'ChargesProvider') return mockChargesProvider;
-          if (token.name === 'TransactionsProvider') return mockTransactionsProvider;
-          if (token.name === 'DocumentsProvider') return mockDocumentsProvider;
-          return null;
-        }),
-      } as unknown as Injector;
+      const mockInjector = getMockInjector(mockChargesProvider, mockTransactionsProvider, mockDocumentsProvider);
 
       const provider = new ChargesMatcherProvider();
       await provider.autoMatchCharges({
@@ -549,14 +513,7 @@ describe('ChargesMatcherProvider - Auto-Match Integration', () => {
         },
       };
 
-      const mockInjector = {
-        get: vi.fn((token: any) => {
-          if (token.name === 'ChargesProvider') return mockChargesProvider;
-          if (token.name === 'TransactionsProvider') return mockTransactionsProvider;
-          if (token.name === 'DocumentsProvider') return mockDocumentsProvider;
-          return null;
-        }),
-      } as unknown as Injector;
+      const mockInjector = getMockInjector(mockChargesProvider, mockTransactionsProvider, mockDocumentsProvider);
 
       const provider = new ChargesMatcherProvider();
       const result = await provider.autoMatchCharges({
@@ -638,6 +595,8 @@ describe('ChargesMatcherProvider - Auto-Match Integration', () => {
                   total_amount: 100,
                   currency_code: 'USD',
                   date: new Date('2024-01-15'),
+                  debtor_id: ADMIN_BUSINESS_ID,
+                  creditor_id: 'business-a',
                 }),
               ]);
             }
@@ -668,14 +627,7 @@ describe('ChargesMatcherProvider - Auto-Match Integration', () => {
         },
       };
 
-      const mockInjector = {
-        get: vi.fn((token: any) => {
-          if (token.name === 'ChargesProvider') return mockChargesProvider;
-          if (token.name === 'TransactionsProvider') return mockTransactionsProvider;
-          if (token.name === 'DocumentsProvider') return mockDocumentsProvider;
-          return null;
-        }),
-      } as unknown as Injector;
+      const mockInjector = getMockInjector(mockChargesProvider, mockTransactionsProvider, mockDocumentsProvider);
 
       (mergeChargesExecutor as any).mockImplementation(() => Promise.resolve());
 

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

@@ -1,4 +1,5 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
+import type { Injector } from 'graphql-modules';
 import type { ChargeWithData } from '../types.js';
 import {
   determineMergeDirection,
@@ -6,10 +7,31 @@ import {
 } from '../providers/auto-match.provider.js';
 import { createMockTransaction, createMockDocument } from './test-helpers.js';
 
+// Mock DI system and ClientsProvider
+vi.mock('../../financial-entities/providers/clients.provider.js', () => ({
+  ClientsProvider: class {},
+}));
+
 // Test constants
 const USER_ID = 'user-123';
 const BUSINESS_A = 'business-a';
 
+// Create a mock injector for testing
+const createMockInjector = () => ({
+  get: vi.fn((token: {name: string}) => {
+    if (token.name === 'ClientsProvider')
+      return {
+        getClientByIdLoader: {
+          load: (businessId: string) => {
+            const isRegisteredClient = businessId.startsWith('client-');
+            return Promise.resolve(isRegisteredClient ? { id: businessId } : null);
+          },
+        },
+      };
+    return null;
+  }),
+}) as Injector;
+
 // Helper to create a charge with data
 function createCharge(overrides: Partial<ChargeWithData> = {}): ChargeWithData {
   return {
@@ -24,7 +46,7 @@ function createCharge(overrides: Partial<ChargeWithData> = {}): ChargeWithData {
 
 describe('processChargeForAutoMatch', () => {
   describe('Single high-confidence match', () => {
-    it('should return matched status when exactly one match >= 0.95', () => {
+    it('should return matched status when exactly one match >= 0.95', async () => {
       const sourceCharge = createCharge({
         chargeId: 'tx-charge-1',
         transactions: [
@@ -54,7 +76,7 @@ describe('processChargeForAutoMatch', () => {
         ],
       });
 
-      const result = processChargeForAutoMatch(sourceCharge, [perfectMatch], USER_ID);
+      const result = await processChargeForAutoMatch(sourceCharge, [perfectMatch], USER_ID, createMockInjector());
 
       expect(result.status).toBe('matched');
       expect(result.match).not.toBeNull();
@@ -62,7 +84,7 @@ describe('processChargeForAutoMatch', () => {
       expect(result.match?.confidenceScore).toBeGreaterThanOrEqual(0.95);
     });
 
-    it('should return matched status for score exactly at 0.95 threshold', () => {
+    it('should return matched status for score exactly at 0.95 threshold', async () => {
       const sourceCharge = createCharge({
         chargeId: 'tx-charge-1',
         transactions: [
@@ -91,14 +113,14 @@ describe('processChargeForAutoMatch', () => {
         ],
       });
 
-      const result = processChargeForAutoMatch(sourceCharge, [nearThresholdMatch], USER_ID);
+      const result = await processChargeForAutoMatch(sourceCharge, [nearThresholdMatch], USER_ID, createMockInjector());
 
       expect(result.status).toBe('matched');
       expect(result.match).not.toBeNull();
       expect(result.match?.confidenceScore).toBeGreaterThanOrEqual(0.95);
     });
 
-    it('should work with document source charge', () => {
+    it('should work with document source charge', async () => {
       const sourceCharge = createCharge({
         chargeId: 'doc-charge-1',
         transactions: [],
@@ -125,7 +147,7 @@ describe('processChargeForAutoMatch', () => {
         documents: [],
       });
 
-      const result = processChargeForAutoMatch(sourceCharge, [perfectMatch], USER_ID);
+      const result = await processChargeForAutoMatch(sourceCharge, [perfectMatch], USER_ID, createMockInjector());
 
       expect(result.status).toBe('matched');
       expect(result.match).not.toBeNull();
@@ -134,7 +156,7 @@ describe('processChargeForAutoMatch', () => {
   });
 
   describe('Multiple high-confidence matches', () => {
-    it('should return skipped status when multiple matches >= 0.95', () => {
+    it('should return skipped status when multiple matches >= 0.95', async () => {
       const sourceCharge = createCharge({
         chargeId: 'tx-charge-1',
         transactions: [
@@ -174,14 +196,14 @@ describe('processChargeForAutoMatch', () => {
         ],
       });
 
-      const result = processChargeForAutoMatch(sourceCharge, [match1, match2], USER_ID);
+      const result = await processChargeForAutoMatch(sourceCharge, [match1, match2], USER_ID, createMockInjector());
 
       expect(result.status).toBe('skipped');
       expect(result.match).toBeNull();
       expect(result.reason).toContain('ambiguous');
     });
 
-    it('should skip even with many high-confidence matches', () => {
+    it('should skip even with many high-confidence matches', async () => {
       const sourceCharge = createCharge({
         chargeId: 'tx-charge-1',
         transactions: [
@@ -201,7 +223,7 @@ describe('processChargeForAutoMatch', () => {
         }),
       );
 
-      const result = processChargeForAutoMatch(sourceCharge, candidates, USER_ID);
+      const result = await processChargeForAutoMatch(sourceCharge, candidates, USER_ID, createMockInjector());
 
       expect(result.status).toBe('skipped');
       expect(result.match).toBeNull();
@@ -209,7 +231,7 @@ describe('processChargeForAutoMatch', () => {
   });
 
   describe('No high-confidence matches', () => {
-    it('should return no-match when best match is below 0.95 threshold', () => {
+    it('should return no-match when best match is below 0.95 threshold', async () => {
       const sourceCharge = createCharge({
         chargeId: 'tx-charge-1',
         transactions: [
@@ -237,28 +259,28 @@ describe('processChargeForAutoMatch', () => {
         ],
       });
 
-      const result = processChargeForAutoMatch(sourceCharge, [poorMatch], USER_ID);
+      const result = await processChargeForAutoMatch(sourceCharge, [poorMatch], USER_ID, createMockInjector());
 
       expect(result.status).toBe('no-match');
       expect(result.match).toBeNull();
       expect(result.reason).toContain('below threshold');
     });
 
-    it('should return no-match when no candidates exist', () => {
+    it('should return no-match when no candidates exist', async () => {
       const sourceCharge = createCharge({
         chargeId: 'tx-charge-1',
         transactions: [createMockTransaction()],
         documents: [],
       });
 
-      const result = processChargeForAutoMatch(sourceCharge, [], USER_ID);
+      const result = await processChargeForAutoMatch(sourceCharge, [], USER_ID, createMockInjector());
 
       expect(result.status).toBe('no-match');
       expect(result.match).toBeNull();
       expect(result.reason).toContain('No candidates found');
     });
 
-    it('should handle match just below threshold (0.949)', () => {
+    it('should handle match just below threshold (0.949)', async () => {
       const sourceCharge = createCharge({
         chargeId: 'tx-charge-1',
         transactions: [
@@ -286,7 +308,7 @@ describe('processChargeForAutoMatch', () => {
         ],
       });
 
-      const result = processChargeForAutoMatch(sourceCharge, [nearMissMatch], USER_ID);
+      const result = await processChargeForAutoMatch(sourceCharge, [nearMissMatch], USER_ID, createMockInjector());
 
       // Should be no-match since it's below threshold
       expect(result.status).toBe('no-match');
@@ -295,31 +317,31 @@ describe('processChargeForAutoMatch', () => {
   });
 
   describe('Edge cases and validation', () => {
-    it('should throw error if source charge is already matched', () => {
+    it('should throw error if source charge is already matched', async () => {
       const matchedCharge = createCharge({
         chargeId: 'matched-charge',
         transactions: [createMockTransaction()],
         documents: [createMockDocument()],
       });
 
-      expect(() => {
-        processChargeForAutoMatch(matchedCharge, [], USER_ID);
-      }).toThrow(/already matched/);
+      await expect(processChargeForAutoMatch(matchedCharge, [], USER_ID, createMockInjector())).rejects.toThrow(
+        /already matched/,
+      );
     });
 
-    it('should throw error if source charge has no transactions or documents', () => {
+    it('should throw error if source charge has no transactions or documents', async () => {
       const emptyCharge = createCharge({
         chargeId: 'empty-charge',
         transactions: [],
         documents: [],
       });
 
-      expect(() => {
-        processChargeForAutoMatch(emptyCharge, [], USER_ID);
-      }).toThrow(/no transactions or documents/);
+      await expect(processChargeForAutoMatch(emptyCharge, [], USER_ID, createMockInjector())).rejects.toThrow(
+        /no transactions or documents/,
+      );
     });
 
-    it('should filter candidates to complementary type only', () => {
+    it('should filter candidates to complementary type only', async () => {
       const sourceCharge = createCharge({
         chargeId: 'tx-charge-1',
         transactions: [createMockTransaction({ amount: "100" })],
@@ -345,14 +367,14 @@ describe('processChargeForAutoMatch', () => {
         }),
       ];
 
-      const result = processChargeForAutoMatch(sourceCharge, candidates, USER_ID);
+      const result = await processChargeForAutoMatch(sourceCharge, candidates, USER_ID, createMockInjector());
 
       // Should only consider document charges (doc-charge-1 and doc-charge-2)
       // Both are perfect matches, so should be skipped as ambiguous
       expect(result.status).toBe('skipped');
     });
 
-    it('should handle various confidence levels correctly', () => {
+    it('should handle various confidence levels correctly', async () => {
       const sourceCharge = createCharge({
         chargeId: 'tx-charge-1',
         transactions: [
@@ -404,7 +426,7 @@ describe('processChargeForAutoMatch', () => {
         }),
       ];
 
-      const result = processChargeForAutoMatch(sourceCharge, candidates, USER_ID);
+      const result = await processChargeForAutoMatch(sourceCharge, candidates, USER_ID, createMockInjector());
 
       // Only one match >= 0.95 (the perfect one)
       expect(result.status).toBe('matched');

package/src/modules/charges-matcher/__tests__/charge-validator.test.ts

@@ -167,17 +167,6 @@ describe('Charge Validator', () => {
       expect(isChargeMatched(charge)).toBe(false);
     });
 
-    it('should return false for charge with transactions and PROFORMA (non-accounting doc)', () => {
-      const charge = {
-        id: 'charge-1',
-        owner_id: 'user-1',
-        transactions: [createMockTransaction({ charge_id: 'charge-1' })],
-        documents: [createMockDocument({ charge_id: 'charge-1', type: 'PROFORMA' })],
-      };
-
-      expect(isChargeMatched(charge)).toBe(false);
-    });
-
     it('should return false for charge with transactions and OTHER (non-accounting doc)', () => {
       const charge = {
         id: 'charge-1',
@@ -218,7 +207,7 @@ describe('Charge Validator', () => {
         id: 'charge-1',
         owner_id: 'user-1',
         transactions: [createMockTransaction({ charge_id: 'charge-1' })],
-        documents: [createMockDocument({ charge_id: 'charge-1', type: 'PROFORMA' })],
+        documents: [createMockDocument({ charge_id: 'charge-1', type: 'OTHER' })],
       };
 
       expect(hasOnlyTransactions(charge)).toBe(true);
@@ -286,7 +275,7 @@ describe('Charge Validator', () => {
         id: 'charge-1',
         owner_id: 'user-1',
         transactions: [],
-        documents: [createMockDocument({ charge_id: 'charge-1', type: 'PROFORMA' })],
+        documents: [createMockDocument({ charge_id: 'charge-1', type: 'OTHER' })],
       };
 
       expect(hasOnlyDocuments(charge)).toBe(false);

package/src/modules/charges-matcher/__tests__/date-confidence.test.ts

@@ -2,6 +2,35 @@ import { describe, expect, it } from 'vitest';
 import { calculateDateConfidence } from '../helpers/date-confidence.helper.js';
 
 describe('calculateDateConfidence', () => {
+  describe('client-aware flag', () => {
+    it('returns 1.0 for client same-business on same day', () => {
+      const date = new Date('2024-01-15');
+      const result = calculateDateConfidence(date, date, true);
+      expect(result).toBe(1.0);
+    });
+
+    it('returns 1.0 for client same-business 30 days apart', () => {
+      const date1 = new Date('2024-01-01');
+      const date2 = new Date('2024-01-31');
+      const result = calculateDateConfidence(date1, date2, true);
+      expect(result).toBe(1.0);
+    });
+
+    it('returns 1.0 for client same-business 365 days apart', () => {
+      const date1 = new Date('2023-01-01');
+      const date2 = new Date('2024-01-01');
+      const result = calculateDateConfidence(date1, date2, true);
+      expect(result).toBe(1.0);
+    });
+
+    it('uses standard degradation when not a client match', () => {
+      const date1 = new Date('2024-01-01');
+      const date2 = new Date('2024-01-31');
+      const result = calculateDateConfidence(date1, date2, false);
+      expect(result).toBe(0.0);
+    });
+  });
+
   describe('same day', () => {
     it('should return 1.0 for identical dates', () => {
       const date = new Date('2024-01-15T10:30:00Z');

package/src/modules/charges-matcher/__tests__/document-aggregator.test.ts

@@ -3,7 +3,6 @@ import {
   aggregateDocuments,
   type Document,
 } from '../providers/document-aggregator.js';
-import type { DocumentType } from '../helpers/document-amount.helper.js';
 
 describe('Document Aggregator', () => {
   const USER_ID = 'user-123';