@classytic/ledger 0.8.0 → 0.9.1

package/README.md

@@ -1,412 +1,158 @@
 # @classytic/ledger
 
-Embeddable double-entry accounting engine for MongoDB. Integer-cents arithmetic, plugin-based, country-agnostic, multi-tenant at every layer. Framework-agnostic — works with Express, Fastify, Nest, Arc, or any plain Mongoose app.
-
-> **0.7.0 (BREAKING)** — `@classytic/ledger` is now a **pure double-entry accounting engine**. Tax computation, return templates, repartition, and exigibility have been removed from the core and country-pack contracts and now live in dedicated tax packages (`@classytic/bd-tax` is the existing reference; `@classytic/ca-tax` will follow). Country packs `@classytic/ledger-bd@0.2.0` and `@classytic/ledger-ca@0.2.0` ship the chart of accounts + journal templates only — they re-export the raw tax data tables as named constants for tax engines to lift. The 0.6.x A/P + A/R primitives (item-level matching, partner ledger, credit limit, FX realization, journal resource, open-item queries) are unchanged. See [CHANGELOG.md](CHANGELOG.md).
+Double-entry accounting engine for MongoDB. Integer-cents arithmetic, plugin-based, country-agnostic, multi-tenant. Framework-agnostic — works with Fastify, Express, Nest, or plain Mongoose.
 
 ## Install
 
 ```bash
 npm install @classytic/ledger @classytic/mongokit mongoose
-npm install @classytic/ledger-ca   # Canada (GIFI chart of accounts)
 npm install @classytic/ledger-bd   # Bangladesh (BFRS chart of accounts)
 ```
 
 ## Quick Start
 
 ```ts
-import mongoose from "mongoose";
-import { createAccountingEngine } from "@classytic/ledger";
-import { canadaPack } from "@classytic/ledger-ca";
+import mongoose from 'mongoose';
+import { createAccountingEngine } from '@classytic/ledger';
+import { bangladeshPack } from '@classytic/ledger-bd';
 
 const engine = createAccountingEngine({
   mongoose: mongoose.connection,
-  country: canadaPack,
-  currency: "CAD",
-  multiTenant: { orgField: "organizationId", orgRef: "Organization" },
+  country: bangladeshPack,
+  currency: 'BDT',
+  multiTenant: { orgField: 'organizationId', orgRef: 'organization' },
 });
 
+// Seed chart of accounts for a branch
 await engine.repositories.accounts.seedAccounts(orgId);
 
-await engine.record.sale(orgId, {
-  date: new Date("2025-04-01"),
-  amount: 11300,                 // $113.00 in cents (caller pre-computes any tax)
-  receivableAccount: "1200",     // AR
-  revenueAccount:    "4010",     // Service Revenue
-  label: "INV-001",
-});
-
-const bs = await engine.reports.balanceSheet({
-  organizationId: orgId,
-  dateOption: "year",
-  dateValue: 2025,
-});
-```
-
-The engine owns the models. After `createAccountingEngine` you have:
-
-| Property | What it gives you |
-| --- | --- |
-| `engine.models.{Account,JournalEntry,FiscalPeriod,Budget,Reconciliation,Journal}` | Mongoose models |
-| `engine.repositories.accounts` | `seedAccounts()`, `bulkCreate()` + plugins |
-| `engine.repositories.journalEntries` | `post()`, `unpost()`, `reverse()`, `duplicate()` + double-entry, fiscal-lock, idempotency |
-| `engine.repositories.journals` | First-class posting channels — `seedDefaults()`, `nextSequenceNumber()` |
-| `engine.repositories.reconciliations` | Item-level matching — `match()`, `unmatch()`, `getOpenItems()` |
-| `engine.repositories.{fiscalPeriods,budgets}` | Plain CRUD |
-| `engine.record.*` | Domain verbs (`sale`, `expense`, `transfer`, `payment`, `adjustment`) |
-| `engine.introspect.*` | Runtime catalog of accounts, journal types, reports, fiscal periods |
-| `engine.reports.*` | All 12 reports, bound to owned models |
-
-## Semantic Record API
-
-Record business operations as domain verbs. The engine resolves account codes and produces a balanced journal entry — you never touch debits/credits.
-
-```ts
-await engine.record.sale(orgId, {
-  date, amount: 10000,
-  receivableAccount: "1001", revenueAccount: "4010",
-});
-
-await engine.record.expense(orgId, {
-  date, amount: 3000,
-  expenseAccount: "6010", paidFromAccount: "2001",
-});
-
-await engine.record.transfer(orgId, { date, amount: 5000, fromAccount: "1001", toAccount: "1002" });
-
-await engine.record.payment(orgId, {
-  date, amount: 11300,
-  fromReceivableAccount: "1200", toCashAccount: "1001",
-});
-
-// Multi-line adjustment (depreciation, accruals, corrections)
-await engine.record.adjustment(orgId, {
-  date, label: "Monthly depreciation",
-  lines: [
-    { account: "6030", debit:  1000 },
-    { account: "1500", credit: 1000 },
+// Post a journal entry
+const entry = await engine.repositories.journalEntries.create({
+  journalType: 'GENERAL',
+  date: new Date(),
+  label: 'Office supplies',
+  journalItems: [
+    { account: expenseAccountId, debit: 500_00, credit: 0 },
+    { account: cashAccountId, debit: 0, credit: 500_00 },
   ],
 });
+await engine.repositories.journalEntries.post(entry._id, orgId);
 ```
 
-> **Tax lines:** the semantic verbs are tax-agnostic in 0.7+. Compute VAT/GST/HST via your tax engine of choice (`@classytic/bd-tax`, the forthcoming `@classytic/ca-tax`, or your own) and either pre-add the tax to `amount` and post the tax line via `record.adjustment`, or post the full entry directly via `engine.repositories.journalEntries.create()`.
+## Multi-Currency (0.9.0+)
 
-All verbs accept `options.user`, `options.session`, `options.idempotencyKey`, plus any custom field — they all flow into mongokit's `RepositoryContext` so audit/observability plugins (and your hooks) pick them up automatically.
-
-## Accounts Payable & Receivable
-
-The 0.6.x A/P + A/R primitives are the foundation for any ERP workflow on top of the ledger.
+GL stays in base currency (BDT). Foreign currency is audit metadata.
 
 ```ts
-// Tag every journal item with a partnerId via extraItemFields (one-time setup)
 const engine = createAccountingEngine({
-  // ...
-  schemaOptions: {
-    journalEntry: {
-      extraItemFields: {
-        partnerId: { type: String, index: true },
-      },
-    },
+  country: bangladeshPack,
+  currency: 'BDT',
+  multiCurrency: { enabled: true, currencies: ['USD', 'EUR', 'GBP'] },
+  bridges: {
+    exchangeRate: myRateBridge, // host-injected rate source
   },
 });
 
-// Post a credit sale on 30-day terms
-const invoice = await engine.repositories.journalEntries.create({
-  state: "posted",
-  date: new Date("2026-01-15"),
+// Post with foreign currency metadata
+await engine.repositories.journalEntries.create({
+  journalType: 'PURCHASES',
+  date: new Date(),
+  label: 'Import from China',
   journalItems: [
-    { account: arId, debit: 100_000, partnerId: "wholesale-1", maturityDate: new Date("2026-02-14") },
-    { account: revenueId, credit: 100_000 },
-  ],
-});
-
-// Customer pays $400 of the $1000 invoice
-const payment = await engine.repositories.journalEntries.create({
-  state: "posted",
-  date: new Date("2026-01-25"),
-  journalItems: [
-    { account: cashId, debit: 40_000 },
-    { account: arId, credit: 40_000, partnerId: "wholesale-1" },
-  ],
-});
-
-// Match the AR sides — partial settlement
-await engine.repositories.reconciliations.match({
-  account: arId,
-  items: [
-    { entry: invoice._id, itemIndex: 0 },
-    { entry: payment._id, itemIndex: 1 },
+    {
+      account: inventoryId,
+      debit: 120_500_00,    // BDT (base currency, always)
+      credit: 0,
+      currency: 'USD',
+      originalDebit: 1_000_00, // USD 1,000.00
+      exchangeRate: 120.50,
+    },
+    { account: apId, debit: 0, credit: 120_500_00 },
   ],
 });
-
-// Open items for this partner (subsidiary ledger)
-await engine.repositories.reconciliations.getOpenItems({
-  accountId: arId,
-  filter: { partnerId: "wholesale-1" },
-});
-
-// Customer statement with running balance + aged buckets
-import { generatePartnerLedger } from "@classytic/ledger";
-await generatePartnerLedger(
-  { AccountModel: engine.models.Account, JournalEntryModel: engine.models.JournalEntry },
-  {
-    controlAccountId: arId,
-    partnerId: "wholesale-1",
-    startDate: new Date("2026-01-01"),
-    endDate: new Date("2026-03-31"),
-  },
-);
-
-// Cross-partner aged A/R buckets
-import { generateAgedBalance } from "@classytic/ledger";
-await generateAgedBalance(
-  { AccountModel, JournalEntryModel, country: canadaPack },
-  { type: "receivable", contactField: "journalItems.partnerId" },
-);
-
-// Enforce per-customer credit limits
-import { creditLimitPlugin } from "@classytic/ledger/plugins";
-creditLimitPlugin({
-  arControlAccountId: arId,
-  JournalEntryModel: engine.models.JournalEntry,
-  getCreditLimit: async (partnerId) => Customer.findById(partnerId).then(c => c?.creditLimit ?? null),
-}).apply(engine.repositories.journalEntries);
 ```
 
-## Introspection
+## Features
 
-```ts
-const catalog = await engine.introspect.catalog(orgId);
-// { accounts, journalTypes, reports, fiscalPeriods }
-
-engine.introspect.accounts(orgId);
-engine.introspect.reports();   // sync — static catalog
-```
-
-## Structured Validation Errors
-
-```ts
-try {
-  await engine.record.sale(orgId, { ... });
-} catch (err) {
-  if (err instanceof AccountingError) {
-    err.status   // 400 | 402 | 403 | 404 | 409
-    err.code     // 'VALIDATION_ERROR' | 'NOT_FOUND' | 'CREDIT_LIMIT_EXCEEDED' | 'PERIOD_LOCKED_FISCAL' | ...
-    err.fields   // [{ path, issue, value }, ...]
-    err.toJSON();
-  }
-}
-```
-
-## Audit, Observability & Framework Integration
-
-Every operation flows through mongokit's `RepositoryContext`. Custom plugins can hook `before:create` / `after:create` / `before:update` / `after:update` / `after:match` to add audit trails, metrics, webhooks, or business rules — none of it is hardcoded into the core.
-
-The `_ledgerInternal` context flag (`'post' | 'unpost' | 'archive' | 'reverseMark' | 'fxRealize'`) tells plugins which engine operation is in flight, so guards (locks, credit limit, immutability) can exempt legitimate engine writes without affecting consumer code.
+| Feature | What it does |
+|---------|-------------|
+| **Double-entry** | `doubleEntryPlugin` validates debit = credit on every post |
+| **Integer cents** | All amounts in minor units (paisa/cents). No float errors. |
+| **Multi-tenant** | `organizationId` scoping via mongokit plugin |
+| **Multi-currency** | Optional foreign currency fields + FX realization + revaluation |
+| **Idempotency** | `idempotencyPlugin` prevents duplicate postings |
+| **Period locking** | `createLockPlugin` blocks edits to closed periods |
+| **Credit limits** | `creditLimitPlugin` enforces per-partner credit caps |
+| **Immutable guard** | `immutableGuardPlugin` prevents posted entry edits |
+| **Country packs** | Pluggable chart of accounts (BD, CA, custom) |
 
 ## Reports
 
-12 typed reports, all multi-tenant scoped, all returning structured JSON ready for any UI:
-
-| Report | Purpose |
-| --- | --- |
-| `trialBalance` | Debits/credits per account with running balances |
-| `balanceSheet` | Assets, liabilities, equity at a date with computed retained earnings |
-| `incomeStatement` | Revenue, COGS, expenses, net income for a period |
-| `generalLedger` | Per-account transaction detail with running balance |
-| `cashFlow` | Operating / investing / financing breakdown |
-| `agedBalance` | A/R or A/P bucketed by age, optionally per partner |
-| `partnerLedger` | Supplier/customer statement with opening + running balance + aged buckets |
-| `dimensionBreakdown` | Group by department/project/cost center |
-| `budgetVsActual` | Variance vs budget per account/period |
-| `revaluation` | Foreign-currency unrealized FX gain/loss at a date |
-| `closeFiscalPeriod` / `reopenFiscalPeriod` | Year-end close pipeline |
-
-## Engine Configuration
-
-```ts
-const engine = createAccountingEngine({
-  mongoose: mongoose.connection,
-  country: canadaPack,
-  currency: "CAD",
-  multiTenant: { orgField: "organizationId", orgRef: "Organization" },
-  multiCurrency: { enabled: true, currencies: ["USD", "EUR"] },
-  fiscalYearStartMonth: 1,
-  idempotency: true,
-  strictness: { immutable: true, requireActor: true },
-  schemaOptions: {
-    journalEntry: {
-      extraItemFields: {
-        partnerId: { type: String, index: true },
-        departmentId: { type: mongoose.Schema.Types.ObjectId },
-      },
-    },
-  },
-});
-```
-
-## Built-in Plugins
-
-| Plugin | Purpose |
-| --- | --- |
-| `doubleEntryPlugin` | Validates debits = credits, account existence, tenant integrity, posted-entry immutability |
-| `fiscalLockPlugin` | Prevents posting into closed fiscal periods (auto-wired) |
-| `dailyLockPlugin` | Per-branch `lastClosedDate` watermark for daily POS close |
-| `createLockPlugin` | Generic lock factory — compose your own scopes (bank recon, payroll, tax filings) |
-| `idempotencyPlugin` | Prevents duplicate entries by key (auto-wired when `idempotency: true`) |
-| `creditLimitPlugin` | Per-partner A/R credit limit enforcement |
-| `fxRealizationPlugin` | Books realized FX gain/loss when matched items have different exchange rates |
-
-`doubleEntryPlugin`, `fiscalLockPlugin`, and `idempotencyPlugin` (when enabled) are wired automatically by the engine. The others are opt-in via `.apply(engine.repositories.journalEntries)` or `.apply(engine.repositories.reconciliations)`.
-
-## Custom Journal Types
-
-The 15 built-in journal types (SALES, PURCHASES, GENERAL, PAYROLL, …) cover standard accounting. Register custom types **before** the first engine call:
-
-```ts
-import { registerJournalType } from "@classytic/ledger";
-
-registerJournalType("POS_SALES",  { code: "POS_SALES",  name: "POS Sales Journal" });
-registerJournalType("ECOM_SALES", { code: "ECOM_SALES", name: "E-Commerce Sales" });
-```
-
-Reference numbers use the type prefix (`POS_SALES/2025/03/0001`). The registry freezes after the first schema is created.
-
-## Country Packs
-
-A country pack ships the **chart of accounts** + accounting conventions for a jurisdiction. Tax (VAT/GST/HST/income-tax) lives in separate tax packages — see "Tax" below.
-
 ```ts
-import { defineCountryPack } from "@classytic/ledger";
-
-export const myPack = defineCountryPack({
-  code: "US",
-  name: "United States",
-  defaultCurrency: "USD",
-  retainedEarningsAccountCode: "3200",
-  accountTypes: [/* chart of accounts */],
-  journalTemplates: [
-    { code: "SALES", name: "Sales", journalType: "SALES", kind: "sale", sequencePrefix: "INV" },
-    // ...
-  ],
-});
+import {
+  generateTrialBalance,
+  generateBalanceSheet,
+  generateIncomeStatement,
+  generateCashFlow,
+  generateGeneralLedger,
+  generateAgedBalance,
+  generateBudgetVsActual,
+  generatePartnerLedger,
+  generateRevaluation,
+} from '@classytic/ledger';
 ```
 
-Available: `@classytic/ledger-ca` (Canada GIFI), `@classytic/ledger-bd` (Bangladesh BFRS).
+All reports accept `{ startDate, endDate, organizationId }` and return typed result objects.
 
-## Tax
+## Bridges
 
-`@classytic/ledger@0.7+` is intentionally tax-agnostic. The same separation Odoo (`account/` vs `l10n_*`), QuickBooks (Ledger vs TaxService), and Xero (accounting vs Xero Tax) all use.
-
-For tax computation, return generation, and repartition:
-
-- **`@classytic/bd-tax`** — Bangladesh income tax + VAT compute, IT-11GA forms, Mushak 9.1 returns, deduction optimizer, depreciation
-- **`@classytic/ca-tax`** *(planned)* — Canadian GST/HST/PST/QST compute, CRA GST34 form, ITC tracking
-- **Or your own** — tax engines just call `engine.repositories.journalEntries.create()` with the tax line items they want posted
-
-The country packs (`ledger-bd`, `ledger-ca`) still re-export their raw tax data tables (`TAX_CODES`, `TAX_CODES_BY_REGION`, `mushakReturnTemplate`, `craReturnTemplate`) as named exports so tax packages can lift them — they're just no longer wired into the `CountryPack` contract.
-
-## Invoice Engine Integration
-
-Wire `@classytic/invoice` to the ledger with one call — no manual journal wiring needed:
+All optional. All methods optional. Features degrade gracefully.
 
 ```ts
-import { createAccountingEngine } from "@classytic/ledger";
-import { createLedgerBridge } from "@classytic/ledger/sync";
-import { createInvoiceEngine } from "@classytic/invoice";
-import { canadaPack } from "@classytic/ledger-ca";
-
-const accounting = createAccountingEngine({
-  mongoose: mongoose.connection,
-  country: canadaPack,
-  currency: "CAD",
-  multiTenant: { orgField: "organizationId", orgRef: "Organization" },
-  idempotency: true,
-});
+import type { ExchangeRateBridge, SourceBridge, NotificationBridge } from '@classytic/ledger';
 
-const invoicing = createInvoiceEngine({
-  mongoose: mongoose.connection,
-  ledger: createLedgerBridge(accounting, {
-    accounts: {
-      receivable: "1200",     // Accounts Receivable
-      payable: "2000",        // Accounts Payable
-      revenue: "4000",        // Revenue
-      expense: "5000",        // Expenses
-      taxPayable: "2100",     // Tax Payable
-      taxReceivable: "1150",  // Tax Receivable
-      cash: "1000",           // Cash / Bank
-    },
-  }),
+const engine = createAccountingEngine({
+  // ...
+  bridges: {
+    exchangeRate: myRateBridge,    // FX rate lookup
+    source: mySourceBridge,        // resolve external doc refs
+    notification: myNotifBridge,   // alert on reversals, period locks
+  },
 });
 ```
 
-The bridge handles all 5 move types (`out_invoice`, `in_invoice`, `out_refund`, `in_refund`, `receipt`), payment recording, and reversal. See [docs/sync.md](docs/sync.md) for the full mapping table and configuration options.
-
-For custom subledgers (inventory, payroll, etc.) that don't use `@classytic/invoice`, see [docs/subledger-integration.md](docs/subledger-integration.md) for the manual `PostingContract` pattern.
-
-## URL-Driven Queries
-
-Parse URL query parameters directly into paginated repository queries via mongokit's `QueryParser`:
+## Plugins
 
 ```ts
-const parser = engine.createQueryParser("journalEntry");
-const parsed = parser.parse(req.query);
-// ?state=posted&date[gte]=2025-01-01&sort=-date&limit=25
-
-const result = await engine.repositories.journalEntries.getAll({
-  ...parsed,
-  filters: { ...parsed.filters, organizationId },
-});
+import {
+  doubleEntryPlugin,
+  idempotencyPlugin,
+  creditLimitPlugin,
+  fxRealizationPlugin,
+  immutableGuardPlugin,
+  createLockPlugin,
+} from '@classytic/ledger';
 ```
 
-Available for all 6 models: `account`, `journalEntry`, `fiscalPeriod`, `budget`, `reconciliation`, `journal`.
+Plugins attach to mongokit repository hooks. They run at POLICY priority before any query.
 
 ## Subpath Exports
 
-| Path | Contents |
-| --- | --- |
-| `@classytic/ledger`           | Engine, Money, plugins, reports, types |
-| `@classytic/ledger/sync`      | `createLedgerBridge`, `wireImport`, `wireExport`, bank/invoice/JE mappers |
-| `@classytic/ledger/money`     | `Money` class |
-| `@classytic/ledger/reports`   | Standalone report generators |
-| `@classytic/ledger/plugins`   | All plugins |
-| `@classytic/ledger/exports`   | CSV export + QuickBooks field maps |
-| `@classytic/ledger/country`   | `defineCountryPack`, `CountryPack` |
-| `@classytic/ledger/constants` | Categories, journal types, currencies |
-
-## Testing
-
-```bash
-npm test                            # 1327 tests, 77 files
-npm run smoke                       # full pipeline against published dist/
-npx vitest run tests/e2e/           # end-to-end scenarios
-npx vitest run tests/scenarios/     # multi-step business scenarios
-npx vitest run tests/hardening/     # edge cases & invariants
+```ts
+import { Money } from '@classytic/ledger/money';
+import { CATEGORIES, CURRENCIES } from '@classytic/ledger/constants';
+import { defineCountryPack } from '@classytic/ledger/country';
+import { exportToCsv, quickbooksFieldMap } from '@classytic/ledger/exports';
 ```
 
-Coverage includes:
-
-- Canadian small-business full-year lifecycle (open → post → close → reopen)
-- Multi-year fiscal cycles with retained-earnings rollover
-- Multi-currency trading with realized + unrealized FX
-- Multi-tenant report isolation (org A cannot see org B)
-- All 12 reports with month / quarter / year / custom date ranges
-- Reversal and correction workflows
-- Custom journal type registry → schema → posting pipeline
-- Item-level matching: 1-to-1, 1-to-many, partial settlement, unmatch
-- Per-partner credit limit enforcement + reversal exemption
-- FX realization plugin auto-booking gain/loss on cross-rate match
-- Full ERP A/P + A/R cycle (bill receipt → match → supplier statement → aged balance)
-- Double-entry conservation across all entries
-- Money arithmetic hardening (overflow, penny-leak, float traps)
-- O-Level / A-Level / university textbook accounting problems
-
-## Requirements
+## Architecture
 
-- Node.js >= 22
-- MongoDB (replica set recommended for transactions)
-- Mongoose >= 9.4.1
-- @classytic/mongokit >= 3.5.6
+- Repositories extend `@classytic/mongokit` Repository directly
+- No service layer — domain verbs live on the repository
+- No barrel re-exports — import from source paths
+- Events: arc-compatible `DomainEvent` / `EventTransport` shapes
+- Country packs: pluggable chart of accounts + journal type seeds
+- Tax: NOT in ledger. Use `@classytic/bd-tax` for Bangladesh tax calculations.
 
 ## License
 

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, u as ExchangeRateBridge } from "../index-Dih0lM65.mjs";
+export { EntryReversedNotification, ExchangeRateBridge, 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 };