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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LorikeetCX.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,12 +2,50 @@
 
 SDK containing embeddable React Native components that renders the LorikeetCX web widget inside a react-native-webview.
 
+> **Alpha.** The surface can still change between releases. Resume, storage and
+> token refresh are host responsibilities today; see [Resuming a
+> conversation](#resuming-a-conversation) and [Identity](#identity).
+
 ## Installation
 
+The three native modules are peer dependencies, so install them alongside the
+SDK. Name them explicitly rather than relying on your package manager to add
+them for you: npm and pnpm auto-install peers, but **neither Yarn Classic nor
+Yarn Berry does, and neither fails the install.** Classic prints `has unmet peer
+dependency`, Berry prints `YN0002 ... doesn't provide`, and both exit
+successfully, and the failure surfaces later, when Metro cannot resolve the
+module.
+Metro reports one missing module at a time, so install all three at once.
+
+Name the SDK's version too. Alphas go to the `alpha` dist tag, not `latest`, so a
+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
+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
 ```
 
+These are native modules, so rebuild rather than just restarting the bundler:
+`pod install` for iOS, a Gradle sync for Android.
+
+The peer ranges are bounded to the major versions this release is built and
+tested against, so an unpinned install cannot silently resolve to an untested
+major. Widening them is a change that needs testing, not a version bump.
+
+### Upgrading from 1.x
+
+- **Peer dependencies.** The three modules above used to arrive transitively.
+  Declare them yourself, and rebuild native.
+- **`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
 
 ```tsx
@@ -29,9 +67,204 @@ 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
+  routing or for the agent to read. Survives a resume
+- `webviewProps` (optional): Forwarded to the underlying WebView. The SDK's
+  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
+
+## Resuming a conversation
+
+Without `ticketId`, every mount loads `/widget`, and `/widget` mints a new
+ticket. A customer who closes the app and comes back gets an empty chat while
+their previous ticket stays open.
+
+The widget reports what you need to resume over the WebView bridge. Store both
+values, scoped to the customer, somewhere that survives an app restart, and pass
+them back on the next mount:
+
+```tsx
+const [resume, setResume] = useState<{ ticketId?: string; session?: string }>(
+  {},
+)
+
+useEffect(() => {
+  void loadResumeForCustomer(customerId).then(setResume)
+}, [customerId])
+
+return (
+  <LorikeetWidgetView
+    publicKey="wk_xxx"
+    authToken={token}
+    ticketId={resume.ticketId}
+    session={resume.session}
+    onWebViewMessage={(event) => {
+      const message = JSON.parse(event.nativeEvent.data)
+      if (message.type === 'persistLorikeetTicketId') {
+        void saveResumeForCustomer(customerId, { ticketId: message.ticketId })
+      }
+      if (message.type === 'persistLorikeetSession') {
+        void saveResumeForCustomer(customerId, { session: message.session })
+      }
+    }}
+  />
+)
+```
+
+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 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
+to the credentials that created it. Never take some of the three from one source
+and the rest from another, even briefly during a render.
+
+When any of them change, which includes logout and switching environment, clear
+your stored `ticketId` and `session` at the same time. Keeping them across a
+credential change either resumes the previous customer's conversation on a
+shared device or sends a ticket id to a backend that has never heard of it.
+
+Anything you load or persist asynchronously needs to be discarded if the
+credentials moved on while it was in flight; a write that lands late will
+otherwise put the old conversation back.
+
+## App lifecycle
+
+The drop-in handles two failures that a WebView does not recover from on its own:
+
+- **Renderer death.** When the OS kills the WebView's content process, the view
+  goes permanently blank with no error. The SDK detects this on both platforms
+  and remounts.
+- **A stale stream after a long background.** The chat page gives its message
+  stream ten attempts with backoff capped at 30s, then stops trying. If the app
+  was backgrounded past that budget, the SDK remounts on return rather than
+  showing a conversation whose stream is dead. Shorter absences are left alone,
+  so an app switch does not cost the customer a draft message.
+
+In both cases the remount resumes the conversation that was on screen. The SDK
+watches the bridge for the live ticket and its session, so a conversation created
+by a mount that had no `ticketId` is not lost, which is what a naive reload would
+do: it would load `/widget` again and mint a second ticket. That memory
+lasts for the life of the component and is scoped to the credentials that
+produced it; surviving a process death is still your storage's job.
+
+If you compose the parts yourself rather than using `LorikeetWidgetView`, both
+are yours to handle.
+
+## Customisation encoding
+
+`customisations` is serialised as base64 of its UTF-8 bytes, which is what the
+chat page decodes. Any Unicode is safe, including emoji and typographic
+punctuation. Earlier versions used the global `btoa`, which accepts Latin-1
+only: a title such as `Self's AI Agent` with a typographic apostrophe threw
+during render.
 
 ## Headless components
 
@@ -71,7 +304,8 @@ WebView component that handles the widget content.
 
 - `uri` (required): The URI that the web view will load
 - `baseUrl` (optional): Base URL for the Lorikeet API (defaults to `https://chat.lorikeetcx.ai`)
-- `webviewProps` (optional): Passed through to the webview component
+- `webviewProps` (optional): Passed through to the webview component. The SDK
+  adds external-link handling on `onNavigationStateChange` and then calls yours
 
 ## Development