@cstar.help/js 0.11.0 → 0.12.0

package/dist/chat/index.d.ts

@@ -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 };

package/dist/chat/index.js

@@ -98,6 +98,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;
@@ -239,6 +247,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;
@@ -247,6 +292,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;
@@ -295,6 +341,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.
@@ -348,8 +458,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 = {
@@ -358,17 +480,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;
@@ -664,6 +873,25 @@ 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;
+  }
+}
 export {
-  ChatClient
+  ChatClient,
+  ChatClientAuthError,
+  ChatClientError,
+  ChatClientNetworkError,
+  ChatClientRateLimitError,
+  ChatClientServerError
 };