@ringg/react-native 0.2.0 → 0.4.0

package/README.md

@@ -0,0 +1,300 @@
+# @ringg/react-native
+
+> ⚠️ **Alpha / pre-release.** Expect rough edges and breaking changes between
+> versions. Pin an exact version if you need stability, and please report
+> anything you hit. See **[Known issues](#known-issues)** below.
+
+Embeddable chat + voice-call widget for [Ringg AI](https://ringg.ai) agents —
+the React Native implementation. Drop `<RinggWidget />` over your app for text
+chat, voice calls, interactive components (forms, calendars, quick replies,
+Block Kit) and a post-call feedback screen.
+
+It runs on the same headless brain as the web widget (`@ringg/core`, bundled
+into this package), so conversation behaviour — reconnection, typing timing,
+message ordering, optimistic sends — is identical across platforms. Only the
+views are native.
+
+## Install
+
+```bash
+npm install @ringg/react-native
+```
+
+Then the three native modules. React Native autolinking only wires native code
+that resolves from **your** app's `node_modules`, so these cannot be ours:
+
+```bash
+npx expo install @livekit/react-native @livekit/react-native-webrtc react-native-svg
+# or, without Expo:
+npm install @livekit/react-native @livekit/react-native-webrtc react-native-svg
+```
+
+Requires React ≥ 18 · React Native ≥ 0.73.
+
+**Expo Go will not work** — LiveKit ships native code, so you need a
+[development build](https://docs.expo.dev/develop/development-builds/introduction/).
+
+## Platform setup (required for voice)
+
+Voice calls need a microphone, background audio and LiveKit's manifest
+metadata. Text chat needs none of it.
+
+**Expo** — add the plugin to `app.json` and rebuild. It applies all of the
+above, including the native transport's own configuration:
+
+```json
+{
+  "expo": {
+    "plugins": ["@ringg/react-native"]
+  }
+}
+```
+
+To change the microphone prompt your users see:
+
+```json
+{
+  "expo": {
+    "plugins": [["@ringg/react-native", { "microphonePermissionText": "Talk to support." }]]
+  }
+}
+```
+
+**Bare React Native** — no config plugins, so the same values by hand.
+
+`ios/<App>/Info.plist`:
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>Voice calls use the microphone.</string>
+<key>UIBackgroundModes</key>
+<array><string>audio</string></array>
+```
+
+`android/app/src/main/AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+```
+
+## Integrate
+
+```tsx
+import { RinggWidget, appOrigin } from "@ringg/react-native";
+import { Platform } from "react-native";
+
+const BUNDLE_ID = Platform.OS === "android" ? "com.acme.app" : "com.acme.App";
+
+export const App = () => (
+  <View style={{ flex: 1 }}>
+    <YourApp />
+    <RinggWidget
+      config={{
+        agentId: "<your-agent-id>",
+        authorization: "Bearer <your-token>",
+        clientOrigin: appOrigin(BUNDLE_ID),
+        title: "Support",
+        defaultTab: "text", // or "audio"
+      }}
+    />
+  </View>
+);
+```
+
+That is the whole integration. The widget renders its own floating trigger and
+panel over whatever is behind it, so make it the **last child** of your root
+view. Tap the trigger and the chat or voice panel opens.
+
+Endpoints, the media transport and the microphone port are the package's
+business, not yours. `config.mode` (`dev` / `stage` / `prod`, default `prod`)
+picks the environment.
+
+### Reading events, or driving the panel yourself
+
+`onReady` hands back the controller the widget built:
+
+```tsx
+<RinggWidget config={config} onReady={(controller) => {
+  controller.eventBus.on("ringg:conversation_status", ({ status, callId }) => {
+    analytics.track(`call_${status}`, { callId });
+  });
+}} />
+```
+
+### Owning the lifecycle yourself
+
+Pass `ports` to override anything the widget would wire by default — a mock
+transport in tests, your own `urlResolver`, a notification player, a handler for
+agent-triggered app actions:
+
+```tsx
+<RinggWidget config={config} ports={{ onDomAction: dispatcher }} />
+```
+
+Or build the controller yourself and pass it instead of `config`, when the
+widget cannot own the transport (a shared room, a custom adapter, several views
+on one controller):
+
+```tsx
+const livekit = createLiveKitTransport();
+const controller = createRinggWidgetController(config, {
+  transport: livekit.transport,
+  urlResolver: defaultUrlResolver,
+  micPermission: createNativeMicPermission(),
+});
+
+<RinggWidget controller={controller} room={livekit.room} />;
+// You built it, so you destroy it: controller.destroy(); livekit.dispose();
+```
+
+## Configuration
+
+`RinggWidgetConfig` — only `agentId` is required:
+
+| Field | Type | Purpose |
+|---|---|---|
+| `agentId` | `string` | your Ringg agent (**required**) |
+| `authorization` | `string` | bearer token for your account |
+| `title` / `description` | `string` | panel header text |
+| `defaultTab` | `"audio" \| "text"` | which mode the panel opens in |
+| `hideTabSelector` | `boolean` | pin the widget to one mode |
+| `defaultExpanded` | `boolean` | open the panel on mount (no trigger) |
+| `bypassStartScreen` | `boolean` | trigger tap starts the call directly |
+| `bypassFeedbackScreen` | `boolean` | skip the post-call rating screen |
+| `clientOrigin` | `string` | **required for real calls** — see below |
+| `variables` | `Record<string, …>` | values for `{{placeholders}}` in agent prompts |
+| `theme` | `WidgetTheme` | colours, radii, button style (gradients supported) |
+| `logoUrl` / `logoStyles` | `string` / `PortableStyles` | branding in the header |
+| `buttons` | `ButtonsConfig` | per-button copy, icons and styles |
+| `legalDisclaimer` | `{ text, links }` | copy under the start buttons |
+| `feedbackScreen` | `FeedbackScreenConfig` | rating screen copy and styling |
+| `voiceCall` | `{ showAnimation, showTranscript }` | voice view options |
+| `enabledSlashCommands` | `SlashCommand[]` | commands offered in the composer |
+| `eventLogs` | `{ enabled, showIds }` | inline pills for agent-triggered actions |
+
+`widgetPosition` and `innerWindowProps` are web-only and ignored here — the
+panel sizes itself to the device.
+
+## Caller identity — required for real calls
+
+The backend allow-lists an agent's callers by the `Origin` header. A browser
+sends it automatically; a native app sends nothing, so the webcall request is
+rejected **before authentication is even considered**:
+
+| response | meaning |
+|---|---|
+| `400 Origin header is required` | no `clientOrigin` was set |
+| `403 Client '…' is not allowed` | it was set, but is not on the agent's list |
+| `401 Invalid credentials` | the token is wrong for that environment |
+
+Pass your app's identity, and add the same string to the agent's allowed
+clients in the dashboard:
+
+```ts
+import { Platform } from "react-native";
+import { appOrigin, createRinggWidgetController } from "@ringg/react-native";
+
+const BUNDLE_ID = Platform.OS === "android" ? "com.acme.app" : "com.acme.App";
+
+createRinggWidgetController(
+  { agentId: "…", authorization: "Bearer …", clientOrigin: appOrigin(BUNDLE_ID) },
+  ports,
+);
+```
+
+`appOrigin` returns `<platform>://<bundleId>` — e.g. `android://com.acme.app`.
+The bundle id is a parameter because React Native cannot read it without a
+native module, and this package will not add one for a single string. Your app
+already declares it, so a constant (or a read of your own app config) is
+enough. `expo-application` reports the same value if you would rather ask the
+OS — but it is native code, so adding it requires rebuilding the app, not just
+restarting the bundler.
+
+## Host events
+
+The controller emits the same events as the web widget. On RN they are
+in-memory rather than DOM events:
+
+```ts
+const unsubscribe = controller.eventBus.on("ringg:conversation_status", ({ status, mode, callId }) => {
+  analytics.track(`call_${status}`, { mode, callId });
+});
+```
+
+Events: `ringg:widget_status`, `ringg:conversation_status`,
+`ringg:feedback_status`, `ringg:calendar_booking`,
+`ringg:component_acknowledgement`.
+
+## Agent-triggered app actions
+
+Agents can fire host actions (`execute_dom_action` on the wire). On web these
+become `CustomEvent`s; RN has no ambient event bus, so you supply the handler
+and receive the same payload:
+
+```ts
+import { createHostActionDispatcher } from "@ringg/react-native";
+
+const ports = {
+  // ...
+  onDomAction: createHostActionDispatcher(({ name, payload }) => {
+    if (name === "open_checkout") navigation.navigate("Checkout", payload);
+  }),
+};
+```
+
+## Notification sound
+
+React Native has no audio playback of its own, and every option is a native
+module — so the widget ships **silent** rather than forcing a dependency on
+every integrator. Wire whichever player your app already has:
+
+```ts
+import { createAudioPlayer } from "expo-audio";
+import { createNotificationPlayer, DEFAULT_CONFIG } from "@ringg/react-native";
+
+const notification = createNotificationPlayer(DEFAULT_CONFIG.notificationTuneUrl, (url) => createAudioPlayer(url).play());
+```
+
+Pass it as `ports.notification`.
+
+## Testing hooks
+
+Every meaningful node carries a `testID` mirroring the web widget's
+`data-ringg` name, prefixed with `ringg-` — `ringg-trigger-button`,
+`ringg-widget-root`, `ringg-header-title`, `ringg-message-input`,
+`ringg-end-call-confirm`, and so on. These are a contract: they will not be
+renamed without a major version.
+
+Two web names have no RN counterpart, because they mark screen-reader-only
+nodes and RN has no visually-hidden text: `ringg-header-status` and
+`ringg-connecting-label`'s `sr-only` sibling. That copy lives in
+`accessibilityLabel` on the surrounding node instead.
+
+## Example app
+
+A runnable Expo harness lives in [`example/`](./example) — it is the reference
+integration and runs fully offline (mock transport + in-process backend) when
+no credentials are configured.
+
+## Known issues
+
+- **Breaking changes between releases.** APIs may shift while pre-1.0.
+- **No frosted-glass blur.** The web widget's header and composer blur what
+  scrolls under them; RN has no blur primitive without a native dependency, so
+  those surfaces are near-opaque instead.
+- **No gradient-filled text.** The typing indicator's shimmer sweeps a gradient
+  through the glyphs on web. RN cannot fill text with a gradient without a
+  masking dependency, so the label takes the colour that sweep averages to and
+  the motion moves into the animated ellipsis beside it.
+- **Markdown is a subset.** Agent replies render bold, italic, inline code,
+  links, lists, headings, code blocks, blockquotes and rules. Tables are not
+  supported and render as plain text.
+- **Voice on emulators is unreliable.** Android emulator networking often
+  cannot establish the media connection, and iOS simulators expose no
+  microphone or playout device. Test voice on a real device.
+- **The policy-finder pack is web-only.** That integrator-specific flow is not
+  part of this package.

package/app.plugin.js

@@ -0,0 +1,73 @@
+/**
+ * Expo config plugin — the whole native setup, in one entry.
+ *
+ * Voice calls need a microphone, background audio and the LiveKit native
+ * module's own manifest metadata. Making integrators assemble that themselves
+ * meant three separate things in their `app.json`: our transport's plugin, a
+ * list of Android permissions, and two `Info.plist` keys. Those are our
+ * requirements, so they are our job:
+ *
+ *   { "expo": { "plugins": ["@ringg/react-native"] } }
+ *
+ * Bare React Native apps have no config plugins and still edit `Info.plist`
+ * and `AndroidManifest.xml` by hand; the values are in the README.
+ *
+ * Plain JS on purpose: Expo resolves `app.plugin.js` from the package root
+ * before any bundler runs, so it cannot be part of the tsup build.
+ */
+
+const { AndroidConfig, withInfoPlist, withPlugins } = require("@expo/config-plugins");
+
+// The subpath, not the package: `main` is deliberately empty there, and the
+// plugin lives at the `app.plugin.js` entry Expo looks for by convention.
+// Requiring it from here (rather than passing the package name for Expo to
+// resolve) keeps it working under pnpm and Yarn PnP, where a dependency of a
+// dependency is not resolvable from the app root.
+const liveKitPlugin = require("@livekit/react-native-expo-plugin/app.plugin");
+const withLiveKit = liveKitPlugin.default ?? liveKitPlugin;
+
+/**
+ * Bluetooth is listed without `maxSdkVersion` filtering: Expo's permission
+ * helper writes plain `uses-permission` entries, and the legacy-only variants
+ * (`BLUETOOTH`, `BLUETOOTH_ADMIN`) are harmless on modern Android. Apps that
+ * care can strip them with their own `withAndroidManifest` plugin.
+ */
+const ANDROID_PERMISSIONS = [
+  "android.permission.INTERNET",
+  "android.permission.RECORD_AUDIO",
+  "android.permission.MODIFY_AUDIO_SETTINGS",
+  "android.permission.ACCESS_NETWORK_STATE",
+  "android.permission.BLUETOOTH_CONNECT",
+];
+
+const DEFAULT_MICROPHONE_TEXT = "Voice calls with the assistant use the microphone.";
+
+/** iOS: the permission prompt copy, and the background mode a live call needs. */
+const withRinggIos = (config, props) =>
+  withInfoPlist(config, (iosConfig) => {
+    // An app that already declares its own copy keeps it: the prompt is user
+    // facing, and ours is a fallback rather than a correction.
+    iosConfig.modResults.NSMicrophoneUsageDescription = props.microphonePermissionText ?? iosConfig.modResults.NSMicrophoneUsageDescription ?? DEFAULT_MICROPHONE_TEXT;
+
+    const backgroundModes = new Set(iosConfig.modResults.UIBackgroundModes ?? []);
+    backgroundModes.add("audio");
+    iosConfig.modResults.UIBackgroundModes = Array.from(backgroundModes);
+
+    return iosConfig;
+  });
+
+/**
+ * @param {object} config Expo config
+ * @param {{ microphonePermissionText?: string }} [props]
+ */
+const withRingg = (config, props = {}) =>
+  withPlugins(config, [
+    // `communication` routes audio to the earpiece/Bluetooth like a phone call
+    // rather than the media stream. A call played through the media channel is
+    // the wrong volume slider and the wrong speaker.
+    [withLiveKit, { android: { audioType: "communication" } }],
+    [AndroidConfig.Permissions.withPermissions, ANDROID_PERMISSIONS],
+    [withRinggIos, props],
+  ]);
+
+module.exports = withRingg;