@liiift-studio/sales-portal 1.8.1 → 2.0.0

package/api/getBalanceTransactions.js

@@ -22,18 +22,34 @@ export default async function handler(req, res) {
 		// Fetch all balance transactions for the period
 		const balanceTransactions = await fetchAllBalanceTransactions(timeRange);
 
-		// Calculate total balance change (ignoring payouts and pending transactions)
-		const totalBalanceChange = balanceTransactions.reduce((total, transaction) => {
-			if (transaction.type === 'payout' || transaction.type === 'stripe_fee' || transaction.status === 'pending') {
-				return total;
+		// Calculate balance change from charges and refunds only (what sales data tracks)
+		const RECONCILIATION_TYPES = ['charge', 'refund'];
+		let totalBalanceChange = 0;
+		const flaggedTransactions = [];
+
+		balanceTransactions.forEach(transaction => {
+			if (transaction.status === 'pending') return;
+
+			if (RECONCILIATION_TYPES.includes(transaction.type)) {
+				totalBalanceChange += transaction.amount;
+			} else if (transaction.type !== 'payout' && transaction.type !== 'stripe_fee') {
+				// Collect disputes, adjustments, connect transfers for review
+				flaggedTransactions.push({
+					id: transaction.id,
+					type: transaction.type,
+					amount: transaction.amount,
+					created: transaction.created,
+					description: transaction.description,
+					source: transaction.source,
+				});
 			}
-			return total + transaction.amount;
-		}, 0);
+		});
 
 		return res.status(200).json({
 			success: true,
 			data: {
 				totalBalanceChange,
+				flaggedTransactions,
 				transactions: balanceTransactions
 			}
 		});

package/api/utils/__tests__/dateUtils.test.js

@@ -0,0 +1,111 @@
+import { describe, test, expect } from 'vitest';
+import { createDateRange, createStripeTimeRange, isInDateRange } from '../dateUtils.js';
+
+describe('createDateRange', () => {
+	test('creates correct month boundaries for January', () => {
+		const { startDate, endDate } = createDateRange({ date: '2024-01-15T00:00:00Z' });
+
+		expect(startDate.toISOString()).toBe('2024-01-01T00:00:00.000Z');
+		expect(endDate.toISOString()).toBe('2024-01-31T23:59:59.999Z');
+	});
+
+	test('creates correct month boundaries for February (leap year)', () => {
+		const { startDate, endDate } = createDateRange({ date: '2024-02-10T00:00:00Z' });
+
+		expect(startDate.toISOString()).toBe('2024-02-01T00:00:00.000Z');
+		expect(endDate.toISOString()).toBe('2024-02-29T23:59:59.999Z');
+	});
+
+	test('creates correct month boundaries for February (non-leap year)', () => {
+		const { startDate, endDate } = createDateRange({ date: '2025-02-10T00:00:00Z' });
+
+		expect(endDate.toISOString()).toBe('2025-02-28T23:59:59.999Z');
+	});
+
+	test('creates correct month boundaries for December', () => {
+		const { startDate, endDate } = createDateRange({ date: '2024-12-25T00:00:00Z' });
+
+		expect(startDate.toISOString()).toBe('2024-12-01T00:00:00.000Z');
+		expect(endDate.toISOString()).toBe('2024-12-31T23:59:59.999Z');
+	});
+
+	test('handles custom date range', () => {
+		const start = new Date('2024-03-15T00:00:00Z').getTime();
+		const end = new Date('2024-06-20T23:59:59Z').getTime();
+
+		const { startDate, endDate } = createDateRange({
+			dateRange: { start, end }
+		});
+
+		expect(startDate.getUTCFullYear()).toBe(2024);
+		expect(startDate.getUTCMonth()).toBe(2); // March
+		expect(startDate.getUTCDate()).toBe(15);
+		expect(startDate.getUTCHours()).toBe(0);
+
+		expect(endDate.getUTCMonth()).toBe(5); // June
+		expect(endDate.getUTCDate()).toBe(20);
+		expect(endDate.getUTCHours()).toBe(23);
+	});
+
+	test('handles serialized Date from JSON (string)', () => {
+		const { startDate, endDate } = createDateRange({
+			date: '2024-03-01T00:00:00.000Z'
+		});
+
+		expect(startDate.toISOString()).toBe('2024-03-01T00:00:00.000Z');
+		expect(endDate.toISOString()).toBe('2024-03-31T23:59:59.999Z');
+	});
+});
+
+describe('createStripeTimeRange', () => {
+	test('converts dates to Unix seconds', () => {
+		const startDate = new Date('2024-03-01T00:00:00.000Z');
+		const endDate = new Date('2024-03-31T23:59:59.999Z');
+
+		const range = createStripeTimeRange(startDate, endDate);
+
+		expect(range.gte).toBe(Math.floor(startDate.getTime() / 1000));
+		expect(range.lte).toBe(Math.floor(endDate.getTime() / 1000));
+	});
+
+	test('does not add padding', () => {
+		const startDate = new Date('2024-01-01T00:00:00.000Z');
+		const endDate = new Date('2024-01-31T23:59:59.999Z');
+
+		const range = createStripeTimeRange(startDate, endDate);
+
+		// Should be exactly the start/end, no ±24hr padding
+		expect(range.gte).toBe(1704067200); // Jan 1 2024 00:00:00 UTC
+		expect(range.lte).toBe(1706745599); // Jan 31 2024 23:59:59 UTC
+	});
+});
+
+describe('isInDateRange', () => {
+	const startDate = new Date('2024-03-01T00:00:00.000Z');
+	const endDate = new Date('2024-03-31T23:59:59.999Z');
+
+	test('includes first second of month', () => {
+		const timestamp = Math.floor(startDate.getTime() / 1000);
+		expect(isInDateRange(timestamp, startDate, endDate)).toBe(true);
+	});
+
+	test('includes last second of month', () => {
+		const timestamp = Math.floor(endDate.getTime() / 1000);
+		expect(isInDateRange(timestamp, startDate, endDate)).toBe(true);
+	});
+
+	test('excludes timestamp before range', () => {
+		const beforeStart = Math.floor(startDate.getTime() / 1000) - 1;
+		expect(isInDateRange(beforeStart, startDate, endDate)).toBe(false);
+	});
+
+	test('excludes timestamp after range', () => {
+		const afterEnd = Math.floor(endDate.getTime() / 1000) + 1;
+		expect(isInDateRange(afterEnd, startDate, endDate)).toBe(false);
+	});
+
+	test('includes mid-month timestamp', () => {
+		const mid = Math.floor(new Date('2024-03-15T12:00:00Z').getTime() / 1000);
+		expect(isInDateRange(mid, startDate, endDate)).toBe(true);
+	});
+});

package/api/utils/__tests__/feeCalculator.test.js

@@ -0,0 +1,100 @@
+import { describe, test, expect } from 'vitest';
+import { calculateFees, formatRefunds } from '../feeCalculator.js';
+
+describe('calculateFees', () => {
+	const mockCharge = {
+		balance_transaction: {
+			fee_details: [
+				{ type: 'stripe_fee', amount: 300 }, // $3.00 Stripe fee
+			]
+		}
+	};
+
+	test('primary item calculates total fee and proportional share', () => {
+		const result = calculateFees({
+			charge: mockCharge,
+			amount: 5000, // $50 of $100 total
+			total: 10000,
+			isPrimaryItem: true,
+			isRefund: false,
+		});
+
+		expect(result.totalTransactionFee).toBe(300);
+		expect(result.stripeFees).toBe(150); // 50% of 300
+	});
+
+	test('non-primary item distributes fee proportionally', () => {
+		const result = calculateFees({
+			charge: mockCharge,
+			amount: 3000, // $30 of $100 total
+			total: 10000,
+			isPrimaryItem: false,
+			isRefund: false,
+			totalFee: 300,
+		});
+
+		expect(result.stripeFees).toBe(90); // 30% of 300
+	});
+
+	test('refunds have zero fees', () => {
+		const result = calculateFees({
+			charge: mockCharge,
+			amount: -5000,
+			total: 10000,
+			isPrimaryItem: false,
+			isRefund: true,
+		});
+
+		expect(result.stripeFees).toBe(0);
+	});
+
+	test('zero total produces zero ratio without crash', () => {
+		const result = calculateFees({
+			charge: mockCharge,
+			amount: 0,
+			total: 0,
+			isPrimaryItem: false,
+			isRefund: false,
+			totalFee: 300,
+		});
+
+		expect(result.stripeFees).toBe(0);
+		expect(result.disputeAmount).toBe(0);
+	});
+});
+
+describe('formatRefunds', () => {
+	const refunds = [
+		{ amount: 5000, created: 1711929600, id: 'ref_1', reason: 'requested_by_customer', status: 'succeeded' },
+	];
+
+	test('returns empty array for no refunds', () => {
+		expect(formatRefunds(null, 5000, 10000)).toEqual([]);
+		expect(formatRefunds([], 5000, 10000)).toEqual([]);
+	});
+
+	test('calculates proportional adjustedTotal', () => {
+		const result = formatRefunds(refunds, 5000, 10000);
+
+		expect(result).toHaveLength(1);
+		expect(result[0].total).toBe(5000); // Full refund amount
+		expect(result[0].adjustedTotal).toBe(2500); // 50% of 5000
+		expect(result[0].percentOf_total).toBe(0.5);
+	});
+
+	test('full-invoice refund has ratio of 1', () => {
+		const result = formatRefunds(refunds, 10000, 10000);
+
+		expect(result[0].adjustedTotal).toBe(5000); // 100% of 5000
+		expect(result[0].percentOf_total).toBe(1);
+	});
+
+	test('preserves refund metadata', () => {
+		const result = formatRefunds(refunds, 5000, 10000);
+
+		expect(result[0].id).toBe('ref_1');
+		expect(result[0].description).toBe('requested_by_customer');
+		expect(result[0].status).toBe('succeeded');
+		expect(result[0].created).toBe(1711929600);
+	});
+});

package/api/utils/processors/invoiceProcessor.js

@@ -85,12 +85,13 @@ function processLineItem({ line, invoice, associatedOrder, associatedTypeface, i
 
 	// Calculate final totals
 	const lineTotal = lineAmount; // Pre-tax total (discounts already applied by Stripe)
-	const lineTotalWithTax = lineAmount + line.tax_amounts.reduce((acc, tax) => acc + tax.amount, 0) - (disputeAmount || 0);
+	const lineTotalWithTax = lineAmount + line.tax_amounts.reduce((acc, tax) => acc + tax.amount, 0);
 
 	return {
 		// Quantities
 		totalWithTax: lineTotalWithTax,
 		total: lineTotal, // Pre-tax total
+		disputeDeduction: disputeAmount || 0,
 		invoiceTotal: invoice.total_excluding_tax,
 		invoiceTotalWithTax: invoice.total,
 		discountAmounts: line.discount_amounts,
@@ -171,8 +172,9 @@ function processShippingCost({ invoice, associatedOrder, totalFee = null, paymen
 
 	return {
 		// Quantities
-		totalWithTax: invoice.shipping_cost.amount_total - disputeAmount,
+		totalWithTax: invoice.shipping_cost.amount_total,
 		total: invoice.shipping_cost.amount_subtotal, // Pre-tax total
+		disputeDeduction: disputeAmount || 0,
 		invoiceTotal: invoice.total_excluding_tax,
 		invoiceTotalWithTax: invoice.total,
 		discountAmounts: null,

package/api/utils/processors/paymentProcessor.js

@@ -221,8 +221,8 @@ function processPaymentItem({ item = {}, payment, associatedOrder, associatedTyp
     const orderTax = associatedOrder?.tax || 0;
     const itemRatio = payment.amount > 0 ? (item.amount || 0) / payment.amount : 0;
     const itemTaxAmount = Math.round(orderTax * itemRatio);
-    const itemTotal = (item.amount || 0) - itemTaxAmount - disputeAmount;
-    const itemTotalWithTax = (item.amount || 0) - disputeAmount;
+    const itemTotal = (item.amount || 0) - itemTaxAmount;
+    const itemTotalWithTax = (item.amount || 0);
 
     // Try to find matching product if no description
     let description = item.description;
@@ -232,6 +232,7 @@ function processPaymentItem({ item = {}, payment, associatedOrder, associatedTyp
     return {
         totalWithTax: itemTotalWithTax,
         total: itemTotal,
+        disputeDeduction: disputeAmount || 0,
         invoiceTotal: payment.amount,
         invoiceTotalWithTax: payment.amount,
         discountAmounts: [],
@@ -313,8 +314,9 @@ function processShippingCost({ payment, associatedOrder, totalFee = null }) {
     });
 
     return {
-        totalWithTax: payment.shipping_cost - disputeAmount,
-        total: payment.shipping_cost - disputeAmount,
+        totalWithTax: payment.shipping_cost,
+        total: payment.shipping_cost,
+        disputeDeduction: disputeAmount || 0,
         invoiceTotal: payment.amount,
         invoiceTotalWithTax: payment.amount,
         discountAmounts: [],

package/components/DateRangeSalesTable.js

@@ -10,7 +10,10 @@ import {
   ListItemText,
   IconButton,
   Tooltip,
-  Box
+  Box,
+  Dialog,
+  DialogTitle,
+  DialogContent
 } from '@mui/material';
 import { DataGrid } from '@mui/x-data-grid';
 import DownloadIcon from '@mui/icons-material/Download';
@@ -71,6 +74,7 @@ export function DateRangeSalesTable({ designer, admin, loading, updateLoadingSta
   const reconciliationData = useReconciliation({
     designer, admin, sales: dateRangeSales, dateRange
   });
+  const [flaggedOpen, setFlaggedOpen] = useState(false);
 
   // Dashboard states for summary data
   const [chartState, setChartState] = useState({
@@ -558,17 +562,61 @@ export function DateRangeSalesTable({ designer, admin, loading, updateLoadingSta
             {!reconciliationData.isLoading && (
               <>
                 <Typography variant="body1">
-                  <strong>Stripe Balance Change:</strong> ${(reconciliationData.totalBalanceChange / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+                  <strong>Stripe Balance (charges + refunds):</strong> ${(reconciliationData.totalBalanceChange / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
                 </Typography>
                 <Typography variant="body1">
-                  <strong>Gross Sales:</strong> ${(reconciliationData.grossSales / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+                  <strong>Calculated Gross:</strong> ${(reconciliationData.grossSales / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+                  {reconciliationData.shippingTotal > 0 && (
+                    <span style={{ opacity: 0.6 }}> (incl. ${(reconciliationData.shippingTotal / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })} shipping)</span>
+                  )}
                 </Typography>
               </>
             )}
+
+            {reconciliationData.flaggedTransactions?.length > 0 && (
+              <Box sx={{ mt: 1 }}>
+                <Tooltip title="View disputes, adjustments, and other flagged transactions">
+                  <Button
+                    size="small"
+                    startIcon={<InfoIcon />}
+                    onClick={() => setFlaggedOpen(true)}
+                    sx={{ color: 'inherit', textTransform: 'none' }}
+                  >
+                    {reconciliationData.flaggedTransactions.length} flagged transaction{reconciliationData.flaggedTransactions.length !== 1 ? 's' : ''}
+                  </Button>
+                </Tooltip>
+              </Box>
+            )}
+
           </Box>
         </Box>
       )}
 
+      {/* Flagged Transactions Modal */}
+      <Dialog open={flaggedOpen} onClose={() => setFlaggedOpen(false)} maxWidth="sm" fullWidth>
+        <DialogTitle>Flagged Transactions</DialogTitle>
+        <DialogContent>
+          <Typography variant="body2" sx={{ mb: 2, opacity: 0.7 }}>
+            These transactions are in Stripe's balance but excluded from the charges+refunds reconciliation.
+          </Typography>
+          {reconciliationData.flaggedTransactions?.map((t, i) => (
+            <Box key={t.id || i} sx={{ display: 'flex', justifyContent: 'space-between', py: 1, borderBottom: '1px solid rgba(0,0,0,0.08)' }}>
+              <Box>
+                <Typography variant="body2" sx={{ fontWeight: 'bold', textTransform: 'capitalize' }}>
+                  {t.type?.replace(/_/g, ' ')}
+                </Typography>
+                <Typography variant="caption" sx={{ opacity: 0.6 }}>
+                  {t.description || t.id} — {new Date(t.created * 1000).toLocaleDateString()}
+                </Typography>
+              </Box>
+              <Typography variant="body2" sx={{ fontWeight: 'bold', color: t.amount < 0 ? 'var(--red, red)' : 'inherit' }}>
+                ${(t.amount / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+              </Typography>
+            </Box>
+          ))}
+        </DialogContent>
+      </Dialog>
+
       {/* Summary Dashboard and Analysis Components - only show when data is loaded */}
       {!!dateRangeSales.length && (
         <>

package/components/Sales.js

@@ -321,10 +321,9 @@ export default function Sales(props) {
 			
 			if (previousSales && previousSales.length > 0) {
 				previousPeriodTotal = previousSales.reduce((sum, sale) => {
+					if (sale.shippingProvision) return sum; // Exclude shipping from revenue
 					const saleTotal = sale.total || 0;
-					const saleTax = sale.taxAmount || 0;
-					const saleShipping = sale.shippingCost || 0;
-					return sum + (saleTotal - saleTax - saleShipping) / 100; // Convert cents to dollars
+					return sum + saleTotal / 100; // Convert cents to dollars
 				}, 0);
 				
 				if (previousPeriodTotal > 0) {
@@ -379,7 +378,7 @@ export default function Sales(props) {
 					};
 				}
 				
-				const saleRevenue = (sale.total - (sale.taxAmount || 0) - (sale.shippingCost || 0)) / 100;
+				const saleRevenue = sale.shippingProvision ? 0 : (sale.total || 0) / 100;
 				locationSales[location].totalRevenue += saleRevenue;
 				locationSales[location].orders += 1;
 			});
@@ -416,7 +415,7 @@ export default function Sales(props) {
 						};
 					}
 					
-					const saleRevenue = (sale.total - (sale.taxAmount || 0) - (sale.shippingCost || 0)) / 100;
+					const saleRevenue = sale.shippingProvision ? 0 : (sale.total || 0) / 100;
 					prevLocationSales[location].totalRevenue += saleRevenue;
 					prevLocationSales[location].orders += 1;
 					prevTotalRevenue += saleRevenue;

package/components/SalesTable.js

@@ -11,7 +11,10 @@ import {
   IconButton,
   Tooltip,
   Box,
-  CircularProgress
+  CircularProgress,
+  Dialog,
+  DialogTitle,
+  DialogContent
 } from '@mui/material';
 import DownloadIcon from '@mui/icons-material/Download';
 import TuneIcon from '@mui/icons-material/Tune';
@@ -35,6 +38,7 @@ export function SalesTable({ sales = [], designer = {}, admin = false, loading =
   const [filterModel, setFilterModel] = useState({ items: [], quickFilterValues: [] });
 
   const reconciliationData = useReconciliation({ designer, admin, sales, date });
+  const [flaggedOpen, setFlaggedOpen] = useState(false);
 
   // Early return if no designer data is available
   if (!designer?.user || !designer?.password) {
@@ -209,18 +213,61 @@ export function SalesTable({ sales = [], designer = {}, admin = false, loading =
             {!reconciliationData.isLoading && (
               <>
                 <Typography variant="body1">
-                  <strong>Stripe Balance Change:</strong> ${(reconciliationData.totalBalanceChange / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+                  <strong>Stripe Balance (charges + refunds):</strong> ${(reconciliationData.totalBalanceChange / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
                 </Typography>
                 <Typography variant="body1">
-                  <strong>Gross Sales:</strong> ${(reconciliationData.grossSales / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+                  <strong>Calculated Gross:</strong> ${(reconciliationData.grossSales / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+                  {reconciliationData.shippingTotal > 0 && (
+                    <span style={{ opacity: 0.6 }}> (incl. ${(reconciliationData.shippingTotal / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })} shipping)</span>
+                  )}
                 </Typography>
               </>
             )}
-            
+
+            {reconciliationData.flaggedTransactions?.length > 0 && (
+              <Box sx={{ mt: 1 }}>
+                <Tooltip title="View disputes, adjustments, and other flagged transactions">
+                  <Button
+                    size="small"
+                    startIcon={<InfoIcon />}
+                    onClick={() => setFlaggedOpen(true)}
+                    sx={{ color: 'inherit', textTransform: 'none' }}
+                  >
+                    {reconciliationData.flaggedTransactions.length} flagged transaction{reconciliationData.flaggedTransactions.length !== 1 ? 's' : ''}
+                  </Button>
+                </Tooltip>
+              </Box>
+            )}
+
           </Box>
         </Box>
       )}
 
+      {/* Flagged Transactions Modal */}
+      <Dialog open={flaggedOpen} onClose={() => setFlaggedOpen(false)} maxWidth="sm" fullWidth>
+        <DialogTitle>Flagged Transactions</DialogTitle>
+        <DialogContent>
+          <Typography variant="body2" sx={{ mb: 2, opacity: 0.7 }}>
+            These transactions are in Stripe's balance but excluded from the charges+refunds reconciliation.
+          </Typography>
+          {reconciliationData.flaggedTransactions?.map((t, i) => (
+            <Box key={t.id || i} sx={{ display: 'flex', justifyContent: 'space-between', py: 1, borderBottom: '1px solid rgba(0,0,0,0.08)' }}>
+              <Box>
+                <Typography variant="body2" sx={{ fontWeight: 'bold', textTransform: 'capitalize' }}>
+                  {t.type?.replace(/_/g, ' ')}
+                </Typography>
+                <Typography variant="caption" sx={{ opacity: 0.6 }}>
+                  {t.description || t.id} — {new Date(t.created * 1000).toLocaleDateString()}
+                </Typography>
+              </Box>
+              <Typography variant="body2" sx={{ fontWeight: 'bold', color: t.amount < 0 ? 'var(--red, red)' : 'inherit' }}>
+                ${(t.amount / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+              </Typography>
+            </Box>
+          ))}
+        </DialogContent>
+      </Dialog>
+
       {/* Sales Table */}
       <Box
         sx={{

package/hooks/__tests__/useReconciliation.test.js

@@ -0,0 +1,91 @@
+import { describe, test, expect } from 'vitest';
+import { calculateGrossSales } from '../calculateGrossSales.js';
+import {
+	simpleSale,
+	saleWithRefund,
+	multiLineItem1,
+	multiLineItem2,
+	shippingSale,
+	disputedSale,
+	paymentIntentSale
+} from '../../__fixtures__/sampleSales.js';
+
+describe('calculateGrossSales', () => {
+	test('simple sale: grossSales equals totalWithTax', () => {
+		const { grossSales, shippingTotal } = calculateGrossSales([simpleSale]);
+
+		expect(grossSales).toBe(5350);
+		expect(shippingTotal).toBe(0);
+	});
+
+	test('shipping is included in gross but tracked separately', () => {
+		const { grossSales, shippingTotal } = calculateGrossSales([simpleSale, shippingSale]);
+
+		expect(grossSales).toBe(5350 + 1605);
+		expect(shippingTotal).toBe(1605);
+	});
+
+	test('refund is subtracted from gross', () => {
+		const { grossSales } = calculateGrossSales([saleWithRefund]);
+
+		// totalWithTax (10700) - refund.total (10700) = 0
+		expect(grossSales).toBe(0);
+	});
+
+	test('multi-line invoice refund is deduplicated by ID', () => {
+		const { grossSales } = calculateGrossSales([multiLineItem1, multiLineItem2]);
+
+		// Both items have totalWithTax 5350 each = 10700
+		// Both have the SAME refund ref_multi789 with total 5000
+		// Should only subtract 5000 once, not twice
+		expect(grossSales).toBe(10700 - 5000);
+	});
+
+	test('refund without ID is still counted (fallback)', () => {
+		const saleWithUnidentifiedRefund = {
+			...simpleSale,
+			refunds: [{
+				total: 1000,
+				adjustedTotal: 1000,
+				// No id field
+			}]
+		};
+
+		const { grossSales } = calculateGrossSales([saleWithUnidentifiedRefund]);
+		// Refund without id is skipped by dedup logic (refund.id is falsy)
+		// So it won't be subtracted — this is a known limitation
+		expect(grossSales).toBe(5350);
+	});
+
+	test('disputed sale: disputeDeduction is NOT subtracted from grossSales', () => {
+		const { grossSales } = calculateGrossSales([disputedSale]);
+
+		// totalWithTax is 21400, disputeDeduction is stored separately
+		// grossSales should be the full 21400
+		expect(grossSales).toBe(21400);
+	});
+
+	test('payment intent sale works the same as invoice', () => {
+		const { grossSales } = calculateGrossSales([paymentIntentSale]);
+
+		expect(grossSales).toBe(8000);
+	});
+
+	test('empty array returns zero', () => {
+		const { grossSales, shippingTotal } = calculateGrossSales([]);
+
+		expect(grossSales).toBe(0);
+		expect(shippingTotal).toBe(0);
+	});
+
+	test('mixed sales: products + shipping + refund', () => {
+		const { grossSales, shippingTotal } = calculateGrossSales([
+			simpleSale,       // 5350
+			shippingSale,     // 1605
+			saleWithRefund,   // 10700 - 10700 refund = 0
+		]);
+
+		expect(grossSales).toBe(5350 + 1605 + 10700 - 10700);
+		expect(shippingTotal).toBe(1605);
+	});
+});

package/hooks/calculateGrossSales.js

@@ -0,0 +1,31 @@
+// Pure function for calculating gross sales — extracted for testability
+/**
+ * Calculates gross sales from sales data, matching Stripe's charge+refund total
+ * @param {Array} sales - Array of sale objects
+ * @returns {Object} grossSales total and shipping breakdown (in cents)
+ */
+export function calculateGrossSales(sales) {
+	let grossSales = 0;
+	let shippingTotal = 0;
+	const processedRefunds = new Set();
+
+	sales.forEach(sale => {
+		// Use totalWithTax for all items — this is what Stripe actually charged
+		grossSales += sale?.totalWithTax || 0;
+
+		if (sale?.shippingProvision) {
+			shippingTotal += sale?.totalWithTax || 0;
+		}
+
+		// Deduplicate refunds by ID — multi-line invoices repeat the same refunds
+		// Use refund.total (actual Stripe amount) not adjustedTotal (proportional)
+		sale?.refunds?.forEach(refund => {
+			if (refund?.id && !processedRefunds.has(refund.id)) {
+				processedRefunds.add(refund.id);
+				grossSales -= (refund.total || 0);
+			}
+		});
+	});
+
+	return { grossSales, shippingTotal };
+}

package/hooks/useReconciliation.js

@@ -1,21 +1,9 @@
 // Shared hook for Stripe balance reconciliation
 import { useState, useEffect } from 'react';
+import { calculateGrossSales } from './calculateGrossSales.js';
 
-/**
- * Calculates gross sales from sales data
- * @param {Array} sales - Array of sale objects
- * @returns {number} Gross sales total in cents
- */
-function calculateGrossSales(sales) {
-	let grossSales = 0;
-	sales.forEach(sale => {
-		sale?.refunds?.map((refund) => {
-			grossSales -= (refund.adjustedTotal || 0);
-		});
-		grossSales += sale?.shippingProvision ? sale?.total : sale?.totalWithTax;
-	});
-	return grossSales;
-}
+// Re-export for backward compatibility
+export { calculateGrossSales };
 
 /**
  * Hook for fetching and comparing Stripe balance transactions against sales data
@@ -33,7 +21,9 @@ export function useReconciliation({ designer, admin, sales, date, dateRange }) {
 		isReconciled: false,
 		totalBalanceChange: 0,
 		grossSales: 0,
+		shippingTotal: 0,
 		difference: 0,
+		flaggedTransactions: [],
 		error: null
 	});
 
@@ -67,14 +57,17 @@ export function useReconciliation({ designer, admin, sales, date, dateRange }) {
 
 				if (data.success) {
 					const totalBalanceChange = data.data.totalBalanceChange;
-					const grossSales = calculateGrossSales(sales);
+					const flaggedTransactions = data.data.flaggedTransactions || [];
+					const { grossSales, shippingTotal } = calculateGrossSales(sales);
 
 					setReconciliationData(prev => ({
 						...prev,
 						totalBalanceChange,
 						grossSales,
+						shippingTotal,
 						difference: totalBalanceChange - grossSales,
 						isReconciled: Math.abs(totalBalanceChange - grossSales) < 1,
+						flaggedTransactions,
 						isLoading: false
 					}));
 				} else {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@liiift-studio/sales-portal",
-	"version": "1.8.1",
+	"version": "2.0.0",
 	"description": "Centralized sales portal package for Liiift Studio projects",
 	"main": "index.js",
 	"types": "index.d.ts",
@@ -49,7 +49,10 @@
 		}
 	},
 	"scripts": {
-		"test": "echo \"No tests yet\" && exit 0"
+		"test": "vitest run",
+		"link:tdf": "npm link && cd ../../sites/tdf && npm link @liiift-studio/sales-portal",
+		"link:darden": "npm link && cd ../../sites/darden && npm link @liiift-studio/sales-portal",
+		"link:positype": "npm link && cd ../../sites/positype && npm link @liiift-studio/sales-portal"
 	},
 	"keywords": [
 		"sales",
@@ -82,6 +85,7 @@
 		"@emotion/react": "^11.14.0",
 		"@emotion/styled": "^11.14.1",
 		"@mui/icons-material": "^5.18.0",
-		"slugify": "^1.6.6"
+		"slugify": "^1.6.6",
+		"vitest": "^4.1.1"
 	}
 }