@classytic/ledger 0.5.1 → 0.6.0

package/dist/country/index.d.mts

@@ -1,2 +1,2 @@
-import { a as TaxReportLine, i as TaxCodesByRegion, n as CountryPackInput, o as TaxReportTemplate, r as TaxCode, s as defineCountryPack, t as CountryPack } from "../index-GmfEFxVn.mjs";
-export { CountryPack, CountryPackInput, TaxCode, TaxCodesByRegion, TaxReportLine, TaxReportTemplate, defineCountryPack };
+import { a as TaxCodesByRegion, c as TaxReportLine, i as TaxCode, l as TaxReportTemplate, n as CountryPackInput, o as TaxExigibility, r as JournalTemplate, s as TaxRepartitionLine, t as CountryPack, u as defineCountryPack } from "../index-BthGypsI.mjs";
+export { CountryPack, CountryPackInput, JournalTemplate, TaxCode, TaxCodesByRegion, TaxExigibility, TaxRepartitionLine, TaxReportLine, TaxReportTemplate, defineCountryPack };

package/dist/{errors-BmRjW38t.mjs → errors-CSDQPNyt.mjs}

@@ -27,7 +27,7 @@ const Errors = {
 	notFound: (msg, fields) => new AccountingError(msg, 404, "NOT_FOUND", fields),
 	conflict: (msg, fields) => new AccountingError(msg, 409, "CONFLICT", fields),
 	immutable: (msg, fields) => new AccountingError(msg, 403, "IMMUTABLE_ENTRY", fields),
-	fiscal: (msg, fields) => new AccountingError(msg, 400, "FISCAL_ERROR", fields)
+	locked: (scope, msg, fields) => new AccountingError(msg, 409, `PERIOD_LOCKED_${scope.toUpperCase()}`, fields)
 };
 //#endregion
 export { Errors as n, AccountingError as t };

package/dist/fx-realization.plugin-CgQFDGv2.mjs

@@ -0,0 +1,459 @@
+import { n as Errors, t as AccountingError } from "./errors-CSDQPNyt.mjs";
+//#region src/plugins/double-entry.plugin.ts
+function doubleEntryPlugin(options = {}) {
+	const { onlyOnPost = true, JournalEntryModel, AccountModel, orgField } = options;
+	function validateItems(items, data) {
+		const lineErrors = [];
+		for (let i = 0; i < items.length; i++) {
+			const d = items[i].debit ?? 0;
+			const c = items[i].credit ?? 0;
+			if (d > 0 && c > 0) lineErrors.push({
+				path: `journalItems.${i}`,
+				issue: "line cannot have both debit and credit greater than zero",
+				value: {
+					debit: d,
+					credit: c
+				}
+			});
+			if (d === 0 && c === 0) lineErrors.push({
+				path: `journalItems.${i}`,
+				issue: "line cannot have both debit and credit equal to zero",
+				value: {
+					debit: 0,
+					credit: 0
+				}
+			});
+		}
+		if (lineErrors.length > 0) throw Errors.validation(`Invalid journal line(s): ${lineErrors.map((e) => `${e.path} — ${e.issue}`).join("; ")}`, lineErrors);
+		const totalDebit = items.reduce((s, i) => s + (i.debit ?? 0), 0);
+		const totalCredit = items.reduce((s, i) => s + (i.credit ?? 0), 0);
+		if (totalDebit !== totalCredit) throw Errors.validation(`Double-entry violation: debits (${totalDebit}) ≠ credits (${totalCredit}). Difference: ${Math.abs(totalDebit - totalCredit)}`, [{
+			path: "journalItems",
+			issue: "debits must equal credits",
+			value: {
+				totalDebit,
+				totalCredit,
+				difference: totalDebit - totalCredit
+			}
+		}]);
+		data.totalDebit = totalDebit;
+		data.totalCredit = totalCredit;
+	}
+	return {
+		name: "accounting:double-entry",
+		apply(repo) {
+			const validate = async (context) => {
+				const data = context.data;
+				if (!data) return;
+				if (onlyOnPost && data.state !== "posted") return;
+				const items = data.journalItems;
+				if (data.state === "posted" && (!items || items.length < 2)) throw Errors.validation(`Cannot post entry: at least 2 journal items required, got ${items?.length ?? 0}.`);
+				if (!items || items.length === 0) return;
+				validateItems(items, data);
+				if (data.state === "posted") {
+					if (!AccountModel) throw new Error("doubleEntryPlugin: AccountModel is required to validate posted entries. Pass AccountModel in plugin options to enable account existence and tenant integrity checks.");
+					await validateAccounts(items, data, context);
+				}
+			};
+			/** Verify all journal item accounts exist and belong to the same org */
+			const validateAccounts = async (items, data, context) => {
+				const missingIdxs = [];
+				items.forEach((item, idx) => {
+					if (item.account == null || item.account === "") missingIdxs.push(idx);
+				});
+				if (missingIdxs.length > 0) throw Errors.validation(`Posted entry has items with missing accounts at index(es): ${missingIdxs.join(", ")}.`, missingIdxs.map((i) => ({
+					path: `journalItems.${i}.account`,
+					issue: "account is required on posted entries"
+				})));
+				const accountIds = items.map((i) => i.account);
+				const selectFields = orgField ? `_id ${orgField}` : "_id";
+				const accounts = await AccountModel?.find({ _id: { $in: accountIds } }).select(selectFields).session(context.session ?? null).lean();
+				const foundIds = new Set(accounts.map((a) => String(a._id)));
+				const missingFieldErrors = [];
+				items.forEach((item, idx) => {
+					if (!foundIds.has(String(item.account))) missingFieldErrors.push({
+						path: `journalItems.${idx}.account`,
+						issue: "account does not exist",
+						value: item.account
+					});
+				});
+				if (missingFieldErrors.length > 0) throw Errors.validation(`${missingFieldErrors.length} item(s) reference non-existent accounts.`, missingFieldErrors);
+				if (orgField && data[orgField] != null) {
+					const dataOrg = String(data[orgField]);
+					const accountOrgById = new Map(accounts.map((a) => [String(a._id), String(a[orgField])]));
+					const crossTenantFieldErrors = [];
+					items.forEach((item, idx) => {
+						const acctOrg = accountOrgById.get(String(item.account));
+						if (acctOrg !== void 0 && acctOrg !== dataOrg) crossTenantFieldErrors.push({
+							path: `journalItems.${idx}.account`,
+							issue: "account belongs to another organization",
+							value: {
+								account: item.account,
+								expectedOrg: dataOrg,
+								actualOrg: acctOrg
+							}
+						});
+					});
+					if (crossTenantFieldErrors.length > 0) throw Errors.validation(`${crossTenantFieldErrors.length} item(s) reference accounts from another organization.`, crossTenantFieldErrors);
+				}
+			};
+			const validateUpdate = async (context) => {
+				const data = context.data;
+				if (!data) return;
+				const internalOp = context._ledgerInternal;
+				if (JournalEntryModel && !internalOp) {
+					const id = context.id;
+					if (id) {
+						if ((await JournalEntryModel.findById(id).select("state").session(context.session ?? null).lean())?.state === "posted") {
+							if (data.state !== void 0 && data.state !== "posted") throw Errors.immutable("Cannot change state of a posted journal entry. Posted entries are immutable.");
+							const allowedKeys = new Set(["state"]);
+							if (Object.keys(data).some((k) => !allowedKeys.has(k))) throw Errors.immutable("Cannot modify a posted journal entry. Use reverse() to create a correcting entry instead.");
+						}
+					}
+				}
+				if (onlyOnPost && data.state !== "posted") return;
+				const items = data.journalItems;
+				if (items !== void 0) {
+					if (items.length < 2) throw Errors.validation(`Cannot post entry: at least 2 journal items required, got ${items.length}.`);
+					validateItems(items, data);
+					if (AccountModel) await validateAccounts(items, data, context);
+					return;
+				}
+				if (!JournalEntryModel) throw new Error("doubleEntryPlugin: JournalEntryModel is required to validate partial updates that set state to \"posted\". Pass JournalEntryModel in plugin options.");
+				const id = context.id;
+				if (!id) throw new Error("doubleEntryPlugin: update context is missing \"id\". Cannot validate partial post without document ID.");
+				const existing = await JournalEntryModel.findById(id).select("journalItems").session(context.session ?? null).lean();
+				if (!existing) return;
+				const persistedItems = existing.journalItems;
+				if (!persistedItems || persistedItems.length < 2) throw Errors.validation(`Cannot post entry: at least 2 journal items required, got ${persistedItems?.length ?? 0}.`);
+				validateItems(persistedItems, data);
+				if (AccountModel) await validateAccounts(persistedItems, {
+					...data,
+					...existing
+				}, context);
+			};
+			repo.on("before:create", validate);
+			repo.on("before:update", validateUpdate);
+		}
+	};
+}
+//#endregion
+//#region src/plugins/idempotency.plugin.ts
+function idempotencyPlugin(options) {
+	const { JournalEntryModel, orgField } = options;
+	return {
+		name: "accounting:idempotency",
+		apply(repo) {
+			repo.on("before:create", async (context) => {
+				const data = context.data;
+				if (!data?.idempotencyKey) return;
+				const query = { idempotencyKey: data.idempotencyKey };
+				if (orgField && data[orgField]) query[orgField] = data[orgField];
+				const existing = await JournalEntryModel.findOne(query).select("_id").session(context.session ?? null).lean();
+				if (existing) throw Errors.conflict(`Duplicate idempotency key: "${data.idempotencyKey}". Existing entry: ${existing._id}`);
+			});
+		}
+	};
+}
+//#endregion
+//#region src/plugins/lock/create-lock-plugin.ts
+function createLockPlugin(options) {
+	const { scope, resolve, accountSelector, AccountModel, JournalEntryModel, orgField } = options;
+	if (accountSelector && !AccountModel) throw new Error(`createLockPlugin({ scope: '${scope}' }): accountSelector requires AccountModel.`);
+	return {
+		name: `accounting:lock:${scope}`,
+		apply(repo) {
+			const run = async (context, isUpdate) => {
+				const data = context.data;
+				if (!data) return;
+				if (data.state !== "posted") return;
+				if (context._ledgerInternal === "reverseMark") return;
+				const session = context.session ?? null;
+				let entryDate;
+				let persistedDoc = null;
+				if (data.date) entryDate = new Date(data.date);
+				else if (!isUpdate) entryDate = /* @__PURE__ */ new Date();
+				else {
+					if (!context.id) throw new Error(`lockPlugin[${scope}]: update context is missing "id". Cannot validate lock without document ID.`);
+					if (!JournalEntryModel) throw new Error(`lockPlugin[${scope}]: JournalEntryModel is required to validate partial updates that set state to "posted".`);
+					const selectFields = orgField ? `date ${orgField} journalItems` : "date journalItems";
+					persistedDoc = await JournalEntryModel.findById(context.id).select(selectFields).session(session).lean();
+					if (persistedDoc?.date) entryDate = new Date(persistedDoc.date);
+				}
+				if (!entryDate) return;
+				let orgValue;
+				if (orgField) {
+					orgValue = data[orgField] ?? context[orgField];
+					if (!orgValue && isUpdate) {
+						if (persistedDoc) orgValue = persistedDoc[orgField];
+						else if (context.id && JournalEntryModel) {
+							const persisted = await JournalEntryModel.findById(context.id).select(orgField).session(session).lean();
+							if (persisted) orgValue = persisted[orgField];
+						}
+					}
+					if (!orgValue) throw new Error(`lockPlugin[${scope}]: orgField "${orgField}" is configured but could not be resolved from payload, context, or persisted document.`);
+				}
+				if (accountSelector && AccountModel) {
+					const accountIds = (data.journalItems ?? persistedDoc?.journalItems ?? []).map((i) => {
+						const a = i.account;
+						if (typeof a === "object" && a !== null) return a._id ?? a;
+						return a;
+					}).filter((id) => id != null);
+					if (accountIds.length === 0) return;
+					if (!(await AccountModel.find({ _id: { $in: accountIds } }).session(session).lean()).some((acc) => accountSelector(acc))) return;
+				}
+				const hit = await resolve({
+					entryDate,
+					orgValue,
+					session,
+					data,
+					repositoryContext: context
+				});
+				if (!hit) return;
+				const datePart = entryDate.toISOString().split("T")[0];
+				const subTypePart = hit.subType ? ` [${hit.subType}]` : "";
+				const refPart = hit.externalRef ? ` (ref: ${hit.externalRef})` : "";
+				throw Errors.locked(hit.scope, `Cannot post entry dated ${datePart}: ${hit.scope}${subTypePart} period "${hit.label}" is closed${refPart}.`);
+			};
+			repo.on("before:create", (ctx) => run(ctx, false));
+			repo.on("before:update", (ctx) => run(ctx, true));
+		}
+	};
+}
+//#endregion
+//#region src/plugins/lock/period-resolver.ts
+function periodResolver(options) {
+	const { scope, PeriodModel, startField = "startDate", endField = "endDate", closedField = "closed", closedValue = true, labelField = "name", subTypeField, externalRefField, orgField, extraQuery } = options;
+	return async (ctx) => {
+		const query = {
+			[startField]: { $lte: ctx.entryDate },
+			[endField]: { $gte: ctx.entryDate },
+			[closedField]: closedValue
+		};
+		if (orgField) {
+			if (!ctx.orgValue) throw new Error(`periodResolver[${scope}]: orgField "${orgField}" set but no orgValue was resolved.`);
+			query[orgField] = ctx.orgValue;
+		}
+		const extra = extraQuery?.(ctx);
+		if (extra) Object.assign(query, extra);
+		const session = ctx.session;
+		const doc = await PeriodModel.findOne(query).session(session).lean();
+		if (!doc) return null;
+		return {
+			scope,
+			label: String(doc[labelField] ?? "(unnamed)"),
+			subType: subTypeField ? doc[subTypeField] : void 0,
+			externalRef: externalRefField ? doc[externalRefField] : void 0
+		};
+	};
+}
+//#endregion
+//#region src/plugins/lock/watermark-resolver.ts
+function watermarkResolver(options) {
+	const { scope, getWatermark, formatLabel } = options;
+	return async (ctx) => {
+		const watermark = await getWatermark(ctx.orgValue, ctx.session);
+		if (!watermark) return null;
+		if (ctx.entryDate.getTime() > watermark.getTime()) return null;
+		return {
+			scope,
+			label: formatLabel?.(watermark, ctx) ?? `through ${watermark.toISOString().split("T")[0]}`
+		};
+	};
+}
+//#endregion
+//#region src/plugins/lock/presets.ts
+function fiscalLockPlugin(options) {
+	return createLockPlugin({
+		scope: "fiscal",
+		JournalEntryModel: options.JournalEntryModel,
+		orgField: options.orgField,
+		resolve: periodResolver({
+			scope: "fiscal",
+			PeriodModel: options.FiscalPeriodModel,
+			orgField: options.orgField
+		})
+	});
+}
+const defaultTaxSelector = (acc) => acc.taxMetadata != null;
+function taxLockPlugin(options) {
+	const { TaxPeriodModel, AccountModel, JournalEntryModel, orgField } = options;
+	const isTaxAffecting = options.isTaxAffecting ?? defaultTaxSelector;
+	const deriveFilter = options.deriveFilter ?? ((data) => ({
+		jurisdiction: data.jurisdiction,
+		taxType: data.taxType
+	}));
+	return createLockPlugin({
+		scope: "tax",
+		accountSelector: isTaxAffecting,
+		AccountModel,
+		JournalEntryModel,
+		orgField,
+		resolve: periodResolver({
+			scope: "tax",
+			PeriodModel: TaxPeriodModel,
+			startField: "periodStart",
+			endField: "periodEnd",
+			closedField: "status",
+			closedValue: { $ne: "open" },
+			labelField: "jurisdiction",
+			subTypeField: "taxType",
+			externalRefField: "returnRef",
+			orgField,
+			extraQuery: (ctx) => {
+				const filter = deriveFilter(ctx.data);
+				if (!filter) return void 0;
+				const out = {};
+				if (filter.jurisdiction) out.jurisdiction = filter.jurisdiction;
+				if (filter.taxType) out.taxType = filter.taxType;
+				return Object.keys(out).length ? out : void 0;
+			}
+		})
+	});
+}
+function dailyLockPlugin(options) {
+	return createLockPlugin({
+		scope: "daily",
+		JournalEntryModel: options.JournalEntryModel,
+		orgField: options.orgField,
+		resolve: watermarkResolver({
+			scope: "daily",
+			getWatermark: options.getLastClosedDate,
+			formatLabel: (watermark) => `day closed through ${watermark.toISOString().split("T")[0]}`
+		})
+	});
+}
+//#endregion
+//#region src/plugins/credit-limit.plugin.ts
+function creditLimitPlugin(options) {
+	const { arControlAccountId, getCreditLimit, partnerField = "partnerId", JournalEntryModel, orgField, toleranceCents = 0 } = options;
+	const arControlStr = String(arControlAccountId);
+	return {
+		name: "accounting:credit-limit",
+		apply(repo) {
+			repo.on("before:create", async (context) => {
+				const data = context.data;
+				if (!data) return;
+				if (context._ledgerInternal) return;
+				if (data.state !== "posted") return;
+				const items = data.journalItems ?? [];
+				if (items.length === 0) return;
+				const session = context.session ?? null;
+				const newExposureByPartner = /* @__PURE__ */ new Map();
+				for (const item of items) {
+					if (String(item.account) !== arControlStr) continue;
+					const delta = (item.debit ?? 0) - (item.credit ?? 0);
+					if (delta <= 0) continue;
+					const partner = item[partnerField];
+					if (partner == null) throw Errors.validation(`creditLimitPlugin: A/R item missing required "${partnerField}" — every credit-sale line must carry a partner reference.`);
+					const key = String(partner);
+					newExposureByPartner.set(key, (newExposureByPartner.get(key) ?? 0) + delta);
+				}
+				if (newExposureByPartner.size === 0) return;
+				for (const [partnerKey, newDelta] of newExposureByPartner) {
+					const limit = await getCreditLimit(partnerKey, session);
+					if (limit == null) continue;
+					const orgFilter = {};
+					if (orgField && context[orgField] != null) orgFilter[orgField] = context[orgField];
+					else if (orgField && data[orgField] != null) orgFilter[orgField] = data[orgField];
+					const pipeline = [
+						{ $match: {
+							state: "posted",
+							...orgFilter
+						} },
+						{ $unwind: "$journalItems" },
+						{ $match: {
+							"journalItems.account": arControlAccountId,
+							[`journalItems.${partnerField}`]: partnerKey,
+							$or: [{ "journalItems.matchingNumber": null }, { "journalItems.matchingNumber": { $exists: false } }]
+						} },
+						{ $group: {
+							_id: null,
+							outstanding: { $sum: { $subtract: [{ $ifNull: ["$journalItems.debit", 0] }, { $ifNull: ["$journalItems.credit", 0] }] } }
+						} }
+					];
+					const currentOutstanding = (await JournalEntryModel.aggregate(pipeline).session(session))[0]?.outstanding ?? 0;
+					const projected = currentOutstanding + newDelta;
+					if (projected > limit + toleranceCents) throw new AccountingError(`Credit limit exceeded for partner ${partnerKey}: projected ${projected}c > limit ${limit}c (current ${currentOutstanding}c + new ${newDelta}c).`, 402, "CREDIT_LIMIT_EXCEEDED", [
+						{
+							path: partnerField,
+							issue: "over credit limit",
+							value: partnerKey
+						},
+						{
+							path: "limit",
+							issue: "partner credit limit in cents",
+							value: limit
+						},
+						{
+							path: "currentOutstanding",
+							issue: "existing open A/R in cents",
+							value: currentOutstanding
+						},
+						{
+							path: "newExposure",
+							issue: "new debit being posted in cents",
+							value: newDelta
+						}
+					]);
+				}
+			});
+		}
+	};
+}
+//#endregion
+//#region src/plugins/fx-realization.plugin.ts
+function fxRealizationPlugin(options) {
+	const { journalEntries, realizedGainAccount, realizedLossAccount, baseCurrency, orgField } = options;
+	return {
+		name: "accounting:fx-realization",
+		apply(repo) {
+			repo.on("after:match", async (ctx) => {
+				const { reconciliation, items, sharedCurrency, session } = ctx;
+				if (!sharedCurrency || sharedCurrency === baseCurrency) return;
+				const rates = items.map((i) => i.exchangeRate).filter((r) => typeof r === "number" && r > 0);
+				if (rates.length < 2) return;
+				if (rates.every((r) => r === rates[0])) return;
+				const baseNet = items.reduce((sum, it) => sum + it.debit - it.credit, 0);
+				if (baseNet === 0) return;
+				const gain = baseNet > 0;
+				const absAmount = Math.abs(baseNet);
+				const accountId = reconciliation.account;
+				const matchingNumber = reconciliation.matchingNumber;
+				const orgId = orgField ? reconciliation[orgField] : void 0;
+				const fxItems = gain ? [{
+					account: realizedGainAccount,
+					debit: 0,
+					credit: absAmount
+				}, {
+					account: accountId,
+					debit: absAmount,
+					credit: 0
+				}] : [{
+					account: realizedLossAccount,
+					debit: absAmount,
+					credit: 0
+				}, {
+					account: accountId,
+					debit: 0,
+					credit: absAmount
+				}];
+				const entryData = {
+					journalType: "MISC",
+					state: "posted",
+					date: /* @__PURE__ */ new Date(),
+					label: `FX realization for ${matchingNumber}`,
+					journalItems: fxItems
+				};
+				if (orgField && orgId != null) entryData[orgField] = orgId;
+				const created = await journalEntries.create(entryData, {
+					session,
+					_ledgerInternal: "fxRealize"
+				});
+				await repo.Model.updateOne({ matchingNumber }, { $set: { fxRealizationEntry: created._id } }, { session: session ?? void 0 });
+			});
+		}
+	};
+}
+//#endregion
+export { taxLockPlugin as a, createLockPlugin as c, fiscalLockPlugin as i, idempotencyPlugin as l, creditLimitPlugin as n, watermarkResolver as o, dailyLockPlugin as r, periodResolver as s, fxRealizationPlugin as t, doubleEntryPlugin as u };