@classytic/ledger 0.2.0 → 0.3.0

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

@@ -1,10 +1,13 @@
 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 { t as requireOrgScope } from "./tenant-guard-Fm6AID_6.mjs";
 import { i as extractMainType } from "./categories-CclX7Q94.mjs";
+import mongoose from "mongoose";
 //#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 +15,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 +26,21 @@ function getDateRange(option, value) {
 				month = parseInt(match[2], 10) - 1;
 			} else {
 				const date = new Date(value);
+				if (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 +49,23 @@ function getDateRange(option, value) {
 		}
 		case "year": {
 			const year = typeof value === "number" ? value : parseInt(String(value), 10);
+			if (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 (isNaN(start.getTime()) || 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
 			};
 		}
@@ -199,7 +214,31 @@ async function generateTrialBalance(opts, params) {
 			}
 		});
 	}
+	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", {
+		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
+		},
 		rows,
 		period: {
 			startDate,
@@ -254,7 +293,7 @@ function buildAccountTypeMap(accountTypes) {
 //#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 +305,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 +364,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 +412,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 +441,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 +456,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);
@@ -503,16 +573,26 @@ async function generateIncomeStatement(opts, params) {
 		});
 		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: Object.values(revenueGroups)
+		groups: sortGroups(revenueGroups)
 	};
 	const expenses = {
 		name: labels.expenses ?? "Expenses",
 		total: Object.values(expenseGroups).reduce((s, g) => s + g.total, 0),
-		groups: Object.values(expenseGroups)
+		groups: sortGroups(expenseGroups)
 	};
 	const cogsCode = country.cogsGroupCode;
 	const isCogs = (name) => cogsCode ? name === cogsCode : name === "Cost of Sales" || name === "Cost of Goods Sold";
@@ -576,6 +656,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 +759,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,
@@ -756,6 +860,7 @@ async function generateCashFlow(opts, params) {
 		});
 		flows[meta.cfCategory].total += amount;
 	}
+	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",
@@ -780,9 +885,623 @@ async function generateCashFlow(opts, params) {
 	};
 }
 //#endregion
+//#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/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
+//#region src/reports/budget-vs-actual.ts
+/**
+* Budget vs Actual Report
+*
+* Compares budgeted amounts against actual journal entry balances
+* for a given period. All monetary values are integer cents.
+*/
+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 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: {
+			$gte: startDate,
+			$lte: endDate
+		}
+	};
+	if (orgField && params.organizationId) baseMatch[orgField] = params.organizationId;
+	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/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) {
+		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
+		});
+	}
+	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/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 +1523,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 +1531,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 +1653,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 { getDateRange as C, buildItemFilters as S, buildAccountTypeMap as _, defaultLogger as a, isVirtualTaxAccount as b, computeRevaluation as c, DEFAULT_BUCKETS as d, generateAgedBalance as f, generateBalanceSheet as g, generateIncomeStatement as h, finalizeSession as i, generateBudgetVsActual as l, generateGeneralLedger as m, reopenFiscalPeriod as n, generateRevaluation as o, generateCashFlow as p, acquireSession as r, buildRevaluationEntry as s, closeFiscalPeriod as t, generateDimensionBreakdown as u, calculateTotal as v, getFiscalYearStart as w, generateTrialBalance as x, computeEndingBalance as y };