winzik/docs/notifications.md

123 lines
9.4 KiB
Markdown

# Notifications push (runtime JumPHP) : spécification
Une application JumPHP qui tourne dans le navigateur peut envoyer des **notifications sur le téléphone** de ses utilisateurs, par
l'intermédiaire de l'application **JumPHP runtime pour Android** (`apps/runtime-android`). Apple : plus tard. Ce document est le
contrat commun entre :
- le **runtime Android** (`apps/runtime-android`) : consentement, réception FCM, affichage, accusés ;
- le **serveur jumphp.net** (dépôt `jumphp-playground`) : abonnements, envoi, files, quotas, stats, studio, administration, MCP distant ;
- l'**extension moteur** `jumphp/notification` (`extensions/notification`, futur dépôt `jumphp-notification`) : l'API PHP des jeux / applis ;
- les **outils du développeur** : `bin/jumphp notify ...` (scripts) et `bin/jumphp notify:mcp` (serveur MCP local pour Claude).
## Trois portes
1. **L'administrateur de jumphp.net** : le droit `notify` de l'application est approuvé, comme `tcp` / `ssh` (studio « Accès réseau »,
approbation par commit) ; il peut suspendre les notifications d'une application ou bloquer un appareil à tout moment.
2. **Le propriétaire de l'application** : seul lui détient le **jeton d'envoi** `jnt_…` (créé dans le studio, montré une fois, révocable,
stocké haché). Sans lui, rien ne part.
3. **La personne** : une boîte de dialogue **native** du runtime (« *Titre* veut vous envoyer des notifications. Autoriser ? ») ; son
accord est gardé sur le téléphone, révocable application par application dans le runtime. Le runtime **revérifie** cet accord à chaque
notification reçue (une notification d'une application non autorisée n'est jamais affichée et le serveur est prévenu).
## Abonnement (page → runtime → serveur)
```
page (extension) runtime Android jumphp.net
│ ticket = POST /api/tcp/ticket {scope:"notify"} ─────────────────────────►│ (droit notify approuvé ?)
│ {"t":"notify-subscribe", ...} ──►│ vérifie origine + ticket (Ticket.kt)
│ │ dialogue natif (Autoriser / Refuser)
│ │ POST /api/notify/devices ─────────────►│ revérifie le ticket, enregistre
│◄── {"t":"notify-subscribed"} ────│◄──────────── {"subscription":"ns_…"} ──│
```
### Messages page ↔ runtime (WebSocket `ws://127.0.0.1:47820/v1`, en plus de docs/runtime-protocol.md)
| Sens | Message |
|---|---|
| page → runtime | `{"t":"notify-subscribe","app":"<slug>","title":"<titre>","ticket":"<ticket notify>","user":"<id choisi par le développeur, ≤128, optionnel>","groups":["<≤32 groupes de ≤64>"]}` |
| runtime → page | `{"t":"notify-subscribed","app":"<slug>","granted":true,"subscription":"ns_…"}` ou `{"t":"notify-subscribed","app":"<slug>","granted":false,"reason":"denied|later|server|ticket"}` |
| page → runtime | `{"t":"notify-unsubscribe","app":"<slug>"}` → `{"t":"notify-unsubscribed","app":"<slug>"}` |
| page → runtime | `{"t":"notify-status","app":"<slug>"}` → `{"t":"notify-status","app":"<slug>","granted":bool,"subscription":"ns_…"|null,"user":"…"|null}` |
| runtime → page | `hello` gagne `"notify":true` quand le runtime sait afficher des notifications (Android) ; le runtime de bureau répond `{"t":"error","code":"unsupported"}` |
Le ticket `notify` est un ticket ordinaire de `/api/tcp/ticket` (même format, mêmes signatures) dont `scope` = `notify` et sans cible
(`host` / `port` vides). Refus gardé 10 min ; 30 s sans réponse = refus ; un seul dialogue à la fois (comme `pair`).
## API du serveur (`https://jumphp.net`)
Côté **runtime** (identifié par l'appareil, jamais par la page) :
- `POST /api/notify/devices` `{device, secret, fcm, ticket, app, origin, user, groups, platform:"android", locale, runtime}` →
`{subscription}`. `device` = UUID généré par le runtime ; `secret` = 32 octets aléatoires base64url gardés par le runtime, jamais
donnés aux pages ; le premier enregistrement d'un `device` fixe le secret (stocké haché), les suivants doivent le redonner.
Ré-abonnement = mise à jour (user, groups, fcm). Le jeton FCM change : même appel.
- `DELETE /api/notify/devices/{subscription}` `{device, secret}` ; `DELETE /api/notify/devices` `{device, secret}` = tout.
- `POST /api/notify/ack` `{device, secret, events:[{n:"<id notification>", e:"delivered|opened|dismissed|refused", at}]}` (par lots).
Côté **développeur** (`Authorization: Bearer jnt_…`, le jeton de l'application) :
- `POST /api/notify/send` `{to:{all?:true, users?:[], groups?:[], subscriptions?:[]}, title (≤65), body (≤240), url? (chemin de
l'application, ex. "/play/?room=ABCD", ou une adresse de son origine), tag?, ttl? (s, défaut 86400, max 604800), data? (≤2 Ko JSON)}`
→ `{id:"nt_…", targets:N}` ; `dry_run:true` = compte seulement.
- `GET /api/notify/notifications?limit&before` (historique) ; `GET /api/notify/notifications/{id}` (détail + compteurs).
- `GET /api/notify/stats?from&to` → par jour : `sent delivered opened dismissed refused failed`, abonnés actifs, désabonnements.
- `GET /api/notify/subscribers?user&group&limit&cursor` (sans jeton FCM ni données d'appareil : `subscription user groups created last_seen`).
- `GET /api/notify/groups` ; `PUT /api/notify/users/{user}/groups` `{groups:[…]}` (le développeur range ses utilisateurs côté serveur aussi).
- `DELETE /api/notify/subscriptions/{subscription}` (le développeur retire un abonné).
Erreurs JSON `{error, code}` ; `429` avec `Retry-After`. Quotas par défaut (modifiables par l'administrateur, par application) :
60 envois / minute, 20 000 livraisons / jour, 1 notification / 10 s vers une même personne pour un même `tag`.
### Message FCM (data, priorité haute)
`{"t":"notify","n":"nt_…","app":"<slug>","title":"…","body":"…","url":"https://…","tag":"…","sub":"ns_…","exp":"<unix>"}` —
le runtime ne lit que ces clés. Le serveur réutilise `App\Service\FcmSender` (déjà là pour `wake`). Un jeton FCM refusé par Google =
abonnement marqué `failed` puis supprimé.
### Notifications globales (administrateur)
L'administrateur peut envoyer à **tous les appareils** (ou ceux d'une application) une notification `app:"jumphp"` affichée sous le nom
JumPHP, dans un canal Android à part que la personne peut couper. Pas de jeton : la page d'administration et le MCP distant
(compte administrateur) seulement.
## Runtime Android
- Dialogue de consentement (même mécanique que `pair` : `ConsentActivity`), en 14 langues ; accord stocké par application
(`notify-grants`), liste + révocation dans l'écran principal (révoquer = `DELETE` côté serveur).
- `FcmService` : `t:"notify"` → accord local présent et pas expiré ? → notification Android (un canal par application, nommé par son titre ;
`tag` remplace la précédente) ; un clic ouvre `url` dans le navigateur et envoie `opened` ; sinon `refused` + désabonnement.
`delivered` à l'affichage, `dismissed` au balayage. Accusés envoyés par lots (WorkManager / au prochain réveil).
- Android 13+ : permission `POST_NOTIFICATIONS` demandée au premier abonnement.
- Le journal (`Journal`) note abonnements, révocations, notifications reçues (sans leur texte).
## Extension `jumphp/notification`
```php
$n = $this->engine->service(\JumphpExtensions\Notification\Notifications::class); // ou injecté dans la scène
$n->supported(); // navigateur + runtime Android prêt (sinon false, avec reason())
$n->subscribe(user: 'player-42', groups: ['beta'])->then(fn (bool $ok) => ...); // Task
$n->status()->then(fn (?Subscription $s) => ...);
$n->unsubscribe();
```
Gui : widget `NotifyToggle` (« Recevoir les notifications ») qui gère tout (runtime absent → `RuntimeGuide`). Côté serveur / scripts PHP :
`JumphpExtensions\Notification\Sender` (`new Sender($token)`, `send()`, `stats()`, `history()`, `groups()`, `setGroups()`) qui
parle à l'API ci-dessus (Http du moteur, ou curl hors moteur).
## Outils du développeur
- `bin/jumphp notify:login <app>` : demande le jeton (saisie masquée), le garde dans `~/.jumphp/notify/tokens.json` (0600), jamais dans le dépôt.
`JUMPHP_NOTIFY_TOKEN` / `JUMPHP_NOTIFY_URL` gagnent.
- `bin/jumphp notify <app> --all|--user U|--group G "Titre" "Texte" [--url /play/] [--dry-run]`, `notify:stats <app>`, `notify:history <app>`.
- `bin/jumphp notify:mcp` : serveur MCP stdio (`claude mcp add jumphp-notify -- bin/jumphp notify:mcp`), outils `notify_send`,
`notify_dry_run`, `notify_stats`, `notify_history`, `notify_subscribers`, `notify_groups`, `notify_set_groups`. Un envoi à `all`
demande `confirm:true`.
- Le MCP distant de jumphp.net (`/mcp`, jeton du compte) gagne `notify_send`, `notify_stats`, `notify_history` pour les projets du compte.
## Studio et administration (jumphp.net)
- **Studio, projet → Notifications** : activer (demande du droit `notify`), créer / renouveler / révoquer le jeton, abonnés, groupes,
formulaire d'envoi (aperçu, envoi test à soi), historique, statistiques (courbes par jour, taux d'ouverture).
- **Administration → Notifications** : vue globale (applications, abonnés, envois du jour, échecs), statistiques complètes, quotas par
application, suspendre une application, bloquer un appareil, notification globale, journal.
- Toutes les chaînes en 14 langues (`fr en es de it pt nl pl ru uk tr ja zh ko`).