@cstar.help/js 0.11.0 → 0.12.0

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/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
 });

package/dist/chat/index.d.cts

@@ -12,6 +12,39 @@ interface ChatConfig {
     /** Polling interval in ms when realtime is disabled or unavailable (defaults to 3000). */
     pollingInterval?: number;
 }
+/**
+ * Which auth path the client used to identify the customer. Set
+ * automatically from the `X-Cstar-Auth-Mode` response header on the first
+ * authenticated response — consumers don't declare it. Useful for runtime
+ * branching in apps that wrap multiple ChatClient instances.
+ */
+type ChatAuthMode = 'hmac' | 'session';
+/**
+ * Parameters for `loginWithSession()` — for integrators that already have
+ * a Supabase access token from their own login flow.
+ */
+interface LoginWithSessionParams {
+    /** Supabase access token (JWT). Used as Bearer for every subsequent call. */
+    accessToken: string;
+    /** Optional: the team UUID. If omitted, derived server-side from the token. */
+    teamId?: string;
+    /** Optional: a hint for the customer name (UI only — server stays authoritative). */
+    customerName?: string;
+}
+/** Parameters for `loginWithCredentials()` — email/password sign-in. */
+interface LoginWithCredentialsParams {
+    email: string;
+    password: string;
+}
+/** Result of a credentials login. The client retains the access token internally. */
+interface LoginWithCredentialsResult {
+    customer: {
+        id: string;
+        email: string;
+        name: string | null;
+    };
+    teamId: string;
+}
 /** Parameters for identifying a customer via HMAC signature verification. */
 interface IdentifyParams {
     /** Customer ID from your system. */
@@ -188,23 +221,125 @@ interface CommunityFollowResult {
     following: boolean;
 }
 
+/**
+ * Typed error classes for the cStar widget chat client.
+ *
+ * Every error thrown by `ChatClient.fetch()` is one of these subclasses,
+ * carrying an HTTP status code, a server-supplied error code, and a
+ * `requestId` (from the `X-Request-Id` response header) that customer
+ * support can match against server-side logs.
+ *
+ * Consumer code can branch on instanceof checks instead of string-matching
+ * error messages, which is a brittle pattern that breaks the moment the
+ * server tweaks its message text:
+ *
+ * ```typescript
+ * try {
+ *   await chat.identify(customer, signature);
+ * } catch (err) {
+ *   if (err instanceof ChatClientAuthError) {
+ *     // bad signature, expired token, etc.
+ *   } else if (err instanceof ChatClientRateLimitError) {
+ *     // back off and retry after err.retryAfter
+ *   }
+ * }
+ * ```
+ */
+/** Base class. Thrown by `ChatClient.fetch()` for any non-2xx response. */
+declare class ChatClientError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly requestId: string | null;
+    constructor(message: string, opts: {
+        code?: string;
+        statusCode: number;
+        requestId?: string | null;
+    });
+}
+/** 401 / 403 — auth failed (bad/expired token, wrong team, etc.). */
+declare class ChatClientAuthError extends ChatClientError {
+    constructor(opts: {
+        message: string;
+        code?: string;
+        statusCode: number;
+        requestId?: string | null;
+    });
+}
+/** 429 — too many requests. Inspect `retryAfter` (seconds) before retrying. */
+declare class ChatClientRateLimitError extends ChatClientError {
+    readonly retryAfter: number | null;
+    constructor(opts: {
+        message: string;
+        code?: string;
+        statusCode: number;
+        requestId?: string | null;
+        retryAfter?: number | null;
+    });
+}
+/** 5xx — the cStar server hit an internal error. Usually transient. */
+declare class ChatClientServerError extends ChatClientError {
+    constructor(opts: {
+        message: string;
+        code?: string;
+        statusCode: number;
+        requestId?: string | null;
+    });
+}
+/**
+ * `fetch()` itself failed before a response was received — DNS, TLS,
+ * abort, offline, CORS misconfiguration, etc. No statusCode or requestId
+ * because the request didn't reach the server. The original cause is
+ * preserved on `originalError`.
+ */
+declare class ChatClientNetworkError extends ChatClientError {
+    readonly originalError: unknown;
+    constructor(opts: {
+        message: string;
+        originalError: unknown;
+    });
+}
+
 /**
  * Customer-facing chat client for the cStar widget API.
  *
- * Real-time messages and typing indicators are enabled by default and
- * fall back to polling automatically. No additional configuration is
- * required — everything the SDK needs is fetched from the cStar API
- * after `identify()`.
+ * Supports two auth paths:
+ *
+ *   1. **HMAC** — `identify(customer, signature)` if you sign customer
+ *      claims with your team's HMAC secret ("Bring Your Own Auth").
+ *   2. **Session** — `loginWithCredentials({ email, password })` or
+ *      `loginWithSession({ accessToken })` if you use cStar's hosted
+ *      Supabase auth (or already have a Supabase session from your app).
+ *
+ * The auth mode is detected automatically from the `X-Cstar-Auth-Mode`
+ * response header on the first authenticated call — consumers don't
+ * declare it. Real-time messages and typing indicators work in both
+ * modes; the SDK opens the right channel based on which login path was
+ * used.
+ *
+ * Real-time is enabled by default and falls back to polling. No extra
+ * configuration is required — everything the SDK needs is fetched from
+ * the cStar API.
  *
  * ```typescript
+ * // HMAC mode
  * const chat = new ChatClient({ teamSlug: 'acme' });
  * await chat.identify(
  *   { externalId: 'usr_123', email: 'jane@co.com', name: 'Jane', timestamp: Date.now() / 1000 },
  *   'hmac_signature_hex'
  * );
+ *
+ * // Session mode (hosted auth)
+ * const chat = new ChatClient({ teamSlug: 'acme' });
+ * await chat.loginWithCredentials({ email: 'jane@co.com', password: 'hunter2' });
+ *
  * chat.onMessage('tkt_abc', (msg) => console.log(msg));
  * chat.onTyping('tkt_abc', ({ agent_name }) => console.log(agent_name, 'is typing'));
  * ```
+ *
+ * Errors thrown by `fetch()` (and by the public methods that wrap it)
+ * are typed: see `ChatClientAuthError`, `ChatClientRateLimitError`,
+ * `ChatClientServerError`, `ChatClientNetworkError`. Each carries
+ * `requestId` for correlating with server-side logs.
  */
 declare class ChatClient {
     private readonly baseUrl;
@@ -214,6 +349,7 @@ declare class ChatClient {
     private sessionToken;
     private teamId;
     private customerId;
+    private authMode;
     private pollingTimers;
     private realtimeManager;
     private presenceManager;
@@ -238,6 +374,31 @@ declare class ChatClient {
      * @param testMode - Whether to use test mode (relaxed timestamp validation)
      */
     identify(customer: IdentifyParams, signature: string, testMode?: boolean): Promise<IdentifyResult>;
+    /**
+     * 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.
+     */
+    loginWithCredentials(params: LoginWithCredentialsParams): Promise<LoginWithCredentialsResult>;
+    /**
+     * 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.
+     */
+    loginWithSession(params: LoginWithSessionParams): Promise<void>;
+    /**
+     * 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(): ChatAuthMode | null;
     /**
      * Subscribe to new messages on a ticket.
      * Uses real-time delivery when available, falls back to polling.
@@ -259,12 +420,33 @@ declare class ChatClient {
     sendTyping(ticketId: string, isTyping: boolean): Promise<void>;
     /** Disconnect all subscriptions and clean up. */
     disconnect(): void;
-    /** @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.
+     */
     fetch<T>(path: string, options: {
         method: string;
         body?: unknown;
         query?: Record<string, string | undefined>;
     }): Promise<T>;
+    /**
+     * 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
+     */
+    private resolveTeamIdFromSlug;
+    /** @internal Bootstrap realtime from a session login (no precomputed customerId). */
+    private initRealtimeFromSession;
     /** @internal Get the stored team ID for requests that need it. */
     getTeamId(): string | null;
     /** @internal Set team ID from identify response or other source. */
@@ -323,4 +505,4 @@ declare class MessagesApi {
     send(ticketId: string, content: string): Promise<Message>;
 }
 
-export { ChatClient, type ChatConfig, type IdentifyParams, type IdentifyResult, type Message, type MessageCallback, type RealtimeTokenResponse, type Ticket, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TypingCallback, type TypingPayload };
+export { type ChatAuthMode, ChatClient, ChatClientAuthError, ChatClientError, ChatClientNetworkError, ChatClientRateLimitError, ChatClientServerError, type ChatConfig, type IdentifyParams, type IdentifyResult, type LoginWithCredentialsParams, type LoginWithCredentialsResult, type LoginWithSessionParams, type Message, type MessageCallback, type RealtimeTokenResponse, type Ticket, type TicketCreateParams, type TicketListParams, type TicketListResponse, type TypingCallback, type TypingPayload };