@repzo/widget-react-native 1.0.0

package/src/index.tsx

@@ -0,0 +1,199 @@
+/**
+ * @repzo/widget-react-native — the Repzo chat widget for React Native.
+ *
+ * Pure JavaScript: no native modules, no config plugin, no pod install. The
+ * public surface mirrors `@intercom/intercom-react-native` so swapping the two
+ * is a rename at each call site.
+ */
+
+import { controller } from './controller';
+import { RepzoWidgetEvents, type EventSubscription, type RepzoWidgetEvent } from './events';
+import { setSecureStorageAdapter, setStorageAdapter } from './storage';
+import type {
+  BootOptions,
+  RepzoWidgetStorageAdapter,
+  WidgetCustomAttributes,
+  WidgetSpaceType,
+  WidgetUser,
+} from './types';
+
+export { RepzoWidgetProvider } from './ui/WidgetProvider';
+export { Launcher as RepzoWidgetLauncher } from './ui/components/Launcher';
+export { RepzoWidgetEvents } from './events';
+export { RepzoWidgetError } from './api/client';
+export { DEFAULT_BASE_URL } from './types';
+export { useWidgetState } from './state/use-widget-state';
+
+export type {
+  AgentUiAction,
+  AgentUiBlock,
+  BootOptions,
+  Conversation,
+  Message,
+  OutboundMessage,
+  PreChatField,
+  RepzoWidgetErrorCode,
+  RepzoWidgetStorageAdapter,
+  WidgetAttachment,
+  WidgetConfig,
+  WidgetCustomAttributes,
+  WidgetSpace,
+  WidgetSpaceType,
+  WidgetState,
+  WidgetUser,
+  WidgetView,
+} from './types';
+export type {
+  EventSubscription,
+  MessageDidArrivePayload,
+  RepzoWidgetEvent,
+  RepzoWidgetEventPayloads,
+} from './events';
+export type { WidgetTheme } from './ui/styles/theme';
+
+/** Spaces the widget can open into — the analogue of Intercom's `Space`. */
+export enum Space {
+  home = 'home',
+  messages = 'messages',
+}
+
+export type RepzoWidgetType = {
+  /**
+   * Start (or resume) a visitor session and connect realtime.
+   * Safe to call repeatedly — a boot for the same widget and user is a no-op,
+   * which matters because `POST /api/widget/init` is rate limited to 10/min.
+   */
+  boot(options: BootOptions): Promise<void>;
+
+  /**
+   * Drop any identity and start a fresh anonymous session. A previously
+   * identified user is fully signed out first (same as `logout()`).
+   */
+  loginUnidentifiedUser(): Promise<void>;
+
+  /**
+   * Identify the visitor. Requires `userId` or `email`; conversations started
+   * anonymously on this device move to the identified visitor. If a
+   * *different* identified user's session is stored, it is signed out first
+   * (same as `logout()`) — their conversations never carry over.
+   */
+  loginUserWithUserAttributes(user: WidgetUser): Promise<void>;
+
+  /**
+   * Attach custom attributes to the visitor's identity so agents see them on
+   * the conversation (max 30 keys, 64-char keys, 512-char values).
+   */
+  updateUser(attributes: WidgetCustomAttributes): Promise<void>;
+
+  /**
+   * Sign the visitor out — await it in your app's sign-out flow. Revokes the
+   * token server-side and removes the push registration (best-effort, 5s cap
+   * each), wipes every user-scoped key, rotates the anonymous device id,
+   * closes realtime and resets the UI. Nothing re-inits until the next
+   * `boot()` / login call.
+   */
+  logout(): Promise<void>;
+
+  /** Open the widget on its default space. */
+  present(): Promise<void>;
+
+  /** Open the widget on a specific space. */
+  presentSpace(space: Space | WidgetSpaceType): Promise<void>;
+
+  /** Open the widget directly on one conversation. */
+  presentConversation(conversationId: string): Promise<void>;
+
+  /** Dismiss the widget. */
+  hide(): Promise<void>;
+
+  /**
+   * Conversations with at least one unread team reply (Intercom's meaning).
+   * A thread stays unread until the visitor opens it — opening the messenger
+   * alone doesn't clear it.
+   */
+  getUnreadConversationCount(): Promise<number>;
+
+  /**
+   * Unread team replies across all conversations — the same number
+   * `UnreadCountDidChange` carries and the launcher badge shows.
+   */
+  getUnreadMessageCount(): Promise<number>;
+
+  /** Record an analytics event against the visitor. */
+  logEvent(eventName: string, metadata?: Record<string, unknown>): Promise<void>;
+
+  /** Switch the active translation locale. */
+  setLocale(locale: string): void;
+
+  /** Subscribe to `RepzoWidgetEvents.*`. Call `.remove()` on unmount. */
+  addEventListener<E extends RepzoWidgetEvent>(
+    event: E,
+    listener: (payload: any) => void
+  ): EventSubscription;
+
+  /** Key/value store for the device id, unread counts and cached theme. */
+  setStorageAdapter(adapter: RepzoWidgetStorageAdapter | null): void;
+
+  /**
+   * Keychain/Keystore-backed store for the visitor token and user key (e.g.
+   * `expo-secure-store`, `react-native-keychain` — see README). Without one
+   * they fall back to `setStorageAdapter`'s store. Call before `boot()`.
+   */
+  setSecureStorageAdapter(adapter: RepzoWidgetStorageAdapter | null): void;
+
+  /**
+   * Manually register an FCM device token for push notifications — the escape
+   * hatch for hosts without `@react-native-firebase/messaging` (with it
+   * installed, `boot({ push: { enabled: true } })` handles everything).
+   */
+  setPushToken(options: { token: string; platform?: 'ios' | 'android'; bundleId?: string }): Promise<void>;
+};
+
+const RepzoWidget: RepzoWidgetType = {
+  boot: (options) => controller.store.boot(options),
+
+  loginUnidentifiedUser: () => controller.store.loginUnidentifiedUser(),
+
+  loginUserWithUserAttributes: (user) => controller.store.loginUserWithUserAttributes(user),
+
+  updateUser: (attributes) => controller.store.updateUser(attributes),
+
+  logout: () => controller.store.logout(),
+
+  present: async () => {
+    controller.store.present();
+  },
+
+  presentSpace: async (space) => {
+    controller.store.present(space as WidgetSpaceType);
+  },
+
+  presentConversation: (conversationId) => controller.store.openConversation(conversationId),
+
+  hide: async () => {
+    controller.store.hide();
+  },
+
+  getUnreadConversationCount: async () =>
+    Object.values(controller.store.getState().unreadByConversation).filter((count) => count > 0)
+      .length,
+
+  getUnreadMessageCount: async () => controller.store.getState().unreadCount,
+
+  logEvent: async (eventName, metadata) => {
+    controller.store.track(eventName, metadata ?? {});
+  },
+
+  setLocale: (locale) => controller.store.setLocale(locale),
+
+  addEventListener: (event, listener) => controller.events.addListener(event, listener),
+
+  setStorageAdapter: (adapter) => setStorageAdapter(adapter),
+
+  setSecureStorageAdapter: (adapter) => setSecureStorageAdapter(adapter),
+
+  setPushToken: (options) => controller.store.push.setManualToken(options),
+};
+
+export default RepzoWidget;
+export { RepzoWidgetEvents as Events };

package/src/locales.ts

@@ -0,0 +1,80 @@
+/**
+ * Translations bundled with the SDK.
+ *
+ * A workspace can still override any key from the dashboard — those win. These
+ * exist so a widget running in a supported language is usable out of the box,
+ * instead of falling back to English for every string an admin has not filled
+ * in by hand.
+ *
+ * Keys mirror `DEFAULT_LABELS` in `./i18n`; `{token}` placeholders must be kept
+ * so word order stays under the translator's control.
+ */
+
+import type { DEFAULT_LABELS } from './i18n';
+
+type LabelMap = Partial<Record<keyof typeof DEFAULT_LABELS, string>>;
+
+const ar: LabelMap = {
+  back: 'رجوع',
+  loading: 'جارٍ التحميل...',
+  loadEarlier: 'تحميل الرسائل السابقة',
+  emptyConversation: 'أرسل رسالة لبدء المحادثة',
+  messagePlaceholder: 'اكتب رسالة...',
+  attachFile: 'إرفاق ملف',
+  failedToSend: 'تعذر الإرسال',
+  thinking: 'يكتب',
+  messages: 'الرسائل',
+  noMessages: 'لا توجد رسائل بعد',
+  historyHidden: 'سجل المحادثات مخفي',
+  startBelow: 'ابدأ محادثة من الأسفل',
+  preChatTitle: 'قبل أن نبدأ',
+  preChatSubtitle: 'أخبرنا قليلاً عنك حتى نتمكن من مساعدتك بشكل أفضل.',
+  preChatSkip: 'تخطٍ',
+  preChatSubmit: 'ابدأ المحادثة',
+  viewPreviousConversations: 'عرض المحادثات السابقة',
+  homeRecentTitle: 'الأحدث',
+  homeViewAllCount: 'عرض الكل ({count})',
+  homeNoConversations: 'ستظهر محادثاتك هنا',
+  homeStatusOnline: 'نحن متصلون',
+  homeStatusAway: 'نحن غير متصلين',
+  unreadBadge: '{count} غير مقروءة',
+  team: 'الفريق',
+  home: 'الرئيسية',
+  close: 'إغلاق',
+  retry: 'إعادة المحاولة',
+  connectionError: 'تعذر تحميل المحادثة. يرجى المحاولة مرة أخرى.',
+  connecting: 'جارٍ توصيلك بالفريق',
+  chatUnavailable: 'المحادثة غير متاحة حاليًا.',
+  identityVerificationError: 'تعذر التحقق من حسابك. يرجى تسجيل الدخول مرة أخرى.',
+  widgetCrashed: 'حدث خطأ ما.',
+  // Kept short: these sit in a tight row beside the agent's name.
+  timeJustNow: 'الآن',
+  timeMinutes: '{count} د',
+  timeHours: '{count} س',
+  timeDays: '{count} ي',
+  timeMonths: '{count} شهر',
+  timeYears: '{count} سنة',
+  today: 'اليوم',
+  yesterday: 'أمس',
+  conversationUpdated: 'تم تحديث المحادثة',
+  procedureSend: 'إرسال التفاصيل',
+  procedureSent: 'تم الإرسال',
+  fieldRequired: '{field} مطلوب',
+  invalidEmail: 'أدخل بريدًا إلكترونيًا صالحًا',
+  working: 'جارٍ العمل...',
+  outboundTitle: 'تحديث جديد',
+  outboundCta: 'اعرف المزيد',
+  dismiss: 'تجاهل',
+  blockService: 'خدمة',
+  blockProduct: 'منتج',
+  blockChooseTime: 'اختر وقتًا',
+  blockProfessional: 'الموظف',
+  blockPriceOffer: 'عرض سعر',
+};
+
+export const BUNDLED_TRANSLATIONS: Record<string, LabelMap> = { ar };
+
+/** `ar-JO`, `ar_SA` and `AR` all resolve to the `ar` bundle. */
+export function baseLanguage(locale?: string | null): string {
+  return (locale ?? '').split(/[-_]/)[0]?.toLowerCase() ?? '';
+}

package/src/push/push-notifications.ts

@@ -0,0 +1,254 @@
+/**
+ * FCM push notifications — optional.
+ *
+ * Powered by the HOST app's `@react-native-firebase/messaging` native module,
+ * loaded via a dynamic require so the SDK itself stays pure JavaScript. Hosts
+ * without Firebase installed get a warn-once no-op; hosts that can't install
+ * it can still register a token manually through `RepzoWidget.setPushToken()`.
+ *
+ * Supports both RNFB API generations: the modular API (`getMessaging()` etc.,
+ * the only one left in v26+) and the legacy namespaced `messaging()` factory.
+ *
+ * The Workstation channel must have its push provider set to FCM — with
+ * OneSignal selected these registrations are stored but unused.
+ */
+
+import { Platform } from 'react-native';
+import type { WidgetApiClient } from '../api/client';
+
+export interface WidgetPushOptions {
+  /** Register this device for FCM pushes after every successful session init. */
+  enabled?: boolean;
+  /**
+   * Ask for notification permission before registering (default true). Set
+   * false when the host app runs its own permission prompt.
+   */
+  requestPermission?: boolean;
+  /**
+   * The app's bundle id / package name. Lets a Workstation channel that serves
+   * several apps pick the matching Firebase key for this device's tokens.
+   * Optional for single-app channels.
+   */
+  bundleId?: string;
+}
+
+interface ManualToken {
+  token: string;
+  platform?: string;
+  bundleId?: string | null;
+}
+
+/** Version-agnostic view over the host's Firebase messaging module. */
+interface MessagingHandle {
+  requestPermission(): Promise<unknown>;
+  registerDeviceForRemoteMessages(): Promise<unknown>;
+  getToken(): Promise<string | null>;
+  onTokenRefresh(cb: (token: string) => void): void;
+  onNotificationOpenedApp(cb: (remoteMessage: any) => void): void;
+  getInitialNotification(): Promise<any>;
+}
+
+function resolveMessaging(): MessagingHandle | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+    const mod = require('@react-native-firebase/messaging');
+
+    // Modular API — the only one in RNFB v26+ (the namespaced default export
+    // was removed). Every call takes the messaging instance as its first arg.
+    if (typeof mod?.getMessaging === 'function') {
+      const instance = mod.getMessaging();
+      return {
+        requestPermission: () => mod.requestPermission(instance),
+        registerDeviceForRemoteMessages: () =>
+          typeof mod.registerDeviceForRemoteMessages === 'function'
+            ? mod.registerDeviceForRemoteMessages(instance)
+            : Promise.resolve(),
+        getToken: () => mod.getToken(instance),
+        onTokenRefresh: (cb) => mod.onTokenRefresh(instance, cb),
+        onNotificationOpenedApp: (cb) => mod.onNotificationOpenedApp(instance, cb),
+        getInitialNotification: () => mod.getInitialNotification(instance),
+      };
+    }
+
+    // Legacy namespaced API (RNFB <= v22): default export is a factory.
+    const factory = mod?.default ?? mod;
+    if (typeof factory !== 'function') return null;
+    const instance = factory();
+    if (!instance) return null;
+    return {
+      requestPermission: () => instance.requestPermission?.() ?? Promise.resolve(),
+      registerDeviceForRemoteMessages: () =>
+        typeof instance.registerDeviceForRemoteMessages === 'function'
+          ? instance.registerDeviceForRemoteMessages()
+          : Promise.resolve(),
+      getToken: () => instance.getToken(),
+      onTokenRefresh: (cb) => instance.onTokenRefresh?.(cb),
+      onNotificationOpenedApp: (cb) => instance.onNotificationOpenedApp?.(cb),
+      getInitialNotification: () => instance.getInitialNotification?.() ?? Promise.resolve(null),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export class PushManager {
+  private options: WidgetPushOptions = {};
+
+  private listenersWired = false;
+
+  private lastToken: string | null = null;
+
+  private manualToken: ManualToken | null = null;
+
+  private warnedMissingModule = false;
+
+  /** False while signed out — token refreshes must not register anywhere. */
+  private active = false;
+
+  /** Registrations still on the wire; unregister() waits for them. */
+  private inflight = new Set<Promise<void>>();
+
+  constructor(
+    private client: WidgetApiClient,
+    private openConversation: (conversationId: string) => void
+  ) {}
+
+  /** Remember the boot options; actual work happens in start() post-init. */
+  configure(options?: WidgetPushOptions) {
+    this.options = options ?? {};
+  }
+
+  /**
+   * Called after every successful session init — the widget token is valid
+   * from here. Re-running after a login switch re-registers the token under
+   * the new identity (the server upsert moves it).
+   */
+  async start(): Promise<void> {
+    this.active = true;
+    if (this.manualToken) {
+      await this.register(this.manualToken);
+    }
+    if (!this.options.enabled) return;
+
+    const messaging = resolveMessaging();
+    if (!messaging) {
+      if (!this.warnedMissingModule) {
+        this.warnedMissingModule = true;
+        console.warn(
+          '[repzo-widget] push is enabled but @react-native-firebase/messaging is not installed — ' +
+            'install it in the app, or provide a token via RepzoWidget.setPushToken()'
+        );
+      }
+      return;
+    }
+
+    try {
+      if (this.options.requestPermission !== false) {
+        // A denial isn't an error: getToken still succeeds, the OS just
+        // won't display anything until the user flips the setting.
+        await messaging.requestPermission();
+      }
+    } catch {
+      // Permission prompt unavailable (e.g. older Android) — keep going.
+    }
+
+    // Wired once and kept for the app's lifetime — taps must work even while
+    // the widget UI is closed, so there is deliberately no teardown.
+    if (!this.listenersWired) {
+      this.listenersWired = true;
+      this.wireTapHandlers(messaging);
+      messaging.onTokenRefresh((token: string) => {
+        void this.register({ token });
+      });
+    }
+
+    // iOS needs the APNs registration before an FCM token exists; RNFB
+    // auto-registers by default, this covers hosts that turned that off.
+    try {
+      await messaging.registerDeviceForRemoteMessages();
+    } catch {
+      // Already registered, or simulator without push support — getToken
+      // decides whether that actually matters.
+    }
+
+    try {
+      const token = await messaging.getToken();
+      if (token) await this.register({ token });
+    } catch (error) {
+      console.warn('[repzo-widget] push token fetch failed', error);
+    }
+  }
+
+  /** Host-supplied token for apps without the Firebase module. */
+  async setManualToken(manual: ManualToken): Promise<void> {
+    this.manualToken = manual;
+    // Before boot (or after logout) it is only remembered; start() sends it.
+    if (this.active) await this.register(manual);
+  }
+
+  /**
+   * Called by logout with the session's token captured up front: the DELETE
+   * is authenticated with it explicitly and never triggers a re-init.
+   * Waits for an in-flight registration first so its token is not missed.
+   */
+  async unregister(authToken: string | null): Promise<void> {
+    this.active = false;
+    await Promise.all([...this.inflight]);
+    const token = this.lastToken;
+    this.lastToken = null;
+    if (!token || !authToken) return;
+    try {
+      await this.client.removePushToken(token, { authToken, skipReauth: true });
+    } catch (error) {
+      console.warn('[repzo-widget] push token removal failed', error);
+    }
+  }
+
+  private register(manual: ManualToken): Promise<void> {
+    if (!this.active) return Promise.resolve();
+    const run = this.client
+      .registerPushToken({
+        token: manual.token,
+        platform: manual.platform ?? (Platform.OS === 'ios' ? 'ios' : 'android'),
+        bundleId: manual.bundleId ?? this.options.bundleId ?? undefined,
+      })
+      .then(
+        () => {
+          this.lastToken = manual.token;
+        },
+        (error) => {
+          console.warn('[repzo-widget] push token registration failed', error);
+        }
+      )
+      .finally(() => {
+        this.inflight.delete(run);
+      });
+    this.inflight.add(run);
+    return run;
+  }
+
+  private wireTapHandlers(messaging: MessagingHandle) {
+    // Background → tapped: the app was alive, just not in front.
+    messaging.onNotificationOpenedApp((remoteMessage: any) => {
+      this.handleTap(remoteMessage);
+    });
+
+    // Killed → tapped: the click that launched the app.
+    void messaging
+      .getInitialNotification()
+      .then((remoteMessage: any) => {
+        if (remoteMessage) this.handleTap(remoteMessage);
+      })
+      .catch(() => {});
+  }
+
+  /** Only widget pushes are ours — host app notifications pass through. */
+  private handleTap(remoteMessage: any) {
+    const data = remoteMessage?.data;
+    if (data?.document_type !== 'widget_message') return;
+    const conversationId = data?.document_id;
+    if (typeof conversationId === 'string' && conversationId) {
+      this.openConversation(conversationId);
+    }
+  }
+}

package/src/state/use-widget-state.ts

@@ -0,0 +1,20 @@
+/**
+ * React binding for the store. The store lives in the controller singleton, so
+ * the widget keeps its session, SSE stream and unread count even when no
+ * component is mounted; this hook only subscribes to it.
+ */
+
+import { useSyncExternalStore } from 'react';
+
+import { controller } from '../controller';
+import type { WidgetState } from '../types';
+import type { WidgetStore } from './widget-store';
+
+export function useWidgetState(): WidgetState {
+  const store = controller.store;
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}
+
+export function useWidgetStore(): WidgetStore {
+  return controller.store;
+}