@accounter/server 0.0.8-alpha-20251102200443-d7162b8ce1dfc629b8b454df17dcec9ed005a052 → 0.0.8-alpha-20251103003648-f6467c8cb9c739ec4439c260bccc7325f6a761ae

package/src/modules/charges-matcher/providers/transaction-aggregator.ts

@@ -0,0 +1,131 @@
+/**
+ * Transaction Aggregator
+ *
+ * Aggregates multiple transactions from a single charge into a unified representation
+ * for matching purposes. Handles fee exclusion, currency validation, business ID
+ * validation, amount summation, date selection, and description concatenation.
+ */
+
+import type { currency } from '@modules/documents/types';
+import type { AggregatedTransaction } from '../types.js';
+
+/**
+ * Minimal transaction interface for aggregation
+ * Based on database schema from accounter_schema.transactions
+ */
+export interface Transaction {
+  id: string; // UUID
+  charge_id: string; // UUID
+  amount: string; // numeric in DB
+  currency: currency; // Currency type
+  business_id: string | null; // UUID or null
+  event_date: Date;
+  debit_date: Date | null;
+  debit_timestamp: Date | null;
+  source_description: string | null;
+  is_fee: boolean | null;
+}
+
+/**
+ * Aggregate multiple transactions into a single representation
+ *
+ * Per specification (section 4.2):
+ * 1. Exclude transactions where is_fee = true
+ * 2. If multiple currencies exist: throw error
+ * 3. If multiple non-null business IDs exist: throw error
+ * 4. Amount: sum of all amounts
+ * 5. Currency: the common currency
+ * 6. Business ID: the single non-null business ID (or null if all null)
+ * 7. Date: earliest event_date
+ * 8. Description: concatenate all source_description values with line breaks
+ *
+ * @param transactions - Array of transactions from a charge
+ * @returns Aggregated transaction data
+ *
+ * @throws {Error} If transactions array is empty
+ * @throws {Error} If no non-fee transactions exist after filtering
+ * @throws {Error} If multiple different currencies exist
+ * @throws {Error} If multiple different non-null business IDs exist
+ *
+ * @example
+ * const aggregated = aggregateTransactions([
+ *   { amount: 100, currency: 'USD', business_id: 'b1', event_date: new Date('2024-01-15'), ... },
+ *   { amount: 50, currency: 'USD', business_id: 'b1', event_date: new Date('2024-01-20'), ... }
+ * ]);
+ * // Returns: { amount: 150, currency: 'USD', businessId: 'b1', date: Date('2024-01-15'), ... }
+ */
+export function aggregateTransactions(transactions: Transaction[]): AggregatedTransaction {
+  // Validate non-empty input
+  if (!transactions || transactions.length === 0) {
+    throw new Error('Cannot aggregate transactions: array is empty');
+  }
+
+  // Filter out fee transactions
+  const nonFeeTransactions = transactions.filter(t => t.is_fee !== true);
+
+  // Validate we have transactions after filtering
+  if (nonFeeTransactions.length === 0) {
+    throw new Error('Cannot aggregate transactions: all transactions are marked as fees');
+  }
+
+  // Validate single currency
+  const currencies = new Set(nonFeeTransactions.map(t => t.currency));
+  if (currencies.size > 1) {
+    throw new Error(
+      `Cannot aggregate transactions: multiple currencies found (${Array.from(currencies).join(', ')})`,
+    );
+  }
+
+  // Validate single non-null business ID
+  const businessIds = nonFeeTransactions
+    .map(t => t.business_id)
+    .filter((id): id is string => id !== null && id !== undefined);
+
+  const uniqueBusinessIds = new Set(businessIds);
+  if (uniqueBusinessIds.size > 1) {
+    throw new Error(
+      `Cannot aggregate transactions: multiple business IDs found (${Array.from(uniqueBusinessIds).join(', ')})`,
+    );
+  }
+
+  // Sum amounts
+  const totalAmount = nonFeeTransactions.reduce((sum, t) => sum + Number(t.amount), 0);
+
+  // Get common currency (safe since we validated single currency)
+  const currency = nonFeeTransactions[0].currency;
+
+  // Get business ID (single non-null or null if all null)
+  const businessId = uniqueBusinessIds.size === 1 ? Array.from(uniqueBusinessIds)[0] : null;
+
+  // Get earliest event_date
+  const earliestDate = nonFeeTransactions.reduce((earliest, t) => {
+    return t.event_date < earliest ? t.event_date : earliest;
+  }, nonFeeTransactions[0].event_date);
+
+  // Get earliest debit_date
+  const earliestDebitDate = nonFeeTransactions.reduce(
+    (earliest, t) => {
+      const debitDate = t.debit_timestamp ?? t.debit_date;
+      if (debitDate === null) return earliest;
+      if (earliest === null) return debitDate;
+      return debitDate < earliest ? debitDate : earliest;
+    },
+    null as Date | null,
+  );
+
+  // Concatenate descriptions with line breaks, filtering out nulls
+  const descriptions = nonFeeTransactions
+    .map(t => t.source_description)
+    .filter((desc): desc is string => desc !== null && desc !== undefined && desc.trim() !== '');
+
+  const description = descriptions.length > 0 ? descriptions.join('\n') : '';
+
+  return {
+    amount: totalAmount,
+    currency,
+    businessId,
+    date: earliestDate,
+    description,
+    debitDate: earliestDebitDate,
+  };
+}

package/src/modules/charges-matcher/resolvers/auto-match-charges.resolver.ts

@@ -0,0 +1,23 @@
+import { GraphQLError } from 'graphql';
+import { ChargesMatcherProvider } from '../providers/charges-matcher.provider.js';
+import type { ChargesMatcherModule } from '../types.js';
+
+export const autoMatchChargesResolver: ChargesMatcherModule.Resolvers = {
+  Mutation: {
+    autoMatchCharges: async (_, __, context) => {
+      try {
+        const result = await context.injector.get(ChargesMatcherProvider).autoMatchCharges(context);
+        return result;
+      } catch (e) {
+        if (e instanceof GraphQLError) {
+          throw e;
+        }
+        const message =
+          (e as Error)?.message ??
+          (e as { errors: Error[] })?.errors.map(e => e.message).toString() ??
+          'Unknown error';
+        throw new GraphQLError(message);
+      }
+    },
+  },
+};

package/src/modules/charges-matcher/resolvers/find-charge-matches.resolver.ts

@@ -0,0 +1,25 @@
+import { GraphQLError } from 'graphql';
+import { ChargesMatcherProvider } from '../providers/charges-matcher.provider.js';
+import type { ChargesMatcherModule } from '../types.js';
+
+export const findChargeMatchesResolver: ChargesMatcherModule.Resolvers = {
+  Query: {
+    findChargeMatches: async (_, { chargeId }, context) => {
+      try {
+        const result = await context.injector
+          .get(ChargesMatcherProvider)
+          .findMatchesForCharge(chargeId, context);
+        return result;
+      } catch (e) {
+        if (e instanceof GraphQLError) {
+          throw e;
+        }
+        const message =
+          (e as Error)?.message ??
+          (e as { errors: Error[] })?.errors.map(e => e.message).toString() ??
+          'Unknown error';
+        throw new GraphQLError(message);
+      }
+    },
+  },
+};

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

@@ -0,0 +1,12 @@
+import type { ChargesMatcherModule } from '../types.js';
+import { autoMatchChargesResolver } from './auto-match-charges.resolver.js';
+import { findChargeMatchesResolver } from './find-charge-matches.resolver.js';
+
+export const chargesMatcherResolvers: ChargesMatcherModule.Resolvers = {
+  Query: {
+    ...findChargeMatchesResolver.Query,
+  },
+  Mutation: {
+    ...autoMatchChargesResolver.Mutation,
+  },
+};

package/src/modules/charges-matcher/typeDefs/charges-matcher.graphql.ts

@@ -0,0 +1,47 @@
+import { gql } from 'graphql-modules';
+
+export default gql`
+  extend type Query {
+    " Find potential matches for a single unmatched charge "
+    findChargeMatches(chargeId: UUID!): ChargeMatchesResult! @auth(role: ACCOUNTANT)
+  }
+
+  extend type Mutation {
+    " Automatically match all unmatched charges above the confidence threshold "
+    autoMatchCharges: AutoMatchChargesResult! @auth(role: ACCOUNTANT)
+  }
+
+  " Result of finding matches for a single charge "
+  type ChargeMatchesResult {
+    " Array of up to 5 matches, ordered by confidence score (highest first) "
+    matches: [ChargeMatch!]!
+  }
+
+  " A single charge match with its confidence score "
+  type ChargeMatch {
+    " UUID of the matched charge "
+    chargeId: UUID!
+    " Confidence score between 0.00 and 1.00 "
+    confidenceScore: Float!
+  }
+
+  " Result of the auto-match operation "
+  type AutoMatchChargesResult {
+    " Total number of charges that were successfully matched and merged "
+    totalMatches: Int!
+    " Array of charges that were merged, with their confidence scores "
+    mergedCharges: [MergedCharge!]!
+    " Array of charge UUIDs that had multiple high-confidence matches and were skipped "
+    skippedCharges: [UUID!]!
+    " Array of error messages encountered during the operation "
+    errors: [String!]!
+  }
+
+  " A charge that was successfully merged during auto-match "
+  type MergedCharge {
+    " UUID of the deleted/merged-away charge "
+    chargeId: UUID!
+    " Confidence score that triggered the merge "
+    confidenceScore: Float!
+  }
+`;

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

@@ -0,0 +1,200 @@
+import type { currency, document_type, IGetAllDocumentsResult } from '@modules/documents/types.js';
+import type { IGetTransactionsByIdsResult } from '@modules/transactions/types.js';
+
+export * from './__generated__/types.js';
+
+/**
+ * Re-export shared types from other modules
+ */
+export type {
+  currency as Currency,
+  document_type as DocumentType,
+} from '@modules/documents/types.js';
+
+/**
+ * Transaction interface matching the database schema
+ * Uses the complete type from transactions module
+ */
+export type Transaction = IGetTransactionsByIdsResult;
+
+/**
+ * Document interface matching the database schema
+ * Uses the complete type from documents module
+ */
+export type Document = IGetAllDocumentsResult;
+
+/**
+ * Represents a single charge match with its confidence score
+ */
+export interface ChargeMatch {
+  /** UUID of the matched charge */
+  chargeId: string;
+  /** Confidence score between 0.00 and 1.00 (two decimal precision) */
+  confidenceScore: number;
+}
+
+/**
+ * Result of finding matches for a single charge
+ */
+export interface ChargeMatchesResult {
+  /** Array of up to 5 matches, ordered by confidence score (highest first) */
+  matches: ChargeMatch[];
+}
+
+/**
+ * Represents a charge that was successfully merged during auto-match
+ */
+export interface MergedCharge {
+  /** UUID of the deleted/merged-away charge */
+  chargeId: string;
+  /** Confidence score that triggered the merge (≥0.95) */
+  confidenceScore: number;
+}
+
+/**
+ * Result of the auto-match operation
+ */
+export interface AutoMatchChargesResult {
+  /** Total number of charges that were successfully matched and merged */
+  totalMatches: number;
+  /** Array of charges that were merged, with their confidence scores */
+  mergedCharges: MergedCharge[];
+  /** Array of charge UUIDs that had multiple high-confidence matches and were skipped */
+  skippedCharges: string[];
+  /** Array of error messages encountered during the operation */
+  errors: string[];
+}
+
+/**
+ * Aggregated transaction data for matching purposes
+ */
+export interface AggregatedTransaction {
+  /** Sum of all transaction amounts */
+  amount: number;
+  /** Common currency across all transactions */
+  currency: currency;
+  /** Single non-null business ID (or null if all are null) */
+  businessId: string | null;
+  /** Earliest event_date among transactions */
+  date: Date;
+  /** Earliest debit_date/debit_timestamp (for receipt matching) */
+  debitDate: Date | null;
+  /** Concatenated source_description values */
+  description: string;
+}
+
+/**
+ * Aggregated document data for matching purposes
+ */
+export interface AggregatedDocument {
+  /** Sum of all normalized document amounts */
+  amount: number;
+  /** Common currency across all documents */
+  currency: currency;
+  /** Single non-null business ID (or null if all are null) */
+  businessId: string | null;
+  /** Latest document date */
+  date: Date;
+  /** Concatenated serial numbers and identifiers */
+  description: string;
+  /** Document type (for date matching logic) */
+  type: document_type;
+  /** Whether the business is on the creditor side */
+  businessIsCreditor: boolean;
+}
+
+/**
+ * Individual confidence scores for different matching factors
+ */
+export interface ConfidenceScores {
+  /** Amount confidence (0.0 - 1.0) */
+  amount: number;
+  /** Currency confidence (0.0 - 1.0) */
+  currency: number;
+  /** Business confidence (0.0 - 1.0) */
+  business: number;
+  /** Date confidence (0.0 - 1.0) */
+  date: number;
+}
+
+/**
+ * Complete confidence calculation result
+ */
+export interface ConfidenceResult {
+  /** Overall weighted confidence score */
+  overall: number;
+  /** Individual component scores */
+  scores: ConfidenceScores;
+}
+
+/**
+ * Charge classification for matching purposes
+ */
+export enum ChargeType {
+  /** Charge has transactions but no accounting documents */
+  TRANSACTION_ONLY = 'TRANSACTION_ONLY',
+  /** Charge has accounting documents but no transactions */
+  DOCUMENT_ONLY = 'DOCUMENT_ONLY',
+  /** Charge has both transactions and accounting documents */
+  MATCHED = 'MATCHED',
+}
+
+/**
+ * Charge with its associated data for matching
+ */
+export interface ChargeWithData {
+  /** Charge UUID */
+  chargeId: string;
+  /** Owner UUID */
+  ownerId: string;
+  /** Charge classification */
+  type: ChargeType;
+  /** Associated transactions (if any) */
+  transactions: Transaction[];
+  /** Associated documents (if any) */
+  documents: Document[];
+}
+
+/**
+ * Candidate charge for matching with aggregated data
+ */
+export interface MatchCandidate {
+  /** Charge UUID */
+  chargeId: string;
+  /** Aggregated transaction data (if transaction charge) */
+  transactionData?: AggregatedTransaction;
+  /** Aggregated document data (if document charge) */
+  documentData?: AggregatedDocument;
+}
+
+/**
+ * Match score result with confidence and components
+ */
+export interface MatchScore {
+  /** Charge ID being scored */
+  chargeId: string;
+  /** Overall confidence score (0.0 - 1.0) */
+  confidenceScore: number;
+  /** Individual confidence component scores */
+  components: ConfidenceScores;
+}
+
+/**
+ * Transaction charge for matching
+ */
+export interface TransactionCharge {
+  /** Charge UUID */
+  chargeId: string;
+  /** Array of transactions in the charge */
+  transactions: Transaction[];
+}
+
+/**
+ * Document charge for matching
+ */
+export interface DocumentCharge {
+  /** Charge UUID */
+  chargeId: string;
+  /** Array of documents in the charge */
+  documents: Document[];
+}

package/src/modules/documents/resolvers/document-suggestions.resolver.ts

@@ -42,13 +42,13 @@ const missingInfoSuggestions: Resolver<
     if (charge?.transactions_event_amount && charge?.transactions_currency) {
       // use transactions info, if exists
       response.amount = {
-        amount: charge.transactions_event_amount,
+        amount: Number(charge.transactions_event_amount),
         currency: formatCurrency(charge.transactions_currency),
       };
     } else if (charge?.documents_event_amount && charge?.documents_currency) {
       // Use parallel documents (if exists) as documents_event_amount is based on invoices OR receipts
       response.amount = {
-        amount: String(charge.documents_event_amount),
+        amount: charge.documents_event_amount,
         currency: formatCurrency(charge.documents_currency),
       };
     }

package/src/modules/green-invoice/helpers/contract-to-draft.helper.ts

@@ -9,7 +9,7 @@ import { Currency } from '@shared/enums';
 import { NewDocumentInfo } from '@shared/gql-types';
 import { dateToTimelessDateString } from '@shared/helpers';
 import { TimelessDateString } from '@shared/types';
-import { getClientFromGreenInvoiceClient } from './green-invoice-clients.helper';
+import { getClientFromGreenInvoiceClient } from './green-invoice-clients.helper.js';
 
 export const convertContractToDraft = async (
   contract: IGetContractsByIdsResult,

package/src/modules/green-invoice/helpers/green-invoice.helper.ts

@@ -21,7 +21,7 @@ import type {
 import { CloudinaryProvider } from '@modules/app-providers/cloudinary.js';
 import { GreenInvoiceClientProvider } from '@modules/app-providers/green-invoice-client.js';
 import { ChargesProvider } from '@modules/charges/providers/charges.provider.js';
-import { CountryCode } from '@modules/countries/types';
+import { CountryCode } from '@modules/countries/types.js';
 import { DocumentsProvider } from '@modules/documents/providers/documents.provider.js';
 import { IssuedDocumentsProvider } from '@modules/documents/providers/issued-documents.provider.js';
 import type { document_status, IInsertDocumentsParams } from '@modules/documents/types';

package/src/modules-app.ts

@@ -20,6 +20,7 @@ import { GmailServiceProvider } from './modules/app-providers/gmail-listener/gma
 import { PubsubServiceProvider } from './modules/app-providers/gmail-listener/pubsub-service.provider.js';
 import { GreenInvoiceClientProvider } from './modules/app-providers/green-invoice-client.js';
 import { businessTripsModule } from './modules/business-trips/index.js';
+import { chargesMatcherModule } from './modules/charges-matcher/index.js';
 import { chargesModule } from './modules/charges/index.js';
 import { chartsModule } from './modules/charts/index.js';
 import { commonModule } from './modules/common/index.js';
@@ -61,6 +62,7 @@ export async function createGraphQLApp(env: Environment) {
       accountantApprovalModule,
       businessTripsModule,
       chargesModule,
+      chargesMatcherModule,
       cornJobsModule,
       depreciationModule,
       documentsModule,

package/src/shared/types/index.ts

@@ -32,7 +32,7 @@ export interface DocumentSuggestionsProto {
   ownerId?: string;
   counterpartyId?: string;
   amount?: {
-    amount: string;
+    amount: number;
     currency: Currency;
   };
   isIncome?: boolean;