rn-erxes-sdk 0.3.3 → 0.3.4

package/README.md

@@ -127,9 +127,15 @@ Supports the classic widget and the full-screen **chat mode** (with voice
 messages and header/drawer actions).
 
 ```tsx
-import { ErxesNativeIOS } from 'rn-erxes-sdk';
+import { ErxesMessenger } from 'rn-erxes-sdk';
 ```
 
+Two APIs are exported:
+
+- **`<ErxesMessenger />`** — a declarative React component that handles configure,
+  user identity, action taps, and the show/hide lifecycle. Recommended for most apps.
+- **`ErxesNativeIOS`** — the low-level native bridge for advanced/imperative control.
+
 ## Requirements
 
 | | |
@@ -174,7 +180,116 @@ cd ios && pod install
 npx expo run:ios
 ```
 
-## Usage
+## Usage — `<ErxesMessenger />` (recommended)
+
+Render the component where the messenger should be active. It configures the SDK on
+mount, dispatches action taps to your `onPress` handlers, and hides the messenger on
+unmount. It renders nothing — the messenger UI is presented natively over your app.
+
+```tsx
+import { ErxesMessenger } from 'rn-erxes-sdk';
+
+<ErxesMessenger
+  integrationId="YOUR_INTEGRATION_ID"
+  subDomain="yourcompany.erxes.io"
+  user={{ name: 'Jane Doe', email: 'user@example.com' }}
+/>
+```
+
+### Example 1 — Classic floating launcher
+
+Shows a draggable button over your app. Tapping it opens the messenger.
+
+```tsx
+<ErxesMessenger
+  integrationId={INTEGRATION_ID}
+  endpoint={ENDPOINT}
+  displayMode="classic"
+  launcherVisible
+  user={CURRENT_USER}
+/>
+```
+
+### Example 2 — Home screen full-screen chat
+
+Chat mode opens full-screen and auto-opens when connected. Bind `visible` to screen
+focus so the messenger shows/hides as the user navigates, and add a header action to
+jump to another screen.
+
+```tsx
+const isFocused = useIsFocused();
+
+<ErxesMessenger
+  visible={isFocused}
+  integrationId={INTEGRATION_ID}
+  endpoint={ENDPOINT}
+  displayMode="chat"
+  user={CURRENT_USER}
+  homeActions={[
+    {
+      id: 'profile',
+      title: 'Profile',
+      systemIcon: 'person.crop.circle',
+      onPress: async ({ hide }) => {
+        await hide();
+        navigation.navigate('Profile', { user: CURRENT_USER });
+      },
+    },
+  ]}
+/>
+```
+
+### Example 3 — Settings → Support screen with a close button
+
+Open chat on mount, hide it on unmount, and add an `X` action that closes the
+messenger and pops the screen.
+
+```tsx
+<ErxesMessenger
+  integrationId={INTEGRATION_ID}
+  endpoint={ENDPOINT}
+  displayMode="chat"
+  autoOpen
+  autoHideOnUnmount
+  user={CURRENT_USER}
+  homeActions={[
+    {
+      id: 'close',
+      title: 'Close',
+      systemIcon: 'xmark',
+      onPress: async ({ hide }) => {
+        await hide();
+        navigation.goBack();
+      },
+    },
+  ]}
+  onReady={() => console.log('erxes messenger ready')}
+  onError={(error) => console.log('erxes messenger error', error)}
+/>
+```
+
+### Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `integrationId` | `string` | Required. |
+| `endpoint` / `serverUrl` / `subDomain` | `string` | Provide one. `subDomain` accepts `'company.erxes.io'`. |
+| `displayMode` | `'classic' \| 'chat'` | Defaults to `'classic'`. |
+| `user` | `ErxesUser` | `{ name?, email?, phone?, customData? }`. |
+| `cachedCustomerId` | `string` | Reuse a cached customer. |
+| `primaryColor` | `string` | Hex accent, e.g. `'#3f78d9'`. |
+| `visible` | `boolean` | Controlled show/hide on change. |
+| `autoOpen` | `boolean` | Open after configure. Defaults to `true` in chat mode. |
+| `autoHideOnUnmount` | `boolean` | Hide on unmount. Defaults to `true`. |
+| `launcherVisible` | `boolean` | Show/hide the floating launcher after configure. |
+| `homeActions` / `drawerActions` | `ErxesAction[]` | `{ id, title, systemIcon, onPress? }`. Chat mode only. |
+| `onLoad` / `onReady` / `onOpen` / `onClose` / `onError` | callbacks | Lifecycle events. |
+| `onAction` | `(id, helpers) => void` | Fallback for tapped actions with no `onPress`. |
+
+Action `onPress` (and `onAction`) receive `ErxesMessengerHelpers`:
+`show`, `hide`, `showLauncher`, `hideLauncher`, `setUser`, `clearUser`.
+
+## Advanced — `ErxesNativeIOS` (low-level)
 
 Call `configure` once at startup. It connects in the background so the messenger opens instantly.
 

package/docs/native-ios.md

@@ -4,6 +4,11 @@
 ([`erxes/erxes-ios-sdk`](https://github.com/erxes/erxes-ios-sdk) `0.30.7`)
 into your React Native app.
 
+> **Most apps should use the `<ErxesMessenger />` component instead** — it wraps
+> this bridge and manages configure, user identity, action taps, and the show/hide
+> lifecycle declaratively. See the [README](../README.md#usage--erxesmessenger-recommended).
+> This guide documents the low-level `ErxesNativeIOS` API for advanced/imperative use.
+
 ## Requirements
 
 | | |

package/lib/commonjs/ErxesMessenger.js

@@ -0,0 +1,160 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ErxesMessenger = ErxesMessenger;
+var _react = require("react");
+var _reactNative = require("react-native");
+var _nativeIos = require("./nativeIos");
+/**
+ * The identified end user. Same shape the native bridge expects — passing
+ * `undefined` leaves the visitor anonymous until you call `setUser` later.
+ */
+
+/**
+ * Helpers handed to action `onPress` callbacks (and `onAction`) so you can drive
+ * the messenger imperatively from inside a tap handler — show/hide it, toggle the
+ * launcher, or swap the user.
+ */
+
+/**
+ * A chat-mode action rendered in the header (`homeActions`) or drawer
+ * (`drawerActions`). Only `id`/`title`/`systemIcon` cross the native bridge; the
+ * `onPress` callback stays in JS and runs when the matching action is tapped.
+ */
+
+/**
+ * Drop `onPress` so only the data-only fields the native bridge understands
+ * (`id`/`title`/`systemIcon`) cross over. React Native cannot send JS functions
+ * to native, so `onPress` is dispatched on the JS side via the action listener.
+ */
+function stripActions(actions) {
+  return actions.map(_ref => {
+    let {
+      onPress: _onPress,
+      ...nativeAction
+    } = _ref;
+    return nativeAction;
+  });
+}
+
+/**
+ * Declarative wrapper around {@link ErxesNativeIOS}. Configures the native erxes
+ * messenger, wires up action taps, and manages the show/hide lifecycle so app
+ * code stays a single component. Renders nothing — the messenger UI is presented
+ * natively over your app.
+ *
+ * For advanced/imperative control, use `ErxesNativeIOS` directly.
+ */
+function ErxesMessenger(_ref2) {
+  let {
+    integrationId,
+    endpoint,
+    serverUrl,
+    subDomain,
+    displayMode = 'classic',
+    user,
+    cachedCustomerId,
+    primaryColor,
+    visible,
+    autoOpen = displayMode === 'chat',
+    autoHideOnUnmount = true,
+    launcherVisible,
+    homeActions = [],
+    drawerActions = [],
+    onLoad,
+    onReady,
+    onOpen,
+    onClose,
+    onError,
+    onAction
+  } = _ref2;
+  // Keep the latest actions/callback in refs so the action listener (registered
+  // once below) always dispatches against current props without re-subscribing.
+  const actionsRef = (0, _react.useRef)([]);
+  const onActionRef = (0, _react.useRef)(onAction);
+  (0, _react.useEffect)(() => {
+    actionsRef.current = [...homeActions, ...drawerActions];
+    onActionRef.current = onAction;
+  }, [homeActions, drawerActions, onAction]);
+  (0, _react.useEffect)(() => {
+    if (_reactNative.Platform.OS !== 'ios') {
+      return;
+    }
+    const helpers = {
+      show: () => _nativeIos.ErxesNativeIOS.showMessenger(),
+      hide: () => _nativeIos.ErxesNativeIOS.hideMessenger(),
+      showLauncher: () => _nativeIos.ErxesNativeIOS.showLauncher(),
+      hideLauncher: () => _nativeIos.ErxesNativeIOS.hideLauncher(),
+      setUser: nextUser => _nativeIos.ErxesNativeIOS.setUser(nextUser),
+      clearUser: () => _nativeIos.ErxesNativeIOS.clearUser()
+    };
+    const sub = _nativeIos.ErxesNativeIOS.addActionListener(async id => {
+      var _onActionRef$current;
+      const action = actionsRef.current.find(item => item.id === id);
+      if (action !== null && action !== void 0 && action.onPress) {
+        await action.onPress(helpers);
+        return;
+      }
+      await ((_onActionRef$current = onActionRef.current) === null || _onActionRef$current === void 0 ? void 0 : _onActionRef$current.call(onActionRef, id, helpers));
+    });
+    async function setup() {
+      try {
+        onLoad === null || onLoad === void 0 ? void 0 : onLoad();
+        if (user) {
+          await _nativeIos.ErxesNativeIOS.setUser(user);
+        }
+        await _nativeIos.ErxesNativeIOS.configure({
+          integrationId,
+          endpoint,
+          serverUrl,
+          subDomain,
+          cachedCustomerId,
+          displayMode,
+          primaryColor,
+          homeActions: stripActions(homeActions),
+          drawerActions: stripActions(drawerActions)
+        });
+        onReady === null || onReady === void 0 ? void 0 : onReady();
+        if (autoOpen) {
+          await _nativeIos.ErxesNativeIOS.showMessenger();
+          onOpen === null || onOpen === void 0 ? void 0 : onOpen();
+        }
+        if (launcherVisible === true) {
+          await _nativeIos.ErxesNativeIOS.showLauncher();
+        } else if (launcherVisible === false) {
+          await _nativeIos.ErxesNativeIOS.hideLauncher();
+        }
+      } catch (error) {
+        onError === null || onError === void 0 ? void 0 : onError(error);
+      }
+    }
+    setup();
+    return () => {
+      sub.remove();
+      if (autoHideOnUnmount) {
+        _nativeIos.ErxesNativeIOS.hideMessenger();
+        onClose === null || onClose === void 0 ? void 0 : onClose();
+      }
+    };
+    // Re-run setup only when the native config identity changes; callbacks and
+    // actions are read through refs so they don't need to be deps here.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [integrationId, endpoint, serverUrl, subDomain, displayMode]);
+  (0, _react.useEffect)(() => {
+    if (_reactNative.Platform.OS !== 'ios' || visible === undefined) {
+      return;
+    }
+    if (visible) {
+      _nativeIos.ErxesNativeIOS.showMessenger();
+      onOpen === null || onOpen === void 0 ? void 0 : onOpen();
+    } else {
+      _nativeIos.ErxesNativeIOS.hideMessenger();
+      onClose === null || onClose === void 0 ? void 0 : onClose();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [visible]);
+  return null;
+}
+//# sourceMappingURL=ErxesMessenger.js.map

package/lib/commonjs/ErxesMessenger.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","_reactNative","_nativeIos","stripActions","actions","map","_ref","onPress","_onPress","nativeAction","ErxesMessenger","_ref2","integrationId","endpoint","serverUrl","subDomain","displayMode","user","cachedCustomerId","primaryColor","visible","autoOpen","autoHideOnUnmount","launcherVisible","homeActions","drawerActions","onLoad","onReady","onOpen","onClose","onError","onAction","actionsRef","useRef","onActionRef","useEffect","current","Platform","OS","helpers","show","ErxesNativeIOS","showMessenger","hide","hideMessenger","showLauncher","hideLauncher","setUser","nextUser","clearUser","sub","addActionListener","id","_onActionRef$current","action","find","item","call","setup","configure","error","remove","undefined"],"sourceRoot":"../../src","sources":["ErxesMessenger.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AAEA,IAAAE,UAAA,GAAAF,OAAA;AAEA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;;AAUA;AACA;AACA;AACA;AACA;;AAiEA;AACA;AACA;AACA;AACA;AACA,SAASG,YAAYA,CAACC,OAAsB,EAAE;EAC5C,OAAOA,OAAO,CAACC,GAAG,CAACC,IAAA;IAAA,IAAC;MAAEC,OAAO,EAAEC,QAAQ;MAAE,GAAGC;IAAa,CAAC,GAAAH,IAAA;IAAA,OAAKG,YAAY;EAAA,EAAC;AAC9E;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,cAAcA,CAAAC,KAAA,EAqBN;EAAA,IArBO;IAC7BC,aAAa;IACbC,QAAQ;IACRC,SAAS;IACTC,SAAS;IACTC,WAAW,GAAG,SAAS;IACvBC,IAAI;IACJC,gBAAgB;IAChBC,YAAY;IACZC,OAAO;IACPC,QAAQ,GAAGL,WAAW,KAAK,MAAM;IACjCM,iBAAiB,GAAG,IAAI;IACxBC,eAAe;IACfC,WAAW,GAAG,EAAE;IAChBC,aAAa,GAAG,EAAE;IAClBC,MAAM;IACNC,OAAO;IACPC,MAAM;IACNC,OAAO;IACPC,OAAO;IACPC;EACmB,CAAC,GAAApB,KAAA;EACpB;EACA;EACA,MAAMqB,UAAU,GAAG,IAAAC,aAAM,EAAgB,EAAE,CAAC;EAC5C,MAAMC,WAAW,GAAG,IAAAD,aAAM,EAACF,QAAQ,CAAC;EAEpC,IAAAI,gBAAS,EAAC,MAAM;IACdH,UAAU,CAACI,OAAO,GAAG,CAAC,GAAGZ,WAAW,EAAE,GAAGC,aAAa,CAAC;IACvDS,WAAW,CAACE,OAAO,GAAGL,QAAQ;EAChC,CAAC,EAAE,CAACP,WAAW,EAAEC,aAAa,EAAEM,QAAQ,CAAC,CAAC;EAE1C,IAAAI,gBAAS,EAAC,MAAM;IACd,IAAIE,qBAAQ,CAACC,EAAE,KAAK,KAAK,EAAE;MACzB;IACF;IAEA,MAAMC,OAA8B,GAAG;MACrCC,IAAI,EAAEA,CAAA,KAAMC,yBAAc,CAACC,aAAa,CAAC,CAAC;MAC1CC,IAAI,EAAEA,CAAA,KAAMF,yBAAc,CAACG,aAAa,CAAC,CAAC;MAC1CC,YAAY,EAAEA,CAAA,KAAMJ,yBAAc,CAACI,YAAY,CAAC,CAAC;MACjDC,YAAY,EAAEA,CAAA,KAAML,yBAAc,CAACK,YAAY,CAAC,CAAC;MACjDC,OAAO,EAAGC,QAAQ,IAAKP,yBAAc,CAACM,OAAO,CAACC,QAAQ,CAAC;MACvDC,SAAS,EAAEA,CAAA,KAAMR,yBAAc,CAACQ,SAAS,CAAC;IAC5C,CAAC;IAED,MAAMC,GAAG,GAAGT,yBAAc,CAACU,iBAAiB,CAAC,MAAOC,EAAE,IAAK;MAAA,IAAAC,oBAAA;MACzD,MAAMC,MAAM,GAAGtB,UAAU,CAACI,OAAO,CAACmB,IAAI,CAAEC,IAAI,IAAKA,IAAI,CAACJ,EAAE,KAAKA,EAAE,CAAC;MAEhE,IAAIE,MAAM,aAANA,MAAM,eAANA,MAAM,CAAE/C,OAAO,EAAE;QACnB,MAAM+C,MAAM,CAAC/C,OAAO,CAACgC,OAAO,CAAC;QAC7B;MACF;MAEA,QAAAc,oBAAA,GAAMnB,WAAW,CAACE,OAAO,cAAAiB,oBAAA,uBAAnBA,oBAAA,CAAAI,IAAA,CAAAvB,WAAW,EAAWkB,EAAE,EAAEb,OAAO,CAAC;IAC1C,CAAC,CAAC;IAEF,eAAemB,KAAKA,CAAA,EAAG;MACrB,IAAI;QACFhC,MAAM,aAANA,MAAM,uBAANA,MAAM,CAAG,CAAC;QAEV,IAAIT,IAAI,EAAE;UACR,MAAMwB,yBAAc,CAACM,OAAO,CAAC9B,IAAI,CAAC;QACpC;QAEA,MAAMwB,yBAAc,CAACkB,SAAS,CAAC;UAC7B/C,aAAa;UACbC,QAAQ;UACRC,SAAS;UACTC,SAAS;UACTG,gBAAgB;UAChBF,WAAW;UACXG,YAAY;UACZK,WAAW,EAAErB,YAAY,CAACqB,WAAW,CAAC;UACtCC,aAAa,EAAEtB,YAAY,CAACsB,aAAa;QAC3C,CAAC,CAAC;QAEFE,OAAO,aAAPA,OAAO,uBAAPA,OAAO,CAAG,CAAC;QAEX,IAAIN,QAAQ,EAAE;UACZ,MAAMoB,yBAAc,CAACC,aAAa,CAAC,CAAC;UACpCd,MAAM,aAANA,MAAM,uBAANA,MAAM,CAAG,CAAC;QACZ;QAEA,IAAIL,eAAe,KAAK,IAAI,EAAE;UAC5B,MAAMkB,yBAAc,CAACI,YAAY,CAAC,CAAC;QACrC,CAAC,MAAM,IAAItB,eAAe,KAAK,KAAK,EAAE;UACpC,MAAMkB,yBAAc,CAACK,YAAY,CAAC,CAAC;QACrC;MACF,CAAC,CAAC,OAAOc,KAAK,EAAE;QACd9B,OAAO,aAAPA,OAAO,uBAAPA,OAAO,CAAG8B,KAAK,CAAC;MAClB;IACF;IAEAF,KAAK,CAAC,CAAC;IAEP,OAAO,MAAM;MACXR,GAAG,CAACW,MAAM,CAAC,CAAC;MAEZ,IAAIvC,iBAAiB,EAAE;QACrBmB,yBAAc,CAACG,aAAa,CAAC,CAAC;QAC9Bf,OAAO,aAAPA,OAAO,uBAAPA,OAAO,CAAG,CAAC;MACb;IACF,CAAC;IACD;IACA;IACA;EACF,CAAC,EAAE,CAACjB,aAAa,EAAEC,QAAQ,EAAEC,SAAS,EAAEC,SAAS,EAAEC,WAAW,CAAC,CAAC;EAEhE,IAAAmB,gBAAS,EAAC,MAAM;IACd,IAAIE,qBAAQ,CAACC,EAAE,KAAK,KAAK,IAAIlB,OAAO,KAAK0C,SAAS,EAAE;MAClD;IACF;IAEA,IAAI1C,OAAO,EAAE;MACXqB,yBAAc,CAACC,aAAa,CAAC,CAAC;MAC9Bd,MAAM,aAANA,MAAM,uBAANA,MAAM,CAAG,CAAC;IACZ,CAAC,MAAM;MACLa,yBAAc,CAACG,aAAa,CAAC,CAAC;MAC9Bf,OAAO,aAAPA,OAAO,uBAAPA,OAAO,CAAG,CAAC;IACb;IACA;EACF,CAAC,EAAE,CAACT,OAAO,CAAC,CAAC;EAEb,OAAO,IAAI;AACb"}

package/lib/commonjs/index.js

@@ -3,6 +3,12 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+Object.defineProperty(exports, "ErxesMessenger", {
+  enumerable: true,
+  get: function () {
+    return _ErxesMessenger.ErxesMessenger;
+  }
+});
 Object.defineProperty(exports, "ErxesNativeIOS", {
   enumerable: true,
   get: function () {
@@ -10,4 +16,5 @@ Object.defineProperty(exports, "ErxesNativeIOS", {
   }
 });
 var _nativeIos = require("./nativeIos");
+var _ErxesMessenger = require("./ErxesMessenger");
 //# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_nativeIos","require"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;;;;;;;;;;AAAA,IAAAA,UAAA,GAAAC,OAAA"}
+{"version":3,"names":["_nativeIos","require","_ErxesMessenger"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;;;;;;;;;;;;;;;;AAAA,IAAAA,UAAA,GAAAC,OAAA;AAOA,IAAAC,eAAA,GAAAD,OAAA"}

package/lib/module/ErxesMessenger.js

@@ -0,0 +1,155 @@
+import { useEffect, useRef } from 'react';
+import { Platform } from 'react-native';
+import { ErxesNativeIOS } from './nativeIos';
+
+/**
+ * The identified end user. Same shape the native bridge expects — passing
+ * `undefined` leaves the visitor anonymous until you call `setUser` later.
+ */
+
+/**
+ * Helpers handed to action `onPress` callbacks (and `onAction`) so you can drive
+ * the messenger imperatively from inside a tap handler — show/hide it, toggle the
+ * launcher, or swap the user.
+ */
+
+/**
+ * A chat-mode action rendered in the header (`homeActions`) or drawer
+ * (`drawerActions`). Only `id`/`title`/`systemIcon` cross the native bridge; the
+ * `onPress` callback stays in JS and runs when the matching action is tapped.
+ */
+
+/**
+ * Drop `onPress` so only the data-only fields the native bridge understands
+ * (`id`/`title`/`systemIcon`) cross over. React Native cannot send JS functions
+ * to native, so `onPress` is dispatched on the JS side via the action listener.
+ */
+function stripActions(actions) {
+  return actions.map(_ref => {
+    let {
+      onPress: _onPress,
+      ...nativeAction
+    } = _ref;
+    return nativeAction;
+  });
+}
+
+/**
+ * Declarative wrapper around {@link ErxesNativeIOS}. Configures the native erxes
+ * messenger, wires up action taps, and manages the show/hide lifecycle so app
+ * code stays a single component. Renders nothing — the messenger UI is presented
+ * natively over your app.
+ *
+ * For advanced/imperative control, use `ErxesNativeIOS` directly.
+ */
+export function ErxesMessenger(_ref2) {
+  let {
+    integrationId,
+    endpoint,
+    serverUrl,
+    subDomain,
+    displayMode = 'classic',
+    user,
+    cachedCustomerId,
+    primaryColor,
+    visible,
+    autoOpen = displayMode === 'chat',
+    autoHideOnUnmount = true,
+    launcherVisible,
+    homeActions = [],
+    drawerActions = [],
+    onLoad,
+    onReady,
+    onOpen,
+    onClose,
+    onError,
+    onAction
+  } = _ref2;
+  // Keep the latest actions/callback in refs so the action listener (registered
+  // once below) always dispatches against current props without re-subscribing.
+  const actionsRef = useRef([]);
+  const onActionRef = useRef(onAction);
+  useEffect(() => {
+    actionsRef.current = [...homeActions, ...drawerActions];
+    onActionRef.current = onAction;
+  }, [homeActions, drawerActions, onAction]);
+  useEffect(() => {
+    if (Platform.OS !== 'ios') {
+      return;
+    }
+    const helpers = {
+      show: () => ErxesNativeIOS.showMessenger(),
+      hide: () => ErxesNativeIOS.hideMessenger(),
+      showLauncher: () => ErxesNativeIOS.showLauncher(),
+      hideLauncher: () => ErxesNativeIOS.hideLauncher(),
+      setUser: nextUser => ErxesNativeIOS.setUser(nextUser),
+      clearUser: () => ErxesNativeIOS.clearUser()
+    };
+    const sub = ErxesNativeIOS.addActionListener(async id => {
+      var _onActionRef$current;
+      const action = actionsRef.current.find(item => item.id === id);
+      if (action !== null && action !== void 0 && action.onPress) {
+        await action.onPress(helpers);
+        return;
+      }
+      await ((_onActionRef$current = onActionRef.current) === null || _onActionRef$current === void 0 ? void 0 : _onActionRef$current.call(onActionRef, id, helpers));
+    });
+    async function setup() {
+      try {
+        onLoad === null || onLoad === void 0 ? void 0 : onLoad();
+        if (user) {
+          await ErxesNativeIOS.setUser(user);
+        }
+        await ErxesNativeIOS.configure({
+          integrationId,
+          endpoint,
+          serverUrl,
+          subDomain,
+          cachedCustomerId,
+          displayMode,
+          primaryColor,
+          homeActions: stripActions(homeActions),
+          drawerActions: stripActions(drawerActions)
+        });
+        onReady === null || onReady === void 0 ? void 0 : onReady();
+        if (autoOpen) {
+          await ErxesNativeIOS.showMessenger();
+          onOpen === null || onOpen === void 0 ? void 0 : onOpen();
+        }
+        if (launcherVisible === true) {
+          await ErxesNativeIOS.showLauncher();
+        } else if (launcherVisible === false) {
+          await ErxesNativeIOS.hideLauncher();
+        }
+      } catch (error) {
+        onError === null || onError === void 0 ? void 0 : onError(error);
+      }
+    }
+    setup();
+    return () => {
+      sub.remove();
+      if (autoHideOnUnmount) {
+        ErxesNativeIOS.hideMessenger();
+        onClose === null || onClose === void 0 ? void 0 : onClose();
+      }
+    };
+    // Re-run setup only when the native config identity changes; callbacks and
+    // actions are read through refs so they don't need to be deps here.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [integrationId, endpoint, serverUrl, subDomain, displayMode]);
+  useEffect(() => {
+    if (Platform.OS !== 'ios' || visible === undefined) {
+      return;
+    }
+    if (visible) {
+      ErxesNativeIOS.showMessenger();
+      onOpen === null || onOpen === void 0 ? void 0 : onOpen();
+    } else {
+      ErxesNativeIOS.hideMessenger();
+      onClose === null || onClose === void 0 ? void 0 : onClose();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [visible]);
+  return null;
+}
+//# sourceMappingURL=ErxesMessenger.js.map

package/lib/module/ErxesMessenger.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["useEffect","useRef","Platform","ErxesNativeIOS","stripActions","actions","map","_ref","onPress","_onPress","nativeAction","ErxesMessenger","_ref2","integrationId","endpoint","serverUrl","subDomain","displayMode","user","cachedCustomerId","primaryColor","visible","autoOpen","autoHideOnUnmount","launcherVisible","homeActions","drawerActions","onLoad","onReady","onOpen","onClose","onError","onAction","actionsRef","onActionRef","current","OS","helpers","show","showMessenger","hide","hideMessenger","showLauncher","hideLauncher","setUser","nextUser","clearUser","sub","addActionListener","id","_onActionRef$current","action","find","item","call","setup","configure","error","remove","undefined"],"sourceRoot":"../../src","sources":["ErxesMessenger.tsx"],"mappings":"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"}

package/lib/module/index.js

@@ -1,2 +1,3 @@
 export { ErxesNativeIOS } from './nativeIos';
+export { ErxesMessenger } from './ErxesMessenger';
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["ErxesNativeIOS"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":"AAAA,SAASA,cAAc,QAAQ,aAAa"}
+{"version":3,"names":["ErxesNativeIOS","ErxesMessenger"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":"AAAA,SAASA,cAAc,QAAQ,aAAa;AAO5C,SAASC,cAAc,QAAQ,kBAAkB"}

package/lib/typescript/ErxesMessenger.d.ts

@@ -0,0 +1,86 @@
+import { type NativeIOSUser } from './nativeIos';
+/**
+ * The identified end user. Same shape the native bridge expects — passing
+ * `undefined` leaves the visitor anonymous until you call `setUser` later.
+ */
+export type ErxesUser = NativeIOSUser;
+/**
+ * Helpers handed to action `onPress` callbacks (and `onAction`) so you can drive
+ * the messenger imperatively from inside a tap handler — show/hide it, toggle the
+ * launcher, or swap the user.
+ */
+export type ErxesMessengerHelpers = {
+    show: () => Promise<void>;
+    hide: () => Promise<void>;
+    showLauncher: () => Promise<void>;
+    hideLauncher: () => Promise<void>;
+    setUser: (user: ErxesUser) => Promise<void>;
+    clearUser: () => Promise<void>;
+};
+/**
+ * A chat-mode action rendered in the header (`homeActions`) or drawer
+ * (`drawerActions`). Only `id`/`title`/`systemIcon` cross the native bridge; the
+ * `onPress` callback stays in JS and runs when the matching action is tapped.
+ */
+export type ErxesAction = {
+    /** Identifier echoed back from native when the action is tapped. */
+    id: string;
+    /** Display title (drawer rows / accessibility label for header icons). */
+    title: string;
+    /** SF Symbol name, e.g. "person.crop.circle". */
+    systemIcon: string;
+    /** Runs when this action is tapped. Receives imperative {@link ErxesMessengerHelpers}. */
+    onPress?: (helpers: ErxesMessengerHelpers) => void | Promise<void>;
+};
+export type ErxesMessengerProps = {
+    /** erxes messenger integration id. Required. */
+    integrationId: string;
+    /** Full endpoint URL. Provide one of `endpoint`/`serverUrl`/`subDomain`. */
+    endpoint?: string;
+    /** Alias for `endpoint`. */
+    serverUrl?: string;
+    /** Sub-domain shorthand, e.g. `'yourcompany.erxes.io'`. */
+    subDomain?: string;
+    /** UI shell to present. Defaults to `'classic'` (the sheet-based widget). */
+    displayMode?: 'classic' | 'chat';
+    /** Identify the user before connecting. */
+    user?: ErxesUser;
+    /** Reuse a previously cached customer id. */
+    cachedCustomerId?: string;
+    /** Primary accent color as a hex string, e.g. `'#3f78d9'`. */
+    primaryColor?: string;
+    /** Controlled visibility. When set, drives show/hide on change. */
+    visible?: boolean;
+    /** Open the messenger once configured. Defaults to `true` in chat mode. */
+    autoOpen?: boolean;
+    /** Hide the messenger when the component unmounts. Defaults to `true`. */
+    autoHideOnUnmount?: boolean;
+    /** Show (`true`) or hide (`false`) the floating launcher after configure. */
+    launcherVisible?: boolean;
+    /** Chat-mode header-right actions. Ignored in `'classic'`. */
+    homeActions?: ErxesAction[];
+    /** Chat-mode drawer top action rows. Ignored in `'classic'`. */
+    drawerActions?: ErxesAction[];
+    /** Fired when setup starts. */
+    onLoad?: () => void;
+    /** Fired after native `configure` succeeds. */
+    onReady?: () => void;
+    /** Fired when the messenger is shown. */
+    onOpen?: () => void;
+    /** Fired when the messenger is hidden. */
+    onClose?: () => void;
+    /** Fired when setup/open/hide fails. */
+    onError?: (error: unknown) => void;
+    /** Fallback for tapped actions that have no `onPress`. */
+    onAction?: (id: string, helpers: ErxesMessengerHelpers) => void | Promise<void>;
+};
+/**
+ * Declarative wrapper around {@link ErxesNativeIOS}. Configures the native erxes
+ * messenger, wires up action taps, and manages the show/hide lifecycle so app
+ * code stays a single component. Renders nothing — the messenger UI is presented
+ * natively over your app.
+ *
+ * For advanced/imperative control, use `ErxesNativeIOS` directly.
+ */
+export declare function ErxesMessenger({ integrationId, endpoint, serverUrl, subDomain, displayMode, user, cachedCustomerId, primaryColor, visible, autoOpen, autoHideOnUnmount, launcherVisible, homeActions, drawerActions, onLoad, onReady, onOpen, onClose, onError, onAction, }: ErxesMessengerProps): null;
+//# sourceMappingURL=ErxesMessenger.d.ts.map

package/lib/typescript/ErxesMessenger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErxesMessenger.d.ts","sourceRoot":"","sources":["../../src/ErxesMessenger.tsx"],"names":[],"mappings":"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"}

package/lib/typescript/index.d.ts

@@ -1,3 +1,5 @@
 export { ErxesNativeIOS } from './nativeIos';
 export type { NativeIOSAction, NativeIOSConfig, NativeIOSUser, } from './nativeIos';
+export { ErxesMessenger } from './ErxesMessenger';
+export type { ErxesUser, ErxesAction, ErxesMessengerHelpers, ErxesMessengerProps, } from './ErxesMessenger';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACV,eAAe,EACf,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACV,eAAe,EACf,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EACV,SAAS,EACT,WAAW,EACX,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-erxes-sdk",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "react-native erxes sdk",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",

package/src/ErxesMessenger.tsx

@@ -0,0 +1,237 @@
+import { useEffect, useRef } from 'react';
+import { Platform } from 'react-native';
+
+import { ErxesNativeIOS, type NativeIOSUser } from './nativeIos';
+
+/**
+ * The identified end user. Same shape the native bridge expects — passing
+ * `undefined` leaves the visitor anonymous until you call `setUser` later.
+ */
+export type ErxesUser = NativeIOSUser;
+
+/**
+ * Helpers handed to action `onPress` callbacks (and `onAction`) so you can drive
+ * the messenger imperatively from inside a tap handler — show/hide it, toggle the
+ * launcher, or swap the user.
+ */
+export type ErxesMessengerHelpers = {
+  show: () => Promise<void>;
+  hide: () => Promise<void>;
+  showLauncher: () => Promise<void>;
+  hideLauncher: () => Promise<void>;
+  setUser: (user: ErxesUser) => Promise<void>;
+  clearUser: () => Promise<void>;
+};
+
+/**
+ * A chat-mode action rendered in the header (`homeActions`) or drawer
+ * (`drawerActions`). Only `id`/`title`/`systemIcon` cross the native bridge; the
+ * `onPress` callback stays in JS and runs when the matching action is tapped.
+ */
+export type ErxesAction = {
+  /** Identifier echoed back from native when the action is tapped. */
+  id: string;
+  /** Display title (drawer rows / accessibility label for header icons). */
+  title: string;
+  /** SF Symbol name, e.g. "person.crop.circle". */
+  systemIcon: string;
+  /** Runs when this action is tapped. Receives imperative {@link ErxesMessengerHelpers}. */
+  onPress?: (helpers: ErxesMessengerHelpers) => void | Promise<void>;
+};
+
+export type ErxesMessengerProps = {
+  /** erxes messenger integration id. Required. */
+  integrationId: string;
+
+  /** Full endpoint URL. Provide one of `endpoint`/`serverUrl`/`subDomain`. */
+  endpoint?: string;
+  /** Alias for `endpoint`. */
+  serverUrl?: string;
+  /** Sub-domain shorthand, e.g. `'yourcompany.erxes.io'`. */
+  subDomain?: string;
+
+  /** UI shell to present. Defaults to `'classic'` (the sheet-based widget). */
+  displayMode?: 'classic' | 'chat';
+
+  /** Identify the user before connecting. */
+  user?: ErxesUser;
+  /** Reuse a previously cached customer id. */
+  cachedCustomerId?: string;
+
+  /** Primary accent color as a hex string, e.g. `'#3f78d9'`. */
+  primaryColor?: string;
+
+  /** Controlled visibility. When set, drives show/hide on change. */
+  visible?: boolean;
+  /** Open the messenger once configured. Defaults to `true` in chat mode. */
+  autoOpen?: boolean;
+  /** Hide the messenger when the component unmounts. Defaults to `true`. */
+  autoHideOnUnmount?: boolean;
+  /** Show (`true`) or hide (`false`) the floating launcher after configure. */
+  launcherVisible?: boolean;
+
+  /** Chat-mode header-right actions. Ignored in `'classic'`. */
+  homeActions?: ErxesAction[];
+  /** Chat-mode drawer top action rows. Ignored in `'classic'`. */
+  drawerActions?: ErxesAction[];
+
+  /** Fired when setup starts. */
+  onLoad?: () => void;
+  /** Fired after native `configure` succeeds. */
+  onReady?: () => void;
+  /** Fired when the messenger is shown. */
+  onOpen?: () => void;
+  /** Fired when the messenger is hidden. */
+  onClose?: () => void;
+  /** Fired when setup/open/hide fails. */
+  onError?: (error: unknown) => void;
+  /** Fallback for tapped actions that have no `onPress`. */
+  onAction?: (
+    id: string,
+    helpers: ErxesMessengerHelpers
+  ) => void | Promise<void>;
+};
+
+/**
+ * Drop `onPress` so only the data-only fields the native bridge understands
+ * (`id`/`title`/`systemIcon`) cross over. React Native cannot send JS functions
+ * to native, so `onPress` is dispatched on the JS side via the action listener.
+ */
+function stripActions(actions: ErxesAction[]) {
+  return actions.map(({ onPress: _onPress, ...nativeAction }) => nativeAction);
+}
+
+/**
+ * Declarative wrapper around {@link ErxesNativeIOS}. Configures the native erxes
+ * messenger, wires up action taps, and manages the show/hide lifecycle so app
+ * code stays a single component. Renders nothing — the messenger UI is presented
+ * natively over your app.
+ *
+ * For advanced/imperative control, use `ErxesNativeIOS` directly.
+ */
+export function ErxesMessenger({
+  integrationId,
+  endpoint,
+  serverUrl,
+  subDomain,
+  displayMode = 'classic',
+  user,
+  cachedCustomerId,
+  primaryColor,
+  visible,
+  autoOpen = displayMode === 'chat',
+  autoHideOnUnmount = true,
+  launcherVisible,
+  homeActions = [],
+  drawerActions = [],
+  onLoad,
+  onReady,
+  onOpen,
+  onClose,
+  onError,
+  onAction,
+}: ErxesMessengerProps) {
+  // Keep the latest actions/callback in refs so the action listener (registered
+  // once below) always dispatches against current props without re-subscribing.
+  const actionsRef = useRef<ErxesAction[]>([]);
+  const onActionRef = useRef(onAction);
+
+  useEffect(() => {
+    actionsRef.current = [...homeActions, ...drawerActions];
+    onActionRef.current = onAction;
+  }, [homeActions, drawerActions, onAction]);
+
+  useEffect(() => {
+    if (Platform.OS !== 'ios') {
+      return;
+    }
+
+    const helpers: ErxesMessengerHelpers = {
+      show: () => ErxesNativeIOS.showMessenger(),
+      hide: () => ErxesNativeIOS.hideMessenger(),
+      showLauncher: () => ErxesNativeIOS.showLauncher(),
+      hideLauncher: () => ErxesNativeIOS.hideLauncher(),
+      setUser: (nextUser) => ErxesNativeIOS.setUser(nextUser),
+      clearUser: () => ErxesNativeIOS.clearUser(),
+    };
+
+    const sub = ErxesNativeIOS.addActionListener(async (id) => {
+      const action = actionsRef.current.find((item) => item.id === id);
+
+      if (action?.onPress) {
+        await action.onPress(helpers);
+        return;
+      }
+
+      await onActionRef.current?.(id, helpers);
+    });
+
+    async function setup() {
+      try {
+        onLoad?.();
+
+        if (user) {
+          await ErxesNativeIOS.setUser(user);
+        }
+
+        await ErxesNativeIOS.configure({
+          integrationId,
+          endpoint,
+          serverUrl,
+          subDomain,
+          cachedCustomerId,
+          displayMode,
+          primaryColor,
+          homeActions: stripActions(homeActions),
+          drawerActions: stripActions(drawerActions),
+        });
+
+        onReady?.();
+
+        if (autoOpen) {
+          await ErxesNativeIOS.showMessenger();
+          onOpen?.();
+        }
+
+        if (launcherVisible === true) {
+          await ErxesNativeIOS.showLauncher();
+        } else if (launcherVisible === false) {
+          await ErxesNativeIOS.hideLauncher();
+        }
+      } catch (error) {
+        onError?.(error);
+      }
+    }
+
+    setup();
+
+    return () => {
+      sub.remove();
+
+      if (autoHideOnUnmount) {
+        ErxesNativeIOS.hideMessenger();
+        onClose?.();
+      }
+    };
+    // Re-run setup only when the native config identity changes; callbacks and
+    // actions are read through refs so they don't need to be deps here.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [integrationId, endpoint, serverUrl, subDomain, displayMode]);
+
+  useEffect(() => {
+    if (Platform.OS !== 'ios' || visible === undefined) {
+      return;
+    }
+
+    if (visible) {
+      ErxesNativeIOS.showMessenger();
+      onOpen?.();
+    } else {
+      ErxesNativeIOS.hideMessenger();
+      onClose?.();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [visible]);
+
+  return null;
+}

package/src/index.tsx

@@ -4,3 +4,11 @@ export type {
   NativeIOSConfig,
   NativeIOSUser,
 } from './nativeIos';
+
+export { ErxesMessenger } from './ErxesMessenger';
+export type {
+  ErxesUser,
+  ErxesAction,
+  ErxesMessengerHelpers,
+  ErxesMessengerProps,
+} from './ErxesMessenger';