@aurabase/realtime 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aurabase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,220 @@
+# @aurabase/realtime
+
+Service temps réel du SDK Aurabase : une connexion WebSocket multiplexée sur des channels (`postgres_changes`, `broadcast`, `presence`).
+
+![npm](https://img.shields.io/npm/v/@aurabase/realtime) ![license](https://img.shields.io/badge/license-MIT-blue)
+
+> Pre-release — pas encore publié sur npm.
+
+Fait partie du SDK **[aurabase](../aurabase)**. Installé automatiquement avec `aurabase` ; ce package est publié séparément pour un usage ciblé / tree-shaking.
+
+## Installation
+
+```bash
+npm i @aurabase/realtime
+```
+
+> Dépend de `@aurabase/core`. Déjà inclus si vous utilisez le package `aurabase` — cette installation ciblée sert à composer votre propre client ou à limiter la taille du bundle. Nécessite un runtime avec `WebSocket` global (navigateur, ou Node avec un polyfill).
+
+## Usage
+
+`RealtimeService` est exposé par le client principal sous `aura.realtime`, et `aura.channel(name)` est un raccourci pour `aura.realtime.channel(name)`.
+
+```ts
+import { createClient } from '@aurabase/aurabase-js'
+
+const aura = createClient('http://localhost:8080', 'my-project', 'aura_anon_xxx')
+```
+
+### Connexion
+
+```ts
+const unsubscribe = aura.realtime.onStateChange((state) => {
+  console.log('realtime state:', state) // 'disconnected' | 'connecting' | 'connected' | 'reconnecting'
+})
+
+aura.realtime.connect()
+console.log(aura.realtime.connectionState)
+
+// Désactive la reconnexion auto (backoff + jitter), ou borne le nombre de tentatives.
+aura.realtime.setAutoReconnect(true, 5)
+
+// Pousse un nouveau token sur la connexion existante (sans reconnexion).
+aura.realtime.refreshToken('new-access-token')
+
+// Erreurs de transport (handshake refusé, coupure, connexion morte).
+const off = aura.realtime.onError((err) => {
+  console.error(err.phase, err.code, err.message)
+  // err.phase : 'handshake' | 'connection' | 'liveness'
+})
+```
+
+### Heartbeat et détection de connexion morte
+
+Un heartbeat applicatif (`{"type":"ping"}`) est envoyé toutes les **25 secondes** via un Worker
+dédié, pour éviter le throttling des timers par les navigateurs en arrière-plan.
+
+Ce heartbeat sert aussi de **détecteur de liveness** : le serveur répond immédiatement au ping et
+pousse de lui-même un `pong` toutes les 30 s, donc si aucun message n'est revenu entre deux ticks,
+la connexion est déclarée morte — même quand le système la croit encore ouverte (TCP à demi-fermé
+sur réseau mobile ou derrière un proxy, cas où aucun `close` n'est jamais émis). Le SDK détache
+alors la socket, notifie via `onError` (`phase: 'liveness'`) et `CHANNEL_ERROR` sur chaque canal,
+puis relance la reconnexion automatique (backoff exponentiel avec jitter).
+
+### Erreurs d'authentification à la connexion
+
+Un handshake refusé par le serveur (token JWT absent/expiré/invalide → HTTP 401) est signalé via
+`onError` avec `phase: 'handshake'`, et remonté aux canaux en `CHANNEL_ERROR`. La spécification
+WebSocket n'expose pas le statut HTTP du handshake au client (l'événement `error` est vide, le code
+de fermeture vaut toujours `1006`) : le SDK nomme donc la phase et les causes possibles, sans
+prétendre distinguer un 401 d'un 429 ou d'un serveur injoignable.
+
+### `postgres_changes`
+
+```ts
+const channel = aura.channel('db:public.posts')
+  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'posts' }, (payload) => {
+    console.log('insert:', payload)
+  })
+  .subscribe((status, err) => {
+    console.log(status, err)
+  })
+```
+
+Statuts émis par le callback de `subscribe()` (mêmes noms et même sémantique que
+`@supabase/realtime-js`) :
+
+| Statut | Quand |
+| --- | --- |
+| `SUBSCRIBED` | le serveur a confirmé l'abonnement |
+| `CHANNEL_ERROR` | refus serveur (RLS, rate limit, canal invalide), échec de handshake, coupure inattendue ou connexion morte — `err` porte le détail |
+| `TIMED_OUT` | aucune confirmation dans les 10 s suivant l'envoi du subscribe (délai réglable : `subscribe(cb, timeoutMs)`) |
+| `CLOSED` | fermeture volontaire du canal : `unsubscribe()`, `removeChannel()`, `removeAllChannels()`, `disconnect()` |
+
+Le compte à rebours de `TIMED_OUT` ne démarre qu'à l'envoi effectif du subscribe : tant que la
+connexion n'est pas ouverte, aucun timeout n'est émis.
+
+## Filtres de colonne (`postgres_changes`)
+
+`postgres_changes` accepte un champ `filter` (syntaxe PostgREST/Supabase : `"column=operator.value"`) pour ne recevoir que les events dont la ligne matche la condition :
+
+```ts
+aura.channel('room')
+  .on('postgres_changes', {
+    event: 'INSERT',
+    schema: 'public',
+    table: 'messages',
+    filter: 'room_id=eq.42',
+  }, (e) => console.log(e))
+  .subscribe()
+```
+
+Opérateurs supportés : `eq, neq, lt, lte, gt, gte, in, like, ilike, is, match, imatch, isdistinct`.
+
+```ts
+// Comparaison numérique.
+{ event: '*', schema: 'public', table: 'items', filter: 'qty=gt.5' }
+
+// Appartenance à un ensemble — les virgules internes à `in.(...)` ne
+// séparent PAS des conditions AND (voir plus bas).
+{ event: '*', schema: 'public', table: 'orders', filter: 'status=in.(open,pending)' }
+
+// Motif SQL LIKE (% / _).
+{ event: '*', schema: 'public', table: 'users', filter: 'name=like.jo%' }
+
+// Négation — préfixe `not.` devant l'opérateur.
+{ event: '*', schema: 'public', table: 'orders', filter: 'status=not.eq.done' }
+
+// AND par virgules — chaque condition séparée par `,` (hors `in.(...)`).
+{ event: '*', schema: 'public', table: 'items', filter: 'room_id=eq.42,qty=gt.5' }
+```
+
+À savoir :
+
+- **Le serveur `aura-realtime` est autoritaire** : il applique déjà le filtre avant d'envoyer l'event sur le socket. Le client réapplique la même logique en second rideau (defense-in-depth) — il ne peut que sur-filtrer, jamais laisser passer un event que le serveur aurait dû exclure.
+- **Fail-closed** : une condition non parsable (syntaxe invalide, opérateur inconnu, trop de valeurs `in`, pattern `match`/`imatch` trop long) exclut l'event plutôt que de le laisser passer.
+- **DELETE** : le filtre est évalué sur **l'ancienne ligne** (`old_record`), pas sur la nouvelle (qui n'existe plus). Les colonnes disponibles dans `old_record` dépendent du `REPLICA IDENTITY` de la table (`DEFAULT` : seule la clé primaire ; `FULL` : toutes les colonnes) — un filtre sur une colonne absente de `old_record` échoue à matcher (résultat non évaluable ⇒ exclusion, jamais inversée par `not.`), **sauf `is.null` et `isdistinct`** qui traitent une colonne absente comme `NULL` et peuvent donc matcher même si la colonne n'est pas présente dans `old_record`.
+- `schema` (et `table`) doivent correspondre exactement au schéma/table réels tels qu'envoyés par le serveur dans l'event — un `schema` incorrect exclut silencieusement tous les events de ce channel.
+
+### Broadcast
+
+```ts
+const room = aura.realtime.channel('room-1', { broadcast: { ack: true, self: true } })
+
+room
+  .on('broadcast', { event: 'cursor-pos' }, (payload) => {
+    console.log(payload)
+  })
+  .subscribe()
+
+// 'ok' | 'timeout' | 'error' — résout à l'ACK serveur si broadcast.ack est activé sur le channel.
+const status = await room.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100, y: 200 } })
+```
+
+#### Broadcast HTTP (sans WebSocket)
+
+Émet un broadcast via REST, sans connexion WebSocket ouverte — utile côté serveur/edge.
+
+```ts
+// POST /v1/realtime/{projectId}/broadcast — pas besoin de connect().
+const { error } = await aura.realtime.httpBroadcast('room-1', 'cursor-pos', { x: 10, y: 20 })
+if (error) console.error(error) // 4xx / rate-limit surfacés proprement
+```
+
+Le nom de canal est préfixé par le projet automatiquement s'il ne l'est pas déjà.
+
+### Canaux privés (`setAuth`)
+
+Les canaux privés (`{ private: true }`) sont autorisés par les policies RLS côté serveur à
+partir du JWT courant. Fixez/rafraîchissez ce token via `setAuth()` **avant** de vous abonner :
+
+```ts
+// Utilise le token fourni (ou, sans argument, reprend client.authStore.token).
+aura.realtime.setAuth(session.access_token)
+
+const secret = aura.realtime
+  .channel('secret-room', { private: true })
+  .on('broadcast', { event: 'msg' }, console.log)
+  .subscribe((status, err) => {
+    if (status === 'CHANNEL_ERROR') console.error('Refusé par la policy RLS', err)
+  })
+```
+
+`setAuth()` propage `{ type: 'access_token' }` sur une connexion ouverte (dédupliqué, sans
+reconnexion). Un token non autorisé par la policy provoque un `CHANNEL_ERROR` à la souscription.
+
+### Presence
+
+```ts
+const lobby = aura.channel('room-1', { config: { presence: { key: 'user-1' } } })
+
+lobby
+  .on('presence', { event: 'sync' }, () => {
+    console.log(lobby.presenceState())
+  })
+  .on('presence', { event: 'join' }, console.log)
+  .on('presence', { event: 'leave' }, console.log)
+  .subscribe()
+
+await lobby.track({ online_at: new Date().toISOString() })
+await lobby.untrack()
+```
+
+### Nettoyage
+
+```ts
+aura.realtime.getChannels()
+aura.realtime.removeChannel('room-1')
+aura.realtime.removeAllChannels()
+aura.realtime.disconnect()
+unsubscribe()
+```
+
+## Limitations
+
+- Pas de limitation de débit configurable (`eventsPerSecond`) sur le broadcast (côté client).
+- La reconnexion réabonne les channels existants mais ne garantit pas la livraison des événements manqués pendant la coupure (au-delà du rejeu par `since_id` quand le serveur le supporte).
+
+## Documentation
+
+Référence complète du SDK (tous les services, types partagés, SSR) : [README racine](../../README.md).