@chatsystem/client 1.2.5 → 1.3.1

package/dist/index.d.ts

@@ -1,73 +1,18 @@
 import { CompanySettingsDTO } from '@chatsystem/shared';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { ReactNode } from 'react';
 
 /**
- * Embeds the ChatSystem chatbot in a React application.
+ * Embeds one ChatSystem widget in a React application.
  *
- * Identity integration is optional. Without `identityProvider`, all existing
- * anonymous behavior remains unchanged.
+ * This remains the recommended API for a single visual widget. Use
+ * `WidgetRuntime` with several `WidgetView` children only when the same Agent
+ * conversation must be visible in several layouts on one page.
  */
-export declare function App({ cssHref, appToken, agentId, displayMode, shouldDisplayLogs, ...contentProps }: AppProps): JSX_2.Element;
+export declare function App({ cssHref, displayMode, appToken, agentId, shouldDisplayLogs, apiUrl, identityProvider, runtimeAdapter, }: AppProps): JSX_2.Element;
 
-/** 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 ChatSystem API base URL. Omit it for the standard hosted API.
-     *
-     * This is primarily useful for internal testing and explicitly supported
-     * self-hosted deployments. HTTPS is mandatory except for localhost.
-     */
-    apiUrl?: string;
-    /**
-     * 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;
-    /**
-     * Optional alternate server boundary for first-party embedded experiences.
-     * The canonical widget still owns settings, messages, streaming and scroll.
-     */
-    runtimeAdapter?: WidgetRuntimeAdapter;
-} & ShadowControls;
+/** Public configuration for the backwards-compatible ChatSystem widget. */
+export declare type AppProps = Omit<WidgetRuntimeProps, "children"> & WidgetViewProps;
 
 /**
  * API-owned commercial presentation settings. Branding is deliberately not a
@@ -85,6 +30,7 @@ export declare type CompanySettingsWithBranding = CompanySettingsDTO & {
     };
 };
 
+/** Supported visual presentations for a ChatSystem widget view. */
 declare enum DisplayModeEnum {
     LAUNCHER = "launcher",
     CHATBOX = "chatbox"
@@ -92,14 +38,10 @@ declare enum DisplayModeEnum {
 
 export declare type DisplayModesTypes = `${DisplayModeEnum}`;
 
-/** 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.
-     */
+export declare type ShadowControls = Readonly<{
+    /** Optional URL for a prebuilt widget stylesheet. */
     cssHref?: string;
-};
+}>;
 
 /**
  * Connects the ChatSystem widget to the host website's existing authentication
@@ -163,6 +105,15 @@ export declare type WidgetIdentityRequest = {
     requiredCapabilities?: string[];
 };
 
+/**
+ * Owns one ChatSystem conversation and all of its mutable execution state.
+ *
+ * Render several `WidgetView` children to expose the same Agent conversation
+ * in different layouts. A prompt, stream or stop action remains singular and
+ * is reflected by every view inside this boundary.
+ */
+export declare function WidgetRuntime({ appToken, agentId, shouldDisplayLogs, apiUrl, identityProvider, runtimeAdapter, children, }: WidgetRuntimeProps): JSX_2.Element;
+
 /**
  * Reuses the complete ChatSystem conversation UI with a different server
  * boundary.
@@ -181,6 +132,29 @@ export declare interface WidgetRuntimeAdapter {
     onAssistantResponseCompleted?(response: Response): void | Promise<void>;
 }
 
+export declare type WidgetRuntimeProps = Readonly<{
+    /** Public ChatSystem app token identifying the customer installation. */
+    appToken: string;
+    /** Optional agent to use instead of the company's default agent. */
+    agentId?: number;
+    /** Enables diagnostic widget logs. Keep disabled in production. */
+    shouldDisplayLogs?: boolean;
+    /** Optional ChatSystem API base URL for supported custom environments. */
+    apiUrl?: string;
+    /**
+     * Optional bridge to the host website's authenticated session.
+     *
+     * Its `getToken()` implementation must call a same-origin customer endpoint
+     * that exchanges the existing host session for a short-lived ChatSystem
+     * widget identity JWT. Never expose a company API key, session cookie or the
+     * host application's own access token to this client component.
+     */
+    identityProvider?: WidgetIdentityProvider;
+    /** Optional alternate transport for first-party embedded experiences. */
+    runtimeAdapter?: WidgetRuntimeAdapter;
+    children: ReactNode;
+}>;
+
 export declare type WidgetSettingsRequest = {
     apiUrl: string;
     appToken: string;
@@ -197,4 +171,18 @@ export declare type WidgetTextPromptRequest = {
     signal: AbortSignal;
 };
 
+/**
+ * Renders one visual presentation of the surrounding `WidgetRuntime`.
+ *
+ * The Shadow DOM and launcher open state belong to this view. Conversation,
+ * loading and cancellation state remain owned by the runtime, so mounting or
+ * closing another view cannot interrupt the shared Agent response.
+ */
+export declare function WidgetView({ cssHref, displayMode, }: WidgetViewProps): JSX_2.Element;
+
+export declare type WidgetViewProps = Readonly<{
+    /** Displays either the launcher widget or the inline chatbox. */
+    displayMode?: DisplayModesTypes;
+}> & ShadowControls;
+
 export { }