@tbs-fitness/contract 0.11.0 → 0.12.0

package/README.md

@@ -6,16 +6,18 @@ It is published as `@tbs-fitness/contract`. The package holds definitions only:
 
 ## What is in it
 
-| Import                                | Contents                                                                                                                                                                            |
-| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@tbs-fitness/contract/enums`         | `ROLES`, `PERMISSIONS`, `CSRF_COOKIE_NAMES`, `CSRF_HEADER`, `ACCOUNT_STATUSES`, `TOKEN_TRANSPORTS`, `AUDIT_OUTCOMES`, `APP_ENVIRONMENTS`, `FEATURE_FLAG_RULE_TYPES` and their types |
-| `@tbs-fitness/contract/common`        | Pagination, response envelopes (`{ data }`, `{ data, meta }`, `{ error }`), `emailSchema`, `phoneSchema`, `safeTextSchema`                                                          |
-| `@tbs-fitness/contract/auth`          | Login, sessions, password changes and resets, account administration                                                                                                                |
-| `@tbs-fitness/contract/client`        | Client sign-up, one-time code verification and resend, client sign-in and profile, password recovery                                                                                |
-| `@tbs-fitness/contract/coach`         | Coach sign-up, one-time code verification and resend, coach sign-in and profile, password recovery                                                                                  |
-| `@tbs-fitness/contract/audit`         | The audit log query and response                                                                                                                                                    |
-| `@tbs-fitness/contract/feature-flags` | Feature flag requests and responses                                                                                                                                                 |
-| `@tbs-fitness/contract/food`          | Food library, metadata, CSV/XLSX import, client food suggestions and their review, and the shared nutrition helpers                                                                 |
+| Import                                  | Contents                                                                                                                                                                            |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tbs-fitness/contract/enums`           | `ROLES`, `PERMISSIONS`, `CSRF_COOKIE_NAMES`, `CSRF_HEADER`, `ACCOUNT_STATUSES`, `TOKEN_TRANSPORTS`, `AUDIT_OUTCOMES`, `APP_ENVIRONMENTS`, `FEATURE_FLAG_RULE_TYPES` and their types |
+| `@tbs-fitness/contract/common`          | Pagination, response envelopes (`{ data }`, `{ data, meta }`, `{ error }`), `emailSchema`, `phoneSchema`, `safeTextSchema`                                                          |
+| `@tbs-fitness/contract/auth`            | Login, sessions, password changes and resets, account administration                                                                                                                |
+| `@tbs-fitness/contract/client`          | Client sign-up, one-time code verification and resend, client sign-in and profile, password recovery                                                                                |
+| `@tbs-fitness/contract/coach`           | Coach sign-up, one-time code verification and resend, coach sign-in and profile, password recovery                                                                                  |
+| `@tbs-fitness/contract/audit`           | The audit log query and response                                                                                                                                                    |
+| `@tbs-fitness/contract/feature-flags`   | Feature flag requests and responses                                                                                                                                                 |
+| `@tbs-fitness/contract/food`            | Food library, metadata, CSV/XLSX import, client food suggestions and their review, and the shared nutrition helpers                                                                 |
+| `@tbs-fitness/contract/meals`           | The meal library: meals of library foods with servings, and their totals                                                                                                            |
+| `@tbs-fitness/contract/nutrition-plans` | Nutrition plans: drafts, publishing, a client's active plan, the Snapshot step, and the builder's shared sums and publish rules                                                     |
 
 Each domain has its own entry point, so names only need to be unique within a domain. `auditLogResponseSchema`, for example, exists in both `/audit` and `/feature-flags`.
 
@@ -43,6 +45,17 @@ const result = createFlagSchema.safeParse(input); // The same rules as the API.
 
 Requests have two types. Clients use `*Input`, where fields with a default are optional. The backend uses `*Body`, which is the result after validation. List queries come from the URL as strings, so they have no `*Input`: use `Partial<PaginationQuery>` or `Partial<AuditLogQuery>`.
 
+## Version 0.12.0
+
+The meal library and nutrition plans for the Nutrition Plan Builder. Additive; consumers install `^0.12.0` explicitly.
+
+- New `/meals`: `createMealSchema`, `updateMealSchema` (with `version`), `mealListQuerySchema`, `mealResponseSchema` (items with per-serving values and totals), `foodPortionSchema`, `servingsSchema` (0.5 to 10 in half steps), `macroTotalsSchema`, `normalizeMealName`.
+- New `/nutrition-plans`:
+  - Requests: `createNutritionPlanSchema` (optional `fromPlanId`), `saveNutritionPlanSchema` (the whole plan with `version`; a half-built plan is valid), `publishNutritionPlanSchema` (`version`, optional `startsOn`), `nutritionPlanListQuerySchema`, `NUTRITION_PLAN_LIMITS`.
+  - Responses: `nutritionPlanResponseSchema` (with `dailyCalories`, `targets`, `dayTotals` and `publishIssues`), `currentNutritionPlansResponseSchema`, `nutritionPlanSummarySchema`, `clientNutritionPlanResponseSchema`, `nutritionPlanSnapshotResponseSchema`.
+  - Sums and rules shared with the builder: `NUTRITION_GUIDELINES`, `guidelineForGoalIcon`, `dailyCalories`, `macroTargets`, `recommendedWaterMl`, `defaultSlots`, `macroKcal`, `slotTargetKcal`, `addTotals`, `scaleTotals`, and `nutritionPlanPublishIssues` with `PUBLISH_ISSUE_CODES`.
+- `/enums`: `MEAL_SORT_FIELDS`, `NUTRITION_PLAN_STATUSES`, `PLAN_SLOT_KINDS`, `PLAN_PHASES`, `PLAN_BLOCK_WEEKS`, `CHEAT_MEAL_PERIODS`, `NUTRITION_GUIDELINE_IDS`, and the permissions `meals:read`, `meals:create`, `meals:update`, `meals:delete`, `nutrition_plans:read`, `nutrition_plans:write`, `nutrition_plans:publish` and `nutrition_plans:read:self`.
+
 ## Version 0.11.0
 
 Client onboarding and generic documents. Additive; consumers install `^0.11.0` explicitly.

package/dist/cjs/enums/index.d.ts

@@ -48,6 +48,14 @@ export declare const PERMISSIONS: {
     readonly documentsReadSelf: "documents:read:self";
     readonly documentsReadAssigned: "documents:read:assigned";
     readonly documentsReadAny: "documents:read:any";
+    readonly mealsRead: "meals:read";
+    readonly mealsCreate: "meals:create";
+    readonly mealsUpdate: "meals:update";
+    readonly mealsDelete: "meals:delete";
+    readonly nutritionPlansRead: "nutrition_plans:read";
+    readonly nutritionPlansWrite: "nutrition_plans:write";
+    readonly nutritionPlansPublish: "nutrition_plans:publish";
+    readonly nutritionPlansReadSelf: "nutrition_plans:read:self";
 };
 export type Permission = (typeof PERMISSIONS)[keyof typeof PERMISSIONS];
 /**
@@ -201,3 +209,26 @@ export declare const HEIGHT_UNITS: readonly ["CM", "FT"];
 export type HeightUnit = (typeof HEIGHT_UNITS)[number];
 export declare const WEIGHT_UNITS: readonly ["KG", "LB"];
 export type WeightUnit = (typeof WEIGHT_UNITS)[number];
+export declare const MEAL_SORT_FIELDS: readonly ["name", "updatedAt"];
+export type MealSortField = (typeof MEAL_SORT_FIELDS)[number];
+/**
+ * A plan is built as a `DRAFT`, becomes `ACTIVE` when published, and is
+ * `ARCHIVED` when a newer plan replaces it. A client has at most one of each
+ * of the first two.
+ */
+export declare const NUTRITION_PLAN_STATUSES: readonly ["DRAFT", "ACTIVE", "ARCHIVED"];
+export type NutritionPlanStatus = (typeof NUTRITION_PLAN_STATUSES)[number];
+export declare const PLAN_SLOT_KINDS: readonly ["MEAL", "SHAKE"];
+export type PlanSlotKind = (typeof PLAN_SLOT_KINDS)[number];
+/** The stretch of the training block the calorie base is set for. */
+export declare const PLAN_PHASES: readonly ["WEEKS_1_2", "WEEKS_3_4", "WEEKS_5_6", "WEEKS_7_8"];
+export type PlanPhase = (typeof PLAN_PHASES)[number];
+/** How long a published plan runs, in weeks. */
+export declare const PLAN_BLOCK_WEEKS: readonly [8, 12, 16];
+export type PlanBlockWeeks = (typeof PLAN_BLOCK_WEEKS)[number];
+/** The period a cheat-meal allowance resets over. Unused cheat meals do not carry over. */
+export declare const CHEAT_MEAL_PERIODS: readonly ["WEEK", "TWO_WEEKS", "MONTH"];
+export type CheatMealPeriod = (typeof CHEAT_MEAL_PERIODS)[number];
+/** Starting points for the calorie base: calories per pound and a macro split. */
+export declare const NUTRITION_GUIDELINE_IDS: readonly ["AGGRESSIVE_CUT", "MODERATE_CUT", "MAINTENANCE", "MUSCLE_GAIN", "AGGRESSIVE_BULK"];
+export type NutritionGuidelineId = (typeof NUTRITION_GUIDELINE_IDS)[number];

package/dist/cjs/enums/index.js

@@ -3,7 +3,7 @@
 // removing one is a breaking change, so it needs a major version.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SLEEP_DURATIONS = exports.BODY_AREAS = exports.ANABOLIC_USE = exports.WATER_INTAKES = exports.ALLERGENS = exports.DIET_TYPES = exports.ACTIVITY_LEVELS = exports.SESSION_LENGTHS = exports.WEEKDAYS = exports.TRAINING_TIMES = exports.EXPERIENCE_LEVELS = exports.GENDERS = exports.ONBOARDING_SECTIONS = exports.ONBOARDING_STEPS = exports.ONBOARDING_STATUSES = exports.DOCUMENT_STATUSES = exports.DOCUMENT_TYPES = exports.SUPPLEMENT_SOURCES = exports.GOAL_SORT_FIELDS = exports.GOAL_STATUSES = exports.GOAL_ICONS = exports.SORT_ORDERS = exports.FOOD_SORT_FIELDS = exports.FOOD_METADATA_SELECTIONS = exports.FOOD_IMPORT_ISSUE_SEVERITIES = exports.FOOD_IMPORT_FILE_TYPES = exports.FOOD_IMPORT_ROW_STATUSES = exports.FOOD_IMPORT_STATUSES = exports.FOOD_IMPORT_MODES = exports.FOOD_SUGGESTION_RESOLUTIONS = exports.FOOD_SUGGESTION_STATUSES = exports.NUTRITION_BASES = exports.PORTION_UNITS = exports.SERVING_UNITS = exports.FOOD_SOURCES = exports.TEMPLATE_STATUSES = exports.DELIVERY_STATUSES = exports.MESSAGE_TYPES = exports.COMMUNICATION_CHANNELS = exports.FEATURE_FLAG_RULE_TYPES = exports.AUDIT_OUTCOMES = exports.CSRF_HEADER = exports.CSRF_COOKIE_NAMES = exports.TOKEN_TRANSPORTS = exports.TIMEZONE_SOURCES = exports.ADMIN_SETTABLE_ACCOUNT_STATUSES = exports.ACCOUNT_STATUSES = exports.PERMISSIONS = exports.ROLES = exports.APP_ENVIRONMENTS = void 0;
-exports.WEIGHT_UNITS = exports.HEIGHT_UNITS = exports.KIDNEY_TEST_ANSWERS = exports.DIGESTIVE_SYMPTOMS = exports.REFLUX_FREQUENCIES = exports.DIGESTION_QUALITIES = void 0;
+exports.NUTRITION_GUIDELINE_IDS = exports.CHEAT_MEAL_PERIODS = exports.PLAN_BLOCK_WEEKS = exports.PLAN_PHASES = exports.PLAN_SLOT_KINDS = exports.NUTRITION_PLAN_STATUSES = exports.MEAL_SORT_FIELDS = exports.WEIGHT_UNITS = exports.HEIGHT_UNITS = exports.KIDNEY_TEST_ANSWERS = exports.DIGESTIVE_SYMPTOMS = exports.REFLUX_FREQUENCIES = exports.DIGESTION_QUALITIES = void 0;
 exports.APP_ENVIRONMENTS = [
     'development',
     'staging',
@@ -56,6 +56,14 @@ exports.PERMISSIONS = {
     documentsReadSelf: 'documents:read:self',
     documentsReadAssigned: 'documents:read:assigned',
     documentsReadAny: 'documents:read:any',
+    mealsRead: 'meals:read',
+    mealsCreate: 'meals:create',
+    mealsUpdate: 'meals:update',
+    mealsDelete: 'meals:delete',
+    nutritionPlansRead: 'nutrition_plans:read',
+    nutritionPlansWrite: 'nutrition_plans:write',
+    nutritionPlansPublish: 'nutrition_plans:publish',
+    nutritionPlansReadSelf: 'nutrition_plans:read:self',
 };
 /**
  * `pending_verification` is a self-registered user who has not yet proved they
@@ -329,3 +337,31 @@ exports.DIGESTIVE_SYMPTOMS = [
 exports.KIDNEY_TEST_ANSWERS = ['YES', 'NO', 'NOT_SURE'];
 exports.HEIGHT_UNITS = ['CM', 'FT'];
 exports.WEIGHT_UNITS = ['KG', 'LB'];
+// Meal library and nutrition plans
+exports.MEAL_SORT_FIELDS = ['name', 'updatedAt'];
+/**
+ * A plan is built as a `DRAFT`, becomes `ACTIVE` when published, and is
+ * `ARCHIVED` when a newer plan replaces it. A client has at most one of each
+ * of the first two.
+ */
+exports.NUTRITION_PLAN_STATUSES = ['DRAFT', 'ACTIVE', 'ARCHIVED'];
+exports.PLAN_SLOT_KINDS = ['MEAL', 'SHAKE'];
+/** The stretch of the training block the calorie base is set for. */
+exports.PLAN_PHASES = [
+    'WEEKS_1_2',
+    'WEEKS_3_4',
+    'WEEKS_5_6',
+    'WEEKS_7_8',
+];
+/** How long a published plan runs, in weeks. */
+exports.PLAN_BLOCK_WEEKS = [8, 12, 16];
+/** The period a cheat-meal allowance resets over. Unused cheat meals do not carry over. */
+exports.CHEAT_MEAL_PERIODS = ['WEEK', 'TWO_WEEKS', 'MONTH'];
+/** Starting points for the calorie base: calories per pound and a macro split. */
+exports.NUTRITION_GUIDELINE_IDS = [
+    'AGGRESSIVE_CUT',
+    'MODERATE_CUT',
+    'MAINTENANCE',
+    'MUSCLE_GAIN',
+    'AGGRESSIVE_BULK',
+];

package/dist/cjs/meals/index.d.ts

@@ -0,0 +1 @@
+export * from './meal.dto.js';

package/dist/cjs/meals/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./meal.dto.js"), exports);

package/dist/cjs/meals/meal.dto.d.ts

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+export declare const MAX_MEAL_NAME_LENGTH = 80;
+export declare const MAX_MEAL_TIMING_LENGTH = 40;
+export declare const MAX_MEAL_NOTES_LENGTH = 500;
+export declare const MAX_MEAL_SEARCH_LENGTH = 80;
+export declare const MAX_MEAL_ITEMS = 20;
+/** Servings of a food's library serving, in half steps. */
+export declare const SERVINGS: {
+    readonly MIN: 0.5;
+    readonly MAX: 10;
+    readonly STEP: 0.5;
+};
+export declare const mealIdParamSchema: z.ZodUUID;
+/** Lower case with spaces collapsed: what duplicate name checks compare. */
+export declare const normalizeMealName: (name: string) => string;
+/** A number of servings: 0.5 to 10, in steps of 0.5. */
+export declare const servingsSchema: z.ZodNumber;
+/** A food and how many of its servings. */
+export declare const foodPortionSchema: z.ZodObject<{
+    foodId: z.ZodUUID;
+    servings: z.ZodNumber;
+}, z.core.$strict>;
+export type FoodPortionInput = z.input<typeof foodPortionSchema>;
+export declare const createMealSchema: z.ZodObject<{
+    name: z.ZodString;
+    timing: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    items: z.ZodArray<z.ZodObject<{
+        foodId: z.ZodUUID;
+        servings: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CreateMealInput = z.input<typeof createMealSchema>;
+export type CreateMealBody = z.output<typeof createMealSchema>;
+export declare const updateMealSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    name: z.ZodOptional<z.ZodString>;
+    timing: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        foodId: z.ZodUUID;
+        servings: z.ZodNumber;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type UpdateMealInput = z.input<typeof updateMealSchema>;
+export type UpdateMealBody = z.output<typeof updateMealSchema>;
+export declare const mealListQuerySchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    search: z.ZodOptional<z.ZodString>;
+    sort: z.ZodDefault<z.ZodEnum<{
+        name: "name";
+        updatedAt: "updatedAt";
+    }>>;
+    order: z.ZodDefault<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}, z.core.$strip>;
+export type MealListQuery = z.output<typeof mealListQuerySchema>;
+/** Calories and the three macros, in kcal and grams. */
+export declare const macroTotalsSchema: z.ZodObject<{
+    calories: z.ZodNumber;
+    protein: z.ZodNumber;
+    carbs: z.ZodNumber;
+    fat: z.ZodNumber;
+}, z.core.$strip>;
+export type MacroTotalsResponse = z.output<typeof macroTotalsSchema>;
+/** The library food a portion refers to, as it was when last read or saved. */
+export declare const portionFoodSchema: z.ZodObject<{
+    name: z.ZodString;
+    servingLabel: z.ZodString;
+    deleted: z.ZodBoolean;
+}, z.core.$strip>;
+export declare const mealItemResponseSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    foodId: z.ZodUUID;
+    servings: z.ZodNumber;
+    food: z.ZodObject<{
+        name: z.ZodString;
+        servingLabel: z.ZodString;
+        deleted: z.ZodBoolean;
+    }, z.core.$strip>;
+    perServing: z.ZodObject<{
+        calories: z.ZodNumber;
+        protein: z.ZodNumber;
+        carbs: z.ZodNumber;
+        fat: z.ZodNumber;
+    }, z.core.$strip>;
+    totals: z.ZodObject<{
+        calories: z.ZodNumber;
+        protein: z.ZodNumber;
+        carbs: z.ZodNumber;
+        fat: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type MealItemResponse = z.output<typeof mealItemResponseSchema>;
+export declare const mealResponseSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    name: z.ZodString;
+    timing: z.ZodNullable<z.ZodString>;
+    notes: z.ZodNullable<z.ZodString>;
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        foodId: z.ZodUUID;
+        servings: z.ZodNumber;
+        food: z.ZodObject<{
+            name: z.ZodString;
+            servingLabel: z.ZodString;
+            deleted: z.ZodBoolean;
+        }, z.core.$strip>;
+        perServing: z.ZodObject<{
+            calories: z.ZodNumber;
+            protein: z.ZodNumber;
+            carbs: z.ZodNumber;
+            fat: z.ZodNumber;
+        }, z.core.$strip>;
+        totals: z.ZodObject<{
+            calories: z.ZodNumber;
+            protein: z.ZodNumber;
+            carbs: z.ZodNumber;
+            fat: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    totals: z.ZodObject<{
+        calories: z.ZodNumber;
+        protein: z.ZodNumber;
+        carbs: z.ZodNumber;
+        fat: z.ZodNumber;
+    }, z.core.$strip>;
+    createdBy: z.ZodObject<{
+        id: z.ZodUUID;
+        fullName: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    updatedBy: z.ZodObject<{
+        id: z.ZodUUID;
+        fullName: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    version: z.ZodNumber;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type MealResponse = z.output<typeof mealResponseSchema>;

package/dist/cjs/meals/meal.dto.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mealResponseSchema = exports.mealItemResponseSchema = exports.portionFoodSchema = exports.macroTotalsSchema = exports.mealListQuerySchema = exports.updateMealSchema = exports.createMealSchema = exports.foodPortionSchema = exports.servingsSchema = exports.normalizeMealName = exports.mealIdParamSchema = exports.SERVINGS = exports.MAX_MEAL_ITEMS = exports.MAX_MEAL_SEARCH_LENGTH = exports.MAX_MEAL_NOTES_LENGTH = exports.MAX_MEAL_TIMING_LENGTH = exports.MAX_MEAL_NAME_LENGTH = void 0;
+const zod_1 = require("zod");
+const date_time_schema_js_1 = require("../common/date-time.schema.js");
+const pagination_schema_js_1 = require("../common/pagination.schema.js");
+const safe_text_schema_js_1 = require("../common/safe-text.schema.js");
+const index_js_1 = require("../enums/index.js");
+const food_dto_js_1 = require("../food/food.dto.js");
+// A meal is a named set of library foods with a number of servings each, such
+// as "Oats + Milk + Banana". Coaches keep a library of them and copy one into a
+// slot of a client's nutrition plan, where it can be changed for that client.
+//
+// Each request has two types. `*Input` is what a client sends, where fields with
+// a default are optional. `*Body` is what the API receives after validation.
+exports.MAX_MEAL_NAME_LENGTH = 80;
+exports.MAX_MEAL_TIMING_LENGTH = 40;
+exports.MAX_MEAL_NOTES_LENGTH = 500;
+exports.MAX_MEAL_SEARCH_LENGTH = 80;
+exports.MAX_MEAL_ITEMS = 20;
+/** Servings of a food's library serving, in half steps. */
+exports.SERVINGS = { MIN: 0.5, MAX: 10, STEP: 0.5 };
+exports.mealIdParamSchema = zod_1.z.uuid();
+/** Lower case with spaces collapsed: what duplicate name checks compare. */
+const normalizeMealName = (name) => name.trim().replace(/\s+/g, ' ').toLowerCase();
+exports.normalizeMealName = normalizeMealName;
+/** A number of servings: 0.5 to 10, in steps of 0.5. */
+exports.servingsSchema = zod_1.z
+    .number()
+    .min(exports.SERVINGS.MIN)
+    .max(exports.SERVINGS.MAX)
+    .refine((value) => Number.isInteger(value / exports.SERVINGS.STEP), {
+    error: `Use steps of ${exports.SERVINGS.STEP}`,
+});
+/** A food and how many of its servings. */
+exports.foodPortionSchema = zod_1.z.strictObject({
+    foodId: zod_1.z.uuid(),
+    servings: exports.servingsSchema,
+});
+const mealNameSchema = (0, safe_text_schema_js_1.safeTextSchema)(exports.MAX_MEAL_NAME_LENGTH);
+const mealTimingSchema = (0, safe_text_schema_js_1.safeTextSchema)(exports.MAX_MEAL_TIMING_LENGTH);
+const mealNotesSchema = (0, safe_text_schema_js_1.safeTextSchema)(exports.MAX_MEAL_NOTES_LENGTH);
+const mealItemsSchema = zod_1.z.array(exports.foodPortionSchema).min(1).max(exports.MAX_MEAL_ITEMS);
+// Strict objects reject unknown fields, so an attempt to set `createdBy`
+// through the API fails loudly.
+exports.createMealSchema = zod_1.z.strictObject({
+    name: mealNameSchema,
+    /** When it is usually eaten, such as "Breakfast" or "Post-workout". */
+    timing: mealTimingSchema.nullable().optional(),
+    notes: mealNotesSchema.nullable().optional(),
+    /** In the order shown. A food may appear more than once. */
+    items: mealItemsSchema,
+});
+exports.updateMealSchema = zod_1.z
+    .strictObject({
+    // The version last read, so that a stale edit is refused rather than lost.
+    version: zod_1.z.number().int().min(1),
+    name: mealNameSchema.optional(),
+    timing: mealTimingSchema.nullable().optional(),
+    notes: mealNotesSchema.nullable().optional(),
+    /** Replaces every item when present. */
+    items: mealItemsSchema.optional(),
+})
+    .refine(({ version: _version, ...changes }) => Object.values(changes).some((value) => value !== undefined), { error: 'Provide at least one field to change' });
+exports.mealListQuerySchema = pagination_schema_js_1.paginationQuerySchema.extend({
+    search: zod_1.z.string().trim().min(1).max(exports.MAX_MEAL_SEARCH_LENGTH).optional(),
+    sort: zod_1.z.enum(index_js_1.MEAL_SORT_FIELDS).default('name'),
+    order: zod_1.z.enum(index_js_1.SORT_ORDERS).default('asc'),
+});
+// Responses
+/** Calories and the three macros, in kcal and grams. */
+exports.macroTotalsSchema = zod_1.z.object({
+    calories: zod_1.z.number(),
+    protein: zod_1.z.number(),
+    carbs: zod_1.z.number(),
+    fat: zod_1.z.number(),
+});
+/** The library food a portion refers to, as it was when last read or saved. */
+exports.portionFoodSchema = zod_1.z.object({
+    name: zod_1.z.string(),
+    /** Such as "1 bowl (150g)". */
+    servingLabel: zod_1.z.string(),
+    /** True when the food has since been deleted from the library. */
+    deleted: zod_1.z.boolean(),
+});
+exports.mealItemResponseSchema = zod_1.z.object({
+    id: zod_1.z.uuid(),
+    foodId: zod_1.z.uuid(),
+    servings: zod_1.z.number(),
+    food: exports.portionFoodSchema,
+    perServing: exports.macroTotalsSchema,
+    /** `perServing` × `servings`. */
+    totals: exports.macroTotalsSchema,
+});
+exports.mealResponseSchema = zod_1.z.object({
+    id: zod_1.z.uuid(),
+    name: zod_1.z.string(),
+    timing: zod_1.z.string().nullable(),
+    notes: zod_1.z.string().nullable(),
+    items: zod_1.z.array(exports.mealItemResponseSchema),
+    totals: exports.macroTotalsSchema,
+    createdBy: food_dto_js_1.userRefSchema,
+    updatedBy: food_dto_js_1.userRefSchema,
+    version: zod_1.z.number().int(),
+    createdAt: date_time_schema_js_1.utcTimestampSchema,
+    updatedAt: date_time_schema_js_1.utcTimestampSchema,
+});

package/dist/cjs/nutrition-plans/index.d.ts

@@ -0,0 +1,2 @@
+export * from './nutrition-math.js';
+export * from './nutrition-plan.dto.js';

package/dist/cjs/nutrition-plans/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./nutrition-math.js"), exports);
+__exportStar(require("./nutrition-plan.dto.js"), exports);

package/dist/cjs/nutrition-plans/nutrition-math.d.ts

@@ -0,0 +1,115 @@
+import { type GoalIcon, type NutritionGuidelineId, type PlanSlotKind } from '../enums/index.js';
+/**
+ * The Nutrition Plan Builder's sums, shared so that the builder's screens and
+ * the API agree on every number and every publish rule. Everything here is
+ * pure.
+ */
+export declare const KG_TO_LB = 2.20462;
+export declare const KCAL_PER_GRAM: {
+    readonly protein: 4;
+    readonly carbs: 4;
+    readonly fat: 9;
+};
+export type MacroKey = keyof typeof KCAL_PER_GRAM;
+export declare const MACRO_KEYS: readonly MacroKey[];
+/** A slot's macros must come to its share of calories within this many kcal. */
+export declare const MEAL_KCAL_TOLERANCE = 10;
+/** The day's foods must come within this share of the daily calories. */
+export declare const DAILY_MACRO_TOLERANCE = 0.05;
+/** Recommended water: 35 ml per kg of body weight, rounded to 100 ml. */
+export declare const WATER_ML_PER_KG = 35;
+export declare const GLASS_ML = 250;
+export declare const CHEAT_MEALS: {
+    readonly MIN: 1;
+    readonly MAX: 3;
+    readonly DEFAULT: 1;
+};
+export type MacroSplit = Record<MacroKey, number>;
+export interface MacroTotals {
+    calories: number;
+    protein: number;
+    carbs: number;
+    fat: number;
+}
+export interface NutritionGuideline {
+    id: NutritionGuidelineId;
+    label: string;
+    calPerLb: number;
+    split: MacroSplit;
+}
+export declare const NUTRITION_GUIDELINES: readonly NutritionGuideline[];
+export declare const DEFAULT_GUIDELINE_ID: NutritionGuidelineId;
+export declare function nutritionGuideline(id: NutritionGuidelineId): NutritionGuideline;
+/** The guideline a goal suggests; maintenance when there is no goal or no match. */
+export declare function guidelineForGoalIcon(icon: GoalIcon | null | undefined): NutritionGuideline;
+export declare function isNutritionGuidelineId(value: string): value is NutritionGuidelineId;
+export declare function poundsOf(kg: number): number;
+/** Weight in pounds × calories per pound, rounded down, unless custom calories are set. */
+export declare function dailyCalories(plan: {
+    weightKg: number;
+    calPerLb: number;
+    customCalories: number | null;
+}): number;
+export interface MacroTarget {
+    percent: number;
+    kcal: number;
+    grams: number;
+}
+export declare function macroTargets(total: number, split: MacroSplit): Record<MacroKey, MacroTarget>;
+export declare function splitTotal(split: MacroSplit): number;
+export declare function recommendedWaterMl(weightKg: number): number;
+/** Calories from macro grams. Unset grams count as zero. */
+export declare function macroKcal(macros: {
+    protein: number | null;
+    carbs: number | null;
+    fat: number | null;
+}): number;
+/** A slot's calories: its share of the day, or null while the share is unset. */
+export declare function slotTargetKcal(share: number | null, total: number): number | null;
+export declare const ZERO_TOTALS: MacroTotals;
+/** Adds macro totals, rounding to one decimal so sums don't drift. */
+export declare function addTotals(...items: readonly MacroTotals[]): MacroTotals;
+/** One serving's values × a number of servings. */
+export declare function scaleTotals(perServing: MacroTotals, servings: number): MacroTotals;
+export interface DefaultSlot {
+    kind: PlanSlotKind;
+    label: string;
+    timing: string;
+}
+/** The labels and timings a new plan starts with for a number of meals and shakes. */
+export declare function defaultSlots(meals: number, shakes: number): DefaultSlot[];
+export declare const PUBLISH_ISSUE_CODES: readonly ["SPLIT_NOT_100", "SLOT_COUNT_MISMATCH", "SLOT_NOT_SET", "SHARES_NOT_100", "SLOT_MACROS_OFF", "SLOT_HAS_NO_FOODS", "DAY_CALORIES_OFF", "CHEAT_COUNT_OUT_OF_RANGE"];
+export type PublishIssueCode = (typeof PUBLISH_ISSUE_CODES)[number];
+export interface PublishIssue {
+    code: PublishIssueCode;
+    /** The slot it is about, by position from 0, when it is about one slot. */
+    slotIndex: number | null;
+    message: string;
+}
+/** The parts of a plan the publish rules read. */
+export interface PlanForPublishCheck {
+    weightKg: number;
+    calPerLb: number;
+    customCalories: number | null;
+    split: MacroSplit;
+    mealsPerDay: number;
+    shakesPerDay: number;
+    slots: readonly {
+        kind: PlanSlotKind;
+        share: number | null;
+        protein: number | null;
+        carbs: number | null;
+        fat: number | null;
+        /** Each food's totals for its servings. */
+        foods: readonly MacroTotals[];
+    }[];
+    cheat: {
+        allowed: boolean;
+        count: number;
+    };
+}
+/**
+ * Why a plan cannot be published yet, in the order the builder's steps check
+ * them. An empty list means it can be.
+ */
+export declare function nutritionPlanPublishIssues(plan: PlanForPublishCheck): PublishIssue[];