@happyvertical/smrt-ledgers 0.30.0

package/dist/index.d.ts

@@ -0,0 +1,647 @@
+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)
+     *
+     * @returns Array of global accounts
+     */
+    findGlobal(): Promise<Account[]>;
+    /**
+     * Find accounts for a tenant plus all global accounts
+     *
+     * @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)
+     *
+     * @returns Array of global journals
+     */
+    findGlobal(): Promise<Journal[]>;
+    /**
+     * Find journals for a tenant plus all global journals
+     *
+     * @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)
+     *
+     * @returns Array of global journal entries
+     */
+    findGlobal(): Promise<JournalEntry[]>;
+    /**
+     * Find journal entries for a tenant plus all global entries
+     *
+     * @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 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 { }