push
Multi-platform mobile push notifications. Notifications are declared
with the defpush macro and delivered through Firebase Cloud Messaging
(FCM) and the Apple Push Notification service (APNs) behind a unified
service, with job-backed reliable delivery and delivery analytics.
Key namespaces
| Namespace | Purpose |
|---|---|
|
Pure: locale resolution and template rendering |
|
|
|
Pure: delivery planning + error classification (retryable / permanent / token-invalid) |
|
Pure: device-token lifecycle logic (registration, rotation, deactivation) |
|
Pure: delivery analytics aggregation |
|
Protocols: |
|
Orchestrator dispatching to platform providers |
|
FCM provider — async parallel delivery via |
|
APNs provider — async parallel delivery via |
|
REST endpoints (devices, callback, stats) |
Declaring notifications
The defpush macro defines notifications declaratively with i18n locale
maps, deep links, priority, TTL, collapse keys, and retry configuration.
Device tokens
Device token lifecycle is managed end to end — registration, rotation, soft-deactivation, and cleanup of stale tokens. Tokens are stored with multi-tenant support.
Reliable delivery
send-push!, schedule-push! and broadcast! enqueue :push/send and
:push/broadcast jobs, so the :wagoe/jobs module must be enabled; the
handlers and queue are wired only then. Each device’s result is recorded in
push_send_log, and a token the provider reports invalid is deactivated.
A failed send to one device is not retried; a job retries only when its
handler throws.
Analytics
An HMAC-secured callback endpoint accepts client-reported delivery and
open events, recorded in push_analytics_events. Each push’s data carries
notification-id, provider-message-id and callback-token; the app posts
them back with device-token, platform and event-type (delivered or
opened). Each device gets its own token, valid for seven days by default and for that
notification, device and platform only; a repeat is answered but counted once.
The sent row and its callbacks share callback_id. This needs
:callback-secret in :wagoe/push: without it pushes carry no token, every
callback is refused with 403, and push warns at boot unless both providers are
mocks.
Two optional :wagoe/push keys tune the token:
| Key | Default | Meaning |
|---|---|---|
|
|
How long a token verifies. Raise it when a push’s provider TTL is longer, or a late callback is refused. |
|
|
Refuse tokens in the 1.0 form, which verify for any notification and device and never expire. |
Endpoints
| Endpoint | Purpose |
|---|---|
|
Register and list the caller’s device tokens |
|
Read or unregister one; a registration’s |
|
HMAC-secured delivery/open analytics callback (public) |
|
Per-notification delivery stats ( |
The module mounts these routes itself. Every route but the callback needs a signed-in user.
Database
| Table | Holds |
|---|---|
|
Registered device tokens |
|
Per-send delivery records |
|
Client-reported delivery/open events |
Mock providers are included for dev/test, and Integrant wiring is provided for all components.