@happyvertical/smrt-ledgers 0.55.24 → 0.56.1

package/dist/manifest.json

@@ -2,7 +2,7 @@
   "version": "1.0.0",
   "timestamp": 0,
   "packageName": "@happyvertical/smrt-ledgers",
-  "packageVersion": "0.55.24",
+  "packageVersion": "0.56.1",
   "objects": {
     "@happyvertical/smrt-ledgers:AccountCollection": {
       "name": "accountcollection",
@@ -385,6 +385,20 @@
           "isStatic": false,
           "isPublic": true
         },
+        "listPostedMovements": {
+          "name": "listPostedMovements",
+          "async": true,
+          "parameters": [
+            {
+              "name": "options",
+              "type": "PostedJournalMovementOptions",
+              "optional": false
+            }
+          ],
+          "returnType": "Promise<PostedJournalMovement[]>",
+          "isStatic": false,
+          "isPublic": true
+        },
         "getAccountLedger": {
           "name": "getAccountLedger",
           "async": true,

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-ledgers",
-  "packageVersion": "0.55.24",
+  "packageVersion": "0.56.1",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "71a344f29b6d9392a438562fc02f4c0e0aa606e03f97797f5cccbbc438321767",
-    "packageJson": "b66e1053d7f6906990965962908208742738dba277b2a9814fbfb531b1758d36",
-    "agents": "ae2190496d153852ff73d18f871a829303927e1c65053b5325b02c0d9f470bfe"
+    "manifest": "356d94907bdd0df05ceee5597b4785fc30c5e49f666266e116d770c1e4635954",
+    "packageJson": "44d1f169b871e7ffe644bc0673af435c0e3ea839fb2a1661495886062f5b5d8c",
+    "agents": "a1bece3d7fcf3112b2b5193fdc51cf4438ba8446af146d1c8ac1c95c8ed2f0c8"
   },
   "exports": [
     ".",
@@ -421,7 +421,8 @@
         "getAccountBalance",
         "getAccountLedger",
         "getTotalsForDateRange",
-        "getTrialBalance"
+        "getTrialBalance",
+        "listPostedMovements"
       ],
       "methodSignatures": [
         {
@@ -502,6 +503,14 @@
             "asOfDate?: Date"
           ],
           "returns": "Promise<TrialBalanceRow[]>"
+        },
+        {
+          "name": "listPostedMovements",
+          "async": true,
+          "params": [
+            "options: PostedJournalMovementOptions"
+          ],
+          "returns": "Promise<PostedJournalMovement[]>"
         }
       ],
       "surfaces": [
@@ -553,6 +562,14 @@
           "path": "/journalentries/findByAccounts",
           "method": "POST"
         },
+        {
+          "kind": "api",
+          "name": "journalentries.listPostedMovements",
+          "operation": "listPostedMovements",
+          "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection",
+          "path": "/journalentries/listPostedMovements",
+          "method": "POST"
+        },
         {
           "kind": "api",
           "name": "journalentries.getAccountLedger",
@@ -621,6 +638,12 @@
           "operation": "findByAccounts",
           "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
         },
+        {
+          "kind": "cli",
+          "name": "journalentrycollection_listPostedMovements",
+          "operation": "listPostedMovements",
+          "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
+        },
         {
           "kind": "cli",
           "name": "journalentrycollection_getAccountLedger",
@@ -681,6 +704,12 @@
           "operation": "findByAccounts",
           "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
         },
+        {
+          "kind": "mcp",
+          "name": "journalentrycollection_listpostedmovements",
+          "operation": "listPostedMovements",
+          "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
+        },
         {
           "kind": "mcp",
           "name": "journalentrycollection_getaccountledger",
@@ -2586,6 +2615,14 @@
       "path": "/journalentries/findByAccounts",
       "method": "POST"
     },
+    {
+      "kind": "api",
+      "name": "journalentries.listPostedMovements",
+      "operation": "listPostedMovements",
+      "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection",
+      "path": "/journalentries/listPostedMovements",
+      "method": "POST"
+    },
     {
       "kind": "api",
       "name": "journalentries.getAccountLedger",
@@ -2654,6 +2691,12 @@
       "operation": "findByAccounts",
       "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
     },
+    {
+      "kind": "cli",
+      "name": "journalentrycollection_listPostedMovements",
+      "operation": "listPostedMovements",
+      "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
+    },
     {
       "kind": "cli",
       "name": "journalentrycollection_getAccountLedger",
@@ -2714,6 +2757,12 @@
       "operation": "findByAccounts",
       "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
     },
+    {
+      "kind": "mcp",
+      "name": "journalentrycollection_listpostedmovements",
+      "operation": "listPostedMovements",
+      "objectName": "@happyvertical/smrt-ledgers:JournalEntryCollection"
+    },
     {
       "kind": "mcp",
       "name": "journalentrycollection_getaccountledger",
@@ -3442,7 +3491,7 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 18
   },
-  "agentDoc": "# @happyvertical/smrt-ledgers\n\nDouble-entry accounting with chart of accounts, journal lifecycle, and balance enforcement.\n\n## Models\n\n- **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?)`. Stored in `ledger_accounts` (explicit `tableName`), never the derived `accounts`: smrt-messages declares an unrelated `Account` on that table (#3098). `src/migrations/ledger-accounts-table.ts` (`smrt db:migrate-ledger-accounts`) moves pre-#3098 rows; the README has the operator sequence.\n- **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).\n- **JournalEntry**: debit XOR credit (not both, validated on save). Multi-currency via `exchangeRate`. Non-negative amounts required.\n\n## Key Methods\n\n- **`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.\n\n## Prompt Registry\n\nRegistered 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.\n\n| Key | Method | Variables |\n|-----|--------|-----------|\n| `smrtLedgers.journal.summarize` | `Journal.summarize()` | `journalNumber`, `journalDate`, `journalDescription`, `journalStatus`, `journalTotal`, `entryCount`, `journalBalanced` |\n\nPII-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.\n\n## Balance Enforcement\n\n`journal.post()` validates `Math.abs(totalDebits - totalCredits) < BALANCE_EPSILON` where `BALANCE_EPSILON = 0.01` (float rounding tolerance). Unbalanced journals cannot be posted.\n\n**This package is unit-agnostic** — `debit` / `credit` are plain DECIMAL numbers and the balance check only compares the two sides, so it holds for whatever unit the posting module uses. As of #2401, journals posted from `@happyvertical/smrt-commerce` (`Payment.recordPayment()`, `Invoice.recognizeRevenue()`) carry **integer minor units**, which balance exactly rather than merely within the epsilon. A consumer mixing modules that post in different units will get arithmetically balanced but semantically meaningless journals; pick one unit per ledger.\n\n## Gotchas\n\n- **Float tolerance**: 0.01 epsilon for balance check — not exact equality\n- **Entry requires journalId**: save Journal first, then add entries\n- **Posted journals cannot be modified**: only voided (`voidReason`, `voidedAt`)\n- **Account types inherited by children**: child cannot differ from parent type\n- **getBalance() is async**: requires JournalEntryCollection query (not stored on Account)\n- **Optional tenancy** on all models\n- **Same-named `Account`**: reference the ledger model by constructor (`@foreignKey(Account)`) or qualified name (`@happyvertical/smrt-ledgers:Account`), never the bare string. The PostgreSQL lanes are `pnpm test:postgres` here (ledgers alone) and in smrt-messages (both packages loaded)\n",
+  "agentDoc": "# @happyvertical/smrt-ledgers\n\nDouble-entry accounting with chart of accounts, journal lifecycle, and balance enforcement.\n\n## Models\n\n- **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?)`. Stored in `ledger_accounts` (explicit `tableName`), never the derived `accounts`: smrt-messages declares an unrelated `Account` on that table (#3098). `src/migrations/ledger-accounts-table.ts` (`smrt db:migrate-ledger-accounts`) moves pre-#3098 rows; the README has the operator sequence.\n- **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).\n- **JournalEntry**: debit XOR credit (not both, validated on save). Multi-currency via `exchangeRate`. Non-negative amounts required.\n\n## Key Methods\n\n- **`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.\n\n## Prompt Registry\n\nRegistered 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.\n\n| Key | Method | Variables |\n|-----|--------|-----------|\n| `smrtLedgers.journal.summarize` | `Journal.summarize()` | `journalNumber`, `journalDate`, `journalDescription`, `journalStatus`, `journalTotal`, `entryCount`, `journalBalanced` |\n\nPII-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.\n\n## Balance Enforcement\n\n`journal.post()` validates `Math.abs(totalDebits - totalCredits) < BALANCE_EPSILON` where `BALANCE_EPSILON = 0.01` (float rounding tolerance). Unbalanced journals cannot be posted.\n\n**This package is unit-agnostic** — `debit` / `credit` are plain DECIMAL numbers and the balance check only compares the two sides, so it holds for whatever unit the posting module uses. As of #2401, journals posted from `@happyvertical/smrt-commerce` (`Payment.recordPayment()`, `Invoice.recognizeRevenue()`) carry **integer minor units**, which balance exactly rather than merely within the epsilon. A consumer mixing modules that post in different units will get arithmetically balanced but semantically meaningless journals; pick one unit per ledger.\n\n`JournalEntryCollection.listPostedMovements({ tenantId, accountIds, from, to,\ncurrency })` is the bounded reporting input. It joins only rows whose entry and\njournal share the requested tenant, includes every posted source (including\nmanual journals), and excludes drafts and voids. Its debit, credit, and\n`creditMinusDebit` values are raw ledger units; commerce must verify its\nminor-unit convention before using them in an exact tax report. Each returned\nmovement retains the requested `tenantId` so consumers can reject a fact that\ncrosses the reporting boundary.\n\n## Gotchas\n\n- **Float tolerance**: 0.01 epsilon for balance check — not exact equality\n- **Entry requires journalId**: save Journal first, then add entries\n- **Posted journals cannot be modified**: only voided (`voidReason`, `voidedAt`)\n- **Account types inherited by children**: child cannot differ from parent type\n- **getBalance() is async**: requires JournalEntryCollection query (not stored on Account)\n- **Optional tenancy** on all models\n- **Same-named `Account`**: reference the ledger model by constructor (`@foreignKey(Account)`) or qualified name (`@happyvertical/smrt-ledgers:Account`), never the bare string. The PostgreSQL lanes are `pnpm test:postgres` here (ledgers alone) and in smrt-messages (both packages loaded)\n",
   "recipes": [
     {
       "id": "ledgers.bookkeeping",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-ledgers",
-  "version": "0.55.24",
+  "version": "0.56.1",
   "description": "Double-entry accounting ledger for the SMRT framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,12 +38,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "0.55.24",
-    "@happyvertical/smrt-prompts": "0.55.24",
-    "@happyvertical/smrt-tenancy": "0.55.24"
+    "@happyvertical/smrt-core": "0.56.1",
+    "@happyvertical/smrt-prompts": "0.56.1",
+    "@happyvertical/smrt-tenancy": "0.56.1"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.55.24",
+    "@happyvertical/smrt-vitest": "0.56.1",
     "@types/node": "24.13.6",
     "fast-glob": "^3.3.3",
     "typescript": "6.0.3",