@lorikeetai/react-native-sdk 2.0.0-alpha.1 → 2.0.0-alpha.2

package/README.md

@@ -22,7 +22,7 @@ bare `pnpm add @lorikeetai/react-native-sdk` installs the 1.x line, and no
 semver range reaches a prerelease either.
 
 ```bash
-pnpm add @lorikeetai/react-native-sdk@2.0.0-alpha.1 \
+pnpm add @lorikeetai/react-native-sdk@2.0.0-alpha.2 \
   react-native-webview@^13.15.0 \
   react-native-safe-area-context@^5.6.0 \
   react-native-svg@^15.13.0
@@ -67,9 +67,12 @@ export default function Screen() {
 - `publicKey` (required): The public key for your Lorikeet account
 - `authToken` (required): Authentication token for the user
 - `baseUrl` (optional): Base URL for the Lorikeet API (defaults to `https://chat.lorikeetcx.ai`)
-- `customisations` (optional): Widget customization options from `@lorikeetai/web-sdk`
+- `customisations` (optional): Widget customisation options. Exported as
+  `Customisations` from this package, so there is nothing else to install
 - `styles` (optional): Style overrides for the header text
-- `onWebViewMessage` (optional): Handler for messages from the webview
+- `onEvent` (optional): What the page reported, as typed events. See [Events](#events)
+- `onWebViewMessage` (optional): Handler for raw messages from the webview.
+  Deprecated in favour of `onEvent`, and still called
 - `ticketId` (optional): Resume this conversation instead of starting a new one
 - `session` (optional): The session token that authorises `ticketId`
 - `metadata` (optional): Arbitrary context attached to the conversation, for
@@ -121,13 +124,102 @@ Pass both or neither. `session` authorises exactly the ticket it was issued
 for, and a resume without it fails with `CUSTOMER_ID_MISSING`.
 
 The SDK does not store these for you, and it does not clear them. On logout,
-clear your own copy, or the next customer on that device resumes the previous
-one's conversation.
+clear your own copy and call the widget's `logout()`; see
+[Logging out](#logging-out).
 
 While `ticketId` is set, the header's new-chat icon reloads that conversation
 rather than starting a new one. To start a new one, clear your stored
 `ticketId` and `session` and let the next mount fall back to `/widget`.
 
+## Events
+
+`onEvent` reports what the page said, as a `LorikeetWidgetEvent`:
+
+| Event                             | Means                                                           |
+| --------------------------------- | --------------------------------------------------------------- |
+| `ready`                           | The conversation is usable                                      |
+| `ticket_created`                  | A ticket this page load created. Once per ticket, never a resume |
+| `customer_message`                | The customer sent something                                     |
+| `agent_message`                   | The agent replied. `markUnread` is the page asking for an unread indicator |
+| `close`                           | The page hid itself, with a `reason` of `ended_by_customer` or `minimised` |
+| `conversation_ended`              | It ended without the customer ending it                         |
+| `new_chat`                        | The page is asking for a replacement conversation               |
+| `persist_ticket_id`               | Store this, with the session, to resume later                   |
+| `persist_session`                 | The other half of that pair                                     |
+| `logged_out`                      | `/logout` cleared this frame. See [Logging out](#logging-out)    |
+| `logout_failed`                   | `/logout` did not confirm. The widget stays unavailable          |
+| `error`                           | A page-level failure. `LORIKEET_ERROR_CODES` lists the codes     |
+
+Names match the web SDK's wherever it has one, so a host integrating both does
+not learn two vocabularies.
+
+`preload_complete` is in the union but cannot reach React Native: the preload
+page posts it to a web parent only. Do not wait on it.
+
+## Logging out
+
+Clearing your own stored `ticketId` and `session` is not enough. The chat keeps
+cookies and its own storage inside the WebView, which native code cannot reach,
+so the next person on the device can reopen the previous customer's
+conversation. Only the chat's `/logout` page can clear those, and only if the
+WebView is navigated to it.
+
+With the drop-in, call `logout()` on its ref:
+
+```tsx
+const widget = useRef<LorikeetWidgetHandle>(null)
+
+return (
+  <>
+    <LorikeetWidgetView {...props} ref={widget} />
+    <Button
+      onPress={() => {
+        widget.current?.logout()
+        void clearResumeForCustomer(customerId)
+      }}
+      title="Sign out"
+    />
+  </>
+)
+```
+
+The widget stays on that page until the chat confirms, and nothing you pass it
+in the meantime changes that: handing it the next customer's credentials while
+the clear is still running would unmount the page mid-clear and leave the last
+customer's cookies on the device. Pass them once `logged_out` has arrived and
+the next chat starts normally.
+
+A logout that does not confirm within ten seconds reports `logout_failed` and
+leaves the widget unavailable rather than opening a chat on a device the
+previous customer's credentials still unlock. Call `logout()` again to retry.
+
+That obligation outlives the component. The SDK stores nothing, so a widget
+unmounted before the clear confirmed, by a screen change or an app restart,
+comes back with no memory of it and opens a chat normally, on a device whose
+cookies were never cleared. Record the failure alongside the conversation you
+already store, and call `logout()` again before mounting a chat for anyone
+else. We would rather own this than ask you to, and
+[ADP-3160](https://linear.app/lorikeet/issue/ADP-3160) is where that storage
+layer belongs.
+
+If you compose the parts yourself, build the URL and navigate to it:
+
+```tsx
+const client = new LorikeetClient({ public_key: publicKey, api_base: baseUrl })
+
+setUri(client.getLogoutUrl())
+```
+
+Either way, wait for `logged_out` before treating the device as clean. The
+WebView's load event does not prove anything: an error page fires it too.
+
+The anonymous customer's long-lived token is deliberately not among these
+events. It identifies the same anonymous customer for a year, this SDK offers
+no way to hand one back, and the web SDK keeps the same message inside the
+frame. A host that genuinely needs it can read the raw bridge, but storing it
+is storing a credential, and [ADP-3160](https://linear.app/lorikeet/issue/ADP-3160)
+is the work that should remove the need.
+
 ## Identity
 
 The public key, base URL and auth token are one unit, and a conversation belongs

package/dist/index.cjs

@@ -144,6 +144,26 @@ var LorikeetClient = class {
 			if (this.metadata) url.searchParams.append("metadata", JSON.stringify(this.metadata));
 			return url.toString();
 		});
+		_defineProperty(
+			this,
+			/**
+			* The page that clears this key's credentials from the WebView: its cookies,
+			* server-side, and the storage the frame keeps. Navigating a WebView here is
+			* the only way to reach either, so a host that only drops its own copy of
+			* `ticketId` and `session` leaves the next person on the device able to
+			* reopen the conversation.
+			*
+			* The page confirms with a `loggedOut` message, which the SDK reports as
+			* `logged_out`. The load event does not: an error page fires that too.
+			*/
+			"getLogoutUrl",
+			() => {
+				const url = new URL(this.baseUrl);
+				url.pathname = "/logout";
+				url.searchParams.append("public_key", this.publicKey);
+				return url.toString();
+			}
+		);
 		if (api_base) this.baseUrl = api_base;
 		this.publicKey = public_key;
 		if (customisations) this.customisations = customisations;
@@ -210,7 +230,10 @@ const eventFromMessage = (message) => {
 	switch (record.type) {
 		case "ready": return { type: "ready" };
 		case "customerMessage": return { type: "customer_message" };
-		case "agentMessage": return { type: "agent_message" };
+		case "agentMessage": return typeof record.markUnread === "boolean" ? {
+			type: "agent_message",
+			markUnread: record.markUnread
+		} : { type: "agent_message" };
 		case "closeChat": {
 			const reason = asNonEmptyString(record.reason);
 			return reason === "ended_by_customer" || reason === "minimised" ? {
@@ -234,6 +257,7 @@ const eventFromMessage = (message) => {
 				session
 			};
 		}
+		case "loggedOut": return { type: "logged_out" };
 		case "error": {
 			const error = asNonEmptyString(record.error);
 			return error === null ? null : {
@@ -284,6 +308,13 @@ const resumedTicketIdFromUri = (uri) => {
 */
 const BACKGROUND_RELOAD_THRESHOLD_MS = 18e4;
 /**
+* How long `/logout` gets to confirm it cleared the frame before the host is
+* told it did not. Matches the web SDK's own budget, and like it, a logout that
+* misses the deadline leaves the widget unavailable rather than letting the next
+* customer start a chat on a device the previous one's credentials still open.
+*/
+const LOGOUT_CONFIRMATION_TIMEOUT_MS = 1e4;
+/**
 * Elapsed time is the only signal available: the bridge reports `ready`,
 * `error` and the persistence messages, but never stream health, so the SDK
 * cannot ask whether the connection actually survived.
@@ -410,6 +441,7 @@ const stylesheet = react_native.StyleSheet.create({
 		textAlign: "center",
 		fontSize: 16
 	},
+	closedControl: { padding: 16 },
 	webView: { flex: 1 },
 	closed: {
 		flex: 1,
@@ -488,8 +520,8 @@ const LorikeetWidgetHeader = ({ title, style, icon = /* @__PURE__ */ (0, react_j
 		]
 	});
 };
-function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, styles, onEvent, onWebViewMessage, ticketId, session, metadata, webviewProps }) {
-	var _customisations$title;
+const LorikeetWidgetView = (0, react.forwardRef)(function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, styles, onEvent, onWebViewMessage, ticketId, session, metadata, webviewProps }, ref) {
+	var _customisations$hideH, _customisations$title;
 	const [lorikeetClient, setLorikeetClient] = (0, react.useState)(null);
 	const [loaded, setLoaded] = (0, react.useState)(null);
 	const [generation, setGeneration] = (0, react.useState)(0);
@@ -514,7 +546,12 @@ function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, sty
 	});
 	const resumingTicketId = ticketId !== void 0 && ticketId !== refusedTicketId ? ticketId : void 0;
 	const [attemptedTicketId, setAttemptedTicketId] = (0, react.useState)(void 0);
-	const [closed, setClosed] = (0, react.useState)(false);
+	const [closed, setClosed] = (0, react.useState)(null);
+	const [clearing, setClearing] = (0, react.useState)(null);
+	const [loggedOutIdentity, setLoggedOutIdentity] = (0, react.useState)(null);
+	const onEventRef = (0, react.useRef)(onEvent);
+	onEventRef.current = onEvent;
+	const hideHeader = (_customisations$hideH = customisations === null || customisations === void 0 ? void 0 : customisations.hideHeader) !== null && _customisations$hideH !== void 0 ? _customisations$hideH : true;
 	const load = (0, react.useCallback)((client, forIdentity, intendedTicketId, resume, force = false) => {
 		const next = client.getWebviewUrl({
 			token: authToken,
@@ -522,7 +559,7 @@ function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, sty
 			session: resume === null || resume === void 0 ? void 0 : resume.session
 		});
 		const unchanged = uriRef.current === next;
-		if (loadedForRef.current.identity !== forIdentity || loadedForRef.current.intendedTicketId !== intendedTicketId) setClosed(false);
+		if (loadedForRef.current.identity !== forIdentity || loadedForRef.current.intendedTicketId !== intendedTicketId) setClosed(null);
 		uriRef.current = next;
 		loadedForRef.current = {
 			identity: forIdentity,
@@ -551,10 +588,12 @@ function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, sty
 			metadata,
 			customisations: {
 				...customisations,
-				hideHeader: (customisations === null || customisations === void 0 ? void 0 : customisations.hideHeader) === void 0 ? true : customisations.hideHeader
+				hideHeader
 			}
 		});
 		setLorikeetClient(lorikeetClient);
+		if (clearing !== null || loggedOutIdentity === identity) return;
+		if (loggedOutIdentity !== null) setLoggedOutIdentity(null);
 		const resume = resumingTicketId !== void 0 ? {
 			session,
 			ticketId: resumingTicketId
@@ -564,13 +603,108 @@ function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, sty
 		publicKey,
 		baseUrl,
 		authToken,
+		clearing,
 		customisations,
+		hideHeader,
+		loggedOutIdentity,
 		metadata,
 		session,
 		resumingTicketId,
 		identity,
 		load
 	]);
+	/**
+	* Clear this customer's chat from the device. Loads the page's own `/logout`,
+	* the only thing that can drop the chat's cookies and the storage the page
+	* keeps; a host clearing its stored `ticketId` and `session` leaves both
+	* behind.
+	*
+	* Nothing else loads until the page confirms with `logged_out`, and nothing
+	* loads for these credentials after it, so pass the next customer's in to
+	* start their chat. Clear your own stored `ticketId` and `session` too.
+	*/
+	const logout = (0, react.useCallback)(() => {
+		observedRef.current = null;
+		setClosed(null);
+		setClearing((previous) => {
+			if (previous !== null) return {
+				...previous,
+				attempt: previous.attempt + 1
+			};
+			setLoggedOutIdentity(identity);
+			return {
+				attempt: 1,
+				baseUrl,
+				identity,
+				uri: new LorikeetClient({
+					api_base: baseUrl,
+					public_key: publicKey
+				}).getLogoutUrl(),
+				webviewProps: {
+					...webviewProps,
+					injectedJavaScript: void 0,
+					injectedJavaScriptBeforeContentLoaded: void 0,
+					onMessage: void 0,
+					onShouldStartLoadWithRequest: void 0
+				}
+			};
+		});
+	}, [
+		baseUrl,
+		identity,
+		publicKey,
+		webviewProps
+	]);
+	/**
+	* Show a minimised conversation again, exactly as the customer left it.
+	*
+	* A no-op unless something is minimised, so a host with its own launcher can
+	* call it without first asking.
+	*/
+	const reopen = (0, react.useCallback)(() => {
+		setClosed((previous) => previous === "minimised" ? null : previous);
+	}, []);
+	/**
+	* What the widget is actually on, for a host that has to store it or draw its
+	* own launcher around it.
+	*/
+	const getConversation = (0, react.useCallback)(() => {
+		const resumable = resumableConversation(observedRef.current, identity, resumingTicketId);
+		if (resumable === null) return null;
+		return {
+			minimised: closed === "minimised",
+			session: resumable.session,
+			ticketId: resumable.ticketId
+		};
+	}, [
+		closed,
+		identity,
+		resumingTicketId
+	]);
+	(0, react.useImperativeHandle)(ref, () => ({
+		getConversation,
+		logout,
+		reopen
+	}), [
+		getConversation,
+		logout,
+		reopen
+	]);
+	const clearingAttempt = clearing === null || clearing === void 0 ? void 0 : clearing.attempt;
+	(0, react.useEffect)(() => {
+		if (clearingAttempt === void 0) return;
+		const timer = setTimeout(() => {
+			var _onEventRef$current;
+			(_onEventRef$current = onEventRef.current) === null || _onEventRef$current === void 0 || _onEventRef$current.call(onEventRef, { type: "logout_failed" });
+		}, LOGOUT_CONFIRMATION_TIMEOUT_MS);
+		return () => {
+			clearTimeout(timer);
+		};
+	}, [clearingAttempt]);
+	const handleClearingEvent = (0, react.useCallback)((event) => {
+		if (event.type === "logged_out") setClearing((previous) => (previous === null || previous === void 0 ? void 0 : previous.attempt) === clearingAttempt ? null : previous);
+		onEvent === null || onEvent === void 0 || onEvent(event);
+	}, [clearingAttempt, onEvent]);
 	const reload = (0, react.useCallback)(() => {
 		const resume = resumableConversation(observedRef.current, identity, resumingTicketId);
 		if (lorikeetClient !== null && resume !== null) {
@@ -602,7 +736,7 @@ function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, sty
 		};
 	}, [reload]);
 	const startNewChat = (0, react.useCallback)(() => {
-		setClosed(false);
+		setClosed(null);
 		if (lorikeetClient !== null && resumingTicketId === void 0) {
 			observedRef.current = null;
 			load(lorikeetClient, identity, void 0, null, true);
@@ -628,7 +762,7 @@ function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, sty
 					intendedTicketId: resumingTicketId
 				};
 			}
-			if (event.type === "close") setClosed(true);
+			if (event.type === "close") setClosed(event.reason === "minimised" ? "minimised" : "ended");
 			if (event.type === "new_chat") startNewChat();
 			if (event.type === "error" && attemptedTicketId !== void 0 && isUnusableConversationCode(event.error)) {
 				observedRef.current = null;
@@ -652,7 +786,31 @@ function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, sty
 		onWebViewMessage === null || onWebViewMessage === void 0 || onWebViewMessage(event);
 		webviewProps === null || webviewProps === void 0 || (_webviewProps$onMessa2 = webviewProps.onMessage) === null || _webviewProps$onMessa2 === void 0 || _webviewProps$onMessa2.call(webviewProps, event);
 	}, [onWebViewMessage, webviewProps]);
-	if (lorikeetClient === null || loaded === null || loaded.identity !== identity || loaded.intendedTicketId !== resumingTicketId) return null;
+	if (clearing !== null) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_native_safe_area_context.SafeAreaView, {
+		edges: [
+			"top",
+			"left",
+			"right"
+		],
+		style: stylesheet.root,
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_native.View, {
+			accessibilityElementsHidden: true,
+			importantForAccessibility: "no-hide-descendants",
+			pointerEvents: "none",
+			style: stylesheet.closed,
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(LorikeetWidgetWebView, {
+				baseUrl: clearing.baseUrl,
+				onEvent: handleClearingEvent,
+				uri: clearing.uri,
+				webviewProps: {
+					...clearing.webviewProps,
+					style: stylesheet.webView
+				}
+			}, `logout|${clearing.attempt}`)
+		})
+	});
+	if (lorikeetClient === null || loaded === null || loaded.identity !== identity || loaded.intendedTicketId !== resumingTicketId || loggedOutIdentity === identity) return null;
+	const isClosed = closed !== null;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_native_safe_area_context.SafeAreaView, {
 		edges: [
 			"top",
@@ -662,44 +820,64 @@ function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, sty
 		style: stylesheet.root,
 		children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_native.View, {
 			style: stylesheet.container,
-			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(LorikeetWidgetHeader, {
-				onIconPress: startNewChat,
-				style: styles === null || styles === void 0 ? void 0 : styles.header,
-				title: (_customisations$title = customisations === null || customisations === void 0 ? void 0 : customisations.title) !== null && _customisations$title !== void 0 ? _customisations$title : "Lorikeet AI Agent"
-			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_native.View, {
-				accessibilityElementsHidden: closed,
-				importantForAccessibility: closed ? "no-hide-descendants" : "auto",
-				pointerEvents: closed ? "none" : "auto",
-				style: closed ? stylesheet.closed : stylesheet.webView,
-				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(LorikeetWidgetWebView, {
-					baseUrl: lorikeetClient.baseUrl,
-					onEvent: handleEvent,
-					ref: webViewRef,
-					uri: loaded.uri,
-					webviewProps: {
-						allowsInlineMediaPlayback: true,
-						mediaPlaybackRequiresUserAction: false,
-						scalesPageToFit: true,
-						startInLoadingState: true,
-						style: stylesheet.webView,
-						...webviewProps,
-						onMessage: handleMessage,
-						onRenderProcessGone: (event) => {
-							var _webviewProps$onRende;
-							if (generation === generationRef.current) reload();
-							webviewProps === null || webviewProps === void 0 || (_webviewProps$onRende = webviewProps.onRenderProcessGone) === null || _webviewProps$onRende === void 0 || _webviewProps$onRende.call(webviewProps, event);
-						},
-						onContentProcessDidTerminate: (event) => {
-							var _webviewProps$onConte;
-							if (generation === generationRef.current) reload();
-							webviewProps === null || webviewProps === void 0 || (_webviewProps$onConte = webviewProps.onContentProcessDidTerminate) === null || _webviewProps$onConte === void 0 || _webviewProps$onConte.call(webviewProps, event);
+			children: [
+				hideHeader && closed !== "minimised" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(LorikeetWidgetHeader, {
+					onIconPress: startNewChat,
+					style: styles === null || styles === void 0 ? void 0 : styles.header,
+					title: (_customisations$title = customisations === null || customisations === void 0 ? void 0 : customisations.title) !== null && _customisations$title !== void 0 ? _customisations$title : "Lorikeet AI Agent"
+				}) : null,
+				closed === "minimised" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_native.TouchableOpacity, {
+					onPress: reopen,
+					style: stylesheet.closedControl,
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_native.Text, {
+						style: stylesheet.headerText,
+						children: "Reopen chat"
+					})
+				}) : null,
+				!hideHeader && closed === "ended" ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_native.TouchableOpacity, {
+					onPress: startNewChat,
+					style: stylesheet.closedControl,
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_native.Text, {
+						style: stylesheet.headerText,
+						children: "Start new chat"
+					})
+				}) : null,
+				/* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_native.View, {
+					accessibilityElementsHidden: isClosed,
+					importantForAccessibility: isClosed ? "no-hide-descendants" : "auto",
+					pointerEvents: isClosed ? "none" : "auto",
+					style: isClosed ? stylesheet.closed : stylesheet.webView,
+					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(LorikeetWidgetWebView, {
+						baseUrl: lorikeetClient.baseUrl,
+						onEvent: handleEvent,
+						ref: webViewRef,
+						uri: loaded.uri,
+						webviewProps: {
+							allowsInlineMediaPlayback: true,
+							mediaPlaybackRequiresUserAction: false,
+							scalesPageToFit: true,
+							startInLoadingState: true,
+							style: stylesheet.webView,
+							...webviewProps,
+							onMessage: handleMessage,
+							onRenderProcessGone: (event) => {
+								var _webviewProps$onRende;
+								if (generation === generationRef.current) reload();
+								webviewProps === null || webviewProps === void 0 || (_webviewProps$onRende = webviewProps.onRenderProcessGone) === null || _webviewProps$onRende === void 0 || _webviewProps$onRende.call(webviewProps, event);
+							},
+							onContentProcessDidTerminate: (event) => {
+								var _webviewProps$onConte;
+								if (generation === generationRef.current) reload();
+								webviewProps === null || webviewProps === void 0 || (_webviewProps$onConte = webviewProps.onContentProcessDidTerminate) === null || _webviewProps$onConte === void 0 || _webviewProps$onConte.call(webviewProps, event);
+							}
 						}
-					}
-				}, `${identity}|${resumingTicketId !== null && resumingTicketId !== void 0 ? resumingTicketId : ""}|${generation}`)
-			})]
+					}, `${identity}|${resumingTicketId !== null && resumingTicketId !== void 0 ? resumingTicketId : ""}|${generation}`)
+				})
+			]
 		})
 	});
-}
+});
+LorikeetWidgetView.displayName = "LorikeetWidgetView";
 
 //#endregion
 exports.LORIKEET_ERROR_CODES = LORIKEET_ERROR_CODES;