@graineai/inapp-react-native 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Graine AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @graineai/inapp-react-native
+
+A Graine AI agent that runs **inside** your React Native app — it sees the
+screen your customer is on, and can act on it.
+
+Android and iOS from one package.
+
+```bash
+npm install @graineai/inapp-react-native
+```
+
+Full documentation: **https://app.graine.ai/docs/in-app**
+
+---
+
+## Quick start
+
+```tsx
+import { GraineProvider, GraineLauncher } from "@graineai/inapp-react-native";
+
+export default function App() {
+  return (
+    <GraineProvider
+      baseUrl="https://app.graine.ai"
+      publishableKey="pk_live_…"
+      variables={{ customer_name: user.firstName }}
+    >
+      <RootNavigator />
+      <GraineLauncher accent="#318CE7" title="Assistant" />
+    </GraineProvider>
+  );
+}
+```
+
+Your publishable key is in the Graine dashboard under **Install & domains**.
+
+## Tell the agent what the customer can see
+
+One hook, beside the state your screen already holds:
+
+```tsx
+useGraineScreen({
+  screen: "kyc_pan",
+  title: "PAN verification",
+  journey: { name: "KYC", step: 2, of: 4 },
+  fields: [
+    { name: "pan", label: "PAN Number", value: pan,
+      status: error ? "invalid" : pan ? "filled" : "empty", error },
+  ],
+});
+```
+
+The description is withdrawn when the component unmounts, so the agent can never
+discuss a screen the customer has left.
+
+## Let the agent act
+
+Declare the action on your agent in the dashboard, then implement it where it
+belongs:
+
+```tsx
+useGraineAction("fill_pan_from_aadhaar", async () => {
+  const value = await lookupPanFromAadhaar();
+  setPan(value);
+  return { status: "ok", data: { pan: value } };
+});
+```
+
+Answer honestly — `ok` makes the agent tell the customer the change is done.
+A refusal with a reason is often more useful:
+
+```tsx
+return { status: "refused", message: "PAN is locked after submission." };
+```
+
+Answer within about five seconds. For slower work, return immediately and report
+the outcome through the next `useGraineScreen` update.
+
+## Voice
+
+```tsx
+<GraineProvider baseUrl="…" publishableKey="pk_live_…" voice>
+```
+
+```tsx
+const { listening, start, stop } = useGraineVoice(adapter, {
+  onTranscript: (text, final) => final && setHeard(text),
+});
+```
+
+Audio is a pluggable four-method `AudioAdapter`, so this package never forces a
+particular native audio module into your build. `liveAudioStreamAdapter` wraps
+`react-native-live-audio-stream`.
+
+Capture must be **16 kHz mono PCM16**. Interruption is handled for you.
+
+## Privacy
+
+Identifiers are masked on the device before any screen data is sent — PAN,
+Aadhaar, card and account numbers, phone numbers and email addresses. The agent
+is told whether a field is filled, empty or rejected, not what is in it.
+
+Add your own formats once, at startup:
+
+```ts
+import { addMaskRule } from "@graineai/inapp-react-native/mask";
+
+addMaskRule(/POL-\d{6}/, "[POLICY]");
+```
+
+The SDK never reads the screen by itself — it reports only the fields you pass
+to `useGraineScreen`. There is no screen recording and no accessibility
+scraping. It never opens the microphone until you call `start()`, and never
+requests a permission on your behalf.
+
+> **A publishable key inside a mobile app is public.** Anyone can extract it
+> from an APK or IPA, and the web domain allowlist does not apply to mobile
+> apps. Rate limits, single-use connection tickets and your account's credit
+> limits are what bound it. See the
+> [security notes](https://app.graine.ai/docs/in-app/privacy) before launch.
+
+## Requirements
+
+- React Native 0.68+
+- React 17+
+
+## API
+
+| | |
+|---|---|
+| `GraineProvider` | Connects the agent. Set `voice` for spoken conversations. |
+| `useGraineAgent()` | Connection state, transcript, and `send()`. |
+| `useGraineScreen(context)` | Report what this screen shows. |
+| `useGraineAction(name, handler)` | Implement one action the agent may call. |
+| `useGraineVoice(adapter, opts)` | Microphone, playback and barge-in. |
+| `GraineLauncher` | Optional default UI. Replace it with your own. |
+| `addMaskRule(pattern, token)` | Mask an app-specific identifier format. |
+
+`GraineInAppClient` is exported for apps that want the transport without the
+React layer.
+
+## Support
+
+https://app.graine.ai/docs/in-app
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,64 @@
+import { type ActionHandler, type AppEvent, type ScreenContext } from "./protocol";
+export declare const SUBPROTOCOL = "graine.embed.v1";
+export interface GraineInAppOptions {
+    baseUrl: string;
+    publishableKey: string;
+    variables?: Record<string, string>;
+    stallAfterMs?: number;
+    voice?: boolean;
+    WebSocketImpl?: any;
+    fetchImpl?: typeof fetch;
+}
+type Listener = (payload: any) => void;
+export interface SessionConfig {
+    agentId: string;
+    webcallAgentId?: string;
+    wsHost?: string;
+    appearance?: Record<string, any>;
+    variables?: Record<string, string>;
+    components?: any[];
+}
+export declare class GraineInAppClient {
+    readonly opts: GraineInAppOptions;
+    config: SessionConfig | null;
+    transport: "gateway" | "direct" | null;
+    private ws;
+    private listeners;
+    private actions;
+    private screen;
+    private screenSeq;
+    private screenSince;
+    private contextTimer;
+    private pendingScreen;
+    private stallTimer;
+    private stallReportedFor;
+    private pingTimer;
+    private agentSpeaking;
+    private bargedIn;
+    constructor(opts: GraineInAppOptions);
+    on(event: string, fn: Listener): () => void;
+    private emit;
+    private get fetch();
+    session(): Promise<SessionConfig>;
+    private ticket;
+    connect(): Promise<void>;
+    private send;
+    private onFrame;
+    private runAction;
+    registerAction(name: string, handler: ActionHandler): () => void;
+    get availableActions(): string[];
+    setScreen(context: ScreenContext | null): void;
+    reportEvent(event: AppEvent): void;
+    private scheduleScreen;
+    private flushScreen;
+    private armStall;
+    noteInteraction(): void;
+    say(text: string): boolean;
+    sendAudio(base64: string, sampleRate?: number): boolean;
+    endUtterance(): boolean;
+    get isAgentSpeaking(): boolean;
+    submitWidget(widgetId: string, data: Record<string, unknown>, summary: string): void;
+    private stopTimers;
+    close(): void;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,330 @@
+import { ACTION_DEADLINE_MS, CONTEXT_THROTTLE_MS, } from "./protocol";
+import { maskDeep } from "./mask";
+export const SUBPROTOCOL = "graine.embed.v1";
+const PING_MS = 25000;
+export class GraineInAppClient {
+    constructor(opts) {
+        this.config = null;
+        this.transport = null;
+        this.ws = null;
+        this.listeners = new Map();
+        this.actions = new Map();
+        this.screen = null;
+        this.screenSeq = 0;
+        this.screenSince = 0;
+        this.contextTimer = null;
+        this.pendingScreen = false;
+        this.stallTimer = null;
+        this.stallReportedFor = null;
+        this.pingTimer = null;
+        this.agentSpeaking = false;
+        this.bargedIn = false;
+        if (!opts?.publishableKey)
+            throw new Error("[Graine] publishableKey is required.");
+        if (!opts?.baseUrl)
+            throw new Error("[Graine] baseUrl is required.");
+        this.opts = { stallAfterMs: 45000, ...opts };
+    }
+    on(event, fn) {
+        if (!this.listeners.has(event))
+            this.listeners.set(event, new Set());
+        this.listeners.get(event).add(fn);
+        return () => this.listeners.get(event)?.delete(fn);
+    }
+    emit(event, payload) {
+        for (const fn of this.listeners.get(event) ?? []) {
+            try {
+                fn(payload);
+            }
+            catch (err) {
+                console.error(`[Graine] listener for "${event}" threw`, err);
+            }
+        }
+    }
+    get fetch() {
+        return this.opts.fetchImpl ?? globalThis.fetch;
+    }
+    async session() {
+        const res = await this.fetch(`${this.opts.baseUrl}/api/embed/session`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ publishableKey: this.opts.publishableKey }),
+        });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok)
+            throw new Error(data?.error || `Embed rejected (${res.status})`);
+        this.config = data;
+        return this.config;
+    }
+    async ticket() {
+        try {
+            const res = await this.fetch(`${this.opts.baseUrl}/api/embed/ticket`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ publishableKey: this.opts.publishableKey }),
+            });
+            if (!res.ok)
+                return null;
+            return await res.json();
+        }
+        catch {
+            return null;
+        }
+    }
+    async connect() {
+        if (!this.config)
+            await this.session();
+        const agentId = this.config.webcallAgentId || this.config.agentId;
+        const t = await this.ticket();
+        let url;
+        let protocols;
+        if (t?.wsUrl && t.ticket) {
+            url = t.wsUrl;
+            protocols = [SUBPROTOCOL, t.ticket];
+            this.transport = "gateway";
+        }
+        else {
+            const host = (this.config.wsHost || "wss://ws.graine.ai").replace(/\/$/, "");
+            const mode = this.opts.voice ? "webcall=1" : "text_chat=1";
+            url = `${host}/chat/v1/${encodeURIComponent(agentId)}?${mode}`;
+            this.transport = "direct";
+        }
+        const WS = this.opts.WebSocketImpl ?? globalThis.WebSocket;
+        const ws = new WS(url, protocols);
+        this.ws = ws;
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("Socket did not open in time")), 15000);
+            ws.onopen = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            ws.onerror = (e) => {
+                clearTimeout(timer);
+                reject(new Error(e?.message || "Socket error"));
+            };
+        });
+        ws.onmessage = (evt) => this.onFrame(evt);
+        ws.onclose = (e) => {
+            this.stopTimers();
+            this.emit("close", { code: e?.code, reason: e?.reason });
+        };
+        this.send({
+            type: "init",
+            meta_data: { context_data: { ...(this.config.variables ?? {}), ...(this.opts.variables ?? {}) } },
+        });
+        this.pingTimer = setInterval(() => this.send({ type: "ping" }), PING_MS);
+        if (this.screen)
+            this.flushScreen();
+        this.emit("open", { transport: this.transport });
+    }
+    send(obj) {
+        if (!this.ws || this.ws.readyState !== 1)
+            return false;
+        try {
+            this.ws.send(JSON.stringify(obj));
+            return true;
+        }
+        catch (err) {
+            console.error("[Graine] send failed", err);
+            return false;
+        }
+    }
+    onFrame(evt) {
+        let msg;
+        try {
+            msg = JSON.parse(typeof evt?.data === "string" ? evt.data : String(evt?.data));
+        }
+        catch {
+            return;
+        }
+        switch (msg.type) {
+            case "text":
+                this.emit("chunk", msg.data);
+                break;
+            case "widget":
+                this.emit("widget", msg.widget);
+                break;
+            case "app_action":
+                void this.runAction(msg.action);
+                break;
+            case "audio":
+                this.emit("audio", {
+                    data: msg.data,
+                    sampleRate: msg.meta_info?.sample_rate ?? 16000,
+                });
+                break;
+            case "beginning_of_stream":
+                this.agentSpeaking = true;
+                this.emit("agent_speaking", true);
+                break;
+            case "end_of_stream":
+                this.agentSpeaking = false;
+                this.emit("agent_speaking", false);
+                break;
+            case "clear":
+            case "interruption":
+                this.agentSpeaking = false;
+                this.emit("clear");
+                break;
+            case "interim_transcript_received":
+                this.emit("transcript", { text: msg.data ?? "", final: false });
+                break;
+            case "transcript":
+                this.emit("transcript", { text: msg.data ?? "", final: true });
+                break;
+            case "pong":
+            case "ack":
+                break;
+            default:
+                this.emit("frame", msg);
+        }
+    }
+    async runAction(request) {
+        const reply = (result) => this.send({ type: "app_action_result", action_id: request.action_id, ...result });
+        const handler = this.actions.get(request.name);
+        if (!handler) {
+            reply({
+                status: "refused",
+                message: `This app build does not implement "${request.name}".`,
+            });
+            return;
+        }
+        this.emit("action", request);
+        try {
+            const result = await Promise.race([
+                Promise.resolve(handler(request.arguments ?? {})),
+                new Promise((_, rej) => setTimeout(() => rej(new Error("handler_timeout")), ACTION_DEADLINE_MS - 500)),
+            ]);
+            reply(result && typeof result === "object" ? result : { status: "ok" });
+        }
+        catch (err) {
+            const timedOut = err?.message === "handler_timeout";
+            if (!timedOut)
+                console.error(`[Graine] action "${request.name}" threw`, err);
+            reply({
+                status: "error",
+                message: timedOut
+                    ? `"${request.name}" did not finish in time.`
+                    : `"${request.name}" failed: ${err?.message ?? "unknown error"}`,
+            });
+        }
+    }
+    registerAction(name, handler) {
+        this.actions.set(name, handler);
+        this.scheduleScreen();
+        return () => {
+            this.actions.delete(name);
+            this.scheduleScreen();
+        };
+    }
+    get availableActions() {
+        return [...this.actions.keys()];
+    }
+    setScreen(context) {
+        const changedScreen = context?.screen !== this.screen?.screen;
+        this.screen = context;
+        if (changedScreen) {
+            this.screenSince = Date.now();
+            this.stallReportedFor = null;
+            this.armStall();
+        }
+        this.scheduleScreen();
+    }
+    reportEvent(event) {
+        this.send({ type: "app_event", event });
+    }
+    scheduleScreen() {
+        if (this.contextTimer) {
+            this.pendingScreen = true;
+            return;
+        }
+        if (!this.flushScreen())
+            return;
+        this.contextTimer = setTimeout(() => {
+            this.contextTimer = null;
+            if (this.pendingScreen) {
+                this.pendingScreen = false;
+                this.scheduleScreen();
+            }
+        }, CONTEXT_THROTTLE_MS);
+    }
+    flushScreen() {
+        if (!this.screen)
+            return false;
+        const { availableActions, ...rest } = this.screen;
+        return this.send({
+            type: "app_context",
+            context: maskDeep({ ...rest, idle_ms: Date.now() - this.screenSince }),
+            available_actions: (availableActions ?? this.availableActions).filter((a) => this.actions.has(a)),
+            seq: ++this.screenSeq,
+        });
+    }
+    armStall() {
+        clearTimeout(this.stallTimer);
+        const after = this.opts.stallAfterMs ?? 0;
+        if (!after || !this.screen)
+            return;
+        const screenId = this.screen.screen;
+        this.stallTimer = setTimeout(() => {
+            if (this.stallReportedFor === screenId)
+                return;
+            this.stallReportedFor = screenId;
+            const title = this.screen?.title ?? screenId;
+            const stuck = (this.screen?.fields ?? []).find((f) => f.status === "invalid" || f.error || f.status === "empty");
+            this.reportEvent({
+                name: "stalled_on_step",
+                detail: stuck
+                    ? `The customer has not touched the "${title}" screen for ${Math.round(after / 1000)}s. ` +
+                        `The "${stuck.label ?? stuck.name}" field is ${stuck.error ? `showing: ${stuck.error}` : stuck.status}.`
+                    : `The customer has not touched the "${title}" screen for ${Math.round(after / 1000)}s.`,
+            });
+        }, after);
+    }
+    noteInteraction() {
+        this.screenSince = Date.now();
+        this.armStall();
+    }
+    say(text) {
+        return this.send({ type: "text", data: text });
+    }
+    sendAudio(base64, sampleRate = 16000) {
+        if (this.agentSpeaking && !this.bargedIn) {
+            this.bargedIn = true;
+            this.send({ type: "barge_in" });
+        }
+        else if (!this.agentSpeaking) {
+            this.bargedIn = false;
+        }
+        return this.send({
+            type: "audio",
+            data: base64,
+            meta_info: { format: "pcm", sample_rate: sampleRate, encoding: "base64" },
+        });
+    }
+    endUtterance() {
+        return this.send({ type: "utterance_end" });
+    }
+    get isAgentSpeaking() {
+        return this.agentSpeaking;
+    }
+    submitWidget(widgetId, data, summary) {
+        this.send({ type: "widget_result", widget_id: widgetId, data });
+        if (summary)
+            this.say(summary);
+    }
+    stopTimers() {
+        clearInterval(this.pingTimer);
+        clearTimeout(this.stallTimer);
+        clearTimeout(this.contextTimer);
+        this.pingTimer = this.stallTimer = this.contextTimer = null;
+    }
+    close() {
+        this.stopTimers();
+        try {
+            this.ws?.close();
+        }
+        catch {
+        }
+        this.ws = null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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 { addMaskRule, maskDeep, maskString } from "./mask";
+export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, type GraineProviderProps, type Turn, } from "./react-native/index";
+export { GraineLauncher, type GraineLauncherProps } from "./react-native/ui";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { GraineInAppClient } from "./client";
+export { VoiceSession, liveAudioStreamAdapter, base64ToPcm16, CAPTURE_SAMPLE_RATE, } from "./voice";
+export { addMaskRule, maskDeep, maskString } from "./mask";
+export { GraineProvider, useGraineAgent, useGraineScreen, useGraineAction, useGraineVoice, } from "./react-native/index";
+export { GraineLauncher } from "./react-native/ui";

package/dist/mask.d.ts

@@ -0,0 +1,4 @@
+export declare function maskString(input: string): string;
+export declare function addMaskRule(pattern: RegExp, token?: string): void;
+export declare function clearMaskRules(): void;
+export declare function maskDeep<T>(value: T): T;

package/dist/mask.js

@@ -0,0 +1,38 @@
+const MASKS = [
+    [/\b[A-Z]{5}[0-9]{4}[A-Z]\b/g, "[PAN]"],
+    [/[\w.+-]+@[\w-]+\.[\w.]{2,}/g, "[EMAIL]"],
+    [/(^|[^\d-])((?:\d[ -]?){13,19})(?![\d-])/g, "$1[CARD]"],
+    [/(^|[^\d+])((?:\+91[-\s]?)?[6-9]\d{9})(?!\d)/g, "$1[PHONE]"],
+    [/(^|[^\d+])(\d{4}\s?\d{4}\s?\d{4})(?!\d)/g, "$1[AADHAAR]"],
+];
+export function maskString(input) {
+    let out = input;
+    for (const [pattern, token] of MASKS)
+        out = out.replace(pattern, token);
+    return out;
+}
+const custom = [];
+export function addMaskRule(pattern, token = "[REDACTED]") {
+    const flags = pattern.flags.includes("g") ? pattern.flags : pattern.flags + "g";
+    custom.push([new RegExp(pattern.source, flags), token]);
+}
+export function clearMaskRules() {
+    custom.length = 0;
+}
+export function maskDeep(value) {
+    if (typeof value === "string") {
+        let out = maskString(value);
+        for (const [pattern, token] of custom)
+            out = out.replace(pattern, token);
+        return out;
+    }
+    if (Array.isArray(value))
+        return value.map(maskDeep);
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = maskDeep(v);
+        return out;
+    }
+    return value;
+}

package/dist/protocol.d.ts

@@ -0,0 +1,60 @@
+export interface ScreenField {
+    name: string;
+    label?: string;
+    value?: string | number | null;
+    status?: "empty" | "filled" | "invalid" | "pending" | "locked";
+    error?: string;
+}
+export interface ScreenContext {
+    screen: string;
+    title?: string;
+    journey?: {
+        name: string;
+        step?: number;
+        of?: number;
+    };
+    fields?: ScreenField[];
+    error?: string;
+    data?: Record<string, unknown>;
+    availableActions?: string[];
+}
+export interface AppContextFrame {
+    type: "app_context";
+    context: ScreenContext & {
+        idle_ms?: number;
+    };
+    available_actions?: string[];
+    seq: number;
+}
+export interface AppEvent {
+    name: string;
+    detail?: string;
+    cooldown_seconds?: number;
+    max_per_session?: number;
+}
+export interface AppEventFrame {
+    type: "app_event";
+    event: AppEvent;
+}
+export interface AppActionRequest {
+    action_id: string;
+    name: string;
+    kind?: string;
+    arguments: Record<string, unknown>;
+}
+export interface AppActionFrame {
+    type: "app_action";
+    action: AppActionRequest;
+}
+export interface AppActionResult {
+    status: "ok" | "error" | "refused";
+    data?: Record<string, unknown>;
+    message?: string;
+}
+export interface AppActionResultFrame extends AppActionResult {
+    type: "app_action_result";
+    action_id: string;
+}
+export type ActionHandler = (args: Record<string, any>) => AppActionResult | void | Promise<AppActionResult | void>;
+export declare const ACTION_DEADLINE_MS = 6000;
+export declare const CONTEXT_THROTTLE_MS = 400;

package/dist/protocol.js

@@ -0,0 +1,2 @@
+export const ACTION_DEADLINE_MS = 6000;
+export const CONTEXT_THROTTLE_MS = 400;

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

@@ -0,0 +1,36 @@
+import React from "react";
+import { GraineInAppClient, type GraineInAppOptions } from "../client";
+import { type AudioAdapter, type VoiceSessionOptions } from "../voice";
+import type { ActionHandler, ScreenContext } from "../protocol";
+interface GraineContextValue {
+    client: GraineInAppClient;
+    connected: boolean;
+    connecting: boolean;
+    error: string | null;
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    messages: Turn[];
+    widgets: any[];
+    send: (text: string) => void;
+}
+export interface Turn {
+    role: "agent" | "customer";
+    text: string;
+    live?: boolean;
+}
+export interface GraineProviderProps extends GraineInAppOptions {
+    children: React.ReactNode;
+    autoConnect?: boolean;
+    onProactive?: (text: string) => void;
+}
+export declare function GraineProvider({ children, autoConnect, onProactive, ...options }: GraineProviderProps): React.JSX.Element;
+export declare function useGraineAgent(): GraineContextValue;
+export declare function useGraineVoice(adapter: AudioAdapter | null, options?: VoiceSessionOptions): {
+    listening: boolean;
+    agentSpeaking: boolean;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+};
+export declare function useGraineScreen(context: ScreenContext | null): void;
+export declare function useGraineAction(name: string, handler: ActionHandler): void;
+export {};

package/dist/react-native/index.js

@@ -0,0 +1,132 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { GraineInAppClient } from "../client";
+import { VoiceSession } from "../voice";
+const Ctx = createContext(null);
+export function GraineProvider({ children, autoConnect = true, onProactive, ...options }) {
+    const clientRef = useRef(null);
+    if (!clientRef.current)
+        clientRef.current = new GraineInAppClient(options);
+    const client = clientRef.current;
+    const [connected, setConnected] = useState(false);
+    const [connecting, setConnecting] = useState(false);
+    const [error, setError] = useState(null);
+    const [open, setOpen] = useState(false);
+    const [messages, setMessages] = useState([]);
+    const [widgets, setWidgets] = useState([]);
+    const proactiveRef = useRef(onProactive);
+    proactiveRef.current = onProactive;
+    const openRef = useRef(open);
+    openRef.current = open;
+    useEffect(() => {
+        const offs = [
+            client.on("open", () => {
+                setConnected(true);
+                setConnecting(false);
+                setError(null);
+            }),
+            client.on("close", () => setConnected(false)),
+            client.on("chunk", (text) => setMessages((prev) => {
+                const last = prev[prev.length - 1];
+                if (last?.role === "agent" && last.live) {
+                    return [...prev.slice(0, -1), { ...last, text: last.text + text }];
+                }
+                if (prev[prev.length - 1]?.role !== "customer") {
+                    proactiveRef.current?.(text);
+                    if (!openRef.current)
+                        setOpen(true);
+                }
+                return [...prev, { role: "agent", text, live: true }];
+            })),
+            client.on("widget", (widget) => setWidgets((prev) => [...prev, widget])),
+        ];
+        if (autoConnect) {
+            setConnecting(true);
+            client.connect().catch((err) => {
+                setConnecting(false);
+                console.error("[Graine]", err?.message ?? err);
+                setError(err?.message ?? "Could not start the agent.");
+            });
+        }
+        return () => {
+            offs.forEach((off) => off());
+            client.close();
+        };
+    }, [client, autoConnect]);
+    const value = useMemo(() => ({
+        client,
+        connected,
+        connecting,
+        error,
+        open,
+        setOpen,
+        messages,
+        widgets,
+        send: (text) => {
+            if (!text.trim())
+                return;
+            setMessages((prev) => [
+                ...prev.map((m) => (m.live ? { ...m, live: false } : m)),
+                { role: "customer", text },
+            ]);
+            client.noteInteraction();
+            client.say(text);
+        },
+    }), [client, connected, connecting, error, open, messages, widgets]);
+    return _jsx(Ctx.Provider, { value: value, children: children });
+}
+function useGraine() {
+    const ctx = useContext(Ctx);
+    if (!ctx)
+        throw new Error("[Graine] useGraine* must be used inside <GraineProvider>.");
+    return ctx;
+}
+export function useGraineAgent() {
+    return useGraine();
+}
+export function useGraineVoice(adapter, options = {}) {
+    const { client } = useGraine();
+    const [listening, setListening] = useState(false);
+    const [agentSpeaking, setAgentSpeaking] = useState(false);
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const sessionRef = useRef(null);
+    if (adapter && !sessionRef.current) {
+        sessionRef.current = new VoiceSession(client, adapter, {
+            onTranscript: (t, f) => optionsRef.current.onTranscript?.(t, f),
+            onAgentSpeaking: (speaking) => {
+                setAgentSpeaking(speaking);
+                optionsRef.current.onAgentSpeaking?.(speaking);
+            },
+        });
+    }
+    useEffect(() => () => { void sessionRef.current?.stop(); }, []);
+    return {
+        listening,
+        agentSpeaking,
+        start: async () => {
+            if (!sessionRef.current)
+                throw new Error("[Graine] useGraineVoice needs an audio adapter.");
+            await sessionRef.current.start();
+            setListening(true);
+        },
+        stop: async () => {
+            await sessionRef.current?.stop();
+            setListening(false);
+        },
+    };
+}
+export function useGraineScreen(context) {
+    const { client } = useGraine();
+    const serialised = JSON.stringify(context ?? null);
+    useEffect(() => {
+        client.setScreen(context);
+        return () => client.setScreen(null);
+    }, [client, serialised]);
+}
+export function useGraineAction(name, handler) {
+    const { client } = useGraine();
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    useEffect(() => client.registerAction(name, (args) => handlerRef.current(args)), [client, name]);
+}

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

@@ -0,0 +1,7 @@
+import React from "react";
+export interface GraineLauncherProps {
+    accent?: string;
+    title?: string;
+    bottom?: number;
+}
+export declare function GraineLauncher({ accent, title, bottom, }: GraineLauncherProps): React.JSX.Element | null;

package/dist/react-native/ui.js

@@ -0,0 +1,125 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { ActivityIndicator, Animated, Easing, KeyboardAvoidingView, Platform, Pressable, ScrollView, StyleSheet, Text, TextInput, View, } from "react-native";
+import { useGraineAgent } from "./index";
+export function GraineLauncher({ accent = "#318CE7", title = "Assistant", bottom = 24, }) {
+    const { connected, connecting, error, open, setOpen, messages, send } = useGraineAgent();
+    const [draft, setDraft] = useState("");
+    const scrollRef = useRef(null);
+    const [unread, setUnread] = useState(0);
+    useEffect(() => {
+        if (!open && messages[messages.length - 1]?.role === "agent")
+            setUnread((n) => n + 1);
+        if (open)
+            setUnread(0);
+    }, [messages, open]);
+    useEffect(() => {
+        if (open)
+            requestAnimationFrame(() => scrollRef.current?.scrollToEnd({ animated: true }));
+    }, [messages, open]);
+    const slide = useRef(new Animated.Value(0)).current;
+    useEffect(() => {
+        Animated.timing(slide, {
+            toValue: open ? 1 : 0,
+            duration: 180,
+            easing: Easing.out(Easing.quad),
+            useNativeDriver: true,
+        }).start();
+    }, [open, slide]);
+    if (error)
+        return null;
+    const submit = () => {
+        const text = draft.trim();
+        if (!text)
+            return;
+        setDraft("");
+        send(text);
+    };
+    return (_jsxs(_Fragment, { children: [open && (_jsxs(Animated.View, { style: [
+                    styles.panel,
+                    {
+                        bottom: bottom + 68,
+                        opacity: slide,
+                        transform: [{ translateY: slide.interpolate({ inputRange: [0, 1], outputRange: [12, 0] }) }],
+                    },
+                ], children: [_jsxs(View, { style: [styles.header, { backgroundColor: accent }], children: [_jsx(Text, { style: styles.headerTitle, children: title }), _jsxs(View, { style: styles.headerRight, children: [connected ? _jsx(View, { style: styles.liveDot }) : connecting ? _jsx(ActivityIndicator, { size: "small", color: "#fff" }) : null, _jsx(Pressable, { onPress: () => setOpen(false), hitSlop: 12, accessibilityLabel: "Close assistant", children: _jsx(Text, { style: styles.close, children: "\u2715" }) })] })] }), _jsxs(ScrollView, { ref: scrollRef, style: styles.transcript, contentContainerStyle: styles.transcriptInner, children: [messages.length === 0 && (_jsx(Text, { style: styles.empty, children: "I can see what you're working on \u2014 ask me anything, or I'll step in if you get stuck." })), messages.map((m, i) => (_jsx(View, { style: [
+                                    styles.bubble,
+                                    m.role === "agent"
+                                        ? styles.agentBubble
+                                        : [styles.customerBubble, { backgroundColor: accent }],
+                                ], children: _jsx(Text, { style: m.role === "agent" ? styles.agentText : styles.customerText, children: m.text }) }, i)))] }), _jsx(KeyboardAvoidingView, { behavior: Platform.OS === "ios" ? "padding" : undefined, children: _jsxs(View, { style: styles.composer, children: [_jsx(TextInput, { style: styles.input, value: draft, onChangeText: setDraft, placeholder: "Type a message", placeholderTextColor: "#9aa0a6", onSubmitEditing: submit, returnKeyType: "send", blurOnSubmit: false }), _jsx(Pressable, { onPress: submit, disabled: !draft.trim(), style: [styles.sendButton, { backgroundColor: accent, opacity: draft.trim() ? 1 : 0.4 }], accessibilityLabel: "Send", children: _jsx(Text, { style: styles.sendLabel, children: "\u2191" }) })] }) })] })), _jsxs(Pressable, { onPress: () => setOpen(!open), style: [styles.launcher, { backgroundColor: accent, bottom }], accessibilityLabel: open ? "Close assistant" : "Open assistant", accessibilityRole: "button", children: [_jsx(Text, { style: styles.launcherIcon, children: open ? "✕" : "✦" }), !open && unread > 0 && _jsx(View, { style: styles.badge })] })] }));
+}
+const styles = StyleSheet.create({
+    launcher: {
+        position: "absolute",
+        right: 20,
+        width: 56,
+        height: 56,
+        borderRadius: 28,
+        alignItems: "center",
+        justifyContent: "center",
+        elevation: 8,
+        shadowColor: "#000",
+        shadowOpacity: 0.22,
+        shadowRadius: 10,
+        shadowOffset: { width: 0, height: 4 },
+    },
+    launcherIcon: { color: "#fff", fontSize: 22, lineHeight: 26 },
+    badge: {
+        position: "absolute",
+        top: 12,
+        right: 12,
+        width: 10,
+        height: 10,
+        borderRadius: 5,
+        backgroundColor: "#ff3b30",
+        borderWidth: 2,
+        borderColor: "#fff",
+    },
+    panel: {
+        position: "absolute",
+        right: 20,
+        left: 20,
+        maxHeight: 460,
+        backgroundColor: "#fff",
+        borderRadius: 18,
+        overflow: "hidden",
+        elevation: 12,
+        shadowColor: "#000",
+        shadowOpacity: 0.18,
+        shadowRadius: 24,
+        shadowOffset: { width: 0, height: 10 },
+    },
+    header: { flexDirection: "row", alignItems: "center", justifyContent: "space-between", padding: 14 },
+    headerTitle: { color: "#fff", fontWeight: "600", fontSize: 15 },
+    headerRight: { flexDirection: "row", alignItems: "center", gap: 12 },
+    liveDot: { width: 8, height: 8, borderRadius: 4, backgroundColor: "#34d399" },
+    close: { color: "#fff", fontSize: 16 },
+    transcript: { maxHeight: 320 },
+    transcriptInner: { padding: 12, gap: 8 },
+    empty: { color: "#9aa0a6", fontSize: 13, lineHeight: 19, padding: 8 },
+    bubble: { maxWidth: "86%", paddingHorizontal: 12, paddingVertical: 9, borderRadius: 16 },
+    agentBubble: { alignSelf: "flex-start", backgroundColor: "#f1f3f4", borderBottomLeftRadius: 5 },
+    customerBubble: { alignSelf: "flex-end", borderBottomRightRadius: 5 },
+    agentText: { color: "#202124", fontSize: 14, lineHeight: 20 },
+    customerText: { color: "#fff", fontSize: 14, lineHeight: 20 },
+    composer: {
+        flexDirection: "row",
+        alignItems: "center",
+        gap: 8,
+        padding: 10,
+        borderTopWidth: StyleSheet.hairlineWidth,
+        borderTopColor: "#e8eaed",
+    },
+    input: {
+        flex: 1,
+        paddingHorizontal: 12,
+        paddingVertical: Platform.OS === "ios" ? 10 : 6,
+        backgroundColor: "#f1f3f4",
+        borderRadius: 20,
+        fontSize: 14,
+        color: "#202124",
+    },
+    sendButton: { width: 36, height: 36, borderRadius: 18, alignItems: "center", justifyContent: "center" },
+    sendLabel: { color: "#fff", fontSize: 17, lineHeight: 20 },
+});

package/dist/voice.d.ts

@@ -0,0 +1,25 @@
+import type { GraineInAppClient } from "./client";
+export declare const CAPTURE_SAMPLE_RATE = 16000;
+export interface AudioAdapter {
+    startCapture(onChunk: (base64: string) => void): Promise<void> | void;
+    stopCapture(): Promise<void> | void;
+    play(pcm16: Int16Array, sampleRate: number): void;
+    clear(): void;
+}
+export declare function base64ToPcm16(b64: string): Int16Array;
+export interface VoiceSessionOptions {
+    onTranscript?: (text: string, final: boolean) => void;
+    onAgentSpeaking?: (speaking: boolean) => void;
+}
+export declare class VoiceSession {
+    private client;
+    private adapter;
+    private options;
+    private offs;
+    private capturing;
+    constructor(client: GraineInAppClient, adapter: AudioAdapter, options?: VoiceSessionOptions);
+    get active(): boolean;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function liveAudioStreamAdapter(LiveAudioStream: any, sink: Pick<AudioAdapter, "play" | "clear">): AudioAdapter;

package/dist/voice.js

@@ -0,0 +1,84 @@
+export const CAPTURE_SAMPLE_RATE = 16000;
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+export function base64ToPcm16(b64) {
+    const clean = b64.replace(/[^A-Za-z0-9+/]/g, "");
+    const bytes = new Uint8Array((clean.length * 3) >> 2);
+    let byte = 0;
+    let acc = 0;
+    let bits = 0;
+    for (let i = 0; i < clean.length; i++) {
+        acc = (acc << 6) | B64.indexOf(clean[i]);
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes[byte++] = (acc >> bits) & 0xff;
+        }
+    }
+    const samples = new Int16Array(byte >> 1);
+    for (let i = 0; i < samples.length; i++) {
+        samples[i] = (bytes[i * 2] | (bytes[i * 2 + 1] << 8)) << 16 >> 16;
+    }
+    return samples;
+}
+export class VoiceSession {
+    constructor(client, adapter, options = {}) {
+        this.client = client;
+        this.adapter = adapter;
+        this.options = options;
+        this.offs = [];
+        this.capturing = false;
+    }
+    get active() {
+        return this.capturing;
+    }
+    async start() {
+        if (this.capturing)
+            return;
+        this.capturing = true;
+        this.offs = [
+            this.client.on("audio", ({ data, sampleRate }) => {
+                this.adapter.play(base64ToPcm16(data), sampleRate);
+            }),
+            this.client.on("clear", () => {
+                this.adapter.clear();
+                this.options.onAgentSpeaking?.(false);
+            }),
+            this.client.on("agent_speaking", (speaking) => this.options.onAgentSpeaking?.(speaking)),
+            this.client.on("transcript", ({ text, final }) => {
+                if (final)
+                    this.client.noteInteraction();
+                this.options.onTranscript?.(text, final);
+            }),
+        ];
+        await this.adapter.startCapture((base64) => this.client.sendAudio(base64, CAPTURE_SAMPLE_RATE));
+    }
+    async stop() {
+        if (!this.capturing)
+            return;
+        this.capturing = false;
+        this.offs.forEach((off) => off());
+        this.offs = [];
+        this.adapter.clear();
+        await this.adapter.stopCapture();
+    }
+}
+export function liveAudioStreamAdapter(LiveAudioStream, sink) {
+    return {
+        async startCapture(onChunk) {
+            LiveAudioStream.init({
+                sampleRate: CAPTURE_SAMPLE_RATE,
+                channels: 1,
+                bitsPerSample: 16,
+                audioSource: 6,
+                bufferSize: 1280,
+            });
+            LiveAudioStream.on("data", onChunk);
+            LiveAudioStream.start();
+        },
+        stopCapture() {
+            LiveAudioStream.stop();
+        },
+        play: sink.play.bind(sink),
+        clear: sink.clear.bind(sink),
+    };
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@graineai/inapp-react-native",
+  "version": "0.1.0",
+  "description": "Graine in-app agent for React Native \u2014 an agent that sees the screen your customer is on and can act on it.",
+  "license": "MIT",
+  "private": false,
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./mask": {
+      "types": "./dist/mask.d.ts",
+      "default": "./dist/mask.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "prepublishOnly": "npm run build && node scripts/verify-package-clean.mjs"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "react-native": ">=0.68"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "react-native": "^0.74.0",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "graine",
+    "voice-ai",
+    "in-app-agent",
+    "react-native",
+    "android",
+    "ios"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://app.graine.ai/docs/in-app",
+  "bugs": {
+    "url": "https://app.graine.ai/docs/in-app"
+  }
+}