@repzo/widget-react-native 1.0.0

package/src/storage.ts

@@ -0,0 +1,153 @@
+/**
+ * Storage adapters.
+ *
+ * `Storage` (device id, unread counts, cached theme) resolves: an adapter
+ * injected via `RepzoWidget.setStorageAdapter()`, then
+ * `@react-native-async-storage/async-storage` if the host app installed it,
+ * then an in-memory map. The in-memory fallback keeps the SDK working (the
+ * session just doesn't survive a relaunch) instead of crashing.
+ *
+ * `SecureStorage` (visitor token, user key) uses the adapter injected via
+ * `RepzoWidget.setSecureStorageAdapter()` — Keychain/Keystore backed — and
+ * falls back to `Storage` when the host provided none. AsyncStorage is
+ * plaintext on disk, so the bearer token belongs in the secure one.
+ */
+
+import type { RepzoWidgetStorageAdapter } from './types';
+
+export const TOKEN_KEY = 'repzo_widget_token';
+/** Identity key (email/userId) the stored token was issued to; absent = anonymous. */
+export const USER_KEY = 'repzo_widget_user_key';
+export const DEVICE_ID_KEY = 'repzo_widget_device_id';
+export const UNREAD_KEY = 'repzo_widget_unread';
+/** Last config received — repaints the real theme instantly on relaunch. */
+/**
+ * v2 wraps the config with the channel/baseUrl/platform it came from. v1 held a
+ * bare config that a foreground refresh could overwrite with the web design,
+ * so it's ignored (and cleared) rather than painted.
+ */
+export const CONFIG_KEY = 'repzo_widget_config_v2';
+export const LEGACY_CONFIG_KEY = 'repzo_widget_config';
+
+function createMemoryAdapter(): RepzoWidgetStorageAdapter {
+  const map = new Map<string, string>();
+  return {
+    getItem: (key) => map.get(key) ?? null,
+    setItem: (key, value) => {
+      map.set(key, value);
+    },
+    removeItem: (key) => {
+      map.delete(key);
+    },
+  };
+}
+
+function resolveAsyncStorage(): RepzoWidgetStorageAdapter | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+    const mod = require('@react-native-async-storage/async-storage');
+    const asyncStorage = mod?.default ?? mod;
+    if (!asyncStorage?.getItem) return null;
+    return {
+      getItem: (key) => asyncStorage.getItem(key),
+      setItem: (key, value) => asyncStorage.setItem(key, value),
+      removeItem: (key) => asyncStorage.removeItem(key),
+    };
+  } catch {
+    return null;
+  }
+}
+
+const memoryAdapter = createMemoryAdapter();
+let injectedAdapter: RepzoWidgetStorageAdapter | null = null;
+let detectedAdapter: RepzoWidgetStorageAdapter | null | undefined;
+
+function activeAdapter(): RepzoWidgetStorageAdapter {
+  if (injectedAdapter) return injectedAdapter;
+  if (detectedAdapter === undefined) detectedAdapter = resolveAsyncStorage();
+  return detectedAdapter ?? memoryAdapter;
+}
+
+export function setStorageAdapter(adapter: RepzoWidgetStorageAdapter | null): void {
+  injectedAdapter = adapter;
+}
+
+export const Storage = {
+  async getItem(key: string): Promise<string | null> {
+    try {
+      return (await activeAdapter().getItem(key)) ?? null;
+    } catch (error) {
+      console.warn('[repzo-widget] storage read failed', error);
+      return null;
+    }
+  },
+
+  async setItem(key: string, value: string): Promise<void> {
+    try {
+      await activeAdapter().setItem(key, value);
+    } catch (error) {
+      console.warn('[repzo-widget] storage write failed', error);
+    }
+  },
+
+  async removeItem(key: string): Promise<void> {
+    try {
+      await activeAdapter().removeItem(key);
+    } catch (error) {
+      console.warn('[repzo-widget] storage delete failed', error);
+    }
+  },
+};
+
+let secureAdapter: RepzoWidgetStorageAdapter | null = null;
+
+export function setSecureStorageAdapter(adapter: RepzoWidgetStorageAdapter | null): void {
+  secureAdapter = adapter;
+}
+
+export const SecureStorage = {
+  async getItem(key: string): Promise<string | null> {
+    if (!secureAdapter) return Storage.getItem(key);
+    try {
+      const value = (await secureAdapter.getItem(key)) ?? null;
+      if (value !== null) return value;
+    } catch (error) {
+      console.warn('[repzo-widget] secure storage read failed', error);
+      return null;
+    }
+    // One-time migration: a session written before the host added a secure
+    // adapter moves out of plaintext storage on first read.
+    const legacy = await Storage.getItem(key);
+    if (legacy !== null) {
+      await SecureStorage.setItem(key, legacy);
+    }
+    return legacy;
+  },
+
+  async setItem(key: string, value: string): Promise<void> {
+    if (!secureAdapter) {
+      await Storage.setItem(key, value);
+      return;
+    }
+    try {
+      await secureAdapter.setItem(key, value);
+    } catch (error) {
+      // Deliberately no plaintext fallback: the value stays in memory only,
+      // so the session lasts until the app is killed.
+      console.warn('[repzo-widget] secure storage write failed', error);
+    }
+    await Storage.removeItem(key);
+  },
+
+  /** Clears both stores, so a pre-migration plaintext copy can't linger. */
+  async removeItem(key: string): Promise<void> {
+    if (secureAdapter) {
+      try {
+        await secureAdapter.removeItem(key);
+      } catch (error) {
+        console.warn('[repzo-widget] secure storage delete failed', error);
+      }
+    }
+    await Storage.removeItem(key);
+  },
+};

package/src/types.ts

@@ -0,0 +1,445 @@
+/**
+ * Wire + UI types for the Repzo widget.
+ *
+ * Shapes mirror the CRM widget API (`/api/widget/*`) and the web widget's
+ * `client/src/widget/lib/api.ts` — keep them in sync so agent-authored
+ * metadata (agentUiBlocks / agentProcedureForm) renders identically.
+ */
+
+export type WidgetSpaceType = 'home' | 'messages';
+
+export interface WidgetSpace {
+  type: WidgetSpaceType;
+  enabled: boolean;
+}
+
+export interface PreChatField {
+  name: string;
+  label: string;
+  type: 'text' | 'email' | 'phone' | 'select';
+  required: boolean;
+  options?: string[];
+}
+
+export interface WidgetConfig {
+  primaryColor: string;
+  homeLogoUrl: string | null;
+  homeBackgroundType: 'solid' | 'gradient' | 'image';
+  homeBackgroundColor: string;
+  homeBackgroundGradientStart: string;
+  homeBackgroundGradientMiddle: string | null;
+  homeBackgroundGradientEnd: string;
+  homeBackgroundImageUrl: string | null;
+  homeHeaderTextColor: 'black' | 'white';
+  homeBackgroundFade: boolean;
+  position: 'left' | 'right';
+  bubbleText: string;
+  welcomeHeading: string;
+  welcomeSubheading: string;
+  preChatEnabled: boolean;
+  preChatFields: PreChatField[];
+  businessHoursEnabled: boolean;
+  offlineMessage: string;
+  spaces: WidgetSpace[];
+  launchDirectly: boolean;
+  showLauncher: boolean;
+  launcherVerticalPadding: number;
+  launcherHorizontalPadding: number;
+  startConversationLabel: string;
+  replyTimeLabel: string;
+  allowNewConversations: boolean;
+  showPreviousConversations: boolean;
+  proactiveEnabled: boolean;
+  proactiveTitle: string;
+  proactiveBody: string;
+  proactiveCtaLabel: string;
+  proactiveDelaySeconds: number;
+  proactivePathContains: string;
+  proactiveFrequency: 'session' | 'visitor';
+  proactiveOpenMode: 'home' | 'new_message';
+  attachmentsEnabled: boolean;
+  analyticsEnabled: boolean;
+  toursEnabled: boolean;
+  defaultLocale: string;
+  enabledLocales: string[];
+  translations: Record<string, Record<string, string>>;
+  identityVerificationEnabled: boolean;
+  hmacMandatory: boolean;
+  isOnline: boolean;
+}
+
+/** Received attachments are normalized: a missing `id`/`size` is filled in. */
+export interface WidgetAttachment {
+  id: string;
+  name: string;
+  url: string;
+  contentType: string;
+  size: number;
+}
+
+export interface Conversation {
+  id: string;
+  subject: string | null;
+  status: string;
+  snippet: string | null;
+  messageCount: number;
+  lastMessageAt: string | null;
+  createdAt: string;
+  agentName: string | null;
+  agentAvatar: string | null;
+  /**
+   * Agent replies the visitor hasn't seen, computed server-side from their
+   * read cursor. Absent on older Workstation deployments — the SDK then falls
+   * back to its locally persisted counts.
+   */
+  unreadCount?: number;
+}
+
+export interface Message {
+  id: string;
+  messageType?: 'message' | 'note' | 'system';
+  direction: 'inbound' | 'outbound';
+  senderType: string;
+  senderName: string | null;
+  body: string | null;
+  bodyPlain: string | null;
+  attachments: WidgetAttachment[] | null;
+  metadata?: Record<string, unknown> | null;
+  status: string | null;
+  createdAt: string;
+}
+
+export interface OutboundMessage {
+  id?: string;
+  type?: 'chat' | 'post' | 'announcement' | 'banner';
+  title?: string;
+  body?: string;
+  bodyHtml?: string;
+  ctaLabel?: string;
+  ctaUrl?: string;
+  imageUrl?: string;
+  prefill?: string;
+}
+
+/** Identity fields accepted by `POST /api/widget/init`. */
+export interface WidgetUser {
+  userId?: string;
+  email?: string;
+  name?: string;
+  phone?: string;
+  /** HMAC-SHA256 hex of (email ?? userId) — only needed when the widget enforces identity verification. */
+  userHash?: string;
+}
+
+export type WidgetCustomAttributes = Record<string, string | number | boolean>;
+
+export interface InitResponse {
+  token: string;
+  identityId: string;
+  config: WidgetConfig;
+  conversations: Conversation[];
+  user?: { name?: string; email?: string };
+}
+
+/** Production Workstation deployment — where `/api/widget/*` is served. */
+export const DEFAULT_BASE_URL = 'https://workstation.repzo.com';
+
+export interface BootOptions {
+  /**
+   * Override the CRM deployment root. Defaults to production Workstation
+   * (`https://workstation.repzo.com`); set it only for a dev/staging CRM.
+   * Android emulators need `http://10.0.2.2:3000` to reach a local CRM.
+   */
+  baseUrl?: string;
+  /** `inbox_channel_accounts.id` of the Website Chat widget. */
+  channelAccountId: string;
+  user?: WidgetUser;
+  /**
+   * Called first for every link the visitor taps inside the widget (agent/AI
+   * replies, campaign CTAs, attachments). Return `true` when the host handled
+   * it (e.g. routed an `myapp://` deep link itself). Otherwise the SDK only
+   * opens `https:`, `http:`, `mailto:` and `tel:` URLs and blocks the rest —
+   * agent-authored text must never be able to fire host deep links,
+   * `intent:` or `javascript:` URLs.
+   */
+  onOpenUrl?: (url: string) => boolean | Promise<boolean>;
+  /**
+   * FCM push registration (requires `@react-native-firebase/messaging` in the
+   * host app and the channel's push provider set to FCM in Workstation).
+   */
+  push?: {
+    enabled?: boolean;
+    /** Default true — set false when the host runs its own permission prompt. */
+    requestPermission?: boolean;
+    /**
+     * The app's bundle id / package name — lets a channel serving several apps
+     * match this device to the right Firebase key. Optional for single-app
+     * channels.
+     */
+    bundleId?: string;
+  };
+}
+
+// ─── Agent UI blocks ────────────────────────────────────────────────────────
+// Structural mirrors of `shared/agent-ui-blocks.ts` in the CRM. Validation is
+// intentionally permissive here (no zod dependency) — the server already
+// validated these before broadcasting them.
+
+export type AgentUiModule =
+  | 'products'
+  | 'product_variants'
+  | 'carts'
+  | 'orders'
+  | 'contacts'
+  | 'leads'
+  | 'appointments'
+  | 'price_offers'
+  | 'send';
+
+export interface AgentUiAction {
+  id: string;
+  type:
+    | 'add_to_cart'
+    | 'buy_now'
+    | 'submit_contact'
+    | 'record_consent'
+    | 'select_appointment_provider'
+    | 'select_appointment_slot'
+    | 'open_record'
+    | 'accept_quote'
+    | 'next_action';
+  label: string;
+  module: AgentUiModule;
+  payload: Record<string, unknown>;
+  navigateTo?: string;
+}
+
+export interface AgentUiProduct {
+  id: string;
+  name: string;
+  type: 'physical' | 'service' | 'digital';
+  shortDescription?: string;
+  description?: string;
+  imageUrl?: string;
+  sku?: string;
+  unit?: string;
+  price: number;
+  currency: string;
+  durationMinutes?: number;
+}
+
+export interface AgentUiCommerceItem {
+  productId?: string;
+  variantId?: string;
+  name: string;
+  description?: string;
+  imageUrl?: string;
+  sku?: string;
+  quantity: number;
+  unitPrice: number;
+  lineTotal: number;
+}
+
+export type AgentUiBlock =
+  | { id: string; module: AgentUiModule; type: 'product_service_card'; product: AgentUiProduct }
+  | {
+      id: string;
+      module: AgentUiModule;
+      type: 'product_choices';
+      productId: string;
+      title: string;
+      variants: Array<{
+        id: string;
+        title: string;
+        sku?: string;
+        price: number;
+        currency: string;
+        imageUrl?: string;
+        available: boolean;
+      }>;
+    }
+  | {
+      id: string;
+      module: AgentUiModule;
+      type: 'commerce_actions';
+      productId: string;
+      variantId?: string;
+      quantity: number;
+      actions: AgentUiAction[];
+    }
+  | {
+      id: string;
+      module: AgentUiModule;
+      type: 'cart_order_summary';
+      title: string;
+      reference?: string;
+      status?: string;
+      currency: string;
+      items: AgentUiCommerceItem[];
+      subtotal: number;
+      discount: number;
+      tax: number;
+      shipping: number;
+      total: number;
+      action?: AgentUiAction;
+    }
+  | {
+      id: string;
+      module: AgentUiModule;
+      type: 'contact_lead_form';
+      title: string;
+      description?: string;
+      fields: Array<{
+        name: string;
+        label: string;
+        type: 'text' | 'email' | 'phone' | 'textarea';
+        required: boolean;
+        placeholder?: string;
+        value?: string;
+      }>;
+      submitLabel: string;
+    }
+  | {
+      id: string;
+      module: AgentUiModule;
+      type: 'consent';
+      statement: string;
+      channels: Array<'email' | 'phone' | 'whatsapp'>;
+      required: boolean;
+      privacyUrl?: string;
+    }
+  | {
+      id: string;
+      module: AgentUiModule;
+      type: 'appointment_slot_picker';
+      serviceId: string;
+      serviceName: string;
+      durationMinutes: number;
+      timezone?: string;
+      locationId?: string;
+      selectedProviderId?: string;
+      providers: Array<{ id: string; name: string; avatarUrl?: string | null }>;
+      days: Array<{
+        date: string;
+        slots: Array<{
+          startTime: string;
+          endTime: string;
+          staffUserId?: string | null;
+          slotToken: string;
+        }>;
+      }>;
+    }
+  | {
+      id: string;
+      module: AgentUiModule;
+      type: 'quote_preview';
+      quoteId: string;
+      name: string;
+      serialNumber?: string;
+      status: string;
+      amount: number;
+      currency: string;
+      validUntil?: string;
+      contactName?: string;
+      items: AgentUiCommerceItem[];
+      actions: AgentUiAction[];
+    }
+  | {
+      id: string;
+      module: AgentUiModule;
+      type: 'success_receipt';
+      title: string;
+      description?: string;
+      entityId?: string;
+      reference?: string;
+      amount?: number;
+      currency?: string;
+      navigateTo?: string;
+      nextActions: AgentUiAction[];
+    };
+
+export interface AgentProcedureForm {
+  procedureId: string;
+  procedureName: string;
+  fields: Array<{
+    name: string;
+    label: string;
+    type: 'text' | 'email' | 'phone' | 'date' | 'time';
+    required: boolean;
+  }>;
+}
+
+// ─── Realtime ───────────────────────────────────────────────────────────────
+
+export type WidgetRealtimeEvent =
+  | 'connected'
+  | 'message.new'
+  | 'typing.start'
+  | 'typing.stop'
+  | 'conversation.updated'
+  | 'conversation.event'
+  | 'error';
+
+// ─── SDK surface ────────────────────────────────────────────────────────────
+
+/**
+ * Async key/value store. The regular adapter holds the device id, unread
+ * counts and cached theme; the optional secure adapter (Keychain/Keystore via
+ * `setSecureStorageAdapter`) holds the visitor token and user key.
+ */
+export interface RepzoWidgetStorageAdapter {
+  getItem(key: string): Promise<string | null> | string | null;
+  setItem(key: string, value: string): Promise<void> | void;
+  removeItem(key: string): Promise<void> | void;
+}
+
+/**
+ * `RepzoWidgetError.code`. The last two come from the server's 403 body and
+ * are terminal — the SDK stops realtime and does not retry on its own:
+ * - `messenger_api_disabled` — the channel's Messenger API is switched off.
+ * - `identity_verification_failed` — `userHash` missing/wrong while the
+ *   channel enforces identity verification.
+ */
+export type RepzoWidgetErrorCode =
+  | 'network'
+  | 'http'
+  | 'messenger_api_disabled'
+  | 'identity_verification_failed';
+
+export type WidgetView = 'bubble' | 'home' | 'prechat' | 'chat' | 'conversations';
+
+export interface WidgetState {
+  booted: boolean;
+  loading: boolean;
+  error: string | null;
+  /** Machine-readable companion to `error` — see `RepzoWidgetErrorCode`. */
+  errorCode: RepzoWidgetErrorCode | null;
+  config: WidgetConfig | null;
+  identityId: string | null;
+  isOpen: boolean;
+  view: WidgetView;
+  activeTab: WidgetSpaceType;
+  conversations: Conversation[];
+  activeConversationId: string | null;
+  messages: Message[];
+  messagesLoading: boolean;
+  hasMoreMessages: boolean;
+  messageCursor: string | null;
+  agentTyping: boolean;
+  /**
+   * Unread team replies across all threads — always the sum of
+   * `unreadByConversation`, so it only drops when a thread is opened.
+   */
+  unreadCount: number;
+  /**
+   * Unread replies per conversation. Only `messageType: 'message'` replies
+   * count (never system rows); a thread stays unread until the visitor
+   * actually opens it.
+   */
+  unreadByConversation: Record<string, number>;
+  locale: string;
+  prefillText: string;
+  outboundMessage: OutboundMessage | null;
+  /** Name/email captured from pre-chat or `loginUserWithUserAttributes`. */
+  visitorProfile: { name?: string; email?: string; phone?: string };
+}