rn-swiftauth-sdk 1.0.0 → 1.0.2

package/README.md

@@ -2,252 +2,130 @@
 
 A production-ready React Native authentication SDK powered by Firebase. Built with TypeScript, offering both pre-built UI components and headless hooks for complete flexibility.
 
-[![npm version](https://img.shields.io/npm/v/swiftauth-sdk.svg)](https://www.npmjs.com/package/swiftauth-sdk)
+[![npm version](https://img.shields.io/npm/v/rn-swiftauth-sdk.svg)](https://www.npmjs.com/package/rn-swiftauth-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## ✨ Features
+## Features
 
-- 🔐 **Email/Password Authentication** - Built-in validation and error handling
-- 🎨 **Pre-built UI Components** - Beautiful, customizable auth screens out of the box
-- 🎣 **Headless Hooks** - Full control with `useAuth()` for custom implementations
-- 🍎 **Social Login Support** - Google and Apple Sign-In (iOS only for Apple)
-- 💾 **Persistent Sessions** - Configurable session management (local/memory)
-- 🎯 **TypeScript First** - Full type safety and IntelliSense support
-- ⚡ **Zero Configuration** - Works with minimal setup
-- 📱 **Expo & Bare React Native** - Compatible with both workflows
+- **Email/Password Authentication** - Built-in validation and error handling
+- **Pre-built UI Components** - Beautiful, customizable auth screens out of the box
+- **Headless Hooks** - Full control with `useAuth()` for custom implementations
+- **Social Login Support** - Google and Apple Sign-In (iOS only for Apple)
+- **Persistent Sessions** - Configurable session management (local/memory)
+- **TypeScript First** - Full type safety and IntelliSense support
+- **Zero Configuration** - Works with minimal setup
+- **Expo & Bare React Native** - Compatible with both workflows
 
 ---
 
-## 📦 Installation
+## Installation
 
 ### Prerequisites
 
-Ensure your environment meets these requirements:
-- **Node.js**: v18 or higher
-- **React Native**: v0.70+
-- **Expo**: SDK 49+ (Recommended)
+- Node.js v18 or higher
+- React Native v0.70+
+- Expo SDK 49+ (Recommended)
 
-### Step 1: Install the SDK
-
-Since SwiftAuth SDK is currently distributed as a source package, clone and link it locally:
+### Install the SDK
 
 ```bash
-# Clone the repository
-git clone https://github.com/allcodez/Auth-SDK_Stage8
-
-# Navigate to SDK folder
-cd Auth-SDK_Stage8/swiftauth-sdk
-
-# Install dependencies and build
-npm install
-npm run build
+npm install rn-swiftauth-sdk
 ```
 
-### Step 2: Link to Your Project
-
-Navigate to your React Native/Expo project and install the SDK:
-
+For Expo projects:
 ```bash
-cd your-project-folder
-npm install ../path/to/Auth-SDK_Stage8/swiftauth-sdk
+npx expo install rn-swiftauth-sdk
 ```
 
-### Step 3: Install Required Dependencies
-
-SwiftAuth requires these peer dependencies:
+### Install Required Dependencies
 
 ```bash
 npm install firebase @react-native-async-storage/async-storage react-native-safe-area-context
 ```
 
-**For Expo projects:**
+For Expo:
 ```bash
 npx expo install firebase @react-native-async-storage/async-storage react-native-safe-area-context
 ```
 
-**For Google Sign-In (Optional):**
+### Optional: Social Login Dependencies
+
+**Google Sign-In:**
 ```bash
 npm install @react-native-google-signin/google-signin
-# or for Expo
-npx expo install @react-native-google-signin/google-signin
 ```
 
-**For Apple Sign-In (Optional, iOS only):**
+**Apple Sign-In (iOS only):**
 ```bash
 npm install @invertase/react-native-apple-authentication
-# or for Expo
-npx expo install @invertase/react-native-apple-authentication
 ```
 
-### Step 4: Metro Configuration (Important)
+### Bare React Native Only
 
-Update your `metro.config.js` to resolve the SDK properly:
-
-```javascript
-const { getDefaultConfig } = require('expo/metro-config');
-const path = require('path');
-
-const projectRoot = __dirname;
-const workspaceRoot = path.resolve(projectRoot, '../');
-
-const config = getDefaultConfig(projectRoot);
-
-config.watchFolders = [workspaceRoot];
-config.resolver.nodeModulesPaths = [
-  path.resolve(projectRoot, 'node_modules'),
-  path.resolve(workspaceRoot, 'node_modules'),
-];
-
-module.exports = config;
+Install iOS CocoaPods:
+```bash
+cd ios && pod install && cd ..
 ```
 
-### ⚠️ Troubleshooting "Duplicate React"
-
-If you encounter an "Invalid Hook Call" error:
-
-1. Build the SDK: `npm run build`
-2. Delete SDK's `node_modules`: `rm -rf node_modules` inside `swiftauth-sdk`
-3. Clear cache and restart: `npx expo start -c`
-
 ---
 
-## 🔧 Firebase Setup
+## Firebase Setup
 
 ### 1. Create Firebase Project
 
-1. Go to [Firebase Console](https://console.firebase.google.com/)
+1. Go to [Firebase Console](https://console.firebase.google.com)
 2. Create a new project or select existing one
-3. Register a **Web App** (click the `</>` icon)
+3. Register a Web App (click the `</>` icon)
 4. Copy the `firebaseConfig` object
 
 ### 2. Enable Authentication Methods
 
-1. Go to **Authentication** > **Sign-in method**
+1. Navigate to **Authentication > Sign-in method**
 2. Enable **Email/Password**
 3. (Optional) Enable **Google** and/or **Apple** for social login
 
 ### 3. Platform-Specific Configuration
 
-#### Android Setup
-
-1. In Firebase Console, register an **Android app**
-2. Download `google-services.json`
-3. Place it in your project: `android/app/google-services.json`
-
-**Update `android/build.gradle`:**
-```gradle
-buildscript {
-  dependencies {
-    // Add this line
-    classpath 'com.google.gms:google-services:4.3.15'
-  }
-}
-```
-
-**Update `android/app/build.gradle`:**
-```gradle
-apply plugin: 'com.android.application'
-// Add this line at the bottom
-apply plugin: 'com.google.gms.google-services'
-```
-
-**Update `app.json` for Expo:**
-```json
-{
-  "expo": {
-    "android": {
-      "googleServicesFile": "./google-services.json",
-      "package": "com.yourcompany.yourapp"
-    }
-  }
-}
-```
-
-#### iOS Setup
-
-1. In Firebase Console, register an **iOS app**
-2. Download `GoogleService-Info.plist`
-3. Place it in your project: `ios/YourAppName/GoogleService-Info.plist`
-
-**For Bare React Native:**
-- Drag `GoogleService-Info.plist` into your Xcode project
-
-**Update `app.json` for Expo:**
-```json
-{
-  "expo": {
-    "ios": {
-      "googleServicesFile": "./GoogleService-Info.plist",
-      "bundleIdentifier": "com.yourcompany.yourapp"
-    }
-  }
-}
-```
-
-**Install CocoaPods (iOS only):**
-```bash
-cd ios
-pod install
-cd ..
-```
-
-### 4. Google Sign-In Configuration (Optional)
-
-#### Get Google Client IDs
-
-1. Go to [Google Cloud Console](https://console.cloud.google.com/)
-2. Select your Firebase project
-3. Go to **APIs & Services** > **Credentials**
-4. You'll need:
-   - **Web Client ID** (for all platforms)
-   - **iOS Client ID** (optional, iOS-specific)
-
-**Update `app.json` for Google Sign-In:**
-```json
-{
-  "expo": {
-    "ios": {
-      "bundleIdentifier": "com.yourcompany.yourapp",
-      "googleServicesFile": "./GoogleService-Info.plist"
-    },
-    "android": {
-      "package": "com.yourcompany.yourapp",
-      "googleServicesFile": "./google-services.json"
+**Android:**
+- Register an Android app in Firebase Console
+- Download `google-services.json` and place in `android/app/`
+- Add to `android/build.gradle`:
+  ```gradle
+  classpath 'com.google.gms:google-services:4.3.15'
+  ```
+- Add to `android/app/build.gradle`:
+  ```gradle
+  apply plugin: 'com.google.gms.google-services'
+  ```
+
+**iOS:**
+- Register an iOS app in Firebase Console
+- Download `GoogleService-Info.plist` and place in project root (Expo) or `ios/YourAppName/` (Bare)
+- Update `app.json`:
+  ```json
+  {
+    "expo": {
+      "ios": {
+        "googleServicesFile": "./GoogleService-Info.plist",
+        "bundleIdentifier": "com.yourcompany.yourapp"
+      }
     }
   }
-}
-```
-
-### 5. Apple Sign-In Configuration (Optional, iOS only)
+  ```
 
-1. Go to your [Apple Developer Account](https://developer.apple.com/)
-2. Enable **Sign in with Apple** capability
-3. Add the capability in Xcode: **Signing & Capabilities** > **+ Capability** > **Sign in with Apple**
-
-**Update `app.json`:**
-```json
-{
-  "expo": {
-    "ios": {
-      "usesAppleSignIn": true
-    }
-  }
-}
-```
+For detailed Firebase setup instructions, see the [Firebase documentation](https://firebase.google.com/docs/ios/setup).
 
 ---
 
-## 🚀 Quick Start
+## Quick Start
 
-### Basic Setup (Email Authentication)
+### Basic Email Authentication
 
-```tsx
-// App.tsx
+```typescript
 import React from 'react';
 import { SafeAreaProvider } from 'react-native-safe-area-context';
-import { AuthProvider, AuthScreen, useAuth } from 'swiftauth-sdk';
+import { AuthProvider, AuthScreen, useAuth } from 'rn-swiftauth-sdk';
 
-// Your Firebase configuration
 const firebaseConfig = {
   apiKey: "AIzaSyD-Your-Actual-Key",
   authDomain: "your-project.firebaseapp.com",
@@ -259,12 +137,7 @@ const firebaseConfig = {
 
 const MainNavigation = () => {
   const { user } = useAuth();
-
-  if (!user) {
-    return <AuthScreen />;
-  }
-
-  return <HomeScreen user={user} />;
+  return user ? <HomeScreen user={user} /> : <AuthScreen />;
 };
 
 export default function App() {
@@ -280,11 +153,14 @@ export default function App() {
 
 ### With Social Login
 
-```tsx
+```typescript
 const firebaseConfig = {
   apiKey: "AIzaSyD-Your-Actual-Key",
   authDomain: "your-project.firebaseapp.com",
   projectId: "your-project-id",
+  storageBucket: "your-project.appspot.com",
+  messagingSenderId: "123456789",
+  appId: "1:123456789:web:abcdef",
   
   // Enable social login
   enableGoogle: true,
@@ -297,44 +173,16 @@ const firebaseConfig = {
 
 ---
 
-## 📚 API Reference
+## API Reference
 
 ### `<AuthProvider>`
 
 Wraps your app and provides authentication context.
 
-**Props:**
-
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
-| `config` | `AuthConfig` | Yes | Firebase configuration object |
-| `children` | `ReactNode` | Yes | Your app components |
-
-**AuthConfig Interface:**
-
-```typescript
-interface AuthConfig {
-  // Firebase credentials (Required)
-  apiKey: string;
-  authDomain: string;
-  projectId: string;
-  storageBucket?: string;
-  messagingSenderId?: string;
-  appId?: string;
-  
-  // Session persistence
-  persistence?: 'local' | 'memory'; // Default: 'local'
-  
-  // Feature flags
-  enableEmail?: boolean;      // Default: true
-  enableGoogle?: boolean;     // Default: false
-  enableApple?: boolean;      // Default: false (iOS only)
-  
-  // Google Sign-In
-  googleWebClientId?: string;
-  googleIosClientId?: string;
-}
-```
+| config | AuthConfig | Yes | Firebase configuration object |
+| children | ReactNode | Yes | Your app components |
 
 ### `useAuth()` Hook
 
@@ -342,63 +190,33 @@ Access authentication state and methods.
 
 ```typescript
 const {
-  user,           // Current user object or null
-  status,         // 'AUTHENTICATED' | 'UNAUTHENTICATED' | 'LOADING'
-  error,          // Last error object or null
-  signInWithEmail,
-  signUpWithEmail,
-  signOut,
-  clearError
+  user,              // Current user object or null
+  status,            // AuthStatus enum
+  error,             // Last error object or null
+  isLoading,         // Boolean loading state
+  signInWithEmail,   // Sign in method
+  signUpWithEmail,   // Sign up method
+  signOut,           // Sign out method
+  clearError         // Clear error state
 } = useAuth();
 ```
 
-**Methods:**
+#### Available Methods
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `signInWithEmail` | `(email: string, password: string) => Promise<void>` | Sign in existing user |
-| `signUpWithEmail` | `(email: string, password: string) => Promise<void>` | Create new account |
+| `signInWithEmail` | `(options: {email, password}) => Promise<void>` | Sign in existing user |
+| `signUpWithEmail` | `(options: {email, password}) => Promise<void>` | Create new account |
 | `signOut` | `() => Promise<void>` | Log out current user |
 | `clearError` | `() => void` | Clear error state |
 
-### `<AuthScreen>` Component
-
-Pre-built authentication UI with login and signup.
-
-**Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `styles` | `AuthScreenStyles` | `undefined` | Custom styles object |
-| `titles` | `object` | `undefined` | Custom text labels |
-| `showPasswordHints` | `boolean` | `true` | Show password requirements |
-
-**Example:**
-
-```tsx
-<AuthScreen 
-  titles={{
-    loginTitle: "Welcome Back",
-    loginSubtitle: "Sign in to continue",
-    signupTitle: "Create Account",
-    signupSubtitle: "Join us today"
-  }}
-  styles={{
-    container: { backgroundColor: '#f5f5f5' },
-    button: { backgroundColor: '#007AFF' },
-    buttonText: { color: '#ffffff' }
-  }}
-  showPasswordHints={true}
-/>
-```
-
 ---
 
-## 🎨 Customization Examples
+## Customization
 
-### Dark Mode Theme
+### Dark Mode Theme Example
 
-```tsx
+```typescript
 <AuthScreen 
   styles={{
     container: { backgroundColor: '#1a1a1a' },
@@ -415,100 +233,83 @@ Pre-built authentication UI with login and signup.
 />
 ```
 
-### Custom UI (Headless)
-
-Build your own interface using the `useAuth()` hook:
+---
 
-```tsx
-import { useState } from 'react';
-import { View, TextInput, Button, Text } from 'react-native';
-import { useAuth } from 'swiftauth-sdk';
+## Error Handling
 
-export const CustomLoginScreen = () => {
-  const { signInWithEmail, error } = useAuth();
-  const [email, setEmail] = useState('');
-  const [password, setPassword] = useState('');
+SwiftAuth maps Firebase errors to user-friendly messages:
 
-  const handleLogin = async () => {
-    try {
-      await signInWithEmail(email, password);
-    } catch (err) {
-      console.error('Login failed:', err);
-    }
-  };
+| Error Code | User Message |
+|------------|--------------|
+| `auth/invalid-credentials` | "Invalid email or password." |
+| `auth/user-not-found` | "Invalid email or password." |
+| `auth/email-already-in-use` | "This email is already registered." |
+| `auth/weak-password` | "Password is too weak." |
+| `auth/network-request-failed` | "Network error. Please check your connection." |
 
-  return (
-    <View style={{ padding: 20 }}>
-      <Text style={{ fontSize: 24, marginBottom: 20 }}>Login</Text>
-      
-      {error && <Text style={{ color: 'red' }}>{error.message}</Text>}
-      
-      <TextInput 
-        placeholder="Email"
-        value={email}
-        onChangeText={setEmail}
-        style={{ borderWidth: 1, padding: 10, marginBottom: 10 }}
-      />
-      
-      <TextInput 
-        placeholder="Password"
-        value={password}
-        onChangeText={setPassword}
-        secureTextEntry
-        style={{ borderWidth: 1, padding: 10, marginBottom: 20 }}
-      />
-      
-      <Button title="Sign In" onPress={handleLogin} />
-    </View>
-  );
-};
-```
+### Basic Usage
 
----
+```typescript
+const { error } = useAuth();
 
-## ⚠️ Error Handling
+if (error) {
+  return <Text style={{ color: 'red' }}>{error.message}</Text>;
+}
+```
 
-SwiftAuth maps Firebase errors to user-friendly codes:
+### Advanced: Raw Firebase Errors
 
-| Error Code | Meaning | User Message |
-|------------|---------|--------------|
-| `auth/invalid-credentials` | Wrong email/password | "Invalid email or password." |
-| `auth/user-not-found` | Account doesn't exist | "Invalid email or password." |
-| `auth/email-already-in-use` | Email already registered | "This email is already registered." |
-| `auth/weak-password` | Password too weak | "Password is too weak." |
-| `auth/network-request-failed` | No internet connection | "Network error. Please check your connection." |
-| `auth/invalid-email` | Invalid email format | "Invalid email address." |
-| `auth/configuration-error` | Missing API keys | "Authentication is not configured correctly." |
+For custom UI implementations, access raw Firebase errors:
 
-**Usage:**
+**Method 1: Try/Catch Block**
+```typescript
+const { signInWithEmail } = useAuth();
+
+const handleLogin = async () => {
+  try {
+    await signInWithEmail({ email, password });
+  } catch (rawError: any) {
+    if (rawError.code === 'auth/requires-recent-login') {
+      showReauthModal();
+    } else if (rawError.code === 'auth/quota-exceeded') {
+      Alert.alert("System Overload", "Please try again later.");
+    }
+  }
+};
+```
 
-```tsx
+**Method 2: Global State**
+```typescript
 const { error } = useAuth();
 
-if (error) {
-  if (error.code === 'auth/network-request-failed') {
-    return <OfflineBanner />;
+useEffect(() => {
+  if (error?.originalError) {
+    const rawCode = (error.originalError as any).code;
+    console.log("Raw Firebase Code:", rawCode);
+    
+    if (rawCode === 'auth/invalid-email') {
+      setLocalizedMessage(t('errors.bad_email'));
+    }
   }
-  return <Text style={{ color: 'red' }}>{error.message}</Text>;
-}
+}, [error]);
 ```
 
 ---
 
-## 🔐 Session Management
+## Session Management
 
 ### Keep User Logged In (Default)
 
-```tsx
+```typescript
 const config = {
   ...firebaseConfig,
   persistence: 'local' // User stays logged in
 };
 ```
 
-### Banking App Mode
+### Memory-Only Session
 
-```tsx
+```typescript
 const config = {
   ...firebaseConfig,
   persistence: 'memory' // User logged out when app closes
@@ -517,58 +318,107 @@ const config = {
 
 ---
 
-## 🧪 Testing
+## Backend Integration
 
-Run the example app to test the SDK:
+The SDK exposes a secure Firebase ID Token (`user.token`) for backend authentication.
 
-```bash
-cd swiftauth-example
-npm install
-npx expo start
+### Frontend: Sending the Token
+
+```typescript
+import { useAuth } from 'rn-swiftauth-sdk';
+
+const UserProfile = () => {
+  const { user } = useAuth();
+
+  const fetchPrivateData = async () => {
+    if (!user?.token) return;
+
+    try {
+      const response = await fetch('https://your-api.com/profile', {
+        method: 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${user.token}`
+        }
+      });
+      
+      const data = await response.json();
+      console.log(data);
+    } catch (error) {
+      console.error('Request failed:', error);
+    }
+  };
+
+  return <Button title="Get Profile" onPress={fetchPrivateData} />;
+};
 ```
 
----
+### Backend: Verifying the Token (Node.js)
 
-## 📖 Full Documentation
+```javascript
+const admin = require('firebase-admin');
 
-- [Installation Guide](./docs/installation.md)
-- [Getting Started](./docs/getting-started.md)
-- [API Reference](./docs/api-reference.md)
-- [Usage Examples](./docs/usage-examples.md)
-- [Error Codes](./docs/error-codes.md)
+// Middleware to verify Firebase ID token
+const verifyToken = async (req, res, next) => {
+  const authHeader = req.headers.authorization;
+  
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return res.status(401).send('Unauthorized');
+  }
+
+  const idToken = authHeader.split('Bearer ')[1];
+  
+  try {
+    const decodedToken = await admin.auth().verifyIdToken(idToken);
+    req.user = decodedToken;
+    next();
+  } catch (error) {
+    res.status(403).send('Invalid Token');
+  }
+};
+
+// Protected route example
+app.get('/profile', verifyToken, (req, res) => {
+  res.json({ userId: req.user.uid, email: req.user.email });
+});
+```
 
 ---
 
-## 🤝 Contributing
+## Example App
 
-We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+Check out our example implementation:
 
----
+```bash
+# Clone the repository
+git clone https://github.com/allcodez/Auth-SDK_Stage8
 
-## 📄 License
+# Navigate to example app
+cd Auth-SDK_Stage8/swiftauth-example
 
-MIT License - see [LICENSE](./LICENSE) file for details.
+# Install dependencies
+npm install
+
+# Start the app
+npx expo start
+```
 
 ---
 
-## 🆘 Support
+## Contributing
 
-- 📧 Email: support@swiftauth.dev
-- 🐛 Issues: [GitHub Issues](https://github.com/allcodez/Auth-SDK_Stage8/issues)
-- 💬 Discussions: [GitHub Discussions](https://github.com/allcodez/Auth-SDK_Stage8/discussions)
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ---
 
-## 🎯 Roadmap
+## License
 
-- [ ] Password reset functionality
-- [ ] Email verification
-- [ ] Phone authentication
-- [ ] Multi-factor authentication (MFA)
-- [ ] Biometric authentication
-- [ ] Session refresh tokens
-- [ ] NPM package distribution
+MIT License - see [LICENSE](LICENSE) file for details.
 
 ---
 
-Made with ❤️ by the SwiftAuth Team
+## Support
+
+- **Issues:** [GitHub Issues](https://github.com/allcodez/Auth-SDK_Stage8/issues)
+- **NPM Package:** [rn-swiftauth-sdk](https://www.npmjs.com/package/rn-swiftauth-sdk)
+- **Documentation:** [Full Docs](https://github.com/allcodez/Auth-SDK_Stage8)