@classytic/ledger 0.1.3

package/docs/country-packs.md

@@ -0,0 +1,117 @@
+# Country Packs
+
+A country pack provides everything country-specific: chart of accounts template, tax codes, tax report templates, and region definitions.
+
+## Using a Country Pack
+
+```typescript
+import { createAccountingEngine } from '@classytic/ledger';
+import { canadaPack } from '@classytic/ledger-ca';
+
+const accounting = createAccountingEngine({
+  country: canadaPack,
+  currency: 'CAD',
+});
+```
+
+## Available Packs
+
+| Package | Country | Account Types | Tax Codes |
+|---|---|---|---|
+| `@classytic/ledger-ca` | Canada | GIFI (CRA) | GST/HST/PST/QST |
+
+## Creating a Custom Country Pack
+
+```typescript
+import { defineCountryPack } from '@classytic/ledger';
+import type { AccountType, TaxCode } from '@classytic/ledger';
+
+const myPack = defineCountryPack({
+  code: 'US',
+  name: 'United States',
+  defaultCurrency: 'USD',
+  accountTypes: [
+    {
+      code: '1000',
+      name: 'Cash',
+      category: 'Balance Sheet-Assets',
+      mainType: 'Assets',
+      normalBalance: 'debit',
+      isGroup: false,
+      isTotal: false,
+    },
+    // ... 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
+});
+```
+
+## CountryPack Interface
+
+```typescript
+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;
+
+  // Auto-generated helpers:
+  getPostingAccountTypes(): AccountType[];
+  getAccountType(code: string): AccountType | undefined;
+  isValidAccountType(code: string): boolean;
+  isPostingAccount(code: string): boolean;
+  getTaxCodesForRegion(region: string): TaxCode[];
+  flattenAccountTypes(): AccountType[];
+}
+```
+
+## AccountType Structure
+
+```typescript
+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
+}
+```
+
+Only accounts where `isGroup === false && isTotal === false` are posting accounts.
+
+## TaxCode Structure
+
+```typescript
+interface TaxCode {
+  code: string;
+  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;
+}
+```

package/docs/engine.md

@@ -0,0 +1,147 @@
+# Engine & Configuration
+
+The `AccountingEngine` is the main entry point. It holds your configuration and provides factory methods for schemas, repositories, and reports.
+
+## Creating an Engine
+
+```typescript
+import { createAccountingEngine } from '@classytic/ledger';
+import { canadaPack } from '@classytic/ledger-ca';
+
+const accounting = createAccountingEngine({
+  country: canadaPack,
+  currency: 'CAD',
+  multiTenant: { orgField: 'business', orgRef: 'Business' },
+  fiscalYearStartMonth: 4, // April (default: 1 = January)
+  logger: winstonLogger,   // optional, defaults to console
+});
+```
+
+## Configuration Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `country` | `CountryPack` | Yes | Country pack (account types, tax codes) |
+| `currency` | `string` | Yes | ISO 4217 currency code |
+| `multiTenant` | `{ orgField, orgRef }` | No | Multi-tenant configuration |
+| `fiscalYearStartMonth` | `number` | No | 1-12, default 1 (January) |
+| `logger` | `Logger` | No | `{ warn, error, info }` interface; defaults to console |
+| `audit` | `AuditConfig` | No | Actor tracking on journal entries (see below) |
+| `idempotency` | `boolean` | No | Enable `idempotencyKey` field on journal entries |
+| `strictness` | `StrictnessConfig` | No | Immutability, actor, and approval requirements |
+
+### Multi-Tenant Config
+
+When `multiTenant` is set, all schemas add an org reference field and compound indexes are scoped per-org. All repository methods and report generators enforce org isolation.
+
+```typescript
+multiTenant: {
+  orgField: 'business',  // field name on documents
+  orgRef: 'Business',    // Mongoose model name for ObjectId ref
+}
+```
+
+Omit `multiTenant` for single-tenant applications.
+
+### Audit Config
+
+```typescript
+audit: {
+  trackActor: true, // adds createdBy, postedBy, reversedByUser fields to journal entries
+}
+```
+
+When enabled, the journal entry schema gains actor-tracking fields. These are populated by `post()` and `reverse()` when `actorId` is passed in options.
+
+### Idempotency
+
+```typescript
+idempotency: true
+```
+
+Adds an `idempotencyKey` field (unique sparse index) to journal entries. When used with `idempotencyPlugin`, prevents duplicate postings on retry. See [Plugins](plugins.md#idempotency-plugin).
+
+### Strictness Config
+
+```typescript
+strictness: {
+  immutable: true,       // unpost() disabled — correction only via reverse()
+  requireActor: true,    // actorId required on post/reverse/unpost
+  requireApproval: true, // approvedBy + approvedAt required before posting
+}
+```
+
+All strictness options are opt-in and default to `false`. See [Repositories](repositories.md#strictness-configuration) for behavioral details.
+
+## Engine Methods
+
+### Schema Factories
+
+```typescript
+accounting.createAccountSchema(options?)       // → Mongoose Schema
+accounting.createJournalEntrySchema('Account', options?)  // → Mongoose Schema
+accounting.createFiscalPeriodSchema(options?)   // → Mongoose Schema
+```
+
+See [Schemas](schemas.md) for details.
+
+### Repository Factory (recommended)
+
+```typescript
+import { createRepository } from '@classytic/mongokit';
+
+const journalRepo = accounting.createJournalEntryRepository(
+  createRepository,
+  { JournalEntryModel: JournalEntry, AccountModel: Account, FiscalPeriodModel: FiscalPeriod },
+);
+// Includes: double-entry + fiscal lock + idempotency plugins, post(), reverse(), duplicate(), unpost()
+```
+
+### Manual Repository Wiring (advanced)
+
+```typescript
+accounting.wireJournalEntryRepository(repo, JournalEntryModel)
+// Adds: repo.post(id, orgId), repo.reverse(id, orgId), repo.duplicate(id, orgId), repo.unpost(id, orgId)
+
+accounting.wireAccountRepository(repo, AccountModel)
+// Adds: repo.seedAccounts(orgId), repo.bulkCreate(accounts, orgId)
+```
+
+See [Repositories](repositories.md) for details.
+
+### Report Engine
+
+```typescript
+const reports = accounting.createReports({ Account, JournalEntry });
+
+await reports.trialBalance({ organizationId, dateOption, dateValue, filters? });
+await reports.balanceSheet({ organizationId, dateOption, dateValue, filters? });
+await reports.incomeStatement({ organizationId, dateOption, dateValue, filters? });
+await reports.generalLedger({ organizationId, dateOption, dateValue, accountId?, filters? });
+await reports.cashFlow({ organizationId, dateOption, dateValue, filters? });
+```
+
+See [Reports](reports.md) for details.
+
+### Account Type Helpers
+
+```typescript
+accounting.getPostingAccountTypes()   // → AccountType[]
+accounting.isValidAccountType('1000') // → boolean
+accounting.getAccountType('1000')     // → AccountType | undefined
+accounting.getTaxCodesForRegion('ON') // → TaxCode[]
+```
+
+## Logger Interface
+
+The engine accepts a logger that implements:
+
+```typescript
+interface Logger {
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+}
+```
+
+Used for transaction fallback warnings (standalone MongoDB) and operational messages. Defaults to `console.warn/error/info` with `[accounting]` prefix.

package/docs/exports.md

@@ -0,0 +1,81 @@
+# Exports
+
+Pure data transformation pipeline for exporting journal entries to CSV. No database dependencies, no side effects.
+
+## Import
+
+```typescript
+import { exportToCsv, flattenJournalEntries, quickbooksFieldMap, universalFieldMap } from '@classytic/ledger/exports';
+```
+
+## Pipeline
+
+```
+PopulatedJournalEntry[] → flattenJournalEntries() → FlatJournalRow[] → exportToCsv() → CSV string
+```
+
+### Step 1: Flatten
+
+```typescript
+const rows = flattenJournalEntries(populatedEntries);
+```
+
+Converts nested journal entries (with embedded items) into flat rows — one row per journal item. Populated account references are resolved to `accountNumber` and `accountName`.
+
+### Step 2: Export to CSV
+
+```typescript
+const csv = exportToCsv(quickbooksFieldMap, rows);
+```
+
+Maps flat rows through a field map and serializes to CSV string.
+
+## Field Maps
+
+### QuickBooks (`quickbooksFieldMap`)
+
+Produces a CSV compatible with QuickBooks Desktop "General Journal" import.
+
+### Universal (`universalFieldMap`)
+
+Exports all available fields for maximum data preservation.
+
+### Custom Field Map
+
+```typescript
+import type { ExportFieldMap, FlatJournalRow } from '@classytic/ledger/exports';
+
+const myFieldMap: ExportFieldMap<FlatJournalRow> = {
+  Date: { header: 'Date', value: row => row.date?.toISOString().split('T')[0] ?? '' },
+  Account: { header: 'Account', value: row => row.accountNumber ?? '' },
+  Debit: { header: 'Debit', value: row => row.debit ? Money.formatPlain(row.debit) : '0' },
+  Credit: { header: 'Credit', value: row => row.credit ? Money.formatPlain(row.credit) : '0' },
+};
+
+const csv = exportToCsv(myFieldMap, rows);
+```
+
+## Types
+
+```typescript
+interface FlatJournalRow {
+  referenceNumber?: string;
+  journalType?: string;
+  date?: Date;
+  label?: string;
+  state?: string;
+  accountNumber?: string;
+  accountName?: string;
+  accountTypeCode?: string;
+  itemLabel?: string;
+  debit?: number;
+  credit?: number;
+  taxCode?: string;
+  taxName?: string;
+}
+```
+
+## Notes
+
+- DB stores debit/credit as integer cents (e.g. `10050` = $100.50). Built-in field maps convert cents to dollars at the CSV boundary via `Money.formatPlain()`.
+- CSV cells are escaped per RFC 4180 (quotes, commas, newlines).

package/docs/money.md

@@ -0,0 +1,81 @@
+# Money
+
+Integer-cents arithmetic helpers for safe financial computation. Avoids floating-point rounding errors by operating on integer minor-unit values.
+
+## Import
+
+```typescript
+import { Money } from '@classytic/ledger';
+// or
+import { fromDecimal, toDecimal, percentage } from '@classytic/ledger/money';
+```
+
+## DB Storage Contract
+
+All monetary fields (`debit`, `credit`, `totalDebit`, `totalCredit`, report balances/totals) are stored as **integer minor units (cents)**. For example, `10050` represents $100.50.
+
+Use `fromDecimal()` at the HTTP/API boundary to convert user-facing dollar inputs to cents. Use `toDecimal()` or `formatPlain()` to convert back for display or CSV export.
+
+```typescript
+// Input boundary (HTTP request):
+const cents = Money.fromDecimal(req.body.debit);  // 100.50 → 10050
+
+// Arithmetic (already in cents):
+const taxCents = Money.percentage(cents, 5);       // 5% of 10050 → 502
+
+// Output boundary (display/CSV):
+const display = Money.formatPlain(taxCents);       // 502 → "5.02"
+```
+
+## API
+
+### Conversion
+
+| Function | Signature | Description |
+|---|---|---|
+| `fromDecimal` | `(dollars, minorUnit?) → cents` | `10.50 → 1050` |
+| `toDecimal` | `(cents, minorUnit?) → dollars` | `1050 → 10.50` |
+| `parseCents` | `(input) → cents` | Parse string/number to cents |
+| `round` | `(amount) → integer` | Round to nearest integer |
+
+### Arithmetic (all operate on cents)
+
+| Function | Signature | Description |
+|---|---|---|
+| `add` | `(a, b) → cents` | Add two amounts |
+| `subtract` | `(a, b) → cents` | Subtract b from a |
+| `multiply` | `(cents, factor) → cents` | Multiply by factor, rounded |
+| `percentage` | `(cents, rate) → cents` | `percentage(10000, 5) → 500` |
+
+### Tax Helpers
+
+| Function | Signature | Description |
+|---|---|---|
+| `splitTaxInclusive` | `(inclusive, rate) → { base, tax }` | Extract tax from inclusive amount |
+| `splitTaxExclusive` | `(exclusive, rate) → { base, tax, total }` | Calculate tax on exclusive amount |
+
+### Allocation
+
+| Function | Signature | Description |
+|---|---|---|
+| `allocate` | `(cents, weights) → cents[]` | Split amount by weights, remainder to largest |
+
+### Formatting
+
+| Function | Signature | Description |
+|---|---|---|
+| `format` | `(cents, currency?) → string` | `1050 → "$10.50"` |
+| `formatPlain` | `(cents, minorUnit?) → string` | `1050 → "10.50"` |
+
+## Money Class
+
+All functions are also available as static methods on the `Money` class:
+
+```typescript
+Money.fromDecimal(10.50)   // 1050
+Money.toDecimal(1050)      // 10.50
+Money.percentage(1050, 5)  // 52
+Money.round(10.7)          // 11  ← rounds to nearest INTEGER (cents)
+```
+
+> **Warning:** `Money.round()` rounds to the nearest **integer** (cents-based). If you need dollar-level rounding to 2 decimal places, use your own helper.

package/docs/plugins.md

@@ -0,0 +1,136 @@
+# Plugins
+
+Plugins hook into mongokit's `before:create` and `before:update` events to enforce accounting rules.
+
+## Double-Entry Plugin
+
+Validates that every posted journal entry satisfies `sum(debits) === sum(credits)`.
+
+```typescript
+import { doubleEntryPlugin } from '@classytic/ledger';
+
+const plugin = doubleEntryPlugin({
+  JournalEntryModel: JournalEntry, // required for immutability guard + partial updates
+  AccountModel: Account,           // validates account existence on posted creates AND updates
+  orgField: 'business',            // validates tenant-account integrity
+});
+```
+
+### What it validates
+
+On `before:create` and `before:update` (when state is `posted`):
+
+1. Each line has debit OR credit > 0 (not both, not zero)
+2. At least 2 journal items
+3. `sum(debits) === sum(credits)` (exact integer match)
+4. Syncs `totalDebit` and `totalCredit` onto the data
+5. All journal item accounts exist (when `AccountModel` provided)
+6. All referenced accounts belong to the same org as the entry (when `orgField` set)
+
+### Account Validation
+
+Account validation runs on **both** `before:create` and `before:update` when `AccountModel` is provided. This closes the `repository.update(id, { state: 'posted' })` bypass — a draft with invalid accounts cannot be posted through the generic update path.
+
+On `before:create` for posted entries, `AccountModel` is **required** and the plugin throws if it's missing (fail-closed). On `before:update`, account validation runs when `AccountModel` is available but does not throw if it's absent (allows unit tests that only check balancing).
+
+### Posted-Entry Protection
+
+When `JournalEntryModel` is provided, the plugin protects posted entries from direct modification via updates:
+
+- Blocks any state transition away from `posted` (e.g. `{ state: 'draft' }`)
+- Blocks any field change on posted entries except idempotent `state: 'posted'`
+- `reversed`/`reversedBy` are NOT allowed through `repository.update()` — `reverse()` uses `entry.save()` directly
+- Partial updates that set `state: 'posted'` without `journalItems` fetch the persisted doc for validation
+
+### Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `JournalEntryModel` | Model | No | Required for immutability guard and partial update validation |
+| `AccountModel` | Model | Yes* | Validates account existence and tenant integrity. *Required on `before:create` (throws if missing). On `before:update`, runs when available. |
+| `orgField` | string | No | Multi-tenant org field name (enables tenant-account integrity check) |
+
+## Fiscal Lock Plugin
+
+Prevents journal entries from being created or posted in a closed fiscal period.
+
+```typescript
+import { fiscalLockPlugin } from '@classytic/ledger';
+
+const plugin = fiscalLockPlugin({
+  FiscalPeriodModel: FiscalPeriod,
+  JournalEntryModel: JournalEntry,  // needed for partial update date resolution
+  orgField: 'business',             // optional, for multi-tenant
+});
+```
+
+### What it validates
+
+On `before:create` and `before:update`:
+
+1. Gets the entry date from the payload, or falls back to the persisted document
+2. Checks if any closed fiscal period covers that date (org-scoped)
+3. Throws if the entry date falls in a closed period
+
+### Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `FiscalPeriodModel` | Model | Yes | Mongoose model for fiscal periods |
+| `JournalEntryModel` | Model | No | Needed to resolve date from persisted doc on partial updates |
+| `orgField` | string | No | Multi-tenant org field name |
+
+## Idempotency Plugin
+
+Prevents duplicate journal entries by checking for existing entries with the same `idempotencyKey`.
+
+```typescript
+import { idempotencyPlugin } from '@classytic/ledger';
+
+const plugin = idempotencyPlugin({
+  JournalEntryModel: JournalEntry,
+});
+```
+
+### Behavior
+
+On `before:create`: if the entry has an `idempotencyKey` and a document with the same key already exists, the plugin throws a 409 Conflict error.
+
+Enable the `idempotencyKey` schema field by setting `idempotency: true` in the engine config. The field has a unique sparse index — entries without a key are not affected.
+
+### When to use
+
+Idempotency keys are essential for subledger integrations where a retry (network failure, queue redelivery) could otherwise create duplicate postings. The subledger generates a deterministic key (e.g. `billing:invoice:INV-001`) and the ledger guarantees at-most-once posting.
+
+### Options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `JournalEntryModel` | Model | Yes | Mongoose model for journal entries |
+
+## Plugin Composition
+
+**Recommended:** Use `accounting.createJournalEntryRepository()` which handles all plugin wiring:
+
+```typescript
+const repo = accounting.createJournalEntryRepository(
+  createRepository,
+  { JournalEntryModel: JournalEntry, AccountModel: Account, FiscalPeriodModel: FiscalPeriod },
+);
+```
+
+For manual composition, plugins are passed as an array to `createRepository()`:
+
+```typescript
+const repo = createRepository(JournalEntry, [
+  doubleEntryPlugin({
+    JournalEntryModel: JournalEntry,
+    AccountModel: Account,
+    orgField: 'business',
+  }),
+  fiscalLockPlugin({ FiscalPeriodModel: FiscalPeriod, JournalEntryModel: JournalEntry, orgField: 'business' }),
+  idempotencyPlugin({ JournalEntryModel: JournalEntry }),
+]);
+```
+
+Plugins fire in registration order on the same hooks. Double-entry runs first (validates balance + accounts), then fiscal-lock (checks period), then idempotency (checks key uniqueness).