API Error Handling — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans.

Goal: Создать useMutationWithToast обёртку, улучшить getApiErrorMessage, исправить CheckoutPage error display.

Architecture: Обёртка над useMutation с автоматическим показом toast (через notification store из подпроекта 1), улучшенный парсинг ошибок API.

Tech Stack: TypeScript, TanStack React Query, Vitest

Depends on: Subproject 1 (toast notifications store)

Task 1: Улучшить getApiErrorMessage

Files:

Modify: client/src/shared/lib/get-api-error-message.ts
Test: modify existing or add new tests
Step 1: Write/update tests

// client/src/shared/lib/__tests__/get-api-error-message.test.ts
import { describe, it, expect } from 'vitest'
import { getApiErrorMessage } from '../get-api-error-message'

describe('getApiErrorMessage', () => {
  it('returns server error message when axios error has response.data.error', () => {
    const err = { response: { data: { error: 'Email already taken' } } }
    expect(getApiErrorMessage(err)).toBe('Email already taken')
  })

  it('returns network error message when no response', () => {
    const err = { message: 'Network Error', code: 'ERR_NETWORK' }
    expect(getApiErrorMessage(err)).toBe('Нет соединения с сервером. Проверьте подключение к интернету.')
  })

  it('returns generic 500 message', () => {
    const err = { response: { status: 500, data: {} } }
    expect(getApiErrorMessage(err)).toBe('Произошла ошибка. Попробуйте повторить позже.')
  })

  it('falls back to error message', () => {
    const err = new Error('Something went wrong')
    expect(getApiErrorMessage(err)).toBe('Something went wrong')
  })

  it('handles unknown error shape', () => {
    expect(getApiErrorMessage({})).toBe('Произошла неизвестная ошибка')
  })
})

Step 2: Run to see failure

Run: cd client && npx vitest run shared/lib/__tests__/get-api-error-message.test.ts Expected: FAIL (existing tests may not cover new cases)

Step 3: Implement improved getApiErrorMessage

// client/src/shared/lib/get-api-error-message.ts
import { isAxiosError } from 'axios'

export function getApiErrorMessage(error: unknown): string {
  if (!error) return 'Произошла неизвестная ошибка'

  if (isAxiosError(error)) {
    if (error.response?.data?.error && typeof error.response.data.error === 'string') {
      return error.response.data.error
    }
    if (!error.response) {
      return 'Нет соединения с сервером. Проверьте подключение к интернету.'
    }
    if (error.response.status >= 500) {
      return 'Произошла ошибка. Попробуйте повторить позже.'
    }
  }

  if (error instanceof Error) {
    return error.message
  }

  return 'Произошла неизвестная ошибка'
}

Step 4: Run tests

Run: cd client && npx vitest run shared/lib/__tests__/get-api-error-message.test.ts Expected: PASS

Step 5: Commit

git add client/src/shared/lib/get-api-error-message.ts client/src/shared/lib/__tests__/get-api-error-message.test.ts
git commit -m "feat: improve getApiErrorMessage with user-friendly messages"

Task 2: useMutationWithToast обёртка

Files:

Create: client/src/shared/lib/use-mutation-with-toast.ts
Test: client/src/shared/lib/__tests__/use-mutation-with-toast.test.tsx
Step 1: Write failing tests

// client/src/shared/lib/__tests__/use-mutation-with-toast.test.tsx
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { renderHook, waitFor } from '@testing-library/react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { useMutationWithToast } from '../use-mutation-with-toast'
import { addNotification } from '../../model/notification'

vi.mock('../../model/notification', () => ({
  addNotification: vi.fn(),
}))

function createWrapper() {
  const qc = new QueryClient()
  return ({ children }: { children: React.ReactNode }) => (
    <QueryClientProvider client={qc}>{children}</QueryClientProvider>
  )
}

describe('useMutationWithToast', () => {
  beforeEach(() => {
    vi.clearAllMocks()
  })

  it('shows success toast on success', async () => {
    const mutationFn = vi.fn().mockResolvedValue({ ok: true })

    const { result } = renderHook(
      () => useMutationWithToast({ mutationFn, successMessage: 'Done!' }),
      { wrapper: createWrapper() },
    )

    result.current.mutate()
    await waitFor(() => expect(result.current.isSuccess).toBe(true))

    expect(addNotification).toHaveBeenCalledWith({ type: 'success', message: 'Done!' })
  })

  it('shows error toast on error', async () => {
    const mutationFn = vi.fn().mockRejectedValue(new Error('Boom'))

    const { result } = renderHook(
      () => useMutationWithToast({ mutationFn }),
      { wrapper: createWrapper() },
    )

    result.current.mutate()
    await waitFor(() => expect(result.current.isError).toBe(true))

    expect(addNotification).toHaveBeenCalledWith({ type: 'error', message: 'Boom' })
  })

  it('calls user-provided onSuccess', async () => {
    const mutationFn = vi.fn().mockResolvedValue({ ok: true })
    const onSuccess = vi.fn()

    const { result } = renderHook(
      () => useMutationWithToast({ mutationFn, onSuccess, successMessage: 'Done!' }),
      { wrapper: createWrapper() },
    )

    result.current.mutate()
    await waitFor(() => expect(result.current.isSuccess).toBe(true))

    expect(onSuccess).toHaveBeenCalled()
  })

  it('does not show success toast if no successMessage', async () => {
    const mutationFn = vi.fn().mockResolvedValue({ ok: true })

    const { result } = renderHook(
      () => useMutationWithToast({ mutationFn }),
      { wrapper: createWrapper() },
    )

    result.current.mutate()
    await waitFor(() => expect(result.current.isSuccess).toBe(true))

    expect(addNotification).not.toHaveBeenCalled()
  })
})

Step 2: Run to verify failure

Run: cd client && npx vitest run shared/lib/__tests__/use-mutation-with-toast.test.tsx Expected: FAIL

Step 3: Implement useMutationWithToast

// client/src/shared/lib/use-mutation-with-toast.ts
import { useMutation, type UseMutationOptions } from '@tanstack/react-query'
import { addNotification } from '../model/notification'
import { getApiErrorMessage } from './get-api-error-message'

type MutationWithToastOptions<TData, TError, TVariables, TContext> =
  UseMutationOptions<TData, TError, TVariables, TContext> & {
    successMessage?: string
  }

export function useMutationWithToast<TData = unknown, TError = unknown, TVariables = void, TContext = unknown>(
  options: MutationWithToastOptions<TData, TError, TVariables, TContext>,
) {
  const { successMessage, onSuccess, onError, ...mutationOptions } = options

  return useMutation({
    ...mutationOptions,
    onSuccess: (data, variables, context) => {
      if (successMessage) {
        addNotification({ type: 'success', message: successMessage })
      }
      onSuccess?.(data, variables, context)
    },
    onError: (error, variables, context) => {
      addNotification({ type: 'error', message: getApiErrorMessage(error) })
      onError?.(error, variables, context)
    },
  })
}

Step 4: Run tests

Run: cd client && npx vitest run shared/lib/__tests__/use-mutation-with-toast.test.tsx Expected: PASS

Step 5: Commit

git add client/src/shared/lib/use-mutation-with-toast.ts client/src/shared/lib/__tests__/use-mutation-with-toast.test.tsx
git commit -m "feat: add useMutationWithToast wrapper"

Task 3: Исправить CheckoutPage error display

Files:

Modify: client/src/pages/checkout/CheckoutPage.tsx
Step 1: Найти прямой вызов error.message

Search for: (createMut.error as Error).message

Step 2: Заменить на getApiErrorMessage

Before:

{createMut.isError && (
  <Alert severity="error">
    {(createMut.error as Error).message}
  </Alert>
)}

After:

import { getApiErrorMessage } from '@/shared/lib/get-api-error-message'

{createMut.isError && (
  <Alert severity="error">
    {getApiErrorMessage(createMut.error)}
  </Alert>
)}

Step 3: Run lint + test + build

cd client && npm run lint && npm test && npm run build

Step 4: Commit

git add client/src/pages/checkout/CheckoutPage.tsx
git commit -m "fix: use getApiErrorMessage in CheckoutPage for user-friendly error display"

8.8 KiB Raw Blame History

API Error Handling — Implementation Plan

Task 1: Улучшить getApiErrorMessage

Task 2: useMutationWithToast обёртка

Task 3: Исправить CheckoutPage error display

8.8 KiB

Raw Blame History