@umituz/react-native-auth 3.4.30 → 3.4.32

package/src/presentation/hooks/useProfileUpdate.md

@@ -0,0 +1,327 @@
+# useProfileUpdate & useProfileEdit
+
+Hooks for profile update operations and profile editing form management.
+
+---
+
+## useProfileUpdate
+
+Hook for profile update operations. Implementation should be provided by the app using Firebase SDK or backend API.
+
+### Usage
+
+```typescript
+import { useProfileUpdate } from '@umituz/react-native-auth';
+
+function ProfileSettings() {
+  const { updateProfile, isUpdating, error } = useProfileUpdate();
+
+  const handleUpdate = async (data: UpdateProfileParams) => {
+    try {
+      await updateProfile(data);
+    } catch (err) {
+      console.error(err);
+    }
+  };
+
+  return <ProfileForm onSave={handleUpdate} />;
+}
+```
+
+### API
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `updateProfile` | `(params: UpdateProfileParams) => Promise<void>` | Profile update function |
+| `isUpdating` | `boolean` | Update in progress |
+| `error` | `string \| null` | Error message |
+
+### Create Your Own Implementation
+
+```typescript
+function useProfileUpdate() {
+  const { user } = useAuth();
+  const [isUpdating, setIsUpdating] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const updateProfile = async (params: UpdateProfileParams) => {
+    if (!user) {
+      throw new Error("No user logged in");
+    }
+
+    if (user.isAnonymous) {
+      throw new Error("Anonymous users cannot update profile");
+    }
+
+    setIsUpdating(true);
+    setError(null);
+
+    try {
+      // Update profile in Firebase Auth
+      await updateProfile(user, {
+        displayName: params.displayName,
+        photoURL: params.photoURL,
+      });
+
+      // Update user document in Firestore
+      await updateDoc(doc(db, 'users', user.uid), {
+        displayName: params.displayName,
+        photoURL: params.photoURL,
+        updatedAt: serverTimestamp(),
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Update failed';
+      setError(message);
+      throw err;
+    } finally {
+      setIsUpdating(false);
+    }
+  };
+
+  return { updateProfile, isUpdating, error };
+}
+```
+
+---
+
+## useProfileEdit
+
+Hook for simple profile editing with form state management.
+
+### Usage
+
+```typescript
+import { useProfileEdit } from '@umituz/react-native-auth';
+
+function EditProfileScreen({ navigation }) {
+  const {
+    formState,
+    setDisplayName,
+    setEmail,
+    setPhotoURL,
+    resetForm,
+    validateForm,
+  } = useProfileEdit({
+    displayName: user?.displayName || '',
+    email: user?.email || '',
+    photoURL: user?.photoURL || null,
+  });
+
+  const handleSave = () => {
+    const { isValid, errors } = validateForm();
+
+    if (!isValid) {
+      Alert.alert('Error', errors.join('\n'));
+      return;
+    }
+
+    updateProfile({
+      displayName: formState.displayName,
+      photoURL: formState.photoURL,
+    });
+
+    navigation.goBack();
+  };
+
+  return (
+    <ScrollView>
+      <TextInput
+        value={formState.displayName}
+        onChangeText={setDisplayName}
+        placeholder="Full Name"
+      />
+
+      <TextInput
+        value={formState.email}
+        onChangeText={setEmail}
+        placeholder="Email"
+        editable={false}
+      />
+
+      <AvatarUploader
+        photoURL={formState.photoURL}
+        onImageSelected={setPhotoURL}
+      />
+
+      <View style={styles.buttons}>
+        <Button onPress={navigation.goBack}>Cancel</Button>
+        <Button
+          onPress={handleSave}
+          disabled={!formState.isModified}
+        >
+          Save
+        </Button>
+      </View>
+    </ScrollView>
+  );
+}
+```
+
+### API
+
+#### Return Value
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `formState` | `ProfileEditFormState` | Form state |
+| `setDisplayName` | `(value: string) => void` | Set display name |
+| `setEmail` | `(value: string) => void` | Set email |
+| `setPhotoURL` | `(value: string \| null) => void` | Set photo URL |
+| `resetForm` | `(initial: Partial<ProfileEditFormState>) => void` | Reset form |
+| `validateForm` | `() => { isValid: boolean; errors: string[] }` | Validate form |
+
+#### ProfileEditFormState
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `displayName` | `string` | Display name |
+| `email` | `string` | Email |
+| `photoURL` | `string \| null` | Photo URL |
+| `isModified` | `boolean` | Form has been modified |
+
+### Validation
+
+`validateForm()` checks:
+
+- **Display name**: Cannot be empty
+- **Email**: Valid email format (if provided)
+
+```typescript
+const { isValid, errors } = validateForm();
+
+if (!isValid) {
+  errors.forEach(error => console.log(error));
+  // ["Display name is required", "Invalid email format"]
+}
+```
+
+## Examples
+
+### Profile Photo Upload
+
+```typescript
+function ProfilePhotoSection() {
+  const { formState, setPhotoURL } = useProfileEdit(initialState);
+
+  const handlePickImage = async () => {
+    const result = await launchImageLibrary({
+      mediaType: 'photo',
+      quality: 0.8,
+    });
+
+    if (result.assets?.[0]) {
+      // Upload to storage and get URL
+      const url = await uploadToStorage(result.assets[0].uri);
+      setPhotoURL(url);
+    }
+  };
+
+  return (
+    <TouchableOpacity onPress={handlePickImage}>
+      {formState.photoURL ? (
+        <Image source={{ uri: formState.photoURL }} />
+      ) : (
+        <View style={styles.placeholder}>
+          <Text>Select Photo</Text>
+        </View>
+      )}
+    </TouchableOpacity>
+  );
+}
+```
+
+### Unsaved Changes Warning
+
+```typescript
+function EditProfileScreen({ navigation }) {
+  const {
+    formState,
+    resetForm,
+    validateForm
+  } = useProfileEdit(initialState);
+
+  useEffect(() => {
+    const unsubscribe = navigation.addListener('beforeRemove', (e) => {
+      if (!formState.isModified) {
+        return;
+      }
+
+      e.preventDefault();
+
+      Alert.alert(
+        'Unsaved Changes',
+        'You have unsaved changes. What would you like to do?',
+        [
+          { text: 'Don\'t Save', style: 'cancel' },
+          {
+            text: 'Save',
+            onPress: () => {
+              saveChanges();
+              navigation.dispatch(e.data.action);
+            }
+          },
+          {
+            text: 'Discard',
+            style: 'destructive',
+            onPress: () => {
+              resetForm(initialState);
+              navigation.dispatch(e.data.action);
+            }
+          },
+        ]
+      );
+    });
+
+    return unsubscribe;
+  }, [navigation, formState.isModified]);
+
+  // ...
+}
+```
+
+### Custom Validation
+
+```typescript
+function ExtendedProfileEdit() {
+  const {
+    formState,
+    setDisplayName,
+    setEmail,
+    setPhotoURL,
+    validateForm
+  } = useProfileEdit(initialState);
+
+  const handleSave = () => {
+    // Base validation
+    const { isValid, errors } = validateForm();
+
+    // Custom validation
+    const customErrors = [];
+
+    if (formState.displayName.length < 3) {
+      customErrors.push('Display name must be at least 3 characters');
+    }
+
+    if (formState.photoURL && !isValidImageUrl(formState.photoURL)) {
+      customErrors.push('Invalid image URL');
+    }
+
+    const allErrors = [...errors, ...customErrors];
+
+    if (allErrors.length > 0) {
+      Alert.alert('Error', allErrors.join('\n'));
+      return;
+    }
+
+    saveProfile();
+  };
+
+  // ...
+}
+```
+
+## Related Hooks
+
+- [`useUserProfile`](./useUserProfile.md) - Display profile data
+- [`useAuth`](./useAuth.md) - Main auth state management
+- [`useAccountManagement`](./useAccountManagement.md) - Account operations

package/src/presentation/hooks/useSocialLogin.md

@@ -0,0 +1,356 @@
+# Social Login Hooks
+
+Hooks for Google and Apple social authentication.
+
+---
+
+## useSocialLogin
+
+General social login functionality. Wraps `@umituz/react-native-firebase`'s `useSocialAuth`.
+
+### Usage
+
+```typescript
+import { useSocialLogin } from '@umituz/react-native-auth';
+
+function LoginScreen() {
+  const {
+    signInWithGoogle,
+    signInWithApple,
+    googleLoading,
+    appleLoading,
+    googleConfigured,
+    appleAvailable,
+  } = useSocialLogin({
+    google: {
+      webClientId: 'your-web-client-id',
+      iosClientId: 'your-ios-client-id',
+    },
+    apple: { enabled: true },
+  });
+
+  return (
+    <View>
+      <Button onPress={signInWithGoogle} disabled={googleLoading || !googleConfigured}>
+        {googleLoading ? 'Signing in...' : 'Sign in with Google'}
+      </Button>
+
+      <Button onPress={signInWithApple} disabled={appleLoading || !appleAvailable}>
+        {appleLoading ? 'Signing in...' : 'Sign in with Apple'}
+      </Button>
+    </View>
+  );
+}
+```
+
+### API
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `signInWithGoogle` | `() => Promise<SocialAuthResult>` | Google sign-in (use `useGoogleAuth` for OAuth) |
+| `signInWithApple` | `() => Promise<SocialAuthResult>` | Apple sign-in |
+| `googleLoading` | `boolean` | Google loading state |
+| `appleLoading` | `boolean` | Apple loading state |
+| `googleConfigured` | `boolean` | Google is configured |
+| `appleAvailable` | `boolean` | Apple is available (iOS only) |
+
+---
+
+## useGoogleAuth
+
+Handles complete Google OAuth flow with `expo-auth-session`.
+
+### Usage
+
+```typescript
+import { useGoogleAuth } from '@umituz/react-native-auth';
+
+function LoginScreen() {
+  const { signInWithGoogle, googleLoading, googleConfigured } = useGoogleAuth({
+    iosClientId: 'your-ios-client-id.apps.googleusercontent.com',
+    webClientId: 'your-web-client-id.apps.googleusercontent.com',
+  });
+
+  const handleGoogleSignIn = async () => {
+    const result = await signInWithGoogle();
+
+    if (result.success) {
+      console.log('Google sign-in successful');
+    } else {
+      Alert.alert('Error', result.error || 'Sign-in failed');
+    }
+  };
+
+  return (
+    <Button onPress={handleGoogleSignIn} disabled={googleLoading || !googleConfigured}>
+      Sign in with Google
+    </Button>
+  );
+}
+```
+
+### API
+
+#### Parameters
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `iosClientId` | `string` | No* | iOS Google Client ID |
+| `webClientId` | `string` | No* | Web Google Client ID |
+| `androidClientId` | `string` | No* | Android Google Client ID |
+
+*At least one must be provided
+
+#### Return Value
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `signInWithGoogle` | `() => Promise<SocialAuthResult>` | Google sign-in function |
+| `googleLoading` | `boolean` | Loading state |
+| `googleConfigured` | `boolean` | Is configured |
+
+### Examples
+
+#### Google Sign-In Screen
+
+```typescript
+function SocialLoginScreen() {
+  const { signInWithGoogle, googleLoading } = useGoogleAuth({
+    iosClientId: Config.GOOGLE_IOS_CLIENT_ID,
+    webClientId: Config.GOOGLE_WEB_CLIENT_ID,
+  });
+
+  const { signInWithApple, appleLoading, appleAvailable } = useAppleAuth();
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Sign In</Text>
+
+      <TouchableOpacity
+        style={styles.googleButton}
+        onPress={signInWithGoogle}
+        disabled={googleLoading}
+      >
+        {googleLoading ? (
+          <ActivityIndicator />
+        ) : (
+          <>
+            <GoogleIcon />
+            <Text>Continue with Google</Text>
+          </>
+        )}
+      </TouchableOpacity>
+
+      {Platform.OS === 'ios' && appleAvailable && (
+        <TouchableOpacity
+          style={styles.appleButton}
+          onPress={signInWithApple}
+          disabled={appleLoading}
+        >
+          {appleLoading ? (
+            <ActivityIndicator />
+          ) : (
+            <>
+              <AppleIcon />
+              <Text>Continue with Apple</Text>
+            </>
+          )}
+        </TouchableOpacity>
+      )}
+    </View>
+  );
+}
+```
+
+#### Error Handling
+
+```typescript
+function LoginWithErrorHandling() {
+  const { signInWithGoogle, googleLoading } = useGoogleAuth({
+    webClientId: Config.GOOGLE_WEB_CLIENT_ID,
+  });
+
+  const handleGoogleSignIn = async () => {
+    try {
+      const result = await signInWithGoogle();
+
+      if (result.success) {
+        navigation.navigate('Home');
+      } else {
+        // User cancelled or error
+        if (result.error?.includes('cancelled')) {
+          return; // Silent cancel
+        }
+        Alert.alert('Error', result.error || 'Google sign-in failed');
+      }
+    } catch (error) {
+      Alert.alert('Error', 'An unexpected error occurred');
+    }
+  };
+
+  return <Button onPress={handleGoogleSignIn} />;
+}
+```
+
+---
+
+## useAppleAuth
+
+Convenience wrapper for Apple Sign-In.
+
+### Usage
+
+```typescript
+import { useAppleAuth } from '@umituz/react-native-auth';
+import { Platform } from 'react-native';
+
+function LoginScreen() {
+  const { signInWithApple, appleLoading, appleAvailable } = useAppleAuth();
+
+  if (Platform.OS !== 'ios' || !appleAvailable) {
+    return null;
+  }
+
+  return (
+    <TouchableOpacity
+      onPress={signInWithApple}
+      disabled={appleLoading}
+      style={styles.appleButton}
+    >
+      {appleLoading ? (
+        <ActivityIndicator />
+      ) : (
+        <>
+          <AppleIcon />
+          <Text>Sign in with Apple</Text>
+        </>
+      )}
+    </TouchableOpacity>
+  );
+}
+```
+
+### API
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `signInWithApple` | `() => Promise<SocialAuthResult>` | Apple sign-in function |
+| `appleLoading` | `boolean` | Loading state |
+| `appleAvailable` | `boolean` | Apple Sign-In is available (iOS only) |
+
+### Platform-Specific Button
+
+```typescript
+function SocialLoginButtons() {
+  const { signInWithApple, appleLoading, appleAvailable } = useAppleAuth();
+  const { signInWithGoogle, googleLoading } = useGoogleAuth({
+    webClientId: Config.GOOGLE_WEB_CLIENT_ID,
+  });
+
+  return (
+    <View>
+      {/* Google - all platforms */}
+      <SocialButton
+        provider="google"
+        onPress={signInWithGoogle}
+        loading={googleLoading}
+      />
+
+      {/* Apple - iOS only */}
+      {Platform.OS === 'ios' && appleAvailable && (
+        <SocialButton
+          provider="apple"
+          onPress={signInWithApple}
+          loading={appleLoading}
+        />
+      )}
+    </View>
+  );
+}
+```
+
+### Apple Sign-In with Error Handling
+
+```typescript
+function AppleLoginButton() {
+  const { signInWithApple, appleLoading, appleAvailable } = useAppleAuth();
+
+  const handleAppleSignIn = async () => {
+    const result = await signInWithApple();
+
+    if (result.success) {
+      console.log('Apple sign-in successful');
+    } else {
+      // Handle error
+      if (result.error?.includes('cancelled')) {
+        console.log('User cancelled');
+      } else {
+        Alert.alert('Error', result.error || 'Apple sign-in failed');
+      }
+    }
+  };
+
+  if (!appleAvailable) {
+    return null;
+  }
+
+  return (
+    <TouchableOpacity onPress={handleAppleSignIn} disabled={appleLoading}>
+      <Text>Sign in with Apple</Text>
+    </TouchableOpacity>
+  );
+}
+```
+
+## SocialAuthResult
+
+All social login functions return the same type:
+
+```typescript
+interface SocialAuthResult {
+  success: boolean;
+  error?: string;
+  user?: AuthUser;
+}
+```
+
+## Configuration
+
+### Get Google Client ID
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select existing
+3. Navigate to "APIs & Services" > "Credentials"
+4. Create "OAuth 2.0 Client IDs":
+   - **iOS**: For your iOS app
+   - **Android**: For your Android app
+   - **Web**: For Expo/web
+
+### Configure Apple Sign-In
+
+1. Go to [Apple Developer](https://developer.apple.com/)
+2. Navigate to "Certificates, Identifiers & Profiles" > "Identifiers"
+3. Select your App ID and enable "Sign In with Apple"
+4. Enable Apple Sign-In in Firebase Console
+
+## Important Notes
+
+### Google
+- Requires `expo-web-browser` setup
+- `WebBrowser.maybeCompleteAuthSession()` must be called in app root
+- At least one client ID must be provided
+
+### Apple
+- Only available on iOS
+- Requires `expo-apple-authentication` setup
+- Requires Apple Developer account
+- Testing requires a physical device (may not work in simulator)
+
+## Related Hooks
+
+- [`useAuth`](./useAuth.md) - Main auth state management
+- [`useSocialLogin`](#usesociallogin) - General social login
+
+## Related Components
+
+- [`SocialLoginButtons`](../components/SocialLoginButtons.md) - Social login button component