@squad-sports/react-native 1.3.1

package/src/realtime/DeepLinkHandler.ts

@@ -0,0 +1,113 @@
+import { Linking } from 'react-native';
+
+export interface DeepLinkRoute {
+  screen: string;
+  params?: Record<string, string>;
+}
+
+const SQUAD_SCHEME = 'squad';
+const UNIVERSAL_LINK_HOST = 'app.withyoursquad.com';
+
+/**
+ * Parses Squad deep links and universal links into navigation actions.
+ *
+ * Supported URLs:
+ * - squad://invite/{code}
+ * - squad://profile/{userId}
+ * - squad://message/{connectionId}
+ * - squad://poll/{pollId}
+ * - https://app.withyoursquad.com/invite/{code}
+ * - https://app.withyoursquad.com/profile/{userId}
+ */
+export class DeepLinkHandler {
+  private static listener: ReturnType<typeof Linking.addEventListener> | null = null;
+
+  /**
+   * Parse a URL into a navigation route.
+   */
+  static parseUrl(url: string): DeepLinkRoute | null {
+    try {
+      let path: string;
+
+      if (url.startsWith(`${SQUAD_SCHEME}://`)) {
+        path = url.replace(`${SQUAD_SCHEME}://`, '');
+      } else if (url.includes(UNIVERSAL_LINK_HOST)) {
+        const urlObj = new URL(url);
+        path = urlObj.pathname.replace(/^\//, '');
+      } else {
+        return null;
+      }
+
+      const segments = path.split('/').filter(Boolean);
+      if (segments.length === 0) return null;
+
+      const [type, id] = segments;
+
+      switch (type) {
+        case 'invite':
+          return id ? { screen: 'Invite', params: { code: id } } : { screen: 'Invite' };
+        case 'profile':
+          return id ? { screen: 'Profile', params: { userId: id } } : null;
+        case 'message':
+        case 'messaging':
+          return id ? { screen: 'Messaging', params: { connectionId: id } } : null;
+        case 'poll':
+          return id ? { screen: 'PollResponse', params: { pollId: id } } : null;
+        case 'event':
+        case 'events':
+          return { screen: 'Events' };
+        case 'wallet':
+          return { screen: 'Wallet' };
+        case 'freestyle':
+          return { screen: 'FreestyleCreate' };
+        default:
+          return { screen: 'Home' };
+      }
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Start listening for deep links.
+   * Returns a cleanup function.
+   */
+  static startListening(onRoute: (route: DeepLinkRoute) => void): () => void {
+    // Handle initial URL (cold start)
+    Linking.getInitialURL().then(url => {
+      if (url) {
+        const route = DeepLinkHandler.parseUrl(url);
+        if (route) onRoute(route);
+      }
+    });
+
+    // Handle URLs while app is running
+    const subscription = Linking.addEventListener('url', ({ url }) => {
+      const route = DeepLinkHandler.parseUrl(url);
+      if (route) onRoute(route);
+    });
+
+    return () => subscription.remove();
+  }
+
+  /**
+   * React Navigation linking config for automatic deep link handling.
+   */
+  static get linkingConfig() {
+    return {
+      prefixes: [`${SQUAD_SCHEME}://`, `https://${UNIVERSAL_LINK_HOST}`],
+      config: {
+        screens: {
+          Home: '',
+          Invite: 'invite/:code?',
+          Profile: 'profile/:userId',
+          Messaging: 'message/:connectionId',
+          PollResponse: 'poll/:pollId',
+          Events: 'events',
+          Wallet: 'wallet',
+          FreestyleCreate: 'freestyle',
+        },
+      },
+    };
+  }
+}

package/src/realtime/EventProcessor.ts

@@ -0,0 +1,313 @@
+import EventEmitter from 'eventemitter3';
+import type { SquadApiClient } from '@squad-sports/core';
+
+/* eslint-disable */
+// Ambient declaration for EventSource in React Native environments
+interface IEventSource {
+  readyState: number;
+  close(): void;
+  addEventListener(type: string, listener: (event: any) => void): void;
+  removeEventListener(type: string, listener: (event: any) => void): void;
+}
+declare var EventSource: { new(url: string, options?: any): IEventSource; OPEN: number };
+/* eslint-enable */
+
+export type ConnectionQuality = 'good' | 'poor' | 'disconnected';
+
+interface QueuedEvent {
+  type: string;
+  data: unknown;
+  attempts: number;
+  timestamp: number;
+}
+
+/**
+ * EventProcessor manages the real-time SSE connection and forwards
+ * server events to the rest of the app via an EventEmitter.
+ *
+ * Ported from squad-demo/src/clients/EventProcessor.ts (1119 lines),
+ * simplified for SDK use.
+ *
+ * Event types emitted:
+ * - `connection:quality` — connection state changes
+ * - `squad:member:add` / `squad:member:remove` — squad membership changes
+ * - `squad:invite:sent` / `squad:invite:accepted` — invite lifecycle
+ * - `connection:{id}:message:create` — new message in a connection
+ * - `message:create` — global new message (for badge counts)
+ * - `user:{id}:update` — user profile updated
+ * - `feed:update` — freestyle feed changed
+ * - `poll:update` — poll data changed
+ * - `attendee:update` — event attendance changed
+ * - `auth:invalid` — session expired
+ */
+export class EventProcessor {
+  private static instance: EventProcessor | null = null;
+
+  readonly emitter = new EventEmitter();
+
+  private eventSource: IEventSource | null = null;
+  private apiClient: SquadApiClient | null = null;
+  private allowEvents = false;
+  private connectionQuality: ConnectionQuality = 'disconnected';
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private eventBuffer: QueuedEvent[] = [];
+  private processedEventIds = new Map<string, number>();
+  private insertionCount = 0;
+
+  // Backoff config
+  private readonly INITIAL_BACKOFF = 1000;
+  private readonly MAX_BACKOFF = 30000;
+  private readonly BACKOFF_MULTIPLIER = 2;
+  private readonly MAX_RECONNECT_ATTEMPTS = 10;
+  private readonly MAX_BUFFER_SIZE = 500;
+
+  private constructor() {}
+
+  static get shared(): EventProcessor {
+    if (!EventProcessor.instance) {
+      EventProcessor.instance = new EventProcessor();
+    }
+    return EventProcessor.instance;
+  }
+
+  static reset(): void {
+    EventProcessor.instance?.disconnect();
+    EventProcessor.instance = null;
+  }
+
+  // --- Configuration ---
+
+  setApiClient(client: SquadApiClient): void {
+    this.apiClient = client;
+  }
+
+  setShouldAllowEvents(allow: boolean): void {
+    this.allowEvents = allow;
+    if (!allow) {
+      this.disconnect();
+    }
+  }
+
+  getConnectionQuality(): ConnectionQuality {
+    return this.connectionQuality;
+  }
+
+  // --- Connection lifecycle ---
+
+  /**
+   * Establish the SSE connection to the server.
+   * Called by the provider when a valid access token is available.
+   */
+  async connect(): Promise<void> {
+    if (!this.apiClient || !this.allowEvents) {
+      return;
+    }
+
+    const token = this.apiClient.currentToken;
+    if (!token) {
+      return;
+    }
+
+    // Disconnect existing connection
+    this.closeEventSource();
+
+    const baseUrl = this.apiClient.baseUrl;
+    const url = `${baseUrl}/v2/events`;
+
+    try {
+      // Create EventSource with auth header
+      // Note: In React Native, we use the vendor react-native-sse library
+      // which supports custom headers. For the SDK, we use a dynamic import.
+      let RNEventSource: any;
+      try {
+        RNEventSource = (await import('react-native-sse')).default;
+      } catch {
+        // react-native-sse not available — use native EventSource if available
+        if (typeof EventSource !== 'undefined') {
+          RNEventSource = EventSource;
+        } else {
+          console.warn('[EventProcessor] No EventSource implementation available');
+          return;
+        }
+      }
+
+      const es = new RNEventSource(url, {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+
+      this.eventSource = es;
+      this.reconnectAttempts = 0;
+
+      // Handle connection open
+      es.addEventListener('open', () => {
+        this.updateConnectionQuality('good');
+        this.reconnectAttempts = 0;
+        this.flushEventBuffer();
+      });
+
+      // Handle incoming messages
+      es.addEventListener('message', (event: any) => {
+        if (!event?.data) return;
+
+        try {
+          const parsed = JSON.parse(event.data);
+          const type = parsed.type ?? event.type ?? 'unknown';
+          const data = parsed.data ?? parsed;
+
+          this.processEvent(type, data);
+        } catch {
+          // Non-JSON event — emit raw
+          this.processEvent('raw', event.data);
+        }
+      });
+
+      // Handle errors
+      es.addEventListener('error', () => {
+        this.updateConnectionQuality('disconnected');
+        this.closeEventSource();
+        this.scheduleReconnect();
+      });
+
+      // Handle specific event types the server sends
+      const serverEventTypes = [
+        'connected',
+        'squad:member:add', 'squad:member:remove',
+        'squad:invite:sent', 'squad:invite:accepted',
+        'feed:update', 'poll:update',
+        'attendee:update',
+      ];
+
+      for (const eventType of serverEventTypes) {
+        es.addEventListener(eventType, (event: any) => {
+          try {
+            const data = event?.data ? JSON.parse(event.data) : {};
+            this.processEvent(eventType, data);
+          } catch {
+            this.processEvent(eventType, {});
+          }
+        });
+      }
+    } catch (error) {
+      console.error('[EventProcessor] Connection failed:', error);
+      this.updateConnectionQuality('disconnected');
+      this.scheduleReconnect();
+    }
+  }
+
+  /**
+   * Disconnect the SSE connection.
+   */
+  disconnect(): void {
+    this.closeEventSource();
+    this.clearReconnectTimer();
+    this.updateConnectionQuality('disconnected');
+  }
+
+  // --- Event processing ---
+
+  private processEvent(type: string, data: unknown): void {
+    // Deduplication with TTL
+    const eventKey = `${type}:${JSON.stringify(data)}`;
+    const now = Date.now();
+    if (this.processedEventIds.has(eventKey)) return;
+    this.processedEventIds.set(eventKey, now);
+    this.insertionCount++;
+
+    // Prune stale entries every 100 insertions
+    if (this.insertionCount % 100 === 0) {
+      const oneHourAgo = now - 60 * 60 * 1000;
+      for (const [key, ts] of this.processedEventIds) {
+        if (ts < oneHourAgo) this.processedEventIds.delete(key);
+      }
+    }
+
+    // Hard cap at 5000
+    if (this.processedEventIds.size > 5000) {
+      const entries = Array.from(this.processedEventIds.entries())
+        .sort((a, b) => a[1] - b[1]);
+      const toRemove = entries.slice(0, entries.length - 3000);
+      for (const [key] of toRemove) this.processedEventIds.delete(key);
+    }
+
+    // Buffer if connection is poor
+    if (this.connectionQuality === 'poor') {
+      this.addToBuffer({ type, data, attempts: 0, timestamp: Date.now() });
+      return;
+    }
+
+    // Emit the event
+    this.emitter.emit(type, data);
+
+    // Also emit global message event for connection-specific messages
+    if (/^connection:.+:message:create$/.test(type)) {
+      this.emitter.emit('message:create', data);
+    }
+  }
+
+  // --- Buffer management ---
+
+  private addToBuffer(event: QueuedEvent): void {
+    if (this.eventBuffer.length >= this.MAX_BUFFER_SIZE) {
+      this.eventBuffer.shift(); // Drop oldest
+    }
+    this.eventBuffer.push(event);
+  }
+
+  private flushEventBuffer(): void {
+    const events = [...this.eventBuffer];
+    this.eventBuffer = [];
+
+    for (const event of events) {
+      this.emitter.emit(event.type, event.data);
+    }
+  }
+
+  // --- Reconnection ---
+
+  private scheduleReconnect(): void {
+    if (this.reconnectAttempts >= this.MAX_RECONNECT_ATTEMPTS) {
+      console.warn('[EventProcessor] Max reconnect attempts reached');
+      this.emitter.emit('connection:maxRetriesReached');
+      return;
+    }
+
+    this.clearReconnectTimer();
+    this.reconnectAttempts++;
+
+    const delay = Math.min(
+      this.INITIAL_BACKOFF * Math.pow(this.BACKOFF_MULTIPLIER, this.reconnectAttempts - 1),
+      this.MAX_BACKOFF,
+    );
+    const jitter = Math.random() * 0.1 * delay;
+
+    this.reconnectTimer = setTimeout(() => {
+      this.connect();
+    }, delay + jitter);
+  }
+
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  // --- Helpers ---
+
+  private closeEventSource(): void {
+    if (this.eventSource) {
+      try {
+        (this.eventSource as any).close();
+      } catch {}
+      this.eventSource = null;
+    }
+  }
+
+  private updateConnectionQuality(quality: ConnectionQuality): void {
+    if (quality !== this.connectionQuality) {
+      this.connectionQuality = quality;
+      this.emitter.emit('connection:quality', quality);
+    }
+  }
+}

package/src/realtime/NetworkMonitor.ts

@@ -0,0 +1,84 @@
+import { useEffect, useState, useCallback } from 'react';
+
+type NetworkListener = (isOnline: boolean) => void;
+
+/**
+ * Monitors network connectivity and notifies listeners.
+ * Uses @react-native-community/netinfo when available.
+ */
+export class NetworkMonitor {
+  private static instance: NetworkMonitor | null = null;
+  private listeners = new Set<NetworkListener>();
+  private isOnline = true;
+  private unsubscribe: (() => void) | null = null;
+
+  static get shared(): NetworkMonitor {
+    if (!NetworkMonitor.instance) {
+      NetworkMonitor.instance = new NetworkMonitor();
+    }
+    return NetworkMonitor.instance;
+  }
+
+  async startMonitoring(): Promise<void> {
+    try {
+      const NetInfo = (await import('@react-native-community/netinfo')).default;
+      this.unsubscribe = NetInfo.addEventListener((state: { isConnected: boolean | null; isInternetReachable: boolean | null }) => {
+        const online = !!(state.isConnected && state.isInternetReachable !== false);
+        this.updateOnlineState(online);
+      });
+    } catch {
+      // NetInfo not available — assume online
+      this.isOnline = true;
+    }
+  }
+
+  stopMonitoring(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+  }
+
+  addListener(listener: NetworkListener): void {
+    this.listeners.add(listener);
+  }
+
+  removeListener(listener: NetworkListener): void {
+    this.listeners.delete(listener);
+  }
+
+  getIsOnline(): boolean {
+    return this.isOnline;
+  }
+
+  private updateOnlineState(online: boolean): void {
+    if (online === this.isOnline) return;
+    this.isOnline = online;
+
+    // Snapshot listeners to avoid mutation during iteration
+    const snapshot = [...this.listeners];
+    for (const listener of snapshot) {
+      listener(online);
+    }
+  }
+}
+
+/**
+ * Hook that provides current network connectivity status.
+ */
+export function useNetworkStatus() {
+  const [isOnline, setIsOnline] = useState(true);
+
+  useEffect(() => {
+    const monitor = NetworkMonitor.shared;
+    monitor.startMonitoring();
+    setIsOnline(monitor.getIsOnline());
+
+    const listener = (online: boolean) => setIsOnline(online);
+    monitor.addListener(listener);
+
+    return () => {
+      monitor.removeListener(listener);
+    };
+  }, []);
+
+  return isOnline;
+}

package/src/realtime/OfflineQueue.ts

@@ -0,0 +1,133 @@
+import type { StorageAdapter } from '@squad-sports/core';
+
+export type OfflineActionType =
+  | 'message:create'
+  | 'freestyle:create'
+  | 'poll:response'
+  | 'connection:invite'
+  | 'message:reaction'
+  | 'freestyle:reaction'
+  | 'user:update';
+
+export interface OfflineAction {
+  id: string;
+  type: OfflineActionType;
+  payload: unknown;
+  createdAt: number;
+  attempts: number;
+}
+
+const STORAGE_KEY = 'SQUAD_SDK_OFFLINE_QUEUE';
+
+/**
+ * Queues mutations when offline and replays them when connectivity returns.
+ * Ported from squad-demo/src/atoms/sync/offline-support.ts.
+ */
+export class OfflineQueue {
+  private queue: OfflineAction[] = [];
+  private isProcessing = false;
+  private storage: StorageAdapter | null = null;
+
+  constructor(storage?: StorageAdapter) {
+    this.storage = storage ?? null;
+    this.loadFromStorage();
+  }
+
+  /**
+   * Add an action to the offline queue.
+   */
+  enqueue(type: OfflineActionType, payload: unknown): void {
+    const action: OfflineAction = {
+      id: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      type,
+      payload,
+      createdAt: Date.now(),
+      attempts: 0,
+    };
+
+    this.queue.push(action);
+    this.persistToStorage();
+  }
+
+  /**
+   * Process all queued actions.
+   * Call this when connectivity is restored.
+   */
+  async processQueue(
+    executor: (action: OfflineAction) => Promise<boolean>,
+  ): Promise<{ succeeded: number; failed: number }> {
+    if (this.isProcessing || this.queue.length === 0) {
+      return { succeeded: 0, failed: 0 };
+    }
+
+    this.isProcessing = true;
+    let succeeded = 0;
+    let failed = 0;
+
+    const pending = [...this.queue];
+    this.queue = [];
+
+    for (const action of pending) {
+      try {
+        action.attempts++;
+        const success = await executor(action);
+
+        if (success) {
+          succeeded++;
+        } else {
+          // Re-queue if under max attempts
+          if (action.attempts < 3) {
+            this.queue.push(action);
+          } else {
+            failed++;
+          }
+        }
+      } catch {
+        if (action.attempts < 3) {
+          this.queue.push(action);
+        } else {
+          failed++;
+        }
+      }
+    }
+
+    this.isProcessing = false;
+    this.persistToStorage();
+
+    return { succeeded, failed };
+  }
+
+  /**
+   * Get the number of pending actions.
+   */
+  get pendingCount(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * Clear all queued actions.
+   */
+  clear(): void {
+    this.queue = [];
+    this.persistToStorage();
+  }
+
+  // --- Persistence ---
+
+  private async loadFromStorage(): Promise<void> {
+    if (!this.storage) return;
+    try {
+      const raw = await this.storage.getItem(STORAGE_KEY);
+      if (raw) {
+        this.queue = JSON.parse(raw);
+      }
+    } catch {}
+  }
+
+  private async persistToStorage(): Promise<void> {
+    if (!this.storage) return;
+    try {
+      await this.storage.setItem(STORAGE_KEY, JSON.stringify(this.queue));
+    } catch {}
+  }
+}