@classytic/ledger 0.8.0 → 0.9.0

package/dist/bridges/index.d.mts

@@ -0,0 +1,2 @@
+import { a as EntryReversedNotification, c as PeriodLockedNotification, i as SourceRef, l as ReconciliationMismatchNotification, n as SourceBridge, o as NotificationBridge, r as SourceBridgeContext, s as NotificationBridgeContext, t as LedgerBridges } from "../index-dqkjgpII.mjs";
+export { EntryReversedNotification, LedgerBridges, NotificationBridge, NotificationBridgeContext, PeriodLockedNotification, ReconciliationMismatchNotification, SourceBridge, SourceBridgeContext, SourceRef };

package/dist/bridges/index.mjs

@@ -0,0 +1 @@
+export {};

package/dist/constants/index.d.mts

@@ -1,2 +1,2 @@
-import { S as isValidCategory, _ as getCategoryMainType, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, g as extractStatementType, h as extractMainType, i as getJournalType, l as getCurrency, m as categoryKey, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, v as getCategoryStatementType, x as isIncomeStatement, y as getNormalBalance } from "../journals-Dd4A9TN3.mjs";
+import { S as isValidCategory, _ as getCategoryMainType, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, g as extractStatementType, h as extractMainType, i as getJournalType, l as getCurrency, m as categoryKey, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, v as getCategoryStatementType, x as isIncomeStatement, y as getNormalBalance } from "../journals-DUpWwFt1.mjs";
 export { CATEGORIES, CATEGORY_KEYS, CURRENCIES, JOURNAL_CODES, JOURNAL_TYPES, categoryKey, extractMainType, extractStatementType, getCategoryMainType, getCategoryStatementType, getCurrency, getCustomJournalTypes, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, registerJournalType };

package/dist/constants/index.mjs

@@ -1,3 +1,3 @@
-import { a as JOURNAL_CODES, c as getCustomJournalTypes, d as isValidJournalType, f as registerJournalType, i as isValidCurrency, l as getJournalType, n as getCurrency, o as JOURNAL_TYPES, r as getMinorUnit, t as CURRENCIES, u as getJournalTypeCodes } from "../currencies-CsuBGfgs.mjs";
-import { a as extractStatementType, c as getNormalBalance, d as isValidCategory, i as extractMainType, l as isBalanceSheet, n as CATEGORY_KEYS, o as getCategoryMainType, r as categoryKey, s as getCategoryStatementType, t as CATEGORIES, u as isIncomeStatement } from "../categories-BkKdv16V.mjs";
+import { a as JOURNAL_CODES, c as getCustomJournalTypes, d as isValidJournalType, f as registerJournalType, i as isValidCurrency, l as getJournalType, n as getCurrency, o as JOURNAL_TYPES, r as getMinorUnit, t as CURRENCIES, u as getJournalTypeCodes } from "../currencies-Jo5oaM_4.mjs";
+import { a as extractStatementType, c as getNormalBalance, d as isValidCategory, i as extractMainType, l as isBalanceSheet, n as CATEGORY_KEYS, o as getCategoryMainType, r as categoryKey, s as getCategoryStatementType, t as CATEGORIES, u as isIncomeStatement } from "../categories-FJlrvzcl.mjs";
 export { CATEGORIES, CATEGORY_KEYS, CURRENCIES, JOURNAL_CODES, JOURNAL_TYPES, categoryKey, extractMainType, extractStatementType, getCategoryMainType, getCategoryStatementType, getCurrency, getCustomJournalTypes, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, registerJournalType };

package/dist/country/index.d.mts

@@ -1,2 +1,2 @@
-import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "../index-RNZsX0Yo.mjs";
+import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "../index-08IpHhrU.mjs";
 export { CountryPack, CountryPackInput, JournalTemplate, defineCountryPack };

package/dist/errors-BI5k4iak.mjs

@@ -0,0 +1,121 @@
+//#region src/utils/errors.ts
+var AccountingError = class extends Error {
+	status;
+	code;
+	fields;
+	constructor(message, status = 400, code = "ACCOUNTING_ERROR", fields) {
+		super(message);
+		this.name = "AccountingError";
+		this.status = status;
+		this.code = code;
+		if (fields && fields.length > 0) this.fields = Object.freeze([...fields]);
+	}
+	/** Serialize to a plain object for API responses and logs. */
+	toJSON() {
+		return {
+			name: this.name,
+			message: this.message,
+			status: this.status,
+			code: this.code,
+			...this.fields ? { fields: this.fields } : {}
+		};
+	}
+};
+const Errors = {
+	validation: (msg, fields) => new AccountingError(msg, 400, "VALIDATION_ERROR", fields),
+	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"),
+	locked: (scope, msg, fields) => new AccountingError(msg, 409, `PERIOD_LOCKED_${scope.toUpperCase()}`, fields)
+};
+/**
+* Thrown when an idempotent create was attempted with a key that already
+* resolved to a different winner (not the common "same winner, same payload"
+* replay — that returns the existing doc without throwing).
+*
+* Typically surfaces when the host supplies an `idempotencyKey` that collides
+* with a logically-different prior write.
+*/
+var IdempotencyConflictError = class extends AccountingError {
+	idempotencyKey;
+	existingId;
+	constructor(idempotencyKey, existingId, message) {
+		super(message ?? `Idempotency key "${idempotencyKey}" already resolved to entry ${String(existingId)}.`, 409, "IDEMPOTENCY_CONFLICT");
+		this.name = "IdempotencyConflictError";
+		this.idempotencyKey = idempotencyKey;
+		this.existingId = existingId;
+	}
+};
+/**
+* Thrown when the unique `referenceNumber` index fires. With the new atomic
+* counter this should be effectively impossible — if it ever throws, it
+* indicates either a pre-atomic-counter doc that was hand-inserted OR a bug
+* in the counter partitioning.
+*/
+var DuplicateReferenceError = class extends AccountingError {
+	referenceNumber;
+	constructor(referenceNumber, message) {
+		super(message ?? `Duplicate reference number "${referenceNumber}".`, 409, "DUPLICATE_REFERENCE_NUMBER");
+		this.name = "DuplicateReferenceError";
+		this.referenceNumber = referenceNumber;
+	}
+};
+/**
+* Thrown when an optimistic-concurrency FSM transition fails because another
+* writer advanced the state or version between our read and our write.
+*
+* Callers should re-fetch the doc and decide whether to retry or surface.
+*/
+var ConcurrencyError = class extends AccountingError {
+	resource;
+	resourceId;
+	constructor(resource, resourceId, message) {
+		super(message ?? `${resource} ${String(resourceId)} was modified by another writer — retry after re-fetch.`, 409, "CONCURRENCY_CONFLICT");
+		this.name = "ConcurrencyError";
+		this.resource = resource;
+		this.resourceId = resourceId;
+	}
+};
+/**
+* Thrown when a mutation targets an entry that is protected by immutability —
+* either `strictness.immutable` or the double-entry plugin's posted-entry
+* guard. Factory `Errors.immutable(msg)` returns this subclass so callers
+* can `instanceof`-match without sniffing the `code` field.
+*/
+var ImmutableViolationError = class extends AccountingError {
+	entryId;
+	constructor(entryId, message, fields) {
+		super(message ?? `Entry ${String(entryId)} is posted and immutable. Use reverse() to correct it.`, 403, "IMMUTABLE_ENTRY", fields);
+		this.name = "ImmutableViolationError";
+		this.entryId = entryId;
+	}
+};
+Errors.immutable = (msg, fields) => new ImmutableViolationError(null, msg, fields);
+/**
+* Detect a Mongo duplicate-key error (11000) and return the index name the
+* conflict hit on, so callers can switch on which unique key fired.
+*
+* Handles both driver-style and mongoose-style error shapes. Safe to call
+* with any `unknown` — returns `null` when the error is not a dup-key.
+*/
+function classifyDuplicateKey(err) {
+	if (!err || typeof err !== "object") return null;
+	const e = err;
+	const code = typeof e.code === "number" ? e.code : typeof e.code === "string" ? Number(e.code) : void 0;
+	const isDriverDup = code === 11e3 || e.name === "MongoServerError" && code === 11e3 || Array.isArray(e.writeErrors) && e.writeErrors.some((w) => w?.code === 11e3);
+	const wrappedMsgMatch = typeof e.message === "string" ? e.message.match(/^Duplicate value for ([a-zA-Z_.0-9,\s]+?)(?:\s*\(|$)/) : null;
+	const isMongokitDup = e.status === 409 && !!wrappedMsgMatch;
+	if (!isDriverDup && !isMongokitDup) return null;
+	let keyPattern = e.keyPattern;
+	if (!keyPattern && Array.isArray(e.writeErrors)) keyPattern = e.writeErrors.find((w) => w?.code === 11e3)?.keyPattern;
+	if (!keyPattern && wrappedMsgMatch) {
+		const fields = wrappedMsgMatch[1].split(",").map((f) => f.trim()).filter(Boolean);
+		keyPattern = Object.fromEntries(fields.map((f) => [f, 1]));
+	}
+	return {
+		indexName: keyPattern ? Object.keys(keyPattern).join("_") : typeof e.message === "string" && e.message.match(/index: ([^\s]+)/)?.[1] ? e.message.match(/index: ([^\s]+)/)[1] : "unknown",
+		keyPattern
+	};
+}
+//#endregion
+export { IdempotencyConflictError as a, Errors as i, ConcurrencyError as n, ImmutableViolationError as o, DuplicateReferenceError as r, classifyDuplicateKey as s, AccountingError as t };

package/dist/events/index.d.mts

@@ -0,0 +1,2 @@
+import { C as EntryReversedPayload, D as ReconciliationUnmatchedPayload, E as ReconciliationMatchedPayload, O as LEDGER_EVENTS, S as EntryPostedPayload, T as JournalSeededPayload, _ as AccountBulkCreatedPayload, a as OutboxOwnershipError, b as EntryCreatedPayload, c as InProcessLedgerBus, d as createEvent, f as DomainEvent, g as PublishManyResult, h as EventTransport, i as OutboxFailOptions, k as LedgerEventName, l as InProcessLedgerBusOptions, m as EventLogger, n as OutboxClaimOptions, o as OutboxStore, p as EventHandler, r as OutboxErrorInfo, s as OutboxWriteOptions, t as OutboxAcknowledgeOptions, u as EventContext, v as AccountSeededPayload, w as EntryUnpostedPayload, x as EntryDuplicatedPayload, y as EntryArchivedPayload } from "../outbox-store-UYC4eZpI.mjs";
+export { type AccountBulkCreatedPayload, type AccountSeededPayload, type DomainEvent, type EntryArchivedPayload, type EntryCreatedPayload, type EntryDuplicatedPayload, type EntryPostedPayload, type EntryReversedPayload, type EntryUnpostedPayload, type EventContext, type EventHandler, type EventLogger, type EventTransport, InProcessLedgerBus, type InProcessLedgerBusOptions, type JournalSeededPayload, LEDGER_EVENTS, type LedgerEventName, type OutboxAcknowledgeOptions, type OutboxClaimOptions, type OutboxErrorInfo, type OutboxFailOptions, OutboxOwnershipError, type OutboxStore, type OutboxWriteOptions, type PublishManyResult, type ReconciliationMatchedPayload, type ReconciliationUnmatchedPayload, createEvent };

package/dist/events/index.mjs

@@ -0,0 +1,2 @@
+import { i as LEDGER_EVENTS, n as InProcessLedgerBus, r as createEvent, t as OutboxOwnershipError } from "../outbox-store-DQbL-KYT.mjs";
+export { InProcessLedgerBus, LEDGER_EVENTS, OutboxOwnershipError, createEvent };

package/dist/exports/index.d.mts

@@ -1,2 +1,2 @@
-import { _ as PopulatedJournalEntry, a as exportToCsv, c as getHeaders, d as serializeCsv, f as CsvOptions, g as PopulatedAccount, h as FlatJournalRow, i as quickbooksFieldMap, l as buildCsv, m as ExportFieldMap, n as flattenJournalEntry, o as extractAllRows, p as ExportField, r as universalFieldMap, s as extractRow, t as flattenJournalEntries, u as escapeCell, v as PopulatedJournalItem } from "../index-bCEeSzdO.mjs";
+import { _ as PopulatedJournalEntry, a as exportToCsv, c as getHeaders, d as serializeCsv, f as CsvOptions, g as PopulatedAccount, h as FlatJournalRow, i as quickbooksFieldMap, l as buildCsv, m as ExportFieldMap, n as flattenJournalEntry, o as extractAllRows, p as ExportField, r as universalFieldMap, s as extractRow, t as flattenJournalEntries, u as escapeCell, v as PopulatedJournalItem } from "../index-J-XIbXH-.mjs";
 export { CsvOptions, ExportField, ExportFieldMap, FlatJournalRow, PopulatedAccount, PopulatedJournalEntry, PopulatedJournalItem, buildCsv, escapeCell, exportToCsv, extractAllRows, extractRow, flattenJournalEntries, flattenJournalEntry, getHeaders, quickbooksFieldMap, serializeCsv, universalFieldMap };

package/dist/exports/index.mjs

@@ -1,2 +1,2 @@
-import { a as exportToCsv, c as getHeaders, d as serializeCsv, i as quickbooksFieldMap, l as buildCsv, n as flattenJournalEntry, o as extractAllRows, r as universalFieldMap, s as extractRow, t as flattenJournalEntries, u as escapeCell } from "../exports-B3whucXe.mjs";
+import { a as exportToCsv, c as getHeaders, d as serializeCsv, i as quickbooksFieldMap, l as buildCsv, n as flattenJournalEntry, o as extractAllRows, r as universalFieldMap, s as extractRow, t as flattenJournalEntries, u as escapeCell } from "../exports-C30yRapf.mjs";
 export { buildCsv, escapeCell, exportToCsv, extractAllRows, extractRow, flattenJournalEntries, flattenJournalEntry, getHeaders, quickbooksFieldMap, serializeCsv, universalFieldMap };

package/dist/{fx-realization.plugin-DDVK-oYO.mjs → fx-realization.plugin-Bxlb8cIx.mjs}

@@ -1,4 +1,4 @@
-import { n as Errors, t as AccountingError } from "./errors-CSDQPNyt.mjs";
+import { a as IdempotencyConflictError, i as Errors, t as AccountingError } from "./errors-BI5k4iak.mjs";
 //#region src/plugins/double-entry.plugin.ts
 function doubleEntryPlugin(options = {}) {
 	const { onlyOnPost = true, JournalEntryModel, AccountModel, orgField } = options;
@@ -166,7 +166,7 @@ function idempotencyPlugin(options) {
 				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}`);
+				if (existing) throw new IdempotencyConflictError(data.idempotencyKey, existing._id);
 			});
 			repo.on("before:createMany", async (context) => {
 				const docs = context.dataArray;

package/dist/{index-RNZsX0Yo.d.mts → index-08IpHhrU.d.mts}

@@ -1,4 +1,4 @@
-import { t as AccountType } from "./core-MpgjCqK0.mjs";
+import { t as AccountType } from "./core-DwjkrRkJ.mjs";
 
 //#region src/country/index.d.ts
 /**

package/dist/index-dqkjgpII.d.mts

@@ -0,0 +1,104 @@
+//#region src/bridges/notification.bridge.d.ts
+/**
+ * NotificationBridge — host-implemented delivery for ledger-originated alerts.
+ *
+ * The ledger generates operational alerts that hosts may want to route to
+ * email, Slack, in-app notifications, or an audit/compliance system:
+ *
+ *   - `periodLocked` — a fiscal period was locked (audit sign-off)
+ *   - `periodUnlocked` — a locked period was re-opened (requires elevated role)
+ *   - `entryReversed` — a posted entry was reversed (accounting correction)
+ *   - `reconciliationMismatch` — match debit/credit totals differ (FX gain/loss)
+ *
+ * This is deliberately thin — richer integrations should subscribe to the
+ * EventTransport (§11-14) and route via their own notification stack.
+ * NotificationBridge exists for hosts that want a direct callback without
+ * owning an event bus.
+ *
+ * All methods are optional. Skip the bridge entirely if the host uses events.
+ */
+interface NotificationBridgeContext {
+  organizationId?: unknown;
+  actorId?: unknown;
+  correlationId?: string;
+}
+interface PeriodLockedNotification {
+  periodId: unknown;
+  startDate: Date;
+  endDate: Date;
+  lockedBy?: unknown;
+}
+interface EntryReversedNotification {
+  originalEntryId: unknown;
+  reversalEntryId: unknown;
+  reversalDate: Date;
+  reversedBy?: unknown;
+  reason?: string;
+}
+interface ReconciliationMismatchNotification {
+  matchingNumber: string;
+  account: unknown;
+  debitTotal: number;
+  creditTotal: number;
+  difference: number;
+  currency: string | null;
+}
+interface NotificationBridge {
+  onPeriodLocked?(payload: PeriodLockedNotification, ctx: NotificationBridgeContext): Promise<void>;
+  onPeriodUnlocked?(payload: PeriodLockedNotification, ctx: NotificationBridgeContext): Promise<void>;
+  onEntryReversed?(payload: EntryReversedNotification, ctx: NotificationBridgeContext): Promise<void>;
+  onReconciliationMismatch?(payload: ReconciliationMismatchNotification, ctx: NotificationBridgeContext): Promise<void>;
+}
+//#endregion
+//#region src/bridges/source.bridge.d.ts
+/**
+ * SourceBridge — host-implemented resolver for polymorphic external references.
+ *
+ * Ledger journal entries commonly carry a `reference`/`externalRef` pointing
+ * at a source document that lives outside the ledger package — an Invoice,
+ * Payment, Payroll Run, Stripe Charge, ERP voucher, etc. Storing these as
+ * opaque `String + sourceModel` (per PACKAGE_RULES §7) keeps the ledger
+ * transport-agnostic: the same schema works whether the source lives in the
+ * same Mongo, a different Mongo, Postgres, or an external REST API.
+ *
+ * Hosts implement `SourceBridge` to hydrate those refs when building
+ * enriched views (partner ledger with invoice details, audit trail with
+ * payment metadata, reconciliation UI with source documents, etc.).
+ *
+ * All methods are optional. Features that need resolution degrade gracefully
+ * when a bridge is not provided.
+ */
+interface SourceRef {
+  sourceId: string;
+  sourceModel: string;
+}
+interface SourceBridgeContext {
+  organizationId?: unknown;
+  actorId?: unknown;
+  [key: string]: unknown;
+}
+interface SourceBridge {
+  /**
+   * Resolve a single external reference.
+   *
+   * Return `null` when the source cannot be found (deleted, permission
+   * denied, wrong model). Do not throw for missing sources — callers
+   * expect `null` for graceful degradation.
+   */
+  resolve?(sourceId: string, sourceModel: string, ctx: SourceBridgeContext): Promise<unknown | null>;
+  /**
+   * Batch resolver — avoids N+1 round-trips when enriching a list.
+   * Key the returned map by `sourceId`. Missing sources may be omitted or
+   * mapped to `null` at the implementer's discretion.
+   */
+  resolveMany?(refs: ReadonlyArray<SourceRef>, ctx: SourceBridgeContext): Promise<Map<string, unknown>>;
+}
+//#endregion
+//#region src/bridges/index.d.ts
+/** Collected bridges exposed as `engine.bridges`. */
+interface LedgerBridges {
+  source?: SourceBridge;
+  notification?: NotificationBridge;
+}
+//#endregion
+export { EntryReversedNotification as a, PeriodLockedNotification as c, SourceRef as i, ReconciliationMismatchNotification as l, SourceBridge as n, NotificationBridge as o, SourceBridgeContext as r, NotificationBridgeContext as s, LedgerBridges as t };