@palbase/web 7.3.8 → 7.4.0

package/dist/internal.cjs

@@ -179,13 +179,22 @@ function wirePlatform() {
   return host === "browser" ? "web" : host;
 }
 var PALBASE_DEFAULT_HOST = "api.palbase.studio";
-var API_KEY_RE = /^pb_([a-z0-9]{4,24})_c[A-Za-z0-9]{20}$/;
+var API_KEY_RE = /^pb_([a-z0-9]{4,24})_c[A-Za-z0-9]{20,}$/;
 function parseEnvironmentRef(apiKey) {
   return API_KEY_RE.exec(apiKey)?.[1] ?? null;
 }
 var MAX_RETRIES = 3;
 var INITIAL_BACKOFF_MS = 200;
 var MAX_RETRY_DELAY_MS = 1e4;
+function withRetryHint(body, response) {
+  if (response.status !== 429) return body;
+  const data = body?.data;
+  const alreadyStated = typeof body?.retry_after === "number" || typeof data === "object" && data !== null && "retryAfter" in data;
+  if (alreadyStated) return body;
+  const seconds = Number.parseInt(response.headers.get("Retry-After") ?? "", 10);
+  if (Number.isNaN(seconds) || seconds <= 0) return body;
+  return { ...body, retry_after: seconds };
+}
 var HttpClient = class _HttpClient {
   apiKey;
   options;
@@ -255,7 +264,7 @@ var HttpClient = class _HttpClient {
     if (this.apiKey && parseEnvironmentRef(this.apiKey) === null) {
       throw new PalbaseError(
         "invalid_api_key",
-        'Invalid API key format. Expected pb_{environment_ref}_c{20_base62_chars}. For dev/staging pass `url: "https://api.dev.palbase.studio"` via options.',
+        'Invalid API key format. Expected pb_{environment_ref}_c{at least 20 base62 chars}. For dev/staging pass `url: "https://api.dev.palbase.studio"` via options.',
         0
       );
     }
@@ -361,7 +370,7 @@ var HttpClient = class _HttpClient {
           errorBody?.error ?? "unknown_error",
           errorBody?.error_description ?? response.statusText,
           response.status,
-          errorBody
+          withRetryHint(errorBody, response)
         ),
         status: response.status
       };
@@ -484,6 +493,15 @@ function isFieldErrorArray(value) {
     (v) => typeof v === "object" && v !== null && typeof v.field === "string" && typeof v.message === "string"
   );
 }
+function fieldErrorsOf(envelope) {
+  const scoped = pickField(pickField(envelope, "data"), "fields");
+  if (isFieldErrorArray(scoped)) return scoped;
+  const flat = pickField(envelope, "fields");
+  return isFieldErrorArray(flat) ? flat : void 0;
+}
+function retryAfterOf(envelope) {
+  return pickNumber(envelope, "retry_after") ?? pickNumber(pickField(envelope, "data"), "retryAfter");
+}
 function pickField(value, key) {
   if (typeof value === "object" && value !== null) {
     return value[key];
@@ -509,20 +527,15 @@ function fromPalbaseError(err) {
   if (err.code === "network_error") return new BackendError("network", base);
   if (err.status === 401) return new BackendError("unauthorized", base);
   if (err.status === 429)
-    return new BackendError("rateLimited", {
-      ...base,
-      retryAfter: pickNumber(err.details, "retry_after")
-    });
-  const nested = pickField(err.details, "details");
-  if (err.status === 400 && isFieldErrorArray(nested))
-    return new BackendError("validation", { ...base, fields: nested });
+    return new BackendError("rateLimited", { ...base, retryAfter: retryAfterOf(err.details) });
+  const fields = fieldErrorsOf(err.details);
+  if (err.status === 400 && fields) return new BackendError("validation", { ...base, fields });
   return new BackendError("server", base);
 }
 function fromEnvelope(status, body) {
   const code = pickString(body, "error") ?? "http_error";
   const message = pickString(body, "error_description") ?? `HTTP ${status}`;
   const requestId = pickString(body, "request_id");
-  const details = pickField(body, "details");
   const params = {
     code,
     message,
@@ -532,13 +545,9 @@ function fromEnvelope(status, body) {
   };
   if (status === 401) return new BackendError("unauthorized", params);
   if (status === 429)
-    return new BackendError("rateLimited", {
-      ...params,
-      // Real 429 wire body has TOP-LEVEL retry_after; nested details is a fallback.
-      retryAfter: pickNumber(body, "retry_after") ?? pickNumber(details, "retry_after")
-    });
-  if (status === 400 && isFieldErrorArray(details))
-    return new BackendError("validation", { ...params, fields: details });
+    return new BackendError("rateLimited", { ...params, retryAfter: retryAfterOf(body) });
+  const fields = fieldErrorsOf(body);
+  if (status === 400 && fields) return new BackendError("validation", { ...params, fields });
   return new BackendError("server", params);
 }
 function isBackendError(e) {
@@ -1594,7 +1603,7 @@ var PalbeAnalytics = class {
 };
 
 // src/api-key.ts
-var PUBLISHABLE_API_KEY_RE = /^pb_([a-z0-9]{4,24})_c[A-Za-z0-9]{20}$/;
+var PUBLISHABLE_API_KEY_RE = /^pb_([a-z0-9]{4,24})_c[A-Za-z0-9]{20,}$/;
 function environmentRefFromPublishableApiKey(apiKey) {
   const match = PUBLISHABLE_API_KEY_RE.exec(apiKey);
   return match ? match[1] ?? "" : "";
@@ -1866,24 +1875,29 @@ var PalbeAuth = class {
    * Self-service account erasure ("right to be forgotten"). Calls palauth
    * `DELETE /auth/user` (session-authed + fresh re-auth): password users pass
    * `{ password }`; passwordless/OAuth users rely on a freshly stepped-up
-   * session. On 202 the erasure workflow is durably queued AND every session is
-   * already revoked server-side — so we tear down local state (mirroring
-   * `signOut()`'s clear, minus the pointless `/logout`) and emit
-   * `signedOut{reason:'accountDeleted'}`.
+   * session. The handler answers **204 with no body** — the erasure has already
+   * finished and every session is already revoked server-side — so we tear down
+   * local state (mirroring `signOut()`'s clear, minus the pointless `/logout`)
+   * and emit `signedOut{reason:'accountDeleted'}`.
+   *
+   * Returns nothing, because there is nothing to return: the handler used to
+   * answer 202 with an `{erasure_id}` naming an asynchronous run, and that id
+   * was removed along with the run (`gdpr_handlers.go:221-229`). Reading it
+   * here threw a `TypeError` AFTER the account was already gone — a success
+   * reported as a failure.
    *
    * On 401 `reauth_required` / 503 `not_configured` (or `erasure_unavailable`)
    * the request throws BEFORE the teardown line, so the local session is left
    * fully intact — the deletion did not happen and the user is still signed in.
    */
   async deleteAccount(params = {}) {
-    const res = await palbeRequest(this.rt, "DELETE", "/auth/user", {
+    await palbeRequest(this.rt, "DELETE", "/auth/user", {
       body: params.password ? { password: params.password } : {}
     });
     this.nextSignOutReason = "accountDeleted";
     this.rt.tokenManager.clearSession();
     this.rt.storage.clear();
     this.cachedUser = null;
-    return { erasureId: res.erasure_id };
   }
   /**
    * @internal — invoked by the transport choke point (`request.ts`), not app code.
@@ -2370,9 +2384,15 @@ var PalbeCalls = class {
    * @param media    - Which media tracks to publish (default: audio + video)
    * @returns        A `Call` in `connecting` state; transitions to `active` once the media room connects.
    *
-   * @throws BackendError('network', { code: 'call_service_unavailable' })  if the SFU is down (503)
-   * @throws BackendError('forbidden', { code: 'not_group_member' })       if the caller is not a member (403)
-   * @throws BackendError('conflict', { code: 'call_room_full' })          if the room is full (409)
+   * Every failure below arrives as kind `'server'` — this SDK's error kinds are
+   * `notConfigured | validation | unauthorized | rateLimited | server | network
+   * | decode`, and only a 401, a 429 or a 400 carrying a field-error array gets
+   * its own kind. So branch on `err.code`, never on the kind.
+   *
+   * @throws BackendError('server', { code: 'calling_unavailable' })  no SFU configured on this stack (503)
+   * @throws BackendError('server', { code: 'not_group_member' })     the caller is not a member of the group (403)
+   * @throws BackendError('server', { code: 'call_room_full' })       the call is at its participant limit (409)
+   * @throws BackendError('server', { code: 'call_provider_error' })  the media provider failed upstream (502)
    */
   async start(groupId, { media = ["audio", "video"] } = {}) {
     if (!groupId) {
@@ -2393,7 +2413,11 @@ var PalbeCalls = class {
    * Accept an incoming call in a messaging group.
    *
    * @param groupId  - Messaging group display-id
-   * @param callId   - Call identifier (from the push notification payload)
+   * @param callId   - Call identifier, carried by the `call_invite` the server
+   *   fans onto the group's conversation topic
+   *   (`pb.realtime.channel('messaging:conv:<rfcGroupId>').on('call_invite', …)`).
+   *   This SDK ships no web push: on the web the invite arrives over realtime or
+   *   over whatever signalling the app already runs.
    * @param media    - Which media tracks to publish (default: audio + video)
    */
   async accept(groupId, callId, { media = ["audio", "video"] } = {}) {
@@ -4496,14 +4520,11 @@ var Chat = class {
   get title() {
     if (this.titleOverride) return this.titleOverride;
     if (this._group?.name) return this._group.name;
-    if (this._draft) {
-      const mode = this._draft.mode;
-      if (mode.kind === "direct") {
-        const peer = this.memberCache.find((m) => m.userId === mode.peerUserId);
-        return peer?.displayName ?? "Chat";
-      }
-      return "Group";
+    if (this.kind === "direct") {
+      const peer = this.memberCache.find((m) => !m.isSelf);
+      return peer?.displayName ?? "Chat";
     }
+    if (this._draft) return "Group";
     const tail = this.id.startsWith("grp_") ? this.id.slice(4) : this.id;
     const short = tail.slice(-4);
     return short ? `Group ${short}` : "Group";
@@ -5477,6 +5498,11 @@ var MessageHub = class {
   emitConv(displayId, e) {
     for (const fn of this.convListeners.get(displayId) ?? []) fn(e);
   }
+  /** How many live conv listeners a group still has — the census the LAST
+   * subscriber reads before tearing the conv topic (and its presence) down. */
+  convListenerCount(displayId) {
+    return this.convListeners.get(displayId)?.size ?? 0;
+  }
   add(map, key, fn) {
     let set = map.get(key);
     if (!set) {
@@ -5514,6 +5540,9 @@ var MessageDeliverySource = class {
   started = false;
   wakeUnsub = null;
   // Per-observed-group conv subscription + heartbeat (presence/typing/read).
+  // `teardown` is the ONE departure path: it stops the heartbeat, broadcasts the
+  // offline frame and drops the subscriptions, so no caller can tear an
+  // observation down without saying goodbye (see observeConversation).
   observed = /* @__PURE__ */ new Map();
   /** Subscribe the device wake topic + run an initial drain. Idempotent. */
   async start() {
@@ -5538,10 +5567,7 @@ var MessageDeliverySource = class {
   stop() {
     this.wakeUnsub?.();
     this.wakeUnsub = null;
-    for (const [, o] of this.observed) {
-      o.unsub();
-      if (o.heartbeat) clearInterval(o.heartbeat);
-    }
+    for (const [, o] of this.observed) o.teardown();
     this.observed.clear();
     this.started = false;
   }
@@ -5772,14 +5798,26 @@ var MessageDeliverySource = class {
       emitPresence(true);
       const heartbeat = setInterval(() => emitPresence(true), 25e3);
       this.observed.set(group.displayId, {
-        unsub: () => {
+        teardown: () => {
+          clearInterval(heartbeat);
+          try {
+            emitPresence(false);
+          } catch {
+          }
           for (const s of subs) s.cancel();
-        },
-        heartbeat
+        }
       });
     } catch {
     }
   }
+  /** Stop observing a group's conv topic: announce OFFLINE, stop the heartbeat
+   * and drop the subscriptions. Idempotent — an unobserved group is a no-op. */
+  unobserveConversation(group) {
+    const o = this.observed.get(group.displayId);
+    if (!o) return;
+    this.observed.delete(group.displayId);
+    o.teardown();
+  }
   /** Announce typing on a group's conv topic (the app calls per keystroke). */
   setTyping(group, isTyping) {
     this.observeConversation(group);
@@ -8007,7 +8045,11 @@ var MessagingCoordinator = class {
   subscribeLive(group, chat) {
     let offMsg = null;
     let offConv = null;
+    let resolved = null;
+    let cancelled = false;
     void this.resolve().then((r) => {
+      if (cancelled) return;
+      resolved = r;
       offMsg = r.hub.onMessage(group.displayId, (m) => {
         void chat.ingestLive(m);
       });
@@ -8015,8 +8057,12 @@ var MessagingCoordinator = class {
       offConv = r.hub.onConv(group.displayId, (e) => chat.applyConv(e.event, e.payload));
     });
     return () => {
+      cancelled = true;
       offMsg?.();
       offConv?.();
+      if (resolved && resolved.hub.convListenerCount(group.displayId) === 0) {
+        resolved.source.unobserveConversation(group);
+      }
     };
   }
   async userIdForDevice(group, deviceId) {
@@ -8874,8 +8920,33 @@ function unwrapBroadcast(frame) {
 function stripRealtimePrefix(topic) {
   return topic.startsWith(REALTIME_PREFIX) ? topic.slice(REALTIME_PREFIX.length) : topic;
 }
+function encodeStateSet(joinRef, ref, topic, key, value, life) {
+  return JSON.stringify([
+    joinRef,
+    String(ref),
+    REALTIME_PREFIX + topic,
+    "state_set",
+    { key, value, life }
+  ]);
+}
+function encodeStateDel(joinRef, ref, topic, key) {
+  return JSON.stringify([joinRef, String(ref), REALTIME_PREFIX + topic, "state_del", { key }]);
+}
+function encodeStateResync(joinRef, ref, topic) {
+  return JSON.stringify([joinRef, String(ref), REALTIME_PREFIX + topic, "state_resync", {}]);
+}
+function encodeAccessToken(joinRef, ref, topic, token) {
+  return JSON.stringify([
+    joinRef,
+    String(ref),
+    REALTIME_PREFIX + topic,
+    "access_token",
+    { access_token: token }
+  ]);
+}
 
 // src/realtime/connection.ts
+var RETRYABLE_REFUSALS = /* @__PURE__ */ new Set(["unavailable", "rate_limited", "too_many_channels"]);
 var WS_OPEN = 1;
 var DEFAULT_HEARTBEAT_MS = 25e3;
 var DEFAULT_MAX_BACKOFF_SECONDS = 30;
@@ -9108,6 +9179,31 @@ var RealtimeSocket = class {
       this.handleChannelClose(frame);
       return;
     }
+    if (frame.event === "state_snapshot") {
+      this.handlers?.onStateSnapshot(stripRealtimePrefix(frame.topic), frame.payload);
+      return;
+    }
+    if (frame.event === "state_diff") {
+      this.handlers?.onStateDiff(stripRealtimePrefix(frame.topic), frame.payload);
+      return;
+    }
+    if (frame.event === "phx_reply") {
+      const body = frame.payload;
+      const topic = stripRealtimePrefix(frame.topic);
+      if (body && body.status === "ok" && body.response && typeof body.response === "object") {
+        this.handlers?.onJoinInfo(topic, body.response);
+        return;
+      }
+      if (body && body.status === "error" && String(frame.ref) === this.joinRefs.get(topic)) {
+        const reason = typeof body.response?.["reason"] === "string" ? body.response["reason"] : "unauthorized";
+        if (!RETRYABLE_REFUSALS.has(reason)) {
+          this.joinedTopics.delete(topic);
+          this.joinRefs.delete(topic);
+        }
+        this.handlers?.onChannelRefused(topic, reason);
+      }
+      return;
+    }
     const inbound = unwrapBroadcast(frame);
     if (inbound) {
       this.channelRejoinAttempts.delete(inbound.topic);
@@ -9148,6 +9244,40 @@ var RealtimeSocket = class {
     }, delayMs);
     this.channelRejoinTimers.set(topic, timer);
   }
+  // MARK: state
+  /** Write one entry on a joined channel's state. Dropped when the topic has no
+   * live join: the server refuses state on a channel this socket is not on, and
+   * the reconnect's join brings a fresh snapshot anyway. */
+  sendStateSet(topic, key, value, life) {
+    const joinRef = this.joinRefs.get(topic);
+    if (joinRef === void 0 || !this.isOpen()) return;
+    this.send(encodeStateSet(joinRef, this.nextRef(), topic, key, value, life));
+  }
+  /** Remove one entry. The server refuses a key this connection does not own. */
+  sendStateDel(topic, key) {
+    const joinRef = this.joinRefs.get(topic);
+    if (joinRef === void 0 || !this.isOpen()) return;
+    this.send(encodeStateDel(joinRef, this.nextRef(), topic, key));
+  }
+  /** Ask for a fresh snapshot — the answer to a detected gap. */
+  sendStateResync(topic) {
+    const joinRef = this.joinRefs.get(topic);
+    if (joinRef === void 0 || !this.isOpen()) return;
+    this.send(encodeStateResync(joinRef, this.nextRef(), topic));
+  }
+  /**
+   * Present a fresher credential on every joined channel WITHOUT rejoining.
+   *
+   * The alternative — dropping and rejoining — reaps this connection's
+   * ephemeral entries (its presence) and forces a full resync on every channel.
+   * A token rotation is not a reconnection and must not look like one.
+   */
+  sendAccessToken(token) {
+    if (!this.isOpen()) return;
+    for (const [topic, joinRef] of this.joinRefs) {
+      this.send(encodeAccessToken(joinRef, this.nextRef(), topic, token));
+    }
+  }
   // MARK: helpers
   /** Drop a single topic's token-expiry rejoin state (cancel its pending timer). */
   clearChannelRejoin(topic) {
@@ -9173,6 +9303,60 @@ var RealtimeSocket = class {
   }
 };
 
+// src/realtime/state.ts
+var PRESENCE_PREFIX = "$p:";
+var ChannelState = class {
+  /** The sequence this local copy is current as of. */
+  seq = 0;
+  /** key → value. Lifetimes are the server's business; a reader only needs the
+   * values, and presence is derived from the key shape. */
+  entries = /* @__PURE__ */ new Map();
+  /** Replace everything. A snapshot is the WHOLE picture, never a merge —
+   * merging one would keep entries the server has since removed. */
+  applySnapshot(body) {
+    this.entries.clear();
+    for (const [k, e] of Object.entries(body.entries ?? {})) {
+      this.entries.set(k, e.v);
+    }
+    this.seq = body.seq;
+  }
+  /**
+   * Apply a diff, or report that it cannot be applied.
+   *
+   * `gap` when this copy is behind the diff's starting point: frames were
+   * missed, and applying anyway would produce a state that never existed on the
+   * server. The state is left untouched so the caller can resync from something
+   * consistent.
+   *
+   * A diff at or below the current sequence is already applied — a resend after
+   * a retry — and is silently accepted so duplicates are harmless.
+   */
+  applyDiff(body) {
+    if (this.seq < body.from_seq) return "gap";
+    if (body.seq <= this.seq) return "applied";
+    for (const [k, e] of Object.entries(body.set ?? {})) this.entries.set(k, e.v);
+    for (const k of body.del ?? []) this.entries.delete(k);
+    this.seq = body.seq;
+    return "applied";
+  }
+  /**
+   * Everyone else's presence.
+   *
+   * `selfConn` is this connection's id, as the join reply reported it. Its own
+   * entry is excluded because an app rendering "who else is here" would
+   * otherwise always show one extra face — itself.
+   */
+  presence(selfConn) {
+    const own = selfConn === void 0 ? void 0 : PRESENCE_PREFIX + selfConn;
+    const out = [];
+    for (const [k, v] of this.entries) {
+      if (!k.startsWith(PRESENCE_PREFIX) || k === own) continue;
+      out.push(v);
+    }
+    return out;
+  }
+};
+
 // src/realtime/facade.ts
 var StatusStore = class {
   currentState = "idle";
@@ -9208,6 +9392,7 @@ var StatusStore = class {
     for (const listener of this.listeners) listener(snapshot);
   }
 };
+var RETRYABLE_REASONS = /* @__PURE__ */ new Set(["unavailable", "rate_limited", "too_many_channels"]);
 var RealtimeChannel = class {
   /** The app-defined channel name (bare sub-topic, no "realtime:" prefix). */
   name;
@@ -9225,6 +9410,23 @@ var RealtimeChannel = class {
   on(event, handler) {
     return this.owner.subscribe(this.name, event, handler);
   }
+  /**
+   * Called when the server REFUSES this channel.
+   *
+   * A join is an authorization decision, and a decision the app never hears is
+   * the same as no decision at all: silence looks exactly like a slow network.
+   * This is where a refusal arrives, carrying the server's own distinction —
+   * `retryable: false` means "you may not" and asking again will not help;
+   * `retryable: true` means the project could not be asked, and the socket's
+   * next reconnect retries on its own.
+   *
+   *     pb.realtime.channel('room:42').onError((err) => {
+   *       if (!err.retryable) showJoinDenied()
+   *     })
+   */
+  onError(handler) {
+    return this.owner.subscribeError(this.name, handler);
+  }
   /**
    * Broadcast `payload` to the channel's other subscribers (web addition —
    * iOS is receive-only). Joins the channel if it isn't already; queued
@@ -9233,6 +9435,57 @@ var RealtimeChannel = class {
   send(event, payload = {}) {
     this.owner.send(this.name, event, payload);
   }
+  /**
+   * Watch one key of the channel's shared state.
+   *
+   * The handler is called with the CURRENT value straight away when there is
+   * one, and again on every change. That is the difference from `on()`: a
+   * subscriber to an event learns nothing until the next one, while state is
+   * already there when you ask.
+   */
+  onState(key, handler) {
+    return this.owner.subscribeState(this.name, key, handler);
+  }
+  /** Read one key without subscribing. */
+  stateValue(key) {
+    return this.owner.stateOf(this.name).entries.get(key);
+  }
+  /** Write one key. `durable` outlives this connection; `ephemeral` is reaped
+   * when it closes, which is what presence is built on. */
+  setState(key, value, opts = {}) {
+    this.owner.writeState(this.name, key, value, opts.life ?? "durable");
+  }
+  /** Remove a key this connection wrote. */
+  clearState(key) {
+    this.owner.clearState(this.name, key);
+  }
+  /**
+   * Announce this client on the channel. `meta` is whatever other participants
+   * should see — a name, an avatar, a cursor.
+   *
+   * It is ephemeral state keyed by this connection, so it disappears when the
+   * socket does. Nothing has to be un-announced on a crash.
+   */
+  presenceEnter(meta) {
+    this.owner.presenceWrite(this.name, meta);
+  }
+  /** Replace the announced value — a cursor moving is this, at whatever rate
+   * the app likes: the server conflates writes it cannot deliver fast enough. */
+  presenceUpdate(meta) {
+    this.owner.presenceWrite(this.name, meta);
+  }
+  /** Leave early. Closing the socket does this on its own. */
+  presenceLeave() {
+    this.owner.presenceClear(this.name);
+  }
+  /** Everyone else currently announced, this client excluded. */
+  presenceOthers() {
+    return this.owner.presenceOthers(this.name);
+  }
+  /** Watch the announced set. Called on every change. */
+  onPresence(handler) {
+    return this.owner.subscribePresence(this.name, handler);
+  }
 };
 var PalbeRealtime = class {
   rt;
@@ -9242,9 +9495,21 @@ var PalbeRealtime = class {
   // Per-(topic, event) handlers — an event may have multiple handlers
   // (multiple .on calls); entry identity is the unsubscribe token.
   handlers = /* @__PURE__ */ new Set();
+  // Per-topic refusal handlers. Kept apart from `handlers` because they are not
+  // refcounted: registering one must not join a channel, and cancelling the
+  // last one must not leave a channel that still has event handlers on it.
+  errorHandlers = /* @__PURE__ */ new Set();
   // Joins are refcounted per topic so the socket only leaves a topic when
   // its last handler cancels (iOS RealtimeClient parity).
   topicRefcount = /* @__PURE__ */ new Map();
+  // Per-topic shared state, and this connection's identity on each topic (from
+  // the join ack). Presence is keyed by that identity, so a write before the
+  // ack has nowhere to go and is queued until it arrives.
+  states = /* @__PURE__ */ new Map();
+  connIds = /* @__PURE__ */ new Map();
+  pendingPresence = /* @__PURE__ */ new Map();
+  stateWatchers = /* @__PURE__ */ new Set();
+  presenceWatchers = /* @__PURE__ */ new Set();
   constructor(rt) {
     this.rt = rt;
   }
@@ -9287,6 +9552,20 @@ var PalbeRealtime = class {
   get status() {
     return this.statusStore;
   }
+  /**
+   * Hand the socket a fresher credential for the SAME user, without rejoining.
+   *
+   * Called when the app's token rotates. The alternative — letting the channels
+   * die at expiry and rejoining — reaps this connection's ephemeral entries
+   * (its presence, on every channel) and forces a full state resync. A token
+   * getting older is not a disconnection and must not cost one.
+   *
+   * A no-op before a socket exists: the first connect resolves a fresh token
+   * on its own.
+   */
+  refreshToken(token) {
+    this.socket?.sendAccessToken(token);
+  }
   /** @internal */
   subscribe(topic, event, handler) {
     const socket = this.ensureSocket();
@@ -9301,7 +9580,9 @@ var PalbeRealtime = class {
         if (cancelled) return;
         cancelled = true;
         this.handlers.delete(entry);
-        const next = (this.topicRefcount.get(topic) ?? 1) - 1;
+        const held = this.topicRefcount.get(topic);
+        if (held === void 0) return;
+        const next = held - 1;
         if (next <= 0) {
           this.topicRefcount.delete(topic);
           socket.leaveTopic(topic);
@@ -9311,6 +9592,25 @@ var PalbeRealtime = class {
       }
     };
   }
+  /**
+   * Register a refusal handler for one topic. Does NOT join: watching for a
+   * refusal is not a subscription, and an app that registers one before its
+   * first `.on()` should not be joining anything yet.
+   *
+   * @internal
+   */
+  subscribeError(topic, handler) {
+    const entry = { topic, handler };
+    this.errorHandlers.add(entry);
+    let cancelled = false;
+    return {
+      cancel: () => {
+        if (cancelled) return;
+        cancelled = true;
+        this.errorHandlers.delete(entry);
+      }
+    };
+  }
   /** @internal */
   send(topic, event, payload) {
     const socket = this.ensureSocket();
@@ -9332,7 +9632,11 @@ var PalbeRealtime = class {
         onReconnect: () => {
         },
         onStateChange: (state) => this.statusStore.setState(state),
-        onChannelError: (topic) => this.handleChannelError(topic)
+        onChannelError: (topic) => this.handleChannelError(topic),
+        onChannelRefused: (topic, reason) => this.handleChannelRefused(topic, reason),
+        onStateSnapshot: (topic, body) => this.applySnapshot(topic, body),
+        onStateDiff: (topic, body) => this.applyDiff(topic, body),
+        onJoinInfo: (topic, info) => this.applyJoinInfo(topic, info)
       });
     }
     return this.socket;
@@ -9346,19 +9650,185 @@ var PalbeRealtime = class {
     }
   }
   /**
-   * A channel died for good (token-expiry rejoin exhausted N attempts). Drop its
-   * handlers + refcount so the app stops expecting events on it, and flip the
-   * status observable to `'error'` (the React `useChannel` hook reports this).
-   * A later `.on()` for the same topic re-joins from scratch (refcount 1).
+  /**
+   * The server refused a channel. Tell whoever asked, and — when the answer is
+   * final — stop pretending the app is subscribed to it.
+   *
+   * `unavailable` leaves everything in place: the project could not be reached
+   * to decide, the socket rejoins on its next reconnect, and dropping the app's
+   * handlers would make a momentary outage look like a permanent denial.
+   */
+  handleChannelRefused(topic, reason) {
+    const retryable = RETRYABLE_REASONS.has(reason);
+    for (const entry of this.errorHandlers) {
+      if (entry.topic === topic) entry.handler({ topic, reason, retryable });
+    }
+    if (retryable) return;
+    this.forgetTopic(topic);
+  }
+  /**
+   * A channel died for good — a token-expiry rejoin that exhausted its attempts.
+   * The app must stop expecting anything on it, and the status observable flips
+   * to `'error'` (the React `useChannel` hook reports that).
+   *
+   * It clears the SAME registries a final refusal clears, and used to clear only
+   * the event handlers. A state or presence watcher left behind here waits
+   * forever for a snapshot that cannot arrive, and fires twice if the app ever
+   * re-subscribes — the identical failure its sibling three functions up
+   * describes, on a channel that was given up on rather than refused.
    */
   handleChannelError(topic) {
+    this.forgetTopic(topic);
+    this.statusStore.setState("error");
+  }
+  /** Drop every registration this topic holds. One place, because "which
+   *  registries" is a question two callers must never answer differently. */
+  forgetTopic(topic) {
     for (const entry of this.handlers) {
       if (entry.topic === topic) this.handlers.delete(entry);
     }
+    for (const entry of this.stateWatchers) {
+      if (entry.topic === topic) this.stateWatchers.delete(entry);
+    }
+    for (const entry of this.presenceWatchers) {
+      if (entry.topic === topic) this.presenceWatchers.delete(entry);
+    }
+    this.pendingPresence.delete(topic);
+    this.states.delete(topic);
+    this.connIds.delete(topic);
     this.topicRefcount.delete(topic);
-    this.statusStore.setState("error");
+  }
+  // ── state ──────────────────────────────────────────────────────────────────
+  /** @internal */
+  stateOf(topic) {
+    let st = this.states.get(topic);
+    if (!st) {
+      st = new ChannelState();
+      this.states.set(topic, st);
+    }
+    return st;
+  }
+  /** @internal */
+  subscribeState(topic, key, handler) {
+    const socket = this.ensureSocket();
+    const entry = { topic, key, handler };
+    this.stateWatchers.add(entry);
+    this.retainTopic(topic, socket);
+    const known = this.stateOf(topic).entries.get(key);
+    if (known !== void 0) handler(known);
+    let cancelled = false;
+    return {
+      cancel: () => {
+        if (cancelled) return;
+        cancelled = true;
+        this.stateWatchers.delete(entry);
+        this.releaseTopic(topic, socket);
+      }
+    };
+  }
+  /** @internal */
+  subscribePresence(topic, handler) {
+    const socket = this.ensureSocket();
+    const entry = { topic, handler };
+    this.presenceWatchers.add(entry);
+    this.retainTopic(topic, socket);
+    handler(this.presenceOthers(topic));
+    let cancelled = false;
+    return {
+      cancel: () => {
+        if (cancelled) return;
+        cancelled = true;
+        this.presenceWatchers.delete(entry);
+        this.releaseTopic(topic, socket);
+      }
+    };
+  }
+  /** @internal */
+  writeState(topic, key, value, life) {
+    const socket = this.ensureSocket();
+    socket.joinTopic(topic);
+    socket.sendStateSet(topic, key, value, life);
+  }
+  /** @internal */
+  clearState(topic, key) {
+    this.ensureSocket().sendStateDel(topic, key);
+  }
+  /** @internal */
+  presenceWrite(topic, meta) {
+    const socket = this.ensureSocket();
+    socket.joinTopic(topic);
+    const conn = this.connIds.get(topic);
+    if (conn === void 0) {
+      this.pendingPresence.set(topic, meta);
+      return;
+    }
+    socket.sendStateSet(topic, PRESENCE_KEY(conn), meta, "ephemeral");
+  }
+  /** @internal */
+  presenceClear(topic) {
+    this.pendingPresence.delete(topic);
+    const conn = this.connIds.get(topic);
+    if (conn === void 0) return;
+    this.ensureSocket().sendStateDel(topic, PRESENCE_KEY(conn));
+  }
+  /** @internal */
+  presenceOthers(topic) {
+    return this.stateOf(topic).presence(this.connIds.get(topic));
+  }
+  retainTopic(topic, socket) {
+    const count = (this.topicRefcount.get(topic) ?? 0) + 1;
+    this.topicRefcount.set(topic, count);
+    if (count === 1) socket.joinTopic(topic);
+  }
+  releaseTopic(topic, socket) {
+    const next = (this.topicRefcount.get(topic) ?? 1) - 1;
+    if (next <= 0) {
+      this.topicRefcount.delete(topic);
+      socket.leaveTopic(topic);
+      return;
+    }
+    this.topicRefcount.set(topic, next);
+  }
+  applySnapshot(topic, body) {
+    this.stateOf(topic).applySnapshot(body);
+    this.notifyState(topic);
+  }
+  applyDiff(topic, body) {
+    if (this.stateOf(topic).applyDiff(body) === "gap") {
+      this.socket?.sendStateResync(topic);
+      return;
+    }
+    this.notifyState(topic);
+  }
+  applyJoinInfo(topic, info) {
+    if (typeof info.conn !== "string" || info.conn === "") return;
+    this.connIds.set(topic, info.conn);
+    const seq = info.state_seq;
+    if (typeof seq === "number" && seq < this.stateOf(topic).seq) {
+      this.stateOf(topic).applySnapshot({ seq, entries: {} });
+    }
+    const held = this.pendingPresence.get(topic);
+    if (held !== void 0) {
+      this.pendingPresence.delete(topic);
+      this.socket?.sendStateSet(topic, PRESENCE_KEY(info.conn), held, "ephemeral");
+    }
+    this.notifyState(topic);
+  }
+  notifyState(topic) {
+    this.statusStore.recordEvent(/* @__PURE__ */ new Date());
+    const st = this.stateOf(topic);
+    for (const w of this.stateWatchers) {
+      if (w.topic === topic) w.handler(st.entries.get(w.key));
+    }
+    if (this.presenceWatchers.size > 0) {
+      const others = this.presenceOthers(topic);
+      for (const w of this.presenceWatchers) {
+        if (w.topic === topic) w.handler(others);
+      }
+    }
   }
 };
+var PRESENCE_KEY = (conn) => `$p:${conn}`;
 
 // src/storage.ts
 function memorySessionStorage() {
@@ -9419,7 +9889,7 @@ function defaultSessionStorage(key) {
 }
 
 // src/version.ts
-var VERSION = "7.3.8";
+var VERSION = "7.4.0";
 
 // src/runtime.ts
 function buildRuntime(config) {
@@ -9597,6 +10067,7 @@ async function callEndpoint(resolveRt, name, input, options) {
 }
 
 // src/upload.ts
+var UPLOAD_PATH = "/v1/storage/upload";
 function abortError() {
   return new BackendError("network", { code: "aborted", message: "Upload aborted" });
 }
@@ -9650,7 +10121,9 @@ async function buildHeaders(rt, extra) {
 }
 function buildForm(options) {
   const form = new FormData();
-  for (const [k, v] of Object.entries(options.fields ?? {})) form.append(k, v);
+  const { body, ...loose } = options.fields ?? {};
+  if (body !== void 0) form.append("body", body);
+  else if (Object.keys(loose).length > 0) form.append("body", JSON.stringify(loose));
   const file = options.contentType && options.file.type !== options.contentType ? new Blob([options.file], { type: options.contentType }) : options.file;
   const filename = options.filename ?? (typeof File !== "undefined" && options.file instanceof File ? options.file.name : "file");
   form.append("file", file, filename);
@@ -9724,8 +10197,8 @@ async function uploadViaFetch(url, form, headers, options) {
 async function uploadEndpoint(resolveRt, name, options) {
   const rt = resolveRt();
   checkConstraints(options);
-  const path = name.startsWith("/") ? name : `/${name}`;
-  const url = `${rt.config.url}${path}`;
+  const route = name.startsWith("/") ? name : `/${name}`;
+  const url = `${rt.config.url}${UPLOAD_PATH}${route}`;
   const headers = await buildHeaders(rt, options.headers);
   const form = buildForm(options);
   const useXHR = options.onProgress !== void 0 && typeof XMLHttpRequest !== "undefined";