feat: add wallet ledger with idempotent credit and debit operations

src/lib/wallet.js

@@ -0,0 +1,70 @@
+"use strict";
+
+class WalletStore {
+  constructor() {
+    this.balances = new Map();
+    this.transactions = [];
+    this.byIdempotencyKey = new Map();
+    this.nextId = 1;
+  }
+
+  getBalance(userId) {
+    return this.balances.get(userId) || 0;
+  }
+
+  listTransactions(userId) {
+    return this.transactions.filter((tx) => tx.userId === userId);
+  }
+
+  applyTransaction({ userId, type, amount, reason, idempotencyKey }) {
+    if (!userId) {
+      throw new Error("userId_required");
+    }
+
+    if (!["credit", "debit", "refund"].includes(type)) {
+      throw new Error("invalid_transaction_type");
+    }
+
+    if (!Number.isInteger(amount) || amount <= 0) {
+      throw new Error("invalid_amount");
+    }
+
+    if (!idempotencyKey) {
+      throw new Error("idempotency_key_required");
+    }
+
+    const existing = this.byIdempotencyKey.get(idempotencyKey);
+    if (existing) {
+      return existing;
+    }
+
+    const currentBalance = this.getBalance(userId);
+
+    if (type === "debit" && currentBalance < amount) {
+      throw new Error("insufficient_credits");
+    }
+
+    const delta = (type === "debit") ? -amount : amount;
+    const newBalance = currentBalance + delta;
+
+    const tx = {
+      id: String(this.nextId++),
+      userId,
+      type,
+      amount,
+      reason: reason || null,
+      idempotencyKey,
+      createdAt: new Date().toISOString(),
+      balanceAfter: newBalance,
+    };
+
+    this.transactions.push(tx);
+    this.byIdempotencyKey.set(idempotencyKey, tx);
+    this.balances.set(userId, newBalance);
+    return tx;
+  }
+}
+
+module.exports = {
+  WalletStore,
+};