@parlr/react-native 0.1.0

package/src/core/api.ts

@@ -0,0 +1,406 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - REST API Client
+// ---------------------------------------------------------------------------
+//
+// Wraps all widget-facing REST endpoints with automatic retry, exponential
+// backoff, session-token injection, and response validation.
+// ---------------------------------------------------------------------------
+
+import axios, {
+  type AxiosInstance,
+  type AxiosError,
+  type InternalAxiosRequestConfig,
+} from 'axios';
+import {
+  ParlrAuthError,
+  ParlrNetworkError,
+  ParlrValidationError,
+} from './errors';
+import type {
+  Attachment,
+  Conversation,
+  ParlrUser,
+  Message,
+  PaginatedResponse,
+  ResolvedConfig,
+  Session,
+} from './types';
+
+// ---------------------------------------------------------------------------
+// Retry configuration
+// ---------------------------------------------------------------------------
+
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 500;
+const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isRetryable(error: AxiosError): boolean {
+  if (!error.response) return true; // network error
+  return RETRYABLE_STATUS.has(error.response.status);
+}
+
+// ---------------------------------------------------------------------------
+// Response validators
+// ---------------------------------------------------------------------------
+
+function validateSession(data: unknown): Session {
+  if (!data || typeof data !== 'object') {
+    throw new ParlrValidationError(
+      'Invalid session response: expected an object',
+    );
+  }
+  const d = data as Record<string, unknown>;
+  // Accept both "token" and "sessionToken" from the server.
+  const token = (typeof d.token === 'string' ? d.token : d.sessionToken) as
+    | string
+    | undefined;
+  if (
+    typeof token !== 'string' ||
+    typeof d.contactId !== 'string' ||
+    typeof d.workspaceId !== 'string' ||
+    typeof d.expiresAt !== 'string'
+  ) {
+    throw new ParlrValidationError(
+      'Invalid session response: missing required fields (token, contactId, workspaceId, expiresAt)',
+    );
+  }
+  return {
+    token,
+    contactId: d.contactId,
+    workspaceId: d.workspaceId,
+    expiresAt: d.expiresAt,
+  };
+}
+
+function validateMessage(data: unknown): Message {
+  if (!data || typeof data !== 'object') {
+    throw new ParlrValidationError(
+      'Invalid message response: expected an object',
+    );
+  }
+  const d = data as Record<string, unknown>;
+  if (
+    typeof d.id !== 'string' ||
+    typeof d.conversationId !== 'string' ||
+    typeof d.senderType !== 'string'
+  ) {
+    throw new ParlrValidationError(
+      'Invalid message response: missing required fields (id, conversationId, senderType)',
+    );
+  }
+  return {
+    id: d.id,
+    conversationId: d.conversationId,
+    content: typeof d.content === 'string' ? d.content : '',
+    contentType: typeof d.contentType === 'string' ? (d.contentType as Message['contentType']) : 'text',
+    senderType: d.senderType as Message['senderType'],
+    senderName: typeof d.senderName === 'string' ? d.senderName : undefined,
+    senderAvatarUrl: typeof d.senderAvatarUrl === 'string' ? d.senderAvatarUrl : undefined,
+    createdAt: typeof d.createdAt === 'string' ? d.createdAt : new Date().toISOString(),
+    clientId: typeof d.clientId === 'string' ? d.clientId : undefined,
+    attachments: Array.isArray(d.attachments) ? (d.attachments as Attachment[]) : [],
+    status: 'sent',
+  };
+}
+
+function validateConversation(data: unknown): Conversation {
+  if (!data || typeof data !== 'object') {
+    throw new ParlrValidationError(
+      'Invalid conversation response: expected an object',
+    );
+  }
+  const d = data as Record<string, unknown>;
+  if (
+    typeof d.id !== 'string' ||
+    typeof d.status !== 'string'
+  ) {
+    throw new ParlrValidationError(
+      'Invalid conversation response: missing required fields (id, status)',
+    );
+  }
+  return {
+    id: d.id,
+    status: d.status as Conversation['status'],
+    subject: typeof d.subject === 'string' ? d.subject : null,
+    lastMessageAt: typeof d.lastMessageAt === 'string' ? d.lastMessageAt : null,
+    unreadCount: typeof d.unreadCount === 'number' ? d.unreadCount : 0,
+    assignee: d.assignee && typeof d.assignee === 'object' ? d.assignee as Conversation['assignee'] : null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Error mapper
+// ---------------------------------------------------------------------------
+
+function mapAxiosError(error: AxiosError): Error {
+  if (!error.response) {
+    return new ParlrNetworkError(
+      error.message || 'Network request failed',
+      undefined,
+      { cause: error },
+    );
+  }
+
+  const status = error.response.status;
+
+  if (status === 401 || status === 403) {
+    return new ParlrAuthError(
+      `Authentication failed (HTTP ${status})`,
+      { cause: error },
+    );
+  }
+
+  return new ParlrNetworkError(
+    `HTTP ${status}: ${error.message}`,
+    status,
+    { cause: error },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+export interface ParlrApiClient {
+  /** Create a new anonymous session. */
+  createSession(): Promise<Session>;
+
+  /** Identify (or re-identify) the contact behind the current session. */
+  identify(user: ParlrUser): Promise<void>;
+
+  /** List conversations for the current contact. */
+  listConversations(page?: number): Promise<PaginatedResponse<Conversation>>;
+
+  /** Create a new conversation (optionally with a first message). */
+  createConversation(initialMessage?: string): Promise<Conversation>;
+
+  /** Fetch messages for a conversation. */
+  getMessages(
+    conversationId: string,
+    page?: number,
+  ): Promise<PaginatedResponse<Message>>;
+
+  /** Send a message within a conversation. */
+  sendMessage(
+    conversationId: string,
+    content: string,
+    clientId: string,
+  ): Promise<Message>;
+
+  /** Notify the server that the contact is typing. */
+  sendTypingIndicator(
+    conversationId: string,
+    isTyping: boolean,
+  ): Promise<void>;
+
+  /** Close a conversation. */
+  closeConversation(conversationId: string): Promise<Conversation>;
+
+  /** Reopen a closed conversation. */
+  reopenConversation(conversationId: string): Promise<Conversation>;
+
+  /** Upload an attachment to a conversation. */
+  uploadAttachment(conversationId: string, formData: FormData): Promise<Attachment>;
+
+  /** Subscribe to push notifications. */
+  subscribePush(token: string, platform: 'ios' | 'android'): Promise<void>;
+
+  /** Unsubscribe from push notifications. */
+  unsubscribePush(token: string): Promise<void>;
+
+  /** Submit a CSAT rating for a conversation. */
+  submitRating(conversationId: string, score: number, comment?: string): Promise<void>;
+
+  /** Search messages in a conversation. */
+  searchMessages(conversationId: string, query: string): Promise<PaginatedResponse<Message>>;
+}
+
+/**
+ * Create a configured API client bound to a resolved config and an optional
+ * session token accessor (so the token can be refreshed externally).
+ */
+export function createApiClient(
+  config: ResolvedConfig,
+  getToken: () => string | null,
+): ParlrApiClient {
+  const http: AxiosInstance = axios.create({
+    baseURL: config.apiBaseUrl,
+    timeout: 15_000,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'X-Workspace-Id': config.workspaceId,
+    },
+  });
+
+  // --- Inject session token and identity token on every request --------------
+  http.interceptors.request.use((req: InternalAxiosRequestConfig) => {
+    const token = getToken();
+    if (token) {
+      req.headers.set('X-Session-Token', token);
+    }
+    if (config.identityToken) {
+      req.headers.set('X-Identity-Token', config.identityToken);
+    }
+    return req;
+  });
+
+  // --- Retry interceptor -----------------------------------------------------
+  http.interceptors.response.use(undefined, async (error: AxiosError) => {
+    const requestConfig = error.config as InternalAxiosRequestConfig & {
+      _retryCount?: number;
+    };
+    if (!requestConfig) throw mapAxiosError(error);
+
+    requestConfig._retryCount = requestConfig._retryCount ?? 0;
+
+    if (requestConfig._retryCount >= MAX_RETRIES || !isRetryable(error)) {
+      throw mapAxiosError(error);
+    }
+
+    requestConfig._retryCount += 1;
+    const jitter = Math.random() * 200;
+    const backoff =
+      BASE_DELAY_MS * Math.pow(2, requestConfig._retryCount - 1) + jitter;
+
+    if (config.debug) {
+      console.log(
+        `[@parlr/react-native] Retry #${requestConfig._retryCount} after ${Math.round(backoff)}ms`,
+      );
+    }
+
+    await delay(backoff);
+    return http.request(requestConfig);
+  });
+
+  // --- Public API methods ----------------------------------------------------
+  return {
+    async createSession(): Promise<Session> {
+      const { data } = await http.post('/sessions', {
+        workspaceId: config.workspaceId,
+      });
+      return validateSession(data);
+    },
+
+    async identify(user: ParlrUser): Promise<void> {
+      await http.post('/identify', user);
+    },
+
+    async listConversations(
+      page = 1,
+    ): Promise<PaginatedResponse<Conversation>> {
+      const { data } = await http.get(
+        '/conversations',
+        { params: { page } },
+      );
+      // Handle both paginated ({ data: [...], meta: {...} }) and plain array responses.
+      if (Array.isArray(data)) {
+        const convs = data.map(validateConversation);
+        return { data: convs, meta: { total: convs.length, page: 1, perPage: convs.length, hasMore: false } };
+      }
+      return data as PaginatedResponse<Conversation>;
+    },
+
+    async createConversation(initialMessage?: string): Promise<Conversation> {
+      const { data } = await http.post('/conversations', {
+        ...(initialMessage ? { message: initialMessage } : {}),
+      });
+      return validateConversation(data);
+    },
+
+    async getMessages(
+      conversationId: string,
+      page = 1,
+    ): Promise<PaginatedResponse<Message>> {
+      const { data } = await http.get(
+        `/conversations/${encodeURIComponent(conversationId)}/messages`,
+        { params: { page } },
+      );
+      // Handle both paginated ({ data: [...], meta: {...} }) and plain array responses.
+      if (Array.isArray(data)) {
+        const messages = data.map(validateMessage);
+        return { data: messages, meta: { total: messages.length, page: 1, perPage: messages.length, hasMore: false } };
+      }
+      return data as PaginatedResponse<Message>;
+    },
+
+    async sendMessage(
+      conversationId: string,
+      content: string,
+      clientId: string,
+    ): Promise<Message> {
+      const { data } = await http.post(
+        `/conversations/${encodeURIComponent(conversationId)}/messages`,
+        { content, clientId },
+      );
+      return validateMessage(data);
+    },
+
+    async sendTypingIndicator(
+      conversationId: string,
+      isTyping: boolean,
+    ): Promise<void> {
+      await http.post(
+        `/conversations/${encodeURIComponent(conversationId)}/typing`,
+        { isTyping },
+      );
+    },
+
+    async closeConversation(conversationId: string): Promise<Conversation> {
+      const { data } = await http.post(
+        `/conversations/${encodeURIComponent(conversationId)}/close`,
+      );
+      return validateConversation(data);
+    },
+
+    async reopenConversation(conversationId: string): Promise<Conversation> {
+      const { data } = await http.post(
+        `/conversations/${encodeURIComponent(conversationId)}/reopen`,
+      );
+      return validateConversation(data);
+    },
+
+    async uploadAttachment(conversationId: string, formData: FormData): Promise<Attachment> {
+      const { data } = await http.post(
+        `/conversations/${encodeURIComponent(conversationId)}/attachments`,
+        formData,
+        { headers: { 'Content-Type': 'multipart/form-data' } },
+      );
+      return data as Attachment;
+    },
+
+    async subscribePush(token: string, platform: 'ios' | 'android'): Promise<void> {
+      await http.post('/push/subscribe', { token, platform });
+    },
+
+    async unsubscribePush(token: string): Promise<void> {
+      await http.post('/push/unsubscribe', { token });
+    },
+
+    async submitRating(conversationId: string, score: number, comment?: string): Promise<void> {
+      await http.post(
+        `/conversations/${encodeURIComponent(conversationId)}/rating`,
+        { score, comment },
+      );
+    },
+
+    async searchMessages(
+      conversationId: string,
+      query: string,
+    ): Promise<PaginatedResponse<Message>> {
+      const { data } = await http.get(
+        `/conversations/${encodeURIComponent(conversationId)}/messages/search`,
+        { params: { q: query } },
+      );
+      if (Array.isArray(data)) {
+        const messages = data.map(validateMessage);
+        return { data: messages, meta: { total: messages.length, page: 1, perPage: messages.length, hasMore: false } };
+      }
+      return data as PaginatedResponse<Message>;
+    },
+  };
+}

package/src/core/config.ts

@@ -0,0 +1,39 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - Configuration
+// ---------------------------------------------------------------------------
+
+import type { ParlrConfig, ResolvedConfig } from './types';
+
+const DEFAULTS = {
+  apiBaseUrl: 'https://api.parlr.chat/api/v1/widget',
+  // WebSocket disabled by default — the Java backend uses STOMP protocol,
+  // not the custom JSON protocol this SDK expects. Enable when the Rust
+  // Gateway is deployed: wsUrl: 'wss://ws.parlr.chat/ws'
+  wsUrl: '',
+  locale: 'fr',
+  debug: false,
+} as const;
+
+/**
+ * Resolve a partial user-supplied config into a fully-qualified config with
+ * all defaults applied.
+ *
+ * @throws {Error} if `workspaceId` is missing or empty.
+ */
+export function resolveConfig(partial: ParlrConfig): ResolvedConfig {
+  if (!partial.workspaceId || partial.workspaceId.trim().length === 0) {
+    throw new Error(
+      '[@parlr/react-native] workspaceId is required. ' +
+        'Pass it as a prop to <ParlrProvider workspaceId="ws_xxx" />.',
+    );
+  }
+
+  return {
+    workspaceId: partial.workspaceId.trim(),
+    apiBaseUrl: (partial.apiBaseUrl ?? DEFAULTS.apiBaseUrl).replace(/\/+$/, ''),
+    wsUrl: (partial.wsUrl ?? DEFAULTS.wsUrl).replace(/\/+$/, ''),
+    locale: partial.locale ?? DEFAULTS.locale,
+    debug: partial.debug ?? DEFAULTS.debug,
+    identityToken: partial.identityToken,
+  };
+}

package/src/core/errors.ts

@@ -0,0 +1,68 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - Error Hierarchy
+// ---------------------------------------------------------------------------
+//
+// Typed error classes for structured error handling throughout the SDK.
+// Consumers can use `instanceof` checks to differentiate error types.
+// ---------------------------------------------------------------------------
+
+/**
+ * Base error class for all Parlr SDK errors.
+ */
+export class ParlrError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ParlrError';
+  }
+}
+
+/**
+ * Network-level error (timeout, DNS failure, no internet).
+ */
+export class ParlrNetworkError extends ParlrError {
+  public readonly statusCode?: number;
+
+  constructor(message: string, statusCode?: number, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ParlrNetworkError';
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * Authentication / session error (expired token, invalid session).
+ */
+export class ParlrAuthError extends ParlrError {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ParlrAuthError';
+  }
+}
+
+/**
+ * Validation error (invalid payload from API or WebSocket).
+ */
+export class ParlrValidationError extends ParlrError {
+  public readonly field?: string;
+
+  constructor(message: string, field?: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ParlrValidationError';
+    this.field = field;
+  }
+}
+
+/**
+ * WebSocket connection error (failed to connect, unexpected close).
+ */
+export class ParlrConnectionError extends ParlrError {
+  public readonly code?: number;
+  public readonly reason?: string;
+
+  constructor(message: string, code?: number, reason?: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'ParlrConnectionError';
+    this.code = code;
+    this.reason = reason;
+  }
+}

package/src/core/offlineQueue.ts

@@ -0,0 +1,94 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - Offline Message Queue
+// ---------------------------------------------------------------------------
+//
+// AsyncStorage-based queue for messages sent while offline. Messages are
+// persisted and flushed automatically when connectivity is restored.
+// ---------------------------------------------------------------------------
+
+import type { ParlrApiClient } from './api';
+
+export interface QueuedMessage {
+  conversationId: string;
+  content: string;
+  clientId: string;
+  timestamp: number;
+}
+
+const QUEUE_KEY = '@parlr/offline_queue';
+
+// In-memory queue that mirrors persistent storage.
+let memoryQueue: QueuedMessage[] = [];
+
+// Lazy AsyncStorage accessor — returns null when unavailable.
+function getAsyncStorage(): {
+  getItem: (key: string) => Promise<string | null>;
+  setItem: (key: string, value: string) => Promise<void>;
+} | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require('@react-native-async-storage/async-storage').default;
+  } catch {
+    return null;
+  }
+}
+
+async function persist(): Promise<void> {
+  try {
+    const storage = getAsyncStorage();
+    if (storage) {
+      await storage.setItem(QUEUE_KEY, JSON.stringify(memoryQueue));
+    }
+  } catch {
+    // Persistence is best-effort — the in-memory queue is always available.
+  }
+}
+
+async function hydrate(): Promise<void> {
+  try {
+    const storage = getAsyncStorage();
+    if (storage) {
+      const raw = await storage.getItem(QUEUE_KEY);
+      if (raw) {
+        memoryQueue = JSON.parse(raw) as QueuedMessage[];
+      }
+    }
+  } catch {
+    // Start with an empty queue if hydration fails.
+  }
+}
+
+// Hydrate on module load (non-blocking).
+hydrate();
+
+/** Enqueue a message for later delivery. */
+export async function queueMessage(msg: QueuedMessage): Promise<void> {
+  memoryQueue.push(msg);
+  await persist();
+}
+
+/** Return all currently queued messages. */
+export async function getQueuedMessages(): Promise<QueuedMessage[]> {
+  return [...memoryQueue];
+}
+
+/** Remove a single message from the queue by clientId. */
+export async function removeFromQueue(clientId: string): Promise<void> {
+  memoryQueue = memoryQueue.filter((m) => m.clientId !== clientId);
+  await persist();
+}
+
+/** Attempt to send all queued messages via the API, removing successful ones. */
+export async function flushQueue(api: ParlrApiClient): Promise<void> {
+  const snapshot = [...memoryQueue];
+
+  for (const msg of snapshot) {
+    try {
+      await api.sendMessage(msg.conversationId, msg.content, msg.clientId);
+      await removeFromQueue(msg.clientId);
+    } catch {
+      // Leave failed messages in the queue for the next flush attempt.
+      break;
+    }
+  }
+}

package/src/core/pushNotifications.ts

@@ -0,0 +1,22 @@
+// ---------------------------------------------------------------------------
+// Parlr React Native SDK - Push Notification Helpers
+// ---------------------------------------------------------------------------
+
+import type { ParlrApiClient } from './api';
+
+/** Register a device push token with the Parlr backend. */
+export async function registerPushToken(
+  api: ParlrApiClient,
+  token: string,
+  platform: 'ios' | 'android',
+): Promise<void> {
+  await api.subscribePush(token, platform);
+}
+
+/** Unregister a previously registered push token. */
+export async function unregisterPushToken(
+  api: ParlrApiClient,
+  token: string,
+): Promise<void> {
+  await api.unsubscribePush(token);
+}