@chatsystem/client 1.1.82 → 1.1.83

package/dist/index.d.ts

@@ -1,12 +1,59 @@
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 
+/**
+ * Embeds the ChatSystem chatbot in a React application.
+ *
+ * Identity integration is optional. Without `identityProvider`, all existing
+ * anonymous behavior remains unchanged.
+ */
 export declare function App({ cssHref, appToken, agentId, displayMode, shouldDisplayLogs, ...contentProps }: AppProps): JSX_2.Element;
 
-declare type AppProps = {
+/** Public configuration for the ChatSystem React widget. */
+export declare type AppProps = {
+    /**
+     * Public ChatSystem app token identifying the customer installation.
+     * This is not a secret and does not authenticate the end user.
+     */
     appToken: string;
+    /** Optional agent to use instead of the company's default agent. */
     agentId?: number;
+    /** Displays either the launcher widget or the inline chatbox. */
     displayMode?: DisplayModesTypes;
+    /** Enables diagnostic widget logs. Keep disabled in normal production use. */
     shouldDisplayLogs?: boolean;
+    /**
+     * Optional bridge to the host website's existing authenticated session.
+     *
+     * Implement this in the customer's frontend integration code, normally next
+     * to the component that renders `<App />`. Its `getToken()` method should
+     * call one same-origin customer endpoint, such as
+     * `/api/chatsystem/identity`. That customer endpoint authenticates the user
+     * with the host's existing cookie/session/SSO and returns a short-lived
+     * ChatSystem widget identity JWT.
+     *
+     * Never return the company API key, the host's primary access token, session
+     * cookie, or SSO token. The widget keeps the returned ChatSystem JWT in
+     * memory only. Omit this property to keep the widget fully anonymous.
+     *
+     * @example
+     * ```tsx
+     * <App
+     *   appToken="public-app-token"
+     *   identityProvider={{
+     *     getToken: async ({ interactive }) => {
+     *       const response = await fetch('/api/chatsystem/identity', {
+     *         credentials: 'include',
+     *       });
+     *       if (!response.ok) return null;
+     *       return (await response.json()).token ?? null;
+     *     },
+     *     subscribe: (onIdentityChanged) =>
+     *       customerAuth.onAuthStateChanged(onIdentityChanged),
+     *   }}
+     * />
+     * ```
+     */
+    identityProvider?: WidgetIdentityProvider;
 } & ShadowControls;
 
 declare enum DisplayModeEnum {
@@ -14,10 +61,77 @@ declare enum DisplayModeEnum {
     CHATBOX = "chatbox"
 }
 
-declare type DisplayModesTypes = `${DisplayModeEnum}`;
+export declare type DisplayModesTypes = `${DisplayModeEnum}`;
 
-declare type ShadowControls = {
+/** Controls how the widget's Shadow DOM receives its stylesheet. */
+export declare type ShadowControls = {
+    /**
+     * Optional URL for a prebuilt widget stylesheet. When omitted, the package
+     * injects its bundled CSS into the Shadow DOM.
+     */
     cssHref?: string;
 };
 
+/**
+ * Connects the ChatSystem widget to the host website's existing authentication
+ * system without exposing passwords, cookies, company API keys, or primary
+ * access tokens to ChatSystem.
+ *
+ * The customer implements this object in frontend integration code. The
+ * customer needs only one new same-origin backend endpoint that validates its
+ * existing session and obtains a short-lived widget identity JWT from
+ * ChatSystem.
+ */
+export declare type WidgetIdentityProvider = {
+    /**
+     * Returns a short-lived ChatSystem widget identity JWT, or `null` when the
+     * visitor is not authenticated.
+     *
+     * This method may be called when the widget opens and before a prompt when a
+     * token is missing or near expiry. It should call the customer's same-origin
+     * identity endpoint with the host session, usually using
+     * `credentials: 'include'`.
+     *
+     * When `request.interactive` is `false`, do not display login UI. When it is
+     * `true`, the implementation may open the host's existing login modal,
+     * popup, SSO flow, or login route and retry the same identity endpoint.
+     *
+     * Never return a company API key or the host's primary authentication token.
+     */
+    getToken(request: WidgetIdentityRequest): Promise<string | null | undefined>;
+    /**
+     * Registers the widget's identity-change listener.
+     *
+     * The host must invoke `onIdentityChanged` after its own login, logout, or
+     * account switch has completed. On logout, destroy the host session first,
+     * then notify the widget. The widget will clear its in-memory JWT and perform
+     * a new silent lookup.
+     *
+     * Return an unsubscribe function that removes the listener. If the host's
+     * authentication SDK already exposes an auth-state subscription, return its
+     * cleanup function directly.
+     */
+    subscribe?(onIdentityChanged: () => void): () => void;
+};
+
+/** Context supplied whenever the widget asks the host for delegated identity. */
+export declare type WidgetIdentityRequest = {
+    /**
+     * When `false`, the provider must perform a silent lookup and must not open
+     * login UI. When `true`, it may invoke the host's existing login or SSO UI
+     * before retrying the same identity endpoint.
+     *
+     * The current identity-only widget requests silent lookup. Interactive mode
+     * is reserved for the forthcoming reconnect/protected-tool flow.
+     */
+    interactive: boolean;
+    /** Optional user-facing reason why authentication is being requested. */
+    reason?: string;
+    /**
+     * Capabilities required by the pending operation. The host backend remains
+     * responsible for deriving and authorizing the capabilities it grants.
+     */
+    requiredCapabilities?: string[];
+};
+
 export { }