@ringg/react-native 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,290 @@
+# @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 peer dependencies, which must be installed in **your** app so there is
+exactly one autolinked copy of each native module:
+
+```bash
+npx expo install @livekit/react-native @livekit/react-native-webrtc livekit-client react-native-svg
+# or, without Expo:
+npm install @livekit/react-native @livekit/react-native-webrtc livekit-client 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)
+
+**Expo** — add the LiveKit plugin and the permissions to `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": ["@livekit/react-native-expo-plugin"],
+    "ios": {
+      "infoPlist": {
+        "NSMicrophoneUsageDescription": "Voice calls use the microphone.",
+        "UIBackgroundModes": ["audio"]
+      }
+    },
+    "android": {
+      "permissions": [
+        "android.permission.RECORD_AUDIO",
+        "android.permission.MODIFY_AUDIO_SETTINGS",
+        "android.permission.ACCESS_NETWORK_STATE",
+        "android.permission.BLUETOOTH_CONNECT"
+      ]
+    }
+  }
+}
+```
+
+**Bare React Native** — the same keys, by hand: `NSMicrophoneUsageDescription`
+and `UIBackgroundModes: [audio]` in `ios/<App>/Info.plist`, and the four
+permissions above in `android/app/src/main/AndroidManifest.xml`.
+
+## Integrate in 3 steps
+
+### 1 · Register the WebRTC globals
+
+Once, at your app entry, **before** anything imports LiveKit:
+
+```ts
+// index.js
+import { registerGlobals } from "@livekit/react-native";
+registerGlobals();
+```
+
+### 2 · Build a transport and a controller
+
+```tsx
+import { useEffect, useMemo } from "react";
+import {
+  RinggWidget,
+  createLiveKitTransport,
+  createNativeMicPermission,
+  createRinggWidgetController,
+} from "@ringg/react-native";
+import { createStaticUrlResolver } from "@ringg/core";
+
+const URLS = {
+  dev: { backendUrl: "https://calling-dev.ringg.ai/ca/api/v0", livekitUrl: "wss://ringg-ai-dev-92tubwpz.livekit.cloud" },
+  stage: { backendUrl: "https://stage-api.ringg.ai/ca/api/v0", livekitUrl: "wss://mercury.webrtc-stage.ringg.ai" },
+  prod: { backendUrl: "https://prod-api.ringg.ai/ca/api/v0", livekitUrl: "wss://mercury.webrtc.ringg.ai" },
+};
+
+export const RinggSupport = () => {
+  const { controller, livekit } = useMemo(() => {
+    const livekit = createLiveKitTransport();
+    const controller = createRinggWidgetController(
+      {
+        agentId: "<your-agent-id>",
+        authorization: "Bearer <your-token>",
+        title: "Support",
+        description: "How can we help?",
+        defaultTab: "text", // or "audio"
+      },
+      {
+        transport: livekit.transport,
+        urlResolver: createStaticUrlResolver(URLS),
+        micPermission: createNativeMicPermission(),
+      },
+    );
+    return { controller, livekit };
+  }, []);
+
+  // Releases the microphone and the audio session — do not skip this.
+  useEffect(() => () => {
+    controller.destroy();
+    livekit.dispose();
+  }, [controller, livekit]);
+
+  return <RinggWidget controller={controller} room={livekit.room} />;
+};
+```
+
+Passing `room` is optional; it only enables the in-call audio visualizer.
+
+### 3 · Mount it over your app
+
+`RinggWidget` renders its own floating trigger and panel over whatever is
+behind it, so make it the **last child** of your root view:
+
+```tsx
+<View style={{ flex: 1 }}>
+  <YourApp />
+  <RinggSupport />
+</View>
+```
+
+Tap the trigger → the chat/voice panel opens. That is the whole integration.
+
+## 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 } from "@ringg/react-native";
+import { DEFAULT_CONFIG } from "@ringg/core";
+
+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.