guideai-app 0.5.4-1 → 0.5.4-3

package/README.md

@@ -37,7 +37,10 @@ function App() {
 | Prop                              | Type       | Required             | Description                                                                                                                                                                         |
 | --------------------------------- | ---------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `authKey`                         | `string`   | Yes (customer embed) | Widget access key; **not** persisted by the package. Exchanged once for a JWT via `POST /widget/session`. **Do not use React’s reserved `key` attribute** — use this prop name.     |
-| `workspace`                       | `string`   | No                   | Workspace slug to use for the realtime session. Forwarded on the `/initialize` body so the server can pick a non-default workspace per request. Omit to use the customer default.   |
+| `workspace`                       | `string`   | No                   | Default workspace **slug** for the first realtime session (single value). Forwarded on `/initialize`. Omit to use the customer default. When used with `workspaces`, pick a slug from that allowlist. |
+| `workspaces`                      | `string` or `string[]` | No | Catalog allowlist: limits which workspaces (and their workflows) end users can access. Omit for all customer workspaces. Comma-separated string (`"sales,support"`) or array. Invalid/empty allowlist removes the widget and logs `console.error`. |
+| `getUserInfo`                     | `function` | No                   | Lets Guide AI know who is signed in on your app (see **Signed-in users** below). |
+| `initializeUserId`               | `string`   | No                   | Advanced: optional fixed user id when you manage identity yourself. |
 | `adminConversationPersistenceKey` | `string`   | No                   | Optional stable key for transcript `localStorage` isolation. Omit to use a non-secret default from the page **origin** (same across SPA routes). Never use the raw access key here. |
 | `React`                           | `React`    | Yes                  | React instance from your application                                                                                                                                                |
 | `ReactDOM`                        | `ReactDOM` | Yes                  | ReactDOM instance from your application                                                                                                                                             |
@@ -45,9 +48,71 @@ function App() {
 | `environment`                     | `string`   | No                   | API environment: `'production'` (default), `'development'`, or `'local'`                                                                                                            |
 | `transcript`                      | `object`   | No                   | Transcript panel configuration (see below)                                                                                                                                          |
 | `input`                           | `object`   | No                   | Text/voice input configuration (see below)                                                                                                                                          |
+| `theme`                           | `string`   | No                   | Built-in color theme preset id (see **Themes** below). Omit for the package default palette.                                                                                        |
 
 You must pass **`authKey`** (customer integration). For authentication details, see **`AUTHENTICATION.md`** in this package.
 
+## Themes
+
+Set the widget color palette with the `theme` prop. All presets are bundled in `guideai-app`; no extra scripts or CDN files are required.
+
+```jsx
+<GuideAI
+	authKey="your-access-key"
+	workspace="your-workspace"
+	React={React}
+	ReactDOM={ReactDOM}
+	theme="dark"
+/>
+```
+
+Role-based catalog example:
+
+```jsx
+<GuideAI
+	authKey={accessKey}
+	workspace="support"
+	workspaces={user.role === 'admin' ? 'admin,support' : 'support'}
+	React={React}
+	ReactDOM={ReactDOM}
+/>
+```
+
+Omit `theme` (or pass `null`) to use the default package palette (**Studio blue**).
+
+### Light themes
+
+| `theme` id     | Name  |
+| -------------- | ----- |
+| `light-ivory`  | Ivory |
+| `light-snow`   | Snow  |
+| `light-sand`   | Sand  |
+| `light-mist`   | Mist  |
+| `light-mint`   | Mint  |
+| `light-sky`    | Sky   |
+| `light-coral`  | Coral |
+| `light-rose`   | Rose  |
+| `light-plum`   | Plum  |
+| `light-slate`  | Slate |
+
+### Dark themes
+
+| `theme` id        | Name         |
+| ----------------- | ------------ |
+| `dark`            | Studio blue  |
+| `dark-muted-gray` | Muted gray   |
+| `dark-midnight`   | Midnight     |
+| `dark-ocean`      | Ocean        |
+| `dark-forest`     | Forest       |
+| `dark-teal`       | Teal         |
+| `dark-violet`     | Violet       |
+| `dark-ember`      | Ember        |
+| `dark-carbon`     | Carbon       |
+| `dark-ruby`       | Ruby         |
+| `dark-graphite`   | Graphite     |
+
+TypeScript hosts can import `GuideAIThemeId` or `GUIDEAI_THEME_IDS` from `guideai-app`. Labels are also available on `GUIDEAI_PRESET_THEMES`.
+
 ## Position Object
 
 The `position` prop accepts an object with CSS positioning properties to control where the Guide AI button appears on your page, as well as z-index configuration for all Guide AI components:
@@ -317,6 +382,51 @@ function App() {
 export default App;
 ```
 
+## Signed-in users (`getUserInfo`)
+
+If people can sign in on your site, pass **`getUserInfo`** so Guide AI can treat them as the same person across visits and tie voice sessions to their account.
+
+- Your function should return something like **`{ username: user.email }`** when someone is logged in. Use whatever stable string identifies them (often an email).
+- When **no one is logged in yet**, you can **`return null`** (or omit **`username`**) so Guide AI keeps a normal anonymous experience without rotating identities on every check.
+- After login or logout, you can notify Guide AI right away by dispatching **`GUIDEAI_HOST_USERINFO_REFRESH_EVENT`** on `window` (import it from `guideai-app` alongside the component).
+
+Wrap **`getUserInfo`** in **`useCallback`** so it doesn’t change every render.
+
+More detail for integrations lives in **`docs/WIDGET_USER_IDENTITY.md`** and **`AUTHENTICATION.md`**.
+
+### Example
+
+```jsx
+import React, { useCallback } from 'react';
+import ReactDOM from 'react-dom';
+import GuideAI, { GUIDEAI_HOST_USERINFO_REFRESH_EVENT } from 'guideai-app';
+
+function App({ currentUser }) {
+	const getUserInfo = useCallback(() => {
+		if (!currentUser) return null;
+
+		return {
+			username: currentUser.email,
+			displayName: currentUser.name,
+		};
+	}, [currentUser]);
+
+	// Optional: after your auth state changes, run:
+	// window.dispatchEvent(new CustomEvent(GUIDEAI_HOST_USERINFO_REFRESH_EVENT));
+
+	return (
+		<GuideAI
+			authKey="your-access-key"
+			workspace="your-workspace"
+			React={React}
+			ReactDOM={ReactDOM}
+			getUserInfo={getUserInfo}
+			position={{ bottom: '20px', right: '20px' }}
+		/>
+	);
+}
+```
+
 ## Getting Your Access Key
 
 To use Guide AI, you'll need an access key and workspace slug. Contact the Guide AI team to get set up.

package/dist/GuideAI.d.ts

@@ -1,3 +1,3 @@
 import { GuideAIProps } from './types/GuideAI.types';
-declare const GuideAI: (props: GuideAIProps) => import("react").JSX.Element | null;
-export default GuideAI;
+declare const GuideAIComponent: (props: GuideAIProps) => import("react").JSX.Element | null;
+export default GuideAIComponent;