@zellio/chat-react-native 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+# @zellio/chat-react-native
 
-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.
+ZeeChat for React Native. This package is a thin wrapper: the native iOS and Android SDKs draw all screens and
+hold all chat logic. JavaScript only configures them, opens them, gives them a token and listens to events.
+
+- Needs the **New Architecture** (Turbo Native Modules). React Native 0.82 and later has no other mode.
+  Tested with React Native 0.88.1 and Expo SDK 58. iOS 15.1+, Android minSdk 24.
+- English docs here. Arabic docs come later.
+
+## 5-minute setup: bare React Native
+
+```sh
+npm install @zellio/chat-react-native
+cd ios && pod install && cd ..
+```
+
+Add the camera text to `ios/<App>/Info.plist` (the SDK asks for camera access only when a customer taps Camera):
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Allow the app to use the camera so you can send photos in chat.</string>
+<key>NSPhotoLibraryUsageDescription</key>
+<string>Allow the app to access your photos so you can send them in chat.</string>
+```
+
+Start it once, as early as you can (top of `index.js` or `App.tsx`):
+
+```ts
+import * as ZellioChat from '@zellio/chat-react-native';
+
+ZellioChat.configure({ appKey: 'zca_...' });
+```
+
+Open it from a button:
+
+```tsx
+<Button title="Chat with us" onPress={() => ZellioChat.present()} />
+```
+
+That is all. The app key is in Zellio Studio.
+
+## 5-minute setup: Expo
+
+```sh
+npx expo install @zellio/chat-react-native
+```
+
+`app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@zellio/chat-react-native",
+        {
+          "cameraPermission": "Allow $(PRODUCT_NAME) to use the camera so you can send photos in chat.",
+          "photoLibraryPermission": "Allow $(PRODUCT_NAME) to access your photos so you can send them in chat."
+        }
+      ]
+    ]
+  }
+}
+```
+
+Then build a development build: `npx expo prebuild` and `npx expo run:ios` / `npx expo run:android`, or EAS Build.
+
+**This does not work in Expo Go.** Expo Go is one fixed app with a fixed list of native modules. This package adds
+native code (a Turbo Native Module and the two native chat SDKs). Native code can only be added when the app is
+built, so you need a development build (or a production build). JavaScript changes still reload fast in a
+development build.
+
+Plugin options (all optional):
+
+| Option | Default | Meaning |
+|---|---|---|
+| `cameraPermission` | English text | `NSCameraUsageDescription`. `false` adds nothing. |
+| `photoLibraryPermission` | English text | `NSPhotoLibraryUsageDescription`. `false` adds nothing. |
+| `enableIosPush` | `false` | Adds the `aps-environment` entitlement and the `remote-notification` background mode. Leave it off if `expo-notifications` already does this. |
+| `apsEnvironment` | `development` | Value of `aps-environment` when `enableIosPush` is on. |
+| `androidMavenRepository` | none | A Maven URL for `ai.zellio:zellio-chat`, only if it is not on Maven Central for you. |
+
+The plugin never adds push entitlements unless you set `enableIosPush`. It keeps any usage text you already set.
+
+## API
+
+```ts
+configure({ appKey, baseUrl?, locale?, theme?, logLevel?, showsInAppBanner?, bannerShowsPreview? }): void
+identify(tokenProvider: () => Promise<string | null>): void
+logout(): void
+present(): void
+presentConversation(id?: string | null): void
+dismiss(): void
+setContext(context: { screen?, itemType?, itemId?, itemTitle?, url? } | null): void
+getUnreadCount(): Promise<number>
+addUnreadListener(cb: (count: number) => void): { remove(): void }
+addEventListener(cb: (event: ZellioChatEvent) => void): { remove(): void }
+setPushToken(token: string, environment?: 'sandbox' | 'production'): void
+isZellioPush(payload): boolean
+handlePush(payload): Promise<boolean>
+handleNotificationTap(payload): Promise<boolean>
+```
+
+`ZellioChatEvent` is `chatOpened | chatClosed | messageSent | messageReceived | error { code }`. Events never carry
+message text. Every call is safe before `configure` and never throws into your app.
+
+`showsInAppBanner` (default true) turns the in-app banner on or off. `bannerShowsPreview` (default true) shows the message text in it; when false it says "New message".
+
+## Identity with a server token
+
+Your server signs a short-lived JWT for the signed-in customer (see the contract in the Zellio docs). The app only
+passes a function that fetches it:
+
+```ts
+ZellioChat.identify(async () => {
+  const response = await fetch('https://api.example.com/zeechat-token', { headers: authHeaders() });
+  if (!response.ok) throw new Error('token');
+  return (await response.json()).token; // return null for a guest
+});
+```
+
+How it works: the native SDK calls your function when it needs a session, and again if the server rejects the token.
+Native sends an event with a request id, JavaScript runs your function and answers with the token or an error. If
+your function does not answer in **15 seconds**, the request fails. The token is never logged, not by JavaScript and
+not by native code. On sign-out call `ZellioChat.logout()`: it deletes all local chat data and removes the push token.
+
+## Context
+
+Tell agents what the customer looks at. It is sent with the next messages:
+
+```ts
+ZellioChat.setContext({ screen: 'Product', itemType: 'product', itemId: '42', itemTitle: 'Linen shirt', url: 'https://shop.example.com/p/42' });
+ZellioChat.setContext(null); // clear
+```
+
+`url` must be `https`. Text is cut to 200 characters.
+
+## Push notifications
+
+This package does not take over your notification code. You keep your push library and forward to this package.
+
+**Android (FCM).** Use the FCM library you already use (for example `@react-native-firebase/messaging`). Pass the
+token with `setPushToken` and each message with `handlePush`:
+
+```ts
+import messaging from '@react-native-firebase/messaging';
+
+messaging().getToken().then((token) => ZellioChat.setPushToken(token));
+messaging().onTokenRefresh((token) => ZellioChat.setPushToken(token));
+
+// Foreground and background (data) messages
+messaging().onMessage(async (message) => { await ZellioChat.handlePush(message.data); });
+messaging().setBackgroundMessageHandler(async (message) => { await ZellioChat.handlePush(message.data); });
+
+// Notification tapped
+messaging().onNotificationOpenedApp((message) => { void ZellioChat.handleNotificationTap(message.data); });
+messaging().getInitialNotification().then((message) => { if (message) void ZellioChat.handleNotificationTap(message.data); });
+```
+
+Do not add a second `FirebaseMessagingService` from this package: Android allows one per app, and FCM goes through
+the library you chose. (The native Android SDK has an optional ready service for apps with no other push code. It is
+not part of this package.)
+
+**iOS (APNs).** Turn on Push Notifications and Background Modes > Remote notifications for the app target (Expo:
+`enableIosPush: true`, or let `expo-notifications` do it). Pass the APNs token as a **hex string**:
+
+```ts
+import * as Notifications from 'expo-notifications';
+
+const token = await Notifications.getDevicePushTokenAsync(); // { type: 'ios', data: '<hex>' }
+ZellioChat.setPushToken(token.data, __DEV__ ? 'sandbox' : 'production');
+
+Notifications.addNotificationReceivedListener((n) => {
+  void ZellioChat.handlePush(n.request.trigger && 'payload' in n.request.trigger ? (n.request.trigger.payload as Record<string, unknown>) : null);
+});
+Notifications.addNotificationResponseReceivedListener((response) => {
+  const trigger = response.notification.request.trigger;
+  if (trigger && 'payload' in trigger) void ZellioChat.handleNotificationTap(trigger.payload as Record<string, unknown>);
+});
+```
+
+`isZellioPush(payload)` is true only when the payload has the `zellio` key, so you can tell our pushes from yours.
+`handlePush` and `handleNotificationTap` resolve `true` when the push was ours.
+
+## Build against the local native SDKs (this repository)
+
+The package depends on `ai.zellio:zellio-chat:<version>` from Maven and on the iOS sources copied into the package.
+Inside the repository:
+
+- **iOS:** `npm run vendor:ios` copies `../ios/Sources` to `ios/vendor` (git-ignored). `npm pack` does it for you. The
+  podspec compiles those sources into the pod, so no extra pod and no CocoaPods trunk push are needed.
+- **Android:** publish the SDK to your local Maven repository, then build the sample with it:
+
+  ```sh
+  cd ../android && ./gradlew :zellio-chat:publishReleasePublicationToMavenLocal
+  ```
+
+  The sample's `android/gradle.properties` has `zellioChatUseMavenLocal=true`, which adds `mavenLocal()` to the sample's
+  repositories. Do the same in your own app to test a local SDK. The sample uses stock React Native 0.88 versions of
+  Kotlin (2.2.0) and the Android Gradle Plugin, so this also checks that the SDK builds against them. Set
+  `zellioChatAndroidVersion` to pin another Maven version.
+
+## Sample
+
+```sh
+cd sdks/react-native && npm ci && npm run build
+cd sample && npm install && npm run setup   # creates zellio.config.json (git-ignored)
+# put your app key in zellio.config.json, then:
+npm start
+npm run android      # Android
+npm run pods && npm run ios   # iOS, macOS only: copies the iOS SDK sources, runs pod install
+```
+
+The sample has a store-like screen, an **Open chat** button, an unread badge and product context.
+
+No account? Run `npm run fixture-server` in `sample/`. It answers the API contract with the shared fixtures. Then set
+`"baseUrl": "http://10.0.2.2:8787"` (Android emulator) or `"http://localhost:8787"` (iOS simulator) in
+`zellio.config.json`. Debug builds allow cleartext HTTP; never ship an http `baseUrl`. The fixture server prints the
+`x-zee-sdk-wrapper` header of each request, which shows `react-native/1.0.0`.
+
+## Troubleshooting
+
+| Problem | Cause and fix |
+|---|---|
+| `TurboModuleRegistry.getEnforcing(...): 'RNZellioChat' could not be found` | The app was not rebuilt after install. Run `pod install` (iOS) and rebuild. In Expo, you are in Expo Go: use a development build. |
+| Nothing happens on `present()` | `configure` was not called, or the app key is empty. Set `logLevel: 'debug'` and read Logcat (`ZellioChat`) or the Xcode console. Calls before `configure` are logged and ignored. |
+| "Chat not available" screen | The app key or `baseUrl` is wrong, or there is no network. Check them in Zellio Studio. |
+| Android: `Could not find ai.zellio:zellio-chat` | The artifact is not on a repository your app uses. Add `mavenCentral()` to `repositories`, or use the Expo option `androidMavenRepository`, or use the local build above. |
+| Android build: `kotlin-android` plugin error | RN 0.88 templates set `android.builtInKotlin=false`. Keep that line in `android/gradle.properties`. |
+| iOS: duplicate symbol or `No such module 'ZellioChatCore'` | `ios/vendor` is out of date. Run `npm run vendor:ios`, then `pod install`. |
+| Token request fails after 15 s | Your `identify` function is slow or never resolves. It must return a string, or `null` for a guest. |
+| iOS push never arrives | Use the **hex** APNs token, and `sandbox` for debug builds and `production` for store builds. |
+| Unread badge stays 0 | The customer has no session yet (no consent, no `identify`), or the app is in the background. |
+
+## Status (honest)
+
+- The TypeScript API, the identify flow and the Expo config plugin are covered by unit tests.
+- The Android module is compiled against the native Android SDK. See the repository notes for what was run.
+- The iOS glue (`RNZellioChat.mm`, `ZCRNBridge.swift`) and the podspec were written on Windows and have **never been
+  compiled**. Expect small fixes on the first macOS build with `pod install`.

package/ZellioChatReactNative.podspec

@@ -0,0 +1,30 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ZellioChatReactNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = { :type => package["license"] }
+  s.authors      = { "Zellio" => "support@zellio.ai" }
+  s.platforms    = { :ios => "15.1" }
+  s.source       = { :git => "https://github.com/zellio-ai/zellio-chat-sdk.git", :tag => "#{s.version}" }
+
+  # ios/*            the Turbo module (Objective-C++) and one Swift bridge file.
+  # ios/vendor/swift the ZeeChat iOS SDK sources. `npm run vendor:ios` copies them from ../ios/Sources and
+  #                  `npm pack` runs it first. They are compiled here, so no extra pod is needed.
+  s.source_files = ["ios/*.{h,m,mm,swift}", "ios/vendor/swift/**/*.swift"]
+  s.private_header_files = "ios/RNZellioChat.h"
+
+  # The privacy manifest of the SDK. A resource bundle is how Apple wants it from a pod.
+  s.resource_bundles = { "ZellioChatReactNativePrivacy" => ["ios/vendor/resources/PrivacyInfo.xcprivacy"] }
+
+  s.swift_version = "5.0"
+  s.pod_target_xcconfig = { "DEFINES_MODULE" => "YES" }
+  s.frameworks = ["SwiftUI", "UIKit"]
+
+  # Adds React-Core, the codegen headers and the New Architecture flags.
+  install_modules_dependencies(s)
+end

package/android/build.gradle

@@ -0,0 +1,62 @@
+// Android half of @zellio/chat-react-native. A React Native app autolinks this module.
+//
+// SDK version: the Maven artifact ai.zellio:zellio-chat. Override with -PzellioChatAndroidVersion=x.y.z
+// (gradle.properties or the command line).
+//
+// Local SDK: publish sdks/android to ~/.m2 (`./gradlew :zellio-chat:publishReleasePublicationToMavenLocal`) and add
+//
+//     allprojects { repositories { mavenLocal() } }
+//
+// to the app's android/build.gradle (the sample does this behind -PzellioChatUseMavenLocal=true).
+
+if (project == rootProject) {
+  buildscript {
+    repositories {
+      google()
+      mavenCentral()
+    }
+    dependencies {
+      classpath "com.android.tools.build:gradle:9.2.1"
+      classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:2.2.0"
+    }
+  }
+}
+
+def sdkVersion = project.findProperty("zellioChatAndroidVersion") ?: "1.0.0"
+
+def ext(String name, Object fallback) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : fallback
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "ai.zellio.chat.reactnative"
+  compileSdk ext("compileSdkVersion", 36)
+
+  defaultConfig {
+    minSdkVersion ext("minSdkVersion", 24)
+    targetSdkVersion ext("targetSdkVersion", 36)
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_17
+    targetCompatibility JavaVersion.VERSION_17
+  }
+}
+
+kotlin {
+  jvmToolchain(17)
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  api "ai.zellio:zellio-chat:${sdkVersion}"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />