@repzo/widget-react-native 1.0.0

package/src/api/realtime.ts

@@ -0,0 +1,225 @@
+/**
+ * SSE transport over `GET /api/widget/sse`, authenticated with an
+ * `Authorization: Bearer` header (never the query string, which ends up in
+ * proxy and server access logs).
+ *
+ * Uses React Native's streaming XMLHttpRequest and handles both network
+ * failures and successful stream EOF with exponential reconnect backoff.
+ * Auth failures never retry here: 401 hands over to the store's re-init,
+ * while 403 is terminal.
+ */
+
+import type { WidgetRealtimeEvent } from '../types';
+import { RepzoWidgetError } from './client';
+import { SseParser } from './sse-parser';
+
+/** Server event names, mapped to the shorter names the store switches on. */
+const SERVER_EVENTS = {
+  connected: 'connected',
+  'widget.message.new': 'message.new',
+  'widget.typing.start': 'typing.start',
+  'widget.typing.stop': 'typing.stop',
+  'widget.conversation.updated': 'conversation.updated',
+  'widget.conversation.event': 'conversation.event',
+} as const;
+
+type ServerEventName = keyof typeof SERVER_EVENTS;
+
+const BASE_RECONNECT_MS = 1_000;
+const MAX_RECONNECT_MS = 60_000;
+/** XHR readyState DONE — the error body is only complete from here. */
+const XHR_DONE = 4;
+/** If DONE never follows a 403 seen mid-body, act on what arrived. */
+const AUTH_ERROR_BODY_WAIT_MS = 3_000;
+
+export type RealtimeHandler = (event: WidgetRealtimeEvent, data: any) => void;
+
+export interface RealtimeAuthHooks {
+  /** 401: the token expired or was revoked. The stream stays closed. */
+  onUnauthorized(token: string): void;
+  /** 403 (e.g. `messenger_api_disabled`): terminal, the stream stays closed. */
+  onForbidden(error: RepzoWidgetError): void;
+}
+
+export class WidgetRealtime {
+  private source: XMLHttpRequest | null = null;
+
+  private connected = false;
+
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  private attempt = 0;
+
+  private closedByUs = false;
+
+  private url: string | null = null;
+
+  private token: string | null = null;
+
+  private handler: RealtimeHandler | null = null;
+
+  private authHooks: RealtimeAuthHooks | null = null;
+
+  private authErrorTimer: ReturnType<typeof setTimeout> | null = null;
+
+  connect(
+    baseUrl: string,
+    token: string,
+    handler: RealtimeHandler,
+    authHooks?: RealtimeAuthHooks
+  ): void {
+    this.close();
+    this.url = `${baseUrl.replace(/\/$/, '')}/api/widget/sse`;
+    this.token = token;
+    this.handler = handler;
+    this.authHooks = authHooks ?? null;
+    this.closedByUs = false;
+    this.open();
+  }
+
+  private open(): void {
+    if (!this.url || !this.token || !this.handler) return;
+
+    const source = new XMLHttpRequest();
+    this.source = source;
+    let offset = 0;
+    const isCurrent = () => this.source === source && !this.closedByUs;
+    const parser = new SseParser((name, raw) => {
+      if (!isCurrent() || !Object.prototype.hasOwnProperty.call(SERVER_EVENTS, name)) return;
+      let payload: unknown = null;
+      if (raw) {
+        try {
+          payload = JSON.parse(raw);
+        } catch {
+          payload = raw;
+        }
+      }
+      this.handler?.(SERVER_EVENTS[name as ServerEventName], payload);
+    });
+    const reconnect = () => {
+      if (!isCurrent()) return;
+      this.handler?.('error', null);
+      // A handler may synchronously close or replace this connection.
+      if (isCurrent()) this.scheduleReconnect();
+    };
+    const read = () => {
+      if (!isCurrent() || source.readyState < 3) return;
+      const complete = source.readyState === XHR_DONE;
+      const status = source.status;
+      if (status === 401 || status === 403) {
+        if (!complete && status === 403) {
+          // Wait for the structured error body, but never wait indefinitely.
+          this.authErrorTimer ??= setTimeout(() => {
+            if (isCurrent()) this.handleAuthError(status, source.responseText);
+          }, AUTH_ERROR_BODY_WAIT_MS);
+          return;
+        }
+        this.handleAuthError(status, source.responseText);
+        return;
+      }
+      if (status >= 200 && status < 300) {
+        if (!this.connected) {
+          this.connected = true;
+          this.attempt = 0;
+        }
+        const text = source.responseText || '';
+        const chunk = text.slice(offset);
+        offset = text.length;
+        parser.push(chunk);
+        // A 200 EOF is a disconnected stream too. Tear it down and notify the
+        // store so the next `connected` event also triggers history catch-up.
+        if (complete) reconnect();
+      } else if (complete) {
+        reconnect();
+      }
+    };
+    source.onreadystatechange = read;
+    source.onprogress = read;
+    source.onerror = reconnect;
+    source.ontimeout = reconnect;
+    source.onabort = reconnect;
+    try {
+      source.open('GET', this.url, true);
+      source.timeout = 0;
+      source.setRequestHeader('Accept', 'text/event-stream');
+      source.setRequestHeader('Cache-Control', 'no-cache');
+      source.setRequestHeader('Authorization', `Bearer ${this.token}`);
+      source.send();
+    } catch {
+      reconnect();
+    }
+  }
+
+  private handleAuthError(status: number, rawBody: string | null | undefined): void {
+    const token = this.token;
+    const hooks = this.authHooks;
+    // Backoff cannot fix an auth failure — stop and let the store decide.
+    this.close();
+    if (!hooks || !token) return;
+    if (status === 401) {
+      hooks.onUnauthorized(token);
+      return;
+    }
+    let body: unknown = null;
+    try {
+      body = rawBody ? JSON.parse(rawBody) : null;
+    } catch {
+      body = null;
+    }
+    hooks.onForbidden(RepzoWidgetError.fromResponse(403, body));
+  }
+
+  private scheduleReconnect(): void {
+    if (this.closedByUs || this.reconnectTimer) return;
+
+    this.teardownSource();
+
+    const delay = Math.min(BASE_RECONNECT_MS * 2 ** this.attempt, MAX_RECONNECT_MS);
+    // Jitter keeps a fleet of devices from reconnecting in lockstep.
+    const jittered = delay * (0.7 + Math.random() * 0.6);
+    this.attempt += 1;
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      if (this.closedByUs) return;
+      this.open();
+    }, jittered);
+  }
+
+  private teardownSource(): void {
+    const source = this.source;
+    this.source = null;
+    this.connected = false;
+    if (this.authErrorTimer) {
+      clearTimeout(this.authErrorTimer);
+      this.authErrorTimer = null;
+    }
+    if (!source) return;
+    source.onreadystatechange = null;
+    source.onprogress = null;
+    source.onerror = null;
+    source.ontimeout = null;
+    source.onabort = null;
+    source.abort();
+  }
+
+  get isConnected(): boolean {
+    // Includes a handshake in progress so the store does not replace the
+    // connection that a successful re-init just started. EOF clears source.
+    return this.source !== null;
+  }
+
+  close(): void {
+    this.closedByUs = true;
+    this.attempt = 0;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.authErrorTimer) {
+      clearTimeout(this.authErrorTimer);
+      this.authErrorTimer = null;
+    }
+    this.teardownSource();
+  }
+}

package/src/api/sse-parser.ts

@@ -0,0 +1,51 @@
+/** Incremental SSE framing. A blank line dispatches an event; EOF alone does not. */
+export class SseParser {
+  private line = '';
+  private event = '';
+  private data: string[] = [];
+  private afterCR = false;
+  private atStart = true;
+
+  constructor(private readonly dispatch: (event: string, data: string) => void) {}
+
+  push(chunk: string): void {
+    for (const char of chunk) {
+      if (this.atStart) {
+        this.atStart = false;
+        if (char === '\uFEFF') continue;
+      }
+      if (this.afterCR) {
+        this.afterCR = false;
+        if (char === '\n') continue;
+      }
+      if (char === '\r' || char === '\n') {
+        const line = this.line;
+        this.line = '';
+        this.afterCR = char === '\r';
+        this.readLine(line);
+      } else {
+        this.line += char;
+      }
+    }
+  }
+
+  private readLine(line: string): void {
+    if (!line) {
+      const event = this.event || 'message';
+      const data = this.data;
+      this.event = '';
+      this.data = [];
+      if (data.length) this.dispatch(event, data.join('\n'));
+      return;
+    }
+    if (line.startsWith(':')) return; // heartbeat/comment
+    const colon = line.indexOf(':');
+    const field = colon < 0 ? line : line.slice(0, colon);
+    let value = colon < 0 ? '' : line.slice(colon + 1);
+    if (value.startsWith(' ')) value = value.slice(1);
+    if (field === 'event') this.event = value;
+    if (field === 'data') this.data.push(value);
+    // Reconnect timing belongs to the transport. The store catches up from
+    // history on reconnect, so no server retry/id fields are needed here.
+  }
+}

package/src/controller.ts

@@ -0,0 +1,20 @@
+/**
+ * Process-wide singleton that owns the store (and therefore the session, the
+ * SSE stream and the unread count). Imperative API calls land here whether or
+ * not `<RepzoWidgetProvider>` is mounted; the provider is a pure subscriber, so
+ * commands issued before boot finishes simply land in state and render once the
+ * provider mounts.
+ */
+
+import { WidgetStore } from './state/widget-store';
+
+class RepzoWidgetController {
+  readonly store = new WidgetStore();
+
+  get events() {
+    return this.store.events;
+  }
+}
+
+export const controller = new RepzoWidgetController();
+export type { RepzoWidgetController };

package/src/device-id.ts

@@ -0,0 +1,71 @@
+/**
+ * Per-install id sent as `trackingVisitorId`. This is the mobile equivalent of
+ * the web widget's `repzo_vid` cookie: it lets the CRM stitch an anonymous
+ * visitor back together if the session token is ever lost. Stable until
+ * `logout()`, which rotates it.
+ */
+
+import { DEVICE_ID_KEY, Storage } from './storage';
+
+let cached: string | null = null;
+
+/**
+ * 16 random bytes from `crypto.getRandomValues` when the runtime has it (RN
+ * with a polyfill, newer Hermes); otherwise Math.random, which is fine for a
+ * correlation id but guessable.
+ */
+function randomBytes(): Uint8Array {
+  const bytes = new Uint8Array(16);
+  const cryptoApi = (globalThis as { crypto?: { getRandomValues?: (array: Uint8Array) => unknown } })
+    .crypto;
+  if (typeof cryptoApi?.getRandomValues === 'function') {
+    try {
+      cryptoApi.getRandomValues(bytes);
+      return bytes;
+    } catch {
+      // Present but unusable (some polyfills throw) — fall through.
+    }
+  }
+  for (let index = 0; index < bytes.length; index += 1) {
+    bytes[index] = (Math.random() * 256) | 0;
+  }
+  return bytes;
+}
+
+/** RFC-4122 v4. */
+function uuidv4(): string {
+  const bytes = randomBytes();
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC-4122 variant
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export async function getDeviceId(): Promise<string> {
+  if (cached) return cached;
+
+  const stored = await Storage.getItem(DEVICE_ID_KEY);
+  if (stored) {
+    cached = stored;
+    return stored;
+  }
+
+  const created = uuidv4();
+  cached = created;
+  await Storage.setItem(DEVICE_ID_KEY, created);
+  return created;
+}
+
+/** Only used by tests and `rotateDeviceId()`. */
+export function resetDeviceIdCache(): void {
+  cached = null;
+}
+
+/**
+ * Called by `logout()`: the id stitches anonymous sessions together, so on a
+ * shared device the next visitor must not inherit the previous user's.
+ */
+export async function rotateDeviceId(): Promise<void> {
+  cached = null;
+  await Storage.removeItem(DEVICE_ID_KEY);
+}

package/src/events.ts

@@ -0,0 +1,74 @@
+/**
+ * Tiny typed event emitter. Pure JS — no NativeEventEmitter, so listeners work
+ * identically on iOS, Android and in tests.
+ */
+
+import type { Conversation, Message } from './types';
+
+export const RepzoWidgetEvents = {
+  UnreadCountDidChange: 'repzoWidget.unreadCountDidChange',
+  MessageDidArrive: 'repzoWidget.messageDidArrive',
+  /** The visitor opened a thread — hosts use it to dismiss that conversation's push notification. */
+  ConversationDidRead: 'repzoWidget.conversationDidRead',
+  WindowDidShow: 'repzoWidget.windowDidShow',
+  WindowDidHide: 'repzoWidget.windowDidHide',
+} as const;
+
+export type RepzoWidgetEvent = (typeof RepzoWidgetEvents)[keyof typeof RepzoWidgetEvents];
+
+export interface MessageDidArrivePayload {
+  conversationId: string;
+  message: Message;
+  /** Null when the reply lands before this device has listed the thread. */
+  conversation: Conversation | null;
+}
+
+export interface RepzoWidgetEventPayloads {
+  [RepzoWidgetEvents.UnreadCountDidChange]: { count: number };
+  [RepzoWidgetEvents.MessageDidArrive]: MessageDidArrivePayload;
+  [RepzoWidgetEvents.ConversationDidRead]: { conversationId: string };
+  [RepzoWidgetEvents.WindowDidShow]: undefined;
+  [RepzoWidgetEvents.WindowDidHide]: undefined;
+}
+
+export interface EventSubscription {
+  remove(): void;
+}
+
+type Listener = (payload: any) => void;
+
+export class EventEmitter {
+  private listeners = new Map<string, Set<Listener>>();
+
+  addListener<E extends RepzoWidgetEvent>(
+    event: E,
+    listener: (payload: RepzoWidgetEventPayloads[E]) => void
+  ): EventSubscription {
+    const current = this.listeners.get(event) ?? new Set<Listener>();
+    current.add(listener as Listener);
+    this.listeners.set(event, current);
+
+    return {
+      remove: () => {
+        this.listeners.get(event)?.delete(listener as Listener);
+      },
+    };
+  }
+
+  emit<E extends RepzoWidgetEvent>(event: E, payload: RepzoWidgetEventPayloads[E]): void {
+    const current = this.listeners.get(event);
+    if (!current) return;
+    // Copy first: a listener may remove itself while we iterate.
+    for (const listener of Array.from(current)) {
+      try {
+        listener(payload);
+      } catch (error) {
+        console.warn('[repzo-widget] event listener threw', error);
+      }
+    }
+  }
+
+  removeAllListeners(): void {
+    this.listeners.clear();
+  }
+}

package/src/i18n.ts

@@ -0,0 +1,114 @@
+/**
+ * Translations come from the widget config (`translations[locale][key]`), with
+ * the widget's default locale as the fallback chain — same lookup as the web
+ * widget's `t()` in `client/src/widget/App.tsx`.
+ */
+
+import { BUNDLED_TRANSLATIONS, baseLanguage } from './locales';
+import type { WidgetConfig } from './types';
+
+export type Translator = (key: string, fallback: string) => string;
+
+/**
+ * Resolution order, most specific first: what the workspace configured for the
+ * active locale, what the SDK ships for it, then the same pair for the
+ * workspace's default locale, and finally the English built-in. Dashboard
+ * copy always outranks a bundled translation.
+ */
+export function createTranslator(config: WidgetConfig | null, locale: string): Translator {
+  const defaultLocale = config?.defaultLocale || 'en';
+  const active = baseLanguage(locale);
+  const fallbackLocale = baseLanguage(defaultLocale);
+
+  return (key, fallback) =>
+    config?.translations?.[locale]?.[key] ||
+    config?.translations?.[active]?.[key] ||
+    BUNDLED_TRANSLATIONS[active]?.[key as keyof typeof DEFAULT_LABELS] ||
+    config?.translations?.[defaultLocale]?.[key] ||
+    BUNDLED_TRANSLATIONS[fallbackLocale]?.[key as keyof typeof DEFAULT_LABELS] ||
+    fallback;
+}
+
+export const DEFAULT_LABELS = {
+  back: 'Back',
+  loading: 'Loading...',
+  loadEarlier: 'Load earlier messages',
+  emptyConversation: 'Send a message to start the conversation',
+  messagePlaceholder: 'Type a message...',
+  attachFile: 'Attach file',
+  failedToSend: 'Failed to send',
+  thinking: 'Typing',
+  messages: 'Messages',
+  noMessages: 'No messages yet',
+  historyHidden: 'Conversation history is hidden',
+  startBelow: 'Start a conversation below',
+  preChatTitle: 'Before we chat',
+  preChatSubtitle: 'Let us know a bit about you so we can help you better.',
+  preChatSkip: 'Skip',
+  preChatSubmit: 'Start chat',
+  viewPreviousConversations: 'View previous conversations',
+  homeRecentTitle: 'Recent',
+  homeViewAllCount: 'View all ({count})',
+  homeNoConversations: 'Your conversations will show up here',
+  homeStatusOnline: "We're online",
+  homeStatusAway: "We're away",
+  unreadBadge: '{count} unread',
+  team: 'Team',
+  home: 'Home',
+  close: 'Close',
+  retry: 'Retry',
+  connectionError: 'We could not load the chat. Please try again.',
+  connecting: 'Connecting you to the team',
+  // Terminal errors — no Retry, nothing the visitor can fix from here.
+  chatUnavailable: 'Chat is not available right now.',
+  identityVerificationError: "We couldn't verify your account. Please sign in again.",
+  // Shown if the widget's own UI hits a render error.
+  widgetCrashed: 'Something went wrong.',
+  // Relative timestamps on the conversation lists.
+  timeJustNow: 'Just now',
+  timeMinutes: '{count}m',
+  timeHours: '{count}h',
+  timeDays: '{count}d',
+  timeMonths: '{count}mo',
+  timeYears: '{count}y',
+  // Day separators inside a thread.
+  today: 'Today',
+  yesterday: 'Yesterday',
+  conversationUpdated: 'Conversation updated',
+  // Forms.
+  procedureSend: 'Send details',
+  procedureSent: 'Sent',
+  fieldRequired: '{field} is required',
+  invalidEmail: 'Enter a valid email address',
+  working: 'Working...',
+  // Proactive card.
+  outboundTitle: 'New update',
+  outboundCta: 'Learn more',
+  dismiss: 'Dismiss',
+  // Rich blocks an agent can send.
+  blockService: 'Service',
+  blockProduct: 'Product',
+  blockChooseTime: 'Choose a time',
+  blockProfessional: 'Professional',
+  blockPriceOffer: 'Price offer',
+} as const;
+
+export type LabelKey = keyof typeof DEFAULT_LABELS;
+
+/**
+ * Fill `{token}` placeholders in a translated string. Interpolation belongs in
+ * the string layer so translators keep control of word order.
+ */
+export function formatLabel(template: string, values: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) =>
+    key in values ? String(values[key]) : match
+  );
+}
+
+export function buildLabels(translate: Translator): Record<LabelKey, string> {
+  const labels = {} as Record<LabelKey, string>;
+  (Object.keys(DEFAULT_LABELS) as LabelKey[]).forEach((key) => {
+    labels[key] = translate(key, DEFAULT_LABELS[key]);
+  });
+  return labels;
+}