@classytic/ledger 0.7.0 → 0.8.0

package/docs/country-packs.md

@@ -1,6 +1,6 @@
 # Country Packs
 
-A country pack provides everything country-specific: chart of accounts template, tax codes, tax report templates, and region definitions.
+A country pack provides the **chart of accounts** + accounting conventions for a jurisdiction (retained-earnings code, COGS group, journal templates, fiscal year start month, report labels). Country packs are intentionally **tax-agnostic** in 0.7+ — tax computation, return templates, and tax code tables live in dedicated tax packages (`@classytic/bd-tax`, the planned `@classytic/ca-tax`, or your own).
 
 ## Using a Country Pack
 
@@ -9,6 +9,7 @@ import { createAccountingEngine } from '@classytic/ledger';
 import { canadaPack } from '@classytic/ledger-ca';
 
 const accounting = createAccountingEngine({
+  mongoose: mongoose.connection,
   country: canadaPack,
   currency: 'CAD',
 });
@@ -16,46 +17,44 @@ const accounting = createAccountingEngine({
 
 ## Available Packs
 
-| Package | Country | Account Types | Tax Codes |
+| Package | Country | Account Types | Notes |
 |---|---|---|---|
-| `@classytic/ledger-ca` | Canada | GIFI (CRA) | GST/HST/PST/QST |
+| `@classytic/ledger-ca` | Canada | GIFI (CRA-aligned) | Re-exports `TAX_CODES`, `TAX_CODES_BY_REGION`, `craReturnTemplate` as raw constants for tax engines to lift |
+| `@classytic/ledger-bd` | Bangladesh | BFRS (~600 accounts) | Re-exports `TAX_CODES`, `TAX_CODES_BY_DIVISION`, `mushakReturnTemplate` as raw constants for tax engines to lift |
 
 ## Creating a Custom Country Pack
 
 ```typescript
 import { defineCountryPack } from '@classytic/ledger';
-import type { AccountType, TaxCode } from '@classytic/ledger';
+import type { AccountType } from '@classytic/ledger';
 
 const myPack = defineCountryPack({
   code: 'US',
   name: 'United States',
   defaultCurrency: 'USD',
+  retainedEarningsAccountCode: '3200',
+  cogsGroupCode: 'Cost of Sales',
   accountTypes: [
     {
       code: '1000',
       name: 'Cash',
-      category: 'Balance Sheet-Assets',
-      mainType: 'Assets',
-      normalBalance: 'debit',
+      category: 'Balance Sheet-Asset',
+      description: 'Cash and equivalents',
+      parentCode: null,
       isGroup: false,
       isTotal: false,
+      cashFlowCategory: 'Operating',
     },
     // ... more account types
   ],
-  taxCodes: {
-    STATE_TAX: {
-      code: 'STATE_TAX',
-      name: 'State Sales Tax',
-      taxType: 'sales',
-      rate: 0.06,
-      direction: 'collected',
-      description: 'State sales tax',
-      active: true,
-    },
-  },
-  taxCodesByRegion: { CA: ['STATE_TAX'] },
-  regions: ['CA', 'NY', 'TX'],
-  taxReport: undefined, // optional tax return template
+  // Optional: declarative journal templates seeded per organization
+  journalTemplates: [
+    { code: 'SALES', name: 'Sales', journalType: 'SALES', kind: 'sale', sequencePrefix: 'INV' },
+    { code: 'PURCHASE', name: 'Purchases', journalType: 'PURCHASES', kind: 'purchase', sequencePrefix: 'BILL' },
+    { code: 'BANK', name: 'Bank', journalType: 'CASH_RECEIPTS', kind: 'bank', sequencePrefix: 'BNK' },
+    { code: 'CASH', name: 'Cash', journalType: 'CASH_PAYMENTS', kind: 'cash', sequencePrefix: 'CSH' },
+    { code: 'MISC', name: 'Miscellaneous', journalType: 'MISC', kind: 'general', sequencePrefix: 'JE' },
+  ],
 });
 ```
 
@@ -66,19 +65,30 @@ interface CountryPack {
   code: string;              // ISO 3166-1 alpha-2
   name: string;
   defaultCurrency: string;
-  accountTypes: AccountType[];
-  taxCodes: Record<string, TaxCode>;
-  taxCodesByRegion: Record<string, string[]>;
-  regions: string[];
-  taxReport?: TaxReportTemplate;
+  accountTypes: readonly AccountType[];
+
+  // Optional declarative journal templates for engine.repositories.journals.seedDefaults()
+  journalTemplates?: readonly JournalTemplate[];
+
+  // Country-specific report defaults
+  retainedEarningsAccountCode?: string;
+  retainedEarningsDisplayCode?: string;
+  currentYearEarningsCode?: string;
+  cogsGroupCode?: string;
+  reportLabels?: {
+    assets?: string;
+    liabilities?: string;
+    equity?: string;
+    revenue?: string;
+    expenses?: string;
+  };
 
   // Auto-generated helpers:
-  getPostingAccountTypes(): AccountType[];
+  getPostingAccountTypes(): readonly AccountType[];
   getAccountType(code: string): AccountType | undefined;
   isValidAccountType(code: string): boolean;
   isPostingAccount(code: string): boolean;
-  getTaxCodesForRegion(region: string): TaxCode[];
-  flattenAccountTypes(): AccountType[];
+  flattenAccountTypes(): readonly AccountType[];
 }
 ```
 
@@ -88,30 +98,44 @@ interface CountryPack {
 interface AccountType {
   code: string;
   name: string;
-  category: CategoryKey;        // e.g. 'Balance Sheet-Assets', 'Income Statement-Income'
-  mainType: MainType;           // 'Assets', 'Liabilities', 'Equity', etc.
-  normalBalance: 'debit' | 'credit';
-  isGroup: boolean;             // structural grouping header (not postable)
-  isTotal: boolean;             // calculated total row (not postable)
-  cashFlowCategory?: string;    // 'Operating', 'Investing', 'Financing'
-  taxMetadata?: TaxMetadata;    // for virtual tax sub-accounts
+  category: CategoryKey;        // e.g. 'Balance Sheet-Asset', 'Income Statement-Income'
+  description: string;
+  parentCode: string | null;    // grouping hierarchy
+  isGroup?: boolean;            // structural grouping header (not postable)
+  isTotal?: boolean;            // calculated total row (not postable)
+  cashFlowCategory?: 'Operating' | 'Investing' | 'Financing' | null;
+  taxMetadata?: TaxMetadata;    // opaque metadata pass-through (no logic)
+  deprecated?: boolean;
+  replacedBy?: string;
+  notes?: string;
 }
 ```
 
-Only accounts where `isGroup === false && isTotal === false` are posting accounts.
+Only accounts where `isGroup !== true && isTotal !== true` are posting accounts.
 
-## TaxCode Structure
+## JournalTemplate Structure
 
 ```typescript
-interface TaxCode {
-  code: string;
+interface JournalTemplate {
+  code: string;                 // 'SALES', 'PURCHASE', 'BANK', ...
   name: string;
-  taxType: string;                    // e.g. 'GST', 'HST', 'PST'
-  rate: number;                       // e.g. 0.05 for 5%
-  direction: 'collected' | 'recoverable' | 'paid';
-  province?: string;
-  reportLines?: number[];             // lines on the tax return
-  description: string;
-  active: boolean;
+  journalType: string;          // one of the registered JOURNAL_TYPES codes
+  sequencePrefix?: string;      // defaults to `code`
+  sequenceStartNum?: number;    // defaults to 1
+  kind?: 'general' | 'sale' | 'purchase' | 'bank' | 'cash' | string;
+  defaultDebitAccountRole?: string;
+  defaultCreditAccountRole?: string;
 }
 ```
+
+When the consumer calls `engine.repositories.journals.seedDefaults(orgId)`, the engine creates one Journal document per template with an isolated sequence counter.
+
+## Tax — out of scope
+
+Country packs in 0.7+ do **not** carry tax code tables, tax return templates, or tax repartition mappings. That work belongs in tax engine packages:
+
+- `@classytic/bd-tax` — Bangladesh income tax slabs, IT-11GA forms, VAT/TDS/VDS computation, Mushak 9.1 return generator, deduction optimizer
+- `@classytic/ca-tax` (planned) — Canadian GST/HST/PST/QST computation, CRA GST34 form, ITC tracking
+- Or roll your own — a tax engine just calls `engine.repositories.journalEntries.create()` with the tax line items it wants posted
+
+Country packs that previously bundled tax data (`ledger-bd`, `ledger-ca`) still re-export it as named constants — `TAX_CODES`, `TAX_CODES_BY_REGION` / `TAX_CODES_BY_DIVISION`, `mushakReturnTemplate`, `craReturnTemplate` — so tax engines can lift it directly without re-typing.

package/docs/engine.md

@@ -21,7 +21,7 @@ const accounting = createAccountingEngine({
 
 | Option | Type | Required | Description |
 |---|---|---|---|
-| `country` | `CountryPack` | Yes | Country pack (account types, tax codes) |
+| `country` | `CountryPack` | Yes | Country pack (chart of accounts + journal templates) |
 | `currency` | `string` | Yes | ISO 4217 currency code |
 | `multiTenant` | `{ orgField, orgRef }` | No | Multi-tenant configuration |
 | `fiscalYearStartMonth` | `number` | No | 1-12, default 1 (January) |
@@ -129,9 +129,10 @@ See [Reports](reports.md) for details.
 accounting.getPostingAccountTypes()   // → AccountType[]
 accounting.isValidAccountType('1000') // → boolean
 accounting.getAccountType('1000')     // → AccountType | undefined
-accounting.getTaxCodesForRegion('ON') // → TaxCode[]
 ```
 
+> Tax code lookups have moved out of the ledger in 0.7+ — they live in dedicated tax engine packages (`@classytic/bd-tax`, etc.). See [Country Packs](country-packs.md#tax--out-of-scope).
+
 ## Logger Interface
 
 The engine accepts a logger that implements:

package/docs/subledger-integration.md

@@ -1,6 +1,20 @@
 # Subledger Integration
 
-This guide explains how to integrate external subledgers (billing, inventory, payroll, etc.) with `@classytic/ledger`. The ledger provides **type-only posting contracts** — your application code is responsible for wiring subledgers to the journal entry repository.
+This guide explains how to integrate external subledgers (billing, inventory, payroll, etc.) with `@classytic/ledger`.
+
+## Which pattern should I use?
+
+| Subledger | Recommended approach |
+|---|---|
+| `@classytic/invoice` | Use `createLedgerBridge()` from `@classytic/ledger/sync` — see [sync.md](sync.md) |
+| Custom invoicing, billing, or any system with the `LedgerBridge` interface | Use `createLedgerBridge()` — same bridge, no `@classytic/invoice` dependency needed |
+| Inventory, payroll, or other custom subledgers | Use the `PostingContract` pattern described below |
+
+If you're integrating with `@classytic/invoice`, **start with [sync.md](sync.md)** — the bridge handles all the wiring for you. This document covers the manual `PostingContract` pattern for custom subledgers that don't use the invoice engine.
+
+---
+
+The ledger provides **type-only posting contracts** — your application code is responsible for wiring subledgers to the journal entry repository.
 
 ## Responsibility Boundaries
 
@@ -13,7 +27,7 @@ This guide explains how to integrate external subledgers (billing, inventory, pa
 | Idempotency (duplicate guard) | Yes — plugin checks `idempotencyKey` uniqueness | Must generate deterministic keys |
 | Posted-entry protection | Yes — plugin blocks field changes on posted entries; fully immutable when `strictness.immutable` enabled | Use `reverse()` for corrections; `unpost()` available when immutable mode is off |
 | Account code → ObjectId resolution | No | Yes — look up account by `accountType` code |
-| Tax calculation | No — country packs define tax codes, not tax logic | Yes — compute tax amounts before posting |
+| Tax calculation | No — tax engines are separate packages (`@classytic/bd-tax`, `@classytic/ca-tax`, etc.) | Yes — compute tax amounts before posting via your tax engine of choice |
 | Source document validation | No | Yes — implement `validate()` on the contract |
 | Creating the journal entry | No — provides `repo.post()` | Yes — call `repo.create()` then `repo.post()` |
 | Transaction coordination | No | Yes — wrap subledger + ledger writes in a session |
@@ -268,18 +282,25 @@ The ledger's `reverse()` creates a new journal entry with debits and credits swa
 
 ## Tax Handling
 
-The ledger's country packs define **tax code metadata** (names, rates, regions) but do **not** compute tax amounts. Tax calculation is the application's responsibility:
+`@classytic/ledger@0.7+` is intentionally tax-agnostic. Country packs ship the chart of accounts and journal templates only — tax computation, return generation, and tax-period filing locks all live in dedicated tax engine packages:
+
+- **`@classytic/bd-tax`** — Bangladesh income tax (IT-11GA), VAT/TDS/VDS computation, Mushak 9.1 returns
+- **`@classytic/ca-tax`** *(planned)* — Canadian GST/HST/PST/QST computation, CRA GST34 form
+- **Or roll your own** — a tax engine just computes amounts and posts the resulting tax line items via `engine.repositories.journalEntries.create()`
+
+The country packs `@classytic/ledger-bd` and `@classytic/ledger-ca` still re-export the raw tax data tables (`TAX_CODES`, `TAX_CODES_BY_DIVISION` / `TAX_CODES_BY_REGION`, `mushakReturnTemplate`, `craReturnTemplate`) as named constants so tax engines can lift them.
+
+The integration pattern:
 
-1. Look up applicable tax codes from the country pack (`accounting.getTaxCodesForRegion('ON')`)
-2. Compute tax amounts in your subledger / business logic
-3. Include tax lines as separate `SubledgerJournalItem` entries with the appropriate tax liability account code
-4. The ledger stores and reports on whatever you post — it does not validate tax arithmetic
+1. Compute tax amounts in your tax engine (input: invoice line items + jurisdiction; output: tax line items with account codes)
+2. Include those tax line items in the same `journalEntries.create()` call as the rest of the entry
+3. The ledger stores and reports on whatever you post — it does not validate tax arithmetic
 
 ## What the Ledger Does Not Do
 
 To set clear expectations, the ledger intentionally does **not**:
 
-- **Compute taxes** — country packs provide tax code catalogs, not calculation engines
+- **Compute taxes** — that lives in dedicated tax engine packages (see above)
 - **Manage invoices, bills, or payments** — these are subledger concerns
 - **Orchestrate multi-step workflows** — approval routing, email notifications, etc. are app-level
 - **Resolve account codes to ObjectIds** — the app must map country-pack codes to tenant accounts

package/docs/sync.md

@@ -0,0 +1,330 @@
+# Sync — Invoice Bridge, Import & Export
+
+`@classytic/ledger/sync` is the integration subpath for connecting external systems to the ledger.
+
+```typescript
+import {
+  // Invoice engine bridge (recommended)
+  createLedgerBridge,
+
+  // Import/export pipeline
+  wireImport,
+  wireExport,
+
+  // Mapper factories (fin-io canonical shapes → JournalEntry)
+  bankStatementMapper,
+  invoiceMapper,
+  journalEntryMapper,
+  openingBalanceMapper,
+} from '@classytic/ledger/sync';
+```
+
+---
+
+## Invoice Engine Integration
+
+### Recommended: `createLedgerBridge()`
+
+Wire `@classytic/invoice` to `@classytic/ledger` with one call. The bridge handles account mapping, tax lines, credit notes, payments, and reversals — no manual journal wiring needed.
+
+```typescript
+import { createAccountingEngine } from '@classytic/ledger';
+import { createLedgerBridge } from '@classytic/ledger/sync';
+import { createInvoiceEngine } from '@classytic/invoice';
+import { canadaPack } from '@classytic/ledger-ca';
+
+// 1. Create the accounting engine
+const accounting = createAccountingEngine({
+  mongoose: connection,
+  country: canadaPack,
+  currency: 'CAD',
+  multiTenant: { orgField: 'organizationId', orgRef: 'Organization' },
+  idempotency: true,
+});
+
+// 2. Create the bridge — map your chart of accounts once
+const bridge = createLedgerBridge(accounting, {
+  accounts: {
+    receivable: '1200',     // Accounts Receivable
+    payable: '2000',        // Accounts Payable
+    revenue: '4000',        // Revenue
+    expense: '5000',        // Cost of Goods Sold / Expenses
+    taxPayable: '2100',     // HST/GST/VAT Payable
+    taxReceivable: '1150',  // HST/GST/VAT Receivable (Input Tax Credit)
+    cash: '1000',           // Cash / Bank
+  },
+});
+
+// 3. Pass the bridge to the invoice engine — done
+const invoicing = createInvoiceEngine({
+  mongoose: connection,
+  ledger: bridge,
+  // ... other invoice config
+});
+```
+
+From this point, every invoice lifecycle operation automatically posts to the ledger:
+
+- **`invoicing.services.posting.post(id)`** → creates a balanced journal entry
+- **`invoicing.services.payment.recordPayment(input)`** → posts a payment entry (DR Cash, CR AR)
+- **`invoicing.services.posting.cancel(id, reason)`** → reverses the journal entry
+- **`invoicing.services.posting.void(id, reason)`** → reverses the journal entry (even if partially paid)
+
+### How the bridge maps each move type
+
+| Invoice Move Type | Journal Lines | Journal Type |
+|---|---|---|
+| `out_invoice` (Customer Invoice) | DR Receivable (total), CR Revenue (per line), CR Tax Payable | `SALES` |
+| `in_invoice` (Vendor Bill) | DR Expense (per line), DR Tax Receivable, CR Payable (total) | `PURCHASES` |
+| `out_refund` (Customer Credit Note) | CR Receivable, DR Revenue (per line), DR Tax Payable | `SALES` |
+| `in_refund` (Vendor Credit Note) | DR Payable, CR Expense (per line), CR Tax Receivable | `PURCHASES` |
+| `receipt` (POS Receipt) | DR Receivable/Cash, CR Revenue (per line), CR Tax Payable | `CASH_RECEIPTS` |
+
+All amounts are integer cents. Tax lines are only added when `taxAmount > 0`.
+
+### Payment recording
+
+When the invoice engine records a payment, the bridge calls `engine.record.payment()`:
+
+```
+DR Cash (1000)        $500.00
+CR Receivable (1200)  $500.00
+```
+
+An idempotency key is automatically derived from the payment ID (`payment:{paymentId}`), preventing duplicate journal entries on retry.
+
+### Reversal
+
+When an invoice is cancelled or voided, the bridge calls `engine.repositories.journalEntries.reverse()`, which creates a mirror entry with debits and credits swapped and links both entries bidirectionally.
+
+### Bridge configuration options
+
+#### `receiptAccount`
+
+Override the debit account for POS receipts. By default, receipts debit the `receivable` account. If your receipts are immediately paid (no A/R), point this at cash:
+
+```typescript
+createLedgerBridge(accounting, {
+  accounts: { ... },
+  receiptAccount: '1000',  // Receipts debit Cash directly
+});
+```
+
+#### `resolvePaymentAccounts`
+
+Custom resolver for payment accounts. Use when you need to determine AR vs AP based on context (e.g., vendor bill payments should clear AP, not AR):
+
+```typescript
+createLedgerBridge(accounting, {
+  accounts: { ... },
+  resolvePaymentAccounts: (input) => {
+    const isVendor = vendorInvoiceIds.has(input.invoiceId);
+    return {
+      receivableOrPayable: isVendor ? '2000' : '1200',
+      cash: '1000',
+    };
+  },
+});
+```
+
+### Double-entry guarantee
+
+The bridge uses `engine.record.adjustment()` internally. This routes through the ledger's double-entry plugin, which validates `sum(debits) === sum(credits)` before persisting. If the invoice engine sends unbalanced data, the ledger rejects it with a structured validation error.
+
+---
+
+### Alternative: Manual wiring (without `createLedgerBridge`)
+
+If you need full control over the journal entry shape — for example, to add dimension fields, use different accounts per line, or handle complex tax scenarios — you can implement the `LedgerBridge` interface yourself:
+
+```typescript
+import type { LedgerBridge } from '@classytic/ledger/sync';
+
+const ledgerBridge: LedgerBridge = {
+  async createJournalEntry(input) {
+    // Use record.adjustment() for multi-line entries with tax
+    const entry = await accounting.record.adjustment(input.organizationId, {
+      date: input.date,
+      label: `Invoice ${input.invoiceId}`,
+      journalType: 'SALES',
+      lines: [
+        { account: '1200', debit: input.totalAmount },
+        ...input.lines.map(line => ({
+          account: '4000',
+          credit: line.amount,
+          label: line.description,
+        })),
+        ...(input.taxAmount > 0
+          ? [{ account: '2100', credit: input.taxAmount, label: 'Tax' }]
+          : []),
+      ],
+    }, {
+      idempotencyKey: input.idempotencyKey,
+    });
+    return String((entry as any)._id);
+  },
+
+  async reverseJournalEntry(journalEntryId, reason) {
+    const { reversal } = await accounting.repositories.journalEntries
+      .reverse(journalEntryId);
+    return String((reversal as any)._id);
+  },
+
+  async recordPayment(input) {
+    const entry = await accounting.record.payment(input.organizationId, {
+      date: input.date,
+      amount: input.amount,
+      fromReceivableAccount: '1200',
+      toCashAccount: '1000',
+      label: `Payment ${input.paymentId} for ${input.invoiceId}`,
+    }, {
+      idempotencyKey: `payment:${input.paymentId}`,
+    });
+    return String((entry as any)._id);
+  },
+};
+
+// Then pass to the invoice engine
+const invoicing = createInvoiceEngine({
+  mongoose: connection,
+  ledger: ledgerBridge,
+});
+```
+
+This gives you the same integration but with full control over account resolution, dimension fields, and tax line construction.
+
+### Using `LedgerBridge` without `@classytic/invoice`
+
+The bridge types are generic — any invoicing system that calls these 3 methods works:
+
+```typescript
+import type { LedgerBridge, LedgerPostInput, LedgerPaymentInput } from '@classytic/ledger/sync';
+
+// Use createLedgerBridge() for standard mapping
+const bridge: LedgerBridge = createLedgerBridge(accounting, { accounts: { ... } });
+
+// Post an invoice
+const jeId = await bridge.createJournalEntry({
+  organizationId: 'org_1',
+  invoiceId: 'INV-001',
+  moveType: 'out_invoice',
+  partnerId: 'customer-123',
+  date: new Date(),
+  currency: 'USD',
+  lines: [
+    { description: 'Consulting', amount: 100000, taxAmount: 13000, taxCode: 'HST' },
+  ],
+  totalAmount: 113000,
+  taxAmount: 13000,
+});
+
+// Record a payment
+await bridge.recordPayment({
+  organizationId: 'org_1',
+  invoiceId: 'INV-001',
+  paymentId: 'PAY-001',
+  amount: 113000,
+  currency: 'USD',
+  date: new Date(),
+  method: 'bank_transfer',
+});
+
+// Reverse (cancel/void)
+await bridge.reverseJournalEntry(jeId, 'Invoice cancelled');
+```
+
+---
+
+## Bank Statement Import
+
+Import bank transactions from any format supported by `@classytic/fin-io`:
+
+```typescript
+import { parseOfx } from '@classytic/fin-io/ofx';
+import { wireImport, bankStatementMapper } from '@classytic/ledger/sync';
+
+const parsed = parseOfx(buffer);
+if (!parsed.ok) throw new Error(parsed.error);
+
+const report = await wireImport({
+  source: parsed.data.flatMap(s => s.transactions),
+  mapper: bankStatementMapper({
+    bankAccountId: bankAccount._id,
+    suspenseAccountId: suspenseAccount._id,
+    categorize: (txn) => knownVendors[txn.counterparty?.name]?.accountId,
+  }),
+  journalEntries: engine.repositories.journalEntries,
+  context: { organizationId },
+}).run();
+
+console.log(`Imported ${report.inserted}, skipped ${report.skipped} duplicates`);
+```
+
+### Available mappers
+
+| Mapper | Source | Output |
+|---|---|---|
+| `bankStatementMapper` | `CanonicalTransaction` (OFX, CAMT, MT940, CSV, Plaid) | 2-line JE: Cash ↔ Suspense |
+| `invoiceMapper` | `CanonicalInvoice` (QBO, Xero JSON) | Multi-line JE: AR/AP ↔ Revenue/Expense ↔ Tax |
+| `journalEntryMapper` | `CanonicalJournalEntry` (QBO, Xero manual journals) | 1:1 mapping |
+| `openingBalanceMapper` | `TrialBalanceInput` | Multi-line opening balance entry |
+
+### Idempotency
+
+Re-running an import on the same file produces zero duplicates. Each mapper extracts a stable `externalId` from the source record (e.g., OFX `FITID`, CAMT `NtryRef`). The `wireImport` pipeline checks for existing entries before creating.
+
+For best performance, provide a `findExisting` callback and add a partial index on `{ organizationId: 1, _externalId: 1 }`.
+
+---
+
+## Export
+
+Stream ledger data to external formats:
+
+```typescript
+import { wireExport } from '@classytic/ledger/sync';
+
+const report = await wireExport({
+  query: { organizationId: 'org_1', state: 'posted' },
+  sink: {
+    fromJournalEntry: (entry) => transformToCSVRow(entry),
+    emit: async (rows) => csvStream.write(rows),
+    flush: async () => csvStream.end(),
+  },
+  journalEntries: engine.repositories.journalEntries,
+  options: { batchSize: 500 },
+}).run();
+```
+
+---
+
+## Writing Custom Mappers
+
+Implement `ImportMapper<TRaw>` for any data source:
+
+```typescript
+import type { ImportMapper } from '@classytic/ledger/sync';
+
+interface MyPayrollRecord {
+  id: string;
+  employeeName: string;
+  grossPay: number;
+  taxWithheld: number;
+  netPay: number;
+  date: Date;
+}
+
+const payrollMapper: ImportMapper<MyPayrollRecord> = {
+  externalId: (record) => `payroll:${record.id}`,
+
+  toJournalEntry: (record, ctx) => ({
+    date: record.date,
+    label: `Payroll — ${record.employeeName}`,
+    journalItems: [
+      { account: salaryExpenseId, debit: record.grossPay, credit: 0 },
+      { account: taxPayableId, debit: 0, credit: record.taxWithheld },
+      { account: cashId, debit: 0, credit: record.netPay },
+    ],
+  }),
+};
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/ledger",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Production-grade double-entry accounting engine for MongoDB — schemas, reports, tax, multi-tenant",
   "type": "module",
   "sideEffects": false,
@@ -42,6 +42,11 @@
       "types": "./dist/exports/index.d.mts",
       "import": "./dist/exports/index.mjs",
       "default": "./dist/exports/index.mjs"
+    },
+    "./sync": {
+      "types": "./dist/sync/index.d.mts",
+      "import": "./dist/sync/index.mjs",
+      "default": "./dist/sync/index.mjs"
     }
   },
   "files": [
@@ -78,9 +83,28 @@
     "url": "git+https://github.com/classytic/accounting.git"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.5.5",
+    "@classytic/fin-io": ">=0.1.0",
+    "@classytic/mongokit": ">=3.5.6",
     "mongoose": ">=9.4.1"
   },
+  "peerDependenciesMeta": {
+    "@classytic/fin-io": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@classytic/fin-io": "file:../fin-io",
+    "@classytic/mongokit": "^3.5.6",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "knip": "^6.3.0",
+    "mongodb-memory-server": "^10.2.3",
+    "mongoose": "^9.4.1",
+    "tsdown": "^0.21.5",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -99,17 +123,5 @@
     "smoke": "node scripts/smoke.mjs",
     "prepublishOnly": "npm run check && npm run build && npm run typecheck && npm test && npm run smoke",
     "release": "npm run check && npm run build && npm run typecheck && npm test && npm run smoke && npm publish --access public"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
-    "@classytic/mongokit": "^3.5.5",
-    "@types/node": "^22.0.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "knip": "^6.3.0",
-    "mongodb-memory-server": "^10.2.3",
-    "mongoose": "^9.4.1",
-    "tsdown": "^0.21.5",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
   }
 }