@ringg/react-native 0.0.1-alpha.9 → 0.3.0

package/README.md

@@ -1,250 +1,290 @@
 # @ringg/react-native
 
-Add AI voice and text agents to your React Native app with [Ringg AI](https://ringg.ai).
+> ⚠️ **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.
 
-## Setup
+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.
 
-### 1. Install
+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
 ```
 
-### 2. Add the Expo plugin
-
-In your `app.json`:
-
-```json
-{
-  "expo": {
-    "plugins": ["@ringg/react-native"]
-  }
-}
-```
-
-### 3. Rebuild
-
-Voice calls require native modules, so you need a **development build** (Expo Go is not supported).
+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 prebuild --clean
-npx expo run:ios
-# or
-npx expo run:android
+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
 ```
 
-## Drop-in widget
-
-Add a complete voice/text chat widget with one component. It renders a floating action button that opens an animated chat panel.
-
-```tsx
-import { RinggWidget } from "@ringg/react-native";
-
-export default function App() {
-  return (
-    <RinggWidget
-      config={{
-        agentId: "your-agent-id",
-        xApiKey: "your-api-key",
-        variables: {
-          callee_name: "Jane Doe",
-        },
-      }}
-    />
-  );
-}
-```
+Requires React ≥ 18 · React Native ≥ 0.73.
 
-### Widget props
+**Expo Go will not work** — LiveKit ships native code, so you need a
+[development build](https://docs.expo.dev/develop/development-builds/introduction/).
 
-| Prop          | Type                       | Description                                                 |
-| ------------- | -------------------------- | ----------------------------------------------------------- |
-| `config`      | `RinggWidgetConfig`        | Agent ID, API key, variables, and customization (see below) |
-| `onEvent`     | `(event, payload) => void` | Callback for widget lifecycle events                        |
-| `triggerSize` | `number`                   | FAB button size in pixels (default: `56`)                   |
+## Platform setup (required for voice)
 
-### Config options
+**Expo** — add the LiveKit plugin and the permissions to `app.json`:
 
-```ts
+```json
 {
-  agentId: string;                        // Required — your agent ID
-  xApiKey: string;                        // Required — your API key
-  variables: Record<string, string>;      // Custom variables sent to the agent
-  mode?: "prod" | "stage";               // Environment (default: "prod")
-  title?: string;                         // Header title
-  description?: string;                   // Header description
-  defaultTab?: "audio" | "text";          // Starting mode (default: "audio")
-  hideTabSelector?: boolean;              // Hide the audio/text toggle
-  logoUrl?: string;                       // Custom logo URL
-  theme?: {                               // Theme overrides
-    primaryColor?: string;
-    backgroundColor?: string;
-    primaryTextColor?: string;
-    secondaryTextColor?: string;
-    buttonStyle?: "rounded" | "pill" | "square";
-  };
+  "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"
+      ]
+    }
+  }
 }
 ```
 
-### Events
-
-Listen to widget lifecycle events via `onEvent`:
+**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`.
 
-```tsx
-<RinggWidget
-  config={config}
-  onEvent={(event, payload) => {
-    switch (event) {
-      case "ringg:conversation_status":
-        // { status: "started" | "ended", mode: "audio" | "text", callId: string }
-        break;
-      case "ringg:widget_status":
-        // { status: "maximised" | "minimised", mode: "audio" | "text" }
-        break;
-      case "ringg:feedback_status":
-        // { status: "submitted" | "skipped", callId: string, rating?: number }
-        break;
-    }
-  }}
-/>
-```
+## Integrate in 3 steps
 
-## Headless hooks
+### 1 · Register the WebRTC globals
 
-Build a completely custom UI. Wrap your screen with `RinggProvider`, then use hooks to control calls, chat, and more.
+Once, at your app entry, **before** anything imports LiveKit:
 
-```tsx
-import { RinggProvider, useRinggCall, useRinggChat } from "@ringg/react-native";
-
-function App() {
-  return (
-    <RinggProvider
-      config={{
-        agentId: "your-agent-id",
-        xApiKey: "your-api-key",
-        variables: {},
-      }}
-    >
-      <ChatScreen />
-    </RinggProvider>
-  );
-}
+```ts
+// index.js
+import { registerGlobals } from "@livekit/react-native";
+registerGlobals();
+```
 
-function ChatScreen() {
-  const call = useRinggCall();
-  const chat = useRinggChat();
+### 2 · Build a transport and a controller
 
-  if (!call.isConnected) {
-    return (
-      <View>
-        <Button title="Start voice call" onPress={() => call.startCall("audio")} disabled={call.isLoading} />
-        <Button title="Start text chat" onPress={() => call.startCall("text")} disabled={call.isLoading} />
-      </View>
+```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 (
-    <View style={{ flex: 1 }}>
-      <FlatList data={chat.messages} keyExtractor={(item) => String(item.timestamp)} renderItem={({ item }) => <Text style={{ alignSelf: item.isSelf ? "flex-end" : "flex-start" }}>{item.message}</Text>} />
-
-      {call.callMode === "audio" && <Button title={call.isMicEnabled ? "Mute" : "Unmute"} onPress={call.toggleMic} />}
+    return { controller, livekit };
+  }, []);
 
-      {call.callMode === "text" && (
-        <TextInput
-          placeholder="Type a message..."
-          onSubmitEditing={(e) => {
-            chat.sendMessage(e.nativeEvent.text);
-          }}
-        />
-      )}
+  // Releases the microphone and the audio session — do not skip this.
+  useEffect(() => () => {
+    controller.destroy();
+    livekit.dispose();
+  }, [controller, livekit]);
 
-      <Button title="End call" onPress={call.endCall} />
-    </View>
-  );
-}
+  return <RinggWidget controller={controller} room={livekit.room} />;
+};
 ```
 
-### useRinggCall()
-
-Controls call lifecycle and microphone.
-
-| Property          | Type                                              | Description                             |
-| ----------------- | ------------------------------------------------- | --------------------------------------- |
-| `startCall(mode)` | `(mediaType: "audio" \| "text") => Promise<void>` | Start a voice or text session           |
-| `endCall()`       | `() => Promise<void>`                             | End the current session                 |
-| `isConnected`     | `boolean`                                         | Whether the agent is connected          |
-| `isLoading`       | `boolean`                                         | Loading state during connect/disconnect |
-| `connectionState` | `"connected" \| "disconnected" \| "reconnecting"` | Detailed connection state               |
-| `callMode`        | `"audio" \| "text"`                               | Current session mode                    |
-| `callId`          | `string \| null`                                  | Current call ID                         |
-| `isMicEnabled`    | `boolean`                                         | Microphone state                        |
-| `toggleMic()`     | `() => Promise<void>`                             | Toggle microphone on/off                |
-| `error`           | `string \| null`                                  | Error message if connection failed      |
-| `clearError()`    | `() => void`                                      | Clear the error state                   |
-
-### useRinggChat()
-
-Send and receive text messages.
-
-| Property            | Type                              | Description                         |
-| ------------------- | --------------------------------- | ----------------------------------- |
-| `messages`          | `ChatMessage[]`                   | All messages in chronological order |
-| `sendMessage(text)` | `(text: string) => Promise<void>` | Send a message to the agent         |
-| `clearMessages()`   | `() => void`                      | Clear message history               |
+Passing `room` is optional; it only enables the in-call audio visualizer.
 
-Each `ChatMessage` has: `{ message: string, isSelf: boolean, name: string, timestamp: number }`.
+### 3 · Mount it over your app
 
-### useRinggTranscripts()
+`RinggWidget` renders its own floating trigger and panel over whatever is
+behind it, so make it the **last child** of your root view:
 
-Real-time speech-to-text during voice calls.
+```tsx
+<View style={{ flex: 1 }}>
+  <YourApp />
+  <RinggSupport />
+</View>
+```
 
-| Property      | Type                | Description                 |
-| ------------- | ------------------- | --------------------------- |
-| `transcripts` | `TranscriptEntry[]` | Live transcription segments |
+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:
 
-### useRinggFeedback()
+```ts
+import { Platform } from "react-native";
+import { appOrigin, createRinggWidgetController } from "@ringg/react-native";
 
-Post-call feedback collection.
+const BUNDLE_ID = Platform.OS === "android" ? "com.acme.app" : "com.acme.App";
 
-| Property                          | Type                                                 | Description            |
-| --------------------------------- | ---------------------------------------------------- | ---------------------- |
-| `submitFeedback(rating, comment)` | `(rating: number, comment: string) => Promise<void>` | Submit feedback        |
-| `skipFeedback()`                  | `() => void`                                         | Skip feedback          |
-| `isSubmitting`                    | `boolean`                                            | Submission in progress |
+createRinggWidgetController(
+  { agentId: "…", authorization: "Bearer …", clientOrigin: appOrigin(BUNDLE_ID) },
+  ports,
+);
+```
 
-### useRinggTheme()
+`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.
 
-Access the resolved theme for custom styling.
+## Host events
 
-| Property               | Type                          | Description                                |
-| ---------------------- | ----------------------------- | ------------------------------------------ |
-| `theme`                | `ResolvedWidgetTheme`         | Full theme with defaults applied           |
-| `getSolidColor(color)` | `(color: string) => string`   | Extract solid color from gradient          |
-| `buttonRadius`         | `string`                      | Border radius for the current button style |
-| `getContrastText(bg)`  | `(bgColor: string) => string` | Get black or white text for a background   |
+The controller emits the same events as the web widget. On RN they are
+in-memory rather than DOM events:
 
-## UI building blocks
+```ts
+const unsubscribe = controller.eventBus.on("ringg:conversation_status", ({ status, mode, callId }) => {
+  analytics.track(`call_${status}`, { mode, callId });
+});
+```
 
-When using headless hooks, you can still use our pre-built UI components individually:
+Events: `ringg:widget_status`, `ringg:conversation_status`,
+`ringg:feedback_status`, `ringg:calendar_booking`,
+`ringg:component_acknowledgement`.
 
-```tsx
-import { MessageBubble, WidgetHeader, CallControls, ActionButton, FeedbackScreen, TabSelector } from "@ringg/react-native";
-```
+## Agent-triggered app actions
 
-## Expo plugin options
+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:
 
-```json
-["@ringg/react-native", { "enableCamera": true }]
+```ts
+import { createHostActionDispatcher } from "@ringg/react-native";
+
+const ports = {
+  // ...
+  onDomAction: createHostActionDispatcher(({ name, payload }) => {
+    if (name === "open_checkout") navigation.navigate("Checkout", payload);
+  }),
+};
 ```
 
-| Option         | Type      | Default | Description                                          |
-| -------------- | --------- | ------- | ---------------------------------------------------- |
-| `enableCamera` | `boolean` | `false` | Request camera permission (for future video support) |
+## Notification sound
 
-## Bare React Native
+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:
 
-If you're not using Expo, see the [bare React Native setup guide](https://ringg.ai/docs/react-native/bare) for manual native configuration.
+```ts
+import { createAudioPlayer } from "expo-audio";
+import { createNotificationPlayer } from "@ringg/react-native";
+import { DEFAULT_CONFIG } from "@ringg/core";
 
-## License
+const notification = createNotificationPlayer(DEFAULT_CONFIG.notificationTuneUrl, (url) => createAudioPlayer(url).play());
+```
 
-[MIT](./LICENSE)
+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.