Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

54.7 KB
Raw Blame
export interface User {
  id: string
  email: string
  is_active: boolean
  is_superuser: boolean
  is_verified: boolean
  is_2fa_enabled: boolean
  preferences: UserPreferences
}

export interface AdminUser {
  id: string
  email: string
  is_active: boolean
  is_superuser: boolean
  is_verified: boolean
  preferences: UserPreferences | null
}

export interface AdminUserList {
  items: AdminUser[]
  total: number
}

export interface Passkey {
  id: string
  name: string
  transports: string[] | null
  aaguid: string | null
  device_type: string | null
  backed_up: boolean | null
  created_at: string
  last_used_at: string | null
}

export interface PasskeyOptionsResponse {
  challenge_id: string
  options: Record<string, unknown>
}

export interface AppSetting {
  key: string
  value: string
}

export type WorkspaceRole = 'owner' | 'editor' | 'viewer' | 'manager'

export type WorkspaceKind = 'personal' | 'business'

export interface Workspace {
  id: string
  name: string
  // Widened on purpose: a workspace stored before the current kind list
  // still has to render. Writes are narrowed to WorkspaceKind.
  kind: string
  is_archived: boolean
  default_currency: string
  locale: string | null
  /** The calendar this workspace keeps its books in, or null to follow the
   *  application timezone. */
  timezone: string | null
  /** Where the workspace files. Selects the fiscal document pack; never the
   *  interface language. */
  tax_jurisdiction: string | null
  icon: string | null
  color: string | null
  created_at: string
  created_by_user_id: string | null
  managed_by_user_id: string | null
  role: WorkspaceRole | null
  /** Modules this workspace shows. Resolved server-side; see lib/modules.ts. */
  enabled_modules: string[]
}

export interface WorkspaceMember {
  id: string
  user_id: string
  email: string
  display_name: string | null
  role: WorkspaceRole
  joined_at: string
}

export interface UserPreferences {
  language?: string
  date_format?: string
  currency_display?: string
  display_name?: string
  onboarding_completed?: boolean
}

export interface Category {
  id: string
  user_id: string
  group_id: string | null
  name: string
  icon: string
  color: string
  is_system: boolean
  is_hidden: boolean
  treat_as_transfer: boolean
  is_ignored: boolean
}

/** Active rules that assign a category, used when retiring one. */
export interface CategoryRuleUsage {
  rules: { id: string; name: string }[]
}

/** Everything that still points at a category, used when deleting one. */
export interface CategoryUsage {
  transactions: number
  budgets: number
  recurring_transactions: number
  rules: { id: string; name: string }[]
}

export interface CategoryGroup {
  id: string
  user_id: string
  name: string
  icon: string
  color: string
  position: number
  is_system: boolean
  is_hidden: boolean
  categories: Category[]
}

export interface ConnectionInstitution {
  name: string
  logo_url: string | null
}

export interface BankConnection {
  id: string
  user_id: string
  provider: string
  institution_name: string
  display_name: string | null
  logo_url: string | null
  external_id: string
  status: string
  settings: ConnectionSettings | null
  last_sync_at: string | null
  created_at: string
  // Institutions this link spans (issue #345). Empty for one-institution
  // providers — institution_name covers those.
  institutions: ConnectionInstitution[]
}

export interface ConnectionSettings {
  payee_source?: 'auto' | 'merchant' | 'payment_data' | 'description' | 'none'
  import_pending?: boolean
  sync_assets?: boolean
}

// Response of POST /connections/{id}/sync: the connection plus what the run
// actually did. "rate_limited" means the provider throttled the request
// (429): nothing was pulled and last_sync_at was left untouched (issue #736).
export interface SyncResult extends BankConnection {
  merged_count: number
  sync_outcome: 'refreshed' | 'rate_limited'
}

export type AccountType = 'checking' | 'savings' | 'credit_card' | 'loan' | 'investment' | 'wallet'

export interface Account {
  id: string
  user_id: string
  connection_id: string | null
  external_id: string | null
  name: string
  display_name: string | null
  // Last 4 chars of the bank's identifier for the account, when the provider
  // exposes one. Tells apart accounts a bank reports under an identical name.
  masked_number: string | null
  // Denormalized bank identity from the linked connection (null for manual
  // accounts). Used to render the institution logo next to the account.
  institution_name: string | null
  institution_logo_url: string | null
  type: string
  secured_asset_id?: string | null
  // Loan accounts only: contract terms the payment schedule is computed from.
  loan_kind?: LoanKind | null
  loan_original_amount?: number | null
  loan_interest_rate?: number | null
  loan_rate_period?: LoanRatePeriod | null
  loan_term_months?: number | null
  loan_first_payment_date?: string | null
  loan_amortization?: LoanAmortization | null
  balance: number
  current_balance: number
  previous_balance: number | null
  // Date of the opening-balance transaction; null when there is none.
  balance_date?: string | null
  balance_primary: number | null
  // No real FX rate: balance_primary is unset and totals use the native amount.
  fx_fallback?: boolean
  currency: string
  credit_limit: number | null
  available_credit: number | null
  statement_close_day: number | null
  payment_due_day: number | null
  next_close_date: string | null
  next_due_date: string | null
  minimum_payment: number | null
  card_brand: string | null
  card_level: string | null
  shared_balance_group: string | null
  // Open bill (due today or later) of a card on a shared credit line, in the
  // account's currency. Null when the card has no such bill; the row then
  // keeps showing the balance.
  open_bill_total?: number | null
  // Same bill in the user's primary currency; null when not converted.
  open_bill_total_primary?: number | null
  is_closed: boolean
  closed_at: string | null
}

export interface CreditCardBill {
  id: string
  account_id: string
  external_id: string
  due_date: string // YYYY-MM-DD
  total_amount: number
  currency: string
  minimum_payment: number | null
}

export interface Collection {
  id: string
  user_id: string
  name: string
  icon: string
  color: string
  position: number
  account_ids: string[]
  account_count: number
  wallet_ids: string[]
  wallet_count: number
}

export interface AccountSummary {
  account_id: string
  current_balance: number
  opening_balance: number
  monthly_income: number
  monthly_expenses: number
  current_balance_primary: number | null
  opening_balance_primary: number | null
  monthly_income_primary: number | null
  monthly_expenses_primary: number | null
  projected_income?: number
  projected_expenses?: number
  projected_income_primary?: number | null
  projected_expenses_primary?: number | null
  fx_fallback?: boolean
}

/** Set when this transaction settles an invoice. Absent in workspaces
 *  without the invoicing module — the query behind it does not run there. */
export interface TransactionInvoiceLink {
  invoice_id: string
  number: number | null
  series: string | null
  /** The name an imported invoice arrived with; it carries no number of
   *  ours, so the badge reads this instead. */
  external_number: string | null
  amount: string
}

/** A description used before, with the category and payee of its latest use. */
export interface DescriptionSuggestion {
  description: string
  category_id: string | null
  payee_id: string | null
}

export interface Transaction {
  /** Every invoice this transaction settles — a payout net of fees
   *  settles several. Absent in a workspace without the module. */
  invoice_links?: TransactionInvoiceLink[] | null
  id: string
  user_id: string
  account_id: string | null
  category_id: string | null
  category: Category | null
  external_id: string | null
  description: string
  original_description: string | null
  amount: number
  currency: string
  date: string
  type: 'debit' | 'credit'
  source: string
  status: 'posted' | 'pending'
  payee: string | null
  payee_id: string | null
  payee_name: string | null
  notes: string | null
  transfer_pair_id: string | null
  /**
   * The other leg of the transfer this row belongs to, when it is one.
   * The paginated list fills it so the badge can name the account the
   * transfer is linked to (issue #810); other endpoints leave it null.
   */
  transfer_counterpart?: { account_id: string; account_name: string } | null
  amount_primary: number | null
  fx_rate_used: number | null
  fx_fallback: boolean
  attachment_count?: number
  installment_number: number | null
  total_installments: number | null
  installment_total_amount: number | null
  installment_purchase_date: string | null
  installment_series_id: string | null
  bill_id: string | null
  // Manual override for which credit-card bill cycle this tx belongs to
  // (issue #92). Empty / null = use auto bucketing (Pluggy bill_id when
  // available, cycle math otherwise). Setting it forces the tx into the
  // bill whose due_date matches.
  effective_bill_date: string | null
  // The recurring bill this transaction fulfills, if any (issue #116).
  recurring_transaction_id?: string | null
  splits: TransactionSplit[]
  // Shared-transaction view fields. Set per-request when the viewer
  // is a linked split member but not the owner. Render `viewer_share`
  // as the amount and treat the row as read-only — editing belongs
  // to the parent's owner.
  is_shared?: boolean
  viewer_share?: number | null
  group_id?: string | null
  // Display name of the parent's owner (the person who actually paid).
  // Derived per-request from the group's `is_self` member.
  parent_owner_name?: string | null
  // Flag to exclude this transaction from reports and dashboard aggregations
  is_ignored: boolean
  // Keeps the transaction in the ledger/balance while excluding it from P&L.
  exclude_from_pnl?: boolean
  // Balance right after this row, filled by the server only when the list
  // was asked for it on a single non-credit-card account (#1202).
  // `running_balance_primary` is null when the account is in the primary
  // currency.
  running_balance?: number | null
  running_balance_primary?: number | null
  virtual?: boolean
}

// Scope for installment-series edits/deletes: "this" (default) only touches
// the target row, "future" touches it plus later installments, "all" touches
// the whole series. Ignored server-side for non-installment transactions.
export type TransactionApplyScope = 'this' | 'future' | 'all'

// Payload for POST /api/transactions/installments. `base` is
// the amount repeated as-is; the backend fans it out into `installments`
// equal parcels sharing the installment fingerprint and stores
// installment_total_amount = base.amount * installments.
export interface InstallmentSeriesInput {
  base: {
    account_id: string
    category_id?: string | null
    payee_id?: string | null
    description: string
    amount: number
    date: string
    type: 'debit' | 'credit'
    currency?: string
    notes?: string | null
    status?: 'posted' | 'pending'
    amount_primary?: number | null
    fx_rate_used?: number | null
    effective_bill_date?: string | null
    splits?: TransactionSplitsInput | null
  }
  installments: number
  first_installment_status?: 'posted' | 'pending'
  frequency?: 'monthly' | 'quarterly' | 'semiannual' | 'weekly' | 'biweekly' | 'yearly'
}

export type ShareType = 'equal' | 'exact' | 'percent'

export interface TransactionSplit {
  id: string
  transaction_id: string
  group_member_id: string
  share_amount: number
  share_type: string
  share_pct: number | null
  notes: string | null
  created_at: string
}

export interface TransactionSplitInput {
  group_member_id: string
  share_amount?: number | null
  share_pct?: number | null
  notes?: string | null
}

export interface TransactionSplitsInput {
  share_type: ShareType
  splits: TransactionSplitInput[]
}

// Payload the transaction dialog sends on save. `splits` is the normalized
// TransactionSplitsInput the split section produces, not the
// TransactionSplit[] rows the API returns, so the edit payload type reflects
// the form's actual shape.
export type TransactionEditPayload = Omit<Partial<Transaction>, 'splits'> & {
  splits?: TransactionSplitsInput | null
}

export type GroupKind = 'social' | 'cost_center' | 'project' | 'client' | 'other'

export interface Group {
  id: string
  user_id: string
  name: string
  kind: GroupKind
  default_currency: string
  icon: string
  color: string
  is_archived: boolean
  // Derived server-side per request. False = the current user is a
  // linked member, not the owner — UI should hide edit affordances.
  is_owner: boolean
  notes: string | null
  created_at: string
  members: GroupMember[]
}

export interface GroupMember {
  id: string
  group_id: string
  name: string
  linked_user_id: string | null
  email: string | null
  is_self: boolean
  created_at: string
}

export interface GroupSettlement {
  id: string
  group_id: string
  from_member_id: string
  to_member_id: string
  amount: number
  currency: string
  date: string
  transaction_id: string | null
  notes: string | null
  created_at: string
}

export interface GroupBalanceLine {
  member_id: string
  currency: string
  // Positive = member owes the owner. Negative = owner owes member.
  amount: number
  // FX-converted to the group's default currency for cross-currency rollups.
  amount_in_default_currency: number
}

export interface GroupBalances {
  group_id: string
  self_member_id: string | null
  default_currency: string
  lines: GroupBalanceLine[]
}

export interface GroupSummaryMonth {
  /** "YYYY-MM" — the client formats it for display. */
  month: string
  total: number
}

export interface GroupSummaryCategory {
  /** Null for transactions with no category. */
  category_id: string | null
  name: string | null
  color: string | null
  total: number
}

export interface GroupSummary {
  group_id: string
  default_currency: string
  total_moved: number
  months: GroupSummaryMonth[]
  categories: GroupSummaryCategory[]
}

/** A fiscal document belonging to a payee. `kind` mirrors the backend's
 *  closed TaxIdKind; the value arrives normalised. */
export interface PayeeTaxId {
  kind: string
  value: string
}

export interface Payee {
  id: string
  user_id: string
  name: string
  /** Legal nature, or null when unknown — the normal state for a row sync created. */
  type: 'person' | 'company' | null
  /** Where the row came from. Server-set at creation and never editable. */
  source: 'manual' | 'sync' | 'import'
  is_favorite: boolean
  notes: string | null
  email: string | null
  phone: string | null
  address: string | null
  website: string | null
  tax_ids: PayeeTaxId[]
  created_at: string
  transaction_count: number
}

/** One document kind as the active workspace's jurisdiction describes it.
 *  `offered` marks the ones its pack asks for; the rest stay selectable,
 *  because a counterparty's country is not the workspace's. */
export interface TaxIdKindOption {
  kind: string
  label_key: string
  mask: string | null
  offered: boolean
}

export interface PayeeSummary {
  payee: Payee
  total_spent: number
  total_received: number
  transaction_count: number
  most_common_category: Category | null
  last_transaction_date: string | null
}

export interface RuleCondition {
  field: string
  op: string
  value: string | number
}

/** A nested group of conditions joined by its own operator.
 *
 * Groups let a rule mix AND and OR — `type is debit AND (contains UBER OR
 * contains 99POP)`. They hold leaf conditions only, capping rule depth at the
 * two levels the engine evaluates and the editor exposes.
 */
export interface RuleConditionGroup {
  op: 'and' | 'or'
  conditions: RuleCondition[]
}

/** An entry of a rule's condition list: a leaf condition or one group. */
export type RuleConditionNode = RuleCondition | RuleConditionGroup

export interface RuleAction {
  op: string
  value: string
}

export interface Rule {
  id: string
  user_id: string
  name: string
  conditions_op: 'and' | 'or'
  conditions: RuleConditionNode[]
  actions: RuleAction[]
  priority: number
  is_active: boolean
  apply_to_existing?: boolean
  overwrite_existing_categories?: boolean
}

export interface RuleExportItem {
  name: string
  conditions_op: 'and' | 'or'
  conditions: RuleConditionNode[]
  actions: RuleAction[]
  priority: number
  is_active: boolean
}

export interface RuleExportPayload {
  format: 'securo-categorization-rules'
  version: number
  rules: RuleExportItem[]
}

export interface RuleImportResponse {
  imported: number
  skipped: number
  overwritten: number
}

/** One matched transaction in a rule preview, with the category the draft rule
 * would leave it in. `will_change` is false when the rule matches but changes
 * nothing — usually a transaction that already has a category the draft keeps. */
export interface RulePreviewItem {
  id: string
  date: string
  description: string
  amount: number
  currency: string
  type: 'debit' | 'credit'
  current_category_id: string | null
  current_category_name: string | null
  new_category_id: string | null
  new_category_name: string | null
  will_change: boolean
}

export interface RulePreviewResponse {
  matched: number
  will_change: number
  /** False when the draft's flags mean saving it changes nothing right now —
   * an inactive rule, or one not being applied to existing transactions. */
  will_apply: boolean
  /** One window of the matches, newest first: `offset` through
   * `offset + limit`. More remain while `offset + sample.length < matched`. */
  sample: RulePreviewItem[]
  offset: number
}

export interface ImportLog {
  id: string
  user_id: string
  /** Null for an order import, which lands on holdings rather than an account. */
  account_id: string | null
  account_name: string | null
  /** Currency of the totals; null when the import has no account. */
  account_currency: string | null
  entity: 'transactions' | 'asset_orders'
  filename: string
  format: string
  transaction_count: number
  total_credit: number
  total_debit: number
  created_at: string
}

export interface ImportPreviewTransaction {
  description: string
  amount: number
  date: string
  type: 'debit' | 'credit'
  external_id?: string | null
  currency?: string | null
  fx_rate?: number | null
  payee_raw?: string | null
  category_name?: string | null
  suggested_category_id?: string | null
  suggested_category_name?: string | null
  excluded?: boolean
  category_id?: string | null
  force_uncategorized?: boolean
  notes?: string | null
}

export interface ImportReviewTransaction extends ImportPreviewTransaction {
  _id: string
  excluded: boolean
  selected_category_id?: string | null
}

export interface FailedRow {
  line_number: number
  description: string
  raw_value: string
  error_reason: string
}

export interface RecurringTransaction {
  id: string
  user_id: string
  account_id: string | null
  category_id: string | null
  description: string
  amount: number
  currency: string
  type: 'debit' | 'credit'
  frequency: 'monthly' | 'quarterly' | 'semiannual' | 'weekly' | 'biweekly' | 'yearly'
  weekend_adjustment: 'none' | 'previous_friday' | 'next_monday'
  day_of_month: number | null
  start_date: string
  end_date: string | null
  is_active: boolean
  auto_generate: boolean
  next_occurrence: string
  amount_primary: number | null
  fx_rate_used: number | null
}

export interface ProjectedTransaction {
  recurring_id: string
  account_id: string | null
  description: string
  amount: number
  amount_primary: number | null
  currency: string
  type: 'debit' | 'credit'
  date: string
  category_id: string | null
  category_name: string | null
  category_icon: string | null
  category_color: string | null
  category_treat_as_transfer: boolean
}

export interface TransactionCalendarItem {
  kind: 'actual' | 'projected'
  id: string | null
  recurring_id: string | null
  date: string
  description: string
  amount: number
  amount_primary: number | null
  currency: string
  type: 'debit' | 'credit'
  account_id: string | null
  account_name: string | null
  category_id: string | null
  category_name: string | null
  category_icon: string | null
  category_color: string | null
  status: string | null
  source: string | null
  transfer_pair_id: string | null
  is_transfer: boolean
  is_ignored: boolean
  exclude_from_pnl: boolean
}

export interface TransactionCalendarDay {
  date: string
  in_month: boolean
  ending_balance: number
  // Combined totals kept for backwards compatibility.
  income: number
  expense: number
  transfer_net: number
  actual_income: number
  actual_expense: number
  actual_transfer_net: number
  projected_income: number
  projected_expense: number
  projected_transfer_net: number
  actual_count: number
  projected_count: number
  has_income: boolean
  has_expense: boolean
  has_transfer: boolean
  items: TransactionCalendarItem[]
}

export interface TransactionCalendarResponse {
  month: string
  currency: string
  account_ids: string[] | null
  days: TransactionCalendarDay[]
}

export interface DashboardSummary {
  total_balance: Record<string, number>
  total_balance_primary: number
  projected_balance: Record<string, number>
  projected_balance_primary: number
  balance_date: string
  monthly_income: number
  monthly_expenses: number
  monthly_income_primary: number
  monthly_expenses_primary: number
  projected_income?: number
  projected_expenses?: number
  projected_income_primary?: number
  projected_expenses_primary?: number
  accounts_count: number
  pending_categorization: number
  pending_categorization_amount: number
  assets_value: Record<string, number>
  assets_value_primary: number
  primary_currency: string
  // At least one currency bucket had no real FX rate, so the *_primary
  // totals sum it at 1:1 and are an estimate, not a conversion (issue #1165).
  fx_fallback?: boolean
  // Net pending balance from group splits in primary currency.
  // Negative = net liability, positive = net receivable. Already
  // accounts for partial settlements.
  pending_shares_net: number
}

export interface SpendingByCategory {
  category_id: string | null
  category_name: string
  category_icon: string
  category_color: string
  total: number
  projected_total: number
  percentage: number
}

export interface MonthlyTrend {
  month: string
  income: number
  expenses: number
}

export interface DailyBalance {
  day: number
  balance: number | null
}

export interface DailyBaseline {
  day: number
  median: number | null
  lower_quartile: number | null
  upper_quartile: number | null
}

/** End-of-day balance of one account, one point per day (#1202). */
export interface AccountRunningBalancePoint {
  date: string
  balance: number
  balance_primary: number | null
}

export interface BalanceHistory {
  current: DailyBalance[]
  opening_balance: number
  baseline: DailyBaseline[]
  comparison: DailyBalance[] | null
  comparison_month: string | null
  comparison_opening_balance: number | null
}

export interface Budget {
  id: string
  user_id: string
  category_id: string
  amount: number
  month: string
  is_recurring: boolean
}

export interface BudgetVsActual {
  category_id: string
  category_name: string
  category_icon: string
  category_color: string
  group_id: string | null
  group_name: string | null
  budget_amount: number | null
  actual_amount: number
  projected_amount: number
  prev_month_amount: number
  projected_prev_month_amount: number
  percentage_used: number | null
  is_recurring: boolean
}

export interface BudgetSuggestion {
  category_id: string
  category_name: string
  category_icon: string
  category_color: string
  group_id: string | null
  group_name: string | null
  suggested_amount: string
  total_spent: string
  months_with_data: number
  existing_budget: boolean
}

export interface BudgetSuggestionResponse {
  month: string
  months_requested: number
  months_analyzed: number
  suggestions: BudgetSuggestion[]
}

export interface Asset {
  id: string
  user_id: string
  name: string
  type: string
  currency: string
  units: number | null
  valuation_method: string
  purchase_date: string | null
  purchase_price: number | null
  sell_date: string | null
  sell_price: number | null
  growth_type: string | null
  growth_rate: number | null
  growth_frequency: string | null
  growth_start_date: string | null
  is_archived: boolean
  position: number
  current_value: number | null
  current_value_primary: number | null
  gain_loss: number | null
  gain_loss_primary: number | null
  value_count: number
  source: string
  connection_id: string | null
  isin: string | null
  maturity_date: string | null
  group_id: string | null
  ticker: string | null
  ticker_exchange: string | null
  last_price: number | null
  last_price_at: string | null
  logo_url: string | null
  // Ledger-derived (issue #235): weighted-average cost per unit (preço médio),
  // cost basis of held units, cumulative realized gain, and whether the holding
  // is driven by the transactions ledger.
  average_price: number | null
  total_invested: number | null
  realized_gain: number | null
  transaction_count: number
}

/** One order read from a broker CSV, before it reaches a holding. */
export interface AssetOrderImport {
  row: number
  ticker: string
  date: string
  kind: 'buy' | 'sell'
  quantity: number
  price: number
  fee: number
  currency: string | null
  name: string | null
  notes: string | null
  external_id: string | null
}

export interface AssetImportRowError {
  row: number
  reason: string
  ticker: string | null
  detail: string | null
}

export interface AssetImportWarning {
  ticker: string
  reason: string
  wallet: string | null
}

export interface AssetImportPreview {
  orders: AssetOrderImport[]
  errors: AssetImportRowError[]
  warnings: AssetImportWarning[]
  csv_columns: string[]
  parse_error: string | null
  holdings_created: number
  holdings_matched: number
  skipped: number
}

export interface AssetImportResult {
  imported: number
  skipped: number
  holdings_created: number
  holdings_matched: number
  errors: AssetImportRowError[]
  warnings: AssetImportWarning[]
}

export interface AssetTransaction {
  id: string
  asset_id: string
  kind: 'buy' | 'sell'
  quantity: number
  price: number
  fee: number
  date: string
  source: string
  notes: string | null
  asset_name: string | null
  ticker: string | null
  currency: string | null
  logo_url: string | null
}

export interface MarketSymbolMatch {
  symbol: string
  name: string | null
  exchange: string | null
  quote_type: string | null
}

export interface MarketSymbolQuote {
  symbol: string
  name: string | null
  exchange: string | null
  currency: string
  price: number
  quote_type: string | null
}

export interface AssetGroup {
  id: string
  user_id: string
  name: string
  icon: string
  color: string
  position: number
  source: string
  connection_id: string | null
  institution_name: string | null
  asset_count: number
  current_value: number
  current_value_primary: number
}

export interface AssetValue {
  id: string
  asset_id: string
  amount: number
  date: string
  source: string
}

export interface Goal {
  id: string
  user_id: string
  name: string
  target_amount: number
  current_amount: number
  currency: string
  target_amount_primary: number | null
  current_amount_primary: number | null
  target_date: string | null
  tracking_type: 'manual' | 'account' | 'asset' | 'asset_group' | 'net_worth'
  account_id: string | null
  asset_id: string | null
  asset_group_id: string | null
  status: 'active' | 'completed' | 'paused' | 'archived'
  icon: string | null
  color: string | null
  position: number
  metadata_json: Record<string, unknown> | null
  created_at: string
  updated_at: string
  percentage: number
  monthly_contribution: number | null
  on_track: 'ahead' | 'on_track' | 'behind' | 'overdue' | 'achieved' | null
  account_name: string | null
  asset_name: string | null
  asset_group_name: string | null
}

export interface GoalSummary {
  id: string
  name: string
  target_amount: number
  current_amount: number
  currency: string
  target_date: string | null
  status: string
  icon: string | null
  color: string | null
  percentage: number
  monthly_contribution: number | null
  on_track: string | null
}

export interface PaginatedResponse<T> {
  items: T[]
  total: number
  page: number
  limit: number
}

// Income / expense / net totals for all transactions matching the active
// filters (issue #185) — accompanies the paginated /transactions response.
export interface TransactionsSummary {
  income: number
  expense: number
  net: number
  // Absolute total of everything excluded from income/expense for the same
  // rows — transfers, treat_as_transfer categories and ignored items (#242).
  excluded: number
  currency: string
}

export interface PaginatedTransactions extends PaginatedResponse<Transaction> {
  summary?: TransactionsSummary
}

// Reports (universal schema for all report types)
export interface ReportBreakdown {
  key: string
  label: string
  value: number
  color: string
}

export interface ReportSummary {
  primary_value: number
  change_amount: number
  change_percent: number | null
  breakdowns: ReportBreakdown[]
}

export interface ReportDataPoint {
  date: string
  value: number
  breakdowns: Record<string, number>
  change: number | null
  composition?: ReportCompositionItem[]
}

export interface ReportMeta {
  type: string
  series_keys: string[]
  currency: string
  interval: string
  forecast_start_date?: string | null
  baseline_active?: boolean
  baseline_lookback_days?: number | null
  runway_date?: string | null
  lowest_balance?: number | null
  lowest_balance_date?: string | null
}

export interface ReportCompositionItem {
  key: string
  label: string
  value: number
  color: string
  group: string
}

export interface CategoryTrendItem {
  key: string
  label: string
  color: string
  total: number
  group: string
  series: ReportDataPoint[]
}

export interface Attachment {
  id: string
  transaction_id: string
  filename: string
  content_type: string
  size: number
  created_at: string
}

export interface ReportResponse {
  summary: ReportSummary
  trend: ReportDataPoint[]
  meta: ReportMeta
  composition: ReportCompositionItem[]
  category_trend: CategoryTrendItem[]
}

// --- Invoices -------------------------------------------------------------
// The ledger of what clients owe. Only reachable from a business
// workspace: the module resolver leaves `invoices` out of a personal
// workspace's `enabled_modules`, so nothing below is ever fetched there.

/** A decision a human took. Never PATCHed directly — each one has its own
 *  endpoint, because a status that changed always has a reason. */
export type InvoiceStatus = 'draft' | 'open' | 'void' | 'uncollectible'

/** Which side of the ledger a document sits on. Everything the UI writes
 *  today is a receivable; `payable` exists so supplier documents have
 *  somewhere to land without a migration when that path arrives. */
export type InvoiceDirection = 'receivable' | 'payable'

/** What the UI renders. The three terminal decisions above, plus the four
 *  facts the server computes from allocations and the due date. Nothing
 *  here is stored in a column. */
export type InvoiceState =
  | 'draft'
  | 'open'
  | 'partial'
  | 'paid'
  | 'overdue'
  | 'void'
  | 'uncollectible'

export interface InvoiceLine {
  id: string
  /** Where the line came from, when it came from the catalog. The
   *  values below are still the line's own copy. */
  product_id: string | null
  price_id: string | null
  fiscal_refs: Record<string, string> | null
  description: string
  quantity: string
  unit: string | null
  unit_price: string
  tax_rate: string | null
  total: string
  position: number
}

export interface InvoiceLineInput {
  description: string
  quantity: string
  /** What the quantity counts — hours, words, pieces. Free text, because
   *  a list here would be a guess about somebody else's trade. */
  unit?: string | null
  unit_price: string
  tax_rate?: string | null
  /** Set when the line was filled from a product. Kept when the person
   *  then edits the values: it is still that product, at their price. */
  product_id?: string | null
  price_id?: string | null
  /** Fiscal references for the line. Filled from the product by the
   *  server when omitted. */
  fiscal_refs?: Record<string, string> | null
}

// ---------------------------------------------------------------------------
// Catalog
// ---------------------------------------------------------------------------

export type ProductKind = 'service' | 'product'
export type PriceBilling = 'one_time' | 'recurring'

export interface ProductPrice {
  id: string
  product_id: string
  currency: string
  unit_price: string
  tax_rate: string | null
  billing: PriceBilling
  interval: InvoiceScheduleFrequency | null
  nickname: string | null
  /** A name of the workspace's own choosing, unique among its prices. */
  lookup_key: string | null
  active: boolean
  external_source: string | null
  external_id: string | null
  created_at: string
}

/** A fiscal reference the workspace's jurisdiction suggests on a product. */
export interface ProductFieldSpec {
  key: string
  label_key: string
  /** Which product kinds it applies to; empty means both. */
  kinds: ProductKind[]
}

export interface Product {
  id: string
  name: string
  description: string | null
  kind: ProductKind
  unit: string | null
  active: boolean
  origin: string
  external_source: string | null
  external_id: string | null
  custom_fields: Record<string, string> | null
  /** Fiscal references keyed as the jurisdiction suggests (`ncm`,
   *  `service_code`, `hs_code`...); any key is accepted. */
  fiscal_refs: Record<string, string> | null
  prices: ProductPrice[]
  created_at: string
  /** Derived by the server: how many invoices name this product. */
  invoice_count: number
}

export interface InstallmentInput {
  due_date: string
  amount: string
  label?: string | null
}

export type InstallmentState = 'open' | 'partial' | 'paid' | 'overdue' | 'draft' | 'void' | 'uncollectible'

export interface InvoiceInstallment {
  id: string
  position: number
  label: string | null
  due_date: string
  amount: string
  /** Derived: how much of it the settled money covers, first-to-last. */
  settled: string
  state: InstallmentState
}

export type DeductionKind = 'withholding_tax' | 'gateway_fee' | 'fx_difference' | 'other'

/** Debt closed without money: tax withheld, a fee kept. Counts towards
 *  settled, never towards received. */
export interface InvoiceDeduction {
  id: string
  kind: DeductionKind
  tax_kind: string | null
  amount: string
  note: string | null
  transaction_id: string | null
  deducted_at: string
}

export interface InvoiceAllocation {
  id: string
  transaction_id: string | null
  credit_note_id: string | null
  amount: string
  method: string
  allocated_at: string
  transaction: {
    id: string
    description: string | null
    date: string | null
    amount: string | null
  } | null
}

/** What a filed document proves. Roles, not file types — a nota fiscal,
 *  a facture and a Rechnung are all `fiscal`, and each locale names it. */
export type InvoiceAttachmentKind = 'bill' | 'fiscal' | 'receipt' | 'contract' | 'other'

export interface InvoiceAttachment {
  id: string
  invoice_id: string
  /** The system that produced or delivered the file — a payment
   *  provider, a fiscal-document integration, a mailbox. Null when a
   *  person uploaded it here. */
  source: string | null
  /** Its id in that system, when it has one. */
  external_id: string | null
  kind: InvoiceAttachmentKind
  /** True on the one file that *is* the document. Downloading the invoice
   *  hands this file over instead of a page drawn from our own fields. */
  is_primary: boolean
  document_number: string | null
  issued_at: string | null
  filename: string
  content_type: string
  size: number
  created_at: string
}

export interface Invoice {
  id: string
  payee_id: string | null
  payee: { id: string; name: string } | null
  document_type: string
  direction: InvoiceDirection
  origin: string
  external_source: string | null
  external_id: string | null
  number: number | null
  series: string | null
  /** The name an imported document arrived with, reproduced verbatim.
   *  Null on anything we wrote, which our own counter names instead. */
  external_number: string | null
  status: InvoiceStatus
  state: InvoiceState
  issue_date: string
  due_date: string
  /** The accrual date — competência / fait générateur / Leistungsdatum.
   *  Defaults to `issue_date` and diverges when work was delivered in a
   *  different period from the one it was billed in. */
  competence_date: string | null
  sent_at: string | null
  currency: string
  subtotal: string
  discount: string
  tax_total: string
  total: string
  amount_paid: string
  /** Settled without cash. Not part of `amount_paid`. */
  amount_deducted: string
  balance: string
  days_overdue: number
  /** The next date money is late after; null once nothing is owed. */
  next_due_date: string | null
  notes: string | null
  internal_notes: string | null
  custom_fields: Record<string, string> | null
  /** Frozen at issuance: issuer, counterparty and labels as they were.
   *  Rendered instead of live settings so changing a logo never rewrites
   *  a document the client already received.
   *
   *  `unknown` rather than `any`: the shape is the server's and it grows
   *  (locale and payment details joined it after the first version), so
   *  every reader asserts the one field it wants instead of the type
   *  quietly promising all of them. */
  snapshot: Record<string, unknown> | null
  /** Present once a shareable link exists. Null until someone asks for
   *  one, and null again once revoked. */
  share_token: string | null
  /** Which agreement and period this invoice answers for, when it was
   *  born from or linked to one. Provenance only: nothing about the
   *  money reads these. */
  schedule_id: string | null
  schedule: { id: string; name: string; frequency: InvoiceScheduleFrequency; status: InvoiceScheduleStatus } | null
  sequence: number | null
  period_start: string | null
  period_end: string | null
  lines: InvoiceLine[]
  allocations: InvoiceAllocation[]
  installments: InvoiceInstallment[]
  deductions: InvoiceDeduction[]
  created_at: string
}

// ---------------------------------------------------------------------------
// Recurring invoices
// ---------------------------------------------------------------------------

/** Decisions a person took about an agreement. `past_due` is not one of
 *  them: it is derived from the agreement's invoices. */
export type InvoiceScheduleStatus = 'active' | 'paused' | 'ended'
export type InvoiceScheduleFrequency =
  | 'weekly'
  | 'biweekly'
  | 'monthly'
  | 'quarterly'
  | 'semiannual'
  | 'yearly'
export type InvoiceScheduleEndType = 'never' | 'on_date' | 'after_count'
export type InvoiceScheduleEndReason =
  | 'canceled_by_client'
  | 'canceled_by_us'
  | 'completed'
  | 'unpaid'
  | 'other'

/** What the agreement says from a date on. One row per price change. */
export interface InvoiceScheduleTerm {
  id: string
  effective_from: string
  lines: InvoiceLineInput[]
  discount: string
  subtotal: string
  tax_total: string
  total: string
  created_at: string
}

export interface InvoiceSchedule {
  id: string
  name: string
  payee_id: string | null
  payee: { id: string; name: string } | null
  origin: string
  external_source: string | null
  external_id: string | null
  status: InvoiceScheduleStatus
  pause_reason: 'manual' | 'failures' | null
  ended_at: string | null
  end_reason: InvoiceScheduleEndReason | null
  frequency: InvoiceScheduleFrequency
  start_date: string
  end_type: InvoiceScheduleEndType
  end_date: string | null
  end_count: number | null
  payment_terms_days: number | null
  currency: string
  notes: string | null
  custom_fields: Record<string, string> | null
  next_sequence: number
  last_generated_at: string | null
  consecutive_failures: number
  terms: InvoiceScheduleTerm[]
  created_at: string
  /** Derived by the server on every read; never stored. */
  current_term: InvoiceScheduleTerm | null
  next_term: InvoiceScheduleTerm | null
  monthly_amount: string
  next_period_start: string | null
  invoice_count: number
  amount_invoiced: string
  amount_paid: string
  past_due_count: number
}

export interface InvoiceScheduleCurrencySummary {
  currency: string
  monthly_recurring: string
  active_count: number
  ended_recently_count: number
  monthly_lost: string
  past_due_count: number
}

export interface InvoiceScheduleSummary {
  active_count: number
  paused_count: number
  ended_count: number
  by_currency: InvoiceScheduleCurrencySummary[]
}

export interface InvoiceSchedulePeriod {
  sequence: number
  period_start: string
  period_end: string
  taken: boolean
}

export interface InvoiceAgingBuckets {
  current: string
  d1_30: string
  d31_60: string
  d61_90: string
  d90_plus: string
}

export interface InvoiceSummary {
  outstanding: string
  overdue_amount: string
  overdue_count: number
  received_this_month: string
  buckets: InvoiceAgingBuckets
  upcoming: Invoice[]
}

export interface InvoiceCustomFieldDef {
  key: string
  label: string
  required?: boolean
}

export interface InvoiceTemplate {
  /** Overrides only. Anything left out falls back to the pack for the
   *  issuer's language, resolved server-side. */
  labels?: Record<string, string>
  custom_fields?: InvoiceCustomFieldDef[]
}

export interface InvoiceSettings {
  /** A starting point that fills the next three fields, not a mode: each
   *  one stays individually overridable afterwards. */
  preset: 'tracking' | 'document'
  document_required: boolean
  initial_state: 'draft' | 'open'
  tax_fields: 'hidden' | 'optional' | 'required'
  default_payment_terms_days: number
  number_prefix: string | null
  series: string | null
  next_number: number
  /** The uploaded mark, addressed by an id that never changes for a
   *  given file. Null when none was uploaded. */
  logo_id: string | null
  issuer_display_name: string | null
  footer_note: string | null
  /** Free text: a Pix key, an IBAN, a routing number. Shown on the
   *  document; never parsed. */
  payment_details: string | null
  accent_color: string | null
  template: InvoiceTemplate | null
}

/** The invoice resolved into a document: what the PDF prints and what the
 *  preview shows, from one definition on the server. Nothing here is
 *  recomputed on this side — a second implementation is how the two
 *  would come to disagree. */
export interface InvoiceDocumentParty {
  name: string | null
  legal_name?: string | null
  address: string | null
  email?: string | null
  /** Already masked server-side, because the PDF has no frontend to ask. */
  tax_ids: { label: string; value: string }[]
}

export interface InvoiceDocumentLine {
  description: string
  quantity: string
  unit: string | null
  unit_price: string
  total: string
  tax_rate: string | null
}

export interface InvoiceDocumentPayload {
  number: string | null
  status: InvoiceStatus
  state: InvoiceState
  issue_date: string
  due_date: string
  currency: string
  subtotal: string
  discount: string
  tax_total: string
  total: string
  amount_paid: string
  /** Settled without money arriving: tax withheld, a fee kept. */
  amount_deducted: string
  balance: string
  issuer: InvoiceDocumentParty
  client: InvoiceDocumentParty
  lines: InvoiceDocumentLine[]
  labels: Record<string, string>
  accent_color: string
  logo_url: string | null
  payment_details: string | null
  notes: string | null
  footer_note: string | null
  custom_fields: { label: string; value: string }[]
  /** On a payable the parties are already swapped server-side; this is
   *  carried so the page can say "received" instead of "issued". */
  direction: InvoiceDirection
  /** False when the invoice is only tracking money — the common case
   *  where the fiscal document was issued somewhere else entirely. */
  has_line_items: boolean
  /** Set when a real document was filed under this invoice. When it is,
   *  that file is the document and the page below is only a summary of
   *  it — nothing here needs redrawing. */
  source_file: { id: string; filename: string; content_type: string } | null
  /** The dates the money is expected on, when more than one. */
  installments: { label: string | null; due_date: string; amount: string }[]
}

export interface IssuerTaxId {
  kind: string
  value: string
}

export interface IssuerProfile {
  legal_name: string | null
  address: string | null
  tax_jurisdiction: string | null
  tax_ids: IssuerTaxId[]
}

export interface InvoiceShareLink {
  token: string
  /** A path, not a URL: only the browser reliably knows the public origin. */
  path: string
}

/** What the filter bar needs to render itself: which years have
 *  invoices, and how many sit in each state for the selected year. */
export interface InvoiceFacets {
  years: number[]
  counts: {
    all: number
    open: number
    overdue: number
    paid: number
    draft: number
  }
}

// ---------------------------------------------------------------------------
// Reconciliation
// ---------------------------------------------------------------------------

/** The signals matching consults, as the API sends them.
 *
 *  Deliberately not an open-ended condition tree like the categorization
 *  rules: matching runs on a fixed set of signals, and a form over exactly
 *  those is honest about what the engine can actually look at. */
/** Which moment a rule runs at.
 *
 *  `money_arrives`: a payment lands and we look for the promise it
 *  answers; the promise came first and was waiting.
 *  `invoice_issued`: a document is written and we look back at money that
 *  arrived before it existed, the client who pays and lets the nota
 *  follow. Weaker evidence: that money already had a life of its own.
 *  `both`: the rule trusts either. */
export type Trigger = 'money_arrives' | 'invoice_issued' | 'both'

export interface ReconciliationConditions {
  // -- Which money the rule is written for. Every one of these decides
  //    whether the rule is consulted at all, before any comparison. Absent
  //    means "no limit", never "none".
  /** Only money in these bank accounts. */
  accounts?: { in: string[] }
  /** Only money from these clients. Different from `counterparty`, which
   *  asks whether the payer is the one named on the invoice. */
  payees?: { in: string[] }
  /** Only money coming in, or only money going out. */
  direction?: 'any' | 'credit' | 'debit'
  /** What the statement line has to say, or must not. Case-insensitive. */
  /** One word, or several meaning *any of them*. Stored as written, so a
   *  rule naming one gateway stays a string and does not read as changed. */
  text?: { contains?: string | string[]; not_contains?: string | string[] }

  // -- How closely the pair has to fit.
  counterparty?: 'any' | 'same_payee'
  amount?: {
    /** `partial` is what makes two transactions on one invoice reachable:
     *  every other mode compares against the whole outstanding balance,
     *  and half of it is simply not that. */
    match: 'exact' | 'tolerance' | 'ratio' | 'partial' | 'set'
    percent?: string
    /** For `set`: how many invoices one payment may cover. */
    max_invoices?: number
    epsilon?: string
    ratios?: string
    difference_kind?: string
    /** For `partial`: the smallest fraction of the balance worth
     *  offering, so a token payment is not proposed as an instalment. */
    min_ratio?: string
    /** For `partial`: the largest, above which the gap is a fee or a
     *  withholding rather than an instalment. */
    max_ratio?: string
    /** Bounds on the movement itself, not on how close it is to the
     *  promise: "never link anything over ten thousand on its own". */
    min?: string
    max?: string
  }
  /** Asymmetric on purpose: late is measured from the due date, early from
   *  the day the promise was written. */
  date?: { before_days: number; after_days: number }
  description_similarity?: { min: string }
  currency?: {
    /** Whether a movement may settle a promise held in another currency. */
    conversion: 'reject' | 'allow'
    /** Only these currency codes. */
    in?: string[]
    /** Only currencies other than the workspace's own: what somebody
     *  means by "check anything that is not in our money". */
    foreign?: boolean
  }
  same_account?: boolean
  /** The defining condition of a transfer: the two legs are on different
   *  accounts. The inverse of `same_account`, and its own key so a rule
   *  reads as a list of things that must be true. */
  different_account?: boolean
  /** Only pairs where one of the two legs sits on an account of this
   *  kind. Either leg is enough: a rule that exists to be careful about
   *  credit cards has to fire whichever end the card is on. */
  account_types?: AccountType[]
  /** One side's statement text has to name the other side's account. The
   *  signal that tells two same-day transfers of the same amount apart,
   *  when one line reads "To FORTUNEO ACCOUNT" and the other does not. */
  account_name_in_description?: boolean
  /** How to separate candidates that all fit. `closest_date` takes the
   *  nearest in time and only gives up when nothing separates them, which
   *  is different from `unique_candidate` refusing whenever there is more
   *  than one. */
  tie_break?: 'closest_date'
  unique_candidate?: boolean
}

export interface ReconciliationRule {
  id: string
  node: string
  /** Set only for a rule the workspace wrote. A shipped rule keeps its
   *  translated name, which would otherwise freeze in one language the day
   *  somebody edited a threshold. */
  name?: string | null
  origin: 'default' | 'custom'
  /** Whether this workspace departed from what we ship. Drives the "you
   *  changed this" mark and the offer to put it back. */
  customised: boolean
  enabled: boolean
  outcome: 'link' | 'suggest'
  trigger: Trigger
  when: ReconciliationConditions
  position: number
}

export interface ReconciliationNode {
  node: string
  /** Whether the set is reachable for this workspace at all. The invoice
   *  rules mean nothing where the module is off. */
  active: boolean
  rules: ReconciliationRule[]
  /** Rules we ship that this workspace threw away. Sent so the page can
   *  offer them back: a shipped rule leaves a tombstone rather than a
   *  hole, so we still know its name, and without this the delete is a
   *  trap, because the row is gone and there is nothing left to click. */
  discarded: { id: string; node: string }[]
}

/** A matching policy as a file. Ids are resolved to names on the way out
 *  and looked up again on the way in: a UUID means nothing in another
 *  database. */
export interface ReconciliationPolicyFile {
  format: string
  version: number
  policy_version: number
  nodes: {
    node: string
    rules: {
      id: string
      origin: string
      name: string | null
      enabled: boolean
      outcome: string
      trigger: string
      when: Record<string, unknown>
    }[]
    discarded: string[]
  }[]
}

export interface ReconciliationRulePatch {
  enabled?: boolean
  outcome?: 'link' | 'suggest'
  trigger?: Trigger
  when?: ReconciliationConditions
  position?: number
}

export interface ReconciliationRuleDraft {
  node: string
  name: string
  outcome: 'link' | 'suggest'
  trigger?: Trigger
  when: ReconciliationConditions
  enabled?: boolean
  position?: number | null
}

/** One match the engine was not confident enough to make on its own.
 *
 *  `scores` is a per-signal breakdown rather than one number: "78% sure" is
 *  not something anyone can check, while "the amount is exact and the date
 *  is four days out" tells a person exactly where to look. */
export interface ReconciliationSuggestion {
  id: string
  node: string
  strategy_id: string
  expectation_kind: 'invoice' | 'recurring' | 'transaction'
  expectation_id: string
  expectation_label?: string | null
  amount: string
  scores: {
    strategy?: string
    description?: number
    amount_expected?: string
    amount_moved?: string
    amount_exact?: boolean
    days_apart?: number
    same_counterparty?: boolean
    currency?: string
  }
  status: 'pending' | 'accepted' | 'declined' | 'expired'
  created_at: string
  /** Everything this one question covers. A single entry for the ordinary
   *  case; several when one payment is offered against several invoices,
   *  which is answered whole or not at all. */
  covers: {
    expectation_kind: 'invoice' | 'recurring' | 'transaction'
    expectation_id: string
    label?: string | null
    amount: string
  }[]
  transaction?: {
    id: string
    description?: string | null
    amount: string
    currency?: string | null
    date: string
    type: string
    /** Which account the money moved on. With transfers in the queue the
     *  question is about accounts, so a row naming only the other side
     *  leaves the reader to work out which of theirs this one is. */
    account_id?: string | null
  } | null
}

/** One thing matching did.
 *
 *  `linked` means the rules did it on their own; `accepted` means a person
 *  did, by answering a question. They are never both written for one act:
 *  the allocation an acceptance produces is its consequence, not a second
 *  event, because the whole stream is organised around that one line. */
export interface ReconciliationHistoryEvent {
  id: string
  at: string
  action: 'linked' | 'suggested' | 'accepted' | 'declined' | 'expired' | 'unlinked'
  expectation_kind: 'invoice' | 'recurring' | 'transaction'
  expectation_id: string
  expectation_label?: string | null
  amount: string
  /** What `amount` is denominated in, resolved from the promise. */
  currency?: string | null
  strategy_id?: string | null
  /** Null means the rules acted on their own. */
  user_id?: string | null
  transaction_id?: string | null
  transaction_description?: string | null
}

export type LoanKind = 'mortgage' | 'auto' | 'personal' | 'student' | 'other'
export type LoanRatePeriod = 'monthly' | 'yearly_effective' | 'yearly_nominal'
export type LoanAmortization = 'price' | 'sac'

export interface LoanInstallment {
  number: number
  due_date: string
  payment: number
  interest: number
  principal: number
  balance: number
}

/** The lender's balance on a date, sent to bring a loan's ledger in line. */
export interface LoanBalanceUpdate {
  balance: number
  date: string
  description: string
  category_id?: string | null
}

/** What the backend recorded: positive when the debt grew, 0 when it already matched. */
export interface LoanBalanceAdjustment {
  adjustment: number
  current_debt: number
  transaction_id: string | null
}

/** A loan's payment schedule, computed by the backend from its contract terms. */
export interface LoanSchedule {
  account_id: string
  currency: string
  current_debt: number
  configured: boolean
  missing: string[]
  monthly_payment: number | null
  payments_due: number | null
  remaining_payments: number | null
  next_payment: LoanInstallment | null
  scheduled_balance: number | null
  ahead_by: number | null
  total_interest: number | null
  total_paid: number | null
  payoff_date: string | null
  projected_payoff_date: string | null
  paid_off: boolean
  installments: LoanInstallment[]
}