@cstar.help/js 0.11.0 → 0.12.1

package/README.md

@@ -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
 );
+```
 
-// List tickets
-const { tickets } = await chat.tickets.list();
+### 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);
+```
+
+### 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/auth/index.cjs

@@ -40,22 +40,22 @@ var AuthClient = class {
    */
   async signup(params) {
     const response = await this.fetch(
-      "/widget/api/auth/signup",
+      "/api/widget/auth/signup",
       {
         method: "POST",
         body: {
-          team_id: this.teamSlug,
+          teamId: this.teamSlug,
           email: params.email,
           password: params.password,
           name: params.name
         }
       }
     );
-    if ("access_token" in response && response.access_token && response.customer) {
+    if ("accessToken" in response && response.accessToken && response.customer) {
       this.session = {
         customer: response.customer,
-        accessToken: response.access_token,
-        refreshToken: response.refresh_token
+        accessToken: response.accessToken,
+        refreshToken: response.refreshToken
       };
     }
     return response;
@@ -69,19 +69,19 @@ var AuthClient = class {
    * @throws Error on invalid credentials, unconfirmed email, or server error
    */
   async login(params) {
-    const response = await this.fetch("/widget/api/auth/login", {
+    const response = await this.fetch("/api/widget/auth/login", {
       method: "POST",
       body: {
-        team_id: this.teamSlug,
+        teamId: this.teamSlug,
         email: params.email,
         password: params.password
       }
     });
-    if (response.access_token && response.customer) {
+    if (response.accessToken && response.customer) {
       this.session = {
         customer: response.customer,
-        accessToken: response.access_token,
-        refreshToken: response.refresh_token
+        accessToken: response.accessToken,
+        refreshToken: response.refreshToken
       };
     }
     return response;

package/dist/auth/index.d.cts

@@ -24,9 +24,9 @@ interface SignupParams {
 interface SignupResult {
     customer: AuthCustomer;
     /** Access token for authenticated requests. Null if email confirmation is required. */
-    access_token: string | null;
+    accessToken: string | null;
     /** Refresh token for renewing the session. Null if email confirmation is required. */
-    refresh_token: string | null;
+    refreshToken: string | null;
 }
 /** Response when email confirmation is required after signup. */
 interface SignupConfirmationResult {
@@ -45,9 +45,9 @@ interface LoginParams {
 interface LoginResult {
     customer: AuthCustomer;
     /** Access token for authenticated requests. */
-    access_token: string | null;
+    accessToken: string | null;
     /** Refresh token for renewing the session. */
-    refresh_token: string | null;
+    refreshToken: string | null;
 }
 /** Stored session with tokens and customer identity. */
 interface AuthSession {

package/dist/auth/index.d.ts

@@ -24,9 +24,9 @@ interface SignupParams {
 interface SignupResult {
     customer: AuthCustomer;
     /** Access token for authenticated requests. Null if email confirmation is required. */
-    access_token: string | null;
+    accessToken: string | null;
     /** Refresh token for renewing the session. Null if email confirmation is required. */
-    refresh_token: string | null;
+    refreshToken: string | null;
 }
 /** Response when email confirmation is required after signup. */
 interface SignupConfirmationResult {
@@ -45,9 +45,9 @@ interface LoginParams {
 interface LoginResult {
     customer: AuthCustomer;
     /** Access token for authenticated requests. */
-    access_token: string | null;
+    accessToken: string | null;
     /** Refresh token for renewing the session. */
-    refresh_token: string | null;
+    refreshToken: string | null;
 }
 /** Stored session with tokens and customer identity. */
 interface AuthSession {

package/dist/auth/index.js

@@ -16,22 +16,22 @@ var AuthClient = class {
    */
   async signup(params) {
     const response = await this.fetch(
-      "/widget/api/auth/signup",
+      "/api/widget/auth/signup",
       {
         method: "POST",
         body: {
-          team_id: this.teamSlug,
+          teamId: this.teamSlug,
           email: params.email,
           password: params.password,
           name: params.name
         }
       }
     );
-    if ("access_token" in response && response.access_token && response.customer) {
+    if ("accessToken" in response && response.accessToken && response.customer) {
       this.session = {
         customer: response.customer,
-        accessToken: response.access_token,
-        refreshToken: response.refresh_token
+        accessToken: response.accessToken,
+        refreshToken: response.refreshToken
       };
     }
     return response;
@@ -45,19 +45,19 @@ var AuthClient = class {
    * @throws Error on invalid credentials, unconfirmed email, or server error
    */
   async login(params) {
-    const response = await this.fetch("/widget/api/auth/login", {
+    const response = await this.fetch("/api/widget/auth/login", {
       method: "POST",
       body: {
-        team_id: this.teamSlug,
+        teamId: this.teamSlug,
         email: params.email,
         password: params.password
       }
     });
-    if (response.access_token && response.customer) {
+    if (response.accessToken && response.customer) {
       this.session = {
         customer: response.customer,
-        accessToken: response.access_token,
-        refreshToken: response.refresh_token
+        accessToken: response.accessToken,
+        refreshToken: response.refreshToken
       };
     }
     return response;

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);
 
@@ -134,6 +139,14 @@ var RealtimeManager = class {
   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;
@@ -275,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;
@@ -283,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;
@@ -331,6 +382,70 @@ var ChatClient = class {
     }
     return response.data;
   }
+  /**
+   * 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.
@@ -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;
@@ -700,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
 });