@onairos/react-native 3.1.16 → 3.1.18

package/src/services/storageService.ts

@@ -1,452 +1,452 @@
-import AsyncStorage from '@react-native-async-storage/async-storage';
-import { clearStoredPin } from './pinStorageUtils';
-
-// Storage keys
-export const STORAGE_KEYS = {
-  // Authentication
-  AUTH_TOKEN: 'auth_token',
-  ONAIROS_JWT_TOKEN: 'onairos_jwt_token',
-  ENOCH_TOKEN: 'enoch_token',
-  
-  // User data
-  USER: 'user',
-  USER_PROFILE: 'userProfile',
-  USER_PROFILE_FALLBACK: 'userProfileFallback',
-  
-  // App state
-  USER_PROGRESS: 'user_progress',
-  ONBOARDING_COMPLETED: 'onboardingCompleted',
-  IS_FIRST_TIME_USER: 'isFirstTimeUser',
-  USER_ATTENDANCE_CONFIRMED: 'userAttendanceConfirmed',
-  
-  // New: Token for completed onboarding with Results access
-  ONBOARDING_COMPLETE_TOKEN: 'onboarding_complete_token',
-  EVENT_ACCESS_TOKEN: 'event_access_token',
-  
-  // Authentication method tracking
-  ONAIROS_USER: 'onairos_user',
-  APPLE_USER: 'apple_user',
-  AUTH_METHOD: 'auth_method',
-  
-  // Session data
-  CURRENT_EVENT_DATA: 'currentEventData',
-  CONNECTED_PLATFORMS: 'connectedPlatforms',
-  PROFILE_IMAGE: 'profileImage',
-  
-  // Admin status
-  USER_ADMIN_STATUS: 'user_admin_status',
-} as const;
-
-// User progress tracking
-export interface UserProgress {
-  lastScreen: string;
-  completedSteps: string[];
-  authMethod: 'apple' | 'onairos' | null;
-  hasProfilePhoto: boolean;
-  hasCompletedProfile: boolean;
-  hasSelectedIntentions: boolean;
-  hasViewedResults: boolean;
-  eventCode?: string;
-  hasEnteredEventCode: boolean;
-  hasRegisteredForEvent?: boolean;
-  // New: Flag to indicate user has completed entire onboarding flow
-  hasReachedEventPage: boolean;
-  // Store event data for returning users
-  eventData?: {
-    eventType?: string;
-    eventCode?: string;
-    photo?: string;
-    userProfile?: any;
-    inferenceData?: any;
-  };
-  timestamp: number;
-}
-
-// Authentication state
-export interface AuthState {
-  isAuthenticated: boolean;
-  authMethod: 'apple' | 'onairos' | null;
-  hasValidToken: boolean;
-  userEmail?: string;
-  userName?: string;
-}
-
-/**
- * Save user progress to track where they left off
- */
-export const saveUserProgress = async (progress: Partial<UserProgress>): Promise<void> => {
-  try {
-    const existingProgress = await getUserProgress();
-    const updatedProgress: UserProgress = {
-      ...existingProgress,
-      ...progress,
-      timestamp: Date.now(),
-    };
-    
-    await AsyncStorage.setItem(STORAGE_KEYS.USER_PROGRESS, JSON.stringify(updatedProgress));
-    console.log('✅ User progress saved:', updatedProgress);
-  } catch (error) {
-    console.error('❌ Error saving user progress:', error);
-  }
-};
-
-/**
- * Get user progress to determine where to resume
- */
-export const getUserProgress = async (): Promise<UserProgress> => {
-  try {
-    const progressData = await AsyncStorage.getItem(STORAGE_KEYS.USER_PROGRESS);
-    if (progressData) {
-      return JSON.parse(progressData);
-    }
-  } catch (error) {
-    console.error('❌ Error getting user progress:', error);
-  }
-  
-  // Return default progress
-  return {
-    lastScreen: 'Welcome',
-    completedSteps: [],
-    authMethod: null,
-    hasProfilePhoto: false,
-    hasCompletedProfile: false,
-    hasSelectedIntentions: false,
-    hasViewedResults: false,
-    hasEnteredEventCode: false,
-    hasRegisteredForEvent: false,
-    hasReachedEventPage: false,
-    timestamp: Date.now(),
-  };
-};
-
-/**
- * Save authentication state
- */
-export const saveAuthState = async (authState: Partial<AuthState>): Promise<void> => {
-  try {
-    const existingState = await getAuthState();
-    const updatedState: AuthState = {
-      ...existingState,
-      ...authState,
-    };
-    
-    // Also save the auth method separately for quick access
-    if (authState.authMethod) {
-      await AsyncStorage.setItem(STORAGE_KEYS.AUTH_METHOD, authState.authMethod);
-    }
-    
-    console.log('✅ Auth state saved:', updatedState);
-  } catch (error) {
-    console.error('❌ Error saving auth state:', error);
-  }
-};
-
-/**
- * Get authentication state
- */
-export const getAuthState = async (): Promise<AuthState> => {
-  try {
-    const authMethod = await AsyncStorage.getItem(STORAGE_KEYS.AUTH_METHOD) as 'apple' | 'onairos' | null;
-    const hasToken = !!(await AsyncStorage.getItem(STORAGE_KEYS.AUTH_TOKEN));
-    
-    return {
-      isAuthenticated: hasToken,
-      authMethod,
-      hasValidToken: hasToken,
-    };
-  } catch (error) {
-    console.error('❌ Error getting auth state:', error);
-    return {
-      isAuthenticated: false,
-      authMethod: null,
-      hasValidToken: false,
-    };
-  }
-};
-
-/**
- * Clear all user data (for logout)
- */
-export const clearUserData = async (): Promise<void> => {
-  try {
-    const keysToRemove = [
-      STORAGE_KEYS.USER,
-      STORAGE_KEYS.USER_PROFILE,
-      STORAGE_KEYS.USER_PROFILE_FALLBACK,
-      STORAGE_KEYS.USER_PROGRESS,
-      STORAGE_KEYS.AUTH_TOKEN,
-      STORAGE_KEYS.ONAIROS_JWT_TOKEN,
-      STORAGE_KEYS.ENOCH_TOKEN,
-      STORAGE_KEYS.ONAIROS_USER,
-      STORAGE_KEYS.APPLE_USER,
-      STORAGE_KEYS.AUTH_METHOD,
-      STORAGE_KEYS.IS_FIRST_TIME_USER,
-      STORAGE_KEYS.USER_ATTENDANCE_CONFIRMED,
-      STORAGE_KEYS.PROFILE_IMAGE,
-      STORAGE_KEYS.ONBOARDING_COMPLETED,
-      // Clear the new onboarding completion tokens
-      STORAGE_KEYS.ONBOARDING_COMPLETE_TOKEN,
-      STORAGE_KEYS.EVENT_ACCESS_TOKEN,
-    ];
-    
-    await AsyncStorage.multiRemove(keysToRemove);
-    
-    // Also clear biometrically stored PIN
-    try {
-      await clearStoredPin();
-      console.log('✅ Biometrically stored PIN cleared');
-    } catch (error) {
-      console.warn('⚠️ Error clearing stored PIN (continuing):', error);
-    }
-    
-    console.log('✅ User data cleared including onboarding completion tokens');
-  } catch (error) {
-    console.error('❌ Error clearing user data:', error);
-  }
-};
-
-/**
- * Get resume navigation target based on user progress
- */
-export const getResumeTarget = async (): Promise<{ screen: string; params?: any }> => {
-  try {
-    const progress = await getUserProgress();
-    const authState = await getAuthState();
-    
-    // HIGHEST PRIORITY: Check event access token first (regardless of auth state)
-    // This ensures release mode reliability when network auth fails
-    const hasEventToken = await hasEventAccessToken();
-    if (hasEventToken || (progress.hasReachedEventPage && progress.hasViewedResults)) {
-      console.log('🎯 User has completed onboarding (verified by token) - returning to Home screen');
-      
-      // After completing first event, users go to Home screen instead of Results
-      // This provides a better post-event experience and central hub
-      return { 
-        screen: 'Home'
-      };
-    }
-    
-    // If not authenticated, start from Welcome
-    if (!authState.isAuthenticated) {
-      return { screen: 'Welcome' };
-    }
-    
-    // If authenticated but no progress, start camera flow
-    if (progress.completedSteps.length === 0) {
-      return { 
-        screen: 'Welcome', 
-        params: { 
-          isNewUser: true,
-          activateCamera: true 
-        }
-      };
-    }
-    
-    // Resume based on last completed step for users still in onboarding
-    if (!progress.hasProfilePhoto) {
-      return { 
-        screen: 'Welcome', 
-        params: { 
-          isNewUser: true,
-          activateCamera: true 
-        }
-      };
-    }
-    
-    if (!progress.hasCompletedProfile) {
-      const profileImage = await AsyncStorage.getItem(STORAGE_KEYS.PROFILE_IMAGE);
-      return { 
-        screen: 'CreateFreshProfile', 
-        params: { 
-          photo: profileImage,
-          isReviewerBypass: authState.authMethod === 'onairos'
-        }
-      };
-    }
-    
-    if (!progress.hasSelectedIntentions) {
-      const userProfile = await AsyncStorage.getItem(STORAGE_KEYS.USER_PROFILE);
-      return { 
-        screen: 'Intention', 
-        params: { 
-          userProfile: userProfile ? JSON.parse(userProfile) : null 
-        }
-      };
-    }
-    
-    // Default to Results if everything is complete
-    const userProfile = await AsyncStorage.getItem(STORAGE_KEYS.USER_PROFILE);
-    return { 
-      screen: 'Results', 
-      params: { 
-        userProfile: userProfile ? JSON.parse(userProfile) : null 
-      }
-    };
-    
-  } catch (error) {
-    console.error('❌ Error determining resume target:', error);
-    return { screen: 'Welcome' };
-  }
-};
-
-/**
- * Check if user has completed onboarding flow
- */
-export const hasCompletedOnboarding = async (): Promise<boolean> => {
-  try {
-    const progress = await getUserProgress();
-    return progress.hasCompletedProfile && progress.hasViewedResults;
-  } catch (error) {
-    console.error('❌ Error checking onboarding status:', error);
-    return false;
-  }
-};
-
-/**
- * Mark user as having reached the event page (completed full onboarding)
- * This creates the token that ensures they always return to Results
- */
-export const markEventPageReached = async (eventData?: {
-  eventType?: string;
-  eventCode?: string;
-  photo?: string;
-  userProfile?: any;
-  inferenceData?: any;
-}): Promise<void> => {
-  try {
-    const progress = await getUserProgress();
-    const updatedProgress: UserProgress = {
-      ...progress,
-      hasReachedEventPage: true,
-      hasViewedResults: true,
-      eventData: eventData || progress.eventData,
-      timestamp: Date.now(),
-    };
-    
-    // Save the updated progress
-    await saveUserProgress(updatedProgress);
-    
-    // Save the onboarding completion token for extra security
-    await AsyncStorage.setItem(STORAGE_KEYS.ONBOARDING_COMPLETE_TOKEN, 'true');
-    await AsyncStorage.setItem(STORAGE_KEYS.EVENT_ACCESS_TOKEN, JSON.stringify({
-      timestamp: Date.now(),
-      eventData: eventData,
-      hasAccess: true
-    }));
-    
-    console.log('✅ User marked as having reached event page - will always return to Results');
-  } catch (error) {
-    console.error('❌ Error marking event page reached:', error);
-  }
-};
-
-/**
- * Check if user has the event access token (completed onboarding)
- */
-export const hasEventAccessToken = async (): Promise<boolean> => {
-  try {
-    const token = await AsyncStorage.getItem(STORAGE_KEYS.ONBOARDING_COMPLETE_TOKEN);
-    const progress = await getUserProgress();
-    return token === 'true' && progress.hasReachedEventPage;
-  } catch (error) {
-    console.error('❌ Error checking event access token:', error);
-    return false;
-  }
-};
-
-/**
- * Mark a step as completed
- */
-export const markStepCompleted = async (step: string): Promise<void> => {
-  try {
-    const progress = await getUserProgress();
-    if (!progress.completedSteps.includes(step)) {
-      progress.completedSteps.push(step);
-      await saveUserProgress(progress);
-    }
-  } catch (error) {
-    console.error('❌ Error marking step completed:', error);
-  }
-};
-
-/**
- * Update user's last screen
- */
-export const updateLastScreen = async (screen: string, params?: any): Promise<void> => {
-  try {
-    await saveUserProgress({ 
-      lastScreen: screen,
-      timestamp: Date.now()
-    });
-  } catch (error) {
-    console.error('❌ Error updating last screen:', error);
-  }
-};
-
-/**
- * Check if this is a returning user with existing progress
- */
-export const isReturningUser = async (): Promise<boolean> => {
-  try {
-    const progress = await getUserProgress();
-    const authState = await getAuthState();
-    
-    return authState.isAuthenticated && progress.completedSteps.length > 0;
-  } catch (error) {
-    console.error('❌ Error checking returning user status:', error);
-    return false;
-  }
-};
-
-/**
- * Mark app as active (call this when app becomes active)
- */
-export const markAppActive = async (): Promise<void> => {
-  try {
-    await saveUserProgress({
-      timestamp: Date.now()
-    });
-    console.log('✅ App marked as active');
-  } catch (error) {
-    console.error('❌ Error marking app as active:', error);
-  }
-};
-
-/**
- * Development utility: Get all stored progress data for debugging
- */
-export const getDebugStorageInfo = async (): Promise<{
-  progress: UserProgress;
-  authState: AuthState;
-  isReturning: boolean;
-  resumeTarget: { screen: string; params?: any };
-}> => {
-  try {
-    const progress = await getUserProgress();
-    const authState = await getAuthState();
-    const isReturning = await isReturningUser();
-    const resumeTarget = await getResumeTarget();
-    
-    return {
-      progress,
-      authState,
-      isReturning,
-      resumeTarget
-    };
-  } catch (error) {
-    console.error('❌ Error getting debug storage info:', error);
-    throw error;
-  }
-};
-
-/**
- * Development utility: Clear all progress (for testing)
- */
-export const clearAllProgress = async (): Promise<void> => {
-  try {
-    await clearUserData();
-    console.log('✅ All progress data cleared');
-  } catch (error) {
-    console.error('❌ Error clearing progress data:', error);
-  }
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { clearStoredPin } from './pinStorageUtils';
+
+// Storage keys
+export const STORAGE_KEYS = {
+  // Authentication
+  AUTH_TOKEN: 'auth_token',
+  ONAIROS_JWT_TOKEN: 'onairos_jwt_token',
+  ENOCH_TOKEN: 'enoch_token',
+  
+  // User data
+  USER: 'user',
+  USER_PROFILE: 'userProfile',
+  USER_PROFILE_FALLBACK: 'userProfileFallback',
+  
+  // App state
+  USER_PROGRESS: 'user_progress',
+  ONBOARDING_COMPLETED: 'onboardingCompleted',
+  IS_FIRST_TIME_USER: 'isFirstTimeUser',
+  USER_ATTENDANCE_CONFIRMED: 'userAttendanceConfirmed',
+  
+  // New: Token for completed onboarding with Results access
+  ONBOARDING_COMPLETE_TOKEN: 'onboarding_complete_token',
+  EVENT_ACCESS_TOKEN: 'event_access_token',
+  
+  // Authentication method tracking
+  ONAIROS_USER: 'onairos_user',
+  APPLE_USER: 'apple_user',
+  AUTH_METHOD: 'auth_method',
+  
+  // Session data
+  CURRENT_EVENT_DATA: 'currentEventData',
+  CONNECTED_PLATFORMS: 'connectedPlatforms',
+  PROFILE_IMAGE: 'profileImage',
+  
+  // Admin status
+  USER_ADMIN_STATUS: 'user_admin_status',
+} as const;
+
+// User progress tracking
+export interface UserProgress {
+  lastScreen: string;
+  completedSteps: string[];
+  authMethod: 'apple' | 'onairos' | null;
+  hasProfilePhoto: boolean;
+  hasCompletedProfile: boolean;
+  hasSelectedIntentions: boolean;
+  hasViewedResults: boolean;
+  eventCode?: string;
+  hasEnteredEventCode: boolean;
+  hasRegisteredForEvent?: boolean;
+  // New: Flag to indicate user has completed entire onboarding flow
+  hasReachedEventPage: boolean;
+  // Store event data for returning users
+  eventData?: {
+    eventType?: string;
+    eventCode?: string;
+    photo?: string;
+    userProfile?: any;
+    inferenceData?: any;
+  };
+  timestamp: number;
+}
+
+// Authentication state
+export interface AuthState {
+  isAuthenticated: boolean;
+  authMethod: 'apple' | 'onairos' | null;
+  hasValidToken: boolean;
+  userEmail?: string;
+  userName?: string;
+}
+
+/**
+ * Save user progress to track where they left off
+ */
+export const saveUserProgress = async (progress: Partial<UserProgress>): Promise<void> => {
+  try {
+    const existingProgress = await getUserProgress();
+    const updatedProgress: UserProgress = {
+      ...existingProgress,
+      ...progress,
+      timestamp: Date.now(),
+    };
+    
+    await AsyncStorage.setItem(STORAGE_KEYS.USER_PROGRESS, JSON.stringify(updatedProgress));
+    console.log('✅ User progress saved:', updatedProgress);
+  } catch (error) {
+    console.error('❌ Error saving user progress:', error);
+  }
+};
+
+/**
+ * Get user progress to determine where to resume
+ */
+export const getUserProgress = async (): Promise<UserProgress> => {
+  try {
+    const progressData = await AsyncStorage.getItem(STORAGE_KEYS.USER_PROGRESS);
+    if (progressData) {
+      return JSON.parse(progressData);
+    }
+  } catch (error) {
+    console.error('❌ Error getting user progress:', error);
+  }
+  
+  // Return default progress
+  return {
+    lastScreen: 'Welcome',
+    completedSteps: [],
+    authMethod: null,
+    hasProfilePhoto: false,
+    hasCompletedProfile: false,
+    hasSelectedIntentions: false,
+    hasViewedResults: false,
+    hasEnteredEventCode: false,
+    hasRegisteredForEvent: false,
+    hasReachedEventPage: false,
+    timestamp: Date.now(),
+  };
+};
+
+/**
+ * Save authentication state
+ */
+export const saveAuthState = async (authState: Partial<AuthState>): Promise<void> => {
+  try {
+    const existingState = await getAuthState();
+    const updatedState: AuthState = {
+      ...existingState,
+      ...authState,
+    };
+    
+    // Also save the auth method separately for quick access
+    if (authState.authMethod) {
+      await AsyncStorage.setItem(STORAGE_KEYS.AUTH_METHOD, authState.authMethod);
+    }
+    
+    console.log('✅ Auth state saved:', updatedState);
+  } catch (error) {
+    console.error('❌ Error saving auth state:', error);
+  }
+};
+
+/**
+ * Get authentication state
+ */
+export const getAuthState = async (): Promise<AuthState> => {
+  try {
+    const authMethod = await AsyncStorage.getItem(STORAGE_KEYS.AUTH_METHOD) as 'apple' | 'onairos' | null;
+    const hasToken = !!(await AsyncStorage.getItem(STORAGE_KEYS.AUTH_TOKEN));
+    
+    return {
+      isAuthenticated: hasToken,
+      authMethod,
+      hasValidToken: hasToken,
+    };
+  } catch (error) {
+    console.error('❌ Error getting auth state:', error);
+    return {
+      isAuthenticated: false,
+      authMethod: null,
+      hasValidToken: false,
+    };
+  }
+};
+
+/**
+ * Clear all user data (for logout)
+ */
+export const clearUserData = async (): Promise<void> => {
+  try {
+    const keysToRemove = [
+      STORAGE_KEYS.USER,
+      STORAGE_KEYS.USER_PROFILE,
+      STORAGE_KEYS.USER_PROFILE_FALLBACK,
+      STORAGE_KEYS.USER_PROGRESS,
+      STORAGE_KEYS.AUTH_TOKEN,
+      STORAGE_KEYS.ONAIROS_JWT_TOKEN,
+      STORAGE_KEYS.ENOCH_TOKEN,
+      STORAGE_KEYS.ONAIROS_USER,
+      STORAGE_KEYS.APPLE_USER,
+      STORAGE_KEYS.AUTH_METHOD,
+      STORAGE_KEYS.IS_FIRST_TIME_USER,
+      STORAGE_KEYS.USER_ATTENDANCE_CONFIRMED,
+      STORAGE_KEYS.PROFILE_IMAGE,
+      STORAGE_KEYS.ONBOARDING_COMPLETED,
+      // Clear the new onboarding completion tokens
+      STORAGE_KEYS.ONBOARDING_COMPLETE_TOKEN,
+      STORAGE_KEYS.EVENT_ACCESS_TOKEN,
+    ];
+    
+    await AsyncStorage.multiRemove(keysToRemove);
+    
+    // Also clear biometrically stored PIN
+    try {
+      await clearStoredPin();
+      console.log('✅ Biometrically stored PIN cleared');
+    } catch (error) {
+      console.warn('⚠️ Error clearing stored PIN (continuing):', error);
+    }
+    
+    console.log('✅ User data cleared including onboarding completion tokens');
+  } catch (error) {
+    console.error('❌ Error clearing user data:', error);
+  }
+};
+
+/**
+ * Get resume navigation target based on user progress
+ */
+export const getResumeTarget = async (): Promise<{ screen: string; params?: any }> => {
+  try {
+    const progress = await getUserProgress();
+    const authState = await getAuthState();
+    
+    // HIGHEST PRIORITY: Check event access token first (regardless of auth state)
+    // This ensures release mode reliability when network auth fails
+    const hasEventToken = await hasEventAccessToken();
+    if (hasEventToken || (progress.hasReachedEventPage && progress.hasViewedResults)) {
+      console.log('🎯 User has completed onboarding (verified by token) - returning to Home screen');
+      
+      // After completing first event, users go to Home screen instead of Results
+      // This provides a better post-event experience and central hub
+      return { 
+        screen: 'Home'
+      };
+    }
+    
+    // If not authenticated, start from Welcome
+    if (!authState.isAuthenticated) {
+      return { screen: 'Welcome' };
+    }
+    
+    // If authenticated but no progress, start camera flow
+    if (progress.completedSteps.length === 0) {
+      return { 
+        screen: 'Welcome', 
+        params: { 
+          isNewUser: true,
+          activateCamera: true 
+        }
+      };
+    }
+    
+    // Resume based on last completed step for users still in onboarding
+    if (!progress.hasProfilePhoto) {
+      return { 
+        screen: 'Welcome', 
+        params: { 
+          isNewUser: true,
+          activateCamera: true 
+        }
+      };
+    }
+    
+    if (!progress.hasCompletedProfile) {
+      const profileImage = await AsyncStorage.getItem(STORAGE_KEYS.PROFILE_IMAGE);
+      return { 
+        screen: 'CreateFreshProfile', 
+        params: { 
+          photo: profileImage,
+          isReviewerBypass: authState.authMethod === 'onairos'
+        }
+      };
+    }
+    
+    if (!progress.hasSelectedIntentions) {
+      const userProfile = await AsyncStorage.getItem(STORAGE_KEYS.USER_PROFILE);
+      return { 
+        screen: 'Intention', 
+        params: { 
+          userProfile: userProfile ? JSON.parse(userProfile) : null 
+        }
+      };
+    }
+    
+    // Default to Results if everything is complete
+    const userProfile = await AsyncStorage.getItem(STORAGE_KEYS.USER_PROFILE);
+    return { 
+      screen: 'Results', 
+      params: { 
+        userProfile: userProfile ? JSON.parse(userProfile) : null 
+      }
+    };
+    
+  } catch (error) {
+    console.error('❌ Error determining resume target:', error);
+    return { screen: 'Welcome' };
+  }
+};
+
+/**
+ * Check if user has completed onboarding flow
+ */
+export const hasCompletedOnboarding = async (): Promise<boolean> => {
+  try {
+    const progress = await getUserProgress();
+    return progress.hasCompletedProfile && progress.hasViewedResults;
+  } catch (error) {
+    console.error('❌ Error checking onboarding status:', error);
+    return false;
+  }
+};
+
+/**
+ * Mark user as having reached the event page (completed full onboarding)
+ * This creates the token that ensures they always return to Results
+ */
+export const markEventPageReached = async (eventData?: {
+  eventType?: string;
+  eventCode?: string;
+  photo?: string;
+  userProfile?: any;
+  inferenceData?: any;
+}): Promise<void> => {
+  try {
+    const progress = await getUserProgress();
+    const updatedProgress: UserProgress = {
+      ...progress,
+      hasReachedEventPage: true,
+      hasViewedResults: true,
+      eventData: eventData || progress.eventData,
+      timestamp: Date.now(),
+    };
+    
+    // Save the updated progress
+    await saveUserProgress(updatedProgress);
+    
+    // Save the onboarding completion token for extra security
+    await AsyncStorage.setItem(STORAGE_KEYS.ONBOARDING_COMPLETE_TOKEN, 'true');
+    await AsyncStorage.setItem(STORAGE_KEYS.EVENT_ACCESS_TOKEN, JSON.stringify({
+      timestamp: Date.now(),
+      eventData: eventData,
+      hasAccess: true
+    }));
+    
+    console.log('✅ User marked as having reached event page - will always return to Results');
+  } catch (error) {
+    console.error('❌ Error marking event page reached:', error);
+  }
+};
+
+/**
+ * Check if user has the event access token (completed onboarding)
+ */
+export const hasEventAccessToken = async (): Promise<boolean> => {
+  try {
+    const token = await AsyncStorage.getItem(STORAGE_KEYS.ONBOARDING_COMPLETE_TOKEN);
+    const progress = await getUserProgress();
+    return token === 'true' && progress.hasReachedEventPage;
+  } catch (error) {
+    console.error('❌ Error checking event access token:', error);
+    return false;
+  }
+};
+
+/**
+ * Mark a step as completed
+ */
+export const markStepCompleted = async (step: string): Promise<void> => {
+  try {
+    const progress = await getUserProgress();
+    if (!progress.completedSteps.includes(step)) {
+      progress.completedSteps.push(step);
+      await saveUserProgress(progress);
+    }
+  } catch (error) {
+    console.error('❌ Error marking step completed:', error);
+  }
+};
+
+/**
+ * Update user's last screen
+ */
+export const updateLastScreen = async (screen: string, params?: any): Promise<void> => {
+  try {
+    await saveUserProgress({ 
+      lastScreen: screen,
+      timestamp: Date.now()
+    });
+  } catch (error) {
+    console.error('❌ Error updating last screen:', error);
+  }
+};
+
+/**
+ * Check if this is a returning user with existing progress
+ */
+export const isReturningUser = async (): Promise<boolean> => {
+  try {
+    const progress = await getUserProgress();
+    const authState = await getAuthState();
+    
+    return authState.isAuthenticated && progress.completedSteps.length > 0;
+  } catch (error) {
+    console.error('❌ Error checking returning user status:', error);
+    return false;
+  }
+};
+
+/**
+ * Mark app as active (call this when app becomes active)
+ */
+export const markAppActive = async (): Promise<void> => {
+  try {
+    await saveUserProgress({
+      timestamp: Date.now()
+    });
+    console.log('✅ App marked as active');
+  } catch (error) {
+    console.error('❌ Error marking app as active:', error);
+  }
+};
+
+/**
+ * Development utility: Get all stored progress data for debugging
+ */
+export const getDebugStorageInfo = async (): Promise<{
+  progress: UserProgress;
+  authState: AuthState;
+  isReturning: boolean;
+  resumeTarget: { screen: string; params?: any };
+}> => {
+  try {
+    const progress = await getUserProgress();
+    const authState = await getAuthState();
+    const isReturning = await isReturningUser();
+    const resumeTarget = await getResumeTarget();
+    
+    return {
+      progress,
+      authState,
+      isReturning,
+      resumeTarget
+    };
+  } catch (error) {
+    console.error('❌ Error getting debug storage info:', error);
+    throw error;
+  }
+};
+
+/**
+ * Development utility: Clear all progress (for testing)
+ */
+export const clearAllProgress = async (): Promise<void> => {
+  try {
+    await clearUserData();
+    console.log('✅ All progress data cleared');
+  } catch (error) {
+    console.error('❌ Error clearing progress data:', error);
+  }
 };