@tbs-fitness/contract 0.2.0 → 0.4.0

package/README.md

@@ -41,6 +41,27 @@ 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.4.0
+
+Communication and runtime settings. Additive; consumers install `^0.4.0` explicitly.
+
+- `/enums`: `COMMUNICATION_CHANNELS` (`EMAIL`, `SMS`), `MESSAGE_TYPES`, `DELIVERY_STATUSES` and `TEMPLATE_STATUSES`.
+- New `/communication`:
+  - `MESSAGE_CATALOGUE`: per message type, the channels that may carry it, the default switches, and the variables its sender supplies, with the required ones.
+  - `templatePlaceholders`, `hasMalformedPlaceholder` and `templateProblems`, the template rules shared by the server and the admin editor.
+  - `createTemplateSchema`, `templateResponseSchema`, `previewTemplateSchema`, `renderedMessageSchema`, `testSendResponseSchema` and `messageTypeResponseSchema`.
+- New `/app-settings`: `APP_SETTING_KEYS`, a value schema and default per key (`communication.channels` master switches, `communication.messages` per type and channel), plus `appSettingResponseSchema`, `updateAppSettingSchema` (`{ value, version }`) and `appSettingHistoryResponseSchema`.
+
+## 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/app-settings/app-settings.dto.d.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+import { type MessageType } from '../enums/index.js';
+/**
+ * Runtime settings an administrator changes without a deploy. Each key has a
+ * value schema here, which both the server and the admin screen use. A key
+ * with no saved value uses its default.
+ */
+export declare const APP_SETTING_KEYS: readonly ["communication.channels", "communication.messages"];
+export type AppSettingKey = (typeof APP_SETTING_KEYS)[number];
+/** A switch per channel. */
+export declare const channelSwitchesSchema: z.ZodObject<{
+    EMAIL: z.ZodBoolean;
+    SMS: z.ZodBoolean;
+}, z.core.$strict>;
+export type ChannelSwitches = z.output<typeof channelSwitchesSchema>;
+/**
+ * Master switches: a channel switched off here sends nothing, whatever the
+ * per-message settings say.
+ */
+export declare const communicationChannelsSettingSchema: z.ZodObject<{
+    EMAIL: z.ZodBoolean;
+    SMS: z.ZodBoolean;
+}, z.core.$strict>;
+/**
+ * Per message type and channel. A type missing from a saved value uses its
+ * catalogue defaults, so a newly added message type needs no data change.
+ */
+export declare const communicationMessagesSettingSchema: z.ZodRecord<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";
+}> & z.core.$partial, z.ZodObject<{
+    EMAIL: z.ZodBoolean;
+    SMS: z.ZodBoolean;
+}, z.core.$strict>>;
+export type CommunicationMessagesSetting = z.output<typeof communicationMessagesSettingSchema>;
+export declare const APP_SETTING_VALUE_SCHEMAS: {
+    readonly 'communication.channels': z.ZodObject<{
+        EMAIL: z.ZodBoolean;
+        SMS: z.ZodBoolean;
+    }, z.core.$strict>;
+    readonly 'communication.messages': z.ZodRecord<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";
+    }> & z.core.$partial, z.ZodObject<{
+        EMAIL: z.ZodBoolean;
+        SMS: z.ZodBoolean;
+    }, z.core.$strict>>;
+};
+export interface AppSettingValues {
+    'communication.channels': ChannelSwitches;
+    'communication.messages': CommunicationMessagesSetting;
+}
+/** Every message type, with its catalogue defaults: the effective value with nothing saved. */
+export declare function defaultMessageSettings(): Record<MessageType, ChannelSwitches>;
+export declare const APP_SETTING_DEFAULTS: AppSettingValues;
+export declare const appSettingKeyParamSchema: z.ZodEnum<{
+    "communication.channels": "communication.channels";
+    "communication.messages": "communication.messages";
+}>;
+export declare const appSettingResponseSchema: z.ZodObject<{
+    key: z.ZodEnum<{
+        "communication.channels": "communication.channels";
+        "communication.messages": "communication.messages";
+    }>;
+    label: z.ZodString;
+    description: z.ZodString;
+    value: z.ZodUnknown;
+    defaultValue: z.ZodUnknown;
+    version: z.ZodNumber;
+    updatedBy: z.ZodNullable<z.ZodUUID>;
+    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>;
+export type AppSettingResponse = z.output<typeof appSettingResponseSchema>;
+export declare const appSettingListResponseSchema: z.ZodArray<z.ZodObject<{
+    key: z.ZodEnum<{
+        "communication.channels": "communication.channels";
+        "communication.messages": "communication.messages";
+    }>;
+    label: z.ZodString;
+    description: z.ZodString;
+    value: z.ZodUnknown;
+    defaultValue: z.ZodUnknown;
+    version: z.ZodNumber;
+    updatedBy: z.ZodNullable<z.ZodUUID>;
+    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strip>>;
+/**
+ * Replaces a setting's value. `version` must be the one last read, so a
+ * change made in between is not silently overwritten. The value is checked
+ * against the key's schema on the server.
+ */
+export declare const updateAppSettingSchema: z.ZodObject<{
+    value: z.ZodUnknown;
+    version: z.ZodNumber;
+}, z.core.$strict>;
+export type UpdateAppSettingInput = z.input<typeof updateAppSettingSchema>;
+export type UpdateAppSettingBody = z.output<typeof updateAppSettingSchema>;
+export declare const appSettingHistoryEntrySchema: z.ZodObject<{
+    id: z.ZodUUID;
+    key: z.ZodEnum<{
+        "communication.channels": "communication.channels";
+        "communication.messages": "communication.messages";
+    }>;
+    previousValue: z.ZodUnknown;
+    newValue: z.ZodUnknown;
+    version: z.ZodNumber;
+    actorUserId: z.ZodUUID;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type AppSettingHistoryEntry = z.output<typeof appSettingHistoryEntrySchema>;
+export declare const appSettingHistoryResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodUUID;
+    key: z.ZodEnum<{
+        "communication.channels": "communication.channels";
+        "communication.messages": "communication.messages";
+    }>;
+    previousValue: z.ZodUnknown;
+    newValue: z.ZodUnknown;
+    version: z.ZodNumber;
+    actorUserId: z.ZodUUID;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strip>>;

package/dist/cjs/app-settings/app-settings.dto.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appSettingHistoryResponseSchema = exports.appSettingHistoryEntrySchema = exports.updateAppSettingSchema = exports.appSettingListResponseSchema = exports.appSettingResponseSchema = exports.appSettingKeyParamSchema = exports.APP_SETTING_DEFAULTS = exports.APP_SETTING_VALUE_SCHEMAS = exports.communicationMessagesSettingSchema = exports.communicationChannelsSettingSchema = exports.channelSwitchesSchema = exports.APP_SETTING_KEYS = void 0;
+exports.defaultMessageSettings = defaultMessageSettings;
+const zod_1 = require("zod");
+const date_time_schema_js_1 = require("../common/date-time.schema.js");
+const message_catalogue_js_1 = require("../communication/message-catalogue.js");
+const index_js_1 = require("../enums/index.js");
+/**
+ * Runtime settings an administrator changes without a deploy. Each key has a
+ * value schema here, which both the server and the admin screen use. A key
+ * with no saved value uses its default.
+ */
+exports.APP_SETTING_KEYS = [
+    'communication.channels',
+    'communication.messages',
+];
+/** A switch per channel. */
+exports.channelSwitchesSchema = zod_1.z.strictObject({
+    EMAIL: zod_1.z.boolean(),
+    SMS: zod_1.z.boolean(),
+});
+/**
+ * Master switches: a channel switched off here sends nothing, whatever the
+ * per-message settings say.
+ */
+exports.communicationChannelsSettingSchema = exports.channelSwitchesSchema;
+/**
+ * Per message type and channel. A type missing from a saved value uses its
+ * catalogue defaults, so a newly added message type needs no data change.
+ */
+exports.communicationMessagesSettingSchema = zod_1.z
+    .partialRecord(zod_1.z.enum(index_js_1.MESSAGE_TYPES), exports.channelSwitchesSchema)
+    .superRefine((value, ctx) => {
+    for (const [type, switches] of Object.entries(value)) {
+        const allowed = message_catalogue_js_1.MESSAGE_CATALOGUE[type].channels;
+        for (const [channel, on] of Object.entries(switches ?? {})) {
+            if (on && !allowed.includes(channel)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: [type, channel],
+                    message: `${message_catalogue_js_1.MESSAGE_CATALOGUE[type].label} cannot be sent by ${channel}`,
+                });
+            }
+        }
+    }
+});
+exports.APP_SETTING_VALUE_SCHEMAS = {
+    'communication.channels': exports.communicationChannelsSettingSchema,
+    'communication.messages': exports.communicationMessagesSettingSchema,
+};
+/** Every message type, with its catalogue defaults: the effective value with nothing saved. */
+function defaultMessageSettings() {
+    return Object.fromEntries(index_js_1.MESSAGE_TYPES.map((type) => [
+        type,
+        { ...message_catalogue_js_1.MESSAGE_CATALOGUE[type].defaultChannels },
+    ]));
+}
+exports.APP_SETTING_DEFAULTS = {
+    'communication.channels': { EMAIL: true, SMS: true },
+    'communication.messages': defaultMessageSettings(),
+};
+exports.appSettingKeyParamSchema = zod_1.z.enum(exports.APP_SETTING_KEYS);
+exports.appSettingResponseSchema = zod_1.z.object({
+    key: zod_1.z.enum(exports.APP_SETTING_KEYS),
+    label: zod_1.z.string(),
+    description: zod_1.z.string(),
+    value: zod_1.z.unknown(),
+    defaultValue: zod_1.z.unknown(),
+    /** 0 until the setting is first saved. Send it back to update. */
+    version: zod_1.z.number().int(),
+    updatedBy: zod_1.z.uuid().nullable(),
+    updatedAt: date_time_schema_js_1.utcTimestampSchema.nullable(),
+});
+exports.appSettingListResponseSchema = zod_1.z.array(exports.appSettingResponseSchema);
+/**
+ * Replaces a setting's value. `version` must be the one last read, so a
+ * change made in between is not silently overwritten. The value is checked
+ * against the key's schema on the server.
+ */
+exports.updateAppSettingSchema = zod_1.z.strictObject({
+    value: zod_1.z.unknown(),
+    version: zod_1.z.number().int().min(0),
+});
+exports.appSettingHistoryEntrySchema = zod_1.z.object({
+    id: zod_1.z.uuid(),
+    key: zod_1.z.enum(exports.APP_SETTING_KEYS),
+    previousValue: zod_1.z.unknown(),
+    newValue: zod_1.z.unknown(),
+    version: zod_1.z.number().int(),
+    actorUserId: zod_1.z.uuid(),
+    createdAt: date_time_schema_js_1.utcTimestampSchema,
+});
+exports.appSettingHistoryResponseSchema = zod_1.z.array(exports.appSettingHistoryEntrySchema);

package/dist/cjs/app-settings/index.d.ts

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

package/dist/cjs/app-settings/index.js

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

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;