@ringg/react-native 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import { FC, ReactNode } from 'react';
+import { Room, RoomOptions } from 'livekit-client';
+import { StyleProp, ViewStyle } from 'react-native';
+
 /**
  * Theme types for the widget.
  * Covers both widget-level theming and per-component theming.
@@ -177,6 +181,16 @@ interface RinggWidgetConfig {
     xApiKey?: string;
     /** JWT for authentication (Authorization header) — wins over xApiKey when both are set */
     authorization?: string;
+    /**
+     * `Origin` to present to the backend, which allow-lists an agent's callers
+     * by that value. Browsers send it themselves, so web leaves this unset and
+     * MUST NOT set it — `Origin` is a forbidden header there. Native callers
+     * send nothing on their own and have to supply their own identity, by
+     * convention `<platform>://<bundleId>` (see @ringg/react-native's
+     * `appOrigin`). Whatever string is given is sent verbatim; only the backend
+     * decides whether it is allowed.
+     */
+    clientOrigin?: string;
     /** Custom variables passed to the agent (e.g., user name, role) */
     variables?: WidgetVariables;
     /** Environment mode — selects which UrlResolver entry to use */
@@ -961,4 +975,381 @@ declare const useRinggShell: (controller: RinggWidgetController) => ShellSnapsho
 declare const useRinggComponents: (controller: RinggWidgetController) => ComponentSnapshot;
 declare const useRinggSlashCommands: (controller: RinggWidgetController) => SlashCommandSnapshot;
 
-export { type ControllerPorts, type RinggWidgetConfig, type RinggWidgetController, type TransportAdapter, createCallbackEventBus, createRinggWidgetController, useRinggComponents, useRinggMessages, useRinggSession, useRinggShell, useRinggSlashCommands, useRinggTyping, useStoreSnapshot };
+/**
+ * RinggWidget — the assembled React Native widget.
+ *
+ * The native counterpart of the web assembly: the same tree, the same order,
+ * the same branches. It holds NO conversation state — every snapshot comes
+ * from `@ringg/core` via the shared hooks and every intent is forwarded to the
+ * controller. If a behaviour looks like it belongs here, it belongs in core.
+ *
+ * Three things genuinely differ from web, all forced by the platform:
+ *
+ *  1. There is no `position: fixed`. The widget is an absolutely-filled
+ *     overlay with `pointerEvents="box-none"`, so taps pass through everywhere
+ *     except the trigger and the panel. Mount it as the LAST child of the app
+ *     root; `widgetPosition` (a web-only config) is ignored and the panel
+ *     sizes itself to the device.
+ *  2. The keyboard covers the bottom of the screen. The panel lives inside a
+ *     `KeyboardAvoidingView` so the composer stays visible while typing —
+ *     without it the input is simply unreachable in text mode.
+ *  3. The transcript cannot measure a child's offset the way web does to
+ *     anchor the newest turn's first line. It pins to the bottom instead, and
+ *     the "new message" / "typing toggled" distinction is preserved so a long
+ *     reply arriving does not yank the view while the user is reading.
+ */
+
+interface RinggWidgetProps {
+    controller: RinggWidgetController;
+    /**
+     * The LiveKit room from `createLiveKitTransport()`. Optional: it only powers
+     * the in-call audio visualizer and the mute button. Without it the widget is
+     * fully functional and the visualizer shows its ambient idle animation.
+     */
+    room?: Room;
+}
+declare const RinggWidget: FC<RinggWidgetProps>;
+
+/**
+ * LiveKit React Native transport — the real `TransportAdapter` over
+ * `@livekit/react-native`, behavior-matched to the web adapter (which is
+ * itself matched to production, @desivocal/agents-cdn).
+ *
+ * The wire behavior is deliberately identical to `web/src/transport/
+ * livekit-transport.ts` — same Room options, same double-send chat, same
+ * agent-classification and session-ended rules — because both talk to the same
+ * backend and core drives them through the same port. Read that file's parity
+ * notes; they apply here verbatim.
+ *
+ * Only what the platform forces differs:
+ *  - remote audio needs no elements. Mobile plays subscribed audio through the
+ *    OS, so `<RoomAudioRenderer />`'s job becomes owning an audio SESSION
+ *    (see platform/audio-session.ts) rather than attaching media elements;
+ *  - `registerGlobals()` must run before a Room is constructed — the adapter
+ *    does it so a missing app-entry call is not a mysterious runtime failure;
+ *  - autoplay policy has no mobile equivalent, so the web adapter's
+ *    `startAudio()` recovery has no counterpart.
+ */
+
+interface LiveKitTransportOptions {
+    /**
+     * Extra LiveKit `RoomOptions` merged over the parity defaults
+     * (`dynacast: true, adaptiveStream: true`). Rarely needed.
+     */
+    roomOptions?: RoomOptions;
+    /**
+     * Own the native audio session for the duration of a call — the mobile
+     * equivalent of production's `<RoomAudioRenderer />`. Default true; disable
+     * when the host app already manages an audio session (an in-app player, a
+     * CallKit/ConnectionService integration).
+     */
+    manageAudioSession?: boolean;
+    /**
+     * Call `registerGlobals()` before constructing the Room. Default true.
+     * Set false when the app already calls it at its entry point — it is
+     * idempotent, so this is a formality rather than a correctness switch.
+     */
+    registerGlobals?: boolean;
+}
+interface LiveKitTransport {
+    transport: TransportAdapter;
+    /**
+     * The underlying Room, for presentational concerns the port cannot express
+     * (visualizer track handles, `isMicrophoneEnabled` readback — spec §11).
+     * State-changing calls must keep going through the transport/core.
+     */
+    room: Room;
+    /** Tears down listeners, handlers and the audio session; disconnects the room. */
+    dispose(): void;
+}
+declare const createLiveKitTransport: (options?: LiveKitTransportOptions) => LiveKitTransport;
+
+/**
+ * Native audio session — React Native's replacement for the web adapter's
+ * hidden `<audio>` elements.
+ *
+ * On web, remote audio needs a DOM element to play into. On mobile it needs
+ * the opposite: nothing to attach, but an OS-level audio session that has to
+ * be configured and activated before the call and released after it, or the
+ * mic indicator stays lit and the app keeps ducking other audio.
+ *
+ * The configuration encodes the mobile audio invariants (AGENTS.md rule 10):
+ * communication mode so the call survives backgrounding and routes through the
+ * earpiece/bluetooth stack rather than the media stream, and a preferred
+ * output list that follows a headset or bluetooth device when one appears.
+ *
+ * Every call is best-effort. A device that refuses to hand over the audio
+ * session must not take the call down with it — the user still gets a
+ * (possibly routed-oddly) conversation, which beats a hard failure.
+ */
+interface AudioSessionPort {
+    /** Configure + activate. Safe to call repeatedly; only the first wins. */
+    start(): Promise<void>;
+    /** Release the session. Safe to call when never started. */
+    stop(): Promise<void>;
+}
+declare const createAudioSession: () => AudioSessionPort;
+
+/**
+ * React Native `MicPermissionPort`.
+ *
+ * Core's session store drives this on audio start: `isGranted()` first, then
+ * `request()`, aborting the call on denial — identical to web. What differs is
+ * how the answer is obtained, and the two platforms genuinely differ:
+ *
+ *  - Android exposes a real permission API, so the state can be READ without
+ *    prompting. That matters: `isGranted()` must never show a dialog, or the
+ *    user gets prompted before they have pressed anything.
+ *  - iOS has no readable pre-check from JS. The only probe is `getUserMedia`,
+ *    which prompts on first use — the same fallback the web port uses for
+ *    browsers without the Permissions API. Once answered, iOS resolves the
+ *    probe from its own record without prompting again.
+ *
+ * The probe must never keep the microphone: every track it opens is stopped
+ * before returning, or the OS recording indicator stays lit before the call
+ * has even started.
+ */
+
+declare const createNativeMicPermission: () => MicPermissionPort;
+
+/**
+ * App identity for the backend's caller allow-list.
+ *
+ * The Ringg backend allow-lists an agent's callers by `Origin`. A browser
+ * attaches it automatically; a native app sends nothing, so it has to present
+ * its own identity — by convention `<platform>://<bundleId>`, the scheme the
+ * backend accepts for app clients. Without it the webcall request is rejected
+ * before authentication even matters (`400 Origin header is required`).
+ *
+ * The bundle id is the INTEGRATOR's, not ours, so the value allow-listed in
+ * the dashboard is their app. React Native cannot read it without a native
+ * module, and this package refuses to grow one for a single string — so the id
+ * is a parameter. Expo apps have it in `expo-application`'s `applicationId`;
+ * bare apps already know their own.
+ *
+ * Mirrors `flutter/lib/src/platform/app_origin.dart`, which derives the same
+ * string from `package_info_plus`.
+ */
+/**
+ * `<platform>://<bundleId>` for the running app — e.g. `android://com.acme.app`.
+ *
+ * Returns undefined on a platform the backend has no scheme for, which
+ * includes react-native-web: there the browser sends a real `Origin` and
+ * setting one from JavaScript is forbidden anyway.
+ */
+declare const appOrigin: (bundleId: string) => string | undefined;
+
+/**
+ * React Native `NotificationPlayer`.
+ *
+ * Core decides WHEN to play (an agent reply or component landing while the
+ * widget is closed); the port only owns the how. On web that is one line —
+ * `new Audio(url)`. RN has no audio playback in the platform at all: every
+ * option (expo-audio, react-native-sound, react-native-video) is a native
+ * module, and forcing one on integrators would mean an extra pod/gradle
+ * dependency and an Expo config plugin for a notification chime.
+ *
+ * So the decision is inverted: the widget ships silent by default and the
+ * integrator opts in with three lines against whichever player their app
+ * already has. `notificationTuneUrl` from the config is handed to that player,
+ * so the URL stays a config concern on every platform.
+ */
+
+/** What an integrator's audio library has to be able to do. */
+type PlayTune = (tuneUrl: string) => void;
+/**
+ * The default. Silent, and deliberately so — a widget that cannot find an
+ * audio library should be quiet, not noisy about it on every reply.
+ */
+declare const createSilentNotificationPlayer: () => NotificationPlayer;
+/**
+ * Bridges the config's tune URL to a host-provided player.
+ *
+ * ```ts
+ * import { createAudioPlayer } from "expo-audio";
+ * const notifications = createNotificationPlayer(DEFAULT_CONFIG.notificationTuneUrl, (url) => createAudioPlayer(url).play());
+ * ```
+ *
+ * Playback failures are swallowed: a chime is best-effort by contract, and a
+ * rejected promise here must never surface mid-conversation.
+ */
+declare const createNotificationPlayer: (tuneUrl: string, playTune: PlayTune) => NotificationPlayer;
+
+/**
+ * Host action dispatcher — the React Native counterpart of the web widget's
+ * `executeDomAction`.
+ *
+ * Core normalises the `execute_dom_action` RPC into a `DomAction` and hands it
+ * to the `onDomAction` port. On web that ends in `window.dispatchEvent`, which
+ * works because the host page is already an event bus. RN has no such ambient
+ * bus, so the integrator supplies the handler and gets the event name plus the
+ * payload the agent sent — the same `{...default_payload, action_id}` detail
+ * the web CustomEvent carries, so a shared backend config drives both.
+ *
+ * Validation, logging and the "unknown kind" path stay identical to web: those
+ * are contract behaviour, not platform detail.
+ */
+
+/** What the host receives — the web CustomEvent, minus the DOM. */
+interface HostAction {
+    /** The agent-configured event name (`CustomEvent.type` on web). */
+    name: string;
+    /** `default_payload` with the action id folded in (`CustomEvent.detail`). */
+    payload: Record<string, unknown>;
+}
+type HostActionHandler = (action: HostAction) => void;
+/**
+ * Builds the `onDomAction` port. `onAction` runs in the caller's context and
+ * is allowed to throw — a broken host handler is reported, never fatal.
+ */
+declare const createHostActionDispatcher: (onAction: HostActionHandler) => (action: DomAction | undefined | null, onLog?: DomActionLogger) => void;
+
+/**
+ * Widget theme for React Native.
+ *
+ * Deliberately thin: the theme VALUES (defaults, presets) and the merge/
+ * contrast LOGIC both come from `@ringg/core` — `mergeWidgetTheme` here is
+ * core's function, not a copy. The web package still carries its own copy of
+ * that table for byte-fidelity with agents-cdn; RN has no such legacy to match
+ * and takes the shared one, so a token change reaches this platform through
+ * codegen (AGENTS.md rule 2).
+ *
+ * What IS local is unit translation. The theme surface is CSS-shaped
+ * (`"16px"`, `"9999px"`, `fontFamily: "inherit"`) because that's the contract
+ * integrators already write against on web; RN needs numbers and a real family
+ * name, so the `resolve*` helpers below are the single conversion point.
+ */
+
+interface WidgetThemeProviderProps {
+    theme?: WidgetTheme;
+    children: ReactNode;
+}
+/** `"16px"` → `16`. Unparseable values fall back rather than laying out as NaN. */
+declare const resolveRadius: (value: string | undefined, fallback?: number) => number;
+/** Button corner radius as an RN number, from core's shared style → CSS mapping. */
+declare const resolveButtonRadius: (style: ButtonStyle | undefined) => number;
+/**
+ * `"inherit"` has no meaning in RN — there is no cascade. Returning undefined
+ * lets `<Text>` fall through to the platform system font, which is what
+ * "inherit" resolves to on web for an unstyled host page.
+ */
+declare const resolveFontFamily: (fontFamily: string | undefined) => string | undefined;
+declare const WidgetThemeProvider: FC<WidgetThemeProviderProps>;
+declare const useWidgetTheme: () => ResolvedWidgetTheme;
+
+/**
+ * Gradient fills for React Native.
+ *
+ * The theme surface is CSS-shaped — `primaryColor` may be a solid hex OR a
+ * `linear-gradient(...)` string (see core `types/theme.ts`, and the gradient
+ * presets in `widget-theme`). The DOM renders those for free; RN has no
+ * gradient primitive at all, so every themed surface goes through here.
+ *
+ * Colour PARSING is not duplicated — `isGradient` / `extractColorsFromGradient`
+ * / `getDominantColor` come from `@ringg/core`, the same functions the web
+ * widget uses (AGENTS.md rule 2: shared values come from core, never a local
+ * re-implementation). Only the two things core cannot know about — the angle in
+ * SVG coordinates, and how to paint it — live in this file.
+ *
+ * Non-linear gradients (radial/conic) degrade to their dominant colour rather
+ * than approximating badly; the theme presets are all linear.
+ */
+
+interface GradientFillProps {
+    /** A theme colour: solid (`#0a0a0b`, `rgb(...)`) or a CSS gradient string. */
+    color: string;
+    /** Applied to the wrapper — size, padding, radius, alignment. */
+    style?: StyleProp<ViewStyle>;
+    children?: ReactNode;
+}
+/**
+ * Paints `color` behind `children`. Solid colours take the cheap path
+ * (`backgroundColor`); gradients get an absolutely-filled SVG layer that
+ * inherits the wrapper's rounding through `overflow: hidden`.
+ */
+declare const GradientFill: FC<GradientFillProps>;
+/**
+ * A guaranteed-solid colour, for the properties RN can only paint flat —
+ * borders, shadows, icon tints, status dots.
+ */
+declare const solidColor: (color: string) => string;
+
+/**
+ * `PortableStyles` → React Native styles.
+ *
+ * `PortableStyles` (core `types/config.ts`) is the deliberately small subset of
+ * CSS the config surface accepts precisely so it can cross platforms. Web hands
+ * the values straight to the DOM; RN cannot — it has no CSS parser, so a
+ * `"16px"` string silently breaks layout instead of throwing.
+ *
+ * This is the one place that converts. Rules, matching the Dart port
+ * (`flutter/lib/src/ui/widgets/portable_styles.dart`):
+ *  - numbers pass through as density-independent pixels;
+ *  - `"16px"` / `"16"` → `16`;
+ *  - `"50%"` survives only where RN accepts percentages (width/height);
+ *  - anything else (`calc()`, `em`, `auto`, gradients in `backgroundColor`) is
+ *    dropped rather than guessed at — a dropped style degrades, a wrong one
+ *    corrupts the layout.
+ */
+
+/** Convert a config `PortableStyles` bag into an RN `ViewStyle`. */
+declare const toViewStyle: (styles: PortableStyles | undefined) => ViewStyle;
+/** Icon sizing from `ButtonIconConfig.size` (same parsing, single value). */
+declare const toSize: (value: string | number | undefined, fallback: number) => number;
+
+/**
+ * Markdown for chat bubbles.
+ *
+ * The web widget hands agent replies to `react-markdown` + `remark-gfm` and
+ * lets Tailwind's prose plugin style the result. Neither of those crosses to
+ * RN, and this package takes no dependency for it, so what lives here is a
+ * renderer for the subset that actually appears in agent replies. Everything
+ * else falls through as the literal text the model wrote — a reply must never
+ * show half-parsed markup.
+ *
+ * Supported: paragraphs, `**bold**`, `*italic*`, inline code, `[links](url)`
+ * (handed to `Linking`), bullet and ordered lists, `#` through `######`
+ * headings, fenced code blocks, blockquotes (which may contain further
+ * blocks), horizontal rules, and backslash escapes.
+ *
+ * Not supported, deliberately: TABLES — GFM's headline feature, but a
+ * phone-width bubble has nowhere to put one, so a table degrades to a
+ * paragraph of its pipe-separated source. Also absent: images (rendered as
+ * their alt text), strikethrough, task lists, footnotes, reference links, raw
+ * HTML, and nested list indentation (nested items flatten into their parent
+ * list).
+ *
+ * Soft line breaks inside a paragraph collapse into spaces, which is what the
+ * browser does for the web widget.
+ */
+
+interface MarkdownProps {
+    content: string;
+    /** Body text. */
+    color: string;
+    /** Chrome that is not text: the rule, the quote bar, the code outline. */
+    mutedColor: string;
+    linkColor: string;
+    fontSize?: number;
+    fontFamily?: string;
+}
+declare const Markdown: FC<MarkdownProps>;
+
+/**
+ * Node identifiers for integrators and end-to-end tests.
+ *
+ * The web widget tags every meaningful node with `data-ringg="..."` and treats
+ * those names as a contract — integrators select on them, so renaming one is a
+ * breaking change. RN has no attribute namespace, but it has `testID`, which
+ * surfaces to the same audiences (Detox, Maestro, Appium, the native view
+ * hierarchy).
+ *
+ * So the mapping is mechanical and total: `data-ringg="header-title"` becomes
+ * `testID="ringg-header-title"`. The prefix keeps widget nodes from colliding
+ * with the host app's own testIDs, and the suffix stays byte-identical to web
+ * so one selector list documents both platforms.
+ */
+/** `"header-title"` → `"ringg-header-title"`. */
+declare const ringgId: (name: string) => string;
+
+export { type AudioSessionPort, type ControllerPorts, GradientFill, type HostAction, type HostActionHandler, type LiveKitTransport, type LiveKitTransportOptions, Markdown, type PlayTune, RinggWidget, type RinggWidgetConfig, type RinggWidgetController, type RinggWidgetProps, type TransportAdapter, WidgetThemeProvider, appOrigin, createAudioSession, createCallbackEventBus, createHostActionDispatcher, createLiveKitTransport, createNativeMicPermission, createNotificationPlayer, createRinggWidgetController, createSilentNotificationPlayer, resolveButtonRadius, resolveFontFamily, resolveRadius, ringgId, solidColor, toSize, toViewStyle, useRinggComponents, useRinggMessages, useRinggSession, useRinggShell, useRinggSlashCommands, useRinggTyping, useStoreSnapshot, useWidgetTheme };