@clivly/chat-widget 0.10.9 → 0.11.0

package/README.md

@@ -46,16 +46,34 @@ npm install @clivly/chat-widget
 ```
 
 ```tsx
-import { ChatWidget, createSessionFetcher } from "@clivly/chat-widget";
+import {
+  ChatWidget,
+  createClivlyTransport,
+  createSessionFetcher,
+} from "@clivly/chat-widget";
+
+// Both at module scope, not inline in the element. `createTransport` is a
+// dependency of the effect that opens the socket, so a new function identity on
+// every render tears the connection down and reopens it in a loop.
+const createTransport = createClivlyTransport();
+const getSession = createSessionFetcher({
+  sessionUrl: "/api/clivly/widget/session",
+});
 
 <ChatWidget
   widgetId="support"
-  getSession={createSessionFetcher({
-    sessionUrl: "/api/clivly/widget/session",
-  })}
+  createTransport={createTransport}
+  getSession={getSession}
 />;
 ```
 
+`createTransport` is optional in the type signature but **required to send
+messages** — it is what opens the socket. Without it the widget mints a session
+and renders the composer, but Send stays disabled and the status line reads
+"Chat is unavailable". (The script-tag mount defaults it for you; the React
+component does not, so that the same component can take
+`createLoopbackTransport()` in tests.)
+
 `widgetId` is the **public slug** you set on the widget record — it is not a
 credential. `sessionUrl` must be the path where you mounted the session route on
 your own origin; `/api/clivly/widget/session` is what `clivly add widget`
@@ -128,6 +146,71 @@ This entry maps to the generated global/browser artifact:
 Use it for script-tag delivery, CDN-style consumption, or any future server path
 that serves the bundled widget directly.
 
+## Skipping the pre-chat form for a signed-in visitor
+
+By default the widget asks for a name and email before opening a conversation.
+When your app already knows who the visitor is, seed that identity and the
+visitor goes straight to the composer.
+
+React:
+
+```tsx
+<ChatWidget
+  defaultVisitor={{ name: user.name, email: user.email }}
+  createTransport={createTransport}
+  getSession={getSession}
+  widgetId="support"
+/>
+```
+
+Script tag — template the values into the tag when you render the page:
+
+```html
+<script
+  src="https://cdn.example.com/widget.global.js"
+  data-widget-id="support"
+  data-session-url="/api/clivly/widget/session"
+  data-visitor-name="Jane Example"
+  data-visitor-email="jane@example.com"
+  defer
+></script>
+```
+
+`mountChatWidget()` takes the same `defaultVisitor` option as the React prop.
+
+**Both fields are required to skip the form.** The session endpoint rejects a
+blank name, so a half-known identity is treated as a prefill: the form still
+renders with the known field filled in. Blank or whitespace-only values count as
+no identity at all.
+
+The session is created when the visitor opens the launcher, not on page load —
+otherwise every visitor who merely loaded a page would create an empty thread in
+your inbox.
+
+### This is not authentication
+
+A seeded identity is self-reported: anyone can edit a prop in React devtools or
+a `data-` attribute in the element inspector. It removes the typing, nothing
+more.
+
+To make the identity trustworthy, pass `resolveUser` to
+`createChatSessionHandler` on your backend. It resolves the caller's real
+session behind your API key, server-side, and that is what marks the resulting
+contact verified:
+
+```ts
+createChatSessionHandler({
+  apiKey: process.env.CLIVLY_API_KEY,
+  resolveUser: async (request) => {
+    const session = await auth.getSession(request);
+    return session ? { id: session.user.id, email: session.user.email, name: session.user.name } : null;
+  },
+});
+```
+
+Use both together for a signed-in user: `defaultVisitor` removes the form,
+`resolveUser` is what makes it trustworthy.
+
 ## Theming
 
 The widget ships light and dark palettes and follows the host app by default.

package/dist/browser-mount.cjs

@@ -256,10 +256,42 @@ const WIDGET_STYLES = `
   padding: 0.5rem 1rem;
   text-align: center;
 }
+/* Only the name carries the gradient. "Powered by" is ordinary running text
+   and inherits the muted colour of the line, so the mark reads as a signature
+   rather than the whole sentence being branded. */
 .clivly-chat-widget__powered a {
   color: inherit;
   text-decoration: none;
 }
+/* The attribution is Clivly's mark, not the host's, so it uses the stops from
+   the logo itself rather than --clivly-chat-accent: the accent is driven by
+   each customer's own brandColor, and a signature that changed colour per
+   customer would stop reading as a signature.
+
+   The color declaration is the fallback and must stay a real colour:
+   background-clip is painted over it, so anything that drops the background —
+   forced-colors, an older engine, a copied-out snippet — degrades to solid
+   coral rather than to invisible text. */
+.clivly-chat-widget__powered-mark {
+  background-image: linear-gradient(90deg, #ff5a4a 0%, #c0231a 100%);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: #c0231a;
+  -webkit-text-fill-color: transparent;
+}
+/* Forced-colors mode strips background-image outright, which would leave the
+   text painted in a transparent fill. Hand the colour back to the UA so the
+   mark inherits the link colour the UA picked rather than re-pinning coral. */
+@media (forced-colors: active) {
+  .clivly-chat-widget__powered a {
+    color: LinkText;
+  }
+  .clivly-chat-widget__powered-mark {
+    background-image: none;
+    color: currentColor;
+    -webkit-text-fill-color: currentColor;
+  }
+}
 .clivly-chat-widget__powered a:hover,
 .clivly-chat-widget__powered a:focus-visible {
   text-decoration: underline;
@@ -483,7 +515,27 @@ function MessageList({ greeting, hasSession, messages }) {
 	});
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: messages.map((message) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(MessageBubble, { message }, message.id)) });
 }
-function ChatWidget({ className, createTransport, getSession, initiallyOpen = false, launcherLabel = "Chat with us", storage = DEFAULT_STORAGE, style, theme = "auto", widgetId }) {
+/**
+* Whether a seeded visitor is complete enough to skip the form.
+*
+* Both fields have to be present and non-blank: the server requires each, so
+* auto-starting on a half-filled identity would trade a form the visitor can
+* complete for an error they cannot.
+*/
+function isCompleteVisitor(visitor) {
+	return Boolean(visitor?.name?.trim() && visitor?.email?.trim());
+}
+/**
+* What the composer says about itself. "Connecting…" claims a socket is in
+* flight, so it is as wrong as "Conversation ready" when no transport exists —
+* the visitor is told to wait for something that will never arrive. The third
+* string keeps the status honest in all three states.
+*/
+function composerStatusText(hasTransport, isReady) {
+	if (!hasTransport) return "Chat is unavailable";
+	return isReady ? "Conversation ready" : "Connecting…";
+}
+function ChatWidget({ className, createTransport, defaultVisitor, getSession, initiallyOpen = false, launcherLabel = "Chat with us", storage = DEFAULT_STORAGE, style, theme = "auto", widgetId }) {
 	const [isOpen, setIsOpen] = (0, react.useState)(initiallyOpen);
 	const [error, setError] = (0, react.useState)(null);
 	const [isConnecting, setIsConnecting] = (0, react.useState)(false);
@@ -492,11 +544,15 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 	const [messages, setMessages] = (0, react.useState)([]);
 	const [session, setSession] = (0, react.useState)(null);
 	const [visitor, setVisitor] = (0, react.useState)({
-		email: "",
-		name: ""
+		email: defaultVisitor?.email ?? "",
+		name: defaultVisitor?.name ?? ""
 	});
 	const transportRef = (0, react.useRef)(null);
 	const listRef = (0, react.useRef)(null);
+	(0, react.useEffect)(() => {
+		if (createTransport) return;
+		console.warn("[clivly] <ChatWidget> was given no createTransport, so messages cannot be sent. Pass createTransport={createClivlyTransport()} — see https://www.npmjs.com/package/@clivly/chat-widget#five-minute-quick-start");
+	}, []);
 	const themeStyle = useThemeStyle(session, style);
 	const resolvedTheme = useResolvedTheme(theme);
 	(0, react.useEffect)(() => () => {
@@ -539,15 +595,13 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 			if (transportRef.current === connection) transportRef.current = null;
 		};
 	}, [createTransport, session]);
-	const submitVisitor = async (event) => {
-		event.preventDefault();
+	const startSession = (0, react.useCallback)(async (identity) => {
 		setError(null);
 		setIsConnecting(true);
 		try {
-			const existingVisitorToken = storage?.getItem(createStorageKey(widgetId)) ?? null;
 			const nextSession = await getSession({
-				visitor,
-				visitorToken: existingVisitorToken,
+				visitor: identity,
+				visitorToken: storage?.getItem(createStorageKey(widgetId)) ?? null,
 				widgetId
 			});
 			storage?.setItem(createStorageKey(widgetId), nextSession.visitorToken);
@@ -559,7 +613,30 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 		} finally {
 			setIsConnecting(false);
 		}
+	}, [
+		getSession,
+		storage,
+		widgetId
+	]);
+	const submitVisitor = async (event) => {
+		event.preventDefault();
+		await startSession(visitor);
 	};
+	(0, react.useEffect)(() => {
+		if (!(isOpen && isCompleteVisitor(defaultVisitor))) return;
+		if (session || isConnecting || error) return;
+		startSession({
+			email: defaultVisitor.email.trim(),
+			name: defaultVisitor.name.trim()
+		}).catch(() => {});
+	}, [
+		defaultVisitor,
+		error,
+		isConnecting,
+		isOpen,
+		session,
+		startSession
+	]);
 	const submitMessage = (event) => {
 		event?.preventDefault();
 		if (!(session && transportRef.current)) {
@@ -591,6 +668,7 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 			setError(resolved.message);
 		}
 	};
+	const canSend = Boolean(createTransport) && isReady;
 	const greeting = session?.widget.config.greeting ?? "Tell us a little about yourself and we’ll pick up the conversation from there.";
 	const panelTitle = session?.widget.name ?? "Start a conversation";
 	const sessionSummary = sessionSummaryText(session, greeting);
@@ -658,7 +736,7 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 								onKeyDown: (event) => {
 									if (!isSendKey(event)) return;
 									event.preventDefault();
-									if (messageDraft.trim() && isReady) submitMessage();
+									if (messageDraft.trim() && canSend) submitMessage();
 								},
 								placeholder: "Write your message",
 								value: messageDraft
@@ -667,10 +745,10 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 							className: "clivly-chat-widget__actions",
 							children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 								className: "clivly-chat-widget__subtitle",
-								children: isReady || !createTransport ? "Conversation ready" : "Connecting…"
+								children: composerStatusText(Boolean(createTransport), isReady)
 							}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 								className: "clivly-chat-widget__button",
-								disabled: !(messageDraft.trim() && isReady),
+								disabled: !(messageDraft.trim() && canSend),
 								type: "submit",
 								children: "Send"
 							})]
@@ -732,11 +810,18 @@ function ChatWidget({ className, createTransport, getSession, initiallyOpen = fa
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 						className: "clivly-chat-widget__powered",
-						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("a", {
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("a", {
 							href: "https://clivly.com",
 							rel: "noopener",
 							target: "_blank",
-							children: "Powered by Clivly"
+							children: [
+								"Powered by",
+								" ",
+								/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: "clivly-chat-widget__powered-mark",
+									children: "Clivly"
+								})
+							]
 						})
 					})
 				]
@@ -827,6 +912,33 @@ function createSessionFetcher({ fetchImpl = fetch, sessionUrl }) {
 //#endregion
 //#region src/browser-mount.tsx
 const MOUNTED_DATA_ATTR = "clivlyMounted";
+/**
+* The identity a script-tag host already knows, read off the tag.
+*
+* The React component takes `defaultVisitor` as a prop; a script tag has only
+* strings, so `data-visitor-name` / `data-visitor-email` are the same seam. A
+* host that server-renders its page can template the signed-in user's details
+* straight into the tag and the visitor never sees the pre-chat form.
+*
+* Returns `undefined` rather than an empty object when neither attribute is
+* present, so the component's own "no identity" path stays untouched. Partial
+* values are passed through deliberately: `ChatWidget` treats one field as a
+* prefill and still renders the form, which is the right outcome for a host
+* that knows an email but not a name.
+*
+* This is self-reported identity — anyone can edit the attribute in devtools.
+* `resolveUser` on the host backend is what makes it trustworthy; this only
+* removes the typing.
+*/
+function readScriptVisitor(dataset) {
+	const email = dataset.visitorEmail?.trim();
+	const name = dataset.visitorName?.trim();
+	if (!(email || name)) return;
+	return {
+		...email ? { email } : {},
+		...name ? { name } : {}
+	};
+}
 function resolveSocketUrl(socketUrlTemplate, conversationId, token) {
 	return socketUrlTemplate.replaceAll("{conversationId}", encodeURIComponent(conversationId)).replaceAll("{token}", encodeURIComponent(token));
 }
@@ -871,6 +983,7 @@ function mountChatWidgetScript(script = document.currentScript) {
 	shadowRoot.append(container);
 	const { root, setTheme } = createWidgetMount({
 		container,
+		defaultVisitor: readScriptVisitor(script.dataset),
 		sessionUrl,
 		socketUrlTemplate: script.dataset.socketUrlTemplate,
 		theme: parseTheme(script.dataset.theme),

package/dist/browser-mount.d.cts

@@ -110,6 +110,24 @@ type CreateChatTransport = (options: CreateChatTransportOptions) => ChatTranspor
 interface ChatWidgetProps {
   className?: string;
   createTransport?: CreateChatTransport;
+  /**
+   * Identity the host already knows, used to skip the pre-chat form.
+   *
+   * When both `name` and `email` are non-empty the widget opens straight into
+   * the conversation and bootstraps the session itself, instead of asking a
+   * signed-in user to retype what the host app already displays in its own
+   * header. A partial value (one field, or blanks) is treated as a prefill:
+   * the form still renders, with the known fields filled in.
+   *
+   * This seeds the *form*, and a form value is self-reported no matter who
+   * typed it. It is not, on its own, proof of identity — anyone can pass any
+   * address here. Verification is a separate, server-side mechanism: pass
+   * `resolveUser` to `createChatSessionHandler` on the host backend and it
+   * resolves the caller's real session behind the API key, which is what marks
+   * the resulting contact verified. Use both together for a signed-in user:
+   * this prop removes the typing, `resolveUser` is what makes it trustworthy.
+   */
+  defaultVisitor?: Partial<ChatWidgetVisitor>;
   getSession: GetSession;
   initiallyOpen?: boolean;
   launcherLabel?: string;
@@ -130,13 +148,13 @@ interface ChatWidgetProps {
 }
 //#endregion
 //#region src/browser-mount.d.ts
-interface MountChatWidgetOptions extends Omit<ChatWidgetProps, "getSession" | "widgetId"> {
+export interface MountChatWidgetOptions extends Omit<ChatWidgetProps, "getSession" | "widgetId"> {
   container: Element | ShadowRoot;
   sessionUrl: string;
   socketUrlTemplate?: string;
   widgetId: string;
 }
-interface ChatWidgetMount {
+export interface ChatWidgetMount {
   root: Root;
   /**
    * Repaint the widget in a different theme. `"auto"` resumes following the
@@ -148,11 +166,10 @@ interface ChatWidgetMount {
    */
   setTheme: (theme: ChatWidgetTheme) => void;
 }
-declare function mountChatWidget(options: MountChatWidgetOptions): Root;
-interface ScriptMountResult extends ChatWidgetMount {
+export declare function mountChatWidget(options: MountChatWidgetOptions): Root;
+export interface ScriptMountResult extends ChatWidgetMount {
   shadowRoot: ShadowRoot;
 }
-declare function mountChatWidgetScript(script?: HTMLScriptElement): ScriptMountResult;
-declare function autoMountChatWidgetScript(script?: HTMLScriptElement | null): ScriptMountResult | null;
-//#endregion
-export { ChatWidgetMount, MountChatWidgetOptions, ScriptMountResult, autoMountChatWidgetScript, mountChatWidget, mountChatWidgetScript };
+export declare function mountChatWidgetScript(script?: HTMLScriptElement): ScriptMountResult;
+export declare function autoMountChatWidgetScript(script?: HTMLScriptElement | null): ScriptMountResult | null;
+//#endregion

package/dist/browser-mount.d.mts

@@ -110,6 +110,24 @@ type CreateChatTransport = (options: CreateChatTransportOptions) => ChatTranspor
 interface ChatWidgetProps {
   className?: string;
   createTransport?: CreateChatTransport;
+  /**
+   * Identity the host already knows, used to skip the pre-chat form.
+   *
+   * When both `name` and `email` are non-empty the widget opens straight into
+   * the conversation and bootstraps the session itself, instead of asking a
+   * signed-in user to retype what the host app already displays in its own
+   * header. A partial value (one field, or blanks) is treated as a prefill:
+   * the form still renders, with the known fields filled in.
+   *
+   * This seeds the *form*, and a form value is self-reported no matter who
+   * typed it. It is not, on its own, proof of identity — anyone can pass any
+   * address here. Verification is a separate, server-side mechanism: pass
+   * `resolveUser` to `createChatSessionHandler` on the host backend and it
+   * resolves the caller's real session behind the API key, which is what marks
+   * the resulting contact verified. Use both together for a signed-in user:
+   * this prop removes the typing, `resolveUser` is what makes it trustworthy.
+   */
+  defaultVisitor?: Partial<ChatWidgetVisitor>;
   getSession: GetSession;
   initiallyOpen?: boolean;
   launcherLabel?: string;
@@ -130,13 +148,13 @@ interface ChatWidgetProps {
 }
 //#endregion
 //#region src/browser-mount.d.ts
-interface MountChatWidgetOptions extends Omit<ChatWidgetProps, "getSession" | "widgetId"> {
+export interface MountChatWidgetOptions extends Omit<ChatWidgetProps, "getSession" | "widgetId"> {
   container: Element | ShadowRoot;
   sessionUrl: string;
   socketUrlTemplate?: string;
   widgetId: string;
 }
-interface ChatWidgetMount {
+export interface ChatWidgetMount {
   root: Root;
   /**
    * Repaint the widget in a different theme. `"auto"` resumes following the
@@ -148,11 +166,10 @@ interface ChatWidgetMount {
    */
   setTheme: (theme: ChatWidgetTheme) => void;
 }
-declare function mountChatWidget(options: MountChatWidgetOptions): Root;
-interface ScriptMountResult extends ChatWidgetMount {
+export declare function mountChatWidget(options: MountChatWidgetOptions): Root;
+export interface ScriptMountResult extends ChatWidgetMount {
   shadowRoot: ShadowRoot;
 }
-declare function mountChatWidgetScript(script?: HTMLScriptElement): ScriptMountResult;
-declare function autoMountChatWidgetScript(script?: HTMLScriptElement | null): ScriptMountResult | null;
-//#endregion
-export { ChatWidgetMount, MountChatWidgetOptions, ScriptMountResult, autoMountChatWidgetScript, mountChatWidget, mountChatWidgetScript };
+export declare function mountChatWidgetScript(script?: HTMLScriptElement): ScriptMountResult;
+export declare function autoMountChatWidgetScript(script?: HTMLScriptElement | null): ScriptMountResult | null;
+//#endregion