@accounter/server 0.0.8-alpha-20251102200443-d7162b8ce1dfc629b8b454df17dcec9ed005a052 → 0.0.8-alpha-20251102213150-c9d936f545d5351df0dc5326c2623266f1ad1f46

package/src/modules/charges-matcher/helpers/amount-confidence.helper.ts

@@ -0,0 +1,88 @@
+/**
+ * Calculate the absolute difference between two numbers as a percentage of the smaller absolute value
+ * @param amount1 - First amount
+ * @param amount2 - Second amount
+ * @returns Percentage difference (0-100+)
+ */
+function calculatePercentageDiff(amount1: number, amount2: number): number {
+  const abs1 = Math.abs(amount1);
+  const abs2 = Math.abs(amount2);
+  const smallerAmount = Math.min(abs1, abs2);
+
+  // Handle zero amounts - if one is zero, we can't calculate percentage
+  // In this case, treat any difference > 1 as beyond 20%
+  if (smallerAmount === 0) {
+    return 100; // Return a high percentage to indicate no match
+  }
+
+  const diff = Math.abs(abs1 - abs2);
+  return (diff / smallerAmount) * 100;
+}
+
+/**
+ * Calculate confidence score based on amount similarity
+ * @param transactionAmount - The transaction amount (signed number)
+ * @param documentAmount - The normalized document amount (signed number)
+ * @returns Confidence score between 0.0 and 1.0
+ */
+export function calculateAmountConfidence(
+  transactionAmount: number,
+  documentAmount: number,
+): number {
+  // Calculate absolute difference
+  const absoluteDiff = Math.abs(Math.abs(transactionAmount) - Math.abs(documentAmount));
+
+  // Exact match (0% difference): 1.0
+  if (absoluteDiff === 0) {
+    return 1.0;
+  }
+
+  // Within 1 currency unit: 0.9
+  if (absoluteDiff <= 1) {
+    return 0.9;
+  }
+
+  // Calculate percentage difference for amounts beyond 1 unit
+  const percentageDiff = calculatePercentageDiff(transactionAmount, documentAmount);
+
+  // 20%+ difference: 0.0
+  if (percentageDiff >= 20) {
+    return 0.0;
+  }
+
+  // Between 1 unit and 20% difference: Linear degradation from 0.7 to 0.0
+  // We need to determine which threshold is reached first:
+  // - The absolute difference exceeds 1 unit (already true at this point)
+  // - The percentage difference reaches 20%
+
+  // Linear interpolation from 0.7 (at percentage start) to 0.0 (at 20%)
+  // We need to find where we are in the range
+
+  // Calculate what percentage corresponds to 1 unit difference
+  const abs1 = Math.abs(transactionAmount);
+  const abs2 = Math.abs(documentAmount);
+  const smallerAmount = Math.min(abs1, abs2);
+
+  const oneUnitPercentage = (1 / smallerAmount) * 100;
+
+  // If we're still within the percentage range that corresponds to 1 unit,
+  // this shouldn't happen since we already checked absoluteDiff <= 1 above
+  // But just in case of floating point issues
+  if (percentageDiff <= oneUnitPercentage) {
+    return 0.9;
+  }
+
+  // Linear degradation from 0.7 to 0.0 over the range [oneUnitPercentage, 20%]
+  const rangeStart = oneUnitPercentage;
+  const rangeEnd = 20;
+  const rangeSpan = rangeEnd - rangeStart;
+
+  // How far are we into this range? (0.0 = at start, 1.0 = at end)
+  const position = (percentageDiff - rangeStart) / rangeSpan;
+
+  // Linear degradation from 0.7 to 0.0
+  const confidence = 0.7 * (1 - position);
+
+  // Round to 2 decimal places
+  return Math.round(confidence * 100) / 100;
+}

package/src/modules/charges-matcher/helpers/business-confidence.helper.ts

@@ -0,0 +1,23 @@
+/**
+ * Calculate confidence score based on business ID match
+ * @param transactionBusinessId - Business ID from transaction (can be null)
+ * @param documentBusinessId - Business ID from document (can be null)
+ * @returns Confidence score: 1.0 (exact match), 0.5 (one or both null), 0.2 (mismatch)
+ */
+export function calculateBusinessConfidence(
+  transactionBusinessId: string | null,
+  documentBusinessId: string | null,
+): number {
+  // If either or both are null, return 0.5
+  if (transactionBusinessId === null || documentBusinessId === null) {
+    return 0.5;
+  }
+
+  // Both are non-null, check if they match
+  if (transactionBusinessId === documentBusinessId) {
+    return 1.0;
+  }
+
+  // Both are non-null but don't match
+  return 0.2;
+}

package/src/modules/charges-matcher/helpers/candidate-filter.helper.ts

@@ -0,0 +1,56 @@
+import type { Document, Transaction } from '../types.js';
+
+/**
+ * Filter transactions that should be excluded from matching
+ * Excludes transactions marked as fees (is_fee = true)
+ * @param transaction - Transaction to check
+ * @returns true if transaction should be included in matching
+ */
+export function isValidTransactionForMatching(transaction: Transaction): boolean {
+  // Exclude fee transactions
+  return !transaction.is_fee;
+}
+
+/**
+ * Filter documents that should be excluded from matching
+ * Excludes documents with null mandatory fields (total_amount or currency_code)
+ * @param document - Document to check
+ * @returns true if document should be included in matching
+ */
+export function isValidDocumentForMatching(document: Document): boolean {
+  // Document must have total_amount (can be zero, but not null)
+  if (document.total_amount === null || document.total_amount === undefined) {
+    return false;
+  }
+
+  // Document must have currency_code
+  if (!document.currency_code) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Check if a date falls within the matching window
+ * Window is calculated as ±windowMonths from the reference date
+ * @param candidateDate - Date to check
+ * @param referenceDate - Center point of the window
+ * @param windowMonths - Number of months before/after (default 12)
+ * @returns true if within window
+ */
+export function isWithinDateWindow(
+  candidateDate: Date,
+  referenceDate: Date,
+  windowMonths: number = 12,
+): boolean {
+  // Calculate the date range
+  const minDate = new Date(referenceDate);
+  minDate.setMonth(minDate.getMonth() - windowMonths);
+
+  const maxDate = new Date(referenceDate);
+  maxDate.setMonth(maxDate.getMonth() + windowMonths);
+
+  // Check if candidate is within range (inclusive)
+  return candidateDate >= minDate && candidateDate <= maxDate;
+}

package/src/modules/charges-matcher/helpers/charge-validator.helper.ts

@@ -0,0 +1,100 @@
+import type { Document, DocumentType, Transaction } from '../types.js';
+
+/**
+ * Represents a charge with its associated transactions and documents
+ */
+interface Charge {
+  id: string;
+  owner_id: string | null;
+  transactions?: Transaction[];
+  documents?: Document[];
+}
+
+/**
+ * Accounting document types that count toward matched/unmatched status
+ */
+const ACCOUNTING_DOC_TYPES: DocumentType[] = [
+  'INVOICE',
+  'CREDIT_INVOICE',
+  'RECEIPT',
+  'INVOICE_RECEIPT',
+];
+
+/**
+ * Validate a charge is properly formed for matching
+ * @throws Error with descriptive message if invalid
+ */
+export function validateChargeForMatching(charge: Charge): void {
+  if (!charge) {
+    throw new Error('Charge is required');
+  }
+
+  if (!charge.id) {
+    throw new Error('Charge must have an ID');
+  }
+
+  if (!charge.owner_id) {
+    throw new Error(`Charge ${charge.id} must have an owner_id`);
+  }
+
+  // Check if charge has data
+  const hasTransactions = charge.transactions && charge.transactions.length > 0;
+  const hasDocuments = charge.documents && charge.documents.length > 0;
+
+  if (!hasTransactions && !hasDocuments) {
+    throw new Error(`Charge ${charge.id} has no transactions or documents - cannot be matched`);
+  }
+}
+
+/**
+ * Check if charge is matched (has both transactions and accounting documents)
+ */
+export function isChargeMatched(charge: Charge): boolean {
+  const hasTransactions = charge.transactions && charge.transactions.length > 0;
+
+  const hasAccountingDocs = charge.documents?.some(doc =>
+    ACCOUNTING_DOC_TYPES.includes(doc.type as DocumentType),
+  );
+
+  return !!hasTransactions && !!hasAccountingDocs;
+}
+
+/**
+ * Check if charge has only transactions (no accounting documents)
+ */
+export function hasOnlyTransactions(charge: Charge): boolean {
+  const hasTransactions = charge.transactions && charge.transactions.length > 0;
+
+  const hasAccountingDocs = charge.documents?.some(doc =>
+    ACCOUNTING_DOC_TYPES.includes(doc.type as DocumentType),
+  );
+
+  return !!hasTransactions && !hasAccountingDocs;
+}
+
+/**
+ * Check if charge has only accounting documents (no transactions)
+ */
+export function hasOnlyDocuments(charge: Charge): boolean {
+  const hasTransactions = charge.transactions && charge.transactions.length > 0;
+
+  const hasAccountingDocs = charge.documents?.some(doc =>
+    ACCOUNTING_DOC_TYPES.includes(doc.type as DocumentType),
+  );
+
+  return !hasTransactions && !!hasAccountingDocs;
+}
+
+/**
+ * Validate that a charge is unmatched (for matching operations)
+ * @throws Error if charge is already matched
+ */
+export function validateChargeIsUnmatched(charge: Charge): void {
+  validateChargeForMatching(charge);
+
+  if (isChargeMatched(charge)) {
+    throw new Error(
+      `Charge ${charge.id} is already matched (has both transactions and accounting documents)`,
+    );
+  }
+}

package/src/modules/charges-matcher/helpers/currency-confidence.helper.ts

@@ -0,0 +1,22 @@
+/**
+ * Calculate confidence score based on currency match
+ * @param transactionCurrency - Currency code from transaction
+ * @param documentCurrency - Currency code from document
+ * @returns 1.0 if same, 0.2 if one/both missing, 0.0 if different
+ */
+export function calculateCurrencyConfidence(
+  transactionCurrency: string | null | undefined,
+  documentCurrency: string | null | undefined,
+): number {
+  // Handle null/undefined/empty cases
+  if (!transactionCurrency || !documentCurrency) {
+    return 0.2;
+  }
+
+  // Case-insensitive comparison
+  if (transactionCurrency.toUpperCase() === documentCurrency.toUpperCase()) {
+    return 1.0;
+  }
+
+  return 0.0;
+}

package/src/modules/charges-matcher/helpers/date-confidence.helper.ts

@@ -0,0 +1,41 @@
+/**
+ * Calculate the absolute difference in days between two dates
+ * Ignores time components by comparing only the date parts
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @returns Absolute difference in days
+ */
+function calculateDaysDifference(date1: Date, date2: Date): number {
+  // Create new dates with time set to midnight to ignore time components
+  const d1 = new Date(date1.getFullYear(), date1.getMonth(), date1.getDate());
+  const d2 = new Date(date2.getFullYear(), date2.getMonth(), date2.getDate());
+
+  // Calculate difference in milliseconds
+  const diffMs = Math.abs(d1.getTime() - d2.getTime());
+
+  // Convert to days
+  const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+
+  return diffDays;
+}
+
+/**
+ * Calculate confidence score based on date proximity
+ * @param date1 - First date
+ * @param date2 - Second date
+ * @returns Confidence score from 0.0 (30+ days) to 1.0 (same day)
+ */
+export function calculateDateConfidence(date1: Date, date2: Date): number {
+  const daysDiff = calculateDaysDifference(date1, date2);
+
+  // 30 or more days: return 0.0
+  if (daysDiff >= 30) {
+    return 0.0;
+  }
+
+  // Linear degradation: 1.0 - (days_diff / 30)
+  const confidence = 1.0 - daysDiff / 30;
+
+  // Round to 2 decimal places
+  return Math.round(confidence * 100) / 100;
+}

package/src/modules/charges-matcher/helpers/document-amount.helper.ts

@@ -0,0 +1,77 @@
+/**
+ * Document Amount Normalization
+ *
+ * Normalizes document amounts for comparison with transaction amounts.
+ * Per specification (section 4.3.1):
+ * 1. Start with absolute value of total_amount
+ * 2. If business is creditor: negate
+ * 3. If document type is CREDIT_INVOICE: negate
+ */
+
+/**
+ * Document types from database schema
+ */
+export type DocumentType =
+  | 'CREDIT_INVOICE'
+  | 'INVOICE'
+  | 'INVOICE_RECEIPT'
+  | 'OTHER'
+  | 'PROFORMA'
+  | 'RECEIPT'
+  | 'UNPROCESSED';
+
+/**
+ * Normalize document amount for comparison with transaction amount
+ *
+ * Per specification:
+ * - Start with absolute value of total_amount
+ * - If business is creditor (debtor is user): negate
+ * - If document type is CREDIT_INVOICE: negate
+ *
+ * Examples:
+ * - INVOICE, business debtor (creditor is user): |100| = 100
+ * - INVOICE, business creditor (debtor is user): |100| * -1 = -100
+ * - CREDIT_INVOICE, business debtor: |100| * -1 = -100
+ * - CREDIT_INVOICE, business creditor: |100| * -1 * -1 = 100 (double negation)
+ *
+ * @param totalAmount - Raw total_amount from document (can be positive or negative)
+ * @param isBusinessCreditor - Whether the business is the creditor (from business extraction)
+ * @param documentType - Type of document
+ * @returns Normalized amount (signed) for comparison with transaction amount
+ *
+ * @example
+ * // Regular invoice where user is creditor (business owes user)
+ * normalizeDocumentAmount(100, false, 'INVOICE') // Returns 100
+ *
+ * @example
+ * // Regular invoice where user is debtor (user owes business)
+ * normalizeDocumentAmount(100, true, 'INVOICE') // Returns -100
+ *
+ * @example
+ * // Credit invoice where user is creditor (user owes business a refund)
+ * normalizeDocumentAmount(100, false, 'CREDIT_INVOICE') // Returns -100
+ *
+ * @example
+ * // Credit invoice where user is debtor (business owes user a refund)
+ * normalizeDocumentAmount(100, true, 'CREDIT_INVOICE') // Returns 100 (double negation)
+ */
+export function normalizeDocumentAmount(
+  totalAmount: number,
+  isBusinessCreditor: boolean,
+  documentType: DocumentType,
+): number {
+  // Step 1: Start with absolute value
+  let normalizedAmount = Math.abs(totalAmount);
+
+  // Step 2: If business is creditor (debtor is user), negate
+  if (isBusinessCreditor) {
+    normalizedAmount = -normalizedAmount;
+  }
+
+  // Step 3: If document type is CREDIT_INVOICE, negate
+  if (documentType === 'CREDIT_INVOICE') {
+    normalizedAmount = -normalizedAmount;
+  }
+
+  return normalizedAmount;
+}

package/src/modules/charges-matcher/helpers/document-business.helper.ts

@@ -0,0 +1,54 @@
+export interface DocumentBusinessInfo {
+  businessId: string | null;
+  isBusinessCreditor: boolean;
+}
+
+/**
+ * Extract business information from a document
+ * @param creditorId - Document's creditor_id
+ * @param debtorId - Document's debtor_id
+ * @param adminBusinessId - Current user's ID
+ * @returns Business ID and whether business is the creditor
+ * @throws Error if both or neither IDs match adminBusinessId
+ */
+export function extractDocumentBusiness(
+  creditorId: string | null,
+  debtorId: string | null,
+  adminBusinessId: string,
+): DocumentBusinessInfo {
+  // Check if both are null
+  if (creditorId === null && debtorId === null) {
+    throw new Error('Document has both creditor_id and debtor_id as null - invalid document state');
+  }
+
+  const isCreditorUser = creditorId === adminBusinessId;
+  const isDebtorUser = debtorId === adminBusinessId;
+
+  // Both sides are user
+  if (isCreditorUser && isDebtorUser) {
+    throw new Error(
+      'Document has both creditor_id and debtor_id equal to user ID - invalid document state',
+    );
+  }
+
+  // Neither side is user
+  if (!isCreditorUser && !isDebtorUser) {
+    throw new Error(
+      'Document has neither creditor_id nor debtor_id equal to user ID - document does not belong to user',
+    );
+  }
+
+  // User is debtor, business is creditor (or creditor is null)
+  if (isDebtorUser) {
+    return {
+      businessId: creditorId,
+      isBusinessCreditor: true,
+    };
+  }
+
+  // User is creditor, business is debtor (or debtor is null)
+  return {
+    businessId: debtorId,
+    isBusinessCreditor: false,
+  };
+}

package/src/modules/charges-matcher/helpers/overall-confidence.helper.ts

@@ -0,0 +1,90 @@
+/**
+ * Overall Confidence Calculator
+ *
+ * Combines individual confidence scores (amount, currency, business, date)
+ * into a single weighted overall confidence score.
+ *
+ * Formula: (amount × 0.4) + (currency × 0.2) + (business × 0.3) + (date × 0.1)
+ */
+
+export interface ConfidenceComponents {
+  amount: number;
+  currency: number;
+  business: number;
+  date: number;
+}
+
+/**
+ * Weights for each confidence component
+ */
+const CONFIDENCE_WEIGHTS = {
+  amount: 0.4,
+  currency: 0.2,
+  business: 0.3,
+  date: 0.1,
+} as const;
+
+/**
+ * Calculate overall confidence score from individual components
+ *
+ * @param components - Individual confidence scores (each 0.0 to 1.0)
+ * @returns Weighted overall confidence score (0.0 to 1.0, rounded to 2 decimals)
+ *
+ * @throws {Error} If any component is null or undefined
+ * @throws {Error} If any component is outside the valid range [0.0, 1.0]
+ *
+ * @example
+ * // Perfect match
+ * calculateOverallConfidence({
+ *   amount: 1.0,
+ *   currency: 1.0,
+ *   business: 1.0,
+ *   date: 1.0
+ * }) // Returns 1.0
+ *
+ * @example
+ * // Mixed confidence
+ * calculateOverallConfidence({
+ *   amount: 0.9,
+ *   currency: 1.0,
+ *   business: 0.5,
+ *   date: 0.8
+ * }) // Returns 0.79
+ */
+export function calculateOverallConfidence(components: ConfidenceComponents): number {
+  // Validate all components are present
+  if (components.amount == null) {
+    throw new Error('Amount confidence is required');
+  }
+  if (components.currency == null) {
+    throw new Error('Currency confidence is required');
+  }
+  if (components.business == null) {
+    throw new Error('Business confidence is required');
+  }
+  if (components.date == null) {
+    throw new Error('Date confidence is required');
+  }
+
+  // Validate all components are in valid range
+  const validateRange = (value: number, name: string): void => {
+    if (value < 0.0 || value > 1.0) {
+      throw new Error(`${name} confidence must be between 0.0 and 1.0, got ${value}`);
+    }
+  };
+
+  validateRange(components.amount, 'Amount');
+  validateRange(components.currency, 'Currency');
+  validateRange(components.business, 'Business');
+  validateRange(components.date, 'Date');
+
+  // Calculate weighted sum
+  const weightedSum =
+    components.amount * CONFIDENCE_WEIGHTS.amount +
+    components.currency * CONFIDENCE_WEIGHTS.currency +
+    components.business * CONFIDENCE_WEIGHTS.business +
+    components.date * CONFIDENCE_WEIGHTS.date;
+
+  // Round to 2 decimal places
+  return Math.round(weightedSum * 100) / 100;
+}

package/src/modules/charges-matcher/index.ts

@@ -0,0 +1,17 @@
+import chargesMatcherTypeDefs from './typeDefs/charges-matcher.graphql.js';
+import { createModule } from 'graphql-modules';
+import { ChargesMatcherProvider } from './providers/charges-matcher.provider.js';
+import { chargesMatcherResolvers } from './resolvers/index.js';
+
+const __dirname = new URL('.', import.meta.url).pathname;
+
+export const chargesMatcherModule = createModule({
+  id: 'charges-matcher',
+  dirname: __dirname,
+  typeDefs: [chargesMatcherTypeDefs],
+  resolvers: [chargesMatcherResolvers],
+  providers: [ChargesMatcherProvider],
+});
+
+export { ChargesMatcherProvider } from './providers/charges-matcher.provider.js';
+export * as ChargesMatcherTypes from './types.js';