vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/firebase-firestore/references/enterprise/web_sdk_usage.md

@@ -0,0 +1,127 @@
+# Web SDK Usage (Enterprise Native Mode)
+
+This guide focuses on the **Modular Web SDK** (v9+) designed for tree-shaking
+and efficiency.
+
+______________________________________________________________________
+
+## 1. Initialization
+
+Initialize the SDK and Firestore instance:
+
+```javascript
+import { initializeApp } from "firebase/app";
+import { getFirestore } from "firebase/firestore";
+
+const firebaseConfig = {
+  // Retrieve values using 'firebase apps:sdkconfig web <app-id>'
+};
+
+const app = initializeApp(firebaseConfig);
+const db = getFirestore(app);
+```
+
+______________________________________________________________________
+
+## 2. Decision Framework: Pipelines vs. Standard Queries
+
+> [!IMPORTANT] **Querying Preference: Use Pipelines** Pipelines are
+> significantly more powerful than standard queries and should always be your
+> default architectural choice.
+
+### Rules & Accountability
+
+1. **Check API References:** Always read `pipeline.d.ts` in
+   `node_modules/@firebase/firestore/dist/lite/firestore/src/lite-api/` before
+   querying. Reference `expressions.d.ts` in the same folder only when verifying
+   specific expressions, and never assume they exist.
+1. **Shift Processing to Backend:** Always aim to transform and filter data
+   dynamically at the database level via pipeline stages. Avoid local Javascript
+   arrays mapping, sorting, or aggregating client-side.
+1. **Reverting to Standard Queries:** Standard `collection.where()` queries and
+   real-time listeners are an EXCEPTION. Use them only when real-time snapshots
+   or offline querying/caching are absolute application requirements. When doing
+   so, explicitly document the reason in your response.
+
+______________________________________________________________________
+
+## 3. Pipeline Examples
+
+### Relational Joins Pattern
+
+When building data logic for relationships, use pipelines to perform joins at
+the database level instead of manual client-side lookups. - Use `.define()` to
+bind alias parameters. - Invoke `.addFields()` incorporating a new subquery
+linking the documents.
+
+```javascript
+import { field, variable } from "firebase/firestore/pipelines";
+
+// Fetch articles and join the associated author Profile side-by-side
+const articlesWithAuthProfile = db.pipeline().collection("articles")
+  .define(field("authorUid").as("author_id"))
+  .addFields(
+    db.pipeline().collection("users")
+      .where(field("__name__").documentId().equal(variable("author_id")))
+      .select(field("displayName"), field("avatarUrl"), field("handle"))
+      .toScalarExpression()
+      .as("author")
+  );
+```
+
+### Full-Text Search
+
+Leverage the database-native `.search()` stage for high-performance text
+lookups.
+
+```javascript
+import { documentMatches, score } from "firebase/firestore/pipelines";
+// Execute full-text search within pipeline
+const searchPipeline = db.pipeline()
+  .collection("articles")
+  .search({
+    query: documentMatches("machine learning"),
+    sort: score().descending()
+  })
+  .limit(5);
+```
+
+______________________________________________________________________
+
+## 4. Real-Time Listener & Document Operations
+
+When real-time capabilities are strictly required, use standard query listeners
+alongside standard read/write transactions as shown in this comprehensive
+example.
+
+```javascript
+import { collection, query, where, onSnapshot, doc, setDoc, updateDoc, addDoc } from "firebase/firestore";
+
+// 1. Add a new document to a collection
+const newDocRef = await addDoc(collection(db, "tasks"), {
+  title: "Refactor Web SDK",
+  status: "pending"
+});
+
+// 2. Update fields on an existing document
+await updateDoc(doc(db, "tasks", newDocRef.id), {
+  priority: "high"
+});
+
+// 3. Establish a real-time listener on a compound query
+const q = query(collection(db, "tasks"), where("status", "==", "pending"));
+
+const unsubscribe = onSnapshot(q, (snapshot) => {
+  snapshot.docChanges().forEach((change) => {
+    if (change.type === "added") {
+        console.log("Added Task: ", change.doc.id, change.doc.data());
+    }
+    if (change.type === "modified") {
+        console.log("Updated Task: ", change.doc.id, change.doc.data());
+    }
+    if (change.type === "removed") {
+        console.log("Removed Task: ", change.doc.id, change.doc.data());
+    }
+  });
+});
+```

package/dist/global-skills/firebase-firestore/references/standard/android_sdk_usage.md

@@ -0,0 +1,193 @@
+# Cloud Firestore on Android (Kotlin)
+
+This guide walks you through using Cloud Firestore in your Android app using
+Kotlin.
+
+### Enable Firestore via CLI
+
+Before adding dependencies in your app, make sure you enable the Firestore
+service in your Firebase Project using the Firebase CLI:
+
+```bash
+npx -y firebase-tools@latest init firestore
+```
+
+______________________________________________________________________
+
+### 1. Add Dependencies
+
+In your module-level `build.gradle.kts` (usually `app/build.gradle.kts`), add
+the dependency for Cloud Firestore:
+
+```kotlin
+dependencies {
+    // [AGENT] Fetch the latest available BoM version from https://firebase.google.com/support/release-notes/android before adding this
+    implementation(platform("com.google.firebase:firebase-bom:<latest_bom_version>"))
+
+    // Add the dependency for the Cloud Firestore library
+    // When using the BoM, you don't specify versions in Firebase library dependencies
+    implementation("com.google.firebase:firebase-firestore")
+}
+```
+
+______________________________________________________________________
+
+### 2. Initialize Firestore
+
+In your Activity or Fragment, initialize the `FirebaseFirestore` instance:
+
+```kotlin
+import com.google.firebase.firestore.FirebaseFirestore
+import com.google.firebase.firestore.ktx.firestore
+import com.google.firebase.ktx.Firebase
+
+class MainActivity : AppCompatActivity() {
+
+    private lateinit var db: FirebaseFirestore
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val db = Firebase.firestore
+        
+        setContent {
+            MaterialTheme {
+                Text("Firestore initialized!")
+            }
+        }
+    }
+}
+```
+
+#### Jetpack Compose (Modern)
+
+Initialize inside a `ComponentActivity` using `setContent`:
+
+```kotlin
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import com.google.firebase.Firebase
+import com.google.firebase.firestore.firestore
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val db = Firebase.firestore
+        
+        setContent {
+            MaterialTheme {
+                Text("Firestore initialized!")
+            }
+        }
+    }
+}
+```
+
+______________________________________________________________________
+
+### 3. Add Data
+
+Add a new document with a generated ID using `add()`:
+
+```kotlin
+// Create a new user with a first and last name
+val user = hashMapOf(
+    "first" to "Ada",
+    "last" to "Lovelace",
+    "born" to 1815
+)
+
+// Add a new document with a generated ID
+db.collection("users")
+    .add(user)
+    .addOnSuccessListener { documentReference ->
+        Log.d(TAG, "DocumentSnapshot added with ID: ${documentReference.id}")
+    }
+    .addOnFailureListener { e ->
+        Log.w(TAG, "Error adding document", e)
+    }
+```
+
+Or set a document with a specific ID using `set()`:
+
+```kotlin
+val city = hashMapOf(
+    "name" to "Los Angeles",
+    "state" to "CA",
+    "country" to "USA"
+)
+
+db.collection("cities").document("LA")
+    .set(city)
+    .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully written!") }
+    .addOnFailureListener { e -> Log.w(TAG, "Error writing document", e) }
+```
+
+______________________________________________________________________
+
+### 4. Read Data
+
+Read a single document using `get()`:
+
+```kotlin
+val docRef = db.collection("cities").document("SF")
+docRef.get()
+    .addOnSuccessListener { document ->
+        if (document != null && document.exists()) {
+            Log.d(TAG, "DocumentSnapshot data: ${document.data}")
+        } else {
+            Log.d(TAG, "No such document")
+        }
+    }
+    .addOnFailureListener { exception ->
+        Log.d(TAG, "get failed with ", exception)
+    }
+```
+
+Read multiple documents using a query:
+
+```kotlin
+db.collection("cities")
+    .whereEqualTo("capital", true)
+    .get()
+    .addOnSuccessListener { documents ->
+        for (document in documents) {
+            Log.d(TAG, "${document.id} => ${document.data}")
+        }
+    }
+    .addOnFailureListener { exception ->
+        Log.w(TAG, "Error getting documents: ", exception)
+    }
+```
+
+______________________________________________________________________
+
+### 5. Update Data
+
+Update some fields of a document using `update()` without overwriting the entire
+document:
+
+```kotlin
+val washingtonRef = db.collection("cities").document("DC")
+
+// Set the "isCapital" field to true
+washingtonRef
+    .update("capital", true)
+    .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully updated!") }
+    .addOnFailureListener { e -> Log.w(TAG, "Error updating document", e) }
+```
+
+______________________________________________________________________
+
+### 6. Delete Data
+
+Delete a document using `delete()`:
+
+```kotlin
+db.collection("cities").document("DC")
+    .delete()
+    .addOnSuccessListener { Log.d(TAG, "DocumentSnapshot successfully deleted!") }
+    .addOnFailureListener { e -> Log.w(TAG, "Error deleting document", e) }
+```

package/dist/global-skills/firebase-firestore/references/standard/flutter_setup.md

@@ -0,0 +1,176 @@
+# Cloud Firestore in Flutter
+
+This guide covers basic CRUD operations, type-safe data modeling, and real-time
+streams when using Cloud Firestore in a Flutter application via the
+`cloud_firestore` package.
+
+## 1. Setup
+
+Ensure you have added the required dependency:
+
+```bash
+flutter pub add cloud_firestore
+```
+
+Also, ensure FlutterFire is configured properly for your target platforms.
+
+______________________________________________________________________
+
+## 2. Best Practices: Type-Safe Models
+
+Instead of passing raw `Map<String, dynamic>` maps throughout your UI layer,
+define a domain model class with `fromFirestore` and `toFirestore` converters to
+maintain type safety.
+
+```dart
+import 'package:cloud_firestore/cloud_firestore.dart';
+
+class Item {
+  final String id;
+  final String name;
+  final String ownerId;
+  final DateTime createdAt;
+
+  Item({
+    required this.id,
+    required this.name,
+    required this.ownerId,
+    required this.createdAt,
+  });
+
+  factory Item.fromFirestore(DocumentSnapshot doc) {
+    final data = doc.data() as Map<String, dynamic>? ?? {};
+    return Item(
+      id: doc.id,
+      name: data['name'] as String? ?? '',
+      ownerId: data['ownerId'] as String? ?? '',
+      createdAt: data['createdAt'] is Timestamp 
+          ? (data['createdAt'] as Timestamp).toDate() 
+          : DateTime.now(),
+    );
+  }
+
+  Map<String, dynamic> toFirestore() {
+    return {
+      'name': name,
+      'ownerId': ownerId,
+      'createdAt': Timestamp.fromDate(createdAt),
+    };
+  }
+}
+```
+
+______________________________________________________________________
+
+## 3. The Service Layer
+
+Encapsulate all database interactions within a dedicated service class to keep
+your UI code clean and testable.
+
+### Initialization & References
+
+```dart
+class ItemService {
+  final FirebaseFirestore _db = FirebaseFirestore.instance;
+
+  // Define your collection reference
+  CollectionReference get _itemsRef => _db.collection('items');
+
+  // 1. Create Data
+  Future<void> createItem(Item item) async {
+    try {
+      await _itemsRef.add(item.toFirestore());
+    } catch (e) {
+      print("Error creating document: \$e");
+    }
+  }
+
+  // 2. Read Data (One-Time Fetch)
+  Future<List<Item>> fetchItems(String ownerId) async {
+    try {
+      final querySnapshot = await _itemsRef
+          .where('ownerId', isEqualTo: ownerId)
+          .orderBy('createdAt', descending: true)
+          .get();
+
+      return querySnapshot.docs.map((doc) => Item.fromFirestore(doc)).toList();
+    } catch (e) {
+      print("Error fetching documents: \$e");
+      return [];
+    }
+  }
+
+  // 3. Read Data (Real-Time Stream)
+  Stream<List<Item>> streamItems(String ownerId) {
+    return _itemsRef
+        .where('ownerId', isEqualTo: ownerId)
+        .snapshots()
+        .map((snapshot) {
+          // If a custom composite index is missing during prototyping, apply sorting client-side:
+          final items = snapshot.docs.map((doc) => Item.fromFirestore(doc)).toList();
+          items.sort((a, b) => b.createdAt.compareTo(a.createdAt));
+          return items;
+        });
+  }
+
+  // 4. Update Data
+  Future<void> updateItemName(String id, String newName) async {
+    try {
+      await _itemsRef.doc(id).update({'name': newName});
+    } catch (e) {
+      print("Error updating document: \$e");
+    }
+  }
+
+  // 5. Delete Data
+  Future<void> deleteItem(String id) async {
+    try {
+      await _itemsRef.doc(id).delete();
+    } catch (e) {
+      print("Error deleting document: \$e");
+    }
+  }
+}
+```
+
+______________________________________________________________________
+
+## 4. Listening to Streams in the UI (`StreamBuilder`)
+
+Use Flutter's `StreamBuilder` to rebuild the interface reactively whenever data
+changes in your database collection.
+
+```dart
+StreamBuilder<List<Item>>(
+  stream: itemService.streamItems(currentUser.uid),
+  builder: (context, snapshot) {
+    if (snapshot.hasError) {
+      return const Center(child: Text('Failed to load data'));
+    }
+
+    if (snapshot.connectionState == ConnectionState.waiting) {
+      return const Center(child: CircularProgressIndicator());
+    }
+
+    final items = snapshot.data ?? [];
+
+    if (items.isEmpty) {
+      return const Center(child: Text('No items found.'));
+    }
+
+    return ListView.builder(
+      itemCount: items.length,
+      itemBuilder: (context, index) {
+        final item = items[index];
+        return ListTile(
+          title: Text(item.name),
+          trailing: IconButton(
+            icon: const Icon(Icons.delete),
+            onPressed: () => itemService.deleteItem(item.id),
+          ),
+        );
+      },
+    );
+  },
+);
+```

package/dist/global-skills/firebase-firestore/references/standard/indexes.md

@@ -0,0 +1,113 @@
+# Firestore Indexes Reference
+
+Indexes allow Firestore to ensure that query performance depends on the size of
+the result set, not the size of the database.
+
+## Index Types
+
+### Single-Field Indexes
+
+In Standard Edition, Firestore **automatically creates** a single-field index
+for every field in a document (and subfields in maps). * **Support**: Simple
+equality queries (`==`) and single-field range/sort queries (`<`, `<=`,
+`orderBy`). * **Behavior**: You generally don't need to manage these unless you
+want to *exempt* a field.
+
+### Composite Indexes
+
+A composite index stores a sorted mapping of all documents based on an ordered
+list of fields. * **Support**: Complex queries that filter or sort by **multiple
+fields**. * **Creation**: These are **NOT** automatically created. You must
+define them manually or via the console/CLI.
+
+## Automatic vs. Manual Management
+
+### What is Automatic?
+
+- Indexes for simple queries.
+- Merging of single-field indexes for multiple equality filters (e.g.,
+  `where("state", "==", "CA").where("country", "==", "USA")`).
+
+### When Do I Need to Act?
+
+If you attempt a query that requires a composite index, the SDK will throw an
+error containing a **direct link** to the Firebase Console to create that
+specific index.
+
+**Example Error:**
+
+> "The query requires an index. You can create it here:
+> https://console.firebase.google.com/project/..."
+
+## Query Support Examples
+
+| Query Type                                                | Index Required                       |
+| :-------------------------------------------------------- | :----------------------------------- |
+| **Simple Equality**<br>\`where("a",                       | Automatic (Single-Field)             |
+| : "==", 1)\` : :                                          |                                      |
+| **Simple Range/Sort**<br>\`where("a",                     | Automatic (Single-Field)             |
+| : ">", 1).orderBy("a")\` : :                              |                                      |
+| **Multiple Equality**<br>\`where("a",                     | Automatic (Merged Single-Field)      |
+| : "==", 1).where("b", "==", 2)\` : :                      |                                      |
+| \*\*Equality +                                            | **Composite Index**                  |
+| : Range/Sort\*\*<br>\`where("a", "==", : :                |                                      |
+| : 1).where("b", ">", 2)\` : :                             |                                      |
+| **Multiple Ranges**<br>\`where("a",                       | **Composite Index** (and technically |
+| : ">", 1).where("b", ">", 2)\` : limited query support) : |                                      |
+| \*\*Array Contains +                                      | **Composite Index**                  |
+| : Equality\*\*<br>\`where("tags", : :                     |                                      |
+| : "array-contains", : :                                   |                                      |
+| : "news").where("active", "==", true)\` : :               |                                      |
+
+## Best Practices & Exemptions
+
+You can **exempt** fields from automatic indexing to save storage or strictly
+enforce write limits.
+
+### 1. High Write Rates (Sequential Values)
+
+- **Problem**: Indexing fields that increase sequentially (like `timestamp`)
+  limits the write rate to ~500 writes/second per collection.
+- **Solution**: If you don't query on this field, **exempt** it from simple
+  indexing.
+
+### 2. Large String/Map/Array Fields
+
+- **Problem**: Indexing limits (40k entries per doc). Indexing large blobs
+  wastes storage.
+- **Solution**: Exempt large text blobs or huge arrays if they aren't used for
+  filtering.
+
+### 3. TTL Fields
+
+- **Problem**: TTL (Time-To-Live) deletion can cause index churn.
+- **Solution**: Exempt the TTL timestamp field from indexing if you don't query
+  it.
+
+## Management
+
+### Config files
+
+Your indexes should be defined in `firestore.indexes.json` (pointed to by
+`firebase.json`).
+
+```json
+{
+  "indexes": [
+    {
+      "collectionGroup": "cities",
+      "queryScope": "COLLECTION",
+      "fields": [
+        { "fieldPath": "country", "order": "ASCENDING" },
+        { "fieldPath": "population", "order": "DESCENDING" }
+      ]
+    }
+  ],
+  "fieldOverrides": []
+}
+```
+
+### CLI Commands
+
+Deploy indexes only:
+`bash npx -y firebase-tools@latest deploy --only firestore:indexes`