Log an expense in PKR. Only amount is required.

date accepts YYYY-MM-DD, 'today', 'yesterday', '-3d', or a day number; it defaults to today. When category is omitted it is inferred from previous expenses at the same merchant. The returned record reflects what was actually saved, including anything inferred.

Log several expenses at once. Each item takes the same fields as add_expense.

Items are validated individually: a bad entry is reported in errors while the rest still save.

Edit an expense. Omitted fields are left alone; pass "" to clear a text field.

Correct the most recently logged expense without needing its id.

Delete an expense. Soft delete — undo_last() restores it.

Restore the most recently deleted expense.

The valid category names. Expenses must use one of these.

List individual expenses. Defaults to the current month.

For totals use summarize() instead — it is far cheaper than adding up rows here.

Spending totals, pre-computed. Never sum expenses by hand — call this.

group_by is one of category, merchant, month, day, tag. period is one of this_month, last_month, ytd, all; from_date/to_date override it.

Free-text search across merchant and note, over all time.

Set a monthly spending limit in PKR for a category.

Budget vs. actual for a month ('YYYY-MM', default current), with burn pace.

Add a monthly recurring expense (rent, internet, subscriptions).

It posts itself on day_of_month each month, tagged 'recurring'. A day past the end of a short month posts on that month's last day. If the day has already passed this month, it posts immediately.

All active recurring expenses.

Stop a recurring expense. Already-posted expenses are left in place.

Write a consistent snapshot of the database to the backups directory.