mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-21 03:26:07 +00:00
feat(assistant): expense, payment and settle-up cards, and expense links into Costs
This commit is contained in:
@@ -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>;
|
||||
|
||||
@@ -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>;
|
||||
|
||||
@@ -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>;
|
||||
|
||||
@@ -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>;
|
||||
|
||||
Reference in New Issue
Block a user