@squad-sports/react-native 1.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Squad For Sports, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# Squad Sports SDK for React Native
+
+[![npm version](https://img.shields.io/npm/v/@squad-sports/react-native.svg)](https://www.npmjs.com/package/@squad-sports/react-native)
+[![Platform](https://img.shields.io/badge/platform-iOS%20%7C%20Android-lightgrey.svg)](https://docs.squadforsports.com)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Add fan engagement features to your sports app in minutes. Drop in a single component and get messaging, polls, freestyles, voice calling, sponsorship inventory, and real-time updates.
+
+## Installation
+
+```bash
+npm install @squad-sports/react-native @squad-sports/core
+```
+
+### Peer Dependencies
+
+```bash
+npm install react-native-gesture-handler react-native-safe-area-context \
+  @react-navigation/native @react-navigation/native-stack \
+  @react-native-async-storage/async-storage \
+  react-native-sse expo-secure-store expo-av expo-image expo-image-picker
+```
+
+## Quick Start
+
+```tsx
+import { SquadExperience } from '@squad-sports/react-native';
+
+export default function App() {
+  return (
+    <SquadExperience
+      partnerId="your-partner-id"
+      apiKey="your-api-key"
+    />
+  );
+}
+```
+
+That's it. The SDK auto-resolves your community config, theming, and features from your partner ID.
+
+### With Ticketmaster SSO
+
+```tsx
+<SquadExperience
+  partnerId="your-partner-id"
+  apiKey="your-api-key"
+  ssoToken={ticketmasterAccessToken}
+/>
+```
+
+### With Seamless Partner Auth (No Login Screen)
+
+```tsx
+<SquadExperience
+  partnerId="your-partner-id"
+  apiKey="your-api-key"
+  userData={{
+    email: user.email,
+    displayName: user.name,
+    externalUserId: user.id,
+  }}
+/>
+```
+
+## Features
+
+- **Messaging** — 1:1 messaging with audio messages and reactions
+- **Polls** — Interactive polls with live results and branded sponsor polls
+- **Freestyles** — Audio posts with community-wide sharing
+- **Squad Line** — Real-time voice calls via Twilio
+- **Events** — Event attendance and check-ins
+- **Wallet** — Rewards, coupons, and sponsor promotions
+- **Sponsorship** — In-app sponsorship inventory (branded polls, content cards, banners, interstitials)
+- **Real-Time** — Server-sent events with offline queueing
+- **Analytics** — 28 event types with custom adapter support (Mixpanel, Amplitude)
+- **SSO** — Ticketmaster, OAuth2, SAML, and custom providers
+
+## Documentation
+
+Full integration guide, API reference, and configuration options:
+
+**[docs.squadforsports.com](https://docs.squadforsports.com)**
+
+## Requirements
+
+- React Native 0.73+
+- React 18+
+- iOS 15+ / Android SDK 24+ (Android 7.0)
+- Expo SDK 50+ (if using Expo)
+
+## Get Your Partner ID
+
+Register at **[partners.squadforsports.com](https://partners.squadforsports.com)** to get your partner ID and API key.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@squad-sports/react-native",
+  "version": "1.3.1",
+  "description": "Squad Sports Experience SDK for React Native",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": ["src"],
+  "scripts": {
+    "build": "echo 'RN package uses source directly'",
+    "typecheck": "tsc --noEmit",
+    "test": "jest --passWithNoTests",
+    "clean": "echo 'nothing to clean'"
+  },
+  "dependencies": {
+    "@squad-sports/core": "1.3.1"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0",
+    "@react-native-async-storage/async-storage": ">=1.20.0",
+    "@react-navigation/native": ">=6.0.0",
+    "@react-navigation/native-stack": ">=6.0.0",
+    "@react-navigation/bottom-tabs": ">=6.0.0",
+    "@gorhom/bottom-sheet": ">=5.0.0",
+    "react-native-gesture-handler": ">=2.0.0",
+    "react-native-safe-area-context": ">=4.0.0",
+    "react-native-screens": ">=3.0.0",
+    "react-native-reanimated": ">=3.0.0",
+    "recoil": ">=0.7.0",
+    "expo-av": ">=15.0.0",
+    "expo-image": ">=2.0.0",
+    "@twilio/voice-react-native-sdk": ">=1.0.0",
+    "expo-secure-store": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "expo-secure-store": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/withyoursquad/squad-sports-react-native.git"
+  },
+  "homepage": "https://docs.squadforsports.com"
+}

package/src/SquadExperience.tsx

@@ -0,0 +1,200 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { ActivityIndicator, Pressable, Text, View } from 'react-native';
+import { NavigationContainer, DefaultTheme } from '@react-navigation/native';
+import type { NavigationContainerRef } from '@react-navigation/native';
+import { AnalyticsTracker } from '@squad-sports/core';
+import type { SquadSDKConfig, SquadConfig, SSOProvider, PartnerUserData } from '@squad-sports/core';
+
+import { SquadProvider } from './SquadProvider';
+import { SquadNavigator } from './navigation/SquadNavigator';
+import { SquadSportsSDK } from './SquadSportsSDK';
+import { useTheme } from './theme/ThemeContext';
+import { ScreenErrorBoundary } from './components/ErrorBoundary';
+
+function SquadNavigationContainer() {
+  const { theme } = useTheme();
+  const navigationRef = useRef<NavigationContainerRef<any>>(null);
+  const routeNameRef = useRef<string | undefined>(undefined);
+
+  const navigationTheme = {
+    ...DefaultTheme,
+    colors: {
+      ...DefaultTheme.colors,
+      background: theme.screenBackground,
+    },
+  };
+
+  const onReady = useCallback(() => {
+    routeNameRef.current = navigationRef.current?.getCurrentRoute()?.name;
+  }, []);
+
+  const onStateChange = useCallback(() => {
+    const currentRouteName = navigationRef.current?.getCurrentRoute()?.name;
+    if (currentRouteName && currentRouteName !== routeNameRef.current) {
+      AnalyticsTracker.shared.trackScreen(currentRouteName);
+      routeNameRef.current = currentRouteName;
+    }
+  }, []);
+
+  return (
+    <NavigationContainer
+      ref={navigationRef}
+      theme={navigationTheme}
+      {...{ independent: true } as any}
+      onReady={onReady}
+      onStateChange={onStateChange}
+    >
+      <SquadNavigator />
+    </NavigationContainer>
+  );
+}
+
+interface SquadExperienceProps {
+  // --- Simple path (recommended) ---
+
+  /** Your Nexus partner ID. Everything else auto-resolves. */
+  partnerId?: string;
+
+  /** Your API key from partners.squadforsports.com. Required when using partnerId. */
+  apiKey?: string;
+
+  /** Pre-authenticated SSO token (Ticketmaster, OAuth, etc.) */
+  ssoToken?: string;
+
+  /** SSO provider (defaults to 'ticketmaster' if ssoToken is provided) */
+  ssoProvider?: SSOProvider;
+
+  /** User data from host app for seamless partner auth (no login required) */
+  userData?: PartnerUserData;
+
+  // --- Full config path ---
+
+  /** Full SDK configuration (overrides partnerId if both provided) */
+  config?: SquadConfig;
+
+  // --- Callbacks ---
+
+  /** Called when SDK initialization completes */
+  onReady?: () => void;
+
+  /** Called if SDK initialization fails */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Self-contained Squad Sports experience.
+ *
+ * Drop this into any React Native app. Three integration levels:
+ *
+ * **Simplest (Nexus partner):**
+ * ```tsx
+ * <SquadExperience partnerId="acme-sports" />
+ * ```
+ *
+ * **With Ticketmaster SSO:**
+ * ```tsx
+ * <SquadExperience partnerId="acme-sports" ssoToken={tmToken} />
+ * ```
+ *
+ * **Full control:**
+ * ```tsx
+ * <SquadExperience config={{ apiKey: '...', environment: 'production', community: { ... } }} />
+ * ```
+ */
+export function SquadExperience({
+  partnerId,
+  apiKey,
+  ssoToken,
+  ssoProvider,
+  userData,
+  config: configProp,
+  onReady,
+  onError,
+}: SquadExperienceProps) {
+  const [resolvedConfig, setResolvedConfig] = useState<SquadSDKConfig | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const [retryCount, setRetryCount] = useState(0);
+
+  useEffect(() => {
+    const init = async () => {
+      setError(null);
+
+      try {
+        let sdkConfig: SquadConfig;
+
+        if (configProp) {
+          // Full config provided
+          sdkConfig = configProp;
+        } else if (partnerId) {
+          if (!apiKey) {
+            throw new Error(
+              '[SquadExperience] apiKey is required when using partnerId. Get your key at partners.squadforsports.com',
+            );
+          }
+          // Simple partner path
+          sdkConfig = {
+            partnerId,
+            apiKey,
+            ssoToken,
+            ssoProvider: ssoProvider ?? (ssoToken ? 'ticketmaster' : undefined),
+            userData,
+          };
+        } else {
+          throw new Error(
+            '[SquadExperience] Either partnerId or config is required.',
+          );
+        }
+
+        const sdk = await SquadSportsSDK.setup(sdkConfig);
+        setResolvedConfig(sdk.config);
+        onReady?.();
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        setError(error);
+        onError?.(error);
+      }
+    };
+
+    init();
+  }, [partnerId, ssoToken, ssoProvider, userData, retryCount]);
+
+  if (error) {
+    return (
+      <View style={{ flex: 1, backgroundColor: '#111111', justifyContent: 'center', alignItems: 'center', padding: 24 }}>
+        <View style={{ backgroundColor: '#1D1D1D', borderRadius: 12, padding: 24, maxWidth: 320 }}>
+          <View style={{ width: 48, height: 48, borderRadius: 24, backgroundColor: '#FF4478', justifyContent: 'center', alignItems: 'center', alignSelf: 'center', marginBottom: 16 }}>
+            <Text style={{ color: '#fff', fontSize: 24, fontWeight: '700' }}>!</Text>
+          </View>
+          <Text style={{ color: '#FFFFFF', fontSize: 16, fontWeight: '600', textAlign: 'center', marginBottom: 8 }}>
+            Unable to load Squad
+          </Text>
+          <Text style={{ color: '#8A8A8A', fontSize: 13, textAlign: 'center', marginBottom: 20 }}>
+            {error.message}
+          </Text>
+          <Pressable
+            onPress={() => setRetryCount(c => c + 1)}
+            style={{ backgroundColor: '#6E82E7', borderRadius: 8, paddingVertical: 12, paddingHorizontal: 24, alignSelf: 'center' }}
+          >
+            <Text style={{ color: '#FFFFFF', fontSize: 14, fontWeight: '600' }}>Try Again</Text>
+          </Pressable>
+        </View>
+      </View>
+    );
+  }
+
+  if (!resolvedConfig) {
+    return (
+      <View style={{ flex: 1, backgroundColor: '#111111', justifyContent: 'center', alignItems: 'center' }}>
+        <ActivityIndicator size="large" color="#6E82E7" />
+      </View>
+    );
+  }
+
+  return (
+    <ScreenErrorBoundary screenName="SquadExperience">
+      <SquadProvider config={resolvedConfig}>
+        <SquadNavigationContainer />
+      </SquadProvider>
+    </ScreenErrorBoundary>
+  );
+}

package/src/SquadProvider.tsx

@@ -0,0 +1,232 @@
+import React, { createContext, useContext, useEffect, useMemo, useState, useCallback } from 'react';
+import { ActivityIndicator, AppState, View } from 'react-native';
+import type { AppStateStatus } from 'react-native';
+import { RecoilRoot } from 'recoil';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+
+import { AnalyticsTracker } from '@squad-sports/core';
+import type { SquadApiClient } from '@squad-sports/core';
+import type { SquadSDKConfig, SquadConfig } from '@squad-sports/core';
+
+import { SquadSportsSDK } from './SquadSportsSDK';
+import { ThemeProvider } from './theme/ThemeContext';
+import { EventProcessor, type ConnectionQuality } from './realtime/EventProcessor';
+import { NetworkMonitor } from './realtime/NetworkMonitor';
+import { OfflineQueue } from './realtime/OfflineQueue';
+import { NetworkBanner } from './components/ux/layout/NetworkBanner';
+
+// --- Contexts ---
+
+const SDKContext = createContext<SquadSportsSDK | null>(null);
+const ApiClientContext = createContext<SquadApiClient | null>(null);
+
+export function useSquadSDK(): SquadSportsSDK {
+  const sdk = useContext(SDKContext);
+  if (!sdk) {
+    throw new Error('useSquadSDK must be used within <SquadProvider>');
+  }
+  return sdk;
+}
+
+export function useApiClient(): SquadApiClient {
+  const client = useContext(ApiClientContext);
+  if (!client) {
+    throw new Error('useApiClient must be used within <SquadProvider>');
+  }
+  return client;
+}
+
+// --- Internal: auto-connects real-time sync when authenticated ---
+
+function RealtimeSyncSentinel({ apiClient }: { apiClient: SquadApiClient }) {
+  const [isOnline, setIsOnline] = useState(true);
+  const [sseQuality, setSSEQuality] = useState<ConnectionQuality>('disconnected');
+
+  useEffect(() => {
+    // Wire up EventProcessor
+    const processor = EventProcessor.shared;
+    processor.setApiClient(apiClient);
+
+    // Only connect SSE if we have a token
+    if (apiClient.currentToken) {
+      processor.setShouldAllowEvents(true);
+      processor.connect();
+    }
+
+    const onQuality = (q: ConnectionQuality) => setSSEQuality(q);
+    processor.emitter.on('connection:quality', onQuality);
+
+    // Wire up network monitoring
+    const monitor = NetworkMonitor.shared;
+    monitor.startMonitoring();
+
+    const onNetworkChange = (online: boolean) => {
+      setIsOnline(online);
+
+      if (online) {
+        // Reconnect SSE when back online
+        if (apiClient.currentToken) {
+          processor.setShouldAllowEvents(true);
+          processor.connect();
+        }
+
+        // Flush offline queue
+        const offlineQueue = new OfflineQueue();
+        offlineQueue.processQueue(async (action) => {
+          // Route actions to appropriate API calls
+          try {
+            switch (action.type) {
+              case 'message:create': {
+                const { Message } = await import('@squad-sports/core');
+                const msg = new Message(action.payload as any);
+                await apiClient.createMessage(msg);
+                return true;
+              }
+              case 'freestyle:reaction': {
+                const { FreestyleReaction } = await import('@squad-sports/core');
+                const payload = action.payload as any;
+                const reaction = new FreestyleReaction(payload.reaction);
+                await apiClient.createFreestyleReaction(reaction, payload.freestyleId);
+                return true;
+              }
+              case 'message:reaction': {
+                const { MessageReaction } = await import('@squad-sports/core');
+                const payload = action.payload as any;
+                const reaction = new MessageReaction(payload.reaction);
+                await apiClient.createMessageReaction(reaction, payload.messageId);
+                return true;
+              }
+              default:
+                return false;
+            }
+          } catch {
+            return false;
+          }
+        });
+      } else {
+        processor.setShouldAllowEvents(false);
+      }
+    };
+
+    monitor.addListener(onNetworkChange);
+
+    // Listen for auth invalidation — disconnect SSE
+    const onAuthInvalid = () => {
+      processor.setShouldAllowEvents(false);
+      processor.disconnect();
+    };
+    apiClient.emitter.on('auth:invalid', onAuthInvalid);
+
+    return () => {
+      processor.emitter.off('connection:quality', onQuality);
+      monitor.removeListener(onNetworkChange);
+      apiClient.emitter.off('auth:invalid', onAuthInvalid);
+    };
+  }, [apiClient]);
+
+  // Return banner visibility — only show when offline
+  return <NetworkBanner isOnline={isOnline} />;
+}
+
+// --- Provider ---
+
+interface SquadProviderProps {
+  children: React.ReactNode;
+  /** Full or partner config. If omitted, uses SquadSportsSDK.shared. */
+  config?: SquadConfig;
+}
+
+/**
+ * Top-level provider that wraps the SDK experience.
+ * Automatically sets up:
+ * - RecoilRoot (state management)
+ * - SafeAreaProvider
+ * - GestureHandler
+ * - Theme (from community config)
+ * - API client context
+ * - Real-time SSE sync (auto-connects when authenticated)
+ * - Network monitoring + offline queue
+ * - Offline banner
+ */
+export function SquadProvider({ children, config }: SquadProviderProps) {
+  const [sdk, setSDK] = useState<SquadSportsSDK | null>(null);
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    const init = async () => {
+      try {
+        let instance: SquadSportsSDK;
+
+        if (config) {
+          instance = await SquadSportsSDK.setup(config);
+        } else {
+          instance = SquadSportsSDK.shared;
+        }
+
+        setSDK(instance);
+      } catch (error) {
+        console.error('[SquadProvider] Initialization error:', error);
+      } finally {
+        setReady(true);
+      }
+    };
+
+    init();
+  }, []);
+
+  // App lifecycle — flush analytics on background, reconnect on foreground
+  useEffect(() => {
+    if (!sdk) return;
+
+    const handleAppStateChange = (nextState: AppStateStatus) => {
+      if (nextState === 'background' || nextState === 'inactive') {
+        AnalyticsTracker.shared.flush();
+        EventProcessor.shared.setShouldAllowEvents(false);
+      } else if (nextState === 'active') {
+        if (sdk.apiClient.currentToken) {
+          EventProcessor.shared.setShouldAllowEvents(true);
+          EventProcessor.shared.connect();
+          sdk.apiClient.validateToken().then((valid: boolean) => {
+            if (!valid) {
+              sdk.apiClient.emitter.emit('auth:invalid', { status: 401, url: '' });
+            }
+          });
+        }
+      }
+    };
+
+    const subscription = AppState.addEventListener('change', handleAppStateChange);
+    return () => subscription.remove();
+  }, [sdk]);
+
+  if (!ready || !sdk) {
+    return (
+      <View style={{ flex: 1, backgroundColor: '#111111', justifyContent: 'center', alignItems: 'center' }}>
+        <ActivityIndicator size="large" color="#ffffff" />
+      </View>
+    );
+  }
+
+  const communityConfig = sdk.config.community;
+
+  return (
+    <SDKContext.Provider value={sdk}>
+      <ApiClientContext.Provider value={sdk.apiClient}>
+        <RecoilRoot>
+          <SafeAreaProvider>
+            <GestureHandlerRootView style={{ flex: 1 }}>
+              <ThemeProvider
+                communityColor={communityConfig.primaryColor}
+                communitySecondaryColor={communityConfig.secondaryColor}
+              >
+                <RealtimeSyncSentinel apiClient={sdk.apiClient} />
+                {children}
+              </ThemeProvider>
+            </GestureHandlerRootView>
+          </SafeAreaProvider>
+        </RecoilRoot>
+      </ApiClientContext.Provider>
+    </SDKContext.Provider>
+  );
+}