herfy-push 1.0.0

Web Push SDK for Herfy applications — send browser push notifications via Control Center VAPID config

herfy-push

Web Push SDK for Herfy applications. Send browser push notifications using only your Control Center client_id and client_secret — no VAPID private key handling in app config.

Installation

pip install herfy-push

Usage

from herfy_push import HerfyPushClient, AsyncHerfyPushClient

# Sync
client = HerfyPushClient.from_credentials(
    client_id="app_customer_care",
    client_secret="your_secret",
    control_center_url="https://cc.herfy.com",
)
client.send(
    subscription={"endpoint": "...", "keys": {"p256dh": "...", "auth": "..."}},
    payload={"title": "SLA breach", "body": "Ticket #123", "url": "https://app/tickets/123"},
)

# Async (FastAPI)
client = AsyncHerfyPushClient.from_env()
await client.send(subscription=..., payload=...)
public_key = await client.get_public_key()  # hand to the browser's pushManager.subscribe()

How it works

1. SDK authenticates with Control Center via POST /oauth/token (cached, TTL configurable via PUSH_TOKEN_CACHE_TTL).
2. SDK fetches VAPID keys from GET /api/config/push (cached for the client's process lifetime).
3. SDK sends directly to the browser's push service via the Web Push protocol (pywebpush) — no further Control Center round-trip per send.

Error handling

• AuthError — Control Center rejected the client credentials.
• ConfigError — Control Center push config endpoint failed or is missing VAPID keys.
• PushSubscriptionExpiredError — the push service returned 404/410: the subscription is dead, delete it from your database.
• SendError — any other send failure.

Environment variables

• CONTROL_CENTER_URL, AUTH_CLIENT_ID, AUTH_CLIENT_SECRET — required, used by .from_env().
• PUSH_TOKEN_CACHE_TTL (default 240), PUSH_REQUEST_TIMEOUT (default 15) — optional.