@tbs-fitness/contract 0.2.0 → 0.3.0

package/README.md

@@ -41,6 +41,16 @@ 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.3.0
+
+Time zones and the platform's date and time rules. Additive, but a caret range on 0.x does not cross minor versions, so consumers install `^0.3.0` explicitly.
+
+- `/common`: `DEFAULT_TIMEZONE` (`UTC`), `isValidTimezone`, `canonicalTimezone` (the current IANA name for a renamed zone, such as `Asia/Kolkata` for `Asia/Calcutta`, which Node and some browsers still report; both schemas below apply it), `timezoneSchema` (an IANA `Area/Location` name or `UTC`; abbreviations such as `IST` and offsets such as `+05:30` are refused), `detectedTimezoneSchema` (a browser suggestion: unusable values become `undefined`), `utcTimestampSchema` (response instants, `Z` only), `instantInputSchema` (request instants, `Z` or an explicit offset, never a bare local time) and `dateOnlySchema` (`YYYY-MM-DD`, never shifted between zones).
+- `/enums`: `TIMEZONE_SOURCES` (`AUTO`, `MANUAL`).
+- `/auth`: `timezonePreferenceSchema`, `updateTimezoneSchema` (`{ timezone, source? }`, source defaults to `MANUAL`), and `timezone` and `timezoneSource` on `accountResponseSchema`.
+- `/coach`: an optional `timezone` on `coachSignupSchema` and `coachLoginSchema`, and `timezone` and `timezoneSource` on `coachProfileSchema`. Both response fields are required, so deploy the backend before a client built on 0.3.0.
+- Every response timestamp now uses `utcTimestampSchema`, which is the same rule as before. Feature-flag request timestamps use `instantInputSchema`.
+
 ## Version 0.2.0 (breaking)
 
 - `ROLES` is now `ADMIN`, `COACH` and `CUSTOMER`. A user has exactly one role.

package/dist/cjs/audit/audit-log.dto.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.auditLogResponseSchema = exports.auditLogQuerySchema = 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 index_js_1 = require("../enums/index.js");
 exports.auditLogQuerySchema = pagination_schema_js_1.paginationQuerySchema.extend({
@@ -20,5 +21,5 @@ exports.auditLogResponseSchema = zod_1.z.object({
     requestId: zod_1.z.string().nullable(),
     correlationId: zod_1.z.string().nullable(),
     metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
-    createdAt: zod_1.z.iso.datetime(),
+    createdAt: date_time_schema_js_1.utcTimestampSchema,
 });

package/dist/cjs/auth/auth.dto.d.ts

@@ -68,6 +68,32 @@ export declare const tokenResponseSchema: z.ZodObject<{
     sessionId: z.ZodUUID;
 }, z.core.$strip>;
 export type TokenResponse = z.output<typeof tokenResponseSchema>;
+/**
+ * A user's time zone preference: an IANA zone, and whether it was detected
+ * (`AUTO`) or chosen (`MANUAL`).
+ */
+export declare const timezonePreferenceSchema: z.ZodObject<{
+    timezone: z.ZodString;
+    timezoneSource: z.ZodEnum<{
+        AUTO: "AUTO";
+        MANUAL: "MANUAL";
+    }>;
+}, z.core.$strip>;
+export type TimezonePreference = z.output<typeof timezonePreferenceSchema>;
+/**
+ * Sets the signed-in user's own time zone. `MANUAL` (the default) is a choice
+ * the user made. `AUTO` records a detected zone that a later sign-in may
+ * replace.
+ */
+export declare const updateTimezoneSchema: z.ZodObject<{
+    timezone: z.ZodPipe<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>, z.ZodTransform<string, string>>;
+    source: z.ZodDefault<z.ZodEnum<{
+        AUTO: "AUTO";
+        MANUAL: "MANUAL";
+    }>>;
+}, z.core.$strict>;
+export type UpdateTimezoneInput = z.input<typeof updateTimezoneSchema>;
+export type UpdateTimezoneBody = z.output<typeof updateTimezoneSchema>;
 export declare const accountResponseSchema: z.ZodObject<{
     id: z.ZodUUID;
     email: z.ZodString;
@@ -79,6 +105,11 @@ export declare const accountResponseSchema: z.ZodObject<{
     roles: z.ZodArray<z.ZodString>;
     permissions: z.ZodArray<z.ZodString>;
     lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
+    timezone: z.ZodString;
+    timezoneSource: z.ZodEnum<{
+        AUTO: "AUTO";
+        MANUAL: "MANUAL";
+    }>;
 }, z.core.$strip>;
 export type AccountResponse = z.output<typeof accountResponseSchema>;
 export declare const loginResponseSchema: z.ZodObject<{
@@ -99,6 +130,11 @@ export declare const loginResponseSchema: z.ZodObject<{
         roles: z.ZodArray<z.ZodString>;
         permissions: z.ZodArray<z.ZodString>;
         lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
+        timezone: z.ZodString;
+        timezoneSource: z.ZodEnum<{
+            AUTO: "AUTO";
+            MANUAL: "MANUAL";
+        }>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type LoginResponse = z.output<typeof loginResponseSchema>;

package/dist/cjs/auth/auth.dto.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.revokedSessionsResponseSchema = exports.adminAccountResponseSchema = exports.passwordResetRequestedResponseSchema = exports.logoutAllResponseSchema = exports.sessionResponseSchema = exports.loginResponseSchema = exports.accountResponseSchema = exports.tokenResponseSchema = exports.idParamSchema = exports.setStatusSchema = exports.setRoleSchema = exports.passwordResetConfirmSchema = exports.passwordResetRequestSchema = exports.changePasswordSchema = exports.refreshSchema = exports.loginSchema = exports.opaqueTokenSchema = exports.submittedPasswordSchema = exports.newPasswordSchema = exports.otpCodeSchema = exports.OTP_LENGTH = exports.MAX_PASSWORD_LENGTH = exports.MIN_PASSWORD_LENGTH = void 0;
+exports.revokedSessionsResponseSchema = exports.adminAccountResponseSchema = exports.passwordResetRequestedResponseSchema = exports.logoutAllResponseSchema = exports.sessionResponseSchema = exports.loginResponseSchema = exports.accountResponseSchema = exports.updateTimezoneSchema = exports.timezonePreferenceSchema = exports.tokenResponseSchema = exports.idParamSchema = exports.setStatusSchema = exports.setRoleSchema = exports.passwordResetConfirmSchema = exports.passwordResetRequestSchema = exports.changePasswordSchema = exports.refreshSchema = exports.loginSchema = exports.opaqueTokenSchema = exports.submittedPasswordSchema = exports.newPasswordSchema = exports.otpCodeSchema = exports.OTP_LENGTH = exports.MAX_PASSWORD_LENGTH = exports.MIN_PASSWORD_LENGTH = void 0;
 const zod_1 = require("zod");
 const contact_schema_js_1 = require("../common/contact.schema.js");
+const date_time_schema_js_1 = require("../common/date-time.schema.js");
 const safe_text_schema_js_1 = require("../common/safe-text.schema.js");
 const index_js_1 = require("../enums/index.js");
 // Per OWASP: length is what matters, with no composition rules. The upper limit
@@ -65,15 +66,34 @@ exports.tokenResponseSchema = zod_1.z.object({
     csrfToken: zod_1.z.string().optional(),
     sessionId: zod_1.z.uuid(),
 });
-exports.accountResponseSchema = zod_1.z.object({
+/**
+ * A user's time zone preference: an IANA zone, and whether it was detected
+ * (`AUTO`) or chosen (`MANUAL`).
+ */
+exports.timezonePreferenceSchema = zod_1.z.object({
+    timezone: zod_1.z.string(),
+    timezoneSource: zod_1.z.enum(index_js_1.TIMEZONE_SOURCES),
+});
+/**
+ * Sets the signed-in user's own time zone. `MANUAL` (the default) is a choice
+ * the user made. `AUTO` records a detected zone that a later sign-in may
+ * replace.
+ */
+exports.updateTimezoneSchema = zod_1.z.strictObject({
+    timezone: date_time_schema_js_1.timezoneSchema,
+    source: zod_1.z.enum(index_js_1.TIMEZONE_SOURCES).default('MANUAL'),
+});
+exports.accountResponseSchema = zod_1.z
+    .object({
     id: zod_1.z.uuid(),
     email: zod_1.z.string(),
     role: zod_1.z.enum(index_js_1.ROLES),
     /** @deprecated Always `[role]`. Kept for clients written before `role`. */
     roles: zod_1.z.array(zod_1.z.string()),
     permissions: zod_1.z.array(zod_1.z.string()),
-    lastLoginAt: zod_1.z.iso.datetime().nullable(),
-});
+    lastLoginAt: date_time_schema_js_1.utcTimestampSchema.nullable(),
+})
+    .extend(exports.timezonePreferenceSchema.shape);
 exports.loginResponseSchema = exports.tokenResponseSchema.extend({
     account: exports.accountResponseSchema,
 });
@@ -81,9 +101,9 @@ exports.sessionResponseSchema = zod_1.z.object({
     id: zod_1.z.uuid(),
     deviceName: zod_1.z.string().nullable(),
     userAgent: zod_1.z.string().nullable(),
-    createdAt: zod_1.z.iso.datetime(),
-    lastUsedAt: zod_1.z.iso.datetime(),
-    expiresAt: zod_1.z.iso.datetime(),
+    createdAt: date_time_schema_js_1.utcTimestampSchema,
+    lastUsedAt: date_time_schema_js_1.utcTimestampSchema,
+    expiresAt: date_time_schema_js_1.utcTimestampSchema,
     current: zod_1.z.boolean(),
 });
 exports.logoutAllResponseSchema = zod_1.z.object({
@@ -97,7 +117,7 @@ exports.adminAccountResponseSchema = zod_1.z.object({
     email: zod_1.z.string(),
     role: zod_1.z.enum(index_js_1.ROLES),
     status: zod_1.z.enum(index_js_1.ACCOUNT_STATUSES),
-    lastLoginAt: zod_1.z.iso.datetime().nullable(),
+    lastLoginAt: date_time_schema_js_1.utcTimestampSchema.nullable(),
 });
 exports.revokedSessionsResponseSchema = zod_1.z.object({
     revokedSessions: zod_1.z.number().int(),

package/dist/cjs/coach/coach-auth.dto.d.ts

@@ -4,6 +4,7 @@ export declare const coachSignupSchema: z.ZodObject<{
     email: z.ZodPipe<z.ZodString, z.ZodEmail>;
     phone: z.ZodOptional<z.ZodString>;
     password: z.ZodString;
+    timezone: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
 }, z.core.$strict>;
 export type CoachSignupInput = z.input<typeof coachSignupSchema>;
 export type CoachSignupBody = z.output<typeof coachSignupSchema>;
@@ -29,6 +30,7 @@ export declare const coachLoginSchema: z.ZodObject<{
     password: z.ZodString;
     deviceName: z.ZodOptional<z.ZodString>;
     rememberMe: z.ZodDefault<z.ZodBoolean>;
+    timezone: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
 }, z.core.$strict>;
 export type CoachLoginInput = z.input<typeof coachLoginSchema>;
 export type CoachLoginBody = z.output<typeof coachLoginSchema>;
@@ -74,6 +76,11 @@ export declare const coachProfileSchema: z.ZodObject<{
     emailVerifiedAt: z.ZodNullable<z.ZodISODateTime>;
     lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
     createdAt: z.ZodISODateTime;
+    timezone: z.ZodString;
+    timezoneSource: z.ZodEnum<{
+        AUTO: "AUTO";
+        MANUAL: "MANUAL";
+    }>;
 }, z.core.$strip>;
 export type CoachProfile = z.output<typeof coachProfileSchema>;
 export declare const coachLoginResponseSchema: z.ZodObject<{
@@ -97,6 +104,11 @@ export declare const coachLoginResponseSchema: z.ZodObject<{
         emailVerifiedAt: z.ZodNullable<z.ZodISODateTime>;
         lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
         createdAt: z.ZodISODateTime;
+        timezone: z.ZodString;
+        timezoneSource: z.ZodEnum<{
+            AUTO: "AUTO";
+            MANUAL: "MANUAL";
+        }>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type CoachLoginResponse = z.output<typeof coachLoginResponseSchema>;

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

@@ -4,6 +4,7 @@ exports.coachLoginResponseSchema = exports.coachProfileSchema = exports.resetTok
 const zod_1 = require("zod");
 const auth_dto_js_1 = require("../auth/auth.dto.js");
 const contact_schema_js_1 = require("../common/contact.schema.js");
+const date_time_schema_js_1 = require("../common/date-time.schema.js");
 const safe_text_schema_js_1 = require("../common/safe-text.schema.js");
 const index_js_1 = require("../enums/index.js");
 exports.coachSignupSchema = zod_1.z.strictObject({
@@ -11,6 +12,8 @@ exports.coachSignupSchema = zod_1.z.strictObject({
     email: contact_schema_js_1.emailSchema,
     phone: contact_schema_js_1.phoneSchema.optional(),
     password: auth_dto_js_1.newPasswordSchema,
+    /** The browser's time zone. Missing or unusable becomes UTC on the server. */
+    timezone: date_time_schema_js_1.detectedTimezoneSchema,
 });
 /** Used by both resend endpoints and by forgot-password. */
 exports.otpEmailSchema = zod_1.z.strictObject({ email: contact_schema_js_1.emailSchema });
@@ -25,7 +28,14 @@ exports.verifyOtpSchema = zod_1.z.strictObject({
  */
 exports.coachLoginSchema = auth_dto_js_1.loginSchema
     .omit({ tokenTransport: true })
-    .extend({ rememberMe: zod_1.z.boolean().default(true) });
+    .extend({
+    rememberMe: zod_1.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: date_time_schema_js_1.detectedTimezoneSchema,
+});
 exports.resetPasswordSchema = zod_1.z.strictObject({
     resetToken: auth_dto_js_1.opaqueTokenSchema,
     newPassword: auth_dto_js_1.newPasswordSchema,
@@ -49,17 +59,19 @@ exports.resetTokenResponseSchema = zod_1.z.object({
     resetToken: zod_1.z.string(),
     expiresInSeconds: zod_1.z.number().int(),
 });
-exports.coachProfileSchema = zod_1.z.object({
+exports.coachProfileSchema = zod_1.z
+    .object({
     id: zod_1.z.uuid(),
     email: zod_1.z.string(),
     fullName: zod_1.z.string().nullable(),
     phone: zod_1.z.string().nullable(),
     role: zod_1.z.literal('COACH'),
     status: zod_1.z.enum(index_js_1.ACCOUNT_STATUSES),
-    emailVerifiedAt: zod_1.z.iso.datetime().nullable(),
-    lastLoginAt: zod_1.z.iso.datetime().nullable(),
-    createdAt: zod_1.z.iso.datetime(),
-});
+    emailVerifiedAt: date_time_schema_js_1.utcTimestampSchema.nullable(),
+    lastLoginAt: date_time_schema_js_1.utcTimestampSchema.nullable(),
+    createdAt: date_time_schema_js_1.utcTimestampSchema,
+})
+    .extend(auth_dto_js_1.timezonePreferenceSchema.shape);
 exports.coachLoginResponseSchema = auth_dto_js_1.tokenResponseSchema.extend({
     coach: exports.coachProfileSchema,
 });

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.paginatedResponseSchema = exports.dataResponseSchema = exports.apiErrorResponseSchema = void 0;
 const zod_1 = require("zod");
+const date_time_schema_js_1 = require("./date-time.schema.js");
 const pagination_schema_js_1 = require("./pagination.schema.js");
 exports.apiErrorResponseSchema = zod_1.z.object({
     error: zod_1.z.object({
@@ -16,7 +17,7 @@ exports.apiErrorResponseSchema = zod_1.z.object({
         }))
             .optional(),
         requestId: zod_1.z.string(),
-        timestamp: zod_1.z.iso.datetime(),
+        timestamp: date_time_schema_js_1.utcTimestampSchema,
         path: zod_1.z.string(),
     }),
 });

package/dist/cjs/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/cjs/common/date-time.schema.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dateOnlySchema = exports.instantInputSchema = exports.utcTimestampSchema = exports.detectedTimezoneSchema = exports.timezoneSchema = exports.DEFAULT_TIMEZONE = void 0;
+exports.isValidTimezone = isValidTimezone;
+exports.canonicalTimezone = canonicalTimezone;
+const zod_1 = require("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.
+ */
+exports.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.
+ */
+function isValidTimezone(value) {
+    if (typeof value !== 'string' || value.length > MAX_TIMEZONE_LENGTH) {
+        return false;
+    }
+    if (value !== exports.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`. */
+function canonicalTimezone(value) {
+    return RENAMED_TIMEZONES[value] ?? value;
+}
+exports.timezoneSchema = zod_1.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.
+ */
+exports.detectedTimezoneSchema = zod_1.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`. */
+exports.utcTimestampSchema = zod_1.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.
+ */
+exports.instantInputSchema = zod_1.z.iso.datetime({ offset: true });
+/** A calendar date with no time and no zone, such as `2026-11-02`. */
+exports.dateOnlySchema = zod_1.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/cjs/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/cjs/common/index.js

@@ -16,5 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./api-response.schema.js"), exports);
 __exportStar(require("./contact.schema.js"), exports);
+__exportStar(require("./date-time.schema.js"), exports);
 __exportStar(require("./pagination.schema.js"), exports);
 __exportStar(require("./safe-text.schema.js"), exports);

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

@@ -12,6 +12,13 @@ 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/cjs/enums/index.js

@@ -2,7 +2,7 @@
 // These values are stored in the database and sent over the API. Renaming or
 // removing one is a breaking change, so it needs a major version.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FEATURE_FLAG_RULE_TYPES = exports.AUDIT_OUTCOMES = exports.TOKEN_TRANSPORTS = exports.ADMIN_SETTABLE_ACCOUNT_STATUSES = exports.ACCOUNT_STATUSES = exports.ROLES = exports.APP_ENVIRONMENTS = void 0;
+exports.FEATURE_FLAG_RULE_TYPES = exports.AUDIT_OUTCOMES = exports.TOKEN_TRANSPORTS = exports.TIMEZONE_SOURCES = exports.ADMIN_SETTABLE_ACCOUNT_STATUSES = exports.ACCOUNT_STATUSES = exports.ROLES = exports.APP_ENVIRONMENTS = void 0;
 exports.APP_ENVIRONMENTS = [
     'development',
     'staging',
@@ -21,6 +21,12 @@ exports.ACCOUNT_STATUSES = [
 ];
 /** The statuses an administrator may set. Verification is never set by hand. */
 exports.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.
+ */
+exports.TIMEZONE_SOURCES = ['AUTO', 'MANUAL'];
 exports.TOKEN_TRANSPORTS = ['body', 'cookie'];
 exports.AUDIT_OUTCOMES = ['success', 'failure'];
 exports.FEATURE_FLAG_RULE_TYPES = [

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.killSwitchResponseSchema = exports.auditLogResponseSchema = exports.flagResponseSchema = exports.ruleResponseSchema = exports.flagListQuerySchema = exports.setKillSwitchSchema = exports.updateRuleSchema = exports.createRuleSchema = exports.updateFlagSchema = exports.createFlagSchema = exports.flagIdParamSchema = 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");
@@ -17,7 +18,7 @@ const keySchema = zod_1.z
 const nameSchema = (0, safe_text_schema_js_1.safeTextSchema)(120);
 const descriptionSchema = (0, safe_text_schema_js_1.safeTextSchema)(500);
 const percentageSchema = zod_1.z.number().int().min(0).max(100);
-const timestampSchema = zod_1.z.iso.datetime({ offset: true });
+const timestampSchema = date_time_schema_js_1.instantInputSchema;
 /** Lower-cased, so that it matches IDs as they come from the database. */
 const accountIdSchema = zod_1.z.string().toLowerCase().pipe(zod_1.z.uuid());
 const scheduleIsOrdered = ({ activationAt, expiresAt, }) => !activationAt || !expiresAt || new Date(activationAt) < new Date(expiresAt);
@@ -95,8 +96,8 @@ exports.ruleResponseSchema = zod_1.z.object({
     ruleType: zod_1.z.enum(index_js_1.FEATURE_FLAG_RULE_TYPES),
     ruleValue: zod_1.z.string(),
     enabled: zod_1.z.boolean(),
-    createdAt: zod_1.z.iso.datetime(),
-    updatedAt: zod_1.z.iso.datetime(),
+    createdAt: date_time_schema_js_1.utcTimestampSchema,
+    updatedAt: date_time_schema_js_1.utcTimestampSchema,
 });
 exports.flagResponseSchema = zod_1.z.object({
     id: zod_1.z.uuid(),
@@ -106,13 +107,13 @@ exports.flagResponseSchema = zod_1.z.object({
     environment: zod_1.z.enum(index_js_1.APP_ENVIRONMENTS),
     enabled: zod_1.z.boolean(),
     rolloutPercentage: zod_1.z.number().int(),
-    activationAt: zod_1.z.iso.datetime().nullable(),
-    expiresAt: zod_1.z.iso.datetime().nullable(),
+    activationAt: date_time_schema_js_1.utcTimestampSchema.nullable(),
+    expiresAt: date_time_schema_js_1.utcTimestampSchema.nullable(),
     version: zod_1.z.number().int(),
     createdBy: zod_1.z.uuid(),
     updatedBy: zod_1.z.uuid(),
-    createdAt: zod_1.z.iso.datetime(),
-    updatedAt: zod_1.z.iso.datetime(),
+    createdAt: date_time_schema_js_1.utcTimestampSchema,
+    updatedAt: date_time_schema_js_1.utcTimestampSchema,
     rules: zod_1.z.array(exports.ruleResponseSchema),
 });
 exports.auditLogResponseSchema = zod_1.z.object({
@@ -124,12 +125,12 @@ exports.auditLogResponseSchema = zod_1.z.object({
     action: zod_1.z.string(),
     previousValue: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
     newValue: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).nullable(),
-    createdAt: zod_1.z.iso.datetime(),
+    createdAt: date_time_schema_js_1.utcTimestampSchema,
 });
 exports.killSwitchResponseSchema = zod_1.z.object({
     environment: zod_1.z.enum(index_js_1.APP_ENVIRONMENTS),
     engaged: zod_1.z.boolean(),
     reason: zod_1.z.string().nullable(),
     updatedBy: zod_1.z.uuid().nullable(),
-    updatedAt: zod_1.z.iso.datetime().nullable(),
+    updatedAt: date_time_schema_js_1.utcTimestampSchema.nullable(),
 });

package/dist/esm/audit/audit-log.dto.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { utcTimestampSchema } from '../common/date-time.schema.js';
 import { paginationQuerySchema } from '../common/pagination.schema.js';
 import { AUDIT_OUTCOMES } from '../enums/index.js';
 export const auditLogQuerySchema = paginationQuerySchema.extend({
@@ -17,5 +18,5 @@ export const auditLogResponseSchema = z.object({
     requestId: z.string().nullable(),
     correlationId: z.string().nullable(),
     metadata: z.record(z.string(), z.unknown()).nullable(),
-    createdAt: z.iso.datetime(),
+    createdAt: utcTimestampSchema,
 });

package/dist/esm/auth/auth.dto.d.ts

@@ -68,6 +68,32 @@ export declare const tokenResponseSchema: z.ZodObject<{
     sessionId: z.ZodUUID;
 }, z.core.$strip>;
 export type TokenResponse = z.output<typeof tokenResponseSchema>;
+/**
+ * A user's time zone preference: an IANA zone, and whether it was detected
+ * (`AUTO`) or chosen (`MANUAL`).
+ */
+export declare const timezonePreferenceSchema: z.ZodObject<{
+    timezone: z.ZodString;
+    timezoneSource: z.ZodEnum<{
+        AUTO: "AUTO";
+        MANUAL: "MANUAL";
+    }>;
+}, z.core.$strip>;
+export type TimezonePreference = z.output<typeof timezonePreferenceSchema>;
+/**
+ * Sets the signed-in user's own time zone. `MANUAL` (the default) is a choice
+ * the user made. `AUTO` records a detected zone that a later sign-in may
+ * replace.
+ */
+export declare const updateTimezoneSchema: z.ZodObject<{
+    timezone: z.ZodPipe<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>, z.ZodTransform<string, string>>;
+    source: z.ZodDefault<z.ZodEnum<{
+        AUTO: "AUTO";
+        MANUAL: "MANUAL";
+    }>>;
+}, z.core.$strict>;
+export type UpdateTimezoneInput = z.input<typeof updateTimezoneSchema>;
+export type UpdateTimezoneBody = z.output<typeof updateTimezoneSchema>;
 export declare const accountResponseSchema: z.ZodObject<{
     id: z.ZodUUID;
     email: z.ZodString;
@@ -79,6 +105,11 @@ export declare const accountResponseSchema: z.ZodObject<{
     roles: z.ZodArray<z.ZodString>;
     permissions: z.ZodArray<z.ZodString>;
     lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
+    timezone: z.ZodString;
+    timezoneSource: z.ZodEnum<{
+        AUTO: "AUTO";
+        MANUAL: "MANUAL";
+    }>;
 }, z.core.$strip>;
 export type AccountResponse = z.output<typeof accountResponseSchema>;
 export declare const loginResponseSchema: z.ZodObject<{
@@ -99,6 +130,11 @@ export declare const loginResponseSchema: z.ZodObject<{
         roles: z.ZodArray<z.ZodString>;
         permissions: z.ZodArray<z.ZodString>;
         lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
+        timezone: z.ZodString;
+        timezoneSource: z.ZodEnum<{
+            AUTO: "AUTO";
+            MANUAL: "MANUAL";
+        }>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type LoginResponse = z.output<typeof loginResponseSchema>;

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

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { emailSchema } from '../common/contact.schema.js';
+import { timezoneSchema, utcTimestampSchema, } from '../common/date-time.schema.js';
 import { safeTextSchema } from '../common/safe-text.schema.js';
-import { ACCOUNT_STATUSES, ADMIN_SETTABLE_ACCOUNT_STATUSES, ROLES, TOKEN_TRANSPORTS, } from '../enums/index.js';
+import { ACCOUNT_STATUSES, ADMIN_SETTABLE_ACCOUNT_STATUSES, ROLES, TIMEZONE_SOURCES, TOKEN_TRANSPORTS, } from '../enums/index.js';
 // Per OWASP: length is what matters, with no composition rules. The upper limit
 // stops very long inputs from being used to exhaust the hashing function.
 export const MIN_PASSWORD_LENGTH = 12;
@@ -62,15 +63,34 @@ export const tokenResponseSchema = z.object({
     csrfToken: z.string().optional(),
     sessionId: z.uuid(),
 });
-export const accountResponseSchema = z.object({
+/**
+ * A user's time zone preference: an IANA zone, and whether it was detected
+ * (`AUTO`) or chosen (`MANUAL`).
+ */
+export const timezonePreferenceSchema = z.object({
+    timezone: z.string(),
+    timezoneSource: z.enum(TIMEZONE_SOURCES),
+});
+/**
+ * Sets the signed-in user's own time zone. `MANUAL` (the default) is a choice
+ * the user made. `AUTO` records a detected zone that a later sign-in may
+ * replace.
+ */
+export const updateTimezoneSchema = z.strictObject({
+    timezone: timezoneSchema,
+    source: z.enum(TIMEZONE_SOURCES).default('MANUAL'),
+});
+export const accountResponseSchema = z
+    .object({
     id: z.uuid(),
     email: z.string(),
     role: z.enum(ROLES),
     /** @deprecated Always `[role]`. Kept for clients written before `role`. */
     roles: z.array(z.string()),
     permissions: z.array(z.string()),
-    lastLoginAt: z.iso.datetime().nullable(),
-});
+    lastLoginAt: utcTimestampSchema.nullable(),
+})
+    .extend(timezonePreferenceSchema.shape);
 export const loginResponseSchema = tokenResponseSchema.extend({
     account: accountResponseSchema,
 });
@@ -78,9 +98,9 @@ export const sessionResponseSchema = z.object({
     id: z.uuid(),
     deviceName: z.string().nullable(),
     userAgent: z.string().nullable(),
-    createdAt: z.iso.datetime(),
-    lastUsedAt: z.iso.datetime(),
-    expiresAt: z.iso.datetime(),
+    createdAt: utcTimestampSchema,
+    lastUsedAt: utcTimestampSchema,
+    expiresAt: utcTimestampSchema,
     current: z.boolean(),
 });
 export const logoutAllResponseSchema = z.object({
@@ -94,7 +114,7 @@ export const adminAccountResponseSchema = z.object({
     email: z.string(),
     role: z.enum(ROLES),
     status: z.enum(ACCOUNT_STATUSES),
-    lastLoginAt: z.iso.datetime().nullable(),
+    lastLoginAt: utcTimestampSchema.nullable(),
 });
 export const revokedSessionsResponseSchema = z.object({
     revokedSessions: z.number().int(),

package/dist/esm/coach/coach-auth.dto.d.ts

@@ -4,6 +4,7 @@ export declare const coachSignupSchema: z.ZodObject<{
     email: z.ZodPipe<z.ZodString, z.ZodEmail>;
     phone: z.ZodOptional<z.ZodString>;
     password: z.ZodString;
+    timezone: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
 }, z.core.$strict>;
 export type CoachSignupInput = z.input<typeof coachSignupSchema>;
 export type CoachSignupBody = z.output<typeof coachSignupSchema>;
@@ -29,6 +30,7 @@ export declare const coachLoginSchema: z.ZodObject<{
     password: z.ZodString;
     deviceName: z.ZodOptional<z.ZodString>;
     rememberMe: z.ZodDefault<z.ZodBoolean>;
+    timezone: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodTransform<string | undefined, unknown>>>;
 }, z.core.$strict>;
 export type CoachLoginInput = z.input<typeof coachLoginSchema>;
 export type CoachLoginBody = z.output<typeof coachLoginSchema>;
@@ -74,6 +76,11 @@ export declare const coachProfileSchema: z.ZodObject<{
     emailVerifiedAt: z.ZodNullable<z.ZodISODateTime>;
     lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
     createdAt: z.ZodISODateTime;
+    timezone: z.ZodString;
+    timezoneSource: z.ZodEnum<{
+        AUTO: "AUTO";
+        MANUAL: "MANUAL";
+    }>;
 }, z.core.$strip>;
 export type CoachProfile = z.output<typeof coachProfileSchema>;
 export declare const coachLoginResponseSchema: z.ZodObject<{
@@ -97,6 +104,11 @@ export declare const coachLoginResponseSchema: z.ZodObject<{
         emailVerifiedAt: z.ZodNullable<z.ZodISODateTime>;
         lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
         createdAt: z.ZodISODateTime;
+        timezone: z.ZodString;
+        timezoneSource: z.ZodEnum<{
+            AUTO: "AUTO";
+            MANUAL: "MANUAL";
+        }>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type CoachLoginResponse = z.output<typeof coachLoginResponseSchema>;

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

@@ -1,6 +1,7 @@
 import { z } from 'zod';
-import { loginSchema, newPasswordSchema, opaqueTokenSchema, otpCodeSchema, tokenResponseSchema, } from '../auth/auth.dto.js';
+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({
@@ -8,6 +9,8 @@ export const coachSignupSchema = z.strictObject({
     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 });
@@ -22,7 +25,14 @@ export const verifyOtpSchema = z.strictObject({
  */
 export const coachLoginSchema = loginSchema
     .omit({ tokenTransport: true })
-    .extend({ rememberMe: z.boolean().default(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,
@@ -46,17 +56,19 @@ export const resetTokenResponseSchema = z.object({
     resetToken: z.string(),
     expiresInSeconds: z.number().int(),
 });
-export const coachProfileSchema = z.object({
+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: z.iso.datetime().nullable(),
-    lastLoginAt: z.iso.datetime().nullable(),
-    createdAt: z.iso.datetime(),
-});
+    emailVerifiedAt: utcTimestampSchema.nullable(),
+    lastLoginAt: utcTimestampSchema.nullable(),
+    createdAt: utcTimestampSchema,
+})
+    .extend(timezonePreferenceSchema.shape);
 export const coachLoginResponseSchema = tokenResponseSchema.extend({
     coach: coachProfileSchema,
 });

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

@@ -12,6 +12,13 @@ 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

@@ -18,6 +18,12 @@ export const ACCOUNT_STATUSES = [
 ];
 /** 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.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.2.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",