@chatsystem/client 1.1.87 → 1.2.0

package/README.md

@@ -1,24 +1,85 @@
-# Use the client
+# ChatSystem Client
 
-## Use it as a react package
+## React package
 
-- ```js
-  import { App } from "@chatsystem/client";
-  <App appToken="YOUR_TOKEN_ID" displayMode="chatbox" />;
-  ```
+```tsx
+import { App } from "@chatsystem/client";
 
-## Use it as a bundled JS script
+<App appToken="YOUR_TOKEN_ID" displayMode="chatbox" />;
+```
 
-- ```js
-  <script
-    type="text/javascript"
-    src="https://chatsystem.s3.eu-west-3.amazonaws.com/index.js"
-    data-appToken="YOUR_TOKEN_ID"
-    data-displayMode="chatbox"
-  ></script>
-  ```
+`appToken` identifies the public customer installation; it is not a user
+credential. `displayMode` accepts `launcher` or `chatbox`.
 
-### Parameters
+### Delegated user identity
 
-- appToken: your appToken, delivered on chatsystem.ai
-- displayMode?: either `bubble` if you want the bubble to display, or `chatbox` if you want to see directly the chatbox. Css is overridable.
+Pass an `identityProvider` when the customer host can recognize its existing
+user session:
+
+```tsx
+import { App, type WidgetIdentityProvider } from "@chatsystem/client";
+
+const identityProvider: WidgetIdentityProvider = {
+  async getToken({ interactive, reason, requiredCapabilities }) {
+    if (interactive) {
+      await customerAuth.ensureSignedIn({ reason, requiredCapabilities });
+    }
+
+    const response = await fetch("/api/chatsystem/identity", {
+      credentials: "include",
+    });
+    if (!response.ok) return null;
+    return (await response.json()).token ?? null;
+  },
+
+  subscribe(onIdentityChanged) {
+    return customerAuth.onAuthStateChanged(onIdentityChanged);
+  },
+};
+
+<App
+  appToken="YOUR_TOKEN_ID"
+  displayMode="chatbox"
+  identityProvider={identityProvider}
+/>;
+```
+
+The provider calls a same-origin customer endpoint. That backend endpoint reads
+the customer session and mints a short-lived ChatSystem widget JWT. Never return
+a company API key, customer access token, cookie, password, or SSO token to the
+widget.
+
+Without `identityProvider`, the widget stays anonymous and does not announce
+interactive identity-gate compatibility.
+
+### Custom API origin
+
+Hosted customers should omit `apiUrl`. Internal tests and explicitly supported
+self-hosted deployments may provide it:
+
+```tsx
+<App
+  appToken="YOUR_TOKEN_ID"
+  apiUrl="https://api.internal.example"
+  displayMode="chatbox"
+/>
+```
+
+The value is scoped to that widget instance. Credentials, query strings,
+fragments, and non-local plain HTTP origins are rejected. Localhost HTTP remains
+available for development.
+
+## Bundled JavaScript
+
+```html
+<script
+  type="text/javascript"
+  src="https://chatsystem.s3.eu-west-3.amazonaws.com/index.js"
+  data-appToken="YOUR_TOKEN_ID"
+  data-displayMode="chatbox"
+></script>
+```
+
+The current bundled-script integration supports anonymous widgets. Delegated
+identity requires the React API until a programmatic script bootstrap is
+released; functions must not be serialized into `data-*` attributes.