vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/firebase-app-hosting-basics/references/configuration.md

@@ -0,0 +1,59 @@
+# App Hosting Configuration (`apphosting.yaml`)
+
+The `apphosting.yaml` file is the source of truth for your backend's
+configuration. It must be located in the root of your app's directory (or the
+specific root directory if using a monorepo).
+
+## File Structure
+
+```yaml
+# apphosting.yaml
+
+# Cloud Run service configuration
+runConfig:
+  cpu: 1
+  memoryMiB: 512
+  minInstances: 0
+  maxInstances: 100
+  concurrency: 80
+
+# Environment variables
+env:
+  - variable: STORAGE_BUCKET
+    value: mybucket.app
+    availability:
+      - BUILD
+      - RUNTIME
+  - variable: API_KEY
+    secret: myApiKeySecret
+```
+
+## `runConfig`
+
+Controls the resources allocated to the Cloud Run service that serves your app.
+
+- `cpu`: Number of vCPUs. Note: If `< 1`, concurrency MUST be set to `1`.
+- `memoryMiB`: RAM in MiB (128 to 32768).
+- `minInstances`: Minimum containers to keep warm (default 0). Set to >= 1 to
+  avoid cold starts.
+- `maxInstances`: Maximum scaling limit (default 100).
+- `concurrency`: Max concurrent requests per instance (default 80).
+
+### Resource Constraints
+
+- **CPU vs Memory**: Higher memory often requires higher CPU.
+  - > 4GiB RAM -> Needs >= 2 vCPU
+  - > 8GiB RAM -> Needs >= 4 vCPU
+
+## `env` (Environment Variables)
+
+Defines environment variables available during build and/or runtime.
+
+- `variable`: The name of the env var (e.g., `NEXT_PUBLIC_API_URL`).
+- `value`: A literal string value.
+- `secret`: The name of a secret in Cloud Secret Manager. use
+  `npx -y firebase-tools@latest apphosting:secrets:set` to create these.
+- `availability`: Where the variable is needed.
+  - `BUILD`: Available during the `npm run build` process.
+  - `RUNTIME`: Available when the app is serving requests.
+  - Defaults to both if not specified.

package/dist/global-skills/firebase-app-hosting-basics/references/emulation.md

@@ -0,0 +1,59 @@
+# App Hosting Emulation
+
+You can test your App Hosting setup locally using the Firebase Local Emulator
+Suite. This allows you to verify your app's behavior with environment variables
+and secrets before deploying.
+
+## Configuration: `apphosting.emulator.yaml`
+
+This optional file overrides `apphosting.yaml` settings specifically for the
+local emulator. Use it to provide local secret values or override resource
+configs. If it contains sensitive values such as API keys, do not commit it to
+source control.
+
+```yaml
+# apphosting.emulator.yaml (gitignored usually)
+runConfig:
+  cpu: 1
+  memoryMiB: 512
+
+env:
+  - variable: API_KEY
+    value: "local-dev-api-key" # Override secret with local value
+```
+
+## Running the Emulator
+
+To start the App Hosting emulator:
+
+```bash
+npx -y firebase-tools@latest emulators:start --only apphosting
+```
+
+Or, if you are also using other emulators (Auth, Firestore, etc.):
+
+```bash
+npx -y firebase-tools@latest emulators:start
+```
+
+## Capabilities
+
+- **Builds your app**: Runs the build command defined in your `package.json` to
+  generate the serving artifact.
+- **Serves locally**: Runs the app on `localhost:5004` (default). Configurable
+  by setting `host` and `port` in the `emulators` block of `firebase.json`, like
+  so:
+
+```json
+{
+  "emulators": {
+    "apphosting": {
+      "host": "localhost",
+      "port": 5004
+    }
+  }
+}
+```
+
+- **Env Var Injection**: Injects variables defined in `apphosting.yaml` and
+  `apphosting.emulator.yaml` into the process.

package/dist/global-skills/firebase-auth-basics/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: firebase-auth-basics
+description: Guide for setting up and using Firebase Authentication. Use this skill when the user's app requires user sign-in, user management, or secure data access using auth rules.
+compatibility: This skill is best used with the Firebase CLI, but does not require it. Firebase CLI can be accessed through `npx -y firebase-tools@latest`.
+---
+
+## Prerequisites
+
+- **Firebase Project**: Created via
+  `npx -y firebase-tools@latest projects:create` (see `firebase-basics`).
+- **Firebase CLI**: Installed and logged in (see `firebase-basics`).
+
+## Core Concepts
+
+Firebase Authentication provides backend services, easy-to-use SDKs, and
+ready-made UI libraries to authenticate users to your app.
+
+### Users
+
+A user is an entity that can sign in to your app. Each user is identified by a
+unique ID (`uid`) which is guaranteed to be unique across all providers. User
+properties include:
+
+- `uid`: Unique identifier.
+- `email`: User's email address (if available).
+- `displayName`: User's display name (if available).
+- `photoURL`: URL to user's photo (if available).
+- `emailVerified`: Boolean indicating if the email is verified.
+
+### Identity Providers
+
+Firebase Auth supports multiple ways to sign in:
+
+- **Email/Password**: Basic email and password authentication.
+- **Federated Identity Providers**: Google, Facebook, Twitter, GitHub,
+  Microsoft, Apple, etc.
+- **Phone Number**: SMS-based authentication.
+- **Anonymous**: Temporary guest accounts that can be linked to permanent
+  accounts later.
+- **Custom Auth**: Integrate with your existing auth system.
+
+Google Sign In is recommended as a good and secure default provider.
+
+### Tokens
+
+When a user signs in, they receive an ID Token (JWT). This token is used to
+identify the user when making requests to Firebase services (Realtime Database,
+Cloud Storage, Firestore) or your own backend.
+
+- **ID Token**: Short-lived (1 hour), verifies identity.
+- **Refresh Token**: Long-lived, used to get new ID tokens.
+
+## Workflow
+
+### 1. Provisioning
+
+#### Option 1. Enabling Authentication via CLI
+
+Only Google Sign In, anonymous auth, and email/password auth can be enabled via
+CLI. For other providers, use the Firebase Console.
+
+Configure Firebase Authentication in `firebase.json` by adding an 'auth' block:
+
+```
+{
+  "auth": {
+    "providers": {
+      "anonymous": true,
+      "emailPassword": true,
+      "googleSignIn": {
+        "oAuthBrandDisplayName": "Your Brand Name",
+        "supportEmail": "support@example.com",
+        "authorizedRedirectUris": ["https://example.com", "http://localhost"]
+      }
+    }
+  }
+}
+```
+
+> [!NOTE] If the Google Sign-In popup opens and immediately closes with the
+> error `[firebase_auth/unauthorized-domain]`, it means the domain is not
+> authorized. For local development, ensure `localhost` is included in the
+> **Authorized Domains** list in the Firebase Console or via the
+> `authorizedDomains` field in `firebase.json`. **CRITICAL**: Do NOT include the
+> protocol or port number in the Authorized Domains list (e.g., use `localhost`,
+> NOT `http://localhost:9090`).
+
+**CRITICAL**: After configuring `firebase.json`, you MUST deploy the auth
+configuration to the Firebase backend for the changes to take effect. This is
+essential for auth providers like Google Sign-In, email/password, etc. to
+auto-generate the necessary OAuth clients for your app platforms. Run:
+
+```bash
+npx -y firebase-tools@latest deploy --only auth
+```
+
+#### Option 2. Enabling Authentication in Console
+
+Enable other providers in the Firebase Console.
+
+1. Go to the
+   https://console.firebase.google.com/project/_/authentication/providers
+1. Select your project.
+1. Enable the desired Sign-in providers (e.g., Email/Password, Google).
+
+### 2. Client Setup & Usage
+
+**Web** See [references/client_sdk_web.md](references/client_sdk_web.md).
+
+**Flutter** See [references/flutter_setup.md](references/flutter_setup.md).
+**Android (Kotlin)** See
+[references/client_sdk_android.md](references/client_sdk_android.md).
+
+### 3. Security Rules
+
+Secure your data using `request.auth` in Firestore/Storage rules.
+
+See [references/security_rules.md](references/security_rules.md).

package/dist/global-skills/firebase-auth-basics/references/client_sdk_android.md

@@ -0,0 +1,160 @@
+# Firebase Authentication on Android (Kotlin)
+
+This guide walks you through using Firebase Authentication in your Android app
+using Kotlin DSL (`build.gradle.kts`) and Kotlin code.
+
+### 1, Enable Authentication via CLI
+
+Before adding dependencies in your app, make sure you enable the Auth service in
+your Firebase Project using the Firebase CLI:
+
+```bash
+npx -y firebase-tools@latest init auth
+```
+
+______________________________________________________________________
+
+### 2. Add Dependencies
+
+In your module-level `build.gradle.kts` (usually `app/build.gradle.kts`), add
+the dependency for Firebase Authentication:
+
+```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 Firebase Authentication library
+    // When using the BoM, you don't specify versions in Firebase library dependencies
+    implementation("com.google.firebase:firebase-auth")
+}
+```
+
+______________________________________________________________________
+
+### 3. Initialize FirebaseAuth
+
+In your Activity or Fragment, initialize the `FirebaseAuth` instance:
+
+```kotlin
+import com.google.firebase.auth.FirebaseAuth
+import com.google.firebase.auth.ktx.auth
+import com.google.firebase.ktx.Firebase
+
+class MainActivity : AppCompatActivity() {
+
+    private lateinit var auth: FirebaseAuth
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val auth = Firebase.auth
+        
+        setContent {
+            MaterialTheme {
+                Text("Auth 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.auth.auth
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val auth = Firebase.auth
+        
+        setContent {
+            MaterialTheme {
+                Text("Auth initialized!")
+            }
+        }
+    }
+}
+```
+
+______________________________________________________________________
+
+### 4. Check Current Auth State
+
+You should check if a user is already signed in when your activity starts:
+
+```kotlin
+public override fun onStart() {
+    super.onStart()
+    // Check if user is signed in (non-null) and update UI accordingly.
+    val currentUser = auth.currentUser
+    if (currentUser != null) {
+        // User is signed in, navigate to main screen or update UI
+    } else {
+        // No user is signed in, prompt for login
+    }
+}
+```
+
+______________________________________________________________________
+
+### 5. Sign Up New Users (Email/Password)
+
+Use `createUserWithEmailAndPassword` to register new users:
+
+```kotlin
+fun signUpUser(email: String, password: String) {
+    auth.createUserWithEmailAndPassword(email, password)
+        .addOnCompleteListener(this) { task ->
+            if (task.isSuccessful) {
+                // Sign up success, update UI with the signed-in user's information
+                val user = auth.currentUser
+                // Navigate to main screen
+            } else {
+                // If sign up fails, display a message to the user.
+                Toast.makeText(baseContext, "Authentication failed.", Toast.LENGTH_SHORT).show()
+            }
+        }
+}
+```
+
+______________________________________________________________________
+
+### 6. Sign In Existing Users (Email/Password)
+
+Use `signInWithEmailAndPassword` to log in existing users:
+
+```kotlin
+fun signInUser(email: String, password: String) {
+    auth.signInWithEmailAndPassword(email, password)
+        .addOnCompleteListener(this) { task ->
+            if (task.isSuccessful) {
+                // Sign in success, update UI with the signed-in user's information
+                val user = auth.currentUser
+                // Navigate to main screen
+            } else {
+                // If sign in fails, display a message to the user.
+                Toast.makeText(baseContext, "Authentication failed.", Toast.LENGTH_SHORT).show()
+            }
+        }
+}
+```
+
+______________________________________________________________________
+
+### 7. Sign Out
+
+To sign out a user, call `signOut()` on the `FirebaseAuth` instance:
+
+```kotlin
+auth.signOut()
+// Navigate to login screen
+```

package/dist/global-skills/firebase-auth-basics/references/client_sdk_web.md

@@ -0,0 +1,301 @@
+# Firebase Authentication Web SDK
+
+## Initialization
+
+First, ensure you have initialized the Firebase App (see `firebase-basics`
+skill). Then, initialize the Auth service:
+
+```javascript
+import { getAuth } from "firebase/auth";
+import { app } from "./firebase"; // Your initialized Firebase App
+
+const auth = getAuth(app);
+export { auth };
+```
+
+## Connect to Emulator
+
+If you are running the Authentication emulator (usually on port 9099), connect
+to it immediately after initialization.
+
+```javascript
+import { getAuth, connectAuthEmulator } from "firebase/auth";
+
+const auth = getAuth();
+// Connect to emulator if running locally
+if (location.hostname === "localhost") {
+  connectAuthEmulator(auth, "http://localhost:9099");
+}
+```
+
+## Sign Up with Email/Password
+
+```javascript
+import { getAuth, createUserWithEmailAndPassword } from "firebase/auth";
+
+const auth = getAuth();
+createUserWithEmailAndPassword(auth, email, password)
+  .then((userCredential) => {
+    const user = userCredential.user;
+    // ...
+  })
+  .catch((error) => {
+    const errorCode = error.code;
+    const errorMessage = error.message;
+    // ..
+  });
+```
+
+## Sign In with Google (Popup)
+
+```javascript
+import { getAuth, signInWithPopup, GoogleAuthProvider } from "firebase/auth";
+
+const auth = getAuth();
+const provider = new GoogleAuthProvider();
+
+signInWithPopup(auth, provider)
+  .then((result) => {
+    // This gives you a Google Access Token. You can use it to access the Google API.
+    const credential = GoogleAuthProvider.credentialFromResult(result);
+    const token = credential.accessToken;
+    // The signed-in user info.
+    const user = result.user;
+    // ...
+  })
+  .catch((error) => {
+    // Handle Errors here.
+    const errorCode = error.code;
+    const errorMessage = error.message;
+    // ...
+  });
+```
+
+> [!IMPORTANT] **Troubleshooting `auth/unauthorized-domain`**: If the popup
+> opens and immediately closes with error `[firebase_auth/unauthorized-domain]`,
+> it means the domain hosting your app is not authorized for OAuth operations in
+> your Firebase project.
+>
+> - **Fix**: Add your domain (e.g., `localhost` for local testing) to the
+>   Authorized Domains list in the Firebase Console (Authentication > Settings >
+>   Authorized domains) or in your `firebase.json` auth config.
+> - **CRITICAL**: Do NOT include the protocol or port number when adding the
+>   domain (e.g., use `localhost`, NOT `http://localhost:9090`).
+
+## Sign In with Facebook (Popup)
+
+```javascript
+import { getAuth, signInWithPopup, FacebookAuthProvider } from "firebase/auth";
+
+const auth = getAuth();
+const provider = new FacebookAuthProvider();
+
+signInWithPopup(auth, provider)
+  .then((result) => {
+    // The signed-in user info.
+    const user = result.user;
+    // This gives you a Facebook Access Token. You can use it to access the Facebook API.
+    const credential = FacebookAuthProvider.credentialFromResult(result);
+    const accessToken = credential.accessToken;
+  })
+  .catch((error) => {
+    // Handle Errors here.
+  });
+```
+
+## Sign In with Apple (Popup)
+
+```javascript
+import { getAuth, signInWithPopup, OAuthProvider } from "firebase/auth";
+
+const auth = getAuth();
+const provider = new OAuthProvider('apple.com');
+
+signInWithPopup(auth, provider)
+  .then((result) => {
+    const user = result.user;
+    // Apple credential
+    const credential = OAuthProvider.credentialFromResult(result);
+    const accessToken = credential.accessToken;
+  })
+  .catch((error) => {
+    // Handle Errors here.
+  });
+```
+
+## Sign In with Twitter (Popup)
+
+```javascript
+import { getAuth, signInWithPopup, TwitterAuthProvider } from "firebase/auth";
+
+const auth = getAuth();
+const provider = new TwitterAuthProvider();
+
+signInWithPopup(auth, provider)
+  .then((result) => {
+    const user = result.user;
+    // Twitter credential
+    const credential = TwitterAuthProvider.credentialFromResult(result);
+    const token = credential.accessToken;
+    const secret = credential.secret;
+  })
+  .catch((error) => {
+    // Handle Errors here.
+  });
+```
+
+## Sign In with GitHub (Popup)
+
+```javascript
+import { getAuth, signInWithPopup, GithubAuthProvider } from "firebase/auth";
+
+const auth = getAuth();
+const provider = new GithubAuthProvider();
+
+signInWithPopup(auth, provider)
+  .then((result) => {
+    const user = result.user;
+    const credential = GithubAuthProvider.credentialFromResult(result);
+    const token = credential.accessToken;
+  })
+  .catch((error) => {
+    // Handle Errors here.
+  });
+```
+
+## Sign In with Microsoft (Popup)
+
+```javascript
+import { getAuth, signInWithPopup, OAuthProvider } from "firebase/auth";
+
+const auth = getAuth();
+const provider = new OAuthProvider('microsoft.com');
+
+signInWithPopup(auth, provider)
+  .then((result) => {
+    const user = result.user;
+    const credential = OAuthProvider.credentialFromResult(result);
+    const accessToken = credential.accessToken;
+  })
+  .catch((error) => {
+    // Handle Errors here.
+  });
+```
+
+## Sign In with Yahoo (Popup)
+
+```javascript
+import { getAuth, signInWithPopup, OAuthProvider } from "firebase/auth";
+
+const auth = getAuth();
+const provider = new OAuthProvider('yahoo.com');
+
+signInWithPopup(auth, provider)
+  .then((result) => {
+    const user = result.user;
+    const credential = OAuthProvider.credentialFromResult(result);
+    const accessToken = credential.accessToken;
+  })
+  .catch((error) => {
+    // Handle Errors here.
+  });
+```
+
+## Sign In Anonymously
+
+```javascript
+import { getAuth, signInAnonymously } from "firebase/auth";
+
+const auth = getAuth();
+signInAnonymously(auth)
+  .then(() => {
+    // Signed in..
+  })
+  .catch((error) => {
+    const errorCode = error.code;
+    const errorMessage = error.message;
+  });
+```
+
+## Email Link Authentication
+
+**1. Send Auth Link**
+
+```javascript
+import { getAuth, sendSignInLinkToEmail } from "firebase/auth";
+
+const auth = getAuth();
+const actionCodeSettings = {
+  // URL you want to redirect back to. The domain must be in the authorized domains list in Firebase Console.
+  url: 'https://www.example.com/finishSignUp?cartId=1234',
+  handleCodeInApp: true,
+};
+
+sendSignInLinkToEmail(auth, email, actionCodeSettings)
+  .then(() => {
+    // Save the email locally so you don't need to ask the user for it again
+    window.localStorage.setItem('emailForSignIn', email);
+  })
+  .catch((error) => {
+    // Error
+  });
+```
+
+**2. Complete Sign In (on landing page)**
+
+```javascript
+import { getAuth, isSignInWithEmailLink, signInWithEmailLink } from "firebase/auth";
+
+const auth = getAuth();
+
+if (isSignInWithEmailLink(auth, window.location.href)) {
+  let email = window.localStorage.getItem('emailForSignIn');
+  if (!email) {
+    email = window.prompt('Please provide your email for confirmation');
+  }
+
+  signInWithEmailLink(auth, email, window.location.href)
+    .then((result) => {
+      window.localStorage.removeItem('emailForSignIn');
+      // You can check result.user
+    })
+    .catch((error) => {
+      // Error
+    });
+}
+```
+
+## Observe Auth State
+
+Recommended way to get the current user. This listener triggers whenever the
+user signs in or out.
+
+```javascript
+import { getAuth, onAuthStateChanged } from "firebase/auth";
+
+const auth = getAuth();
+onAuthStateChanged(auth, (user) => {
+  if (user) {
+    // User is signed in, see docs for a list of available properties
+    // https://firebase.google.com/docs/reference/js/firebase.User
+    const uid = user.uid;
+    // ...
+  } else {
+    // User is signed out
+    // ...
+  }
+});
+```
+
+## Sign Out
+
+```javascript
+import { getAuth, signOut } from "firebase/auth";
+
+const auth = getAuth();
+signOut(auth).then(() => {
+  // Sign-out successful.
+}).catch((error) => {
+  // An error happened.
+});
+```