@sagepilot-ai/react-native-sdk 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sagepilot 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,422 @@
+# `@sagepilot-ai/react-native-sdk`
+
+Official React Native SDK for adding Sagepilot chat to iOS and Android apps.
+
+The SDK opens the Sagepilot-hosted chat experience inside a React Native WebView and provides APIs for setup, identity, unread count, and app-owned launchers.
+
+## Requirements
+
+- React 18+
+- React Native 0.72+
+- `react-native-webview` 13+
+- A Sagepilot workspace id and chat channel id
+- Secure token storage for production apps
+
+## Install
+
+```bash
+npm install @sagepilot-ai/react-native-sdk react-native-webview
+```
+
+For secure persisted sessions, also install one storage library:
+
+```bash
+npm install react-native-keychain
+```
+
+Expo apps can use `expo-secure-store` instead:
+
+```bash
+npx expo install expo-secure-store
+```
+
+## Configuration Values
+
+You configure the SDK with:
+
+- `key`: public routing config in the format `workspace_id:channel_id`
+- `tokenStorage`: secure storage adapter for SDK-created customer session tokens
+- optional request, presentation, and behavior settings
+
+For normal Sagepilot cloud usage, omit `host`; API calls default to `https://api.sagepilot.ai` and the WebView uses the Sagepilot-hosted widget origin.
+
+```ts
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id"
+});
+```
+
+If your workspace uses a dedicated host:
+
+```ts
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id",
+  host: "https://your-sagepilot-host.com"
+});
+```
+
+The `key` is not a secret. It is safe to ship in a mobile app. Do not put server API keys, signing secrets, or private workspace secrets in a React Native app.
+
+### Supported Configuration Options
+
+These options are part of the supported React Native SDK configuration contract.
+
+| Option | Purpose |
+|---|---|
+| `key` | Public routing key in the format `workspace_id:channel_id`. |
+| `host` | Sagepilot customer-manager/API host override. Most apps should omit this. |
+| `widgetHost` | Optional hosted widget origin override for development or dedicated widget routing. Most apps should omit this. |
+| `headers` | Additional headers for SDK service requests. Do not pass server API keys or long-lived secrets from a mobile app. |
+| `fetch` | Custom fetch implementation for runtimes that need one. |
+| `tokenStorage` | Secure storage adapter for SDK-created customer session tokens. |
+| `anonymousId` | Optional stable anonymous identifier sent when the SDK creates a customer session. |
+| `metadata` | Optional app metadata merged into the session creation payload. |
+| `deviceInfo` | Optional adapter that returns device metadata to include during session creation. |
+| `presentation.style` | Modal presentation style: `"sheet"`, `"fullScreen"`, or `"push"`. |
+| `presentation.mobile` | Adds `mobile=1` to the hosted widget URL. Defaults to `true` for React Native. |
+| `presentation.showCloseButton` | Controls whether the provider renders a native close button around the WebView. Defaults to `false` so the hosted Sagepilot widget owns close behavior. |
+| `theme.accentColor` | Primary brand color used as the fallback launcher button color. |
+| `theme.logoUrl` | Optional brand logo URL exposed in SDK theme state. |
+| `theme.preferredColorScheme` | Optional hosted chat color scheme hint: `"light"`, `"dark"`, or `"system"`. |
+| `theme.launcher` | Optional chat launcher icon, label, and badge color configuration. |
+| `behavior.preloadWebView` | Preloads a hidden hosted chat WebView after configuration. |
+| `behavior.enableUnreadPolling` | Starts or disables automatic unread-count polling after configuration. |
+| `behavior.unreadPollIntervalMs` | Sets the unread polling interval in milliseconds. |
+
+`SagepilotChatProvider` renders the Sagepilot-hosted chat UI in a React Native WebView. Most Sagepilot cloud apps do not need any host override.
+
+### Chat Launcher Theme
+
+Use `theme.launcher` to configure the icon button and unread badge colors for your app-owned launcher. The SDK resolves omitted values to Sagepilot defaults, so customers only need to set the colors they want to control.
+
+```ts
+const CHAT_LAUNCHER_CONFIG = {
+  label: "Support",
+  buttonColor: "#173c2d",
+  pressedButtonColor: "#225340",
+  disabledButtonColor: "#d8cdbb",
+  borderColor: "#2a5e49",
+  disabledBorderColor: "#cbbda9",
+  iconColor: "#fff8ef",
+  iconInsideColor: "#173c2d",
+  labelColor: "#d4e9dc",
+  disabledContentColor: "#8d8172",
+  unreadBadgeColor: "#e76f51",
+  unreadBadgeTextColor: "#ffffff",
+  unreadBadgeBorderColor: "#efe4d4"
+};
+
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id",
+  theme: {
+    accentColor: CHAT_LAUNCHER_CONFIG.buttonColor,
+    preferredColorScheme: "system",
+    launcher: CHAT_LAUNCHER_CONFIG
+  }
+});
+```
+
+Use the resolved launcher theme from `useSagepilotChat()` when rendering your own button:
+
+```tsx
+import { Pressable, Text, View } from "react-native";
+import { MessageCircle } from "lucide-react-native";
+import { useSagepilotChat } from "@sagepilot-ai/react-native-sdk";
+
+export function ChatLauncher() {
+  const { configured, unreadCount, presentMessages, theme } = useSagepilotChat();
+  const launcher = theme.launcher;
+
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={launcher.label}
+      disabled={!configured}
+      onPress={presentMessages}
+      style={({ pressed }) => ({
+        alignItems: "center",
+        backgroundColor: !configured
+          ? launcher.disabledButtonColor
+          : pressed
+            ? launcher.pressedButtonColor
+            : launcher.buttonColor,
+        borderColor: !configured ? launcher.disabledBorderColor : launcher.borderColor,
+        borderRadius: 28,
+        borderWidth: 1,
+        height: 56,
+        justifyContent: "center",
+        width: 56
+      })}
+    >
+      <MessageCircle
+        color={!configured ? launcher.disabledContentColor : launcher.iconColor}
+        fill={!configured ? launcher.disabledContentColor : launcher.iconInsideColor}
+        size={24}
+      />
+      {unreadCount > 0 ? (
+        <View
+          style={{
+            alignItems: "center",
+            backgroundColor: launcher.unreadBadgeColor,
+            borderColor: launcher.unreadBadgeBorderColor,
+            borderRadius: 9,
+            borderWidth: 1,
+            minWidth: 18,
+            paddingHorizontal: 4,
+            position: "absolute",
+            right: -2,
+            top: -2
+          }}
+        >
+          <Text style={{ color: launcher.unreadBadgeTextColor, fontSize: 11 }}>
+            {unreadCount}
+          </Text>
+        </View>
+      ) : null}
+    </Pressable>
+  );
+}
+```
+
+## Secure Session Storage
+
+The SDK creates opaque customer session tokens at runtime. These tokens are not exposed through hooks or public session APIs.
+
+If `tokenStorage` is not provided, tokens are kept in memory only and the session will not persist after the app process restarts. Production apps should pass secure native storage.
+
+### React Native Keychain
+
+`react-native-keychain` stores values in iOS Keychain and Android secure storage backed by Android Keystore.
+
+```ts
+import * as Keychain from "react-native-keychain";
+import {
+  SagepilotChat,
+  createKeychainTokenStorage
+} from "@sagepilot-ai/react-native-sdk";
+
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id",
+  tokenStorage: createKeychainTokenStorage(Keychain)
+});
+```
+
+### Expo SecureStore
+
+Expo SecureStore uses iOS Keychain and Android encrypted storage backed by Android Keystore.
+
+```ts
+import * as SecureStore from "expo-secure-store";
+import { SagepilotChat } from "@sagepilot-ai/react-native-sdk";
+
+await SagepilotChat.configure({
+  key: "workspace_id:channel_id",
+  tokenStorage: {
+    getItem: SecureStore.getItemAsync,
+    setItem: SecureStore.setItemAsync,
+    removeItem: SecureStore.deleteItemAsync
+  }
+});
+```
+
+## Basic Setup
+
+Configure the SDK after your app knows the current workspace/channel and, if available, the current user.
+
+```tsx
+import * as Keychain from "react-native-keychain";
+import { useEffect } from "react";
+import {
+  SagepilotChat,
+  SagepilotChatProvider,
+  createKeychainTokenStorage
+} from "@sagepilot-ai/react-native-sdk";
+
+const tokenStorage = createKeychainTokenStorage(Keychain);
+
+export function SagepilotProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    let cancelled = false;
+
+    async function setupSagepilot() {
+      await SagepilotChat.configure({
+        key: "workspace_id:channel_id",
+        tokenStorage,
+        presentation: {
+          style: "sheet",
+          mobile: true
+        },
+        behavior: {
+          preloadWebView: true,
+          enableUnreadPolling: true
+        }
+      });
+
+      if (!cancelled) {
+        await SagepilotChat.identify({
+          userId: "user_123",
+          email: "customer@example.com",
+          name: "Customer Name"
+        });
+      }
+    }
+
+    void setupSagepilot().catch(console.warn);
+
+    return () => {
+      cancelled = true;
+      SagepilotChat.destroy();
+    };
+  }, []);
+
+  return <SagepilotChatProvider>{children}</SagepilotChatProvider>;
+}
+```
+
+Mount the provider once near the top of your app:
+
+```tsx
+export function App() {
+  return (
+    <SagepilotProvider>
+      <RootNavigator />
+    </SagepilotProvider>
+  );
+}
+```
+
+## Opening Chat
+
+The SDK does not force a launcher UI. Use the hook to connect Sagepilot to your own button, tab, badge, or help screen.
+
+```tsx
+import { Pressable, Text } from "react-native";
+import { useSagepilotChat } from "@sagepilot-ai/react-native-sdk";
+
+export function SupportButton() {
+  const { configured, unreadCount, presentMessages } = useSagepilotChat();
+
+  return (
+    <Pressable disabled={!configured} onPress={presentMessages}>
+      <Text>
+        Support{unreadCount > 0 ? ` (${unreadCount})` : ""}
+      </Text>
+    </Pressable>
+  );
+}
+```
+
+Other open helpers:
+
+```ts
+SagepilotChat.present();
+SagepilotChat.presentMessages();
+SagepilotChat.presentMessageComposer("I need help with my order");
+```
+
+## Identity
+
+Call `identify()` when you know the signed-in app user.
+
+```ts
+await SagepilotChat.identify({
+  userId: user.id,
+  email: user.email,
+  name: user.name,
+  phone: user.phone,
+  customProperties: {
+    plan: "pro",
+    storeId: "store_123"
+  }
+});
+```
+
+If identity verification is enabled for your workspace, generate `userHash` on your server and pass only the generated hash to the app:
+
+```ts
+await SagepilotChat.identify({
+  userId: user.id,
+  email: user.email,
+  userHash: serverGeneratedUserHash
+});
+```
+
+Never generate `userHash` in the mobile app with a signing secret.
+
+## Logout
+
+When the app user signs out, clear Sagepilot identity/session state:
+
+```ts
+await SagepilotChat.logout();
+await SagepilotChat.destroy();
+```
+
+`logout()` removes the known customer identity from the current SDK session. `destroy()` stops polling, clears in-memory state, and removes SDK listeners.
+
+## Public API
+
+### Setup
+
+- `SagepilotChat.configure(config)`: initializes the SDK, loads channel config, creates or resumes a customer session, and starts unread polling unless disabled.
+- `SagepilotChat.destroy()`: stops polling, clears in-memory SDK state, and removes listeners.
+- `SagepilotChat.getChannel()`: returns the loaded channel bootstrap data.
+
+### Identity And Session
+
+- `SagepilotChat.identify(identity)`: links the active session to a known customer.
+- `SagepilotChat.logout()`: removes known-customer identity from the active session.
+- `SagepilotChat.getSession()`: fetches the current session and returns safe session metadata. It does not expose the session token.
+- `SagepilotChat.getSessionState()`: returns safe local session metadata. It does not expose the session token.
+- `SagepilotChat.getIdentityState()`: returns local identity state.
+- `SagepilotChat.onIdentify(callback)`: subscribes to successful identify events.
+
+### Hosted Chat UI
+
+- `SagepilotChat.present()`: opens the hosted chat home screen.
+- `SagepilotChat.presentMessages()`: opens the hosted conversations/messages screen.
+- `SagepilotChat.presentMessageComposer(message?)`: opens a fresh message composer and optionally pre-fills the composer text. It does not auto-send.
+- `SagepilotChat.dismiss()`: closes the hosted chat modal.
+- `SagepilotChat.hide()`: alias for `dismiss()`.
+- `SagepilotChat.toggle()`: opens the chat when closed and closes it when open.
+- `SagepilotChat.isPresented()`: returns whether the hosted chat modal is open.
+- `SagepilotChatProvider`: renders the hosted Sagepilot chat inside a React Native modal WebView.
+
+When `SagepilotChatProvider` is mounted, the SDK preloads a hidden hosted WebView after `configure()` so the first visible open can reuse warmed network/cache state. Disable this with `behavior.preloadWebView: false`.
+
+### Unread State
+
+- `SagepilotChat.getUnreadCount()`: fetches and returns the current unread count.
+- `SagepilotChat.onUnreadChange(callback)`: subscribes to unread count changes.
+- `SagepilotChat.startUnreadPolling(intervalMs?)`: starts unread polling.
+- `SagepilotChat.stopUnreadPolling()`: stops unread polling.
+
+### Lifecycle Events
+
+- `SagepilotChat.onReady(callback)`: fires when SDK configuration completes.
+- `SagepilotChat.onPresent(callback)`: fires when chat opens.
+- `SagepilotChat.onDismiss(callback)`: fires when chat closes.
+- `SagepilotChat.onError(callback)`: subscribes to SDK errors.
+- `SagepilotChat.onStateChange(callback)`: subscribes to local SDK state changes.
+
+### React Hook
+
+- `useSagepilotChat()`: returns presentation helpers, unread count, identity state, and common actions for app-owned launchers and badges.
+
+### Storage Helpers
+
+- `createKeychainTokenStorage(keychain, options?)`: adapts `react-native-keychain` for secure session token storage.
+
+Do not use AsyncStorage for session tokens.
+
+## Runtime Notes
+
+The React Native UI uses `react-native-webview` to show the Sagepilot-owned hosted conversation. The SDK injects mobile WebView polish for viewport scaling, text selection, tap highlighting, native bridge message forwarding, and secure hosted-auth handoff.
+
+Customers should depend on the public SDK methods and components, not WebView internals or hosted route implementation details.
+
+## License
+
+MIT. See [LICENSE.md](./LICENSE.md).
+
+The MIT License applies only to this SDK code. It does not grant access to Sagepilot AI services, workspaces, API credentials, hosted infrastructure, models, data, or paid features. Use of Sagepilot AI hosted services, APIs, Workspace IDs, and runtime-generated license keys is governed separately by Sagepilot AI's Terms of Service or the applicable customer agreement.

package/android/.gitkeep

@@ -0,0 +1 @@
+