/** * A workout entered by hand: the form's draft, its validation, and the one * batch entry it becomes. * * HealthLog records workouts; it does not plan them. So the hand-entered * shape is the session as a health record sees it and nothing more: what, * when, how long, and optionally how far and how much energy. No sets, no * exercises, no heart rate typed in from memory. * * The entry is written through `POST /api/workouts/batch`, the same route the * phone syncs through, as `source: "MANUAL"` with an `externalId` minted once * per opened form. That id is what makes a double submit (a second tap, a * retried request) a `duplicate` instead of a second row: the route's * `(userId, source, externalId)` key catches it. * * Pure, no React and no fetch, so the rules are pinned without a browser. * Error values are i18n keys; the form translates them. */ import { z } from "zod/v4"; import { getQuantityTransform, invertDisplayTransform, type UnitPreference, } from "@/lib/measurements/display-transform"; import { wallClockInTz, zonedWallClockToUtc } from "@/lib/tz/wall-clock"; import { workoutSportTypeEnum, type WorkoutSportType, } from "@/lib/validations/workout"; import { randomId } from "@/lib/random-id"; import { isSurfaceVisible, type SurfaceModuleMap } from "@/lib/modules/surface"; /** One session is at most a day long. */ export const MANUAL_WORKOUT_MAX_DURATION_SEC = 24 * 60 * 60; /** The batch schema's own ceiling: 1000 km. */ export const MANUAL_WORKOUT_MAX_DISTANCE_M = 1_000_000; /** A day of hard endurance work stays well under this. */ export const MANUAL_WORKOUT_MAX_ENERGY_KCAL = 20_000; /** * Slack on "not in the future". The form's default start is the minute the * sheet opened, and the clock keeps moving while the person types. */ const FUTURE_TOLERANCE_MS = 60_000; export interface ManualWorkoutDraft { /** Empty until the person picks one. */ sportType: WorkoutSportType | ""; /** Wall clock in the profile timezone, `yyyy-MM-ddTHH:mm`. */ start: string; hours: string; minutes: string; /** In the reader's unit (km or mi). Empty means not recorded. */ distance: string; /** Kilocalories. Empty means not recorded. */ energyKcal: string; } export type ManualWorkoutField = "sportType" | "start" | "duration" | "distance" | "energyKcal"; /** The one entry of the `POST /api/workouts/batch` body this form sends. */ export interface ManualWorkoutEntry { sportType: WorkoutSportType; startedAt: string; endedAt: string; source: "MANUAL"; externalId: string; totalDistanceM?: number; totalEnergyKcal?: number; } export interface ManualWorkoutContext { /** The profile timezone the start is read in. */ timezone: string; unitPreference: UnitPreference; /** The id this form instance sends with every submit. */ externalId: string; now: Date; } export type ManualWorkoutResult = | { ok: true; entry: ManualWorkoutEntry } | { ok: false; errors: Partial> }; const ERR = "insights.workouts.manual.errors"; /** * Whether "Log workout" is offered: in one's own record, with the workouts * module on. * * Own record only because the route behind it is: the batch ingest resolves * the caller (`requireAuth`), and a delegate acting on somebody else's record * would be refused, so no section of a grant can admit it. The module half is * the `capture:workout` surface; an absent module map (the account still * loading) offers it, the gate's default-on contract. * * The workouts page asks this; the dashboard add menu and the capture picker * ask `visibleCaptureKinds`, which applies the same two terms to the * `workout` kind. */ export function canLogWorkout( caps: { inSharedRecord: boolean }, modules?: SurfaceModuleMap | null, ): boolean { return !caps.inSharedRecord && isSurfaceVisible("capture:workout", modules); } /** A fresh id for one opened form. The prefix says where the row came from. */ export function newManualWorkoutExternalId(): string { return `manual:${randomId()}`; } /** `now` as the wall clock the start field shows, `yyyy-MM-ddTHH:mm`. */ export function wallClockNow(now: Date, timezone: string): string { const p = wallClockInTz(now, timezone); const pad = (n: number) => String(n).padStart(2, "0"); return `${p.year}-${pad(p.month)}-${pad(p.day)}T${pad(p.hour)}:${pad(p.minute)}`; } export function emptyManualWorkoutDraft(): ManualWorkoutDraft { return { sportType: "", // Blank on purpose (#1085): a blank start means "it just ended", so the // workout is saved as starting `duration` before now. start: "", hours: "", minutes: "", distance: "", energyKcal: "", }; } const WALL_CLOCK = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/; function startToUtc(start: string, timezone: string): Date | null { const m = WALL_CLOCK.exec(start); if (!m) return null; const [year, month, day, hour, minute] = m.slice(1).map(Number) as [ number, number, number, number, number, ]; if (month < 1 || month > 12 || day < 1 || day > 31) return null; if (hour > 23 || minute > 59) return null; const at = zonedWallClockToUtc({ year, month, day, hour, minute }, timezone); return Number.isNaN(at.getTime()) ? null : at; } /** * A typed number, or `null` for an empty field, or `NaN` for garbage. * Accepts a decimal comma, which is what half the locales type. */ function parseDecimal(raw: string): number | null { const trimmed = raw.trim(); if (trimmed === "") return null; if (!/^\d+([.,]\d+)?$/.test(trimmed)) return Number.NaN; return Number(trimmed.replace(",", ".")); } function parseWhole(raw: string): number | null { const trimmed = raw.trim(); if (trimmed === "") return null; if (!/^\d+$/.test(trimmed)) return Number.NaN; return Number(trimmed); } /** * The draft, checked. Built per call because "not in the future" and the * unit conversion depend on the context. */ function manualWorkoutSchema(ctx: ManualWorkoutContext) { return z .object({ sportType: z.string(), start: z.string(), hours: z.string(), minutes: z.string(), distance: z.string(), energyKcal: z.string(), }) .superRefine((d, issue) => { if (!workoutSportTypeEnum.safeParse(d.sportType).success) { issue.addIssue({ code: "custom", path: ["sportType"], message: `${ERR}.sportRequired`, }); } const startBlank = d.start.trim() === ""; const startedAt = startBlank ? null : startToUtc(d.start, ctx.timezone); if (!startBlank && startedAt === null) { issue.addIssue({ code: "custom", path: ["start"], message: `${ERR}.startRequired`, }); } else if ( startedAt !== null && startedAt.getTime() > ctx.now.getTime() + FUTURE_TOLERANCE_MS ) { issue.addIssue({ code: "custom", path: ["start"], message: `${ERR}.startInFuture`, }); } const hours = parseWhole(d.hours); const minutes = parseWhole(d.minutes); if ( Number.isNaN(hours) || Number.isNaN(minutes) || (minutes !== null && minutes > 59) ) { issue.addIssue({ code: "custom", path: ["duration"], message: `${ERR}.durationInvalid`, }); } else { const sec = ((hours ?? 0) * 60 + (minutes ?? 0)) * 60; if (sec <= 0) { issue.addIssue({ code: "custom", path: ["duration"], message: `${ERR}.durationRequired`, }); } else if (sec > MANUAL_WORKOUT_MAX_DURATION_SEC) { issue.addIssue({ code: "custom", path: ["duration"], message: `${ERR}.durationTooLong`, }); } else if ( // Only a start the person entered can push the end past now; a // blank start is read as "now minus the duration". startedAt !== null && startedAt.getTime() + sec * 1000 > ctx.now.getTime() + FUTURE_TOLERANCE_MS ) { issue.addIssue({ code: "custom", path: ["duration"], message: `${ERR}.endInFuture`, }); } } const distance = parseDecimal(d.distance); if ( distance !== null && (Number.isNaN(distance) || toMetres(distance, ctx.unitPreference) > MANUAL_WORKOUT_MAX_DISTANCE_M) ) { issue.addIssue({ code: "custom", path: ["distance"], message: `${ERR}.distanceInvalid`, }); } const energy = parseDecimal(d.energyKcal); if ( energy !== null && (Number.isNaN(energy) || energy > MANUAL_WORKOUT_MAX_ENERGY_KCAL) ) { issue.addIssue({ code: "custom", path: ["energyKcal"], message: `${ERR}.energyInvalid`, }); } }); } /** A distance in the reader's unit, in metres to a tenth. */ function toMetres(display: number, preference: UnitPreference): number { const metres = invertDisplayTransform( display, getQuantityTransform("distance", preference), ); return Math.round(metres * 10) / 10; } /** * Validate the draft and build the batch entry from it, field by field. * Returns the first error per field when it does not validate. */ export function buildManualWorkoutEntry( draft: ManualWorkoutDraft, ctx: ManualWorkoutContext, ): ManualWorkoutResult { const parsed = manualWorkoutSchema(ctx).safeParse(draft); if (!parsed.success) { const errors: Partial> = {}; for (const issue of parsed.error.issues) { const field = issue.path[0] as ManualWorkoutField; errors[field] ??= issue.message; } return { ok: false, errors }; } // Every branch below was proven by the schema above. const durationSec = ((parseWhole(draft.hours) ?? 0) * 60 + (parseWhole(draft.minutes) ?? 0)) * 60; const startedAt = draft.start.trim() === "" ? new Date(ctx.now.getTime() - durationSec * 1000) : startToUtc(draft.start, ctx.timezone)!; const distance = parseDecimal(draft.distance); const energy = parseDecimal(draft.energyKcal); const entry: ManualWorkoutEntry = { sportType: draft.sportType as WorkoutSportType, startedAt: startedAt.toISOString(), endedAt: new Date(startedAt.getTime() + durationSec * 1000).toISOString(), source: "MANUAL", externalId: ctx.externalId, }; if (distance !== null) { entry.totalDistanceM = toMetres(distance, ctx.unitPreference); } if (energy !== null) entry.totalEnergyKcal = energy; return { ok: true, entry }; }