@iota-big3/sdk-gateway

/** * Financial Sector Type Definitions * Following Phase 2g: Strict types for financial operations * * @module financial-types * @description Provides type-safe financial operations with: * - Decimal precision (no floating point errors) * - Immutable transaction records * - Double-entry bookkeeping constraints * - Currency handling * - Audit trail support * - SOX/Financial compliance */ import type { AuthUser, Brand, Result } from './index'; /** * Precise decimal type for financial calculations * Prevents floating point errors in monetary calculations * * @example * ```typescript * // Store as integer cents/minor units * const amount: MonetaryAmount = { * value: 12350, // $123.50 * precision: 2, * currency: 'USD' * }; * ``` */ export interface MonetaryAmount { /** Value in minor units (e.g., cents for USD) */ readonly value: bigint; /** Decimal precision (e.g., 2 for USD) */ readonly precision: number; /** ISO 4217 currency code */ readonly currency: Currency; } /** * ISO 4217 Currency codes * Expandable but starting with common currencies */ export type Currency = 'USD' | 'EUR' | 'GBP' | 'JPY' | 'CAD' | 'AUD' | 'CHF' | 'CNY' | string; /** * Branded account number type for type safety */ export type AccountNumber = Brand<string, 'AccountNumber'>; /** * Branded transaction ID for immutability tracking */ export type TransactionId = Brand<string, 'TransactionId'>; /** * Branded journal entry ID */ export type JournalEntryId = Brand<string, 'JournalEntryId'>; /** * Chart of Accounts - Account Types * Based on standard accounting principles */ export declare enum AccountType { Asset = "ASSET", Liability = "LIABILITY", Equity = "EQUITY", Revenue = "REVENUE", Expense = "EXPENSE", ContraAsset = "CONTRA_ASSET", ContraLiability = "CONTRA_LIABILITY", ContraEquity = "CONTRA_EQUITY", ContraRevenue = "CONTRA_REVENUE", ContraExpense = "CONTRA_EXPENSE" } /** * General Ledger Account * Immutable account definition */ export interface GLAccount { readonly accountNumber: AccountNumber; readonly name: string; readonly type: AccountType; readonly currency: Currency; readonly normalBalance: 'DEBIT' | 'CREDIT'; readonly isActive: boolean; readonly parentAccount?: AccountNumber; readonly metadata: Readonly<{ createdAt: string; createdBy: string; description?: string; taxRelevant?: boolean; costCenter?: string; }>; } /** * Debit or Credit side of a transaction */ export declare enum EntryType { Debit = "DEBIT", Credit = "CREDIT" } /** * Single line item in a journal entry * Immutable once created */ export interface JournalEntryLine { readonly account: AccountNumber; readonly amount: MonetaryAmount; readonly type: EntryType; readonly description?: string; readonly costCenter?: string; readonly project?: string; readonly metadata?: Readonly<Record<string, string>>; } /** * Journal Entry - Must balance (debits = credits) * Immutable transaction record */ export interface JournalEntry { readonly id: JournalEntryId; readonly date: string; readonly description: string; readonly lines: readonly JournalEntryLine[]; readonly status: JournalEntryStatus; readonly reference?: string; readonly reversalOf?: JournalEntryId; readonly metadata: Readonly<{ createdAt: string; createdBy: string; approvedAt?: string; approvedBy?: string; postedAt?: string; postedBy?: string; source: string; sourceId?: string; }>; } /** * Journal Entry Status - Workflow states */ export declare enum JournalEntryStatus { Draft = "DRAFT", PendingApproval = "PENDING_APPROVAL", Approved = "APPROVED", Posted = "POSTED", Reversed = "REVERSED", Rejected = "REJECTED" } /** * Account Balance at a point in time */ export interface AccountBalance { readonly account: AccountNumber; readonly balance: MonetaryAmount; readonly asOf: string; readonly debitTotal: MonetaryAmount; readonly creditTotal: MonetaryAmount; readonly transactionCount: number; } /** * Trial Balance - All account balances */ export interface TrialBalance { readonly asOf: string; readonly balances: readonly AccountBalance[]; readonly totalDebits: MonetaryAmount; readonly totalCredits: MonetaryAmount; readonly isBalanced: boolean; } /** * Double-entry validation result */ export interface DoubleEntryValidation { readonly isValid: boolean; readonly totalDebits: MonetaryAmount; readonly totalCredits: MonetaryAmount; readonly difference?: MonetaryAmount; readonly errors: readonly string[]; } /** * Financial period definition */ export interface FiscalPeriod { readonly id: string; readonly name: string; readonly startDate: string; readonly endDate: string; readonly status: 'OPEN' | 'CLOSED' | 'LOCKED'; readonly year: number; readonly quarter: 1 | 2 | 3 | 4; readonly month: number; } /** * Audit trail entry */ export interface AuditEntry { readonly id: string; readonly timestamp: string; readonly userId: string; readonly action: AuditAction; readonly entityType: string; readonly entityId: string; readonly changes?: Readonly<{ field: string; oldValue: unknown; newValue: unknown; }>[]; readonly metadata?: Readonly<Record<string, unknown>>; } export declare enum AuditAction { Create = "CREATE", Update = "UPDATE", Delete = "DELETE", Approve = "APPROVE", Reject = "REJECT", Post = "POST", Reverse = "REVERSE", Export = "EXPORT", View = "VIEW" } /** * Financial system user with specific permissions */ export interface FinancialUser extends Omit<AuthUser, 'permissions'> { readonly userType: 'accountant' | 'controller' | 'cfo' | 'auditor' | 'clerk'; readonly permissions: readonly FinancialPermission[]; readonly approvalLimit?: MonetaryAmount; readonly costCenters?: readonly string[]; } export declare enum FinancialPermission { ViewJournalEntries = "VIEW_JOURNAL_ENTRIES", ViewTrialBalance = "VIEW_TRIAL_BALANCE", ViewFinancialReports = "VIEW_FINANCIAL_REPORTS", ViewAuditTrail = "VIEW_AUDIT_TRAIL", CreateJournalEntry = "CREATE_JOURNAL_ENTRY", CreateAccount = "CREATE_ACCOUNT", EditDraftEntry = "EDIT_DRAFT_ENTRY", PostJournalEntry = "POST_JOURNAL_ENTRY", ReverseJournalEntry = "REVERSE_JOURNAL_ENTRY", ApproveJournalEntry = "APPROVE_JOURNAL_ENTRY", ApproveNewAccount = "APPROVE_NEW_ACCOUNT", ClosePeriod = "CLOSE_PERIOD", ReopenPeriod = "REOPEN_PERIOD", ManageChartOfAccounts = "MANAGE_CHART_OF_ACCOUNTS", ManageUsers = "MANAGE_USERS", ExportData = "EXPORT_DATA" } /** * Result of posting a journal entry */ export interface PostingResult { readonly success: boolean; readonly journalEntryId?: JournalEntryId; readonly errors?: readonly string[]; readonly warnings?: readonly string[]; readonly affectedAccounts?: readonly AccountNumber[]; } /** * Financial validation context */ export interface FinancialValidationContext { readonly user: FinancialUser; readonly period: FiscalPeriod; readonly action: string; readonly amount?: MonetaryAmount; readonly accounts?: readonly AccountNumber[]; readonly requiresApproval?: boolean; readonly approvalThreshold?: MonetaryAmount; } /** * Check if account is a balance sheet account */ export declare function isBalanceSheetAccount(type: AccountType): boolean; /** * Check if account is an income statement account */ export declare function isIncomeStatementAccount(type: AccountType): boolean; /** * Get normal balance for account type */ export declare function getNormalBalance(type: AccountType): 'DEBIT' | 'CREDIT'; /** * Add two monetary amounts (must be same currency) */ export declare function addMoney(a: MonetaryAmount, b: MonetaryAmount): Result<MonetaryAmount, Error>; /** * Subtract monetary amounts (must be same currency) */ export declare function subtractMoney(a: MonetaryAmount, b: MonetaryAmount): Result<MonetaryAmount, Error>; /** * Format monetary amount for display */ export declare function formatMoney(amount: MonetaryAmount): string; export declare const financialTypes: { isBalanceSheetAccount: typeof isBalanceSheetAccount; isIncomeStatementAccount: typeof isIncomeStatementAccount; getNormalBalance: typeof getNormalBalance; addMoney: typeof addMoney; subtractMoney: typeof subtractMoney; formatMoney: typeof formatMoney; }; //# sourceMappingURL=financial-types.d.ts.map