@cstar.help/js 0.16.1 → 0.17.2

package/dist/chat/index.cjs

@@ -40,6 +40,28 @@ __export(chat_exports, {
 module.exports = __toCommonJS(chat_exports);
 
 // src/chat/realtime.ts
+var channelRemovals = /* @__PURE__ */ new WeakMap();
+var CHANNEL_DRAIN_TIMEOUT_MS = 5e3;
+function removeRealtimeChannel(client, channel) {
+  const pending = channelRemovals.get(client) ?? /* @__PURE__ */ new Set();
+  channelRemovals.set(client, pending);
+  const removal = client.removeChannel(channel);
+  pending.add(removal);
+  const settled = () => pending.delete(removal);
+  void removal.then(settled, settled);
+}
+async function closeRealtimeClient(client) {
+  const pending = [...channelRemovals.get(client) ?? []];
+  if (pending.length) {
+    let timeout;
+    const deadline = new Promise((resolve) => {
+      timeout = setTimeout(resolve, CHANNEL_DRAIN_TIMEOUT_MS);
+    });
+    await Promise.race([Promise.allSettled(pending), deadline]);
+    clearTimeout(timeout);
+  }
+  await client.realtime.disconnect();
+}
 var RealtimeManager = class {
   constructor(options) {
     this.client = null;
@@ -47,6 +69,8 @@ var RealtimeManager = class {
     this.channels = /* @__PURE__ */ new Map();
     this.refreshTimer = null;
     this.currentToken = null;
+    this.destroyed = false;
+    this.cleanupPromise = null;
     this.options = options;
   }
   /**
@@ -54,6 +78,7 @@ var RealtimeManager = class {
    * Returns true if successful, false if the realtime runtime is unavailable.
    */
   init() {
+    if (this.destroyed) return Promise.resolve(false);
     if (this.initPromise) return this.initPromise;
     this.initPromise = this.doInit();
     return this.initPromise;
@@ -61,11 +86,17 @@ var RealtimeManager = class {
   async doInit() {
     try {
       const tokenData = await this.options.fetchToken();
+      if (this.destroyed) return false;
       const { createClient } = await import(
         /* webpackIgnore: true */
         "@supabase/supabase-js"
       );
+      if (this.destroyed) return false;
+      this.currentToken = tokenData.token;
       this.client = createClient(tokenData.realtimeUrl, tokenData.realtimeKey, {
+        // Reconnects and heartbeats must refresh from cStar's customer JWT,
+        // rather than the dedicated client's empty hosted-auth session.
+        accessToken: async () => this.currentToken,
         auth: { persistSession: false, autoRefreshToken: false },
         realtime: { params: { eventsPerSecond: 10 } }
       });
@@ -92,10 +123,13 @@ var RealtimeManager = class {
     this.refreshTimer = setTimeout(() => this.doRefresh(), delay);
   }
   async doRefresh() {
+    if (this.destroyed) return;
     try {
       const tokenData = await this.options.fetchToken();
+      if (this.destroyed) return;
       this.setToken(tokenData);
     } catch {
+      if (this.destroyed) return;
       this.refreshTimer = setTimeout(() => this.doRefresh(), 3e4);
     }
   }
@@ -103,12 +137,14 @@ var RealtimeManager = class {
    * Subscribe to new messages on a ticket via Postgres Changes.
    * Returns an unsubscribe function.
    */
-  subscribeToMessages(ticketId, callback) {
+  subscribeToMessages(ticketId, callback, onStatus) {
     if (!this.client) return () => {
     };
     const channelName = `messages:${ticketId}`;
     this.removeChannel(channelName);
-    const channel = this.client.channel(channelName).on(
+    const channel = this.client.channel(channelName);
+    this.channels.set(channelName, channel);
+    channel.on(
       "postgres_changes",
       {
         event: "INSERT",
@@ -117,6 +153,7 @@ var RealtimeManager = class {
         filter: `ticket_id=eq.${ticketId}`
       },
       (payload) => {
+        if (this.channels.get(channelName) !== channel) return;
         const row = payload.new;
         if (!row) return;
         const message = {
@@ -131,9 +168,10 @@ var RealtimeManager = class {
         };
         callback(message);
       }
-    ).subscribe();
-    this.channels.set(channelName, channel);
-    return () => this.removeChannel(channelName);
+    ).subscribe((status) => {
+      if (this.channels.get(channelName) === channel) onStatus?.(status);
+    });
+    return () => this.removeChannel(channelName, channel);
   }
   /** Get the underlying realtime client (for sharing with PresenceManager). */
   getClient() {
@@ -151,15 +189,18 @@ var RealtimeManager = class {
   get isReady() {
     return this.client !== null && this.currentToken !== null;
   }
-  removeChannel(name) {
+  removeChannel(name, expected) {
     const existing = this.channels.get(name);
+    if (expected && existing !== expected) return;
     if (existing && this.client) {
-      this.client.removeChannel(existing);
       this.channels.delete(name);
+      removeRealtimeChannel(this.client, existing);
     }
   }
   /** Clean up all channels, timers, and the client. */
   destroy() {
+    if (this.destroyed) return this.cleanupPromise ?? Promise.resolve();
+    this.destroyed = true;
     if (this.refreshTimer) {
       clearTimeout(this.refreshTimer);
       this.refreshTimer = null;
@@ -168,9 +209,13 @@ var RealtimeManager = class {
       this.removeChannel(name);
     }
     this.channels.clear();
+    const client = this.client;
     this.client = null;
     this.initPromise = null;
     this.currentToken = null;
+    this.cleanupPromise = client ? closeRealtimeClient(client).catch(() => {
+    }) : Promise.resolve();
+    return this.cleanupPromise;
   }
 };
 
@@ -200,7 +245,10 @@ var PresenceManager = class {
     };
     const channelName = `typing:${ticketId}`;
     this.removeChannel(channelName);
-    const channel = this.client.channel(`ticket:${ticketId}`).on("broadcast", { event: "typing" }, (data) => {
+    const channel = this.client.channel(`ticket:${ticketId}`);
+    this.channels.set(channelName, channel);
+    channel.on("broadcast", { event: "typing" }, (data) => {
+      if (this.channels.get(channelName) !== channel) return;
       const payload = data?.payload;
       if (!payload) return;
       if (payload.agent_id) {
@@ -212,8 +260,7 @@ var PresenceManager = class {
         callback(typingPayload);
       }
     }).subscribe();
-    this.channels.set(channelName, channel);
-    return () => this.removeChannel(channelName);
+    return () => this.removeChannel(channelName, channel);
   }
   /**
    * Send a customer typing indicator.
@@ -266,11 +313,12 @@ var PresenceManager = class {
     } catch {
     }
   }
-  removeChannel(name) {
+  removeChannel(name, expected) {
     const existing = this.channels.get(name);
+    if (expected && existing !== expected) return;
     if (existing && this.client) {
-      this.client.removeChannel(existing);
       this.channels.delete(name);
+      removeRealtimeChannel(this.client, existing);
     }
   }
   /** Clean up all channels and timers. */
@@ -333,6 +381,94 @@ var ChatClientNetworkError = class extends ChatClientError {
   }
 };
 
+// src/chat/attachments.ts
+var UUID = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i;
+function downloadFilename(header) {
+  const extended = header?.match(/(?:^|;)\s*filename\*\s*=\s*UTF-8''([^;]*)/i);
+  let name = "";
+  if (extended) {
+    try {
+      name = decodeURIComponent(extended[1]);
+    } catch {
+    }
+  }
+  if (!name) {
+    const fallback = header?.match(/(?:^|;)\s*filename\s*=\s*(?:"((?:\\.|[^"\\])*)"|([^;]*))/i);
+    name = fallback?.[1]?.replace(/\\(.)/g, "$1") ?? fallback?.[2] ?? "";
+  }
+  return name.split(/[\\/]/).pop()?.replace(/[\x00-\x1f\x7f]/g, "").replace(/^[\s.]+|[\s.]+$/g, "") || "download";
+}
+var AttachmentsApi = class {
+  constructor(chat) {
+    this.chat = chat;
+  }
+  async download(reference, options = {}) {
+    const assertCurrent = this.chat.captureSession();
+    if (!this.chat.getAuthMode())
+      throw new ChatClientAuthError("Sign in before downloading a file.");
+    const { ticketId, messageId, attachmentIndex } = reference;
+    if (typeof ticketId !== "string" || typeof messageId !== "string" || !UUID.test(ticketId) || !UUID.test(messageId) || !Number.isSafeInteger(attachmentIndex) || attachmentIndex < 0) {
+      throw new TypeError("A saved ticket, message and nonnegative attachment index are required.");
+    }
+    const controller = new AbortController();
+    const signal = options.signal;
+    const download = options.download === false ? "0" : "1";
+    const abort = () => controller.abort();
+    const assertOwned = () => {
+      assertCurrent();
+      controller.signal.throwIfAborted();
+    };
+    const unsubscribe = this.chat.subscribe(() => {
+      try {
+        assertCurrent();
+      } catch {
+        abort();
+      }
+    });
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    try {
+      assertOwned();
+      const teamId = await this.chat.ensureTeamId(controller.signal);
+      assertOwned();
+      const result = await this.chat.fetch(
+        "/api/widget/attachments/download",
+        {
+          method: "GET",
+          query: {
+            teamId,
+            ticketId,
+            messageId,
+            attachmentIndex: String(attachmentIndex),
+            download
+          },
+          signal: controller.signal,
+          cache: "no-store",
+          readBody: async (response) => {
+            assertOwned();
+            const blob = await response.blob();
+            assertOwned();
+            return {
+              blob,
+              filename: downloadFilename(response.headers.get("Content-Disposition")),
+              contentType: blob.type.split(";")[0] || "application/octet-stream",
+              size: blob.size
+            };
+          }
+        }
+      );
+      assertOwned();
+      return result;
+    } catch (error) {
+      assertOwned();
+      throw error;
+    } finally {
+      unsubscribe();
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+};
+
 // src/chat/index.ts
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var DEFAULT_POLLING_INTERVAL = 3e3;
@@ -342,7 +478,9 @@ var ChatClient = class {
     this.teamId = null;
     this.customerId = null;
     this.authMode = null;
-    this.pollingTimers = /* @__PURE__ */ new Map();
+    this.sessionGeneration = 0;
+    this.pollingSubscriptions = /* @__PURE__ */ new Set();
+    this.realtimeMessageSubscriptions = /* @__PURE__ */ new Map();
     this.stateListeners = /* @__PURE__ */ new Set();
     this.realtimeManager = null;
     this.presenceManager = null;
@@ -354,6 +492,7 @@ var ChatClient = class {
     this.realtimeEnabled = config.realtime !== false;
     this.tickets = new TicketsApi(this);
     this.messages = new MessagesApi(this);
+    this.attachments = new AttachmentsApi(this);
     this.community = new ChatCommunityApi(this);
   }
   /**
@@ -368,6 +507,8 @@ var ChatClient = class {
    * @param testMode - Whether to use test mode (relaxed timestamp validation)
    */
   async identify(customer, signature, testMode = false) {
+    const generation = this.retireSession();
+    this.assertSession(generation);
     const response = await this.fetch(
       "/api/widget/verify-identity",
       {
@@ -380,15 +521,18 @@ var ChatClient = class {
         }
       }
     );
+    this.assertSession(generation);
     this.sessionToken = response.data.sessionToken;
     this.teamId = response.data.teamId;
     this.customerId = response.data.customer.id;
     this.authMode = "hmac";
     this.notifyStateChanged();
+    this.assertSession(generation);
     if (this.realtimeEnabled) {
       this.realtimeInitPromise = this.initRealtime(
         response.data.customer.id,
-        response.data.customer.name || customer.name || customer.email
+        response.data.customer.name || customer.name || customer.email,
+        generation
       );
     }
     return response.data;
@@ -403,11 +547,15 @@ var ChatClient = class {
    * Supabase session, use `loginWithSession({ accessToken })` instead.
    */
   async loginWithCredentials(params) {
+    const generation = this.retireSession();
+    this.assertSession(generation);
     const teamId = await this.resolveTeamIdFromSlug();
+    this.assertSession(generation);
     const response = await this.fetch("/api/widget/auth/login", {
       method: "POST",
       body: { email: params.email, password: params.password, teamId }
     });
+    this.assertSession(generation);
     if (!response.accessToken) {
       throw new ChatClientAuthError({
         message: "Login succeeded but no session was issued",
@@ -416,11 +564,14 @@ var ChatClient = class {
         requestId: null
       });
     }
-    await this.loginWithSession({
-      accessToken: response.accessToken,
-      teamId,
-      customerName: response.customer.name ?? response.customer.email
-    });
+    this.applySession(
+      {
+        accessToken: response.accessToken,
+        teamId,
+        customerName: response.customer.name ?? response.customer.email
+      },
+      generation
+    );
     return {
       customer: {
         id: this.customerId ?? response.customer.id,
@@ -439,15 +590,22 @@ var ChatClient = class {
    * every request — there is no client-side validation here.
    */
   async loginWithSession(params) {
+    const teamId = params.teamId ?? this.teamId;
+    const generation = this.retireSession();
+    this.applySession({ ...params, ...teamId ? { teamId } : {} }, generation);
+  }
+  applySession(params, generation) {
+    this.assertSession(generation);
     this.sessionToken = params.accessToken;
     if (params.teamId) {
       this.teamId = params.teamId;
     }
     this.authMode = "session";
     this.notifyStateChanged();
+    this.assertSession(generation);
     if (this.realtimeEnabled) {
       const customerName = params.customerName ?? "";
-      this.realtimeInitPromise = this.initRealtimeFromSession(customerName);
+      this.realtimeInitPromise = this.initRealtimeFromSession(customerName, generation);
     }
   }
   /**
@@ -489,7 +647,15 @@ var ChatClient = class {
    */
   onMessage(ticketId, callback) {
     if (this.realtimeReady && this.realtimeManager) {
-      return this.realtimeManager.subscribeToMessages(ticketId, callback);
+      this.realtimeMessageSubscriptions.get(ticketId)?.();
+      const unsubscribe = this.pollMessages(ticketId, callback, this.realtimeManager);
+      this.realtimeMessageSubscriptions.set(ticketId, unsubscribe);
+      return () => {
+        unsubscribe();
+        if (this.realtimeMessageSubscriptions.get(ticketId) === unsubscribe) {
+          this.realtimeMessageSubscriptions.delete(ticketId);
+        }
+      };
     }
     return this.pollMessages(ticketId, callback);
   }
@@ -500,8 +666,11 @@ var ChatClient = class {
    * @returns Unsubscribe function
    */
   onTyping(ticketId, callback) {
+    const generation = this.sessionGeneration;
     if (this.realtimeReady && this.presenceManager) {
-      return this.presenceManager.subscribeToTyping(ticketId, callback);
+      return this.presenceManager.subscribeToTyping(ticketId, (typing) => {
+        if (generation === this.sessionGeneration) callback(typing);
+      });
     }
     return () => {
     };
@@ -517,25 +686,44 @@ var ChatClient = class {
   }
   /** Disconnect all subscriptions and clean up. */
   disconnect() {
-    if (this.realtimeManager) {
-      this.realtimeManager.destroy();
-      this.realtimeManager = null;
-    }
+    this.retireSession();
+  }
+  retireSession() {
+    const generation = ++this.sessionGeneration;
     if (this.presenceManager) {
       this.presenceManager.destroy();
       this.presenceManager = null;
     }
+    if (this.realtimeManager) {
+      this.realtimeManager.destroy();
+      this.realtimeManager = null;
+    }
     this.realtimeReady = false;
     this.realtimeInitPromise = null;
-    for (const timer of this.pollingTimers.values()) {
-      clearInterval(timer);
+    for (const unsubscribe of this.pollingSubscriptions) {
+      unsubscribe();
     }
-    this.pollingTimers.clear();
+    this.pollingSubscriptions.clear();
+    this.realtimeMessageSubscriptions.clear();
     this.sessionToken = null;
     this.teamId = null;
     this.customerId = null;
     this.authMode = null;
     this.notifyStateChanged();
+    return generation;
+  }
+  assertSession(generation) {
+    if (generation !== this.sessionGeneration) {
+      throw new ChatClientAuthError({
+        code: "SESSION_CHANGED",
+        message: "Your sign-in session changed. This operation belongs to the previous session."
+      });
+    }
+  }
+  /** @internal Keep a public operation owned across its asynchronous prerequisites. */
+  captureSession() {
+    const generation = this.sessionGeneration;
+    return () => this.assertSession(generation);
   }
   /**
    * @internal Make an authenticated request to the widget API.
@@ -550,6 +738,12 @@ var ChatClient = class {
    * server-confirmed mode.
    */
   async fetch(path, options) {
+    const generation = this.sessionGeneration;
+    const assertRequest = () => {
+      this.assertSession(generation);
+      options.signal?.throwIfAborted();
+    };
+    assertRequest();
     const url = this.buildUrl(path, options.query);
     const headers = {
       "Content-Type": "application/json"
@@ -562,14 +756,18 @@ var ChatClient = class {
       response = await globalThis.fetch(url, {
         method: options.method,
         headers,
+        ...options.signal ? { signal: options.signal } : {},
+        ...options.cache ? { cache: options.cache } : {},
         body: options.body ? JSON.stringify(options.body) : void 0
       });
     } catch (networkErr) {
+      assertRequest();
       throw new ChatClientNetworkError({
         message: networkErr instanceof Error ? networkErr.message : "Network request failed",
         originalError: networkErr
       });
     }
+    assertRequest();
     const responseHeaders = response.headers && typeof response.headers.get === "function" ? response.headers : null;
     const headerMode = responseHeaders?.get("X-Cstar-Auth-Mode") ?? null;
     if (headerMode === "hmac" || headerMode === "session") {
@@ -577,9 +775,11 @@ var ChatClient = class {
       this.authMode = headerMode;
       if (previous !== headerMode) this.notifyStateChanged();
     }
+    assertRequest();
     const requestId = responseHeaders?.get("X-Request-Id") ?? null;
     if (!response.ok) {
       const errorBody = await response.json().catch(() => ({ error: { code: "UNKNOWN", message: "Request failed" } }));
+      assertRequest();
       const code = errorBody.error?.code ?? "UNKNOWN";
       const message = errorBody.error?.message ?? `Widget API error: ${response.status}`;
       if (response.status === 401 || response.status === 403) {
@@ -616,7 +816,14 @@ var ChatClient = class {
         requestId
       });
     }
-    return response.json();
+    try {
+      const body = options.readBody ? await options.readBody(response) : await response.json();
+      assertRequest();
+      return body;
+    } catch (error) {
+      assertRequest();
+      throw error;
+    }
   }
   /**
    * Look up the team UUID from the configured `teamSlug`. Used by
@@ -625,37 +832,41 @@ var ChatClient = class {
    *
    * @internal
    */
-  async resolveTeamIdFromSlug() {
+  async resolveTeamIdFromSlug(signal) {
     const response = await this.fetch(
       "/api/widget/team-by-slug",
       {
         method: "GET",
+        signal,
         query: { teamSlug: this.teamSlug }
       }
     );
     return response.data.teamId;
   }
   /** @internal Bootstrap realtime from a session login (no precomputed customerId). */
-  async initRealtimeFromSession(customerName) {
+  async initRealtimeFromSession(customerName, generation) {
+    const manager = new RealtimeManager({ fetchToken: () => this.fetchRealtimeToken(generation) });
+    this.realtimeManager = manager;
     try {
-      this.realtimeManager = new RealtimeManager({
-        fetchToken: () => this.fetchRealtimeToken()
-      });
-      const ready = await this.realtimeManager.init();
+      const ready = await manager.init();
+      if (generation !== this.sessionGeneration || this.realtimeManager !== manager) {
+        manager.destroy();
+        return;
+      }
       if (!ready) return;
       this.realtimeReady = true;
-      const token = this.realtimeManager.getCurrentToken();
+      const token = manager.getCurrentToken();
       const customerId = token ? decodeJwtSub(token) : null;
       if (customerId) {
         this.customerId = customerId;
         this.presenceManager = new PresenceManager({ customerId, customerName });
-        const client = this.realtimeManager.getClient();
+        const client = manager.getClient();
         if (client) {
           this.presenceManager.setClient(client);
         }
       }
     } catch {
-      this.realtimeReady = false;
+      if (generation === this.sessionGeneration) this.realtimeReady = false;
     }
   }
   /** @internal Get the stored team ID for requests that need it. */
@@ -664,23 +875,23 @@ var ChatClient = class {
   }
   /**
    * Resolve a team ID, lazily looking it up from `teamSlug` if no team ID
-   * has been cached yet. Used by `tickets.list` and friends so that a
-   * caller who constructed `new ChatClient({ teamSlug, publishableKey })`
-   * doesn't have to manually call `loginWithCredentials` before reading
-   * public data.
-   *
-   * Closes NEW-v3-05 — `TicketsState(chatClient)` previously errored
-   * `"Missing teamId"` when the chat client was teamSlug-only because the
-   * tickets sub-resource read `getTeamId()` synchronously and bailed.
+   * has been cached yet. Authenticated resources and realtime bootstrap
+   * use this after session login so callers do not need to list tickets
+   * or set a UUID before opening an existing conversation.
    */
-  async ensureTeamId() {
+  async ensureTeamId(signal) {
+    const assertCurrent = this.captureSession();
+    signal?.throwIfAborted();
     if (this.teamId) return this.teamId;
     if (!this.teamSlug) {
       throw new ChatClientAuthError(
         "Missing teamId. Construct ChatClient with `teamSlug` or call `setTeamId()` / `identify()` / `loginWithCredentials()` first."
       );
     }
-    this.teamId = await this.resolveTeamIdFromSlug();
+    const teamId = await this.resolveTeamIdFromSlug(signal);
+    assertCurrent();
+    signal?.throwIfAborted();
+    this.teamId = teamId;
     return this.teamId;
   }
   /** @internal Set team ID from identify response or other source. */
@@ -693,63 +904,116 @@ var ChatClient = class {
       await this.realtimeInitPromise;
     }
   }
-  async initRealtime(customerId, customerName) {
+  async initRealtime(customerId, customerName, generation) {
+    const manager = new RealtimeManager({ fetchToken: () => this.fetchRealtimeToken(generation) });
+    this.realtimeManager = manager;
     try {
-      this.realtimeManager = new RealtimeManager({
-        fetchToken: () => this.fetchRealtimeToken()
-      });
-      const ready = await this.realtimeManager.init();
+      const ready = await manager.init();
+      if (generation !== this.sessionGeneration || this.realtimeManager !== manager) {
+        manager.destroy();
+        return;
+      }
       if (ready) {
         this.realtimeReady = true;
         this.presenceManager = new PresenceManager({
           customerId,
           customerName
         });
-        const client = this.realtimeManager.getClient();
+        const client = manager.getClient();
         if (client) {
           this.presenceManager.setClient(client);
         }
       }
     } catch {
-      this.realtimeReady = false;
+      if (generation === this.sessionGeneration) this.realtimeReady = false;
     }
   }
-  async fetchRealtimeToken() {
+  async fetchRealtimeToken(generation) {
+    this.assertSession(generation);
+    const teamId = await this.ensureTeamId();
+    this.assertSession(generation);
     const response = await this.fetch(
       "/api/widget/realtime-token",
       {
         method: "POST",
-        body: { teamId: this.teamId }
+        body: { teamId }
       }
     );
+    this.assertSession(generation);
     return response.data;
   }
-  pollMessages(ticketId, callback) {
-    let lastMessageId = null;
-    const poll = async () => {
+  pollMessages(ticketId, callback, manager) {
+    const seen = /* @__PURE__ */ new Set();
+    let initialized = false;
+    let active = true;
+    let inFlight = false;
+    let catchUpQueued = false;
+    let connected = false;
+    let timer;
+    let stopRealtime;
+    const deliver = (message) => {
+      if (!active || seen.has(message.id)) return;
+      seen.add(message.id);
+      callback(message);
+    };
+    const stopPolling = () => {
+      clearInterval(timer);
+      timer = void 0;
+    };
+    const startPolling = () => {
+      if (active && timer === void 0) {
+        timer = setInterval(() => void poll(), this.pollingInterval);
+      }
+    };
+    const poll = async (catchUp = false) => {
+      if (!active) return;
+      if (inFlight) {
+        if (catchUp) catchUpQueued = true;
+        return;
+      }
+      inFlight = true;
       try {
-        const messages = await this.messages.list(ticketId);
-        if (messages.length > 0) {
-          const latest = messages[messages.length - 1];
-          if (lastMessageId && latest.id !== lastMessageId) {
-            const lastIdx = messages.findIndex((m) => m.id === lastMessageId);
-            const newMessages = lastIdx >= 0 ? messages.slice(lastIdx + 1) : [latest];
-            for (const msg of newMessages) {
-              callback(msg);
+        do {
+          catchUpQueued = false;
+          try {
+            const messages = await this.messages.list(ticketId);
+            if (!active) return;
+            for (const message of messages) {
+              if (!active) return;
+              if (initialized) deliver(message);
+              else seen.add(message.id);
             }
+            initialized = true;
+            if (connected) stopPolling();
+          } catch {
+            startPolling();
           }
-          lastMessageId = latest.id;
-        }
-      } catch {
+        } while (active && catchUpQueued);
+      } finally {
+        inFlight = false;
       }
     };
-    poll();
-    const timer = setInterval(poll, this.pollingInterval);
-    this.pollingTimers.set(ticketId, timer);
-    return () => {
-      clearInterval(timer);
-      this.pollingTimers.delete(ticketId);
+    const unsubscribe = () => {
+      active = false;
+      stopPolling();
+      stopRealtime?.();
+      this.pollingSubscriptions.delete(unsubscribe);
     };
+    this.pollingSubscriptions.add(unsubscribe);
+    void poll();
+    startPolling();
+    stopRealtime = manager?.subscribeToMessages(ticketId, deliver, (status) => {
+      if (!active) return;
+      if (status === "SUBSCRIBED") {
+        connected = true;
+        stopPolling();
+      } else if (["CHANNEL_ERROR", "TIMED_OUT", "CLOSED"].includes(status)) {
+        connected = false;
+        startPolling();
+      } else return;
+      void poll(true);
+    });
+    return unsubscribe;
   }
   buildUrl(path, query) {
     const base = `${this.baseUrl}${path}`;
@@ -768,10 +1032,12 @@ var TicketsApi = class {
   }
   /** List tickets for the identified customer. */
   async list(params) {
+    const assertCurrent = this.chat.captureSession();
     if (this.chat.getAuthMode() === null) {
       throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     }
     const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch("/api/widget/conversations", {
       method: "GET",
       query: {
@@ -780,6 +1046,7 @@ var TicketsApi = class {
         cursor: params?.cursor
       }
     });
+    assertCurrent();
     const data = response.data.tickets ?? response.data.conversations ?? [];
     const cursor = response.data.cursor;
     const hasMore = response.data.hasMore;
@@ -791,10 +1058,12 @@ var TicketsApi = class {
   }
   /** Create a new ticket. */
   async create(params) {
+    const assertCurrent = this.chat.captureSession();
     if (this.chat.getAuthMode() === null) {
       throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
     }
     const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch("/api/widget/tickets", {
       method: "POST",
       body: {
@@ -803,6 +1072,7 @@ var TicketsApi = class {
         message: params.message
       }
     });
+    assertCurrent();
     const messages = (response.data.messages ?? []).map((m) => ({
       id: m.id,
       content: m.content,
@@ -831,8 +1101,12 @@ var ChatCommunityApi = class {
   }
   /** Create a new community post as the identified customer. */
   async createPost(params) {
-    const teamId = this.chat.getTeamId();
-    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
+    const assertCurrent = this.chat.captureSession();
+    if (this.chat.getAuthMode() === null) {
+      throw new ChatClientAuthError("Sign in or identify a customer before accessing community.");
+    }
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: {
@@ -844,12 +1118,17 @@ var ChatCommunityApi = class {
         customFields: params.customFields
       }
     });
+    assertCurrent();
     return response.data.post;
   }
   /** Update a post. Only the original author can edit. */
   async updatePost(postId, params) {
-    const teamId = this.chat.getTeamId();
-    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
+    const assertCurrent = this.chat.captureSession();
+    if (this.chat.getAuthMode() === null) {
+      throw new ChatClientAuthError("Sign in or identify a customer before accessing community.");
+    }
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: {
@@ -861,21 +1140,31 @@ var ChatCommunityApi = class {
         customFields: params.customFields
       }
     });
+    assertCurrent();
     return response.data.post;
   }
   /** Delete a post (soft delete). Only the original author can delete. */
   async deletePost(postId) {
-    const teamId = this.chat.getTeamId();
-    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
+    const assertCurrent = this.chat.captureSession();
+    if (this.chat.getAuthMode() === null) {
+      throw new ChatClientAuthError("Sign in or identify a customer before accessing community.");
+    }
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: { teamId, action: "deletePost", postId }
     });
+    assertCurrent();
   }
   /** Update a comment. Only the original author can edit. */
   async updateComment(postId, commentId, params) {
-    const teamId = this.chat.getTeamId();
-    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
+    const assertCurrent = this.chat.captureSession();
+    if (this.chat.getAuthMode() === null) {
+      throw new ChatClientAuthError("Sign in or identify a customer before accessing community.");
+    }
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: {
@@ -886,31 +1175,46 @@ var ChatCommunityApi = class {
         commentBody: params.body
       }
     });
+    assertCurrent();
     return response.data.comment;
   }
   /** Delete a comment (soft delete). Only the original author can delete. */
   async deleteComment(postId, commentId) {
-    const teamId = this.chat.getTeamId();
-    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
+    const assertCurrent = this.chat.captureSession();
+    if (this.chat.getAuthMode() === null) {
+      throw new ChatClientAuthError("Sign in or identify a customer before accessing community.");
+    }
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: { teamId, action: "deleteComment", postId, commentId }
     });
+    assertCurrent();
   }
   /** Toggle vote on a post. Returns new vote state and count. */
   async vote(postId) {
-    const teamId = this.chat.getTeamId();
-    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
+    const assertCurrent = this.chat.captureSession();
+    if (this.chat.getAuthMode() === null) {
+      throw new ChatClientAuthError("Sign in or identify a customer before accessing community.");
+    }
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: { teamId, action: "vote", postId }
     });
+    assertCurrent();
     return response.data;
   }
   /** Add a comment to a post. Supports 1-level nesting via parentCommentId. */
   async comment(postId, params) {
-    const teamId = this.chat.getTeamId();
-    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
+    const assertCurrent = this.chat.captureSession();
+    if (this.chat.getAuthMode() === null) {
+      throw new ChatClientAuthError("Sign in or identify a customer before accessing community.");
+    }
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: {
@@ -921,37 +1225,53 @@ var ChatCommunityApi = class {
         parentCommentId: params.parentCommentId ?? null
       }
     });
+    assertCurrent();
     return response.data.comment;
   }
   /** Toggle follow on a post. */
   async follow(postId) {
-    const teamId = this.chat.getTeamId();
-    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
+    const assertCurrent = this.chat.captureSession();
+    if (this.chat.getAuthMode() === null) {
+      throw new ChatClientAuthError("Sign in or identify a customer before accessing community.");
+    }
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch("/api/widget/community", {
       method: "POST",
       body: { teamId, action: "follow", postId }
     });
+    assertCurrent();
     return response.data;
   }
   /** Check if the current user has voted on a post. */
   async getVoteStatus(postId) {
-    const teamId = this.chat.getTeamId();
-    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
+    const assertCurrent = this.chat.captureSession();
+    if (this.chat.getAuthMode() === null) {
+      throw new ChatClientAuthError("Sign in or identify a customer before accessing community.");
+    }
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch("/api/widget/community", {
       method: "GET",
       query: { teamId, postId }
     });
+    assertCurrent();
     return response.data.voted;
   }
   /** Check vote status for multiple posts in one request. */
   async bulkVoteStatus(postIds) {
     if (postIds.length === 0) return {};
-    const teamId = this.chat.getTeamId();
-    if (!teamId) throw new ChatClientAuthError("Not identified. Call chat.identify() first.");
+    const assertCurrent = this.chat.captureSession();
+    if (this.chat.getAuthMode() === null) {
+      throw new ChatClientAuthError("Sign in or identify a customer before accessing community.");
+    }
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch("/api/widget/community", {
       method: "GET",
       query: { teamId, postIds: postIds.join(",") }
     });
+    assertCurrent();
     return response.data;
   }
 };
@@ -961,22 +1281,27 @@ var MessagesApi = class {
   }
   /** List messages for a ticket. */
   async list(ticketId) {
-    const teamId = this.chat.getTeamId();
+    const assertCurrent = this.chat.captureSession();
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch(
       "/api/widget/messages",
       {
         method: "GET",
         query: {
-          teamId: teamId ?? void 0,
+          teamId,
           ticketId
         }
       }
     );
+    assertCurrent();
     return response.data.messages;
   }
   /** Send a message to a ticket. */
   async send(ticketId, content) {
-    const teamId = this.chat.getTeamId();
+    const assertCurrent = this.chat.captureSession();
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch(
       "/api/widget/messages",
       {
@@ -988,6 +1313,7 @@ var MessagesApi = class {
         }
       }
     );
+    assertCurrent();
     return response.data.message;
   }
 };