@classytic/ledger 0.7.0 → 0.8.0

package/dist/index.d.mts

@@ -1,12 +1,12 @@
-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-BkGjuVZj.mjs";
-import { S as isValidCategory, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, i as getJournalType, l as getCurrency, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, x as isIncomeStatement, y as getNormalBalance } from "./journals-C50E9mpo.mjs";
-import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "./index-BX8miYdu.mjs";
-import { _ as PopulatedJournalEntry, a as exportToCsv, h as FlatJournalRow, i as quickbooksFieldMap, m as ExportFieldMap, p as ExportField, r as universalFieldMap, t as flattenJournalEntries } from "./index-D1ZjgVxn.mjs";
+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-MpgjCqK0.mjs";
+import { S as isValidCategory, a as getJournalTypeCodes, b as isBalanceSheet, c as CURRENCIES, d as isValidCurrency, f as CATEGORIES, i as getJournalType, l as getCurrency, n as JOURNAL_TYPES, o as isValidJournalType, p as CATEGORY_KEYS, r as getCustomJournalTypes, s as registerJournalType, t as JOURNAL_CODES, u as getMinorUnit, x as isIncomeStatement, y as getNormalBalance } from "./journals-Dd4A9TN3.mjs";
+import { i as defineCountryPack, n as CountryPackInput, r as JournalTemplate, t as CountryPack } from "./index-RNZsX0Yo.mjs";
+import { _ as PopulatedJournalEntry, a as exportToCsv, h as FlatJournalRow, i as quickbooksFieldMap, m as ExportFieldMap, p as ExportField, r as universalFieldMap, t as flattenJournalEntries } from "./index-bCEeSzdO.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 { $ as AgedBalanceParams, A as generateDimensionBreakdown, B as BalanceSheetReport, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as IncomeStatementReport, H as CashFlowSection, I as BudgetVsActualRow, J as ReportCategory, K as LedgerEntry, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as AgedBalanceOptions, T as reopenFiscalPeriod, U as GeneralLedgerAccount, V as CashFlowReport, W as GeneralLedgerReport, X as TrialBalanceReport, Y as ReportGroup, Z as TrialBalanceRow, a as RevaluationReport, at as Logger, b as generateGeneralLedger, c as RevaluationRate, d as computeRevaluation, et as AgedBalanceReport, f as PartnerLedgerLine, g as generatePartnerLedger, h as PartnerLedgerReport, i as RevaluationParams, it as generateAgedBalance, k as DimensionBreakdownRow, l as RevaluationResult, m as PartnerLedgerParams, n as generateTrialBalance, nt as AgedBucketConfig, o as generateRevaluation, ot as defaultLogger, p as PartnerLedgerOptions, q as ReportAccount, r as RevaluationOptions, rt as DEFAULT_BUCKETS, s as AccountForeignBalance, tt as AgedBalanceRow, u as buildRevaluationEntry, v as generateIncomeStatement, w as closeFiscalPeriod, z as generateBalanceSheet } from "./trial-balance-DTc8kzTD.mjs";
-import { A as OpenItem, C as AccountRepository, D as JournalItemRef, E as JournalEntryRepository, F as SeedOptions, I as SeedResult, M as ReconciliationRepository, N as ReverseOptions, O as JournalRepository, P as ReverseResult, S as creditLimitPlugin, T as BulkCreateResult, _ as FxRealizationPluginOptions, a as dailyLockPlugin, b as doubleEntryPlugin, c as periodResolver, d as LockAccountSelector, f as LockHit, g as idempotencyPlugin, i as FiscalLockPluginOptions, j as PostOptions, k as MatchInput, l as createLockPlugin, m as LockResolverContext, n as watermarkResolver, o as fiscalLockPlugin, p as LockResolver, r as DailyLockPluginOptions, s as PeriodResolverOptions, t as WatermarkResolverOptions, u as CreateLockPluginOptions, v as fxRealizationPlugin, w as BulkCreateInput, x as CreditLimitPluginOptions } from "./index-Bl0_ak5w.mjs";
+import { $ as AgedBalanceParams, A as generateDimensionBreakdown, B as BalanceSheetReport, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, G as IncomeStatementReport, H as CashFlowSection, I as BudgetVsActualRow, J as ReportCategory, K as LedgerEntry, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as AgedBalanceOptions, T as reopenFiscalPeriod, U as GeneralLedgerAccount, V as CashFlowReport, W as GeneralLedgerReport, X as TrialBalanceReport, Y as ReportGroup, Z as TrialBalanceRow, a as RevaluationReport, at as Logger, b as generateGeneralLedger, c as RevaluationRate, d as computeRevaluation, et as AgedBalanceReport, f as PartnerLedgerLine, g as generatePartnerLedger, h as PartnerLedgerReport, i as RevaluationParams, it as generateAgedBalance, k as DimensionBreakdownRow, l as RevaluationResult, m as PartnerLedgerParams, n as generateTrialBalance, nt as AgedBucketConfig, o as generateRevaluation, ot as defaultLogger, p as PartnerLedgerOptions, q as ReportAccount, r as RevaluationOptions, rt as DEFAULT_BUCKETS, s as AccountForeignBalance, tt as AgedBalanceRow, u as buildRevaluationEntry, v as generateIncomeStatement, w as closeFiscalPeriod, z as generateBalanceSheet } from "./trial-balance-DTj-c21f.mjs";
+import { A as OpenItem, C as AccountRepository, D as JournalItemRef, E as JournalEntryRepository, F as SeedOptions, I as SeedResult, M as ReconciliationRepository, N as ReverseOptions, O as JournalRepository, P as ReverseResult, S as creditLimitPlugin, T as BulkCreateResult, _ as FxRealizationPluginOptions, a as dailyLockPlugin, b as doubleEntryPlugin, c as periodResolver, d as LockAccountSelector, f as LockHit, g as idempotencyPlugin, i as FiscalLockPluginOptions, j as PostOptions, k as MatchInput, l as createLockPlugin, m as LockResolverContext, n as watermarkResolver, o as fiscalLockPlugin, p as LockResolver, r as DailyLockPluginOptions, s as PeriodResolverOptions, t as WatermarkResolverOptions, u as CreateLockPluginOptions, v as fxRealizationPlugin, w as BulkCreateInput, x as CreditLimitPluginOptions } from "./index-BSsvrf3m.mjs";
+import { PaginationConfig, PluginType, QueryParser, QueryParserOptions, Repository } from "@classytic/mongokit";
 import { ClientSession, Connection, Model } from "mongoose";
-import { PaginationConfig, PluginType, Repository } from "@classytic/mongokit";
 
 //#region src/types/engine.d.ts
 /** Mongokit plugins to install per repository (composes with engine built-ins). */
@@ -381,6 +381,28 @@ interface RecordAdjustmentInput {
   readonly dimensions?: Record<string, unknown>;
   readonly journalType?: string;
 }
+interface RecordOpeningBalanceInput {
+  /** Cutover date — typically start of fiscal year. */
+  readonly cutoverDate: Date;
+  /**
+   * Account balances in integer cents, signed:
+   *   - Positive = normal debit balance (assets)
+   *   - Negative = normal credit balance (liabilities, equity)
+   *
+   * Should only contain balance sheet accounts. P&L cumulative effect
+   * belongs in retained earnings (the equity account).
+   */
+  readonly balances: ReadonlyArray<{
+    readonly account: AccountCode;
+    readonly balance: Cents$1;
+  }>;
+  /**
+   * Equity contra account code. Defaults to the country pack's
+   * `retainedEarningsAccountCode` (e.g. '3600' for CA, '3310' for BD).
+   */
+  readonly equityAccount?: AccountCode;
+  readonly label?: string;
+}
 interface RecordAPI {
   /**
    * Record a sale. Debits cash/AR, credits revenue. Tax lines — if needed —
@@ -418,6 +440,31 @@ interface RecordAPI {
    * the other verbs. Amounts must balance (debits = credits).
    */
   adjustment(organizationId: unknown, input: RecordAdjustmentInput, options?: RecordOptions): Promise<unknown>;
+  /**
+   * Record opening balances for a cutover migration. Creates a single
+   * multi-line journal entry with each account's balance, contra'd against
+   * an equity account (retained earnings by default).
+   *
+   * Follows the Odoo convention: regular JE, not a special type. Only
+   * balance sheet accounts should be passed — P&L cumulative effect belongs
+   * in the equity contra account.
+   *
+   * Idempotent: uses `_externalId: 'opening-balance:{date}'` so re-calling
+   * with the same cutover date fails cleanly (duplicate key error).
+   *
+   * @example
+   * ```typescript
+   * await engine.record.openingBalance(orgId, {
+   *   cutoverDate: new Date('2025-01-01'),
+   *   balances: [
+   *     { account: '1000', balance: 5000000 },   // $50k cash
+   *     { account: '2620', balance: -1875000 },   // $18.75k AP
+   *     { account: '3600', balance: -3125000 },   // $31.25k RE
+   *   ],
+   * });
+   * ```
+   */
+  openingBalance(organizationId: unknown, input: RecordOpeningBalanceInput, options?: RecordOptions): Promise<unknown>;
 }
 //#endregion
 //#region src/engine.d.ts
@@ -540,10 +587,80 @@ declare class AccountingEngine {
   isValidAccountType(code: string): boolean;
   /** Get account type definition by code */
   getAccountType(code: string): AccountType | undefined;
+  /**
+   * Create a pre-configured QueryParser for URL-driven queries against
+   * ledger repositories. Returns a mongokit QueryParser with the correct
+   * schema and pagination limits for the specified model.
+   *
+   * @param model - Which ledger model to parse queries for
+   * @param overrides - Additional QueryParserOptions to merge
+   *
+   * @example
+   * ```typescript
+   * const parser = engine.createQueryParser('journalEntry');
+   * const parsed = parser.parse(req.query);
+   * const result = await engine.repositories.journalEntries.getAll({
+   *   ...parsed,
+   *   filters: { ...parsed.filters, organizationId },
+   * });
+   * ```
+   */
+  createQueryParser(model: 'account' | 'journalEntry' | 'fiscalPeriod' | 'budget' | 'reconciliation' | 'journal', overrides?: Partial<QueryParserOptions>): QueryParser;
   private _buildReports;
 }
 declare function createAccountingEngine(config: AccountingEngineConfig): AccountingEngine;
 //#endregion
+//#region src/repositories/reconciliation.repository.d.ts
+interface MatchHookItem {
+  entry: unknown;
+  itemIndex: number;
+  debit: number;
+  credit: number;
+  amountCurrency: number | null;
+  exchangeRate: number | null;
+}
+/**
+ * Context passed to `before:match` and `after:match` hooks.
+ *
+ * - `before:match`: fired after validation but before the matchingNumber is
+ *   stamped and the reconciliation doc is created. Throw to abort.
+ * - `after:match`: fired after the reconciliation doc is persisted. Used by
+ *   fxRealizationPlugin, and can be used by invoice packages to update
+ *   payment state.
+ */
+interface MatchHookContext {
+  /** The input that was passed to match(). */
+  input: MatchInput;
+  /** Validated + enriched item snapshots with debit/credit/currency info. */
+  items: MatchHookItem[];
+  /** Shared currency across all items, or null if mixed. */
+  sharedCurrency: string | null;
+  /** The matching number (auto-generated or caller-provided). */
+  matchingNumber: string;
+  /** Totals for the matched set. */
+  debitTotal: number;
+  creditTotal: number;
+  isFullReconcile: boolean;
+  /** The created reconciliation document (only in after:match). */
+  reconciliation?: unknown;
+  session: ClientSession | null;
+}
+/**
+ * Context passed to `before:unmatch` and `after:unmatch` hooks.
+ */
+interface UnmatchHookContext {
+  matchingNumber: string;
+  /** The reconciliation document being removed. */
+  reconciliation: Record<string, unknown>;
+  /** The items that will be / were unmatched. */
+  items: Array<{
+    entry: unknown;
+    itemIndex: number;
+  }>;
+  organizationId?: unknown;
+  session: ClientSession | null;
+}
+//#endregion
 //#region src/utils/account-helpers.d.ts
 /**
  * Check if an account type is a virtual tax sub-account.
@@ -764,4 +881,4 @@ interface PostingResult {
   idempotencyKeys?: string[];
 }
 //#endregion
-export { type AccountCode, type AccountForeignBalance, type AccountRepository, type AccountSummary, type AccountType, AccountingEngine, type AccountingEngineConfig, AccountingError, type ActorContext, type AgedBalanceOptions, type AgedBalanceParams, type AgedBalanceReport, type AgedBalanceRow, type AgedBucketConfig, type AuditConfig, type BalanceSheetReport, type BudgetVsActualOptions, type BudgetVsActualParams, type BudgetVsActualReport, type BudgetVsActualRow, type BulkCreateInput, type BulkCreateResult, CATEGORIES, CATEGORY_KEYS, CURRENCIES, type CashFlowCategory, type CashFlowReport, type CashFlowSection, type CategoryKey, type Cents, type CountryPack, type CountryPackInput, type CreateLockPluginOptions, type CreditLimitPluginOptions, type Currency, DEFAULT_BUCKETS, type DailyLockPluginOptions, type DateOption, type DateRange, type DimensionBreakdownOptions, type DimensionBreakdownParams, type DimensionBreakdownReport, type DimensionBreakdownRow, type DimensionDefinition, type EntryState, Errors, type ExportField, type ExportFieldMap, type FieldError, type FiscalLockPluginOptions, type FiscalPeriodSummary, type FlatJournalRow, type FxRealizationPluginOptions, type GeneralLedgerAccount, type GeneralLedgerReport, type IncomeStatementReport, type IntrospectAPI, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryRepository, type JournalItem, type JournalItemRef, type JournalRepository, type JournalSchemaOptions, type JournalTemplate, type JournalType, type LedgerEntry, type LedgerModels, type LedgerPaginationConfig, type LedgerRepositories, type LedgerRepositoryPlugins, type LockAccountSelector, type LockHit, type LockResolver, type LockResolverContext, type Logger, type MainType, type MatchInput, type ModelNames, Money, type MultiCurrencyConfig, type MultiTenantConfig, type NormalBalance, type OpenItem, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type PeriodResolverOptions, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type ReconciliationRepository, type RecordAPI, type RecordAdjustmentInput, type RecordAdjustmentLine, type RecordExpenseInput, type RecordOptions, type RecordPaymentInput, type RecordSaleInput, type RecordTransferInput, type ReportAccount, type ReportCategory, type ReportDescriptor, type ReportGroup, type ResolvedModelNames, type RevaluationOptions, type RevaluationParams, type RevaluationRate, type RevaluationReport, type RevaluationResult, type ReverseOptions, type ReverseResult, type SchemaOptions, type SeedOptions, type SeedResult, type Cents$1 as SemanticCents, type SessionResult, type StatementType, type StrictnessConfig, type SubledgerJournalItem, type SubledgerPostingInput, type TaxDetail, type TaxMetadata, type TotalAccountOp, type TrialBalanceReport, type TrialBalanceRow, type WatermarkResolverOptions, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildRevaluationEntry, calculateTotal, closeFiscalPeriod, computeEndingBalance, computeRevaluation, createAccountingEngine, createLockPlugin, createModels, createRepositories, creditLimitPlugin, dailyLockPlugin, defaultLogger, defineCountryPack, doubleEntryPlugin, exportToCsv, finalizeSession, fiscalLockPlugin, flattenJournalEntries, format, formatPlain, fromDecimal, fxRealizationPlugin, generateAgedBalance, generateBalanceSheet, generateBudgetVsActual, generateCashFlow, generateDimensionBreakdown, generateGeneralLedger, generateIncomeStatement, generatePartnerLedger, generateRevaluation, generateTrialBalance, getCurrency, getCustomJournalTypes, getDateRange, getFiscalYearStart, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, idempotencyPlugin, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, isVirtualTaxAccount, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, watermarkResolver };
+export { type AccountCode, type AccountForeignBalance, type AccountRepository, type AccountSummary, type AccountType, AccountingEngine, type AccountingEngineConfig, AccountingError, type ActorContext, type AgedBalanceOptions, type AgedBalanceParams, type AgedBalanceReport, type AgedBalanceRow, type AgedBucketConfig, type AuditConfig, type BalanceSheetReport, type BudgetVsActualOptions, type BudgetVsActualParams, type BudgetVsActualReport, type BudgetVsActualRow, type BulkCreateInput, type BulkCreateResult, CATEGORIES, CATEGORY_KEYS, CURRENCIES, type CashFlowCategory, type CashFlowReport, type CashFlowSection, type CategoryKey, type Cents, type CountryPack, type CountryPackInput, type CreateLockPluginOptions, type CreditLimitPluginOptions, type Currency, DEFAULT_BUCKETS, type DailyLockPluginOptions, type DateOption, type DateRange, type DimensionBreakdownOptions, type DimensionBreakdownParams, type DimensionBreakdownReport, type DimensionBreakdownRow, type DimensionDefinition, type EntryState, Errors, type ExportField, type ExportFieldMap, type FieldError, type FiscalLockPluginOptions, type FiscalPeriodSummary, type FlatJournalRow, type FxRealizationPluginOptions, type GeneralLedgerAccount, type GeneralLedgerReport, type IncomeStatementReport, type IntrospectAPI, JOURNAL_CODES, JOURNAL_TYPES, type JournalEntryRepository, type JournalItem, type JournalItemRef, type JournalRepository, type JournalSchemaOptions, type JournalTemplate, type JournalType, type LedgerEntry, type LedgerModels, type LedgerPaginationConfig, type LedgerRepositories, type LedgerRepositoryPlugins, type LockAccountSelector, type LockHit, type LockResolver, type LockResolverContext, type Logger, type MainType, type MatchHookContext, type MatchHookItem, type MatchInput, type ModelNames, Money, type MultiCurrencyConfig, type MultiTenantConfig, type NormalBalance, type OpenItem, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type PeriodResolverOptions, type PopulatedJournalEntry, type PostOptions, type PostingContract, type PostingResult, type ReconciliationRepository, type RecordAPI, type RecordAdjustmentInput, type RecordAdjustmentLine, type RecordExpenseInput, type RecordOptions, type RecordPaymentInput, type RecordSaleInput, type RecordTransferInput, type ReportAccount, type ReportCategory, type ReportDescriptor, type ReportGroup, type ResolvedModelNames, type RevaluationOptions, type RevaluationParams, type RevaluationRate, type RevaluationReport, type RevaluationResult, type ReverseOptions, type ReverseResult, type SchemaOptions, type SeedOptions, type SeedResult, type Cents$1 as SemanticCents, type SessionResult, type StatementType, type StrictnessConfig, type SubledgerJournalItem, type SubledgerPostingInput, type TaxDetail, type TaxMetadata, type TotalAccountOp, type TrialBalanceReport, type TrialBalanceRow, type UnmatchHookContext, type WatermarkResolverOptions, acquireSession, add, allocate, buildAccountTypeMap, buildDimensionFields, buildDimensionIndexes, buildItemFilters, buildRevaluationEntry, calculateTotal, closeFiscalPeriod, computeEndingBalance, computeRevaluation, createAccountingEngine, createLockPlugin, createModels, createRepositories, creditLimitPlugin, dailyLockPlugin, defaultLogger, defineCountryPack, doubleEntryPlugin, exportToCsv, finalizeSession, fiscalLockPlugin, flattenJournalEntries, format, formatPlain, fromDecimal, fxRealizationPlugin, generateAgedBalance, generateBalanceSheet, generateBudgetVsActual, generateCashFlow, generateDimensionBreakdown, generateGeneralLedger, generateIncomeStatement, generatePartnerLedger, generateRevaluation, generateTrialBalance, getCurrency, getCustomJournalTypes, getDateRange, getFiscalYearStart, getJournalType, getJournalTypeCodes, getMinorUnit, getNormalBalance, idempotencyPlugin, isBalanceSheet, isIncomeStatement, isValidCategory, isValidCurrency, isValidJournalType, isVirtualTaxAccount, multiply, parseCents, percentage, periodResolver, quickbooksFieldMap, registerJournalType, reopenFiscalPeriod, resolveModelNames, splitTaxExclusive, splitTaxInclusive, subtract, toDecimal, universalFieldMap, watermarkResolver };

package/dist/index.mjs

@@ -3,11 +3,12 @@ import { Money, add, allocate, format, formatPlain, fromDecimal, multiply, parse
 import { n as Errors, t as AccountingError } from "./errors-CSDQPNyt.mjs";
 import { C as isVirtualTaxAccount, E as requireOrgScope, S as computeEndingBalance, T as generateAgedBalance, _ as buildItemFilters, a as finalizeSession, b as buildAccountTypeMap, c as generateRevaluation, d as generateIncomeStatement, f as generateGeneralLedger, g as generateBalanceSheet, h as generateBudgetVsActual, i as acquireSession, l as buildRevaluationEntry, m as generateCashFlow, n as closeFiscalPeriod, o as defaultLogger, p as generateDimensionBreakdown, r as reopenFiscalPeriod, s as generateTrialBalance, t as generatePartnerLedger, u as computeRevaluation, v as getDateRange, w as DEFAULT_BUCKETS, x as calculateTotal, y as getFiscalYearStart } from "./partner-ledger-D9H5hegI.mjs";
 import { c as getNormalBalance, d as isValidCategory, l as isBalanceSheet, n as CATEGORY_KEYS, t as CATEGORIES, u as isIncomeStatement } from "./categories-BkKdv16V.mjs";
-import { a as watermarkResolver, c as idempotencyPlugin, i as fiscalLockPlugin, l as doubleEntryPlugin, n as creditLimitPlugin, o as periodResolver, r as dailyLockPlugin, s as createLockPlugin, t as fxRealizationPlugin } from "./fx-realization.plugin-CfYy1tB6.mjs";
+import { a as watermarkResolver, c as idempotencyPlugin, i as fiscalLockPlugin, l as doubleEntryPlugin, n as creditLimitPlugin, o as periodResolver, r as dailyLockPlugin, s as createLockPlugin, t as fxRealizationPlugin } from "./fx-realization.plugin-DDVK-oYO.mjs";
+import { t as buildOpeningBalanceEntry } from "./opening-balance-DPXmAIzN.mjs";
 import { defineCountryPack } from "./country/index.mjs";
-import { a as exportToCsv, i as quickbooksFieldMap, r as universalFieldMap, t as flattenJournalEntries } from "./exports-BP-0Ni5W.mjs";
+import { a as exportToCsv, i as quickbooksFieldMap, r as universalFieldMap, t as flattenJournalEntries } from "./exports-B3whucXe.mjs";
+import { QueryParser, Repository } from "@classytic/mongokit";
 import mongoose, { Schema } from "mongoose";
-import { Repository } from "@classytic/mongokit";
 //#region src/schemas/currency-field.ts
 /**
 * Build the Mongoose currency field definition.
@@ -919,11 +920,10 @@ function createModels(connection, config) {
 * onto an existing mongokit Repository.
 *
 * @param repository - A mongokit Repository instance (already created)
-* @param AccountModel - The Mongoose model for accounts
 * @param country - The CountryPack for account type lookups
 * @param orgField - The multi-tenant field name (e.g. 'business')
 */
-function wireAccountMethods(repository, AccountModel, country, orgField) {
+function wireAccountMethods(repository, country, orgField) {
 	repository.on("before:create", (ctx) => {
 		const code = ctx.data?.accountTypeCode;
 		if (code && !country.isPostingAccount(code)) throw Errors.validation(`Cannot create account with type "${code}" — it is a structural group or calculated total, not a posting account.`);
@@ -936,7 +936,10 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 		const postingTypes = country.getPostingAccountTypes();
 		const filter = {};
 		if (orgField && orgId != null) filter[orgField] = orgId;
-		const existing = await AccountModel.find(filter).select("accountNumber").lean();
+		const existing = await repository.findAll(filter, {
+			select: { accountNumber: 1 },
+			lean: true
+		});
 		const existingNumbers = new Set(existing.map((a) => a.accountNumber));
 		const toCreate = postingTypes.filter((at) => !existingNumbers.has(at.code)).map((at) => {
 			const doc = {
@@ -953,7 +956,7 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 		};
 		try {
 			return {
-				created: (await AccountModel.insertMany(toCreate, {
+				created: (await repository.createMany(toCreate, {
 					session: options.session ?? void 0,
 					ordered: false
 				})).length,
@@ -1034,7 +1037,10 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 		};
 		const existsFilter = { accountNumber: { $in: validAccounts.map((a) => a.accountNumber) } };
 		if (orgField && orgId != null) existsFilter[orgField] = orgId;
-		const existingDocs = await AccountModel.find(existsFilter).select("accountNumber").lean();
+		const existingDocs = await repository.findAll(existsFilter, {
+			select: { accountNumber: 1 },
+			lean: true
+		});
 		const existingNumbers = new Set(existingDocs.map((d) => d.accountNumber));
 		const toCreate = [];
 		for (const item of validAccounts) if (existingNumbers.has(item.accountNumber)) results.skipped.push({
@@ -1056,7 +1062,7 @@ function wireAccountMethods(repository, AccountModel, country, orgField) {
 				return doc;
 			});
 			try {
-				const inserted = await AccountModel.insertMany(docs, { ordered: false });
+				const inserted = await repository.createMany(docs, { ordered: false });
 				results.created = toCreate.map((item, idx) => ({
 					accountTypeCode: item.accountTypeCode,
 					active: item.active,
@@ -1541,6 +1547,7 @@ function wireReconciliationMethods(repository, ReconciliationModel, JournalEntry
 	const create = repository.create.bind(repository);
 	const deleteById = repository.delete.bind(repository);
 	const repoInstance = repository;
+	const emitHook = repoInstance.emitAsync.bind(repoInstance);
 	repository.match = async (input) => {
 		const { account, items, note, reconciledBy, organizationId, session = null } = input;
 		let { matchingNumber } = input;
@@ -1585,6 +1592,17 @@ function wireReconciliationMethods(repository, ReconciliationModel, JournalEntry
 		const isFullReconcile = difference === 0;
 		const sharedCurrency = currencies.size === 1 ? Array.from(currencies)[0] : null;
 		if (!matchingNumber) matchingNumber = await nextMatchingNumber(ReconciliationModel, orgField, organizationId, session);
+		const hookCtx = {
+			input,
+			items: itemSnapshots,
+			sharedCurrency,
+			matchingNumber,
+			debitTotal,
+			creditTotal,
+			isFullReconcile,
+			session
+		};
+		await emitHook("before:match", hookCtx);
 		const bulkOps = itemSnapshots.map((snap) => ({ updateOne: {
 			filter: { _id: snap.entry },
 			update: { $set: { [`journalItems.${snap.itemIndex}.matchingNumber`]: matchingNumber } }
@@ -1612,12 +1630,9 @@ function wireReconciliationMethods(repository, ReconciliationModel, JournalEntry
 		};
 		if (orgField && organizationId != null) reconciliationData[orgField] = organizationId;
 		const record = await create(reconciliationData);
-		const emit = repoInstance._emitHook;
-		if (emit) await emit.call(repoInstance, "after:match", {
-			reconciliation: record,
-			items: itemSnapshots,
-			sharedCurrency,
-			session
+		await emitHook("after:match", {
+			...hookCtx,
+			reconciliation: record
 		});
 		return record;
 	};
@@ -1628,13 +1643,23 @@ function wireReconciliationMethods(repository, ReconciliationModel, JournalEntry
 		if (orgField && organizationId != null) query[orgField] = organizationId;
 		const existing = await ReconciliationModel.findOne(query).session(session).lean();
 		if (!existing) throw Errors.notFound(`Reconciliation ${matchingNumber} not found`);
-		const bulkOps = (existing.items ?? []).map((it) => ({ updateOne: {
+		const items = existing.items ?? [];
+		const unmatchCtx = {
+			matchingNumber,
+			reconciliation: existing,
+			items,
+			organizationId,
+			session
+		};
+		await emitHook("before:unmatch", unmatchCtx);
+		const bulkOps = items.map((it) => ({ updateOne: {
 			filter: { _id: it.entry },
 			update: { $set: { [`journalItems.${it.itemIndex}.matchingNumber`]: null } }
 		} }));
 		if (bulkOps.length > 0) await JournalEntryModel.bulkWrite(bulkOps, { session: session ?? void 0 });
 		const result = await deleteById(String(existing._id));
 		if (!result.success) throw Errors.notFound("Failed to delete reconciliation record");
+		await emitHook("after:unmatch", unmatchCtx);
 		return result;
 	};
 	repository.getOpenItems = async (params) => {
@@ -1727,7 +1752,7 @@ function createRepositories(models, config, plugins = {}, pagination = {}) {
 	const fpPagination = pagination.fiscalPeriod ?? {};
 	const budgetPagination = pagination.budget ?? {};
 	const reconPagination = pagination.reconciliation ?? {};
-	const accounts = wireAccountMethods(new Repository(models.Account, plugins.account ?? [], accountPagination), models.Account, country, orgField);
+	const accounts = wireAccountMethods(new Repository(models.Account, plugins.account ?? [], accountPagination), country, orgField);
 	const jePlugins = [
 		...plugins.journalEntry ?? [],
 		doubleEntryPlugin({
@@ -2255,16 +2280,80 @@ function buildRecordAPI({ models, repositories, config }) {
 			journalItems: items
 		}, options);
 	};
+	const openingBalance = async (organizationId, input, options) => {
+		if (!input.balances || input.balances.length === 0) throw Errors.validation("Opening balance requires at least one account balance.", [{
+			path: "balances",
+			issue: "must contain at least 1 entry",
+			value: 0
+		}]);
+		const equityCode = input.equityAccount ?? config.country?.retainedEarningsAccountCode;
+		if (!equityCode) throw Errors.validation("Equity contra account code is required. Pass equityAccount or configure retainedEarningsAccountCode in the country pack.", [{
+			path: "equityAccount",
+			issue: "required",
+			value: void 0
+		}]);
+		const result = buildOpeningBalanceEntry({
+			cutoverDate: input.cutoverDate,
+			balances: input.balances.map((b) => ({
+				accountCode: b.account,
+				balance: b.balance
+			})),
+			equityAccountCode: equityCode,
+			label: input.label
+		});
+		const acctMap = await resolveAccounts(organizationId, result.entry.journalItems.map((item) => item.account), "balances", options?.session ?? null);
+		const items = result.entry.journalItems.map((item) => buildItem(acctMap.get(item.account), item.debit, item.credit, item.label));
+		return postEntry(organizationId, {
+			journalType: result.entry.journalType ?? "GENERAL",
+			date: result.entry.date,
+			label: result.entry.label,
+			journalItems: items,
+			...result.entry.extra
+		}, options);
+	};
 	return {
 		sale,
 		expense,
 		transfer,
 		payment,
-		adjustment
+		adjustment,
+		openingBalance
 	};
 }
 //#endregion
 //#region src/engine.ts
+/**
+* AccountingEngine — The main entry point for @classytic/ledger.
+*
+* The engine owns all models, repositories, and reports. Matches the
+* @classytic/flow and @classytic/promo pattern: pass a mongoose connection
+* in config, and everything is auto-wired.
+*
+* @example
+* ```typescript
+* import mongoose from 'mongoose';
+* import { createAccountingEngine } from '@classytic/ledger';
+* import { canadaPack } from '@classytic/ledger-ca';
+*
+* const engine = createAccountingEngine({
+*   mongoose: mongoose.connection,
+*   country: canadaPack,
+*   currency: 'CAD',
+*   multiTenant: { orgField: 'organizationId', orgRef: 'Organization' },
+* });
+*
+* // Models — auto-created Mongoose models
+* engine.models.Account
+* engine.models.JournalEntry
+*
+* // Repositories — plugins + domain methods pre-wired
+* await engine.repositories.accounts.seedAccounts(orgId);
+* await engine.repositories.journalEntries.post(entryId, orgId);
+*
+* // Reports — bound to owned models
+* const bs = await engine.reports.balanceSheet({ organizationId: orgId, dateOption: 'year', dateValue: 2025 });
+* ```
+*/
 var AccountingEngine = class {
 	config;
 	country;
@@ -2313,6 +2402,60 @@ var AccountingEngine = class {
 	getAccountType(code) {
 		return this.country.getAccountType(code);
 	}
+	/**
+	* Create a pre-configured QueryParser for URL-driven queries against
+	* ledger repositories. Returns a mongokit QueryParser with the correct
+	* schema and pagination limits for the specified model.
+	*
+	* @param model - Which ledger model to parse queries for
+	* @param overrides - Additional QueryParserOptions to merge
+	*
+	* @example
+	* ```typescript
+	* const parser = engine.createQueryParser('journalEntry');
+	* const parsed = parser.parse(req.query);
+	* const result = await engine.repositories.journalEntries.getAll({
+	*   ...parsed,
+	*   filters: { ...parsed.filters, organizationId },
+	* });
+	* ```
+	*/
+	createQueryParser(model, overrides) {
+		const paginationConfig = this.config.pagination ?? {};
+		const entry = {
+			account: {
+				model: this.models.Account,
+				pagination: paginationConfig.account
+			},
+			journalEntry: {
+				model: this.models.JournalEntry,
+				pagination: paginationConfig.journalEntry
+			},
+			fiscalPeriod: {
+				model: this.models.FiscalPeriod,
+				pagination: paginationConfig.fiscalPeriod
+			},
+			budget: {
+				model: this.models.Budget,
+				pagination: paginationConfig.budget
+			},
+			reconciliation: {
+				model: this.models.Reconciliation,
+				pagination: paginationConfig.reconciliation
+			},
+			journal: {
+				model: this.models.Journal,
+				pagination: paginationConfig.journal
+			}
+		}[model];
+		if (!entry) throw new Error(`createQueryParser: unknown model "${model}"`);
+		return new QueryParser({
+			schema: entry.model.schema,
+			maxLimit: entry.pagination?.maxLimit ?? 100,
+			searchMode: "regex",
+			...overrides
+		});
+	}
 	_buildReports() {
 		const AccountModel = this.models.Account;
 		const JournalEntryModel = this.models.JournalEntry;

package/dist/{journals-C50E9mpo.d.mts → journals-Dd4A9TN3.d.mts}

@@ -1,4 +1,4 @@
-import { d as JournalType, f as MainType, h as StatementType, i as CategoryKey, o as Currency, r as Category } from "./core-BkGjuVZj.mjs";
+import { d as JournalType, f as MainType, h as StatementType, i as CategoryKey, o as Currency, r as Category } from "./core-MpgjCqK0.mjs";
 
 //#region src/constants/categories.d.ts
 /** All valid categories */

package/dist/opening-balance-DPXmAIzN.mjs

@@ -0,0 +1,60 @@
+//#region src/sync/builders/opening-balance.ts
+function buildOpeningBalanceEntry(input) {
+	const { cutoverDate, balances, equityAccountCode } = input;
+	const dateStr = cutoverDate.toISOString().split("T")[0];
+	const label = input.label ?? `Opening Balance — Cutover ${dateStr}`;
+	const items = [];
+	let totalDebit = 0;
+	let totalCredit = 0;
+	for (const { accountCode, balance } of balances) {
+		if (balance === 0) continue;
+		if (balance > 0) {
+			items.push({
+				account: accountCode,
+				debit: balance,
+				credit: 0,
+				label: "Opening balance"
+			});
+			totalDebit += balance;
+		} else {
+			const absBalance = Math.abs(balance);
+			items.push({
+				account: accountCode,
+				debit: 0,
+				credit: absBalance,
+				label: "Opening balance"
+			});
+			totalCredit += absBalance;
+		}
+	}
+	const residual = totalDebit - totalCredit;
+	const lineCount = items.length;
+	if (residual > 0) items.push({
+		account: equityAccountCode,
+		debit: 0,
+		credit: residual,
+		label: "Opening balance equity (contra)"
+	});
+	else if (residual < 0) items.push({
+		account: equityAccountCode,
+		debit: Math.abs(residual),
+		credit: 0,
+		label: "Opening balance equity (contra)"
+	});
+	return {
+		entry: {
+			date: cutoverDate,
+			label,
+			journalType: "GENERAL",
+			journalItems: items,
+			extra: {
+				_externalId: `opening-balance:${dateStr}`,
+				_importSource: "opening-balance"
+			}
+		},
+		residual,
+		lineCount
+	};
+}
+//#endregion
+export { buildOpeningBalanceEntry as t };

package/dist/plugins/index.d.mts

@@ -1,2 +1,2 @@
-import { S as creditLimitPlugin, _ as FxRealizationPluginOptions, a as dailyLockPlugin, b as doubleEntryPlugin, c as periodResolver, d as LockAccountSelector, f as LockHit, g as idempotencyPlugin, h as IdempotencyPluginOptions, i as FiscalLockPluginOptions, l as createLockPlugin, m as LockResolverContext, n as watermarkResolver, o as fiscalLockPlugin, p as LockResolver, r as DailyLockPluginOptions, s as PeriodResolverOptions, t as WatermarkResolverOptions, u as CreateLockPluginOptions, v as fxRealizationPlugin, x as CreditLimitPluginOptions, y as DoubleEntryPluginOptions } from "../index-Bl0_ak5w.mjs";
+import { S as creditLimitPlugin, _ as FxRealizationPluginOptions, a as dailyLockPlugin, b as doubleEntryPlugin, c as periodResolver, d as LockAccountSelector, f as LockHit, g as idempotencyPlugin, h as IdempotencyPluginOptions, i as FiscalLockPluginOptions, l as createLockPlugin, m as LockResolverContext, n as watermarkResolver, o as fiscalLockPlugin, p as LockResolver, r as DailyLockPluginOptions, s as PeriodResolverOptions, t as WatermarkResolverOptions, u as CreateLockPluginOptions, v as fxRealizationPlugin, x as CreditLimitPluginOptions, y as DoubleEntryPluginOptions } from "../index-BSsvrf3m.mjs";
 export { type CreateLockPluginOptions, type CreditLimitPluginOptions, type DailyLockPluginOptions, type DoubleEntryPluginOptions, type FiscalLockPluginOptions, type FxRealizationPluginOptions, type IdempotencyPluginOptions, type LockAccountSelector, type LockHit, type LockResolver, type LockResolverContext, type PeriodResolverOptions, type WatermarkResolverOptions, createLockPlugin, creditLimitPlugin, dailyLockPlugin, doubleEntryPlugin, fiscalLockPlugin, fxRealizationPlugin, idempotencyPlugin, periodResolver, watermarkResolver };

package/dist/plugins/index.mjs

@@ -1,2 +1,2 @@
-import { a as watermarkResolver, c as idempotencyPlugin, i as fiscalLockPlugin, l as doubleEntryPlugin, n as creditLimitPlugin, o as periodResolver, r as dailyLockPlugin, s as createLockPlugin, t as fxRealizationPlugin } from "../fx-realization.plugin-CfYy1tB6.mjs";
+import { a as watermarkResolver, c as idempotencyPlugin, i as fiscalLockPlugin, l as doubleEntryPlugin, n as creditLimitPlugin, o as periodResolver, r as dailyLockPlugin, s as createLockPlugin, t as fxRealizationPlugin } from "../fx-realization.plugin-DDVK-oYO.mjs";
 export { createLockPlugin, creditLimitPlugin, dailyLockPlugin, doubleEntryPlugin, fiscalLockPlugin, fxRealizationPlugin, idempotencyPlugin, periodResolver, watermarkResolver };

package/dist/reports/index.d.mts

@@ -1,2 +1,2 @@
-import { $ as AgedBalanceParams, A as generateDimensionBreakdown, C as FiscalReopenResult, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, I as BudgetVsActualRow, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as AgedBalanceOptions, R as BalanceSheetOptions, S as FiscalCloseResult, T as reopenFiscalPeriod, _ as IncomeStatementOptions, a as RevaluationReport, b as generateGeneralLedger, et as AgedBalanceReport, f as PartnerLedgerLine, g as generatePartnerLedger, h as PartnerLedgerReport, i as RevaluationParams, it as generateAgedBalance, j as CashFlowOptions, k as DimensionBreakdownRow, m as PartnerLedgerParams, n as generateTrialBalance, nt as AgedBucketConfig, o as generateRevaluation, p as PartnerLedgerOptions, r as RevaluationOptions, rt as DEFAULT_BUCKETS, t as TrialBalanceOptions, tt as AgedBalanceRow, v as generateIncomeStatement, w as closeFiscalPeriod, x as FiscalCloseOptions, y as GeneralLedgerOptions, z as generateBalanceSheet } from "../trial-balance-DTc8kzTD.mjs";
+import { $ as AgedBalanceParams, A as generateDimensionBreakdown, C as FiscalReopenResult, D as DimensionBreakdownParams, E as DimensionBreakdownOptions, F as BudgetVsActualReport, I as BudgetVsActualRow, L as generateBudgetVsActual, M as generateCashFlow, N as BudgetVsActualOptions, O as DimensionBreakdownReport, P as BudgetVsActualParams, Q as AgedBalanceOptions, R as BalanceSheetOptions, S as FiscalCloseResult, T as reopenFiscalPeriod, _ as IncomeStatementOptions, a as RevaluationReport, b as generateGeneralLedger, et as AgedBalanceReport, f as PartnerLedgerLine, g as generatePartnerLedger, h as PartnerLedgerReport, i as RevaluationParams, it as generateAgedBalance, j as CashFlowOptions, k as DimensionBreakdownRow, m as PartnerLedgerParams, n as generateTrialBalance, nt as AgedBucketConfig, o as generateRevaluation, p as PartnerLedgerOptions, r as RevaluationOptions, rt as DEFAULT_BUCKETS, t as TrialBalanceOptions, tt as AgedBalanceRow, v as generateIncomeStatement, w as closeFiscalPeriod, x as FiscalCloseOptions, y as GeneralLedgerOptions, z as generateBalanceSheet } from "../trial-balance-DTj-c21f.mjs";
 export { type AgedBalanceOptions, type AgedBalanceParams, type AgedBalanceReport, type AgedBalanceRow, type AgedBucketConfig, type BalanceSheetOptions, type BudgetVsActualOptions, type BudgetVsActualParams, type BudgetVsActualReport, type BudgetVsActualRow, type CashFlowOptions, DEFAULT_BUCKETS, type DimensionBreakdownOptions, type DimensionBreakdownParams, type DimensionBreakdownReport, type DimensionBreakdownRow, type FiscalCloseOptions, type FiscalCloseResult, type FiscalReopenResult, type GeneralLedgerOptions, type IncomeStatementOptions, type PartnerLedgerLine, type PartnerLedgerOptions, type PartnerLedgerParams, type PartnerLedgerReport, type RevaluationOptions, type RevaluationParams, type RevaluationReport, type TrialBalanceOptions, closeFiscalPeriod, generateAgedBalance, generateBalanceSheet, generateBudgetVsActual, generateCashFlow, generateDimensionBreakdown, generateGeneralLedger, generateIncomeStatement, generatePartnerLedger, generateRevaluation, generateTrialBalance, reopenFiscalPeriod };