@darkpos/pricing 1.0.146 → 1.0.147

package/__TEST__/invoice/refundInvoices.test.js

@@ -0,0 +1,239 @@
+const usePricing = require('../../index');
+const mockStores = require('../mocks/stores');
+
+const pricing = usePricing({ store: mockStores[0] });
+
+const ORDER_ID = 'order-1';
+const OVERPAID_ITEM_ID = 'item-0';
+const UNDERPAID_ITEM_ID = 'item-1';
+
+const liveOrder = {
+  _id: ORDER_ID,
+  items: [
+    {
+      _id: OVERPAID_ITEM_ID,
+      total: 10.5,
+      totalPaid: 14.7,
+      status: { paid: { value: true }, picked: { value: false } },
+    },
+    {
+      _id: UNDERPAID_ITEM_ID,
+      total: 10.5,
+      totalPaid: 10.3,
+      status: { paid: { value: false }, picked: { value: false } },
+    },
+  ],
+};
+
+const ordersById = { [ORDER_ID]: liveOrder };
+
+const overpaidInvoiceItem = {
+  orderId: ORDER_ID,
+  orderItemId: OVERPAID_ITEM_ID,
+  total: 14.7,
+  totalPaid: 14.7,
+  amount: 14.7,
+  status: { paid: { value: true }, picked: { value: false } },
+};
+
+const partiallyPaidInvoiceItem = {
+  orderId: ORDER_ID,
+  orderItemId: UNDERPAID_ITEM_ID,
+  total: 13.65,
+  totalPaid: 10.3,
+  amount: 10.3,
+  status: { paid: { value: false }, picked: { value: false } },
+};
+
+describe('computeRefundables', () => {
+  const overpaidState = pricing.invoice.resolveItemState(
+    overpaidInvoiceItem,
+    ordersById
+  ); // excess +4.2
+  const underpaidState = pricing.invoice.resolveItemState(
+    partiallyPaidInvoiceItem,
+    ordersById
+  ); // excess -0.2
+
+  test('refunds the full excess from the overpaid item and redistributes the surplus to the underpaid item', () => {
+    const [overpaidRefundable, underpaidCredit] =
+      pricing.invoice.computeRefundables([overpaidState, underpaidState], 4);
+    expect(overpaidRefundable).toBe(4.2); // full overpayment cleared
+    expect(underpaidCredit).toBe(-0.2); // 0.2 credit applied to cover the gap
+  });
+
+  test('net refund amount across all items equals the requested refund total', () => {
+    const [overpaidRefundable, underpaidCredit] =
+      pricing.invoice.computeRefundables([overpaidState, underpaidState], 4);
+    expect(overpaidRefundable + underpaidCredit).toBe(4);
+  });
+
+  test('result is order-independent — same outcome when items are reversed', () => {
+    const [underpaidCredit, overpaidRefundable] =
+      pricing.invoice.computeRefundables([underpaidState, overpaidState], 4);
+    expect(overpaidRefundable).toBe(4.2);
+    expect(underpaidCredit).toBe(-0.2);
+  });
+
+  test('never-paid item receives no credit even when overpaid surplus exists', () => {
+    const neverPaidState = {
+      ...pricing.invoice.resolveItemState(partiallyPaidInvoiceItem, ordersById),
+      itemTotalPaid: 0,
+      excess: -10.5,
+    };
+    const [overpaidRefundable, neverPaidRefundable] =
+      pricing.invoice.computeRefundables([overpaidState, neverPaidState], 4);
+    expect(overpaidRefundable).toBe(4); // capped — no surplus to redistribute
+    expect(neverPaidRefundable).toBe(0); // never-paid item stays untouched
+  });
+
+  test('draws directly from totalPaid when no overpaid items exist', () => {
+    const exactlyPaidState = { ...overpaidState, excess: 0 };
+    const [refundable] = pricing.invoice.computeRefundables(
+      [exactlyPaidState],
+      5
+    );
+    expect(refundable).toBe(5);
+  });
+
+  test('returns all zeros when the requested refund amount is 0', () => {
+    const refundables = pricing.invoice.computeRefundables(
+      [overpaidState, underpaidState],
+      0
+    );
+    expect(refundables).toEqual([0, 0]);
+  });
+});
+
+describe('applyRefundToInvoices', () => {
+  const invoicesForOnePayment = [
+    {
+      _id: 'inv-1',
+      amount: 25,
+      paymentOrderItems: [overpaidInvoiceItem, partiallyPaidInvoiceItem],
+    },
+  ];
+
+  test('the refund invoice has the correct total amount and both item refunds', () => {
+    const refundInvoices = pricing.invoice.applyRefundToInvoices(
+      invoicesForOnePayment,
+      ordersById,
+      4
+    );
+    expect(refundInvoices).toHaveLength(1);
+    expect(refundInvoices[0].amount).toBe(-4);
+    expect(refundInvoices[0].paymentOrderItems).toHaveLength(2);
+    expect(refundInvoices[0].paymentOrderItems[0].amount).toBe(-4.2);
+    expect(refundInvoices[0].paymentOrderItems[1].amount).toBe(0.2);
+  });
+
+  test('the overpaid item is cleared to its exact total and marked as paid', () => {
+    const refundInvoices = pricing.invoice.applyRefundToInvoices(
+      invoicesForOnePayment,
+      ordersById,
+      4
+    );
+    expect(refundInvoices[0].paymentOrderItems[0].status.paid.value).toBe(true);
+  });
+
+  test('the underpaid item receives a credit that covers its remaining balance and is marked as paid', () => {
+    const refundInvoices = pricing.invoice.applyRefundToInvoices(
+      invoicesForOnePayment,
+      ordersById,
+      4
+    );
+    expect(refundInvoices[0].paymentOrderItems[1].status.paid.value).toBe(true);
+  });
+
+  test('returns an empty array when the refund amount is 0', () => {
+    const refundInvoices = pricing.invoice.applyRefundToInvoices(
+      invoicesForOnePayment,
+      ordersById,
+      0
+    );
+    expect(refundInvoices).toEqual([]);
+  });
+
+  test('skips invoices that are already refunded or have no positive balance', () => {
+    const invoicesIncludingAlreadyRefunded = [
+      {
+        _id: 'inv-already-refunded',
+        amount: -5,
+        paymentOrderItems: [overpaidInvoiceItem],
+      },
+      ...invoicesForOnePayment,
+    ];
+    const refundInvoices = pricing.invoice.applyRefundToInvoices(
+      invoicesIncludingAlreadyRefunded,
+      ordersById,
+      4
+    );
+    expect(refundInvoices).toHaveLength(1);
+    expect(refundInvoices[0]._id).toBe('inv-1');
+  });
+
+  test('distributes the refund across multiple invoices when the first is exhausted', () => {
+    const splitPaymentInvoices = [
+      {
+        _id: 'first-payment',
+        amount: 14.7,
+        paymentOrderItems: [overpaidInvoiceItem],
+      },
+      {
+        _id: 'second-payment',
+        amount: 10.3,
+        paymentOrderItems: [partiallyPaidInvoiceItem],
+      },
+    ];
+    // Refund 5: overpaid item covers 4.2, the remaining 0.8 comes from the second invoice
+    const refundInvoices = pricing.invoice.applyRefundToInvoices(
+      splitPaymentInvoices,
+      ordersById,
+      5
+    );
+    expect(refundInvoices).toHaveLength(2);
+    expect(refundInvoices[0].amount).toBe(-4.2);
+    expect(refundInvoices[1].amount).toBe(-0.8);
+  });
+});
+
+describe('buildItemRefund', () => {
+  const overpaidItemState = pricing.invoice.resolveItemState(
+    overpaidInvoiceItem,
+    ordersById
+  );
+  const underpaidItemState = pricing.invoice.resolveItemState(
+    partiallyPaidInvoiceItem,
+    ordersById
+  );
+
+  test('overpaid item: refunding its full excess results in a negative amount and paid = true', () => {
+    const itemRefund = pricing.invoice.buildItemRefund(overpaidItemState, 4.2);
+    expect(itemRefund.amount).toBe(-4.2);
+    expect(itemRefund.totalPaid).toBe(14.7); // pre-refund value preserved
+    expect(itemRefund.total).toBe(10.5);
+    expect(itemRefund.status.paid.value).toBe(true); // 14.7 - 4.2 = 10.5 >= 10.5
+  });
+
+  test('underpaid item: applying a credit results in a positive amount and paid = true', () => {
+    const itemRefund = pricing.invoice.buildItemRefund(
+      underpaidItemState,
+      -0.2
+    );
+    expect(itemRefund.amount).toBe(0.2); // positive = credit
+    expect(itemRefund.totalPaid).toBe(10.3);
+    expect(itemRefund.total).toBe(10.5);
+    expect(itemRefund.status.paid.value).toBe(true); // 10.3 - (-0.2) = 10.5 >= 10.5
+  });
+
+  test('paid stays false when the refund does not fully cover the remaining balance', () => {
+    const itemRefund = pricing.invoice.buildItemRefund(underpaidItemState, 2); // totalPaid drops to 8.3
+    expect(itemRefund.status.paid.value).toBe(false); // 8.3 < 10.5
+  });
+
+  test('preserves all other fields from the original invoice item', () => {
+    const itemRefund = pricing.invoice.buildItemRefund(overpaidItemState, 4.2);
+    expect(itemRefund.orderId).toBe(ORDER_ID);
+    expect(itemRefund.orderItemId).toBe(OVERPAID_ITEM_ID);
+  });
+});

package/lib/invoice/applyRefundToInvoices.js

@@ -0,0 +1,52 @@
+module.exports = ({ utils, actions }) => {
+  const { math } = utils;
+
+  /**
+   * Distributes a refund amount across a set of payment invoices.
+   *
+   * For each invoice, it resolves the live state of each item, computes
+   * the refundable amounts (order-independent), and builds the refund entries.
+   *
+   * Returns an array of refund invoices ready to be persisted — each with a
+   * negative amount (the refund) and updated paymentOrderItems.
+   */
+  return function applyRefundToInvoices(
+    paymentInvoices,
+    ordersById,
+    totalToRefund
+  ) {
+    let remaining = totalToRefund;
+
+    return paymentInvoices
+      .filter(({ amount }) => amount > 0)
+      .map(({ amount, paymentOrderItems, ...rest }) => {
+        if (remaining <= 0) return null;
+
+        const itemStates = (paymentOrderItems || []).map(item =>
+          actions.resolveItemState(item, ordersById)
+        );
+        const refundables = actions.computeRefundables(itemStates, remaining);
+
+        let invoiceRefundAmount = 0;
+        const itemRefunds = itemStates
+          .map((state, i) => {
+            const refundable = refundables[i];
+            if (refundable === 0) return null;
+            invoiceRefundAmount = math.add(invoiceRefundAmount, refundable);
+            return actions.buildItemRefund(state, refundable);
+          })
+          .filter(Boolean);
+
+        remaining = math.sub(remaining, invoiceRefundAmount);
+
+        if (invoiceRefundAmount <= 0) return null;
+
+        return {
+          ...rest,
+          amount: -invoiceRefundAmount,
+          paymentOrderItems: itemRefunds,
+        };
+      })
+      .filter(Boolean);
+  };
+};

package/lib/invoice/buildItemRefund.js

@@ -0,0 +1,23 @@
+module.exports = ({ utils }) => {
+  const { math } = utils;
+
+  return function buildItemRefund(
+    { item, itemTotal, itemTotalPaid, currentStatus },
+    refundable
+  ) {
+    const nextTotalPaid = math.sub(itemTotalPaid, refundable);
+    return {
+      ...item,
+      total: itemTotal,
+      totalPaid: itemTotalPaid,
+      amount: -refundable,
+      status: {
+        ...currentStatus,
+        paid: {
+          ...((currentStatus && currentStatus.paid) || {}),
+          value: nextTotalPaid >= itemTotal,
+        },
+      },
+    };
+  };
+};

package/lib/invoice/computeRefundables.js

@@ -0,0 +1,59 @@
+module.exports = ({ utils }) => {
+  const { math } = utils;
+
+  return function computeRefundables(itemStates, totalToRefund) {
+    const refundables = new Array(itemStates.length).fill(0);
+
+    if (totalToRefund <= 0) return refundables;
+
+    // Only partially-paid underpaid items are eligible to absorb redistribution credits.
+    const eligibleDeficit = itemStates.reduce(
+      (sum, { excess, itemTotalPaid }) => {
+        const isPartiallyPaidAndUnderpaid = excess < 0 && itemTotalPaid > 0;
+        return isPartiallyPaidAndUnderpaid
+          ? math.add(sum, math.sub(0, excess))
+          : sum;
+      },
+      0
+    );
+
+    // Cap total drawn from overpaid items so the net refund never exceeds totalToRefund.
+    let maxFromOverpaid = math.add(totalToRefund, eligibleDeficit);
+    let tempRemaining = totalToRefund;
+
+    // Pass 1: refund each overpaid item's excess, capped by maxFromOverpaid
+    itemStates.forEach(({ excess }, i) => {
+      if (excess > 0 && maxFromOverpaid > 0) {
+        const refund = excess > maxFromOverpaid ? maxFromOverpaid : excess;
+        refundables[i] = refund;
+        tempRemaining = math.sub(tempRemaining, refund);
+        maxFromOverpaid = math.sub(maxFromOverpaid, refund);
+      }
+    });
+
+    if (tempRemaining < 0) {
+      // Pass 2a: over-refunded — spread surplus as credits to partially-paid underpaid items
+      let surplus = math.sub(0, tempRemaining);
+      itemStates.forEach(({ excess, itemTotalPaid }, i) => {
+        if (excess < 0 && itemTotalPaid > 0 && surplus > 0) {
+          const deficit = math.sub(0, excess);
+          const credit = surplus > deficit ? deficit : surplus;
+          refundables[i] = -credit;
+          surplus = math.sub(surplus, credit);
+        }
+      });
+    } else if (tempRemaining > 0) {
+      // Pass 2b: under-refunded — draw remainder from non-overpaid items (totalPaid > 0)
+      itemStates.forEach(({ itemTotalPaid, excess }, i) => {
+        if (excess <= 0 && itemTotalPaid > 0 && tempRemaining > 0) {
+          const refund =
+            tempRemaining > itemTotalPaid ? itemTotalPaid : tempRemaining;
+          refundables[i] = refund;
+          tempRemaining = math.sub(tempRemaining, refund);
+        }
+      });
+    }
+
+    return refundables;
+  };
+};

package/lib/invoice/index.js

@@ -1,5 +1,9 @@
 const getStatusByItems = require('./getStatusByItems');
 const getTotalByItems = require('./getTotalByItems');
+const resolveItemState = require('./resolveItemState');
+const computeRefundables = require('./computeRefundables');
+const buildItemRefund = require('./buildItemRefund');
+const applyRefundToInvoices = require('./applyRefundToInvoices');
 
 const invoiceActions = (deps = {}) => {
   const actions = {};
@@ -12,6 +16,10 @@ const invoiceActions = (deps = {}) => {
   const freezedActions = Object.freeze({
     getStatusByItems: getStatusByItems(innerDeps),
     getTotalByItems: getTotalByItems(innerDeps),
+    resolveItemState: resolveItemState(innerDeps),
+    computeRefundables: computeRefundables(innerDeps),
+    buildItemRefund: buildItemRefund(innerDeps),
+    applyRefundToInvoices: applyRefundToInvoices(innerDeps),
   });
 
   Object.keys(freezedActions).forEach(actionName => {

package/lib/invoice/resolveItemState.js

@@ -0,0 +1,25 @@
+module.exports = ({ utils }) => {
+  const { math } = utils;
+
+  return function resolveItemState(paymentOrderItem, ordersById) {
+    const order = (ordersById && ordersById[paymentOrderItem.orderId]) || {};
+    const orderItem = (order.items || []).find(
+      each => each._id === paymentOrderItem.orderItemId
+    );
+
+    const itemTotal =
+      (orderItem && orderItem.total) || paymentOrderItem.total || 0;
+    const itemTotalPaid =
+      (orderItem && orderItem.totalPaid) || paymentOrderItem.totalPaid || 0;
+    const currentStatus =
+      (orderItem && orderItem.status) || paymentOrderItem.status || {};
+
+    return {
+      item: paymentOrderItem,
+      itemTotal,
+      itemTotalPaid,
+      currentStatus,
+      excess: math.sub(itemTotalPaid, itemTotal),
+    };
+  };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darkpos/pricing",
-  "version": "1.0.146",
+  "version": "1.0.147",
   "description": "Pricing calculator",
   "author": "Dark POS",
   "license": "ISC",
@@ -54,5 +54,5 @@
     "supertest": "^6.2.3",
     "supervisor": "^0.12.0"
   },
-  "gitHead": "50cda463bcaad6e5aa03bded3329269a9ac99398"
+  "gitHead": "c983de0f3b8d4978e2fb0b68551ba347dbdc4d55"
 }