@cstar.help/js 0.10.3 → 0.12.0

package/README.md

@@ -30,7 +30,7 @@ cStar has one package with **six entry points**, each designed for a different c
 
 ### The Security Model
 
-cStar uses **two key types** to control access — the same pattern as Stripe and Supabase:
+cStar uses **two key types** to control access — the same pattern as Stripe:
 
 ```
 Secret keys (sk_live_*, sk_test_*)
@@ -200,32 +200,84 @@ const { data: searchResults } = await cstar.search.query({
 
 Build custom chat experiences in the browser. Uses a publishable key — safe for frontend code.
 
+The chat client supports two authentication modes:
+
+- **HMAC** — your server signs the customer payload with the team's signing secret. Best for sites where users are already authenticated server-side.
+- **Session** — the customer signs in directly with email/password (or magic link). Best for standalone widgets and customer portals where there's no host-app session to bridge.
+
+You don't have to pick the mode up-front. The first response from any cstar endpoint includes an `X-Cstar-Auth-Mode` header, which the SDK caches; `chat.getAuthMode()` returns `'hmac'`, `'session'`, or `null` after the first call.
+
+### HMAC
+
 ```typescript
 import { ChatClient } from '@cstar.help/js/chat';
 
 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
 );
+```
+
+### Session (email/password)
+
+```typescript
+const chat = new ChatClient({ teamSlug: 'acme' });
+
+// Login with credentials — returns the customer + tokens
+const { customer, accessToken, refreshToken } = await chat.loginWithCredentials(
+	'jane@example.com',
+	'hunter2'
+);
+
+// Or rehydrate from previously stored tokens
+await chat.loginWithSession(accessToken, refreshToken);
+```
 
-// List conversations
-const { conversations } = await chat.conversations.list();
+### Once authenticated (either mode)
 
-// Send a message
+```typescript
+const { tickets } = await chat.tickets.list();
 await chat.messages.send('tkt_abc123', 'Thanks for the help!');
 
-// Subscribe to new messages
 const unsubscribe = chat.onMessage('tkt_abc123', (message) => {
 	console.log(`${message.sender_name}: ${message.content}`);
 });
 
-// Clean up
 chat.disconnect();
 ```
 
+### Typed errors
+
+Every `ChatClient` request throws a typed subclass of `ChatClientError` on failure. Each carries a `requestId` (from the `X-Request-Id` response header) so customer support can correlate against server logs.
+
+```typescript
+import {
+	ChatClientError,
+	ChatClientAuthError,
+	ChatClientRateLimitError,
+	ChatClientServerError,
+	ChatClientNetworkError
+} from '@cstar.help/js/chat';
+
+try {
+	await chat.identify(customer, signature);
+} catch (err) {
+	if (err instanceof ChatClientAuthError) {
+		// 401 / 403 — bad signature, expired token, wrong team
+	} else if (err instanceof ChatClientRateLimitError) {
+		// 429 — back off for err.retryAfter seconds
+	} else if (err instanceof ChatClientServerError) {
+		// 5xx — usually transient, retry with backoff
+	} else if (err instanceof ChatClientNetworkError) {
+		// fetch() itself failed — DNS, offline, CORS — see err.originalError
+	} else if (err instanceof ChatClientError) {
+		console.log('Error', err.code, err.statusCode, 'requestId:', err.requestId);
+	}
+}
+```
+
 ---
 
 ## Client-Side: Public Knowledge Base

package/dist/chat/index.cjs

@@ -30,7 +30,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/chat/index.ts
 var chat_exports = {};
 __export(chat_exports, {
-  ChatClient: () => ChatClient
+  ChatClient: () => ChatClient,
+  ChatClientAuthError: () => ChatClientAuthError,
+  ChatClientError: () => ChatClientError,
+  ChatClientNetworkError: () => ChatClientNetworkError,
+  ChatClientRateLimitError: () => ChatClientRateLimitError,
+  ChatClientServerError: () => ChatClientServerError
 });
 module.exports = __toCommonJS(chat_exports);
 
@@ -45,8 +50,8 @@ var RealtimeManager = class {
     this.options = options;
   }
   /**
-   * Initialize the Supabase client and authenticate with a realtime token.
-   * Returns true if successful, false if @supabase/supabase-js is unavailable.
+   * Initialize the realtime client and authenticate with a token.
+   * Returns true if successful, false if the realtime runtime is unavailable.
    */
   init() {
     if (this.initPromise) return this.initPromise;
@@ -55,15 +60,15 @@ var RealtimeManager = class {
   }
   async doInit() {
     try {
+      const tokenData = await this.options.fetchToken();
       const { createClient } = await import(
         /* webpackIgnore: true */
         "@supabase/supabase-js"
       );
-      this.client = createClient(this.options.supabaseUrl, this.options.supabaseAnonKey, {
+      this.client = createClient(tokenData.realtimeUrl, tokenData.realtimeKey, {
         auth: { persistSession: false, autoRefreshToken: false },
         realtime: { params: { eventsPerSecond: 10 } }
       });
-      const tokenData = await this.options.fetchToken();
       this.setToken(tokenData);
       return true;
     } catch {
@@ -121,7 +126,8 @@ var RealtimeManager = class {
           sender_name: row.sender_name ?? "",
           created_at: row.created_at,
           read_at: row.read_at ?? null,
-          attachments: row.attachments ?? []
+          attachments: row.attachments ?? [],
+          payload: row.payload ?? null
         };
         callback(message);
       }
@@ -129,10 +135,18 @@ var RealtimeManager = class {
     this.channels.set(channelName, channel);
     return () => this.removeChannel(channelName);
   }
-  /** Get the underlying Supabase client (for sharing with PresenceManager). */
+  /** Get the underlying realtime client (for sharing with PresenceManager). */
   getClient() {
     return this.client;
   }
+  /**
+   * The current Supabase JWT (set by init/refresh). Returned so callers can
+   * decode the `sub` claim to learn the customerId — required after a
+   * session-mode login where the SDK doesn't have customerId at hand.
+   */
+  getCurrentToken() {
+    return this.currentToken;
+  }
   /** Whether the realtime manager is initialized and has a token. */
   get isReady() {
     return this.client !== null && this.currentToken !== null;
@@ -171,7 +185,7 @@ var PresenceManager = class {
     this.typingClearTimers = /* @__PURE__ */ new Map();
     this.options = options;
   }
-  /** Set the Supabase client (shared from RealtimeManager). */
+  /** Set the realtime client (shared from RealtimeManager). */
   setClient(client) {
     this.client = client;
   }
@@ -274,6 +288,43 @@ var PresenceManager = class {
   }
 };
 
+// src/chat/errors.ts
+var ChatClientError = class extends Error {
+  constructor(message, opts) {
+    super(message);
+    this.name = "ChatClientError";
+    this.code = opts.code ?? "UNKNOWN";
+    this.statusCode = opts.statusCode;
+    this.requestId = opts.requestId ?? null;
+  }
+};
+var ChatClientAuthError = class extends ChatClientError {
+  constructor(opts) {
+    super(opts.message, opts);
+    this.name = "ChatClientAuthError";
+  }
+};
+var ChatClientRateLimitError = class extends ChatClientError {
+  constructor(opts) {
+    super(opts.message, opts);
+    this.name = "ChatClientRateLimitError";
+    this.retryAfter = opts.retryAfter ?? null;
+  }
+};
+var ChatClientServerError = class extends ChatClientError {
+  constructor(opts) {
+    super(opts.message, opts);
+    this.name = "ChatClientServerError";
+  }
+};
+var ChatClientNetworkError = class extends ChatClientError {
+  constructor(opts) {
+    super(opts.message, { code: "NETWORK_ERROR", statusCode: 0, requestId: null });
+    this.name = "ChatClientNetworkError";
+    this.originalError = opts.originalError;
+  }
+};
+
 // src/chat/index.ts
 var DEFAULT_BASE_URL = "https://www.cstar.help";
 var DEFAULT_POLLING_INTERVAL = 3e3;
@@ -282,6 +333,7 @@ var ChatClient = class {
     this.sessionToken = null;
     this.teamId = null;
     this.customerId = null;
+    this.authMode = null;
     this.pollingTimers = /* @__PURE__ */ new Map();
     this.realtimeManager = null;
     this.presenceManager = null;
@@ -290,18 +342,17 @@ var ChatClient = class {
     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.realtimeEnabled = config.realtime !== false;
+    this.tickets = new TicketsApi(this);
     this.messages = new MessagesApi(this);
     this.community = new ChatCommunityApi(this);
   }
   /**
    * Identify a customer using HMAC signature verification.
-   * Must be called before accessing conversations or messages.
+   * Must be called before accessing tickets or messages.
    *
-   * If `supabaseUrl` and `supabaseAnonKey` were provided in the config,
-   * this will also initialize real-time subscriptions (non-blocking).
+   * Real-time subscriptions are initialized automatically (non-blocking)
+   * unless `realtime: false` was passed in config.
    *
    * @param customer - Customer identity fields
    * @param signature - HMAC-SHA256 hex signature of the signed fields
@@ -323,7 +374,7 @@ var ChatClient = class {
     this.sessionToken = response.data.sessionToken;
     this.teamId = response.data.teamId;
     this.customerId = response.data.customer.id;
-    if (this.supabaseUrl && this.supabaseAnonKey) {
+    if (this.realtimeEnabled) {
       this.realtimeInitPromise = this.initRealtime(
         response.data.customer.id,
         response.data.customer.name || customer.name || customer.email
@@ -332,8 +383,72 @@ var ChatClient = class {
     return response.data;
   }
   /**
-   * Subscribe to new messages on a conversation.
-   * Uses Supabase Realtime (Postgres Changes) when available, falls back to polling.
+   * Sign in with cStar's hosted password auth. The SDK keeps the resulting
+   * Supabase access token and uses it as Bearer for every subsequent call.
+   * Real-time bootstraps automatically (same flow as `identify()`).
+   *
+   * Use this when your customers don't have a session in your app and you
+   * want cStar to handle login. For the case where your app already has a
+   * Supabase session, use `loginWithSession({ accessToken })` instead.
+   */
+  async loginWithCredentials(params) {
+    const teamId = await this.resolveTeamIdFromSlug();
+    const response = await this.fetch("/api/widget/auth/login", {
+      method: "POST",
+      body: { email: params.email, password: params.password, teamId }
+    });
+    if (!response.accessToken) {
+      throw new ChatClientAuthError({
+        message: "Login succeeded but no session was issued",
+        code: "NO_SESSION",
+        statusCode: 200,
+        requestId: null
+      });
+    }
+    await this.loginWithSession({
+      accessToken: response.accessToken,
+      teamId,
+      customerName: response.customer.name ?? response.customer.email
+    });
+    return {
+      customer: {
+        id: this.customerId ?? response.customer.id,
+        email: response.customer.email,
+        name: response.customer.name
+      },
+      teamId
+    };
+  }
+  /**
+   * Use an existing Supabase access token for widget calls. Skip the cStar
+   * login flow entirely; the SDK uses the supplied token as Bearer and
+   * bootstraps real-time the same way `identify()` does.
+   *
+   * The widget API verifies the token via the `widget-session` strategy on
+   * every request — there is no client-side validation here.
+   */
+  async loginWithSession(params) {
+    this.sessionToken = params.accessToken;
+    if (params.teamId) {
+      this.teamId = params.teamId;
+    }
+    this.authMode = "session";
+    if (this.realtimeEnabled) {
+      const customerName = params.customerName ?? "";
+      this.realtimeInitPromise = this.initRealtimeFromSession(customerName);
+    }
+  }
+  /**
+   * Returns the auth mode the client is currently using, or `null` before
+   * any authenticated call has resolved one. Useful for branching UI
+   * (e.g. to show a "Sign out" button only in session mode).
+   */
+  getAuthMode() {
+    return this.authMode;
+  }
+  /**
+   * Subscribe to new messages on a ticket.
+   * Uses real-time delivery when available, falls back to polling.
    *
    * @returns Unsubscribe function
    */
@@ -345,7 +460,7 @@ var ChatClient = class {
   }
   /**
    * Subscribe to typing indicator events.
-   * Requires Supabase Realtime — returns a no-op if unavailable.
+   * Requires real-time — returns a no-op when unavailable.
    *
    * @returns Unsubscribe function
    */
@@ -357,8 +472,8 @@ var ChatClient = class {
     };
   }
   /**
-   * Send a customer typing indicator (requires realtime).
-   * No-op if realtime is not available.
+   * Send a customer typing indicator (requires real-time).
+   * No-op when real-time is unavailable.
    */
   async sendTyping(ticketId, isTyping) {
     if (this.presenceManager) {
@@ -384,8 +499,20 @@ var ChatClient = class {
     this.sessionToken = null;
     this.teamId = null;
     this.customerId = null;
+    this.authMode = null;
   }
-  /** @internal Make an authenticated request to the widget API. */
+  /**
+   * @internal Make an authenticated request to the widget API.
+   *
+   * On any non-2xx response, throws a typed subclass of `ChatClientError`
+   * (`ChatClientAuthError`, `ChatClientRateLimitError`, etc.) so consumers
+   * can branch on error class instead of parsing message strings.
+   *
+   * On the way out, reads the `X-Cstar-Auth-Mode` response header (set by
+   * widgetHandler on every response) and caches it on the client. After
+   * the first authenticated round-trip, `getAuthMode()` returns the
+   * server-confirmed mode.
+   */
   async fetch(path, options) {
     const url = this.buildUrl(path, options.query);
     const headers = {
@@ -394,17 +521,104 @@ var ChatClient = class {
     if (this.sessionToken) {
       headers["Authorization"] = `Bearer ${this.sessionToken}`;
     }
-    const response = await globalThis.fetch(url, {
-      method: options.method,
-      headers,
-      body: options.body ? JSON.stringify(options.body) : void 0
-    });
+    let response;
+    try {
+      response = await globalThis.fetch(url, {
+        method: options.method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : void 0
+      });
+    } catch (networkErr) {
+      throw new ChatClientNetworkError({
+        message: networkErr instanceof Error ? networkErr.message : "Network request failed",
+        originalError: networkErr
+      });
+    }
+    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") {
+      this.authMode = headerMode;
+    }
+    const requestId = responseHeaders?.get("X-Request-Id") ?? null;
     if (!response.ok) {
-      const errorBody = await response.json().catch(() => ({ error: { message: "Request failed" } }));
-      throw new Error(errorBody.error?.message ?? `Widget API error: ${response.status}`);
+      const errorBody = await response.json().catch(() => ({ error: { code: "UNKNOWN", message: "Request failed" } }));
+      const code = errorBody.error?.code ?? "UNKNOWN";
+      const message = errorBody.error?.message ?? `Widget API error: ${response.status}`;
+      if (response.status === 401 || response.status === 403) {
+        throw new ChatClientAuthError({
+          message,
+          code,
+          statusCode: response.status,
+          requestId
+        });
+      }
+      if (response.status === 429) {
+        const retryAfterHeader = responseHeaders?.get("Retry-After") ?? null;
+        const retryAfter = retryAfterHeader ? parseInt(retryAfterHeader, 10) : null;
+        throw new ChatClientRateLimitError({
+          message,
+          code,
+          statusCode: response.status,
+          requestId,
+          retryAfter: Number.isFinite(retryAfter ?? NaN) ? retryAfter : null
+        });
+      }
+      if (response.status >= 500) {
+        throw new ChatClientServerError({
+          message,
+          code,
+          statusCode: response.status,
+          requestId
+        });
+      }
+      throw new ChatClientError(message, {
+        code,
+        statusCode: response.status,
+        requestId
+      });
     }
     return response.json();
   }
+  /**
+   * Look up the team UUID from the configured `teamSlug`. Used by
+   * `loginWithCredentials`. HMAC integrators (`identify()`) never hit
+   * this path — verify-identity accepts the slug directly.
+   *
+   * @internal
+   */
+  async resolveTeamIdFromSlug() {
+    const response = await this.fetch(
+      "/api/widget/team-by-slug",
+      {
+        method: "GET",
+        query: { teamSlug: this.teamSlug }
+      }
+    );
+    return response.data.teamId;
+  }
+  /** @internal Bootstrap realtime from a session login (no precomputed customerId). */
+  async initRealtimeFromSession(customerName) {
+    try {
+      this.realtimeManager = new RealtimeManager({
+        fetchToken: () => this.fetchRealtimeToken()
+      });
+      const ready = await this.realtimeManager.init();
+      if (!ready) return;
+      this.realtimeReady = true;
+      const token = this.realtimeManager.getCurrentToken();
+      const customerId = token ? decodeJwtSub(token) : null;
+      if (customerId) {
+        this.customerId = customerId;
+        this.presenceManager = new PresenceManager({ customerId, customerName });
+        const client = this.realtimeManager.getClient();
+        if (client) {
+          this.presenceManager.setClient(client);
+        }
+      }
+    } catch {
+      this.realtimeReady = false;
+    }
+  }
   /** @internal Get the stored team ID for requests that need it. */
   getTeamId() {
     return this.teamId;
@@ -422,8 +636,6 @@ var ChatClient = class {
   async initRealtime(customerId, customerName) {
     try {
       this.realtimeManager = new RealtimeManager({
-        supabaseUrl: this.supabaseUrl,
-        supabaseAnonKey: this.supabaseAnonKey,
         fetchToken: () => this.fetchRealtimeToken()
       });
       const ready = await this.realtimeManager.init();
@@ -490,28 +702,29 @@ var ChatClient = class {
     return qs ? `${base}?${qs}` : base;
   }
 };
-var ConversationsApi = class {
+var TicketsApi = class {
   constructor(chat) {
     this.chat = chat;
   }
-  /** List conversations for the identified customer. */
+  /** List tickets for the identified customer. */
   async list(params) {
     const teamId = this.chat.getTeamId();
     if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
-    const response = await this.chat.fetch(
-      "/api/widget/conversations",
-      {
-        method: "GET",
-        query: {
-          teamId,
-          limit: params?.limit?.toString(),
-          cursor: params?.cursor
-        }
+    const response = await this.chat.fetch("/api/widget/conversations", {
+      method: "GET",
+      query: {
+        teamId,
+        limit: params?.limit?.toString(),
+        cursor: params?.cursor
       }
-    );
-    return response.data;
+    });
+    return {
+      tickets: response.data.tickets ?? response.data.conversations ?? [],
+      cursor: response.data.cursor,
+      hasMore: response.data.hasMore
+    };
   }
-  /** Create a new conversation (ticket). */
+  /** Create a new ticket. */
   async create(params) {
     const teamId = this.chat.getTeamId();
     if (!teamId) throw new Error("Not identified. Call chat.identify() first.");
@@ -669,7 +882,7 @@ var MessagesApi = class {
   constructor(chat) {
     this.chat = chat;
   }
-  /** List messages for a conversation. */
+  /** List messages for a ticket. */
   async list(ticketId) {
     const teamId = this.chat.getTeamId();
     const response = await this.chat.fetch(
@@ -684,7 +897,7 @@ var MessagesApi = class {
     );
     return response.data.messages;
   }
-  /** Send a message to a conversation. */
+  /** Send a message to a ticket. */
   async send(ticketId, content) {
     const teamId = this.chat.getTeamId();
     const response = await this.chat.fetch(
@@ -701,7 +914,26 @@ var MessagesApi = class {
     return response.data.message;
   }
 };
+function decodeJwtSub(jwt) {
+  try {
+    const parts = jwt.split(".");
+    if (parts.length !== 3) return null;
+    const payloadB64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = payloadB64 + "=".repeat((4 - payloadB64.length % 4) % 4);
+    const payload = JSON.parse(
+      typeof atob === "function" ? atob(padded) : Buffer.from(padded, "base64").toString("utf-8")
+    );
+    return typeof payload.sub === "string" ? payload.sub : null;
+  } catch {
+    return null;
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  ChatClient
+  ChatClient,
+  ChatClientAuthError,
+  ChatClientError,
+  ChatClientNetworkError,
+  ChatClientRateLimitError,
+  ChatClientServerError
 });