Struct BudgetService 

pub struct BudgetService<'a> { /* private fields */ }

Service for budget management

Implementations

impl<'a> BudgetService<'a>

pub fn new(storage: &'a Storage) -> Self

Create a new budget service

pub fn assign_to_category( &self, category_id: CategoryId, period: &BudgetPeriod, amount: Money, ) -> EnvelopeResult<BudgetAllocation>

Assign funds to a category for a period

pub fn add_to_category( &self, category_id: CategoryId, period: &BudgetPeriod, amount: Money, ) -> EnvelopeResult<BudgetAllocation>

Add to a category’s budget for a period

pub fn move_between_categories( &self, from_category_id: CategoryId, to_category_id: CategoryId, period: &BudgetPeriod, amount: Money, ) -> EnvelopeResult<()>

Move funds between categories for a period

pub fn get_allocation( &self, category_id: CategoryId, period: &BudgetPeriod, ) -> EnvelopeResult<BudgetAllocation>

Get the allocation for a category in a period

pub fn get_category_summary( &self, category_id: CategoryId, period: &BudgetPeriod, ) -> EnvelopeResult<CategoryBudgetSummary>

Get budget summary for a category in a period

pub fn calculate_category_activity( &self, category_id: CategoryId, period: &BudgetPeriod, ) -> EnvelopeResult<Money>

Calculate activity (spending) for a category in a period

pub fn calculate_income_for_period( &self, period: &BudgetPeriod, ) -> EnvelopeResult<Money>

Calculate total income for a period (sum of all positive transactions)

pub fn get_available_to_budget( &self, period: &BudgetPeriod, ) -> EnvelopeResult<Money>

Calculate Available to Budget for a period

Available to Budget = Total On-Budget Balances - Total Budgeted for current + prior periods

pub fn get_expected_income(&self, period: &BudgetPeriod) -> Option<Money>

Get expected income for a period (if set)

pub fn is_over_expected_income( &self, period: &BudgetPeriod, ) -> EnvelopeResult<Option<Money>>

Check if total budgeted exceeds expected income

Returns Some(overage_amount) if over budget, None otherwise

pub fn get_remaining_to_budget_from_income( &self, period: &BudgetPeriod, ) -> EnvelopeResult<Option<Money>>

Get remaining amount that can be budgeted based on expected income

Returns the difference between expected income and total budgeted. Positive = room to budget more, Negative = over-budgeted

pub fn get_budget_overview( &self, period: &BudgetPeriod, ) -> EnvelopeResult<BudgetOverview>

Get a complete budget overview for a period

pub fn get_allocation_history( &self, category_id: CategoryId, ) -> EnvelopeResult<Vec<BudgetAllocation>>

Get all allocations for a category (history)

pub fn calculate_cumulative_budgeted( &self, category_id: CategoryId, up_to_period: &BudgetPeriod, ) -> EnvelopeResult<Money>

Calculate the cumulative amount budgeted to a category across all periods up to and including the specified period.

This is useful for ByDate targets where progress should reflect total budgeted over time, not just current available balance.

pub fn calculate_cumulative_paid( &self, category_id: CategoryId, up_to_period: &BudgetPeriod, ) -> EnvelopeResult<Money>

Calculate the cumulative amount paid/spent from a category across all time up to and including the specified period.

This returns the absolute value of negative activity (outflows/payments). Useful for ByDate targets where payments should count as progress even if no explicit budgeting occurred.

pub fn get_carryover( &self, category_id: CategoryId, period: &BudgetPeriod, ) -> EnvelopeResult<Money>

Calculate the carryover amount for a category going into a specific period

This is the “Available” balance from the previous period, which includes:

• Budgeted amount
• Previous carryover
• Activity (spending)

pub fn apply_rollover( &self, category_id: CategoryId, period: &BudgetPeriod, ) -> EnvelopeResult<BudgetAllocation>

Apply rollover from the previous period to a category’s allocation

This should be called when entering a new period to carry forward any surplus or deficit from the previous period.

pub fn apply_rollover_all( &self, period: &BudgetPeriod, ) -> EnvelopeResult<Vec<BudgetAllocation>>

Apply rollover for all categories for a period

This calculates and sets the carryover amount for every category based on their Available balance from the previous period.

pub fn get_overspent_categories( &self, period: &BudgetPeriod, ) -> EnvelopeResult<Vec<CategoryBudgetSummary>>

Get a list of overspent categories for a period

pub fn set_target( &self, category_id: CategoryId, amount: Money, cadence: TargetCadence, ) -> EnvelopeResult<BudgetTarget>

Create or update a budget target for a category

pub fn update_target( &self, target_id: BudgetTargetId, amount: Option<Money>, cadence: Option<TargetCadence>, ) -> EnvelopeResult<BudgetTarget>

Update an existing budget target

pub fn get_target( &self, category_id: CategoryId, ) -> EnvelopeResult<Option<BudgetTarget>>

Get the active target for a category

pub fn get_suggested_budget( &self, category_id: CategoryId, period: &BudgetPeriod, ) -> EnvelopeResult<Option<Money>>

Get the suggested budget amount for a category based on its target

pub fn get_suggested_budget_with_progress( &self, category_id: CategoryId, period: &BudgetPeriod, ) -> EnvelopeResult<Option<Money>>

Get the suggested budget amount for a category, accounting for progress made.

For ByDate targets, this subtracts what’s already been paid from the target amount before calculating the monthly suggestion. This prevents over-budgeting when payments have already been made toward a debt payoff goal.

For other target types (Weekly, Monthly, Yearly, Custom), this delegates to the standard calculation since those are recurring targets.

pub fn delete_target(&self, target_id: BudgetTargetId) -> EnvelopeResult<bool>

Delete a target

pub fn remove_target(&self, category_id: CategoryId) -> EnvelopeResult<bool>

Remove target for a category

pub fn get_all_targets(&self) -> EnvelopeResult<Vec<BudgetTarget>>

Get all active targets

pub fn auto_fill_from_target( &self, category_id: CategoryId, period: &BudgetPeriod, ) -> EnvelopeResult<Option<BudgetAllocation>>

Auto-fill budget for a category based on its target

Uses progress-aware calculation for ByDate targets, accounting for payments already made toward the goal.

pub fn auto_fill_all_targets( &self, period: &BudgetPeriod, ) -> EnvelopeResult<Vec<BudgetAllocation>>

Auto-fill budgets for all categories with targets

Uses progress-aware calculation for ByDate targets, accounting for payments already made toward each goal.