@cstar.help/js 0.16.0 → 0.17.0

package/dist/chat/index.cjs

@@ -47,6 +47,7 @@ var RealtimeManager = class {
     this.channels = /* @__PURE__ */ new Map();
     this.refreshTimer = null;
     this.currentToken = null;
+    this.destroyed = false;
     this.options = options;
   }
   /**
@@ -54,6 +55,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,10 +63,12 @@ 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.client = createClient(tokenData.realtimeUrl, tokenData.realtimeKey, {
         auth: { persistSession: false, autoRefreshToken: false },
         realtime: { params: { eventsPerSecond: 10 } }
@@ -92,10 +96,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);
     }
   }
@@ -160,6 +167,7 @@ var RealtimeManager = class {
   }
   /** Clean up all channels, timers, and the client. */
   destroy() {
+    this.destroyed = true;
     if (this.refreshTimer) {
       clearTimeout(this.refreshTimer);
       this.refreshTimer = null;
@@ -333,6 +341,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 +438,8 @@ 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.stateListeners = /* @__PURE__ */ new Set();
     this.realtimeManager = null;
     this.presenceManager = null;
@@ -354,6 +451,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 +466,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 +480,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 +506,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 +523,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 +549,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);
     }
   }
   /**
@@ -488,8 +605,11 @@ var ChatClient = class {
    * @returns Unsubscribe function
    */
   onMessage(ticketId, callback) {
+    const generation = this.sessionGeneration;
     if (this.realtimeReady && this.realtimeManager) {
-      return this.realtimeManager.subscribeToMessages(ticketId, callback);
+      return this.realtimeManager.subscribeToMessages(ticketId, (message) => {
+        if (generation === this.sessionGeneration) callback(message);
+      });
     }
     return this.pollMessages(ticketId, callback);
   }
@@ -500,8 +620,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,6 +640,10 @@ var ChatClient = class {
   }
   /** Disconnect all subscriptions and clean up. */
   disconnect() {
+    this.retireSession();
+  }
+  retireSession() {
+    const generation = ++this.sessionGeneration;
     if (this.realtimeManager) {
       this.realtimeManager.destroy();
       this.realtimeManager = null;
@@ -527,15 +654,29 @@ var ChatClient = class {
     }
     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.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 +691,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 +709,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 +728,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 +769,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 +785,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. */
@@ -673,14 +837,19 @@ var ChatClient = class {
    * `"Missing teamId"` when the chat client was teamSlug-only because the
    * tickets sub-resource read `getTeamId()` synchronously and bailed.
    */
-  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,28 +862,32 @@ 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 response = await this.fetch(
       "/api/widget/realtime-token",
       {
@@ -722,34 +895,47 @@ var ChatClient = class {
         body: { teamId: this.teamId }
       }
     );
+    this.assertSession(generation);
     return response.data;
   }
   pollMessages(ticketId, callback) {
     let lastMessageId = null;
+    let initialized = false;
+    let active = true;
+    let inFlight = false;
     const poll = async () => {
+      if (!active || inFlight) 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 (lastMessageId && latest.id !== lastMessageId) {
+          if (initialized && latest.id !== lastMessageId) {
             const lastIdx = messages.findIndex((m) => m.id === lastMessageId);
-            const newMessages = lastIdx >= 0 ? messages.slice(lastIdx + 1) : [latest];
+            const newMessages = lastIdx >= 0 ? messages.slice(lastIdx + 1) : lastMessageId ? [latest] : messages;
             for (const msg of newMessages) {
+              if (!active) return;
               callback(msg);
             }
           }
           lastMessageId = latest.id;
         }
+        initialized = true;
       } catch {
+      } finally {
+        inFlight = false;
       }
     };
     poll();
     const timer = setInterval(poll, this.pollingInterval);
-    this.pollingTimers.set(ticketId, timer);
-    return () => {
+    const unsubscribe = () => {
+      active = false;
       clearInterval(timer);
-      this.pollingTimers.delete(ticketId);
+      this.pollingSubscriptions.delete(unsubscribe);
     };
+    this.pollingSubscriptions.add(unsubscribe);
+    return unsubscribe;
   }
   buildUrl(path, query) {
     const base = `${this.baseUrl}${path}`;
@@ -768,10 +954,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 +968,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 +980,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 +994,7 @@ var TicketsApi = class {
         message: params.message
       }
     });
+    assertCurrent();
     const messages = (response.data.messages ?? []).map((m) => ({
       id: m.id,
       content: m.content,
@@ -961,6 +1153,7 @@ var MessagesApi = class {
   }
   /** List messages for a ticket. */
   async list(ticketId) {
+    const assertCurrent = this.chat.captureSession();
     const teamId = this.chat.getTeamId();
     const response = await this.chat.fetch(
       "/api/widget/messages",
@@ -972,10 +1165,12 @@ var MessagesApi = class {
         }
       }
     );
+    assertCurrent();
     return response.data.messages;
   }
   /** Send a message to a ticket. */
   async send(ticketId, content) {
+    const assertCurrent = this.chat.captureSession();
     const teamId = this.chat.getTeamId();
     const response = await this.chat.fetch(
       "/api/widget/messages",
@@ -988,6 +1183,7 @@ var MessagesApi = class {
         }
       }
     );
+    assertCurrent();
     return response.data.message;
   }
 };