Об этом проекте

Легкий и типизированный TypeScript-клиент для API Alegra, ориентированный на уровень интеграции. Он охватывает аутентификацию, пагинацию и обработку ограничений частоты запросов (rate limits) с повторными попытками для ресурсов контактов, товаров и счетов. Это неофициальный проект, не связанный с Alegra; документация представлена на испанском языке из-за ее дефицита по мнению автора. Аутентификация Используется HTTP Basic с электронной почтой и API-токеном (не паролем). Токен генерируется в Alegra в разделе интеграций/API аккаунта. Базовый URL: https://api.alegra.com/api/v1; ошибка аутентификации возвращает HTTP 401. В README рекомендуется хранить учетные данные в переменных окружения, для чего прилагается файл .env.example. Пагинация API возвращает максимум 30 записей на страницу с помощью параметров start (offset) и limit. Клиент предоставляет асинхронный генератор для постраничного обхода без загрузки всех данных в память, а также методы для получения одной страницы или сбора всех результатов. Доступные ресурсы и методы: контакты (listar, obtener, paginar, listarTodos), товары (listar, obtener, paginar, listarTodos) и счета (listar, obtener, paginar, listarTodas). Для непокрытых эндпоинтов можно использовать прямой клиент с общим методом request, принимающим параметры запроса. Rate limits и повторные попытки В README указан лимит 150 запросов в минуту на пользователя (примерно 2,5 в секунду). При превышении API возвращает HTTP 429 и сообщает статус в заголовках X-Rate-Limit-Limit, X-Rate-Limit-Remaining и X-Rate-Limit-Reset (оставшиеся секунды до сброса окна); по словам автора, Alegra не отправляет Retry-After. Клиент автоматически повторяет запросы при 429 и 5xx ошибках: в случае 429 он ждет время, указанное в X-Rate-Limit-Reset (или Retry-After, если он есть), а при их отсутствии применяет экспоненциальный откат с джиттером. Ошибки 4xx не повторяются, однако предусмотрены повторы при сетевых сбоях. Конфигурируемые опции: minRequestIntervalMs (превентивный интервал между запросами), maxRetries, retryBaseMs и timeoutMs. Таймаут запроса реализован через AbortController. Если попытки при 429 исчерпаны, выбрасывается AlegraRateLimitError, которая может содержать retryAfterSeconds. Ошибки Для разграничения API-ошибок и исчерпания лимитов использования представлены классы AlegraApiError (со статусом, эндпоинтом и телом ответа) и AlegraRateLimitError. Требования и разработка Требуется Node.js 18 или выше из-за использования нативного fetch; runtime-зависимостей нет, что делает проект переносимым в Node, Deno и edge-среды. Процесс разработки включает npm run build, тестирование с помощью vitest на симулированном fetch и фиктивных данных, а также проверку типов (lint:types). Примеры используют вымышленные данные и учетные данные из переменных окружения. Лицензия MIT; версия в changelog — 0.1.0, первая публичная версия. Область применения В README содержится предупреждение о том, что включенная сводная таблица API Alegra должна обновляться при изменении официального API, а сам свод создан из-за нехватки документации на испанском языке. Заявления о производительности или сравнения с другими клиентами не приводятся.