@tbs-fitness/contract 0.1.0 → 0.2.0

package/README.md

@@ -11,6 +11,7 @@ It is published as `@tbs-fitness/contract`. The package holds definitions only:
 | `@tbs-fitness/contract/enums`         | `ROLES`, `ACCOUNT_STATUSES`, `TOKEN_TRANSPORTS`, `AUDIT_OUTCOMES`, `APP_ENVIRONMENTS`, `FEATURE_FLAG_RULE_TYPES` and their types |
 | `@tbs-fitness/contract/common`        | Pagination, response envelopes (`{ data }`, `{ data, meta }`, `{ error }`), `emailSchema`, `phoneSchema`, `safeTextSchema`       |
 | `@tbs-fitness/contract/auth`          | Login, sessions, password changes and resets, account administration                                                             |
+| `@tbs-fitness/contract/coach`         | Coach sign-up, one-time code verification and resend, coach sign-in and profile, password recovery                               |
 | `@tbs-fitness/contract/audit`         | The audit log query and response                                                                                                 |
 | `@tbs-fitness/contract/feature-flags` | Feature flag requests and responses                                                                                              |
 
@@ -40,6 +41,15 @@ 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.2.0 (breaking)
+
+- `ROLES` is now `ADMIN`, `COACH` and `CUSTOMER`. A user has exactly one role.
+- `ACCOUNT_STATUSES` adds `pending_verification`. Administrators set only `ADMIN_SETTABLE_ACCOUNT_STATUSES`.
+- `setRolesSchema` is replaced by `setRoleSchema` (`{ role }`), and `adminAccountResponseSchema` has `role` instead of `roles`. `accountResponseSchema` adds `role` and keeps `roles` as `[role]`.
+- New: `@tbs-fitness/contract/coach`, and `OTP_LENGTH`, `otpCodeSchema`, `opaqueTokenSchema` and `submittedPasswordSchema` in `/auth`.
+
+A caret range on 0.x does not cross minor versions, so consumers must install `^0.2.0` explicitly.
+
 ## Installing it
 
 The package is public on npm, so installing it needs no token:

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

@@ -1,7 +1,13 @@
 import { z } from 'zod';
 export declare const MIN_PASSWORD_LENGTH = 12;
 export declare const MAX_PASSWORD_LENGTH = 128;
+/** Every one-time code the API sends has this many digits. */
+export declare const OTP_LENGTH = 6;
+export declare const otpCodeSchema: z.ZodString;
 export declare const newPasswordSchema: z.ZodString;
+/** No minimum at login, so an old short password fails like any wrong password. */
+export declare const submittedPasswordSchema: z.ZodString;
+export declare const opaqueTokenSchema: z.ZodString;
 export declare const loginSchema: z.ZodObject<{
     email: z.ZodPipe<z.ZodString, z.ZodEmail>;
     password: z.ZodString;
@@ -35,15 +41,15 @@ export declare const passwordResetConfirmSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type PasswordResetConfirmInput = z.input<typeof passwordResetConfirmSchema>;
 export type PasswordResetConfirmBody = z.output<typeof passwordResetConfirmSchema>;
-export declare const setRolesSchema: z.ZodObject<{
-    roles: z.ZodArray<z.ZodEnum<{
-        admin: "admin";
-        trainer: "trainer";
-        customer: "customer";
-    }>>;
+export declare const setRoleSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        ADMIN: "ADMIN";
+        COACH: "COACH";
+        CUSTOMER: "CUSTOMER";
+    }>;
 }, z.core.$strict>;
-export type SetRolesInput = z.input<typeof setRolesSchema>;
-export type SetRolesBody = z.output<typeof setRolesSchema>;
+export type SetRoleInput = z.input<typeof setRoleSchema>;
+export type SetRoleBody = z.output<typeof setRoleSchema>;
 export declare const setStatusSchema: z.ZodObject<{
     status: z.ZodEnum<{
         active: "active";
@@ -65,6 +71,11 @@ export type TokenResponse = z.output<typeof tokenResponseSchema>;
 export declare const accountResponseSchema: z.ZodObject<{
     id: z.ZodUUID;
     email: z.ZodString;
+    role: z.ZodEnum<{
+        ADMIN: "ADMIN";
+        COACH: "COACH";
+        CUSTOMER: "CUSTOMER";
+    }>;
     roles: z.ZodArray<z.ZodString>;
     permissions: z.ZodArray<z.ZodString>;
     lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
@@ -80,6 +91,11 @@ export declare const loginResponseSchema: z.ZodObject<{
     account: z.ZodObject<{
         id: z.ZodUUID;
         email: z.ZodString;
+        role: z.ZodEnum<{
+            ADMIN: "ADMIN";
+            COACH: "COACH";
+            CUSTOMER: "CUSTOMER";
+        }>;
         roles: z.ZodArray<z.ZodString>;
         permissions: z.ZodArray<z.ZodString>;
         lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
@@ -107,8 +123,13 @@ export type PasswordResetRequestedResponse = z.output<typeof passwordResetReques
 export declare const adminAccountResponseSchema: z.ZodObject<{
     id: z.ZodUUID;
     email: z.ZodString;
-    roles: z.ZodArray<z.ZodString>;
+    role: z.ZodEnum<{
+        ADMIN: "ADMIN";
+        COACH: "COACH";
+        CUSTOMER: "CUSTOMER";
+    }>;
     status: z.ZodEnum<{
+        pending_verification: "pending_verification";
         active: "active";
         disabled: "disabled";
     }>;

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

@@ -1,6 +1,6 @@
 "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.setRolesSchema = exports.passwordResetConfirmSchema = exports.passwordResetRequestSchema = exports.changePasswordSchema = exports.refreshSchema = exports.loginSchema = exports.newPasswordSchema = 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.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 safe_text_schema_js_1 = require("../common/safe-text.schema.js");
@@ -10,40 +10,51 @@ const index_js_1 = require("../enums/index.js");
 exports.MIN_PASSWORD_LENGTH = 12;
 exports.MAX_PASSWORD_LENGTH = 128;
 const MAX_OPAQUE_TOKEN_LENGTH = 512;
+/** Every one-time code the API sends has this many digits. */
+exports.OTP_LENGTH = 6;
+exports.otpCodeSchema = zod_1.z
+    .string()
+    .trim()
+    .regex(new RegExp(`^\\d{${exports.OTP_LENGTH}}$`), {
+    error: `Enter the ${exports.OTP_LENGTH}-digit code`,
+});
 exports.newPasswordSchema = zod_1.z
     .string()
     .min(exports.MIN_PASSWORD_LENGTH)
     .max(exports.MAX_PASSWORD_LENGTH);
 /** No minimum at login, so an old short password fails like any wrong password. */
-const submittedPasswordSchema = zod_1.z.string().min(1).max(exports.MAX_PASSWORD_LENGTH);
-const opaqueTokenSchema = zod_1.z.string().min(1).max(MAX_OPAQUE_TOKEN_LENGTH);
+exports.submittedPasswordSchema = zod_1.z
+    .string()
+    .min(1)
+    .max(exports.MAX_PASSWORD_LENGTH);
+exports.opaqueTokenSchema = zod_1.z.string().min(1).max(MAX_OPAQUE_TOKEN_LENGTH);
 // Strict objects reject unknown fields, so an attempt to send `roles` or
 // `status` fails loudly rather than being silently ignored.
 exports.loginSchema = zod_1.z.strictObject({
     email: contact_schema_js_1.emailSchema,
-    password: submittedPasswordSchema,
+    password: exports.submittedPasswordSchema,
     deviceName: (0, safe_text_schema_js_1.safeTextSchema)(100).optional(),
     tokenTransport: zod_1.z.enum(index_js_1.TOKEN_TRANSPORTS).default('body'),
 });
 exports.refreshSchema = zod_1.z
-    .strictObject({ refreshToken: opaqueTokenSchema.optional() })
+    .strictObject({ refreshToken: exports.opaqueTokenSchema.optional() })
     .default({});
 exports.changePasswordSchema = zod_1.z.strictObject({
-    currentPassword: submittedPasswordSchema,
+    currentPassword: exports.submittedPasswordSchema,
     newPassword: exports.newPasswordSchema,
 });
 exports.passwordResetRequestSchema = zod_1.z.strictObject({
     email: contact_schema_js_1.emailSchema,
 });
 exports.passwordResetConfirmSchema = zod_1.z.strictObject({
-    token: opaqueTokenSchema,
+    token: exports.opaqueTokenSchema,
     newPassword: exports.newPasswordSchema,
 });
-exports.setRolesSchema = zod_1.z.strictObject({
-    roles: zod_1.z.array(zod_1.z.enum(index_js_1.ROLES)).max(index_js_1.ROLES.length),
+exports.setRoleSchema = zod_1.z.strictObject({
+    role: zod_1.z.enum(index_js_1.ROLES),
 });
 exports.setStatusSchema = zod_1.z.strictObject({
-    status: zod_1.z.enum(index_js_1.ACCOUNT_STATUSES),
+    status: zod_1.z.enum(index_js_1.ADMIN_SETTABLE_ACCOUNT_STATUSES),
 });
 exports.idParamSchema = zod_1.z.uuid();
 exports.tokenResponseSchema = zod_1.z.object({
@@ -57,6 +68,8 @@ exports.tokenResponseSchema = zod_1.z.object({
 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(),
@@ -82,7 +95,7 @@ exports.passwordResetRequestedResponseSchema = zod_1.z.object({
 exports.adminAccountResponseSchema = zod_1.z.object({
     id: zod_1.z.uuid(),
     email: zod_1.z.string(),
-    roles: zod_1.z.array(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(),
 });

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

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+export declare const coachSignupSchema: z.ZodObject<{
+    fullName: z.ZodPipe<z.ZodString, z.ZodString>;
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    phone: z.ZodOptional<z.ZodString>;
+    password: z.ZodString;
+}, z.core.$strict>;
+export type CoachSignupInput = z.input<typeof coachSignupSchema>;
+export type CoachSignupBody = z.output<typeof coachSignupSchema>;
+/** Used by both resend endpoints and by forgot-password. */
+export declare const otpEmailSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+}, z.core.$strict>;
+export type OtpEmailInput = z.input<typeof otpEmailSchema>;
+export type OtpEmailBody = z.output<typeof otpEmailSchema>;
+export declare const verifyOtpSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    code: z.ZodString;
+}, z.core.$strict>;
+export type VerifyOtpInput = z.input<typeof verifyOtpSchema>;
+export type VerifyOtpBody = z.output<typeof verifyOtpSchema>;
+/**
+ * Coaches sign in from the browser, so the refresh token always travels in an
+ * HttpOnly cookie. `rememberMe: false` makes that cookie end with the browser
+ * session instead of persisting.
+ */
+export declare const coachLoginSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    password: z.ZodString;
+    deviceName: z.ZodOptional<z.ZodString>;
+    rememberMe: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type CoachLoginInput = z.input<typeof coachLoginSchema>;
+export type CoachLoginBody = z.output<typeof coachLoginSchema>;
+export declare const resetPasswordSchema: z.ZodObject<{
+    resetToken: z.ZodString;
+    newPassword: z.ZodString;
+}, z.core.$strict>;
+export type ResetPasswordInput = z.input<typeof resetPasswordSchema>;
+export type ResetPasswordBody = z.output<typeof resetPasswordSchema>;
+/**
+ * Says what the client needs to drive the code screen, and nothing about
+ * whether the email belongs to an account: the same values are returned either
+ * way.
+ */
+export declare const otpDispatchResponseSchema: z.ZodObject<{
+    message: z.ZodString;
+    otpLength: z.ZodNumber;
+    expiresInSeconds: z.ZodNumber;
+    resendAvailableInSeconds: z.ZodNumber;
+}, z.core.$strip>;
+export type OtpDispatchResponse = z.output<typeof otpDispatchResponseSchema>;
+export declare const signupVerifiedResponseSchema: z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>;
+export type SignupVerifiedResponse = z.output<typeof signupVerifiedResponseSchema>;
+/** Issued only after a recovery code is verified. It can reset a password once. */
+export declare const resetTokenResponseSchema: z.ZodObject<{
+    resetToken: z.ZodString;
+    expiresInSeconds: z.ZodNumber;
+}, z.core.$strip>;
+export type ResetTokenResponse = z.output<typeof resetTokenResponseSchema>;
+export declare const coachProfileSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    email: z.ZodString;
+    fullName: z.ZodNullable<z.ZodString>;
+    phone: z.ZodNullable<z.ZodString>;
+    role: z.ZodLiteral<"COACH">;
+    status: z.ZodEnum<{
+        pending_verification: "pending_verification";
+        active: "active";
+        disabled: "disabled";
+    }>;
+    emailVerifiedAt: z.ZodNullable<z.ZodISODateTime>;
+    lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type CoachProfile = z.output<typeof coachProfileSchema>;
+export declare const coachLoginResponseSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    tokenType: z.ZodLiteral<"Bearer">;
+    expiresInSeconds: z.ZodNumber;
+    refreshToken: z.ZodOptional<z.ZodString>;
+    csrfToken: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodUUID;
+    coach: z.ZodObject<{
+        id: z.ZodUUID;
+        email: z.ZodString;
+        fullName: z.ZodNullable<z.ZodString>;
+        phone: z.ZodNullable<z.ZodString>;
+        role: z.ZodLiteral<"COACH">;
+        status: z.ZodEnum<{
+            pending_verification: "pending_verification";
+            active: "active";
+            disabled: "disabled";
+        }>;
+        emailVerifiedAt: z.ZodNullable<z.ZodISODateTime>;
+        lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CoachLoginResponse = z.output<typeof coachLoginResponseSchema>;

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

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coachLoginResponseSchema = exports.coachProfileSchema = exports.resetTokenResponseSchema = exports.signupVerifiedResponseSchema = exports.otpDispatchResponseSchema = exports.resetPasswordSchema = exports.coachLoginSchema = exports.verifyOtpSchema = exports.otpEmailSchema = exports.coachSignupSchema = void 0;
+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 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({
+    fullName: (0, safe_text_schema_js_1.safeTextSchema)(100).pipe(zod_1.z.string().min(2, { error: 'Enter your full name' })),
+    email: contact_schema_js_1.emailSchema,
+    phone: contact_schema_js_1.phoneSchema.optional(),
+    password: auth_dto_js_1.newPasswordSchema,
+});
+/** Used by both resend endpoints and by forgot-password. */
+exports.otpEmailSchema = zod_1.z.strictObject({ email: contact_schema_js_1.emailSchema });
+exports.verifyOtpSchema = zod_1.z.strictObject({
+    email: contact_schema_js_1.emailSchema,
+    code: auth_dto_js_1.otpCodeSchema,
+});
+/**
+ * Coaches sign in from the browser, so the refresh token always travels in an
+ * HttpOnly cookie. `rememberMe: false` makes that cookie end with the browser
+ * session instead of persisting.
+ */
+exports.coachLoginSchema = auth_dto_js_1.loginSchema
+    .omit({ tokenTransport: true })
+    .extend({ rememberMe: zod_1.z.boolean().default(true) });
+exports.resetPasswordSchema = zod_1.z.strictObject({
+    resetToken: auth_dto_js_1.opaqueTokenSchema,
+    newPassword: auth_dto_js_1.newPasswordSchema,
+});
+/**
+ * Says what the client needs to drive the code screen, and nothing about
+ * whether the email belongs to an account: the same values are returned either
+ * way.
+ */
+exports.otpDispatchResponseSchema = zod_1.z.object({
+    message: zod_1.z.string(),
+    otpLength: zod_1.z.number().int(),
+    expiresInSeconds: zod_1.z.number().int(),
+    resendAvailableInSeconds: zod_1.z.number().int(),
+});
+exports.signupVerifiedResponseSchema = zod_1.z.object({
+    message: zod_1.z.string(),
+});
+/** Issued only after a recovery code is verified. It can reset a password once. */
+exports.resetTokenResponseSchema = zod_1.z.object({
+    resetToken: zod_1.z.string(),
+    expiresInSeconds: zod_1.z.number().int(),
+});
+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(),
+});
+exports.coachLoginResponseSchema = auth_dto_js_1.tokenResponseSchema.extend({
+    coach: exports.coachProfileSchema,
+});

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

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

package/dist/cjs/coach/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("./coach-auth.dto.js"), exports);

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

@@ -1,9 +1,17 @@
 export declare const APP_ENVIRONMENTS: readonly ["development", "staging", "production"];
 export type AppEnvironment = (typeof APP_ENVIRONMENTS)[number];
-export declare const ROLES: readonly ["admin", "trainer", "customer"];
+/** Each user has exactly one role. A new role is added here and nowhere else. */
+export declare const ROLES: readonly ["ADMIN", "COACH", "CUSTOMER"];
 export type Role = (typeof ROLES)[number];
-export declare const ACCOUNT_STATUSES: readonly ["active", "disabled"];
+/**
+ * `pending_verification` is a self-registered user who has not yet proved they
+ * own their email address. Such a user cannot sign in.
+ */
+export declare const ACCOUNT_STATUSES: readonly ["pending_verification", "active", "disabled"];
 export type AccountStatus = (typeof ACCOUNT_STATUSES)[number];
+/** The statuses an administrator may set. Verification is never set by hand. */
+export declare const ADMIN_SETTABLE_ACCOUNT_STATUSES: readonly ["active", "disabled"];
+export type AdminSettableAccountStatus = (typeof ADMIN_SETTABLE_ACCOUNT_STATUSES)[number];
 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,14 +2,25 @@
 // 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.ACCOUNT_STATUSES = exports.ROLES = exports.APP_ENVIRONMENTS = void 0;
+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.APP_ENVIRONMENTS = [
     'development',
     'staging',
     'production',
 ];
-exports.ROLES = ['admin', 'trainer', 'customer'];
-exports.ACCOUNT_STATUSES = ['active', 'disabled'];
+/** Each user has exactly one role. A new role is added here and nowhere else. */
+exports.ROLES = ['ADMIN', 'COACH', 'CUSTOMER'];
+/**
+ * `pending_verification` is a self-registered user who has not yet proved they
+ * own their email address. Such a user cannot sign in.
+ */
+exports.ACCOUNT_STATUSES = [
+    'pending_verification',
+    'active',
+    'disabled',
+];
+/** The statuses an administrator may set. Verification is never set by hand. */
+exports.ADMIN_SETTABLE_ACCOUNT_STATUSES = ['active', 'disabled'];
 exports.TOKEN_TRANSPORTS = ['body', 'cookie'];
 exports.AUDIT_OUTCOMES = ['success', 'failure'];
 exports.FEATURE_FLAG_RULE_TYPES = [

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

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

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

@@ -1,7 +1,13 @@
 import { z } from 'zod';
 export declare const MIN_PASSWORD_LENGTH = 12;
 export declare const MAX_PASSWORD_LENGTH = 128;
+/** Every one-time code the API sends has this many digits. */
+export declare const OTP_LENGTH = 6;
+export declare const otpCodeSchema: z.ZodString;
 export declare const newPasswordSchema: z.ZodString;
+/** No minimum at login, so an old short password fails like any wrong password. */
+export declare const submittedPasswordSchema: z.ZodString;
+export declare const opaqueTokenSchema: z.ZodString;
 export declare const loginSchema: z.ZodObject<{
     email: z.ZodPipe<z.ZodString, z.ZodEmail>;
     password: z.ZodString;
@@ -35,15 +41,15 @@ export declare const passwordResetConfirmSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type PasswordResetConfirmInput = z.input<typeof passwordResetConfirmSchema>;
 export type PasswordResetConfirmBody = z.output<typeof passwordResetConfirmSchema>;
-export declare const setRolesSchema: z.ZodObject<{
-    roles: z.ZodArray<z.ZodEnum<{
-        admin: "admin";
-        trainer: "trainer";
-        customer: "customer";
-    }>>;
+export declare const setRoleSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        ADMIN: "ADMIN";
+        COACH: "COACH";
+        CUSTOMER: "CUSTOMER";
+    }>;
 }, z.core.$strict>;
-export type SetRolesInput = z.input<typeof setRolesSchema>;
-export type SetRolesBody = z.output<typeof setRolesSchema>;
+export type SetRoleInput = z.input<typeof setRoleSchema>;
+export type SetRoleBody = z.output<typeof setRoleSchema>;
 export declare const setStatusSchema: z.ZodObject<{
     status: z.ZodEnum<{
         active: "active";
@@ -65,6 +71,11 @@ export type TokenResponse = z.output<typeof tokenResponseSchema>;
 export declare const accountResponseSchema: z.ZodObject<{
     id: z.ZodUUID;
     email: z.ZodString;
+    role: z.ZodEnum<{
+        ADMIN: "ADMIN";
+        COACH: "COACH";
+        CUSTOMER: "CUSTOMER";
+    }>;
     roles: z.ZodArray<z.ZodString>;
     permissions: z.ZodArray<z.ZodString>;
     lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
@@ -80,6 +91,11 @@ export declare const loginResponseSchema: z.ZodObject<{
     account: z.ZodObject<{
         id: z.ZodUUID;
         email: z.ZodString;
+        role: z.ZodEnum<{
+            ADMIN: "ADMIN";
+            COACH: "COACH";
+            CUSTOMER: "CUSTOMER";
+        }>;
         roles: z.ZodArray<z.ZodString>;
         permissions: z.ZodArray<z.ZodString>;
         lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
@@ -107,8 +123,13 @@ export type PasswordResetRequestedResponse = z.output<typeof passwordResetReques
 export declare const adminAccountResponseSchema: z.ZodObject<{
     id: z.ZodUUID;
     email: z.ZodString;
-    roles: z.ZodArray<z.ZodString>;
+    role: z.ZodEnum<{
+        ADMIN: "ADMIN";
+        COACH: "COACH";
+        CUSTOMER: "CUSTOMER";
+    }>;
     status: z.ZodEnum<{
+        pending_verification: "pending_verification";
         active: "active";
         disabled: "disabled";
     }>;

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

@@ -1,19 +1,30 @@
 import { z } from 'zod';
 import { emailSchema } from '../common/contact.schema.js';
 import { safeTextSchema } from '../common/safe-text.schema.js';
-import { ACCOUNT_STATUSES, ROLES, TOKEN_TRANSPORTS } from '../enums/index.js';
+import { ACCOUNT_STATUSES, ADMIN_SETTABLE_ACCOUNT_STATUSES, ROLES, 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;
 export const MAX_PASSWORD_LENGTH = 128;
 const MAX_OPAQUE_TOKEN_LENGTH = 512;
+/** Every one-time code the API sends has this many digits. */
+export const OTP_LENGTH = 6;
+export const otpCodeSchema = z
+    .string()
+    .trim()
+    .regex(new RegExp(`^\\d{${OTP_LENGTH}}$`), {
+    error: `Enter the ${OTP_LENGTH}-digit code`,
+});
 export const newPasswordSchema = z
     .string()
     .min(MIN_PASSWORD_LENGTH)
     .max(MAX_PASSWORD_LENGTH);
 /** No minimum at login, so an old short password fails like any wrong password. */
-const submittedPasswordSchema = z.string().min(1).max(MAX_PASSWORD_LENGTH);
-const opaqueTokenSchema = z.string().min(1).max(MAX_OPAQUE_TOKEN_LENGTH);
+export const submittedPasswordSchema = z
+    .string()
+    .min(1)
+    .max(MAX_PASSWORD_LENGTH);
+export const opaqueTokenSchema = z.string().min(1).max(MAX_OPAQUE_TOKEN_LENGTH);
 // Strict objects reject unknown fields, so an attempt to send `roles` or
 // `status` fails loudly rather than being silently ignored.
 export const loginSchema = z.strictObject({
@@ -36,11 +47,11 @@ export const passwordResetConfirmSchema = z.strictObject({
     token: opaqueTokenSchema,
     newPassword: newPasswordSchema,
 });
-export const setRolesSchema = z.strictObject({
-    roles: z.array(z.enum(ROLES)).max(ROLES.length),
+export const setRoleSchema = z.strictObject({
+    role: z.enum(ROLES),
 });
 export const setStatusSchema = z.strictObject({
-    status: z.enum(ACCOUNT_STATUSES),
+    status: z.enum(ADMIN_SETTABLE_ACCOUNT_STATUSES),
 });
 export const idParamSchema = z.uuid();
 export const tokenResponseSchema = z.object({
@@ -54,6 +65,8 @@ export const tokenResponseSchema = z.object({
 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(),
@@ -79,7 +92,7 @@ export const passwordResetRequestedResponseSchema = z.object({
 export const adminAccountResponseSchema = z.object({
     id: z.uuid(),
     email: z.string(),
-    roles: z.array(z.string()),
+    role: z.enum(ROLES),
     status: z.enum(ACCOUNT_STATUSES),
     lastLoginAt: z.iso.datetime().nullable(),
 });

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

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+export declare const coachSignupSchema: z.ZodObject<{
+    fullName: z.ZodPipe<z.ZodString, z.ZodString>;
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    phone: z.ZodOptional<z.ZodString>;
+    password: z.ZodString;
+}, z.core.$strict>;
+export type CoachSignupInput = z.input<typeof coachSignupSchema>;
+export type CoachSignupBody = z.output<typeof coachSignupSchema>;
+/** Used by both resend endpoints and by forgot-password. */
+export declare const otpEmailSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+}, z.core.$strict>;
+export type OtpEmailInput = z.input<typeof otpEmailSchema>;
+export type OtpEmailBody = z.output<typeof otpEmailSchema>;
+export declare const verifyOtpSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    code: z.ZodString;
+}, z.core.$strict>;
+export type VerifyOtpInput = z.input<typeof verifyOtpSchema>;
+export type VerifyOtpBody = z.output<typeof verifyOtpSchema>;
+/**
+ * Coaches sign in from the browser, so the refresh token always travels in an
+ * HttpOnly cookie. `rememberMe: false` makes that cookie end with the browser
+ * session instead of persisting.
+ */
+export declare const coachLoginSchema: z.ZodObject<{
+    email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+    password: z.ZodString;
+    deviceName: z.ZodOptional<z.ZodString>;
+    rememberMe: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type CoachLoginInput = z.input<typeof coachLoginSchema>;
+export type CoachLoginBody = z.output<typeof coachLoginSchema>;
+export declare const resetPasswordSchema: z.ZodObject<{
+    resetToken: z.ZodString;
+    newPassword: z.ZodString;
+}, z.core.$strict>;
+export type ResetPasswordInput = z.input<typeof resetPasswordSchema>;
+export type ResetPasswordBody = z.output<typeof resetPasswordSchema>;
+/**
+ * Says what the client needs to drive the code screen, and nothing about
+ * whether the email belongs to an account: the same values are returned either
+ * way.
+ */
+export declare const otpDispatchResponseSchema: z.ZodObject<{
+    message: z.ZodString;
+    otpLength: z.ZodNumber;
+    expiresInSeconds: z.ZodNumber;
+    resendAvailableInSeconds: z.ZodNumber;
+}, z.core.$strip>;
+export type OtpDispatchResponse = z.output<typeof otpDispatchResponseSchema>;
+export declare const signupVerifiedResponseSchema: z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strip>;
+export type SignupVerifiedResponse = z.output<typeof signupVerifiedResponseSchema>;
+/** Issued only after a recovery code is verified. It can reset a password once. */
+export declare const resetTokenResponseSchema: z.ZodObject<{
+    resetToken: z.ZodString;
+    expiresInSeconds: z.ZodNumber;
+}, z.core.$strip>;
+export type ResetTokenResponse = z.output<typeof resetTokenResponseSchema>;
+export declare const coachProfileSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    email: z.ZodString;
+    fullName: z.ZodNullable<z.ZodString>;
+    phone: z.ZodNullable<z.ZodString>;
+    role: z.ZodLiteral<"COACH">;
+    status: z.ZodEnum<{
+        pending_verification: "pending_verification";
+        active: "active";
+        disabled: "disabled";
+    }>;
+    emailVerifiedAt: z.ZodNullable<z.ZodISODateTime>;
+    lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type CoachProfile = z.output<typeof coachProfileSchema>;
+export declare const coachLoginResponseSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    tokenType: z.ZodLiteral<"Bearer">;
+    expiresInSeconds: z.ZodNumber;
+    refreshToken: z.ZodOptional<z.ZodString>;
+    csrfToken: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodUUID;
+    coach: z.ZodObject<{
+        id: z.ZodUUID;
+        email: z.ZodString;
+        fullName: z.ZodNullable<z.ZodString>;
+        phone: z.ZodNullable<z.ZodString>;
+        role: z.ZodLiteral<"COACH">;
+        status: z.ZodEnum<{
+            pending_verification: "pending_verification";
+            active: "active";
+            disabled: "disabled";
+        }>;
+        emailVerifiedAt: z.ZodNullable<z.ZodISODateTime>;
+        lastLoginAt: z.ZodNullable<z.ZodISODateTime>;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type CoachLoginResponse = z.output<typeof coachLoginResponseSchema>;

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

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

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

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

package/dist/esm/coach/index.js

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

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

@@ -1,9 +1,17 @@
 export declare const APP_ENVIRONMENTS: readonly ["development", "staging", "production"];
 export type AppEnvironment = (typeof APP_ENVIRONMENTS)[number];
-export declare const ROLES: readonly ["admin", "trainer", "customer"];
+/** Each user has exactly one role. A new role is added here and nowhere else. */
+export declare const ROLES: readonly ["ADMIN", "COACH", "CUSTOMER"];
 export type Role = (typeof ROLES)[number];
-export declare const ACCOUNT_STATUSES: readonly ["active", "disabled"];
+/**
+ * `pending_verification` is a self-registered user who has not yet proved they
+ * own their email address. Such a user cannot sign in.
+ */
+export declare const ACCOUNT_STATUSES: readonly ["pending_verification", "active", "disabled"];
 export type AccountStatus = (typeof ACCOUNT_STATUSES)[number];
+/** The statuses an administrator may set. Verification is never set by hand. */
+export declare const ADMIN_SETTABLE_ACCOUNT_STATUSES: readonly ["active", "disabled"];
+export type AdminSettableAccountStatus = (typeof ADMIN_SETTABLE_ACCOUNT_STATUSES)[number];
 export declare const TOKEN_TRANSPORTS: readonly ["body", "cookie"];
 export type TokenTransport = (typeof TOKEN_TRANSPORTS)[number];
 export declare const AUDIT_OUTCOMES: readonly ["success", "failure"];

package/dist/esm/enums/index.js

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

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

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

package/package.json

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