@graineai/inapp-react-native 0.12.0 → 0.15.0

package/INTEGRATION.md

@@ -135,6 +135,34 @@ agent just does not know their name.
 
 ---
 
+### Metadata before the first word
+
+Two places, and the difference is when you know the value.
+
+```tsx
+// Known at build time — carried in the init frame, before the agent speaks.
+<GraineProvider variables={{ tier: 'gold', region: 'IN' }} />
+
+// Known after sign-in — merged into that same init frame if it lands before the
+// socket opens, sent on the next context frame if it lands after.
+identify({ name: user.name, plan: user.plan });
+```
+
+`identify()` wins over `variables` on the same key: a signed-in customer is more
+specific than a default. Both are masked on the device before they leave it.
+
+### It reaches the call record, not only the prompt
+
+Traits are stored on the conversation as `app_user`, and the name labels the row
+in Call History. A web call has no phone number to identify it by, so without
+this every in-app conversation shows a session id.
+
+Read from the LIVE identity rather than the init frame, so a customer who signs
+in halfway through is identified from that moment rather than from a frame that
+predates them.
+
+---
+
 ## Step 3 — Report what is ON the screen
 
 The route gives the agent a screen *name*. This gives it the contents.
@@ -218,6 +246,23 @@ updating the screen.
 
 ---
 
+### Declaring them: paste, do not retype
+
+Keep the list in your repo — `docs/agent-actions.json` is the convention — and
+load it with **Embed & Widgets → App actions → Import from JSON**. A bare array
+works, so does `{ "appActions": [...] }`.
+
+Names must match your `useGraineAction` handlers exactly, and that is the whole
+argument for importing: a name one underscore out declares a tool your app will
+refuse for the life of the release, and the agent keeps trying it. `enum`
+constraints are preserved, so a value the model cannot get wrong stays that way.
+
+Import replaces the panel's contents rather than merging — the file is the
+source of truth, and a merge leaves actions declared here and implemented
+nowhere. Save is what pushes the catalogue to the agent.
+
+---
+
 ## Step 5 — Product events, without interrupting
 
 ```tsx
@@ -235,6 +280,30 @@ and the runtime decides whether it is worth interrupting for.
 
 ---
 
+### When something should be spoken about
+
+```tsx
+const { client } = useGraineAgent();
+client.reportEvent({
+  name: 'mandate_failed',
+  detail: 'Their mandate was declined twice. Offer to switch to a card.',
+});
+```
+
+`track()` is "know this when they next ask". `reportEvent()` is "this may be
+worth interrupting for". `detail` tells the agent what to OFFER — without it the
+agent reads an event name aloud, which is worse than saying nothing.
+
+Reserve it for a dead end the customer would want addressed without asking: a
+save that never reached the server, an upload that failed twice, a payment
+declined. Not a tap, not a navigation, not a save that worked.
+
+The runtime still decides whether to speak: silent while it is talking, while a
+reply is generating, for 20s after the last intervention, and after three in a
+session.
+
+---
+
 ## Step 6 — React to the conversation
 
 ```tsx
@@ -406,6 +475,12 @@ 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.
 
+**Nothing is left holding the call.** An outstanding action's waiter is released
+in a `finally`, so a customer closing the app mid-action releases it too, and
+every wait has a deadline — an app that never answers cannot hold the turn open
+against someone who has already gone. A timeout is reported rather than
+swallowed, because silence would have the agent claim the change landed.
+
 **`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.

package/dist/audio.js

@@ -60,7 +60,8 @@ export function decodeAgentAudio(bytes, declared, latched, fallbackPcmRate = 160
     const pcm16 = muLawWins ? asMuLaw : asPcm;
     const kind = muLawWins ? "mulaw" : "pcm";
     const sampleRate = muLawWins ? 8000 : declared?.sampleRate || fallbackPcmRate;
-    const confident = rms(pcm16) >= CONFIDENT_RMS;
+    const confident = rms(asPcm) >= CONFIDENT_RMS &&
+        zeroCrossingRate(asMuLaw) !== zeroCrossingRate(asPcm);
     return { pcm16, sampleRate, kind, latch: confident ? { kind, sampleRate } : null };
 }
 const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type ActionHandler, type AppActionResult, type AppEvent, type ScreenContext } from "./protocol";
+import { type ActionHandler, type AppActionResult, type AppEvent, type ScreenContext } from "./protocol.js";
 export declare const SUBPROTOCOL = "graine.embed.v1";
 export interface GraineInAppOptions {
     baseUrl: string;
@@ -54,6 +54,12 @@ export declare class GraineInAppClient {
     private runAction;
     private invokeAction;
     getScreen(): ScreenContext | null;
+    getIdentity(): Record<string, string>;
+    getRecentEvents(): Array<{
+        name: string;
+        at: number;
+        data?: Record<string, unknown>;
+    }>;
     getAvailableActions(): string[];
     registerAction(name: string, handler: ActionHandler): () => void;
     get availableActions(): string[];

package/dist/client.js

@@ -1,5 +1,5 @@
-import { ACTION_DEADLINE_MS, CONTEXT_THROTTLE_MS, } from "./protocol";
-import { maskDeep } from "./mask";
+import { ACTION_DEADLINE_MS, CONTEXT_THROTTLE_MS, } from "./protocol.js";
+import { maskDeep } from "./mask.js";
 export const SUBPROTOCOL = "graine.embed.v1";
 const PING_MS = 25000;
 export class GraineInAppClient {
@@ -262,6 +262,12 @@ export class GraineInAppClient {
     getScreen() {
         return this.screen;
     }
+    getIdentity() {
+        return { ...this.identity };
+    }
+    getRecentEvents() {
+        return [...this.recentEvents];
+    }
     getAvailableActions() {
         return [...this.actions.keys()];
     }
@@ -299,6 +305,7 @@ export class GraineInAppClient {
             this.scheduleScreen();
     }
     scheduleScreen() {
+        this.emit("screen", { screen: this.screen, actions: this.getAvailableActions() });
         if (this.contextTimer) {
             this.pendingScreen = true;
             return;

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-export type { ActionHandler, AppActionRequest, AppActionResult, AppEvent, ScreenContext, ScreenField, } from "./protocol";
-export { GraineInAppClient, type GraineInAppOptions, type SessionConfig } from "./client";
-export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, type AudioAdapter, type VoiceSessionOptions, } from "./voice";
-export { EchoGuard, decodeAgentAudio, decodeMuLaw, decodePcm16, base64ToBytes, type AudioFormat, type DecodedAudio, } from "./audio";
-export { addMaskRule, maskDeep, maskString } from "./mask";
-export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, type GraineEvent, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index";
-export { GraineAgentBar, GraineLauncher, type GraineAgentBarProps, type GraineLauncherProps, type GraineBarTheme, } from "./react-native/ui";
-export { GraineVoiceLauncher, type GraineVoiceLauncherProps, type GraineVoiceApi, } from "./react-native/voice-launcher";
-export { LauncherVisibilityTracker, activeRouteName, type LauncherInset, type LauncherContinuity, type LauncherDelayPolicy, type LauncherGroup, type LauncherVisibility, type VisibilityDecision, } from "./react-native/navigation";
+export type { ActionHandler, AppActionRequest, AppActionResult, AppEvent, ScreenContext, ScreenField, } from "./protocol.js";
+export { GraineInAppClient, type GraineInAppOptions, type SessionConfig } 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, type GraineEvent, type GraineProviderProps, type Turn, type Caption, } from "./react-native/index.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 { LauncherVisibilityTracker, activeRouteName, type LauncherInset, type LauncherContinuity, type LauncherDelayPolicy, type LauncherGroup, type LauncherVisibility, type VisibilityDecision, } from "./react-native/navigation.js";

package/dist/index.js

@@ -1,8 +1,9 @@
-export { GraineInAppClient } from "./client";
-export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, } from "./voice";
-export { EchoGuard, decodeAgentAudio, decodeMuLaw, decodePcm16, base64ToBytes, } from "./audio";
-export { addMaskRule, maskDeep, maskString } from "./mask";
-export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, useGraineIdentify, useGraineEvents, useGraineTrack, useGraineTap, } from "./react-native/index";
-export { GraineAgentBar, GraineLauncher, } from "./react-native/ui";
-export { GraineVoiceLauncher, } from "./react-native/voice-launcher";
-export { LauncherVisibilityTracker, activeRouteName, } from "./react-native/navigation";
+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, } from "./react-native/index.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 { LauncherVisibilityTracker, activeRouteName, } from "./react-native/navigation.js";

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

@@ -1,8 +1,8 @@
 import React from "react";
-import { GraineInAppClient, type GraineInAppOptions } from "../client";
-import { type AudioAdapter, type VoiceSessionOptions } from "../voice";
-import type { ActionHandler, ScreenContext } from "../protocol";
-import { type LauncherInset, type LauncherVisibility } from "./navigation";
+import { GraineInAppClient, type GraineInAppOptions } from "../client.js";
+import { type AudioAdapter, type VoiceSessionOptions } from "../voice.js";
+import type { ActionHandler, ScreenContext } from "../protocol.js";
+import { type LauncherInset, type LauncherVisibility } from "./navigation.js";
 interface GraineContextValue {
     client: GraineInAppClient;
     connected: boolean;

package/dist/react-native/index.js

@@ -1,9 +1,9 @@
 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";
+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, ...options }) {
     const clientRef = useRef(null);

package/dist/react-native/ui.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { ActivityIndicator, Image, KeyboardAvoidingView, Platform, Pressable, ScrollView, StyleSheet, Text, TextInput, useColorScheme, View, } from "react-native";
-import { useGraineAgent } from "./index";
+import { useGraineAgent } from "./index.js";
 const DARK = {
     surface: "#17161A",
     border: "rgba(255,255,255,0.09)",

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

@@ -1,10 +1,11 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { AppState, View } from "react-native";
-import { useGraineAgent } from "./index";
+import { useGraineAgent } from "./index.js";
 export function GraineVoiceLauncher({ webView: WebView, autoStart = false, onCaption, onCallState, onMicDenied, onEnded, children, }) {
     const { client, appearance } = useGraineAgent();
     const ref = useRef(null);
+    const startedRef = useRef(false);
     const [connected, setConnected] = useState(false);
     const [connecting, setConnecting] = useState(false);
     const [muted, setMutedState] = useState(false);
@@ -40,12 +41,16 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, onCap
             case "graine:ready":
                 setReady(true);
                 pushContext();
-                if (autoStart)
+                if (autoStart && !startedRef.current) {
+                    startedRef.current = true;
                     post({ type: "graine:start-call" });
+                }
                 return;
             case "graine:call":
                 setConnected(!!msg.connected);
                 setConnecting(!!msg.connecting);
+                if (!msg.connected && !msg.connecting)
+                    startedRef.current = false;
                 onCallState?.({ connected: !!msg.connected, connecting: !!msg.connecting });
                 return;
             case "graine:muted":
@@ -93,13 +98,28 @@ export function GraineVoiceLauncher({ webView: WebView, autoStart = false, onCap
     useEffect(() => () => { post({ type: "graine:end-call" }); }, [post]);
     useEffect(() => {
         let last = AppState.currentState;
+        let pending = null;
+        const CONFIRM_MS = 2000;
         const sub = AppState.addEventListener("change", (next) => {
             const wasActive = last === "active";
             last = next;
-            if (next === "background" && wasActive)
-                post({ type: "graine:end-call" });
+            if (next === "active") {
+                if (pending) {
+                    clearTimeout(pending);
+                    pending = null;
+                }
+                return;
+            }
+            if (next === "background" && wasActive && !pending) {
+                pending = setTimeout(() => {
+                    pending = null;
+                    if (AppState.currentState !== "active")
+                        post({ type: "graine:end-call" });
+                }, CONFIRM_MS);
+            }
         });
-        return () => sub.remove();
+        return () => { if (pending)
+            clearTimeout(pending); sub.remove(); };
     }, [post]);
     const agentId = client.config?.agentId;
     if (!agentId)

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

@@ -0,0 +1,41 @@
+export type RtcVoiceState = "idle" | "connecting" | "ringing" | "active" | "ended";
+export type RtcVoiceErrorCode = "mint_failed" | "microphone_denied" | "connect_failed" | "already_active";
+export declare class RtcVoiceError extends Error {
+    readonly code: RtcVoiceErrorCode;
+    readonly cause?: unknown;
+    constructor(code: RtcVoiceErrorCode, message: string, cause?: unknown);
+}
+export interface RtcVoiceSession {
+    server: string;
+    username: string;
+    password: string;
+    realm: string;
+    application_sid: string;
+    agent_id?: string;
+    expires_at?: string;
+}
+export interface RtcVoiceOptions {
+    publishableKey?: string;
+    baseUrl?: string;
+    getSession?: () => Promise<RtcVoiceSession>;
+    onState?: (s: RtcVoiceState) => void;
+    onEnded?: (reason: string) => void;
+    onLog?: (line: string) => void;
+    sessionId?: string;
+}
+export declare class RtcVoiceSessionController {
+    private client;
+    private call;
+    private state;
+    private startToken;
+    readonly sessionId: string;
+    private opts;
+    constructor(opts: RtcVoiceOptions);
+    getState(): RtcVoiceState;
+    private set;
+    private log;
+    private mint;
+    start(): Promise<void>;
+    setMuted(muted: boolean): void;
+    stop(): Promise<void>;
+}

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

@@ -0,0 +1,143 @@
+export class RtcVoiceError extends Error {
+    constructor(code, message, cause) {
+        super(message);
+        this.name = "RtcVoiceError";
+        this.code = code;
+        this.cause = cause;
+    }
+}
+function newSessionId() {
+    return `${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 10)}`;
+}
+export class RtcVoiceSessionController {
+    constructor(opts) {
+        this.client = null;
+        this.call = null;
+        this.state = "idle";
+        this.startToken = null;
+        this.opts = opts;
+        this.sessionId = opts.sessionId || newSessionId();
+    }
+    getState() {
+        return this.state;
+    }
+    set(s) {
+        this.state = s;
+        this.opts.onState?.(s);
+    }
+    log(l) {
+        this.opts.onLog?.(l);
+    }
+    async mint() {
+        if (this.opts.getSession)
+            return this.opts.getSession();
+        if (!this.opts.publishableKey) {
+            throw new RtcVoiceError("mint_failed", "Pass publishableKey (or getSession for a custom backend).");
+        }
+        const base = (this.opts.baseUrl || "https://www.graine.ai").replace(/\/$/, "");
+        let res;
+        try {
+            res = await fetch(`${base}/api/embed/rtc-session`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ publishableKey: this.opts.publishableKey }),
+            });
+        }
+        catch (e) {
+            throw new RtcVoiceError("mint_failed", "Could not reach the call service.", e);
+        }
+        if (!res.ok) {
+            let detail = "";
+            try {
+                detail = (await res.json())?.error || "";
+            }
+            catch {
+            }
+            throw new RtcVoiceError("mint_failed", detail || `Could not start a call (${res.status}).`);
+        }
+        return res.json();
+    }
+    async start() {
+        if (this.state !== "idle" && this.state !== "ended") {
+            throw new RtcVoiceError("already_active", "A call is already in progress.");
+        }
+        const token = (this.startToken = Symbol("start"));
+        this.set("connecting");
+        try {
+            const session = await this.mint();
+            if (token !== this.startToken)
+                return;
+            this.log(`session for ${session.realm}`);
+            const { createJambonzClient } = await import("@jambonz/client-sdk-react-native");
+            this.client = createJambonzClient({
+                server: session.server,
+                username: session.username,
+                password: session.password,
+                realm: session.realm,
+            });
+            this.client.on("error", (e) => this.log(`client error: ${e?.message ?? e}`));
+            await this.client.connect();
+            if (token !== this.startToken) {
+                await this.stop();
+                return;
+            }
+            this.log("registered");
+            this.call = this.client.callApplication(session.application_sid, {
+                headers: {
+                    "X-Graine-Session-Id": this.sessionId,
+                    ...(session.agent_id ? { "X-Graine-Agent-Id": session.agent_id } : {}),
+                },
+            });
+            this.call.on("stateChanged", (s) => this.log(`call: ${s}`));
+            this.call.on("accepted", () => {
+                this.set("active");
+                this.log("audio flowing");
+            });
+            this.call.on("ended", (c) => {
+                this.set("ended");
+                this.opts.onEnded?.(c?.reason || "ended");
+            });
+            this.call.on("failed", (c) => {
+                this.set("ended");
+                this.opts.onEnded?.(c?.reason || "failed");
+            });
+            this.set("ringing");
+        }
+        catch (err) {
+            if (token !== this.startToken)
+                return;
+            this.set("ended");
+            throw err instanceof RtcVoiceError
+                ? err
+                : new RtcVoiceError("connect_failed", err?.message || "Could not connect.", err);
+        }
+    }
+    setMuted(muted) {
+        try {
+            if (muted)
+                this.call?.mute?.();
+            else
+                this.call?.unmute?.();
+        }
+        catch {
+        }
+    }
+    async stop() {
+        if (this.state === "idle" || this.state === "ended")
+            return;
+        this.startToken = null;
+        try {
+            this.call?.hangup?.();
+        }
+        catch {
+        }
+        try {
+            await this.client?.disconnect?.();
+        }
+        catch {
+        }
+        this.call = null;
+        this.client = null;
+        this.set("ended");
+    }
+}

package/dist/voice.d.ts

@@ -1,4 +1,4 @@
-import type { GraineInAppClient } from "./client";
+import type { GraineInAppClient } from "./client.js";
 export declare const CAPTURE_SAMPLE_RATE = 16000;
 export declare const MIN_PLAYOUT_BUFFER_SECONDS = 0.15;
 export interface AudioAdapter {

package/dist/voice.js

@@ -1,4 +1,4 @@
-import { EchoGuard, base64ToBytes, decodeAgentAudio, decodePcm16 } from "./audio";
+import { EchoGuard, base64ToBytes, decodeAgentAudio, decodePcm16 } from "./audio.js";
 export const CAPTURE_SAMPLE_RATE = 16000;
 export const MIN_PLAYOUT_BUFFER_SECONDS = 0.15;
 export function base64ToPcm16(b64) {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@graineai/inapp-react-native",
-  "version": "0.12.0",
+  "version": "0.15.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",
   "private": false,
@@ -35,7 +36,8 @@
   },
   "peerDependencies": {
     "react": ">=17",
-    "react-native": ">=0.68"
+    "react-native": ">=0.68",
+    "@jambonz/client-sdk-react-native": "^0.1.4"
   },
   "devDependencies": {
     "@types/react": "^18.2.0",
@@ -60,5 +62,10 @@
   "homepage": "https://www.graine.ai/docs/in-app",
   "bugs": {
     "url": "https://www.graine.ai/docs/in-app"
+  },
+  "peerDependenciesMeta": {
+    "@jambonz/client-sdk-react-native": {
+      "optional": true
+    }
   }
 }