feat(domain): add core types and zod schemas

src/lib/domain/schemas.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+
+export const USERNAME_RE = /^[a-z0-9_.-]{3,32}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+export function isValidDate(s: string): boolean {
+	if (!DATE_RE.test(s)) return false;
+	const d = new Date(`${s}T00:00:00Z`);
+	return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === s;
+}
+
+export const DateString = z.string().refine(isValidDate, 'Invalid date');
+export const IsoTimestamp = z.string().refine((s) => !Number.isNaN(Date.parse(s)), 'Invalid timestamp');
+export const Cents = z.number().int().positive();
+export const UserId = z.string().min(1);
+
+export const UserSchema = z.object({
+	id: UserId,
+	username: z.string().regex(USERNAME_RE),
+	displayName: z.string().trim().min(1).max(120),
+	passwordHash: z.string().min(1),
+	role: z.enum(['admin', 'member']),
+	active: z.boolean(),
+	mustChangePassword: z.boolean(),
+	sessionVersion: z.number().int().nonnegative(),
+	createdAt: IsoTimestamp,
+	updatedAt: IsoTimestamp
+});
+
+export const SplitSchema = z.discriminatedUnion('mode', [
+	z.object({ mode: z.literal('equal'), participants: z.array(UserId).min(1) }),
+	z.object({ mode: z.literal('percent'), bp: z.record(UserId, z.number().int().positive()) }),
+	z.object({ mode: z.literal('exact'), cents: z.record(UserId, Cents) })
+]);
+
+const AuditSchema = {
+	createdBy: UserId,
+	createdAt: IsoTimestamp,
+	updatedBy: UserId,
+	updatedAt: IsoTimestamp
+};
+
+export const ExpensePhotoSchema = z.object({
+	key: z.string().min(1),
+	contentType: z.string().min(1),
+	width: z.number().int().positive().optional(),
+	height: z.number().int().positive().optional()
+});
+
+export const ExpenseSchema = z.object({
+	id: z.string().min(1),
+	version: z.number().int().positive(),
+	description: z.string().trim().min(1).max(120),
+	amountCents: Cents,
+	currency: z.string().length(3),
+	date: DateString,
+	paidBy: UserId,
+	split: SplitSchema,
+	shares: z.record(UserId, Cents),
+	photo: ExpensePhotoSchema.optional(),
+	notes: z.string().max(2000).optional(),
+	...AuditSchema
+});
+
+export const SettlementSchema = z
+	.object({
+		id: z.string().min(1),
+		version: z.number().int().positive(),
+		from: UserId,
+		to: UserId,
+		amountCents: Cents,
+		date: DateString,
+		note: z.string().max(2000).optional(),
+		...AuditSchema
+	})
+	.refine((s) => s.from !== s.to, { message: 'from and to must differ', path: ['to'] });
+
+export const UsersFileSchema = z.object({
+	version: z.literal(1),
+	users: z.array(UserSchema)
+});
+export type UsersFile = z.infer<typeof UsersFileSchema>;

src/lib/domain/types.ts

@@ -1,3 +1,81 @@
+export type Role = 'admin' | 'member';
+
 export interface User {
 	id: string;
+	username: string;
+	displayName: string;
+	passwordHash: string;
+	role: Role;
+	active: boolean;
+	mustChangePassword: boolean;
+	sessionVersion: number;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export type PublicUser = Omit<User, 'passwordHash'>;
+
+export function toPublicUser(u: User): PublicUser {
+	const { passwordHash: _omit, ...rest } = u;
+	return rest;
+}
+
+export type Split =
+	| { mode: 'equal'; participants: string[] }
+	| { mode: 'percent'; bp: Record<string, number> }
+	| { mode: 'exact'; cents: Record<string, number> };
+
+export type SplitMode = Split['mode'];
+
+export interface ExpensePhoto {
+	key: string;
+	contentType: string;
+	width?: number;
+	height?: number;
+}
+
+export interface AuditFields {
+	createdBy: string;
+	createdAt: string;
+	updatedBy: string;
+	updatedAt: string;
+}
+
+export interface Expense extends AuditFields {
+	id: string;
+	version: number;
+	description: string;
+	amountCents: number;
+	currency: string;
+	date: string;
+	paidBy: string;
+	split: Split;
+	shares: Record<string, number>;
+	photo?: ExpensePhoto;
+	notes?: string;
+}
+
+export interface Settlement extends AuditFields {
+	id: string;
+	version: number;
+	from: string;
+	to: string;
+	amountCents: number;
+	date: string;
+	note?: string;
+}
+
+/** Everything the caller supplies; id/version/audit fields are added by the Ledger. */
+export type ExpenseBody = Omit<Expense, 'id' | 'version' | keyof AuditFields>;
+export type SettlementBody = Omit<Settlement, 'id' | 'version' | keyof AuditFields>;
+
+export function splitParticipants(split: Split): string[] {
+	switch (split.mode) {
+		case 'equal':
+			return [...split.participants];
+		case 'percent':
+			return Object.keys(split.bp);
+		case 'exact':
+			return Object.keys(split.cents);
+	}
 }

tests/unit/domain/schemas.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import { ExpenseSchema, SettlementSchema, UserSchema } from '../../../src/lib/domain/schemas';
+
+const baseExpense = {
+	id: 'e_01HZX',
+	version: 1,
+	description: 'Dinner',
+	amountCents: 3000,
+	currency: 'USD',
+	date: '2026-08-29',
+	paidBy: 'u_a',
+	split: { mode: 'equal', participants: ['u_a', 'u_b'] },
+	shares: { u_a: 1500, u_b: 1500 },
+	createdBy: 'u_a',
+	createdAt: '2026-08-29T10:00:00.000Z',
+	updatedBy: 'u_a',
+	updatedAt: '2026-08-29T10:00:00.000Z'
+};
+
+describe('ExpenseSchema', () => {
+	it('accepts a valid equal-split expense', () => {
+		expect(ExpenseSchema.parse(baseExpense)).toEqual(baseExpense);
+	});
+
+	it('rejects non-integer or non-positive amounts', () => {
+		expect(ExpenseSchema.safeParse({ ...baseExpense, amountCents: 12.5 }).success).toBe(false);
+		expect(ExpenseSchema.safeParse({ ...baseExpense, amountCents: 0 }).success).toBe(false);
+	});
+
+	it('rejects malformed dates', () => {
+		expect(ExpenseSchema.safeParse({ ...baseExpense, date: '2026-13-01' }).success).toBe(false);
+		expect(ExpenseSchema.safeParse({ ...baseExpense, date: '29/08/2026' }).success).toBe(false);
+	});
+
+	it('accepts percent and exact splits', () => {
+		const pct = { ...baseExpense, split: { mode: 'percent', bp: { u_a: 5000, u_b: 5000 } } };
+		const exact = { ...baseExpense, split: { mode: 'exact', cents: { u_a: 1000, u_b: 2000 } } };
+		expect(ExpenseSchema.safeParse(pct).success).toBe(true);
+		expect(ExpenseSchema.safeParse(exact).success).toBe(true);
+	});
+
+	it('rejects unknown split modes', () => {
+		expect(ExpenseSchema.safeParse({ ...baseExpense, split: { mode: 'random' } }).success).toBe(false);
+	});
+});
+
+describe('SettlementSchema', () => {
+	it('rejects from === to', () => {
+		const s = {
+			id: 's_1', version: 1, from: 'u_a', to: 'u_a', amountCents: 100, date: '2026-08-29',
+			createdBy: 'u_a', createdAt: '2026-08-29T10:00:00.000Z', updatedBy: 'u_a', updatedAt: '2026-08-29T10:00:00.000Z'
+		};
+		expect(SettlementSchema.safeParse(s).success).toBe(false);
+		expect(SettlementSchema.safeParse({ ...s, to: 'u_b' }).success).toBe(true);
+	});
+});
+
+describe('UserSchema', () => {
+	it('enforces username charset and length', () => {
+		const u = {
+			id: 'u_1', username: 'bob', displayName: 'Bob', passwordHash: 'x', role: 'member', active: true,
+			mustChangePassword: false, sessionVersion: 1, createdAt: '2026-08-29T10:00:00.000Z', updatedAt: '2026-08-29T10:00:00.000Z'
+		};
+		expect(UserSchema.safeParse(u).success).toBe(true);
+		expect(UserSchema.safeParse({ ...u, username: 'Bo' }).success).toBe(false);
+		expect(UserSchema.safeParse({ ...u, username: 'bob smith' }).success).toBe(false);
+	});
+});