@graineai/inapp-react-native 0.21.0 → 0.23.0

package/INTEGRATION.md

@@ -765,6 +765,39 @@ and resamples in its output stage, which is where the artefacts came from.
 
 ---
 
+## Coming from RevRag
+
+Same shape, different names. If you have a RevRag integration, this is the
+whole translation:
+
+| RevRag | Graine |
+| --- | --- |
+| `useInitialize({ apiKey })` → `{ isInitialized, error }` | `useGraineReady()` → `{ ready, error }` (the key goes on `GraineProvider`) |
+| `EmbedProvider navigationRef appVersion` | `GraineProvider navigationRef appVersion` |
+| `includeScreens` | `includeScreens` |
+| `embedButtonDelayMs` | `launcherDelayMs` |
+| `embedButtonVisibilityConfig` `{ defaultDelayMs, defaultInset, groups }` | `visibility` `{ defaultDelayMs, defaultInset, groups }` |
+| `EmbedButtonGroupConfig` `{ id, screens, continuity, delayMs, delayPolicy, inset }` | `LauncherGroup` — identical fields |
+| `continuous` / `perScreen` | same |
+| `perScreen` / `oncePerGroupEntry` / `oncePerAppSession` | same |
+| `EmbedButtonInset` | `LauncherInset` — same shape |
+| `EmbedButton` (mount it yourself) | `GraineLauncher` |
+| `Embed.Event(USER_DATA, { app_user_id, data })` | `useGraineIdentify()` / `client.identify({ id, name, … })` |
+| `Embed.Event(SCREEN_STATE, { screen, data })` | `useGraineScreen({ screen, fields })` |
+| `Embed.Event(CUSTOM_EVENT, data)` / `ANALYTICS_DATA` | `useGraineTrack()` / `client.track(name, data)` |
+| `embedOnAgent(AGENT_CONVERSATION_STARTED / ENDED)` | `useGraineEvents(e => e.type === "conversation_started" / "conversation_ended")` |
+| `AgentEvent.MICROPHONE_PERMISSION_DENIED` | `{ type: "mic_denied", reason }` on the same stream |
+| `AgentEvent.POPUP_MESSAGE_VISIBLE` | `{ type: "launcher_shown", screen }` |
+| `checkPermissions()` | `requestMicrophonePermission()` |
+| server `widget_config` | `appearance` from the session, via `resolveNativeAppearance` |
+| LiveKit native setup | none — see *Why there is no LiveKit step* |
+
+Two things RevRag has that are deliberately absent: a LiveKit install step
+(audio rides a WebView on a hosted page, so audio fixes ship without an app
+release), and click tracking on every touchable by default (`useGraineTap` is
+opt-in per element, because a stream of every tap is noise the agent has to be
+told to ignore).
+
 ## Reference
 
 | Hook | For |

package/dist/client.d.ts

@@ -17,6 +17,16 @@ export interface SessionConfig {
     appearance?: Record<string, any>;
     variables?: Record<string, string>;
     components?: any[];
+    appActions?: Array<{
+        tool_name?: string;
+        toolName?: string;
+        name?: string;
+    }>;
+}
+export interface ActionDiagnosis {
+    usable: string[];
+    undeclared: string[];
+    unhandled: string[];
 }
 export declare class GraineInAppClient {
     readonly opts: GraineInAppOptions;
@@ -40,12 +50,15 @@ export declare class GraineInAppClient {
     private muted;
     private playoutClock;
     private identity;
+    private appVersion;
     private recentEvents;
     constructor(opts: GraineInAppOptions);
     on(event: string, fn: Listener): () => void;
-    private emit;
+    emit(event: string, payload?: any): void;
     private get fetch();
     session(): Promise<SessionConfig>;
+    checkActions(): ActionDiagnosis;
+    private reportActionMismatch;
     private ticket;
     connect(): Promise<void>;
     private openSocket;
@@ -72,6 +85,7 @@ export declare class GraineInAppClient {
     reportEvent(event: AppEvent): void;
     track(name: string, data?: Record<string, unknown>): void;
     private scheduleScreen;
+    setAppVersion(version: string | null | undefined): void;
     buildContextFrame(): {
         type: "app_context";
         context: Record<string, unknown>;

package/dist/client.js

@@ -24,6 +24,7 @@ export class GraineInAppClient {
         this.muted = false;
         this.playoutClock = null;
         this.identity = {};
+        this.appVersion = null;
         this.recentEvents = [];
         if (!opts?.publishableKey)
             throw new Error("[Graine] publishableKey is required.");
@@ -68,8 +69,37 @@ export class GraineInAppClient {
             throw new Error(data?.error || `Embed rejected (${res.status})`);
         }
         this.config = data;
+        this.reportActionMismatch();
         return this.config;
     }
+    checkActions() {
+        const registered = [...this.actions.keys()];
+        const declared = new Set((this.config?.appActions ?? [])
+            .map((a) => a?.tool_name || a?.toolName || a?.name)
+            .filter((n) => Boolean(n)));
+        return {
+            usable: registered.filter((n) => declared.has(n)),
+            undeclared: registered.filter((n) => !declared.has(n)),
+            unhandled: [...declared].filter((n) => !this.actions.has(n)),
+        };
+    }
+    reportActionMismatch() {
+        if (this.actions.size === 0)
+            return;
+        const { undeclared, unhandled } = this.checkActions();
+        if (!undeclared.length && !unhandled.length)
+            return;
+        this.emit("diagnostic", { type: "actions", ...this.checkActions() });
+        if (undeclared.length) {
+            console.warn(`[Graine] This app registered ${undeclared.length} action(s) the agent is not ` +
+                `configured to call, so the agent cannot use them: ${undeclared.join(", ")}. ` +
+                `Add them to the agent's app_actions in Embed & Widgets.`);
+        }
+        if (unhandled.length) {
+            console.warn(`[Graine] The agent is configured to call ${unhandled.length} action(s) this ` +
+                `build does not implement: ${unhandled.join(", ")}. It will be refused mid-sentence.`);
+        }
+    }
     async ticket() {
         try {
             const res = await this.fetch(`${this.opts.baseUrl}/api/embed/ticket`, {
@@ -341,6 +371,10 @@ export class GraineInAppClient {
             }
         }, CONTEXT_THROTTLE_MS);
     }
+    setAppVersion(version) {
+        const v = version == null ? "" : String(version).trim();
+        this.appVersion = v || null;
+    }
     buildContextFrame() {
         const hasIdentity = Object.keys(this.identity).length > 0;
         if (!this.screen && !hasIdentity && this.recentEvents.length === 0)
@@ -352,6 +386,7 @@ export class GraineInAppClient {
                 ...rest,
                 ...(this.screen ? { idle_ms: Date.now() - this.screenSince } : {}),
                 ...(Object.keys(this.identity).length ? { user: this.identity } : {}),
+                ...(this.appVersion ? { app_version: this.appVersion } : {}),
                 ...(this.recentEvents.length ? { recent_events: this.recentEvents } : {}),
                 ...(this.highlightables.size ? { highlightable: [...this.highlightables] } : {}),
             }),

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export type { ActionHandler, AppActionRequest, AppActionResult, AppEvent, ScreenContext, ScreenField, } from "./protocol.js";
-export { GraineInAppClient, type GraineInAppOptions, type SessionConfig } from "./client.js";
+export { GraineInAppClient, type GraineInAppOptions, type SessionConfig, type ActionDiagnosis, } from "./client.js";
 export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, type AudioAdapter, type VoiceSessionOptions, } from "./voice.js";
 export { EchoGuard, decodeAgentAudio, decodeMuLaw, decodePcm16, base64ToBytes, type AudioFormat, type DecodedAudio, } from "./audio.js";
 export { addMaskRule, maskDeep, maskString } from "./mask.js";
-export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, type GraineEvent, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index.js";
+export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, useGraineReady, type GraineEvent, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index.js";
+export { requestMicrophonePermission } from "./react-native/permissions.js";
 export { resolveNativeAppearance, type NativeAppearance, type NativeAppearanceFallback, } from "./react-native/appearance.js";
 export { RtcVoiceSessionController, RtcVoiceError, type RtcVoiceState, type RtcVoiceErrorCode, type RtcVoiceSession, type RtcVoiceOptions, } from "./react-native/voice-rtc.js";
 export { GraineAgentBar, GraineLauncher, type GraineAgentBarProps, type GraineLauncherProps, type GraineBarTheme, } from "./react-native/ui.js";

package/dist/index.js

@@ -1,8 +1,9 @@
-export { GraineInAppClient } from "./client.js";
+export { GraineInAppClient, } from "./client.js";
 export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, } from "./voice.js";
 export { EchoGuard, decodeAgentAudio, decodeMuLaw, decodePcm16, base64ToBytes, } from "./audio.js";
 export { addMaskRule, maskDeep, maskString } from "./mask.js";
-export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, } from "./react-native/index.js";
+export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, useGraineHighlight, useGraineWidget, useGraineReady, } from "./react-native/index.js";
+export { requestMicrophonePermission } from "./react-native/permissions.js";
 export { resolveNativeAppearance, } from "./react-native/appearance.js";
 export { RtcVoiceSessionController, RtcVoiceError, } from "./react-native/voice-rtc.js";
 export { GraineAgentBar, GraineLauncher, } from "./react-native/ui.js";

package/dist/react-native/index.d.ts

@@ -21,6 +21,7 @@ interface GraineContextValue {
     launcherInset: LauncherInset;
     currentScreen: string | null;
     appearance: Record<string, any> | null;
+    sessionReady: boolean;
     onEvent: (fn: (e: GraineEvent) => void) => () => void;
     track: (name: string, data?: Record<string, unknown>) => void;
     identify: (user: Record<string, unknown> | null) => void;
@@ -49,6 +50,12 @@ export type GraineEvent = {
 } | {
     type: "error";
     message: string;
+} | {
+    type: "mic_denied";
+    reason: string;
+} | {
+    type: "launcher_shown";
+    screen: string | null;
 };
 export interface GraineWidget {
     id: string;
@@ -75,11 +82,12 @@ export interface GraineProviderProps extends Partial<GraineInAppOptions> {
     navigationRef?: {
         current: any;
     } | null;
+    appVersion?: string;
     includeScreens?: string[];
     launcherDelayMs?: number;
     visibility?: LauncherVisibility;
 }
-export declare function GraineProvider({ children, autoConnect, onProactive, endOnBackground, navigationRef, includeScreens, launcherDelayMs, visibility, client: providedClient, ...options }: GraineProviderProps): React.JSX.Element;
+export declare function GraineProvider({ children, autoConnect, onProactive, endOnBackground, navigationRef, appVersion, includeScreens, launcherDelayMs, visibility, client: providedClient, ...options }: GraineProviderProps): React.JSX.Element;
 export declare function useGraineAgent(): GraineContextValue;
 export declare function useGraineEvents(handler: (e: GraineEvent) => void): void;
 export declare function useGraineTrack(): (name: string, data?: Record<string, unknown>) => void;
@@ -101,4 +109,8 @@ export declare function useGraineWidget(): {
     dismiss: () => void;
 };
 export declare function useGraineAction(name: string, handler: ActionHandler): void;
+export declare function useGraineReady(): {
+    ready: boolean;
+    error: string | null;
+};
 export {};

package/dist/react-native/index.js

@@ -5,7 +5,7 @@ import { GraineInAppClient } from "../client.js";
 import { VoiceSession } from "../voice.js";
 import { LauncherVisibilityTracker, activeRouteName, } from "./navigation.js";
 const Ctx = createContext(null);
-export function GraineProvider({ children, autoConnect = true, onProactive, endOnBackground = true, navigationRef, includeScreens, launcherDelayMs = 0, visibility, client: providedClient, ...options }) {
+export function GraineProvider({ children, autoConnect = true, onProactive, endOnBackground = true, navigationRef, appVersion, includeScreens, launcherDelayMs = 0, visibility, client: providedClient, ...options }) {
     const clientRef = useRef(null);
     if (!clientRef.current) {
         clientRef.current =
@@ -37,6 +37,7 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
         return () => { listenersRef.current.delete(fn); };
     }, []);
     const [appearance, setAppearance] = useState(null);
+    const [sessionReady, setSessionReady] = useState(false);
     const [currentScreen, setCurrentScreen] = useState(null);
     const [launcherVisible, setLauncherVisible] = useState(false);
     const [launcherInset, setLauncherInset] = useState({ right: 16, bottom: 20 });
@@ -76,12 +77,14 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
             }
             if (decision.delayMs <= 0) {
                 setLauncherVisible(true);
+                emitEvent({ type: "launcher_shown", screen: route });
                 return;
             }
             setLauncherVisible(false);
             showTimerRef.current = setTimeout(() => {
                 showTimerRef.current = null;
                 setLauncherVisible(true);
+                emitEvent({ type: "launcher_shown", screen: route });
             }, decision.delayMs);
         };
         apply();
@@ -95,6 +98,7 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
                 nav.removeListener("state", apply);
         };
     }, [navigationRef, client]);
+    useEffect(() => { client.setAppVersion(appVersion); }, [client, appVersion]);
     useEffect(() => {
         if (!navigationRef?.current)
             setLauncherVisible(true);
@@ -129,6 +133,7 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
                 return [...prev, { role: "agent", text, live: true }];
             })),
             client.on("widget", (widget) => setWidgets((prev) => [...prev, widget])),
+            client.on("mic_denied", (p) => emitEvent({ type: "mic_denied", reason: String(p?.reason || "NotAllowedError") })),
             client.on("muted", (m) => {
                 setMutedState(m);
                 emitEvent({ type: "muted", muted: m });
@@ -153,6 +158,7 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
                 const cfg = client.config ?? (await client.session());
                 if (cfg?.appearance)
                     setAppearance(cfg.appearance);
+                setSessionReady(true);
             }
             catch {
             }
@@ -234,11 +240,12 @@ export function GraineProvider({ children, autoConnect = true, onProactive, endO
         launcherInset,
         currentScreen,
         appearance,
+        sessionReady,
         onEvent,
         track: (name, data) => client.track(name, data),
         identify: (user) => client.identify(user),
     }), [client, connected, connecting, error, open, messages, widgets, muted, agentSpeaking, caption,
-        launcherVisible, launcherInset, currentScreen, onEvent, appearance]);
+        launcherVisible, launcherInset, currentScreen, onEvent, appearance, sessionReady]);
     return _jsx(Ctx.Provider, { value: value, children: children });
 }
 function useGraine() {
@@ -368,3 +375,7 @@ export function useGraineAction(name, handler) {
     handlerRef.current = handler;
     useEffect(() => client.registerAction(name, (args) => handlerRef.current(args)), [client, name]);
 }
+export function useGraineReady() {
+    const { sessionReady, error } = useGraineAgent();
+    return { ready: sessionReady, error };
+}

package/dist/react-native/permissions.d.ts

@@ -0,0 +1,5 @@
+export declare function requestMicrophonePermission(rationale?: {
+    title?: string;
+    message?: string;
+    buttonPositive?: string;
+}): Promise<boolean>;

package/dist/react-native/permissions.js

@@ -0,0 +1,21 @@
+import { PermissionsAndroid, Platform } from "react-native";
+export async function requestMicrophonePermission(rationale = {}) {
+    if (Platform.OS !== "android")
+        return true;
+    try {
+        const perm = PermissionsAndroid?.PERMISSIONS?.RECORD_AUDIO;
+        if (!perm)
+            return true;
+        if (await PermissionsAndroid.check(perm))
+            return true;
+        const res = await PermissionsAndroid.request(perm, {
+            title: rationale.title ?? "Microphone",
+            message: rationale.message ?? "Allow the microphone so you can talk to the assistant.",
+            buttonPositive: rationale.buttonPositive ?? "Allow",
+        });
+        return res === PermissionsAndroid.RESULTS.GRANTED;
+    }
+    catch {
+        return true;
+    }
+}

package/dist/react-native/voice-launcher.js

@@ -1,7 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { AppState, PermissionsAndroid, Platform, View } from "react-native";
+import { AppState, View } from "react-native";
 import { useGraineAgent } from "./index.js";
+import { requestMicrophonePermission } from "./permissions.js";
 export function GraineVoiceLauncher({ webView: WebView, autoStart = false, transport, onTransport, onCaption, onCallState, onMicDenied, onError, onEnded, children, }) {
     const { client, appearance } = useGraineAgent();
     const ref = useRef(null);
@@ -34,26 +35,7 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
         })();
         return () => { cancelled = true; };
     }, [client, voiceAgentId]);
-    const ensureMic = useCallback(async () => {
-        if (Platform.OS !== "android")
-            return true;
-        try {
-            const perm = PermissionsAndroid?.PERMISSIONS?.RECORD_AUDIO;
-            if (!perm)
-                return true;
-            if (await PermissionsAndroid.check(perm))
-                return true;
-            const res = await PermissionsAndroid.request(perm, {
-                title: "Microphone",
-                message: "Allow the microphone so you can talk to the assistant.",
-                buttonPositive: "Allow",
-            });
-            return res === PermissionsAndroid.RESULTS.GRANTED;
-        }
-        catch {
-            return true;
-        }
-    }, []);
+    const ensureMic = useCallback(() => requestMicrophonePermission(), []);
     const pushContext = useCallback(() => {
         const frame = client.buildContextFrame();
         if (!frame)
@@ -80,6 +62,7 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
         if (!(await ensureMic())) {
             setConnecting(false);
             onMicDenied?.("NotAllowedError");
+            client.emit("mic_denied", { reason: "NotAllowedError" });
             return;
         }
         post({ type: "graine:start-call" });
@@ -155,6 +138,7 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
                 onEnded?.();
                 return;
             case "graine:mic-denied":
+                client.emit("mic_denied", { reason: String(msg.reason || "NotAllowedError") });
                 onMicDenied?.(String(msg.reason || "denied"));
                 return;
             case "graine:widget": {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@graineai/inapp-react-native",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "type": "module",
-  "description": "Graine in-app agent for React Native \u2014 an agent that sees the screen your customer is on and can act on it.",
+  "description": "Graine in-app agent for React Native — an agent that sees the screen your customer is on and can act on it.",
   "license": "MIT",
   "private": false,
   "main": "dist/index.js",