noboarding 0.1.0-alpha

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "noboarding",
+  "version": "0.1.0-alpha",
+  "description": "React Native SDK for remote onboarding flow management",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "react-native",
+    "onboarding",
+    "sdk",
+    "analytics",
+    "a/b-testing"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0",
+    "expo-linear-gradient": ">=12.0.0",
+    "@expo/vector-icons": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "expo-linear-gradient": {
+      "optional": true
+    },
+    "@expo/vector-icons": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@react-native-async-storage/async-storage": "^1.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.72.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/OnboardingFlow.tsx

@@ -0,0 +1,276 @@
+import React, { useState, useEffect, useRef, useCallback } from 'react';
+import { View, ActivityIndicator, StyleSheet, Text, TouchableOpacity } from 'react-native';
+import { API } from './api';
+import { AnalyticsManager } from './analytics';
+import { OnboardingFlowProps, ScreenConfig, ConditionalDestination, ConditionalRoutes } from './types';
+import { resolveDestination } from './variableUtils';
+import { ElementRenderer } from './components/ElementRenderer';
+
+// Generate unique IDs
+const generateUserId = (): string => {
+  return `user_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+};
+
+const generateSessionId = (): string => {
+  return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+};
+
+export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
+  apiKey,
+  onComplete,
+  onSkip,
+  baseUrl,
+  initialVariables,
+  customComponents,
+  onUserIdGenerated,
+}) => {
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [screens, setScreens] = useState<ScreenConfig[]>([]);
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [collectedData, setCollectedData] = useState<Record<string, any>>({});
+  const [variables, setVariables] = useState<Record<string, any>>(initialVariables || {});
+
+  const apiRef = useRef<API | null>(null);
+  const analyticsRef = useRef<AnalyticsManager | null>(null);
+  const userIdRef = useRef<string>(generateUserId());
+  const sessionIdRef = useRef<string>(generateSessionId());
+
+  useEffect(() => {
+    // Notify parent of the generated user ID
+    if (onUserIdGenerated) {
+      onUserIdGenerated(userIdRef.current);
+    }
+
+    initializeFlow();
+
+    return () => {
+      // Cleanup: flush remaining analytics
+      if (analyticsRef.current) {
+        analyticsRef.current.destroy();
+      }
+    };
+  }, []);
+
+  const initializeFlow = async () => {
+    try {
+      setLoading(true);
+      setError(null);
+
+      // Initialize API client
+      const api = new API(apiKey, baseUrl);
+      apiRef.current = api;
+
+      // Initialize analytics
+      const analytics = new AnalyticsManager(
+        api,
+        userIdRef.current,
+        sessionIdRef.current
+      );
+      analyticsRef.current = analytics;
+
+      // Track onboarding start
+      analytics.track('onboarding_started');
+
+      // Fetch configuration
+      const configResponse = await api.getConfig();
+      // Backward compatibility: normalize legacy 'custom_screen' (with elements) to 'noboard_screen'
+      const normalizedScreens = configResponse.config.screens.map(s => ({
+        ...s,
+        type: (s.type === ('custom_screen' as any) && s.elements) ? 'noboard_screen' as ScreenConfig['type'] : s.type,
+      }));
+      setScreens(normalizedScreens);
+
+      setLoading(false);
+    } catch (err) {
+      console.error('Failed to initialize onboarding flow:', err);
+      setError('Failed to load onboarding. Please try again.');
+      setLoading(false);
+    }
+  };
+
+  const handleNext = (data?: Record<string, any>) => {
+    // Collect data from this screen
+    if (data) {
+      setCollectedData((prev) => ({ ...prev, ...data }));
+    }
+
+    // Check if this is the last screen
+    if (currentIndex >= screens.length - 1) {
+      handleComplete(data);
+    } else {
+      setCurrentIndex((prev) => prev + 1);
+    }
+  };
+
+  const handleSkipScreen = () => {
+    // Move to next screen or complete
+    if (currentIndex >= screens.length - 1) {
+      handleComplete();
+    } else {
+      setCurrentIndex((prev) => prev + 1);
+    }
+  };
+
+  const handleSetVariable = useCallback((name: string, value: any) => {
+    setVariables(prev => ({ ...prev, [name]: value }));
+  }, []);
+
+  const handleComplete = async (lastScreenData?: Record<string, any>) => {
+    const finalData = {
+      ...collectedData,
+      ...(lastScreenData || {}),
+      _variables: variables,
+    };
+
+    // Track completion
+    if (analyticsRef.current) {
+      analyticsRef.current.track('onboarding_completed');
+      await analyticsRef.current.flush();
+    }
+
+    // Call developer's completion callback with collected data
+    onComplete(finalData);
+  };
+
+  const handleSkipAll = async () => {
+    if (analyticsRef.current) {
+      analyticsRef.current.track('onboarding_abandoned', {
+        current_screen_index: currentIndex,
+      });
+      await analyticsRef.current.flush();
+    }
+
+    if (onSkip) {
+      onSkip();
+    }
+  };
+
+  if (loading) {
+    return (
+      <View style={styles.centerContainer}>
+        <ActivityIndicator size="large" color="#007AFF" />
+        <Text style={styles.loadingText}>Loading...</Text>
+      </View>
+    );
+  }
+
+  if (error) {
+    return (
+      <View style={styles.centerContainer}>
+        <Text style={styles.errorText}>{error}</Text>
+      </View>
+    );
+  }
+
+  if (screens.length === 0) {
+    return (
+      <View style={styles.centerContainer}>
+        <Text style={styles.errorText}>No onboarding screens configured</Text>
+      </View>
+    );
+  }
+
+  const currentScreen = screens[currentIndex];
+
+  // Handle noboard_screen type — render with ElementRenderer
+  if (currentScreen.type === 'noboard_screen' && currentScreen.elements) {
+    const handleElementNavigate = (destination: string | ConditionalDestination | ConditionalRoutes) => {
+      const resolved = resolveDestination(destination, variables);
+      if (!resolved) return;
+
+      if (resolved === 'next') {
+        handleNext();
+      } else if (resolved === 'previous') {
+        setCurrentIndex((prev) => Math.max(0, prev - 1));
+      } else {
+        // Navigate to specific screen by ID
+        const targetIndex = screens.findIndex((s) => s.id === resolved);
+        if (targetIndex >= 0) {
+          setCurrentIndex(targetIndex);
+        } else {
+          handleNext();
+        }
+      }
+    };
+
+    return (
+      <View style={styles.container}>
+        <ElementRenderer
+          elements={currentScreen.elements}
+          analytics={analyticsRef.current!}
+          screenId={currentScreen.id}
+          onNavigate={handleElementNavigate}
+          onDismiss={onSkip ? handleSkipAll : handleNext}
+          variables={variables}
+          onSetVariable={handleSetVariable}
+        />
+      </View>
+    );
+  }
+
+  // Handle custom_screen type — developer-registered React Native components
+  if (currentScreen.type === 'custom_screen') {
+    const componentName = currentScreen.custom_component_name;
+    const CustomComponent = customComponents?.[componentName || ''];
+
+    if (!CustomComponent) {
+      return (
+        <View style={styles.centerContainer}>
+          <Text style={styles.errorText}>
+            Component "{componentName}" not found.
+          </Text>
+          <TouchableOpacity
+            style={{ marginTop: 16, padding: 12 }}
+            onPress={() => handleNext()}
+          >
+            <Text style={{ color: '#007AFF', fontSize: 16 }}>Skip</Text>
+          </TouchableOpacity>
+        </View>
+      );
+    }
+
+    return (
+      <View style={styles.container}>
+        <CustomComponent
+          analytics={analyticsRef.current!}
+          onNext={() => handleNext()}
+          onSkip={onSkip ? handleSkipAll : undefined}
+          data={collectedData}
+          onDataUpdate={(newData) => setCollectedData(prev => ({ ...prev, ...newData }))}
+        />
+      </View>
+    );
+  }
+
+  // Unknown screen type fallback
+  return (
+    <View style={styles.centerContainer}>
+      <Text style={styles.errorText}>
+        Unknown screen type: "{currentScreen.type}"
+      </Text>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  centerContainer: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+    padding: 24,
+  },
+  loadingText: {
+    marginTop: 16,
+    fontSize: 16,
+    color: '#000000',
+  },
+  errorText: {
+    fontSize: 16,
+    color: '#FF3B30',
+    textAlign: 'center',
+  },
+});

package/src/analytics.ts

@@ -0,0 +1,84 @@
+import { API } from './api';
+import { AnalyticsEvent } from './types';
+
+const BATCH_SIZE = 10;
+const FLUSH_INTERVAL_MS = 10000; // 10 seconds
+
+export class AnalyticsManager {
+  private api: API;
+  private events: AnalyticsEvent[] = [];
+  private userId: string;
+  private sessionId: string;
+  private flushTimer: NodeJS.Timeout | null = null;
+
+  constructor(api: API, userId: string, sessionId: string) {
+    this.api = api;
+    this.userId = userId;
+    this.sessionId = sessionId;
+
+    // Start auto-flush timer
+    this.startFlushTimer();
+  }
+
+  /**
+   * Track an analytics event
+   */
+  track(eventName: string, properties?: Record<string, any>): void {
+    const event: AnalyticsEvent = {
+      event: eventName,
+      user_id: this.userId,
+      session_id: this.sessionId,
+      timestamp: Date.now(),
+      properties: properties || {},
+    };
+
+    this.events.push(event);
+
+    // Auto-flush if batch size reached
+    if (this.events.length >= BATCH_SIZE) {
+      this.flush();
+    }
+  }
+
+  /**
+   * Manually flush events to backend
+   */
+  async flush(): Promise<void> {
+    if (this.events.length === 0) {
+      return;
+    }
+
+    // Take current events and clear queue
+    const eventsToSend = [...this.events];
+    this.events = [];
+
+    try {
+      await this.api.trackEvents(eventsToSend);
+      console.log(`Flushed ${eventsToSend.length} events`);
+    } catch (error) {
+      console.error('Failed to flush events:', error);
+      // Put events back in queue to retry later
+      this.events.unshift(...eventsToSend);
+    }
+  }
+
+  /**
+   * Start auto-flush timer
+   */
+  private startFlushTimer(): void {
+    this.flushTimer = setInterval(() => {
+      this.flush();
+    }, FLUSH_INTERVAL_MS);
+  }
+
+  /**
+   * Stop auto-flush timer and flush remaining events
+   */
+  async destroy(): Promise<void> {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+  }
+}

package/src/api.ts

@@ -0,0 +1,173 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import {
+  OnboardingConfig,
+  GetConfigResponse,
+  AnalyticsEvent,
+  TrackEventsResponse,
+  AssignVariantResponse,
+} from './types';
+
+const CACHE_KEY = '@noboarding:config';
+const CACHE_EXPIRY_MS = 60 * 60 * 1000; // 1 hour
+
+interface CachedConfig {
+  config: GetConfigResponse;
+  timestamp: number;
+}
+
+export class API {
+  private apiKey: string;
+  private baseUrl: string;
+  private supabaseAnonKey = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImhobW16bXJzcHRlZ3ByZnp0cXRxIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzA3ODM1MDUsImV4cCI6MjA4NjM1OTUwNX0.otIIs3ZyWTHTnDZ1NbZolzeHjWv__wmHekxZevhKryI';
+
+  constructor(apiKey: string, baseUrl?: string) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl || 'https://hhmmzmrsptegprfztqtq.supabase.co/functions/v1';
+  }
+
+  /**
+   * Fetch onboarding configuration from API
+   */
+  async getConfig(): Promise<GetConfigResponse> {
+    try {
+      const response = await fetch(`${this.baseUrl}/get-config`, {
+        method: 'GET',
+        headers: {
+          'Authorization': `Bearer ${this.supabaseAnonKey}`,
+          'x-api-key': this.apiKey,
+          'Content-Type': 'application/json',
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to fetch config: ${response.status}`);
+      }
+
+      const data: GetConfigResponse = await response.json();
+
+      // Cache the config
+      await this.cacheConfig(data);
+
+      return data;
+    } catch (error) {
+      console.error('Error fetching config:', error);
+      // Try to return cached config as fallback
+      const cached = await this.getCachedConfig();
+      if (cached) {
+        console.log('Using cached config as fallback');
+        return cached;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get cached configuration
+   */
+  async getCachedConfig(): Promise<GetConfigResponse | null> {
+    try {
+      const cached = await AsyncStorage.getItem(CACHE_KEY);
+      if (!cached) {
+        return null;
+      }
+
+      const parsedCache: CachedConfig = JSON.parse(cached);
+      const now = Date.now();
+
+      // Check if cache is expired
+      if (now - parsedCache.timestamp > CACHE_EXPIRY_MS) {
+        await AsyncStorage.removeItem(CACHE_KEY);
+        return null;
+      }
+
+      return parsedCache.config;
+    } catch (error) {
+      console.error('Error reading cached config:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Cache configuration locally
+   */
+  private async cacheConfig(config: GetConfigResponse): Promise<void> {
+    try {
+      const cacheData: CachedConfig = {
+        config,
+        timestamp: Date.now(),
+      };
+      await AsyncStorage.setItem(CACHE_KEY, JSON.stringify(cacheData));
+    } catch (error) {
+      console.error('Error caching config:', error);
+    }
+  }
+
+  /**
+   * Send analytics events to backend
+   */
+  async trackEvents(events: AnalyticsEvent[]): Promise<TrackEventsResponse> {
+    try {
+      const response = await fetch(`${this.baseUrl}/track-events`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.supabaseAnonKey}`,
+          'x-api-key': this.apiKey,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ events }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to track events: ${response.status}`);
+      }
+
+      return await response.json();
+    } catch (error) {
+      console.error('Error tracking events:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Get A/B test variant assignment
+   */
+  async assignVariant(
+    experimentId: string,
+    userId: string
+  ): Promise<AssignVariantResponse> {
+    try {
+      const response = await fetch(`${this.baseUrl}/assign-variant`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.supabaseAnonKey}`,
+          'x-api-key': this.apiKey,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          experiment_id: experimentId,
+          user_id: userId,
+        }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Failed to assign variant: ${response.status}`);
+      }
+
+      return await response.json();
+    } catch (error) {
+      console.error('Error assigning variant:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Clear cached config
+   */
+  async clearCache(): Promise<void> {
+    try {
+      await AsyncStorage.removeItem(CACHE_KEY);
+    } catch (error) {
+      console.error('Error clearing cache:', error);
+    }
+  }
+}