Skip to content
calternal docs

calternal_plugin_money::views

API shapes for Money and the functions that build them from a ledger.

Every amount is an integer in minor units of the named currency, with its scale (ISO 4217 exponent) beside it, so a client formats it for the User’s locale without floating point (DESIGN §48: the UI formats amounts). |amount| <= 2^53 - 1 always holds (see calternal_money::units), so the integers are exact in JavaScript.

The UI only ever sees these shapes; only the codec knows the file syntax (#462: “the UI talks only to the Money API”).

Source: crates/plugins/money/src/views.rs

Structs

Section titled “Structs”

AccountList

Section titled “AccountList”
pub struct AccountList

Accounts of a budget with totals.

Fields

  • pub budget_id: String: Budget ID.
  • pub currency: String: Budget currency.
  • pub scale: u32: Decimal places of currency.
  • pub on_budget_total: i64: Sum of on-budget balances.
  • pub tracking_total: i64: Sum of tracking balances.
  • pub accounts: Vec<AccountView>: Accounts in file order.

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:197

AccountView

Section titled “AccountView”
pub struct AccountView

One account with its balances in budget minor units.

Fields

  • pub closed: bool: Closed accounts remain available through history and deep links (#1130).
  • pub id: String: Account ID.
  • pub name: String: Display name.
  • pub kind: String: cash, card or tracking.
  • pub currency: String: Account currency.
  • pub on_budget: bool: False for Tracking accounts.
  • pub balance: i64: Balance of every recorded row.
  • pub cleared_balance: i64: Balance of cleared rows.
  • pub uncleared_balance: i64: Balance of uncleared rows.
  • pub payment_category_id: Option<String>: For a Card account: its payment Category.
  • pub debt_not_covered: Option<i64>: For a Card account: debt its payment reserve does not cover.

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:169

AssignInput

Section titled “AssignInput”
pub struct AssignInput

Set the total assigned to a category in a month.

Fields

  • pub amount: i64: Minor units; may be negative.

Implements: Deserialize, ToSchema

Source: crates/plugins/money/src/views.rs:148

BudgetSummary

Section titled “BudgetSummary”
pub struct BudgetSummary

One budget folder in the User’s Money/ folder.

Fields

  • pub id: String: Stable budget ID (budget-id in the frontmatter).
  • pub name: String: Display name (the # title of Budget.md).
  • pub currency: String: Budget currency, ISO 4217.
  • pub scale: u32: Decimal places of currency.
  • pub folder: String: Folder name under Money/.
  • pub problem: Option<String>: Why the files cannot be posted, when they are broken.

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:24

CategoryCreated

Section titled “CategoryCreated”
pub struct CategoryCreated

A created category.

Fields

  • pub id: String: Category ID.
  • pub name: String: Display name.
  • pub group: String: Group name.

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:241

CategoryView

Section titled “CategoryView”
pub struct CategoryView

A category’s numbers in one month.

Fields

  • pub id: String: Category ID.
  • pub name: String: Display name.
  • pub kind: String: expense or payment (a Card payment Category).
  • pub hidden: bool: True when visibility:: is not visible.
  • pub assigned: i64: Assigned in this month.
  • pub activity: i64: Activity in this month.
  • pub available: i64: Available at the end of this month.
  • pub state: String: available, funded, overspent, underfunded or funded_ahead.
  • pub state_label: String: The funding label for the state, for example Funded for next 2 months.
  • pub target: Option<i64>: Monthly target, if any.
  • pub months_funded: Option<i64>: Full target months covered by Available.
  • pub target_remainder: Option<i64>: Available beyond the full target months.
  • pub card_account_id: Option<String>: For a payment Category, the Card account it pays.

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:53

ClearedInput

Section titled “ClearedInput”
pub struct ClearedInput

Set a row’s cleared flag.

Fields

  • pub account_id: Option<String>: Select a transfer leg; absent means the primary Account (#1130).
  • pub cleared: bool: New cleared state.

Implements: Deserialize, ToSchema

Source: crates/plugins/money/src/views.rs:400

CreateAccount

Section titled “CreateAccount”
pub struct CreateAccount

Create an account (and, for a Card account, its payment Category).

Fields

  • pub name: String: Display name.
  • pub kind: String: cash, card or tracking.
  • pub opening_balance: Option<i64>: Opening balance in minor units (a Card account’s debt is negative).
  • pub opening_date: Option<String>: Date of the opening balance YYYY-MM-DD (required with a balance).

Implements: Deserialize, ToSchema

Source: crates/plugins/money/src/views.rs:216

CreateBudget

Section titled “CreateBudget”
pub struct CreateBudget

Create a budget: Money/<name>/ with Budget.md and Accounts.md.

Fields

  • pub name: String: Budget name; also the folder name.
  • pub currency: String: Budget currency, ISO 4217 (for example EUR).

Implements: Deserialize, ToSchema

Source: crates/plugins/money/src/views.rs:43

CreateCategory

Section titled “CreateCategory”
pub struct CreateCategory

Create an expense category in a group (the group is created if needed).

Fields

  • pub group: String: Group name.
  • pub name: String: Category name.

Implements: Deserialize, ToSchema

Source: crates/plugins/money/src/views.rs:231

GroupView

Section titled “GroupView”
pub struct GroupView

A category group (a ## heading) with its categories and totals.

Fields

  • pub name: String: Group name.
  • pub assigned: i64: Sum of Assigned.
  • pub activity: i64: Sum of Activity.
  • pub available: i64: Sum of Available.
  • pub categories: Vec<CategoryView>: Categories in file order.

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:85

InflowCategory

Section titled “InflowCategory”
pub struct InflowCategory

A category whose inflows go to Ready to Assign.

Fields

  • pub id: String: Category ID.
  • pub name: String: Display name.

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:137

MonthView

Section titled “MonthView”
pub struct MonthView

The budget table for one month.

Fields

  • pub budget_id: String: Budget ID.
  • pub budget_name: String: Budget name.
  • pub month: String: Month YYYY-MM.
  • pub revision: u64: Ordered source generation; file replacements also advance it. Clients keep the greatest (#984).
  • pub currency: String: Budget currency.
  • pub scale: u32: Decimal places of currency.
  • pub ready_to_assign: i64: Ready to Assign at the end of the month.
  • pub ready_label: String: Ready to Assign, or Assigned more than you have below zero.
  • pub assigned: i64: Sum of Assigned over all shown categories.
  • pub activity: i64: Sum of Activity over all shown categories.
  • pub available: i64: Sum of Available over all shown categories.
  • pub overspent_count: u32: Categories that are overspent or underfunded.
  • pub groups: Vec<GroupView>: Groups in file order (expense and payment categories only).
  • pub inflow_categories: Vec<InflowCategory>: Income and opening-balance categories: a transaction in one of them adds to Ready to Assign (the “Inflow: Ready to Assign” Category; DESIGN §48; #931).

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:101

MoveInput

Section titled “MoveInput”
pub struct MoveInput

Move assigned money from one category to another in a month.

Fields

  • pub from_category_id: String: Category that gives the money.
  • pub to_category_id: String: Category that receives it.
  • pub amount: i64: Minor units, greater than zero.

Implements: Deserialize, ToSchema

Source: crates/plugins/money/src/views.rs:157

SourceRowView

Section titled “SourceRowView”
pub struct SourceRowView

Typed source evidence for split, transfer and Tracking rows (#1130). The API crate owns its schema; the pure Money crate has no HTTP dependency. Evidence records never create additional postings.

Fields

  • pub id: String: Original export identity.
  • pub date: String: Original date in YYYY-MM-DD form.
  • pub amount: i64: Original amount in budget minor units.
  • pub account_id: String: Stable Money Account identity.
  • pub category_id: Option<String>: Stable Money Category identity, when the source had one.
  • pub payee: String: Original Payee, flattened for a Markdown row.
  • pub notes: String: Original Notes, including whitespace.
  • pub cleared: bool: Independent source cleared mark.
  • pub reconciled: bool: Independent source reconciled mark.

Implements: Serialize, ToSchema, From<&calternal_money::import::SourceRow>

Source: crates/plugins/money/src/views.rs:267

SplitView

Section titled “SplitView”
pub struct SplitView

One split leg of a transaction.

Fields

  • pub category_id: String: Category ID.
  • pub category_name: String: Category name.
  • pub amount: i64: Amount in budget minor units.

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:253

TransactionInput

Section titled “TransactionInput”
pub struct TransactionInput

Create or replace a simple transaction (one account, one category).

Fields

  • pub notes: Option<String>: Separate notes; omitted on an edit to preserve existing notes (#1130).
  • pub date: String: Date YYYY-MM-DD.
  • pub amount: i64: Minor units: outflow negative, inflow positive.
  • pub account_id: String: Account ID (in the budget currency).
  • pub category_id: String: Expense, income or opening-balance category ID.
  • pub payee: String: Payee text; transaction Notes use their own field (#1130).
  • pub cleared: Option<bool>: Cleared flag (#cleared); defaults to false.

Implements: Deserialize, ToSchema

Source: crates/plugins/money/src/views.rs:379

TransactionList

Section titled “TransactionList”
pub struct TransactionList

Register rows, newest first.

Fields

  • pub budget_id: String: Budget ID.
  • pub currency: String: Budget currency.
  • pub scale: u32: Decimal places of the budget currency.
  • pub transactions: Vec<TransactionView>: Rows sorted by date, newest first; same-date rows in reverse file order.

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:364

TransactionView

Section titled “TransactionView”
pub struct TransactionView

One register row.

Fields

  • pub notes: String: Separate notes, with original whitespace (#1130).
  • pub reconciled: bool: True when this source row was reconciled (#1130).
  • pub source_rows: Vec<SourceRowView>: Original source rows, retained without extra postings (#1130).
  • pub id: String: Transaction ID (the row’s ^block-id).
  • pub date: String: Date YYYY-MM-DD.
  • pub account_id: String: Account whose register shows this row.
  • pub account_name: String: Account name.
  • pub category_id: String: Category ID (a Split or Transfer marker for those rows).
  • pub category_name: String: Category name.
  • pub payee: String: Payee text exactly as written (with its tags); Notes are separate (#1130).
  • pub memo: String: Payee text without tag tokens, for display next to tags.
  • pub tags: Vec<String>: Inline calternal tags in the Payee, in order, without #cleared (the cleared flag has its own column). Parsed by the Notes tag grammar so a Money tag is the same tag everywhere (DESIGN §48: ordinary tags).
  • pub cleared: bool: This Account’s cleared mark; explicit source state overrides legacy #cleared tags and remains independent of reconciled state (#1130).
  • pub amount: i64: Amount in currency minor units, as seen by account_id.
  • pub currency: String: Currency of amount.
  • pub scale: u32: Decimal places of currency.
  • pub budget_amount: i64: Amount in budget minor units.
  • pub kind: String: simple, split, transfer or card_payment.
  • pub transfer_account_id: Option<String>: The other Account of a transfer or Card payment.
  • pub transfer_category_id: Option<String>: Category posted by a transfer between on-budget and off-budget accounts.
  • pub transfer_category_name: Option<String>: Display name for transfer_category_id.
  • pub splits: Vec<SplitView>: Split legs.
  • pub editable: bool: True when this build can edit the row (simple, unreconciled rows only; #462, #1130).

Implements: Serialize, ToSchema

Source: crates/plugins/money/src/views.rs:308

Functions

Section titled “Functions”

account_list

Section titled “account_list”
pub fn account_list(ledger: &Ledger, totals: Option<&MonthTotals>) -> Result<AccountList>

Accounts with balances. totals is the last replayed month (or None for a budget without data).

Source: crates/plugins/money/src/views.rs:713

all_transactions

Section titled “all_transactions”
pub fn all_transactions(ledger: &Ledger) -> Vec<&Transaction>

The ledger’s rows sorted newest first (same date: later file rows first).

Source: crates/plugins/money/src/views.rs:540

budget_amount

Section titled “budget_amount”
pub fn budget_amount(ledger: &Ledger, transaction: &Transaction) -> Minor

The budget-currency amount of a row (its fx total, or its own amount).

Source: crates/plugins/money/src/views.rs:521

memo_and_tags

Section titled “memo_and_tags”
pub fn memo_and_tags(payee: &str) -> (String, Vec<String>)

Split a payee and memo into its text and its inline tags.

Tag bytes are removed and runs of spaces collapse, so “Market #weekly, stall 4” reads “Market, stall 4” with the chip weekly.

Source: crates/plugins/money/src/views.rs:690

month_view

Section titled “month_view”
pub fn month_view(
    ledger: &Ledger,
    name: &str,
    totals: &MonthTotals,
    revision: u64,
) -> Result<MonthView>

Build the month report and attach the write sequence read under the Money lock (#984).

Source: crates/plugins/money/src/views.rs:423

scale_of

Section titled “scale_of”
pub fn scale_of(currency: &str) -> u32

Budget currency scale; the ledger was validated, so it exists.

Source: crates/plugins/money/src/views.rs:408

transaction_views

Section titled “transaction_views”
pub fn transaction_views(
    ledger: &Ledger,
    account: Option<&str>,
    month: Option<&str>,
) -> Vec<TransactionView>

Register rows for account (both legs of transfers) and/or month. Each transfer leg keeps its original Date, Notes and marks (#1130).

Source: crates/plugins/money/src/views.rs:569

unsupported_reason

Section titled “unsupported_reason”
pub fn unsupported_reason(transaction: &Transaction) -> Option<&'static str>

Detail rows an edit must refuse (splits, transfers, FX, and import-only Ready to Assign reconciliation): Some(reason).

Source: crates/plugins/money/src/views.rs:778