@foxford/sdk 5.0.0

package/README.mdx

@@ -0,0 +1,493 @@
+Пакет SDK для работы с платформой Foxford. Предоставляет типизированный интерфейс для взаимодействия с API Foxford и управление виджетами.
+
+## Основные компоненты
+
+### Foxford - основной класс
+
+Класс Foxford является точкой входа в SDK. Инициализируется с конфигурацией и предоставляет доступ ко всем сервисам.
+
+**Конструктор:**
+```typescript
+new Foxford(config?: FoxfordConfig)
+```
+
+**Свойства:**
+
+- `user` - UserService для управления пользовательскими данными
+- `cart` - CartService для работы с корзиной
+- `course` - CourseService для получения информации о курсах
+- `promo` - PromoService для работы с промокодами
+- `tag` - TagService для управления тегами
+- `widgets` - Widgets для инициализации виджетов
+- `productPack` - ProductPackService для работы с пакетами продуктов
+- `appOptions` - AppOptionsService для получения опций приложения
+- `captcha` - CaptchaService для работы с капчей
+
+**Методы:**
+
+- `shortURL(url: string): Promise<ApiResponse<unknown>>` - создание короткой ссылки
+- `applyPlugin(plugin: SdkPlugin): void` - применение плагина к SDK
+
+### Конфигурация (FoxfordConfig)
+
+```typescript
+interface FoxfordConfig {
+  host?: string                    // Базовый URL API (по умолчанию: https://foxford.ru)
+  widgetsVersion?: 'latest' | string  // Версия виджетов (deprecated)
+  antibot?: boolean                // Включить антимеханизм защиты (по умолчанию: true)
+  antibotConfig?: FoxfordAntibotConfig  // Конфигурация антибота
+  api?: ApiConfig                  // Дополнительная конфигурация API
+  captchaConfig?: () => CaptchaConfig   // Конфигурация капчи
+  widgetsConfig?: WidgetsInitConfig    // Конфигурация виджетов (deprecated)
+}
+```
+
+### События SDK
+
+```typescript
+static events = {
+  FETCH_APP_OPTIONS: 'Foxford.app_options.fetch',
+  LR_REGISTRATION_SET: 'LR_REGISTRATION_SET'
+}
+```
+
+---
+
+## Сервисы
+
+### UserService
+
+Предоставляет методы для работы с пользовательскими данными.
+
+**Методы:**
+
+- `async addTag(id: number): Promise<unknown>` - добавить тег пользователю
+- `async enrollCourse(id: number): Promise<void>` - записать пользователя на курс (deprecated, используйте CourseService)
+
+### CartService
+
+Работа с корзиной.
+
+**Методы:**
+
+- `createCartItem(id: number, type: CartItemResourceType): CartItemDTO` - создать объект элемента корзины
+- `async addCartItemToCart(cartItem: CartItemDTO): Promise<unknown>` - добавить элемент в корзину
+
+### CourseService
+
+Работа с курсами.
+
+**Методы:**
+
+- `async getCourse(id: number): Promise<Course>` - получить информацию о курсе по ID
+- `async enrollCourse(id: number): Promise<void>` - записать пользователя на курс
+
+**Пример:**
+```typescript
+const course = await sdk.course.getCourse(123)
+await sdk.course.enrollCourse(123)
+```
+
+### PromoService
+
+Работа с промокодами и акциями.
+
+**Методы:**
+
+- `async checkPromocode(code: string): Promise<unknown>` - проверить валидность промокода
+- `async trackCodeCampaign(promoCode: string): Promise<void>` - записать факт показа промокода
+
+### TagService
+
+Управление тегами пользователей.
+
+**Методы:**
+
+- `async addTag(id: number): Promise<unknown>` - добавить тег пользователю
+
+### WidgetsService
+
+Инициализация и управление виджетами Foxford.
+
+**Типы:**
+
+```typescript
+type Widget = {
+  name: 'menu' | 'reviews' | 'featuredCoaches' | 'coachEnrollment' |
+         'shortForm' | 'userTypePrompt' | 'teachersSlider' | 'externshipFormats'
+  options: Record<string, any>
+  container?: HTMLElement
+}
+
+type WidgetsInitConfig = {
+  version?: 'latest' | string
+  locale?: 'ru'
+}
+```
+
+**Методы:**
+
+- `async create(config: WidgetsConfig): Promise<void>` - инициализировать виджеты
+- `async update(name: string, config: Widget): Promise<void>` - обновить существующий виджет
+
+**Пример:**
+```typescript
+await sdk.widgets.create({
+  widgets: [
+    {
+      name: 'menu',
+      options: { /* опции */ }
+    }
+  ]
+})
+```
+
+### ProductPackService
+
+Работа с пакетами продуктов.
+
+**Методы:**
+
+- `async getProductPack(id: number): Promise<ProductPack>` - получить информацию о пакете продукта по ID
+
+### AppOptionsService
+
+Получение опций приложения (настройки, флаги экспериментов и т.д.).
+
+**Методы:**
+
+- `async getCurrentAppOptions(): Promise<AppOptions>` - получить текущие опции (с кешированием)
+- `async getAppOptions(): Promise<AppOptions>` - получить опции из API
+
+---
+
+## Сущности и типы данных
+
+### UserDTO
+
+```typescript
+interface UserDTO {
+  id: null | number
+  email: string
+  firstName: string
+  middleName: string
+  lastName: string
+  fullName: string
+  shortName: string
+  createdAt: null | string
+  timezone: null | string
+  locale: null | string
+  grade: { id: null | number; index: null | number; name: null | string; translit: null | string }
+  phone: null | string
+  avatarUrl: string
+  isParent: boolean
+  isGraduated: boolean
+  gradeChecked: boolean
+  type: null | 'pupil' | 'agent'
+  isCoach: boolean
+  isMiniGroupTeacher: boolean
+  isExternshipCoach: boolean
+  isAgent: boolean
+  methodist: boolean
+  address: { /* адресные данные */ } | null
+  socialNets: Array<{ provider: 'facebook' | 'google_oauth2' | ...; uid: number }>
+  skype: null | string
+  settings?: { /* настройки пользователя */ }
+  bonus: { giftAmount: number; realMoneyAmount: number }
+  bonusAmount: number
+  hasActivePurchases: boolean
+  hasAttemptsSolveExamRehearsals: boolean
+  hasBookmarks: boolean
+  tags: null | string[]
+  cartTemplateId: null | number
+  cartItemsCount: number
+  onboardingFinished: boolean
+  emailConfirmed: boolean
+  phoneConfirmed: boolean
+  // ... и другие поля
+}
+```
+
+### ProductPack
+
+```typescript
+type ProductPack = {
+  name: string
+  description: string
+  meta_title: string
+  meta_description: string
+  published: true
+  content_description: string
+  disciplines_scope: string
+  guaranteed_admission: true
+  grade_names: string
+  is_purchased: false
+  learning_flow: { title: string; steps: Array<{ header: string; description: string }> }
+  offers: { intro: string; items: Array<{ title: string; description: string }> }
+  price_block: {
+    price: number
+    initial_price: number
+    title: string
+    description: string
+    points: Array<string>
+    price_per_month: number
+    initial_price_per_month: number
+  }
+  product_pack_items: Array<ProductTypeItem>
+  faq_items: Array<{ question: string; answer: string }>
+  landing_image_urls: Array<string>
+}
+```
+
+---
+
+## Плагины
+
+### ConfirmPhone
+
+Плагин для подтверждения номера телефона в формах.
+
+**Конструктор:**
+```typescript
+new ConfirmPhone(node: HTMLInputElement, options?: IConfirmPhoneOptions)
+```
+
+**Методы:**
+
+- `apply(sdk: Foxford): void` - применить плагин к SDK
+- `destroy(): void` - удалить плагин
+- `requestCode(payloadData: TRequestData): Promise<TRequestResponse>` - запросить код подтверждения
+- `confirmCode(payloadData: TConfirmData): Promise<TConfirmResponse>` - подтвердить код
+
+**Опции конфигурации:**
+
+```typescript
+{
+  className?: string                    // CSS класс контейнера
+  confirmCodeInvalidText?: string      // Текст ошибки неверного кода
+  confirmCodePlaceholderText?: string  // Плейсхолдер поля кода
+  confirmedInputClassName?: string     // CSS класс подтвержденного поля
+  disabledClassName?: string           // CSS класс отключенного состояния
+  errorClassName?: string              // CSS класс ошибки
+  hiddenClassName?: string             // CSS класс скрытого элемента
+  inputParentsToHide?: string[]        // Элементы-родители для скрытия
+  requestButtonText?: string           // Текст кнопки запроса кода
+  retryButtonText?: string             // Текст кнопки повторной отправки
+  sendCodeButtonText?: string          // Текст кнопки отправки кода
+  unconfirmedHintText?: string         // Текст подсказки неподтвержденного номера
+  untilRetryText?: string              // Текст таймера повторной отправки
+  userData?: { phone: string; phoneConfirmed: boolean }  // Данные пользователя
+}
+```
+
+### EmailAutocomplete
+
+Плагин для автодополнения email-адресов с проверкой на опечатки (используется алгоритм Левенштейна).
+
+**Конструктор:**
+```typescript
+new EmailAutocomplete(node: HTMLInputElement, options?: EacOptions)
+```
+
+**Методы:**
+
+- `apply(): void` - применить плагин к полю ввода
+- `destroy(): void` - удалить плагин
+- `clear(): void` - очистить состояние плагина
+
+**Опции конфигурации:**
+
+```typescript
+{
+  emailDomains?: string[]              // Список доменов для автодополнения (по умолчанию: gmail.com, mail.ru, yandex.ru и др.)
+  suggestionClass?: string             // CSS класс для отображения автодополнения
+  suggestionColor?: string             // Цвет текста автодополнения
+  suitableColor?: string               // Цвет сообщения "возможно, вы имели в виду"
+  suitableEmailColor?: string          // Цвет email-адреса в подсказке
+  suitableFontSize?: string            // Размер шрифта подсказки
+  suitableLineHeight?: string          // Высота строки подсказки
+  suitableLevenshteinTreshold?: number  // Допустимое расстояние Левенштейна (по умолчанию: 5)
+  
+  onAutocomplete?(value: string): void      // Коллбек при автодополнении
+  onShowSuitableEmail?(): void              // Коллбек при показе подсказки
+  onClickSuitableEmail?(): void             // Коллбек при клике на подсказку
+  onHideSuitableEmail?(): void              // Коллбек при скрытии подсказки
+}
+```
+
+---
+
+## Антимеханизм защиты (FoxfordAntibot)
+
+Механизм для борьбы с автоматизированными запросами.
+
+**Конструктор:**
+```typescript
+new FoxfordAntibot(config?: FoxfordAntibotConfig)
+```
+
+**Опции конфигурации:**
+
+```typescript
+{
+  antibotFrameSrc?: string      // URL для антимеханизма (по умолчанию: https://foxford.ru/antibot/ping)
+  antibotOnload?(e: Event): void  // Коллбек при успешной инициализации
+  antibotOnerror?(): void         // Коллбек при ошибке инициализации
+  debug?: boolean                 // Режим отладки
+}
+```
+
+---
+
+## API плагины
+
+SDK поставляется с набором встроенных API плагинов:
+
+- `CamelizeRequestPlugin` - трансформация snake_case в camelCase для запросов к API
+- `ReferrerRequestPlugin` - добавление реферера в заголовки запросов
+- `DataLayerEventDispatcherPlugin` - отправка событий в dataLayer для Google Analytics
+- `CaptchaPlugin` - интеграция с капчей
+
+---
+
+## Примеры использования
+
+### Инициализация SDK
+
+```typescript
+import { Foxford } from '@foxford/sdk'
+
+const sdk = new Foxford({
+  host: 'https://foxford.ru',
+  antibot: true,
+  widgetsConfig: {
+    locale: 'ru'
+  }
+})
+```
+
+### Работа с курсами
+
+```typescript
+// Получить информацию о курсе
+const course = await sdk.course.getCourse(123)
+console.log(course)
+
+// Записаться на курс
+await sdk.course.enrollCourse(123)
+```
+
+### Работа с корзиной
+
+```typescript
+// Создать элемент корзины
+const cartItem = sdk.cart.createCartItem(456, 'course')
+
+// Добавить в корзину
+await sdk.cart.addCartItemToCart(cartItem)
+```
+
+### Работа с промокодами
+
+```typescript
+// Проверить промокод
+const result = await sdk.promo.checkPromocode('DISCOUNT2024')
+console.log(result)
+
+// Записать факт показа промокода
+await sdk.promo.trackCodeCampaign('DISCOUNT2024')
+```
+
+### Инициализация виджетов
+
+```typescript
+await sdk.widgets.create({
+  locale: 'ru',
+  widgets: [
+    {
+      name: 'menu',
+      options: {}
+    },
+    {
+      name: 'reviews',
+      options: { limit: 5 }
+    },
+    {
+      name: 'featuredCoaches',
+      options: { count: 3 }
+    }
+  ]
+})
+```
+
+### Подтверждение телефона
+
+```typescript
+import { ConfirmPhone } from '@foxford/sdk'
+
+const phoneInput = document.querySelector('input[type="tel"]') as HTMLInputElement
+const confirmPlugin = new ConfirmPhone(phoneInput, {
+  userData: {
+    phone: '+79991234567',
+    phoneConfirmed: false
+  }
+})
+
+confirmPlugin.apply(sdk)
+```
+
+### Автодополнение email
+
+```typescript
+import { EmailAutocomplete } from '@foxford/sdk'
+
+const emailInput = document.querySelector('input[type="email"]') as HTMLInputElement
+const autocompletePlugin = new EmailAutocomplete(emailInput, {
+  emailDomains: ['gmail.com', 'yandex.ru'],
+  onAutocomplete: (value) => {
+    console.log('Автодополнено:', value)
+  }
+})
+
+autocompletePlugin.apply()
+```
+
+---
+
+## Ошибки
+
+### LogginError
+
+Ошибка при работе с авторизацией.
+
+```typescript
+import { LogginError } from '@foxford/sdk'
+
+throw new LogginError('Unauthorized', { cause: error })
+```
+
+### ConfirmationCodeRequestError
+
+Ошибка при запросе кода подтверждения.
+
+```typescript
+import { ConfirmationCodeRequestError } from '@foxford/sdk'
+
+throw new ConfirmationCodeRequestError('Invalid code', { cause: error })
+```
+
+---
+
+## Экспортные точки
+
+SDK предоставляет следующие экспортные точки:
+
+- `@foxford/sdk` - основной пакет с Foxford и всеми сервисами
+- `@foxford/sdk/plugins/confirm-phone` - плагин подтверждения телефона отдельно
+- `@foxford/sdk/plugins/autocomplete-email` - плагин автодополнения email отдельно
+
+---
+
+## Лицензия
+
+MIT © Foxford Co