@tbs-fitness/contract 0.2.0 → 0.4.0

package/dist/esm/common/date-time.schema.js

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+/**
+ * The platform's date and time rules, shared so the backend and the apps
+ * validate them identically:
+ *
+ * - An instant (something that happened at one moment) travels as ISO 8601.
+ *   Responses always use UTC with `Z`. Requests may use `Z` or an explicit
+ *   offset, but never a bare local time, which would be ambiguous.
+ * - A date-only value (a birthday, an expiry date) travels as `YYYY-MM-DD` and
+ *   is never converted between time zones.
+ * - A time zone is an IANA identifier such as `Asia/Kolkata`. Abbreviations
+ *   (`IST`) and fixed offsets (`+05:30`) are refused, because offsets change
+ *   with daylight saving.
+ */
+export const DEFAULT_TIMEZONE = 'UTC';
+const MAX_TIMEZONE_LENGTH = 64;
+// The IANA areas used for real places. `Etc/*` and the legacy aliases
+// (`US/Eastern`, `EST`) are left out: the first are fixed offsets, and the
+// second have modern names.
+const AREA_LOCATION = /^(?:Africa|America|Antarctica|Arctic|Asia|Atlantic|Australia|Europe|Indian|Pacific)\/[A-Za-z0-9_+-]+(?:\/[A-Za-z0-9_+-]+)?$/;
+/**
+ * True for `UTC` and for an IANA `Area/Location` name the runtime's time zone
+ * database knows. Runs anywhere `Intl` does, so the browser and the server
+ * agree.
+ */
+export function isValidTimezone(value) {
+    if (typeof value !== 'string' || value.length > MAX_TIMEZONE_LENGTH) {
+        return false;
+    }
+    if (value !== DEFAULT_TIMEZONE && !AREA_LOCATION.test(value)) {
+        return false;
+    }
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: value });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Browsers and Node report some zones by names IANA has since replaced, because
+// their Unicode data keeps the old ones. Saving the current name means one
+// place is stored, compared and shown one way everywhere.
+const RENAMED_TIMEZONES = {
+    'Asia/Calcutta': 'Asia/Kolkata',
+    'Asia/Saigon': 'Asia/Ho_Chi_Minh',
+    'Asia/Katmandu': 'Asia/Kathmandu',
+    'Asia/Rangoon': 'Asia/Yangon',
+    'Europe/Kiev': 'Europe/Kyiv',
+    'Europe/Uzhgorod': 'Europe/Kyiv',
+    'Europe/Zaporozhye': 'Europe/Kyiv',
+    'Atlantic/Faeroe': 'Atlantic/Faroe',
+    'America/Godthab': 'America/Nuuk',
+    'Pacific/Enderbury': 'Pacific/Kanton',
+    'Pacific/Truk': 'Pacific/Chuuk',
+    'Pacific/Ponape': 'Pacific/Pohnpei',
+    'America/Buenos_Aires': 'America/Argentina/Buenos_Aires',
+    'America/Catamarca': 'America/Argentina/Catamarca',
+    'America/Cordoba': 'America/Argentina/Cordoba',
+    'America/Jujuy': 'America/Argentina/Jujuy',
+    'America/Mendoza': 'America/Argentina/Mendoza',
+    'America/Indianapolis': 'America/Indiana/Indianapolis',
+    'America/Louisville': 'America/Kentucky/Louisville',
+};
+/** The current IANA name for a zone, such as `Asia/Kolkata` for `Asia/Calcutta`. */
+export function canonicalTimezone(value) {
+    return RENAMED_TIMEZONES[value] ?? value;
+}
+export const timezoneSchema = z
+    .string()
+    .trim()
+    .refine(isValidTimezone, {
+    error: 'Choose a time zone such as Asia/Kolkata',
+})
+    .transform(canonicalTimezone);
+/**
+ * A time zone the client detected and suggests, such as at sign-up. A missing
+ * or unusable value becomes `undefined` instead of failing the request, and the
+ * server then applies its default.
+ */
+export const detectedTimezoneSchema = z
+    .unknown()
+    .transform((value) => {
+    const trimmed = typeof value === 'string' ? value.trim() : value;
+    return isValidTimezone(trimmed) ? canonicalTimezone(trimmed) : undefined;
+})
+    .optional();
+/** An instant in a response: ISO 8601 in UTC, ending in `Z`. */
+export const utcTimestampSchema = z.iso.datetime();
+/**
+ * An instant in a request: ISO 8601 with `Z` or an explicit offset, such as
+ * `2026-11-02T15:00:00+05:30`. A local time without either is refused.
+ */
+export const instantInputSchema = z.iso.datetime({ offset: true });
+/** A calendar date with no time and no zone, such as `2026-11-02`. */
+export const dateOnlySchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, { error: 'Use the format YYYY-MM-DD' })
+    .refine(isRealCalendarDate, { error: 'Enter a real calendar date' });
+function isRealCalendarDate(value) {
+    const [year, month, day] = value.split('-').map(Number);
+    // UTC is used only to check the calendar, so no zone can move the date.
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return (date.getUTCFullYear() === year &&
+        date.getUTCMonth() === month - 1 &&
+        date.getUTCDate() === day);
+}

package/dist/esm/common/index.d.ts

@@ -1,4 +1,5 @@
 export * from './api-response.schema.js';
 export * from './contact.schema.js';
+export * from './date-time.schema.js';
 export * from './pagination.schema.js';
 export * from './safe-text.schema.js';

package/dist/esm/common/index.js

@@ -1,4 +1,5 @@
 export * from './api-response.schema.js';
 export * from './contact.schema.js';
+export * from './date-time.schema.js';
 export * from './pagination.schema.js';
 export * from './safe-text.schema.js';

package/dist/esm/communication/index.d.ts

@@ -0,0 +1,2 @@
+export * from './message-catalogue.js';
+export * from './template.dto.js';

package/dist/esm/communication/index.js

@@ -0,0 +1,2 @@
+export * from './message-catalogue.js';
+export * from './template.dto.js';

package/dist/esm/communication/message-catalogue.d.ts

@@ -0,0 +1,26 @@
+import type { CommunicationChannel, MessageType } from '../enums/index.js';
+/**
+ * What the platform knows about each message type: the channels that may carry
+ * it, the channels switched on by default, and the variables its sender
+ * supplies. A template may only use supplied variables, and must use the
+ * required ones, so an admin can never activate a template the system cannot
+ * fill.
+ */
+export interface MessageTypeDefinition {
+    label: string;
+    description: string;
+    channels: readonly CommunicationChannel[];
+    defaultChannels: Readonly<Record<CommunicationChannel, boolean>>;
+    /** Every variable the sender passes, with a sample value for previews. */
+    variables: Readonly<Record<string, {
+        description: string;
+        example: string;
+    }>>;
+    /** Variables every template for this type must use. */
+    requiredVariables: readonly string[];
+}
+export declare const MESSAGE_CATALOGUE: Readonly<Record<MessageType, MessageTypeDefinition>>;
+/** The longest SMS body a template may have: four concatenated GSM-7 segments. */
+export declare const MAX_SMS_LENGTH = 612;
+/** One GSM-7 segment. Longer messages are split and cost more. */
+export declare const SMS_SEGMENT_LENGTH = 160;

package/dist/esm/communication/message-catalogue.js

@@ -0,0 +1,50 @@
+const OTP_VARIABLES = {
+    code: { description: 'The one-time code', example: '482915' },
+    fullName: { description: "The recipient's name", example: 'Biki Singh' },
+    expiresInMinutes: {
+        description: 'Minutes until the code expires',
+        example: '10',
+    },
+    appName: { description: 'The product name', example: 'TBS' },
+};
+export const MESSAGE_CATALOGUE = {
+    'auth.otp.signup_verification': {
+        label: 'Sign-up verification code',
+        description: 'Sent when a coach signs up, to verify their email address.',
+        channels: ['EMAIL', 'SMS'],
+        defaultChannels: { EMAIL: true, SMS: false },
+        variables: OTP_VARIABLES,
+        requiredVariables: ['code'],
+    },
+    'auth.otp.password_reset': {
+        label: 'Password recovery code',
+        description: 'Sent when a coach asks to reset a forgotten password.',
+        channels: ['EMAIL', 'SMS'],
+        defaultChannels: { EMAIL: true, SMS: false },
+        variables: OTP_VARIABLES,
+        requiredVariables: ['code'],
+    },
+    'auth.password_reset_link': {
+        label: 'Password reset link',
+        description: 'Sent when an administrator account requests a reset link.',
+        channels: ['EMAIL'],
+        defaultChannels: { EMAIL: true, SMS: false },
+        variables: {
+            resetUrl: {
+                description: 'The single-use reset link',
+                example: 'https://app.example.com/reset-password?token=…',
+            },
+            fullName: { description: "The recipient's name", example: 'Biki Singh' },
+            expiresInMinutes: {
+                description: 'Minutes until the link expires',
+                example: '30',
+            },
+            appName: { description: 'The product name', example: 'TBS' },
+        },
+        requiredVariables: ['resetUrl'],
+    },
+};
+/** The longest SMS body a template may have: four concatenated GSM-7 segments. */
+export const MAX_SMS_LENGTH = 612;
+/** One GSM-7 segment. Longer messages are split and cost more. */
+export const SMS_SEGMENT_LENGTH = 160;

package/dist/esm/communication/template.dto.d.ts

@@ -0,0 +1,240 @@
+import { z } from 'zod';
+import { type CommunicationChannel, type MessageType } from '../enums/index.js';
+/** The variable names used as `{{name}}` in a piece of template text, in order, without repeats. */
+export declare function templatePlaceholders(text: string): string[];
+/** True when the text has a `{{` or `}}` that is not part of a valid placeholder. */
+export declare function hasMalformedPlaceholder(text: string): boolean;
+/** A variable a template declares. Its value is supplied when the message is sent. */
+export declare const templateVariableSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    example: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type TemplateVariable = z.output<typeof templateVariableSchema>;
+interface TemplateShape {
+    messageType: MessageType;
+    channel: CommunicationChannel;
+    subject?: string | null | undefined;
+    bodyText: string;
+    bodyHtml?: string | null | undefined;
+    variables: {
+        name: string;
+    }[];
+}
+/**
+ * The rules every template must meet before it is saved: the declared
+ * variables match the placeholders exactly, every one is supplied by the
+ * message type, and the type's required variables are used. Shared by the
+ * server and the admin editor, so both report the same problems.
+ */
+export declare function templateProblems(template: TemplateShape): {
+    path: string;
+    message: string;
+}[];
+/** A new draft. Saved templates are never edited; a change is a new version. */
+export declare const createTemplateSchema: z.ZodObject<{
+    messageType: z.ZodEnum<{
+        "auth.otp.signup_verification": "auth.otp.signup_verification";
+        "auth.otp.password_reset": "auth.otp.password_reset";
+        "auth.password_reset_link": "auth.password_reset_link";
+    }>;
+    channel: z.ZodEnum<{
+        EMAIL: "EMAIL";
+        SMS: "SMS";
+    }>;
+    name: z.ZodPipe<z.ZodString, z.ZodString>;
+    subject: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    bodyText: z.ZodString;
+    bodyHtml: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    variables: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        example: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CreateTemplateInput = z.input<typeof createTemplateSchema>;
+export type CreateTemplateBody = z.output<typeof createTemplateSchema>;
+export declare const templateListQuerySchema: z.ZodObject<{
+    messageType: z.ZodOptional<z.ZodEnum<{
+        "auth.otp.signup_verification": "auth.otp.signup_verification";
+        "auth.otp.password_reset": "auth.otp.password_reset";
+        "auth.password_reset_link": "auth.password_reset_link";
+    }>>;
+    channel: z.ZodOptional<z.ZodEnum<{
+        EMAIL: "EMAIL";
+        SMS: "SMS";
+    }>>;
+}, z.core.$strict>;
+export type TemplateListQuery = z.output<typeof templateListQuerySchema>;
+export declare const templateResponseSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    messageType: z.ZodEnum<{
+        "auth.otp.signup_verification": "auth.otp.signup_verification";
+        "auth.otp.password_reset": "auth.otp.password_reset";
+        "auth.password_reset_link": "auth.password_reset_link";
+    }>;
+    channel: z.ZodEnum<{
+        EMAIL: "EMAIL";
+        SMS: "SMS";
+    }>;
+    version: z.ZodNumber;
+    name: z.ZodString;
+    subject: z.ZodNullable<z.ZodString>;
+    bodyText: z.ZodString;
+    bodyHtml: z.ZodNullable<z.ZodString>;
+    variables: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        example: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    status: z.ZodEnum<{
+        active: "active";
+        draft: "draft";
+        archived: "archived";
+    }>;
+    createdBy: z.ZodNullable<z.ZodUUID>;
+    createdAt: z.ZodISODateTime;
+    activatedBy: z.ZodNullable<z.ZodUUID>;
+    activatedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type TemplateResponse = z.output<typeof templateResponseSchema>;
+export declare const templateListResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodUUID;
+    messageType: z.ZodEnum<{
+        "auth.otp.signup_verification": "auth.otp.signup_verification";
+        "auth.otp.password_reset": "auth.otp.password_reset";
+        "auth.password_reset_link": "auth.password_reset_link";
+    }>;
+    channel: z.ZodEnum<{
+        EMAIL: "EMAIL";
+        SMS: "SMS";
+    }>;
+    version: z.ZodNumber;
+    name: z.ZodString;
+    subject: z.ZodNullable<z.ZodString>;
+    bodyText: z.ZodString;
+    bodyHtml: z.ZodNullable<z.ZodString>;
+    variables: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        example: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    status: z.ZodEnum<{
+        active: "active";
+        draft: "draft";
+        archived: "archived";
+    }>;
+    createdBy: z.ZodNullable<z.ZodUUID>;
+    createdAt: z.ZodISODateTime;
+    activatedBy: z.ZodNullable<z.ZodUUID>;
+    activatedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>>;
+/** Renders unsaved text, or a saved version, with the catalogue's sample values. */
+export declare const previewTemplateSchema: z.ZodUnion<readonly [z.ZodObject<{
+    templateId: z.ZodUUID;
+}, z.core.$strict>, z.ZodObject<{
+    messageType: z.ZodEnum<{
+        "auth.otp.signup_verification": "auth.otp.signup_verification";
+        "auth.otp.password_reset": "auth.otp.password_reset";
+        "auth.password_reset_link": "auth.password_reset_link";
+    }>;
+    channel: z.ZodEnum<{
+        EMAIL: "EMAIL";
+        SMS: "SMS";
+    }>;
+    name: z.ZodPipe<z.ZodString, z.ZodString>;
+    subject: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    bodyText: z.ZodString;
+    bodyHtml: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    variables: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        example: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>;
+export type PreviewTemplateInput = z.input<typeof previewTemplateSchema>;
+export type PreviewTemplateBody = z.output<typeof previewTemplateSchema>;
+export declare const renderedMessageSchema: z.ZodObject<{
+    channel: z.ZodEnum<{
+        EMAIL: "EMAIL";
+        SMS: "SMS";
+    }>;
+    subject: z.ZodNullable<z.ZodString>;
+    bodyText: z.ZodString;
+    bodyHtml: z.ZodNullable<z.ZodString>;
+    smsSegments: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type RenderedMessage = z.output<typeof renderedMessageSchema>;
+export declare const testSendResponseSchema: z.ZodObject<{
+    channel: z.ZodEnum<{
+        EMAIL: "EMAIL";
+        SMS: "SMS";
+    }>;
+    sentTo: z.ZodString;
+}, z.core.$strip>;
+export type TestSendResponse = z.output<typeof testSendResponseSchema>;
+/** A catalogue entry, with the built-in default template for each channel. */
+export declare const messageTypeResponseSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        "auth.otp.signup_verification": "auth.otp.signup_verification";
+        "auth.otp.password_reset": "auth.otp.password_reset";
+        "auth.password_reset_link": "auth.password_reset_link";
+    }>;
+    label: z.ZodString;
+    description: z.ZodString;
+    channels: z.ZodArray<z.ZodEnum<{
+        EMAIL: "EMAIL";
+        SMS: "SMS";
+    }>>;
+    variables: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        example: z.ZodString;
+    }, z.core.$strip>>;
+    requiredVariables: z.ZodArray<z.ZodString>;
+    defaults: z.ZodArray<z.ZodObject<{
+        channel: z.ZodEnum<{
+            EMAIL: "EMAIL";
+            SMS: "SMS";
+        }>;
+        subject: z.ZodNullable<z.ZodString>;
+        bodyText: z.ZodString;
+        bodyHtml: z.ZodNullable<z.ZodString>;
+        variables: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MessageTypeResponse = z.output<typeof messageTypeResponseSchema>;
+export declare const messageTypeListResponseSchema: z.ZodArray<z.ZodObject<{
+    type: z.ZodEnum<{
+        "auth.otp.signup_verification": "auth.otp.signup_verification";
+        "auth.otp.password_reset": "auth.otp.password_reset";
+        "auth.password_reset_link": "auth.password_reset_link";
+    }>;
+    label: z.ZodString;
+    description: z.ZodString;
+    channels: z.ZodArray<z.ZodEnum<{
+        EMAIL: "EMAIL";
+        SMS: "SMS";
+    }>>;
+    variables: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        example: z.ZodString;
+    }, z.core.$strip>>;
+    requiredVariables: z.ZodArray<z.ZodString>;
+    defaults: z.ZodArray<z.ZodObject<{
+        channel: z.ZodEnum<{
+            EMAIL: "EMAIL";
+            SMS: "SMS";
+        }>;
+        subject: z.ZodNullable<z.ZodString>;
+        bodyText: z.ZodString;
+        bodyHtml: z.ZodNullable<z.ZodString>;
+        variables: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export {};

package/dist/esm/communication/template.dto.js

@@ -0,0 +1,200 @@
+import { z } from 'zod';
+import { utcTimestampSchema } from '../common/date-time.schema.js';
+import { safeTextSchema } from '../common/safe-text.schema.js';
+import { COMMUNICATION_CHANNELS, MESSAGE_TYPES, TEMPLATE_STATUSES, } from '../enums/index.js';
+import { MAX_SMS_LENGTH, MESSAGE_CATALOGUE } from './message-catalogue.js';
+const PLACEHOLDER = /\{\{\s*([A-Za-z][A-Za-z0-9_]*)\s*\}\}/g;
+/** The variable names used as `{{name}}` in a piece of template text, in order, without repeats. */
+export function templatePlaceholders(text) {
+    const names = new Set();
+    for (const match of text.matchAll(PLACEHOLDER)) {
+        names.add(match[1]);
+    }
+    return [...names];
+}
+/** True when the text has a `{{` or `}}` that is not part of a valid placeholder. */
+export function hasMalformedPlaceholder(text) {
+    const rest = text.replace(PLACEHOLDER, '');
+    return rest.includes('{{') || rest.includes('}}');
+}
+const MAX_SUBJECT_LENGTH = 200;
+const MAX_BODY_LENGTH = 20000;
+/** A variable a template declares. Its value is supplied when the message is sent. */
+export const templateVariableSchema = z.strictObject({
+    name: z
+        .string()
+        .regex(/^[A-Za-z][A-Za-z0-9_]*$/, {
+        error: 'Use letters, digits and underscores, starting with a letter',
+    })
+        .max(64),
+    description: safeTextSchema(200).optional(),
+    example: z.string().max(500).optional(),
+});
+const templateFields = {
+    messageType: z.enum(MESSAGE_TYPES),
+    channel: z.enum(COMMUNICATION_CHANNELS),
+    name: safeTextSchema(100).pipe(z.string().min(1, { error: 'Name it' })),
+    subject: z.string().max(MAX_SUBJECT_LENGTH).nullish(),
+    bodyText: z
+        .string()
+        .min(1, { error: 'Write the message' })
+        .max(MAX_BODY_LENGTH),
+    bodyHtml: z.string().max(MAX_BODY_LENGTH).nullish(),
+    variables: z.array(templateVariableSchema).max(20),
+};
+/**
+ * The rules every template must meet before it is saved: the declared
+ * variables match the placeholders exactly, every one is supplied by the
+ * message type, and the type's required variables are used. Shared by the
+ * server and the admin editor, so both report the same problems.
+ */
+export function templateProblems(template) {
+    const problems = [];
+    const definition = MESSAGE_CATALOGUE[template.messageType];
+    const isEmail = template.channel === 'EMAIL';
+    if (!definition.channels.includes(template.channel)) {
+        problems.push({
+            path: 'channel',
+            message: `${definition.label} cannot be sent by ${template.channel}`,
+        });
+    }
+    if (isEmail && !template.subject?.trim()) {
+        problems.push({ path: 'subject', message: 'An email needs a subject' });
+    }
+    if (!isEmail && (template.subject || template.bodyHtml)) {
+        problems.push({
+            path: 'bodyHtml',
+            message: 'Only email templates have a subject or HTML',
+        });
+    }
+    if (template.channel === 'SMS' && template.bodyText.length > MAX_SMS_LENGTH) {
+        problems.push({
+            path: 'bodyText',
+            message: `An SMS can be at most ${String(MAX_SMS_LENGTH)} characters`,
+        });
+    }
+    const texts = [
+        template.subject ?? '',
+        template.bodyText,
+        template.bodyHtml ?? '',
+    ];
+    if (texts.some(hasMalformedPlaceholder)) {
+        problems.push({
+            path: 'bodyText',
+            message: 'Write placeholders as {{name}}, with matching braces',
+        });
+    }
+    const used = new Set(texts.flatMap(templatePlaceholders));
+    const declared = template.variables.map((variable) => variable.name);
+    const declaredSet = new Set(declared);
+    if (declaredSet.size !== declared.length) {
+        problems.push({ path: 'variables', message: 'Declare each variable once' });
+    }
+    for (const name of used) {
+        if (!declaredSet.has(name)) {
+            problems.push({
+                path: 'variables',
+                message: `{{${name}}} is used but not declared`,
+            });
+        }
+    }
+    for (const name of declaredSet) {
+        if (!used.has(name)) {
+            problems.push({
+                path: 'variables',
+                message: `${name} is declared but not used`,
+            });
+        }
+        if (!(name in definition.variables)) {
+            problems.push({
+                path: 'variables',
+                message: `${definition.label} does not supply ${name}`,
+            });
+        }
+    }
+    for (const name of definition.requiredVariables) {
+        if (!declaredSet.has(name)) {
+            problems.push({
+                path: 'variables',
+                message: `${definition.label} must include {{${name}}}`,
+            });
+        }
+    }
+    return problems;
+}
+/** A new draft. Saved templates are never edited; a change is a new version. */
+export const createTemplateSchema = z
+    .strictObject(templateFields)
+    .superRefine((template, ctx) => {
+    for (const problem of templateProblems(template)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [problem.path],
+            message: problem.message,
+        });
+    }
+});
+export const templateListQuerySchema = z.strictObject({
+    messageType: z.enum(MESSAGE_TYPES).optional(),
+    channel: z.enum(COMMUNICATION_CHANNELS).optional(),
+});
+export const templateResponseSchema = z.object({
+    id: z.uuid(),
+    messageType: z.enum(MESSAGE_TYPES),
+    channel: z.enum(COMMUNICATION_CHANNELS),
+    version: z.number().int(),
+    name: z.string(),
+    subject: z.string().nullable(),
+    bodyText: z.string(),
+    bodyHtml: z.string().nullable(),
+    variables: z.array(z.object({
+        name: z.string(),
+        description: z.string().optional(),
+        example: z.string().optional(),
+    })),
+    status: z.enum(TEMPLATE_STATUSES),
+    createdBy: z.uuid().nullable(),
+    createdAt: utcTimestampSchema,
+    activatedBy: z.uuid().nullable(),
+    activatedAt: utcTimestampSchema.nullable(),
+});
+export const templateListResponseSchema = z.array(templateResponseSchema);
+/** Renders unsaved text, or a saved version, with the catalogue's sample values. */
+export const previewTemplateSchema = z.union([
+    z.strictObject({ templateId: z.uuid() }),
+    z.strictObject(templateFields),
+]);
+export const renderedMessageSchema = z.object({
+    channel: z.enum(COMMUNICATION_CHANNELS),
+    subject: z.string().nullable(),
+    bodyText: z.string(),
+    bodyHtml: z.string().nullable(),
+    /** SMS only: how many 160-character segments it takes. */
+    smsSegments: z.number().int().nullable(),
+});
+export const testSendResponseSchema = z.object({
+    channel: z.enum(COMMUNICATION_CHANNELS),
+    /** The signed-in admin's own address, masked, such as `b***@tbs.coach`. */
+    sentTo: z.string(),
+});
+/** A catalogue entry, with the built-in default template for each channel. */
+export const messageTypeResponseSchema = z.object({
+    type: z.enum(MESSAGE_TYPES),
+    label: z.string(),
+    description: z.string(),
+    channels: z.array(z.enum(COMMUNICATION_CHANNELS)),
+    variables: z.array(z.object({
+        name: z.string(),
+        description: z.string(),
+        example: z.string(),
+    })),
+    requiredVariables: z.array(z.string()),
+    defaults: z.array(z.object({
+        channel: z.enum(COMMUNICATION_CHANNELS),
+        subject: z.string().nullable(),
+        bodyText: z.string(),
+        bodyHtml: z.string().nullable(),
+        variables: z.array(z.object({ name: z.string() })),
+    })),
+});
+export const messageTypeListResponseSchema = z.array(messageTypeResponseSchema);

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

@@ -12,9 +12,35 @@ export type AccountStatus = (typeof ACCOUNT_STATUSES)[number];
 /** The statuses an administrator may set. Verification is never set by hand. */
 export declare const ADMIN_SETTABLE_ACCOUNT_STATUSES: readonly ["active", "disabled"];
 export type AdminSettableAccountStatus = (typeof ADMIN_SETTABLE_ACCOUNT_STATUSES)[number];
+/**
+ * Where a user's time zone came from. `AUTO` was detected from their browser
+ * and may be updated when they sign in elsewhere. `MANUAL` was chosen by the
+ * user, and only the user changes it.
+ */
+export declare const TIMEZONE_SOURCES: readonly ["AUTO", "MANUAL"];
+export type TimezoneSource = (typeof TIMEZONE_SOURCES)[number];
 export declare const TOKEN_TRANSPORTS: readonly ["body", "cookie"];
 export type TokenTransport = (typeof TOKEN_TRANSPORTS)[number];
 export declare const AUDIT_OUTCOMES: readonly ["success", "failure"];
 export type AuditOutcome = (typeof AUDIT_OUTCOMES)[number];
 export declare const FEATURE_FLAG_RULE_TYPES: readonly ["user", "customer", "trainer", "role"];
 export type FeatureFlagRuleType = (typeof FEATURE_FLAG_RULE_TYPES)[number];
+/**
+ * The ways a message can reach someone. WhatsApp and push are added here when
+ * their channel modules are built.
+ */
+export declare const COMMUNICATION_CHANNELS: readonly ["EMAIL", "SMS"];
+export type CommunicationChannel = (typeof COMMUNICATION_CHANNELS)[number];
+/**
+ * Every message the platform sends. Each has a catalogue entry in
+ * `@tbs-fitness/contract/communication` saying which channels may carry it and
+ * which variables its sender supplies.
+ */
+export declare const MESSAGE_TYPES: readonly ["auth.otp.signup_verification", "auth.otp.password_reset", "auth.password_reset_link"];
+export type MessageType = (typeof MESSAGE_TYPES)[number];
+/** What happened to one message on one channel. */
+export declare const DELIVERY_STATUSES: readonly ["sent", "skipped_disabled", "skipped_unreachable", "failed", "failed_missing_variables"];
+export type DeliveryStatus = (typeof DELIVERY_STATUSES)[number];
+/** Only one version of a template per message type and channel is active. */
+export declare const TEMPLATE_STATUSES: readonly ["draft", "active", "archived"];
+export type TemplateStatus = (typeof TEMPLATE_STATUSES)[number];