@cstar.help/js 0.17.0 → 0.17.2

package/README.md

@@ -233,7 +233,7 @@ The client keeps the access token internally. The public result contains `custom
 
 ### Session (existing customer token)
 
-Pass an existing cStar customer token as an object. A token from an unrelated Supabase project does not establish a cStar customer session. Include the cStar team UUID when your application has it.
+Pass an existing cStar customer token as an object. A token from an unrelated Supabase project does not establish a cStar customer session. Include the cStar team UUID when your application has it. Otherwise the client resolves its configured team slug before message, community and realtime requests.
 
 ```typescript
 import { ChatClient, type LoginWithSessionParams } from '@cstar.help/js/chat';

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;
@@ -48,6 +70,7 @@ var RealtimeManager = class {
     this.refreshTimer = null;
     this.currentToken = null;
     this.destroyed = false;
+    this.cleanupPromise = null;
     this.options = options;
   }
   /**
@@ -69,7 +92,11 @@ var RealtimeManager = class {
         "@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 } }
       });
@@ -110,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",
@@ -124,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 = {
@@ -138,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() {
@@ -158,15 +189,17 @@ 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);
@@ -176,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;
   }
 };
 
@@ -208,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) {
@@ -220,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.
@@ -274,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. */
@@ -440,6 +480,7 @@ var ChatClient = class {
     this.authMode = null;
     this.sessionGeneration = 0;
     this.pollingSubscriptions = /* @__PURE__ */ new Set();
+    this.realtimeMessageSubscriptions = /* @__PURE__ */ new Map();
     this.stateListeners = /* @__PURE__ */ new Set();
     this.realtimeManager = null;
     this.presenceManager = null;
@@ -605,11 +646,16 @@ var ChatClient = class {
    * @returns Unsubscribe function
    */
   onMessage(ticketId, callback) {
-    const generation = this.sessionGeneration;
     if (this.realtimeReady && this.realtimeManager) {
-      return this.realtimeManager.subscribeToMessages(ticketId, (message) => {
-        if (generation === this.sessionGeneration) callback(message);
-      });
+      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);
   }
@@ -644,20 +690,21 @@ var ChatClient = class {
   }
   retireSession() {
     const generation = ++this.sessionGeneration;
-    if (this.realtimeManager) {
-      this.realtimeManager.destroy();
-      this.realtimeManager = null;
-    }
     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 unsubscribe of this.pollingSubscriptions) {
       unsubscribe();
     }
     this.pollingSubscriptions.clear();
+    this.realtimeMessageSubscriptions.clear();
     this.sessionToken = null;
     this.teamId = null;
     this.customerId = null;
@@ -828,14 +875,9 @@ 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(signal) {
     const assertCurrent = this.captureSession();
@@ -887,54 +929,90 @@ var ChatClient = class {
     }
   }
   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;
+  pollMessages(ticketId, callback, manager) {
+    const seen = /* @__PURE__ */ new Set();
     let initialized = false;
     let active = true;
     let inFlight = false;
-    const poll = async () => {
-      if (!active || inFlight) return;
+    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 (!active) return;
-        if (messages.length > 0) {
-          const latest = messages[messages.length - 1];
-          if (initialized && latest.id !== lastMessageId) {
-            const lastIdx = messages.findIndex((m) => m.id === lastMessageId);
-            const newMessages = lastIdx >= 0 ? messages.slice(lastIdx + 1) : lastMessageId ? [latest] : messages;
-            for (const msg of newMessages) {
+        do {
+          catchUpQueued = false;
+          try {
+            const messages = await this.messages.list(ticketId);
+            if (!active) return;
+            for (const message of messages) {
               if (!active) return;
-              callback(msg);
+              if (initialized) deliver(message);
+              else seen.add(message.id);
             }
+            initialized = true;
+            if (connected) stopPolling();
+          } catch {
+            startPolling();
           }
-          lastMessageId = latest.id;
-        }
-        initialized = true;
-      } catch {
+        } while (active && catchUpQueued);
       } finally {
         inFlight = false;
       }
     };
-    poll();
-    const timer = setInterval(poll, this.pollingInterval);
     const unsubscribe = () => {
       active = false;
-      clearInterval(timer);
+      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) {
@@ -1023,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: {
@@ -1036,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: {
@@ -1053,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: {
@@ -1078,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: {
@@ -1113,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;
   }
 };
@@ -1154,13 +1282,14 @@ var MessagesApi = class {
   /** List messages for a ticket. */
   async list(ticketId) {
     const assertCurrent = this.chat.captureSession();
-    const teamId = this.chat.getTeamId();
+    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
         }
       }
@@ -1171,7 +1300,8 @@ var MessagesApi = class {
   /** Send a message to a ticket. */
   async send(ticketId, content) {
     const assertCurrent = this.chat.captureSession();
-    const teamId = this.chat.getTeamId();
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch(
       "/api/widget/messages",
       {

package/dist/chat/index.d.cts

@@ -321,6 +321,7 @@ declare class ChatClient {
     private authMode;
     private sessionGeneration;
     private pollingSubscriptions;
+    private realtimeMessageSubscriptions;
     private stateListeners;
     private realtimeManager;
     private presenceManager;
@@ -443,14 +444,9 @@ declare class ChatClient {
     getTeamId(): string | null;
     /**
      * 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.
      */
     ensureTeamId(signal?: AbortSignal): Promise<string>;
     /** @internal Set team ID from identify response or other source. */

package/dist/chat/index.d.ts

@@ -321,6 +321,7 @@ declare class ChatClient {
     private authMode;
     private sessionGeneration;
     private pollingSubscriptions;
+    private realtimeMessageSubscriptions;
     private stateListeners;
     private realtimeManager;
     private presenceManager;
@@ -443,14 +444,9 @@ declare class ChatClient {
     getTeamId(): string | null;
     /**
      * 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.
      */
     ensureTeamId(signal?: AbortSignal): Promise<string>;
     /** @internal Set team ID from identify response or other source. */

package/dist/chat/index.js

@@ -1,4 +1,26 @@
 // 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;
@@ -7,6 +29,7 @@ var RealtimeManager = class {
     this.refreshTimer = null;
     this.currentToken = null;
     this.destroyed = false;
+    this.cleanupPromise = null;
     this.options = options;
   }
   /**
@@ -28,7 +51,11 @@ var RealtimeManager = class {
         "@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 } }
       });
@@ -69,12 +96,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",
@@ -83,6 +112,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 = {
@@ -97,9 +127,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() {
@@ -117,15 +148,17 @@ 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);
@@ -135,9 +168,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;
   }
 };
 
@@ -167,7 +204,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) {
@@ -179,8 +219,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.
@@ -233,11 +272,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. */
@@ -399,6 +439,7 @@ var ChatClient = class {
     this.authMode = null;
     this.sessionGeneration = 0;
     this.pollingSubscriptions = /* @__PURE__ */ new Set();
+    this.realtimeMessageSubscriptions = /* @__PURE__ */ new Map();
     this.stateListeners = /* @__PURE__ */ new Set();
     this.realtimeManager = null;
     this.presenceManager = null;
@@ -564,11 +605,16 @@ var ChatClient = class {
    * @returns Unsubscribe function
    */
   onMessage(ticketId, callback) {
-    const generation = this.sessionGeneration;
     if (this.realtimeReady && this.realtimeManager) {
-      return this.realtimeManager.subscribeToMessages(ticketId, (message) => {
-        if (generation === this.sessionGeneration) callback(message);
-      });
+      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);
   }
@@ -603,20 +649,21 @@ var ChatClient = class {
   }
   retireSession() {
     const generation = ++this.sessionGeneration;
-    if (this.realtimeManager) {
-      this.realtimeManager.destroy();
-      this.realtimeManager = null;
-    }
     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 unsubscribe of this.pollingSubscriptions) {
       unsubscribe();
     }
     this.pollingSubscriptions.clear();
+    this.realtimeMessageSubscriptions.clear();
     this.sessionToken = null;
     this.teamId = null;
     this.customerId = null;
@@ -787,14 +834,9 @@ 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(signal) {
     const assertCurrent = this.captureSession();
@@ -846,54 +888,90 @@ var ChatClient = class {
     }
   }
   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;
+  pollMessages(ticketId, callback, manager) {
+    const seen = /* @__PURE__ */ new Set();
     let initialized = false;
     let active = true;
     let inFlight = false;
-    const poll = async () => {
-      if (!active || inFlight) return;
+    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 (!active) return;
-        if (messages.length > 0) {
-          const latest = messages[messages.length - 1];
-          if (initialized && latest.id !== lastMessageId) {
-            const lastIdx = messages.findIndex((m) => m.id === lastMessageId);
-            const newMessages = lastIdx >= 0 ? messages.slice(lastIdx + 1) : lastMessageId ? [latest] : messages;
-            for (const msg of newMessages) {
+        do {
+          catchUpQueued = false;
+          try {
+            const messages = await this.messages.list(ticketId);
+            if (!active) return;
+            for (const message of messages) {
               if (!active) return;
-              callback(msg);
+              if (initialized) deliver(message);
+              else seen.add(message.id);
             }
+            initialized = true;
+            if (connected) stopPolling();
+          } catch {
+            startPolling();
           }
-          lastMessageId = latest.id;
-        }
-        initialized = true;
-      } catch {
+        } while (active && catchUpQueued);
       } finally {
         inFlight = false;
       }
     };
-    poll();
-    const timer = setInterval(poll, this.pollingInterval);
     const unsubscribe = () => {
       active = false;
-      clearInterval(timer);
+      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) {
@@ -982,8 +1060,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: {
@@ -995,12 +1077,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: {
@@ -1012,21 +1099,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: {
@@ -1037,31 +1134,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: {
@@ -1072,37 +1184,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;
   }
 };
@@ -1113,13 +1241,14 @@ var MessagesApi = class {
   /** List messages for a ticket. */
   async list(ticketId) {
     const assertCurrent = this.chat.captureSession();
-    const teamId = this.chat.getTeamId();
+    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
         }
       }
@@ -1130,7 +1259,8 @@ var MessagesApi = class {
   /** Send a message to a ticket. */
   async send(ticketId, content) {
     const assertCurrent = this.chat.captureSession();
-    const teamId = this.chat.getTeamId();
+    const teamId = await this.chat.ensureTeamId();
+    assertCurrent();
     const response = await this.chat.fetch(
       "/api/widget/messages",
       {

package/dist/index.cjs

@@ -278,7 +278,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.15.1";
+var SDK_VERSION = "0.17.2";
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var DEFAULT_API_VERSION = "2026-03-01";
 var DEFAULT_MAX_RETRIES = 3;

package/dist/index.js

@@ -237,7 +237,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.15.1";
+var SDK_VERSION = "0.17.2";
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var DEFAULT_API_VERSION = "2026-03-01";
 var DEFAULT_MAX_RETRIES = 3;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cstar.help/js",
-	"version": "0.17.0",
+	"version": "0.17.2",
 	"description": "Official TypeScript SDK for the cStar customer support platform",
 	"type": "module",
 	"main": "./dist/index.cjs",