@aurabase/realtime 0.4.1 → 0.5.1

package/dist/index.cjs

@@ -2,9 +2,28 @@
 
 var core = require('@aurabase/core');
 
-// src/RealtimeService.ts
-
 // src/columnFilter.ts
+function logicalSchema(physical) {
+  if (!physical.startsWith("project_")) return physical;
+  const rest = physical.slice("project_".length);
+  if (rest.length < 36) return physical;
+  switch (rest.slice(36)) {
+    case "":
+      return "public";
+    case "_auth":
+      return "auth";
+    case "_storage":
+      return "storage";
+    case "_platform":
+      return "platform";
+    default:
+      return physical;
+  }
+}
+function schemaMatches(filterSchema, payloadSchema) {
+  if (typeof payloadSchema !== "string") return false;
+  return filterSchema === payloadSchema || filterSchema === logicalSchema(payloadSchema);
+}
 var VALID_OPS = /* @__PURE__ */ new Set([
   "eq",
   "neq",
@@ -45,8 +64,11 @@ function parseColumnFilter(filterStr) {
     value = stripped;
   } else if (op === "is") {
     if (value !== "null" && value !== "true" && value !== "false") return null;
+  } else if (op === "like" || op === "ilike") {
+    if (value.length > MAX_REGEX_PATTERN_LEN) return null;
   } else if (op === "match" || op === "imatch") {
     if (value.length > MAX_REGEX_PATTERN_LEN) return null;
+    if (hasCatastrophicBacktrackingRisk(value)) return null;
     try {
       new RegExp(value, op === "imatch" ? "i" : void 0);
     } catch {
@@ -102,6 +124,12 @@ function compareNumeric(a, b, cmp) {
   if (an === null || bn === null) return false;
   return cmp(an, bn);
 }
+function hasCatastrophicBacktrackingRisk(pattern) {
+  const QUANT = "(?:[+*]|\\{\\d*,\\d*\\})";
+  if (new RegExp(`\\([^()]*${QUANT}[^()]*\\)${QUANT}`).test(pattern)) return true;
+  if (new RegExp(`\\([^()]*\\|[^()]*\\)${QUANT}`).test(pattern)) return true;
+  return false;
+}
 function likeToRegExp(pattern, caseInsensitive) {
   let re = "^";
   for (const ch of pattern) {
@@ -193,9 +221,10 @@ function matchesColumnFilter(filter, record) {
 
 // src/AuraChannel.ts
 var DEFAULT_SUBSCRIBE_TIMEOUT_MS = 1e4;
+var PERTE_D_ABONNEMENT = /Non abonné au canal|Accès révoqué au channel/;
 var AuraChannel = class {
   name;
-  _projectId;
+  _projectPrefix;
   _listeners = [];
   _subscribed = false;
   _sendFn = null;
@@ -211,8 +240,18 @@ var AuraChannel = class {
   _refCounter = 0;
   /** Dernier event ID recu — utilise pour since_id au reconnect */
   _lastEventId = null;
-  /** Pending ACK callbacks : ref_id → resolve */
+  /** Pending ACK callbacks : ref_id → solde la promesse de `send()` avec un statut. */
   _pendingAcks = /* @__PURE__ */ new Map();
+  /**
+   * Abonnement vu par le SERVEUR — à ne pas confondre avec `_subscribed`, qui n'est que
+   * l'INTENTION de l'appelant (et pilote le re-subscribe après reconnexion).
+   *
+   * C18 (rejeu) : `_subscribed` était posé optimistement par `subscribe()` et n'était
+   * jamais infirmé quand le serveur REFUSAIT l'abonnement. `send({ ack })` armait alors un
+   * compte à rebours de 5 s pour un accusé structurellement impossible — mesuré sur le banc
+   * à 5 065 ms, alors que le serveur avait répondu en 6 ms « Non abonné au canal … ».
+   */
+  _serverState = "pending";
   /**
    * Timer d'attente de la confirmation `subscribed`. Armé à l'ENVOI effectif du
    * message subscribe (parité phoenix : `Push#startTimeout` ne démarre qu'au
@@ -223,13 +262,22 @@ var AuraChannel = class {
   _subscribeTimeoutMs = DEFAULT_SUBSCRIBE_TIMEOUT_MS;
   /** `CLOSED` n'est émis qu'une fois par cycle de vie du canal (unsubscribe idempotent). */
   _closedEmitted = false;
-  constructor(name, projectId, options) {
+  /**
+   * @param projectPrefix Préfixe de projet du canal sur le fil (`"<project_id>:"`, ou `""`
+   *   s'il est inconnu), résolu PARESSEUSEMENT : le SDK ne connaît le projet qu'à travers
+   *   le token de session, qui peut arriver après la création du canal (connexion
+   *   différée). Une valeur figée à la construction serait alors périmée pour toujours,
+   *   le canal étant mémorisé par `RealtimeService`.
+   */
+  constructor(name, projectPrefix, options) {
     this.name = name;
-    this._projectId = projectId;
-    this._isPrivate = options?.private ?? false;
-    this._broadcastAck = options?.broadcast?.ack ?? false;
-    this._broadcastSelf = options?.broadcast?.self ?? false;
-    this._presenceKey = options?.config?.presence?.key ?? "";
+    this._projectPrefix = projectPrefix;
+    const bcast = options?.broadcast ?? options?.config?.broadcast;
+    const pres = options?.presence ?? options?.config?.presence;
+    this._isPrivate = Boolean(options?.private ?? options?.config?.private ?? false);
+    this._broadcastAck = Boolean(bcast?.ack ?? false);
+    this._broadcastSelf = Boolean(bcast?.self ?? false);
+    this._presenceKey = typeof pres?.key === "string" ? pres.key : "";
   }
   /** Génère un ref_id unique pour la corrélation request/response. */
   _nextRef() {
@@ -237,7 +285,7 @@ var AuraChannel = class {
   }
   /** Full channel name with project prefix (for server protocol) */
   get fullName() {
-    return `${this._projectId}:${this.name}`;
+    return `${this._projectPrefix()}${this.name}`;
   }
   on(type, filter, callback) {
     this._listeners.push({ type, filter, callback });
@@ -262,6 +310,7 @@ var AuraChannel = class {
   subscribe(callback, timeoutMs) {
     this._subscribeCallback = callback ?? null;
     this._subscribed = true;
+    this._serverState = "pending";
     this._closedEmitted = false;
     if (typeof timeoutMs === "number" && timeoutMs > 0) {
       this._subscribeTimeoutMs = timeoutMs;
@@ -297,6 +346,7 @@ var AuraChannel = class {
         private: this._isPrivate
       }
     };
+    this._serverState = "pending";
     this._sendFn(JSON.stringify(msg));
     this._armSubscribeTimeout();
   }
@@ -367,45 +417,84 @@ var AuraChannel = class {
   }
   // ─── Broadcast ──────────────────────────────────────────────────────────
   /**
-   * Send a broadcast message to the channel.
-   * If broadcast.ack=true, returns a Promise that resolves when the server ACKs.
+   * Envoie un message broadcast sur le canal.
+   *
+   * Avec `broadcast: { ack: true }`, la promesse ne se résout qu'à l'accusé de réception du
+   * serveur (`broadcast_ack`) ; sans `ack`, elle se résout dès la remise au transport.
+   *
+   * Le statut rendu nomme sa CAUSE — voir {@link BroadcastSendStatus} :
+   * `'ok'`, `'timeout'`, `'not_connected'`, `'requires_subscription'`, `'error'`.
+   *
+   * **`'requires_subscription'`** signifie que le serveur n'a pas d'abonnement pour ce canal
+   * — soit `.subscribe()` n'a jamais été appelé, soit le serveur l'a REFUSÉ (RLS,
+   * `private_only`, quota) ou révoqué depuis. Rien n'est émis dans ce cas : le serveur
+   * rejetterait l'écriture (`Non abonné au canal '…' — Subscribe requis avant Broadcast`).
    *
    * @example
    * ```ts
-   * // Without ACK (fire & forget)
+   * // Sans ACK (fire & forget)
    * channel.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100, y: 200 } })
    *
-   * // With ACK (wait for server confirmation)
-   * await channel.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100 } })
+   * // Avec ACK — le modèle est celui de Supabase : on écrit APRÈS SUBSCRIBED.
+   * channel.subscribe(async (statut) => {
+   *   if (statut !== 'SUBSCRIBED') return // CHANNEL_ERROR = le serveur a refusé ce canal
+   *   const status = await channel.send({ type: 'broadcast', event: 'cursor-pos', payload: { x: 100 } })
+   *   if (status === 'requires_subscription') {
+   *     // l'abonnement a été refusé ou révoqué entre-temps ; la cause a été remontée en
+   *     // CHANNEL_ERROR à ce même callback.
+   *   }
+   * })
    * ```
    */
   send(message) {
     return new Promise((resolve) => {
       if (!this._sendFn) {
-        resolve("error");
+        resolve("not_connected");
+        return;
+      }
+      if (!this._subscribed || this._serverState === "refused") {
+        resolve("requires_subscription");
         return;
       }
       const ref_id = message.ref_id ?? this._nextRef();
-      if (this._broadcastAck) {
-        const timer = setTimeout(() => {
+      const ackExpected = this._broadcastAck;
+      let ackTimer = null;
+      if (ackExpected) {
+        ackTimer = setTimeout(() => {
           this._pendingAcks.delete(ref_id);
           resolve("timeout");
         }, 5e3);
-        this._pendingAcks.set(ref_id, () => {
-          clearTimeout(timer);
-          resolve("ok");
+        this._pendingAcks.set(ref_id, (status) => {
+          if (ackTimer) clearTimeout(ackTimer);
+          resolve(status);
         });
-      } else {
-        resolve("ok");
       }
-      this._sendFn(
-        JSON.stringify({
-          type: "broadcast",
-          channel: this.fullName,
-          ref_id,
-          payload: { event: message.event, ...message.payload }
-        })
-      );
+      const cancelAck = () => {
+        if (ackTimer) clearTimeout(ackTimer);
+        this._pendingAcks.delete(ref_id);
+      };
+      let delivered;
+      try {
+        delivered = this._sendFn(
+          JSON.stringify({
+            type: "broadcast",
+            channel: this.fullName,
+            ref_id,
+            payload: { event: message.event, ...message.payload }
+          })
+        ) !== false;
+      } catch {
+        cancelAck();
+        resolve("error");
+        return;
+      }
+      if (!delivered) {
+        cancelAck();
+        resolve("not_connected");
+        return;
+      }
+      if (ackExpected) return;
+      resolve("ok");
     });
   }
   // ─── Presence ───────────────────────────────────────────────────────────
@@ -418,19 +507,25 @@ var AuraChannel = class {
    * await channel.track({ user: 'user-1', online_at: new Date().toISOString() })
    * ```
    */
-  async track(state) {
-    if (!this._sendFn) return "error";
-    this._sendFn(
-      JSON.stringify({
-        type: "presence_update",
-        channel: this.fullName,
-        meta: state
-      })
-    );
-    return "ok";
+  track(state) {
+    if (!this._sendFn) return Promise.resolve("error");
+    if (!this._subscribed || this._serverState === "refused") return Promise.resolve("error");
+    try {
+      const delivered = this._sendFn(
+        JSON.stringify({
+          type: "presence_update",
+          channel: this.fullName,
+          meta: state
+        })
+      ) !== false;
+      if (!delivered) return Promise.resolve("error");
+    } catch {
+      return Promise.resolve("error");
+    }
+    return Promise.resolve("ok");
   }
-  /** Stop tracking presence. */
-  async untrack() {
+  /** Stop tracking presence. Même contrat que `track()`. */
+  untrack() {
     return this.track({});
   }
   /** Get the current presence state for this channel. */
@@ -444,6 +539,7 @@ var AuraChannel = class {
       case "subscribed": {
         const subMsg = msg;
         if (subMsg.subscription_id) this._subscriptionId = subMsg.subscription_id;
+        this._serverState = "subscribed";
         this._clearSubscribeTimeout();
         this._emitStatus("SUBSCRIBED");
         break;
@@ -483,8 +579,18 @@ var AuraChannel = class {
       }
       case "error": {
         const errMsg = msg;
+        const errChannel = errMsg.channel;
+        if (errChannel && errChannel !== this.fullName && errChannel !== this.name) {
+          break;
+        }
         this._clearSubscribeTimeout();
         this._emitStatus("CHANNEL_ERROR", new Error(errMsg.message ?? "Unknown error"));
+        const nommeCeCanal = errChannel !== void 0;
+        const perteDAbonnement = nommeCeCanal && (this._serverState !== "subscribed" || PERTE_D_ABONNEMENT.test(errMsg.message ?? ""));
+        if (perteDAbonnement) {
+          this._serverState = "refused";
+          this._settlePendingAcks("requires_subscription");
+        }
         break;
       }
       case "token_refreshed":
@@ -493,16 +599,29 @@ var AuraChannel = class {
         const ackMsg = msg;
         const refId = ackMsg.ref_id ?? ackMsg.message_id;
         if (refId) {
-          const resolve = this._pendingAcks.get(refId);
-          if (resolve) {
+          const settle = this._pendingAcks.get(refId);
+          if (settle) {
             this._pendingAcks.delete(refId);
-            resolve();
+            settle("ok");
           }
         }
         break;
       }
     }
   }
+  /**
+   * Solde TOUS les accusés en attente de ce canal avec un statut donné.
+   *
+   * Le protocole ne corrèle pas l'erreur serveur au `ref_id` de l'écriture refusée : quand
+   * le serveur déclare n'avoir aucun abonnement pour ce canal, AUCUN accusé en vol ne peut
+   * plus aboutir — les solder tous est donc exact, pas approximatif.
+   */
+  _settlePendingAcks(status) {
+    if (this._pendingAcks.size === 0) return;
+    const settlers = Array.from(this._pendingAcks.values());
+    this._pendingAcks.clear();
+    for (const settle of settlers) settle(status);
+  }
   /** Dispatch a RealtimeEvent to matching listeners. */
   _dispatchEvent(event) {
     if (!event) return;
@@ -515,51 +634,49 @@ var AuraChannel = class {
     if (eventType === "presence") {
       const payload = event.payload;
       const action = payload.action;
-      const key = payload.user_id || payload.client_id;
+      const clientId = payload.client_id;
+      const locate = () => {
+        for (const [key, arr] of Object.entries(this._presenceState)) {
+          const index = arr.findIndex((p) => p.client_id === clientId);
+          if (index >= 0) return { key, index };
+        }
+        return null;
+      };
       if (action === "join") {
-        if (!this._presenceState[key]) this._presenceState[key] = [];
-        if (!this._presenceState[key].some((p) => p.client_id === payload.client_id)) {
-          const presenceInfo = {
-            client_id: payload.client_id,
+        const key = payload.user_id || clientId;
+        if (!locate()) {
+          if (!this._presenceState[key]) this._presenceState[key] = [];
+          this._presenceState[key].push({
+            client_id: clientId,
             user_id: payload.user_id ?? void 0,
             metadata: payload.metadata ?? payload.meta ?? {},
             joined_at: (/* @__PURE__ */ new Date()).toISOString(),
             last_seen: (/* @__PURE__ */ new Date()).toISOString()
-          };
-          this._presenceState[key].push(presenceInfo);
+          });
         }
       } else if (action === "leave") {
-        const arr = this._presenceState[key];
-        if (arr) {
-          const idx = arr.findIndex((p) => p.client_id === payload.client_id);
-          if (idx >= 0) arr.splice(idx, 1);
-          if (arr.length === 0) delete this._presenceState[key];
+        const found = locate();
+        if (found) {
+          const arr = this._presenceState[found.key];
+          arr.splice(found.index, 1);
+          if (arr.length === 0) delete this._presenceState[found.key];
         }
       } else if (action === "update") {
-        const arr = this._presenceState[key];
-        if (arr) {
-          const idx = arr.findIndex((p) => p.client_id === payload.client_id);
-          if (idx >= 0) {
-            arr[idx].metadata = payload.metadata ?? payload.meta ?? {};
-            arr[idx].last_seen = (/* @__PURE__ */ new Date()).toISOString();
-          } else {
-            const presenceInfo = {
-              client_id: payload.client_id,
-              user_id: payload.user_id ?? void 0,
-              metadata: payload.metadata ?? payload.meta ?? {},
-              joined_at: (/* @__PURE__ */ new Date()).toISOString(),
-              last_seen: (/* @__PURE__ */ new Date()).toISOString()
-            };
-            this._presenceState[key].push(presenceInfo);
-          }
+        const found = locate();
+        if (found) {
+          const entry = this._presenceState[found.key][found.index];
+          entry.metadata = payload.metadata ?? payload.meta ?? {};
+          entry.last_seen = (/* @__PURE__ */ new Date()).toISOString();
         } else {
-          this._presenceState[key] = [{
-            client_id: payload.client_id,
+          const key = payload.user_id || clientId;
+          if (!this._presenceState[key]) this._presenceState[key] = [];
+          this._presenceState[key].push({
+            client_id: clientId,
             user_id: payload.user_id ?? void 0,
             metadata: payload.metadata ?? payload.meta ?? {},
             joined_at: (/* @__PURE__ */ new Date()).toISOString(),
             last_seen: (/* @__PURE__ */ new Date()).toISOString()
-          }];
+          });
         }
       }
     }
@@ -570,7 +687,7 @@ var AuraChannel = class {
           const filterEvent = filter.event.toLowerCase();
           if (filterEvent === "*" || filterEvent === eventType) {
             const payload = event.payload;
-            if (filter.schema && payload.schema !== filter.schema) continue;
+            if (filter.schema && !schemaMatches(filter.schema, payload.schema)) continue;
             if (filter.table && payload.table !== filter.table) continue;
             if (filter.filter) {
               const target = eventType === "delete" ? payload.old_record : payload.record;
@@ -580,14 +697,32 @@ var AuraChannel = class {
                 }
               }
             }
-            listener.callback(event);
+            const cdcPayload = payload && typeof payload === "object" ? payload : {};
+            if (cdcPayload.new === void 0 && cdcPayload.record !== void 0) {
+              cdcPayload.new = cdcPayload.record;
+            }
+            if (cdcPayload.old === void 0 && cdcPayload.old_record !== void 0) {
+              cdcPayload.old = cdcPayload.old_record;
+            }
+            if (cdcPayload.eventType === void 0 && cdcPayload.type !== void 0) {
+              cdcPayload.eventType = cdcPayload.type;
+            }
+            const enrichedEvent = Object.assign(Object.create(event), {
+              new: cdcPayload.record,
+              old: cdcPayload.old_record,
+              eventType: cdcPayload.type,
+              schema: cdcPayload.schema,
+              table: cdcPayload.table
+            });
+            listener.callback(enrichedEvent);
           }
         }
       } else if (listener.type === "broadcast") {
         if (eventType === "broadcast") {
           const filter = listener.filter;
-          const payload = event.payload;
-          if (!filter.event || payload.event === filter.event) {
+          const broadcastPayload = event.payload && typeof event.payload === "object" ? event.payload : void 0;
+          const broadcastEvent = broadcastPayload?.event;
+          if (!filter.event || filter.event === "*" || broadcastEvent === filter.event) {
             listener.callback(event);
           }
         }
@@ -623,6 +758,24 @@ var AuraChannel = class {
   }
 };
 
+// src/errors.ts
+var RealtimeConnectionError = class _RealtimeConnectionError extends Error {
+  /** Phase du cycle de vie où l'échec s'est produit. */
+  phase;
+  /** Code de fermeture WebSocket (RFC 6455 §7.4), si le runtime l'a fourni. */
+  code;
+  /** Raison de fermeture fournie par le serveur, si présente (souvent vide). */
+  reason;
+  constructor(phase, message, options) {
+    super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = "RealtimeConnectionError";
+    this.phase = phase;
+    this.code = options?.code;
+    this.reason = options?.reason;
+    Object.setPrototypeOf(this, _RealtimeConnectionError.prototype);
+  }
+};
+
 // src/HeartbeatManager.ts
 var HeartbeatManager = class _HeartbeatManager {
   _worker = null;
@@ -766,29 +919,17 @@ function getTokenExpiryMs(token) {
   if (typeof exp !== "number" || !Number.isFinite(exp)) return null;
   return exp * 1e3;
 }
-
-// src/errors.ts
-var RealtimeConnectionError = class _RealtimeConnectionError extends Error {
-  /** Phase du cycle de vie où l'échec s'est produit. */
-  phase;
-  /** Code de fermeture WebSocket (RFC 6455 §7.4), si le runtime l'a fourni. */
-  code;
-  /** Raison de fermeture fournie par le serveur, si présente (souvent vide). */
-  reason;
-  constructor(phase, message, options) {
-    super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
-    this.name = "RealtimeConnectionError";
-    this.phase = phase;
-    this.code = options?.code;
-    this.reason = options?.reason;
-    Object.setPrototypeOf(this, _RealtimeConnectionError.prototype);
-  }
-};
+function getTokenProjectId(token) {
+  const payload = decodeJwtPayload(token);
+  const pid = payload?.project_id;
+  return typeof pid === "string" && pid !== "" ? pid : null;
+}
 
 // src/RealtimeService.ts
 var HEARTBEAT_INTERVAL_MS = 25e3;
 var MAX_TIMEOUT_MS = 2147483647;
 var LIVENESS_GUARD_INTERVAL_MS = 3e4;
+var CANAL_QUALIFIE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}:/;
 var LIVENESS_MAX_SILENCE_MS = 9e4;
 var RealtimeService = class _RealtimeService {
   client;
@@ -806,6 +947,8 @@ var RealtimeService = class _RealtimeService {
   _tokenRefreshTimer = null;
   /** Dernier access_token propagé au serveur — évite les pushs redondants (propagation différentielle). */
   _lastSentToken = null;
+  /** Token d'authentification explicite passé à setAuth(), prioritaire sur authStore. */
+  _customAuthToken = null;
   /** Listeners d'erreurs de transport (handshake refusé, coupure, connexion morte). */
   _errorListeners = /* @__PURE__ */ new Set();
   /**
@@ -835,6 +978,10 @@ var RealtimeService = class _RealtimeService {
   get connectionState() {
     return this._state;
   }
+  /** Whether the WebSocket is currently connected. */
+  get isConnected() {
+    return this._state === "connected";
+  }
   /** Listen for connection state changes. */
   onStateChange(callback) {
     this._stateListeners.add(callback);
@@ -897,6 +1044,21 @@ var RealtimeService = class _RealtimeService {
       }
     }
   }
+  // ─── Préfixe de projet des canaux ───────────────────────────────────────
+  /**
+   * Préfixe de projet déduit du token courant (`<project_id>:`), vide si aucun token.
+   *
+   * Utilisé pour normaliser les noms de canaux : le serveur (`aura-realtime`) attend
+   * systématiquement `<project_id>:<canal>` sur le protocole WebSocket et REST, alors que
+   * l'utilisateur passe généralement un nom court (`room-1`). Sans session, aucun préfixe
+   * à préfixer ; la connexion WS échouerait de toute façon, le serveur exigeant un JWT.
+   */
+  _projectPrefix() {
+    const token = this._customAuthToken ?? this.client.authStore.token;
+    if (!token) return "";
+    const pid = getTokenProjectId(token);
+    return pid ? `${pid}:` : "";
+  }
   // ─── WebSocket URL ──────────────────────────────────────────────────────
   get _wsUrl() {
     const base = this.client.baseUrl.replace(/^http/, "ws");
@@ -910,7 +1072,7 @@ var RealtimeService = class _RealtimeService {
     }
     this._intentionalClose = false;
     this._setState("connecting");
-    const token = this.client.authStore.token;
+    const token = this._customAuthToken ?? this.client.authStore.token;
     const params = new URLSearchParams();
     if (token) params.set("token", token);
     if (this.client.apiKey) params.set("apikey", this.client.apiKey);
@@ -929,6 +1091,9 @@ var RealtimeService = class _RealtimeService {
       opened = true;
       this._reconnectAttempts = 0;
       this._setState("connected");
+      if (this._customAuthToken && this._customAuthToken !== this._lastSentToken) {
+        this.refreshToken(this._customAuthToken);
+      }
       this._awaitingPong = false;
       this._lastServerMessageAt = Date.now();
       this._heartbeat.start(() => this._heartbeatTick(ws), HEARTBEAT_INTERVAL_MS);
@@ -1106,11 +1271,21 @@ var RealtimeService = class _RealtimeService {
       this._goDisconnected();
     }
   }
-  /** Send raw data through the WebSocket. */
+  /**
+   * Send raw data through the WebSocket.
+   *
+   * @returns `true` si le message a été remis à la socket, `false` s'il a été **jeté**
+   * (socket absente ou non-OPEN). Ce retour n'est pas cosmétique : sans lui,
+   * `AuraChannel.send()`/`track()` rendaient `'ok'` pour un message qui n'avait jamais
+   * quitté le process — la seule branche de `send()` capable de rendre `'error'` était
+   * une exception que ce `_send` ne lève jamais (C18/N24).
+   */
   _send(data) {
     if (this._ws && this._ws.readyState === WebSocket.OPEN) {
       this._ws.send(data);
+      return true;
     }
+    return false;
   }
   /** Refresh the JWT token on an existing connection (no disconnect). */
   refreshToken(token) {
@@ -1144,36 +1319,83 @@ var RealtimeService = class _RealtimeService {
    */
   setAuth(token) {
     const resolved = token ?? this.client.authStore.token;
-    if (resolved == null) return;
+    this._customAuthToken = resolved ?? null;
+    if (resolved == null) {
+      this._lastSentToken = null;
+      return;
+    }
     this.refreshToken(resolved);
   }
   /**
    * Envoie un broadcast par HTTP (REST), sans connexion WebSocket ouverte
    * (parité `@supabase/realtime-js`). Utile côté serveur/edge.
    *
-   * POST `/v1/realtime/{projectId}/broadcast` avec le contrat du handler backend
+   * POST `/v1/realtime/broadcast` avec le contrat du handler backend
    * (`broadcast.rs`) : `{ channel, payload }`, `channel` préfixé par le projet,
    * `event` replié dans `payload` (aligné sur le broadcast WS).
    *
-   * @param channel Nom du canal (préfixé projet automatiquement si absent).
+   * ### Le canal DOIT porter le projet — y compris hors session (K2)
+   *
+   * Le handler exige `channel.starts_with("{project_id}:")` et répond sinon
+   * `403 « Le canal n'appartient pas à ce projet »`
+   * (`services/aura-realtime/src/handlers/broadcast.rs`, fonction `broadcast`).
+   *
+   * Avec une session, ce préfixe est ajouté ici même : il est lu dans le claim
+   * `project_id` du jeton (voir {@link _projectPrefix}).
+   *
+   * **Sans session — le cas d'usage serveur/edge de cette méthode** — le SDK n'a AUCUN
+   * identifiant de projet : l'URL est la seule désignation du tenant côté client, et rien
+   * ne la traduit en `project_id` (c'est la passerelle qui fait cette résolution, à partir
+   * de l'hôte). L'authentification, elle, passe : pour le realtime, la passerelle forge un
+   * JWT interne à partir des claims de la clé API et écrase l'`Authorization`
+   * (`aura-gateway/src/proxy/sse_proxy.rs::do_http_proxy`). Émettre un canal nu produisait
+   * donc un `403` dont le message ne nomme jamais la forme attendue.
+   *
+   * Cette méthode **refuse** désormais ce cas, sans appel réseau
+   * (`error.code === 'realtime_channel_non_qualifie'`) : passez le canal déjà qualifié,
+   * `"<project_id>:<canal>"`. Cette forme est acceptée dans les deux situations — avec une
+   * session, elle n'est pas préfixée une seconde fois.
+   *
+   * @param channel Nom du canal. Avec une session : nom nu ou déjà qualifié. Sans session :
+   *                OBLIGATOIREMENT `"<project_id>:<canal>"`.
    * @param event   Nom de l'événement broadcast.
    * @param payload Données de l'événement.
-   * @returns `AuraResponse<null>` — `error` non nul en cas de 4xx/rate-limit.
+   * @returns `AuraResponse<null>` — `error` non nul en cas de 4xx/rate-limit, ou de canal
+   *          non qualifiable (refus local, aucun appel réseau).
    *
    * @example
    * ```ts
+   * // Navigateur, utilisateur connecté : le projet vient du jeton de session.
    * await aura.realtime.httpBroadcast('room-1', 'cursor', { x: 10, y: 20 })
+   *
+   * // Serveur / edge (clé service_role, aucune session) : qualifier le canal.
+   * await aura.realtime.httpBroadcast(`${PROJECT_ID}:room-1`, 'cursor', { x: 10, y: 20 })
    * ```
    */
   httpBroadcast(channel, event, payload = {}) {
-    const prefix = `${this.client.projectId}:`;
-    const fullChannel = channel.startsWith(prefix) ? channel : `${prefix}${channel}`;
+    const prefix = this._projectPrefix();
+    let fullChannel;
+    if (prefix) {
+      fullChannel = channel.startsWith(prefix) ? channel : `${prefix}${channel}`;
+    } else if (CANAL_QUALIFIE.test(channel)) {
+      fullChannel = channel;
+    } else {
+      return Promise.resolve({
+        data: null,
+        error: new core.AuraError(0, {
+          error: {
+            code: "realtime_channel_non_qualifie",
+            message: `httpBroadcast: le canal "${channel}" n'est pas qualifi\xE9 et aucune session n'est ouverte \u2014 le SDK n'a donc aucun \`project_id\` \xE0 lui pr\xE9fixer, alors que le serveur l'EXIGE (403 \xAB Le canal n'appartient pas \xE0 ce projet \xBB). Passez le canal sous la forme "<project_id>:` + channel + `" \u2014 c'est la forme attendue c\xF4t\xE9 serveur/edge, o\xF9 il n'y a pas de session utilisateur.`
+          }
+        })
+      });
+    }
     const body = {
       channel: fullChannel,
       payload: { event, ...payload }
     };
     return core.fetchWithAuth(
-      `${this.client.baseUrl}/v1/realtime/${this.client.projectId}/broadcast`,
+      `${this.client.baseUrl}/v1/realtime/broadcast`,
       { method: "POST", body },
       this.client
     );
@@ -1271,7 +1493,7 @@ var RealtimeService = class _RealtimeService {
   channel(name, options) {
     const existing = this._channels.get(name);
     if (existing) return existing;
-    const ch = new AuraChannel(name, this.client.projectId, options);
+    const ch = new AuraChannel(name, () => this._projectPrefix(), options);
     this._channels.set(name, ch);
     this.connect();
     if (this._ws && this._ws.readyState === WebSocket.OPEN) {
@@ -1279,8 +1501,9 @@ var RealtimeService = class _RealtimeService {
     }
     return ch;
   }
-  /** Remove a channel. */
-  removeChannel(name) {
+  /** Remove a channel by name or by AuraChannel instance. */
+  removeChannel(channel) {
+    const name = typeof channel === "string" ? channel : channel.name;
     const ch = this._channels.get(name);
     if (ch) {
       ch.unsubscribe();
@@ -1303,19 +1526,37 @@ var RealtimeService = class _RealtimeService {
   _dispatch(msg) {
     const channelFull = "channel" in msg ? msg.channel : "topic" in msg ? msg.topic : void 0;
     if (channelFull) {
-      const prefix = `${this.client.projectId}:`;
-      const name = channelFull.startsWith(prefix) ? channelFull.slice(prefix.length) : channelFull;
+      const prefix = this._projectPrefix();
+      const name = prefix && channelFull.startsWith(prefix) ? channelFull.slice(prefix.length) : channelFull;
       const ch = this._channels.get(name);
       if (ch) {
         ch._onMessage(msg);
         return;
       }
+      if (channelFull.includes(":")) {
+        const colonIdx = channelFull.indexOf(":");
+        const relativeName = channelFull.slice(colonIdx + 1);
+        const relCh = this._channels.get(relativeName);
+        if (relCh) {
+          relCh._onMessage(msg);
+          return;
+        }
+      }
       for (const [, channel] of this._channels) {
-        if (channel.fullName === channelFull || channelFull.startsWith(channel.fullName + ":")) {
+        if (channel.fullName === channelFull || channel.name === channelFull || channelFull.startsWith(channel.fullName + ":") || channelFull.endsWith(`:${channel.name}`)) {
           channel._onMessage(msg);
           return;
         }
       }
+      if (msg.type === "error") {
+        if (typeof console !== "undefined") {
+          console.warn(
+            "[aura-realtime] Erreur serveur pour un canal inconnu de ce client \u2014 ignor\xE9e (aucun canal local concern\xE9) :",
+            { channel: channelFull, message: msg.message }
+          );
+        }
+        return;
+      }
     }
     if (msg.type === "token_refreshed") {
       return;
@@ -1349,22 +1590,6 @@ var RealtimeService = class _RealtimeService {
       }
     }
   }
-  // ─── Backward compatibility ─────────────────────────────────────────────
-  /**
-   * Simple callback-based subscription (legacy API).
-   * Prefer using `.channel().on().subscribe()` instead.
-   *
-   * @deprecated Use `channel().on().subscribe()` instead.
-   */
-  on(channelName, callback) {
-    this.connect();
-    const ch = this.channel(channelName);
-    ch.on("postgres_changes", { event: "*" }, callback);
-    ch.subscribe();
-    return {
-      unsubscribe: () => this.removeChannel(channelName)
-    };
-  }
 };
 
 exports.AuraChannel = AuraChannel;