@parlr/react-native 0.1.0

package/src/core/session.ts

@@ -0,0 +1,156 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - Session Manager
+// ---------------------------------------------------------------------------
+//
+// Manages the widget session lifecycle. Uses expo-secure-store when available,
+// falls back to in-memory storage otherwise.
+// ---------------------------------------------------------------------------
+
+import type { Session } from './types';
+
+const STORE_KEY_PREFIX = 'parlr_session_';
+
+function storeKey(workspaceId: string): string {
+  return `${STORE_KEY_PREFIX}${workspaceId}`;
+}
+
+// ---------------------------------------------------------------------------
+// Storage abstraction with fallback
+// ---------------------------------------------------------------------------
+
+interface StorageAdapter {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  deleteItem(key: string): Promise<void>;
+}
+
+/** In-memory fallback when expo-secure-store is not available. */
+const memoryStore = new Map<string, string>();
+
+const memoryAdapter: StorageAdapter = {
+  async getItem(key) {
+    return memoryStore.get(key) ?? null;
+  },
+  async setItem(key, value) {
+    memoryStore.set(key, value);
+  },
+  async deleteItem(key) {
+    memoryStore.delete(key);
+  },
+};
+
+let _adapter: StorageAdapter | null = null;
+
+function getAdapter(): StorageAdapter {
+  if (_adapter) return _adapter;
+
+  try {
+    // Dynamic import to keep expo-secure-store truly optional.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const SecureStore = require('expo-secure-store');
+    if (SecureStore?.setItemAsync) {
+      _adapter = {
+        getItem: (key: string) => SecureStore.getItemAsync(key),
+        setItem: (key: string, value: string) =>
+          SecureStore.setItemAsync(key, value),
+        deleteItem: (key: string) => SecureStore.deleteItemAsync(key),
+      };
+      return _adapter;
+    }
+  } catch {
+    // expo-secure-store not available — use memory fallback.
+  }
+
+  _adapter = memoryAdapter;
+  return _adapter;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Persist session to secure storage (or memory fallback). */
+export async function saveSession(
+  workspaceId: string,
+  session: Session,
+): Promise<void> {
+  const adapter = getAdapter();
+  await adapter.setItem(storeKey(workspaceId), JSON.stringify(session));
+}
+
+/** Retrieve persisted session, or null if none exists. */
+export async function loadSession(
+  workspaceId: string,
+): Promise<Session | null> {
+  const adapter = getAdapter();
+  try {
+    const raw = await adapter.getItem(storeKey(workspaceId));
+    if (!raw) return null;
+
+    const session: Session = JSON.parse(raw);
+
+    // Validate required fields.
+    if (
+      typeof session.token !== 'string' ||
+      typeof session.contactId !== 'string' ||
+      typeof session.expiresAt !== 'string'
+    ) {
+      console.warn(
+        '[@parlr/react-native] Stored session has invalid shape, clearing.',
+      );
+      await clearSession(workspaceId);
+      return null;
+    }
+
+    return session;
+  } catch (err) {
+    // Corrupted data — clear and return null.
+    console.warn(
+      '[@parlr/react-native] Failed to load session, clearing:',
+      err,
+    );
+    await clearSession(workspaceId);
+    return null;
+  }
+}
+
+/**
+ * Returns true when the session token has not yet expired.
+ * Adds a 60-second safety margin to avoid edge-case failures.
+ */
+export function isSessionValid(session: Session): boolean {
+  try {
+    const expiresAt = new Date(session.expiresAt).getTime();
+    if (isNaN(expiresAt)) {
+      console.warn(
+        '[@parlr/react-native] Invalid expiresAt date:',
+        session.expiresAt,
+      );
+      return false;
+    }
+    const margin = 60_000; // 60 s
+    return Date.now() < expiresAt - margin;
+  } catch (err) {
+    console.warn(
+      '[@parlr/react-native] Error checking session validity:',
+      err,
+    );
+    return false;
+  }
+}
+
+/** Delete persisted session for a workspace. */
+export async function clearSession(workspaceId: string): Promise<void> {
+  const adapter = getAdapter();
+  try {
+    await adapter.deleteItem(storeKey(workspaceId));
+  } catch {
+    // Best-effort — nothing to do if deletion fails.
+  }
+}
+
+/** Reset the storage adapter (for testing). */
+export function _resetAdapter(): void {
+  _adapter = null;
+  memoryStore.clear();
+}

package/src/core/theme.ts

@@ -0,0 +1,133 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - Theming System
+// ---------------------------------------------------------------------------
+
+export interface ParlrTheme {
+  colors: {
+    primary: string;
+    primaryText: string;
+    background: string;
+    surface: string;
+    surfaceDark: string;
+    text: string;
+    textSecondary: string;
+    border: string;
+    success: string;
+    error: string;
+    agentBubble: string;
+    agentBubbleDark: string;
+    agentText: string;
+    agentTextDark: string;
+    contactBubble: string;
+    contactText: string;
+  };
+  borderRadius: {
+    bubble: number;
+    input: number;
+    button: number;
+    avatar: number;
+  };
+  spacing: {
+    xs: number;
+    sm: number;
+    md: number;
+    lg: number;
+    xl: number;
+  };
+  typography: {
+    headerSize: number;
+    bodySize: number;
+    captionSize: number;
+  };
+}
+
+export const defaultLightTheme: ParlrTheme = {
+  colors: {
+    primary: '#6366F1',
+    primaryText: '#FFFFFF',
+    background: '#FFFFFF',
+    surface: '#F9FAFB',
+    surfaceDark: '#F3F4F6',
+    text: '#111827',
+    textSecondary: '#6B7280',
+    border: '#E5E7EB',
+    success: '#10B981',
+    error: '#EF4444',
+    agentBubble: '#F3F4F6',
+    agentBubbleDark: '#E5E7EB',
+    agentText: '#111827',
+    agentTextDark: '#111827',
+    contactBubble: '#6366F1',
+    contactText: '#FFFFFF',
+  },
+  borderRadius: {
+    bubble: 16,
+    input: 12,
+    button: 8,
+    avatar: 20,
+  },
+  spacing: {
+    xs: 4,
+    sm: 8,
+    md: 16,
+    lg: 24,
+    xl: 32,
+  },
+  typography: {
+    headerSize: 18,
+    bodySize: 15,
+    captionSize: 12,
+  },
+};
+
+export const defaultDarkTheme: ParlrTheme = {
+  colors: {
+    primary: '#818CF8',
+    primaryText: '#FFFFFF',
+    background: '#111827',
+    surface: '#1F2937',
+    surfaceDark: '#374151',
+    text: '#F9FAFB',
+    textSecondary: '#9CA3AF',
+    border: '#374151',
+    success: '#34D399',
+    error: '#F87171',
+    agentBubble: '#1F2937',
+    agentBubbleDark: '#374151',
+    agentText: '#F9FAFB',
+    agentTextDark: '#F9FAFB',
+    contactBubble: '#818CF8',
+    contactText: '#FFFFFF',
+  },
+  borderRadius: {
+    bubble: 16,
+    input: 12,
+    button: 8,
+    avatar: 20,
+  },
+  spacing: {
+    xs: 4,
+    sm: 8,
+    md: 16,
+    lg: 24,
+    xl: 32,
+  },
+  typography: {
+    headerSize: 18,
+    bodySize: 15,
+    captionSize: 12,
+  },
+};
+
+/** Deep-merge a base theme with partial overrides. */
+export function mergeTheme(
+  base: ParlrTheme,
+  overrides: Partial<ParlrTheme>,
+): ParlrTheme {
+  return {
+    colors: { ...base.colors, ...overrides.colors },
+    borderRadius: { ...base.borderRadius, ...overrides.borderRadius },
+    spacing: { ...base.spacing, ...overrides.spacing },
+    typography: { ...base.typography, ...overrides.typography },
+  };
+}

package/src/core/types.ts

@@ -0,0 +1,237 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - Core Types
+// ---------------------------------------------------------------------------
+
+import type { ParlrError } from './errors';
+import type { ParlrTheme } from './theme';
+
+/** SDK configuration. Only `workspaceId` is required. */
+export interface ParlrConfig {
+  /** Unique workspace identifier (e.g. "ws_abc123"). */
+  workspaceId: string;
+  /** REST API base URL. Defaults to https://api.parlr.chat/api/v1/widget */
+  apiBaseUrl?: string;
+  /** WebSocket endpoint. Defaults to wss://ws.parlr.chat/ws */
+  wsUrl?: string;
+  /** Locale code (BCP-47). Defaults to "fr". */
+  locale?: string;
+  /** Enable verbose console logging. Defaults to false. */
+  debug?: boolean;
+  /** Global error callback for the host app to monitor SDK errors. */
+  onError?: (error: ParlrError) => void;
+  /** HMAC identity verification token for secure identification. */
+  identityToken?: string;
+  /** Custom theme overrides. Merged with the default light/dark theme. */
+  theme?: Partial<ParlrTheme>;
+}
+
+/** Resolved configuration with all defaults applied. */
+export interface ResolvedConfig {
+  workspaceId: string;
+  apiBaseUrl: string;
+  wsUrl: string;
+  locale: string;
+  debug: boolean;
+  onError?: (error: ParlrError) => void;
+  identityToken?: string;
+}
+
+/** Visitor / contact identity passed by the host app. */
+export interface ParlrUser {
+  email?: string;
+  name?: string;
+  firstName?: string;
+  lastName?: string;
+  externalId?: string;
+  phone?: string;
+  company?: string;
+  customAttributes?: Record<string, unknown>;
+}
+
+/** Persisted session returned by the widget API. */
+export interface Session {
+  token: string;
+  contactId: string;
+  workspaceId: string;
+  expiresAt: string;
+}
+
+/** Conversation summary. */
+export interface Conversation {
+  id: string;
+  status: 'open' | 'resolved' | 'pending' | 'closed';
+  subject: string | null;
+  lastMessageAt: string | null;
+  unreadCount: number;
+  assignee?: {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+  } | null;
+}
+
+/** Attachment on a message. */
+export interface Attachment {
+  id: string;
+  name: string;
+  url: string;
+  contentType: string;
+  size: number;
+}
+
+/** Content type of a message. */
+export type MessageContentType = 'text' | 'image' | 'file' | 'rich';
+
+/** CSAT rating request. */
+export interface RatingRequest {
+  score: number;
+  comment?: string;
+}
+
+/** Chat message within a conversation. */
+export interface Message {
+  id: string;
+  conversationId: string;
+  senderType: 'contact' | 'agent';
+  senderName?: string;
+  senderAvatarUrl?: string;
+  content: string;
+  createdAt: string;
+  /** Client-generated UUID used for optimistic updates and idempotency. */
+  clientId?: string;
+  /** Delivery status for optimistic messages. */
+  status?: 'sending' | 'sent' | 'failed' | 'read';
+  /** File/media attachments. */
+  attachments?: Attachment[];
+  /** Content type of the message body. */
+  contentType?: MessageContentType;
+  /** Rich content metadata (cards, buttons, etc.). */
+  metadata?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket event types — discriminated unions for type safety
+// ---------------------------------------------------------------------------
+
+export type WsOutgoingType =
+  | 'auth'
+  | 'send_message'
+  | 'typing_start'
+  | 'typing_stop'
+  | 'message_seen'
+  | 'ping';
+
+export type WsIncomingType =
+  | 'auth_ok'
+  | 'auth_error'
+  | 'new_message'
+  | 'typing_start'
+  | 'typing_stop'
+  | 'message_seen'
+  | 'conversation_updated'
+  | 'pong'
+  | 'disconnected'
+  | 'error';
+
+export interface WsOutgoingPayload {
+  type: WsOutgoingType;
+  payload?: Record<string, unknown>;
+}
+
+export interface WsIncomingPayload {
+  type: WsIncomingType;
+  payload?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Typed WebSocket event payloads (incoming)
+// ---------------------------------------------------------------------------
+
+export interface WsNewMessagePayload {
+  id: string;
+  conversationId: string;
+  senderType: 'contact' | 'agent';
+  senderName?: string;
+  senderAvatarUrl?: string;
+  content: string;
+  createdAt: string;
+  clientId?: string;
+}
+
+export interface WsTypingPayload {
+  conversationId: string;
+  senderType?: 'agent' | 'contact';
+  senderName?: string;
+}
+
+export interface WsMessageSeenPayload {
+  conversationId: string;
+  messageId: string;
+  seenBy: string;
+}
+
+export interface WsConversationUpdatedPayload {
+  conversationId: string;
+  status?: 'open' | 'resolved' | 'pending' | 'closed';
+  assignee?: { id: string; name: string } | null;
+}
+
+export interface WsAuthOkPayload {
+  contactId: string;
+}
+
+export interface WsAuthErrorPayload {
+  code?: number;
+  reason?: string;
+  message?: string;
+}
+
+export interface WsErrorPayload {
+  code?: string;
+  message?: string;
+}
+
+/** Type-safe mapping from incoming WS event type to its payload. */
+export interface WsEventMap {
+  auth_ok: WsAuthOkPayload;
+  auth_error: WsAuthErrorPayload;
+  new_message: WsNewMessagePayload;
+  typing_start: WsTypingPayload;
+  typing_stop: WsTypingPayload;
+  message_seen: WsMessageSeenPayload;
+  conversation_updated: WsConversationUpdatedPayload;
+  pong: Record<string, never>;
+  disconnected: { code?: number; reason?: string };
+  error: WsErrorPayload;
+}
+
+// ---------------------------------------------------------------------------
+// API response wrappers
+// ---------------------------------------------------------------------------
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  meta: {
+    page: number;
+    perPage: number;
+    total: number;
+    hasMore: boolean;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Provider / context shape
+// ---------------------------------------------------------------------------
+
+export interface ParlrContextValue {
+  config: ResolvedConfig;
+  session: Session | null;
+  isReady: boolean;
+  isConnected: boolean;
+  conversations: Conversation[];
+  unreadCount: number;
+  identify: (user: ParlrUser) => Promise<void>;
+  refreshConversations: () => Promise<void>;
+  /** Resolved theme (light or dark, merged with user overrides). */
+  theme: ParlrTheme;
+}