refactor: improve OTP error handling (#369)

Author: raivieiraadriano92

src/components/magic-link-verify.test.tsx

@@ -190,7 +190,19 @@ describe('MagicLinkVerify', () => {
       await waitForStateChange()
 
       expect(screen.getByText('Verification Failed')).toBeInTheDocument()
-      expect(screen.getByText('The link has expired or is invalid. Please request a new one.')).toBeInTheDocument()
+      expect(screen.getByText('This link is invalid. Please request a new one.')).toBeInTheDocument()
+    })
+
+    it('shows specific error for OTP_EXPIRED', async () => {
+      mockSignInEmailOtp.mockResolvedValue({
+        error: { code: 'OTP_EXPIRED', message: 'OTP expired' },
+      })
+
+      renderComponent('user@example.com', '123456')
+      await waitForStateChange()
+
+      expect(screen.getByText('Verification Failed')).toBeInTheDocument()
+      expect(screen.getByText('This link has expired. Please request a new one.')).toBeInTheDocument()
     })
 
     it('shows error when signIn throws', async () => {

src/components/magic-link-verify.tsx

@@ -7,6 +7,7 @@ import { useNavigate, useSearchParams } from 'react-router'
 import { Button } from '@/components/ui/button'
 import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from '@/components/ui/dialog'
 import { useAuth } from '@/contexts'
+import { getOtpErrorMessage } from '@/lib/otp-error-messages'
 import { useSettings } from '@/hooks/use-settings'
 
 type VerifyState = { status: 'verifying' } | { status: 'success' } | { status: 'error'; message: string }
@@ -47,14 +48,7 @@ export const MagicLinkVerify = () => {
         })
 
         if (result.error) {
-          // Handle specific error codes from Better Auth
-          if (result.error.code === 'TOO_MANY_ATTEMPTS') {
-            setState({ status: 'error', message: 'Too many attempts. Please request a new code.' })
-          } else if (result.error.code === 'INVALID_OTP') {
-            setState({ status: 'error', message: 'The link has expired or is invalid. Please request a new one.' })
-          } else {
-            setState({ status: 'error', message: result.error.message || 'Verification failed. Please try again.' })
-          }
+          setState({ status: 'error', message: getOtpErrorMessage(result.error, 'link') })
           return
         }
 

src/components/sign-in/use-sign-in-form-state.ts

@@ -1,4 +1,5 @@
 import type { AuthClient } from '@/contexts'
+import { getOtpErrorMessage } from '@/lib/otp-error-messages'
 import { setAuthToken } from '@/lib/auth-token'
 import { isValidEmailFormat } from '@/lib/utils'
 import { useReducer, type FormEvent } from 'react'
@@ -135,7 +136,7 @@ export const useSignInFormState = ({
       })
 
       if (result.error) {
-        dispatch({ type: 'VERIFY_ERROR', payload: result.error.message || 'Invalid code. Please try again.' })
+        dispatch({ type: 'VERIFY_ERROR', payload: getOtpErrorMessage(result.error, 'code') })
         return
       }
 

src/lib/otp-error-messages.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'bun:test'
+import { getOtpErrorMessage } from './otp-error-messages'
+
+describe('getOtpErrorMessage', () => {
+  describe('link context', () => {
+    it('returns link-specific message for OTP_EXPIRED', () => {
+      expect(getOtpErrorMessage({ code: 'OTP_EXPIRED', message: 'OTP expired' }, 'link')).toBe(
+        'This link has expired. Please request a new one.',
+      )
+    })
+
+    it('returns link-specific message for INVALID_OTP', () => {
+      expect(getOtpErrorMessage({ code: 'INVALID_OTP', message: 'Invalid OTP' }, 'link')).toBe(
+        'This link is invalid. Please request a new one.',
+      )
+    })
+
+    it('returns message for TOO_MANY_ATTEMPTS', () => {
+      expect(getOtpErrorMessage({ code: 'TOO_MANY_ATTEMPTS', message: 'Too many attempts' }, 'link')).toBe(
+        'Too many attempts. Please request a new code.',
+      )
+    })
+  })
+
+  describe('code context', () => {
+    it('returns code-specific message for OTP_EXPIRED', () => {
+      expect(getOtpErrorMessage({ code: 'OTP_EXPIRED', message: 'OTP expired' }, 'code')).toBe(
+        'This code has expired. Please request a new one.',
+      )
+    })
+
+    it('returns code-specific message for INVALID_OTP', () => {
+      expect(getOtpErrorMessage({ code: 'INVALID_OTP', message: 'Invalid OTP' }, 'code')).toBe(
+        'Invalid code. Please try again.',
+      )
+    })
+
+    it('returns message for TOO_MANY_ATTEMPTS', () => {
+      expect(getOtpErrorMessage({ code: 'TOO_MANY_ATTEMPTS', message: 'Too many attempts' }, 'code')).toBe(
+        'Too many attempts. Please request a new code.',
+      )
+    })
+  })
+
+  describe('fallbacks', () => {
+    it('uses error.message when code is unknown', () => {
+      expect(getOtpErrorMessage({ code: 'UNKNOWN', message: 'Custom message' }, 'link')).toBe('Custom message')
+    })
+
+    it('uses fallback when error has no code or message', () => {
+      expect(getOtpErrorMessage({}, 'link')).toBe('Verification failed. Please try again.')
+    })
+  })
+})

src/lib/otp-error-messages.ts

@@ -0,0 +1,26 @@
+type OtpError = { code?: string; message?: string }
+type OtpErrorContext = 'link' | 'code'
+
+const messages: Record<OtpErrorContext, Record<string, string>> = {
+  link: {
+    OTP_EXPIRED: 'This link has expired. Please request a new one.',
+    INVALID_OTP: 'This link is invalid. Please request a new one.',
+    TOO_MANY_ATTEMPTS: 'Too many attempts. Please request a new code.',
+  },
+  code: {
+    OTP_EXPIRED: 'This code has expired. Please request a new one.',
+    INVALID_OTP: 'Invalid code. Please try again.',
+    TOO_MANY_ATTEMPTS: 'Too many attempts. Please request a new code.',
+  },
+}
+
+const fallback = 'Verification failed. Please try again.'
+
+/**
+ * Returns a user-friendly message for OTP verification errors.
+ * Handles OTP_EXPIRED, INVALID_OTP, and TOO_MANY_ATTEMPTS from Better Auth.
+ */
+export const getOtpErrorMessage = (error: OtpError, context: OtpErrorContext): string => {
+  const message = error?.code ? messages[context][error.code] : undefined
+  return message ?? error?.message ?? fallback
+}