@lorikeetai/react-native-sdk 2.0.0 → 2.1.0

package/README.md

@@ -40,9 +40,6 @@ major. Widening them is a change that needs testing, not a version bump.
 - **`webviewProps` now reach the WebView.** The drop-in previously discarded
   them. If you were passing props that silently did nothing, they take effect
   now.
-- **Lazy ticket creation.** A ticket is no longer created when the widget opens,
-  which changes when conversations appear in your Lorikeet queue and in anything
-  counting them.
 
 ## Basic Usage
 
@@ -52,7 +49,7 @@ import { LorikeetWidgetView } from '@lorikeetai/react-native-sdk'
 export default function Screen() {
   return (
     <LorikeetWidgetView
-      publicKey="wk_xxx"
+      publicKey="your-public-key"
       authToken="your-auth-token"
       onWebViewMessage={(event) => console.log(event.nativeEvent.data)}
     />
@@ -62,7 +59,9 @@ export default function Screen() {
 
 **Props:**
 
-- `publicKey` (required): The public key for your Lorikeet account
+- `publicKey` (required): The public key issued for your Lorikeet account. Use the value you were
+  given rather than matching a shape: the format has changed over time, and keys issued under
+  earlier ones keep working
 - `authToken` (required): Authentication token for the user
 - `baseUrl` (optional): Base URL for the Lorikeet API (defaults to `https://chat.lorikeetcx.ai`)
 - `customisations` (optional): Widget customisation options. Exported as
@@ -79,6 +78,48 @@ export default function Screen() {
   defaults for media playback, scaling and the loading state can all be
   overridden; `onMessage` is additive, so the SDK reads the bridge first and
   then calls yours
+- `avoidKeyboard` (optional): Pads the widget clear of the keyboard. Defaults to
+  `true`. See [The keyboard](#the-keyboard)
+
+## The keyboard
+
+Android apps drawn edge to edge, the default for current Expo and React Native
+apps, no longer resize their window for the keyboard. `adjustResize` in the
+manifest does not change that. Nothing shrinks the WebView, so the keyboard
+covers the composer and the page is never told the keyboard is there.
+
+`LorikeetWidgetView` handles this itself: it wraps its content in a
+`KeyboardAvoidingView` with `behavior="padding"` on both platforms, and measures
+its own position so it works below a navigation header or tab bar. On iOS the
+same padding keeps the page's header on screen. If your screen already makes
+room for the keyboard, pass `avoidKeyboard={false}`, or the widget is padded
+twice.
+
+If you compose the parts yourself, the keyboard is yours. Wrap them in a
+`KeyboardAvoidingView` with `behavior="padding"` on both platforms, and set
+`keyboardVerticalOffset` to their distance from the top of the screen.
+`apps/rn-widget-demo/src/components/WidgetPane.tsx` measures it with
+`measureInWindow`. Check it on an Android device: an iOS simulator will not
+show the problem.
+
+## Which header you get
+
+`hideHeader` decides whose header the customer sees, not whether there is one.
+`LorikeetWidgetView` defaults it to `true`.
+
+| Value                          | The chat page's header | The SDK's own header                               |
+| ------------------------------ | ---------------------- | -------------------------------------------------- |
+| `false`                        | Shown                  | Not rendered                                       |
+| `true` (the drop-in's default) | Hidden                 | Rendered, with a new-chat control and nothing else |
+
+The page's header is the one carrying the controls for leaving a conversation.
+The SDK's carries a new-chat control and nothing else, so under the drop-in's
+default a host that neither sets `hideHeader: false` nor builds its own header
+leaves the customer no way out of the chat.
+
+Which controls the page's header offers, and what they are called, depends on
+the account. Build against "the page's own controls" rather than a fixed set,
+and ask us what your account serves before reproducing them.
 
 ## Resuming a conversation
 
@@ -101,7 +142,7 @@ useEffect(() => {
 
 return (
   <LorikeetWidgetView
-    publicKey="wk_xxx"
+    publicKey="your-public-key"
     authToken={token}
     ticketId={resume.ticketId}
     session={resume.session}
@@ -154,6 +195,43 @@ 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.
 
+## Minimise, end and new chat
+
+`close` means the page hid itself. It may carry a `reason`: a minimise keeps the
+conversation and offers a control that reopens it, an end offers one that starts a
+replacement. Treat an absent reason as an end, because that is what the widget
+does.
+
+Do not unmount on `close`. The end and any CSAT rating are still in flight, and
+tearing the page down cancels them. The widget hides the chat itself.
+
+While `ticketId` is set, the new-chat control reloads that conversation rather
+than replacing it. To start a new conversation, clear your stored `ticketId` and
+`session` and stop passing them, so the next load falls back to `/widget`.
+
+## The widget handle
+
+Pass a `ref` to `LorikeetWidgetView` to reach these.
+
+```tsx
+const widget = useRef<LorikeetWidgetHandle>(null)
+
+widget.current?.getConversation() // { minimised, ticketId?, session? } | null
+widget.current?.logout()
+widget.current?.reopen()
+```
+
+- `getConversation()` reports the conversation the widget is on, which is not
+  always the one the host passed in: a refused resume is replaced, and a new chat
+  replaces the conversation before it. It returns `null` until the page has
+  reported a ticket, and it can report a ticket with no session, so it supplements
+  the persistence events rather than replacing them.
+- `logout()` clears this customer's chat from the device. See
+  [Logging out](#logging-out).
+- `reopen()` shows a minimised conversation again, exactly as the customer left
+  it. Nothing reloads and nothing is reported. A no-op unless the widget is
+  minimised, so a host with its own launcher can call it unconditionally.
+
 ## Logging out
 
 Clearing your own stored `ticketId` and `session` is not enough. The chat keeps
@@ -194,11 +272,26 @@ 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.
+cookies were never cleared.
+
+So persist the logout before you start it, rather than recording that it failed.
+Write down the `baseUrl`, `publicKey` and cookie-store `webviewProps` you are
+clearing, read it at launch, and delete it only once `logged_out` has arrived.
+Waiting for `logout_failed` is not enough on its own: unmounting cancels its
+timer, so an app that dies inside the ten seconds reports nothing at all.
+
+Recovery then has to clear that recorded target rather than whatever the next
+launch happens to configure. The page drops only that public key's entry, and
+settings such as `sharedCookiesEnabled` decide which cookie store it reaches, so
+clearing another account or another store reports `logged_out` just the same.
+
+It does not need the customer who left, though. The page needs no `authToken`, so
+a host that no longer holds the departed customer's, which after a restart is the
+normal case, can still clear the device by navigating a WebView to
+`getLogoutUrl()` and waiting for its confirmation, as below. Do not reach for the
+drop-in's `logout()` here: it clears for whichever credentials are in props and
+then will not open a chat for them until they change, so calling it with the next
+customer's props locks that customer out instead of the last one.
 
 If you compose the parts yourself, build the URL and navigate to it:
 
@@ -215,8 +308,7 @@ 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.
+is storing a credential.
 
 ## Identity
 
@@ -307,8 +399,14 @@ WebView component that handles the widget content.
 
 ## Development
 
-- Build: `pnpm -w turbo build --filter=@lorikeetai/react-native-sdk`
-- Lint: `pnpm --filter=@lorikeetai/react-native-sdk lint`
+This package is outside the root pnpm workspace, on its own lockfile, so run these from `packages/react-native-widget` after `pnpm install` there.
+
+- Build: `pnpm build`
+- Test: `pnpm test`
+- Typecheck: `pnpm typecheck`
+- Lint: `pnpm lint`. It uses the root's oxlint and oxfmt, so run `pnpm install` at the repository root first.
+
+To release, bump `version` in `package.json` and add its `CHANGELOG.md` section in the same pull request. See `docs/engineering/sdk-releases.md`.
 
 ## License
 

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-//#region \0rolldown/runtime.js
+// \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -25,7 +25,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 
-//#endregion
 let react = require("react");
 let react_native = require("react-native");
 let react_native_safe_area_context = require("react-native-safe-area-context");
@@ -34,7 +33,7 @@ let react_native_svg = require("react-native-svg");
 react_native_svg = __toESM(react_native_svg, 1);
 let react_jsx_runtime = require("react/jsx-runtime");
 
-//#region src/bridge.ts
+// src/bridge.ts
 /**
 * The public key, base URL and token are one unit, and a conversation belongs to
 * the credentials that created it. Stamping an observation with them is what
@@ -54,8 +53,7 @@ const resumableConversation = (observed, identity, intendedTicketId) => {
 	};
 };
 
-//#endregion
-//#region src/encode.ts
+// src/encode.ts
 const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 /**
 * Base64 of a string's UTF-8 bytes.
@@ -82,8 +80,7 @@ function base64EncodeUtf8(value) {
 	return encoded;
 }
 
-//#endregion
-//#region \0@oxc-project+runtime@0.147.0/helpers/esm/typeof.js
+// \0@oxc-project+runtime@0.156.0/helpers/esm/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
 	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
@@ -93,8 +90,7 @@ function _typeof(o) {
 	}, _typeof(o);
 }
 
-//#endregion
-//#region \0@oxc-project+runtime@0.147.0/helpers/esm/toPrimitive.js
+// \0@oxc-project+runtime@0.156.0/helpers/esm/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -106,15 +102,13 @@ function toPrimitive(t, r) {
 	return ("string" === r ? String : Number)(t);
 }
 
-//#endregion
-//#region \0@oxc-project+runtime@0.147.0/helpers/esm/toPropertyKey.js
+// \0@oxc-project+runtime@0.156.0/helpers/esm/toPropertyKey.js
 function toPropertyKey(t) {
 	var i = toPrimitive(t, "string");
 	return "symbol" == _typeof(i) ? i : i + "";
 }
 
-//#endregion
-//#region \0@oxc-project+runtime@0.147.0/helpers/esm/defineProperty.js
+// \0@oxc-project+runtime@0.156.0/helpers/esm/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -124,8 +118,7 @@ function _defineProperty(e, r, t) {
 	}) : e[r] = t, e;
 }
 
-//#endregion
-//#region src/client.ts
+// src/client.ts
 var LorikeetClient = class {
 	constructor({ customisations, api_base, metadata, public_key }) {
 		_defineProperty(this, "baseUrl", "https://chat.lorikeetcx.ai");
@@ -171,8 +164,7 @@ var LorikeetClient = class {
 	}
 };
 
-//#endregion
-//#region src/errors.ts
+// src/errors.ts
 /**
 * The chat page's error vocabulary, as it reaches a host in
 * `{ type: 'error', error: CODE }`. Mirrored here because the page publishes it
@@ -219,8 +211,7 @@ function isUnusableConversation(message) {
 	return type === "error" && typeof error === "string" ? isUnusableConversationCode(error) : false;
 }
 
-//#endregion
-//#region src/events.ts
+// src/events.ts
 const asRecord = (message) => typeof message === "object" && message !== null && !Array.isArray(message) ? message : null;
 const asNonEmptyString = (value) => typeof value === "string" && value !== "" ? value : null;
 /**
@@ -298,8 +289,7 @@ const resumedTicketIdFromUri = (uri) => {
 	return (_segments$ = segments[2]) !== null && _segments$ !== void 0 ? _segments$ : null;
 };
 
-//#endregion
-//#region src/lifecycle.ts
+// src/lifecycle.ts
 /**
 * The page gives its message stream ten attempts with exponential backoff
 * capped at 30s (`message-stream-utils.tsx`), so the budget runs out roughly
@@ -336,8 +326,7 @@ const shouldReloadAfterBackground = (backgroundedAt, now, thresholdMs = BACKGROU
 	return elapsed >= thresholdMs;
 };
 
-//#endregion
-//#region src/links.ts
+// src/links.ts
 /**
 * Schemes the WebView resolves for itself. None of them is a page the customer
 * asked to leave the app for, and the OS cannot open them anyway.
@@ -382,8 +371,7 @@ const isInternalNavigation = (url, baseUrl) => {
 	return target.origin === base.origin;
 };
 
-//#endregion
-//#region src/message-circle-plus-icon.tsx
+// src/message-circle-plus-icon.tsx
 const MessageCirclePlusIcon = ({ size = 24, color = "currentColor", strokeWidth = 2 }) => {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_native_svg.default, {
 		fill: "none",
@@ -420,13 +408,13 @@ const MessageCirclePlusIcon = ({ size = 24, color = "currentColor", strokeWidth
 	});
 };
 
-//#endregion
-//#region src/widget.tsx
+// src/widget.tsx
 const stylesheet = react_native.StyleSheet.create({
 	root: {
 		flex: 1,
 		backgroundColor: "#fff"
 	},
+	keyboardAvoiding: { flex: 1 },
 	container: {
 		flex: 1,
 		borderRadius: 8,
@@ -530,7 +518,7 @@ const LorikeetWidgetHeader = ({ title, style, icon = /* @__PURE__ */ (0, react_j
 		]
 	});
 };
-const LorikeetWidgetView = (0, react.forwardRef)(function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, styles, onEvent, onWebViewMessage, ticketId, session, metadata, webviewProps }, ref) {
+const LorikeetWidgetView = (0, react.forwardRef)(function LorikeetWidgetView({ publicKey, baseUrl, authToken, customisations, styles, onEvent, onWebViewMessage, ticketId, session, metadata, webviewProps, avoidKeyboard = true }, ref) {
 	var _customisations$hideH, _customisations$title;
 	const [lorikeetClient, setLorikeetClient] = (0, react.useState)(null);
 	const [loaded, setLoaded] = (0, react.useState)(null);
@@ -541,6 +529,15 @@ const LorikeetWidgetView = (0, react.forwardRef)(function LorikeetWidgetView({ p
 		setGeneration((previous) => previous + 1);
 	}, []);
 	const webViewRef = (0, react.useRef)(null);
+	const containerRef = (0, react.useRef)(null);
+	const [keyboardOffset, setKeyboardOffset] = (0, react.useState)(0);
+	const measureKeyboardOffset = (0, react.useCallback)((event) => {
+		var _containerRef$current;
+		const { y } = event.nativeEvent.layout;
+		(_containerRef$current = containerRef.current) === null || _containerRef$current === void 0 || _containerRef$current.measureInWindow((_x, windowY) => {
+			setKeyboardOffset(windowY - y);
+		});
+	}, []);
 	const [refusedTicketId, setRefusedTicketId] = (0, react.useState)(null);
 	const observedRef = (0, react.useRef)(null);
 	const backgroundedAtRef = (0, react.useRef)(null);
@@ -828,68 +825,75 @@ const LorikeetWidgetView = (0, react.forwardRef)(function LorikeetWidgetView({ p
 			"right"
 		],
 		style: stylesheet.root,
-		children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_native.View, {
-			style: stylesheet.container,
-			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);
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_native.KeyboardAvoidingView, {
+			behavior: "padding",
+			enabled: avoidKeyboard,
+			keyboardVerticalOffset: keyboardOffset,
+			onLayout: measureKeyboardOffset,
+			style: stylesheet.keyboardAvoiding,
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_native.View, {
+				ref: containerRef,
+				style: stylesheet.container,
+				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.LOGOUT_CONFIRMATION_TIMEOUT_MS = LOGOUT_CONFIRMATION_TIMEOUT_MS;
 exports.LORIKEET_ERROR_CODES = LORIKEET_ERROR_CODES;
 exports.LorikeetClient = LorikeetClient;