@shaykec/app-agent 1.0.5 → 1.0.6

package/templates/shared/ios/FirebaseBackend/FirestoreService.swift

@@ -0,0 +1,206 @@
+import Foundation
+import FirebaseFirestore
+import FirebaseFirestoreSwift
+
+/// Generic Firestore CRUD service with real-time listeners.
+/// Supports Codable models and provides async/await APIs.
+class FirestoreService {
+    static let shared = FirestoreService()
+    
+    private let db = Firestore.firestore()
+    
+    private init() {}
+    
+    // MARK: - Fetch Collection
+    
+    /// Fetch all documents from a collection.
+    /// - Parameter collection: Collection name
+    /// - Returns: Array of decoded models
+    func fetchCollection<T: Codable>(_ collection: String) async throws -> [T] {
+        let snapshot = try await db.collection(collection).getDocuments()
+        return try snapshot.documents.compactMap { document in
+            try document.data(as: T.self)
+        }
+    }
+    
+    /// Fetch documents with a query filter.
+    /// - Parameters:
+    ///   - collection: Collection name
+    ///   - field: Field to filter on
+    ///   - value: Value to match
+    /// - Returns: Array of decoded models
+    func fetchCollection<T: Codable>(_ collection: String, whereField field: String, isEqualTo value: Any) async throws -> [T] {
+        let snapshot = try await db.collection(collection)
+            .whereField(field, isEqualTo: value)
+            .getDocuments()
+        return try snapshot.documents.compactMap { document in
+            try document.data(as: T.self)
+        }
+    }
+    
+    // MARK: - Fetch Document
+    
+    /// Fetch a single document by ID.
+    /// - Parameters:
+    ///   - collection: Collection name
+    ///   - id: Document ID
+    /// - Returns: Decoded model
+    func fetchDocument<T: Codable>(_ collection: String, id: String) async throws -> T {
+        let document = try await db.collection(collection).document(id).getDocument()
+        return try document.data(as: T.self)
+    }
+    
+    // MARK: - Create
+    
+    /// Create a new document with auto-generated ID.
+    /// - Parameters:
+    ///   - collection: Collection name
+    ///   - data: Encodable model
+    /// - Returns: Generated document ID
+    func create<T: Encodable>(_ collection: String, data: T) async throws -> String {
+        let documentRef = try db.collection(collection).addDocument(from: data)
+        return documentRef.documentID
+    }
+    
+    /// Create a document with a specific ID.
+    /// - Parameters:
+    ///   - collection: Collection name
+    ///   - id: Document ID
+    ///   - data: Encodable model
+    func create<T: Encodable>(_ collection: String, id: String, data: T) async throws {
+        try db.collection(collection).document(id).setData(from: data)
+    }
+    
+    // MARK: - Update
+    
+    /// Update specific fields in a document.
+    /// - Parameters:
+    ///   - collection: Collection name
+    ///   - id: Document ID
+    ///   - fields: Dictionary of fields to update
+    func update(_ collection: String, id: String, fields: [String: Any]) async throws {
+        try await db.collection(collection).document(id).updateData(fields)
+    }
+    
+    /// Update a document by replacing it with new data.
+    /// - Parameters:
+    ///   - collection: Collection name
+    ///   - id: Document ID
+    ///   - data: Encodable model
+    func update<T: Encodable>(_ collection: String, id: String, data: T) async throws {
+        try db.collection(collection).document(id).setData(from: data, merge: true)
+    }
+    
+    // MARK: - Delete
+    
+    /// Delete a document.
+    /// - Parameters:
+    ///   - collection: Collection name
+    ///   - id: Document ID
+    func delete(_ collection: String, id: String) async throws {
+        try await db.collection(collection).document(id).delete()
+    }
+    
+    // MARK: - Real-time Listeners
+    
+    /// Listen to collection changes in real-time.
+    /// - Parameter collection: Collection name
+    /// - Returns: AsyncStream of document arrays
+    func listen<T: Codable>(_ collection: String) -> AsyncStream<[T]> {
+        AsyncStream { continuation in
+            let listener = db.collection(collection).addSnapshotListener { snapshot, error in
+                if let error = error {
+                    continuation.finish(throwing: error)
+                    return
+                }
+                
+                guard let snapshot = snapshot else {
+                    continuation.finish()
+                    return
+                }
+                
+                do {
+                    let items = try snapshot.documents.compactMap { document in
+                        try document.data(as: T.self)
+                    }
+                    continuation.yield(items)
+                } catch {
+                    continuation.finish(throwing: error)
+                }
+            }
+            
+            continuation.onTermination = { @Sendable _ in
+                listener.remove()
+            }
+        }
+    }
+    
+    /// Listen to a single document changes in real-time.
+    /// - Parameters:
+    ///   - collection: Collection name
+    ///   - id: Document ID
+    /// - Returns: AsyncStream of document
+    func listen<T: Codable>(_ collection: String, id: String) -> AsyncStream<T?> {
+        AsyncStream { continuation in
+            let listener = db.collection(collection).document(id).addSnapshotListener { snapshot, error in
+                if let error = error {
+                    continuation.finish(throwing: error)
+                    return
+                }
+                
+                guard let snapshot = snapshot, snapshot.exists else {
+                    continuation.yield(nil)
+                    return
+                }
+                
+                do {
+                    let item = try snapshot.data(as: T.self)
+                    continuation.yield(item)
+                } catch {
+                    continuation.finish(throwing: error)
+                }
+            }
+            
+            continuation.onTermination = { @Sendable _ in
+                listener.remove()
+            }
+        }
+    }
+    
+    /// Listen to collection changes with a query filter.
+    /// - Parameters:
+    ///   - collection: Collection name
+    ///   - field: Field to filter on
+    ///   - value: Value to match
+    /// - Returns: AsyncStream of document arrays
+    func listen<T: Codable>(_ collection: String, whereField field: String, isEqualTo value: Any) -> AsyncStream<[T]> {
+        AsyncStream { continuation in
+            let listener = db.collection(collection)
+                .whereField(field, isEqualTo: value)
+                .addSnapshotListener { snapshot, error in
+                    if let error = error {
+                        continuation.finish(throwing: error)
+                        return
+                    }
+                    
+                    guard let snapshot = snapshot else {
+                        continuation.finish()
+                        return
+                    }
+                    
+                    do {
+                        let items = try snapshot.documents.compactMap { document in
+                            try document.data(as: T.self)
+                        }
+                        continuation.yield(items)
+                    } catch {
+                        continuation.finish(throwing: error)
+                    }
+                }
+            
+            continuation.onTermination = { @Sendable _ in
+                listener.remove()
+            }
+        }
+    }
+}

package/templates/shared/ios/FirebaseBackend/INTEGRATION.md

@@ -0,0 +1,287 @@
+# FirebaseBackend Module — Integration Guide
+
+## Prerequisites
+
+### iOS Dependencies
+
+1. **Add Firebase SDK via Swift Package Manager:**
+   - In Xcode: File → Add Packages...
+   - URL: `https://github.com/firebase/firebase-ios-sdk`
+   - Select: `FirebaseAuth`, `FirebaseFirestore`, `FirebaseStorage`, `FirebaseRemoteConfig`
+
+2. **Add Google Sign-In SDK:**
+   - URL: `https://github.com/google/GoogleSignIn-iOS`
+   - Select: `GoogleSignIn`
+
+3. **Add GoogleService-Info.plist:**
+   - Download from Firebase Console → Project Settings → iOS app
+   - Add to Xcode project (ensure "Copy items if needed" is checked)
+   - Ensure it's added to the app target
+
+4. **Initialize Firebase in App:**
+   ```swift
+   import FirebaseCore
+   
+   @main
+   struct YourApp: App {
+       init() {
+           FirebaseConfigService.shared.configure()
+       }
+       // ...
+   }
+   ```
+
+5. **Configure Google Sign-In in AppDelegate or SceneDelegate:**
+   ```swift
+   import GoogleSignIn
+   
+   func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+       return GIDSignIn.sharedInstance.handle(url)
+   }
+   ```
+
+## AppConfig Additions
+
+Add to `AppConfig.Features`:
+
+```swift
+// CUSTOMIZE:FEATURES
+static let enableFirebaseBackend = true
+static let enableGoogleSignIn = true
+static let enableAppleSignIn = true
+```
+
+## Navigation Wiring
+
+### Auth Flow
+
+Add authentication gate to Profile tab or as onboarding:
+
+```swift
+import FirebaseAuth
+
+struct ProfileView: View {
+    @StateObject private var authService = FirebaseAuthService.shared
+    
+    var body: some View {
+        if authService.isLoggedIn {
+            FirebaseProfileScreen()
+        } else {
+            FirebaseLoginScreen {
+                // Handle successful login
+            }
+        }
+    }
+}
+```
+
+### Login Screen
+
+```swift
+NavigationStack {
+    FirebaseLoginScreen {
+        // Navigate to main app content
+    }
+}
+```
+
+### Sign Up Screen
+
+```swift
+NavigationStack {
+    FirebaseSignUpScreen {
+        // Navigate to main app content
+    }
+}
+```
+
+### Forgot Password Screen
+
+```swift
+NavigationStack {
+    FirebaseForgotPasswordScreen()
+}
+```
+
+### Profile Screen
+
+```swift
+NavigationStack {
+    FirebaseProfileScreen()
+}
+```
+
+## Service Usage
+
+### FirebaseAuthService
+
+```swift
+let authService = FirebaseAuthService.shared
+
+// Sign in with email
+try await authService.signInWithEmail(email: "user@example.com", password: "password123")
+
+// Create user
+try await authService.createUser(email: "user@example.com", password: "password123", displayName: "John Doe")
+
+// Sign in with Google
+try await authService.signInWithGoogle()
+
+// Sign in with Apple
+try await authService.signInWithApple()
+
+// Sign in anonymously
+try await authService.signInAnonymously()
+
+// Send password reset
+try await authService.sendPasswordReset(email: "user@example.com")
+
+// Sign out
+try authService.signOut()
+
+// Delete account
+try await authService.deleteAccount()
+
+// Observe auth state
+authService.$authState
+    .sink { state in
+        switch state {
+        case .loggedOut:
+            // Show login screen
+        case .authenticating:
+            // Show loading
+        case .loggedIn(let user):
+            // Show app content
+        case .error(let message):
+            // Show error
+        }
+    }
+```
+
+### FirestoreService
+
+```swift
+let firestore = FirestoreService.shared
+
+// Create document
+let itemId = try await firestore.create("items", data: MyModel(...))
+
+// Fetch collection
+let items: [MyModel] = try await firestore.fetchCollection("items")
+
+// Fetch document
+let item: MyModel = try await firestore.fetchDocument("items", id: itemId)
+
+// Update document
+try await firestore.update("items", id: itemId, fields: ["title": "New Title"])
+
+// Delete document
+try await firestore.delete("items", id: itemId)
+
+// Listen to collection changes
+for await items: [MyModel] in firestore.listen("items") {
+    // Update UI
+}
+```
+
+### FirebaseStorageService
+
+```swift
+let storage = FirebaseStorageService.shared
+
+// Upload data
+let url = try await storage.upload(data: imageData, path: "images/profile.jpg")
+
+// Upload with progress
+for await (progress, url) in storage.uploadProgress(data: imageData, path: "images/profile.jpg") {
+    print("Progress: \(progress * 100)%")
+    if let url = url {
+        print("Upload complete: \(url)")
+    }
+}
+
+// Download data
+let data = try await storage.download(path: "images/profile.jpg")
+
+// Get download URL
+let url = try await storage.getDownloadURL(path: "images/profile.jpg")
+
+// Delete file
+try await storage.delete(path: "images/profile.jpg")
+```
+
+### FirebaseConfigService
+
+```swift
+let config = FirebaseConfigService.shared
+
+// Fetch Remote Config
+try await config.fetchRemoteConfig()
+
+// Get values
+let featureEnabled = config.boolValue(forKey: "feature_enabled")
+let apiEndpoint = config.stringValue(forKey: "api_endpoint")
+let maxItems = config.numberValue(forKey: "max_items")
+```
+
+## String Merge
+
+Add `Strings.Firebase` enum to the app's `Strings.swift` file. All strings are in the module's `Strings.swift`.
+
+## Test IDs
+
+| Test ID | Element |
+|---------|---------|
+| `firebase_login_title` | Login screen title |
+| `firebase_login_email_field` | Email text field |
+| `firebase_login_password_field` | Password text field |
+| `firebase_login_sign_in_button` | Sign in button |
+| `firebase_login_forgot_password_button` | Forgot password link |
+| `firebase_login_google_button` | Google Sign-In button |
+| `firebase_login_apple_button` | Apple Sign-In button |
+| `firebase_login_sign_up_link` | Sign up link |
+| `firebase_signup_title` | Sign up screen title |
+| `firebase_signup_display_name_field` | Display name field |
+| `firebase_signup_email_field` | Email field |
+| `firebase_signup_password_field` | Password field |
+| `firebase_signup_confirm_password_field` | Confirm password field |
+| `firebase_signup_create_account_button` | Create account button |
+| `firebase_forgot_password_email_field` | Email field |
+| `firebase_forgot_password_send_button` | Send reset link button |
+| `firebase_profile_avatar` | Profile avatar |
+| `firebase_profile_display_name` | Display name |
+| `firebase_profile_email` | Email |
+| `firebase_profile_sign_out_button` | Sign out button |
+| `firebase_profile_delete_account_button` | Delete account button |
+
+## Module Dependencies
+
+- **ErrorHandling** (optional) — for displaying auth errors
+- **NetworkBanner** (optional) — for connectivity awareness
+
+## Usage Notes
+
+- **Offline Support:** Firestore has built-in offline persistence. No additional caching layer needed.
+- **Real-time Updates:** FirestoreService uses Firestore listeners for automatic real-time synchronization.
+- **User Isolation:** Items are filtered by `userId` field. Ensure `userId` is set when creating items.
+- **Security Rules:** Configure Firestore security rules in Firebase Console.
+- **Collection Names:** Customize collection names to match your domain (e.g., "recipes" instead of "items").
+- **Google Sign-In:** Requires proper URL scheme configuration in Info.plist.
+- **Apple Sign-In:** Requires Apple Developer account and proper entitlements.
+
+## Firestore Data Structure
+
+Items should be stored with this structure:
+```json
+{
+  "id": "item-123",
+  "title": "Item Title",
+  "subtitle": "Subtitle",
+  "description": "Description",
+  "category": "Category Name",
+  "isFavorite": false,
+  "createdAt": "2024-01-01T00:00:00Z",
+  "userId": "firebase-user-id",
+  "metadata": {}
+}
+```

package/templates/shared/ios/FirebaseBackend/SETUP.md

@@ -0,0 +1,224 @@
+# FirebaseBackend Module — Setup Guide
+
+## Firebase Console Setup
+
+### 1. Create Firebase Project
+
+1. Go to [Firebase Console](https://console.firebase.google.com/)
+2. Click "Add project"
+3. Enter project name and follow the setup wizard
+4. Enable Google Analytics (optional)
+
+### 2. Add iOS App
+
+1. In Firebase Console, click "Add app" → iOS
+2. Enter your iOS bundle ID (e.g., `com.yourcompany.yourapp`)
+3. Register the app
+4. Download `GoogleService-Info.plist`
+5. Add `GoogleService-Info.plist` to your Xcode project
+
+### 3. Enable Authentication Methods
+
+1. Go to **Authentication** → **Sign-in method**
+2. Enable **Email/Password**
+3. Enable **Google** (requires OAuth client ID configuration)
+4. Enable **Apple** (requires Apple Developer account)
+
+### 4. Configure Google Sign-In
+
+1. In Firebase Console → **Authentication** → **Sign-in method** → **Google**
+2. Enable Google Sign-In
+3. Add your iOS app's bundle ID
+4. Download the updated `GoogleService-Info.plist`
+5. In Xcode, add URL scheme from `REVERSED_CLIENT_ID` in `GoogleService-Info.plist`:
+   - Open `Info.plist`
+   - Add URL Types → Item 0 → URL Schemes → Item 0
+   - Value: `REVERSED_CLIENT_ID` from `GoogleService-Info.plist`
+
+### 5. Configure Apple Sign-In
+
+1. In Firebase Console → **Authentication** → **Sign-in method** → **Apple**
+2. Enable Apple Sign-In
+3. In Xcode, enable Sign in with Apple capability:
+   - Select your target → Signing & Capabilities
+   - Click "+ Capability"
+   - Add "Sign in with Apple"
+
+### 6. Set Up Firestore Database
+
+1. Go to **Firestore Database**
+2. Click "Create database"
+3. Start in **test mode** (for development)
+4. Choose a location close to your users
+5. Configure security rules (see below)
+
+### 7. Configure Firestore Security Rules
+
+Replace the default rules with:
+
+```javascript
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    // Users can only read/write their own data
+    match /{collection}/{document} {
+      allow read, write: if request.auth != null && 
+        resource.data.userId == request.auth.uid;
+      
+      // Allow creation with userId set
+      allow create: if request.auth != null && 
+        request.resource.data.userId == request.auth.uid;
+    }
+  }
+}
+```
+
+### 8. Set Up Firebase Storage
+
+1. Go to **Storage**
+2. Click "Get started"
+3. Start in **test mode** (for development)
+4. Choose a location
+5. Configure security rules (see below)
+
+### 9. Configure Storage Security Rules
+
+Replace the default rules with:
+
+```javascript
+rules_version = '2';
+service firebase.storage {
+  match /b/{bucket}/o {
+    // Users can only upload/download their own files
+    match /{userId}/{allPaths=**} {
+      allow read, write: if request.auth != null && request.auth.uid == userId;
+    }
+  }
+}
+```
+
+### 10. Set Up Remote Config
+
+1. Go to **Remote Config**
+2. Click "Get started"
+3. Add parameters:
+   - `feature_enabled` (Boolean, default: `false`)
+   - `api_endpoint` (String, default: `https://api.example.com`)
+   - `max_items` (Number, default: `100`)
+
+## Xcode Configuration
+
+### 1. Add Swift Package Dependencies
+
+1. File → Add Packages...
+2. Add Firebase iOS SDK: `https://github.com/firebase/firebase-ios-sdk`
+3. Select: `FirebaseAuth`, `FirebaseFirestore`, `FirebaseStorage`, `FirebaseRemoteConfig`
+4. Add Google Sign-In SDK: `https://github.com/google/GoogleSignIn-iOS`
+5. Select: `GoogleSignIn`
+
+### 2. Configure Info.plist
+
+Add URL scheme for Google Sign-In:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+    <dict>
+        <key>CFBundleTypeRole</key>
+        <string>Editor</string>
+        <key>CFBundleURLSchemes</key>
+        <array>
+            <string>YOUR_REVERSED_CLIENT_ID</string>
+        </array>
+    </dict>
+</array>
+```
+
+Replace `YOUR_REVERSED_CLIENT_ID` with the value from `GoogleService-Info.plist`.
+
+### 3. Initialize Firebase
+
+In your `App.swift` or `AppDelegate.swift`:
+
+```swift
+import SwiftUI
+import FirebaseCore
+
+@main
+struct YourApp: App {
+    init() {
+        FirebaseConfigService.shared.configure()
+    }
+    
+    var body: some Scene {
+        WindowGroup {
+            ContentView()
+        }
+    }
+}
+```
+
+### 4. Handle Google Sign-In URL
+
+In `AppDelegate.swift` or `SceneDelegate.swift`:
+
+```swift
+import GoogleSignIn
+
+func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
+    return GIDSignIn.sharedInstance.handle(url)
+}
+```
+
+## Testing
+
+1. **Test Email/Password Auth:**
+   - Create a test user in Firebase Console → Authentication
+   - Or use the sign-up screen in your app
+
+2. **Test Google Sign-In:**
+   - Ensure `GoogleService-Info.plist` is correctly configured
+   - Test on a real device (simulator may have issues)
+
+3. **Test Apple Sign-In:**
+   - Requires Apple Developer account
+   - Test on a real device
+
+4. **Test Firestore:**
+   - Create a test document via the app
+   - Verify it appears in Firebase Console
+
+5. **Test Storage:**
+   - Upload a test image
+   - Verify it appears in Firebase Console → Storage
+
+6. **Test Remote Config:**
+   - Fetch config values
+   - Update values in Firebase Console
+   - Fetch again to verify updates
+
+## Troubleshooting
+
+### Google Sign-In Not Working
+
+- Verify `REVERSED_CLIENT_ID` is in URL schemes
+- Check `GoogleService-Info.plist` is in the app bundle
+- Ensure OAuth client ID is configured in Firebase Console
+
+### Apple Sign-In Not Working
+
+- Verify Sign in with Apple capability is enabled
+- Check Apple Developer account is active
+- Ensure bundle ID matches Firebase project
+
+### Firestore Permission Denied
+
+- Check security rules in Firebase Console
+- Verify user is authenticated (`request.auth != null`)
+- Ensure `userId` field matches `request.auth.uid`
+
+### Storage Permission Denied
+
+- Check security rules in Firebase Console
+- Verify file path matches user ID pattern
+- Ensure user is authenticated