@happyvertical/smrt-ledgers 0.51.32 → 0.51.33

package/dist/index.d.ts

@@ -1,717 +1,73 @@
-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';
-import { SmrtCollection } from '@happyvertical/smrt-core';
-import { SmrtHierarchical } from '@happyvertical/smrt-core';
-import { SmrtObject } from '@happyvertical/smrt-core';
-
-export declare class Account extends SmrtHierarchical {
-    /**
-     * Tenant ID for multi-tenancy support (nullable for global accounts)
-     */
-    tenantId: string | null;
-    /**
-     * Account number (e.g., "1000", "5030")
-     */
-    number: string;
-    /**
-     * Account name (e.g., "Cash", "Coffee Expense")
-     */
-    name: string;
-    /**
-     * Account description
-     */
-    description: string;
-    /**
-     * Account type - one of the 5 core types
-     */
-    type: AccountType;
-    /**
-     * Whether the account is active
-     */
-    active: boolean;
-    /**
-     * Extensible metadata
-     */
-    metadata: Record<string, unknown>;
-    constructor(options?: AccountOptions);
-    /**
-     * Check if this is a top-level account (no parent)
-     */
-    isTopLevel(): boolean;
-    /**
-     * Check if this is a debit-normal account (Asset, Expense)
-     * Debit-normal accounts increase with debits
-     */
-    isDebitNormal(): boolean;
-    /**
-     * Check if this is a credit-normal account (Liability, Equity, Revenue)
-     * Credit-normal accounts increase with credits
-     */
-    isCreditNormal(): boolean;
-    /**
-     * Get full account path (e.g., "Assets > Current > Cash")
-     */
-    getFullPath(): Promise<string>;
-    /**
-     * Build tree node for this account and its children
-     */
-    toTreeNode(): Promise<AccountTreeNode>;
-    /**
-     * Get the current balance of this account
-     */
-    getBalance(asOfDate?: Date): Promise<number>;
-    /**
-     * Create a sub-account under this account
-     */
-    createChild(options: Omit<AccountOptions, 'parentId' | 'type'>): Promise<Account>;
-}
-
-export declare class AccountCollection extends SmrtCollection<Account> {
-    static readonly _itemClass: typeof Account;
-    /**
-     * Find account by number
-     *
-     * @param number - Account number
-     * @returns Account or null
-     */
-    findByNumber(number: string): Promise<Account | null>;
-    /**
-     * Find accounts by type
-     *
-     * @param type - Account type
-     * @returns Array of accounts
-     */
-    findByType(type: AccountType): Promise<Account[]>;
-    /**
-     * Find all active accounts
-     *
-     * @returns Array of active accounts
-     */
-    findActive(): Promise<Account[]>;
-    /**
-     * Find top-level accounts (no parent)
-     *
-     * @returns Array of top-level accounts
-     */
-    findTopLevel(): Promise<Account[]>;
-    /**
-     * Find direct children of an account
-     *
-     * @param parentId - Parent account ID
-     * @returns Array of child accounts
-     */
-    findChildren(parentId: string): Promise<Account[]>;
-    /**
-     * Get the complete account tree
-     *
-     * @returns AccountTree structure
-     */
-    getTree(): Promise<AccountTree>;
-    /**
-     * Get or create an account by number
-     *
-     * @param number - Account number
-     * @param defaults - Default values if creating
-     * @returns Account
-     */
-    getOrCreateByNumber(number: string, defaults?: Partial<{
-        name: string;
-        description: string;
-        type: AccountType;
-        parentId: string | null;
-    }>): Promise<Account>;
-    /**
-     * Find accounts grouped by type
-     *
-     * @returns Record of type to accounts array
-     */
-    groupByType(): Promise<Record<AccountType, Account[]>>;
-    /**
-     * Get all descendants of an account recursively
-     *
-     * @param accountId - Account ID
-     * @returns Array of all descendant accounts
-     */
-    getDescendants(accountId: string): Promise<Account[]>;
-    /**
-     * Find all accounts belonging to a specific tenant
-     *
-     * @param tenantId - Tenant ID
-     * @returns Array of tenant's accounts
-     */
-    findByTenant(tenantId: string): Promise<Account[]>;
-    /**
-     * Find all global accounts (no tenant association).
-     *
-     * Routes through the shared tenant-global helper so it does not throw under
-     * an active tenant context (an explicit `tenant_id IS NULL` filter would be
-     * flagged as an isolation violation). (#1600)
-     *
-     * @returns Array of global accounts
-     */
-    findGlobal(): Promise<Account[]>;
-    /**
-     * Find accounts for a tenant plus all global accounts.
-     *
-     * Fails closed if an active tenant context requests a different tenant's
-     * rows; the admin/system path keeps the cross-tenant capability. (#1600)
-     *
-     * @param tenantId - Tenant ID
-     * @returns Array of tenant's accounts and global accounts
-     */
-    findWithGlobals(tenantId: string): Promise<Account[]>;
-}
-
-/**
- * Options for creating an Account
- */
-export declare interface AccountOptions extends SmrtClassOptions {
-    tenantId?: string | null;
-    number?: string;
-    name?: string;
-    description?: string;
-    type?: AccountType;
-    parentId?: string | null;
-    active?: boolean;
-    metadata?: Record<string, unknown>;
-}
-
-/**
- * Account tree structure
- */
-export declare interface AccountTree {
-    roots: AccountTreeNode[];
-}
-
-/**
- * Account tree node for hierarchical display
- */
-export declare interface AccountTreeNode {
-    account: Account;
-    children: AccountTreeNode[];
-}
-
-/**
- * The five core account types in double-entry accounting
- */
-export declare type AccountType = 'asset' | 'liability' | 'equity' | 'revenue' | 'expense';
-
-/**
- * Data for creating a complete journal with entries
- */
-export declare interface CreateJournalData {
-    date?: Date;
-    description: string;
-    sourceModule?: string;
-    sourceRef?: string | null;
-    entries: JournalEntryData[];
-    metadata?: Record<string, unknown>;
-}
-
-export declare class Journal extends SmrtObject {
-    /**
-     * Tenant ID for multi-tenancy support (nullable for global journals)
-     */
-    tenantId: string | null;
-    /**
-     * Journal number (auto-generated sequence, e.g., "JNL-0001")
-     */
-    number: string;
-    /**
-     * Transaction date
-     */
-    date: Date;
-    /**
-     * Description of the financial event
-     */
-    description: string;
-    /**
-     * Source module that created this journal (e.g., "smrt-commerce", "manual")
-     */
-    sourceModule: string;
-    /**
-     * External reference (e.g., order ID, invoice number)
-     */
-    sourceRef: string | null;
-    /**
-     * Journal status: draft, posted, voided
-     */
-    status: JournalStatus;
-    /**
-     * When the journal was posted (finalized)
-     */
-    postedAt: Date | null;
-    /**
-     * When the journal was voided
-     */
-    voidedAt: Date | null;
-    /**
-     * Reason for voiding (if voided)
-     */
-    voidReason: string | null;
-    /**
-     * Extensible metadata
-     */
-    metadata: Record<string, unknown>;
-    constructor(options?: JournalOptions);
-    /**
-     * Check if journal is in draft status
-     */
-    isDraft(): boolean;
-    /**
-     * Check if journal has been posted
-     */
-    isPosted(): boolean;
-    /**
-     * Check if journal has been voided
-     */
-    isVoided(): boolean;
-    /**
-     * Check if journal can be modified
-     */
-    isEditable(): boolean;
-    /**
-     * Get all entries for this journal
-     */
-    getEntries(): Promise< JournalEntry[]>;
-    /**
-     * Calculate total debits
-     */
-    getTotalDebits(): Promise<number>;
-    /**
-     * Calculate total credits
-     */
-    getTotalCredits(): Promise<number>;
-    /**
-     * Check if journal entries are balanced (debits = credits)
-     */
-    isBalanced(): Promise<boolean>;
-    /**
-     * Add an entry to this journal (only if draft)
-     */
-    addEntry(data: JournalEntryData): Promise<void>;
-    /**
-     * Post the journal (finalize and make immutable)
-     */
-    post(): Promise<void>;
-    /**
-     * Void the journal (mark as cancelled with reason)
-     */
-    void(reason: string): Promise<void>;
-    /**
-     * AI-powered: Generate a summary of this journal.
-     *
-     * Uses the `smrtLedgers.journal.summarize` prompt registered via
-     * `@happyvertical/smrt-prompts`, allowing tenant- or instance-level
-     * overrides of the template, model, and parameters at runtime.
-     *
-     * Only non-PII journal fields (number, date, description, status, balanced
-     * flag) plus aggregate totals and entry count are sent to the AI provider.
-     * Internal foreign-key fields (tenantId, sourceRef, individual entry
-     * account IDs) and the extensible `metadata` blob are intentionally
-     * excluded.
-     *
-     * @returns Generated summary text
-     */
-    summarize(): Promise<string>;
-}
-
-export declare class JournalCollection extends SmrtCollection<Journal> {
-    static readonly _itemClass: typeof Journal;
-    /**
-     * Generate next journal number
-     *
-     * Uses timestamp and random component to avoid collisions
-     * in concurrent environments without relying on shared state.
-     */
-    private generateJournalNumber;
-    /**
-     * Find journal by number
-     *
-     * @param number - Journal number
-     * @returns Journal or null
-     */
-    findByNumber(number: string): Promise<Journal | null>;
-    /**
-     * Find journals by date range
-     *
-     * @param start - Start date
-     * @param end - End date
-     * @returns Array of journals
-     */
-    findByDateRange(start: Date, end: Date): Promise<Journal[]>;
-    /**
-     * Find journals by source module
-     *
-     * @param sourceModule - Source module name
-     * @returns Array of journals
-     */
-    findBySource(sourceModule: string): Promise<Journal[]>;
-    /**
-     * Find journals by status
-     *
-     * @param status - Journal status
-     * @returns Array of journals
-     */
-    findByStatus(status: JournalStatus): Promise<Journal[]>;
-    /**
-     * Find draft journals
-     *
-     * @returns Array of draft journals
-     */
-    findDrafts(): Promise<Journal[]>;
-    /**
-     * Find posted journals
-     *
-     * @returns Array of posted journals
-     */
-    findPosted(): Promise<Journal[]>;
-    /**
-     * Create a complete journal with entries
-     *
-     * @param data - Journal data with entries
-     * @returns Created journal
-     */
-    createWithEntries(data: CreateJournalData): Promise<Journal>;
-    /**
-     * Post a journal by ID
-     *
-     * @param journalId - Journal ID
-     * @returns Posted journal
-     */
-    post(journalId: string): Promise<Journal>;
-    /**
-     * Void a journal by ID
-     *
-     * @param journalId - Journal ID
-     * @param reason - Reason for voiding
-     * @returns Voided journal
-     */
-    void(journalId: string, reason: string): Promise<Journal>;
-    /**
-     * Find journals by source reference
-     *
-     * @param sourceRef - External reference
-     * @returns Array of journals
-     */
-    findBySourceRef(sourceRef: string): Promise<Journal[]>;
-    /**
-     * Get journals for a specific month
-     *
-     * @param year - Year
-     * @param month - Month (1-12)
-     * @returns Array of journals
-     */
-    findByMonth(year: number, month: number): Promise<Journal[]>;
-    /**
-     * Find all journals belonging to a specific tenant
-     *
-     * @param tenantId - Tenant ID
-     * @returns Array of tenant's journals
-     */
-    findByTenant(tenantId: string): Promise<Journal[]>;
-    /**
-     * Find all global journals (no tenant association).
-     *
-     * Routes through the shared tenant-global helper so it does not throw under
-     * an active tenant context. (#1600)
-     *
-     * @returns Array of global journals
-     */
-    findGlobal(): Promise<Journal[]>;
-    /**
-     * Find journals for a tenant plus all global journals.
-     *
-     * Fails closed if an active tenant context requests a different tenant's
-     * rows; the admin/system path keeps the cross-tenant capability. (#1600)
-     *
-     * @param tenantId - Tenant ID
-     * @returns Array of tenant's journals and global journals
-     */
-    findWithGlobals(tenantId: string): Promise<Journal[]>;
-}
-
-export declare class JournalEntry extends SmrtObject {
-    /**
-     * Tenant ID for multi-tenancy support (nullable for global entries)
-     */
-    tenantId: string | null;
-    /**
-     * Parent journal ID (required)
-     */
-    journalId: string;
-    /**
-     * Account ID (required)
-     */
-    accountId: string;
-    /**
-     * Debit amount (left side)
-     */
-    debit: number;
-    /**
-     * Credit amount (right side)
-     */
-    credit: number;
-    /**
-     * Currency code (e.g., "USD", "CAD", "EUR")
-     */
-    currency: string;
-    /**
-     * Exchange rate to base currency
-     */
-    exchangeRate: number;
-    /**
-     * Line memo/description
-     */
-    memo: string;
-    /**
-     * Extensible metadata
-     */
-    metadata: Record<string, unknown>;
-    constructor(options?: JournalEntryOptions);
-    /**
-     * Validate entry before save
-     */
-    protected validateBeforeSave(): Promise<void>;
-    /**
-     * Check if this is a debit entry
-     */
-    isDebit(): boolean;
-    /**
-     * Check if this is a credit entry
-     */
-    isCredit(): boolean;
-    /**
-     * Get the entry amount (positive value regardless of debit/credit)
-     */
-    getAmount(): number;
-    /**
-     * Get the amount in base currency
-     */
-    getBaseAmount(): number;
-    /**
-     * Get the parent journal
-     */
-    getJournal(): Promise< Journal | null>;
-    /**
-     * Get the account
-     */
-    getAccount(): Promise< Account | null>;
-    /**
-     * Get a formatted description of this entry
-     */
-    getDescription(): Promise<string>;
-}
-
-export declare class JournalEntryCollection extends SmrtCollection<JournalEntry> {
-    static readonly _itemClass: typeof JournalEntry;
-    /**
-     * Find entries by journal
-     *
-     * @param journalId - Journal ID
-     * @returns Array of entries
-     */
-    findByJournal(journalId: string): Promise<JournalEntry[]>;
-    /**
-     * Find entries by account
-     *
-     * @param accountId - Account ID
-     * @returns Array of entries
-     */
-    findByAccount(accountId: string): Promise<JournalEntry[]>;
-    /**
-     * Get account balance
-     *
-     * For debit-normal accounts (Asset, Expense): balance = debits - credits
-     * For credit-normal accounts (Liability, Equity, Revenue): balance = credits - debits
-     *
-     * @param accountId - Account ID
-     * @param asOfDate - Optional date to calculate balance as of
-     * @returns Account balance
-     */
-    getAccountBalance(accountId: string, asOfDate?: Date): Promise<number>;
-    /**
-     * Get trial balance
-     *
-     * @param asOfDate - Optional date for trial balance
-     * @returns Array of trial balance rows
-     */
-    getTrialBalance(asOfDate?: Date): Promise<TrialBalanceRow[]>;
-    /**
-     * Get total debits and credits for a date range
-     *
-     * @param start - Start date
-     * @param end - End date
-     * @returns Object with totalDebits and totalCredits
-     */
-    getTotalsForDateRange(start: Date, end: Date): Promise<{
-        totalDebits: number;
-        totalCredits: number;
-    }>;
-    /**
-     * Get entries for multiple accounts
-     *
-     * @param accountIds - Array of account IDs
-     * @returns Array of entries
-     */
-    findByAccounts(accountIds: string[]): Promise<JournalEntry[]>;
-    /**
-     * Get the running balance for an account (list of entries with running total)
-     *
-     * @param accountId - Account ID
-     * @returns Array of entries with running balance
-     */
-    getAccountLedger(accountId: string): Promise<Array<{
-        entry: JournalEntry;
-        runningBalance: number;
-    }>>;
-    /**
-     * Find all journal entries belonging to a specific tenant
-     *
-     * @param tenantId - Tenant ID
-     * @returns Array of tenant's journal entries
-     */
-    findByTenant(tenantId: string): Promise<JournalEntry[]>;
-    /**
-     * Find all global journal entries (no tenant association).
-     *
-     * Routes through the shared tenant-global helper so it does not throw under
-     * an active tenant context. (#1600)
-     *
-     * @returns Array of global journal entries
-     */
-    findGlobal(): Promise<JournalEntry[]>;
-    /**
-     * Find journal entries for a tenant plus all global entries.
-     *
-     * Fails closed if an active tenant context requests a different tenant's
-     * rows; the admin/system path keeps the cross-tenant capability. (#1600)
-     *
-     * @param tenantId - Tenant ID
-     * @returns Array of tenant's entries and global entries
-     */
-    findWithGlobals(tenantId: string): Promise<JournalEntry[]>;
-}
-
-/**
- * Entry data for creating journal entries
- */
-export declare interface JournalEntryData {
-    accountId: string;
-    debit?: number;
-    credit?: number;
-    currency?: string;
-    exchangeRate?: number;
-    memo?: string;
-}
-
-/**
- * Options for creating a JournalEntry
- */
-export declare interface JournalEntryOptions extends SmrtClassOptions {
-    tenantId?: string | null;
-    journalId?: string;
-    accountId?: string;
-    debit?: number;
-    credit?: number;
-    currency?: string;
-    exchangeRate?: number;
-    memo?: string;
-    metadata?: Record<string, unknown>;
-}
-
-/**
- * Options for creating a Journal
- */
-export declare interface JournalOptions extends SmrtClassOptions {
-    tenantId?: string | null;
-    number?: string;
-    date?: Date;
-    description?: string;
-    sourceModule?: string;
-    sourceRef?: string | null;
-    status?: JournalStatus;
-    postedAt?: Date | null;
-    voidedAt?: Date | null;
-    voidReason?: string | null;
-    metadata?: Record<string, unknown>;
-}
-
-/**
- * Journal status lifecycle
- */
-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;
-    model?: string | undefined;
-};
-
-export declare const smrtLedgersJournalSummarizePrompt: PromptDefinition;
-
-/**
- * A row in the trial balance report
- */
-export declare interface TrialBalanceRow {
-    accountId: string;
-    accountNumber: string;
-    accountName: string;
-    accountType: AccountType;
-    debitBalance: number;
-    creditBalance: number;
-}
-
-export { }
+/**
+ * @happyvertical/smrt-ledgers
+ *
+ * Double-entry accounting ledger for the SMRT framework.
+ *
+ * This package provides models for managing a general ledger with proper
+ * double-entry accounting: every journal must balance (debits = credits).
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   Account,
+ *   AccountCollection,
+ *   Journal,
+ *   JournalCollection,
+ *   JournalEntry,
+ *   JournalEntryCollection
+ * } from '@happyvertical/smrt-ledgers';
+ *
+ * // Create collections
+ * const accounts = await AccountCollection.create({
+ *   db: { type: 'sqlite', url: 'ledger.db' }
+ * });
+ * const journals = await JournalCollection.create({
+ *   db: { type: 'sqlite', url: 'ledger.db' }
+ * });
+ *
+ * // Create chart of accounts
+ * 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 balanced journal entry (IDs guaranteed after save())
+ * const journal = await journals.createWithEntries({
+ *   description: 'Cash sale',
+ *   entries: [
+ *     { accountId: cash.id!, debit: 100 },
+ *     { accountId: revenue.id!, credit: 100 }
+ *   ]
+ * });
+ *
+ * // Post the journal (finalize it)
+ * await journal.post();
+ *
+ * // Get account balance
+ * const cashBalance = await cash.getBalance();
+ * console.log(`Cash balance: $${cashBalance}`);
+ * ```
+ *
+ * @packageDocumentation
+ */
+import './__smrt-register__.js';
+import './prompts.js';
+export { AccountCollection } from './collections/Accounts';
+export { JournalEntryCollection } from './collections/JournalEntries';
+export { JournalCollection } from './collections/Journals';
+export { LEDGER_ACCOUNTS_TABLE, LEDGER_ACCOUNTS_TABLE_MOVE, LEGACY_ACCOUNTS_TABLE, LedgerAccountsTableMoveError, type LedgerAccountsTableMoveOptions, type LedgerAccountsTableMovePlan, type LedgerAccountsTableMoveResult, migrateLedgerAccountsTable, planLedgerAccountsTableMove, } from './migrations/ledger-accounts-table';
+export { Account } from './models/Account';
+export { Journal } from './models/Journal';
+export { JournalEntry } from './models/JournalEntry';
+export { promptMessageOptions, smrtLedgersJournalSummarizePrompt, } from './prompts';
+export type { AccountOptions, AccountTree, AccountTreeNode, AccountType, CreateJournalData, JournalEntryData, JournalEntryOptions, JournalOptions, JournalStatus, TrialBalanceRow, } from './types';
+//# sourceMappingURL=index.d.ts.map