@classytic/ledger 0.2.0 → 0.4.0

package/dist/trial-balance-DcQ0xj_4.d.mts

@@ -0,0 +1,530 @@
+import { c as DateRange } from "./core-8Xfnpn6g.mjs";
+import { t as CountryPack } from "./index-CxZqRaOU.mjs";
+import { t as Logger } from "./logger-UbTdBb1x.mjs";
+import { ClientSession, Model } from "mongoose";
+
+//#region src/reports/aged-balance.d.ts
+interface AgedBucketConfig {
+  label: string;
+  minDays: number;
+  maxDays: number;
+}
+declare const DEFAULT_BUCKETS: AgedBucketConfig[];
+interface AgedBalanceOptions {
+  AccountModel: Model<unknown>;
+  JournalEntryModel: Model<unknown>;
+  country: CountryPack;
+  orgField?: string;
+}
+interface AgedBalanceParams {
+  organizationId?: unknown;
+  asOfDate?: Date;
+  type: 'receivable' | 'payable';
+  accountIds?: unknown[];
+  dueDateField?: string;
+  contactField?: string;
+  buckets?: AgedBucketConfig[];
+}
+interface AgedBalanceRow {
+  accountId: unknown;
+  accountName: string;
+  accountCode: string;
+  contactId?: unknown;
+  total: number;
+  buckets: Record<string, number>;
+}
+interface AgedBalanceReport {
+  metadata: {
+    generatedAt: string;
+    asOfDate: string;
+    type: string;
+  };
+  bucketLabels: string[];
+  rows: AgedBalanceRow[];
+  totals: Record<string, number>;
+  grandTotal: number;
+}
+declare function generateAgedBalance(opts: AgedBalanceOptions, params: AgedBalanceParams): Promise<AgedBalanceReport>;
+//#endregion
+//#region src/types/report.d.ts
+interface ReportMetadata {
+  businessName?: string;
+  generatedAt: string;
+}
+interface ReportAccount {
+  id: unknown;
+  name: string;
+  code: string;
+  balance: number;
+  isTotal?: boolean;
+  isVirtualTotal?: boolean;
+  isCalculated?: boolean;
+}
+interface ReportGroup {
+  name: string;
+  total: number;
+  accounts: ReportAccount[];
+}
+interface ReportCategory {
+  name: string;
+  total: number;
+  groups: ReportGroup[];
+}
+interface TrialBalanceRow {
+  account: unknown;
+  initial: {
+    debit: number;
+    credit: number;
+  };
+  current: {
+    debit: number;
+    credit: number;
+  };
+  ending: {
+    debit: number;
+    credit: number;
+  };
+}
+interface TrialBalanceReport {
+  metadata?: ReportMetadata & {
+    periodStart: string;
+    periodEnd: string;
+    displayPeriod: string;
+  };
+  rows: TrialBalanceRow[];
+  period: DateRange;
+}
+interface BalanceSheetReport {
+  metadata: ReportMetadata & {
+    asOfDate: string;
+    displayDate: string;
+  };
+  assets: ReportCategory;
+  liabilities: ReportCategory;
+  equity: ReportCategory;
+  summary: {
+    totalAssets: number;
+    totalLiabilities: number;
+    totalEquity: number;
+    liabilitiesAndEquity: number;
+    difference: number;
+    isBalanced: boolean;
+  };
+}
+interface IncomeStatementReport {
+  metadata: ReportMetadata & {
+    periodStart: string;
+    periodEnd: string;
+    displayPeriod: string;
+  };
+  revenue: ReportCategory;
+  costOfSales: number;
+  grossProfit: number;
+  expenses: ReportCategory;
+  operatingIncome: number;
+  netIncome: number;
+}
+interface LedgerEntry {
+  date: Date;
+  referenceNumber: string;
+  label: string;
+  debit: number;
+  credit: number;
+  runningBalance: number;
+}
+interface GeneralLedgerAccount {
+  account: unknown;
+  openingBalance: number;
+  entries: LedgerEntry[];
+  closingBalance: number;
+}
+interface GeneralLedgerReport {
+  metadata?: ReportMetadata & {
+    periodStart: string;
+    periodEnd: string;
+    displayPeriod: string;
+  };
+  accounts: GeneralLedgerAccount[];
+  period: DateRange;
+}
+interface CashFlowSection {
+  total: number;
+  accounts: Array<{
+    name: string;
+    code: string;
+    amount: number;
+  }>;
+}
+interface CashFlowReport {
+  metadata: ReportMetadata & {
+    periodStart: string;
+    periodEnd: string;
+    displayPeriod: string;
+  };
+  operating: CashFlowSection;
+  investing: CashFlowSection;
+  financing: CashFlowSection;
+  netCashFlow: number;
+}
+interface TaxAccountBalance {
+  code: string;
+  name: string;
+  balance: number;
+  taxMetadata?: unknown;
+}
+interface TaxReturnSummary {
+  totalSales: number;
+  gstHstCollected: number;
+  inputTaxCredits: number;
+  netTax: number;
+  finalAmount: number;
+  isRefund: boolean;
+  refundAmount: number;
+  paymentAmount: number;
+}
+interface TaxReport {
+  period: {
+    startDate: string;
+    endDate: string;
+    province: string;
+  };
+  accountBalances: {
+    collected: Record<string, TaxAccountBalance>;
+    itc: Record<string, TaxAccountBalance>;
+    instalments: Record<string, TaxAccountBalance>;
+  };
+  craLines: Record<string | number, number>;
+  summary: TaxReturnSummary;
+  calculatedAt: string;
+}
+//#endregion
+//#region src/reports/balance-sheet.d.ts
+interface BalanceSheetOptions {
+  AccountModel: Model<unknown>;
+  JournalEntryModel: Model<unknown>;
+  country: CountryPack;
+  orgField?: string;
+  fiscalYearStartMonth?: number;
+  /**
+   * The retained earnings account code (e.g. '3600' CA, '3310' BD).
+   * This account is excluded from normal equity grouping and its balance
+   * is folded into the computed Retained Earnings section.
+   */
+  retainedEarningsAccountCode?: string;
+  /** Display code for the "Previous Years Retained Earnings" line */
+  retainedEarningsDisplayCode?: string;
+  /** Display code for current year net income (default: '3680') */
+  currentYearEarningsCode?: string;
+}
+declare function generateBalanceSheet(opts: BalanceSheetOptions, params: {
+  organizationId?: unknown;
+  dateOption: 'month' | 'quarter' | 'year' | 'custom';
+  dateValue: unknown;
+  businessName?: string;
+  filters?: Record<string, unknown>;
+}): Promise<BalanceSheetReport>;
+//#endregion
+//#region src/reports/budget-vs-actual.d.ts
+interface BudgetVsActualOptions {
+  AccountModel: Model<unknown>;
+  JournalEntryModel: Model<unknown>;
+  BudgetModel: Model<unknown>;
+  country: CountryPack;
+  orgField?: string;
+}
+interface BudgetVsActualParams {
+  organizationId?: unknown;
+  dateOption: 'month' | 'quarter' | 'year' | 'custom';
+  dateValue: unknown;
+  accountIds?: unknown[];
+  filters?: Record<string, unknown>;
+}
+interface BudgetVsActualRow {
+  accountId: unknown;
+  accountName: string;
+  accountCode: string;
+  category: string;
+  budgetAmount: number;
+  actualAmount: number;
+  variance: number;
+  variancePercent: number;
+}
+interface BudgetVsActualReport {
+  metadata: {
+    generatedAt: string;
+    periodStart: string;
+    periodEnd: string;
+  };
+  rows: BudgetVsActualRow[];
+  summary: {
+    totalBudget: number;
+    totalActual: number;
+    totalVariance: number;
+  };
+}
+declare function generateBudgetVsActual(opts: BudgetVsActualOptions, params: BudgetVsActualParams): Promise<BudgetVsActualReport>;
+//#endregion
+//#region src/reports/cash-flow.d.ts
+interface CashFlowOptions {
+  AccountModel: Model<unknown>;
+  JournalEntryModel: Model<unknown>;
+  country: CountryPack;
+  orgField?: string;
+}
+declare function generateCashFlow(opts: CashFlowOptions, params: {
+  organizationId?: unknown;
+  dateOption: 'month' | 'quarter' | 'year' | 'custom';
+  dateValue: unknown;
+  businessName?: string;
+  filters?: Record<string, unknown>;
+}): Promise<CashFlowReport>;
+//#endregion
+//#region src/reports/dimension-breakdown.d.ts
+interface DimensionBreakdownOptions {
+  AccountModel: Model<unknown>;
+  JournalEntryModel: Model<unknown>;
+  country: CountryPack;
+  orgField?: string;
+}
+interface DimensionBreakdownParams {
+  organizationId?: unknown;
+  dateOption: 'month' | 'quarter' | 'year' | 'custom';
+  dateValue: unknown;
+  /** Field on journalItems to group by, e.g. 'departmentId' */
+  dimension: string;
+  /** Filter accounts by category, e.g. 'Income Statement-Expense' */
+  accountCategory?: string;
+  /** Additional item-level filters */
+  filters?: Record<string, unknown>;
+}
+interface DimensionBreakdownRow {
+  dimensionValue: unknown;
+  accounts: Array<{
+    id: unknown;
+    name: string;
+    code: string;
+    balance: number;
+  }>;
+  total: number;
+}
+interface DimensionBreakdownReport {
+  metadata: {
+    generatedAt: string;
+    dimension: string;
+    periodStart: string;
+    periodEnd: string;
+  };
+  rows: DimensionBreakdownRow[];
+  grandTotal: number;
+}
+declare function generateDimensionBreakdown(opts: DimensionBreakdownOptions, params: DimensionBreakdownParams): Promise<DimensionBreakdownReport>;
+//#endregion
+//#region src/reports/fiscal-close.d.ts
+interface FiscalCloseOptions {
+  AccountModel: Model<unknown>;
+  JournalEntryModel: Model<unknown>;
+  FiscalPeriodModel: Model<unknown>;
+  country: CountryPack;
+  orgField?: string;
+  /** The retained earnings account code — where year-end net income is transferred to */
+  retainedEarningsAccountCode?: string;
+  logger?: Logger;
+}
+interface FiscalCloseResult {
+  periodId: unknown;
+  netIncome: number;
+  closingEntryId: unknown | null;
+  accountsClosed: number;
+  closedAt: Date;
+}
+declare function closeFiscalPeriod(opts: FiscalCloseOptions, params: {
+  periodId: unknown;
+  organizationId?: unknown;
+  closedBy?: string;
+  session?: ClientSession;
+}): Promise<FiscalCloseResult>;
+interface FiscalReopenResult {
+  periodId: unknown;
+  deletedEntryId: unknown | null;
+  reopenedAt: Date;
+}
+declare function reopenFiscalPeriod(opts: Pick<FiscalCloseOptions, 'JournalEntryModel' | 'FiscalPeriodModel'> & {
+  orgField?: string;
+  logger?: Logger; /** Any model on the same connection — used to start sessions */
+  AccountModel?: Model<unknown>;
+}, params: {
+  periodId: unknown;
+  organizationId?: unknown;
+  reopenedBy?: string;
+  session?: ClientSession;
+}): Promise<FiscalReopenResult>;
+//#endregion
+//#region src/reports/general-ledger.d.ts
+interface GeneralLedgerOptions {
+  AccountModel: Model<unknown>;
+  JournalEntryModel: Model<unknown>;
+  country: CountryPack;
+  orgField?: string;
+  fiscalYearStartMonth?: number;
+}
+declare function generateGeneralLedger(opts: GeneralLedgerOptions, params: {
+  organizationId?: unknown;
+  dateOption: 'month' | 'quarter' | 'year' | 'custom';
+  dateValue: unknown;
+  accountId?: string;
+  businessName?: string;
+  filters?: Record<string, unknown>;
+}): Promise<GeneralLedgerReport>;
+//#endregion
+//#region src/reports/income-statement.d.ts
+interface IncomeStatementOptions {
+  AccountModel: Model<unknown>;
+  JournalEntryModel: Model<unknown>;
+  country: CountryPack;
+  orgField?: string;
+}
+declare function generateIncomeStatement(opts: IncomeStatementOptions, params: {
+  organizationId?: unknown;
+  dateOption: 'month' | 'quarter' | 'year' | 'custom';
+  dateValue: unknown;
+  businessName?: string;
+  filters?: Record<string, unknown>;
+}): Promise<IncomeStatementReport>;
+//#endregion
+//#region src/utils/revaluation.d.ts
+/**
+ * Foreign Exchange Revaluation Utilities
+ *
+ * Pure functions for computing unrealized exchange gains/losses
+ * on foreign-currency-denominated balance sheet accounts.
+ *
+ * All monetary values are integer cents.
+ * Exchange rates are decimals (e.g., 1 USD = 1.37 CAD means rate = 1.37).
+ */
+/** A new exchange rate for a foreign currency */
+interface RevaluationRate {
+  /** ISO 4217 currency code */
+  currency: string;
+  /** New exchange rate: 1 foreign unit = rate base units (decimal, e.g. 1.37) */
+  rate: number;
+}
+/** An account's foreign-currency balance at historical rates */
+interface AccountForeignBalance {
+  accountId: unknown;
+  accountName: string;
+  accountCode: string;
+  currency: string;
+  /** Integer cents in foreign currency */
+  foreignBalance: number;
+  /** Integer cents in base currency (at historical rates) */
+  baseBalance: number;
+  /** CategoryKey of the account */
+  category: string;
+}
+/** Result of revaluing a single account */
+interface RevaluationResult {
+  accountId: unknown;
+  accountName: string;
+  accountCode: string;
+  currency: string;
+  foreignBalance: number;
+  /** Base currency amount at historical rates (integer cents) */
+  historicalBase: number;
+  /** Base currency amount at the new rate (integer cents) */
+  revaluedBase: number;
+  /** revaluedBase - historicalBase; positive = gain, negative = loss */
+  gainLoss: number;
+}
+/**
+ * Compute revaluation results for a set of accounts at new exchange rates.
+ *
+ * For each account, finds the matching rate by currency, computes the
+ * revalued base amount, and determines the gain/loss.
+ * Accounts with zero gain/loss are excluded from the results.
+ *
+ * @param accounts - Foreign-currency account balances at historical rates
+ * @param rates - New exchange rates to revalue against
+ * @param baseCurrency - The functional/base currency code (accounts in this currency are skipped)
+ */
+declare function computeRevaluation(accounts: AccountForeignBalance[], rates: RevaluationRate[], baseCurrency: string): RevaluationResult[];
+/**
+ * Build a balanced revaluation journal entry from revaluation results.
+ *
+ * For each result with a non-zero gain/loss:
+ * - Gain (positive gainLoss): Debit the account, Credit the unrealized gain/loss account
+ * - Loss (negative gainLoss): Credit the account, Debit the unrealized gain/loss account
+ *
+ * @param results - Revaluation results from computeRevaluation
+ * @param unrealizedGainLossAccountId - The account to book the offsetting entry against
+ * @param date - Date for the revaluation entry
+ */
+declare function buildRevaluationEntry(results: RevaluationResult[], unrealizedGainLossAccountId: unknown, date: Date): {
+  journalItems: Array<{
+    account: unknown;
+    debit: number;
+    credit: number;
+    label: string;
+    originalDebit: number;
+    originalCredit: number;
+  }>;
+  totalDebit: number;
+  totalCredit: number;
+  label: string;
+};
+//#endregion
+//#region src/reports/revaluation.d.ts
+interface RevaluationOptions {
+  AccountModel: Model<unknown>;
+  JournalEntryModel: Model<unknown>;
+  country: CountryPack;
+  orgField?: string;
+  baseCurrency: string;
+}
+interface RevaluationParams {
+  organizationId?: unknown;
+  asOfDate: Date;
+  rates: RevaluationRate[];
+  unrealizedGainLossAccountId: unknown;
+  /** If true, create and save the revaluation journal entry */
+  generateEntry?: boolean;
+}
+interface RevaluationReport {
+  metadata: {
+    generatedAt: string;
+    asOfDate: string;
+    baseCurrency: string;
+  };
+  results: RevaluationResult[];
+  totalGainLoss: number;
+  /** Present only when generateEntry was true */
+  entryId?: unknown;
+}
+/**
+ * Generate a foreign exchange revaluation report.
+ *
+ * 1. Finds all accounts with a `currency` field (foreign-currency accounts)
+ * 2. Filters to balance sheet accounts only (not P&L)
+ * 3. Aggregates foreign-currency and base-currency balances from posted entries
+ * 4. Computes gain/loss at the new rates
+ * 5. Optionally creates and saves a balanced journal entry
+ */
+declare function generateRevaluation(opts: RevaluationOptions, params: RevaluationParams): Promise<RevaluationReport>;
+//#endregion
+//#region src/reports/trial-balance.d.ts
+interface TrialBalanceOptions {
+  AccountModel: Model<unknown>;
+  JournalEntryModel: Model<unknown>;
+  country: CountryPack;
+  orgField?: string;
+  fiscalYearStartMonth?: number;
+}
+declare function generateTrialBalance(opts: TrialBalanceOptions, params: {
+  organizationId?: unknown;
+  dateOption: 'month' | 'quarter' | 'year' | 'custom';
+  dateValue: unknown;
+  accountId?: string;
+  businessName?: string;
+  filters?: Record<string, unknown>;
+}): Promise<TrialBalanceReport>;
+//#endregion
+export { AgedBucketConfig as $, BudgetVsActualReport as A, IncomeStatementReport as B, DimensionBreakdownReport as C, generateCashFlow as D, CashFlowOptions as E, BalanceSheetReport as F, TaxReport as G, ReportAccount as H, CashFlowReport as I, TrialBalanceRow as J, TaxReturnSummary as K, CashFlowSection as L, generateBudgetVsActual as M, BalanceSheetOptions as N, BudgetVsActualOptions as O, generateBalanceSheet as P, AgedBalanceRow as Q, GeneralLedgerAccount as R, DimensionBreakdownParams as S, generateDimensionBreakdown as T, ReportCategory as U, LedgerEntry as V, ReportGroup as W, AgedBalanceParams as X, AgedBalanceOptions as Y, AgedBalanceReport as Z, FiscalCloseResult as _, RevaluationReport as a, reopenFiscalPeriod as b, RevaluationRate as c, computeRevaluation as d, DEFAULT_BUCKETS as et, IncomeStatementOptions as f, FiscalCloseOptions as g, generateGeneralLedger as h, RevaluationParams as i, BudgetVsActualRow as j, BudgetVsActualParams as k, RevaluationResult as l, GeneralLedgerOptions as m, generateTrialBalance as n, generateRevaluation as o, generateIncomeStatement as p, TrialBalanceReport as q, RevaluationOptions as r, AccountForeignBalance as s, TrialBalanceOptions as t, generateAgedBalance as tt, buildRevaluationEntry as u, FiscalReopenResult as v, DimensionBreakdownRow as w, DimensionBreakdownOptions as x, closeFiscalPeriod as y, GeneralLedgerReport as z };

package/docs/reports.md

@@ -120,7 +120,7 @@ const result = await closeFiscalPeriod(
 ```
 
 - Zeroes all income/expense account balances via a `YEAR_END` closing journal entry
-- Transfers net income to retained earnings (default code: `3660`, configurable via `retainedEarningsCode`)
+- Transfers net income to retained earnings (configurable via `retainedEarningsAccountCode`)
 - Marks period as `closed: true`
 - Atomic by default (internal transaction)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/ledger",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Production-grade double-entry accounting engine for MongoDB — schemas, reports, tax, multi-tenant",
   "type": "module",
   "sideEffects": false,
@@ -88,8 +88,8 @@
     "url": "git+https://github.com/classytic/accounting.git"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.3.2",
-    "mongoose": ">=9.0.0"
+    "@classytic/mongokit": ">=3.5.3",
+    "mongoose": ">=9.4.1"
   },
   "engines": {
     "node": ">=22"
@@ -101,14 +101,22 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build && npm run typecheck",
-    "release": "npm run build && npm run typecheck && npm publish --access public"
+    "lint": "biome check src/",
+    "lint:fix": "biome check src/ --write",
+    "format": "biome format src/ --write",
+    "check": "biome ci src/ --diagnostic-level=error",
+    "knip": "knip",
+    "prepublishOnly": "npm run check && npm run build && npm run typecheck && npm test",
+    "release": "npm run check && npm run build && npm run typecheck && npm test && npm publish --access public"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
+    "@classytic/mongokit": "^3.5.3",
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "knip": "^6.3.0",
     "mongodb-memory-server": "^10.2.3",
-    "mongoose": "^9.3.1",
+    "mongoose": "^9.4.1",
     "tsdown": "^0.21.5",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"

package/dist/account.repository-C7gwFLfM.d.mts

@@ -1,29 +0,0 @@
-import { t as CountryPack } from "./index-ZnSiqHYV.mjs";
-import { s as StrictnessConfig } from "./engine-BzBMpWuy.mjs";
-import { Model } from "mongoose";
-
-//#region src/repositories/journal-entry.repository.d.ts
-/**
- * Wire post/reverse onto an existing mongokit Repository.
- *
- * @param repository - A mongokit Repository instance (already created)
- * @param JournalEntryModel - The Mongoose model for journal entries
- * @param orgField - The multi-tenant field name (e.g. 'business')
- * @param strictness - Strictness rules (immutable, requireActor, requireApproval)
- */
-declare function wireJournalEntryMethods(repository: any, JournalEntryModel: Model<unknown>, orgField?: string, strictness?: StrictnessConfig): void;
-//#endregion
-//#region src/repositories/account.repository.d.ts
-/**
- * Wire seedAccounts, bulkCreate and posting-account validation
- * onto an existing mongokit Repository.
- *
- * @param repository - A mongokit Repository instance (already created)
- * @param AccountModel - The Mongoose model for accounts
- * @param country - The CountryPack for account type lookups
- * @param orgField - The multi-tenant field name (e.g. 'business')
- */
-declare function wireAccountMethods(repository: any, AccountModel: Model<unknown>, country: CountryPack, orgField?: string): void;
-//#endregion
-export { wireJournalEntryMethods as n, wireAccountMethods as t };
-//# sourceMappingURL=account.repository-C7gwFLfM.d.mts.map

package/dist/account.repository-C7gwFLfM.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"account.repository-C7gwFLfM.d.mts","names":[],"sources":["../src/repositories/journal-entry.repository.ts","../src/repositories/account.repository.ts"],"mappings":";;;;;;;;;;;;;iBAgEgB,uBAAA,CAEd,UAAA,OACA,iBAAA,EAAmB,KAAA,WACnB,QAAA,WACA,UAAA,GAAa,gBAAA;;;;;;;;;;;;iBC3CC,kBAAA,CAEd,UAAA,OACA,YAAA,EAAc,KAAA,WACd,OAAA,EAAS,WAAA,EACT,QAAA"}