Skip to content
calternal docs

calternal_money::schedule

Derived schedules: upcoming bills and card statement cycles.

Port of upcoming_bills and card_statements in the #404 oracle. Nothing here posts a transaction, assigns money or changes a balance: a plan or a subscription only shows a bill (DESIGN §48).

Rules kept from the oracle and DESIGN §48:

  • A schedule keeps its original day: a Jan 31 monthly charge is due on the last day of February, then on Mar 31 again.
  • A subscription uses its latest price:: on or before the due date; every price row is validated first, even future ones.
  • statement-balance and minimum plans show a bill only in the cycle of next due::; a fixed plan repeats monthly.
  • A statement cycle runs from the day after the previous close through the close. due after:: N days counts the close as day one; due day:: N is day N of the next month, clamped. Weekends and holidays move a date only with business days:: true, using caller-supplied holidays.
  • A confirmed statement:: history row wins over the computed cycle sum; the difference is Unrecorded. The closing balance is all recorded card debt at the close. The issuer minimum is never derived.

Source: crates/calternal-money/src/schedule.rs

Structs

Section titled “Structs”

CardStatement

Section titled “CardStatement”
pub struct CardStatement

One card statement cycle.

Fields

  • pub account_id: String: Card account ID.
  • pub close_date: String: Close date.
  • pub due_date: String: Due date.
  • pub currency: String: Card currency.
  • pub computed: Minor: Net card activity inside the cycle (debt positive).
  • pub amount: Minor: The bill: the confirmed amount, else the computed amount.
  • pub unrecorded: Minor: Confirmed minus computed (zero when not confirmed): Unrecorded.
  • pub confirmed: bool: True when the User confirmed this cycle’s amount.
  • pub coverage: Option<BillCoverage>: Reserve coverage, when reserves were supplied and currencies match.
  • pub closing_balance: Minor: All recorded card debt at the close (what issuers bill in total).
  • pub minimum: Option<Minor>: The issuer’s minimum due, when confirmed.

Implements: Clone, Debug, Serialize

Source: crates/calternal-money/src/schedule.rs:95

UpcomingBill

Section titled “UpcomingBill”
pub struct UpcomingBill

One derived upcoming charge. amount keeps the written decimal text.

Fields

  • pub block_id: String: Subscription or card block ID.
  • pub date: String: Due date YYYY-MM-DD.
  • pub amount: String: Amount text as written.
  • pub currency: String: Currency as written.
  • pub category_id: String: Category the bill belongs to.
  • pub account_id: String: Account that pays it.
  • pub source: BillSource: Source.
  • pub cancel_by: Option<String>: cancel by:: date, if any.
  • pub coverage: Option<BillCoverage>: Card reserve coverage, when reserves were supplied.

Implements: Clone, Debug, Serialize

Source: crates/calternal-money/src/schedule.rs:72

Enums

Section titled “Enums”

BillSource

Section titled “BillSource”
pub enum BillSource

Where an upcoming bill comes from.

Variants

  • Subscription: A subscription under ## Subscriptions in Budget.md.
  • CardPayment: A card payment plan in Accounts.md.

Implements: Clone, Copy, Debug, Eq, PartialEq, Serialize

BillSource::as_str

Section titled “BillSource::as_str”
pub const fn as_str(self) -> &'static str

The oracle’s name.

Source: crates/calternal-money/src/schedule.rs:53

Functions

Section titled “Functions”

add_months

Section titled “add_months”
pub fn add_months(value: NaiveDate, count: i32) -> NaiveDate

Add count months to a date, clamping the day in short months while keeping the original day for later months.

Source: crates/calternal-money/src/schedule.rs:122

card_statements

Section titled “card_statements”
pub fn card_statements(
    budget: &Document,
    accounts_document: &Document,
    months: &[Document],
    month: &str,
    holidays: &[String],
    reserves: Option<&HashMap<String, Minor>>,
) -> Result<Vec<CardStatement>>

Compute each card’s statement cycle that closes in month.

holidays are the issuer’s holiday dates (YYYY-MM-DD); reserves maps card IDs to budget-currency reserves. Sorted by (close date, card ID).

Source: crates/calternal-money/src/schedule.rs:494

date_for_month

Section titled “date_for_month”
pub fn date_for_month(first: &str, cadence: &str, month: &str) -> Result<Option<String>>

The due date of a schedule in month, or None when it is not due then.

cadence is monthly, quarterly or yearly; the date keeps the first date’s day (clamped, never drifting).

Source: crates/calternal-money/src/schedule.rs:143

day_of_month

Section titled “day_of_month”
pub fn day_of_month(year: i32, month: u32, day: u32) -> NaiveDate

The given day in a month, clamped to the month’s last day.

Source: crates/calternal-money/src/schedule.rs:129

upcoming_bills

Section titled “upcoming_bills”
pub fn upcoming_bills(
    budget: &Document,
    accounts_document: &Document,
    month: &str,
    reserves: Option<&HashMap<String, Minor>>,
) -> Result<Vec<UpcomingBill>>

Derive the bills due in month (subscriptions and card payment plans), sorted by (date, block ID). reserves maps card IDs to budget-currency reserves (from crate::budget::MonthTotals::card_payment_balance).

Source: crates/calternal-money/src/schedule.rs:188