@liiift-studio/sales-portal 1.8.1 → 2.3.0

package/api/getBalanceTransactions.js

@@ -22,18 +22,70 @@ 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;
+		// Build detailed reconciliation data
+		const RECONCILIATION_TYPES = ['charge', 'refund'];
+		let rawTotal = 0; // Accumulate as float, round once at the end
+		let chargeCount = 0;
+		let refundCount = 0;
+		let chargeTotal = 0;
+		let refundTotal = 0;
+		let settlementCurrency = null;
+		let hasCurrencyConversion = false;
+		let pendingCount = 0;
+		const flaggedTransactions = [];
+
+		balanceTransactions.forEach(transaction => {
+			if (!settlementCurrency && transaction.currency) {
+				settlementCurrency = transaction.currency;
+			}
+
+			if (transaction.status === 'pending') {
+				pendingCount++;
+				return;
+			}
+
+			const rate = transaction.exchange_rate || 1;
+			if (rate !== 1) hasCurrencyConversion = true;
+			const originalAmount = transaction.amount / rate;
+
+			if (RECONCILIATION_TYPES.includes(transaction.type)) {
+				rawTotal += originalAmount;
+				if (transaction.type === 'charge') {
+					chargeCount++;
+					chargeTotal += originalAmount;
+				} else {
+					refundCount++;
+					refundTotal += originalAmount;
+				}
+			} else if (transaction.type !== 'payout' && transaction.type !== 'stripe_fee') {
+				flaggedTransactions.push({
+					id: transaction.id,
+					type: transaction.type,
+					amount: Math.round(originalAmount),
+					created: transaction.created,
+					description: transaction.description,
+					source: transaction.source,
+				});
 			}
-			return total + transaction.amount;
-		}, 0);
+		});
+
+		// Round the accumulated total once to minimize rounding error
+		const totalBalanceChange = Math.round(rawTotal);
 
 		return res.status(200).json({
 			success: true,
 			data: {
 				totalBalanceChange,
+				flaggedTransactions,
+				diagnostics: {
+					chargeCount,
+					refundCount,
+					chargeTotal: Math.round(chargeTotal),
+					refundTotal: Math.round(refundTotal),
+					pendingCount,
+					settlementCurrency,
+					hasCurrencyConversion,
+				},
 				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,14 +85,16 @@ 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,
+		chargeAmount: invoice.charge?.amount || invoice.total,
 		discountAmounts: line.discount_amounts,
 		taxAmounts: line.tax_amounts,
 		stripeFees: totalFees,
@@ -139,7 +141,8 @@ function processLineItem({ line, invoice, associatedOrder, associatedTypeface, i
 		orderNumber: associatedOrder?.orderNumber || null,
 		author: associatedTypeface?.author || null,
 		typeface: associatedTypeface || null,
-		saleType: "invoice"
+		saleType: "invoice",
+		currency: invoice.currency || 'usd'
 	};
 }
 
@@ -171,10 +174,12 @@ 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,
+		chargeAmount: invoice.charge?.amount || invoice.total,
 		discountAmounts: null,
 		stripeFees: totalFees,
 		disputed,
@@ -228,7 +233,8 @@ function processShippingCost({ invoice, associatedOrder, totalFee = null, paymen
 		orderNumber: associatedOrder?.orderNumber || null,
 		author: null,
 		typeface: null,
-		saleType: "invoice"
+		saleType: "invoice",
+		currency: invoice.currency || 'usd'
 	};
 }
 

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,8 +232,10 @@ function processPaymentItem({ item = {}, payment, associatedOrder, associatedTyp
     return {
         totalWithTax: itemTotalWithTax,
         total: itemTotal,
+        disputeDeduction: disputeAmount || 0,
         invoiceTotal: payment.amount,
         invoiceTotalWithTax: payment.amount,
+        chargeAmount: payment.latest_charge?.amount || payment.amount,
         discountAmounts: [],
         stripeFees: totalFees,
         disputed,
@@ -282,7 +284,8 @@ function processPaymentItem({ item = {}, payment, associatedOrder, associatedTyp
         orderNumber: associatedOrder?.orderNumber || null,
         author: associatedTypeface?.author || null,
         typeface: associatedTypeface || null,
-        saleType: "paymentIntent"
+        saleType: "paymentIntent",
+        currency: payment.currency || 'usd'
     };
 }
 
@@ -313,10 +316,12 @@ 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,
+        chargeAmount: payment.latest_charge?.amount || payment.amount,
         discountAmounts: [],
         stripeFees: totalFees,
         disputed,
@@ -357,7 +362,8 @@ function processShippingCost({ payment, associatedOrder, totalFee = null }) {
         orderNumber: associatedOrder?.orderNumber || null,
         author: null,
         typeface: null,
-        saleType: "paymentIntent"
+        saleType: "paymentIntent",
+        currency: payment.currency || 'usd'
     };
 }
 

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({
@@ -501,25 +505,21 @@ export function DateRangeSalesTable({ designer, admin, loading, updateLoadingSta
       {/* Reconciliation Check - Only show for admin users */}
       {admin && dateRangeSales.length > 0 && (
         <Box sx={{ width: '100%', mb: 2 }}>
-          <Box 
-            sx={{ 
-              display: 'inline-block',
-              gap: 2,
-              p: 2,
-              ml: -2,
-              borderRadius: '4px',
-              border: reconciliationData.isReconciled 
-                ? '2px solid var(--green, green)' 
-                : '2px solid var(--red, red)',
-              color: reconciliationData.isReconciled
-                ? 'var(--green, green)'
-                : 'var(--red, red)',
-              backgroundColor: 'rgba(255, 255, 255, 0.9)',
-              filter: 'invert(0) !important',
-              '& *': { filter: 'invert(0) !important' },
-            }}
-          >
-            
+          <Box sx={{
+            display: 'inline-block',
+            p: 2,
+            ml: -2,
+            borderRadius: '4px',
+            border: reconciliationData.isReconciled
+              ? '2px solid var(--green, green)'
+              : '2px solid var(--red, red)',
+            color: reconciliationData.isReconciled
+              ? 'var(--green, green)'
+              : 'var(--red, red)',
+            backgroundColor: 'rgba(255, 255, 255, 0.9)',
+            filter: 'invert(0) !important',
+            '& *': { filter: 'invert(0) !important' },
+          }}>
             {reconciliationData.error ? (
               <Typography variant="body1" sx={{ color: 'var(--red, red)' }}>
                 <WarningIcon fontSize="small" sx={{ mr: 1 }} />
@@ -528,47 +528,93 @@ export function DateRangeSalesTable({ designer, admin, loading, updateLoadingSta
             ) : reconciliationData.isLoading ? (
               <Typography variant="body1"><CircularProgress size={24} sx={{ mr: 1 }} /> Checking reconciliation...</Typography>
             ) : reconciliationData.isReconciled ? (
-              <Typography variant="body1" sx={{ fontWeight: 'bold'}}>
+              <Typography variant="body1" sx={{ fontWeight: 'bold', display: 'flex', alignItems: 'center', gap: 1 }}>
                 <CheckCircleIcon /> Reconciled
+                {reconciliationData.percentOff !== 0 && (
+                  <span style={{ fontWeight: 'normal', opacity: 0.7 }}>
+                    ({Math.abs(reconciliationData.percentOff).toFixed(2)}% variance)
+                  </span>
+                )}
               </Typography>
             ) : (
-              <Box sx={{ display: 'flex', alignItems: 'center' }}>
-                <Tooltip title="The difference between Stripe balance change and gross sales">
-                  <Typography variant="body1" sx={{ fontWeight: 'bold', display: 'flex', alignItems: 'center' }}>
-                    <WarningIcon/> Needs Reconciliation (Difference: ${(Math.abs(reconciliationData.difference) / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })})
-                  </Typography>
-                </Tooltip>
-                <Tooltip 
-                  title={
-                    <React.Fragment>
-                      <Typography variant="body2" sx={{ fontWeight: 'bold' }}>Possible causes:</Typography>
-                      <Typography variant="body2">• This could be due to a sale being refunded outside your selected date range. Check for the same difference in other periods.</Typography>
-                    </React.Fragment>
-                  }
-                  placement="right"
-                  arrow
-                >
-                  <IconButton size="small" sx={{ ml: 1, color: 'inherit' }}>
-                    <InfoIcon fontSize="small" />
-                  </IconButton>
-                </Tooltip>
-              </Box>
+              <Typography variant="body1" sx={{ fontWeight: 'bold', display: 'flex', alignItems: 'center', gap: 1 }}>
+                <WarningIcon /> Needs Reconciliation — ${(Math.abs(reconciliationData.difference) / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })} off ({Math.abs(reconciliationData.percentOff).toFixed(2)}%)
+              </Typography>
             )}
-            
-            {!reconciliationData.isLoading && (
+
+            {!reconciliationData.isLoading && !reconciliationData.error && (
               <>
                 <Typography variant="body1">
-                  <strong>Stripe Balance Change:</strong> ${(reconciliationData.totalBalanceChange / 100).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+                  <strong>Stripe Balance:</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.checks?.length > 0 && (
+                  <Box sx={{ mt: 2, borderTop: '1px solid currentColor', pt: 1, opacity: 0.9 }}>
+                    {reconciliationData.checks.map((check, i) => (
+                      <Tooltip key={i} title={check.tip || ''} placement="right" arrow>
+                        <Typography variant="body2" sx={{
+                          display: 'flex', alignItems: 'center', gap: 0.5, py: 0.25,
+                          cursor: check.tip ? 'help' : 'default',
+                        }}>
+                          <span style={{ fontSize: '0.9em' }}>
+                            {check.status === 'pass' ? '✓' : check.status === 'fail' ? '✗' : check.status === 'warn' ? '⚠' : 'ℹ'}
+                          </span>
+                          <strong>{check.label}:</strong> {check.detail}
+                        </Typography>
+                      </Tooltip>
+                    ))}
+                  </Box>
+                )}
+
+                {reconciliationData.flaggedTransactions?.length > 0 && (
+                  <Box sx={{ mt: 1 }}>
+                    <Button
+                      size="small"
+                      startIcon={<InfoIcon />}
+                      onClick={() => setFlaggedOpen(true)}
+                      sx={{ color: 'inherit', textTransform: 'none' }}
+                    >
+                      View {reconciliationData.flaggedTransactions.length} flagged transaction{reconciliationData.flaggedTransactions.length !== 1 ? 's' : ''}
+                    </Button>
+                  </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 && (
         <>