@aurabase/aurabase-js 0.3.0

package/packages/realtime/dist/index.js

@@ -0,0 +1,973 @@
+import { fetchWithAuth } from '@aurabase/core';
+
+// src/RealtimeService.ts
+
+// src/columnFilter.ts
+var VALID_OPS = /* @__PURE__ */ new Set([
+  "eq",
+  "neq",
+  "lt",
+  "lte",
+  "gt",
+  "gte",
+  "in",
+  "like",
+  "ilike",
+  "is",
+  "match",
+  "imatch",
+  "isdistinct"
+]);
+var MAX_REGEX_PATTERN_LEN = 512;
+var MAX_IN_VALUES = 100;
+function parseColumnFilter(filterStr) {
+  const eqIdx = filterStr.indexOf("=");
+  if (eqIdx === -1) return null;
+  const column = filterStr.slice(0, eqIdx);
+  if (!column) return null;
+  let rest = filterStr.slice(eqIdx + 1);
+  let negated = false;
+  if (rest.startsWith("not.")) {
+    negated = true;
+    rest = rest.slice(4);
+  }
+  const dotIdx = rest.indexOf(".");
+  if (dotIdx === -1) return null;
+  const opStr = rest.slice(0, dotIdx);
+  let value = rest.slice(dotIdx + 1);
+  if (!VALID_OPS.has(opStr)) return null;
+  const op = opStr;
+  if (op === "in") {
+    const stripped = value.replace(/^\(+/, "").replace(/\)+$/, "");
+    if (stripped.split(",").length > MAX_IN_VALUES) return null;
+    value = stripped;
+  } else if (op === "is") {
+    if (value !== "null" && value !== "true" && value !== "false") return null;
+  } else if (op === "match" || op === "imatch") {
+    if (value.length > MAX_REGEX_PATTERN_LEN) return null;
+    try {
+      new RegExp(value, op === "imatch" ? "i" : void 0);
+    } catch {
+      return null;
+    }
+  }
+  return { column, op, value, negated };
+}
+function splitTopLevel(s) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "(") depth += 1;
+    else if (c === ")") depth = Math.max(0, depth - 1);
+    else if (c === "," && depth === 0) {
+      parts.push(s.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(s.slice(start));
+  return parts;
+}
+function parseFilterSet(s) {
+  const parts = splitTopLevel(s);
+  const out = [];
+  for (const part of parts) {
+    const cf = parseColumnFilter(part.trim());
+    if (!cf) return null;
+    out.push(cf);
+  }
+  return out;
+}
+function jsonValueToString(field) {
+  if (typeof field === "string") return field;
+  if (typeof field === "number" || typeof field === "boolean") return String(field);
+  if (field === null) return "null";
+  try {
+    return JSON.stringify(field) ?? "";
+  } catch {
+    return "";
+  }
+}
+function parseStrictNumber(s) {
+  if (s.trim() === "") return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+}
+function compareNumeric(a, b, cmp) {
+  const an = parseStrictNumber(a);
+  const bn = parseStrictNumber(b);
+  if (an === null || bn === null) return false;
+  return cmp(an, bn);
+}
+function likeToRegExp(pattern, caseInsensitive) {
+  let re = "^";
+  for (const ch of pattern) {
+    if (ch === "%") re += ".*";
+    else if (ch === "_") re += ".";
+    else re += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  re += "$";
+  try {
+    return new RegExp(re, caseInsensitive ? "i" : void 0);
+  } catch {
+    return null;
+  }
+}
+function matchesRaw(cf, record) {
+  if (cf.op === "is") {
+    const field2 = record[cf.column];
+    switch (cf.value) {
+      case "null":
+        return field2 === void 0 || field2 === null;
+      case "true":
+        return field2 === true;
+      case "false":
+        return field2 === false;
+      default:
+        return false;
+    }
+  }
+  if (cf.op === "isdistinct") {
+    const field2 = record[cf.column];
+    const fieldIsNull = field2 === void 0 || field2 === null;
+    if (fieldIsNull) return true;
+    return jsonValueToString(field2) !== cf.value;
+  }
+  if (!(cf.column in record) || record[cf.column] === void 0) return null;
+  const field = record[cf.column];
+  const fieldStr = jsonValueToString(field);
+  switch (cf.op) {
+    case "eq":
+      return fieldStr === cf.value;
+    case "neq":
+      return fieldStr !== cf.value;
+    case "lt":
+      return compareNumeric(fieldStr, cf.value, (a, b) => a < b);
+    case "lte":
+      return compareNumeric(fieldStr, cf.value, (a, b) => a <= b);
+    case "gt":
+      return compareNumeric(fieldStr, cf.value, (a, b) => a > b);
+    case "gte":
+      return compareNumeric(fieldStr, cf.value, (a, b) => a >= b);
+    case "in":
+      return cf.value.split(",").map((v) => v.trim()).some((v) => v === fieldStr);
+    case "like": {
+      const re = likeToRegExp(cf.value, false);
+      return re ? re.test(fieldStr) : null;
+    }
+    case "ilike": {
+      const re = likeToRegExp(cf.value, true);
+      return re ? re.test(fieldStr) : null;
+    }
+    case "match": {
+      try {
+        return new RegExp(cf.value).test(fieldStr);
+      } catch {
+        return null;
+      }
+    }
+    case "imatch": {
+      try {
+        return new RegExp(cf.value, "i").test(fieldStr);
+      } catch {
+        return null;
+      }
+    }
+    default:
+      return null;
+  }
+}
+function matchesSingle(cf, record) {
+  const raw = matchesRaw(cf, record);
+  if (raw === null) return false;
+  return cf.negated ? !raw : raw;
+}
+function matchesColumnFilter(filter, record) {
+  const set = parseFilterSet(filter);
+  if (!set) return false;
+  return set.every((cf) => matchesSingle(cf, record));
+}
+
+// src/AuraChannel.ts
+var AuraChannel = class {
+  name;
+  _projectId;
+  _listeners = [];
+  _subscribed = false;
+  _sendFn = null;
+  _subscribeCallback = null;
+  _presenceState = {};
+  _isPrivate = false;
+  _broadcastAck = false;
+  _broadcastSelf = false;
+  _presenceKey = "";
+  /** ID de subscription retourné par le serveur (utilisé pour le filtre RLS allowed_sub_ids) */
+  _subscriptionId = null;
+  /** Compteur pour générer des ref_id uniques par connexion */
+  _refCounter = 0;
+  /** Dernier event ID recu — utilise pour since_id au reconnect */
+  _lastEventId = null;
+  /** Pending ACK callbacks : ref_id → resolve */
+  _pendingAcks = /* @__PURE__ */ new Map();
+  constructor(name, projectId, 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 ?? "";
+  }
+  /** Génère un ref_id unique pour la corrélation request/response. */
+  _nextRef() {
+    return `${this.fullName}:r${++this._refCounter}`;
+  }
+  /** Full channel name with project prefix (for server protocol) */
+  get fullName() {
+    return `${this._projectId}:${this.name}`;
+  }
+  on(type, filter, callback) {
+    this._listeners.push({ type, filter, callback });
+    return this;
+  }
+  // ─── Subscribe ──────────────────────────────────────────────────────────
+  /**
+   * Subscribe to the channel. Sends the Subscribe message to the server
+   * with the full config (postgres_changes, broadcast, presence).
+   */
+  subscribe(callback) {
+    this._subscribeCallback = callback ?? null;
+    this._subscribed = true;
+    if (this._sendFn) {
+      this._doSubscribe();
+    }
+    return this;
+  }
+  /** Called by RealtimeService once the WS connection is ready. */
+  _bindSend(sendFn) {
+    this._sendFn = sendFn;
+  }
+  /** Send the subscribe message to the server. */
+  _doSubscribe() {
+    if (!this._sendFn) return;
+    const pgFilters = this._listeners.filter((l) => l.type === "postgres_changes").map((l) => l.filter);
+    const msg = {
+      type: "subscribe",
+      channel: this.fullName,
+      ref_id: this._nextRef(),
+      since_id: this._lastEventId ?? void 0,
+      config: {
+        postgres_changes: pgFilters,
+        broadcast: {
+          self_broadcast: this._broadcastSelf,
+          // ← depuis les options du channel
+          ack: this._broadcastAck
+          // ← depuis les options du channel
+        },
+        presence: { key: this._presenceKey },
+        // ← depuis les options du channel
+        private: this._isPrivate
+      }
+    };
+    this._sendFn(JSON.stringify(msg));
+  }
+  /** Unsubscribe from the channel. */
+  unsubscribe() {
+    if (this._sendFn) {
+      this._sendFn(JSON.stringify({ type: "unsubscribe", channel: this.fullName }));
+    }
+    this._subscribed = false;
+    this._listeners.length = 0;
+    this._presenceState = {};
+  }
+  // ─── Broadcast ──────────────────────────────────────────────────────────
+  /**
+   * Send a broadcast message to the channel.
+   * If broadcast.ack=true, returns a Promise that resolves when the server ACKs.
+   *
+   * @example
+   * ```ts
+   * // Without 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 } })
+   * ```
+   */
+  send(message) {
+    return new Promise((resolve) => {
+      if (!this._sendFn) {
+        resolve("error");
+        return;
+      }
+      const ref_id = message.ref_id ?? this._nextRef();
+      if (this._broadcastAck) {
+        const timer = setTimeout(() => {
+          this._pendingAcks.delete(ref_id);
+          resolve("timeout");
+        }, 5e3);
+        this._pendingAcks.set(ref_id, () => {
+          clearTimeout(timer);
+          resolve("ok");
+        });
+      } else {
+        resolve("ok");
+      }
+      this._sendFn(
+        JSON.stringify({
+          type: "broadcast",
+          channel: this.fullName,
+          ref_id,
+          payload: { event: message.event, ...message.payload }
+        })
+      );
+    });
+  }
+  // ─── Presence ───────────────────────────────────────────────────────────
+  /**
+   * Track presence state for this client.
+   * Returns a Promise that resolves with 'ok' once tracked (compatible Supabase).
+   *
+   * @example
+   * ```ts
+   * 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";
+  }
+  /** Stop tracking presence. */
+  async untrack() {
+    return this.track({});
+  }
+  /** Get the current presence state for this channel. */
+  presenceState() {
+    return { ...this._presenceState };
+  }
+  // ─── Internal: dispatch server messages ──────────────────────────────────
+  /** Called by RealtimeService when a server message arrives for this channel. */
+  _onMessage(msg) {
+    switch (msg.type) {
+      case "subscribed": {
+        const subMsg = msg;
+        if (subMsg.subscription_id) this._subscriptionId = subMsg.subscription_id;
+        this._subscribeCallback?.("SUBSCRIBED");
+        break;
+      }
+      case "event": {
+        const evtMsg = msg;
+        if (evtMsg.id) {
+          const event = {
+            id: evtMsg.id,
+            event: evtMsg.event,
+            topic: evtMsg.topic,
+            payload: evtMsg.payload,
+            timestamp: evtMsg.timestamp,
+            allowed_sub_ids: evtMsg.allowed_sub_ids
+          };
+          this._dispatchEvent(event);
+        }
+        break;
+      }
+      case "presence_state": {
+        const presMsg = msg;
+        if (presMsg.presences) {
+          this._presenceState = {};
+          for (const p of presMsg.presences) {
+            const key = p.user_id || p.client_id;
+            if (!this._presenceState[key]) this._presenceState[key] = [];
+            this._presenceState[key].push(p);
+          }
+          for (const l of this._listeners) {
+            if (l.type === "presence" && l.filter.event === "sync") {
+              l.callback(this._presenceState);
+            }
+          }
+        }
+        break;
+      }
+      case "error": {
+        const errMsg = msg;
+        this._subscribeCallback?.("CHANNEL_ERROR", new Error(errMsg.message ?? "Unknown error"));
+        break;
+      }
+      case "token_refreshed":
+        break;
+      case "broadcast_ack": {
+        const ackMsg = msg;
+        const refId = ackMsg.ref_id ?? ackMsg.message_id;
+        if (refId) {
+          const resolve = this._pendingAcks.get(refId);
+          if (resolve) {
+            this._pendingAcks.delete(refId);
+            resolve();
+          }
+        }
+        break;
+      }
+    }
+  }
+  /** Dispatch a RealtimeEvent to matching listeners. */
+  _dispatchEvent(event) {
+    if (!event) return;
+    if (event.id) this._lastEventId = event.id;
+    const allowed = event.allowed_sub_ids;
+    if (allowed && this._subscriptionId && !allowed.includes(this._subscriptionId)) {
+      return;
+    }
+    const eventType = event.event;
+    if (eventType === "presence") {
+      const payload = event.payload;
+      const action = payload.action;
+      const key = payload.user_id || payload.client_id;
+      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,
+            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];
+        }
+      } 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);
+          }
+        } else {
+          this._presenceState[key] = [{
+            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()
+          }];
+        }
+      }
+    }
+    for (const listener of this._listeners) {
+      if (listener.type === "postgres_changes") {
+        const filter = listener.filter;
+        if (eventType === "insert" || eventType === "update" || eventType === "delete") {
+          const filterEvent = filter.event.toLowerCase();
+          if (filterEvent === "*" || filterEvent === eventType) {
+            const payload = event.payload;
+            if (filter.schema && payload.schema !== filter.schema) continue;
+            if (filter.table && payload.table !== filter.table) continue;
+            if (filter.filter) {
+              const target = eventType === "delete" ? payload.old_record : payload.record;
+              if (target && typeof target === "object") {
+                if (!matchesColumnFilter(filter.filter, target)) {
+                  continue;
+                }
+              }
+            }
+            listener.callback(event);
+          }
+        }
+      } else if (listener.type === "broadcast") {
+        if (eventType === "broadcast") {
+          const filter = listener.filter;
+          const payload = event.payload;
+          if (!filter.event || payload.event === filter.event) {
+            listener.callback(event);
+          }
+        }
+      } else if (listener.type === "presence") {
+        if (eventType === "presence") {
+          const filter = listener.filter;
+          const payload = event.payload;
+          const action = payload.action;
+          if (filter.event === "join" && action === "join") {
+            listener.callback({
+              key: payload.user_id || payload.client_id,
+              newPresences: [payload]
+            });
+          } else if (filter.event === "leave" && action === "leave") {
+            listener.callback({
+              key: payload.user_id || payload.client_id,
+              leftPresences: [payload]
+            });
+          } else if (filter.event === "sync") {
+            listener.callback(this.presenceState());
+          }
+        }
+      }
+    }
+  }
+  /** Whether this channel has been subscribed. */
+  get isSubscribed() {
+    return this._subscribed;
+  }
+  /** Get listeners (for re-subscribe after reconnect). */
+  _getListeners() {
+    return this._listeners;
+  }
+};
+
+// src/HeartbeatManager.ts
+var HeartbeatManager = class {
+  _worker = null;
+  _workerUrl = null;
+  _interval = null;
+  _sendFn = null;
+  start(sendPing, intervalMs = 25e3) {
+    this.stop();
+    this._sendFn = sendPing;
+    if (typeof Worker !== "undefined" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function") {
+      try {
+        const code = `let i=null;onmessage=(e)=>{if(e.data.type==='start'){if(i)clearInterval(i);i=setInterval(()=>postMessage('ping'),e.data.interval||25000);}else if(e.data.type==='stop'){if(i){clearInterval(i);i=null;}}};`;
+        const blob = new Blob([code], { type: "application/javascript" });
+        this._workerUrl = URL.createObjectURL(blob);
+        this._worker = new Worker(this._workerUrl);
+        this._worker.onmessage = () => {
+          this._sendFn?.();
+        };
+        this._worker.postMessage({ type: "start", interval: intervalMs });
+        return;
+      } catch {
+        this._worker = null;
+        if (this._workerUrl) {
+          try {
+            URL.revokeObjectURL(this._workerUrl);
+          } catch {
+          }
+          this._workerUrl = null;
+        }
+      }
+    }
+    this._interval = setInterval(() => {
+      this._sendFn?.();
+    }, intervalMs);
+  }
+  stop() {
+    if (this._worker) {
+      try {
+        this._worker.postMessage({ type: "stop" });
+        this._worker.terminate();
+      } catch {
+      }
+      this._worker = null;
+    }
+    if (this._workerUrl) {
+      try {
+        URL.revokeObjectURL(this._workerUrl);
+      } catch {
+      }
+      this._workerUrl = null;
+    }
+    if (this._interval) {
+      clearInterval(this._interval);
+      this._interval = null;
+    }
+    this._sendFn = null;
+  }
+  get isActive() {
+    return this._worker !== null || this._interval !== null;
+  }
+};
+
+// src/RealtimeService.ts
+var RealtimeService = class _RealtimeService {
+  client;
+  _ws = null;
+  _channels = /* @__PURE__ */ new Map();
+  _state = "disconnected";
+  _stateListeners = /* @__PURE__ */ new Set();
+  // ─── Reconnection state ──────────────────────────────────────────────
+  _autoReconnect = true;
+  _reconnectAttempts = 0;
+  _maxReconnectAttempts = Infinity;
+  _reconnectTimer = null;
+  _intentionalClose = false;
+  _heartbeat = new HeartbeatManager();
+  _tokenRefreshTimer = null;
+  /** Dernier access_token propagé au serveur — évite les pushs redondants (propagation différentielle). */
+  _lastSentToken = null;
+  /** Backoff delays in ms: 1s, 2s, 4s, 8s, 16s, 30s (cap) */
+  static BACKOFF_MS = [1e3, 2e3, 4e3, 8e3, 16e3, 3e4];
+  constructor(client) {
+    this.client = client;
+  }
+  /** Current connection state. */
+  get connectionState() {
+    return this._state;
+  }
+  /** Listen for connection state changes. */
+  onStateChange(callback) {
+    this._stateListeners.add(callback);
+    return () => this._stateListeners.delete(callback);
+  }
+  _setState(state) {
+    this._state = state;
+    for (const cb of this._stateListeners) {
+      try {
+        cb(state);
+      } catch {
+      }
+    }
+  }
+  // ─── WebSocket URL ──────────────────────────────────────────────────────
+  get _wsUrl() {
+    const base = this.client.baseUrl.replace(/^http/, "ws");
+    return `${base}/v1/realtime/ws`;
+  }
+  // ─── Connection management ──────────────────────────────────────────────
+  /** Ensure the WebSocket connection is open. */
+  connect() {
+    if (this._ws && (this._ws.readyState === WebSocket.OPEN || this._ws.readyState === WebSocket.CONNECTING)) {
+      return;
+    }
+    this._intentionalClose = false;
+    this._setState("connecting");
+    const token = this.client.authStore.token;
+    const params = new URLSearchParams();
+    if (token) params.set("token", token);
+    if (this.client.apiKey) params.set("apikey", this.client.apiKey);
+    const url = `${this._wsUrl}?${params.toString()}`;
+    const ws = new WebSocket(url);
+    this._ws = ws;
+    ws.onopen = () => {
+      if (ws !== this._ws) {
+        try {
+          ws.close();
+        } catch {
+        }
+        return;
+      }
+      this._reconnectAttempts = 0;
+      this._setState("connected");
+      this._heartbeat.start(() => this._send(JSON.stringify({ type: "ping" })), 25e3);
+      this._scheduleTokenRefresh();
+      for (const channel of this._channels.values()) {
+        channel._bindSend((data) => this._send(data));
+        if (channel.isSubscribed) {
+          channel._doSubscribe();
+        }
+      }
+    };
+    ws.onmessage = (evt) => {
+      if (ws !== this._ws) return;
+      try {
+        const raw = typeof evt.data === "string" ? evt.data : "";
+        const msg = JSON.parse(raw);
+        this._dispatch(msg);
+      } catch (e) {
+        if (typeof console !== "undefined") {
+          console.warn("[aura-realtime] Failed to parse WS message:", evt.data, e);
+        }
+      }
+    };
+    ws.onclose = () => {
+      if (ws !== this._ws) return;
+      this._ws = null;
+      this._lastSentToken = null;
+      this._heartbeat.stop();
+      if (this._intentionalClose) {
+        this._setState("disconnected");
+        this._intentionalClose = false;
+      } else if (this._autoReconnect) {
+        this._scheduleReconnect();
+      } else {
+        this._setState("disconnected");
+      }
+    };
+    ws.onerror = (evt) => {
+      if (ws !== this._ws) return;
+      if (typeof console !== "undefined") {
+        console.warn("[aura-realtime] WebSocket error", evt);
+      }
+    };
+  }
+  /** Send raw data through the WebSocket. */
+  _send(data) {
+    if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+      this._ws.send(data);
+    }
+  }
+  /** Refresh the JWT token on an existing connection (no disconnect). */
+  refreshToken(token) {
+    if (token === this._lastSentToken) {
+      this._scheduleTokenRefresh();
+      return;
+    }
+    this._lastSentToken = token;
+    this._send(JSON.stringify({ type: "access_token", token }));
+    this._scheduleTokenRefresh();
+  }
+  /**
+   * Définit/rafraîchit explicitement le token utilisé pour l'autorisation des
+   * canaux privés et broadcast (parité `@supabase/realtime-js` `setAuth`).
+   *
+   * - Avec `token` : utilise ce token. Sinon, reprend `client.authStore.token`.
+   * - Propage via le pipeline existant `refreshToken` (push
+   *   `{ type:'access_token', token }` sur une connexion ouverte, dédupliqué via
+   *   `_lastSentToken`). N'ouvre ni ne ferme aucune connexion WS.
+   * - Hors-ligne : `connect()` lit `client.authStore.token` au moment de l'open,
+   *   donc `setAuth()` doit être appelé avec un token présent dans le store (ou
+   *   après authentification) pour prendre effet sur une future connexion.
+   *
+   * À appeler AVANT de s'abonner à un canal privé (`channel(name,{private:true})`).
+   *
+   * @example
+   * ```ts
+   * aura.realtime.setAuth(session.access_token)
+   * const ch = aura.realtime.channel('secret', { private: true }).subscribe()
+   * ```
+   */
+  setAuth(token) {
+    const resolved = token ?? this.client.authStore.token;
+    if (resolved == 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
+   * (`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).
+   * @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.
+   *
+   * @example
+   * ```ts
+   * await aura.realtime.httpBroadcast('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 body = {
+      channel: fullChannel,
+      payload: { event, ...payload }
+    };
+    return fetchWithAuth(
+      `${this.client.baseUrl}/v1/realtime/${this.client.projectId}/broadcast`,
+      { method: "POST", body },
+      this.client
+    );
+  }
+  /**
+   * Schedule proactive token refresh at 80% of the JWT TTL.
+   * Prevents token expiration during an active WebSocket session.
+   */
+  _scheduleTokenRefresh() {
+    if (this._tokenRefreshTimer) {
+      clearTimeout(this._tokenRefreshTimer);
+      this._tokenRefreshTimer = null;
+    }
+    const token = this.client.authStore.token;
+    if (!token) return;
+    try {
+      const payload = JSON.parse(atob(token.split(".")[1]));
+      const exp = payload.exp * 1e3;
+      const ttl = exp - Date.now();
+      if (ttl <= 0) return;
+      const refreshIn = ttl * 0.8;
+      this._tokenRefreshTimer = setTimeout(async () => {
+        this._tokenRefreshTimer = null;
+        try {
+          const res = await this.client.auth.refreshSession();
+          if (res.data) {
+            this.refreshToken(res.data.access_token);
+          }
+        } catch {
+        }
+      }, refreshIn);
+    } catch {
+    }
+  }
+  /** Schedule a reconnection attempt with exponential backoff + jitter. */
+  _scheduleReconnect() {
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+    if (this._reconnectAttempts >= this._maxReconnectAttempts) {
+      this._setState("disconnected");
+      return;
+    }
+    this._reconnectAttempts++;
+    this._setState("reconnecting");
+    const idx = Math.min(this._reconnectAttempts - 1, _RealtimeService.BACKOFF_MS.length - 1);
+    const baseDelay = _RealtimeService.BACKOFF_MS[idx];
+    const jitter = Math.random() * baseDelay * 0.25;
+    const delay = baseDelay + jitter;
+    this._reconnectTimer = setTimeout(() => {
+      this._reconnectTimer = null;
+      this.connect();
+    }, delay);
+  }
+  /** Enable/disable auto-reconnect (enabled by default). */
+  setAutoReconnect(enabled, maxAttempts) {
+    this._autoReconnect = enabled;
+    if (maxAttempts !== void 0) this._maxReconnectAttempts = maxAttempts;
+  }
+  /** Disconnect the WebSocket and clean up all channels. */
+  disconnect() {
+    this._intentionalClose = true;
+    this._heartbeat.stop();
+    if (this._tokenRefreshTimer) {
+      clearTimeout(this._tokenRefreshTimer);
+      this._tokenRefreshTimer = null;
+    }
+    if (this._reconnectTimer) {
+      clearTimeout(this._reconnectTimer);
+      this._reconnectTimer = null;
+    }
+    this._reconnectAttempts = 0;
+    for (const channel of this._channels.values()) {
+      channel.unsubscribe();
+    }
+    this._channels.clear();
+    if (this._ws) {
+      this._ws.close();
+      this._ws = null;
+    }
+    this._setState("disconnected");
+    this._lastSentToken = null;
+  }
+  // ─── Channel factory ────────────────────────────────────────────────────
+  /**
+   * Create or retrieve a channel by name.
+   * Returns an `AuraChannel` with chainable `.on()` / `.subscribe()` API.
+   *
+   * @example
+   * ```ts
+   * const channel = aura.realtime.channel('room-1')
+   * ```
+   */
+  channel(name, options) {
+    const existing = this._channels.get(name);
+    if (existing) return existing;
+    const ch = new AuraChannel(name, this.client.projectId, options);
+    this._channels.set(name, ch);
+    this.connect();
+    if (this._ws && this._ws.readyState === WebSocket.OPEN) {
+      ch._bindSend((data) => this._send(data));
+    }
+    return ch;
+  }
+  /** Remove a channel. */
+  removeChannel(name) {
+    const ch = this._channels.get(name);
+    if (ch) {
+      ch.unsubscribe();
+      this._channels.delete(name);
+    }
+  }
+  /** List active channels. */
+  getChannels() {
+    return Array.from(this._channels.values());
+  }
+  /** Remove all channels and subscriptions. */
+  removeAllChannels() {
+    for (const ch of this._channels.values()) {
+      ch.unsubscribe();
+    }
+    this._channels.clear();
+  }
+  // ─── Message dispatch ───────────────────────────────────────────────────
+  /** Route incoming server messages to the correct channel. */
+  _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 ch = this._channels.get(name);
+      if (ch) {
+        ch._onMessage(msg);
+        return;
+      }
+      for (const [, channel] of this._channels) {
+        if (channel.fullName === channelFull || channelFull.startsWith(channel.fullName + ":")) {
+          channel._onMessage(msg);
+          return;
+        }
+      }
+    }
+    if (msg.type === "token_refreshed") {
+      return;
+    }
+    if (msg.type === "pong") {
+      return;
+    }
+    if (msg.type === "broadcast_ack") {
+      const ack = msg;
+      const refId = ack.ref_id ?? ack.message_id;
+      if (refId) {
+        const marker = refId.lastIndexOf(":r");
+        if (marker > 0) {
+          const fullName = refId.slice(0, marker);
+          for (const ch of this._channels.values()) {
+            if (ch.fullName === fullName) {
+              ch._onMessage(msg);
+              return;
+            }
+          }
+        }
+      }
+      for (const ch of this._channels.values()) {
+        ch._onMessage(msg);
+      }
+      return;
+    }
+    if (msg.type === "error") {
+      for (const ch of this._channels.values()) {
+        ch._onMessage(msg);
+      }
+    }
+  }
+  // ─── 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)
+    };
+  }
+};
+
+export { AuraChannel, HeartbeatManager, RealtimeService };