@liiift-studio/sales-portal 3.1.3 → 3.1.4

package/api/getYearSales.js

@@ -1,13 +1,68 @@
-// API endpoint for fetching a full year of sales data in a single request
+// API endpoint for fetching a full year of sales data with year-level aggregates
 import { authenticateDesigner, processSalesData } from './utils/salesDataProcessor';
 import { sendError, requirePost } from './utils/apiResponse';
 
-export const config = { maxDuration: 300 };
+export const config = { maxDuration: 800 };
+
+/**
+ * Extracts tax total from a sale's taxAmounts array
+ */
+function getSaleTax(sale) {
+	let tax = 0;
+	sale?.taxAmounts?.forEach(t => { tax += t.amount || 0; });
+	return tax;
+}
+
+/**
+ * Extracts discount total from a sale's discountAmounts array
+ */
+function getSaleDiscount(sale) {
+	let discount = 0;
+	sale?.discountAmounts?.forEach(d => { discount += d.amount || 0; });
+	return discount;
+}
+
+/**
+ * Extracts refund total from a sale's refunds and dispute data
+ */
+function getSaleRefund(sale) {
+	let refund = 0;
+	if (sale?.disputed) {
+		refund += (sale.totalWithTax || 0) - (sale.total || 0);
+	}
+	sale?.refunds?.forEach(r => { refund += r.adjustedTotal || 0; });
+	return refund;
+}
+
+/**
+ * Extracts typeface title from a sale description
+ */
+function getTypefaceTitle(sale) {
+	if (!sale.description) return 'Unknown Typeface';
+	let title = sale.description.substring(0, sale.description.indexOf(' ('));
+	if (title === '') title = sale.description.substring(0, sale.description.indexOf(' —'));
+	if (title === '') title = sale.description.substring(0, sale.description.indexOf('.'));
+	if (title === '') title = sale.description;
+	return title;
+}
+
+/**
+ * Extracts license type name from a sale description
+ */
+function getLicenseName(sale) {
+	const parenthesisMatch = sale.description?.match(/\((.*?)\)/);
+	if (parenthesisMatch?.[1]) return parenthesisMatch[1].trim();
+	if (sale.description?.includes('—')) {
+		const parts = sale.description.split('—');
+		if (parts.length > 1) return parts[1].trim();
+	}
+	if (sale.license) return sale.license;
+	return 'Unknown';
+}
 
 /**
  * Fetches 12 months of sales data, processes each month, and returns
- * the results grouped by month with typeface breakdowns.
- * This avoids 12 separate API calls from the frontend.
+ * the results grouped by month with year-level aggregates for all components.
  */
 export default async function handler(req, res) {
 	if (!requirePost(req, res)) return;
@@ -26,6 +81,16 @@ export default async function handler(req, res) {
 
 		const months = [];
 
+		// Year-level aggregation accumulators
+		let yearTax = 0;
+		let yearDiscounts = 0;
+		let yearRefunds = 0;
+		let yearOrderCount = 0;
+		const yearLocationMap = {};
+		const yearTypefaceMap = {};
+		const yearLicenseMap = {};
+		const processedSalesKeys = new Set();
+
 		// Process each month sequentially to avoid Stripe rate limiting
 		for (let month = 0; month < 12; month++) {
 			const monthDate = new Date(Date.UTC(year, month, 1));
@@ -37,7 +102,7 @@ export default async function handler(req, res) {
 					admin
 				});
 
-				// Group sales by typeface for the stacked chart
+				// Per-month aggregation (existing)
 				const typefaceMap = {};
 				let monthTotal = 0;
 				let shippingTotal = 0;
@@ -48,13 +113,88 @@ export default async function handler(req, res) {
 						return;
 					}
 
+					const saleTotal = sale.total || 0;
+					const saleTax = getSaleTax(sale);
+					const saleDiscount = getSaleDiscount(sale);
+					const saleRefund = getSaleRefund(sale);
+
+					// Per-month typeface chart data (existing behavior)
 					const typefaceName = sale.typeface?.title || sale.description?.split(' (')[0] || 'Other';
 					if (!typefaceMap[typefaceName]) {
 						typefaceMap[typefaceName] = { total: 0, count: 0 };
 					}
-					typefaceMap[typefaceName].total += sale.total || 0;
+					typefaceMap[typefaceName].total += saleTotal;
 					typefaceMap[typefaceName].count += 1;
-					monthTotal += sale.total || 0;
+					monthTotal += saleTotal;
+
+					// Year-level aggregates
+					yearTax += saleTax;
+					yearDiscounts += saleDiscount;
+					yearRefunds += saleRefund;
+					yearOrderCount += 1;
+
+					// Deduplicate for year-level detailed aggregation
+					const saleKey = `${sale.saleType || ''}-${sale.id}-${sale.lineId || ''}`;
+					if (processedSalesKeys.has(saleKey)) return;
+					processedSalesKeys.add(saleKey);
+
+					// Year location data
+					const countryCode = sale.paymentMethod?.origin?.country ||
+						sale.customerAddress?.country ||
+						sale.billingAddress?.country ||
+						'Unknown';
+					if (!yearLocationMap[countryCode]) {
+						yearLocationMap[countryCode] = { revenue: 0, orders: 0 };
+					}
+					yearLocationMap[countryCode].revenue += saleTotal;
+					yearLocationMap[countryCode].orders += 1;
+
+					// Year typeface data (rich, for TypefaceList/TopPerformers)
+					const title = getTypefaceTitle(sale);
+					if (!yearTypefaceMap[title]) {
+						yearTypefaceMap[title] = {
+							title,
+							total: 0,
+							grossTotal: 0,
+							taxTotal: 0,
+							discountTotal: 0,
+							refundTotal: 0,
+							orders: 0,
+							author: sale.typeface?.author || sale.author || null,
+						};
+					}
+					const tf = yearTypefaceMap[title];
+					tf.total += saleTotal;
+					tf.grossTotal += saleTotal;
+					tf.taxTotal += saleTax;
+					tf.discountTotal += saleDiscount;
+					tf.refundTotal += saleRefund;
+					tf.orders += 1;
+					// Keep the most detailed author info
+					if (!tf.author && (sale.typeface?.author || sale.author)) {
+						tf.author = sale.typeface?.author || sale.author;
+					}
+
+					// Year license type data (for LicenseTypeList)
+					const licenseName = getLicenseName(sale);
+					if (!yearLicenseMap[licenseName]) {
+						yearLicenseMap[licenseName] = {
+							name: licenseName,
+							total: 0,
+							grossTotal: 0,
+							taxTotal: 0,
+							discountTotal: 0,
+							refundTotal: 0,
+							orders: 0,
+						};
+					}
+					const lt = yearLicenseMap[licenseName];
+					lt.total += saleTotal;
+					lt.grossTotal += saleTotal;
+					lt.taxTotal += saleTax;
+					lt.discountTotal += saleDiscount;
+					lt.refundTotal += saleRefund;
+					lt.orders += 1;
 				});
 
 				months.push({
@@ -69,7 +209,6 @@ export default async function handler(req, res) {
 						.sort((a, b) => b.total - a.total),
 				});
 			} catch (monthError) {
-				// If a single month fails, include it with zero data rather than failing the whole request
 				console.error(`Error processing month ${month + 1}/${year}:`, monthError.message);
 				months.push({
 					month,
@@ -84,19 +223,36 @@ export default async function handler(req, res) {
 			}
 		}
 
-		// Build a list of all typefaces across the year for consistent chart series
+		// Build year-level arrays from maps
 		const allTypefaces = new Set();
 		months.forEach(m => m.typefaces.forEach(t => allTypefaces.add(t.name)));
 
+		const yearTypefaces = Object.values(yearTypefaceMap)
+			.sort((a, b) => b.total - a.total);
+
+		const yearLicenseTypes = Object.values(yearLicenseMap)
+			.sort((a, b) => b.total - a.total);
+
 		res.status(200).json({
 			success: true,
 			data: {
 				year,
 				months,
 				allTypefaces: [...allTypefaces].sort(),
+				currency: months.find(m => m.currency)?.currency || 'usd',
+
+				// Existing year totals
 				yearTotal: months.reduce((sum, m) => sum + m.total, 0),
 				yearShipping: months.reduce((sum, m) => sum + m.shippingTotal, 0),
-				currency: months.find(m => m.currency)?.currency || 'usd',
+
+				// New year-level aggregates
+				yearTax,
+				yearDiscounts,
+				yearRefunds,
+				yearOrderCount,
+				yearLocationData: yearLocationMap,
+				yearTypefaces,
+				yearLicenseTypes,
 			}
 		});
 	} catch (error) {

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

@@ -0,0 +1,313 @@
+// Tests for year sales aggregation helper functions
+import { describe, test, expect } from 'vitest';
+
+// Since the helpers are inline in getYearSales.js, we replicate them here for testing.
+// If they're ever extracted into a shared util, import them directly instead.
+
+function getSaleTax(sale) {
+	let tax = 0;
+	sale?.taxAmounts?.forEach(t => { tax += t.amount || 0; });
+	return tax;
+}
+
+function getSaleDiscount(sale) {
+	let discount = 0;
+	sale?.discountAmounts?.forEach(d => { discount += d.amount || 0; });
+	return discount;
+}
+
+function getSaleRefund(sale) {
+	let refund = 0;
+	if (sale?.disputed) {
+		refund += (sale.totalWithTax || 0) - (sale.total || 0);
+	}
+	sale?.refunds?.forEach(r => { refund += r.adjustedTotal || 0; });
+	return refund;
+}
+
+function getTypefaceTitle(sale) {
+	if (!sale.description) return 'Unknown Typeface';
+	let title = sale.description.substring(0, sale.description.indexOf(' ('));
+	if (title === '') title = sale.description.substring(0, sale.description.indexOf(' —'));
+	if (title === '') title = sale.description.substring(0, sale.description.indexOf('.'));
+	if (title === '') title = sale.description;
+	return title;
+}
+
+function getLicenseName(sale) {
+	const parenthesisMatch = sale.description?.match(/\((.*?)\)/);
+	if (parenthesisMatch?.[1]) return parenthesisMatch[1].trim();
+	if (sale.description?.includes('—')) {
+		const parts = sale.description.split('—');
+		if (parts.length > 1) return parts[1].trim();
+	}
+	if (sale.license) return sale.license;
+	return 'Unknown';
+}
+
+describe('getSaleTax', () => {
+	test('returns 0 for sale with no taxAmounts', () => {
+		expect(getSaleTax({})).toBe(0);
+		expect(getSaleTax({ taxAmounts: [] })).toBe(0);
+		expect(getSaleTax(null)).toBe(0);
+	});
+
+	test('sums multiple tax amounts', () => {
+		const sale = {
+			taxAmounts: [
+				{ amount: 500 },
+				{ amount: 300 },
+			]
+		};
+		expect(getSaleTax(sale)).toBe(800);
+	});
+
+	test('handles missing amount fields', () => {
+		const sale = { taxAmounts: [{ amount: 100 }, {}] };
+		expect(getSaleTax(sale)).toBe(100);
+	});
+});
+
+describe('getSaleDiscount', () => {
+	test('returns 0 for sale with no discounts', () => {
+		expect(getSaleDiscount({})).toBe(0);
+		expect(getSaleDiscount({ discountAmounts: [] })).toBe(0);
+	});
+
+	test('sums discount amounts', () => {
+		const sale = {
+			discountAmounts: [
+				{ amount: 200 },
+				{ amount: 150 },
+			]
+		};
+		expect(getSaleDiscount(sale)).toBe(350);
+	});
+});
+
+describe('getSaleRefund', () => {
+	test('returns 0 for sale with no refunds or disputes', () => {
+		expect(getSaleRefund({})).toBe(0);
+	});
+
+	test('sums refund adjustedTotals', () => {
+		const sale = {
+			refunds: [
+				{ adjustedTotal: 1000 },
+				{ adjustedTotal: 500 },
+			]
+		};
+		expect(getSaleRefund(sale)).toBe(1500);
+	});
+
+	test('adds disputed amount from totalWithTax - total', () => {
+		const sale = {
+			disputed: true,
+			totalWithTax: 5000,
+			total: 4200,
+		};
+		expect(getSaleRefund(sale)).toBe(800);
+	});
+
+	test('combines disputed and refunded amounts', () => {
+		const sale = {
+			disputed: true,
+			totalWithTax: 5000,
+			total: 4200,
+			refunds: [{ adjustedTotal: 300 }],
+		};
+		expect(getSaleRefund(sale)).toBe(1100);
+	});
+});
+
+describe('getTypefaceTitle', () => {
+	test('extracts title before parenthesis', () => {
+		expect(getTypefaceTitle({ description: 'Berna (Desktop License)' })).toBe('Berna');
+	});
+
+	test('extracts title before em dash', () => {
+		expect(getTypefaceTitle({ description: 'Berna — Desktop' })).toBe('Berna');
+	});
+
+	test('extracts title before period', () => {
+		expect(getTypefaceTitle({ description: 'Berna.otf' })).toBe('Berna');
+	});
+
+	test('returns full description if no delimiter', () => {
+		expect(getTypefaceTitle({ description: 'Berna' })).toBe('Berna');
+	});
+
+	test('returns Unknown Typeface when no description', () => {
+		expect(getTypefaceTitle({})).toBe('Unknown Typeface');
+	});
+});
+
+describe('getLicenseName', () => {
+	test('extracts license from parentheses', () => {
+		expect(getLicenseName({ description: 'Berna (Desktop License)' })).toBe('Desktop License');
+	});
+
+	test('extracts license after em dash', () => {
+		expect(getLicenseName({ description: 'Berna — Web License' })).toBe('Web License');
+	});
+
+	test('uses license property as fallback', () => {
+		expect(getLicenseName({ description: 'Berna', license: 'App' })).toBe('App');
+	});
+
+	test('returns Unknown when no license info', () => {
+		expect(getLicenseName({ description: 'Berna' })).toBe('Unknown');
+		expect(getLicenseName({})).toBe('Unknown');
+	});
+});
+
+describe('year-level aggregation logic', () => {
+	// Simulate the aggregation loop from getYearSales.js
+	function aggregateYearData(monthlySales) {
+		let yearTax = 0;
+		let yearDiscounts = 0;
+		let yearRefunds = 0;
+		let yearOrderCount = 0;
+		const yearLocationMap = {};
+		const yearTypefaceMap = {};
+		const yearLicenseMap = {};
+
+		monthlySales.flat().forEach(sale => {
+			if (sale.shippingProvision) return;
+
+			const saleTotal = sale.total || 0;
+			const saleTax = getSaleTax(sale);
+			const saleDiscount = getSaleDiscount(sale);
+			const saleRefund = getSaleRefund(sale);
+
+			yearTax += saleTax;
+			yearDiscounts += saleDiscount;
+			yearRefunds += saleRefund;
+			yearOrderCount += 1;
+
+			// Location
+			const countryCode = sale.paymentMethod?.origin?.country || 'Unknown';
+			if (!yearLocationMap[countryCode]) {
+				yearLocationMap[countryCode] = { revenue: 0, orders: 0 };
+			}
+			yearLocationMap[countryCode].revenue += saleTotal;
+			yearLocationMap[countryCode].orders += 1;
+
+			// Typeface
+			const title = getTypefaceTitle(sale);
+			if (!yearTypefaceMap[title]) {
+				yearTypefaceMap[title] = { title, total: 0, grossTotal: 0, taxTotal: 0, discountTotal: 0, refundTotal: 0, orders: 0 };
+			}
+			yearTypefaceMap[title].total += saleTotal;
+			yearTypefaceMap[title].grossTotal += saleTotal;
+			yearTypefaceMap[title].taxTotal += saleTax;
+			yearTypefaceMap[title].discountTotal += saleDiscount;
+			yearTypefaceMap[title].refundTotal += saleRefund;
+			yearTypefaceMap[title].orders += 1;
+
+			// License
+			const licenseName = getLicenseName(sale);
+			if (!yearLicenseMap[licenseName]) {
+				yearLicenseMap[licenseName] = { name: licenseName, total: 0, grossTotal: 0, taxTotal: 0, discountTotal: 0, refundTotal: 0, orders: 0 };
+			}
+			yearLicenseMap[licenseName].total += saleTotal;
+			yearLicenseMap[licenseName].grossTotal += saleTotal;
+			yearLicenseMap[licenseName].taxTotal += saleTax;
+			yearLicenseMap[licenseName].discountTotal += saleDiscount;
+			yearLicenseMap[licenseName].refundTotal += saleRefund;
+			yearLicenseMap[licenseName].orders += 1;
+		});
+
+		return {
+			yearTax,
+			yearDiscounts,
+			yearRefunds,
+			yearOrderCount,
+			yearLocationData: yearLocationMap,
+			yearTypefaces: Object.values(yearTypefaceMap).sort((a, b) => b.total - a.total),
+			yearLicenseTypes: Object.values(yearLicenseMap).sort((a, b) => b.total - a.total),
+		};
+	}
+
+	const mockSales = [
+		// Month 1
+		[
+			{
+				total: 10000, description: 'Berna (Desktop License)',
+				taxAmounts: [{ amount: 500 }], discountAmounts: [], refunds: [],
+				paymentMethod: { origin: { country: 'US' } },
+			},
+			{
+				total: 5000, description: 'Mckl (Web License)',
+				taxAmounts: [{ amount: 250 }], discountAmounts: [{ amount: 100 }], refunds: [],
+				paymentMethod: { origin: { country: 'GB' } },
+			},
+		],
+		// Month 2
+		[
+			{
+				total: 8000, description: 'Berna (Desktop License)',
+				taxAmounts: [{ amount: 400 }], discountAmounts: [], refunds: [{ adjustedTotal: 200 }],
+				paymentMethod: { origin: { country: 'US' } },
+			},
+			{
+				total: 0, shippingProvision: true, // should be skipped
+			},
+		],
+	];
+
+	test('aggregates year totals correctly', () => {
+		const result = aggregateYearData(mockSales);
+
+		expect(result.yearOrderCount).toBe(3); // 3 non-shipping sales
+		expect(result.yearTax).toBe(1150); // 500 + 250 + 400
+		expect(result.yearDiscounts).toBe(100);
+		expect(result.yearRefunds).toBe(200);
+	});
+
+	test('aggregates location data correctly', () => {
+		const result = aggregateYearData(mockSales);
+
+		expect(result.yearLocationData['US'].revenue).toBe(18000); // 10000 + 8000
+		expect(result.yearLocationData['US'].orders).toBe(2);
+		expect(result.yearLocationData['GB'].revenue).toBe(5000);
+		expect(result.yearLocationData['GB'].orders).toBe(1);
+	});
+
+	test('aggregates typeface data correctly', () => {
+		const result = aggregateYearData(mockSales);
+
+		const berna = result.yearTypefaces.find(t => t.title === 'Berna');
+		expect(berna.total).toBe(18000);
+		expect(berna.orders).toBe(2);
+		expect(berna.taxTotal).toBe(900); // 500 + 400
+		expect(berna.refundTotal).toBe(200);
+
+		const mckl = result.yearTypefaces.find(t => t.title === 'Mckl');
+		expect(mckl.total).toBe(5000);
+		expect(mckl.orders).toBe(1);
+	});
+
+	test('aggregates license type data correctly', () => {
+		const result = aggregateYearData(mockSales);
+
+		const desktop = result.yearLicenseTypes.find(l => l.name === 'Desktop License');
+		expect(desktop.total).toBe(18000);
+		expect(desktop.orders).toBe(2);
+
+		const web = result.yearLicenseTypes.find(l => l.name === 'Web License');
+		expect(web.total).toBe(5000);
+		expect(web.orders).toBe(1);
+	});
+
+	test('skips shipping provisions', () => {
+		const result = aggregateYearData(mockSales);
+		expect(result.yearOrderCount).toBe(3); // shipping sale not counted
+	});
+
+	test('typefaces sorted by total descending', () => {
+		const result = aggregateYearData(mockSales);
+		expect(result.yearTypefaces[0].title).toBe('Berna'); // 18000 > 5000
+		expect(result.yearTypefaces[1].title).toBe('Mckl');
+	});
+});

package/components/Insights.js

@@ -43,89 +43,106 @@ const getCountryName = (code) => {
  * @param {Object} props.locationData - Data about sales by location
  * @returns {JSX.Element} Insights component
  */
-export default function Insights({ 
-	sales = [], 
-	previousSales = [], 
+export default function Insights({
+	sales = [],
+	previousSales = [],
 	loading = false,
 	chartState,
 	date,
-	locationData = {}
+	locationData = {},
+	viewMode = 'month',
+	yearData = null
 }) {
-	if (!sales || !chartState) {
+	const isYearView = viewMode === 'year' && yearData;
+
+	if (!isYearView && (!sales || !chartState)) {
 		return null;
 	}
 
 	// Get month name for display
 	const monthName = new Date(date).toLocaleString("en-US", { timeZone: 'UTC', month: "long" });
 	const year = new Date(date).getUTCFullYear();
-	
-	// NOTE: Values from chartState are transformed in the processChartData function in salesDataProcessing.js
-	// Values from the API are in cents, but processChartData divides them by 100 for display
-	
-	// Net revenue (excluding tax and shipping)
-	const netRevenue = (chartState.salesMax - chartState.taxData.at(-1) - chartState.shippingData.at(-1)) || 0;
-	
-	// Gross revenue (including tax and shipping)
-	const grossRevenue = chartState.salesMax || 0;
-	
-	const taxTotal = chartState.taxData.at(-1) || 0;
-	const shippingTotal = chartState.shippingData.at(-1) || 0;
-	
-	const orderCount = sales.length;
-	const averageOrderValue = orderCount ? netRevenue / orderCount : 0;
-	// Sum all daily discount amounts to get total discounts for the period
-	const discountTotal = chartState.discountLostData.reduce((sum, val) => sum + val, 0) || 0;
-	const discountRate = netRevenue > 0 ? (discountTotal / (netRevenue + discountTotal)) * 100 : 0;
-	const refundTotal = chartState.refundTotal || 0;
-	const refundRate = netRevenue > 0 ? (refundTotal / (netRevenue + refundTotal)) * 100 : 0;
-	
-	// Location data
-	const { 
-		topLocation = 'Unknown', 
-		topLocationPercentage = 0, 
-		previousTopLocation = '',
-		previousTopLocationPercentage = 0,
-		locationChange = null 
-	} = locationData;
-	
-	// Calculate previous period metrics (if available)
-	let previousRevenue = 0;
-	let previousOrderCount = 0;
-	let previousAvgOrderValue = 0;
-	let previousRefundTotal = 0;
+
+	// Compute metrics based on view mode
+	let grossRevenue, netRevenue, orderCount, averageOrderValue, discountTotal, discountRate, refundTotal, refundRate;
+	let topLocation = 'Unknown', topLocationPercentage = 0, locationChange = null;
 	let hasPreviousData = false;
-	
-	if (previousSales && previousSales.length > 0) {
-		hasPreviousData = true;
-		previousOrderCount = previousSales.length;
-		
-		// Important: Raw sale data is in cents, but after applying processChartData, 
-		// the previous period data would be in dollars.
-		// Here we're calculating manually, so we need to convert the values ourselves
-		previousRevenue = previousSales.reduce((sum, sale) => {
-			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
-		}, 0);
-		
-		previousRefundTotal = previousSales.reduce((sum, sale) => {
-			if (sale.refunds && sale.refunds.length > 0) {
-				return sum + sale.refunds.reduce((refundSum, refund) => {
-					return refundSum + (refund.adjustedTotal || 0);
-				}, 0) / 100; // Convert cents to dollars
-			}
-			return sum;
-		}, 0);
-		
-		previousAvgOrderValue = previousOrderCount ? previousRevenue / previousOrderCount : 0;
+	let revenueChange = null, orderCountChange = null, avgOrderValueChange = null, refundChange = null;
+
+	if (isYearView) {
+		// Year view: compute from yearData (values in cents from API)
+		grossRevenue = (yearData.yearTotal || 0) / 100;
+		const yearTax = (yearData.yearTax || 0) / 100;
+		const yearShipping = (yearData.yearShipping || 0) / 100;
+		netRevenue = grossRevenue - yearTax - yearShipping;
+		orderCount = yearData.yearOrderCount || 0;
+		averageOrderValue = orderCount ? netRevenue / orderCount : 0;
+		discountTotal = (yearData.yearDiscounts || 0) / 100;
+		discountRate = netRevenue > 0 ? (discountTotal / (netRevenue + discountTotal)) * 100 : 0;
+		refundTotal = (yearData.yearRefunds || 0) / 100;
+		refundRate = netRevenue > 0 ? (refundTotal / (netRevenue + refundTotal)) * 100 : 0;
+
+		// Derive top location from yearLocationData map
+		if (yearData.yearLocationData) {
+			let maxRevenue = 0;
+			let totalRevenue = 0;
+			Object.entries(yearData.yearLocationData).forEach(([code, data]) => {
+				totalRevenue += data.revenue || 0;
+				if ((data.revenue || 0) > maxRevenue) {
+					maxRevenue = data.revenue;
+					topLocation = code;
+				}
+			});
+			topLocationPercentage = totalRevenue > 0 ? (maxRevenue / totalRevenue) * 100 : 0;
+		}
+	} else {
+		// Month view: existing logic
+		netRevenue = (chartState.salesMax - chartState.taxData.at(-1) - chartState.shippingData.at(-1)) || 0;
+		grossRevenue = chartState.salesMax || 0;
+		orderCount = sales.length;
+		averageOrderValue = orderCount ? netRevenue / orderCount : 0;
+		discountTotal = chartState.discountLostData.reduce((sum, val) => sum + val, 0) || 0;
+		discountRate = netRevenue > 0 ? (discountTotal / (netRevenue + discountTotal)) * 100 : 0;
+		refundTotal = chartState.refundTotal || 0;
+		refundRate = netRevenue > 0 ? (refundTotal / (netRevenue + refundTotal)) * 100 : 0;
+
+		// Location data from month view
+		const locData = locationData || {};
+		topLocation = locData.topLocation || 'Unknown';
+		topLocationPercentage = locData.topLocationPercentage || 0;
+		locationChange = locData.locationChange ?? null;
+
+		// Calculate previous period metrics (if available)
+		let previousRevenue = 0;
+		let previousOrderCount = 0;
+		let previousAvgOrderValue = 0;
+		let previousRefundTotal = 0;
+
+		if (previousSales && previousSales.length > 0) {
+			hasPreviousData = true;
+			previousOrderCount = previousSales.length;
+			previousRevenue = previousSales.reduce((sum, sale) => {
+				const saleTotal = sale.total || 0;
+				const saleTax = sale.taxAmount || 0;
+				const saleShipping = sale.shippingCost || 0;
+				return sum + (saleTotal - saleTax - saleShipping) / 100;
+			}, 0);
+			previousRefundTotal = previousSales.reduce((sum, sale) => {
+				if (sale.refunds && sale.refunds.length > 0) {
+					return sum + sale.refunds.reduce((refundSum, refund) => {
+						return refundSum + (refund.adjustedTotal || 0);
+					}, 0) / 100;
+				}
+				return sum;
+			}, 0);
+			previousAvgOrderValue = previousOrderCount ? previousRevenue / previousOrderCount : 0;
+		}
+
+		revenueChange = calculatePercentageChange(grossRevenue, previousRevenue);
+		orderCountChange = calculatePercentageChange(orderCount, previousOrderCount);
+		avgOrderValueChange = calculatePercentageChange(averageOrderValue, previousAvgOrderValue);
+		refundChange = calculatePercentageChange(refundTotal, previousRefundTotal);
 	}
-	
-	// Calculate period-over-period changes with our utility function
-	const revenueChange = calculatePercentageChange(grossRevenue, previousRevenue);
-	const orderCountChange = calculatePercentageChange(orderCount, previousOrderCount);
-	const avgOrderValueChange = calculatePercentageChange(averageOrderValue, previousAvgOrderValue);
-	const refundChange = calculatePercentageChange(refundTotal, previousRefundTotal);
 		
 	// Helper function to get trend icon
 	const getTrendIcon = (change) => {
@@ -150,21 +167,21 @@ export default function Insights({
 			title: 'Gross Sales',
 			value: formatCurrency(grossRevenue),
 			change: revenueChange,
-			tooltip: hasPreviousData ? `Previous: ${formatCurrency(previousRevenue)}` : 'No prior data available',
+			tooltip: isYearView ? `${year} year total` : hasPreviousData ? 'vs prior month' : 'No prior data available',
 			bgcolor: '#000000',
 		},
 		{
 			title: 'Orders',
 			value: orderCount,
 			change: orderCountChange,
-			tooltip: hasPreviousData ? `Previous: ${previousOrderCount}` : 'No prior data available',
+			tooltip: isYearView ? `${year} year total` : hasPreviousData ? 'vs prior month' : 'No prior data available',
 			bgcolor: '#000000',
 		},
 		{
 			title: 'Avg. Order Value',
 			value: formatCurrency(averageOrderValue),
 			change: avgOrderValueChange,
-			tooltip: hasPreviousData ? `Previous: ${formatCurrency(previousAvgOrderValue)}` : 'No prior data available',
+			tooltip: isYearView ? `${year} year average` : hasPreviousData ? 'vs prior month' : 'No prior data available',
 			bgcolor: '#000000',
 		},
 		{
@@ -184,9 +201,10 @@ export default function Insights({
 			title: 'Top Location',
 			value: topLocation !== 'Unknown' ? `${topLocationPercentage.toFixed(0)}% ${topLocation}` : 'Unknown',
 			change: locationChange,
-			tooltip: previousTopLocation ? 
-				`Previous top location: ${previousTopLocation} (${previousTopLocationPercentage.toFixed(1)}%)` : 
-				'No prior data available',
+			tooltip: isYearView ? `${year} top market` :
+				(locationData?.previousTopLocation ?
+				`Previous: ${locationData.previousTopLocation} (${(locationData.previousTopLocationPercentage || 0).toFixed(1)}%)` :
+				'No prior data available'),
 			bgcolor: '#000000',
 			isLocationCard: true,
 			locationCode: topLocation,

package/components/LicenseTypeList.js

@@ -67,8 +67,8 @@ export default function LicenseTypeList({ licenseTypeData, sales, loading, admin
 					width: '100%',
 					margin: "20px 0 10px",
 					borderRadius: "4px",
-					opacity: !!sales.length ? 1 : 0.25,
-					pointerEvents: !!sales.length ? "" : "none",
+					opacity: !!(sales?.length || licenseTypeData?.length) ? 1 : 0.25,
+					pointerEvents: !!(sales?.length || licenseTypeData?.length) ? "" : "none",
 					border: "1px solid var(--black, black)",
 					'&:hover': { boxShadow: "0 0 8px rgba(0,0,0,0.25)" },
 				}}

package/components/Sales.js

@@ -51,6 +51,11 @@ export default function Sales(props) {
 	const [viewMode, setViewMode] = useState('month'); // 'month' | 'year'
 	const [displayLosses, setDisplayLosses] = useState(false);
 
+	// Year view state
+	const [yearData, setYearData] = useState(null);
+	const [yearLoading, setYearLoading] = useState(false);
+	const [yearError, setYearError] = useState('');
+
 	// Max retry attempts for failed API calls
 	const MAX_RETRIES = 3;
 
@@ -309,6 +314,48 @@ export default function Sales(props) {
 		loadData();
 	}, [designer?.user, designer?.password, designer?.admin, date, enabled]);
 
+	// Fetch year sales data when in year view mode
+	async function fetchYearSales() {
+		if (!designer?.user || !designer?.password || !date) return;
+		setYearLoading(true);
+		setYearError('');
+		try {
+			const response = await fetchWithRetry(
+				'/api/sales-portal/getYearSales',
+				{
+					method: 'POST',
+					headers: { 'Content-Type': 'application/json' },
+					body: JSON.stringify({
+						user: designer?.user,
+						password: designer?.password,
+						year: date.getUTCFullYear(),
+						admin: designer?.admin
+					}),
+				},
+				'Year sales data'
+			);
+			if (!response.ok) throw new Error(`HTTP ${response.status}`);
+			const data = await response.json();
+			if (data.success) {
+				setYearData(data.data);
+			} else {
+				setYearError('Error retrieving year sales data');
+			}
+		} catch (err) {
+			if (err.name !== 'AbortError' && err.message !== 'Failed to fetch') {
+				setYearError('Error retrieving year sales data');
+				console.error(err);
+			}
+		} finally {
+			setYearLoading(false);
+		}
+	}
+
+	useEffect(() => {
+		if (viewMode !== 'year' || !enabled || !date) return;
+		fetchYearSales();
+	}, [viewMode, designer?.user, designer?.password, designer?.admin, date, enabled]);
+
 	// Process sales data
 	useEffect(() => {
 		if (!sales || !date) return;
@@ -551,23 +598,23 @@ export default function Sales(props) {
 						display: "inline-block",
 					}}
 				>
-					<Box 
+					<Box
 						component={"span"}
 						sx={{
-							background: (sales?.reduce((acc, curr) => acc + curr.total, 0) / 100) > 0 ? 'rgba(var(--greenRGB, 0, 255, 0), 0.25)' : "",
+							background: ((viewMode === 'year' ? (yearData?.yearTotal || 0) / 100 : sales?.reduce((acc, curr) => acc + curr.total, 0) / 100)) > 0 ? 'rgba(var(--greenRGB, 0, 255, 0), 0.25)' : "",
 							padding: "5px 10px 0 10px",
 						}}
 					>
-						{sales ? <Box component="span" sx={{ fontVariationSettings: '"wght" 300' }}><Box component="span" sx={{ display: { xs: 'none', md: 'inherit' }, opacity: "0.5" }}>{getCurrencyLabel(sales[0]?.currency)}</Box>{getCurrencySymbol(sales[0]?.currency)} </Box> : ``}
-						{sales ? (
+						{sales ? <Box component="span" sx={{ fontVariationSettings: '"wght" 300' }}><Box component="span" sx={{ display: { xs: 'none', md: 'inherit' }, opacity: "0.5" }}>{getCurrencyLabel(viewMode === 'year' ? yearData?.currency : sales[0]?.currency)}</Box>{getCurrencySymbol(viewMode === 'year' ? yearData?.currency : sales[0]?.currency)} </Box> : ``}
+						{sales || yearData ? (
 							<>
 								<span className={`sales-total`} style={{ fontVariationSettings: '"wght" 900' }}>
-									{(total).toLocaleString('en-US', { minimumFractionDigits: 2 })}
+									{(viewMode === 'year' ? (yearData?.yearTotal || 0) / 100 : total).toLocaleString('en-US', { minimumFractionDigits: 2 })}
 								</span>
 							</>
 						) : `0.00`}
 					</Box>
-					{previousSales && previousSales.length > 0 && revenueChangePercent && (
+					{viewMode !== 'year' && previousSales && previousSales.length > 0 && revenueChangePercent && (
 						<Tooltip 
 							title={`Net Sales (after tax and shipping): ${previousSales && previousSales.length > 0 ? revenueChangePercent.toFixed(1) + '% vs prior month' : 'No prior month data'}`}
 							placement="top"
@@ -814,7 +861,7 @@ export default function Sales(props) {
 				</Box>
 			}
 		</Box>
-	), [loading, sales, total, designer, date, message, revenueChangePercent, previousSales, retryInfo, viewMode]);
+	), [loading, sales, total, designer, date, message, revenueChangePercent, previousSales, retryInfo, viewMode, yearData]);
 
 	return (
 		<LocalizationProvider dateAdapter={AdapterDayjs}>
@@ -841,10 +888,10 @@ export default function Sales(props) {
 					{HeaderSection}
 
 					{/* Sales Data Display */}
-					{!!sales.length && (
+					{!!(sales.length || (viewMode === 'year' && yearData)) && (
 						<>
 							<Box
-								data-disabled={loading}
+								data-disabled={loading || yearLoading}
 								className={`sales-data-section ${styles.salesSection}`}
 								sx={{
 									width: '100%',
@@ -858,7 +905,9 @@ export default function Sales(props) {
 								{viewMode === 'year' && date ? (
 									<Box className="year-overview-wrapper">
 										<YearOverview
-											designer={designer}
+											data={yearData}
+											loading={yearLoading}
+											error={yearError}
 											year={date.getUTCFullYear()}
 											onMonthClick={(monthIndex) => {
 												const newDate = new Date(Date.UTC(date.getUTCFullYear(), monthIndex, 1));
@@ -890,19 +939,21 @@ export default function Sales(props) {
 										chartState={chartState}
 										date={date}
 										locationData={locationData}
+										viewMode={viewMode}
+										yearData={yearData}
 									/>
 								</Box>
 
 								{/* Top Performers Section */}
-								{!!(categories && typefaceData && typefaceData.length) && (
+								{!!(categories && (typefaceData?.length || (viewMode === 'year' && yearData?.yearTypefaces?.length))) && (
 									<Box className="top-performers-wrapper">
 										<TopPerformers
-											typefaceData={typefaceData}
+											typefaceData={viewMode === 'year' ? yearData?.yearTypefaces : typefaceData}
 											designersData={designersData}
-											total={total}
+											total={viewMode === 'year' ? (yearData?.yearTotal || 0) : total}
 											chartState={chartState}
 											sales={sales}
-											loading={loading}
+											loading={viewMode === 'year' ? yearLoading : loading}
 											admin={admin}
 										/>
 									</Box>
@@ -911,9 +962,9 @@ export default function Sales(props) {
 								{/* Typeface List */}
 								<Box className="typeface-list-wrapper">
 									<TypefaceList
-										typefaceData={typefaceData}
+										typefaceData={viewMode === 'year' ? yearData?.yearTypefaces : typefaceData}
 										sales={sales}
-										loading={loading}
+										loading={viewMode === 'year' ? yearLoading : loading}
 										admin={admin}
 									/>
 								</Box>
@@ -921,15 +972,15 @@ export default function Sales(props) {
 								{/* License Type List */}
 								<Box className="license-type-list-wrapper">
 									<LicenseTypeList
-										licenseTypeData={licenseTypeData}
+										licenseTypeData={viewMode === 'year' ? yearData?.yearLicenseTypes : licenseTypeData}
 										sales={sales}
-										loading={loading}
+										loading={viewMode === 'year' ? yearLoading : loading}
 										admin={admin}
 									/>
 								</Box>
 
 								{/* Sales Table Section */}
-								{designer && (
+								{viewMode !== 'year' && designer && (
 									<Box className="sales-table-wrapper">
 										<SalesTable
 											sales={sales}

package/components/TopPerformers.js

@@ -101,8 +101,8 @@ export default function TopPerformers({
 						width: '100%',
 						margin: "20px 0 10px",
 						borderRadius: "4px",
-						opacity: !!sales.length ? 1 : 0.25,
-						pointerEvents: !!sales.length ? "" : "none",
+						opacity: !!(sales?.length || typefaceData?.length) ? 1 : 0.25,
+						pointerEvents: !!(sales?.length || typefaceData?.length) ? "" : "none",
 						border: "1px solid var(--black, black)",
 						'&:hover': { boxShadow: "0 0 8px rgba(0,0,0,0.25)" },
 					}}
@@ -234,8 +234,8 @@ export default function TopPerformers({
 						width: '100%',
 						margin: "20px 0 10px",
 						borderRadius: "4px",
-						opacity: !!sales.length ? 1 : 0.25,
-						pointerEvents: !!sales.length ? "" : "none",
+						opacity: !!(sales?.length || typefaceData?.length) ? 1 : 0.25,
+						pointerEvents: !!(sales?.length || typefaceData?.length) ? "" : "none",
 						border: "1px solid var(--black, black)",
 
 						'&:hover': { boxShadow: "0 0 8px rgba(0,0,0,0.25)" },

package/components/TypefaceList.js

@@ -55,8 +55,8 @@ export default function TypefaceList({ typefaceData, sales, loading, admin }) {
 					width: '100%',
 					margin: "20px 0 10px",
 					borderRadius: "4px",
-					opacity: !!sales.length ? 1 : 0.25,
-					pointerEvents: !!sales.length ? "" : "none",
+					opacity: !!(sales?.length || typefaceData?.length) ? 1 : 0.25,
+					pointerEvents: !!(sales?.length || typefaceData?.length) ? "" : "none",
 					border: "1px solid var(--black, black)",
 					'&:hover': { boxShadow: "0 0 8px rgba(0,0,0,0.25)" },
 				}}

package/components/YearOverview.js

@@ -1,5 +1,5 @@
 // Year overview component showing 12-month stacked bar chart by typeface
-import React, { useState, useEffect, useMemo } from 'react';
+import React, { useMemo } from 'react';
 import { Box, Typography, CircularProgress, Tooltip } from '@mui/material';
 import { ResponsiveChartContainer } from '@mui/x-charts/ResponsiveChartContainer';
 import { BarPlot } from '@mui/x-charts/BarChart';
@@ -34,38 +34,7 @@ const COLORS = [
  * @param {number} props.year - Year to display
  * @param {Function} props.onMonthClick - Called when a bar is clicked, receives month index
  */
-export default function YearOverview({ designer, year, onMonthClick }) {
-	const [data, setData] = useState(null);
-	const [loading, setLoading] = useState(false);
-	const [error, setError] = useState('');
-
-	useEffect(() => {
-		if (!designer?.user || !designer?.password || !year) return;
-
-		setLoading(true);
-		setError('');
-
-		fetch('/api/sales-portal/getYearSales', {
-			method: 'POST',
-			headers: { 'Content-Type': 'application/json' },
-			body: JSON.stringify({
-				user: designer.user,
-				password: designer.password,
-				year,
-				admin: designer.admin || false,
-			}),
-		})
-			.then(res => res.json())
-			.then(res => {
-				if (res.success) {
-					setData(res.data);
-				} else {
-					setError(res.message || 'Failed to load year data');
-				}
-			})
-			.catch(err => setError(err.message))
-			.finally(() => setLoading(false));
-	}, [designer?.user, designer?.password, designer?.admin, year]);
+export default function YearOverview({ data, loading = false, error = '', year, onMonthClick }) {
 
 	// Build chart series from typeface data
 	const { series, xAxisData, topTypefaces } = useMemo(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@liiift-studio/sales-portal",
-	"version": "3.1.3",
+	"version": "3.1.4",
 	"description": "Centralized sales portal package for Liiift Studio projects",
 	"main": "index.js",
 	"types": "index.d.ts",