@cstar.help/js 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 cStar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -23,8 +23,8 @@ Manage tickets, customers, articles, and webhooks with your secret API key.
 import { CStarClient } from '@cstar.help/js';
 
 const cstar = new CStarClient({
-  apiKey: 'sk_live_abc123...',
-  teamId: 'tm_your_team_id',
+	apiKey: 'sk_live_abc123...',
+	teamId: 'tm_your_team_id'
 });
 
 // List open tickets
@@ -32,8 +32,8 @@ const { data: tickets } = await cstar.tickets.list({ status: 'open' });
 
 // Create a ticket
 const { data: ticket } = await cstar.tickets.create({
-  title: 'Help with billing',
-  customerId: 'cus_abc123',
+	title: 'Help with billing',
+	customerId: 'cus_abc123'
 });
 
 // Get a customer with expanded fields
@@ -41,7 +41,7 @@ const { data: customer } = await cstar.customers.get('cus_abc123');
 
 // Auto-paginate through all tickets
 for await (const ticket of cstar.tickets.listAutoPaginating({ status: 'open' })) {
-  console.log(ticket.title);
+	console.log(ticket.title);
 }
 ```
 
@@ -56,8 +56,8 @@ const chat = new ChatClient({ teamSlug: 'acme' });
 
 // Identify the customer (HMAC signature from your server)
 await chat.identify(
-  { externalId: 'usr_123', email: 'jane@example.com', name: 'Jane', timestamp: Date.now() / 1000 },
-  hmacSignature
+	{ externalId: 'usr_123', email: 'jane@example.com', name: 'Jane', timestamp: Date.now() / 1000 },
+	hmacSignature
 );
 
 // List conversations
@@ -68,7 +68,7 @@ await chat.messages.send('tkt_abc123', 'Thanks for the help!');
 
 // Subscribe to new messages (polling)
 const unsubscribe = chat.onMessage('tkt_abc123', (message) => {
-  console.log(`${message.sender_name}: ${message.content}`);
+	console.log(`${message.sender_name}: ${message.content}`);
 });
 
 // Clean up
@@ -105,12 +105,12 @@ import { constructEvent } from '@cstar.help/js/webhook';
 const event = constructEvent(rawBody, signature, 'whsec_your_secret');
 
 switch (event.type) {
-  case 'ticket.created':
-    console.log('New ticket:', event.data.title);
-    break;
-  case 'customer.created':
-    console.log('New customer:', event.data.email);
-    break;
+	case 'ticket.created':
+		console.log('New ticket:', event.data.title);
+		break;
+	case 'customer.created':
+		console.log('New customer:', event.data.email);
+		break;
 }
 ```
 
@@ -126,24 +126,24 @@ const event = await constructEventAsync(rawBody, signature, secret);
 
 ### CStarClient
 
-| Resource | Methods |
-|----------|---------|
-| `cstar.tickets` | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
-| `cstar.tickets.messages` | `.list(ticketId)` `.create(ticketId, params)` |
-| `cstar.customers` | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
-| `cstar.articles` | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
-| `cstar.webhooks` | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.test(id)` |
+| Resource                 | Methods                                                                                         |
+| ------------------------ | ----------------------------------------------------------------------------------------------- |
+| `cstar.tickets`          | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
+| `cstar.tickets.messages` | `.list(ticketId)` `.create(ticketId, params)`                                                   |
+| `cstar.customers`        | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
+| `cstar.articles`         | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.listAutoPaginating()` |
+| `cstar.webhooks`         | `.list()` `.get(id)` `.create(params)` `.update(id, params)` `.del(id)` `.test(id)`             |
 
 ### Configuration
 
 ```typescript
 const cstar = new CStarClient({
-  apiKey: 'sk_live_...',    // Required — secret or publishable key
-  teamId: 'tm_...',         // Required — your team ID
-  baseUrl: 'https://...',   // Optional — defaults to https://app.cstar.help
-  version: '2026-03-01',    // Optional — API version header
-  maxRetries: 3,            // Optional — retry attempts for 5xx/429
-  timeout: 30000,           // Optional — request timeout in ms
+	apiKey: 'sk_live_...', // Required — secret or publishable key
+	teamId: 'tm_...', // Required — your team ID
+	baseUrl: 'https://...', // Optional — defaults to https://app.cstar.help
+	version: '2026-03-01', // Optional — API version header
+	maxRetries: 3, // Optional — retry attempts for 5xx/429
+	timeout: 30000 // Optional — request timeout in ms
 });
 ```
 
@@ -154,8 +154,8 @@ Test mode is auto-detected from your API key prefix:
 ```typescript
 // Uses test data — no real customers affected
 const cstar = new CStarClient({
-  apiKey: 'sk_test_abc123...',
-  teamId: 'tm_your_team_id',
+	apiKey: 'sk_test_abc123...',
+	teamId: 'tm_your_team_id'
 });
 
 console.log(cstar.isTestMode); // true
@@ -169,15 +169,15 @@ All API errors throw typed exceptions:
 import { CStarError, CStarNotFoundError, CStarValidationError } from '@cstar.help/js';
 
 try {
-  await cstar.tickets.get('tkt_nonexistent');
+	await cstar.tickets.get('tkt_nonexistent');
 } catch (err) {
-  if (err instanceof CStarNotFoundError) {
-    console.log('Ticket not found:', err.message);
-  } else if (err instanceof CStarValidationError) {
-    console.log('Invalid param:', err.param);
-  } else if (err instanceof CStarError) {
-    console.log('API error:', err.code, err.statusCode);
-  }
+	if (err instanceof CStarNotFoundError) {
+		console.log('Ticket not found:', err.message);
+	} else if (err instanceof CStarValidationError) {
+		console.log('Invalid param:', err.param);
+	} else if (err instanceof CStarError) {
+		console.log('API error:', err.code, err.statusCode);
+	}
 }
 ```
 
@@ -187,8 +187,8 @@ Safely retry create operations:
 
 ```typescript
 const { data: ticket } = await cstar.tickets.create(
-  { title: 'Billing issue', customerId: 'cus_abc' },
-  { idempotencyKey: 'create-billing-issue-usr123' }
+	{ title: 'Billing issue', customerId: 'cus_abc' },
+	{ idempotencyKey: 'create-billing-issue-usr123' }
 );
 ```
 

package/dist/chat/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/chat/index.ts
@@ -23,16 +33,265 @@ __export(chat_exports, {
   ChatClient: () => ChatClient
 });
 module.exports = __toCommonJS(chat_exports);
+
+// 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;
 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);
   }
@@ -40,6 +299,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)
@@ -58,40 +320,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.
@@ -99,17 +348,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) {
@@ -139,6 +412,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;