Settling Debts

// Source: routes/settlements.js:14-70
const simplifyDebts = (balances) => {
  // Separate creditors (owed money) and debtors (owe money)
  const balanceArray = Object.keys(balances).map(userId => ({
    user: userId,
    amount: balances[userId]
  }));
  
  const creditors = balanceArray.filter(b => b.amount > 0);
  const debtors = balanceArray.filter(b => b.amount < 0);
  
  // Sort by largest amounts
  creditors.sort((a, b) => b.amount - a.amount);
  debtors.sort((a, b) => a.amount - b.amount);
  
  const transactions = [];
  let debtorIndex = 0;
  let creditorIndex = 0;
  
  while (debtorIndex < debtors.length && creditorIndex < creditors.length) {
    const debtor = debtors[debtorIndex];
    const creditor = creditors[creditorIndex];
    
    // Settle the smaller of the two amounts
    const amountToSettle = Math.min(Math.abs(debtor.amount), creditor.amount);
    const roundedAmount = Math.round(amountToSettle * 100) / 100;
    
    if (roundedAmount > 0) {
      transactions.push({
        from: debtor.user,
        to: creditor.user,
        amount: roundedAmount,
      });
    }
    
    // Update balances
    debtor.amount += roundedAmount;
    creditor.amount -= roundedAmount;
    
    // Move to next if settled
    if (Math.abs(debtor.amount) < 0.01) debtorIndex++;
    if (creditor.amount < 0.01) creditorIndex++;
  }
  
  return transactions;
};

// Source: models/Settlement.js
{
  group: ObjectId,           // Reference to the group
  type: 'group',              // 'group' or 'individual'
  createdBy: ObjectId,        // Who initiated the settlement
  status: 'completed',        // 'pending', 'completed', or 'cancelled'
  summary: [                  // Optimized transaction list
    {
      from: ObjectId,         // User who pays
      to: ObjectId,           // User who receives
      amount: Number          // Amount to transfer
    }
  ],
  createdAt: Date
}

// Backend: routes/settlements.js:144-174
GET /api/settlements/group/:groupId

// Returns array of settlements
[
  {
    "_id": "507f1f77bcf86cd799439013",
    "group": "507f1f77bcf86cd799439011",
    "type": "group",
    "status": "completed",
    "createdBy": {
      "_id": "507f191e810c19729de860ea",
      "name": "Alice",
      "email": "[email protected]"
    },
    "summary": [
      {
        "from": { "_id": "...", "name": "Bob" },
        "to": { "_id": "...", "name": "Alice" },
        "amount": 150
      }
    ],
    "createdAt": "2024-01-20T15:30:00.000Z"
  }
]