@wexio/messenger-widget-react 1.0.0 → 1.0.1

package/README.md

@@ -1,15 +1,38 @@
-# @wexio/messenger-widget-react
+# Welcome to @wexio/messenger-widget-react 👋
 
-[![npm version](https://img.shields.io/npm/v/@wexio/messenger-widget-react.svg)](https://www.npmjs.com/package/@wexio/messenger-widget-react)
-[![license](https://img.shields.io/npm/l/@wexio/messenger-widget-react.svg)](./LICENSE)
+[![Version](https://img.shields.io/npm/v/@wexio/messenger-widget-react.svg)](https://www.npmjs.com/package/@wexio/messenger-widget-react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-wexio.io-blue.svg)](https://wexio.io/docs)
 
-Native React component for the [Wexio](https://wexio.io) web messenger. Renders inside a Shadow DOM portal so widget styles never collide with the host React app. Same widget runtime as the script-injected iframe and the `<wexio-widget>` web component — your visitors see the same widget regardless of which delivery flavour you embed.
+Native React component for the [Wexio](https://wexio.io) web messenger. Renders inside a Shadow DOM portal for full style isolation — same `WidgetShell` runtime as the script-injected iframe and the `<wexio-widget>` web component. Same chat, same visitor identity, same backend; the only difference is **where the React tree mounts.**
 
-## Install
+🏠 [Website](https://wexio.io)
+📚 [Developer Docs](https://wexio.io/docs)
+
+## 📂 Description
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Identifying users](#identifying-users)
+- [Props](#props)
+- [Methods](#methods)
+- [Types](#types)
+- [SSR](#ssr)
+- [Browser support](#browser-support)
+- [Troubleshooting](#troubleshooting)
+- [Use with other frameworks](#use-with-other-frameworks)
+- [Author](#author)
+- [License](#-license)
+
+## Installation
 
 ```bash
 yarn add @wexio/messenger-widget-react
-# or
+```
+
+or
+
+```bash
 npm install @wexio/messenger-widget-react
 ```
 
@@ -17,6 +40,8 @@ npm install @wexio/messenger-widget-react
 
 ## Quick start
 
+Import the package on every page that should display the messenger (or on a common component used by them) and render the component. This must be done on the client side.
+
 ```tsx
 import { WexioWidget } from "@wexio/messenger-widget-react";
 
@@ -30,24 +55,24 @@ export default function App() {
 }
 ```
 
-That's it — the widget mounts a floating launcher in the bottom-right corner of the viewport and handles the rest (theme, locale, panel open/close, identity handshake, real-time chat).
+That's it — the widget mounts a floating launcher, handles its own theme/locale/state, and the operator dashboard sees the visitor immediately. The component manages its own lifecycle internally, so re-renders due to host DOM changes won't trigger a re-boot.
 
 ## Identifying users
 
-Pass a verified `user` to log a known visitor in (the Wexio equivalent of Intercom's `boot({ user_id, ... })`). Provide ONE proof — a Google FedCM `id_token`, a host-signed `jwt`, or a legacy `userId` + `userHash` HMAC pair:
+Pass a verified `user` to log a known visitor in (the Wexio equivalent of Intercom's `boot({ user_id, ... })`). Provide ONE proof — a Google FedCM `id_token`, a host-signed `jwt`, or the legacy `userId` + `userHash` HMAC pair:
 
 ```tsx
 <WexioWidget
   publicKey="pk_live_..."
   user={{
-    jwt: serverSignedJwt,
+    jwt: serverSignedJwt, // host-signed identity token (recommended)
     name: "Ada Lovelace",
     email: "ada@example.com",
   }}
 />
 ```
 
-For an unverified pre-fill (skip the prechat form when the visitor's email is already known but you can't sign it), use `prefill` instead:
+For an **unverified pre-fill** (skip the prechat form when the visitor's email is already known but you can't sign it), use `prefill`:
 
 ```tsx
 <WexioWidget publicKey="pk_live_..." prefill={{ email: "ada@example.com" }} />
@@ -66,35 +91,146 @@ For an unverified pre-fill (skip the prechat form when the visitor's email is al
 | `prefill`           | [`VisitorPrefill`](#visitorprefill)                   | Unverified pre-fill for the prechat form.                                                                                                |
 | `config`            | [`InjectableWidgetConfig`](#injectablewidgetconfig)   | Pre-resolved widget config. Set this if you already have the config server-rendered or fetched app-wide — skips the bootstrap fetch.     |
 | `lightboxViewport`  | `boolean`                                             | Render the media lightbox (image / video gallery) as a viewport-fixed overlay. Set `true` when the widget's host box is very small.      |
-| `onResize`          | `(size: { width: number; height: number }) => void`   | Fired whenever the widget's intended dimensions change (open ↔ closed ↔ expanded).                                                       |
+| `onResize`          | `(size: { width: number; height: number }) => void`   | Fired whenever the widget's intended dimensions change (open ↔ closed ↔ expanded). Use for host-side layout sync.                        |
 | `onClose`           | `() => void`                                          | Fired when the visitor taps the close chip.                                                                                              |
 | `className`         | `string`                                              | Pass-through class on the outer host `<div>`. Style this with normal layout CSS.                                                         |
 | `style`             | `React.CSSProperties`                                 | Pass-through inline styles for the outer host `<div>`.                                                                                   |
 
-### Imperative API
+## Methods
+
+The visitor- and operator-facing imperative methods (`show`, `hide`, `update`, `shutdown`, `showSpace`, `showMessages`, `whoami`, `onUnreadCountChange`, etc.) live on `window.WexioWidget` once the component has mounted, mirroring the script loader's surface. A typed React hook (`useWexioWidget()`) ships in a future minor — until then, reach for the global from `useEffect`.
+
+### show / hide / toggle
+
+Open or close the messenger panel.
+
+```ts
+window.WexioWidget?.show();
+window.WexioWidget?.hide();
+window.WexioWidget?.toggle();
+```
+
+### update
+
+Patch live config (swap identity, switch theme, change locale).
+
+```ts
+window.WexioWidget?.update({ locale: "uk" });
+```
+
+### shutdown / boot
+
+Wipe session (token, sticky visitor id, prechat flags); `boot` re-initialises. Use on logout / shared devices.
+
+```ts
+window.WexioWidget?.shutdown();
+window.WexioWidget?.boot({ publicKey: "pk_live_..." });
+```
+
+### showSpace
+
+Open the messenger and route to a specific tab.
+
+```ts
+window.WexioWidget?.showSpace("home");
+window.WexioWidget?.showSpace("messages");
+window.WexioWidget?.showSpace("help");
+window.WexioWidget?.showSpace("news");
+window.WexioWidget?.showSpace("profile");
+```
+
+### showMessages
+
+Alias for `showSpace("messages")`.
+
+```ts
+window.WexioWidget?.showMessages();
+```
+
+### showNewMessage
+
+Open ready-to-compose. Optional prefill for the composer.
+
+```ts
+window.WexioWidget?.showNewMessage();
+window.WexioWidget?.showNewMessage("Hi, I have a question about...");
+```
+
+### showArticle / showNews
+
+Deep-link into a help article or news post.
+
+```ts
+window.WexioWidget?.showArticle(articleId);
+window.WexioWidget?.showNews(newsItemId);
+```
+
+### onShow / onHide
+
+Fire a callback when the messenger opens/closes.
+
+```ts
+window.WexioWidget?.onShow(() => {
+  console.log("messenger opened");
+});
+window.WexioWidget?.onHide(() => {
+  console.log("messenger closed");
+});
+```
 
-The visitor- and operator-facing imperative methods (`show`, `hide`, `update`, `shutdown`, `showSpace`, `showMessages`, `whoami`, `onUnreadCountChange`, etc.) live on `window.WexioWidget` once the component has mounted, mirroring the script loader's surface. A typed React hook (`useWexioWidget()`) is in progress and ships in a future minor — until then, reach for the global from `useEffect`:
+### onUnreadCountChange
+
+Fires immediately with the current count, then on every change. Common use: badge the host tab title.
 
 ```tsx
 useEffect(() => {
-  window.WexioWidget?.onUnreadCountChange?.((count) => {
+  return window.WexioWidget?.onUnreadCountChange?.((count) => {
     document.title = count > 0 ? `(${count}) Inbox` : "Inbox";
   });
 }, []);
 ```
 
-See the [full method reference](https://github.com/wexiohub/messenger-widget-react#api) on GitHub.
+### hideNotifications
+
+Suppress launcher peek bubbles on new operator messages.
+
+```ts
+window.WexioWidget?.hideNotifications(true);  // suppress
+window.WexioWidget?.hideNotifications(false); // restore
+```
+
+### whoami / getVisitorId
+
+Read the current session.
+
+```ts
+const me = window.WexioWidget?.whoami();
+// → { visitorId, peopleId, displayName, verified } | null
+const visitorId = window.WexioWidget?.getVisitorId();
+```
+
+### setLocale
+
+Programmatic language switch.
+
+```ts
+window.WexioWidget?.setLocale("uk");
+```
+
+### Future / reserved
+
+The following names are reserved on the public surface for upcoming features and are no-ops today (with a `console.warn` in dev builds): `trackEvent`, `startTour`, `startSurvey`, `startChecklist`, `showTicket`. They'll light up when the corresponding backend features ship.
 
 ## Types
 
-### `VisitorIdentity`
+### VisitorIdentity
 
 ```ts
 interface VisitorIdentity {
-  googleIdToken?: string;          // Google FedCM id_token (preferred)
-  jwt?: string;                    // Host-signed JWT
-  userId?: string;                 // Legacy HMAC pair…
-  userHash?: string;               // …(HMAC-SHA256(userId, integrationSecret))
+  googleIdToken?: string; // Google FedCM id_token (preferred)
+  jwt?: string;           // Host-signed JWT
+  userId?: string;        // Legacy HMAC pair…
+  userHash?: string;      // …(HMAC-SHA256(userId, integrationSecret))
   name?: string;
   email?: string;
   phone?: string;
@@ -102,7 +238,7 @@ interface VisitorIdentity {
 }
 ```
 
-### `VisitorPrefill`
+### VisitorPrefill
 
 ```ts
 interface VisitorPrefill {
@@ -112,7 +248,7 @@ interface VisitorPrefill {
 }
 ```
 
-### `InjectableWidgetConfig`
+### InjectableWidgetConfig
 
 The pre-resolved widget config shape (theme, features, blocks, prechat, messenger chrome, sounds, locale strategy). It deliberately excludes `status`, `branding`, and `security.allowedOrigins` — those are server-owned and not host-overridable. Pull the full type from the package:
 
@@ -128,6 +264,52 @@ The component renders `null` on the server. The Shadow-DOM portal target mounts
 
 Modern evergreen browsers — anything that supports Shadow DOM and ES2020. Internet Explorer is not supported.
 
-## License
+## Troubleshooting
+
+### Messenger not showing on page
+
+- Check that the correct `publicKey` is being passed.
+- Check the messenger is **active** for your integration on https://app.wexio.io.
+- Confirm the component renders on the client (not during SSR) — `<WexioWidget>` returns `null` until the first `useEffect`.
+
+### No user data attached
+
+- Verify you're computing `userHash` server-side as `HMAC-SHA256(userId, integrationSecret)`. Never expose the integration secret to the browser.
+- Confirm the proof you pass in `user` is one of: `googleIdToken`, `jwt`, or `userId` + `userHash`. Passing multiple proofs uses the first one detected (Google → jwt → HMAC).
+
+### TypeScript errors after upgrade
+
+The public type surface is locked to `entries/public.ts` in the source repo. If you previously relied on undocumented props (`mode: "preview"`, `configOverride`, `useDummyData`, `previewData`), they are no longer exposed — they were dashboard-only and never meant to ship. Remove them and the build will pass.
+
+## Use with other frameworks
+
+The underlying widget runtime is a Web Component, so it works in any modern framework — even without a typed wrapper:
+
+```html
+<wexio-widget public-key="pk_live_..."></wexio-widget>
+<script type="module" src="https://cdn.wexio.io/widget.js"></script>
+```
+
+Typed wrappers are on the roadmap:
+
+- `@wexio/messenger-widget-vue` — coming soon
+- `@wexio/messenger-widget-angular` — coming soon
+- `@wexio/messenger-widget-ember` — coming soon
+
+For plain HTML / script-injection setups, paste the loader snippet from https://wexio.io/docs.
+
+## Author
+
+👤 **Wexio** ([https://wexio.io](https://wexio.io))
+
+## Show your support
+
+Give a ⭐️ if this package helped you!
+
+## 📝 License
+
+This project is [MIT](./LICENSE) licensed.
+
+---
 
-[MIT](./LICENSE) © Wexio
+_Created with ❤️ by [Wexio](https://wexio.io)_