@graineai/inapp-react-native 0.11.0 → 0.11.1

package/INTEGRATION.md

@@ -18,6 +18,24 @@ Package: `@graineai/inapp-react-native`
 | Peer install | `react-native-webview` — autolinks, no setup code |
 | From Graine | your **publishable key**, from Agent → Embed & Widgets |
 
+### Two dashboard steps first
+
+Each takes a minute and each, skipped, produces a failure that looks like
+something else.
+
+**1. Give the app its own agent.** Clone the website agent rather than pointing
+the app at it. Actions are declared per agent and every surface that agent serves
+is offered all of them, so a shared agent hands your website tools that only
+exist inside the app — and picks worse for having them. The clone carries the
+prompt, knowledge base and voice across; change only what differs.
+
+**2. Add `app://` to that agent's Allowed domains** (Agent → Embed & Widgets →
+Install & domains). A native app has no `Origin` header, and there is no header a
+client could send that we would trust instead — so `app://` is how you say "this
+agent may also be reached from an app". Without it the connection is refused with
+`no_origin` and **the launcher never renders**, which reads exactly like a bad
+key. An empty allowlist refuses everything for the same reason.
+
 **There is no native setup.** No `MainApplication.kt` edit, no `AppDelegate.swift`
 edit, no ProGuard rules, no babel plugin ordering. The microphone and speaker run
 inside a WebView pointed at your hosted agent page, so every fix to the audio
@@ -140,9 +158,33 @@ screen; when it fires it names the field that is `invalid` or `empty`, so the
 agent opens with "the PAN isn't being accepted" rather than "need a hand?".
 Without `status` it can only manage the second one.
 
+| `status` | Means | What the agent does |
+|---|---|---|
+| `empty` | Nothing entered | Offers to fill it |
+| `filled` | Has a value | Leaves it alone |
+| `invalid` | Rejected — pair with `error` | Names the problem, offers the fix |
+| `pending` | In flight | Waits instead of claiming either outcome |
+| `locked` | Not changeable from here | Routes elsewhere rather than offering to type |
+
+`locked` is the one worth remembering. An OS permission the customer must grant
+in system settings is not `empty` — nobody can fill it on this screen. Marked
+`empty`, the agent offers to do it and fails; marked `locked`, it says where to go.
+
 Report the real value. Masking happens on the way out and again on arrival — a
 screen that pre-redacts just blinds the agent.
 
+**Name every screen.** The route the SDK reports is an identifier, not a name.
+Ship `kyc_documents` and the agent reads your routing table to your customers.
+Keep a `Record<ScreenName, string>` of the words actually printed on each screen,
+typed over your route union so the screen somebody adds next year fails the build
+instead of reaching a customer as a slug.
+
+**Where the hook goes.** Below every piece of state it reads — the object is
+built during render, so a `const` declared under it is in its temporal dead zone
+and throws — and above every early return, or the hook order changes between
+renders. Action handlers have neither constraint: their bodies only run when the
+agent calls them.
+
 ---
 
 ## Step 4 — Let it act
@@ -276,8 +318,55 @@ part. Everything else is unchanged.
 
 ---
 
+## Session lifecycle
+
+One session per client, and it follows the app.
+
+**Backgrounding ends the call.** Switching apps does not unmount a React tree,
+so without this the WebView stays mounted with the microphone open and the
+conversation still billing while nobody is listening. iOS makes it worse rather
+than better: it suspends the WebView's audio without telling the socket, so the
+call survives as a leg that can no longer hear anything and bills for silence.
+
+The session ends on `background`, never on `inactive` — iOS reports `inactive`
+for the app switcher, a pulled-down notification, and the moment a permission
+dialog appears, so ending on it would mean the microphone prompt hangs up the
+call that asked for it.
+
+```tsx
+<GraineProvider … endOnBackground={false}>   {/* default: true */}
+```
+
+Turn it off only if a conversation should genuinely survive a switch to another
+app, and you are prepared to explain the open microphone.
+
+Text sessions reconnect when the app returns. **Voice does not auto-resume** — a
+call is something a person chose to start, and starting one again because they
+came back to the app is a microphone opening unasked. `connected` goes false;
+draw from that.
+
+**`connect()` is idempotent.** Calling it twice returns the same session rather
+than opening a second socket. This matters under React 18 strict mode, which
+mounts effects twice: previously the first socket was orphaned with no reference
+to close it, and the runtime kept it open and billing until its own timeout.
+
+**`close()` sends a stop frame** before dropping the socket, so the conversation
+is filed as ended rather than as a customer who vanished mid-turn. It is called
+for you on unmount and on backgrounding.
+
+---
+
 ## Troubleshooting
 
+**Nothing renders at all, and the console says `no_origin`.**
+The agent's Allowed domains has no `app://` entry. `no_domains_configured` means
+the allowlist is empty, which denies everything. Both are dashboard fixes, not
+code.
+
+**The agent offers to do things this app cannot.**
+The website agent is being reused. Actions are declared per agent and offered on
+every surface it serves — clone it and give the app its own.
+
 **The agent talks but does not know what screen I am on.**
 `navigationRef` must be the same ref you pass to `NavigationContainer`, and
 `GraineProvider` must wrap it.

package/dist/client.d.ts

@@ -23,6 +23,7 @@ export declare class GraineInAppClient {
     config: SessionConfig | null;
     transport: "gateway" | "direct" | null;
     private ws;
+    private connecting;
     private listeners;
     private actions;
     private screen;
@@ -46,6 +47,7 @@ export declare class GraineInAppClient {
     session(): Promise<SessionConfig>;
     private ticket;
     connect(): Promise<void>;
+    private openSocket;
     private send;
     private onFrame;
     executeAction(name: string, args?: Record<string, unknown>): Promise<AppActionResult>;

package/dist/client.js

@@ -7,6 +7,7 @@ export class GraineInAppClient {
         this.config = null;
         this.transport = null;
         this.ws = null;
+        this.connecting = null;
         this.listeners = new Map();
         this.actions = new Map();
         this.screen = null;
@@ -87,6 +88,14 @@ export class GraineInAppClient {
         }
     }
     async connect() {
+        if (this.ws && (this.ws.readyState === 0 || this.ws.readyState === 1))
+            return;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = this.openSocket().finally(() => { this.connecting = null; });
+        return this.connecting;
+    }
+    async openSocket() {
         if (!this.config)
             await this.session();
         const agentId = this.config.webcallAgentId || this.config.agentId;
@@ -410,6 +419,7 @@ export class GraineInAppClient {
     }
     close() {
         this.stopTimers();
+        this.connecting = null;
         const sock = this.ws;
         this.ws = null;
         if (!sock)

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

@@ -64,6 +64,7 @@ export interface GraineProviderProps extends GraineInAppOptions {
     children: React.ReactNode;
     autoConnect?: boolean;
     onProactive?: (text: string) => void;
+    endOnBackground?: boolean;
     navigationRef?: {
         current: any;
     } | null;
@@ -71,7 +72,7 @@ export interface GraineProviderProps extends GraineInAppOptions {
     launcherDelayMs?: number;
     visibility?: LauncherVisibility;
 }
-export declare function GraineProvider({ children, autoConnect, onProactive, navigationRef, includeScreens, launcherDelayMs, visibility, ...options }: GraineProviderProps): React.JSX.Element;
+export declare function GraineProvider({ children, autoConnect, onProactive, endOnBackground, navigationRef, includeScreens, launcherDelayMs, visibility, ...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;

package/dist/react-native/index.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { AppState } from "react-native";
 import { GraineInAppClient } from "../client";
 import { VoiceSession } from "../voice";
 import { LauncherVisibilityTracker, activeRouteName, } from "./navigation";
 const Ctx = createContext(null);
-export function GraineProvider({ children, autoConnect = true, onProactive, navigationRef, includeScreens, launcherDelayMs = 0, visibility, ...options }) {
+export function GraineProvider({ children, autoConnect = true, onProactive, endOnBackground = true, navigationRef, includeScreens, launcherDelayMs = 0, visibility, ...options }) {
     const clientRef = useRef(null);
     if (!clientRef.current)
         clientRef.current = new GraineInAppClient(options);
@@ -158,6 +159,29 @@ export function GraineProvider({ children, autoConnect = true, onProactive, navi
             client.close();
         };
     }, [client, autoConnect]);
+    useEffect(() => {
+        if (!endOnBackground)
+            return;
+        let last = AppState.currentState;
+        const sub = AppState.addEventListener("change", (next) => {
+            const wasActive = last === "active";
+            last = next;
+            if (next === "background" && wasActive) {
+                client.close();
+                setConnected(false);
+                setConnecting(false);
+                return;
+            }
+            if (next === "active" && !wasActive && autoConnect) {
+                setConnecting(true);
+                client.connect().catch((err) => {
+                    setConnecting(false);
+                    console.error("[Graine]", err?.message ?? err);
+                });
+            }
+        });
+        return () => sub.remove();
+    }, [client, endOnBackground, autoConnect]);
     const value = useMemo(() => ({
         client,
         connected,

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

@@ -1,6 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from "react";
-import { View } from "react-native";
+import { AppState, View } from "react-native";
 import { useGraineAgent } from "./index";
 export function GraineVoiceLauncher({ webView: WebView, autoStart = false, onCaption, onCallState, onMicDenied, onEnded, children, }) {
     const { client, appearance } = useGraineAgent();
@@ -91,6 +91,16 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, onCap
         }, [post]),
     };
     useEffect(() => () => { post({ type: "graine:end-call" }); }, [post]);
+    useEffect(() => {
+        let last = AppState.currentState;
+        const sub = AppState.addEventListener("change", (next) => {
+            const wasActive = last === "active";
+            last = next;
+            if (next === "background" && wasActive)
+                post({ type: "graine:end-call" });
+        });
+        return () => sub.remove();
+    }, [post]);
     const agentId = client.config?.agentId;
     if (!agentId)
         return _jsx(_Fragment, { children: children?.(api) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graineai/inapp-react-native",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "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,