@classytic/ledger 0.1.3

package/dist/idempotency.plugin-C6r8RI8d.mjs

@@ -0,0 +1,165 @@
+import { n as Errors } from "./errors-CeqRahE-.mjs";
+
+//#region src/plugins/double-entry.plugin.ts
+function doubleEntryPlugin(options = {}) {
+	const { onlyOnPost = true, JournalEntryModel, AccountModel, orgField } = options;
+	function validateItems(items, data) {
+		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) throw Errors.validation(`Invalid journal item at index ${i}: a line cannot have both debit (${d}) and credit (${c}) greater than zero.`);
+			if (d === 0 && c === 0) throw Errors.validation(`Invalid journal item at index ${i}: a line cannot have both debit and credit equal to zero.`);
+		}
+		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)}`);
+		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 accountIds = items.map((i) => i.account).filter((a) => a != null && a !== "");
+				if (accountIds.length === 0) throw Errors.validation("Posted entry has items with missing accounts.");
+				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 missingCount = accountIds.filter((id) => !foundIds.has(String(id))).length;
+				if (missingCount > 0) throw Errors.validation(`${missingCount} item(s) reference non-existent accounts.`);
+				if (orgField && data[orgField] != null) {
+					const dataOrg = String(data[orgField]);
+					const crossTenant = accounts.filter((a) => String(a[orgField]) !== dataOrg);
+					if (crossTenant.length > 0) throw Errors.validation(`${crossTenant.length} item(s) reference accounts from another organization.`);
+				}
+			};
+			const validateUpdate = async (context) => {
+				const data = context.data;
+				if (!data) return;
+				if (JournalEntryModel) {
+					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", (payload) => validate(payload));
+			repo.on("before:update", (payload) => validateUpdate(payload));
+		}
+	};
+}
+
+//#endregion
+//#region src/plugins/fiscal-lock.plugin.ts
+function fiscalLockPlugin(options) {
+	const { FiscalPeriodModel, JournalEntryModel, orgField } = options;
+	return {
+		name: "accounting:fiscal-lock",
+		apply(repo) {
+			const checkPeriod = async (context, isUpdate) => {
+				const data = context.data;
+				if (!data) return;
+				if (data.state !== "posted") 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("fiscalLockPlugin: update context is missing \"id\". Cannot validate fiscal lock without document ID.");
+					if (!JournalEntryModel) throw new Error("fiscalLockPlugin: JournalEntryModel is required to validate partial updates that set state to \"posted\". Pass JournalEntryModel in plugin options.");
+					const selectFields = orgField ? `date ${orgField}` : "date";
+					persistedDoc = await JournalEntryModel.findById(context.id).select(selectFields).session(session).lean();
+					if (persistedDoc?.date) entryDate = new Date(persistedDoc.date);
+				}
+				if (!entryDate) return;
+				const query = {
+					startDate: { $lte: entryDate },
+					endDate: { $gte: entryDate },
+					closed: true
+				};
+				if (orgField) {
+					let 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(`fiscalLockPlugin: orgField "${orgField}" is configured but could not be resolved from payload, context, or persisted document. Refusing to run unscoped fiscal period query.`);
+					query[orgField] = orgValue;
+				}
+				const closedPeriod = await FiscalPeriodModel.findOne(query).session(session).lean();
+				if (closedPeriod) {
+					const period = closedPeriod;
+					throw Errors.fiscal(`Cannot post entry dated ${entryDate.toISOString().split("T")[0]}: fiscal period "${period.name}" is closed.`);
+				}
+			};
+			repo.on("before:create", (payload) => checkPeriod(payload, false));
+			repo.on("before:update", (payload) => checkPeriod(payload, true));
+		}
+	};
+}
+
+//#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 (raw) => {
+				const context = raw;
+				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
+export { fiscalLockPlugin as n, doubleEntryPlugin as r, idempotencyPlugin as t };
+//# sourceMappingURL=idempotency.plugin-C6r8RI8d.mjs.map

package/dist/idempotency.plugin-C6r8RI8d.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.plugin-C6r8RI8d.mjs","names":[],"sources":["../src/plugins/double-entry.plugin.ts","../src/plugins/fiscal-lock.plugin.ts","../src/plugins/idempotency.plugin.ts"],"sourcesContent":["/**\r\n * Double-Entry Validation Plugin for @classytic/mongokit\r\n *\r\n * Ensures every journal entry posted via the repository satisfies:\r\n *   sum(debits) === sum(credits)\r\n *\r\n * Plugs into the before:create and before:update hooks.\r\n */\r\n\r\nimport type { Model } from 'mongoose';\r\nimport { Errors } from '../utils/errors.js';\r\n\r\n/** Minimal interface matching @classytic/mongokit RepositoryInstance */\r\ninterface RepositoryInstance {\r\n  on(event: string, listener: (data: unknown) => void | Promise<void>): unknown;\r\n}\r\n\r\nexport interface DoubleEntryPluginOptions {\r\n  /** Only enforce on posted entries (default: true) */\r\n  onlyOnPost?: boolean;\r\n  /** Mongoose model — required to validate partial updates that only set state */\r\n  JournalEntryModel?: Model<unknown>;\r\n  /** Account model — when provided, posted creates verify account existence + tenant scoping */\r\n  AccountModel?: Model<unknown>;\r\n  /** Multi-tenant org field name (e.g. 'business'). Required for tenant-account integrity checks. */\r\n  orgField?: string;\r\n}\r\n\r\nexport function doubleEntryPlugin(options: DoubleEntryPluginOptions = {}) {\r\n  const { onlyOnPost = true, JournalEntryModel, AccountModel, orgField } = options;\r\n\r\n  function validateItems(\r\n    items: Array<{ debit?: number; credit?: number }>,\r\n    data: Record<string, unknown>,\r\n  ): void {\r\n    // Each line must be debit OR credit (not both), and cannot be zero-value\r\n    for (let i = 0; i < items.length; i++) {\r\n      const d = items[i].debit ?? 0;\r\n      const c = items[i].credit ?? 0;\r\n      if (d > 0 && c > 0) {\r\n        throw Errors.validation(\r\n          `Invalid journal item at index ${i}: a line cannot have both debit (${d}) and credit (${c}) greater than zero.`,\r\n        );\r\n      }\r\n      if (d === 0 && c === 0) {\r\n        throw Errors.validation(\r\n          `Invalid journal item at index ${i}: a line cannot have both debit and credit equal to zero.`,\r\n        );\r\n      }\r\n    }\r\n\r\n    const totalDebit = items.reduce((s, i) => s + (i.debit ?? 0), 0);\r\n    const totalCredit = items.reduce((s, i) => s + (i.credit ?? 0), 0);\r\n\r\n    // Integer cents — exact comparison, no floating-point drift possible.\r\n    if (totalDebit !== totalCredit) {\r\n      throw Errors.validation(\r\n        `Double-entry violation: debits (${totalDebit}) ≠ credits (${totalCredit}). ` +\r\n        `Difference: ${Math.abs(totalDebit - totalCredit)}`,\r\n      );\r\n    }\r\n\r\n    // Sync totals onto the data object\r\n    data.totalDebit = totalDebit;\r\n    data.totalCredit = totalCredit;\r\n  }\r\n\r\n  return {\r\n    name: 'accounting:double-entry',\r\n    apply(repo: RepositoryInstance) {\r\n      const validate = async (context: Record<string, unknown>) => {\r\n        const data = context.data as Record<string, unknown> | undefined;\r\n        if (!data) return;\r\n\r\n        // Skip draft entries if configured\r\n        if (onlyOnPost && data.state !== 'posted') return;\r\n\r\n        const items = data.journalItems as Array<{ debit?: number; credit?: number; account?: unknown }> | undefined;\r\n\r\n        // Posted entries must have at least 2 journal items\r\n        if (data.state === 'posted' && (!items || items.length < 2)) {\r\n          throw Errors.validation(\r\n            `Cannot post entry: at least 2 journal items required, got ${items?.length ?? 0}.`,\r\n          );\r\n        }\r\n\r\n        if (!items || items.length === 0) return;\r\n\r\n        validateItems(items, data);\r\n\r\n        // Account existence + tenant-account integrity (fail-closed for posted creates)\r\n        if (data.state === 'posted') {\r\n          if (!AccountModel) {\r\n            throw new Error(\r\n              'doubleEntryPlugin: AccountModel is required to validate posted entries. ' +\r\n              'Pass AccountModel in plugin options to enable account existence and tenant integrity checks.',\r\n            );\r\n          }\r\n          await validateAccounts(items, data, context);\r\n        }\r\n      };\r\n\r\n      /** Verify all journal item accounts exist and belong to the same org */\r\n      const validateAccounts = async (\r\n        items: Array<{ account?: unknown }>,\r\n        data: Record<string, unknown>,\r\n        context: Record<string, unknown>,\r\n      ) => {\r\n        const accountIds = items\r\n          .map(i => i.account)\r\n          .filter(a => a != null && a !== '');\r\n\r\n        if (accountIds.length === 0) {\r\n          throw Errors.validation('Posted entry has items with missing accounts.');\r\n        }\r\n\r\n        const selectFields = orgField ? `_id ${orgField}` : '_id';\r\n        const accounts = await AccountModel!.find({ _id: { $in: accountIds } })\r\n          .select(selectFields)\r\n          .session((context.session as import('mongoose').ClientSession) ?? null)\r\n          .lean() as Array<Record<string, unknown>>;\r\n\r\n        // Check all accounts exist\r\n        const foundIds = new Set(accounts.map(a => String(a._id)));\r\n        const missingCount = accountIds.filter(id => !foundIds.has(String(id))).length;\r\n        if (missingCount > 0) {\r\n          throw Errors.validation(\r\n            `${missingCount} item(s) reference non-existent accounts.`,\r\n          );\r\n        }\r\n\r\n        // Check tenant scoping\r\n        if (orgField && data[orgField] != null) {\r\n          const dataOrg = String(data[orgField]);\r\n          const crossTenant = accounts.filter(a => String(a[orgField]) !== dataOrg);\r\n          if (crossTenant.length > 0) {\r\n            throw Errors.validation(\r\n              `${crossTenant.length} item(s) reference accounts from another organization.`,\r\n            );\r\n          }\r\n        }\r\n      };\r\n\r\n      const validateUpdate = async (context: Record<string, unknown>) => {\r\n        const data = context.data as Record<string, unknown> | undefined;\r\n        if (!data) return;\r\n\r\n        // ── Immutability guard: block modifications to posted entries ──────\r\n        // Allow: idempotent state re-set (state: 'posted')\r\n        // Block: everything else — including reversed/reversedBy (only settable via\r\n        //        reverse() which uses entry.save() directly, bypassing this hook)\r\n        if (JournalEntryModel) {\r\n          const id = context.id;\r\n          if (id) {\r\n            // Check if target entry is already posted\r\n            const target = await JournalEntryModel.findById(id)\r\n              .select('state')\r\n              .session((context.session as import('mongoose').ClientSession) ?? null)\r\n              .lean() as Record<string, unknown> | null;\r\n\r\n            if (target?.state === 'posted') {\r\n              // Block any state transition away from 'posted' (immutable ledger)\r\n              if (data.state !== undefined && data.state !== 'posted') {\r\n                throw Errors.immutable(\r\n                  'Cannot change state of a posted journal entry. Posted entries are immutable.',\r\n                );\r\n              }\r\n\r\n              // Only allow idempotent state re-set on posted entries.\r\n              // reversed/reversedBy are NOT allowed through repository.update() —\r\n              // reverse() uses entry.save() directly to bypass the plugin, so any\r\n              // attempt to set these flags through the generic update path is illegitimate.\r\n              const allowedKeys = new Set(['state']);\r\n              const dataKeys = Object.keys(data);\r\n              const hasDisallowedKeys = dataKeys.some(k => !allowedKeys.has(k));\r\n\r\n              if (hasDisallowedKeys) {\r\n                throw Errors.immutable(\r\n                  'Cannot modify a posted journal entry. Use reverse() to create a correcting entry instead.',\r\n                );\r\n              }\r\n            }\r\n          }\r\n        }\r\n\r\n        if (onlyOnPost && data.state !== 'posted') return;\r\n\r\n        const items = data.journalItems as Array<{ debit?: number; credit?: number }> | undefined;\r\n\r\n        if (items !== undefined) {\r\n          // Items present in payload — validate directly\r\n          if (items.length < 2) {\r\n            throw Errors.validation(\r\n              `Cannot post entry: at least 2 journal items required, got ${items.length}.`,\r\n            );\r\n          }\r\n          validateItems(items, data);\r\n\r\n          // Account existence + tenant-account integrity (when AccountModel provided)\r\n          if (AccountModel) {\r\n            await validateAccounts(items as Array<{ account?: unknown }>, data, context);\r\n          }\r\n          return;\r\n        }\r\n\r\n        // state → posted but no journalItems in payload: fetch the persisted doc\r\n        if (!JournalEntryModel) {\r\n          throw new Error(\r\n            'doubleEntryPlugin: JournalEntryModel is required to validate partial updates that set state to \"posted\". ' +\r\n            'Pass JournalEntryModel in plugin options.',\r\n          );\r\n        }\r\n\r\n        const id = context.id;\r\n        if (!id) {\r\n          throw new Error(\r\n            'doubleEntryPlugin: update context is missing \"id\". Cannot validate partial post without document ID.',\r\n          );\r\n        }\r\n\r\n        const existing = await JournalEntryModel.findById(id)\r\n          .select('journalItems')\r\n          .session((context.session as import('mongoose').ClientSession) ?? null)\r\n          .lean() as Record<string, unknown> | null;\r\n\r\n        if (!existing) return; // will 404 downstream\r\n\r\n        const persistedItems = existing.journalItems as Array<{ debit?: number; credit?: number; account?: unknown }> | undefined;\r\n        if (!persistedItems || persistedItems.length < 2) {\r\n          throw Errors.validation(\r\n            `Cannot post entry: at least 2 journal items required, got ${persistedItems?.length ?? 0}.`,\r\n          );\r\n        }\r\n\r\n        validateItems(persistedItems, data);\r\n\r\n        // Account existence + tenant-account integrity (when AccountModel provided)\r\n        if (AccountModel) {\r\n          await validateAccounts(persistedItems, { ...data, ...existing }, context);\r\n        }\r\n      };\r\n\r\n      repo.on('before:create', (payload: unknown) => validate(payload as Record<string, unknown>));\r\n      repo.on('before:update', (payload: unknown) => validateUpdate(payload as Record<string, unknown>));\r\n    },\r\n  };\r\n}\r\n","/**\r\n * Fiscal Lock Plugin for @classytic/mongokit\r\n *\r\n * Prevents journal entries from being created or posted\r\n * in a closed fiscal period.\r\n *\r\n * Requires a FiscalPeriod model to check against.\r\n */\r\n\r\nimport type { Model, ClientSession } from 'mongoose';\r\nimport { Errors } from '../utils/errors.js';\r\n\r\n/** Minimal interface matching @classytic/mongokit RepositoryInstance */\r\ninterface RepositoryInstance {\r\n  on(event: string, listener: (data: unknown) => void | Promise<void>): unknown;\r\n}\r\n\r\nexport interface FiscalLockPluginOptions {\r\n  /** Mongoose model for fiscal periods */\r\n  FiscalPeriodModel: Model<unknown>;\r\n  /** Mongoose model for journal entries — needed to look up persisted date on partial updates */\r\n  JournalEntryModel?: Model<unknown>;\r\n  /** Organization field name (for multi-tenant) */\r\n  orgField?: string;\r\n}\r\n\r\nexport function fiscalLockPlugin(options: FiscalLockPluginOptions) {\r\n  const { FiscalPeriodModel, JournalEntryModel, orgField } = options;\r\n\r\n  return {\r\n    name: 'accounting:fiscal-lock',\r\n    apply(repo: RepositoryInstance) {\r\n      const checkPeriod = async (context: Record<string, unknown>, isUpdate: boolean) => {\r\n        const data = context.data as Record<string, unknown> | undefined;\r\n        if (!data) return;\r\n\r\n        // Only check when posting or creating posted entries\r\n        if (data.state !== 'posted') return;\r\n\r\n        const session = (context.session as ClientSession) ?? null;\r\n\r\n        // Resolve the entry date (and org field from persisted doc if needed)\r\n        let entryDate: Date | undefined;\r\n        let persistedDoc: Record<string, unknown> | null = null;\r\n\r\n        if (data.date) {\r\n          entryDate = new Date(data.date as string | number | Date);\r\n        } else if (!isUpdate) {\r\n          // Create without explicit date — schema will default to now, so check against now\r\n          entryDate = new Date();\r\n        } else {\r\n          // Partial update without date — fetch the persisted doc\r\n          if (!context.id) {\r\n            throw new Error(\r\n              'fiscalLockPlugin: update context is missing \"id\". Cannot validate fiscal lock without document ID.',\r\n            );\r\n          }\r\n          if (!JournalEntryModel) {\r\n            throw new Error(\r\n              'fiscalLockPlugin: JournalEntryModel is required to validate partial updates that set state to \"posted\". ' +\r\n              'Pass JournalEntryModel in plugin options.',\r\n            );\r\n          }\r\n          const selectFields = orgField ? `date ${orgField}` : 'date';\r\n          persistedDoc = await JournalEntryModel.findById(context.id)\r\n            .select(selectFields)\r\n            .session(session)\r\n            .lean() as Record<string, unknown> | null;\r\n          if (persistedDoc?.date) {\r\n            entryDate = new Date(persistedDoc.date as string | number | Date);\r\n          }\r\n        }\r\n\r\n        if (!entryDate) return; // No date to check against (new entry without date defaults to draft)\r\n\r\n        // Build query\r\n        const query: Record<string, unknown> = {\r\n          startDate: { $lte: entryDate },\r\n          endDate: { $gte: entryDate },\r\n          closed: true,\r\n        };\r\n\r\n        // Multi-tenant scope — check payload, context, then persisted doc\r\n        if (orgField) {\r\n          let orgValue = data[orgField] ?? context[orgField];\r\n\r\n          if (!orgValue && isUpdate) {\r\n            // Org field not in payload or context — resolve from persisted doc\r\n            if (persistedDoc) {\r\n              orgValue = persistedDoc[orgField];\r\n            } else if (context.id && JournalEntryModel) {\r\n              const persisted = await JournalEntryModel.findById(context.id)\r\n                .select(orgField)\r\n                .session(session)\r\n                .lean() as Record<string, unknown> | null;\r\n              if (persisted) orgValue = persisted[orgField];\r\n            }\r\n          }\r\n\r\n          if (!orgValue) {\r\n            throw new Error(\r\n              `fiscalLockPlugin: orgField \"${orgField}\" is configured but could not be resolved from ` +\r\n              'payload, context, or persisted document. Refusing to run unscoped fiscal period query.',\r\n            );\r\n          }\r\n\r\n          query[orgField] = orgValue;\r\n        }\r\n\r\n        const closedPeriod = await FiscalPeriodModel.findOne(query).session(session).lean();\r\n\r\n        if (closedPeriod) {\r\n          const period = closedPeriod as Record<string, unknown>;\r\n          throw Errors.fiscal(\r\n            `Cannot post entry dated ${entryDate.toISOString().split('T')[0]}: ` +\r\n            `fiscal period \"${period.name}\" is closed.`,\r\n          );\r\n        }\r\n      };\r\n\r\n      repo.on('before:create', (payload: unknown) => checkPeriod(payload as Record<string, unknown>, false));\r\n      repo.on('before:update', (payload: unknown) => checkPeriod(payload as Record<string, unknown>, true));\r\n    },\r\n  };\r\n}\r\n","/**\r\n * Idempotency Plugin for @classytic/mongokit\r\n *\r\n * Prevents duplicate journal entries by checking for existing entries\r\n * with the same idempotency key before creation.\r\n */\r\n\r\nimport type { Model, ClientSession } from 'mongoose';\r\nimport { Errors } from '../utils/errors.js';\r\n\r\n/** Minimal interface matching @classytic/mongokit RepositoryInstance */\r\ninterface RepositoryInstance {\r\n  on(event: string, listener: (data: unknown) => void | Promise<void>): unknown;\r\n}\r\n\r\nexport interface IdempotencyPluginOptions {\r\n  /** Mongoose model for journal entries */\r\n  JournalEntryModel: Model<unknown>;\r\n  /** Multi-tenant org field name */\r\n  orgField?: string;\r\n}\r\n\r\nexport function idempotencyPlugin(options: IdempotencyPluginOptions) {\r\n  const { JournalEntryModel, orgField } = options;\r\n\r\n  return {\r\n    name: 'accounting:idempotency',\r\n    apply(repo: RepositoryInstance) {\r\n      repo.on('before:create', async (raw: unknown) => {\r\n        const context = raw as Record<string, unknown>;\r\n        const data = context.data as Record<string, unknown> | undefined;\r\n        if (!data?.idempotencyKey) return;\r\n\r\n        const query: Record<string, unknown> = {\r\n          idempotencyKey: data.idempotencyKey,\r\n        };\r\n        if (orgField && data[orgField]) {\r\n          query[orgField] = data[orgField];\r\n        }\r\n\r\n        const existing = await JournalEntryModel.findOne(query)\r\n          .select('_id')\r\n          .session((context.session as ClientSession) ?? null)\r\n          .lean() as Record<string, unknown> | null;\r\n\r\n        if (existing) {\r\n          throw Errors.conflict(\r\n            `Duplicate idempotency key: \"${data.idempotencyKey}\". Existing entry: ${existing._id}`,\r\n          );\r\n        }\r\n      });\r\n    },\r\n  };\r\n}\r\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,308 @@
+import { _ as TaxMetadata, a as Cents, c as DateRange, d as JournalType, f as MainType, g as TaxDetail, h as StatementType, i as CategoryKey, l as EntryState, m as ObjectId, n as CashFlowCategory, o as Currency, p as NormalBalance, s as DateOption, t as AccountType, u as JournalItem, v as TotalAccountOp } from "./core-Cx0baosR.mjs";
+import { _ as getNormalBalance, a as JOURNAL_CODES, b as isValidCategory, c as getJournalTypeCodes, d as CATEGORY_KEYS, i as isValidCurrency, l as isValidJournalType, n as getCurrency, o as JOURNAL_TYPES, r as getMinorUnit, t as CURRENCIES, u as CATEGORIES, v as isBalanceSheet, y as isIncomeStatement } from "./currencies-Bkn3FNkC.mjs";
+import { CountryPack, CountryPackInput, TaxCode, TaxCodesByRegion, TaxReportLine, TaxReportTemplate, defineCountryPack } from "./country/index.mjs";
+import { _ as PopulatedJournalEntry, a as exportToCsv, h as FlatJournalRow, m as ExportFieldMap, n as quickbooksFieldMap, p as ExportField, r as flattenJournalEntries, t as universalFieldMap } from "./universal-x33ZJODp.mjs";
+import { Money, abs, add, allocate, equals, format, formatPlain, fromDecimal, isNegative, isPositive, isValid, isZero, max, min, multiply, negate, parseCents, percentage, round, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal } from "./money.mjs";
+import { n as defaultLogger, t as Logger } from "./logger-Cv6VVc4r.mjs";
+import { a as SchemaOptions, i as MultiTenantConfig, n as AuditConfig, o as StrictnessConfig, r as JournalSchemaOptions, t as AccountingEngineConfig } from "./engine-Cd73EOT6.mjs";
+import { n as createJournalEntrySchema, r as createAccountSchema, t as createFiscalPeriodSchema } from "./fiscal-period.schema-DI2scngu.mjs";
+import { i as fiscalLockPlugin, n as idempotencyPlugin, o as doubleEntryPlugin } from "./idempotency.plugin-BESs9YPD.mjs";
+import { C as ReportAccount, D as TaxReturnSummary, E as TaxReport, O as TrialBalanceReport, S as LedgerEntry, T as ReportGroup, _ as CashFlowReport, a as reopenFiscalPeriod, b as GeneralLedgerReport, d as generateIncomeStatement, g as BalanceSheetReport, h as generateTrialBalance, i as closeFiscalPeriod, k as TrialBalanceRow, l as generateGeneralLedger, p as generateBalanceSheet, s as generateCashFlow, v as CashFlowSection, w as ReportCategory, x as IncomeStatementReport, y as GeneralLedgerAccount } from "./fiscal-close-CzUzpnMg.mjs";
+import { n as wireJournalEntryMethods, t as wireAccountMethods } from "./account.repository-1C2sZvB2.mjs";
+import * as mongoose$1 from "mongoose";
+import { ClientSession, Connection, Model } from "mongoose";
+
+//#region src/engine.d.ts
+declare class AccountingEngine {
+  readonly config: AccountingEngineConfig;
+  readonly country: CountryPack;
+  readonly currency: string;
+  readonly money: {
+    readonly round: typeof round;
+    readonly fromDecimal: typeof fromDecimal;
+    readonly toDecimal: typeof toDecimal;
+    readonly add: typeof add;
+    readonly subtract: typeof subtract;
+    readonly multiply: typeof multiply;
+    readonly percentage: typeof percentage;
+    readonly splitTaxInclusive: typeof splitTaxInclusive;
+    readonly splitTaxExclusive: typeof splitTaxExclusive;
+    readonly allocate: typeof allocate;
+    readonly equals: typeof equals;
+    readonly isZero: typeof isZero;
+    readonly isPositive: typeof isPositive;
+    readonly isNegative: typeof isNegative;
+    readonly abs: typeof abs;
+    readonly negate: typeof negate;
+    readonly min: typeof min;
+    readonly max: typeof max;
+    readonly format: typeof format;
+    readonly formatPlain: typeof formatPlain;
+    readonly isValid: typeof isValid;
+    readonly parseCents: typeof parseCents;
+  };
+  constructor(config: AccountingEngineConfig);
+  createAccountSchema(options?: SchemaOptions): mongoose$1.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+    timestamps: true;
+  }, any, any, unknown, {
+    [x: string]: any;
+  } & Required<{
+    _id: unknown;
+  }> & {
+    __v: number;
+  }>;
+  createJournalEntrySchema(accountModelName: string, options?: JournalSchemaOptions): mongoose$1.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+    timestamps: true;
+  }, any, any, unknown, {
+    [x: string]: any;
+  } & Required<{
+    _id: unknown;
+  }> & {
+    __v: number;
+  }>;
+  createFiscalPeriodSchema(options?: SchemaOptions): mongoose$1.Schema<any, Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
+    timestamps: true;
+  }, any, any, unknown, {
+    [x: string]: any;
+  } & Required<{
+    _id: unknown;
+  }> & {
+    __v: number;
+  }>;
+  createReports(models: {
+    Account: Model<unknown>;
+    JournalEntry: Model<unknown>;
+  }): {
+    trialBalance: (params: {
+      organizationId?: unknown;
+      dateOption: "month" | "quarter" | "year" | "custom";
+      dateValue: unknown;
+      accountId?: string;
+      filters?: Record<string, unknown>;
+    }) => Promise<TrialBalanceReport>;
+    balanceSheet: (params: {
+      organizationId?: unknown;
+      dateOption: "month" | "quarter" | "year" | "custom";
+      dateValue: unknown;
+      businessName?: string;
+      filters?: Record<string, unknown>;
+    }) => Promise<BalanceSheetReport>;
+    incomeStatement: (params: {
+      organizationId?: unknown;
+      dateOption: "month" | "quarter" | "year" | "custom";
+      dateValue: unknown;
+      businessName?: string;
+      filters?: Record<string, unknown>;
+    }) => Promise<IncomeStatementReport>;
+    generalLedger: (params: {
+      organizationId?: unknown;
+      dateOption: "month" | "quarter" | "year" | "custom";
+      dateValue: unknown;
+      accountId?: string;
+      filters?: Record<string, unknown>;
+    }) => Promise<GeneralLedgerReport>;
+    cashFlow: (params: {
+      organizationId?: unknown;
+      dateOption: "month" | "quarter" | "year" | "custom";
+      dateValue: unknown;
+      businessName?: string;
+      filters?: Record<string, unknown>;
+    }) => Promise<CashFlowReport>;
+  };
+  /** Get all posting account types (accounts you can post transactions to) */
+  getPostingAccountTypes(): readonly AccountType[];
+  /** Validate an account type code */
+  isValidAccountType(code: string): boolean;
+  /** Get account type definition by code */
+  getAccountType(code: string): AccountType | undefined;
+  /** Get tax codes for a region */
+  getTaxCodesForRegion(region: string): TaxCode[];
+  /**
+   * Create a fully-configured journal entry repository with secure plugin wiring.
+   * This is the **recommended** way to set up journal entry repositories.
+   *
+   * Includes:
+   * - Double-entry plugin with account existence + tenant integrity validation
+   * - Fiscal lock plugin (when FiscalPeriodModel is provided)
+   * - post(), unpost(), reverse(), and duplicate() domain methods
+   *
+   * @param createRepository - The `createRepository` function from @classytic/mongokit
+   * @param models.JournalEntryModel - Mongoose model for journal entries
+   * @param models.AccountModel - Mongoose model for accounts (required for secure posted-create validation)
+   * @param models.FiscalPeriodModel - Mongoose model for fiscal periods (optional, enables fiscal lock)
+   * @param additionalPlugins - Extra plugins to include (e.g. timestampPlugin)
+   * @returns A wired repository with post(), unpost(), reverse(), duplicate(), and all plugins configured
+   */
+  createJournalEntryRepository(createRepository: (model: Model<unknown>, plugins: any[]) => any, models: {
+    JournalEntryModel: Model<unknown>;
+    AccountModel: Model<unknown>;
+    FiscalPeriodModel?: Model<unknown>;
+  }, additionalPlugins?: any[]): any;
+  /**
+   * Wire post/reverse domain methods onto a mongokit Repository
+   * for journal entries. The repository must already be created via
+   * `createRepository(Model, plugins)` from @classytic/mongokit.
+   *
+   * **Note:** Prefer `createJournalEntryRepository()` which guarantees
+   * secure plugin wiring. This method only adds domain methods and does
+   * not validate plugin configuration.
+   *
+   * @param repository - An existing mongokit Repository instance
+   * @param JournalEntryModel - The Mongoose model for journal entries
+   * @returns The same repository, now with `.post()` and `.reverse()`
+   */
+  wireJournalEntryRepository(repository: any, JournalEntryModel: Model<unknown>): any;
+  /**
+   * Wire seedAccounts/bulkCreate and posting-account validation onto a
+   * mongokit Repository for accounts. The repository must already be
+   * created via `createRepository(Model, plugins)` from @classytic/mongokit.
+   *
+   * @param repository - An existing mongokit Repository instance
+   * @param AccountModel - The Mongoose model for accounts
+   * @returns The same repository, now with `.seedAccounts()` and `.bulkCreate()`
+   */
+  wireAccountRepository(repository: any, AccountModel: Model<unknown>): any;
+}
+declare function createAccountingEngine(config: AccountingEngineConfig): AccountingEngine;
+//#endregion
+//#region src/utils/date-range.d.ts
+/**
+ * Compute start/end dates from a date option + value.
+ *
+ * Examples:
+ *   getDateRange('month', '2025-03')            → Mar 1 – Mar 31
+ *   getDateRange('quarter', { quarter: 2, year: 2025 }) → Apr 1 – Jun 30
+ *   getDateRange('year', 2025)                  → Jan 1 – Dec 31
+ *   getDateRange('custom', { startDate, endDate })
+ */
+declare function getDateRange(option: DateOption, value: unknown): DateRange;
+/** Get fiscal year start date for a given date and fiscal start month */
+declare function getFiscalYearStart(date: Date, fiscalStartMonth?: number): Date;
+//#endregion
+//#region src/utils/account-helpers.d.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.
+ */
+declare function isVirtualTaxAccount(accountType: AccountType, accountMap: Map<string, AccountType>): boolean;
+/**
+ * Calculate a total from sub-accounts using the totalAccountTypes formula.
+ * @param formula - Array of { account, operation } instructions
+ * @param balanceMap - Map of account code → balance
+ */
+declare function calculateTotal(formula: readonly TotalAccountOp[], balanceMap: Map<string, number>): number;
+/**
+ * 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
+ */
+declare function computeEndingBalance(category: CategoryKey, totalDebit: number, totalCredit: number): number;
+/**
+ * Build a lookup map from an array of account types.
+ */
+declare function buildAccountTypeMap(accountTypes: readonly AccountType[]): Map<string, AccountType>;
+//#endregion
+//#region src/utils/errors.d.ts
+/**
+ * Typed error for the accounting package.
+ * Carries HTTP status + machine-readable code.
+ * Replaces all ad-hoc `(error as ...).status = N` patterns.
+ */
+declare class AccountingError extends Error {
+  readonly status: number;
+  readonly code: string;
+  constructor(message: string, status?: number, code?: string);
+}
+/** Convenience factory functions */
+declare const Errors: {
+  readonly validation: (msg: string) => AccountingError;
+  readonly notFound: (msg: string) => AccountingError;
+  readonly conflict: (msg: string) => AccountingError;
+  readonly immutable: (msg: string) => AccountingError;
+  readonly fiscal: (msg: string) => AccountingError;
+};
+//#endregion
+//#region src/utils/session.d.ts
+interface SessionResult {
+  session: ClientSession | null;
+  ownSession: boolean;
+}
+/**
+ * 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.
+ */
+declare function acquireSession(db: Connection, externalSession: ClientSession | undefined | null, logger?: Logger): Promise<SessionResult>;
+/**
+ * Finalize an owned session: commit or abort, then always end.
+ */
+declare function finalizeSession(session: ClientSession | null, ownSession: boolean, success: boolean): Promise<void>;
+//#endregion
+//#region src/utils/filter-builder.d.ts
+/**
+ * Filter Builder — Sanitizes user-supplied dimension filters for aggregation pipelines.
+ *
+ * Prevents injection of dangerous MongoDB operators while allowing
+ * standard equality and comparison filters on custom dimension fields.
+ */
+/**
+ * Build a sanitized filter object from user-supplied dimension filters.
+ * Blocks dangerous operators ($where, $expr, $function, etc.).
+ *
+ * @param filters - Key-value filters (e.g. { 'journalItems.departmentId': 'dept-1' })
+ * @returns Sanitized filter object safe for $match stages
+ * @throws Error if a blocked operator is used
+ */
+declare function buildItemFilters(filters?: Record<string, unknown>): Record<string, unknown>;
+//#endregion
+//#region src/types/contracts.d.ts
+/** A single line produced by a subledger for posting */
+interface SubledgerJournalItem {
+  /** Account type code (resolved to ObjectId by the app layer) */
+  accountCode: string;
+  /** Integer cents */
+  debit: number;
+  /** Integer cents */
+  credit: number;
+  /** Line-item description */
+  label?: string;
+  /** Extra dimension fields (departmentId, projectId, etc.) */
+  extraFields?: Record<string, unknown>;
+}
+/** The shape of a journal entry that a subledger produces */
+interface SubledgerPostingInput {
+  journalType: string;
+  label: string;
+  date: Date;
+  journalItems: SubledgerJournalItem[];
+  /** Prevents duplicate postings on retry */
+  idempotencyKey?: string;
+  /** Arbitrary metadata for the entry (stored via extraFields) */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Contract that subledger posting adapters must implement.
+ *
+ * @typeParam TSource - The source document type (e.g., Invoice, Bill, PayrollRun)
+ */
+interface PostingContract<TSource = unknown> {
+  /** Unique name for this subledger (e.g. 'billing', 'inventory', 'payroll') */
+  readonly name: string;
+  /** Convert a source document into one or more journal entry inputs */
+  toJournalEntries(source: TSource): SubledgerPostingInput[];
+  /** Validate that the source document is ready to post. Throws on failure. */
+  validate(source: TSource): void;
+}
+/** Result of a subledger posting operation */
+interface PostingResult {
+  journalEntryIds: (string | ObjectId)[];
+  idempotencyKeys?: string[];
+}
+//#endregion
+export { type AccountType, AccountingEngine, type AccountingEngineConfig, AccountingError, type AuditConfig, type BalanceSheetReport, CATEGORIES, CATEGORY_KEYS, CURRENCIES, type CashFlowCategory, type CashFlowReport, type CashFlowSection, type CategoryKey, type Cents, type CountryPack, type CountryPackInput, type Currency, type DateOption, type DateRange, type EntryState, Errors, type ExportField, type ExportFieldMap, type FlatJournalRow, type GeneralLedgerAccount, type GeneralLedgerReport, type IncomeStatementReport, JOURNAL_CODES, JOURNAL_TYPES, type JournalItem, type JournalSchemaOptions, type JournalType, type LedgerEntry, type Logger, type MainType, Money, type MultiTenantConfig, type NormalBalance, type PopulatedJournalEntry, type PostingContract, type PostingResult, type ReportAccount, type ReportCategory, type ReportGroup, type SchemaOptions, type SessionResult, type StatementType, type StrictnessConfig, type SubledgerJournalItem, type SubledgerPostingInput, type TaxCode, type TaxCodesByRegion, type TaxDetail, type TaxMetadata, type TaxReport, type TaxReportLine, type TaxReportTemplate, type TaxReturnSummary, type TotalAccountOp, type TrialBalanceReport, type TrialBalanceRow, acquireSession, add, allocate, buildAccountTypeMap, buildItemFilters, calculateTotal, closeFiscalPeriod, computeEndingBalance, createAccountSchema, createAccountingEngine, createFiscalPeriodSchema, createJournalEntrySchema, defaultLogger, defineCountryPack, doubleEntryPlugin, exportToCsv, finalizeSession, fiscalLockPlugin, flattenJournalEntries, format, formatPlain, fromDecimal, generateBalanceSheet, generateCashFlow, generateGeneralLedger, generateIncomeStatement, generateTrialBalance, getCurrency, getDateRange, getFiscalYearStart, getJournalTypeCodes, getMinorUnit, getNormalBalance, idempotencyPlugin, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, isVirtualTaxAccount, multiply, parseCents, percentage, quickbooksFieldMap, reopenFiscalPeriod, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, wireAccountMethods, wireJournalEntryMethods };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/engine.ts","../src/utils/date-range.ts","../src/utils/account-helpers.ts","../src/utils/errors.ts","../src/utils/session.ts","../src/utils/filter-builder.ts","../src/types/contracts.ts"],"mappings":"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"}