@cstar.help/js 0.11.0 → 0.12.1

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

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