@happyvertical/smrt-ledgers 0.30.0

package/AGENTS.md

@@ -0,0 +1,36 @@
+# @happyvertical/smrt-ledgers
+
+Double-entry accounting with chart of accounts, journal lifecycle, and balance enforcement.
+
+## Models
+
+- **Account**: 5 types (asset/liability/equity/revenue/expense). Hierarchical via `parentId`. Debit-normal (asset, expense) vs credit-normal (liability, equity, revenue). Methods: `getAncestors()`, `getFullPath()`, `toTreeNode()`, `getBalance(asOfDate?)`.
+- **Journal**: lifecycle `draft → posted → voided`. **Immutable after posting** (can only void, not edit). `sourceModule`/`sourceRef` for cross-package attribution. Auto-numbered (e.g., "JNL-0001"). `summarize()` is AI-powered via the smrt-prompts registry (see Prompt Registry below).
+- **JournalEntry**: debit XOR credit (not both, validated on save). Multi-currency via `exchangeRate`. Non-negative amounts required.
+
+## Key Methods
+
+- **`Journal.summarize()`**: Generates a natural-language summary via the registered `smrtLedgers.journal.summarize` prompt, resolved through `@happyvertical/smrt-prompts`. Tenants can override the template, model, temperature, or other params via `_smrt_prompt_overrides` without code changes. Only non-PII fields (number, date, description, status, aggregate total, entry count, balanced flag) reach the AI provider.
+
+## Prompt Registry
+
+Registered at module-load time via `definePrompt()` in `src/prompts.ts`. Side-effect imported from `src/index.ts` so consumers automatically see the prompts after importing any export from this package.
+
+| Key | Method | Variables |
+|-----|--------|-----------|
+| `smrtLedgers.journal.summarize` | `Journal.summarize()` | `journalNumber`, `journalDate`, `journalDescription`, `journalStatus`, `journalTotal`, `entryCount`, `journalBalanced` |
+
+PII-conscious variable selection: `tenantId`, `sourceRef` (may reference customer/vendor identifiers), per-entry `accountId`/`id`, and the extensible `metadata` blob are intentionally NOT exposed as prompt variables. Tenants who need richer context should override the template via `PromptOverride` and supply their own variables through a custom call site.
+
+## Balance Enforcement
+
+`journal.post()` validates `Math.abs(totalDebits - totalCredits) < BALANCE_EPSILON` where `BALANCE_EPSILON = 0.01` (float rounding tolerance). Unbalanced journals cannot be posted.
+
+## Gotchas
+
+- **Float tolerance**: 0.01 epsilon for balance check — not exact equality
+- **Entry requires journalId**: save Journal first, then add entries
+- **Posted journals cannot be modified**: only voided (`voidReason`, `voidedAt`)
+- **Account types inherited by children**: child cannot differ from parent type
+- **getBalance() is async**: requires JournalEntryCollection query (not stored on Account)
+- **Optional tenancy** on all models

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @happyvertical/smrt-ledgers
+
+Double-entry accounting ledger for the SMRT framework. Hierarchical chart of accounts, journal lifecycle with immutability after posting, and balance enforcement with epsilon tolerance.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-ledgers
+```
+
+## Usage
+
+```typescript
+import {
+  Account, AccountCollection,
+  Journal, JournalCollection,
+  JournalEntry, JournalEntryCollection
+} from '@happyvertical/smrt-ledgers';
+
+// Set up chart of accounts
+const accounts = new AccountCollection(db);
+const cash = await accounts.create({
+  number: '1000',
+  name: 'Cash',
+  type: 'asset',
+});
+await cash.save();
+
+const revenue = await accounts.create({
+  number: '4000',
+  name: 'Sales Revenue',
+  type: 'revenue',
+});
+await revenue.save();
+
+// Create a sub-account under Cash
+const checking = await cash.createChild({
+  number: '1010',
+  name: 'Checking Account',
+});
+
+// Create a balanced journal with entries
+const journals = new JournalCollection(db);
+const journal = await journals.createWithEntries({
+  description: 'Cash sale',
+  sourceModule: 'manual',
+  entries: [
+    { accountId: cash.id, debit: 100.00 },
+    { accountId: revenue.id, credit: 100.00 },
+  ],
+});
+
+// Post the journal (validates balance, then immutable)
+await journal.post();
+
+// Query balances
+const cashBalance = await cash.getBalance();
+
+// Get trial balance across all active accounts
+const entries = new JournalEntryCollection(db);
+const trialBalance = await entries.getTrialBalance();
+
+// Void a journal (cannot edit after posting, only void)
+await journal.void('Duplicate entry');
+```
+
+## Double-Entry Accounting
+
+Every journal must balance before it can be posted. The balance check uses `BALANCE_EPSILON = 0.001` to handle floating-point rounding:
+
+```
+Math.abs(totalDebits - totalCredits) < 0.001
+```
+
+Account types follow standard accounting rules:
+- **Debit-normal** (Asset, Expense): balance = debits - credits
+- **Credit-normal** (Liability, Equity, Revenue): balance = credits - debits
+
+### Journal Lifecycle
+
+Journals follow a strict `draft -> posted -> voided` lifecycle:
+- **Draft**: editable, entries can be added via `journal.addEntry()`
+- **Posted**: immutable, balance validated, `postedAt` timestamp set
+- **Voided**: marked with `voidReason` and `voidedAt`, cannot be edited or re-posted
+
+Each JournalEntry must have either a debit or a credit (not both, not zero). Amounts must be non-negative. Multi-currency is supported via `exchangeRate` on each entry.
+
+## API
+
+### Models
+
+| Export | Description |
+|--------|------------|
+| `Account` | Chart of accounts entry with type, number, hierarchical parent, and balance queries |
+| `Journal` | Transaction journal with status lifecycle, auto-numbered (JNL-*), sourceModule/sourceRef for cross-package attribution |
+| `JournalEntry` | Individual debit or credit line within a journal, with currency and exchange rate |
+
+### Collections
+
+| Export | Key Methods |
+|--------|------------|
+| `AccountCollection` | `findChildren()`, `findActive()` |
+| `JournalCollection` | `createWithEntries()`, `findByNumber()`, `findByDateRange()`, `findBySource()`, `findByStatus()`, `findDrafts()`, `findPosted()` |
+| `JournalEntryCollection` | `findByJournal()`, `findByAccount()`, `getAccountBalance()`, `getTrialBalance()`, `getAccountLedger()`, `getTotalsForDateRange()` |
+
+### Types
+
+| Export | Description |
+|--------|------------|
+| `AccountType` | `'asset'`, `'liability'`, `'equity'`, `'revenue'`, `'expense'` |
+| `JournalStatus` | `'draft'`, `'posted'`, `'voided'` |
+| `AccountOptions` | Options for creating an Account |
+| `JournalOptions` | Options for creating a Journal |
+| `JournalEntryOptions` | Options for creating a JournalEntry |
+| `JournalEntryData` | Entry data for `addEntry()` / `createWithEntries()` |
+| `CreateJournalData` | Full journal + entries creation payload |
+| `TrialBalanceRow` | Row in trial balance report (accountId, number, name, type, debit/credit balances) |
+| `AccountTree` | Tree of account nodes (roots array) |
+| `AccountTreeNode` | Single node in account tree (account + children) |
+
+## Dependencies
+
+- `@happyvertical/smrt-core` -- ORM and code generation
+- `@happyvertical/smrt-tenancy` -- multi-tenant scoping