rystem.authentication.social.client 0.5.0 → 0.5.4

package/README.md

@@ -87,87 +87,111 @@ yarn add rystem.authentication.social.client
 pnpm add rystem.authentication.social.client
 ```
 
-### 🚀 React Native Setup
+---
+
+## 📱 React Native Complete Guide
+
+This library is **100% framework-agnostic** and works perfectly in **React Native**, **Expo**, and any mobile framework! However, setup differs from web because:
 
-The library works with **React Native** without any polyfills! You just need to provide custom implementations for:
+1. ❌ **No `window`, `document`, or `localStorage`** in React Native
+2. ❌ **Web SDK scripts** (Google Sign-In SDK, `@azure/msal-browser`) don't work in React Native
+3. ✅ **Native SDKs** must be used instead (`@react-native-google-signin/google-signin`, `@react-native-community/msal`)
 
-1. **Storage Service** (use AsyncStorage or Secure Storage instead of localStorage)
-2. **Routing Service** (use Linking API for deep links)
+### 🎯 Architecture Overview
 
-#### Example React Native Setup
+| Component | Web | React Native |
+|-----------|-----|--------------|
+| **Core Services** (`SocialLoginManager`, `setupSocialLogin`) | ✅ Works | ✅ Works |
+| **React Hooks** (`useSocialToken`, `useSocialUser`) | ✅ Works | ✅ Works |
+| **UI Components** (`MicrosoftButton`, `GoogleButton`) | ✅ Works | ❌ **Web-only** |
+| **Storage** | `LocalStorageService` | Custom `IStorageService` (AsyncStorage) |
+| **Routing** | `WindowRoutingService` | Custom `IRoutingService` (Linking) |
+| **Platform** | `BrowserPlatformService` | Custom `IPlatformService` (Dimensions) |
+
+### 📋 Setup Checklist
+
+- [ ] 1. Install `@react-native-async-storage/async-storage`
+- [ ] 2. Create `ReactNativeStorageService` implementing `IStorageService`
+- [ ] 3. Create `ReactNativeRoutingService` implementing `IRoutingService`
+- [ ] 4. Create `ReactNativePlatformService` implementing `IPlatformService`
+- [ ] 5. Install native OAuth SDKs (`@react-native-community/msal`, `@react-native-google-signin/google-signin`)
+- [ ] 6. Create custom login button components
+- [ ] 7. Use `SocialLoginManager.Instance(null).updateToken()` after successful native login
+
+---
+
+### 🔧 Step 1-4: Implementing Platform Services
+
+#### 💾 Storage Service (AsyncStorage)
+
+```bash
+npm install @react-native-async-storage/async-storage
+```
 
 ```typescript
 // services/ReactNativeStorageService.ts
 import AsyncStorage from '@react-native-async-storage/async-storage';
-import { IStorageService } from 'rystem.authentication.social.react';
+import { IStorageService } from 'rystem.authentication.social.client';
 
 export class ReactNativeStorageService implements IStorageService {
-    async get(key: string): Promise<string | null> {
-        try {
-            return await AsyncStorage.getItem(key);
-        } catch (error) {
-            console.error('AsyncStorage get error:', error);
-            return null;
-        }
+    get(key: string): string | null {
+        // Note: AsyncStorage is async, but IStorageService expects sync
+        // Use synchronous approach or modify your usage to handle promises
+        let result: string | null = null;
+        AsyncStorage.getItem(key).then(value => result = value);
+        return result;
     }
 
-    async set(key: string, value: string): Promise<void> {
-        try {
-            await AsyncStorage.setItem(key, value);
-        } catch (error) {
-            console.error('AsyncStorage set error:', error);
-        }
+    set(key: string, value: string): void {
+        AsyncStorage.setItem(key, value).catch(error =>
+            console.error('AsyncStorage set error:', error)
+        );
     }
 
-    async remove(key: string): Promise<void> {
-        try {
-            await AsyncStorage.removeItem(key);
-        } catch (error) {
-            console.error('AsyncStorage remove error:', error);
-        }
+    remove(key: string): void {
+        AsyncStorage.removeItem(key).catch(error =>
+            console.error('AsyncStorage remove error:', error)
+        );
     }
 
-    async has(key: string): Promise<boolean> {
-        const value = await this.get(key);
-        return value !== null;
+    has(key: string): boolean {
+        return this.get(key) !== null;
     }
 
-    async clear(): Promise<void> {
-        try {
-            await AsyncStorage.clear();
-        } catch (error) {
-            console.error('AsyncStorage clear error:', error);
-        }
+    clear(): void {
+        AsyncStorage.clear().catch(error =>
+            console.error('AsyncStorage clear error:', error)
+        );
     }
 }
+```
+
+#### 🧭 Routing Service (Linking API)
 
+```typescript
 // services/ReactNativeRoutingService.ts
 import { Linking } from 'react-native';
-import { IRoutingService } from 'rystem.authentication.social.react';
+import { IRoutingService } from 'rystem.authentication.social.client';
 
 export class ReactNativeRoutingService implements IRoutingService {
     private currentUrl: URL | null = null;
 
     constructor() {
-        // Parse initial URL
         Linking.getInitialURL().then(url => {
             if (url) this.currentUrl = new URL(url);
         });
 
-        // Listen for deep link events
         Linking.addEventListener('url', ({ url }) => {
             this.currentUrl = new URL(url);
         });
     }
 
     getSearchParam(key: string): string | null {
-        if (!this.currentUrl) return null;
-        return this.currentUrl.searchParams.get(key);
+        return this.currentUrl?.searchParams.get(key) ?? null;
     }
 
     getAllSearchParams(): URLSearchParams {
-        if (!this.currentUrl) return new URLSearchParams();
-        return this.currentUrl.searchParams;
+        return this.currentUrl?.searchParams ?? new URLSearchParams();
     }
 
     getCurrentPath(): string {
@@ -176,43 +200,97 @@ export class ReactNativeRoutingService implements IRoutingService {
     }
 
     navigateTo(url: string): void {
-        // For OAuth URLs, open in browser
         Linking.openURL(url);
     }
 
     navigateReplace(path: string): void {
-        // React Native navigation - implement with your router (React Navigation, Expo Router)
+        // Implement with React Navigation or Expo Router
         console.log('Navigate to:', path);
     }
 
     openPopup(url: string, name: string, features: string): Window | null {
-        // React Native doesn't support popups - use in-app browser
         Linking.openURL(url);
         return null;
     }
 }
+```
 
-// App setup
-import { setupSocialLogin, PlatformType, LoginMode } from 'rystem.authentication.social.react';
+#### 📐 Platform Service (Dimensions & Events)
+
+```typescript
+// services/ReactNativePlatformService.ts
+import { Dimensions, EventEmitter } from 'react-native';
+import { IPlatformService } from 'rystem.authentication.social.client';
+
+export class ReactNativePlatformService implements IPlatformService {
+    private eventEmitter = new EventEmitter();
+
+    addStorageListener(callback: () => void): void {
+        this.eventEmitter.addListener('storage', callback);
+    }
+
+    removeStorageListener(callback: () => void): void {
+        this.eventEmitter.removeListener('storage', callback);
+    }
+
+    getScreenWidth(): number {
+        return Dimensions.get('window').width;
+    }
+
+    getScreenHeight(): number {
+        return Dimensions.get('window').height;
+    }
+
+    loadScript(id: string, src: string, onLoad: () => void): HTMLScriptElement | null {
+        console.warn('Script loading not supported in React Native');
+        onLoad();
+        return null;
+    }
+
+    scriptExists(id: string): boolean {
+        return false;
+    }
+
+    removeScript(scriptElement: HTMLScriptElement): void {
+        // No-op
+    }
+
+    isPopup(): boolean {
+        return false;
+    }
+
+    closeWindow(): void {
+        // No-op
+    }
+}
+```
+
+#### ⚙️ Complete Setup
+
+```typescript
+// App.tsx
+import { setupSocialLogin, PlatformType, LoginMode } from 'rystem.authentication.social.client';
 import { ReactNativeStorageService } from './services/ReactNativeStorageService';
 import { ReactNativeRoutingService } from './services/ReactNativeRoutingService';
+import { ReactNativePlatformService } from './services/ReactNativePlatformService';
+import { Platform, Alert } from 'react-native';
 
 setupSocialLogin(x => {
     x.apiUri = "https://api.yourdomain.com";
 
-    // ✅ Provide React Native implementations
+    // ✅ Inject React Native implementations
     x.storageService = new ReactNativeStorageService();
     x.routingService = new ReactNativeRoutingService();
+    x.platformService = new ReactNativePlatformService();
 
-    // Platform configuration
     x.platform = {
-        type: PlatformType.Auto,  // Auto-detects iOS/Android
+        type: PlatformType.Auto,
         redirectPath: Platform.select({
             ios: 'myapp://oauth/callback',
             android: 'myapp://oauth/callback',
             default: '/account/login'
         }),
-        loginMode: LoginMode.Redirect  // Always redirect for mobile
+        loginMode: LoginMode.Redirect
     };
 
     x.microsoft.clientId = "your-client-id";
@@ -224,10 +302,190 @@ setupSocialLogin(x => {
 });
 ```
 
-**Why No Polyfills?**
-- ✅ The library now checks `typeof window !== 'undefined'` before accessing browser APIs
-- ✅ You inject platform-specific implementations via `IStorageService` and `IRoutingService`
-- ✅ No need for hacky polyfills or modifying `global` object
+---
+
+### 🎨 Step 5-6: Native Login Buttons
+
+#### 📘 Microsoft Login (Native MSAL)
+
+```bash
+npm install @react-native-community/msal
+```
+
+```typescript
+// components/MicrosoftLoginButton.tsx
+import React from 'react';
+import { Pressable, Text, StyleSheet, Alert } from 'react-native';
+import { MSALConfiguration, MSALResult, PublicClientApplication } from '@react-native-community/msal';
+import { SocialLoginManager, ProviderType } from 'rystem.authentication.social.client';
+
+const MSAL_CONFIG: MSALConfiguration = {
+    auth: {
+        clientId: 'your-microsoft-client-id',
+        authority: 'https://login.microsoftonline.com/consumers',
+    },
+};
+
+export const MicrosoftLoginButton = () => {
+    const handleLogin = async () => {
+        try {
+            const pca = new PublicClientApplication(MSAL_CONFIG);
+            await pca.init();
+
+            const result: MSALResult = await pca.acquireToken({
+                scopes: ['openid', 'profile', 'email', 'User.Read'],
+            });
+
+            // ✅ Send token to backend
+            await SocialLoginManager.Instance(null).updateToken(
+                ProviderType.Microsoft,
+                result.idToken
+            );
+
+            console.log('✅ Microsoft login successful');
+        } catch (error: any) {
+            console.error('❌ Microsoft login failed:', error);
+            Alert.alert('Login Failed', error.message || 'Unknown error');
+        }
+    };
+
+    return (
+        <Pressable style={[styles.button, { backgroundColor: '#2f2f2f' }]} onPress={handleLogin}>
+            <Text style={styles.text}>🪟 Sign in with Microsoft</Text>
+        </Pressable>
+    );
+};
+
+const styles = StyleSheet.create({
+    button: { padding: 12, borderRadius: 8, alignItems: 'center', marginVertical: 8 },
+    text: { color: '#fff', fontSize: 16, fontWeight: '600' },
+});
+```
+
+#### 🔴 Google Login (Native SDK)
+
+```bash
+npm install @react-native-google-signin/google-signin
+```
+
+```typescript
+// components/GoogleLoginButton.tsx
+import React from 'react';
+import { Pressable, Text, StyleSheet, Alert } from 'react-native';
+import { GoogleSignin, statusCodes } from '@react-native-google-signin/google-signin';
+import { SocialLoginManager, ProviderType } from 'rystem.authentication.social.client';
+
+// Configure once at app startup
+GoogleSignin.configure({
+    webClientId: 'your-google-web-client-id.apps.googleusercontent.com',
+    offlineAccess: true,
+    forceCodeForRefreshToken: true,
+    iosClientId: 'your-ios-client-id.apps.googleusercontent.com',
+});
+
+export const GoogleLoginButton = () => {
+    const handleLogin = async () => {
+        try {
+            await GoogleSignin.hasPlayServices();
+            const userInfo = await GoogleSignin.signIn();
+
+            if (!userInfo.idToken) throw new Error('No ID token received');
+
+            // ✅ Send token to backend
+            await SocialLoginManager.Instance(null).updateToken(
+                ProviderType.Google,
+                userInfo.idToken
+            );
+
+            console.log('✅ Google login successful');
+        } catch (error: any) {
+            if (error.code === statusCodes.SIGN_IN_CANCELLED) {
+                console.log('User cancelled login');
+            } else if (error.code === statusCodes.PLAY_SERVICES_NOT_AVAILABLE) {
+                Alert.alert('Error', 'Play Services not available');
+            } else {
+                console.error('❌ Google login failed:', error);
+                Alert.alert('Login Failed', error.message);
+            }
+        }
+    };
+
+    return (
+        <Pressable style={[styles.button, { backgroundColor: '#4285F4' }]} onPress={handleLogin}>
+            <Text style={styles.text}>🔵 Sign in with Google</Text>
+        </Pressable>
+    );
+};
+
+const styles = StyleSheet.create({
+    button: { padding: 12, borderRadius: 8, alignItems: 'center', marginVertical: 8 },
+    text: { color: '#fff', fontSize: 16, fontWeight: '600' },
+});
+```
+
+---
+
+### 📱 Step 7: Usage in Your App
+
+```typescript
+// screens/LoginScreen.tsx
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { MicrosoftLoginButton } from '../components/MicrosoftLoginButton';
+import { GoogleLoginButton } from '../components/GoogleLoginButton';
+import { useSocialToken, useSocialUser } from 'rystem.authentication.social.client';
+
+export const LoginScreen = () => {
+    const token = useSocialToken();
+    const user = useSocialUser();
+
+    if (!token.isExpired) {
+        return (
+            <View style={styles.container}>
+                <Text style={styles.welcome}>Welcome, {user.username}!</Text>
+                <Text>Provider: {user.provider}</Text>
+                <Text>Email: {user.email}</Text>
+            </View>
+        );
+    }
+
+    return (
+        <View style={styles.container}>
+            <Text style={styles.title}>Choose Login Method</Text>
+            <MicrosoftLoginButton />
+            <GoogleLoginButton />
+        </View>
+    );
+};
+
+const styles = StyleSheet.create({
+    container: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: 20 },
+    title: { fontSize: 20, fontWeight: 'bold', marginBottom: 20 },
+    welcome: { fontSize: 24, fontWeight: 'bold', marginBottom: 10 },
+});
+```
+
+---
+
+### ✅ React Native Summary
+
+**What You Need:**
+1. Implement 3 services: `IStorageService`, `IRoutingService`, `IPlatformService`
+2. Install native OAuth SDKs (not web SDKs!)
+3. Create custom UI components
+4. Call `SocialLoginManager.Instance(null).updateToken()` after native login success
+
+**What Works Automatically:**
+- ✅ `useSocialToken()` / `useSocialUser()` hooks
+- ✅ Token storage and refresh logic
+- ✅ Backend communication
+
+**Why No `window` Access Issues:**
+- ✅ Library uses service abstractions (`IStorageService`, `IRoutingService`, `IPlatformService`)
+- ✅ You inject platform-specific implementations
+- ✅ No polyfills needed!
+
+---
 
 ### ⚠️ Important for React Router / Next.js Users
 
@@ -240,36 +498,34 @@ If you're using **React Router** or **Next.js App Router**, OAuth callbacks and
 - Next.js App Router (v13+)
 - Unit Testing
 
-## 🚀 Quick Start
+## 🚀 Quick Start (Web Applications)
 
 ### 1. Setup Configuration (main.tsx)
 
 ```typescript
-import { SocialLoginWrapper, setupSocialLogin } from 'rystem.authentication.social.react';
+import { SocialLoginWrapper, setupSocialLogin } from 'rystem.authentication.social.client';
 import App from './App';
 
 setupSocialLogin(x => {
+    // 🚀 ONE-LINE SETUP for web applications
+    // This configures localStorage, window routing, and browser platform APIs
+    x.useBrowserDefaults();
+
     // API server URL
     x.apiUri = "https://localhost:7017";
-    
-    // Optional: Custom redirect path (default: "/account/login")
-    x.platform = {
-        redirectPath: "/account/login"  // Auto-detects domain
-    };
-    
+
     // Configure OAuth providers (only clientId needed for client-side)
     x.microsoft.clientId = "0b90db07-be9f-4b29-b673-9e8ee9265927";
     x.google.clientId = "23769141170-lfs24avv5qrj00m4cbmrm202c0fc6gcg.apps.googleusercontent.com";
     x.facebook.clientId = "345885718092912";
     x.github.clientId = "97154d062f2bb5d28620";
-    x.amazon.clientId = "amzn1.application-oa2-client.dffbc466d62c44e49d71ad32f4aecb62";
-    
+
     // Error handling callback
     x.onLoginFailure = (error) => {
         console.error(`Login failed: ${error.message} (Code: ${error.code})`);
         alert(`Authentication error: ${error.message}`);
     };
-    
+
     // Automatic token refresh when expired
     x.automaticRefresh = true;
 });
@@ -285,10 +541,49 @@ function Root() {
 export default Root;
 ```
 
+#### 🤔 What does `useBrowserDefaults()` do?
+
+This helper method **automatically configures three essential services** for web browsers:
+
+1. **`storageService`**: `LocalStorageService` → Uses browser `localStorage` to persist tokens, PKCE verifiers, and user data
+2. **`routingService`**: `WindowRoutingService` → Uses `window.location` to read OAuth callback parameters and `window.history` for navigation
+3. **`platformService`**: `BrowserPlatformService` → Uses `window`, `document`, and DOM APIs for popup windows, screen dimensions, and external SDK loading
+
+**Why is this needed?**  
+The library is **framework-agnostic** and works in **React**, **React Native**, **Next.js**, and **Expo**. Each environment has different APIs:
+- **Web**: Uses `window`, `localStorage`, `document`
+- **React Native**: Uses `AsyncStorage`, `Linking`, `Dimensions`
+- **Next.js SSR**: May not have `window` available
+
+By requiring explicit service configuration, the library:
+- ✅ Forces you to think about your environment
+- ✅ Avoids unexpected crashes in non-browser environments
+- ✅ Makes it clear which dependencies are being used
+- ✅ Allows easy customization (e.g., using React Router instead of `window.history`)
+
+**Alternative: Manual configuration**
+
+If you want more control, you can configure services manually:
+
+```typescript
+import { LocalStorageService, WindowRoutingService, BrowserPlatformService } from 'rystem.authentication.social.client';
+
+setupSocialLogin(x => {
+    x.storageService = new LocalStorageService();
+    x.routingService = new WindowRoutingService();
+    x.platformService = new BrowserPlatformService();
+    // ... rest of config
+});
+```
+
+**For React Native setup**, see the [📱 React Native Complete Guide](#-react-native-complete-guide) section below.
+
+---
+
 ### 2. Use in Components
 
 ```typescript
-import { useSocialToken, useSocialUser, SocialLoginButtons, SocialLogoutButton } from 'rystem.authentication.social.react';
+import { useSocialToken, useSocialUser, SocialLoginButtons, SocialLogoutButton } from 'rystem.authentication.social.client';
 
 export const App = () => {
     const token = useSocialToken();

package/lib/buttons/CreateSocialButton.js

@@ -15,8 +15,10 @@ const CreateSocialButton = ({ provider, className = '', redirect_uri, children,
         // Clean up any leftover popup result from previous attempts
         // Note: Popup mode uses native localStorage for cross-window communication (storage event)
         // The popup processes token exchange and saves the result (success or error)
-        const social_result = `social_result_${provider}`;
-        localStorage.removeItem(social_result);
+        if (typeof window !== 'undefined' && typeof localStorage !== 'undefined') {
+            const social_result = `social_result_${provider}`;
+            localStorage.removeItem(social_result);
+        }
     }, [provider]);
     (0, react_1.useEffect)(() => {
         // Note: Popup window callback (detect code + write to localStorage) 
@@ -32,37 +34,27 @@ const CreateSocialButton = ({ provider, className = '', redirect_uri, children,
         !isSdkLoaded && load();
     }, [isSdkLoaded]);
     (0, react_1.useEffect)(() => () => {
-        if (scriptNodeRef.current)
-            scriptNodeRef.current.remove();
+        if (scriptNodeRef.current) {
+            settings.platformService.removeScript(scriptNodeRef.current);
+        }
     }, []);
     const checkIsExistsSDKScript = (0, react_1.useCallback)(() => {
-        return !!document.getElementById(scriptId);
-    }, []);
-    const insertScript = (0, react_1.useCallback)((d, s = 'script', id, jsSrc, cb) => {
-        const sdkScriptTag = d.createElement(s);
-        sdkScriptTag.id = id;
-        sdkScriptTag.src = jsSrc;
-        sdkScriptTag.async = true;
-        sdkScriptTag.defer = true;
-        sdkScriptTag.crossorigin = "anonymous";
-        const scriptNode = document.getElementsByTagName('script')[0];
-        scriptNodeRef.current = sdkScriptTag;
-        scriptNode &&
-            scriptNode.parentNode &&
-            scriptNode.parentNode.insertBefore(sdkScriptTag, scriptNode);
-        sdkScriptTag.onload = cb;
-    }, []);
+        return settings.platformService.scriptExists(scriptId);
+    }, [scriptId]);
     const load = (0, react_1.useCallback)(() => {
         if (checkIsExistsSDKScript()) {
             setIsSdkLoaded(true);
         }
         else {
-            insertScript(document, 'script', scriptId, scriptUri ?? "", () => {
+            const scriptElement = settings.platformService.loadScript(scriptId, scriptUri ?? "", () => {
                 onScriptLoad && onScriptLoad();
                 setIsSdkLoaded(true);
             });
+            if (scriptElement) {
+                scriptNodeRef.current = scriptElement;
+            }
         }
-    }, [checkIsExistsSDKScript, insertScript]);
+    }, [checkIsExistsSDKScript, scriptId, scriptUri, onScriptLoad]);
     const handlePostMessage = (0, react_1.useCallback)(async (code) => {
         if (code)
             __1.SocialLoginManager.Instance(null).updateToken(provider, code);
@@ -75,6 +67,10 @@ const CreateSocialButton = ({ provider, className = '', redirect_uri, children,
         settings.onLoginFailure({ code: 7, message: x, provider: provider });
     };
     const onChangeLocalStorage = (0, react_1.useCallback)(() => {
+        if (typeof window === 'undefined') {
+            console.warn('CreateSocialButton: window not available (React Native or SSR?)');
+            return;
+        }
         window.removeEventListener('storage', onChangeLocalStorage, false);
         // Popup mode: The popup processes the token exchange and saves the result
         // We just need to read the result and update the UI (or show error)
@@ -131,11 +127,12 @@ const CreateSocialButton = ({ provider, className = '', redirect_uri, children,
             }
             else {
                 // Popup mode: open in popup window using routing service
-                window.addEventListener('storage', onChangeLocalStorage, false);
+                settings.platformService.addStorageListener(onChangeLocalStorage);
+                // Calculate popup position
                 const width = 450;
                 const height = 730;
-                const left = window.screen.width / 2 - width / 2;
-                const top = window.screen.height / 2 - height / 2;
+                const left = settings.platformService.getScreenWidth() / 2 - width / 2;
+                const top = settings.platformService.getScreenHeight() / 2 - height / 2;
                 const features = 'menubar=no,location=no,resizable=no,scrollbars=no,status=no, width=' +
                     width +
                     ', height=' +
@@ -152,6 +149,10 @@ const CreateSocialButton = ({ provider, className = '', redirect_uri, children,
         isSdkLoaded,
         onChangeLocalStorage,
         loginMode,
+        load,
+        onClick,
+        handlePostMessage,
+        handleError,
     ]);
     return ((0, jsx_runtime_1.jsx)("div", { className: className, onClick: onLogin, children: children }, provider.toString()));
 };

package/lib/context/SocialLoginWrapper.js

@@ -23,13 +23,15 @@ const SocialLoginWrapper = (c) => {
         const loginMode = settings.platform?.loginMode || LoginMode_1.LoginMode.Popup;
         // Use routingService to read URL parameters (supports React Router, Next.js, etc.)
         const routingService = settings.routingService;
+        const storageService = settings.storageService;
+        const platformService = settings.platformService;
         const code = routingService.getSearchParam(queryCode);
         const stateParam = routingService.getSearchParam(queryState);
         console.log('🔍 SocialLoginWrapper: OAuth callback detection:', {
             code: code ? 'present' : 'missing',
             state: stateParam,
             loginMode,
-            isPopup: window.opener !== null,
+            isPopup: platformService.isPopup(),
             alreadyProcessed: callbackProcessedRef.current,
             routingService: routingService.constructor.name
         });
@@ -44,43 +46,41 @@ const SocialLoginWrapper = (c) => {
                 const providerName = ProviderType_1.ProviderType[providerType];
                 // Mark as processed BEFORE making API call
                 callbackProcessedRef.current = true;
-                // Check if we're in a popup window (simpler condition)
-                // If window.opener exists, we're definitely in a popup, regardless of loginMode config
-                if (window.opener) {
+                // Check if we're in a popup window using platformService
+                if (platformService.isPopup()) {
                     // POPUP MODE: Process token exchange IN THE POPUP, then save result and close
                     console.log('✅ [Popup] Detected popup window, processing token exchange in popup');
-                    const social_code = `social_code_${providerType}`;
                     const social_result = `social_result_${providerType}`;
                     __1.SocialLoginManager.Instance(null).updateToken(providerType, code)
                         .then(() => {
                         console.log('✅ [Popup] Token exchange successful, saving success result');
-                        // Save success result for main window
-                        localStorage.setItem(social_result, JSON.stringify({
+                        // Save success result for main window using storage service
+                        storageService.set(social_result, JSON.stringify({
                             success: true,
                             provider: providerName
                         }));
-                        // Close popup after ensuring localStorage is written
+                        // Close popup after ensuring storage is written
                         setTimeout(() => {
                             console.log('🔒 [Popup] Closing popup after successful login');
-                            window.close();
+                            platformService.closeWindow();
                         }, 100);
                     })
                         .catch((error) => {
                         console.error('❌ [Popup] Token exchange failed:', error);
-                        // Save error result for main window
-                        localStorage.setItem(social_result, JSON.stringify({
+                        // Save error result for main window using storage service
+                        storageService.set(social_result, JSON.stringify({
                             success: false,
                             provider: providerName,
                             error: error.message || 'Token exchange failed'
                         }));
-                        // Close popup after ensuring localStorage is written
+                        // Close popup after ensuring storage is written
                         setTimeout(() => {
                             console.log('🔒 [Popup] Closing popup after error');
-                            window.close();
+                            platformService.closeWindow();
                         }, 100);
                     });
                     // Note: The main window's CreateSocialButton will receive the storage event
-                    // and read the result (success or error) from localStorage
+                    // and read the result (success or error) from storage
                 }
                 else {
                     // REDIRECT MODE: Process token exchange directly in main window
@@ -89,7 +89,6 @@ const SocialLoginWrapper = (c) => {
                         .then(() => {
                         console.log('✅ Token exchange successful');
                         // Get return URL saved before OAuth redirect using storage service
-                        const storageService = settings.storageService;
                         const returnUrl = storageService.get('social_login_return_url');
                         storageService.remove('social_login_return_url');
                         if (returnUrl) {
@@ -116,7 +115,7 @@ const SocialLoginWrapper = (c) => {
                             });
                         }
                         // Clean return URL on error using storage service
-                        settings.storageService.remove('social_login_return_url');
+                        storageService.remove('social_login_return_url');
                         // Clean URL even on error using routing service
                         const cleanPath = routingService.getCurrentPath().split('?')[0];
                         routingService.navigateReplace(cleanPath);

package/lib/index.d.ts

@@ -40,6 +40,8 @@ export { TokenStorageService } from './services/TokenStorageService';
 export { UserStorageService } from './services/UserStorageService';
 export type { IRoutingService } from './services/IRoutingService';
 export { WindowRoutingService } from './services/WindowRoutingService';
+export type { IPlatformService } from './services/IPlatformService';
+export { BrowserPlatformService } from './services/BrowserPlatformService';
 export { PlatformType } from './models/setup/PlatformType';
 export { LoginMode } from './models/setup/LoginMode';
 export type { PlatformConfig, PlatformSelector } from './models/setup/PlatformConfig';

package/lib/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.selectByPlatform = exports.buildRedirectUri = exports.isReactNative = exports.isMobilePlatform = exports.getDefaultRedirectUri = exports.detectPlatform = exports.LoginMode = exports.PlatformType = exports.WindowRoutingService = exports.UserStorageService = exports.TokenStorageService = exports.PkceStorageService = exports.LocalStorageService = exports.PinterestIcon = exports.TikTokIcon = exports.InstagramIcon = exports.AmazonIcon = exports.LinkedInIcon = exports.XIcon = exports.GitHubIcon = exports.FacebookIcon = exports.GoogleIcon = exports.MicrosoftIcon = exports.ModernSocialButton = exports.generateCodeChallenge = exports.generateCodeVerifier = exports.SocialLoginButtons = exports.CreateSocialButton = exports.ProviderType = exports.SocialLoginManager = exports.setupSocialLogin = exports.getSocialLoginSettings = exports.removeSocialLogin = exports.useSocialUser = exports.useSocialToken = exports.SocialLoginContextLogout = exports.SocialLoginContextRefresh = exports.SocialLoginContextUpdate = exports.SocialLoginWrapper = exports.SocialLogoutButton = exports.PinterestButton = exports.InstagramButton = exports.TikTokButton = exports.XButton = exports.LinkedinButton = exports.GitHubButton = exports.FacebookButton = exports.MicrosoftButton = exports.GoogleButton = exports.AmazonButton = void 0;
+exports.buildRedirectUri = exports.isReactNative = exports.isMobilePlatform = exports.getDefaultRedirectUri = exports.detectPlatform = exports.LoginMode = exports.PlatformType = exports.BrowserPlatformService = exports.WindowRoutingService = exports.UserStorageService = exports.TokenStorageService = exports.PkceStorageService = exports.LocalStorageService = exports.PinterestIcon = exports.TikTokIcon = exports.InstagramIcon = exports.AmazonIcon = exports.LinkedInIcon = exports.XIcon = exports.GitHubIcon = exports.FacebookIcon = exports.GoogleIcon = exports.MicrosoftIcon = exports.ModernSocialButton = exports.generateCodeChallenge = exports.generateCodeVerifier = exports.SocialLoginButtons = exports.CreateSocialButton = exports.ProviderType = exports.SocialLoginManager = exports.setupSocialLogin = exports.getSocialLoginSettings = exports.removeSocialLogin = exports.useSocialUser = exports.useSocialToken = exports.SocialLoginContextLogout = exports.SocialLoginContextRefresh = exports.SocialLoginContextUpdate = exports.SocialLoginWrapper = exports.SocialLogoutButton = exports.PinterestButton = exports.InstagramButton = exports.TikTokButton = exports.XButton = exports.LinkedinButton = exports.GitHubButton = exports.FacebookButton = exports.MicrosoftButton = exports.GoogleButton = exports.AmazonButton = void 0;
+exports.selectByPlatform = void 0;
 var AmazonButton_1 = require("./buttons/singles/AmazonButton");
 Object.defineProperty(exports, "AmazonButton", { enumerable: true, get: function () { return AmazonButton_1.AmazonButton; } });
 var GoogleButton_1 = require("./buttons/singles/GoogleButton");
@@ -75,6 +76,8 @@ var UserStorageService_1 = require("./services/UserStorageService");
 Object.defineProperty(exports, "UserStorageService", { enumerable: true, get: function () { return UserStorageService_1.UserStorageService; } });
 var WindowRoutingService_1 = require("./services/WindowRoutingService");
 Object.defineProperty(exports, "WindowRoutingService", { enumerable: true, get: function () { return WindowRoutingService_1.WindowRoutingService; } });
+var BrowserPlatformService_1 = require("./services/BrowserPlatformService");
+Object.defineProperty(exports, "BrowserPlatformService", { enumerable: true, get: function () { return BrowserPlatformService_1.BrowserPlatformService; } });
 // Platform and login mode support
 var PlatformType_1 = require("./models/setup/PlatformType");
 Object.defineProperty(exports, "PlatformType", { enumerable: true, get: function () { return PlatformType_1.PlatformType; } });

package/lib/models/setup/SocialLoginSettings.d.ts

@@ -2,6 +2,7 @@ import { SocialLoginErrorResponse, SocialParameter } from "../..";
 import { PlatformConfig } from "./PlatformConfig";
 import { IStorageService } from "../../services/IStorageService";
 import { IRoutingService } from "../../services/IRoutingService";
+import { IPlatformService } from "../../services/IPlatformService";
 export interface SocialLoginSettings {
     apiUri: string;
     automaticRefresh: boolean;
@@ -10,26 +11,73 @@ export interface SocialLoginSettings {
     title: string | null;
     /**
      * Storage service for persisting tokens, PKCE verifiers, etc.
-     * Default: LocalStorageService (browser localStorage)
      *
-     * @example Custom secure storage for mobile
-     * storageService: new SecureStorageService()
+     * ⚠️ **Required**: Must be configured explicitly or via `useBrowserDefaults()`.
+     *
+     * Web: Use `x.useBrowserDefaults()` or manually set `new LocalStorageService()`
+     * React Native: Implement `IStorageService` with AsyncStorage
+     *
+     * @example Web (automatic)
+     * x.useBrowserDefaults();
+     *
+     * @example Web (manual)
+     * x.storageService = new LocalStorageService();
+     *
+     * @example React Native
+     * x.storageService = new ReactNativeStorageService();
      */
     storageService: IStorageService;
     /**
      * Routing service for URL parameter reading and navigation
-     * Default: WindowRoutingService (uses window.location and window.history)
+     *
+     * ⚠️ **Required**: Must be configured explicitly or via `useBrowserDefaults()`.
+     *
+     * Web: Use `x.useBrowserDefaults()` or manually set `new WindowRoutingService()`
+     * React Native: Implement `IRoutingService` with Linking API
      *
      * IMPORTANT: Required for React Router, Next.js App Router, and other client-side routing frameworks
      * to properly handle OAuth callbacks, redirects, and return URLs.
      *
-     * @example React Router with useSearchParams, useNavigate, and useLocation hooks
-     * routingService: new ReactRouterRoutingService()
+     * @example Web (automatic)
+     * x.useBrowserDefaults();
      *
-     * @example Next.js App Router with useRouter, usePathname, and useSearchParams
-     * routingService: new NextAppRouterRoutingService()
+     * @example Web (manual)
+     * x.routingService = new WindowRoutingService();
+     *
+     * @example React Router
+     * x.routingService = new ReactRouterRoutingService();
+     *
+     * @example Next.js App Router
+     * x.routingService = new NextAppRouterRoutingService();
+     *
+     * @example React Native
+     * x.routingService = new ReactNativeRoutingService();
      */
     routingService: IRoutingService;
+    /**
+     * Platform service for environment-specific operations (events, dimensions, scripts)
+     *
+     * ⚠️ **Required**: Must be configured explicitly or via `useBrowserDefaults()`.
+     *
+     * Web: Use `x.useBrowserDefaults()` or manually set `new BrowserPlatformService()`
+     * React Native: Implement `IPlatformService` with Dimensions, EventEmitter
+     *
+     * Used by UI components for:
+     * - Storage event listeners (popup ↔ main window communication)
+     * - Screen dimensions (popup positioning)
+     * - External script loading (Google SDK, Facebook SDK)
+     * - Window operations (popup detection, closing)
+     *
+     * @example Web (automatic)
+     * x.useBrowserDefaults();
+     *
+     * @example Web (manual)
+     * x.platformService = new BrowserPlatformService();
+     *
+     * @example React Native
+     * x.platformService = new ReactNativePlatformService();
+     */
+    platformService: IPlatformService;
     /**
      * Platform configuration (Web, iOS, Android)
      *
@@ -58,6 +106,31 @@ export interface SocialLoginSettings {
     instagram: SocialParameter;
     pinterest: SocialParameter;
     tiktok: SocialParameter;
+    /**
+     * 🚀 Helper method for WEB applications
+     *
+     * Automatically configures browser-based services:
+     * - `storageService`: LocalStorageService (uses browser localStorage)
+     * - `routingService`: WindowRoutingService (uses window.location and window.history)
+     * - `platformService`: BrowserPlatformService (uses window, document, DOM APIs)
+     *
+     * ⚠️ **Web only**: Do NOT call this in React Native applications!
+     *
+     * @example Basic web setup
+     * setupSocialLogin(x => {
+     *     x.useBrowserDefaults(); // ✅ One line to configure all browser services
+     *     x.apiUri = "https://api.example.com";
+     *     x.microsoft.clientId = "your-client-id";
+     * });
+     *
+     * @example With custom routing (React Router, Next.js)
+     * setupSocialLogin(x => {
+     *     x.useBrowserDefaults();
+     *     x.routingService = new ReactRouterRoutingService(); // Override routing only
+     *     // ... rest of config
+     * });
+     */
+    useBrowserDefaults(): void;
 }
 export interface IIdentityTransformer<TIdentity> {
     toPlain: (input: TIdentity | any) => any;

package/lib/services/BrowserPlatformService.d.ts

@@ -0,0 +1,38 @@
+import type { IPlatformService } from './IPlatformService';
+/**
+ * Browser implementation of IPlatformService
+ * Uses native window, document, and DOM APIs
+ *
+ * @example
+ * ```typescript
+ * const platformService = new BrowserPlatformService();
+ *
+ * // Listen for storage events (popup communication)
+ * platformService.addStorageListener(() => {
+ *     console.log('Storage changed!');
+ * });
+ *
+ * // Get screen dimensions
+ * const width = platformService.getScreenWidth();
+ *
+ * // Load external script (e.g., Google SDK)
+ * platformService.loadScript('google-sdk', 'https://apis.google.com/js/api.js', () => {
+ *     console.log('Google SDK loaded!');
+ * });
+ * ```
+ */
+export declare class BrowserPlatformService implements IPlatformService {
+    /**
+     * Check if browser APIs are available
+     */
+    private isAvailable;
+    addStorageListener(callback: () => void): void;
+    removeStorageListener(callback: () => void): void;
+    getScreenWidth(): number;
+    getScreenHeight(): number;
+    loadScript(id: string, src: string, onLoad: () => void): HTMLScriptElement | null;
+    scriptExists(id: string): boolean;
+    removeScript(scriptElement: HTMLScriptElement): void;
+    isPopup(): boolean;
+    closeWindow(): void;
+}

package/lib/services/BrowserPlatformService.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserPlatformService = void 0;
+/**
+ * Browser implementation of IPlatformService
+ * Uses native window, document, and DOM APIs
+ *
+ * @example
+ * ```typescript
+ * const platformService = new BrowserPlatformService();
+ *
+ * // Listen for storage events (popup communication)
+ * platformService.addStorageListener(() => {
+ *     console.log('Storage changed!');
+ * });
+ *
+ * // Get screen dimensions
+ * const width = platformService.getScreenWidth();
+ *
+ * // Load external script (e.g., Google SDK)
+ * platformService.loadScript('google-sdk', 'https://apis.google.com/js/api.js', () => {
+ *     console.log('Google SDK loaded!');
+ * });
+ * ```
+ */
+class BrowserPlatformService {
+    /**
+     * Check if browser APIs are available
+     */
+    isAvailable() {
+        return typeof window !== 'undefined';
+    }
+    // ===== Storage Event Handling =====
+    addStorageListener(callback) {
+        if (!this.isAvailable()) {
+            console.warn('BrowserPlatformService: window not available (SSR?)');
+            return;
+        }
+        window.addEventListener('storage', callback, false);
+    }
+    removeStorageListener(callback) {
+        if (!this.isAvailable()) {
+            return;
+        }
+        window.removeEventListener('storage', callback, false);
+    }
+    // ===== Screen Dimensions =====
+    getScreenWidth() {
+        if (!this.isAvailable() || !window.screen) {
+            return 1024; // Default fallback
+        }
+        return window.screen.width;
+    }
+    getScreenHeight() {
+        if (!this.isAvailable() || !window.screen) {
+            return 768; // Default fallback
+        }
+        return window.screen.height;
+    }
+    // ===== Script Loading =====
+    loadScript(id, src, onLoad) {
+        if (!this.isAvailable() || typeof document === 'undefined') {
+            console.warn('BrowserPlatformService: document not available (SSR?)');
+            onLoad(); // Call callback anyway to avoid hanging
+            return null;
+        }
+        // Check if script already exists
+        if (this.scriptExists(id)) {
+            onLoad();
+            return document.getElementById(id);
+        }
+        const script = document.createElement('script');
+        script.id = id;
+        script.src = src;
+        script.async = true;
+        script.defer = true;
+        script.crossOrigin = 'anonymous';
+        script.onload = onLoad;
+        const firstScript = document.getElementsByTagName('script')[0];
+        if (firstScript && firstScript.parentNode) {
+            firstScript.parentNode.insertBefore(script, firstScript);
+        }
+        else {
+            document.head.appendChild(script);
+        }
+        return script;
+    }
+    scriptExists(id) {
+        if (!this.isAvailable() || typeof document === 'undefined') {
+            return false;
+        }
+        return !!document.getElementById(id);
+    }
+    removeScript(scriptElement) {
+        if (!this.isAvailable() || typeof document === 'undefined') {
+            return;
+        }
+        if (scriptElement && scriptElement.parentNode) {
+            scriptElement.parentNode.removeChild(scriptElement);
+        }
+    }
+    // ===== Window Operations =====
+    isPopup() {
+        if (!this.isAvailable()) {
+            return false;
+        }
+        return window.opener !== null;
+    }
+    closeWindow() {
+        if (!this.isAvailable()) {
+            console.warn('BrowserPlatformService: window not available (SSR?)');
+            return;
+        }
+        window.close();
+    }
+}
+exports.BrowserPlatformService = BrowserPlatformService;

package/lib/services/IPlatformBrowserService.js

@@ -0,0 +1 @@
+"use strict";

package/lib/services/IPlatformService.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Platform-agnostic service for environment-specific operations
+ * Abstracts browser/native APIs for cross-platform support
+ *
+ * Implementations:
+ * - BrowserPlatformService (web): Uses window, document, storage events
+ * - ReactNativePlatformService (mobile): Uses EventEmitter, Dimensions, Linking
+ *
+ * Use cases:
+ * - Web: DOM manipulation, popup windows, storage events
+ * - React Native: Custom events, screen dimensions, deep links
+ * - SSR: No-op implementations to avoid crashes
+ */
+export interface IPlatformService {
+    /**
+     * Add listener for storage changes (used for popup → main window communication)
+     * Web: Uses window.addEventListener('storage', ...)
+     * React Native: Uses custom event emitter or no-op
+     *
+     * @param callback Function to call when storage changes
+     */
+    addStorageListener(callback: () => void): void;
+    /**
+     * Remove storage event listener
+     * Web: Uses window.removeEventListener('storage', ...)
+     * React Native: Removes custom event listener
+     *
+     * @param callback Function to remove
+     */
+    removeStorageListener(callback: () => void): void;
+    /**
+     * Get screen width for popup positioning
+     * Web: Returns window.screen.width
+     * React Native: Returns Dimensions.get('window').width
+     *
+     * @returns Screen width in pixels
+     */
+    getScreenWidth(): number;
+    /**
+     * Get screen height for popup positioning
+     * Web: Returns window.screen.height
+     * React Native: Returns Dimensions.get('window').height
+     *
+     * @returns Screen height in pixels
+     */
+    getScreenHeight(): number;
+    /**
+     * Load external JavaScript SDK
+     * Web: Injects <script> tag into document
+     * React Native: No-op (SDKs are bundled or not used)
+     *
+     * @param id Unique script ID
+     * @param src Script URL
+     * @param onLoad Callback when script loads
+     * @returns Script element if loaded, null otherwise
+     */
+    loadScript(id: string, src: string, onLoad: () => void): HTMLScriptElement | null;
+    /**
+     * Check if script is already loaded
+     * Web: Checks document.getElementById(id)
+     * React Native: Returns false (no script loading)
+     *
+     * @param id Script ID
+     * @returns True if script exists
+     */
+    scriptExists(id: string): boolean;
+    /**
+     * Remove loaded script
+     * Web: Removes script tag from DOM
+     * React Native: No-op
+     *
+     * @param scriptElement Script element to remove
+     */
+    removeScript(scriptElement: HTMLScriptElement): void;
+    /**
+     * Check if current window is a popup window
+     * Web: Checks window.opener !== null
+     * React Native: Returns false (no popup concept)
+     *
+     * @returns True if running in a popup window
+     */
+    isPopup(): boolean;
+    /**
+     * Close current window (used after popup OAuth callback)
+     * Web: Calls window.close()
+     * React Native: No-op or custom navigation
+     */
+    closeWindow(): void;
+}

package/lib/services/IPlatformService.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/setup/setupSocialLogin.d.ts

@@ -1,2 +1,29 @@
 import { SocialLoginSettings, SocialLoginManager } from "..";
+/**
+ * Setup social login authentication
+ *
+ * ⚠️ **Important**: You MUST configure the following services:
+ * - `storageService` (IStorageService)
+ * - `routingService` (IRoutingService)
+ * - `platformService` (IPlatformService)
+ *
+ * For **web applications**, use the helper method:
+ * ```typescript
+ * setupSocialLogin(x => {
+ *     x.useBrowserDefaults(); // ✅ Sets up localStorage, window routing, and browser platform
+ *     x.apiUri = "https://api.example.com";
+ *     x.microsoft.clientId = "your-client-id";
+ * });
+ * ```
+ *
+ * For **React Native**, provide custom implementations:
+ * ```typescript
+ * setupSocialLogin(x => {
+ *     x.storageService = new ReactNativeStorageService();
+ *     x.routingService = new ReactNativeRoutingService();
+ *     x.platformService = new ReactNativePlatformService();
+ *     // ... rest of config
+ * });
+ * ```
+ */
 export declare const setupSocialLogin: (settings: (settings: SocialLoginSettings) => void) => SocialLoginManager;

package/lib/setup/setupSocialLogin.js

@@ -7,6 +7,34 @@ const PlatformType_1 = require("../models/setup/PlatformType");
 const platform_1 = require("../utils/platform");
 const LocalStorageService_1 = require("../services/LocalStorageService");
 const WindowRoutingService_1 = require("../services/WindowRoutingService");
+const BrowserPlatformService_1 = require("../services/BrowserPlatformService");
+/**
+ * Setup social login authentication
+ *
+ * ⚠️ **Important**: You MUST configure the following services:
+ * - `storageService` (IStorageService)
+ * - `routingService` (IRoutingService)
+ * - `platformService` (IPlatformService)
+ *
+ * For **web applications**, use the helper method:
+ * ```typescript
+ * setupSocialLogin(x => {
+ *     x.useBrowserDefaults(); // ✅ Sets up localStorage, window routing, and browser platform
+ *     x.apiUri = "https://api.example.com";
+ *     x.microsoft.clientId = "your-client-id";
+ * });
+ * ```
+ *
+ * For **React Native**, provide custom implementations:
+ * ```typescript
+ * setupSocialLogin(x => {
+ *     x.storageService = new ReactNativeStorageService();
+ *     x.routingService = new ReactNativeRoutingService();
+ *     x.platformService = new ReactNativePlatformService();
+ *     // ... rest of config
+ * });
+ * ```
+ */
 const setupSocialLogin = function (settings) {
     // ✅ Lazy evaluation: only access window when actually needed
     const getDefaultApiUri = () => {
@@ -17,15 +45,17 @@ const setupSocialLogin = function (settings) {
         return '';
     };
     const parameters = {
-        apiUri: getDefaultApiUri(), // ✅ Safe: checks window existence
+        apiUri: getDefaultApiUri(),
         title: null,
         onLoginFailure: (data) => { console.log(data.code); },
         automaticRefresh: false,
-        storageService: new LocalStorageService_1.LocalStorageService(), // Default: localStorage
-        routingService: new WindowRoutingService_1.WindowRoutingService(), // Default: window.location + window.history
+        // ❌ Temporarily undefined - MUST be configured before validation
+        storageService: undefined,
+        routingService: undefined,
+        platformService: undefined,
         platform: {
             type: PlatformType_1.PlatformType.Auto,
-            redirectPath: undefined, // Smart default: will use window.location.origin + "/account/login"
+            redirectPath: undefined,
             loginMode: LoginMode_1.LoginMode.Popup
         },
         google: {},
@@ -38,8 +68,52 @@ const setupSocialLogin = function (settings) {
         instagram: {},
         pinterest: {},
         tiktok: {},
+        // ✅ Helper method for web applications
+        useBrowserDefaults: function () {
+            this.storageService = new LocalStorageService_1.LocalStorageService();
+            this.routingService = new WindowRoutingService_1.WindowRoutingService();
+            this.platformService = new BrowserPlatformService_1.BrowserPlatformService();
+        }
     };
     settings(parameters);
+    // ✅ VALIDATION: Ensure required services are configured
+    const missingServices = [];
+    if (!parameters.storageService) {
+        missingServices.push('storageService (IStorageService)');
+    }
+    if (!parameters.routingService) {
+        missingServices.push('routingService (IRoutingService)');
+    }
+    if (!parameters.platformService) {
+        missingServices.push('platformService (IPlatformService)');
+    }
+    if (missingServices.length > 0) {
+        const errorMessage = `
+🚨 Missing required services in setupSocialLogin():
+
+${missingServices.map(s => `  ❌ ${s}`).join('\n')}
+
+📖 Solutions:
+
+1️⃣  For WEB applications, use the helper method:
+   setupSocialLogin(x => {
+       x.useBrowserDefaults(); // ✅ Auto-configures browser services
+       x.apiUri = "https://api.example.com";
+       x.microsoft.clientId = "your-client-id";
+   });
+
+2️⃣  For REACT NATIVE, provide custom implementations:
+   setupSocialLogin(x => {
+       x.storageService = new ReactNativeStorageService();
+       x.routingService = new ReactNativeRoutingService();
+       x.platformService = new ReactNativePlatformService();
+       // ... rest of config
+   });
+
+📚 Documentation: https://github.com/KeyserDSoze/Rystem/blob/master/src/Authentication/rystem.authentication.social.client/README.md
+        `.trim();
+        throw new Error(errorMessage);
+    }
     // Auto-detect platform if set to 'auto'
     if (!parameters.platform) {
         parameters.platform = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rystem.authentication.social.client",
-  "version": "0.5.0",
+  "version": "0.5.4",
   "author": "Alessandro Rapiti <alessandro.rapiti44@gmail.com>",
   "license": "MIT",
   "description": "Framework-agnostic social authentication library for web and mobile (React, React Native, Next.js, Expo, etc.)",