@figoailabs/figochat-react-native 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,10 @@
1
+ # Changelog
2
+
3
+ ## 1.0.0
4
+
5
+ - First public release.
6
+ - Chat with a Figo AI assistant, with retry and a welcome message.
7
+ - Voice messages: record, upload and send the transcript ("Processing your voice message…" while it runs).
8
+ - File and photo uploads with OCR.
9
+ - Live agent messages over Pusher, with the realtime settings kept AES-encrypted in memory.
10
+ - User-friendly error messages; technical details go to `onError`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Figo AI Labs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,125 @@
1
- # Temporary Holding Version
1
+ # FigoChat SDK for React Native
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Chat with a Figo AI assistant from your React Native app: text chat, voice messages (speech to text) and file uploads (with OCR for images), themed with your brand color.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ npm install @figoailabs/figochat-react-native # once published; or: npm install ../figochatsdk/react-native
9
+ npx expo install expo-audio expo-document-picker @react-native-community/netinfo
10
+ ```
11
+
12
+ `pusher-js` (live agent messages) and `crypto-js` come with the SDK. `@react-native-community/netinfo` is required by `pusher-js` on React Native.
13
+
14
+ For strong random keys in `FigoCrypto`, install `react-native-get-random-values` (bare RN) or `expo-crypto` and import it once at app start. Without either, keys fall back to `Math.random`.
15
+
16
+ Bare React Native (no Expo) apps first run `npx install-expo-modules@latest` so the two Expo modules can load.
17
+
18
+ ### Permissions
19
+
20
+ **Expo** — add to `app.json`:
21
+
22
+ ```json
23
+ {
24
+ "expo": {
25
+ "plugins": [
26
+ ["expo-audio", { "microphonePermission": "Allow $(PRODUCT_NAME) to record voice messages for chat." }]
27
+ ]
28
+ }
29
+ }
30
+ ```
31
+
32
+ **Bare RN** — iOS `Info.plist`: `NSMicrophoneUsageDescription`. Android `AndroidManifest.xml`: `<uses-permission android:name="android.permission.RECORD_AUDIO" />`.
33
+
34
+ ## Use
35
+
36
+ ```tsx
37
+ import { FigoChat, FigoChatView } from '@figoailabs/figochat-react-native';
38
+
39
+ // once, e.g. after the user signs in
40
+ FigoChat.initialize({
41
+ apiKey: 'YOUR_API_KEY',
42
+ assistantId: 'YOUR_ASSISTANT_ID',
43
+ fullName: 'Ada Lovelace',
44
+ emailAddress: 'ada@example.com',
45
+ mobilePhone: '+2348012345678',
46
+ primaryColor: '#F97316',
47
+ // optional
48
+ title: 'Support',
49
+ welcomeMessage: 'Hi Ada! How can I help you today?',
50
+ });
51
+
52
+ export function SupportScreen({ navigation }) {
53
+ return <FigoChatView onClose={() => navigation.goBack()} />;
54
+ }
55
+ ```
56
+
57
+ As a modal:
58
+
59
+ ```tsx
60
+ import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
61
+
62
+ <Modal visible={open} animationType="slide" onRequestClose={() => setOpen(false)}>
63
+ {/* a Modal is its own native window, so it needs its own SafeAreaProvider */}
64
+ <SafeAreaProvider>
65
+ <SafeAreaView style={{ flex: 1 }}>
66
+ <FigoChatView onClose={() => setOpen(false)} />
67
+ </SafeAreaView>
68
+ </SafeAreaProvider>
69
+ </Modal>
70
+ ```
71
+
72
+ A runnable Expo app is in [`example/`](example/).
73
+
74
+ ### `initialize` options
75
+
76
+ | Option | Required | Description |
77
+ |---|---|---|
78
+ | `apiKey` | ✓ | API key from the Figo AI dashboard |
79
+ | `assistantId` | ✓ | Assistant to chat with |
80
+ | `fullName` | ✓ | Signed-in user's name |
81
+ | `emailAddress` | ✓ | Signed-in user's email |
82
+ | `mobilePhone` | ✓ | Signed-in user's phone, international format |
83
+ | `primaryColor` | ✓ | Hex brand color, e.g. `#F97316` |
84
+ | `baseUrl` | | Defaults to `https://api.figolabs.ai` |
85
+ | `title` | | Header title, default `Chat` |
86
+ | `welcomeMessage` | | First assistant message |
87
+ | `threadId` | | Resume an earlier conversation |
88
+ | `maxFiles` | | Files per message, default 5 |
89
+ | `maxFileSizeMB` | | Default 10 |
90
+ | `autoSendVoice` | | Send transcription immediately (default) or put it in the input |
91
+ | `timeoutMs` | | Default 120000 |
92
+
93
+ ### `FigoChatView` props
94
+
95
+ `onClose`, `showHeader`, `placeholder`, `enableVoice`, `enableAttachments`, `keyboardVerticalOffset` (rarely needed: the view keeps its input above the keyboard by itself), `icons` (replace the glyph icons with your icon library: `send`, `attach`, `mic`, `stop`, `close`, `newChat`), `onError`, `style`.
96
+
97
+ ### Other calls
98
+
99
+ ```ts
100
+ FigoChat.getThreadId(); // save it to resume later via initialize({ threadId })
101
+ FigoChat.resetConversation(); // next message starts a new thread
102
+ FigoChat.logout(); // clear config on sign-out
103
+
104
+ // Build your own UI
105
+ const client = FigoChat.getClient();
106
+ const { answer } = await client.sendMessage('Hello');
107
+ const text = await client.transcribe({ uri, name: 'voice.m4a', mimeType: 'audio/mp4' });
108
+ const urls = await client.uploadFiles([{ uri, name: 'receipt.jpg', mimeType: 'image/jpeg' }]);
109
+ ```
110
+
111
+ All errors are `FigoChatError` with a `code` (`401`, `49`, `TIMEOUT`, `NETWORK`, …). The chat screen never shows these technical messages to users. It shows friendly text instead, such as "Chat isn't available right now. Please try again later." for a bad key, no credits or a plan limit, and "You seem to be offline…" for network problems. `onError` still receives the full technical error for your logs. Apps with their own UI can use `friendlyMessage(error)`.
112
+
113
+ ## How it works
114
+
115
+ - **Text** → `POST /api/v1/chat/assistant/{assistantId}`; the `X-Thread-Id` response header keeps the conversation going.
116
+ - **Voice** → recorded as AAC `.m4a` with `expo-audio`, sent to `POST /api/v1/stt`, and the text is sent as a chat message.
117
+ - **Files** → picked with `expo-document-picker`, uploaded as base64 to `POST /api/v1/cdn/upload/ocr/{assistantId}`; the returned urls are appended to the message so the assistant gets the OCR text of images.
118
+
119
+ ## Live agent messages
120
+
121
+ After the first reply, the chat subscribes to the Pusher channel named after the conversation's thread id. Messages a live agent sends from Tawk.to, Zoho SalesIQ or FreshChat appear on the left, like assistant replies. The Pusher key and cluster come from `GET /api/v1/realtime/config`. They're kept encrypted in memory with `FigoCrypto` (AES-256 with a random per-session key) and decrypted only when subscribing.
122
+
123
+ ## API key security
124
+
125
+ The API key ships inside the mobile app, so anyone who unpacks the app can read it and call every API-key endpoint, spending the company's credits. Create a dedicated key for the SDK in the Figo AI dashboard, give it an expiry, and rotate it if it leaks. For stronger protection, have your own backend issue short-lived keys and pass them to `initialize` after sign-in.
@@ -0,0 +1,24 @@
1
+ import { FigoChatClient } from './client';
2
+ import { FigoRealtimeConfigStore } from './realtime';
3
+ import type { FigoChatConfig } from './types';
4
+ /**
5
+ * Entry point of the SDK. Call `FigoChat.initialize(...)` once (for example after the user signs in),
6
+ * then render `<FigoChatView />`.
7
+ */
8
+ export declare const FigoChat: {
9
+ initialize(config: FigoChatConfig): void;
10
+ isInitialized(): boolean;
11
+ /** The API client, for apps that want to build their own UI. */
12
+ getClient(): FigoChatClient;
13
+ getConfig(): FigoChatConfig;
14
+ /** @internal encrypted realtime settings used by FigoChatView to subscribe to the thread channel. */
15
+ getRealtimeStore(): FigoRealtimeConfigStore;
16
+ /** Thread id of the current conversation; store it and pass it as `threadId` to resume later. */
17
+ getThreadId(): string | undefined;
18
+ /** Starts a new conversation on the next message. */
19
+ resetConversation(): void;
20
+ /** Clears the configuration, e.g. when the user signs out. */
21
+ logout(): void;
22
+ /** @internal used by FigoChatView to re-render after initialize/reset/logout. */
23
+ subscribe(listener: () => void): () => void;
24
+ };
@@ -0,0 +1,76 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.FigoChat = void 0;
4
+ const client_1 = require("./client");
5
+ const crypto_1 = require("./crypto");
6
+ const realtime_1 = require("./realtime");
7
+ const HEX_COLOR = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
8
+ let current = null;
9
+ const listeners = new Set();
10
+ /**
11
+ * Entry point of the SDK. Call `FigoChat.initialize(...)` once (for example after the user signs in),
12
+ * then render `<FigoChatView />`.
13
+ */
14
+ exports.FigoChat = {
15
+ initialize(config) {
16
+ const required = ['apiKey', 'assistantId', 'fullName', 'emailAddress', 'mobilePhone', 'primaryColor'];
17
+ const missing = required.filter((k) => !String(config[k] ?? '').trim());
18
+ if (missing.length) {
19
+ throw new client_1.FigoChatError(`FigoChat.initialize: missing ${missing.join(', ')}.`, 'CONFIG');
20
+ }
21
+ if (!HEX_COLOR.test(config.primaryColor.trim())) {
22
+ throw new client_1.FigoChatError('FigoChat.initialize: primaryColor must be a hex color such as #F97316.', 'CONFIG');
23
+ }
24
+ const normalized = {
25
+ ...config,
26
+ apiKey: config.apiKey.trim(),
27
+ assistantId: config.assistantId.trim(),
28
+ fullName: config.fullName.trim(),
29
+ emailAddress: config.emailAddress.trim(),
30
+ mobilePhone: config.mobilePhone.trim(),
31
+ primaryColor: config.primaryColor.trim(),
32
+ };
33
+ const client = new client_1.FigoChatClient(normalized);
34
+ current = { config: normalized, client, realtime: new realtime_1.FigoRealtimeConfigStore(client, new crypto_1.FigoCrypto()) };
35
+ listeners.forEach((l) => l());
36
+ },
37
+ isInitialized() {
38
+ return current !== null;
39
+ },
40
+ /** The API client, for apps that want to build their own UI. */
41
+ getClient() {
42
+ return requireInitialized().client;
43
+ },
44
+ getConfig() {
45
+ return requireInitialized().config;
46
+ },
47
+ /** @internal encrypted realtime settings used by FigoChatView to subscribe to the thread channel. */
48
+ getRealtimeStore() {
49
+ return requireInitialized().realtime;
50
+ },
51
+ /** Thread id of the current conversation; store it and pass it as `threadId` to resume later. */
52
+ getThreadId() {
53
+ return current?.client.getThreadId();
54
+ },
55
+ /** Starts a new conversation on the next message. */
56
+ resetConversation() {
57
+ current?.client.resetThread();
58
+ listeners.forEach((l) => l());
59
+ },
60
+ /** Clears the configuration, e.g. when the user signs out. */
61
+ logout() {
62
+ current = null;
63
+ listeners.forEach((l) => l());
64
+ },
65
+ /** @internal used by FigoChatView to re-render after initialize/reset/logout. */
66
+ subscribe(listener) {
67
+ listeners.add(listener);
68
+ return () => listeners.delete(listener);
69
+ },
70
+ };
71
+ function requireInitialized() {
72
+ if (!current) {
73
+ throw new client_1.FigoChatError('FigoChat is not initialized. Call FigoChat.initialize(...) first.', 'NOT_INITIALIZED');
74
+ }
75
+ return current;
76
+ }
@@ -0,0 +1,26 @@
1
+ import React from 'react';
2
+ import { StyleProp, ViewStyle } from 'react-native';
3
+ import { FigoChatError } from './client';
4
+ export interface FigoChatViewProps {
5
+ /** Shows a close button in the header and calls this when it is pressed. */
6
+ onClose?: () => void;
7
+ /** Hide the header if the host app draws its own. Defaults to true. */
8
+ showHeader?: boolean;
9
+ /** Input placeholder. Defaults to "Type a message". */
10
+ placeholder?: string;
11
+ /** Turn voice notes off. Defaults to true. */
12
+ enableVoice?: boolean;
13
+ /** Turn file uploads off. Defaults to true. */
14
+ enableAttachments?: boolean;
15
+ /**
16
+ * Extra space added above the keyboard on iOS. Rarely needed: the view measures how much of it the
17
+ * keyboard covers, so it already works inside modals, under navigation headers and in safe areas.
18
+ */
19
+ keyboardVerticalOffset?: number;
20
+ /** Replace the built-in glyph icons with your own (e.g. from an icon library). */
21
+ icons?: Partial<Record<'send' | 'attach' | 'mic' | 'stop' | 'close' | 'newChat', React.ReactNode>>;
22
+ /** Called with every error the view shows, for logging. */
23
+ onError?: (error: FigoChatError) => void;
24
+ style?: StyleProp<ViewStyle>;
25
+ }
26
+ export declare function FigoChatView({ onClose, showHeader, placeholder, enableVoice, enableAttachments, keyboardVerticalOffset, icons, onError, style, }: FigoChatViewProps): React.JSX.Element;