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

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.1 \
+  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
@@ -32,6 +70,109 @@ export default function Screen() {
 - `customisations` (optional): Widget customization options from `@lorikeetai/web-sdk`
 - `styles` (optional): Style overrides for the header text
 - `onWebViewMessage` (optional): Handler for messages from the webview
+- `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, or the next customer on that device resumes the previous
+one's conversation.
+
+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`.
+
+## 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 +212,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