@cstar.help/js 0.1.0 → 0.1.1

package/dist/chat/index.d.cts

@@ -40,6 +40,14 @@ interface IdentifyResult {
     };
     sessionToken: string;
     expiresAt: string;
+    /** Team UUID — used for realtime token requests. */
+    teamId: string;
+}
+/** Response from the realtime-token endpoint. */
+interface RealtimeTokenResponse {
+    token: string;
+    expiresAt: string;
+    refreshAt: string;
 }
 /** A customer conversation (maps to a ticket). */
 interface Conversation {
@@ -92,22 +100,38 @@ type TypingCallback = (payload: TypingPayload) => void;
 /**
  * Customer-facing chat client for the cStar widget API.
  *
+ * Supports real-time messages and typing indicators when `supabaseUrl`
+ * and `supabaseAnonKey` are provided and `@supabase/supabase-js` is installed.
+ * Falls back to polling otherwise.
+ *
  * ```typescript
- * const chat = new ChatClient({ teamSlug: 'acme' });
+ * const chat = new ChatClient({
+ *   teamSlug: 'acme',
+ *   supabaseUrl: 'https://xxx.supabase.co',
+ *   supabaseAnonKey: 'eyJ...',
+ * });
  * await chat.identify(
  *   { externalId: 'usr_123', email: 'jane@co.com', name: 'Jane', timestamp: Date.now() / 1000 },
  *   'hmac_signature_hex'
  * );
- * const { conversations } = await chat.conversations.list();
+ * chat.onMessage('tkt_abc', (msg) => console.log(msg));
+ * chat.onTyping('tkt_abc', ({ agent_name }) => console.log(agent_name, 'is typing'));
  * ```
  */
 declare class ChatClient {
     private readonly baseUrl;
     private readonly teamSlug;
     private readonly pollingInterval;
+    private readonly supabaseUrl?;
+    private readonly supabaseAnonKey?;
     private sessionToken;
     private teamId;
+    private customerId;
     private pollingTimers;
+    private realtimeManager;
+    private presenceManager;
+    private realtimeReady;
+    private realtimeInitPromise;
     /** Sub-resource for managing conversations. */
     readonly conversations: ConversationsApi;
     /** Sub-resource for managing messages. */
@@ -117,6 +141,9 @@ declare class ChatClient {
      * Identify a customer using HMAC signature verification.
      * Must be called before accessing conversations or messages.
      *
+     * If `supabaseUrl` and `supabaseAnonKey` were provided in the config,
+     * this will also initialize real-time subscriptions (non-blocking).
+     *
      * @param customer - Customer identity fields
      * @param signature - HMAC-SHA256 hex signature of the signed fields
      * @param testMode - Whether to use test mode (relaxed timestamp validation)
@@ -124,7 +151,7 @@ declare class ChatClient {
     identify(customer: IdentifyParams, signature: string, testMode?: boolean): Promise<IdentifyResult>;
     /**
      * Subscribe to new messages on a conversation.
-     * Falls back to polling when Supabase Realtime is not available.
+     * Uses Supabase Realtime (Postgres Changes) when available, falls back to polling.
      *
      * @returns Unsubscribe function
      */
@@ -135,7 +162,12 @@ declare class ChatClient {
      *
      * @returns Unsubscribe function
      */
-    onTyping(_ticketId: string, _callback: TypingCallback): () => void;
+    onTyping(ticketId: string, callback: TypingCallback): () => void;
+    /**
+     * Send a customer typing indicator (requires realtime).
+     * No-op if realtime is not available.
+     */
+    sendTyping(ticketId: string, isTyping: boolean): Promise<void>;
     /** Disconnect all subscriptions and clean up. */
     disconnect(): void;
     /** @internal Make an authenticated request to the widget API. */
@@ -148,6 +180,11 @@ declare class ChatClient {
     getTeamId(): string | null;
     /** @internal Set team ID from identify response or other source. */
     setTeamId(teamId: string): void;
+    /** @internal Wait for realtime to be initialized (for testing). */
+    waitForRealtime(): Promise<void>;
+    private initRealtime;
+    private fetchRealtimeToken;
+    private pollMessages;
     private buildUrl;
 }
 /** Conversations sub-resource on ChatClient. */
@@ -169,4 +206,4 @@ declare class MessagesApi {
     send(ticketId: string, content: string): Promise<WidgetMessage>;
 }
 
-export { ChatClient, type ChatConfig, type Conversation, type ConversationCreateParams, type ConversationListParams, type ConversationListResponse, type IdentifyParams, type IdentifyResult, type MessageCallback, type TypingCallback, type WidgetMessage };
+export { ChatClient, type ChatConfig, type Conversation, type ConversationCreateParams, type ConversationListParams, type ConversationListResponse, type IdentifyParams, type IdentifyResult, type MessageCallback, type RealtimeTokenResponse, type TypingCallback, type TypingPayload, type WidgetMessage };

package/dist/chat/index.d.ts

@@ -40,6 +40,14 @@ interface IdentifyResult {
     };
     sessionToken: string;
     expiresAt: string;
+    /** Team UUID — used for realtime token requests. */
+    teamId: string;
+}
+/** Response from the realtime-token endpoint. */
+interface RealtimeTokenResponse {
+    token: string;
+    expiresAt: string;
+    refreshAt: string;
 }
 /** A customer conversation (maps to a ticket). */
 interface Conversation {
@@ -92,22 +100,38 @@ type TypingCallback = (payload: TypingPayload) => void;
 /**
  * Customer-facing chat client for the cStar widget API.
  *
+ * Supports real-time messages and typing indicators when `supabaseUrl`
+ * and `supabaseAnonKey` are provided and `@supabase/supabase-js` is installed.
+ * Falls back to polling otherwise.
+ *
  * ```typescript
- * const chat = new ChatClient({ teamSlug: 'acme' });
+ * const chat = new ChatClient({
+ *   teamSlug: 'acme',
+ *   supabaseUrl: 'https://xxx.supabase.co',
+ *   supabaseAnonKey: 'eyJ...',
+ * });
  * await chat.identify(
  *   { externalId: 'usr_123', email: 'jane@co.com', name: 'Jane', timestamp: Date.now() / 1000 },
  *   'hmac_signature_hex'
  * );
- * const { conversations } = await chat.conversations.list();
+ * chat.onMessage('tkt_abc', (msg) => console.log(msg));
+ * chat.onTyping('tkt_abc', ({ agent_name }) => console.log(agent_name, 'is typing'));
  * ```
  */
 declare class ChatClient {
     private readonly baseUrl;
     private readonly teamSlug;
     private readonly pollingInterval;
+    private readonly supabaseUrl?;
+    private readonly supabaseAnonKey?;
     private sessionToken;
     private teamId;
+    private customerId;
     private pollingTimers;
+    private realtimeManager;
+    private presenceManager;
+    private realtimeReady;
+    private realtimeInitPromise;
     /** Sub-resource for managing conversations. */
     readonly conversations: ConversationsApi;
     /** Sub-resource for managing messages. */
@@ -117,6 +141,9 @@ declare class ChatClient {
      * Identify a customer using HMAC signature verification.
      * Must be called before accessing conversations or messages.
      *
+     * If `supabaseUrl` and `supabaseAnonKey` were provided in the config,
+     * this will also initialize real-time subscriptions (non-blocking).
+     *
      * @param customer - Customer identity fields
      * @param signature - HMAC-SHA256 hex signature of the signed fields
      * @param testMode - Whether to use test mode (relaxed timestamp validation)
@@ -124,7 +151,7 @@ declare class ChatClient {
     identify(customer: IdentifyParams, signature: string, testMode?: boolean): Promise<IdentifyResult>;
     /**
      * Subscribe to new messages on a conversation.
-     * Falls back to polling when Supabase Realtime is not available.
+     * Uses Supabase Realtime (Postgres Changes) when available, falls back to polling.
      *
      * @returns Unsubscribe function
      */
@@ -135,7 +162,12 @@ declare class ChatClient {
      *
      * @returns Unsubscribe function
      */
-    onTyping(_ticketId: string, _callback: TypingCallback): () => void;
+    onTyping(ticketId: string, callback: TypingCallback): () => void;
+    /**
+     * Send a customer typing indicator (requires realtime).
+     * No-op if realtime is not available.
+     */
+    sendTyping(ticketId: string, isTyping: boolean): Promise<void>;
     /** Disconnect all subscriptions and clean up. */
     disconnect(): void;
     /** @internal Make an authenticated request to the widget API. */
@@ -148,6 +180,11 @@ declare class ChatClient {
     getTeamId(): string | null;
     /** @internal Set team ID from identify response or other source. */
     setTeamId(teamId: string): void;
+    /** @internal Wait for realtime to be initialized (for testing). */
+    waitForRealtime(): Promise<void>;
+    private initRealtime;
+    private fetchRealtimeToken;
+    private pollMessages;
     private buildUrl;
 }
 /** Conversations sub-resource on ChatClient. */
@@ -169,4 +206,4 @@ declare class MessagesApi {
     send(ticketId: string, content: string): Promise<WidgetMessage>;
 }
 
-export { ChatClient, type ChatConfig, type Conversation, type ConversationCreateParams, type ConversationListParams, type ConversationListResponse, type IdentifyParams, type IdentifyResult, type MessageCallback, type TypingCallback, type WidgetMessage };
+export { ChatClient, type ChatConfig, type Conversation, type ConversationCreateParams, type ConversationListParams, type ConversationListResponse, type IdentifyParams, type IdentifyResult, type MessageCallback, type RealtimeTokenResponse, type TypingCallback, type TypingPayload, type WidgetMessage };

package/dist/chat/index.js

@@ -1,3 +1,243 @@
+// src/chat/realtime.ts
+var RealtimeManager = class {
+  constructor(options) {
+    this.client = null;
+    this.initPromise = null;
+    this.channels = /* @__PURE__ */ new Map();
+    this.refreshTimer = null;
+    this.currentToken = null;
+    this.options = options;
+  }
+  /**
+   * Initialize the Supabase client and authenticate with a realtime token.
+   * Returns true if successful, false if @supabase/supabase-js is unavailable.
+   */
+  init() {
+    if (this.initPromise) return this.initPromise;
+    this.initPromise = this.doInit();
+    return this.initPromise;
+  }
+  async doInit() {
+    try {
+      const { createClient } = await import(
+        /* webpackIgnore: true */
+        "@supabase/supabase-js"
+      );
+      this.client = createClient(this.options.supabaseUrl, this.options.supabaseAnonKey, {
+        auth: { persistSession: false, autoRefreshToken: false },
+        realtime: { params: { eventsPerSecond: 10 } }
+      });
+      const tokenData = await this.options.fetchToken();
+      this.setToken(tokenData);
+      return true;
+    } catch {
+      this.initPromise = null;
+      return false;
+    }
+  }
+  setToken(tokenData) {
+    this.currentToken = tokenData.token;
+    if (this.client) {
+      this.client.realtime.setAuth(tokenData.token);
+    }
+    this.scheduleRefresh(tokenData.refreshAt);
+  }
+  scheduleRefresh(refreshAt) {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+    }
+    const msUntilRefresh = new Date(refreshAt).getTime() - Date.now();
+    const delay = Math.max(msUntilRefresh, 1e4);
+    this.refreshTimer = setTimeout(() => this.doRefresh(), delay);
+  }
+  async doRefresh() {
+    try {
+      const tokenData = await this.options.fetchToken();
+      this.setToken(tokenData);
+    } catch {
+      this.refreshTimer = setTimeout(() => this.doRefresh(), 3e4);
+    }
+  }
+  /**
+   * Subscribe to new messages on a ticket via Postgres Changes.
+   * Returns an unsubscribe function.
+   */
+  subscribeToMessages(ticketId, callback) {
+    if (!this.client) return () => {
+    };
+    const channelName = `messages:${ticketId}`;
+    this.removeChannel(channelName);
+    const channel = this.client.channel(channelName).on(
+      "postgres_changes",
+      {
+        event: "INSERT",
+        schema: "public",
+        table: "messages",
+        filter: `ticket_id=eq.${ticketId}`
+      },
+      (payload) => {
+        const row = payload.new;
+        if (!row) return;
+        const message = {
+          id: row.id,
+          content: row.content,
+          sender: row.sender,
+          sender_name: row.sender_name ?? "",
+          created_at: row.created_at,
+          read_at: row.read_at ?? null,
+          attachments: row.attachments ?? []
+        };
+        callback(message);
+      }
+    ).subscribe();
+    this.channels.set(channelName, channel);
+    return () => this.removeChannel(channelName);
+  }
+  /** Get the underlying Supabase client (for sharing with PresenceManager). */
+  getClient() {
+    return this.client;
+  }
+  /** Whether the realtime manager is initialized and has a token. */
+  get isReady() {
+    return this.client !== null && this.currentToken !== null;
+  }
+  removeChannel(name) {
+    const existing = this.channels.get(name);
+    if (existing && this.client) {
+      this.client.removeChannel(existing);
+      this.channels.delete(name);
+    }
+  }
+  /** Clean up all channels, timers, and the client. */
+  destroy() {
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+    for (const [name] of this.channels) {
+      this.removeChannel(name);
+    }
+    this.channels.clear();
+    this.client = null;
+    this.initPromise = null;
+    this.currentToken = null;
+  }
+};
+
+// src/chat/presence.ts
+var TYPING_THROTTLE_MS = 2e3;
+var TYPING_CLEAR_DELAY_MS = 3e3;
+var PresenceManager = class {
+  constructor(options) {
+    this.client = null;
+    this.channels = /* @__PURE__ */ new Map();
+    this.lastTypingSentAt = /* @__PURE__ */ new Map();
+    this.typingClearTimers = /* @__PURE__ */ new Map();
+    this.options = options;
+  }
+  /** Set the Supabase client (shared from RealtimeManager). */
+  setClient(client) {
+    this.client = client;
+  }
+  /**
+   * Subscribe to agent typing events on a ticket.
+   * Only fires callback for agent typing (has `agent_id`), not customer typing echoes.
+   *
+   * @returns Unsubscribe function
+   */
+  subscribeToTyping(ticketId, callback) {
+    if (!this.client) return () => {
+    };
+    const channelName = `typing:${ticketId}`;
+    this.removeChannel(channelName);
+    const channel = this.client.channel(`ticket:${ticketId}`).on("broadcast", { event: "typing" }, (data) => {
+      const payload = data?.payload;
+      if (!payload) return;
+      if (payload.agent_id) {
+        const typingPayload = {
+          agent_id: payload.agent_id,
+          agent_name: payload.agent_name || "Agent",
+          is_typing: !!payload.is_typing
+        };
+        callback(typingPayload);
+      }
+    }).subscribe();
+    this.channels.set(channelName, channel);
+    return () => this.removeChannel(channelName);
+  }
+  /**
+   * Send a customer typing indicator.
+   * Throttled: max 1 typing=true per 2s, auto-clears after 3s.
+   */
+  async sendTyping(ticketId, isTyping) {
+    if (!this.client) return;
+    const existingTimer = this.typingClearTimers.get(ticketId);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+      this.typingClearTimers.delete(ticketId);
+    }
+    if (isTyping) {
+      const lastSent = this.lastTypingSentAt.get(ticketId) || 0;
+      const now = Date.now();
+      if (now - lastSent < TYPING_THROTTLE_MS) {
+        const timer2 = setTimeout(() => {
+          this.doSendTyping(ticketId, false);
+        }, TYPING_CLEAR_DELAY_MS);
+        this.typingClearTimers.set(ticketId, timer2);
+        return;
+      }
+      this.lastTypingSentAt.set(ticketId, now);
+      const timer = setTimeout(() => {
+        this.doSendTyping(ticketId, false);
+      }, TYPING_CLEAR_DELAY_MS);
+      this.typingClearTimers.set(ticketId, timer);
+    }
+    await this.doSendTyping(ticketId, isTyping);
+  }
+  async doSendTyping(ticketId, isTyping) {
+    if (!this.client) return;
+    try {
+      const sendChannelName = `typing-send:${ticketId}`;
+      let channel = this.channels.get(sendChannelName);
+      if (!channel) {
+        channel = this.client.channel(`ticket:${ticketId}`);
+        channel.subscribe();
+        this.channels.set(sendChannelName, channel);
+      }
+      await channel.send({
+        type: "broadcast",
+        event: "typing",
+        payload: {
+          customer_id: this.options.customerId,
+          customer_name: this.options.customerName,
+          is_typing: isTyping
+        }
+      });
+    } catch {
+    }
+  }
+  removeChannel(name) {
+    const existing = this.channels.get(name);
+    if (existing && this.client) {
+      this.client.removeChannel(existing);
+      this.channels.delete(name);
+    }
+  }
+  /** Clean up all channels and timers. */
+  destroy() {
+    for (const timer of this.typingClearTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.typingClearTimers.clear();
+    this.lastTypingSentAt.clear();
+    for (const [name] of this.channels) {
+      this.removeChannel(name);
+    }
+    this.channels.clear();
+    this.client = null;
+  }
+};
+
 // src/chat/index.ts
 var DEFAULT_BASE_URL = "https://app.cstar.help";
 var DEFAULT_POLLING_INTERVAL = 3e3;
@@ -5,10 +245,17 @@ var ChatClient = class {
   constructor(config) {
     this.sessionToken = null;
     this.teamId = null;
+    this.customerId = null;
     this.pollingTimers = /* @__PURE__ */ new Map();
+    this.realtimeManager = null;
+    this.presenceManager = null;
+    this.realtimeReady = false;
+    this.realtimeInitPromise = null;
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.teamSlug = config.teamSlug;
     this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
+    this.supabaseUrl = config.supabaseUrl;
+    this.supabaseAnonKey = config.supabaseAnonKey;
     this.conversations = new ConversationsApi(this);
     this.messages = new MessagesApi(this);
   }
@@ -16,6 +263,9 @@ var ChatClient = class {
    * Identify a customer using HMAC signature verification.
    * Must be called before accessing conversations or messages.
    *
+   * If `supabaseUrl` and `supabaseAnonKey` were provided in the config,
+   * this will also initialize real-time subscriptions (non-blocking).
+   *
    * @param customer - Customer identity fields
    * @param signature - HMAC-SHA256 hex signature of the signed fields
    * @param testMode - Whether to use test mode (relaxed timestamp validation)
@@ -34,40 +284,27 @@ var ChatClient = class {
       }
     );
     this.sessionToken = response.data.sessionToken;
+    this.teamId = response.data.teamId;
+    this.customerId = response.data.customer.id;
+    if (this.supabaseUrl && this.supabaseAnonKey) {
+      this.realtimeInitPromise = this.initRealtime(
+        response.data.customer.id,
+        response.data.customer.name || customer.name || customer.email
+      );
+    }
     return response.data;
   }
   /**
    * Subscribe to new messages on a conversation.
-   * Falls back to polling when Supabase Realtime is not available.
+   * Uses Supabase Realtime (Postgres Changes) when available, falls back to polling.
    *
    * @returns Unsubscribe function
    */
   onMessage(ticketId, callback) {
-    let lastMessageId = null;
-    const poll = async () => {
-      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);
-            }
-          }
-          lastMessageId = latest.id;
-        }
-      } catch {
-      }
-    };
-    poll();
-    const timer = setInterval(poll, this.pollingInterval);
-    this.pollingTimers.set(ticketId, timer);
-    return () => {
-      clearInterval(timer);
-      this.pollingTimers.delete(ticketId);
-    };
+    if (this.realtimeReady && this.realtimeManager) {
+      return this.realtimeManager.subscribeToMessages(ticketId, callback);
+    }
+    return this.pollMessages(ticketId, callback);
   }
   /**
    * Subscribe to typing indicator events.
@@ -75,17 +312,41 @@ var ChatClient = class {
    *
    * @returns Unsubscribe function
    */
-  onTyping(_ticketId, _callback) {
+  onTyping(ticketId, callback) {
+    if (this.realtimeReady && this.presenceManager) {
+      return this.presenceManager.subscribeToTyping(ticketId, callback);
+    }
     return () => {
     };
   }
+  /**
+   * Send a customer typing indicator (requires realtime).
+   * No-op if realtime is not available.
+   */
+  async sendTyping(ticketId, isTyping) {
+    if (this.presenceManager) {
+      await this.presenceManager.sendTyping(ticketId, isTyping);
+    }
+  }
   /** Disconnect all subscriptions and clean up. */
   disconnect() {
+    if (this.realtimeManager) {
+      this.realtimeManager.destroy();
+      this.realtimeManager = null;
+    }
+    if (this.presenceManager) {
+      this.presenceManager.destroy();
+      this.presenceManager = null;
+    }
+    this.realtimeReady = false;
+    this.realtimeInitPromise = null;
     for (const timer of this.pollingTimers.values()) {
       clearInterval(timer);
     }
     this.pollingTimers.clear();
     this.sessionToken = null;
+    this.teamId = null;
+    this.customerId = null;
   }
   /** @internal Make an authenticated request to the widget API. */
   async fetch(path, options) {
@@ -115,6 +376,72 @@ var ChatClient = class {
   setTeamId(teamId) {
     this.teamId = teamId;
   }
+  /** @internal Wait for realtime to be initialized (for testing). */
+  async waitForRealtime() {
+    if (this.realtimeInitPromise) {
+      await this.realtimeInitPromise;
+    }
+  }
+  async initRealtime(customerId, customerName) {
+    try {
+      this.realtimeManager = new RealtimeManager({
+        supabaseUrl: this.supabaseUrl,
+        supabaseAnonKey: this.supabaseAnonKey,
+        fetchToken: () => this.fetchRealtimeToken()
+      });
+      const ready = await this.realtimeManager.init();
+      if (ready) {
+        this.realtimeReady = true;
+        this.presenceManager = new PresenceManager({
+          customerId,
+          customerName
+        });
+        const client = this.realtimeManager.getClient();
+        if (client) {
+          this.presenceManager.setClient(client);
+        }
+      }
+    } catch {
+      this.realtimeReady = false;
+    }
+  }
+  async fetchRealtimeToken() {
+    const response = await this.fetch(
+      "/api/widget/realtime-token",
+      {
+        method: "POST",
+        body: { teamId: this.teamId }
+      }
+    );
+    return response.data;
+  }
+  pollMessages(ticketId, callback) {
+    let lastMessageId = null;
+    const poll = async () => {
+      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);
+            }
+          }
+          lastMessageId = latest.id;
+        }
+      } catch {
+      }
+    };
+    poll();
+    const timer = setInterval(poll, this.pollingInterval);
+    this.pollingTimers.set(ticketId, timer);
+    return () => {
+      clearInterval(timer);
+      this.pollingTimers.delete(ticketId);
+    };
+  }
   buildUrl(path, query) {
     const base = `${this.baseUrl}${path}`;
     if (!query) return base;