Клиент API CodeWar для школ
===========================

В архиве два файла:

  CodeWarClient.php   сам клиент - один класс, ни одной зависимости, PHP 7.4+
  example.php         рабочий пример: завести класс, показать пароли, выгрузить
                      статистику за неделю в CSV

Документация: https://codewar.ru/api


Как начать
----------

1. Положите CodeWarClient.php к себе в проект.

2. Возьмите ключ в кабинете преподавателя:
   Класс -> API для школы -> Создать ключ.
   Ключ показывается один раз, второй раз его не покажут - у нас хранится
   только хеш. Потеряли - отзовите и создайте новый.

3. Положите ключ в переменную окружения, а не в код: код попадёт в
   репозиторий, а переменная окружения - нет.

     Windows:      set CODEWAR_KEY=cw_live_...
     Linux, macOS: export CODEWAR_KEY=cw_live_...

4. Проверьте, что всё работает:

     php example.php setup

   Команды примера: setup (завести класс и учеников), passwords (показать
   логины и пароли), stats (выгрузить статистику за неделю в CSV).


Как пользоваться
----------------

    require __DIR__ . '/CodeWarClient.php';

    $cw = new CodeWarClient(getenv('CODEWAR_KEY'));

    $who    = $cw->me();                       // ключ рабочий? что мне можно?
    $class  = $cw->createClass('7Б информатика');
    $result = $cw->addStudents($class['id'], ['Иванов Пётр', 'Петрова Анна']);

    foreach ($result['data'] as $student) {
        echo $student['login'], ' ', $student['password'], PHP_EOL;
    }

    // Смотреть обязательно: здесь те, кого не завели, и почему
    foreach ($result['meta']['skipped'] as $skipped) {
        echo 'пропущен ', $skipped['name'], ': ', $skipped['reason'], PHP_EOL;
    }


Что клиент делает за вас
------------------------

  - подставляет заголовок Authorization: ключ никогда не уходит в адрес;
  - бросает CodeWarApiException с полями errorCode, status, fields, requestId;
  - сам ждёт и повторяет запрос, упёршийся в предел частоты (429);
  - листает страницы: allStudents() и allSessions() возвращают всё сразу.

Ошибки разбирайте по errorCode, а не по тексту: текст мы можем переписать,
код - нет. Список кодов есть в документации.


О чём стоит помнить
-------------------

  - Ключ работает только с вашими классами и вашими учениками. На чужие
    приходит 404 - не «скрыто», а «такого нет».
  - Пароль ученика виден, пока ученик не задаст свой в личном кабинете.
    У тех, кто пришёл в класс по ссылке со своим аккаунтом, пароля нет
    никогда: в ответе у них "managed": false.
  - Ключ - это доступ к персональным данным детей. Его место на вашем
    сервере, а не в репозитории, не в JavaScript на странице и не в
    мобильном приложении.

Лицензия: делайте с этими файлами что хотите.
