docs(auth): document the OTP verification flow on register, verifyOtp, resendOtp

src/modules/auth.types.ts

@@ -362,8 +362,10 @@ export interface AuthModule {
   /**
    * Registers a new user account.
    *
-   * Creates a new user account with email and password. After successful registration,
-   * use {@linkcode loginViaEmailPassword | loginViaEmailPassword()} to log in the user.
+   * Creates a new user account with email and password. Registration sends an OTP
+   * code to the user's email. Pass that code to
+   * {@linkcode verifyOtp | verifyOtp()} to complete verification, then log the user
+   * in with {@linkcode loginViaEmailPassword | loginViaEmailPassword()}.
    *
    * @param params - Registration details including email, password, and optional fields.
    * @returns Promise resolving to the registration response.
@@ -377,7 +379,13 @@ export interface AuthModule {
    *   referral_code: 'FRIEND2024'
    * });
    *
-   * // Login after registration
+   * // Verify with the OTP code from the user's email
+   * await base44.auth.verifyOtp({
+   *   email: 'newuser@example.com',
+   *   otpCode: '123456'
+   * });
+   *
+   * // Log the user in after verification
    * const { access_token, user } = await base44.auth.loginViaEmailPassword(
    *   'newuser@example.com',
    *   'securePassword123'
@@ -387,17 +395,23 @@ export interface AuthModule {
   register(params: RegisterParams): Promise<any>;
 
   /**
-   * Verifies an OTP (One-time password) code.
+   * Verifies an OTP (one-time password) code.
    *
-   * Validates an OTP code sent to the user's email during registration
-   * or authentication.
+   * Confirms that the user owns the email address by checking the code sent to
+   * their inbox during {@linkcode register | register()}. After a successful
+   * call, log the user in with
+   * {@linkcode loginViaEmailPassword | loginViaEmailPassword()}. If the code
+   * has expired or the user didn't receive it, send a fresh one with
+   * {@linkcode resendOtp | resendOtp()}.
    *
-   * @param params - Object containing email and OTP code.
-   * @returns Promise resolving to the verification response if valid.
-   * @throws Error if the OTP code is invalid, expired, or verification fails.
+   * @param params - The email being verified and the OTP code the user entered.
+   * @returns Promise resolving to the verification response, which includes an
+   * access token for the now-verified user.
+   * @throws Error if the OTP code is invalid or expired.
    *
    * @example
    * ```typescript
+   * // Verify the code the user entered from their email
    * try {
    *   await base44.auth.verifyOtp({
    *     email: 'user@example.com',
@@ -408,20 +422,46 @@ export interface AuthModule {
    *   console.error('Invalid or expired OTP code');
    * }
    * ```
+   *
+   * @example
+   * ```typescript
+   * // Full registration flow
+   * await base44.auth.register({
+   *   email: 'newuser@example.com',
+   *   password: 'securePassword123'
+   * });
+   *
+   * // The user receives an OTP code by email. Collect it and verify.
+   * await base44.auth.verifyOtp({
+   *   email: 'newuser@example.com',
+   *   otpCode: '123456'
+   * });
+   *
+   * // Log the user in after verification
+   * const { access_token, user } = await base44.auth.loginViaEmailPassword(
+   *   'newuser@example.com',
+   *   'securePassword123'
+   * );
+   * ```
    */
   verifyOtp(params: VerifyOtpParams): Promise<any>;
 
   /**
    * Resends an OTP code to the user's email address.
    *
-   * Requests a new OTP code to be sent to the specified email address.
+   * Call this when the user didn't receive the original code sent by
+   * {@linkcode register | register()}, or when the previous code has expired.
+   * The new code replaces the previous one. Pass it to
+   * {@linkcode verifyOtp | verifyOtp()} to complete verification.
    *
-   * @param email - Email address to send the OTP to.
-   * @returns Promise resolving when the OTP is sent successfully.
+   * @param email - Email address to send the new OTP to.
+   * @returns Promise resolving once the new OTP has been sent, with a
+   * confirmation message and the new code's expiration window.
    * @throws Error if the email is invalid or the request fails.
    *
    * @example
    * ```typescript
+   * // Resend the OTP when the user didn't receive the original
    * try {
    *   await base44.auth.resendOtp('user@example.com');
    *   console.log('OTP resent! Please check your email.');