reis-mobile 0.3.5

package/skills/firebase-auth/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: firebase-auth
+description: Integrates Firebase Authentication into Flutter apps. Use when setting up auth, managing auth state, implementing email/password or social sign-in, handling auth errors, managing users, or applying security best practices.
+routing: manual
+stacks: [flutter]
+source: https://github.com/evanca/flutter-ai-rules
+license: MIT
+---
+
+# Firebase Authentication Skill
+
+This skill defines how to correctly use Firebase Authentication in Flutter applications.
+
+## When to Use
+
+Use this skill when:
+
+* Setting up Firebase Authentication in a Flutter project.
+* Listening to authentication state changes.
+* Implementing email/password or social sign-in.
+* Managing user profiles, account linking, or MFA.
+* Handling authentication errors.
+* Applying security best practices for auth flows.
+
+---
+
+## 1. Setup and Configuration
+
+```
+flutter pub add firebase_auth
+```
+
+```dart
+import 'package:firebase_auth/firebase_auth.dart';
+```
+
+- Enable desired authentication providers in the **Firebase console** before using them.
+- Initialize Firebase before using any Firebase Authentication features.
+
+**Local emulator for testing:**
+
+```dart
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await Firebase.initializeApp();
+  await FirebaseAuth.instance.useAuthEmulator('localhost', 9099);
+  // ...
+}
+```
+
+---
+
+## 2. Authentication State Management
+
+Use the appropriate stream based on what you need to observe:
+
+| Stream | Fires when |
+|---|---|
+| `authStateChanges()` | User signs in or out |
+| `idTokenChanges()` | ID token changes (including custom claims) |
+| `userChanges()` | User data changes (e.g., profile updates) |
+
+```dart
+FirebaseAuth.instance
+  .authStateChanges()
+  .listen((User? user) {
+    if (user == null) {
+      print('User is currently signed out!');
+    } else {
+      print('User is signed in!');
+    }
+  });
+```
+
+- Listen to these streams **immediately** when the app starts to handle the initial auth state.
+- Custom claims are only available after sign-in, re-authentication, token expiration, or manual token refresh.
+
+---
+
+## 3. Email and Password Authentication
+
+**Create a new account:**
+
+```dart
+try {
+  final credential = await FirebaseAuth.instance.createUserWithEmailAndPassword(
+    email: emailAddress,
+    password: password,
+  );
+} on FirebaseAuthException catch (e) {
+  if (e.code == 'weak-password') {
+    print('The password provided is too weak.');
+  } else if (e.code == 'email-already-in-use') {
+    print('The account already exists for that email.');
+  }
+} catch (e) {
+  print(e);
+}
+```
+
+**Sign in:**
+
+```dart
+try {
+  final credential = await FirebaseAuth.instance.signInWithEmailAndPassword(
+    email: emailAddress,
+    password: password,
+  );
+} on FirebaseAuthException catch (e) {
+  if (e.code == 'user-not-found') {
+    print('No user found for that email.');
+  } else if (e.code == 'wrong-password') {
+    print('Wrong password provided for that user.');
+  }
+}
+```
+
+- Verify the user's email address after account creation.
+- Firebase rate-limits new email/password sign-ups from the same IP to protect against abuse.
+- On iOS/macOS, authentication state persists between app re-installs via the system keychain.
+
+---
+
+## 4. Social Authentication
+
+**Google Sign-In (native platforms):**
+
+```dart
+Future<UserCredential> signInWithGoogle() async {
+  final GoogleSignInAccount? googleUser = await GoogleSignIn.instance.authenticate();
+  final GoogleSignInAuthentication googleAuth = googleUser.authentication;
+  final credential = GoogleAuthProvider.credential(idToken: googleAuth.idToken);
+  return await FirebaseAuth.instance.signInWithCredential(credential);
+}
+```
+
+**Google Sign-In (web):**
+
+```dart
+Future<UserCredential> signInWithGoogle() async {
+  GoogleAuthProvider googleProvider = GoogleAuthProvider();
+  googleProvider.addScope('https://www.googleapis.com/auth/contacts.readonly');
+  googleProvider.setCustomParameters({'login_hint': 'user@example.com'});
+  return await FirebaseAuth.instance.signInWithPopup(googleProvider);
+}
+```
+
+- Configure platform-specific settings for each provider (e.g., SHA1 key for Google Sign-In on Android).
+- If a user signs in with a social provider after registering with the same email manually, Firebase's trusted provider concept will automatically change their authentication provider.
+
+---
+
+## 5. Error Handling
+
+- Always use `try-catch` with `FirebaseAuthException`.
+- Check `e.code` to identify specific error types.
+- Handle `account-exists-with-different-credential` by fetching sign-in methods for the email and guiding users through the correct flow.
+- Handle `too-many-requests` with retry logic or user feedback.
+- Handle `operation-not-allowed` by ensuring the provider is enabled in the Firebase console.
+
+---
+
+## 6. User Management
+
+```dart
+// Update profile
+await FirebaseAuth.instance.currentUser?.updateProfile(
+  displayName: "Jane Q. User",
+  photoURL: "https://example.com/jane-q-user/profile.jpg",
+);
+
+// Update email (sends verification to new address first)
+await user?.verifyBeforeUpdateEmail("newemail@example.com");
+```
+
+- Use `verifyBeforeUpdateEmail()` — **not** `updateEmail()` — to change a user's email. The email only updates after the user verifies it.
+- Store only essential info in the auth profile; use a database for additional user data.
+- Use `linkWithCredential()` to connect multiple auth providers to a single account.
+- Verify the user's identity before linking new credentials.
+- Use `fetchSignInMethodsForEmail()` when handling account linking.
+
+---
+
+## 7. Security Best Practices
+
+- Never store sensitive authentication credentials in client-side code.
+- Monitor auth state changes for proper session management.
+- Validate user input before submitting authentication requests to prevent injection attacks.
+- Call `FirebaseAuth.instance.signOut()` when users exit the app.
+- For sensitive operations, re-authenticate users with `reauthenticateWithCredential()`.
+- Enforce strong password policies for email/password auth.
+- In Realtime Database and Cloud Storage Security Rules, use the `auth` variable to get the signed-in user's UID for access control.
+- Use multi-factor authentication for sensitive applications.
+
+---
+
+## 8. Multi-Factor Authentication
+
+> **Security warning:** Avoid SMS-based MFA. SMS is insecure and easy to compromise or spoof.
+
+> **Platform limitation:** Windows does not support MFA. MFA with multiple tenants is not supported on Flutter.
+
+- Enable at least one MFA-compatible provider before implementing MFA.
+
+---
+
+## 9. Email Link Authentication
+
+> **Important:** Firebase Dynamic Links is deprecated for email link authentication. Firebase Hosting is now used to send sign-in links.
+
+- Set `handleCodeInApp: true` in `ActionCodeSettings` — sign-in must always be completed in the app.
+- Store the user's email locally (e.g., `SharedPreferences`) when sending the sign-in link.
+- **Never** pass the user's email in redirect URL parameters — this enables session injection attacks.
+- Use HTTPS URLs in production to prevent link interception.
+- Configure the app to detect incoming links and parse the underlying deep link for sign-in completion.
+
+---
+
+## References
+
+- [Firebase Authentication Flutter documentation](https://firebase.google.com/docs/auth/flutter/start)
+- [Email/password authentication](https://firebase.google.com/docs/auth/flutter/password-auth)
+- [Federated identity & social sign-in](https://firebase.google.com/docs/auth/flutter/federated-auth)
+- [Multi-factor authentication](https://firebase.google.com/docs/auth/flutter/multi-factor)

package/skills/firebase-cloud-firestore/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: firebase-cloud-firestore
+description: Integrates Cloud Firestore into Flutter apps. Use when setting up Firestore, designing document/collection structure, reading and writing data, working with real-time listeners, designing for scale, or applying security rules.
+routing: manual
+stacks: [flutter]
+source: https://github.com/evanca/flutter-ai-rules
+license: MIT
+---
+
+# Firebase Cloud Firestore Skill
+
+This skill defines how to correctly use Cloud Firestore in Flutter applications.
+
+## When to Use
+
+Use this skill when:
+
+* Setting up and configuring Cloud Firestore in a Flutter project.
+* Designing document and collection structure.
+* Performing read, write, or real-time listener operations.
+* Optimizing for scale and avoiding hotspots.
+* Applying Firestore security rules.
+
+---
+
+## 1. Database Selection
+
+Choose **Cloud Firestore** when your app needs:
+- Rich, hierarchical data models with subcollections.
+- Complex queries: chaining filters, combining filtering and sorting on a property.
+- Transactions that atomically read and write data from any part of the database.
+- High availability (typical uptime 99.999%) or critical-level reliability.
+- Scalability.
+
+Use **Realtime Database** instead for simple data models requiring simple lookups and extremely low-latency synchronization (typical response times under 10ms).
+
+---
+
+## 2. Setup and Configuration
+
+```
+flutter pub add cloud_firestore
+```
+
+```dart
+import 'package:cloud_firestore/cloud_firestore.dart';
+
+final db = FirebaseFirestore.instance; // after Firebase.initializeApp()
+```
+
+**Location:**
+- Select the database location closest to your users and compute resources.
+- Use **multi-region** locations for critical apps (maximum availability and durability).
+- Use **regional** locations for lower costs and lower write latency for latency-sensitive apps.
+
+**iOS/macOS:** Consider pre-compiled frameworks to improve build times:
+```ruby
+pod 'FirebaseFirestore',
+  :git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
+  :tag => 'IOS_SDK_VERSION'
+```
+
+---
+
+## 3. Document Structure
+
+- Avoid document IDs `.` and `..` (special meaning in Firestore paths).
+- Avoid forward slashes (`/`) in document IDs (path separators).
+- **Do not** use monotonically increasing document IDs (e.g., `Customer1`, `Customer2`) — causes write hotspots.
+- Use Firestore's **automatic document IDs** when possible:
+
+```dart
+db.collection("users").add(user).then((DocumentReference doc) =>
+    print('DocumentSnapshot added with ID: ${doc.id}'));
+```
+
+- Avoid these characters in field names (require extra escaping): `.` `[` `]` `*` `` ` ``
+- Use **subcollections** within documents to organize complex, hierarchical data rather than deeply nested objects.
+
+---
+
+## 4. Indexing
+
+- Set **collection-level index exemptions** to reduce write latency and storage costs.
+- Disable Descending & Array indexing for fields that don't need them.
+- Exempt string fields with long values that aren't used for querying.
+- Exempt fields with sequential values (e.g., timestamps) from indexing if not used in queries — avoids the 500 writes/second index limit.
+- Add single-field exemptions for TTL fields.
+- Exempt large array or map fields not used in queries — avoids the 40,000 index entries per document limit.
+- Firestore queries are indexed by default; query performance is proportional to the result set size, not the dataset size.
+
+---
+
+## 5. Read and Write Operations
+
+- **Always use asynchronous calls** to minimize latency impact:
+
+```dart
+await db.collection("users").get().then((event) {
+  for (var doc in event.docs) {
+    print("${doc.id} => ${doc.data()}");
+  }
+});
+```
+
+- **Do not use offsets for pagination** — use cursors instead to avoid retrieving and being billed for skipped documents.
+- Implement **transaction retries** when accessing Firestore directly through REST or RPC APIs.
+- For writing a large number of documents, use a **bulk writer** instead of the atomic batch writer.
+- Execute independent operations (e.g., a document lookup and a query) **in parallel**, not sequentially.
+- Firestore queries are **shallow**: they only return documents in a specific collection or collection group, not subcollection data.
+- Be aware of write rate limits: ~1 write per second per document.
+
+---
+
+## 6. Designing for Scale
+
+- Avoid high read or write rates to **lexicographically close documents** (hotspotting).
+- Avoid creating new documents with **monotonically increasing fields** (like timestamps) at a very high rate.
+- Avoid **deleting documents** in a collection at a high rate.
+- **Gradually increase traffic** when writing to the database at a high rate.
+- Avoid queries that skip over recently deleted data — use `start_at` to find the correct start point.
+- Distribute writes across different document paths to avoid contention.
+- Firestore scales automatically to ~1 million concurrent connections and 10,000 writes/second.
+
+---
+
+## 7. Real-time Updates
+
+- **Limit** the number of simultaneous real-time listeners.
+- **Detach listeners** when they are no longer needed:
+
+```dart
+final subscription = db.collection("users")
+    .snapshots()
+    .listen((event) {
+      // Handle the data
+    });
+
+// When no longer needed:
+subscription.cancel();
+```
+
+- Use **compound queries** to filter data server-side rather than filtering on the client.
+- For large collections, use queries to limit the data being listened to — never listen to an entire large collection.
+- For presence functionality (online/offline status), implement custom presence solutions as described in Firebase documentation.
+
+---
+
+## 8. Security
+
+- Always use **Firebase Security Rules** to protect Firestore data.
+- **Validate user input** before submitting to Firestore to prevent injection attacks.
+- Use **transactions** for operations that require atomic updates to multiple documents.
+- Implement proper **error handling** for all Firestore operations.
+- Never store sensitive information in Firestore without proper access controls.
+- Security rules **do not cascade** unless you use a wildcard.
+- If a query's results might contain data the user doesn't have access to, **the entire query fails**.
+
+---
+
+## References
+
+- [Cloud Firestore Flutter documentation](https://firebase.google.com/docs/firestore/quickstart?hl=en&authuser=0&platform=flutter)
+- [Cloud Firestore best practices](https://firebase.google.com/docs/firestore/best-practices)
+- [Cloud Firestore security rules](https://firebase.google.com/docs/firestore/security/get-started)

package/skills/firebase-cloud-functions/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: firebase-cloud-functions
+description: Calls Firebase Cloud Functions from Flutter apps. Use when setting up callable functions, passing data to functions, handling errors from function calls, optimizing performance, or testing with the Firebase Emulator Suite.
+routing: manual
+stacks: [flutter]
+source: https://github.com/evanca/flutter-ai-rules
+license: MIT
+---
+
+# Firebase Cloud Functions Skill
+
+This skill defines how to correctly call Firebase Cloud Functions from Flutter applications.
+
+## When to Use
+
+Use this skill when:
+
+* Setting up and configuring Cloud Functions in a Flutter project.
+* Calling callable functions and handling their results.
+* Handling errors from function calls.
+* Optimizing function call performance.
+* Testing with the Firebase Emulator Suite.
+
+---
+
+## 1. Setup and Configuration
+
+```
+flutter pub add cloud_functions
+```
+
+```dart
+import 'package:cloud_functions/cloud_functions.dart';
+
+// After Firebase.initializeApp():
+final functions = FirebaseFunctions.instance;
+```
+
+- Initialize Firebase before using any Cloud Functions features.
+- For region-specific deployments, specify the region when getting the instance.
+- Deploy callable functions to Firebase **before** attempting to call them from your Flutter app.
+- Consider implementing **App Check** to prevent abuse of your Cloud Functions.
+
+---
+
+## 2. Calling Functions
+
+Use `httpsCallable` to reference a function, then `call` to invoke it:
+
+```dart
+final result = await FirebaseFunctions.instance
+  .httpsCallable('functionName')
+  .call(data);
+```
+
+- Pass data as a `Map` — it is automatically serialized to JSON:
+
+```dart
+final result = await FirebaseFunctions.instance
+  .httpsCallable('addMessage')
+  .call({
+    "text": messageText,
+    "push": true,
+  });
+```
+
+- Access the result via the `data` property — it is automatically deserialized from JSON:
+
+```dart
+final responseData = result.data;
+// Cast to expected type if needed:
+final responseString = result.data as String;
+```
+
+- **Do not** pass authentication tokens in function parameters — they are automatically included by the SDK.
+- Keep function names consistent between client code and server-side implementations.
+
+---
+
+## 3. Error Handling
+
+Always wrap function calls in `try-catch` and check for `FirebaseFunctionsException`:
+
+```dart
+try {
+  final result = await FirebaseFunctions.instance
+    .httpsCallable('functionName')
+    .call(data);
+  // Handle successful result
+} catch (e) {
+  if (e is FirebaseFunctionsException) {
+    print('Error code: ${e.code}');
+    print('Error message: ${e.message}');
+    print('Error details: ${e.details}');
+  } else {
+    print('Error: $e');
+  }
+}
+```
+
+- Handle network connectivity issues and timeouts appropriately.
+- Provide meaningful error messages to users when function calls fail.
+- Consider implementing retry logic for transient errors.
+
+---
+
+## 4. Performance Optimization
+
+Set a timeout appropriate to the expected execution time:
+
+```dart
+final callable = FirebaseFunctions.instance.httpsCallable(
+  'functionName',
+  options: HttpsCallableOptions(
+    timeout: const Duration(seconds: 30),
+  ),
+);
+```
+
+- Minimize the amount of data passed to and from functions to reduce latency.
+- Use batch operations when possible to reduce the number of function calls.
+- Consider client-side caching for frequently used function results.
+- Monitor function performance in the Firebase Console to identify bottlenecks.
+- Account for **cold starts** for infrequently used functions.
+- Implement proper loading states in the UI while waiting for function responses.
+
+---
+
+## 5. Testing and Development
+
+Use the Firebase Emulator Suite for local development and testing:
+
+```dart
+FirebaseFunctions.instance.useFunctionsEmulator('localhost', 5001);
+```
+
+- Test functions with both valid and invalid inputs to ensure proper validation.
+- Verify that functions handle authentication correctly.
+- Test with different user roles and permissions to ensure proper access control.
+- Implement unit tests for client-side function calling logic.
+- Use integration tests to verify end-to-end function behavior.
+
+---
+
+## References
+
+- [Cloud Functions for Firebase Flutter documentation](https://firebase.google.com/docs/functions/callable?platform=flutter)
+- [Firebase Emulator Suite](https://firebase.google.com/docs/emulator-suite)