@tbs-fitness/contract 0.2.0 → 0.4.0

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

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

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.TEMPLATE_STATUSES = exports.DELIVERY_STATUSES = exports.MESSAGE_TYPES = exports.COMMUNICATION_CHANNELS = 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 = [
@@ -29,3 +35,28 @@ exports.FEATURE_FLAG_RULE_TYPES = [
     'trainer',
     'role',
 ];
+/**
+ * The ways a message can reach someone. WhatsApp and push are added here when
+ * their channel modules are built.
+ */
+exports.COMMUNICATION_CHANNELS = ['EMAIL', 'SMS'];
+/**
+ * Every message the platform sends. Each has a catalogue entry in
+ * `@tbs-fitness/contract/communication` saying which channels may carry it and
+ * which variables its sender supplies.
+ */
+exports.MESSAGE_TYPES = [
+    'auth.otp.signup_verification',
+    'auth.otp.password_reset',
+    'auth.password_reset_link',
+];
+/** What happened to one message on one channel. */
+exports.DELIVERY_STATUSES = [
+    'sent',
+    'skipped_disabled',
+    'skipped_unreachable',
+    'failed',
+    'failed_missing_variables',
+];
+/** Only one version of a template per message type and channel is active. */
+exports.TEMPLATE_STATUSES = ['draft', 'active', 'archived'];

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/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/esm/app-settings/app-settings.dto.js

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+import { utcTimestampSchema } from '../common/date-time.schema.js';
+import { MESSAGE_CATALOGUE } from '../communication/message-catalogue.js';
+import { MESSAGE_TYPES } 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 const APP_SETTING_KEYS = [
+    'communication.channels',
+    'communication.messages',
+];
+/** A switch per channel. */
+export const channelSwitchesSchema = z.strictObject({
+    EMAIL: z.boolean(),
+    SMS: z.boolean(),
+});
+/**
+ * Master switches: a channel switched off here sends nothing, whatever the
+ * per-message settings say.
+ */
+export const communicationChannelsSettingSchema = 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.
+ */
+export const communicationMessagesSettingSchema = z
+    .partialRecord(z.enum(MESSAGE_TYPES), channelSwitchesSchema)
+    .superRefine((value, ctx) => {
+    for (const [type, switches] of Object.entries(value)) {
+        const allowed = 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[type].label} cannot be sent by ${channel}`,
+                });
+            }
+        }
+    }
+});
+export const APP_SETTING_VALUE_SCHEMAS = {
+    'communication.channels': communicationChannelsSettingSchema,
+    'communication.messages': communicationMessagesSettingSchema,
+};
+/** Every message type, with its catalogue defaults: the effective value with nothing saved. */
+export function defaultMessageSettings() {
+    return Object.fromEntries(MESSAGE_TYPES.map((type) => [
+        type,
+        { ...MESSAGE_CATALOGUE[type].defaultChannels },
+    ]));
+}
+export const APP_SETTING_DEFAULTS = {
+    'communication.channels': { EMAIL: true, SMS: true },
+    'communication.messages': defaultMessageSettings(),
+};
+export const appSettingKeyParamSchema = z.enum(APP_SETTING_KEYS);
+export const appSettingResponseSchema = z.object({
+    key: z.enum(APP_SETTING_KEYS),
+    label: z.string(),
+    description: z.string(),
+    value: z.unknown(),
+    defaultValue: z.unknown(),
+    /** 0 until the setting is first saved. Send it back to update. */
+    version: z.number().int(),
+    updatedBy: z.uuid().nullable(),
+    updatedAt: utcTimestampSchema.nullable(),
+});
+export const appSettingListResponseSchema = z.array(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.
+ */
+export const updateAppSettingSchema = z.strictObject({
+    value: z.unknown(),
+    version: z.number().int().min(0),
+});
+export const appSettingHistoryEntrySchema = z.object({
+    id: z.uuid(),
+    key: z.enum(APP_SETTING_KEYS),
+    previousValue: z.unknown(),
+    newValue: z.unknown(),
+    version: z.number().int(),
+    actorUserId: z.uuid(),
+    createdAt: utcTimestampSchema,
+});
+export const appSettingHistoryResponseSchema = z.array(appSettingHistoryEntrySchema);

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

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

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

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

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;