mirror of
https://github.com/mauriceboe/TREK.git
synced 2026-11-21 19:40:34 +00:00
6d6efddc4e
- list_budget_items lists a trip's expenses with their ids, payers and splits, page by page so no page is cut down on its way to a model; get_budget_per_person answers who paid and owes what. Both in a new budget-items.mcp.ts, checked like their REST twins. - get_wind_forecast reads the hourly wind, gusts and direction of a day. - get_journey_tracks lists a journey's GPX tracks; the line for drawing rides under a key the provider never receives. - The Dawarich wishlist scan and the countries the recordings suggest become tools, with their confirming writes, in DawarichAtlasMcp in the Atlas group; the shared time window check refuses alike on REST and MCP, and the model never sees when the user was last seen in a city. - The journal's map, tracks and recorded days load with the journey group instead of riding in the core of every step. - The prompt points at list_budget_items for expense ids (the trip summary never carried them) and names the shares and the wind tools; each new read has its own live step.
451 lines
19 KiB
TypeScript
451 lines
19 KiB
TypeScript
import { idSchema } from '../common/primitives.schema';
|
|
|
|
import { z } from 'zod';
|
|
|
|
/**
|
|
* Budget API contract — single source of truth for the /api/trips/:tripId/budget
|
|
* endpoints (expense items, per-member splits, paid toggles, settlement).
|
|
*
|
|
* Trip-scoped: every endpoint verifies trip access (404 "Trip not found") and
|
|
* mutations check the 'budget_edit' permission (403 "No permission"). The legacy
|
|
* route (server/src/routes/budget.ts) wraps services/budgetService.ts; rows are
|
|
* DB-shaped and kept open. Mutations broadcast over WebSocket with the forwarded
|
|
* X-Socket-Id. Updating a linked item's total_price also syncs the price into the
|
|
* linked reservation's metadata (and broadcasts reservation:updated).
|
|
*/
|
|
|
|
/**
|
|
* Budget item member as embedded on a budget item
|
|
* (server/src/services/budgetService.ts -> loadItemMembers). `paid` is the raw
|
|
* SQLite INTEGER (0/1); `avatar_url` is the resolved avatar (avatarUrl()).
|
|
*/
|
|
export const budgetItemMemberSchema = z.object({
|
|
user_id: z.number(),
|
|
paid: z.number(),
|
|
username: z.string(),
|
|
avatar_url: z.string().nullable().optional(),
|
|
avatar: z.string().nullable().optional(),
|
|
budget_item_id: z.number().optional(),
|
|
amount: z.number().nullable().optional(),
|
|
});
|
|
export type BudgetItemMember = z.infer<typeof budgetItemMemberSchema>;
|
|
|
|
/**
|
|
* The fixed "Costs" expense categories. Unlike the old budget, users cannot
|
|
* create their own categories — every expense maps to one of these keys. The
|
|
* label/icon/colour per key live in the client; the server only stores the key.
|
|
* Pre-rework rows used free-text categories; those are shown as `other`.
|
|
*/
|
|
export const COST_CATEGORIES = [
|
|
'accommodation',
|
|
'food',
|
|
'groceries',
|
|
'transport',
|
|
'flights',
|
|
'activities',
|
|
'sightseeing',
|
|
'shopping',
|
|
'fees',
|
|
'health',
|
|
'tips',
|
|
'fuel',
|
|
'parking',
|
|
'other',
|
|
] as const;
|
|
export type CostCategory = (typeof COST_CATEGORIES)[number];
|
|
|
|
/**
|
|
* Maps a reservation `type` (flight, train, hotel, …) to one of the fixed Costs
|
|
* categories, so an expense created from a booking lands in the right bucket
|
|
* instead of a free-text/localized label. Unknown types fall back to `other`.
|
|
*/
|
|
const RESERVATION_TYPE_TO_COST_CATEGORY: Record<string, CostCategory> = {
|
|
flight: 'flights',
|
|
plane: 'flights',
|
|
train: 'transport',
|
|
bus: 'transport',
|
|
car: 'transport',
|
|
'car-rental': 'transport',
|
|
ferry: 'transport',
|
|
boat: 'transport',
|
|
taxi: 'transport',
|
|
transfer: 'transport',
|
|
transport: 'transport',
|
|
hotel: 'accommodation',
|
|
accommodation: 'accommodation',
|
|
lodging: 'accommodation',
|
|
parking: 'parking',
|
|
restaurant: 'food',
|
|
activity: 'activities',
|
|
};
|
|
|
|
export function typeToCostCategory(type: string | null | undefined): CostCategory {
|
|
if (!type) return 'other';
|
|
return RESERVATION_TYPE_TO_COST_CATEGORY[type.trim().toLowerCase()] || 'other';
|
|
}
|
|
|
|
/**
|
|
* One payer of an expense — a row of budget_item_payers. `amount` is in the
|
|
* expense's own currency (budget_items.currency). Several payers can split who
|
|
* actually paid one bill. Username/avatar are joined for display.
|
|
*/
|
|
export const budgetItemPayerSchema = z.object({
|
|
user_id: z.number(),
|
|
amount: z.number(),
|
|
username: z.string().optional(),
|
|
avatar_url: z.string().nullable().optional(),
|
|
avatar: z.string().nullable().optional(),
|
|
budget_item_id: z.number().optional(),
|
|
});
|
|
export type BudgetItemPayer = z.infer<typeof budgetItemPayerSchema>;
|
|
|
|
export const budgetItemReceiptSchema = z.object({
|
|
id: z.number(),
|
|
filename: z.string(),
|
|
original_name: z.string(),
|
|
file_size: z.number().nullable().optional(),
|
|
mime_type: z.string().nullable().optional(),
|
|
url: z.string(),
|
|
});
|
|
export type BudgetItemReceipt = z.infer<typeof budgetItemReceiptSchema>;
|
|
|
|
/**
|
|
* Budget item entity as returned by the budget list/create/update endpoints
|
|
* (server/src/services/budgetService.ts). Columns of the `budget_items` table
|
|
* plus the embedded `members` (equal-split participants), `payers` and `receipts` arrays.
|
|
* total_price is the sum of payer amounts in `currency`; `exchange_rate` converts
|
|
* that to the trip base currency (NULL currency + rate 1 = base currency).
|
|
* On a row in another currency, rate 1 means the rate was never frozen: the
|
|
* server converts it with today's rate, and without one leaves it out of every
|
|
* figure and lists it under the settlement's `unconverted`.
|
|
*/
|
|
export const budgetItemSchema = z.object({
|
|
id: z.number(),
|
|
trip_id: z.number(),
|
|
category: z.string(),
|
|
name: z.string(),
|
|
total_price: z.number(),
|
|
currency: z.string().nullable().optional(),
|
|
exchange_rate: z.number().optional(),
|
|
persons: z.number().nullable().optional(),
|
|
days: z.number().nullable().optional(),
|
|
note: z.string().nullable().optional(),
|
|
/** Itemized receipt behind a per-item split, as JSON. Its own column since #1658. */
|
|
ticket_json: z.string().nullable().optional(),
|
|
reservation_id: z.number().nullable().optional(),
|
|
/** Set when the expense was created from a place (#1298) — the same link
|
|
* reservation_id is for a booking, on the other side of the planner. */
|
|
place_id: z.number().nullable().optional(),
|
|
paid_by_user_id: z.number().nullable().optional(),
|
|
expense_date: z.string().nullable().optional(),
|
|
sort_order: z.number().optional(),
|
|
created_at: z.string().optional(),
|
|
members: z.array(budgetItemMemberSchema).optional(),
|
|
payers: z.array(budgetItemPayerSchema).optional(),
|
|
receipts: z.array(budgetItemReceiptSchema).optional(),
|
|
});
|
|
export type BudgetItem = z.infer<typeof budgetItemSchema>;
|
|
|
|
const payerInputSchema = z.object({
|
|
user_id: z.number(),
|
|
amount: z.number(),
|
|
});
|
|
|
|
const memberInputSchema = z.object({
|
|
user_id: z.number(),
|
|
amount: z.number().nullable().optional(),
|
|
});
|
|
|
|
const currencyCodeSchema = z.string().regex(/^[A-Z]{3}$/);
|
|
|
|
/**
|
|
* A rate table the caller already holds (the client's cached rates), lent to the
|
|
* server for a write. `rates` are units of each currency per 1 `base`, which is
|
|
* how a frozen `exchange_rate` reads when `base` is the trip currency.
|
|
*
|
|
* The server uses a rate from here only for a currency it cannot quote itself,
|
|
* and only while `base` is the trip's current currency; its own rate always wins,
|
|
* and a rate already frozen or sent as `exchange_rate` is never replaced.
|
|
*/
|
|
export const budgetFallbackFxSchema = z.object({
|
|
base: currencyCodeSchema,
|
|
rates: z.record(currencyCodeSchema, z.number().finite().min(1e-9).max(1e9)).refine(
|
|
(rates) => {
|
|
const n = Object.keys(rates).length;
|
|
return n >= 1 && n <= 200;
|
|
},
|
|
{ message: 'rates must hold between 1 and 200 currencies' },
|
|
),
|
|
});
|
|
export type BudgetFallbackFx = z.infer<typeof budgetFallbackFxSchema>;
|
|
|
|
export const budgetCreateItemRequestSchema = z.object({
|
|
name: z.string().min(1),
|
|
category: z.string().optional(),
|
|
total_price: z.number().optional(),
|
|
currency: z.string().nullable().optional(),
|
|
exchange_rate: z.number().optional(),
|
|
// Multi-payer: who paid how much (in the expense currency). When omitted, the
|
|
// server falls back to total_price with no explicit payer.
|
|
payers: z.array(payerInputSchema).optional(),
|
|
// Equal-split participants. When omitted, the item has no split (planning-only).
|
|
member_ids: z.array(z.number()).optional(),
|
|
members: z.array(memberInputSchema).optional(),
|
|
persons: z.number().nullable().optional(),
|
|
days: z.number().nullable().optional(),
|
|
note: z.string().nullable().optional(),
|
|
ticket_json: z.string().nullable().optional(),
|
|
expense_date: z.string().nullable().optional(),
|
|
// Link this expense to a reservation (e.g. created from a booking's
|
|
// "add expense" flow). The server stores it on budget_items.reservation_id.
|
|
reservation_id: z.number().optional(),
|
|
// The same for a place: the place form's "add expense" flow saves the place
|
|
// first, then creates the expense against it (#1298).
|
|
place_id: z.number().optional(),
|
|
// Receipt files to link to this expense
|
|
receipt_file_ids: z.array(z.number()).optional(),
|
|
// Rates to freeze a foreign currency with when the server has none of its own.
|
|
fallback_fx: budgetFallbackFxSchema.optional(),
|
|
});
|
|
export type BudgetCreateItemRequest = z.infer<typeof budgetCreateItemRequestSchema>;
|
|
|
|
/** Update accepts the same fields plus total_price changes; all optional. */
|
|
export const budgetUpdateItemRequestSchema = z.object({
|
|
name: z.string().optional(),
|
|
category: z.string().optional(),
|
|
total_price: z.number().optional(),
|
|
currency: z.string().nullable().optional(),
|
|
exchange_rate: z.number().optional(),
|
|
payers: z.array(payerInputSchema).optional(),
|
|
member_ids: z.array(z.number()).optional(),
|
|
members: z.array(memberInputSchema).optional(),
|
|
persons: z.number().nullable().optional(),
|
|
days: z.number().nullable().optional(),
|
|
note: z.string().nullable().optional(),
|
|
ticket_json: z.string().nullable().optional(),
|
|
expense_date: z.string().nullable().optional(),
|
|
receipt_file_ids: z.array(z.number()).optional(),
|
|
// Link an existing expense to a booking or a place on the same trip (#2084);
|
|
// null lets go of the link and keeps the expense. Omitted leaves it as is.
|
|
reservation_id: z.number().int().positive().nullable().optional(),
|
|
place_id: z.number().int().positive().nullable().optional(),
|
|
fallback_fx: budgetFallbackFxSchema.optional(),
|
|
});
|
|
export type BudgetUpdateItemRequest = z.infer<typeof budgetUpdateItemRequestSchema>;
|
|
|
|
/** Replace the explicit payers of an expense (amounts in expense currency). */
|
|
export const budgetUpdatePayersRequestSchema = z.object({
|
|
payers: z.array(payerInputSchema),
|
|
});
|
|
export type BudgetUpdatePayersRequest = z.infer<typeof budgetUpdatePayersRequestSchema>;
|
|
|
|
/**
|
|
* A persisted settle-up transfer (budget_settlements row): "from paid to" a
|
|
* given amount, entered in the payer's display `currency`. `exchange_rate` is the
|
|
* live rate frozen at settle time (units of that currency per 1 trip currency), so
|
|
* a settled position stays balanced when live rates drift (#1445). Legacy rows
|
|
* have currency = null / exchange_rate = 1 and convert with live rates. A row in
|
|
* another currency with rate 1 was never frozen: without a live rate it is left
|
|
* out of the balances and listed under the settlement's `unconverted`. Creating
|
|
* one marks a suggested flow as paid; deleting it (undo) brings the flow back.
|
|
*/
|
|
export const budgetSettlementSchema = z.object({
|
|
id: z.number(),
|
|
trip_id: z.number(),
|
|
from_user_id: z.number(),
|
|
to_user_id: z.number(),
|
|
amount: z.number(),
|
|
currency: z.string().nullable().optional(),
|
|
exchange_rate: z.number().optional(),
|
|
created_at: z.string().optional(),
|
|
// The calendar day the transfer actually happened (YYYY-MM-DD), independent of
|
|
// `created_at` (when it was recorded) — same split as budget_items' expense_date
|
|
// vs. created_at. Null/absent on rows recorded before this column existed; the
|
|
// ledger falls back to `created_at`'s date for those.
|
|
settled_at: z.string().nullable().optional(),
|
|
// A free-text note on the payment (#2340). Null when none was written.
|
|
note: z.string().nullable().optional(),
|
|
created_by_user_id: z.number().nullable().optional(),
|
|
from_username: z.string().optional(),
|
|
from_avatar_url: z.string().nullable().optional(),
|
|
to_username: z.string().optional(),
|
|
to_avatar_url: z.string().nullable().optional(),
|
|
});
|
|
export type BudgetSettlement = z.infer<typeof budgetSettlementSchema>;
|
|
|
|
export const budgetCreateSettlementRequestSchema = z.object({
|
|
from_user_id: z.number(),
|
|
to_user_id: z.number(),
|
|
amount: z.number(),
|
|
// The display currency the amount was entered in; the server freezes its FX rate.
|
|
currency: z.string().nullable().optional(),
|
|
// The day the transfer happened. Null when the caller sets none; the ledger then
|
|
// uses the day it was recorded, which is where every older payment already sits.
|
|
settled_at: z.string().nullable().optional(),
|
|
// A free-text note on the payment (#2340); blank stores none.
|
|
note: z.string().max(500).nullable().optional(),
|
|
// Rates to freeze `currency` with when the server has none of its own.
|
|
fallback_fx: budgetFallbackFxSchema.optional(),
|
|
});
|
|
export type BudgetCreateSettlementRequest = z.infer<typeof budgetCreateSettlementRequestSchema>;
|
|
|
|
/** Edit a persisted settle-up transfer (same fields as create; full replace). */
|
|
export const budgetUpdateSettlementRequestSchema = z.object({
|
|
from_user_id: z.number(),
|
|
to_user_id: z.number(),
|
|
amount: z.number(),
|
|
currency: z.string().nullable().optional(),
|
|
settled_at: z.string().nullable().optional(),
|
|
// Omitted leaves the note as it is; null or blank clears it (#2340).
|
|
note: z.string().max(500).nullable().optional(),
|
|
fallback_fx: budgetFallbackFxSchema.optional(),
|
|
});
|
|
export type BudgetUpdateSettlementRequest = z.infer<typeof budgetUpdateSettlementRequestSchema>;
|
|
|
|
/**
|
|
* POST …/budget/freeze-rates: pin a rate on every row in a foreign currency that
|
|
* has none frozen yet, not only the rows the settlement lists under `unconverted`
|
|
* but also those it still converts at today's rate. The server's own rate comes
|
|
* first; `fallback_fx` only fills a currency it cannot quote. A row that is frozen,
|
|
* in the trip currency or without a currency is never touched, so a second call
|
|
* never moves a rate the first one froze.
|
|
*/
|
|
export const budgetFreezeRatesRequestSchema = z.object({
|
|
fallback_fx: budgetFallbackFxSchema.optional(),
|
|
});
|
|
export type BudgetFreezeRatesRequest = z.infer<typeof budgetFreezeRatesRequestSchema>;
|
|
|
|
/** The rows the call froze, and the currencies no rate was found for. */
|
|
export const budgetFreezeRatesResponseSchema = z.object({
|
|
items: z.array(budgetItemSchema),
|
|
settlements: z.array(budgetSettlementSchema),
|
|
unresolved: z.array(z.string()),
|
|
});
|
|
export type BudgetFreezeRatesResponse = z.infer<typeof budgetFreezeRatesResponseSchema>;
|
|
|
|
/**
|
|
* GET …/budget/settlement query. `base` is the display currency. `base_rate` is
|
|
* units of it per 1 trip currency, from the caller's own rates; the server uses
|
|
* it only when it cannot quote that pair itself, and then only in place of the
|
|
* missing display quote. That quote also reads a legacy transfer without a
|
|
* currency, which is taken to be in the display currency, as with a live quote.
|
|
*/
|
|
export const budgetSettlementQuerySchema = z.object({
|
|
base: z.string().optional(),
|
|
base_rate: z.coerce.number().finite().min(1e-9).max(1e9).optional(),
|
|
});
|
|
export type BudgetSettlementQuery = z.infer<typeof budgetSettlementQuerySchema>;
|
|
|
|
/**
|
|
* What the settlement left out because no rate could convert it: expenses and
|
|
* transfers in a foreign currency with no frozen rate, while no live rate for
|
|
* that currency is to be had. Such a row counts in none of the figures, so the
|
|
* balances still add up to zero. `currencies` are upper case, deduplicated and
|
|
* sorted. The settlement also says which `currency` its amounts are in: the
|
|
* display currency asked for, or the trip currency when that one cannot be
|
|
* quoted.
|
|
*/
|
|
export const budgetUnconvertedSchema = z.object({
|
|
item_ids: z.array(idSchema),
|
|
settlement_ids: z.array(idSchema),
|
|
currencies: z.array(z.string()),
|
|
});
|
|
export type BudgetUnconverted = z.infer<typeof budgetUnconvertedSchema>;
|
|
|
|
/**
|
|
* What the trip actually costs one participant, as GET …/budget/settlement
|
|
* returns it alongside the balances and the suggested flows.
|
|
*
|
|
* `final = expenses - reimbursed - pending`, and the identity holds to the cent
|
|
* in whatever display currency was asked for: the server derives all four
|
|
* figures from the one integer-cent ledger the balances come from, so a
|
|
* breakdown can never disagree with the balance shown next to it. Every amount
|
|
* is in that display currency.
|
|
*
|
|
* A participant who fronted nothing and owes nothing is absent, exactly like
|
|
* they are from `balances` — a client listing the trip's roster fills the gap
|
|
* with zeroes rather than expecting a row per member.
|
|
*
|
|
* `sources` lists the rows each of the three figures is made of, in whole cents
|
|
* of the same display currency. The server spreads a figure over its rows with
|
|
* the same largest-remainder split the figure itself came from, so every list
|
|
* sums to its figure exactly; a client that converted the expense list on its
|
|
* own, with whatever rate it has today, would not land on the same number.
|
|
*/
|
|
export const budgetParticipantFinalSchema = z.object({
|
|
user_id: z.number(),
|
|
username: z.string(),
|
|
avatar_url: z.string().nullable(),
|
|
/** Gross outlay: what this participant fronted as a payer on split expenses. */
|
|
expenses: z.number(),
|
|
/** Recorded settle-up transfers, netted: received minus sent. */
|
|
reimbursed: z.number(),
|
|
/** Still to be squared up — the participant's current balance, positive when owed. */
|
|
pending: z.number(),
|
|
/** What the trip leaves them out of pocket once everything has been settled. */
|
|
final: z.number(),
|
|
sources: z.object({
|
|
/** Per expense they paid on: what they fronted, negative for a refund they received. Σ = expenses. */
|
|
fronted: z.array(z.object({ item_id: z.number(), cents: z.number().int() })),
|
|
/** Per recorded transfer on their side: positive when received, negative when sent. Σ = reimbursed. */
|
|
moved: z.array(
|
|
z.object({
|
|
settlement_id: z.number(),
|
|
from_user_id: z.number(),
|
|
to_user_id: z.number(),
|
|
cents: z.number().int(),
|
|
}),
|
|
),
|
|
/** Per suggested flow on their side: positive when it comes to them, negative when they owe it. Σ = pending. */
|
|
outstanding: z.array(z.object({ from_user_id: z.number(), to_user_id: z.number(), cents: z.number().int() })),
|
|
}),
|
|
});
|
|
export type BudgetParticipantFinal = z.infer<typeof budgetParticipantFinalSchema>;
|
|
|
|
export const budgetUpdateMembersRequestSchema = z.object({
|
|
user_ids: z.array(z.number()),
|
|
});
|
|
export type BudgetUpdateMembersRequest = z.infer<typeof budgetUpdateMembersRequestSchema>;
|
|
|
|
export const budgetToggleMemberPaidRequestSchema = z.object({
|
|
paid: z.boolean(),
|
|
});
|
|
export type BudgetToggleMemberPaidRequest = z.infer<typeof budgetToggleMemberPaidRequestSchema>;
|
|
|
|
export const budgetReorderItemsRequestSchema = z.object({
|
|
orderedIds: z.array(z.number()),
|
|
});
|
|
export type BudgetReorderItemsRequest = z.infer<typeof budgetReorderItemsRequestSchema>;
|
|
|
|
export const budgetReorderCategoriesRequestSchema = z.object({
|
|
orderedCategories: z.array(z.string()),
|
|
});
|
|
export type BudgetReorderCategoriesRequest = z.infer<typeof budgetReorderCategoriesRequestSchema>;
|
|
|
|
/** How many expenses one page of the MCP expense list holds when the caller does not say. */
|
|
export const BUDGET_ITEMS_PAGE_DEFAULT = 50;
|
|
const BUDGET_ITEMS_PAGE_MAX = 100;
|
|
|
|
/**
|
|
* One page of the expense list an MCP client reads (list_budget_items): the
|
|
* expenses in their list order from `offset`, at most `limit` of them. A
|
|
* budget of a few hundred rows is too long for one answer to a model, so it
|
|
* pages; the totals next to the page always cover the whole trip.
|
|
*/
|
|
export const budgetItemsPageSchema = z.object({
|
|
offset: z
|
|
.number()
|
|
.int()
|
|
.min(0)
|
|
.optional()
|
|
.describe('How many expenses to skip: the next_offset of the page before (default 0)'),
|
|
limit: z
|
|
.number()
|
|
.int()
|
|
.min(1)
|
|
.max(BUDGET_ITEMS_PAGE_MAX)
|
|
.optional()
|
|
.describe(`How many expenses at most (default ${BUDGET_ITEMS_PAGE_DEFAULT}, at most ${BUDGET_ITEMS_PAGE_MAX})`),
|
|
});
|
|
export type BudgetItemsPage = z.infer<typeof budgetItemsPageSchema>;
|