# Виджеты участника

Готовые элементы страницы (web components) для сайта мерчанта: участник, вошедший на сайте, видит свои баллы, историю
и показывает на кассе код — без разработки интерфейса (ADR-0018). Виджеты говорят с API участника
([member-v1.yaml](member-v1.yaml)) от имени одного участника, с сеансом, который открыл бэкенд сайта.

| Элемент | Что показывает | Скоупы сеанса |
|---|---|---|
| `<loyal-member-card>` | Баллы, которые можно потратить (участнику с приостановленным списанием — баллы на счёте и предупреждение); ещё не доступные, в резерве под оплату и ближайшее сгорание; уровень, его начисление и путь до следующего; карты штампов — штампы до следующей бесплатной единицы и бесплатные, которые можно получить; код для приглашения друзей. | `profile` |
| `<loyal-points-history>` | Операции с баллами, новые сверху, страницами с кнопкой «Показать ещё». | `history` и `profile` (знаки после запятой у баллов) |
| `<loyal-presentation-code>` | По нажатию — код для кассы и его QR-код на две минуты с обратным отсчётом; истёкший код исчезает. | `presentation_code` |

## Как это устроено

1. **Бэкенд сайта** открывает вошедшему участнику сеанс: `POST /api/management/v1/member-sessions` с ключом, у которого
   есть скоуп `widgets` (для `presentation_code` — ещё и `members`: касса списывает баллы по коду без SMS). В запросе —
   программа, участник (`member_id` или `external_id` мерчанта), сайт страницы `origin` так, как его пишет браузер
   (`https://shop.example.com`), скоупы и срок `ttl_seconds` (60–3600, по умолчанию 900). Ответ — токен `lms_…`.
2. **Страница** подключает скрипт виджетов и даёт виджетам функцию `tokenProvider`: она просит токен у бэкенда сайта и
   возвращает его — или `null`, если сеанса для этой страницы нет (участник не вошёл или ещё не участник программы).
   Сбой бэкенда функция сообщает исключением. Токен живёт только в памяти страницы: не в адресе, не в cookie и не в
   localStorage.
3. **Виджеты** с одной функцией и одним API делят один сеанс: функцию зовут один раз на сеанс. Истёкший или закрытый
   сеанс (ответ 401) виджеты заменяют сами, снова позвав функцию; когда нового нет — показывают «Войдите на сайте» и
   сообщают событием `loyal-session-expired`.

Сеанс работает только со страниц своего сайта (`Origin` каждого запроса браузер ставит сам) и только пока действует
ключ, который его открыл. Страница на том же сайте, что и API, `Origin` не отправляет — виджеты всегда говорят с API на
его собственном адресе.

### Бэкенд сайта на PHP

С [PHP SDK](../../sdk/php/README.md) — обработчик `POST /loyalty/member-session` сайта:

```php
use Loyal\Sdk\ClientOptions;
use Loyal\Sdk\Exception\ConflictException;
use Loyal\Sdk\Exception\NotFoundException;
use Loyal\Sdk\Generated\ProblemCode;
use Loyal\Sdk\ManagementClient;

// Ключ мерчанта (lm_…) со скоупами widgets и members; партнёр — ManagementClient::forPartner(…)->forMerchant($merchantId).
$site = ManagementClient::forMerchantKey(getenv('LOYAL_MERCHANT_KEY'), new ClientOptions(baseUrl: 'https://api.example.com'));

header('Content-Type: application/json');
header('Cache-Control: no-store');

// Пока сеанс действует, его отдают снова: каждый новый сеанс — вызов Management API и запись в журнале аудита.
$cached = $_SESSION['loyal_member_session'] ?? null;

if ($user !== null && $cached !== null && $cached['user'] === $user->id && strtotime($cached['expires_at']) > time() + 60) {
    echo json_encode(['token' => $cached['token']]);

    return;
}

try {
    $session = $user === null ? null : $site->issueMemberSession(body: [
        'program_id' => $programId,
        'external_id' => (string) $user->id,                     // или member_id; external_id — строка
        'origin' => 'https://shop.example.com',                  // сайт страницы с виджетами
        'scopes' => ['profile', 'history', 'presentation_code'], // по умолчанию — profile и history
    ]);
} catch (NotFoundException $e) {
    $session = null;                                             // ещё не участник программы
} catch (ConflictException $e) {
    if (! $e->is(ProblemCode::MEMBER_BLOCKED)) {
        throw $e;
    }

    $session = null;                                             // участник заблокирован
}

if ($session !== null) {
    $_SESSION['loyal_member_session'] = ['user' => $user->id, 'token' => $session['token'], 'expires_at' => $session['expires_at']];
}

// null — сеанса для этой страницы нет: виджеты покажут «Войдите на сайте», страница решит, что предложить.
echo json_encode(['token' => $session['token'] ?? null]);
```

- Остальные ошибки (ключ отозван, лимит запросов, сбой платформы) обработчик отдаёт ответом 5xx: функция страницы
  бросает исключение, и виджеты предлагают «Повторить», а не вход.
- Если мерчант объединил дубль участника с основной записью (ADR-0019), `external_id` находит основную запись сам, а
  сеанс по `member_id` дубля не открывается: 409 `member_merged` (`$e->is(ProblemCode::MEMBER_MERGED)`), и
  `$e->extension('survivor_id')` — id записи, у которой теперь всё: сайт сохраняет его у пользователя вместо прежнего.
- Обработчик отвечает только вошедшему пользователю своего сайта и защищён от запросов чужих страниц, как любое
  действие сайта (cookie сайта с `SameSite`, CSRF-токен).
- Когда участник выходит, бэкенд закрывает все его сеансы и забывает сохранённый токен:
  `$site->revokeMemberSessions(body: ['program_id' => $programId, 'external_id' => (string) $user->id])`
  (`POST /api/management/v1/member-sessions:revoke`).

## Страница

Код для страницы с текущей версией и её integrity — в кабинете партнёра, раздел «Виджеты»; та же пара — в
`https://api.example.com/embed/v1/build.json`.

```html
<script type="module" src="https://api.example.com/embed/v1/<версия>/loyal-widgets.js"
        integrity="sha384-…" crossorigin="anonymous"></script>

<loyal-member-card></loyal-member-card>
<loyal-points-history limit="20"></loyal-points-history>
<loyal-presentation-code></loyal-presentation-code>

<script type="module">
  // csrfToken — CSRF-токен сайта, как у любого его POST-запроса.
  const tokenProvider = async () => {
    const response = await fetch('/loyalty/member-session', { method: 'POST', headers: { 'X-CSRF-TOKEN': csrfToken } });

    if (!response.ok) {
      throw new Error(`Сеанс участника не получен: ${response.status}`);
    }

    return (await response.json()).token; // null — сеанса для этой страницы нет
  };

  for (const widget of document.querySelectorAll('loyal-member-card, loyal-points-history, loyal-presentation-code')) {
    widget.tokenProvider = tokenProvider;
  }

  document.addEventListener('loyal-session-expired', () => {
    // Сеанса нет: покажите вход — или, если пользователь вошёл, приглашение в программу.
  });
</script>
```

- **Версия.** Каждая версия — свой адрес `/embed/v1/<версия>/`; опубликованная версия не меняется и не удаляется,
  поэтому integrity (SRI) остаётся верным, а скрипт нельзя подменить. Новая версия появляется в кабинете — переходите
  на неё, когда будете готовы. `v1` в адресе — поколение элементов и их свойств: в нём они меняются только совместимо.
- **Модуль.** Скрипт подключается как `type="module"` (без `defer`: модуль и так ждёт разбора страницы) с атрибутом
  `crossorigin`. Свойства, заданные элементам до загрузки скрипта, виджеты подхватывают.
- **Выход и смена пользователя.** Когда участник выходит без перезагрузки страницы, вызовите `endSession()` у любого
  виджета: все виджеты этого сеанса сразу перестают показывать его данные, а следующий вход возьмёт новый сеанс. Без
  этого `refresh()` покажет данные по прежнему сеансу, пока он не истечёт, — того, кто вышел.
- **Песочница** (ADR-0012) — скрипт со своего адреса песочницы (`https://sandbox.api.example.com/embed/v1/…`) и сеансы
  `lms_test_…`; сеанс другого окружения виджет не примет.

## Элементы

### Атрибуты

| Атрибут | Элемент | Что задаёт |
|---|---|---|
| `limit` | `<loyal-points-history>` | Операций на странице истории: 1–100, по умолчанию 10. |

### Свойства и методы

| Имя | Что делает |
|---|---|
| `tokenProvider` | Функция без аргументов, которая возвращает токен сеанса (`lms_…`) или `null` — можно через `Promise`. Виджеты с одной функцией и одним API делят сеанс; новая функция — новый сеанс. Исключение функции — «Не удалось загрузить данные» с кнопкой «Повторить». |
| `api` | Адрес API (`https://api.example.com`), если он не тот сайт, с которого загружен скрипт виджетов (по умолчанию — тот). Только свойство из скрипта страницы, не атрибут: разметку на странице может вставить и чужой, а виджет отдаёт API сеанс участника. Новый адрес — виджет начинает заново. |
| `texts` | Свои тексты вместо текстов виджета: объект `{ ключ: текст }` (ключи — ниже). Неизвестные ключи и не строки пропускаются с предупреждением в консоли. |
| `refresh()` | Показать данные заново, проверив настройки (например, после того как участник снова вошёл на сайте). Сеанс остаётся прежним: смена пользователя — через `endSession()`. |
| `endSession()` | Закрыть сеанс виджетов с той же функцией и тем же API (участник вышел на сайте) — можно и у виджета, которого уже нет на странице: все они сразу перестают показывать данные участника до `refresh()`, а сеанс закрывается и в API. Возвращает `Promise`. |

### Событие `loyal-session-expired`

Виджет сообщает, что сеанса участника нет и нового нет: функция вернула `null` (`detail.reason` — `signed_out`) или API
отверг сеанс, который она только что дала (`rejected`: например, участника заблокировали или его сеансы закрыли сразу
после выдачи). Событие всплывает (`bubbles`, `composed`) — его можно слушать на `document`; каждый виджет сообщает о
себе сам. После `endSession()` события нет: выход начал сам сайт.

### Что видит участник, когда данных нет

| Состояние | Текст | Что делать |
|---|---|---|
| Сеанса нет | «Войдите на сайте, чтобы увидеть свои баллы.» | Событие `loyal-session-expired`; после входа — `refresh()`. |
| Программа не работает | «Программа лояльности пока не работает.» и «Повторить» | Правила программы не опубликованы (409 `rules_not_published`). |
| Виджет не настроен | «Виджет не настроен: ему не хватает доступа.» | Причина — в консоли браузера: неверный `api`, сеанс без нужного скоупа (`scope_missing`), страница не с сайта сеанса (`origin_mismatch`), сеанс другого окружения, функция вернула не токен. |
| Сбой | «Не удалось загрузить данные. Попробуйте ещё раз.» и «Повторить» | Сеть, лимиты API (429), ошибки сервера, исключение функции. |

## Оформление

Виджеты рисуются в своём Shadow DOM: стили страницы в них не проникают, и наоборот. Шрифт и цвет текста виджеты
наследуют от страницы; остальное задаётся переменными и частями.

```css
loyal-member-card,
loyal-points-history,
loyal-presentation-code {
  --loyal-color-accent: #e11d48;
  --loyal-radius: 4px;
}

loyal-member-card::part(balance-value) {
  font-size: 2.5rem;
}

/* Программа без «Приведи друга»: код для приглашения ничего не даёт. */
loyal-member-card::part(referral) {
  display: none;
}
```

Код для приглашения друзей есть у каждого участника, даже если в программе нет бонусов «Приведи друга»: в такой
программе скройте его, как в примере.

### Переменные

| Переменная | По умолчанию | Что задаёт |
|---|---|---|
| `--loyal-font-family` | шрифт страницы | Шрифт виджета. |
| `--loyal-font-size` | `1rem` | Размер текста. |
| `--loyal-color-text` | цвет текста страницы | Цвет текста. |
| `--loyal-color-muted` | цвет текста на 70 % | Второстепенный текст: даты, подсказки. |
| `--loyal-color-background` | прозрачный | Фон рамки виджета. |
| `--loyal-color-border` | серый полупрозрачный | Рамка виджета и разделители. |
| `--loyal-color-accent` | `#0f766e` | Баланс, кнопки, штампы, полоса прогресса. |
| `--loyal-color-accent-text` | `#fff` | Текст кнопок. |
| `--loyal-color-positive` | `#15803d` | Начисления в истории. |
| `--loyal-color-negative` | `#b91c1c` | Списания в истории и сбои. |
| `--loyal-color-notice` | жёлтый полупрозрачный | Фон предупреждения о приостановленном списании и бесплатных штампах. |
| `--loyal-radius` | `12px` | Скругление рамки. |
| `--loyal-button-radius` | `8px` | Скругление кнопок. |
| `--loyal-padding` | `16px` | Отступ внутри рамки. |
| `--loyal-gap` | `8px` | Расстояние между строками. |
| `--loyal-qr-size` | `200px` | Размер QR-кода. |

### Части (`::part()`)

| Часть | Элемент | Что это |
|---|---|---|
| `widget` | все | Рамка виджета. |
| `title` | все | Заголовок. |
| `message` | все | Сообщение: загрузка, нет сеанса, сбой, пустая история, истёкший код. |
| `button` | все | Кнопка: «Повторить», «Показать ещё», «Показать код», «Новый код». |
| `phone` | карта | Маскированный телефон. |
| `balance` | карта | Строка баланса. |
| `balance-value` | карта | Баллы, которые можно потратить (при приостановленном списании — на счёте). |
| `expiration` | карта | Ближайшее сгорание. |
| `notice` | карта | Предупреждение о приостановленном списании. |
| `tier` | карта | Блок уровня. |
| `progress` | карта | Полоса пути до следующего уровня (`<progress>`). |
| `next-tier` | карта | Что осталось до следующего уровня. |
| `stamps` | карта | Блок карт штампов. |
| `stamp-card` | карта | Одна карта штампов. |
| `stamp` | карта | Отметка штампа. |
| `stamp-filled` | карта | Полученный штамп (вместе с `stamp`). |
| `stamp-free` | карта | Бесплатные единицы, которые можно получить. |
| `referral` | карта | Код для приглашения друзей. |
| `list` | история | Список операций. |
| `item` | история | Операция. |
| `amount` | история | Изменение баллов операции. |
| `hint` | код | Подсказка до показа кода. |
| `qr` | код | QR-код (`<img>`). |
| `code` | код | Цифры кода. |
| `countdown` | код | Сколько код ещё действует. |

### Тексты

Любой текст виджета можно заменить своим через свойство `texts`; `{name}` — место значения, которое подставляет
виджет. Пример — баллы программы называются бонусами: слово после числа задают ключи `points.*`, а баллы упоминают ещё
тексты `signedOut`, `card.onAccount`, `card.frozen`, `history.title`, `history.empty`, `history.type.activation`,
`history.type.capture`, `history.type.restore`, `history.type.transfer`, `history.type.other`,
`history.reference.activity` и `code.hint` — замените и их.

```js
widget.texts = {
  'points.one': 'бонус',
  'points.few': 'бонуса',
  'points.many': 'бонусов',
  'points.other': 'бонуса',
  'history.title': 'История бонусов',
  // …и остальные тексты о баллах.
};
```

| Ключ | Текст |
|---|---|
| `loading` | Загрузка… |
| `retry` | Повторить |
| `error` | Не удалось загрузить данные. Попробуйте ещё раз. |
| `signedOut` | Войдите на сайте, чтобы увидеть свои баллы. |
| `unavailable` | Программа лояльности пока не работает. |
| `forbidden` | Виджет не настроен: ему не хватает доступа. |
| `points.one` | балл (1, 21 балл) |
| `points.few` | балла (2, 3, 4 балла) |
| `points.many` | баллов (5, 11 баллов) |
| `points.other` | балла (число с дробной частью: 1,50 балла) |
| `card.title` | Карта участника (без имени) |
| `card.greeting` | Здравствуйте, {name}! |
| `card.spendable` | Можно потратить |
| `card.onAccount` | Баллы на счёте (подпись баланса при приостановленном списании) |
| `card.available` | На счёте: {points} |
| `card.pending` | Ещё станут доступны: {points} |
| `card.held` | В резерве под оплату: {points} |
| `card.expiration` | Сгорание {date}: {points} |
| `card.frozen` | Тратить баллы пока нельзя: списание приостановлено. Баллы за покупки начисляются. |
| `card.tier` | Уровень «{title}» |
| `card.accrual` | Начисление — {percent} % от суммы, оплаченной деньгами |
| `card.retained` | Уровень сохраняется до {date} |
| `card.next` | До уровня «{title}»: {left} |
| `card.nextReached` | Условия уровня «{title}» выполнены |
| `card.top` | Это высший уровень |
| `card.leftAmount` | ещё {amount} |
| `card.leftPurchases.one` | ещё {count} покупка |
| `card.leftPurchases.few` | ещё {count} покупки |
| `card.leftPurchases.many` | ещё {count} покупок |
| `card.and` | « и » — между условиями уровня |
| `card.progress` | Путь до уровня «{title}» (подпись полосы для экранного диктора) |
| `card.stamps` | {title}: {stamps} из {goal} (штампы до следующей бесплатной единицы) |
| `card.stampsFree` | Можно получить бесплатно: {count} |
| `card.referral` | Код для друзей: {code} |
| `history.title` | История баллов |
| `history.empty` | Операций с баллами пока не было. |
| `history.more` | Показать ещё |
| `history.type.accrual` | Начисление |
| `history.type.activation` | Баллы стали доступны |
| `history.type.hold` | Резерв под оплату |
| `history.type.capture` | Оплата баллами |
| `history.type.release` | Резерв снят |
| `history.type.expiration` | Сгорание |
| `history.type.restore` | Возврат баллов за возвращённую покупку |
| `history.type.reversal` | Отмена начисления |
| `history.type.adjustment` | Корректировка |
| `history.type.transfer` | Перенос баллов (при объединении двух профилей участника) |
| `history.type.other` | Операция с баллами (тип, которого виджет не знает) |
| `history.reference.receipt` | покупка |
| `history.reference.welcome_bonus` | приветственный бонус |
| `history.reference.birthday_bonus` | бонус ко дню рождения |
| `history.reference.referral_bonus` | бонус за приглашение |
| `history.reference.activity` | баллы за действие |
| `history.reference.member_transfer` | объединение профилей |
| `code.title` | Код для кассы |
| `code.hint` | Покажите код кассиру: касса найдёт вас по нему и сможет списать баллы. Никому другому код не сообщайте. |
| `code.show` | Показать код |
| `code.qr` | QR-код для кассы (описание картинки) |
| `code.left` | Код действует ещё {time} |
| `code.expired` | Срок кода истёк. |
| `code.new` | Новый код |

Тексты и значения виджеты вставляют только как текст, никогда как разметку: имя участника или свой текст сайта не
станут частью страницы. Код для кассы действует две минуты с выдачи; виджет считает их от отправки запроса по
собственному времени устройства, поэтому неверные часы телефона не покажут код дольше, чем он работает.

## Политика безопасности страницы (CSP)

Если сайт задаёт заголовок `Content-Security-Policy`, добавьте в него адрес платформы для скрипта и запросов виджетов
и картинки `data:` для QR-кода:

```
script-src https://api.example.com;
connect-src https://api.example.com;
img-src data:;
```

- Свой код страницы (функцию `tokenProvider` и подписку на событие) держите во внешнем файле сайта или пометьте nonce,
  как любой свой скрипт: строгая политика не выполнит встроенный `<script>` без него. С `'strict-dynamic'` адреса в
  `script-src` не действуют — подключайте скрипт виджетов с nonce.
- Стили виджетов — общая таблица стилей их Shadow DOM (constructable stylesheets): `style-src 'unsafe-inline'` им не
  нужен. Браузер без таких таблиц (Safari до 16.4) получает элемент `<style>`, который строгая политика без
  `'unsafe-inline'` не применит: виджеты работают, но без оформления.

**Браузеры:** текущие версии Chrome, Edge, Firefox, Safari и браузеров на их движках — с модулями, custom elements и
Shadow DOM.

## Для платформы: раздача скрипта

Сборки виджетов — статические файлы `public/embed/v1/<версия>/loyal-widgets.js` (их собирает
`composer widgets:build` из `frontend/widgets`, они хранятся в git). Модули и SRI браузер загружает запросом CORS,
поэтому веб-сервер отдаёт `/embed/` с заголовками:

```nginx
location /embed/ {
    add_header Access-Control-Allow-Origin "*" always;
    add_header Cross-Origin-Resource-Policy "cross-origin" always;
    add_header X-Content-Type-Options "nosniff" always;

    location ~ ^/embed/v1/[0-9a-f]{12}/ {
        add_header Access-Control-Allow-Origin "*" always;
        add_header Cross-Origin-Resource-Policy "cross-origin" always;
        add_header X-Content-Type-Options "nosniff" always;
        # Без always: ответ 404 (версия ещё не на этом сервере) не должен остаться в кэше на год.
        add_header Cache-Control "public, max-age=31536000, immutable";
    }
}
```

Директивы `add_header` уровня `server` (HSTS и другие) в такие `location` не наследуются — повторите их там.

Apache (`mod_headers`, в конфигурации сервера или виртуального хоста):

```apache
<LocationMatch "^/embed/">
    Header always set Access-Control-Allow-Origin "*"
    Header always set Cross-Origin-Resource-Policy "cross-origin"
    Header always set X-Content-Type-Options "nosniff"
</LocationMatch>
<LocationMatch "^/embed/v1/[0-9a-f]{12}/">
    # Без always: только успешные ответы.
    Header set Cache-Control "public, max-age=31536000, immutable"
</LocationMatch>
```

`build.json` кэшируется ненадолго (без `immutable`). Файлы версии никогда не меняются: если файл с именем версии
отличается от сборки, `composer widgets:build` отказывается его перезаписать, а тест платформы не даёт удалить или
изменить закоммиченную сборку.

Локальная проверка — `php artisan db:seed --class=LocalWidgetsSeeder` и страница `/widgets-demo` (только в окружении
`local`, [docs/dev/setup.md](../dev/setup.md)).
