README

Самостоятельный Composer-пакет big-bang-notify/sdk для отправки уведомлений по Telegram user ID и получения статуса доставки. Namespace: BigBangNotify\Sdk. HTTP-клиент работает без Laravel; для Laravel 13 есть необязательный service provider.

Требования: PHP 8.3+, cURL и JSON. Тестовая матрица: PHP 8.3, 8.4, 8.5 и Laravel 13. Приложение Big Bang Notify, его БД и Telegram bot token пакету не нужны.

Установка

В Docker-окружении приложения-потребителя:

composer require big-bang-notify/sdk:^0.1

Пакет распространяется через Packagist, исходники — в GitHub. Дополнительный repositories override не требуется. Локальное подключение и VCS описаны в руководстве по установке. Версию Composer определяет по веткам/тегам; поле version в composer.json отсутствует.

Обычный PHP

use BigBangNotify\Sdk\Client;

$client = new Client('https://big-bang-notify.com', (string) getenv('BBN_API_SECRET'));

// ID — из проверенного Telegram update вашего бота.
// Payload, occurred_at и key сохраняются с исходным событием для повторов.
$receipt = $client->sendNotification((string) $telegramUserId, [
    'category' => 'orders',
    'event_type' => 'order.updated',
    'title' => 'Заказ обновлён',
    'body' => 'Откройте приложение, чтобы посмотреть детали.',
    'occurred_at' => $eventOccurredAt,
], 'order-update-'.$eventId);

$status = $client->notificationStatus($receipt['id']);

BBN_API_SECRET — credential бота-источника, выданный администратором сервиса. Храните его на backend. Telegram bot token и API-секрет имеют разные назначения. Пользователь один раз регистрируется в Big Bang Notify через служебного бота; linkAccount, код синхронизации и вход через SDK не нужны.

202 означает сохранённую запись inbox; provider_accepted — принятие push-провайдером. OS-показ проверяется отдельно. Сервис выполняет fan-out на все активные устройства аккаунта; inbox сохраняется и без push-подписок.

Laravel 13

Provider обнаруживается автоматически. Добавьте BBN_API_SECRET в приватную конфигурацию приложения; BBN_URL по умолчанию https://big-bang-notify.com. В контейнере Laravel:

php artisan vendor:publish --tag=bbn-sdk-config

use BigBangNotify\Sdk\Client;

$client = app(Client::class);

BBN_ALLOW_INSECURE по умолчанию false. Явный HTTP override предназначен для локального fixture; рабочее подключение использует HTTPS. SDK не меняет маршруты, миграции, очереди и аутентификацию приложения.

Ошибки и повторы

ApiException предоставляет errorCode, httpStatus и retryAfter без raw response body в сообщении. SDK сохраняет известные машинные коды сервиса; неизвестное значение code заменяется на http_error с сохранением HTTP status и Retry-After. network_unknown / status 0 означает неопределённый исход: сервис мог принять запрос. Автоматических повторов нет. Используйте тот же idempotency key и точно тот же payload, включая occurred_at.

Ошибка	Значение
recipient_not_found / 404	Пользователь не зарегистрирован; SDK не создаёт аккаунт
bot_blocked / 403	Пользователь запретил источник
idempotency_conflict / 409	Под этим ключом принят другой payload
rate_limited / 429	Учитывайте Retry-After и повторяйте исходное событие
invalid_response	Ответ не соответствует ожидаемому JSON-объекту

Некорректные URL, Telegram ID, UUID, idempotency key и credentials вызывают InvalidArgumentException; не кодируемый в JSON payload — JsonException. Не логируйте credentials, title/body и metadata. Redirects не выполняются; connect timeout 3 секунды, общий timeout 10 секунд.

Чувствительные аргументы Client и CurlTransport скрыты из PHP exception traces через SensitiveParameter, включая ошибки JSON-кодирования. Это не заменяет настройку zend.exception_ignore_args=On и фильтрацию данных в диагностике приложения. Собственные реализации Transport должны помечать чувствительные параметры и защищать свои ошибки самостоятельно: атрибуты интерфейса не наследуются реализациями.

Разработка

docker compose config --quiet
docker compose build sdk
docker compose run --rm sdk composer install --no-interaction --prefer-dist
docker compose run --rm sdk composer check
docker compose run --rm sdk composer check-platform-reqs
docker compose down

Check включает manifest, Pint, PHPStan, PHPUnit и установку Composer archive в чистые PHP/Laravel-проекты. Laravel smoke проверяет auto-discovery и vendor:publish. HTTP-тесты используют внутренний Docker fixture; реальный сервис не вызывается. GitHub CI повторяет проверки на PHP 8.3/8.4/8.5.

composer.lock фиксирует dev toolchain, но не зависимости потребителей. В архив не включаются vendor, тесты, Docker/CI-файлы, lock, конфигурация окружения и кэши. Планируемый номер релиза — VERSION; см. release runbook.

Лицензия: MIT.

big-bang-notify / sdk

Package info

Security

Statistics