@tbs-fitness/contract 0.1.0 → 0.3.0

package/dist/esm/coach/coach-auth.dto.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { loginSchema, newPasswordSchema, opaqueTokenSchema, otpCodeSchema, timezonePreferenceSchema, tokenResponseSchema, } from '../auth/auth.dto.js';
+import { emailSchema, phoneSchema } from '../common/contact.schema.js';
+import { detectedTimezoneSchema, utcTimestampSchema, } from '../common/date-time.schema.js';
+import { safeTextSchema } from '../common/safe-text.schema.js';
+import { ACCOUNT_STATUSES } from '../enums/index.js';
+export const coachSignupSchema = z.strictObject({
+    fullName: safeTextSchema(100).pipe(z.string().min(2, { error: 'Enter your full name' })),
+    email: emailSchema,
+    phone: phoneSchema.optional(),
+    password: newPasswordSchema,
+    /** The browser's time zone. Missing or unusable becomes UTC on the server. */
+    timezone: detectedTimezoneSchema,
+});
+/** Used by both resend endpoints and by forgot-password. */
+export const otpEmailSchema = z.strictObject({ email: emailSchema });
+export const verifyOtpSchema = z.strictObject({
+    email: emailSchema,
+    code: otpCodeSchema,
+});
+/**
+ * Coaches sign in from the browser, so the refresh token always travels in an
+ * HttpOnly cookie. `rememberMe: false` makes that cookie end with the browser
+ * session instead of persisting.
+ */
+export const coachLoginSchema = loginSchema
+    .omit({ tokenTransport: true })
+    .extend({
+    rememberMe: z.boolean().default(true),
+    /**
+     * The browser's time zone. It replaces the saved one only while the
+     * coach's preference is `AUTO`; a manual choice is never overwritten.
+     */
+    timezone: detectedTimezoneSchema,
+});
+export const resetPasswordSchema = z.strictObject({
+    resetToken: opaqueTokenSchema,
+    newPassword: newPasswordSchema,
+});
+/**
+ * Says what the client needs to drive the code screen, and nothing about
+ * whether the email belongs to an account: the same values are returned either
+ * way.
+ */
+export const otpDispatchResponseSchema = z.object({
+    message: z.string(),
+    otpLength: z.number().int(),
+    expiresInSeconds: z.number().int(),
+    resendAvailableInSeconds: z.number().int(),
+});
+export const signupVerifiedResponseSchema = z.object({
+    message: z.string(),
+});
+/** Issued only after a recovery code is verified. It can reset a password once. */
+export const resetTokenResponseSchema = z.object({
+    resetToken: z.string(),
+    expiresInSeconds: z.number().int(),
+});
+export const coachProfileSchema = z
+    .object({
+    id: z.uuid(),
+    email: z.string(),
+    fullName: z.string().nullable(),
+    phone: z.string().nullable(),
+    role: z.literal('COACH'),
+    status: z.enum(ACCOUNT_STATUSES),
+    emailVerifiedAt: utcTimestampSchema.nullable(),
+    lastLoginAt: utcTimestampSchema.nullable(),
+    createdAt: utcTimestampSchema,
+})
+    .extend(timezonePreferenceSchema.shape);
+export const coachLoginResponseSchema = tokenResponseSchema.extend({
+    coach: coachProfileSchema,
+});

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

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

package/dist/esm/coach/index.js

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

package/dist/esm/common/api-response.schema.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { utcTimestampSchema } from './date-time.schema.js';
 import { paginationMetaSchema, } from './pagination.schema.js';
 export const apiErrorResponseSchema = z.object({
     error: z.object({
@@ -13,7 +14,7 @@ export const apiErrorResponseSchema = z.object({
         }))
             .optional(),
         requestId: z.string(),
-        timestamp: z.iso.datetime(),
+        timestamp: utcTimestampSchema,
         path: z.string(),
     }),
 });

package/dist/esm/common/date-time.schema.d.ts

@@ -0,0 +1,39 @@
+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 declare const DEFAULT_TIMEZONE = "UTC";
+/**
+ * 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 declare function isValidTimezone(value: unknown): value is string;
+/** The current IANA name for a zone, such as `Asia/Kolkata` for `Asia/Calcutta`. */
+export declare function canonicalTimezone(value: string): string;
+export declare const timezoneSchema: z.ZodPipe<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>, z.ZodTransform<string, string>>;
+/**
+ * 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 declare const detectedTimezoneSchema: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
+/** An instant in a response: ISO 8601 in UTC, ending in `Z`. */
+export declare const utcTimestampSchema: z.ZodISODateTime;
+/**
+ * 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 declare const instantInputSchema: z.ZodISODateTime;
+/** A calendar date with no time and no zone, such as `2026-11-02`. */
+export declare const dateOnlySchema: z.ZodString;

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/enums/index.d.ts

@@ -1,9 +1,24 @@
 export declare const APP_ENVIRONMENTS: readonly ["development", "staging", "production"];
 export type AppEnvironment = (typeof APP_ENVIRONMENTS)[number];
-export declare const ROLES: readonly ["admin", "trainer", "customer"];
+/** Each user has exactly one role. A new role is added here and nowhere else. */
+export declare const ROLES: readonly ["ADMIN", "COACH", "CUSTOMER"];
 export type Role = (typeof ROLES)[number];
-export declare const ACCOUNT_STATUSES: readonly ["active", "disabled"];
+/**
+ * `pending_verification` is a self-registered user who has not yet proved they
+ * own their email address. Such a user cannot sign in.
+ */
+export declare const ACCOUNT_STATUSES: readonly ["pending_verification", "active", "disabled"];
 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"];

package/dist/esm/enums/index.js

@@ -5,8 +5,25 @@ export const APP_ENVIRONMENTS = [
     'staging',
     'production',
 ];
-export const ROLES = ['admin', 'trainer', 'customer'];
-export const ACCOUNT_STATUSES = ['active', 'disabled'];
+/** Each user has exactly one role. A new role is added here and nowhere else. */
+export const ROLES = ['ADMIN', 'COACH', 'CUSTOMER'];
+/**
+ * `pending_verification` is a self-registered user who has not yet proved they
+ * own their email address. Such a user cannot sign in.
+ */
+export const ACCOUNT_STATUSES = [
+    'pending_verification',
+    'active',
+    'disabled',
+];
+/** The statuses an administrator may set. Verification is never set by hand. */
+export const ADMIN_SETTABLE_ACCOUNT_STATUSES = ['active', 'disabled'];
+/**
+ * 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 const TIMEZONE_SOURCES = ['AUTO', 'MANUAL'];
 export const TOKEN_TRANSPORTS = ['body', 'cookie'];
 export const AUDIT_OUTCOMES = ['success', 'failure'];
 export const FEATURE_FLAG_RULE_TYPES = [

package/dist/esm/feature-flags/feature-flag.dto.d.ts

@@ -41,9 +41,9 @@ export declare const createRuleSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strict>, z.ZodObject<{
     ruleType: z.ZodLiteral<"role">;
     ruleValue: z.ZodEnum<{
-        admin: "admin";
-        trainer: "trainer";
-        customer: "customer";
+        ADMIN: "ADMIN";
+        COACH: "COACH";
+        CUSTOMER: "CUSTOMER";
     }>;
     enabled: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>], "ruleType">;
@@ -67,9 +67,9 @@ export declare const flagListQuerySchema: z.ZodObject<{
 export declare const ruleResponseSchema: z.ZodObject<{
     id: z.ZodUUID;
     ruleType: z.ZodEnum<{
-        trainer: "trainer";
-        customer: "customer";
         user: "user";
+        customer: "customer";
+        trainer: "trainer";
         role: "role";
     }>;
     ruleValue: z.ZodString;
@@ -100,9 +100,9 @@ export declare const flagResponseSchema: z.ZodObject<{
     rules: z.ZodArray<z.ZodObject<{
         id: z.ZodUUID;
         ruleType: z.ZodEnum<{
-            trainer: "trainer";
-            customer: "customer";
             user: "user";
+            customer: "customer";
+            trainer: "trainer";
             role: "role";
         }>;
         ruleValue: z.ZodString;

package/dist/esm/feature-flags/feature-flag.dto.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { instantInputSchema, utcTimestampSchema, } from '../common/date-time.schema.js';
 import { paginationQuerySchema } from '../common/pagination.schema.js';
 import { safeTextSchema } from '../common/safe-text.schema.js';
 import { APP_ENVIRONMENTS, FEATURE_FLAG_RULE_TYPES, ROLES, } from '../enums/index.js';
@@ -14,7 +15,7 @@ const keySchema = z
 const nameSchema = safeTextSchema(120);
 const descriptionSchema = safeTextSchema(500);
 const percentageSchema = z.number().int().min(0).max(100);
-const timestampSchema = z.iso.datetime({ offset: true });
+const timestampSchema = instantInputSchema;
 /** Lower-cased, so that it matches IDs as they come from the database. */
 const accountIdSchema = z.string().toLowerCase().pipe(z.uuid());
 const scheduleIsOrdered = ({ activationAt, expiresAt, }) => !activationAt || !expiresAt || new Date(activationAt) < new Date(expiresAt);
@@ -92,8 +93,8 @@ export const ruleResponseSchema = z.object({
     ruleType: z.enum(FEATURE_FLAG_RULE_TYPES),
     ruleValue: z.string(),
     enabled: z.boolean(),
-    createdAt: z.iso.datetime(),
-    updatedAt: z.iso.datetime(),
+    createdAt: utcTimestampSchema,
+    updatedAt: utcTimestampSchema,
 });
 export const flagResponseSchema = z.object({
     id: z.uuid(),
@@ -103,13 +104,13 @@ export const flagResponseSchema = z.object({
     environment: z.enum(APP_ENVIRONMENTS),
     enabled: z.boolean(),
     rolloutPercentage: z.number().int(),
-    activationAt: z.iso.datetime().nullable(),
-    expiresAt: z.iso.datetime().nullable(),
+    activationAt: utcTimestampSchema.nullable(),
+    expiresAt: utcTimestampSchema.nullable(),
     version: z.number().int(),
     createdBy: z.uuid(),
     updatedBy: z.uuid(),
-    createdAt: z.iso.datetime(),
-    updatedAt: z.iso.datetime(),
+    createdAt: utcTimestampSchema,
+    updatedAt: utcTimestampSchema,
     rules: z.array(ruleResponseSchema),
 });
 export const auditLogResponseSchema = z.object({
@@ -121,12 +122,12 @@ export const auditLogResponseSchema = z.object({
     action: z.string(),
     previousValue: z.record(z.string(), z.unknown()).nullable(),
     newValue: z.record(z.string(), z.unknown()).nullable(),
-    createdAt: z.iso.datetime(),
+    createdAt: utcTimestampSchema,
 });
 export const killSwitchResponseSchema = z.object({
     environment: z.enum(APP_ENVIRONMENTS),
     engaged: z.boolean(),
     reason: z.string().nullable(),
     updatedBy: z.uuid().nullable(),
-    updatedAt: z.iso.datetime().nullable(),
+    updatedAt: utcTimestampSchema.nullable(),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbs-fitness/contract",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "TBS API contract: Zod schemas, DTO types and enums shared by the backend, web and mobile apps",
   "license": "UNLICENSED",
   "type": "module",
@@ -33,6 +33,16 @@
         "default": "./dist/cjs/auth/index.js"
       }
     },
+    "./coach": {
+      "import": {
+        "types": "./dist/esm/coach/index.d.ts",
+        "default": "./dist/esm/coach/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/coach/index.d.ts",
+        "default": "./dist/cjs/coach/index.js"
+      }
+    },
     "./common": {
       "import": {
         "types": "./dist/esm/common/index.d.ts",