KO

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":"","granted":false,"reason":"denied
page → runtime {"t":"notify-unsubscribe","app":"<slug>"} → {"t":"notify-unsubscribed","app":"<slug>"}
page → runtime {"t":"notify-status","app":"<slug>"} → `{"t":"notify-status","app":"","granted":bool,"subscription":"ns_…"
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

$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).