@repzo/widget-react-native 1.0.0

package/src/agent-ui-blocks.ts

@@ -0,0 +1,302 @@
+/**
+ * Structural parsing for agent-authored UI blocks.
+ *
+ * The CRM validates these with zod (`shared/agent-ui-blocks.ts`) before
+ * broadcasting, so this side only needs to reject malformed payloads rather
+ * than re-implement the schema — which keeps the SDK dependency-free. Action
+ * message formatting is copied verbatim so the transcript reads the same on
+ * web and mobile.
+ */
+
+import type { AgentUiAction, AgentUiBlock, AgentProcedureForm } from './types';
+
+const KNOWN_BLOCK_TYPES = new Set([
+  'product_service_card',
+  'product_choices',
+  'commerce_actions',
+  'cart_order_summary',
+  'contact_lead_form',
+  'consent',
+  'appointment_slot_picker',
+  'quote_preview',
+  'success_receipt',
+]);
+
+const KNOWN_ACTION_TYPES = new Set([
+  'add_to_cart',
+  'buy_now',
+  'submit_contact',
+  'record_consent',
+  'select_appointment_provider',
+  'select_appointment_slot',
+  'open_record',
+  'accept_quote',
+  'next_action',
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+// The renderer dereferences nested fields and hands strings to <Text>, so a
+// block is only accepted when every field it touches has the right shape —
+// one wrong type (`providers` missing, a numeric slot time, a string
+// `amount`) must skip that block, not throw inside the host app's tree.
+
+const isString = (value: unknown): value is string => typeof value === 'string';
+
+const isNumber = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value);
+
+const isOptional = (value: unknown, check: (value: unknown) => boolean) =>
+  value === undefined || value === null || check(value);
+
+const isArrayOf = (value: unknown, check: (item: unknown) => boolean) =>
+  Array.isArray(value) && value.every(check);
+
+function isAction(value: unknown): value is AgentUiAction {
+  if (!isRecord(value)) return false;
+  return (
+    isString(value.id) &&
+    isString(value.label) &&
+    isString(value.type) &&
+    KNOWN_ACTION_TYPES.has(value.type) &&
+    isRecord(value.payload)
+  );
+}
+
+function isCommerceItem(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isString(value.name) &&
+    isNumber(value.quantity) &&
+    isNumber(value.unitPrice) &&
+    isNumber(value.lineTotal)
+  );
+}
+
+function isVariant(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.title) &&
+    isNumber(value.price) &&
+    isString(value.currency)
+  );
+}
+
+function isFormField(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isString(value.name) &&
+    isString(value.label) &&
+    isOptional(value.placeholder, isString) &&
+    isOptional(value.value, isString)
+  );
+}
+
+function isProvider(value: unknown): boolean {
+  return isRecord(value) && isString(value.id) && isString(value.name);
+}
+
+function isSlot(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isString(value.startTime) &&
+    isString(value.endTime) &&
+    isString(value.slotToken) &&
+    isOptional(value.staffUserId, isString)
+  );
+}
+
+function isDay(value: unknown): boolean {
+  return isRecord(value) && isString(value.date) && isArrayOf(value.slots, isSlot);
+}
+
+function isValidBlock(block: Record<string, unknown>): boolean {
+  switch (block.type) {
+    case 'product_service_card': {
+      const product = block.product;
+      return (
+        isRecord(product) &&
+        isString(product.name) &&
+        isNumber(product.price) &&
+        isString(product.currency) &&
+        isOptional(product.imageUrl, isString) &&
+        isOptional(product.shortDescription, isString) &&
+        isOptional(product.description, isString) &&
+        isOptional(product.unit, isString) &&
+        isOptional(product.durationMinutes, isNumber)
+      );
+    }
+    case 'product_choices':
+      return (
+        isString(block.productId) &&
+        isString(block.title) &&
+        Array.isArray(block.variants) &&
+        block.variants.length > 0 &&
+        block.variants.every(isVariant)
+      );
+    case 'commerce_actions':
+      return isArrayOf(block.actions, isAction);
+    case 'cart_order_summary':
+      return (
+        isString(block.title) &&
+        isString(block.currency) &&
+        isArrayOf(block.items, isCommerceItem) &&
+        isNumber(block.subtotal) &&
+        isNumber(block.total) &&
+        isOptional(block.discount, isNumber) &&
+        isOptional(block.tax, isNumber) &&
+        isOptional(block.shipping, isNumber) &&
+        isOptional(block.status, isString) &&
+        isOptional(block.action, isAction)
+      );
+    case 'contact_lead_form':
+      return (
+        isString(block.title) &&
+        isString(block.submitLabel) &&
+        isOptional(block.description, isString) &&
+        Array.isArray(block.fields) &&
+        block.fields.length > 0 &&
+        block.fields.every(isFormField)
+      );
+    case 'consent':
+      return isString(block.statement) && isArrayOf(block.channels, isString);
+    case 'appointment_slot_picker':
+      return (
+        isString(block.serviceId) &&
+        isString(block.serviceName) &&
+        isNumber(block.durationMinutes) &&
+        isOptional(block.timezone, isString) &&
+        isOptional(block.selectedProviderId, isString) &&
+        isOptional(block.providers, (value) => isArrayOf(value, isProvider)) &&
+        Array.isArray(block.days) &&
+        block.days.length > 0 &&
+        block.days.every(isDay)
+      );
+    case 'quote_preview':
+      return (
+        isString(block.name) &&
+        isString(block.currency) &&
+        isString(block.status) &&
+        isNumber(block.amount) &&
+        isOptional(block.serialNumber, isString) &&
+        isOptional(block.contactName, isString) &&
+        isOptional(block.validUntil, isString) &&
+        isOptional(block.actions, (value) => isArrayOf(value, isAction))
+      );
+    case 'success_receipt':
+      return (
+        isString(block.title) &&
+        isOptional(block.description, isString) &&
+        isOptional(block.reference, isString) &&
+        isOptional(block.amount, isNumber) &&
+        isOptional(block.currency, isString) &&
+        isOptional(block.nextActions, (value) => isArrayOf(value, isAction))
+      );
+    default:
+      return false;
+  }
+}
+
+/**
+ * Drops blocks this SDK version does not know how to render, or whose fields
+ * don't match what the renderer reads. Optional lists the server may omit
+ * come back as empty arrays.
+ */
+export function parseAgentUiBlocks(value: unknown): AgentUiBlock[] {
+  if (!Array.isArray(value)) return [];
+  const blocks: AgentUiBlock[] = [];
+  for (const block of value) {
+    if (!isRecord(block)) continue;
+    if (!isString(block.id) || !isString(block.type)) continue;
+    if (!KNOWN_BLOCK_TYPES.has(block.type) || !isValidBlock(block)) continue;
+
+    const normalized =
+      block.type === 'appointment_slot_picker'
+        ? { ...block, providers: block.providers ?? [] }
+        : block.type === 'quote_preview'
+          ? { ...block, actions: block.actions ?? [] }
+          : block.type === 'success_receipt'
+            ? { ...block, nextActions: block.nextActions ?? [] }
+            : block;
+    blocks.push(normalized as unknown as AgentUiBlock);
+  }
+  return blocks;
+}
+
+export function getAgentUiBlocks(metadata: Record<string, unknown> | null | undefined) {
+  if (!isRecord(metadata)) return [];
+  return parseAgentUiBlocks(metadata.agentUiBlocks);
+}
+
+export function getProcedureForm(
+  metadata: Record<string, unknown> | null | undefined
+): AgentProcedureForm | null {
+  if (!isRecord(metadata)) return null;
+  const form = metadata.agentProcedureForm;
+  if (!isRecord(form) || !Array.isArray(form.fields) || form.fields.length === 0) return null;
+
+  return {
+    procedureId: typeof form.procedureId === 'string' ? form.procedureId : '',
+    procedureName: typeof form.procedureName === 'string' ? form.procedureName : 'Details',
+    fields: form.fields
+      .filter((field: any) => field && typeof field.name === 'string')
+      .map((field: any) => ({
+        name: field.name,
+        label: typeof field.label === 'string' ? field.label : field.name,
+        type: ['email', 'phone', 'date', 'time', 'text'].includes(field.type) ? field.type : 'text',
+        required: field.required !== false,
+      })),
+  };
+}
+
+export function formatAgentUiActionMessage(action: AgentUiAction): string {
+  const payload = action.payload;
+  switch (action.type) {
+    case 'add_to_cart':
+      return `Add ${String(payload.productName || 'this item')} to my cart${
+        payload.variantTitle ? ` (${String(payload.variantTitle)})` : ''
+      }.`;
+    case 'buy_now':
+      if (payload.cartId) return `Create an order from cart ${String(payload.cartId)}.`;
+      if (action.module === 'appointments' || payload.productType === 'service') {
+        return `Book ${String(payload.productName || 'this service')}${
+          payload.variantTitle ? ` (${String(payload.variantTitle)})` : ''
+        }.`;
+      }
+      return `Buy ${String(payload.productName || 'this item')} now${
+        payload.variantTitle ? ` (${String(payload.variantTitle)})` : ''
+      }.`;
+    case 'select_appointment_provider':
+      return `Show appointment times for ${String(
+        payload.serviceName || 'this service'
+      )} with ${String(payload.providerName || 'any available professional')}.`;
+    case 'select_appointment_slot':
+      return `Book ${String(payload.serviceName || 'this service')} on ${String(
+        payload.date || 'the selected date'
+      )} at ${String(payload.startTime || 'the selected time')}${
+        payload.providerName ? ` with ${String(payload.providerName)}` : ''
+      }.`;
+    case 'accept_quote':
+      return `I accept quote ${String(payload.reference || payload.quoteId || '')}.`.trim();
+    case 'record_consent':
+      return `I consent to being contacted by ${
+        Array.isArray(payload.channels) ? payload.channels.join(', ') : 'the selected channel'
+      }.`;
+    case 'open_record':
+      return action.label;
+    case 'submit_contact':
+      return (
+        Object.entries(payload)
+          .filter(([, value]) => typeof value === 'string' && value.trim())
+          .map(([key, value]) => `${key}: ${String(value).trim()}`)
+          .join('\n') || 'I have submitted my contact details.'
+      );
+    case 'next_action':
+      return action.label;
+    default:
+      return action.label;
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,332 @@
+/**
+ * Fetch client for `/api/widget/*`.
+ *
+ * Ported from the web widget's `client/src/widget/lib/api.ts`, with
+ * localStorage swapped for the storage adapter and EventSource moved to
+ * `api/realtime.ts`. Visitor tokens live up to 14 days with no refresh, so a
+ * 401 triggers one silent re-init + retry (single-flight, owned by the store).
+ * The token itself lives in `SecureStorage`.
+ */
+
+import { SecureStorage, TOKEN_KEY } from '../storage';
+import type {
+  AgentUiAction,
+  Conversation,
+  InitResponse,
+  Message,
+  OutboundMessage,
+  RepzoWidgetErrorCode,
+  WidgetAttachment,
+  WidgetConfig,
+  WidgetUser,
+} from '../types';
+import { isHttpUrl, urlScheme } from '../ui/utils/safe-url';
+
+/** Server `code`s that no retry or re-init can fix. */
+const TERMINAL_CODES = new Set<RepzoWidgetErrorCode>([
+  'messenger_api_disabled',
+  'identity_verification_failed',
+]);
+
+export function isTerminalErrorCode(code: string | null | undefined): boolean {
+  return !!code && TERMINAL_CODES.has(code as RepzoWidgetErrorCode);
+}
+
+export class RepzoWidgetError extends Error {
+  readonly status: number;
+
+  readonly code: RepzoWidgetErrorCode;
+
+  constructor(message: string, status: number, code: RepzoWidgetErrorCode = 'http') {
+    super(message);
+    this.name = 'RepzoWidgetError';
+    this.status = status;
+    this.code = code;
+  }
+
+  /** Builds the error for a non-2xx `{ message, code }` body. */
+  static fromResponse(status: number, body: unknown): RepzoWidgetError {
+    const payload = (body && typeof body === 'object' ? body : {}) as {
+      message?: unknown;
+      code?: unknown;
+    };
+    const message = typeof payload.message === 'string' && payload.message ? payload.message : null;
+    const code =
+      status === 403 && typeof payload.code === 'string' && isTerminalErrorCode(payload.code)
+        ? (payload.code as RepzoWidgetErrorCode)
+        : 'http';
+    return new RepzoWidgetError(message || `HTTP ${status}`, status, code);
+  }
+}
+
+interface RequestOptions {
+  method?: 'GET' | 'POST' | 'DELETE';
+  body?: unknown;
+  /**
+   * Never re-init on 401: set for init itself (so a 401 never recurses) and
+   * for logout-time calls, which must not mint a session for a signed-out user.
+   */
+  skipReauth?: boolean;
+  /** Authenticate with this token instead of the stored one (logout). */
+  authToken?: string | null;
+}
+
+export class WidgetApiClient {
+  private baseUrl = '';
+
+  private channelAccountId = '';
+
+  private token: string | null = null;
+
+  private tokenLoaded = false;
+
+  /**
+   * Set by the store: given the token that just got a 401, returns a valid
+   * token (fresh, or one another caller already minted), or null.
+   */
+  reauthorize: ((failedToken: string | null) => Promise<string | null>) | null = null;
+
+  /** Set by the store: a 403 with a terminal `code` came back from any endpoint. */
+  onTerminalError: ((error: RepzoWidgetError) => void) | null = null;
+
+  configure(baseUrl: string, channelAccountId: string) {
+    this.baseUrl = baseUrl.replace(/\/$/, '');
+    this.channelAccountId = channelAccountId;
+  }
+
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  getChannelAccountId(): string {
+    return this.channelAccountId;
+  }
+
+  async getToken(): Promise<string | null> {
+    if (this.token) return this.token;
+    if (!this.tokenLoaded) {
+      this.tokenLoaded = true;
+      this.token = await SecureStorage.getItem(TOKEN_KEY);
+    }
+    return this.token;
+  }
+
+  async setToken(token: string): Promise<void> {
+    this.token = token;
+    this.tokenLoaded = true;
+    await SecureStorage.setItem(TOKEN_KEY, token);
+  }
+
+  async clearToken(): Promise<void> {
+    this.token = null;
+    this.tokenLoaded = true;
+    await SecureStorage.removeItem(TOKEN_KEY);
+  }
+
+  /**
+   * Absolute URL for a server media path (avatars, attachments). Only ever
+   * returns `http(s)` — relative paths resolve against `baseUrl`; any other
+   * scheme (`file:`, `data:`, `intent:`, host deep links…) yields null.
+   */
+  resolveUrl(url: string | null | undefined): string | null {
+    const trimmed = url?.trim();
+    if (!trimmed) return null;
+    if (isHttpUrl(trimmed)) return trimmed;
+    if (urlScheme(trimmed)) return null;
+    const resolved = `${this.baseUrl}${trimmed.startsWith('/') ? '' : '/'}${trimmed}`;
+    return isHttpUrl(resolved) ? resolved : null;
+  }
+
+  private async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    let sentToken: string | null = null;
+
+    const send = async (): Promise<Response> => {
+      const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+      const token = options.authToken !== undefined ? options.authToken : await this.getToken();
+      sentToken = token;
+      if (token) headers.Authorization = `Bearer ${token}`;
+
+      try {
+        return await fetch(`${this.baseUrl}${path}`, {
+          method: options.method ?? 'GET',
+          headers,
+          body: options.body === undefined ? undefined : JSON.stringify(options.body),
+        });
+      } catch (error) {
+        throw new RepzoWidgetError(
+          error instanceof Error ? error.message : 'Network request failed',
+          0,
+          'network'
+        );
+      }
+    };
+
+    let response = await send();
+
+    // The token expired or was revoked: mint a new session once.
+    if (response.status === 401 && !options.skipReauth && this.reauthorize) {
+      const refreshed = await this.reauthorize(sentToken);
+      if (refreshed) response = await send();
+    }
+
+    if (!response.ok) {
+      const body = await response.json().catch(() => null);
+      const error = RepzoWidgetError.fromResponse(response.status, body);
+      // skipReauth calls (init, logout-time) are handled by their caller,
+      // which knows whether the result is still current.
+      if (isTerminalErrorCode(error.code) && !options.skipReauth) this.onTerminalError?.(error);
+      throw error;
+    }
+
+    if (response.status === 204) return undefined as T;
+    return (await response.json()) as T;
+  }
+
+  // ─── Endpoints ────────────────────────────────────────────────────────────
+
+  /** Public config. `platform` makes the server apply the Mobile SDKs overrides. */
+  getConfig(platform?: 'ios' | 'android' | 'web'): Promise<WidgetConfig> {
+    const query = platform ? `?platform=${encodeURIComponent(platform)}` : '';
+    return this.request(`/api/widget/config/${encodeURIComponent(this.channelAccountId)}${query}`);
+  }
+
+  getOutboundMessage(): Promise<{ message: OutboundMessage | null }> {
+    return this.request(`/api/widget/outbound/${encodeURIComponent(this.channelAccountId)}`);
+  }
+
+  /**
+   * Does NOT store the returned token — the store persists it only once it
+   * knows the identity op that asked for it is still current.
+   */
+  async init(params: {
+    user?: WidgetUser;
+    trackingVisitorId?: string;
+    platform?: string;
+    sdkVersion?: string;
+    /** False for fresh sessions — never resume another identity's token. */
+    resumeToken?: boolean;
+  }): Promise<InitResponse> {
+    const visitorToken = params.resumeToken === false ? null : await this.getToken();
+    const user = params.user
+      ? {
+          ...(params.user.email ? { email: params.user.email } : {}),
+          ...(params.user.name ? { name: params.user.name } : {}),
+          ...(params.user.phone ? { phone: params.user.phone } : {}),
+          ...(params.user.userId ? { user_id: params.user.userId } : {}),
+          ...(params.user.userHash ? { user_hash: params.user.userHash } : {}),
+        }
+      : undefined;
+
+    return this.request<InitResponse>('/api/widget/init', {
+      method: 'POST',
+      skipReauth: true,
+      body: {
+        channelAccountId: this.channelAccountId,
+        visitorToken,
+        trackingVisitorId: params.trackingVisitorId,
+        platform: params.platform,
+        sdkVersion: params.sdkVersion,
+        ...(user ? { user } : {}),
+      },
+    });
+  }
+
+  /** Revokes `token` server-side. A 401 means it was already dead — fine. */
+  async logout(token: string): Promise<void> {
+    try {
+      await this.request('/api/widget/logout', {
+        method: 'POST',
+        skipReauth: true,
+        authToken: token,
+      });
+    } catch (error) {
+      if (error instanceof RepzoWidgetError && error.status === 401) return;
+      throw error;
+    }
+  }
+
+  sendMessage(data: {
+    conversationId?: string;
+    forceNewConversation?: boolean;
+    body: string;
+    attachments?: WidgetAttachment[];
+    visitorName?: string;
+    visitorEmail?: string;
+    agentUiAction?: AgentUiAction;
+  }): Promise<{ messageId: string; conversationId: string; isNewConversation: boolean }> {
+    return this.request('/api/widget/messages', { method: 'POST', body: data });
+  }
+
+  listConversations(): Promise<{ data: Conversation[] }> {
+    return this.request('/api/widget/conversations');
+  }
+
+  listMessages(
+    conversationId: string,
+    cursor?: string | null
+  ): Promise<{ data: Message[]; meta: { hasMore: boolean; nextCursor: string | null } }> {
+    const query = cursor ? `?cursor=${encodeURIComponent(cursor)}` : '';
+    return this.request(
+      `/api/widget/conversations/${encodeURIComponent(conversationId)}/messages${query}`
+    );
+  }
+
+  /**
+   * Advances the visitor's read cursor for a thread they're watching live.
+   * Best effort and `skipReauth`: a burst of live replies must never turn an
+   * expired token into a burst of re-inits.
+   */
+  markConversationRead(conversationId: string): Promise<void> {
+    return this.request(
+      `/api/widget/conversations/${encodeURIComponent(conversationId)}/read`,
+      { method: 'POST', skipReauth: true }
+    );
+  }
+
+  identify(data: {
+    email?: string;
+    name?: string;
+    phone?: string;
+    customAttributes?: Record<string, string | number | boolean>;
+  }): Promise<void> {
+    return this.request('/api/widget/identify', { method: 'POST', body: data });
+  }
+
+  sendTyping(conversationId: string, isTyping: boolean): Promise<void> {
+    return this.request('/api/widget/typing', {
+      method: 'POST',
+      body: { conversationId, isTyping },
+    });
+  }
+
+  trackEvent(data: {
+    event: string;
+    visitorId?: string | null;
+    metadata?: Record<string, unknown>;
+  }): Promise<void> {
+    return this.request('/api/widget/events', {
+      method: 'POST',
+      body: { ...data, channelAccountId: this.channelAccountId },
+    });
+  }
+
+  registerPushToken(data: {
+    token: string;
+    platform: string;
+    bundleId?: string;
+  }): Promise<void> {
+    return this.request('/api/widget/push-token', { method: 'POST', body: data });
+  }
+
+  /** Logout passes the session's token explicitly and `skipReauth`. */
+  removePushToken(
+    token: string,
+    auth: { authToken?: string | null; skipReauth?: boolean } = {}
+  ): Promise<void> {
+    return this.request('/api/widget/push-token', {
+      method: 'DELETE',
+      body: { token },
+      ...auth,
+    });
+  }
+}