npm package: @skroz/frontend
Description: React-компоненты для аутентификации: формы входа/регистрации, OAuth-кнопки, Telegram-авторизация. Построена на Relay + Next.js + Ant Design.
Latest version: 0.0.38

# @skroz/frontend

React-компоненты для аутентификации: формы входа/регистрации, OAuth-кнопки, Telegram-авторизация. Построена на Relay + Next.js + Ant Design.

## Relay и SKROZ_PROTECTION

### Проблема

Relay компилирует `graphql\`` теги в артефакты в `src/graphql/` (`artifactDirectory` в relay.config.json).
**Relay удаляет все файлы из этой директории, которые он не распознаёт** (т.е. не нашёл соответствующий `graphql\`` тег в исходниках).

Так как библиотека поставляется с уже скомпилированными артефактами в `src/`, а `graphql\`` теги в исходниках убраны — при следующей компиляции relay снёс бы их.

### Решение: SKROZ_PROTECTION

Relay-скрипт проекта умеет «разблокировать» мутации перед компиляцией и «блокировать» обратно. Определение мутации хранится внутри комментария — в рантайме оно не выполняется, но скрипт его видит и может восстановить.

### Формат блока

```tsx
/*
  SKROZ_PROTECTION NOTE:
  The Relay compiler has generated artifacts for this mutation.
  Explicit import of FooMutationNode is used.

  Mutation definition (for reference/regeneration):
  graphql`
      mutation FooMutation($input: SomeInput!) {
        someField(input: $input) {
          id
        }
      }
    `
*/
import FooMutationNode, { FooMutation } from '../graphql/FooMutation.graphql';
```

### Правила именования

- Название мутации **должно начинаться с имени файла компонента** (без `.tsx`):
  - `OAuthButtons.tsx` → `OAuthButtonsMutation`
  - `TelegramBotAuthButton.tsx` → `TelegramBotAuthButtonGenerateMutation`, `TelegramBotAuthButtonConfirmMutation`
- **Один блок `/* SKROZ_PROTECTION */` = одна мутация.** При нескольких мутациях в одном файле — несколько отдельных блоков.
- Relay генерирует тип с точным именем мутации. Если нужен другой — использовать alias при импорте: `import { TelegramAuthData as TelegramAuthDataInput }`.

---

## Экспорты

### Auth-компоненты

| Компонент | Описание |
|---|---|
| `Auth` | Обёртка/контейнер для auth-страниц |
| `Login` | Страница/форма входа |
| `Register` | Страница/форма регистрации |
| `Forgot` | Форма запроса восстановления пароля |
| `RecoverPassword` | Форма ввода нового пароля по токену |
| `AuthFooterLinks` | Ссылки внизу auth-форм (войти / зарегистрироваться) |
| `LoginForm` | Форма логина без страничной обёртки |
| `ResendLinkButton` | Кнопка повторной отправки письма |
| `LogoutButton` | Кнопка выхода |
| `AuthModal` | Модалка с auth-формами |
| `AuthButtons` | Набор кнопок (вход / регистрация) |

### OAuth

#### `OAuthButtons`

Отображает кнопки всех провайдеров. Для Telegram может показывать либо официальный виджет (`telegramBotUsername`), либо кастомную кнопку через `authViaBot` из `FrontendConfig`.

```tsx
import { OAuthButtons } from '@skroz/frontend';

<OAuthButtons
  providers={['google', 'vk', 'telegram']}
  redirectUris={{ google: '...', vk: '...' }}
  telegramBotUsername="MyBot"
  onSuccess={() => router.push('/dashboard')}
/>
```

Props: `providers: OAuthProvider[]`, `redirectUris?: Partial<Record<OAuthProvider, string>>`, `telegramBotUsername?: string`, `onSuccess?: () => void`

Relay-мутация: `OAuthButtonsMutation` (`src/graphql/OAuthButtonsMutation.graphql.ts`)

#### `OAuthButton`

Одиночная кнопка OAuth-провайдера.

#### `OAuthProvider` (type)

```ts
type OAuthProvider = 'google' | 'vk' | 'ya' | 'mail' | 'apple' | 'telegram'
```

#### `TelegramBotAuthButton`

Кнопка авторизации через Telegram-бота (deep link + polling). Работает в паре с `generateTelegramAuthToken` / `confirmTelegramAuthToken` мутациями и функцией `confirmTelegramBotAuth` из `@skroz/profile-api` на стороне бота.

**Redirect-логика убрана** — редирект после входа обрабатывается глобально в `MyProfileProvider`.

```tsx
import { TelegramBotAuthButton } from '@skroz/frontend';

<TelegramBotAuthButton onSuccess={() => router.push('/dashboard')} />
```

Props: `onSuccess?: () => void`

Relay-мутации: `TelegramBotAuthButtonGenerateMutation`, `TelegramBotAuthButtonConfirmMutation`

#### `oauth-icons`

SVG-иконки провайдеров (реэкспортируются из `src/auth/oauth-icons/`).

---

## FrontendConfig

`useFrontendConfig()` возвращает `{ oauthClientIds, authViaBot }`.

`authViaBot` — если передан в `FrontendProvider`, подставляется вместо Telegram Login Widget внутри `OAuthButtons`. Используется для `TelegramBotAuthButton` (авторизация через бота, а не через виджет).

---

## Артефакты Relay (src/graphql/)

| Файл | Мутация |
|---|---|
| `OAuthButtonsMutation.graphql.ts` | `oauthLogin` |
| `TelegramBotAuthButtonGenerateMutation.graphql.ts` | `generateTelegramAuthToken` |
| `TelegramBotAuthButtonConfirmMutation.graphql.ts` | `confirmTelegramAuthToken` |