@graineai/inapp-react-native 0.27.4 → 0.28.0

package/INTEGRATION.md

@@ -389,6 +389,46 @@ nowhere. Save is what pushes the catalogue to the agent.
 
 ---
 
+### The contract, exactly
+
+Four rules decide what the agent can do and what the customer is told. Each
+one has bitten a real integration.
+
+**Registration is per mounted screen.** `useGraineAction` registers the
+handler when the component mounts and unregisters it when it unmounts, so the
+agent is offered only what the screen in front of the customer can actually
+do. Register in the screen that performs the action, not at the root — an
+action registered at the root is offered on every screen, including the ones
+where it makes no sense, and the agent will call it there.
+
+**`availableActions` narrows; omitting it is the default you want.**
+On `useGraineScreen`, leave it out and every action registered on the mounted
+screen is offered. Pass a list to offer a subset. Pass `[]` to offer
+*nothing* — say that deliberately, for a read-only screen. It can only ever
+narrow: an action the dashboard never declared is not callable whatever
+appears here, and the server enforces that, not this field. (Before 0.27.3
+the SDK could send `[]` by accident while handlers were still registering,
+which disarmed the agent for the whole screen; it now sends `[]` only when
+you wrote `[]`.)
+
+**A handler has six seconds.** `ACTION_DEADLINE_MS`. Return promptly — do
+the slow part after you have answered. A handler that has not resolved by
+then is answered as a timeout on the runtime side, and the agent tells the
+customer it was *not* done rather than guessing. A handler that throws is
+answered as `error` for the same reason.
+
+**The status is what the customer is told.** `{ status: "ok" }` makes the
+agent say it is done, so return it only when it is. `{ status: "refused",
+message }` is often the most useful answer you can give — "this field is
+locked after submission" — and the agent passes the reason on. `message` is
+for the agent, which decides how to phrase it, not text read to the customer.
+
+**Where it all ends up.** Every call the agent makes lands in Call History
+with the app's answer beside it — "Ran set_ring (state: off) → ok" or
+"→ refused: …" — on the timeline against the turn it happened in, and in the
+execution log. A refusal there is the moment a customer was told something
+that did not happen, which is exactly the row a product team wants to find.
+
 ## Step 4b — Show them where, and draw them things
 
 ### Pointing at something on screen
@@ -518,6 +558,53 @@ your funnel.
 
 ---
 
+## Captions and hanging up
+
+`GraineVoiceLauncher`'s render prop gives you the whole transcript and the CC
+switch, so a caption box is a `map` and nothing else. **0.28.0.**
+
+```tsx
+<GraineVoiceLauncher webView={WebView} active={open} autoStart>
+  {(api) => (
+    <>
+      {api.captionsOn && api.captions.map((c, i) => (
+        <Text key={i} style={{ opacity: c.live ? 0.7 : 1 }}>
+          {c.role === "agent" ? "Ring" : "You"}: {c.text}
+        </Text>
+      ))}
+      <Button title="CC" onPress={() => api.setCaptionsOn(!api.captionsOn)} />
+      <Button title="End" onPress={api.end} />
+    </>
+  )}
+</GraineVoiceLauncher>
+```
+
+| On `api` | |
+|---|---|
+| `captions` | Every turn so far, oldest first, capped at `CAPTION_HISTORY` (12) |
+| `caption` | The turn being said now, or the last one. `null` before any |
+| `captionsOn` / `setCaptionsOn` | The CC switch. Defaults **on** |
+| `clearCaptions()` | Forget the transcript without ending the call |
+| `end()` | Hang up |
+
+A turn arrives many times as its words come in — each with fuller text and
+`live: true` — then once more settled with `live: false`. The launcher folds
+those into one entry, so `captions` holds turns, not keystrokes. Render `live`
+ones as provisional if you want; they are the same line about to be finished.
+
+The transcript is **cleared when a call starts and when you set `active={false}`**.
+A call's words outliving its call is a privacy question, not a feature — if you
+need them afterwards, copy them in `onEnded`.
+
+`onCaption` still fires for every line and is unchanged; it is now a convenience
+on top of `captions` rather than the only way to see them.
+
+**Hanging up** happens on `api.end()` and again on `active={false}` — both post
+the same idempotent stop frame, so a host that does one, the other, or both
+ends exactly one call. Before 0.27.6 the deactivate path was conditional on the
+launcher's own idea of whether a call was running, which could close the UI and
+leave the call up.
+
 ## Tap capture when your screens sit above the provider
 
 `GraineProvider` wraps its children in `GraineTouchCapture`, so an app whose
@@ -727,7 +814,7 @@ is not happening, and the table says which.
 
 | Wait | What it is | When it is paid | Typical |
 |---|---|---|---|
-| Page load | The voice engine is a page in a WebView | **Before the tap** — `GraineFab` and the provider mount the engine on open and keep it warm (0.27.2+) | ~4s, hidden |
+| Page load | The voice engine is a page in a WebView | **Before the tap** — `GraineFab` mounts the engine on open; a custom bar mounts `GraineVoiceLauncher` at launch with `active={false}` and flips it on open (0.27.5) | ~4s, hidden |
 | Mint + REGISTER | A 120-second SIP credential, then registration on the SBC | **Before the tap**, re-warmed as it nears expiry | ~1.6s, hidden |
 | Microphone | The OS permission prompt, first time only | At the tap | 0 once granted |
 | INVITE → answer | The call itself | At the tap | ~0.3s |
@@ -1037,6 +1124,7 @@ told to ignore).
 | `onMicDenied` | `(reason) => void` | `NotAllowedError` is a refusal; `NotFoundError` is a device with no usable microphone. Different sentences for a customer. |
 | `onError` | `(message) => void` | Voice could not be set up at all — key rejected, agent not enabled for apps, no network. Without this the launcher renders nothing and you cannot tell why. |
 | `children` | `(api) => ReactNode` | Receives `{ connected, connecting, muted, start, end, setMuted }`. |
+| `active` | `boolean` | Default `true`. Mount early with `false` so the engine page loads before the customer needs it (it registers nothing while idle); flip to `true` when your UI opens — with `autoStart` that places the call, without it it warms the registration so the tap is instant. Back to `false` ends a live call. (0.27.5; 0.27.6 makes that hangup unconditional) |
 
 **The launcher owns the connection.** It asks for the microphone, resolves the
 session, holds the socket and relays your screen, actions and events onto it. So

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { UNNAMED_TAP } from "./protocol.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";
-export { GraineVoiceLauncher, type GraineVoiceLauncherProps, type GraineVoiceApi, } from "./react-native/voice-launcher.js";
+export { GraineVoiceLauncher, CAPTION_HISTORY, type GraineVoiceLauncherProps, type GraineVoiceApi, } from "./react-native/voice-launcher.js";
 export { LauncherVisibilityTracker, activeRouteName, type LauncherInset, type LauncherContinuity, type LauncherDelayPolicy, type LauncherGroup, type LauncherVisibility, type VisibilityDecision, } from "./react-native/navigation.js";

package/dist/index.js

@@ -10,5 +10,5 @@ export { UNNAMED_TAP } from "./protocol.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";
-export { GraineVoiceLauncher, } from "./react-native/voice-launcher.js";
+export { GraineVoiceLauncher, CAPTION_HISTORY, } from "./react-native/voice-launcher.js";
 export { LauncherVisibilityTracker, activeRouteName, } from "./react-native/navigation.js";

package/dist/react-native/voice-launcher.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import { type Caption } from "./index.js";
 export interface GraineVoiceLauncherProps {
     transport?: "ws" | "rtc";
     onTransport?: (info: {
@@ -9,6 +10,7 @@ export interface GraineVoiceLauncherProps {
     }) => void;
     webView: React.ComponentType<any>;
     autoStart?: boolean;
+    active?: boolean;
     onCaption?: (c: {
         role: string;
         text: string;
@@ -31,5 +33,11 @@ export interface GraineVoiceApi {
     start: () => void;
     end: () => void;
     setMuted: (m: boolean) => void;
+    captions: Caption[];
+    caption: Caption | null;
+    captionsOn: boolean;
+    setCaptionsOn: (on: boolean) => void;
+    clearCaptions: () => void;
 }
-export declare function GraineVoiceLauncher({ webView: WebView, autoStart, transport, onTransport, onCaption, onCallState, onMicDenied, onError, onEnded, children, }: GraineVoiceLauncherProps): React.JSX.Element;
+export declare const CAPTION_HISTORY = 12;
+export declare function GraineVoiceLauncher({ webView: WebView, autoStart, active, transport, onTransport, onCaption, onCallState, onMicDenied, onError, onEnded, children, }: GraineVoiceLauncherProps): React.JSX.Element;

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

@@ -3,14 +3,28 @@ import { useCallback, useEffect, useRef, useState } from "react";
 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, }) {
+export const CAPTION_HISTORY = 12;
+export function GraineVoiceLauncher({ webView: WebView, autoStart = false, active = true, transport, onTransport, onCaption, onCallState, onMicDenied, onError, onEnded, children, }) {
     const { client, appearance } = useGraineAgent();
     const ref = useRef(null);
     const startedRef = useRef(false);
+    const activeRef = useRef(active);
+    activeRef.current = active;
+    const mountedIdleRef = useRef(!active);
     const [connected, setConnected] = useState(false);
     const [connecting, setConnecting] = useState(false);
     const [muted, setMutedState] = useState(false);
     const [ready, setReady] = useState(false);
+    const [captions, setCaptions] = useState([]);
+    const [captionsOn, setCaptionsOn] = useState(true);
+    const foldCaption = useCallback((next) => {
+        setCaptions((prev) => {
+            const tail = prev[prev.length - 1];
+            const continues = tail && tail.live && tail.role === next.role;
+            const merged = continues ? [...prev.slice(0, -1), next] : [...prev, next];
+            return merged.length > CAPTION_HISTORY ? merged.slice(-CAPTION_HISTORY) : merged;
+        });
+    }, []);
     const post = useCallback((msg) => {
         ref.current?.injectJavaScript(`window.postMessage(${JSON.stringify(msg)}, "*"); true;`);
     }, []);
@@ -113,7 +127,7 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
             case "graine:ready":
                 setReady(true);
                 pushContext();
-                if ((autoStart || pendingStartRef.current) && !startedRef.current) {
+                if ((autoStart || pendingStartRef.current) && !startedRef.current && activeRef.current) {
                     pendingStartRef.current = false;
                     startedRef.current = true;
                     void beginCall();
@@ -129,9 +143,16 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
             case "graine:muted":
                 setMutedState(!!msg.muted);
                 return;
-            case "graine:caption":
-                onCaption?.({ role: msg.role, text: msg.text, live: !!msg.live });
+            case "graine:caption": {
+                const line = {
+                    role: msg.role === "agent" ? "agent" : "customer",
+                    text: String(msg.text ?? ""),
+                    live: !!msg.live,
+                };
+                foldCaption(line);
+                onCaption?.(line);
                 return;
+            }
             case "graine:ended":
                 setConnected(false);
                 setConnecting(false);
@@ -158,15 +179,21 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
                 return;
             }
         }
-    }, [autoStart, beginCall, client, onCaption, onCallState, onMicDenied, onTransport, onError, onEnded, post, pushContext]);
+    }, [autoStart, beginCall, client, onCaption, onCallState, onMicDenied, onTransport, onError, onEnded, post, pushContext, foldCaption]);
     const pendingStartRef = useRef(false);
     const api = {
         connected,
         connecting,
         muted,
         ready: !!voiceAgentId && ready,
+        captions,
+        caption: captions.length ? captions[captions.length - 1] : null,
+        captionsOn,
+        setCaptionsOn,
+        clearCaptions: useCallback(() => setCaptions([]), []),
         start: useCallback(() => {
             setConnecting(true);
+            setCaptions([]);
             if (!ready) {
                 pendingStartRef.current = true;
                 return;
@@ -180,6 +207,38 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
         }, [post]),
     };
     useEffect(() => () => { post({ type: "graine:end-call" }); }, [post]);
+    const activeSeenRef = useRef(null);
+    useEffect(() => {
+        const first = activeSeenRef.current === null;
+        activeSeenRef.current = active;
+        if (active) {
+            if (autoStart) {
+                if (startedRef.current)
+                    return;
+                setConnecting(true);
+                setCaptions([]);
+                if (ready) {
+                    startedRef.current = true;
+                    void beginCall();
+                }
+                else
+                    pendingStartRef.current = true;
+            }
+            else if (!first) {
+                post({ type: "graine:warm" });
+            }
+            return;
+        }
+        if (first)
+            return;
+        post({ type: "graine:end-call" });
+        startedRef.current = false;
+        pendingStartRef.current = false;
+        setConnected(false);
+        setConnecting(false);
+        setCaptions([]);
+        onCallState?.({ connected: false, connecting: false });
+    }, [active]);
     useEffect(() => {
         let last = AppState.currentState;
         let pending = null;
@@ -211,6 +270,7 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, trans
     const effectiveTransport = transport ?? (appearance?.audioTransport === "rtc" ? "rtc" : "ws");
     const src = `${client.opts.baseUrl.replace(/\/$/, "")}/embed/${voiceAgentId}` +
         `?mode=voice&branding=0&embed=1&transport=${effectiveTransport}` +
+        (mountedIdleRef.current ? "&idle=1" : "") +
         `&pk=${encodeURIComponent(client.opts.publishableKey)}` +
         (appearance?.accent ? `&accent=${encodeURIComponent(String(appearance.accent).replace("#", ""))}` : "");
     return (_jsxs(_Fragment, { children: [_jsx(View, { style: { position: "absolute", width: 1, height: 1, opacity: 0, bottom: 0, left: 0 }, pointerEvents: "none", children: _jsx(WebView, { ref: ref, source: { uri: src }, originWhitelist: ["*"], javaScriptEnabled: true, domStorageEnabled: true, allowsInlineMediaPlayback: true, mediaPlaybackRequiresUserAction: false, mediaCapturePermissionGrantType: "grant", onMessage: onMessage, style: { width: 1, height: 1, backgroundColor: "transparent" } }) }), children?.(api)] }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graineai/inapp-react-native",
-  "version": "0.27.4",
+  "version": "0.28.0",
   "type": "module",
   "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",