@cstar.help/js 0.10.3 → 0.12.0

package/dist/chat/index.d.cts

@@ -4,13 +4,47 @@ interface ChatConfig {
     teamSlug: string;
     /** Override the base URL (defaults to https://www.cstar.help). */
     baseUrl?: string;
-    /** Supabase project URL for realtime subscriptions (optional). */
-    supabaseUrl?: string;
-    /** Supabase anon key for realtime subscriptions (optional). */
-    supabaseAnonKey?: string;
-    /** Polling interval in ms when Supabase Realtime is not available (defaults to 3000). */
+    /**
+     * Enable real-time messages and typing indicators. Defaults to true.
+     * When false, the SDK falls back to polling.
+     */
+    realtime?: boolean;
+    /** 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. */
@@ -43,14 +77,16 @@ interface IdentifyResult {
     /** Team UUID — used for realtime token requests. */
     teamId: string;
 }
-/** Response from the realtime-token endpoint. */
+/** @internal Response from the realtime-token endpoint. */
 interface RealtimeTokenResponse {
     token: string;
     expiresAt: string;
     refreshAt: string;
+    realtimeUrl: string;
+    realtimeKey: string;
 }
-/** A customer conversation (maps to a ticket). */
-interface Conversation {
+/** A ticket — a customer's support thread. */
+interface Ticket {
     id: string;
     ticketNumber: string;
     subject: string;
@@ -60,14 +96,14 @@ interface Conversation {
     updatedAt: string;
     closedAt: string | null;
 }
-/** Paginated conversation list response. */
-interface ConversationListResponse {
-    conversations: Conversation[];
+/** Paginated ticket list response. */
+interface TicketListResponse {
+    tickets: Ticket[];
     cursor: string | null;
     hasMore: boolean;
 }
-/** A message in a conversation. */
-interface WidgetMessage {
+/** A message on a ticket. */
+interface Message {
     id: string;
     content: string;
     sender: 'customer' | 'agent';
@@ -75,25 +111,30 @@ interface WidgetMessage {
     created_at: string;
     read_at: string | null;
     attachments: unknown[];
+    /** Raw AI SDK response payload for agent messages. Widgets can use this
+     * with `extractToolCallsFromPayload` to render customer-safe tool chips. */
+    payload?: Record<string, unknown> | null;
+    /** Whether this message was sent by an AI agent. */
+    is_bot?: boolean;
 }
-/** Parameters for listing conversations. */
-interface ConversationListParams {
+/** Parameters for listing tickets. */
+interface TicketListParams {
     limit?: number;
     cursor?: string;
 }
-/** Parameters for creating a new conversation. */
-interface ConversationCreateParams {
+/** Parameters for creating a new ticket. */
+interface TicketCreateParams {
     subject: string;
     message?: string;
 }
-/** Typing indicator payload from realtime subscription. */
+/** Typing indicator payload. */
 interface TypingPayload {
     agent_id: string;
     agent_name: string;
     is_typing: boolean;
 }
 /** Callback for message events. */
-type MessageCallback = (message: WidgetMessage) => void;
+type MessageCallback = (message: Message) => void;
 /** Callback for typing indicator events. */
 type TypingCallback = (payload: TypingPayload) => void;
 
@@ -180,43 +221,142 @@ 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.
  *
- * Supports real-time messages and typing indicators when `supabaseUrl`
- * and `supabaseAnonKey` are provided and `@supabase/supabase-js` is installed.
- * Falls back to polling otherwise.
+ * 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
- * const chat = new ChatClient({
- *   teamSlug: 'acme',
- *   supabaseUrl: 'https://xxx.supabase.co',
- *   supabaseAnonKey: 'eyJ...',
- * });
+ * // 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;
     private readonly teamSlug;
     private readonly pollingInterval;
-    private readonly supabaseUrl?;
-    private readonly supabaseAnonKey?;
+    private readonly realtimeEnabled;
     private sessionToken;
     private teamId;
     private customerId;
+    private authMode;
     private pollingTimers;
     private realtimeManager;
     private presenceManager;
     private realtimeReady;
     private realtimeInitPromise;
-    /** Sub-resource for managing conversations. */
-    readonly conversations: ConversationsApi;
+    /** Sub-resource for managing tickets. */
+    readonly tickets: TicketsApi;
     /** Sub-resource for managing messages. */
     readonly messages: MessagesApi;
     /** Sub-resource for community actions (create posts, vote, comment). Uses the same session as chat. */
@@ -224,10 +364,10 @@ declare class ChatClient {
     constructor(config: ChatConfig);
     /**
      * 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
@@ -235,32 +375,78 @@ declare class ChatClient {
      */
     identify(customer: IdentifyParams, signature: string, testMode?: boolean): Promise<IdentifyResult>;
     /**
-     * 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.
+     */
+    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.
      *
      * @returns Unsubscribe function
      */
     onMessage(ticketId: string, callback: MessageCallback): () => void;
     /**
      * 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
      */
     onTyping(ticketId: string, callback: TypingCallback): () => void;
     /**
-     * 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.
      */
     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. */
@@ -272,14 +458,14 @@ declare class ChatClient {
     private pollMessages;
     private buildUrl;
 }
-/** Conversations sub-resource on ChatClient. */
-declare class ConversationsApi {
+/** Tickets sub-resource on ChatClient. */
+declare class TicketsApi {
     private readonly chat;
     constructor(chat: ChatClient);
-    /** List conversations for the identified customer. */
-    list(params?: ConversationListParams): Promise<ConversationListResponse>;
-    /** Create a new conversation (ticket). */
-    create(params: ConversationCreateParams): Promise<Conversation>;
+    /** List tickets for the identified customer. */
+    list(params?: TicketListParams): Promise<TicketListResponse>;
+    /** Create a new ticket. */
+    create(params: TicketCreateParams): Promise<Ticket>;
 }
 /**
  * Community sub-resource on ChatClient.
@@ -313,10 +499,10 @@ declare class ChatCommunityApi {
 declare class MessagesApi {
     private readonly chat;
     constructor(chat: ChatClient);
-    /** List messages for a conversation. */
-    list(ticketId: string): Promise<WidgetMessage[]>;
-    /** Send a message to a conversation. */
-    send(ticketId: string, content: string): Promise<WidgetMessage>;
+    /** List messages for a ticket. */
+    list(ticketId: string): Promise<Message[]>;
+    /** Send a message to a ticket. */
+    send(ticketId: string, content: string): Promise<Message>;
 }
 
-export { ChatClient, type ChatConfig, type Conversation, type ConversationCreateParams, type ConversationListParams, type ConversationListResponse, type IdentifyParams, type IdentifyResult, type MessageCallback, type RealtimeTokenResponse, type TypingCallback, type TypingPayload, type WidgetMessage };
+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 };