bstp-agent-widget 0.2.77 → 0.2.79

package/README.md

@@ -30,31 +30,88 @@ npm publish --access public
 bun add bstp-agent-widget
 ```
 
+### 1. Provide runtime configuration via `/environment.json`
+
+Host applications must expose a GenAI configuration inside their own `public/environment.json`. The widget loads this file by default (or the URL you pass with `environmentUrl`).
+
+```json
+{
+  "url": {
+    "api": "https://your-api",
+    "apiPaths": {
+      "genai": "genai/api/v1"
+    }
+  },
+  "genai": {
+    "config": {
+      "assistantId": 220,
+      "agents": [
+        {
+          "assistantKey": "salesAgent",
+          "assistantId": 220,
+          "label": "Sales Assistant",
+          "initialMessage": "Hello, my customer id is "
+        }
+      ]
+    }
+  }
+}
+```
+
+> GenAI login credentials are bundled inside the widget. Do **not** expose `genai.init` or any client secrets in your app's `environment.json`.
+
+### 2. Mount the widget (React example)
+
+Prefer mounting through `mountAgentChatWidgetFromEnvironment`. It automatically hydrates GenAI config from the environment file, while allowing optional overrides through the `config` option.
+
 ```tsx
-import { AgentChatWidget } from 'bstp-agent-widget';
+import { useEffect, useRef } from 'react';
+import { mountAgentChatWidgetFromEnvironment } from 'bstp-agent-widget';
 import 'bstp-agent-widget/style.css';
 
-export function Page() {
-  return (
-    <AgentChatWidget
-      config={{
-        baseUrl: 'https://your-genai-api-url',
-        assistantId: 123,
-        genaiInit: {
-          email: 'agent@example.com',
-          clientSecret: 'secret',
+export function AgentWidgetHost() {
+  const hostRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    if (!hostRef.current) return;
+
+    let cleanup: (() => void) | undefined;
+
+    (async () => {
+      cleanup = await mountAgentChatWidgetFromEnvironment(hostRef.current!, {
+        runtime: {
+          customerId: '590100010884',
+          customerToken: 'jwt-token',
+          language: 'tr-TR',
         },
-      }}
-      runtime={{
-        customerId: '590100010884',
-        customerToken: 'jwt-token',
-        language: 'tr-TR',
-      }}
-    />
-  );
+        // Optional: override assistant selection coming from environment.json
+        config: {
+          assistantId: 220,
+          assistants: [
+            {
+              assistantKey: 'serviceAgent',
+              assistantId: 94,
+              label: 'Get help with your service issues',
+              initialMessage: 'Hello, my customer id is ',
+            },
+          ],
+        },
+        // Optional UI overrides
+        // theme: { withinPortal: true, fabPosition: { bottom: 16, right: 16 } },
+        // Optional: supply a different environment file
+        // environmentUrl: '/configs/widget-environment.json',
+      });
+    })();
+
+    return () => cleanup?.();
+  }, []);
+
+  return <div ref={hostRef} />;
 }
 ```
 
+> Precedence rules: runtime data is always provided by the host. If you pass a `config` option, the widget overrides the `genai.config` block from `environment.json` before booting (so every consumer, including initial automated messages, sees the admin UI values). When no override is provided, it falls back to the values coming from `environment.json`.
+
 ## Development Notes
 
 - `react` and `react-dom` are defined as `peerDependencies`.
@@ -101,15 +158,19 @@ export class AgentChatWidgetComponent implements AfterViewInit, OnDestroy {
         customerToken: 'jwt-token',
         language: 'en-US',
       },
-      // Agent config can be supplied by host app.
-      // baseUrl and genai.init still come from environment.json.
+      // Optional: override what environment.json provides
       config: {
         assistantId: 220,
         assistants: [
-          { assistantKey: 'salesAgent', assistantId: 220, label: 'Sales Assistant' },
+          {
+            assistantKey: 'salesAgent',
+            assistantId: 220,
+            label: 'Sales Assistant',
+            initialMessage: 'Hello, my customer id is ',
+          },
         ],
       },
-      ui: {
+      theme: {
         zIndex: 12000,
         withinPortal: true,
         fabPosition: { bottom: 16, right: 16 },
@@ -137,13 +198,21 @@ export class AgentChatWidgetComponent implements AfterViewInit, OnDestroy {
   },
   "genai": {
     "config": {
-      "assistantId": 220
+      "assistantId": 220,
+      "agents": [
+        {
+          "assistantKey": "serviceAgent",
+          "assistantId": 94,
+          "label": "Get help with your service issues",
+          "initialMessage": "Hello, my customer id is "
+        }
+      ]
     }
   }
 }
 ```
 
-Base URL is resolved from `url.api` + `url.apiPaths.genai`.
+Base URL is resolved from `url.api` + `url.apiPaths.genai`. External `config` overrides supplied when mounting the widget take precedence over this environment file. GenAI login credentials are managed internally by the widget, so Angular hosts never provide `genai.init`.
 
 # React Starter Kit