@cstar.help/js 0.1.0 → 0.2.0

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;
@@ -149,17 +476,14 @@ var ConversationsApi = class {
   /** Create a new conversation (ticket). */
   async create(params) {
     const teamId = this.chat.getTeamId();
-    const response = await this.chat.fetch(
-      "/api/widget/tickets",
-      {
-        method: "POST",
-        body: {
-          teamId,
-          subject: params.subject,
-          message: params.message
-        }
+    const response = await this.chat.fetch("/api/widget/tickets", {
+      method: "POST",
+      body: {
+        teamId,
+        subject: params.subject,
+        message: params.message
       }
-    );
+    });
     return {
       id: response.data.id,
       ticketNumber: "",

package/dist/index.cjs

@@ -97,7 +97,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.0";
 var DEFAULT_BASE_URL = "https://app.cstar.help";
 var DEFAULT_API_VERSION = "2026-03-01";
 var DEFAULT_MAX_RETRIES = 3;
@@ -179,7 +179,7 @@ var HttpClient = class {
   }
   buildHeaders(idempotencyKey) {
     const headers = {
-      "Authorization": `Bearer ${this.config.apiKey}`,
+      Authorization: `Bearer ${this.config.apiKey}`,
       "Content-Type": "application/json",
       "CStar-Version": this.config.version,
       "User-Agent": `@cstar.help/js/${SDK_VERSION}`
@@ -235,10 +235,7 @@ var BaseResource = class {
   }
   /** Delete a resource by ID. */
   async del(id) {
-    return this.client.request(
-      "DELETE",
-      `${this.basePath}/${id}`
-    );
+    return this.client.request("DELETE", `${this.basePath}/${id}`);
   }
   /**
    * Auto-paginating async iterator that yields every item across all pages.
@@ -285,21 +282,14 @@ var TicketMessagesResource = class {
   }
   /** List all messages on a ticket. */
   async list(ticketId) {
-    return this.client.request(
-      "GET",
-      `/tickets/${ticketId}/messages`
-    );
+    return this.client.request("GET", `/tickets/${ticketId}/messages`);
   }
   /** Add a message to a ticket. */
   async create(ticketId, params, options) {
-    return this.client.request(
-      "POST",
-      `/tickets/${ticketId}/messages`,
-      {
-        body: params,
-        idempotencyKey: options?.idempotencyKey
-      }
-    );
+    return this.client.request("POST", `/tickets/${ticketId}/messages`, {
+      body: params,
+      idempotencyKey: options?.idempotencyKey
+    });
   }
 };
 var TicketsResource = class extends BaseResource {

package/dist/index.js

@@ -65,7 +65,7 @@ function parseError(statusCode, body, retryAfter) {
 }
 
 // src/client.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.0";
 var DEFAULT_BASE_URL = "https://app.cstar.help";
 var DEFAULT_API_VERSION = "2026-03-01";
 var DEFAULT_MAX_RETRIES = 3;
@@ -147,7 +147,7 @@ var HttpClient = class {
   }
   buildHeaders(idempotencyKey) {
     const headers = {
-      "Authorization": `Bearer ${this.config.apiKey}`,
+      Authorization: `Bearer ${this.config.apiKey}`,
       "Content-Type": "application/json",
       "CStar-Version": this.config.version,
       "User-Agent": `@cstar.help/js/${SDK_VERSION}`
@@ -203,10 +203,7 @@ var BaseResource = class {
   }
   /** Delete a resource by ID. */
   async del(id) {
-    return this.client.request(
-      "DELETE",
-      `${this.basePath}/${id}`
-    );
+    return this.client.request("DELETE", `${this.basePath}/${id}`);
   }
   /**
    * Auto-paginating async iterator that yields every item across all pages.
@@ -253,21 +250,14 @@ var TicketMessagesResource = class {
   }
   /** List all messages on a ticket. */
   async list(ticketId) {
-    return this.client.request(
-      "GET",
-      `/tickets/${ticketId}/messages`
-    );
+    return this.client.request("GET", `/tickets/${ticketId}/messages`);
   }
   /** Add a message to a ticket. */
   async create(ticketId, params, options) {
-    return this.client.request(
-      "POST",
-      `/tickets/${ticketId}/messages`,
-      {
-        body: params,
-        idempotencyKey: options?.idempotencyKey
-      }
-    );
+    return this.client.request("POST", `/tickets/${ticketId}/messages`, {
+      body: params,
+      idempotencyKey: options?.idempotencyKey
+    });
   }
 };
 var TicketsResource = class extends BaseResource {

package/dist/library/index.cjs

@@ -65,10 +65,24 @@ var LibraryClient = class {
       q: query
     };
     if (params?.limit) queryParams.limit = String(params.limit);
-    return this.fetch(
-      `/api/library/${this.teamSlug}/search`,
-      queryParams
-    );
+    return this.fetch(`/api/library/${this.teamSlug}/search`, queryParams);
+  }
+  /** Get the most viewed articles, sorted by view count descending. */
+  async popularArticles(limit = 5) {
+    const articles = await this.articles({ limit: 50 });
+    return articles.sort((a, b) => (b.view_count ?? 0) - (a.view_count ?? 0)).slice(0, limit);
+  }
+  /** Get aggregate stats for this knowledge base (article count, category count, total views). */
+  async stats() {
+    const [categories, articles] = await Promise.all([
+      this.categories(),
+      this.articles({ limit: 1e3 })
+    ]);
+    return {
+      totalArticles: articles.length,
+      totalCategories: categories.length,
+      totalViews: articles.reduce((sum, a) => sum + (a.view_count ?? 0), 0)
+    };
   }
   async fetch(path, query) {
     let url = `${this.baseUrl}${path}`;

package/dist/library/index.d.cts

@@ -50,6 +50,12 @@ interface LibrarySearchResult {
     count: number;
     query: string;
 }
+/** Aggregate stats for a public knowledge base. */
+interface LibraryStats {
+    totalArticles: number;
+    totalCategories: number;
+    totalViews: number;
+}
 
 /**
  * Public knowledge base client. No authentication required.
@@ -76,7 +82,11 @@ declare class LibraryClient {
      * Returns matching articles with relevance ranking.
      */
     search(query: string, params?: LibrarySearchParams): Promise<LibrarySearchResult>;
+    /** Get the most viewed articles, sorted by view count descending. */
+    popularArticles(limit?: number): Promise<LibraryArticle[]>;
+    /** Get aggregate stats for this knowledge base (article count, category count, total views). */
+    stats(): Promise<LibraryStats>;
     private fetch;
 }
 
-export { type Category, type LibraryArticle, type LibraryArticleListParams, LibraryClient, type LibraryConfig, type LibrarySearchParams, type LibrarySearchResult };
+export { type Category, type LibraryArticle, type LibraryArticleListParams, LibraryClient, type LibraryConfig, type LibrarySearchParams, type LibrarySearchResult, type LibraryStats };

package/dist/library/index.d.ts

@@ -50,6 +50,12 @@ interface LibrarySearchResult {
     count: number;
     query: string;
 }
+/** Aggregate stats for a public knowledge base. */
+interface LibraryStats {
+    totalArticles: number;
+    totalCategories: number;
+    totalViews: number;
+}
 
 /**
  * Public knowledge base client. No authentication required.
@@ -76,7 +82,11 @@ declare class LibraryClient {
      * Returns matching articles with relevance ranking.
      */
     search(query: string, params?: LibrarySearchParams): Promise<LibrarySearchResult>;
+    /** Get the most viewed articles, sorted by view count descending. */
+    popularArticles(limit?: number): Promise<LibraryArticle[]>;
+    /** Get aggregate stats for this knowledge base (article count, category count, total views). */
+    stats(): Promise<LibraryStats>;
     private fetch;
 }
 
-export { type Category, type LibraryArticle, type LibraryArticleListParams, LibraryClient, type LibraryConfig, type LibrarySearchParams, type LibrarySearchResult };
+export { type Category, type LibraryArticle, type LibraryArticleListParams, LibraryClient, type LibraryConfig, type LibrarySearchParams, type LibrarySearchResult, type LibraryStats };

package/dist/library/index.js

@@ -41,10 +41,24 @@ var LibraryClient = class {
       q: query
     };
     if (params?.limit) queryParams.limit = String(params.limit);
-    return this.fetch(
-      `/api/library/${this.teamSlug}/search`,
-      queryParams
-    );
+    return this.fetch(`/api/library/${this.teamSlug}/search`, queryParams);
+  }
+  /** Get the most viewed articles, sorted by view count descending. */
+  async popularArticles(limit = 5) {
+    const articles = await this.articles({ limit: 50 });
+    return articles.sort((a, b) => (b.view_count ?? 0) - (a.view_count ?? 0)).slice(0, limit);
+  }
+  /** Get aggregate stats for this knowledge base (article count, category count, total views). */
+  async stats() {
+    const [categories, articles] = await Promise.all([
+      this.categories(),
+      this.articles({ limit: 1e3 })
+    ]);
+    return {
+      totalArticles: articles.length,
+      totalCategories: categories.length,
+      totalViews: articles.reduce((sum, a) => sum + (a.view_count ?? 0), 0)
+    };
   }
   async fetch(path, query) {
     let url = `${this.baseUrl}${path}`;