@happyvertical/smrt-ledgers 0.51.24 → 0.51.25

package/AGENTS.md

@@ -4,7 +4,7 @@ Double-entry accounting with chart of accounts, journal lifecycle, and balance e
 
 ## 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?)`.
+- **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.
 - **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.
 
@@ -36,3 +36,4 @@ PII-conscious variable selection: `tenantId`, `sourceRef` (may reference custome
 - **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
+- **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)

package/README.md

@@ -103,6 +103,14 @@ Each JournalEntry must have either a debit or a credit (not both, not zero). Amo
 | `JournalCollection` | `createWithEntries()`, `findByNumber()`, `findByDateRange()`, `findBySource()`, `findByStatus()`, `findDrafts()`, `findPosted()` |
 | `JournalEntryCollection` | `findByJournal()`, `findByAccount()`, `getAccountBalance()`, `getTrialBalance()`, `getAccountLedger()`, `getTotalsForDateRange()` |
 
+### Migration
+
+| Export | Description |
+|--------|------------|
+| `planLedgerAccountsTableMove(db)` | Count the ledger rows a pre-#3098 `accounts` table still holds, without writing |
+| `migrateLedgerAccountsTable(db, options?)` | Move them into `ledger_accounts` (see [Upgrading](#upgrading-from-051x-the-ledger_accounts-table-3098)) |
+| `LedgerAccountsTableMoveError` | Thrown when the move refuses (uncertain rows, id clash, missing table, non-PostgreSQL) |
+
 ### Types
 
 | Export | Description |
@@ -118,6 +126,44 @@ Each JournalEntry must have either a debit or a credit (not both, not zero). Amo
 | `AccountTree` | Tree of account nodes (roots array) |
 | `AccountTreeNode` | Single node in account tree (account + children) |
 
+## Upgrading from 0.51.x: the `ledger_accounts` table (#3098)
+
+`Account` is stored in `ledger_accounts`. Earlier releases derived the table
+name `accounts`, which `@happyvertical/smrt-messages` also uses for its
+unrelated messaging `Account`; an app with both packages got one union table
+whose rows each package read as its own. An existing database moves its ledger
+accounts once, in a PostgreSQL maintenance window:
+
+1. `smrt db:migrate` — creates `ledger_accounts`. It reports, and does not
+   apply, the `journal_entries.account_id` foreign key while the old one still
+   points at `accounts`.
+2. `smrt db:migrate-ledger-accounts --dry-run`, then without `--dry-run` —
+   copies every ledger row (ids, hierarchy and metadata unchanged) into
+   `ledger_accounts`, detaches the ledger foreign keys from `accounts`, and
+   deletes the moved rows, in one locked transaction. Messaging rows (those
+   with an STI discriminator) stay. Before writing anything it refuses a row
+   whose owner is uncertain, ids already present in `ledger_accounts`, and any
+   foreign key into `accounts` that no registered model declares (it would
+   otherwise dangle, or cascade); a rerun is a no-op. The same step is
+   `migrateLedgerAccountsTable(db)` / `planLedgerAccountsTableMove(db)` from
+   this package — call it with the application's models registered, as the
+   CLI does.
+3. `smrt db:migrate` — adds the foreign keys against `ledger_accounts`.
+
+Afterwards `accounts` is either empty (ledgers only — drop it when nothing else
+uses it) or holds only messaging accounts plus the unused ledger columns
+`number`, `type`, `parent_id`, `description`, `active` and `metadata`, which
+can be dropped once verified. A database that never ran ledgers needs nothing.
+
+The move supports PostgreSQL. On SQLite, a database whose `accounts` table
+holds only ledger accounts is upgraded with
+`ALTER TABLE accounts RENAME TO ledger_accounts` before step 1; a SQLite
+database that also holds messaging accounts must be rebuilt.
+
+Code that referenced the ledger model by the bare name `'Account'` should use
+the constructor or the qualified name `@happyvertical/smrt-ledgers:Account`;
+the exported `Account` and `AccountCollection` are unchanged.
+
 ## Dependencies
 
 - `@happyvertical/smrt-core` -- ORM and code generation

package/dist/chunks/Account-Dr4tA_Gn.js

@@ -0,0 +1,128 @@
+import { SmrtHierarchical, smrt } from "@happyvertical/smrt-core";
+import { TenantScoped, tenantId } from "@happyvertical/smrt-tenancy";
+//#region src/models/Account.ts
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+	var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+	for (var i = decorators.length - 1, decorator; i >= 0; i--) if (decorator = decorators[i]) result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+	if (kind && result) __defProp(target, key, result);
+	return result;
+};
+var Account = class extends SmrtHierarchical {
+	tenantId = null;
+	/**
+	* Account number (e.g., "1000", "5030")
+	*/
+	number = "";
+	/**
+	* Account name (e.g., "Cash", "Coffee Expense")
+	*/
+	name = "";
+	/**
+	* Account description
+	*/
+	description = "";
+	/**
+	* Account type - one of the 5 core types
+	*/
+	type = "asset";
+	/**
+	* Whether the account is active
+	*/
+	active = true;
+	/**
+	* Extensible metadata
+	*/
+	metadata = {};
+	constructor(options = {}) {
+		super(options);
+		if (options.number !== void 0) this.number = options.number;
+		if (options.name !== void 0) this.name = options.name;
+		if (options.description !== void 0) this.description = options.description;
+		if (options.type !== void 0) this.type = options.type;
+		if (options.parentId !== void 0) this.parentId = options.parentId;
+		if (options.active !== void 0) this.active = options.active;
+		if (options.metadata !== void 0) this.metadata = options.metadata;
+	}
+	/**
+	* Check if this is a top-level account (no parent)
+	*/
+	isTopLevel() {
+		return this.parentId === null;
+	}
+	/**
+	* Check if this is a debit-normal account (Asset, Expense)
+	* Debit-normal accounts increase with debits
+	*/
+	isDebitNormal() {
+		return this.type === "asset" || this.type === "expense";
+	}
+	/**
+	* Check if this is a credit-normal account (Liability, Equity, Revenue)
+	* Credit-normal accounts increase with credits
+	*/
+	isCreditNormal() {
+		return this.type === "liability" || this.type === "equity" || this.type === "revenue";
+	}
+	/**
+	* Get full account path (e.g., "Assets > Current > Cash")
+	*/
+	async getFullPath() {
+		return [...(await this.getAncestors()).map((a) => a.name), this.name].join(" > ");
+	}
+	/**
+	* Build tree node for this account and its children
+	*/
+	async toTreeNode() {
+		const children = await this.getChildren();
+		const childNodes = await Promise.all(children.map((c) => c.toTreeNode()));
+		return {
+			account: this,
+			children: childNodes
+		};
+	}
+	/**
+	* Get the current balance of this account
+	*/
+	async getBalance(asOfDate) {
+		if (!this.id) return 0;
+		const { JournalEntryCollection } = await import("../index.js").then((n) => n.t);
+		return await (await JournalEntryCollection.create(this.options)).getAccountBalance(this.id, asOfDate);
+	}
+	/**
+	* Create a sub-account under this account
+	*/
+	async createChild(options) {
+		if (!this.id) throw new Error("Account must be saved before creating children");
+		const { AccountCollection } = await import("../index.js").then((n) => n.n);
+		const account = await (await AccountCollection.create(this.options)).create({
+			...options,
+			parentId: this.id,
+			type: this.type
+		});
+		await account.save();
+		return account;
+	}
+};
+__decorateClass([tenantId({ nullable: true })], Account.prototype, "tenantId", 2);
+Account = __decorateClass([TenantScoped({ mode: "optional" }), smrt({
+	tableName: "ledger_accounts",
+	api: { include: [
+		"list",
+		"get",
+		"create",
+		"update",
+		"delete"
+	] },
+	mcp: { include: [
+		"list",
+		"get",
+		"create"
+	] },
+	cli: { skipApiCheck: true }
+})], Account);
+//#endregion
+export { Account as t };
+
+//# sourceMappingURL=Account-Dr4tA_Gn.js.map

package/dist/chunks/Account-Dr4tA_Gn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Account-Dr4tA_Gn.js","names":[],"sources":["../../src/models/Account.ts"],"sourcesContent":["/**\n * Account model - Chart of accounts entry\n *\n * Represents a single account in the chart of accounts.\n * The 5 core types: Asset, Liability, Equity, Revenue, Expense\n */\n\nimport { SmrtHierarchical, smrt } from '@happyvertical/smrt-core';\nimport { TenantScoped, tenantId } from '@happyvertical/smrt-tenancy';\nimport type { AccountOptions, AccountTreeNode, AccountType } from '../types';\n\n@TenantScoped({ mode: 'optional' })\n@smrt({\n  // Own table, never the derived `accounts`: smrt-messages declares an\n  // unrelated `Account` on that table (#3098). Existing `accounts`-hosted\n  // ledgers move with `smrt db:migrate-ledger-accounts`.\n  tableName: 'ledger_accounts',\n  api: { include: ['list', 'get', 'create', 'update', 'delete'] },\n  mcp: { include: ['list', 'get', 'create'] },\n  cli: { skipApiCheck: true },\n})\nexport class Account extends SmrtHierarchical {\n  /**\n   * Tenant ID for multi-tenancy support (nullable for global accounts)\n   */\n  @tenantId({ nullable: true })\n  tenantId: string | null = null;\n\n  /**\n   * Account number (e.g., \"1000\", \"5030\")\n   */\n  number: string = '';\n\n  /**\n   * Account name (e.g., \"Cash\", \"Coffee Expense\")\n   */\n  name: string = '';\n\n  /**\n   * Account description\n   */\n  description: string = '';\n\n  /**\n   * Account type - one of the 5 core types\n   */\n  type: AccountType = 'asset';\n\n  // parentId inherited from SmrtHierarchical (null = top-level)\n\n  /**\n   * Whether the account is active\n   */\n  active: boolean = true;\n\n  /**\n   * Extensible metadata\n   */\n  metadata: Record<string, unknown> = {};\n\n  constructor(options: AccountOptions = {}) {\n    super(options);\n    if (options.number !== undefined) this.number = options.number;\n    if (options.name !== undefined) this.name = options.name;\n    if (options.description !== undefined)\n      this.description = options.description;\n    if (options.type !== undefined) this.type = options.type;\n    if (options.parentId !== undefined) this.parentId = options.parentId;\n    if (options.active !== undefined) this.active = options.active;\n    if (options.metadata !== undefined) this.metadata = options.metadata;\n  }\n\n  /**\n   * Check if this is a top-level account (no parent)\n   */\n  isTopLevel(): boolean {\n    return this.parentId === null;\n  }\n\n  /**\n   * Check if this is a debit-normal account (Asset, Expense)\n   * Debit-normal accounts increase with debits\n   */\n  isDebitNormal(): boolean {\n    return this.type === 'asset' || this.type === 'expense';\n  }\n\n  /**\n   * Check if this is a credit-normal account (Liability, Equity, Revenue)\n   * Credit-normal accounts increase with credits\n   */\n  isCreditNormal(): boolean {\n    return (\n      this.type === 'liability' ||\n      this.type === 'equity' ||\n      this.type === 'revenue'\n    );\n  }\n\n  // Hierarchy traversal (getParent / getChildren / getAncestors /\n  // getDescendants / getHierarchy / moveTo) provided by SmrtHierarchical.\n  // Account-specific helpers (getFullPath / getBalance / createChild /\n  // toTreeNode) remain below.\n\n  /**\n   * Get full account path (e.g., \"Assets > Current > Cash\")\n   */\n  async getFullPath(): Promise<string> {\n    const ancestors = await this.getAncestors();\n    const names = [...ancestors.map((a) => a.name), this.name];\n    return names.join(' > ');\n  }\n\n  /**\n   * Build tree node for this account and its children\n   */\n  async toTreeNode(): Promise<AccountTreeNode> {\n    const children = await this.getChildren();\n    const childNodes = await Promise.all(children.map((c) => c.toTreeNode()));\n    return {\n      account: this,\n      children: childNodes,\n    };\n  }\n\n  /**\n   * Get the current balance of this account\n   */\n  async getBalance(asOfDate?: Date): Promise<number> {\n    if (!this.id) return 0;\n    const { JournalEntryCollection } = await import(\n      '../collections/JournalEntries'\n    );\n    const collection = await JournalEntryCollection.create(this.options);\n    return await collection.getAccountBalance(this.id, asOfDate);\n  }\n\n  /**\n   * Create a sub-account under this account\n   */\n  async createChild(\n    options: Omit<AccountOptions, 'parentId' | 'type'>,\n  ): Promise<Account> {\n    if (!this.id) {\n      throw new Error('Account must be saved before creating children');\n    }\n    const { AccountCollection } = await import('../collections/Accounts');\n    const collection = await AccountCollection.create(this.options);\n    const account = await collection.create({\n      ...options,\n      parentId: this.id,\n      type: this.type, // Inherit type from parent\n    });\n    await account.save();\n    return account;\n  }\n}\n"],"mappings":";;;;;;;;;;;AAqBO,IAAM,UAAN,cAAsB,iBAAiB;CAK5C,WAA0B;;;;CAK1B,SAAiB;;;;CAKjB,OAAe;;;;CAKf,cAAsB;;;;CAKtB,OAAoB;;;;CAOpB,SAAkB;;;;CAKlB,WAAoC,CAAC;CAErC,YAAY,UAA0B,CAAC,GAAG;EACxC,MAAM,OAAO;EACb,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;EACxD,IAAI,QAAQ,SAAS,KAAA,GAAW,KAAK,OAAO,QAAQ;EACpD,IAAI,QAAQ,gBAAgB,KAAA,GAC1B,KAAK,cAAc,QAAQ;EAC7B,IAAI,QAAQ,SAAS,KAAA,GAAW,KAAK,OAAO,QAAQ;EACpD,IAAI,QAAQ,aAAa,KAAA,GAAW,KAAK,WAAW,QAAQ;EAC5D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;EACxD,IAAI,QAAQ,aAAa,KAAA,GAAW,KAAK,WAAW,QAAQ;CAC9D;;;;CAKA,aAAsB;EACpB,OAAO,KAAK,aAAa;CAC3B;;;;;CAMA,gBAAyB;EACvB,OAAO,KAAK,SAAS,WAAW,KAAK,SAAS;CAChD;;;;;CAMA,iBAA0B;EACxB,OACE,KAAK,SAAS,eACd,KAAK,SAAS,YACd,KAAK,SAAS;CAElB;;;;CAUA,MAAM,cAA+B;EAGnC,OAAO,CADQ,IAAG,MADM,KAAK,aAAa,EAAA,CACd,KAAK,MAAM,EAAE,IAAI,GAAG,KAAK,IAC9C,CAAA,CAAM,KAAK,KAAK;CACzB;;;;CAKA,MAAM,aAAuC;EAC3C,MAAM,WAAW,MAAM,KAAK,YAAY;EACxC,MAAM,aAAa,MAAM,QAAQ,IAAI,SAAS,KAAK,MAAM,EAAE,WAAW,CAAC,CAAC;EACxE,OAAO;GACL,SAAS;GACT,UAAU;EACZ;CACF;;;;CAKA,MAAM,WAAW,UAAkC;EACjD,IAAI,CAAC,KAAK,IAAI,OAAO;EACrB,MAAM,EAAE,2BAA2B,MAAM,OACvC,cAAA,CAAA,MAAA,MAAA,EAAA,CAAA;EAGF,OAAO,OAAM,MADY,uBAAuB,OAAO,KAAK,OAAO,EAAA,CAC3C,kBAAkB,KAAK,IAAI,QAAQ;CAC7D;;;;CAKA,MAAM,YACJ,SACkB;EAClB,IAAI,CAAC,KAAK,IACR,MAAM,IAAI,MAAM,gDAAgD;EAElE,MAAM,EAAE,sBAAsB,MAAM,OAAO,cAAA,CAAA,MAAA,MAAA,EAAA,CAAA;EAE3C,MAAM,UAAU,OAAM,MADG,kBAAkB,OAAO,KAAK,OAAO,EAAA,CAC7B,OAAO;GACtC,GAAG;GACH,UAAU,KAAK;GACf,MAAM,KAAK;EACb,CAAC;EACD,MAAM,QAAQ,KAAK;EACnB,OAAO;CACT;AACF;AAlIE,gBAAA,CADC,SAAS,EAAE,UAAU,KAAK,CAAC,CAAA,GAJjB,QAKX,WAAA,YAAA,CAAA;AALW,UAAN,gBAAA,CAVN,aAAa,EAAE,MAAM,WAAW,CAAC,GACjC,KAAK;CAIJ,WAAW;CACX,KAAK,EAAE,SAAS;EAAC;EAAQ;EAAO;EAAU;EAAU;CAAQ,EAAE;CAC9D,KAAK,EAAE,SAAS;EAAC;EAAQ;EAAO;CAAQ,EAAE;CAC1C,KAAK,EAAE,cAAc,KAAK;AAC5B,CAAC,CAAA,GACY,OAAA"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { DatabaseInterface } from '@happyvertical/smrt-core/migrations';
 import { PromptDefinition } from '@happyvertical/smrt-prompts';
 import { ResolvedPromptAI } from '@happyvertical/smrt-prompts';
 import { SmrtClassOptions } from '@happyvertical/smrt-core';
@@ -643,6 +644,56 @@ export declare interface JournalOptions extends SmrtClassOptions {
  */
 export declare type JournalStatus = 'draft' | 'posted' | 'voided';
 
+export declare const LEDGER_ACCOUNTS_TABLE = "ledger_accounts";
+
+export declare const LEDGER_ACCOUNTS_TABLE_MOVE = "@happyvertical/smrt-ledgers:ledger-accounts-table:v1";
+
+export declare class LedgerAccountsTableMoveError extends Error {
+    constructor(message: string);
+}
+
+export declare interface LedgerAccountsTableMoveOptions {
+    backfillName?: string;
+    packageName?: string;
+    /** PostgreSQL `lock_timeout`, milliseconds (default 30000). */
+    lockTimeout?: number;
+    /** PostgreSQL `statement_timeout`, milliseconds (default 60000). */
+    statementTimeout?: number;
+}
+
+export declare interface LedgerAccountsTableMovePlan {
+    /** Whether a legacy `accounts` table with ledger columns exists. */
+    legacyTable: boolean;
+    /** Ledger rows still in `accounts` that this migration would move. */
+    pending: number;
+    /** Messaging rows that stay in `accounts`. */
+    messagingRows: number;
+}
+
+export declare interface LedgerAccountsTableMoveResult {
+    ran: boolean;
+    moved: number;
+    /** Rows (messaging accounts) left in `accounts`. */
+    remainingLegacyRows: number;
+    /** `table.column` foreign keys detached from `accounts`. */
+    detachedForeignKeys: string[];
+}
+
+export declare const LEGACY_ACCOUNTS_TABLE = "accounts";
+
+/**
+ * Move ledger accounts from `accounts` into `ledger_accounts` in one
+ * transaction under an exclusive lock. Operator-invoked and idempotent: a
+ * rerun, or a database that never had ledger rows in `accounts`, is a no-op.
+ */
+export declare function migrateLedgerAccountsTable(db: DatabaseInterface, options?: LedgerAccountsTableMoveOptions): Promise<LedgerAccountsTableMoveResult>;
+
+/**
+ * Inspect the legacy table without changing anything. Read-only portable SQL,
+ * so it also reports what a SQLite database would need moved.
+ */
+export declare function planLedgerAccountsTableMove(db: DatabaseInterface): Promise<LedgerAccountsTableMovePlan>;
+
 export declare function promptMessageOptions(ai: ResolvedPromptAI): {
     maxTokens?: number | undefined;
     temperature?: number | undefined;