@hearthlog/module-finance 0.0.0-stage → 1.0.1

package/src/pages/month.ts

@@ -0,0 +1,99 @@
+import { deferPage, type PagePublisher } from '@hearthlog/sdk/runtime';
+import type { ModuleLoadEvent } from '@hearthlog/sdk/runtime';
+import type { Asset } from '../data/assets.js';
+import type { BudgetItem } from '@hearthlog/sdk/data';
+import type { BudgetItemSort, BudgetPlanSummary } from '../data/budgets.js';
+import type { BalanceRange, TimelineOutlook } from '../data/finance-timeline.js';
+import { queryDatabase } from '@hearthlog/sdk/data';
+import { parseBudgetItemSort } from '../data/budgets.js';
+import { loadBalanceFloor } from '../finance/floor.js';
+import { appClock } from '@hearthlog/sdk/runtime';
+import { format } from 'date-fns';
+
+export interface FinancePageData {
+    /** The month the endless views open at; today's month opens at Today. */
+    year: number;
+    month: number;
+    today: string;
+    outlook: TimelineOutlook;
+    /** Lowest and highest balance over all history and every plan: one fixed scale. */
+    range: BalanceRange;
+    floor: number;
+    assets: Asset[];
+    assetsSum: number;
+    budgetPlans: BudgetPlanSummary[];
+    budgetIncomeItems: BudgetItem[];
+    budgetExpenseItems: BudgetItem[];
+    selectedPlanId: string | null;
+    incomeSort: BudgetItemSort | null;
+    expenseSort: BudgetItemSort | null;
+}
+
+function emptyData(year: number, month: number): FinancePageData {
+    return {
+        year,
+        month,
+        today: '',
+        outlook: { available: 0, low: { amount: 0, date: '' }, end: 0, endDate: null, lastDone: null },
+        range: { min: 0, max: 0 },
+        floor: 0,
+        assets: [],
+        assetsSum: 0,
+        budgetPlans: [],
+        budgetIncomeItems: [],
+        budgetExpenseItems: [],
+        selectedPlanId: null,
+        incomeSort: null,
+        expenseSort: null,
+    };
+}
+
+const loadData = async (
+    { params, parent, url }: ModuleLoadEvent,
+    publish: PagePublisher<FinancePageData>,
+): Promise<FinancePageData> => {
+    // The layout's load supplies the assets; the route loader receives untyped parent data.
+    const { assetsData } = await parent() as { assetsData: Promise<{ assets: Asset[]; assetsSum: number }> };
+    const assetsReady = assetsData.then((value) => { publish(value, 'assets'); return value; });
+    void assetsReady.catch(() => undefined);
+    const now = await appClock.ready();
+    const today = format(now, 'yyyy-MM-dd');
+    const isBudgetTab = url.searchParams.get('tab') === 'budget';
+    const requestedPlanId = url.searchParams.get('plan');
+    const incomeSort = parseBudgetItemSort(url.searchParams.get('incomeSort'));
+    const expenseSort = parseBudgetItemSort(url.searchParams.get('expenseSort'));
+
+    // The endless views read the months and weeks that scroll into view on
+    // their own; the page loads what spans all of them.
+    const [{ assets, assetsSum }, floor, result] = await Promise.all([
+        assetsReady,
+        loadBalanceFloor(),
+        queryDatabase(async (repositories) => {
+            const [outlook, range, budgetPlans] = await Promise.all([
+                repositories.timeline.getOutlook({ today }),
+                repositories.timeline.getRange({ today }),
+                isBudgetTab ? repositories.budgets.getPlans() : Promise.resolve([] as BudgetPlanSummary[]),
+            ]);
+            const selectedPlan = budgetPlans.find((plan) => plan.id === requestedPlanId) ?? budgetPlans[0];
+            const [budgetIncomeItems, budgetExpenseItems] = selectedPlan
+                ? await Promise.all([
+                    repositories.budgets.getPlanItems(selectedPlan.id, 'income', incomeSort),
+                    repositories.budgets.getPlanItems(selectedPlan.id, 'expense', expenseSort),
+                ])
+                : [[], []];
+            return { outlook, range, budgetPlans, budgetIncomeItems, budgetExpenseItems, selectedPlanId: selectedPlan ? selectedPlan.id : null };
+        }),
+    ]);
+
+    return { year: Number(params.year ?? 0), month: Number(params.month ?? 0), today, floor, assets, assetsSum, incomeSort, expenseSort, ...result };
+};
+
+export const load = (event: ModuleLoadEvent) => {
+    event.depends('app:transactions');
+    event.depends('app:budgets');
+    return deferPage<FinancePageData>(
+        event,
+        emptyData(Number(event.params.year ?? 0), Number(event.params.month ?? 0)),
+        (publish) => loadData(event, publish),
+    );
+};

package/src/server/category-pick.ts

@@ -0,0 +1,44 @@
+import { aiInput, AiRequestError, type AiCapabilityDefinition } from '@hearthlog/contracts';
+import { TRANSACTION_CATEGORIES } from '../finance/categories.js';
+import type { CategoryPickItem } from '../finance/category-pick.js';
+
+const MAX_NAME = 200;
+
+const MEANINGS: Record<string, string> = {
+    income: 'Money received: salary, refunds, interest',
+    housing: 'Rent, mortgage, energy, water, home repairs',
+    food: 'Groceries, restaurants, cafés, takeaway',
+    transport: 'Fuel, public transport, taxis, parking, car costs',
+    subscriptions: 'Recurring digital or membership services',
+    health: 'Doctors, pharmacy, insurance for health, sport',
+    shopping: 'Clothes, electronics, household goods, online shops',
+    leisure: 'Entertainment, hobbies, culture, trips',
+    kids: 'Children: school, childcare, toys, clothing',
+    gifts: 'Gifts and donations',
+    other: 'A real expense that fits none of the others',
+};
+
+/** Which category a bank transaction belongs to, picked by a small decision model. */
+export const categoryPick: AiCapabilityDefinition = {
+    options: () => TRANSACTION_CATEGORIES
+        .filter((category) => category.value !== 'unknown')
+        .map((category) => ({ value: category.value, meaning: MEANINGS[category.value] ?? category.label })),
+    parseItem(value): CategoryPickItem {
+        const item = aiInput.object(value);
+        const direction = item.direction;
+        if (direction !== 'income' && direction !== 'expense') throw new AiRequestError('Invalid direction');
+        const amount = item.amount;
+        if (typeof amount !== 'number' || !Number.isFinite(amount) || amount < 0 || amount > 1e12) {
+            throw new AiRequestError('Invalid amount');
+        }
+        return { id: aiInput.id(item.id), name: aiInput.text(item.name, MAX_NAME), amount, direction };
+    },
+    question(item) {
+        const transaction = item as CategoryPickItem;
+        return {
+            state: `Bank transaction of a Czech household. Name: ${JSON.stringify(transaction.name)}. ` +
+                `Amount: ${transaction.amount} CZK (${transaction.direction}).`,
+            instructions: 'Which category does this transaction belong to? Answer none if the name is unclear or no category fits.',
+        };
+    },
+};

package/src/server/index.ts

@@ -0,0 +1,11 @@
+import type { ServerModule } from '@hearthlog/sdk/server';
+import { categoryPick } from './category-pick.js';
+
+/** Finance's part of the gateway Worker: the AI decision that suggests a transaction's category. */
+const finance: ServerModule<Env> = {
+    id: 'org.stor.finance',
+    routes: [],
+    ai: { 'category-pick': categoryPick },
+};
+
+export default finance;

package/src/styles.css

@@ -0,0 +1,12 @@
+/* Finance's recipes: the Today card link and the phone list's running balance. Imported by the host's stylesheet. */
+
+@layer components {
+    a > .stor-today-card { transition: transform 160ms ease, box-shadow 160ms ease; }
+    a > .stor-today-card:hover { transform: translateY(-1px); box-shadow: var(--stor-shadow-md); }
+}
+
+@media (max-width: 767px) {
+    /* Lists show their figures only when asked: the running balance, the balance line, month figures. */
+    [data-phone-balance="off"] [data-balance], [data-phone-balance="off"] [data-river] { display: none; }
+    [data-phone-balance="off"] [data-timeline-scroll] { --river: 0px !important; }
+}