@classytic/ledger 0.2.0 → 0.4.0

package/dist/{fiscal-close-L631E3De.mjs → fiscal-close-DmPV82e4.mjs}

@@ -1,10 +1,189 @@
-import { n as Errors } from "./errors-B7yC-Jfw.mjs";
-import { i as requireOrgScope, n as finalizeSession, r as defaultLogger, t as acquireSession } from "./session-Ba8E3Ufa.mjs";
-import { i as extractMainType } from "./categories-CclX7Q94.mjs";
+import { n as Errors } from "./errors-BoGUSUYL.mjs";
+import { t as requireOrgScope } from "./tenant-guard-CAxXoWuS.mjs";
+import { i as extractMainType } from "./categories-FJlrvzcl.mjs";
+import mongoose from "mongoose";
+//#region src/reports/aged-balance.ts
+const DEFAULT_BUCKETS = [
+	{
+		label: "Current",
+		minDays: 0,
+		maxDays: 31
+	},
+	{
+		label: "31-60",
+		minDays: 31,
+		maxDays: 61
+	},
+	{
+		label: "61-90",
+		minDays: 61,
+		maxDays: 91
+	},
+	{
+		label: "90+",
+		minDays: 91,
+		maxDays: Infinity
+	}
+];
+async function generateAgedBalance(opts, params) {
+	const { AccountModel, JournalEntryModel, country, orgField } = opts;
+	requireOrgScope(orgField, params.organizationId);
+	const asOfDate = params.asOfDate ?? /* @__PURE__ */ new Date();
+	const buckets = params.buckets ?? DEFAULT_BUCKETS;
+	const bucketLabels = buckets.map((b) => b.label);
+	const dueDateField = params.dueDateField ?? "journalItems.dueDate";
+	const contactField = params.contactField;
+	const accountQuery = { active: true };
+	if (orgField && params.organizationId) accountQuery[orgField] = params.organizationId;
+	let targetAccountIds;
+	if (params.accountIds && params.accountIds.length > 0) targetAccountIds = params.accountIds;
+	else {
+		const allAccounts = await AccountModel.find(accountQuery).lean();
+		const categoryPrefix = params.type === "receivable" ? "Balance Sheet-Asset" : "Balance Sheet-Liability";
+		targetAccountIds = allAccounts.filter((a) => {
+			const at = country.getAccountType(a.accountTypeCode);
+			return at && !at.isGroup && at.category.startsWith(categoryPrefix);
+		}).map((a) => a._id);
+	}
+	if (targetAccountIds.length === 0) return {
+		metadata: {
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			asOfDate: asOfDate.toISOString().split("T")[0],
+			type: params.type
+		},
+		bucketLabels,
+		rows: [],
+		totals: Object.fromEntries(bucketLabels.map((l) => [l, 0])),
+		grandTotal: 0
+	};
+	const allAccounts = await AccountModel.find(accountQuery).lean();
+	const accountLookup = new Map(allAccounts.map((a) => [String(a._id), a]));
+	const baseMatch = {
+		state: "posted",
+		date: { $lte: asOfDate }
+	};
+	if (orgField && params.organizationId) baseMatch[orgField] = params.organizationId;
+	asOfDate.getTime();
+	const groupId = { account: "$journalItems.account" };
+	if (contactField) groupId.contact = `$${contactField}`;
+	const bucketBranches = buckets.map((b) => {
+		return {
+			case: b.maxDays === Infinity ? { $gte: ["$daysPastDue", b.minDays] } : { $and: [{ $gte: ["$daysPastDue", b.minDays] }, { $lt: ["$daysPastDue", b.maxDays] }] },
+			then: b.label
+		};
+	});
+	const pipeline = [
+		{ $match: baseMatch },
+		{ $unwind: "$journalItems" },
+		{ $match: { "journalItems.account": { $in: targetAccountIds } } },
+		{ $addFields: { daysPastDue: { $floor: { $divide: [{ $subtract: [asOfDate, { $ifNull: [`$${dueDateField}`, asOfDate] }] }, 1e3 * 60 * 60 * 24] } } } },
+		{ $addFields: { daysPastDue: { $max: ["$daysPastDue", 0] } } },
+		{ $addFields: { bucketLabel: { $switch: {
+			branches: bucketBranches,
+			default: bucketLabels[bucketLabels.length - 1]
+		} } } },
+		{ $addFields: { netAmount: params.type === "receivable" ? { $subtract: ["$journalItems.debit", "$journalItems.credit"] } : { $subtract: ["$journalItems.credit", "$journalItems.debit"] } } },
+		{ $group: {
+			_id: {
+				...groupId,
+				bucket: "$bucketLabel"
+			},
+			amount: { $sum: "$netAmount" }
+		} }
+	];
+	const results = await JournalEntryModel.aggregate(pipeline);
+	const rowKey = (accountId, contactId) => contactField ? `${String(accountId)}::${String(contactId ?? "")}` : String(accountId);
+	const rowMap = /* @__PURE__ */ new Map();
+	for (const r of results) {
+		const key = rowKey(r._id.account, r._id.contact);
+		if (!rowMap.has(key)) {
+			const acc = accountLookup.get(String(r._id.account));
+			rowMap.set(key, {
+				accountId: r._id.account,
+				accountName: acc?.name ?? "",
+				accountCode: acc?.accountNumber ?? "",
+				...contactField ? { contactId: r._id.contact } : {},
+				total: 0,
+				buckets: Object.fromEntries(bucketLabels.map((l) => [l, 0]))
+			});
+		}
+		const row = rowMap.get(key);
+		if (row.buckets[r._id.bucket] !== void 0) row.buckets[r._id.bucket] += r.amount;
+		row.total += r.amount;
+	}
+	const rows = Array.from(rowMap.values()).sort((a, b) => a.accountCode.localeCompare(b.accountCode, void 0, { numeric: true }));
+	const totals = Object.fromEntries(bucketLabels.map((l) => [l, 0]));
+	let grandTotal = 0;
+	for (const row of rows) {
+		for (const label of bucketLabels) totals[label] += row.buckets[label];
+		grandTotal += row.total;
+	}
+	return {
+		metadata: {
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			asOfDate: asOfDate.toISOString().split("T")[0],
+			type: params.type
+		},
+		bucketLabels,
+		rows,
+		totals,
+		grandTotal
+	};
+}
+//#endregion
+//#region src/utils/account-helpers.ts
+/**
+* Account Helper Utilities
+*/
+/**
+* Check if an account type is a virtual tax sub-account.
+* Returns true if the account's parent has `isVirtualTotal: true`.
+* Works for any country pack — no code format assumptions.
+*/
+function isVirtualTaxAccount(accountType, accountMap) {
+	if (!accountType.parentCode) return false;
+	return accountMap.get(accountType.parentCode)?.isVirtualTotal === true;
+}
+/**
+* Calculate a total from sub-accounts using the totalAccountTypes formula.
+* @param formula - Array of { account, operation } instructions
+* @param balanceMap - Map of account code → balance
+*/
+function calculateTotal(formula, balanceMap) {
+	let total = 0;
+	for (const item of formula) {
+		const balance = balanceMap.get(item.account) ?? 0;
+		total += item.operation === "+" ? balance : -balance;
+	}
+	return total;
+}
+/**
+* Compute the ending balance for an account given its debits and credits.
+* Uses the account's main type to determine normal balance direction.
+*
+* Assets & Expenses: debit - credit
+* Liabilities, Equity & Income: credit - debit
+*/
+function computeEndingBalance(category, totalDebit, totalCredit) {
+	const mainType = extractMainType(category);
+	if (mainType === "Asset" || mainType === "Expense") return totalDebit - totalCredit;
+	return totalCredit - totalDebit;
+}
+/**
+* Build a lookup map from an array of account types.
+*/
+function buildAccountTypeMap(accountTypes) {
+	const map = /* @__PURE__ */ new Map();
+	for (const at of accountTypes) map.set(at.code, at);
+	return map;
+}
+//#endregion
 //#region src/utils/date-range.ts
 /**
 * Compute start/end dates from a date option + value.
 *
+* @throws {Error} If value is null/undefined/invalid for the given option
+*
 * Examples:
 *   getDateRange('month', '2025-03')            → Mar 1 – Mar 31
 *   getDateRange('quarter', { quarter: 2, year: 2025 }) → Apr 1 – Jun 30
@@ -12,6 +191,7 @@ import { i as extractMainType } from "./categories-CclX7Q94.mjs";
 *   getDateRange('custom', { startDate, endDate })
 */
 function getDateRange(option, value) {
+	if (value == null && (option === "month" || option === "quarter" || option === "year" || option === "custom")) throw new Error(`dateValue is required for dateOption "${option}"`);
 	switch (option) {
 		case "month": {
 			let year;
@@ -22,16 +202,21 @@ function getDateRange(option, value) {
 				month = parseInt(match[2], 10) - 1;
 			} else {
 				const date = new Date(value);
+				if (Number.isNaN(date.getTime())) throw new Error(`Invalid month value: ${String(value)}`);
 				year = date.getFullYear();
 				month = date.getMonth();
 			}
+			if (year < 1900 || year > 9999) throw new Error(`Year ${year} is out of valid range (1900–9999)`);
 			return {
 				startDate: new Date(year, month, 1),
 				endDate: new Date(year, month + 1, 0, 23, 59, 59, 999)
 			};
 		}
 		case "quarter": {
+			if (typeof value !== "object" || value === null) throw new Error("Quarter dateValue must be an object with { quarter, year }");
 			const { quarter, year } = value;
+			if (!Number.isInteger(quarter) || quarter < 1 || quarter > 4) throw new Error(`Invalid quarter: ${quarter}. Must be 1–4.`);
+			if (!Number.isInteger(year) || year < 1900 || year > 9999) throw new Error(`Invalid year: ${year}. Must be 1900–9999.`);
 			const startMonth = (quarter - 1) * 3;
 			return {
 				startDate: new Date(year, startMonth, 1),
@@ -40,17 +225,23 @@ function getDateRange(option, value) {
 		}
 		case "year": {
 			const year = typeof value === "number" ? value : parseInt(String(value), 10);
+			if (Number.isNaN(year) || year < 1900 || year > 9999) throw new Error(`Invalid year: ${String(value)}. Must be a number between 1900–9999.`);
 			return {
 				startDate: new Date(year, 0, 1),
 				endDate: new Date(year, 11, 31, 23, 59, 59, 999)
 			};
 		}
 		case "custom": {
-			const { startDate, endDate } = value;
-			const end = new Date(endDate);
+			if (typeof value !== "object" || value === null) throw new Error("Custom dateValue must be an object with { startDate, endDate }");
+			const { startDate: rawStart, endDate: rawEnd } = value;
+			if (!rawStart || !rawEnd) throw new Error("Custom date range requires both startDate and endDate");
+			const start = new Date(rawStart);
+			const end = new Date(rawEnd);
+			if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) throw new Error("Custom date range contains invalid dates");
+			if (start > end) throw new Error("startDate must be before endDate");
 			if (end.getHours() === 0 && end.getMinutes() === 0 && end.getSeconds() === 0 && end.getMilliseconds() === 0) end.setHours(23, 59, 59, 999);
 			return {
-				startDate: new Date(startDate),
+				startDate: start,
 				endDate: end
 			};
 		}
@@ -107,154 +298,9 @@ function buildItemFilters(filters) {
 	return result;
 }
 //#endregion
-//#region src/reports/trial-balance.ts
-async function generateTrialBalance(opts, params) {
-	const { AccountModel, JournalEntryModel, country, orgField, fiscalYearStartMonth = 1 } = opts;
-	requireOrgScope(orgField, params.organizationId);
-	const { startDate, endDate } = getDateRange(params.dateOption, params.dateValue);
-	const fiscalYearStart = getFiscalYearStart(startDate, fiscalYearStartMonth);
-	const itemFilters = buildItemFilters(params.filters);
-	const accountQuery = { active: true };
-	if (orgField && params.organizationId) accountQuery[orgField] = params.organizationId;
-	const allAccounts = await AccountModel.find(accountQuery).lean();
-	const bsIds = [];
-	const isIds = [];
-	for (const acc of allAccounts) {
-		const at = country.getAccountType(acc.accountTypeCode);
-		if (!at || at.isGroup) continue;
-		if (at.category.startsWith("Balance Sheet")) bsIds.push(acc._id);
-		else if (at.category.startsWith("Income Statement")) isIds.push(acc._id);
-	}
-	const baseMatch = { state: "posted" };
-	if (orgField && params.organizationId) baseMatch[orgField] = params.organizationId;
-	const accountFilter = params.accountId ? { "journalItems.account": params.accountId } : {};
-	const buildPipeline = (ids, dateFrom, dateTo) => [
-		{ $match: {
-			...baseMatch,
-			date: {
-				$gte: dateFrom,
-				$lt: dateTo
-			}
-		} },
-		{ $unwind: "$journalItems" },
-		{ $match: {
-			"journalItems.account": { $in: ids },
-			...accountFilter,
-			...itemFilters
-		} },
-		{ $group: {
-			_id: "$journalItems.account",
-			d: { $sum: "$journalItems.debit" },
-			c: { $sum: "$journalItems.credit" }
-		} }
-	];
-	const [bsInitial, isInitial, current] = await Promise.all([
-		bsIds.length ? JournalEntryModel.aggregate(buildPipeline(bsIds, /* @__PURE__ */ new Date(0), startDate)) : [],
-		isIds.length ? JournalEntryModel.aggregate(buildPipeline(isIds, fiscalYearStart, startDate)) : [],
-		JournalEntryModel.aggregate(buildPipeline([...bsIds, ...isIds], startDate, new Date(endDate.getTime() + 1)))
-	]);
-	const map = /* @__PURE__ */ new Map();
-	for (const r of [...bsInitial, ...isInitial]) {
-		const key = String(r._id);
-		map.set(key, {
-			iD: r.d,
-			iC: r.c,
-			cD: 0,
-			cC: 0
-		});
-	}
-	for (const r of current) {
-		const key = String(r._id);
-		const existing = map.get(key) ?? {
-			iD: 0,
-			iC: 0,
-			cD: 0,
-			cC: 0
-		};
-		existing.cD = r.d;
-		existing.cC = r.c;
-		map.set(key, existing);
-	}
-	const accountLookup = new Map(allAccounts.map((a) => [String(a._id), a]));
-	const rows = [];
-	for (const [id, bal] of map) {
-		const acc = accountLookup.get(id);
-		const net = bal.iD + bal.cD - (bal.iC + bal.cC);
-		rows.push({
-			account: acc ?? id,
-			initial: {
-				debit: bal.iD,
-				credit: bal.iC
-			},
-			current: {
-				debit: bal.cD,
-				credit: bal.cC
-			},
-			ending: net >= 0 ? {
-				debit: net,
-				credit: 0
-			} : {
-				debit: 0,
-				credit: Math.abs(net)
-			}
-		});
-	}
-	return {
-		rows,
-		period: {
-			startDate,
-			endDate
-		}
-	};
-}
-//#endregion
-//#region src/utils/account-helpers.ts
-/**
-* Check if an account type is a virtual tax sub-account.
-* Returns true if the account's parent has `isVirtualTotal: true`.
-* Works for any country pack — no code format assumptions.
-*/
-function isVirtualTaxAccount(accountType, accountMap) {
-	if (!accountType.parentCode) return false;
-	return accountMap.get(accountType.parentCode)?.isVirtualTotal === true;
-}
-/**
-* Calculate a total from sub-accounts using the totalAccountTypes formula.
-* @param formula - Array of { account, operation } instructions
-* @param balanceMap - Map of account code → balance
-*/
-function calculateTotal(formula, balanceMap) {
-	let total = 0;
-	for (const item of formula) {
-		const balance = balanceMap.get(item.account) ?? 0;
-		total += item.operation === "+" ? balance : -balance;
-	}
-	return total;
-}
-/**
-* Compute the ending balance for an account given its debits and credits.
-* Uses the account's main type to determine normal balance direction.
-*
-* Assets & Expenses: debit - credit
-* Liabilities, Equity & Income: credit - debit
-*/
-function computeEndingBalance(category, totalDebit, totalCredit) {
-	const mainType = extractMainType(category);
-	if (mainType === "Asset" || mainType === "Expense") return totalDebit - totalCredit;
-	return totalCredit - totalDebit;
-}
-/**
-* Build a lookup map from an array of account types.
-*/
-function buildAccountTypeMap(accountTypes) {
-	const map = /* @__PURE__ */ new Map();
-	for (const at of accountTypes) map.set(at.code, at);
-	return map;
-}
-//#endregion
 //#region src/reports/balance-sheet.ts
 async function generateBalanceSheet(opts, params) {
-	const { AccountModel, JournalEntryModel, country, orgField, fiscalYearStartMonth = 1, retainedEarningsCode = country.retainedEarningsCode ?? "3660", currentYearEarningsCode = country.currentYearEarningsCode ?? "3680" } = opts;
+	const { AccountModel, JournalEntryModel, country, orgField, fiscalYearStartMonth = 1, retainedEarningsAccountCode = country.retainedEarningsAccountCode, retainedEarningsDisplayCode = country.retainedEarningsDisplayCode ?? retainedEarningsAccountCode, currentYearEarningsCode = country.currentYearEarningsCode ?? "3680" } = opts;
 	requireOrgScope(orgField, params.organizationId);
 	const { endDate } = getDateRange(params.dateOption, params.dateValue);
 	const fiscalYearStart = getFiscalYearStart(endDate, fiscalYearStartMonth);
@@ -266,13 +312,15 @@ async function generateBalanceSheet(opts, params) {
 		const at = country.getAccountType(a.accountTypeCode);
 		return at && !at.isGroup && at.category.startsWith("Balance Sheet");
 	}).map((a) => a._id);
+	const reAccountIds = retainedEarningsAccountCode ? allAccounts.filter((a) => a.accountTypeCode === retainedEarningsAccountCode).map((a) => a._id) : [];
+	const reAccountIdSet = new Set(reAccountIds.map(String));
 	const isIds = allAccounts.filter((a) => {
 		const at = country.getAccountType(a.accountTypeCode);
 		return at && !at.isGroup && !at.isTotal && at.category.startsWith("Income Statement");
 	}).map((a) => a._id);
 	const baseMatch = { state: "posted" };
 	if (orgField && params.organizationId) baseMatch[orgField] = params.organizationId;
-	const [bsResults, netIncomeResults, priorRetainedResults] = await Promise.all([
+	const [bsResults, netIncomeResults, priorRetainedResults, reAccountResults] = await Promise.all([
 		JournalEntryModel.aggregate([
 			{ $match: {
 				...baseMatch,
@@ -323,10 +371,27 @@ async function generateBalanceSheet(opts, params) {
 				d: { $sum: "$journalItems.debit" },
 				c: { $sum: "$journalItems.credit" }
 			} }
-		])
+		]),
+		...reAccountIds.length > 0 ? [JournalEntryModel.aggregate([
+			{ $match: {
+				...baseMatch,
+				date: { $lte: endDate }
+			} },
+			{ $unwind: "$journalItems" },
+			{ $match: {
+				"journalItems.account": { $in: reAccountIds },
+				...itemFilters
+			} },
+			{ $group: {
+				_id: null,
+				d: { $sum: "$journalItems.debit" },
+				c: { $sum: "$journalItems.credit" }
+			} }
+		])] : [Promise.resolve([])]
 	]);
 	const netIncome = netIncomeResults.length > 0 ? netIncomeResults[0].c - netIncomeResults[0].d : 0;
-	const priorRetained = priorRetainedResults.length > 0 ? priorRetainedResults[0].c - priorRetainedResults[0].d : 0;
+	const priorUnclosedPL = priorRetainedResults.length > 0 ? priorRetainedResults[0].c - priorRetainedResults[0].d : 0;
+	const priorRetained = (reAccountResults.length > 0 ? reAccountResults[0].c - reAccountResults[0].d : 0) + priorUnclosedPL;
 	const accountMap = new Map(allAccounts.map((a) => [String(a._id), a]));
 	const accountTypeMap = buildAccountTypeMap(country.accountTypes);
 	const balanceMap = /* @__PURE__ */ new Map();
@@ -354,6 +419,7 @@ async function generateBalanceSheet(opts, params) {
 	for (const r of bsResults) {
 		const acc = accountMap.get(String(r._id));
 		if (!acc) continue;
+		if (reAccountIdSet.has(String(r._id))) continue;
 		const at = country.getAccountType(acc.accountTypeCode);
 		if (!at) continue;
 		const mainType = extractMainType(at.category) ?? "Asset";
@@ -382,7 +448,7 @@ async function generateBalanceSheet(opts, params) {
 		accounts: [{
 			id: "prior-retained",
 			name: "Previous Years Retained Earnings",
-			code: retainedEarningsCode,
+			code: retainedEarningsDisplayCode ?? retainedEarningsAccountCode ?? "",
 			balance: priorRetained
 		}, {
 			id: "current-year",
@@ -397,13 +463,24 @@ async function generateBalanceSheet(opts, params) {
 		groupsMap.Equity[reGroup.name].accounts.push(...reGroup.accounts);
 		groupsMap.Equity[reGroup.name].total += reGroup.total;
 	}
+	const sortAccountsInGroups = (groups) => {
+		for (const g of Object.values(groups)) g.accounts.sort((a, b) => (a.code ?? "").localeCompare(b.code ?? "", void 0, { numeric: true }));
+	};
+	sortAccountsInGroups(groupsMap.Asset);
+	sortAccountsInGroups(groupsMap.Liability);
+	sortAccountsInGroups(groupsMap.Equity);
+	const sortGroupsByCode = (groups) => groups.sort((a, b) => {
+		const codeA = a.accounts[0]?.code ?? "";
+		const codeB = b.accounts[0]?.code ?? "";
+		return codeA.localeCompare(codeB, void 0, { numeric: true });
+	});
 	const pruneGroups = (groups) => Object.values(groups).map((g) => ({
 		...g,
 		accounts: g.accounts.filter((a) => a.balance !== 0 || a.isTotal || a.isCalculated)
 	})).filter((g) => g.accounts.length > 0 || g.total !== 0);
-	assets.groups = pruneGroups(groupsMap.Asset);
-	liabilities.groups = pruneGroups(groupsMap.Liability);
-	equity.groups = Object.values(groupsMap.Equity);
+	assets.groups = sortGroupsByCode(pruneGroups(groupsMap.Asset));
+	liabilities.groups = sortGroupsByCode(pruneGroups(groupsMap.Liability));
+	equity.groups = sortGroupsByCode(Object.values(groupsMap.Equity));
 	assets.total = assets.groups.reduce((s, g) => s + g.total, 0);
 	liabilities.total = liabilities.groups.reduce((s, g) => s + g.total, 0);
 	equity.total = equity.groups.reduce((s, g) => s + g.total, 0);
@@ -433,19 +510,41 @@ async function generateBalanceSheet(opts, params) {
 	};
 }
 //#endregion
-//#region src/reports/income-statement.ts
-async function generateIncomeStatement(opts, params) {
-	const { AccountModel, JournalEntryModel, country, orgField } = opts;
+//#region src/reports/budget-vs-actual.ts
+async function generateBudgetVsActual(opts, params) {
+	const { AccountModel, JournalEntryModel, BudgetModel, country, orgField } = opts;
 	requireOrgScope(orgField, params.organizationId);
 	const { startDate, endDate } = getDateRange(params.dateOption, params.dateValue);
-	const itemFilters = buildItemFilters(params.filters);
-	const q = { active: true };
-	if (orgField && params.organizationId) q[orgField] = params.organizationId;
-	const allAccounts = await AccountModel.find(q).lean();
-	const isIds = allAccounts.filter((a) => {
-		const at = country.getAccountType(a.accountTypeCode);
-		return at && !at.isGroup && !at.isTotal && at.category.startsWith("Income Statement");
-	}).map((a) => a._id);
+	const budgetQuery = {
+		periodStart: { $lte: endDate },
+		periodEnd: { $gte: startDate }
+	};
+	if (orgField && params.organizationId) budgetQuery[orgField] = params.organizationId;
+	if (params.accountIds && params.accountIds.length > 0) budgetQuery.account = { $in: params.accountIds };
+	const budgets = await BudgetModel.find(budgetQuery).lean();
+	if (budgets.length === 0) return {
+		metadata: {
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			periodStart: startDate.toISOString(),
+			periodEnd: endDate.toISOString()
+		},
+		rows: [],
+		summary: {
+			totalBudget: 0,
+			totalActual: 0,
+			totalVariance: 0
+		}
+	};
+	const budgetByAccount = /* @__PURE__ */ new Map();
+	for (const b of budgets) {
+		const key = String(b.account);
+		budgetByAccount.set(key, (budgetByAccount.get(key) ?? 0) + b.amount);
+	}
+	const accountIds = [...budgetByAccount.keys()];
+	const accountQuery = { _id: { $in: accountIds } };
+	if (orgField && params.organizationId) accountQuery[orgField] = params.organizationId;
+	const accounts = await AccountModel.find(accountQuery).lean();
+	const accountMap = new Map(accounts.map((a) => [String(a._id), a]));
 	const baseMatch = {
 		state: "posted",
 		date: {
@@ -454,11 +553,105 @@ async function generateIncomeStatement(opts, params) {
 		}
 	};
 	if (orgField && params.organizationId) baseMatch[orgField] = params.organizationId;
-	const results = await JournalEntryModel.aggregate([
+	const pipeline = [
+		{ $match: baseMatch },
+		{ $unwind: "$journalItems" },
+		{ $match: { "journalItems.account": { $in: accountIds.map((id) => new mongoose.Types.ObjectId(id)) } } },
+		{ $group: {
+			_id: "$journalItems.account",
+			totalDebit: { $sum: "$journalItems.debit" },
+			totalCredit: { $sum: "$journalItems.credit" }
+		} }
+	];
+	const actuals = await JournalEntryModel.aggregate(pipeline);
+	const actualByAccount = /* @__PURE__ */ new Map();
+	for (const a of actuals) actualByAccount.set(String(a._id), {
+		debit: a.totalDebit,
+		credit: a.totalCredit
+	});
+	const rows = [];
+	for (const [accountId, budgetAmount] of budgetByAccount) {
+		const acc = accountMap.get(accountId);
+		if (!acc) continue;
+		const at = country.getAccountType(acc.accountTypeCode);
+		if (!at || at.isGroup) continue;
+		const actual = actualByAccount.get(accountId) ?? {
+			debit: 0,
+			credit: 0
+		};
+		const mainType = extractMainType(at.category);
+		let actualAmount;
+		if (mainType === "Income") actualAmount = actual.credit - actual.debit;
+		else if (mainType === "Expense") actualAmount = actual.debit - actual.credit;
+		else if (mainType === "Asset") actualAmount = actual.debit - actual.credit;
+		else actualAmount = actual.credit - actual.debit;
+		const variance = actualAmount - budgetAmount;
+		const variancePercent = budgetAmount !== 0 ? Math.round(variance / budgetAmount * 1e4) / 100 : 0;
+		rows.push({
+			accountId: acc._id,
+			accountName: acc.name,
+			accountCode: acc.accountNumber,
+			category: at.category,
+			budgetAmount,
+			actualAmount,
+			variance,
+			variancePercent
+		});
+	}
+	rows.sort((a, b) => a.accountCode.localeCompare(b.accountCode));
+	const summary = {
+		totalBudget: rows.reduce((s, r) => s + r.budgetAmount, 0),
+		totalActual: rows.reduce((s, r) => s + r.actualAmount, 0),
+		totalVariance: rows.reduce((s, r) => s + r.variance, 0)
+	};
+	return {
+		metadata: {
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			periodStart: startDate.toISOString(),
+			periodEnd: endDate.toISOString()
+		},
+		rows,
+		summary
+	};
+}
+//#endregion
+//#region src/reports/cash-flow.ts
+async function generateCashFlow(opts, params) {
+	const { AccountModel, JournalEntryModel, country, orgField } = opts;
+	requireOrgScope(orgField, params.organizationId);
+	const { startDate, endDate } = getDateRange(params.dateOption, params.dateValue);
+	const itemFilters = buildItemFilters(params.filters);
+	const q = { active: true };
+	if (orgField && params.organizationId) q[orgField] = params.organizationId;
+	const allAccounts = await AccountModel.find(q).lean();
+	const accountCfMap = /* @__PURE__ */ new Map();
+	const accountMap = new Map(allAccounts.map((a) => [String(a._id), a]));
+	const cfAccountIds = [];
+	for (const acc of allAccounts) {
+		const at = country.getAccountType(acc.accountTypeCode);
+		if (!at || at.isGroup || at.isTotal) continue;
+		const cf = at.cashFlowCategory;
+		if (!cf) continue;
+		const normalized = cf.charAt(0).toUpperCase() + cf.slice(1);
+		accountCfMap.set(String(acc._id), {
+			category: at.category,
+			cfCategory: normalized
+		});
+		cfAccountIds.push(acc._id);
+	}
+	const baseMatch = {
+		state: "posted",
+		date: {
+			$gte: startDate,
+			$lte: endDate
+		}
+	};
+	if (orgField && params.organizationId) baseMatch[orgField] = params.organizationId;
+	const results = cfAccountIds.length > 0 ? await JournalEntryModel.aggregate([
 		{ $match: baseMatch },
 		{ $unwind: "$journalItems" },
 		{ $match: {
-			"journalItems.account": { $in: isIds },
+			"journalItems.account": { $in: cfAccountIds },
 			...itemFilters
 		} },
 		{ $group: {
@@ -466,65 +659,38 @@ async function generateIncomeStatement(opts, params) {
 			d: { $sum: "$journalItems.debit" },
 			c: { $sum: "$journalItems.credit" }
 		} }
-	]);
-	const accountMap = new Map(allAccounts.map((a) => [String(a._id), a]));
-	const revenueGroups = {};
-	const expenseGroups = {};
-	const resolveGroupName = (at) => {
-		const visited = /* @__PURE__ */ new Set();
-		let current = at.parentCode ? country.getAccountType(at.parentCode) : void 0;
-		while (current && !visited.has(current.code)) {
-			if (current.isGroup) return current.name;
-			visited.add(current.code);
-			current = current.parentCode ? country.getAccountType(current.parentCode) : void 0;
+	]) : [];
+	const flows = {
+		Operating: {
+			total: 0,
+			accounts: []
+		},
+		Investing: {
+			total: 0,
+			accounts: []
+		},
+		Financing: {
+			total: 0,
+			accounts: []
 		}
-		return at.name;
 	};
 	for (const r of results) {
-		const acc = accountMap.get(String(r._id));
-		if (!acc) continue;
-		const at = country.getAccountType(acc.accountTypeCode);
-		if (!at) continue;
-		const mainType = extractMainType(at.category);
-		const netAmount = mainType === "Income" ? r.c - r.d : r.d - r.c;
-		if (netAmount === 0) continue;
-		const groupName = resolveGroupName(at);
-		const groups = mainType === "Income" ? revenueGroups : expenseGroups;
-		if (!(groupName in groups)) groups[groupName] = {
-			name: groupName,
-			total: 0,
-			accounts: []
-		};
-		groups[groupName].accounts.push({
-			id: acc._id,
-			name: acc.name ?? at.name,
-			code: acc.accountNumber ?? at.code,
-			balance: netAmount
+		const accIdStr = String(r._id);
+		const meta = accountCfMap.get(accIdStr);
+		if (!meta) continue;
+		const amount = computeEndingBalance(meta.category, r.d, r.c);
+		const acc = accountMap.get(accIdStr);
+		const at = country.getAccountType(acc?.accountTypeCode);
+		flows[meta.cfCategory].accounts.push({
+			name: acc?.name ?? at?.name ?? "",
+			code: acc?.accountNumber ?? at?.code ?? "",
+			amount
 		});
-		groups[groupName].total += netAmount;
+		flows[meta.cfCategory].total += amount;
 	}
-	const labels = country.reportLabels ?? {};
-	const revenue = {
-		name: labels.revenue ?? "Revenue",
-		total: Object.values(revenueGroups).reduce((s, g) => s + g.total, 0),
-		groups: Object.values(revenueGroups)
-	};
-	const expenses = {
-		name: labels.expenses ?? "Expenses",
-		total: Object.values(expenseGroups).reduce((s, g) => s + g.total, 0),
-		groups: Object.values(expenseGroups)
-	};
-	const cogsCode = country.cogsGroupCode;
-	const isCogs = (name) => cogsCode ? name === cogsCode : name === "Cost of Sales" || name === "Cost of Goods Sold";
-	const costOfSales = expenses.groups.find((g) => isCogs(g.name))?.total ?? 0;
-	const grossProfit = revenue.total - costOfSales;
-	const operatingIncome = grossProfit - expenses.groups.filter((g) => !isCogs(g.name)).reduce((s, g) => s + g.total, 0);
-	const netIncome = revenue.total - expenses.total;
-	const periodDisplay = params.dateOption === "year" ? `For the year ended ${endDate.toLocaleDateString("en-US", {
-		year: "numeric",
-		month: "long",
-		day: "numeric"
-	})}` : `${startDate.toLocaleDateString("en-US", {
+	for (const section of Object.values(flows)) section.accounts.sort((a, b) => a.code.localeCompare(b.code, void 0, { numeric: true }));
+	const netCashFlow = flows.Operating.total + flows.Investing.total + flows.Financing.total;
+	const periodDisplay = `${startDate.toLocaleDateString("en-US", {
 		month: "short",
 		day: "numeric"
 	})} – ${endDate.toLocaleDateString("en-US", {
@@ -540,12 +706,116 @@ async function generateIncomeStatement(opts, params) {
 			periodEnd: endDate.toISOString().split("T")[0],
 			displayPeriod: periodDisplay
 		},
-		revenue,
-		costOfSales,
-		grossProfit,
-		expenses,
-		operatingIncome,
-		netIncome
+		operating: flows.Operating,
+		investing: flows.Investing,
+		financing: flows.Financing,
+		netCashFlow
+	};
+}
+//#endregion
+//#region src/reports/dimension-breakdown.ts
+async function generateDimensionBreakdown(opts, params) {
+	const { AccountModel, JournalEntryModel, country, orgField } = opts;
+	requireOrgScope(orgField, params.organizationId);
+	const { startDate, endDate } = getDateRange(params.dateOption, params.dateValue);
+	const itemFilters = buildItemFilters(params.filters);
+	const accountQuery = { active: true };
+	if (orgField && params.organizationId) accountQuery[orgField] = params.organizationId;
+	const allAccounts = await AccountModel.find(accountQuery).lean();
+	const accountIds = allAccounts.filter((a) => {
+		const at = country.getAccountType(a.accountTypeCode);
+		if (!at || at.isGroup || at.isTotal) return false;
+		if (params.accountCategory && at.category !== params.accountCategory) return false;
+		return true;
+	}).map((a) => a._id);
+	if (accountIds.length === 0) return {
+		metadata: {
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			dimension: params.dimension,
+			periodStart: startDate.toISOString().split("T")[0],
+			periodEnd: endDate.toISOString().split("T")[0]
+		},
+		rows: [],
+		grandTotal: 0
+	};
+	const accountMap = new Map(allAccounts.map((a) => [String(a._id), a]));
+	const dimensionPath = `journalItems.${params.dimension}`;
+	const baseMatch = {
+		state: "posted",
+		date: {
+			$gte: startDate,
+			$lte: endDate
+		}
+	};
+	if (orgField && params.organizationId) baseMatch[orgField] = params.organizationId;
+	const pipeline = [
+		{ $match: baseMatch },
+		{ $unwind: "$journalItems" },
+		{ $match: {
+			"journalItems.account": { $in: accountIds },
+			...itemFilters
+		} },
+		{ $group: {
+			_id: {
+				dimension: `$${dimensionPath}`,
+				account: "$journalItems.account"
+			},
+			d: { $sum: "$journalItems.debit" },
+			c: { $sum: "$journalItems.credit" }
+		} }
+	];
+	const results = await JournalEntryModel.aggregate(pipeline);
+	const dimensionMap = /* @__PURE__ */ new Map();
+	for (const r of results) {
+		const dimKey = r._id.dimension == null ? "__null__" : String(r._id.dimension);
+		const accKey = String(r._id.account);
+		if (!dimensionMap.has(dimKey)) dimensionMap.set(dimKey, /* @__PURE__ */ new Map());
+		dimensionMap.get(dimKey)?.set(accKey, {
+			d: r.d,
+			c: r.c
+		});
+	}
+	const rows = [];
+	const sortedDimKeys = [...dimensionMap.keys()].sort((a, b) => {
+		if (a === "__null__") return 1;
+		if (b === "__null__") return -1;
+		return a.localeCompare(b);
+	});
+	for (const dimKey of sortedDimKeys) {
+		const accountBalances = dimensionMap.get(dimKey);
+		const dimensionValue = dimKey === "__null__" ? null : results.find((r) => String(r._id.dimension) === dimKey)?._id.dimension ?? null;
+		const accounts = [];
+		let total = 0;
+		for (const [accId, bal] of accountBalances) {
+			const acc = accountMap.get(accId);
+			if (!acc) continue;
+			const at = country.getAccountType(acc.accountTypeCode);
+			const balance = at && (at.category === "Income Statement-Income" || at.category === "Balance Sheet-Liability" || at.category === "Balance Sheet-Equity") ? bal.c - bal.d : bal.d - bal.c;
+			accounts.push({
+				id: acc._id,
+				name: acc.name ?? at?.name ?? "",
+				code: acc.accountNumber ?? at?.code ?? "",
+				balance
+			});
+			total += balance;
+		}
+		accounts.sort((a, b) => a.code.localeCompare(b.code, void 0, { numeric: true }));
+		rows.push({
+			dimensionValue,
+			accounts,
+			total
+		});
+	}
+	const grandTotal = rows.reduce((s, r) => s + r.total, 0);
+	return {
+		metadata: {
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			dimension: params.dimension,
+			periodStart: startDate.toISOString().split("T")[0],
+			periodEnd: endDate.toISOString().split("T")[0]
+		},
+		rows,
+		grandTotal
 	};
 }
 //#endregion
@@ -576,6 +846,11 @@ async function generateGeneralLedger(opts, params) {
 			endDate
 		}
 	};
+	filtered.sort((a, b) => {
+		const codeA = a.acc.accountNumber ?? a.at.code;
+		const codeB = b.acc.accountNumber ?? b.at.code;
+		return codeA.localeCompare(codeB, void 0, { numeric: true });
+	});
 	const bsAccountIds = [];
 	const isAccountIds = [];
 	const allAccountIds = [];
@@ -674,7 +949,26 @@ async function generateGeneralLedger(opts, params) {
 			closingBalance: runningBalance
 		});
 	}
+	const periodDisplay = params.dateOption === "year" ? `For the year ended ${endDate.toLocaleDateString("en-US", {
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	})}` : `${startDate.toLocaleDateString("en-US", {
+		month: "short",
+		day: "numeric"
+	})} – ${endDate.toLocaleDateString("en-US", {
+		year: "numeric",
+		month: "short",
+		day: "numeric"
+	})}`;
 	return {
+		metadata: {
+			businessName: params.businessName,
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			periodStart: startDate.toISOString().split("T")[0],
+			periodEnd: endDate.toISOString().split("T")[0],
+			displayPeriod: periodDisplay
+		},
 		accounts: glAccounts,
 		period: {
 			startDate,
@@ -683,8 +977,8 @@ async function generateGeneralLedger(opts, params) {
 	};
 }
 //#endregion
-//#region src/reports/cash-flow.ts
-async function generateCashFlow(opts, params) {
+//#region src/reports/income-statement.ts
+async function generateIncomeStatement(opts, params) {
 	const { AccountModel, JournalEntryModel, country, orgField } = opts;
 	requireOrgScope(orgField, params.organizationId);
 	const { startDate, endDate } = getDateRange(params.dateOption, params.dateValue);
@@ -692,22 +986,11 @@ async function generateCashFlow(opts, params) {
 	const q = { active: true };
 	if (orgField && params.organizationId) q[orgField] = params.organizationId;
 	const allAccounts = await AccountModel.find(q).lean();
-	const accountCfMap = /* @__PURE__ */ new Map();
-	const accountMap = new Map(allAccounts.map((a) => [String(a._id), a]));
-	const cfAccountIds = [];
-	for (const acc of allAccounts) {
-		const at = country.getAccountType(acc.accountTypeCode);
-		if (!at || at.isGroup || at.isTotal) continue;
-		const cf = at.cashFlowCategory;
-		if (!cf) continue;
-		const normalized = cf.charAt(0).toUpperCase() + cf.slice(1);
-		accountCfMap.set(String(acc._id), {
-			category: at.category,
-			cfCategory: normalized
-		});
-		cfAccountIds.push(acc._id);
-	}
-	const baseMatch = {
+	const isIds = allAccounts.filter((a) => {
+		const at = country.getAccountType(a.accountTypeCode);
+		return at && !at.isGroup && !at.isTotal && at.category.startsWith("Income Statement");
+	}).map((a) => a._id);
+	const baseMatch = {
 		state: "posted",
 		date: {
 			$gte: startDate,
@@ -715,11 +998,11 @@ async function generateCashFlow(opts, params) {
 		}
 	};
 	if (orgField && params.organizationId) baseMatch[orgField] = params.organizationId;
-	const results = cfAccountIds.length > 0 ? await JournalEntryModel.aggregate([
+	const results = await JournalEntryModel.aggregate([
 		{ $match: baseMatch },
 		{ $unwind: "$journalItems" },
 		{ $match: {
-			"journalItems.account": { $in: cfAccountIds },
+			"journalItems.account": { $in: isIds },
 			...itemFilters
 		} },
 		{ $group: {
@@ -727,37 +1010,399 @@ async function generateCashFlow(opts, params) {
 			d: { $sum: "$journalItems.debit" },
 			c: { $sum: "$journalItems.credit" }
 		} }
-	]) : [];
-	const flows = {
-		Operating: {
-			total: 0,
-			accounts: []
-		},
-		Investing: {
+	]);
+	const accountMap = new Map(allAccounts.map((a) => [String(a._id), a]));
+	const revenueGroups = {};
+	const expenseGroups = {};
+	const resolveGroupName = (at) => {
+		const visited = /* @__PURE__ */ new Set();
+		let current = at.parentCode ? country.getAccountType(at.parentCode) : void 0;
+		while (current && !visited.has(current.code)) {
+			if (current.isGroup) return current.name;
+			visited.add(current.code);
+			current = current.parentCode ? country.getAccountType(current.parentCode) : void 0;
+		}
+		return at.name;
+	};
+	for (const r of results) {
+		const acc = accountMap.get(String(r._id));
+		if (!acc) continue;
+		const at = country.getAccountType(acc.accountTypeCode);
+		if (!at) continue;
+		const mainType = extractMainType(at.category);
+		const netAmount = mainType === "Income" ? r.c - r.d : r.d - r.c;
+		if (netAmount === 0) continue;
+		const groupName = resolveGroupName(at);
+		const groups = mainType === "Income" ? revenueGroups : expenseGroups;
+		if (!(groupName in groups)) groups[groupName] = {
+			name: groupName,
 			total: 0,
 			accounts: []
+		};
+		groups[groupName].accounts.push({
+			id: acc._id,
+			name: acc.name ?? at.name,
+			code: acc.accountNumber ?? at.code,
+			balance: netAmount
+		});
+		groups[groupName].total += netAmount;
+	}
+	const sortGroups = (groups) => {
+		const sorted = Object.values(groups);
+		for (const g of sorted) g.accounts.sort((a, b) => (a.code ?? "").localeCompare(b.code ?? "", void 0, { numeric: true }));
+		sorted.sort((a, b) => {
+			const codeA = a.accounts[0]?.code ?? "";
+			const codeB = b.accounts[0]?.code ?? "";
+			return codeA.localeCompare(codeB, void 0, { numeric: true });
+		});
+		return sorted;
+	};
+	const labels = country.reportLabels ?? {};
+	const revenue = {
+		name: labels.revenue ?? "Revenue",
+		total: Object.values(revenueGroups).reduce((s, g) => s + g.total, 0),
+		groups: sortGroups(revenueGroups)
+	};
+	const expenses = {
+		name: labels.expenses ?? "Expenses",
+		total: Object.values(expenseGroups).reduce((s, g) => s + g.total, 0),
+		groups: sortGroups(expenseGroups)
+	};
+	const cogsCode = country.cogsGroupCode;
+	const isCogs = (name) => cogsCode ? name === cogsCode : name === "Cost of Sales" || name === "Cost of Goods Sold";
+	const costOfSales = expenses.groups.find((g) => isCogs(g.name))?.total ?? 0;
+	const grossProfit = revenue.total - costOfSales;
+	const operatingIncome = grossProfit - expenses.groups.filter((g) => !isCogs(g.name)).reduce((s, g) => s + g.total, 0);
+	const netIncome = revenue.total - expenses.total;
+	const periodDisplay = params.dateOption === "year" ? `For the year ended ${endDate.toLocaleDateString("en-US", {
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	})}` : `${startDate.toLocaleDateString("en-US", {
+		month: "short",
+		day: "numeric"
+	})} – ${endDate.toLocaleDateString("en-US", {
+		year: "numeric",
+		month: "short",
+		day: "numeric"
+	})}`;
+	return {
+		metadata: {
+			businessName: params.businessName,
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			periodStart: startDate.toISOString().split("T")[0],
+			periodEnd: endDate.toISOString().split("T")[0],
+			displayPeriod: periodDisplay
 		},
-		Financing: {
-			total: 0,
-			accounts: []
-		}
+		revenue,
+		costOfSales,
+		grossProfit,
+		expenses,
+		operatingIncome,
+		netIncome
 	};
+}
+//#endregion
+//#region src/utils/revaluation.ts
+/**
+* Compute revaluation results for a set of accounts at new exchange rates.
+*
+* For each account, finds the matching rate by currency, computes the
+* revalued base amount, and determines the gain/loss.
+* Accounts with zero gain/loss are excluded from the results.
+*
+* @param accounts - Foreign-currency account balances at historical rates
+* @param rates - New exchange rates to revalue against
+* @param baseCurrency - The functional/base currency code (accounts in this currency are skipped)
+*/
+function computeRevaluation(accounts, rates, baseCurrency) {
+	const rateMap = new Map(rates.map((r) => [r.currency, r.rate]));
+	const results = [];
+	for (const acct of accounts) {
+		if (acct.currency === baseCurrency) continue;
+		const rate = rateMap.get(acct.currency);
+		if (rate === void 0) continue;
+		const revaluedBase = Math.round(acct.foreignBalance * rate);
+		const gainLoss = revaluedBase - acct.baseBalance;
+		if (gainLoss === 0) continue;
+		results.push({
+			accountId: acct.accountId,
+			accountName: acct.accountName,
+			accountCode: acct.accountCode,
+			currency: acct.currency,
+			foreignBalance: acct.foreignBalance,
+			historicalBase: acct.baseBalance,
+			revaluedBase,
+			gainLoss
+		});
+	}
+	return results;
+}
+/**
+* Build a balanced revaluation journal entry from revaluation results.
+*
+* For each result with a non-zero gain/loss:
+* - Gain (positive gainLoss): Debit the account, Credit the unrealized gain/loss account
+* - Loss (negative gainLoss): Credit the account, Debit the unrealized gain/loss account
+*
+* @param results - Revaluation results from computeRevaluation
+* @param unrealizedGainLossAccountId - The account to book the offsetting entry against
+* @param date - Date for the revaluation entry
+*/
+function buildRevaluationEntry(results, unrealizedGainLossAccountId, date) {
+	const journalItems = [];
+	let totalDebit = 0;
+	let totalCredit = 0;
 	for (const r of results) {
-		const accIdStr = String(r._id);
-		const meta = accountCfMap.get(accIdStr);
-		if (!meta) continue;
-		const amount = computeEndingBalance(meta.category, r.d, r.c);
-		const acc = accountMap.get(accIdStr);
-		const at = country.getAccountType(acc?.accountTypeCode);
-		flows[meta.cfCategory].accounts.push({
-			name: acc?.name ?? at?.name ?? "",
-			code: acc?.accountNumber ?? at?.code ?? "",
-			amount
+		if (r.gainLoss === 0) continue;
+		const absAmount = Math.abs(r.gainLoss);
+		if (r.gainLoss > 0) {
+			journalItems.push({
+				account: r.accountId,
+				debit: absAmount,
+				credit: 0,
+				originalDebit: 0,
+				originalCredit: 0,
+				label: `FX revaluation ${r.currency} — gain`
+			});
+			journalItems.push({
+				account: unrealizedGainLossAccountId,
+				debit: 0,
+				credit: absAmount,
+				originalDebit: 0,
+				originalCredit: 0,
+				label: `FX revaluation ${r.currency} — gain`
+			});
+		} else {
+			journalItems.push({
+				account: r.accountId,
+				debit: 0,
+				credit: absAmount,
+				originalDebit: 0,
+				originalCredit: 0,
+				label: `FX revaluation ${r.currency} — loss`
+			});
+			journalItems.push({
+				account: unrealizedGainLossAccountId,
+				debit: absAmount,
+				credit: 0,
+				originalDebit: 0,
+				originalCredit: 0,
+				label: `FX revaluation ${r.currency} — loss`
+			});
+		}
+		totalDebit += absAmount;
+		totalCredit += absAmount;
+	}
+	const dateStr = date.toISOString().split("T")[0];
+	return {
+		journalItems,
+		totalDebit,
+		totalCredit,
+		label: `Foreign exchange revaluation — ${dateStr}`
+	};
+}
+//#endregion
+//#region src/reports/revaluation.ts
+/**
+* Generate a foreign exchange revaluation report.
+*
+* 1. Finds all accounts with a `currency` field (foreign-currency accounts)
+* 2. Filters to balance sheet accounts only (not P&L)
+* 3. Aggregates foreign-currency and base-currency balances from posted entries
+* 4. Computes gain/loss at the new rates
+* 5. Optionally creates and saves a balanced journal entry
+*/
+async function generateRevaluation(opts, params) {
+	const { AccountModel, JournalEntryModel, country, orgField, baseCurrency } = opts;
+	requireOrgScope(orgField, params.organizationId);
+	const accountQuery = {
+		active: true,
+		currency: {
+			$exists: true,
+			$ne: null
+		}
+	};
+	if (orgField && params.organizationId) accountQuery[orgField] = params.organizationId;
+	const bsAccounts = (await AccountModel.find(accountQuery).lean()).filter((a) => {
+		const at = country.getAccountType(a.accountTypeCode);
+		return at && !at.isGroup && at.category.startsWith("Balance Sheet");
+	});
+	if (bsAccounts.length === 0) return {
+		metadata: {
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			asOfDate: params.asOfDate.toISOString().split("T")[0],
+			baseCurrency
+		},
+		results: [],
+		totalGainLoss: 0
+	};
+	const bsAccountIds = bsAccounts.map((a) => a._id);
+	const baseMatch = {
+		state: "posted",
+		date: { $lte: params.asOfDate }
+	};
+	if (orgField && params.organizationId) baseMatch[orgField] = params.organizationId;
+	const balanceResults = await JournalEntryModel.aggregate([
+		{ $match: baseMatch },
+		{ $unwind: "$journalItems" },
+		{ $match: { "journalItems.account": { $in: bsAccountIds } } },
+		{ $group: {
+			_id: "$journalItems.account",
+			debit: { $sum: "$journalItems.debit" },
+			credit: { $sum: "$journalItems.credit" },
+			originalDebit: { $sum: { $ifNull: ["$journalItems.originalDebit", 0] } },
+			originalCredit: { $sum: { $ifNull: ["$journalItems.originalCredit", 0] } }
+		} }
+	]);
+	const accountMap = new Map(bsAccounts.map((a) => [String(a._id), a]));
+	const accountBalances = [];
+	for (const r of balanceResults) {
+		const acct = accountMap.get(String(r._id));
+		if (!acct) continue;
+		const at = country.getAccountType(acct.accountTypeCode);
+		if (!at) continue;
+		accountBalances.push({
+			accountId: r._id,
+			accountName: acct.name ?? at.name,
+			accountCode: acct.accountNumber ?? at.code,
+			currency: acct.currency,
+			foreignBalance: r.originalDebit - r.originalCredit,
+			baseBalance: r.debit - r.credit,
+			category: at.category
 		});
-		flows[meta.cfCategory].total += amount;
 	}
-	const netCashFlow = flows.Operating.total + flows.Investing.total + flows.Financing.total;
-	const periodDisplay = `${startDate.toLocaleDateString("en-US", {
+	const results = computeRevaluation(accountBalances, params.rates, baseCurrency);
+	const totalGainLoss = results.reduce((sum, r) => sum + r.gainLoss, 0);
+	let entryId;
+	if (params.generateEntry && results.length > 0) {
+		const entryData = buildRevaluationEntry(results, params.unrealizedGainLossAccountId, params.asOfDate);
+		const doc = {
+			journalType: "GENERAL",
+			state: "posted",
+			date: params.asOfDate,
+			label: entryData.label,
+			journalItems: entryData.journalItems,
+			totalDebit: entryData.totalDebit,
+			totalCredit: entryData.totalCredit
+		};
+		if (orgField && params.organizationId) doc[orgField] = params.organizationId;
+		entryId = (await JournalEntryModel.create(doc))._id;
+	}
+	return {
+		metadata: {
+			generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			asOfDate: params.asOfDate.toISOString().split("T")[0],
+			baseCurrency
+		},
+		results,
+		totalGainLoss,
+		...entryId !== void 0 ? { entryId } : {}
+	};
+}
+//#endregion
+//#region src/reports/trial-balance.ts
+async function generateTrialBalance(opts, params) {
+	const { AccountModel, JournalEntryModel, country, orgField, fiscalYearStartMonth = 1 } = opts;
+	requireOrgScope(orgField, params.organizationId);
+	const { startDate, endDate } = getDateRange(params.dateOption, params.dateValue);
+	const fiscalYearStart = getFiscalYearStart(startDate, fiscalYearStartMonth);
+	const itemFilters = buildItemFilters(params.filters);
+	const accountQuery = { active: true };
+	if (orgField && params.organizationId) accountQuery[orgField] = params.organizationId;
+	const allAccounts = await AccountModel.find(accountQuery).lean();
+	const bsIds = [];
+	const isIds = [];
+	for (const acc of allAccounts) {
+		const at = country.getAccountType(acc.accountTypeCode);
+		if (!at || at.isGroup) continue;
+		if (at.category.startsWith("Balance Sheet")) bsIds.push(acc._id);
+		else if (at.category.startsWith("Income Statement")) isIds.push(acc._id);
+	}
+	const baseMatch = { state: "posted" };
+	if (orgField && params.organizationId) baseMatch[orgField] = params.organizationId;
+	const accountFilter = params.accountId ? { "journalItems.account": params.accountId } : {};
+	const buildPipeline = (ids, dateFrom, dateTo) => [
+		{ $match: {
+			...baseMatch,
+			date: {
+				$gte: dateFrom,
+				$lt: dateTo
+			}
+		} },
+		{ $unwind: "$journalItems" },
+		{ $match: {
+			"journalItems.account": { $in: ids },
+			...accountFilter,
+			...itemFilters
+		} },
+		{ $group: {
+			_id: "$journalItems.account",
+			d: { $sum: "$journalItems.debit" },
+			c: { $sum: "$journalItems.credit" }
+		} }
+	];
+	const [bsInitial, isInitial, current] = await Promise.all([
+		bsIds.length ? JournalEntryModel.aggregate(buildPipeline(bsIds, /* @__PURE__ */ new Date(0), startDate)) : [],
+		isIds.length ? JournalEntryModel.aggregate(buildPipeline(isIds, fiscalYearStart, startDate)) : [],
+		JournalEntryModel.aggregate(buildPipeline([...bsIds, ...isIds], startDate, new Date(endDate.getTime() + 1)))
+	]);
+	const map = /* @__PURE__ */ new Map();
+	for (const r of [...bsInitial, ...isInitial]) {
+		const key = String(r._id);
+		map.set(key, {
+			iD: r.d,
+			iC: r.c,
+			cD: 0,
+			cC: 0
+		});
+	}
+	for (const r of current) {
+		const key = String(r._id);
+		const existing = map.get(key) ?? {
+			iD: 0,
+			iC: 0,
+			cD: 0,
+			cC: 0
+		};
+		existing.cD = r.d;
+		existing.cC = r.c;
+		map.set(key, existing);
+	}
+	const accountLookup = new Map(allAccounts.map((a) => [String(a._id), a]));
+	const rows = [];
+	for (const [id, bal] of map) {
+		const acc = accountLookup.get(id);
+		const net = bal.iD + bal.cD - (bal.iC + bal.cC);
+		rows.push({
+			account: acc ?? id,
+			initial: {
+				debit: bal.iD,
+				credit: bal.iC
+			},
+			current: {
+				debit: bal.cD,
+				credit: bal.cC
+			},
+			ending: net >= 0 ? {
+				debit: net,
+				credit: 0
+			} : {
+				debit: 0,
+				credit: Math.abs(net)
+			}
+		});
+	}
+	rows.sort((a, b) => {
+		const codeA = a.account?.accountNumber ?? a.account?.accountTypeCode ?? "";
+		const codeB = b.account?.accountNumber ?? b.account?.accountTypeCode ?? "";
+		return codeA.localeCompare(codeB, void 0, { numeric: true });
+	});
+	const periodDisplay = params.dateOption === "year" ? `For the year ended ${endDate.toLocaleDateString("en-US", {
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	})}` : `${startDate.toLocaleDateString("en-US", {
 		month: "short",
 		day: "numeric"
 	})} – ${endDate.toLocaleDateString("en-US", {
@@ -773,16 +1418,87 @@ async function generateCashFlow(opts, params) {
 			periodEnd: endDate.toISOString().split("T")[0],
 			displayPeriod: periodDisplay
 		},
-		operating: flows.Operating,
-		investing: flows.Investing,
-		financing: flows.Financing,
-		netCashFlow
+		rows,
+		period: {
+			startDate,
+			endDate
+		}
 	};
 }
 //#endregion
+//#region src/utils/logger.ts
+/** Default console-based implementation */
+const defaultLogger = {
+	warn: (msg, meta) => console.warn(`[accounting] ${msg}`, meta ?? ""),
+	error: (msg, meta) => console.error(`[accounting] ${msg}`, meta ?? ""),
+	info: (msg, meta) => console.info(`[accounting] ${msg}`, meta ?? "")
+};
+//#endregion
+//#region src/utils/session.ts
+/**
+* Acquire a session: uses external if provided, otherwise creates an internal one.
+* Returns { session, ownSession } so callers can commit/abort/end appropriately.
+*
+* When transactions are unavailable (no replica set / standalone), returns
+* session=null and the function runs without transactional safety.
+*/
+async function acquireSession(db, externalSession, logger = defaultLogger) {
+	if (externalSession) return {
+		session: externalSession,
+		ownSession: false
+	};
+	try {
+		const session = await db.startSession();
+		try {
+			const conn = db;
+			if ((conn.getClient?.() ?? conn.client)?.topology?.description?.type === "Single") {
+				session.endSession();
+				logger.warn("Transactions unavailable (standalone MongoDB). Operation is not atomic.");
+				return {
+					session: null,
+					ownSession: false
+				};
+			}
+		} catch {}
+		try {
+			session.startTransaction();
+			return {
+				session,
+				ownSession: true
+			};
+		} catch (err) {
+			session.endSession();
+			logger.warn("Transactions unavailable (no replica set). Operation is not atomic.", { error: err.message });
+			return {
+				session: null,
+				ownSession: false
+			};
+		}
+	} catch {
+		return {
+			session: null,
+			ownSession: false
+		};
+	}
+}
+/**
+* Finalize an owned session: commit or abort, then always end.
+*/
+async function finalizeSession(session, ownSession, success) {
+	if (!ownSession || !session) return;
+	try {
+		if (success && session.inTransaction()) await session.commitTransaction();
+		else if (!success && session.inTransaction()) try {
+			await session.abortTransaction();
+		} catch {}
+	} finally {
+		session.endSession();
+	}
+}
+//#endregion
 //#region src/reports/fiscal-close.ts
 async function closeFiscalPeriod(opts, params) {
-	const { AccountModel, JournalEntryModel, FiscalPeriodModel, country, orgField, retainedEarningsCode = country.retainedEarningsCode ?? "3660", logger = defaultLogger } = opts;
+	const { AccountModel, JournalEntryModel, FiscalPeriodModel, country, orgField, retainedEarningsAccountCode = country.retainedEarningsAccountCode ?? "3600", logger = defaultLogger } = opts;
 	const { periodId, organizationId, closedBy } = params;
 	requireOrgScope(orgField, organizationId);
 	const { session, ownSession } = await acquireSession(AccountModel.db, params.session, logger);
@@ -804,7 +1520,7 @@ async function closeFiscalPeriod(opts, params) {
 		for (const acc of allAccounts) {
 			const at = country.getAccountType(acc.accountTypeCode);
 			if (!at) continue;
-			if (acc.accountTypeCode === retainedEarningsCode) retainedEarningsId = acc._id;
+			if (acc.accountTypeCode === retainedEarningsAccountCode) retainedEarningsId = acc._id;
 			if (at.isGroup || at.isTotal) continue;
 			if (at.category.startsWith("Income Statement")) isAccounts.push({
 				id: acc._id,
@@ -812,7 +1528,7 @@ async function closeFiscalPeriod(opts, params) {
 				isIncome: at.category === "Income Statement-Income"
 			});
 		}
-		if (!retainedEarningsId) throw Errors.fiscal(`Retained earnings account (code: ${retainedEarningsCode}) not found. Create this account before closing the fiscal period.`);
+		if (!retainedEarningsId) throw Errors.fiscal(`Retained earnings account (code: ${retainedEarningsAccountCode}) not found. Create this account before closing the fiscal period.`);
 		const baseMatch = {
 			state: "posted",
 			date: {
@@ -934,6 +1650,4 @@ async function reopenFiscalPeriod(opts, params) {
 	}
 }
 //#endregion
-export { generateIncomeStatement as a, calculateTotal as c, generateTrialBalance as d, buildItemFilters as f, generateGeneralLedger as i, computeEndingBalance as l, getFiscalYearStart as m, reopenFiscalPeriod as n, generateBalanceSheet as o, getDateRange as p, generateCashFlow as r, buildAccountTypeMap as s, closeFiscalPeriod as t, isVirtualTaxAccount as u };
-
-//# sourceMappingURL=fiscal-close-L631E3De.mjs.map
+export { DEFAULT_BUCKETS as C, isVirtualTaxAccount as S, getDateRange as _, defaultLogger as a, calculateTotal as b, buildRevaluationEntry as c, generateGeneralLedger as d, generateDimensionBreakdown as f, buildItemFilters as g, generateBalanceSheet as h, finalizeSession as i, computeRevaluation as l, generateBudgetVsActual as m, reopenFiscalPeriod as n, generateTrialBalance as o, generateCashFlow as p, acquireSession as r, generateRevaluation as s, closeFiscalPeriod as t, generateIncomeStatement as u, getFiscalYearStart as v, generateAgedBalance as w, computeEndingBalance as x, buildAccountTypeMap as y };