@classytic/ledger 0.10.3 → 0.11.0

package/dist/sync/index.mjs

@@ -1,530 +0,0 @@
-import { t as buildOpeningBalanceEntry } from "../opening-balance-1cixYh6Y.mjs";
-//#region src/sync/ledger-bridge.ts
-const isCustomerSide = (t) => t === "out_invoice" || t === "out_refund" || t === "receipt";
-const isRefund = (t) => t === "out_refund" || t === "in_refund";
-const JOURNAL_TYPE_MAP = {
-	out_invoice: "SALES",
-	in_invoice: "PURCHASES",
-	out_refund: "SALES",
-	in_refund: "PURCHASES",
-	receipt: "CASH_RECEIPTS"
-};
-/**
-* Create a LedgerBridge implementation backed by a @classytic/ledger engine.
-*
-* @param engine - The accounting engine (or any object matching the minimal
-*   shape: `{ record: { adjustment, payment }, repositories: { journalEntries: { reverse } } }`)
-* @param config - Account mapping configuration
-* @returns A LedgerBridge that the invoice engine can use
-*/
-function createLedgerBridge(engine, config) {
-	const { accounts } = config;
-	return {
-		async createJournalEntry(input) {
-			const customerSide = isCustomerSide(input.moveType);
-			const refund = isRefund(input.moveType);
-			const isReceipt = input.moveType === "receipt";
-			const balanceSheetAccount = customerSide ? isReceipt && config.receiptAccount ? config.receiptAccount : accounts.receivable : accounts.payable;
-			const incomeOrExpenseAccount = customerSide ? accounts.revenue : accounts.expense;
-			const taxAccount = customerSide ? accounts.taxPayable : accounts.taxReceivable;
-			const lines = [];
-			if (customerSide && !refund) {
-				lines.push({
-					account: balanceSheetAccount,
-					debit: input.totalAmount,
-					label: `Invoice ${input.invoiceId}`
-				});
-				for (const line of input.lines) lines.push({
-					account: incomeOrExpenseAccount,
-					credit: line.amount,
-					label: line.description
-				});
-				if (input.taxAmount > 0) lines.push({
-					account: taxAccount,
-					credit: input.taxAmount,
-					label: "Tax"
-				});
-			} else if (customerSide && refund) {
-				lines.push({
-					account: balanceSheetAccount,
-					credit: input.totalAmount,
-					label: `Credit Note ${input.invoiceId}`
-				});
-				for (const line of input.lines) lines.push({
-					account: incomeOrExpenseAccount,
-					debit: line.amount,
-					label: line.description
-				});
-				if (input.taxAmount > 0) lines.push({
-					account: taxAccount,
-					debit: input.taxAmount,
-					label: "Tax reversal"
-				});
-			} else if (!customerSide && !refund) {
-				for (const line of input.lines) lines.push({
-					account: incomeOrExpenseAccount,
-					debit: line.amount,
-					label: line.description
-				});
-				if (input.taxAmount > 0) lines.push({
-					account: taxAccount,
-					debit: input.taxAmount,
-					label: "Tax"
-				});
-				lines.push({
-					account: balanceSheetAccount,
-					credit: input.totalAmount,
-					label: `Bill ${input.invoiceId}`
-				});
-			} else {
-				lines.push({
-					account: balanceSheetAccount,
-					debit: input.totalAmount,
-					label: `Vendor Credit ${input.invoiceId}`
-				});
-				for (const line of input.lines) lines.push({
-					account: incomeOrExpenseAccount,
-					credit: line.amount,
-					label: line.description
-				});
-				if (input.taxAmount > 0) lines.push({
-					account: taxAccount,
-					credit: input.taxAmount,
-					label: "Tax reversal"
-				});
-			}
-			const label = input.notes ? `${input.moveType} ${input.invoiceId} — ${input.notes}` : `${input.moveType} ${input.invoiceId}`;
-			const result = await engine.record.adjustment(input.organizationId, {
-				date: input.date,
-				lines,
-				label,
-				journalType: JOURNAL_TYPE_MAP[input.moveType] ?? "GENERAL"
-			}, input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {});
-			return String(result._id);
-		},
-		async reverseJournalEntry(journalEntryId, _reason, ctx) {
-			const options = {};
-			if (ctx.actorId) options.actorId = ctx.actorId;
-			if (ctx.session) options.session = ctx.session;
-			const result = await engine.repositories.journalEntries.reverse(journalEntryId, ctx.organizationId, options);
-			return String(result.reversal._id);
-		},
-		async recordPayment(input) {
-			let fromAccount;
-			let toAccount;
-			if (config.resolvePaymentAccounts) {
-				const resolved = config.resolvePaymentAccounts(input);
-				fromAccount = resolved.receivableOrPayable;
-				toAccount = resolved.cash;
-			} else {
-				fromAccount = accounts.receivable;
-				toAccount = accounts.cash;
-			}
-			const result = await engine.record.payment(input.organizationId, {
-				date: input.date,
-				amount: input.amount,
-				fromReceivableAccount: fromAccount,
-				toCashAccount: toAccount,
-				label: `Payment ${input.paymentId} for ${input.invoiceId}`
-			}, { idempotencyKey: `payment:${input.paymentId}` });
-			return String(result._id);
-		}
-	};
-}
-//#endregion
-//#region src/sync/mappers/bank-statement.ts
-function bankStatementMapper(config) {
-	return {
-		externalId: (txn) => txn.externalId,
-		toJournalEntry: (txn, _ctx) => {
-			const cents = Number(txn.amount.amount);
-			const absCents = Math.abs(cents);
-			const isInflow = cents > 0;
-			const counterAccount = config.categorize?.(txn) ?? config.suspenseAccountId;
-			const label = [
-				config.labelPrefix ?? "Import",
-				txn.description,
-				txn.counterparty?.name
-			].filter(Boolean).join(" — ");
-			return {
-				date: txn.postedDate,
-				label,
-				referenceNumber: txn.externalId,
-				journalItems: isInflow ? [{
-					account: config.bankAccountId,
-					debit: absCents,
-					credit: 0
-				}, {
-					account: counterAccount,
-					debit: 0,
-					credit: absCents
-				}] : [{
-					account: counterAccount,
-					debit: absCents,
-					credit: 0
-				}, {
-					account: config.bankAccountId,
-					debit: 0,
-					credit: absCents
-				}],
-				extra: {
-					_importSource: txn.type ?? "bank-import",
-					_importCounterparty: txn.counterparty?.name,
-					_importReference: txn.reference
-				}
-			};
-		}
-	};
-}
-//#endregion
-//#region src/sync/mappers/invoice.ts
-function invoiceMapper(config) {
-	return {
-		externalId: (inv) => inv.externalId,
-		toJournalEntry: (inv) => {
-			const isSales = inv.type === "sales";
-			const total = Number(inv.total.amount);
-			const taxTotal = Number(inv.taxTotal.amount);
-			const items = [];
-			if (isSales) items.push({
-				account: config.receivablesAccountId,
-				debit: total,
-				credit: 0
-			});
-			else items.push({
-				account: config.payablesAccountId,
-				debit: 0,
-				credit: total
-			});
-			for (const line of inv.lines) {
-				const lineAmount = Number(line.amount.amount);
-				const account = (line.accountCode ? config.resolveAccountCode?.(line.accountCode) : void 0) ?? (isSales ? config.defaultRevenueAccountId : config.defaultExpenseAccountId);
-				if (isSales) items.push({
-					account,
-					debit: 0,
-					credit: lineAmount,
-					label: line.description
-				});
-				else items.push({
-					account,
-					debit: lineAmount,
-					credit: 0,
-					label: line.description
-				});
-			}
-			if (taxTotal > 0) {
-				const taxAccount = isSales ? config.taxLiabilityAccountId : config.taxReceivableAccountId;
-				if (taxAccount) if (isSales) items.push({
-					account: taxAccount,
-					debit: 0,
-					credit: taxTotal
-				});
-				else items.push({
-					account: taxAccount,
-					debit: taxTotal,
-					credit: 0
-				});
-			}
-			return {
-				date: inv.issueDate,
-				label: `${isSales ? "Sales" : "Purchase"} Invoice — ${inv.contact.name ?? inv.externalId}`,
-				referenceNumber: inv.externalId,
-				journalItems: items,
-				extra: {
-					_importSource: "invoice-import",
-					_importContactName: inv.contact.name,
-					_importContactRef: inv.contact.reference
-				}
-			};
-		}
-	};
-}
-//#endregion
-//#region src/sync/mappers/journal-entry.ts
-function journalEntryMapper(config) {
-	return {
-		externalId: (je) => je.externalId,
-		toJournalEntry: (je) => ({
-			date: je.date,
-			label: je.narration ?? `Imported JE ${je.externalId}`,
-			referenceNumber: je.externalId,
-			journalItems: je.lines.map((line) => ({
-				account: config.resolveAccountCode(line.accountCode),
-				debit: line.debit ? Number(line.debit.amount) : 0,
-				credit: line.credit ? Number(line.credit.amount) : 0,
-				label: line.description
-			})),
-			extra: { _importSource: "journal-entry-import" }
-		})
-	};
-}
-//#endregion
-//#region src/sync/mappers/opening-balance.ts
-function openingBalanceMapper(config) {
-	return {
-		externalId: (_tb) => {
-			return `opening-balance:${config.cutoverDate.toISOString().split("T")[0]}`;
-		},
-		toJournalEntry: (tb, _ctx) => {
-			const balances = [];
-			for (const line of tb.lines) {
-				const net = (line.debit ? Number(line.debit.amount) : 0) - (line.credit ? Number(line.credit.amount) : 0);
-				if (net === 0) continue;
-				const resolved = config.resolveAccountCode(line.accountCode);
-				if (!resolved) continue;
-				balances.push({
-					accountCode: String(resolved),
-					balance: net
-				});
-			}
-			if (balances.length === 0) return null;
-			return buildOpeningBalanceEntry({
-				cutoverDate: config.cutoverDate,
-				balances,
-				equityAccountCode: String(config.equityAccountId)
-			}).entry;
-		}
-	};
-}
-//#endregion
-//#region src/sync/wire-export.ts
-function wireExport(args) {
-	const batchSize = args.options?.batchSize ?? 100;
-	const onProgress = args.options?.onProgress;
-	return { async run() {
-		const start = performance.now();
-		let emitted = 0;
-		const errors = [];
-		const entries = await args.journalEntries.getAll(args.query);
-		let batch = [];
-		for (const entry of entries) {
-			try {
-				const out = args.sink.fromJournalEntry(entry);
-				batch.push(out);
-			} catch (err) {
-				const id = entry?._id;
-				errors.push({
-					entryId: id ? String(id) : void 0,
-					message: err.message
-				});
-				continue;
-			}
-			if (batch.length >= batchSize) {
-				const count = batch.length;
-				await args.sink.emit(batch);
-				batch = [];
-				emitted += count;
-				onProgress?.({ emitted });
-			}
-		}
-		if (batch.length > 0) {
-			const count = batch.length;
-			await args.sink.emit(batch);
-			batch = [];
-			emitted += count;
-			onProgress?.({ emitted });
-		}
-		if (args.sink.flush) await args.sink.flush();
-		return {
-			ok: errors.length === 0,
-			emitted,
-			errors,
-			durationMs: performance.now() - start
-		};
-	} };
-}
-//#endregion
-//#region src/sync/wire-import.ts
-function wireImport(args) {
-	const batchSize = args.options?.batchSize ?? 100;
-	const strict = args.options?.strict ?? false;
-	const dryRun = args.options?.dryRun ?? false;
-	const journalType = args.options?.journalType ?? "GENERAL";
-	const onProgress = args.options?.onProgress;
-	const useBulk = !dryRun && typeof args.journalEntries.createMany === "function";
-	return { async run() {
-		const start = performance.now();
-		const ctx = {
-			organizationId: args.context.organizationId,
-			importedAt: /* @__PURE__ */ new Date(),
-			importRunId: args.context.importRunId
-		};
-		let inserted = 0;
-		let skipped = 0;
-		let failed = 0;
-		const errors = [];
-		let processed = 0;
-		const batch = [];
-		for await (const raw of toAsyncIterable(args.source)) {
-			batch.push(raw);
-			if (batch.length >= batchSize) {
-				const result = await processBatch(batch.splice(0));
-				inserted += result.inserted;
-				skipped += result.skipped;
-				failed += result.failed;
-				errors.push(...result.errors);
-				processed += result.processed;
-				if (strict && result.failed > 0) break;
-				onProgress?.({ processed });
-			}
-		}
-		if (batch.length > 0) {
-			const result = await processBatch(batch);
-			inserted += result.inserted;
-			skipped += result.skipped;
-			failed += result.failed;
-			errors.push(...result.errors);
-			processed += result.processed;
-			onProgress?.({ processed });
-		}
-		return {
-			ok: failed === 0,
-			inserted,
-			skipped,
-			failed,
-			errors,
-			durationMs: performance.now() - start
-		};
-		async function processBatch(records) {
-			let batchInserted = 0;
-			let batchSkipped = 0;
-			let batchFailed = 0;
-			const batchErrors = [];
-			const externalIds = [];
-			for (const raw of records) try {
-				externalIds.push(args.mapper.externalId(raw));
-			} catch (err) {
-				externalIds.push("");
-				batchErrors.push({
-					externalId: void 0,
-					message: `externalId() threw: ${err.message}`,
-					cause: err
-				});
-				batchFailed += 1;
-			}
-			const existingSet = /* @__PURE__ */ new Set();
-			const validIds = externalIds.filter((id) => id.length > 0);
-			if (validIds.length > 0 && args.findExisting) try {
-				const found = await args.findExisting(validIds, ctx.organizationId);
-				for (const id of found) existingSet.add(id);
-			} catch {}
-			const pendingDocs = [];
-			for (let i = 0; i < records.length; i++) {
-				const raw = records[i];
-				const externalId = externalIds[i];
-				if (!externalId) continue;
-				if (existingSet.has(externalId)) {
-					batchSkipped += 1;
-					continue;
-				}
-				let inputs;
-				try {
-					inputs = args.mapper.toJournalEntry(raw, ctx);
-				} catch (err) {
-					batchErrors.push({
-						externalId,
-						message: `toJournalEntry() threw: ${err.message}`,
-						cause: err
-					});
-					batchFailed += 1;
-					continue;
-				}
-				if (inputs === null) {
-					batchSkipped += 1;
-					continue;
-				}
-				const inputArray = Array.isArray(inputs) ? inputs : [inputs];
-				for (const input of inputArray) {
-					if (dryRun) {
-						batchInserted += 1;
-						continue;
-					}
-					const doc = {
-						journalType: input.journalType ?? journalType,
-						journal: input.journal,
-						label: input.label ?? "Import",
-						date: input.date,
-						journalItems: input.journalItems.map((item) => ({
-							account: item.account,
-							debit: item.debit,
-							credit: item.credit,
-							label: item.label,
-							currency: item.currency,
-							exchangeRate: item.exchangeRate,
-							originalDebit: item.originalDebit,
-							originalCredit: item.originalCredit,
-							matchingNumber: item.matchingNumber,
-							maturityDate: item.maturityDate
-						})),
-						_externalId: externalId,
-						state: "posted",
-						...ctx.organizationId !== void 0 ? { organizationId: ctx.organizationId } : {},
-						...ctx.importRunId ? { _importRunId: ctx.importRunId } : {},
-						...input.extra
-					};
-					pendingDocs.push({
-						externalId,
-						doc
-					});
-				}
-			}
-			if (dryRun || pendingDocs.length === 0) return {
-				inserted: batchInserted,
-				skipped: batchSkipped,
-				failed: batchFailed,
-				errors: batchErrors,
-				processed: records.length
-			};
-			if (useBulk) try {
-				await args.journalEntries.createMany?.(pendingDocs.map((p) => p.doc));
-				batchInserted += pendingDocs.length;
-			} catch (_err) {
-				for (const { externalId, doc } of pendingDocs) try {
-					await args.journalEntries.create(doc);
-					batchInserted += 1;
-				} catch (innerErr) {
-					const innerMsg = innerErr.message;
-					if (innerMsg.includes("idempotency") || innerMsg.includes("duplicate")) batchSkipped += 1;
-					else {
-						batchErrors.push({
-							externalId,
-							message: innerMsg,
-							cause: innerErr
-						});
-						batchFailed += 1;
-					}
-				}
-			}
-			else for (const { externalId, doc } of pendingDocs) try {
-				await args.journalEntries.create(doc);
-				batchInserted += 1;
-			} catch (err) {
-				const msg = err.message;
-				if (msg.includes("idempotency") || msg.includes("duplicate")) batchSkipped += 1;
-				else {
-					batchErrors.push({
-						externalId,
-						message: msg,
-						cause: err
-					});
-					batchFailed += 1;
-				}
-			}
-			return {
-				inserted: batchInserted,
-				skipped: batchSkipped,
-				failed: batchFailed,
-				errors: batchErrors,
-				processed: records.length
-			};
-		}
-	} };
-}
-function toAsyncIterable(source) {
-	if (Symbol.asyncIterator in Object(source)) return source;
-	return { async *[Symbol.asyncIterator]() {
-		for (const item of source) yield item;
-	} };
-}
-//#endregion
-export { bankStatementMapper, buildOpeningBalanceEntry, createLedgerBridge, invoiceMapper, journalEntryMapper, openingBalanceMapper, wireExport, wireImport };

package/dist/sync-JvchM3FO.d.mts

@@ -1,152 +0,0 @@
-import { a as Cents } from "./core-DwjkrRkJ.mjs";
-
-//#region src/types/sync.d.ts
-/**
- * Maps a raw record (from any source) into a JournalEntry creation payload.
- * The consumer passes this to wireImport. Reference implementations ship
- * for every fin-io canonical shape: ofxBankMapper, camtBankMapper, etc.
- */
-interface ImportMapper<TRaw> {
-  /**
-   * Transform one raw record into zero, one, or many JournalEntry inputs.
-   * Return null to skip a record (e.g. opening-balance entries).
-   */
-  toJournalEntry(raw: TRaw, ctx: ImportContext): JournalEntryInput | JournalEntryInput[] | null;
-  /**
-   * Stable, source-assigned unique ID for the raw record. Used for
-   * idempotent re-imports — wireImport checks for an existing entry
-   * with this idempotencyKey before creating.
-   */
-  externalId(raw: TRaw): string;
-}
-interface ImportContext {
-  organizationId: unknown;
-  /** When the import job started, for audit. */
-  importedAt: Date;
-  /** Optional run-scoped tag (e.g. 'monthly-bank-import-2026-04'). */
-  importRunId?: string;
-}
-/**
- * Minimal JournalEntry creation payload. This is what the mapper produces
- * and wireImport passes to `journalEntries.create()`. The shape matches
- * the AccountingEngine's expected create input.
- */
-interface JournalEntryInput {
-  journalType?: string;
-  journal?: unknown;
-  referenceNumber?: string;
-  label?: string;
-  date: Date;
-  journalItems: JournalItemInput[];
-  /** Extra fields injected into the entry doc (dimension fields, tags, etc.). */
-  extra?: Record<string, unknown>;
-}
-interface JournalItemInput {
-  account: unknown;
-  debit: Cents;
-  credit: Cents;
-  label?: string;
-  currency?: string;
-  exchangeRate?: number;
-  originalDebit?: Cents;
-  originalCredit?: Cents;
-  matchingNumber?: string;
-  maturityDate?: Date;
-}
-/**
- * Result of an import run. Always returned — never thrown. Errors on
- * individual records do NOT abort the run unless `strict: true`.
- */
-interface ImportReport {
-  ok: boolean;
-  inserted: number;
-  skipped: number;
-  failed: number;
-  errors: ImportError[];
-  durationMs: number;
-}
-interface ImportError {
-  externalId?: string;
-  message: string;
-  cause?: unknown;
-}
-/**
- * Maps a JournalEntry into an external format record. Used by wireExport.
- */
-interface ExportSink<TOut> {
-  fromJournalEntry(entry: unknown): TOut;
-  emit(records: TOut[]): Promise<void>;
-  flush?(): Promise<void>;
-}
-interface ExportReport {
-  ok: boolean;
-  emitted: number;
-  errors: Array<{
-    entryId?: string;
-    message: string;
-  }>;
-  durationMs: number;
-}
-interface WireImportArgs<TRaw> {
-  /** The raw records to import. */
-  source: Iterable<TRaw> | AsyncIterable<TRaw>;
-  /** Maps raw → JournalEntry input. */
-  mapper: ImportMapper<TRaw>;
-  /** The ledger's JournalEntry repository (from createRepositories()). */
-  journalEntries: {
-    create(data: Record<string, unknown>): Promise<unknown>;
-    /**
-     * Bulk create journal entries. When provided, wireImport uses this for
-     * batch inserts instead of per-record create() — dramatically faster
-     * for large imports (single round-trip per batch instead of N).
-     *
-     * Falls back to sequential create() if not provided.
-     */
-    createMany?(data: Record<string, unknown>[]): Promise<unknown[]>;
-    getAll(query: Record<string, unknown>): Promise<unknown[]>;
-  };
-  /** Organizational context. */
-  context: Pick<ImportContext, 'organizationId' | 'importRunId'>;
-  /**
-   * Optional callback that checks whether entries with the given
-   * referenceNumbers already exist. Returns the set of existing ones.
-   * If not provided, wireImport skips the pre-check and relies on
-   * create() errors (or the idempotency plugin) for dedup.
-   *
-   * Example using Mongoose Model directly:
-   *   findExisting: async (refNums, orgId) => {
-   *     const docs = await JournalEntry.find({
-   *       organizationId: orgId,
-   *       referenceNumber: { $in: refNums },
-   *     }).select('referenceNumber').lean();
-   *     return new Set(docs.map(d => d.referenceNumber));
-   *   }
-   */
-  findExisting?: (referenceNumbers: string[], organizationId: unknown) => Promise<Set<string>>;
-  options?: {
-    /** First error aborts the run. Default: false. */strict?: boolean; /** Entries per batch. Default: 100. */
-    batchSize?: number; /** Dry-run: do everything except persist. Default: false. */
-    dryRun?: boolean; /** Progress callback. */
-    onProgress?: (p: {
-      processed: number;
-      total?: number;
-    }) => void; /** Journal type for imported entries. Default: 'GENERAL'. */
-    journalType?: string;
-  };
-}
-interface WireExportArgs<TOut> {
-  /** Query to select entries for export. */
-  query: Record<string, unknown>;
-  sink: ExportSink<TOut>;
-  journalEntries: {
-    getAll(query: Record<string, unknown>): Promise<unknown[]>;
-  };
-  options?: {
-    batchSize?: number;
-    onProgress?: (p: {
-      emitted: number;
-    }) => void;
-  };
-}
-//#endregion
-export { ImportMapper as a, JournalItemInput as c, ImportError as i, WireExportArgs as l, ExportSink as n, ImportReport as o, ImportContext as r, JournalEntryInput as s, ExportReport as t, WireImportArgs as u };