feat(assistant): expense, payment and settle-up cards, and expense links into Costs

This commit is contained in:
Maurice
2026-10-22 15:50:49 +02:00
parent c94545419b
commit b52990bf27
65 changed files with 4763 additions and 95 deletions
@@ -0,0 +1,154 @@
import { ASSISTANT_CHANGE_VERB_KEYS, assistantAppliedSchema, assistantChangePreviewSchema } from '../assistant.schema';
import { BUDGET_APPLIED_ENTITIES, BUDGET_CARD_SCHEMAS, BUDGET_VERB_KEYS } from './budget.contract';
import { costPerPersonCardSchema, type CostPerPersonCard } from './cost-per-person.card';
import { EXPENSE_PEOPLE_MAX, expensesCardSchema, type CardExpense, type ExpensesCard } from './expenses.card';
import { storedTrekCardSchema, trekCardSchema } from './index';
import { paymentsCardSchema, type PaymentsCard } from './payments.card';
import { settlementCardSchema, type SettlementCard } from './settlement.card';
import { describe, expect, it } from 'vitest';
const ana = { id: 7, name: 'Ana', avatarKey: 'ana.png' };
const ben = { id: 8, name: 'Ben', avatarKey: null };
const dinner: CardExpense = {
id: 31,
name: 'Dinner at Lokanta',
category: 'food',
amount: { amount: 84, currency: 'EUR' },
tripAmount: null,
date: '2026-06-03',
place: { id: 12, name: 'Lokanta' },
payers: [{ person: ana, amount: 84 }],
split: 'equal',
shares: [
{ person: ana, amount: 42, paid: true },
{ person: ben, amount: 42, paid: false },
],
moreShares: 0,
note: null,
receipts: 2,
before: null,
highlight: [],
change: 'none',
};
const expenses: ExpensesCard = {
kind: 'expenses',
rows: [dinner],
offset: 0,
more: 13,
total: { amount: 1204.5, currency: 'EUR' },
unconverted: 1,
};
const payments: PaymentsCard = {
kind: 'payments',
rows: [
{
id: null,
from: ben,
to: ana,
amount: { amount: 42.5, currency: 'EUR' },
date: '2026-06-07',
note: 'Bank transfer',
before: { from: ana, to: null, amount: { amount: 40, currency: 'EUR' } },
change: 'changed',
},
],
more: 0,
};
const settlement: SettlementCard = {
kind: 'settlement',
currency: 'EUR',
flows: [{ from: ben, to: ana, amount: 42.5 }],
moreFlows: 0,
balances: [
{ person: ana, balance: 42.5 },
{ person: ben, balance: -42.5 },
],
moreBalances: 0,
recorded: 3,
unconverted: { entries: 2, currencies: ['USD'] },
};
const perPerson: CostPerPersonCard = {
kind: 'costPerPerson',
currency: 'EUR',
rows: [{ person: ana, share: 69, paid: 45, count: 2 }],
more: 0,
};
describe('budget cards', () => {
it('CARDS-BUD-001: the four kinds join the card union and read back as built', () => {
expect(BUDGET_CARD_SCHEMAS).toEqual([
expensesCardSchema,
paymentsCardSchema,
settlementCardSchema,
costPerPersonCardSchema,
]);
for (const card of [expenses, payments, settlement, perPerson]) {
expect(trekCardSchema.parse(card)).toEqual(card);
expect(storedTrekCardSchema.parse(card)).toEqual(card);
}
});
it('CARDS-BUD-002: a waiting change states what it replaces and whom it is about', () => {
const update: CardExpense = {
...dinner,
amount: { amount: 96, currency: 'EUR' },
before: { name: null, amount: { amount: 84, currency: 'EUR' }, category: null, date: null, split: 'custom' },
highlight: [8],
change: 'changed',
};
expect(expensesCardSchema.parse({ ...expenses, rows: [update], total: null }).rows[0]).toEqual(update);
expect(expensesCardSchema.safeParse({ ...expenses, rows: [{ ...update, change: 'moved' }] }).success).toBe(false);
// A refund is a negative amount; nothing past a billion is.
const refund = { ...dinner, amount: { amount: -20, currency: 'EUR' } };
expect(expensesCardSchema.safeParse({ ...expenses, rows: [refund] }).success).toBe(true);
expect(expensesCardSchema.safeParse({ ...expenses, total: { amount: 2e9, currency: 'EUR' } }).success).toBe(false);
});
it('CARDS-BUD-003: lists and splits are bounded, and a card past a bound reads as no card', () => {
const many = Array.from({ length: EXPENSE_PEOPLE_MAX + 1 }, (_, i) => ({
person: { ...ben, id: 100 + i },
amount: 1,
paid: false,
}));
expect(storedTrekCardSchema.parse({ ...expenses, rows: [{ ...dinner, shares: many }] })).toBeNull();
expect(storedTrekCardSchema.parse({ ...expenses, rows: Array.from({ length: 13 }, () => dinner) })).toBeNull();
expect(storedTrekCardSchema.parse({ ...expenses, rows: [] })).toBeNull();
expect(storedTrekCardSchema.parse({ ...expenses, offset: -1 })).toBeNull();
const free = { ...payments.rows[0], amount: { amount: 0, currency: 'EUR' } };
expect(storedTrekCardSchema.parse({ ...payments, rows: [free] })).toBeNull();
expect(storedTrekCardSchema.parse({ ...settlement, currency: 'euro' })).toBeNull();
expect(storedTrekCardSchema.parse({ ...perPerson, rows: [] })).toBeNull();
});
it('CARDS-BUD-004: people carry a stored file name only, never an address', () => {
const linked = { ...ana, avatarKey: 'https://sso.example/ana.png' };
expect(storedTrekCardSchema.parse({ ...perPerson, rows: [{ ...perPerson.rows[0], person: linked }] })).toBeNull();
const upward = { from: ana, to: { ...ben, avatarKey: '../x' }, amount: 1 };
expect(storedTrekCardSchema.parse({ ...settlement, flows: [upward] })).toBeNull();
});
it('CARDS-BUD-005: a payment change reads its verb, and a payment receipt its own entity', () => {
expect(BUDGET_VERB_KEYS).toEqual(['addPayment', 'updatePayment']);
for (const verb of BUDGET_VERB_KEYS) expect(ASSISTANT_CHANGE_VERB_KEYS).toContain(verb);
const preview = {
toolCallId: 'c1',
verbKey: 'addPayment',
subject: 'Ben → Ana',
rows: [],
dayId: null,
placeIds: [],
undoable: true,
card: payments,
};
expect(assistantChangePreviewSchema.parse(preview)).toMatchObject({ verbKey: 'addPayment', card: payments });
expect(BUDGET_APPLIED_ENTITIES).toEqual(['settlement']);
const receipt = { toolCallId: 'c1', entity: 'settlement', ids: [5], dayId: null, undoUntil: null };
expect(assistantAppliedSchema.parse(receipt).entity).toBe('settlement');
});
});
@@ -21,5 +21,7 @@ export const BUDGET_CARD_SCHEMAS = [
settlementCardSchema,
costPerPersonCardSchema,
] as const;
export const BUDGET_VERB_KEYS = [] as const;
export const BUDGET_APPLIED_ENTITIES = [] as const;
/** A settle-up payment recorded or changed; removing one is a plain removal. */
export const BUDGET_VERB_KEYS = ['addPayment', 'updatePayment'] as const;
/** A settle-up payment: the receipt opens the Costs tab, where the payments are listed. */
export const BUDGET_APPLIED_ENTITIES = ['settlement'] as const;
@@ -1,5 +1,30 @@
import { cardCurrencySchema, cardPersonSchema } from './card-parts';
import { z } from 'zod';
/** What the trip costs each traveller. Only its kind so far; the budget cards give it its fields. */
export const costPerPersonCardSchema = z.object({ kind: z.literal('costPerPerson') });
/**
* What the trip's expenses come to for each traveller, in the trip
* currency: the sum of their shares, how much of that is marked paid, and in
* how many expenses they take part. Largest share first.
*/
/** Travellers one card names; the rest are counted in `more`. */
export const COST_PER_PERSON_ROWS_MAX = 20;
export const costPerPersonCardSchema = z.object({
kind: z.literal('costPerPerson'),
currency: cardCurrencySchema,
rows: z
.array(
z.object({
person: cardPersonSchema,
share: z.number().min(-1e9).max(1e9),
paid: z.number().min(-1e9).max(1e9),
count: z.number().int().min(0).max(100_000),
}),
)
.min(1)
.max(COST_PER_PERSON_ROWS_MAX),
more: z.number().int().min(0).max(1000),
});
export type CostPerPersonCard = z.infer<typeof costPerPersonCardSchema>;
+97 -3
View File
@@ -1,8 +1,102 @@
import { idSchema } from '../../common/primitives.schema';
import { cardDateSchema, cardMoneySchema, cardPersonSchema, cardText } from './card-parts';
import { z } from 'zod';
/**
* Expenses of the trip, with who paid and who shares them. Only its kind so far; the budget cards give
* it its fields.
* Expenses of the trip as the Costs page shows them: the name, the amount in
* the currency it was paid in (and in the trip currency when that differs and
* a rate is known), the day, the place it belongs to, who paid how much and
* who shares it. One card serves the expense list (`list_budget_items`) and
* every change to a single expense: the row of a change carries what it
* replaces (`before`), the people it is about (`highlight`) and what happens
* to it (`change`). Amounts are numbers with a currency code; the client
* writes them the way the Costs page does.
*/
export const expensesCardSchema = z.object({ kind: z.literal('expenses') });
/** Rows one expenses card lists; the rest are counted in `more`. */
export const EXPENSE_ROWS_MAX = 12;
/** Payers or shares one row names; the rest of a split are counted in `moreShares`. */
export const EXPENSE_PEOPLE_MAX = 20;
/** A signed amount: a refund is negative (#2176). */
const cardAmountSchema = z.number().min(-1e9).max(1e9);
/** How an expense is shared: evenly, in amounts of its own per person, or by nobody (planning only). */
export const expenseSplitSchema = z.enum(['equal', 'custom', 'none']);
/** What a change does to a row; an answer's rows are `none`. */
export const expenseChangeSchema = z.enum(['none', 'new', 'changed', 'willDelete']);
/** One person's part of an expense, and whether they have paid it. */
export const cardExpenseShareSchema = z.object({
person: cardPersonSchema,
amount: cardAmountSchema,
paid: z.boolean(),
});
/** Someone who paid for the expense, and how much. */
export const cardExpensePayerSchema = z.object({ person: cardPersonSchema, amount: cardAmountSchema });
/**
* The values a waiting update replaces, each null where the update leaves it
* alone: a category or a date that was empty before reads as unchanged.
*/
export const cardExpenseBeforeSchema = z.object({
name: cardText(120).nullable(),
amount: cardMoneySchema.nullable(),
category: z.string().max(60).nullable(),
date: cardDateSchema.nullable(),
split: expenseSplitSchema.nullable(),
});
export const cardExpenseSchema = z.object({
/** Null while a new expense waits for its decision. */
id: idSchema.nullable(),
name: cardText(120),
/** As stored; the client maps it to a Costs category, legacy free text included. */
category: z.string().max(60).nullable(),
/** The total in the currency it was entered in (the trip's when it names none). */
amount: cardMoneySchema,
/** The total in the trip currency, only when that differs and a rate converts it. */
tripAmount: cardMoneySchema.nullable(),
date: cardDateSchema.nullable(),
place: z.object({ id: idSchema, name: cardText(120) }).nullable(),
payers: z.array(cardExpensePayerSchema).max(EXPENSE_PEOPLE_MAX),
split: expenseSplitSchema,
shares: z.array(cardExpenseShareSchema).max(EXPENSE_PEOPLE_MAX),
/** Shares of the split past the ones named. */
moreShares: z.number().int().min(0).max(1000),
/** A change row's note; list rows leave it out. */
note: cardText(160).nullable(),
/** How many receipts are attached; never the files themselves. */
receipts: z.number().int().min(0).max(999),
before: cardExpenseBeforeSchema.nullable(),
/** The people the change is about: a paid tick set, someone joining the split. */
highlight: z.array(idSchema).max(EXPENSE_PEOPLE_MAX),
change: expenseChangeSchema,
});
export const expensesCardSchema = z.object({
kind: z.literal('expenses'),
rows: z.array(cardExpenseSchema).min(1).max(EXPENSE_ROWS_MAX),
/**
* Where in the trip's list the rows start: a later page of the list starts
* past 0, so two pages read as one list only where they meet. 0 on a change.
*/
offset: z.number().int().min(0).max(100_000),
/** Expenses of the trip the card leaves out. */
more: z.number().int().min(0).max(100_000),
/** The list's total over every expense, in the trip currency; null on a change. */
total: cardMoneySchema.nullable(),
/** Expenses the total leaves out: foreign ones no rate converts yet. */
unconverted: z.number().int().min(0).max(100_000),
});
export type ExpensesCard = z.infer<typeof expensesCardSchema>;
export type CardExpense = z.infer<typeof cardExpenseSchema>;
export type CardExpenseShare = z.infer<typeof cardExpenseShareSchema>;
export type CardExpensePayer = z.infer<typeof cardExpensePayerSchema>;
export type CardExpenseBefore = z.infer<typeof cardExpenseBeforeSchema>;
export type ExpenseSplit = z.infer<typeof expenseSplitSchema>;
export type ExpenseChange = z.infer<typeof expenseChangeSchema>;
+48 -2
View File
@@ -1,5 +1,51 @@
import { idSchema } from '../../common/primitives.schema';
import { cardCurrencySchema, cardDateSchema, cardPersonSchema, cardText } from './card-parts';
import { expenseChangeSchema } from './expenses.card';
import { z } from 'zod';
/** Payments between the travellers. Only its kind so far; the budget cards give it its fields. */
export const paymentsCardSchema = z.object({ kind: z.literal('payments') });
/**
* Settle-up payments between the travellers, as the Costs page lists them
* under its payment history: who paid whom, how much, on which day, with the
* note it carries. One card serves the list (`list_settlements`) and every
* change to one payment; a waiting change names what it replaces in `before`.
*/
/** Payments one card lists; the rest are counted in `more`. */
export const PAYMENT_ROWS_MAX = 12;
/** What one payment moved: always more than nothing. */
export const cardPaymentMoneySchema = z.object({
amount: z.number().positive().max(1e9),
currency: cardCurrencySchema,
});
/** The values a waiting update of a payment replaces, each null where it stays. */
export const cardPaymentBeforeSchema = z.object({
from: cardPersonSchema.nullable(),
to: cardPersonSchema.nullable(),
amount: cardPaymentMoneySchema.nullable(),
});
export const cardPaymentSchema = z.object({
/** Null while a new payment waits for its decision. */
id: idSchema.nullable(),
from: cardPersonSchema,
to: cardPersonSchema,
amount: cardPaymentMoneySchema,
/** The day it was paid, else the day it was recorded. */
date: cardDateSchema.nullable(),
note: cardText(120).nullable(),
before: cardPaymentBeforeSchema.nullable(),
change: expenseChangeSchema,
});
export const paymentsCardSchema = z.object({
kind: z.literal('payments'),
rows: z.array(cardPaymentSchema).min(1).max(PAYMENT_ROWS_MAX),
more: z.number().int().min(0).max(100_000),
});
export type PaymentsCard = z.infer<typeof paymentsCardSchema>;
export type CardPayment = z.infer<typeof cardPaymentSchema>;
export type CardPaymentMoney = z.infer<typeof cardPaymentMoneySchema>;
+33 -2
View File
@@ -1,5 +1,36 @@
import { cardCurrencySchema, cardPersonSchema } from './card-parts';
import { z } from 'zod';
/** Who pays whom to settle up. Only its kind so far; the budget cards give it its fields. */
export const settlementCardSchema = z.object({ kind: z.literal('settlement') });
/**
* Settle up as the Costs page shows it: the payments that would square the
* trip (who pays whom), each traveller's balance (positive is owed money,
* negative owes it), how many payments were already recorded, and the
* entries no exchange rate converts yet, which count in no figure. Every
* amount is in `currency`.
*/
/** Suggested payments one card names; the rest are counted in `moreFlows`. */
export const SETTLEMENT_FLOWS_MAX = 12;
/** Balances one card names; the rest are counted in `moreBalances`. */
export const SETTLEMENT_BALANCES_MAX = 20;
export const settlementCardSchema = z.object({
kind: z.literal('settlement'),
currency: cardCurrencySchema,
flows: z
.array(z.object({ from: cardPersonSchema, to: cardPersonSchema, amount: z.number().positive().max(1e9) }))
.max(SETTLEMENT_FLOWS_MAX),
moreFlows: z.number().int().min(0).max(1000),
balances: z
.array(z.object({ person: cardPersonSchema, balance: z.number().min(-1e9).max(1e9) }))
.max(SETTLEMENT_BALANCES_MAX),
moreBalances: z.number().int().min(0).max(1000),
/** Payments already recorded. */
recorded: z.number().int().min(0).max(100_000),
unconverted: z.object({
entries: z.number().int().min(0).max(100_000),
currencies: z.array(cardCurrencySchema).max(6),
}),
});
export type SettlementCard = z.infer<typeof settlementCardSchema>;