vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/firebase-data-connect/reference/cloud_functions.md

@@ -0,0 +1,184 @@
+# Cloud Functions Integration Reference
+
+Use this reference to handle database events in SQL Connect by triggering Cloud
+Functions in response to mutation executions.
+
+______________________________________________________________________
+
+## Core Trigger Configuration
+
+To handle a mutation execution, define the `onMutationExecuted` event handler.
+
+### 🚨 Critical Infinite Loop Constraint
+
+Unlike document-based database triggers (like Firestore or Realtime Database),
+**SQL Connect event triggers do not provide a "before" snapshot of the data.**
+Because SQL Connect proxies requests directly to PostgreSQL, "before" states
+cannot be resolved transactionally.
+
+- **Warning**: If `onMutationExecuted` executes a SQL Connect mutation, it can
+  trigger another `onMutationExecuted` trigger in a cascading loop. Make sure
+  that `onMutationExecuted` has a filter on `operation` to reduce the chance of
+  infinite loops.
+- **Rule**: Ensure that no mutation executed inside the function can ever
+  trigger the handler itself, even indirectly.
+
+### Location & Region Matching Rule
+
+**The Cloud Function region option must match your SQL Connect service
+location.** You **must** explicitly configure the `region` parameter (e.g.,
+`'us-central1'`) in the trigger options to match the `location` specified in
+`dataconnect.yaml`.
+
+```typescript
+import { onMutationExecuted } from "firebase-functions/dataconnect";
+import { logger } from "firebase-functions";
+
+export const logMutation = onMutationExecuted(
+  {
+    region: "europe-west1" // Must match the SQL Connect service location
+  },
+  (event) => {
+    logger.info("A mutation was executed!", {
+      eventId: event.id,
+      type: event.type
+    });
+  }
+);
+```
+
+______________________________________________________________________
+
+## Event Filtering
+
+To prevent unnecessary function invocations and infinite execution loops,
+**always specify narrow filters** using `service` and `operation` attributes.
+
+- **`service` & `operation` (Recommended)**: Always specify these to restrict
+  the trigger to a specific mutation in your project.
+- **`connector` (Optional)**: Can be omitted if you want to trigger on the same
+  operation name across multiple connectors. Specify it only if you need to
+  restrict the trigger to a specific connector.
+
+### Comprehensive Example
+
+```typescript
+import { onMutationExecuted } from "firebase-functions/dataconnect";
+import { logger } from "firebase-functions";
+
+// Triggers for "CreateUser" mutation in "myAppService" service.
+// 'connector' is omitted (optional), meaning it matches "CreateUser" in any connector.
+export const onUserCreate = onMutationExecuted(
+  {
+    service: "myAppService",
+    operation: "CreateUser",
+    // region: "us-central1" // Optional: defaults to us-central1, change if database is elsewhere
+  },
+  (event) => {
+    logger.info("A new user was created!");
+  }
+);
+
+// Advanced: Trigger using wildcards or capture variables
+export const onMutationCaptures = onMutationExecuted(
+  {
+    service: "myAppService",
+    operation: "{operation}", // Captures matching operation name dynamically
+  },
+  (event) => {
+    const triggeredOp = event.params.operation;
+    logger.info(`Captured operation execution: ${triggeredOp}`);
+  }
+);
+```
+
+______________________________________________________________________
+
+## Accessing User Authentication Context
+
+Extract security credentials about the caller who executed the mutation using
+`event.authType` and `event.authId`.
+
+### Auth Context Mappings
+
+| Triggered Principal                  | `event.authType`    | `event.authId`                                   |
+| :----------------------------------- | :------------------ | :----------------------------------------------- |
+| **Authenticated end user**           | `"app_user"`        | Firebase Auth token UID                          |
+| **Unauthenticated end user**         | `"unauthenticated"` | Empty                                            |
+| **Admin SDK (Impersonating User)**   | `"app_user"`        | Firebase Auth token UID of the impersonated user |
+| **Admin SDK (Impersonating Unauth)** | `"unauthenticated"` | Empty                                            |
+| **Admin SDK (Full privileges)**      | `"admin"`           | Empty                                            |
+
+### Auth Extraction Example
+
+```typescript
+export const processSensitiveMutation = onMutationExecuted(
+  { operation: "UpdateFinancials" },
+  (event) => {
+    if (event.authType === "admin") {
+      console.log("Elevated admin mutation execution.");
+    } else {
+      console.log(`Mutation initiated by user: ${event.authId}`);
+    }
+  }
+);
+```
+
+______________________________________________________________________
+
+## Parsing Event Data Payloads
+
+The trigger payload provides inputs passed to the mutation (`payload.variables`)
+and return values generated from the execution (`payload.data`).
+
+### Event Payload Structure
+
+```json
+{
+  "authType": "app_user",
+  "authId": "user-123",
+  "data": {
+    "payload": {
+      "variables": {
+        "movieId": "m-1",
+        "rating": 5
+      },
+      "data": {
+        "review_insert": {
+          "id": "r-99"
+        }
+      },
+      "errors": []
+    }
+  }
+}
+```
+
+- **`event.data.payload.variables`**: Inputs passed to the mutation.
+- **`event.data.payload.data`**: Fields returned by the mutation execution.
+- **`event.data.payload.errors`**: Array of execution errors. Empty if
+  successful.
+
+### Payload Extraction Example
+
+```typescript
+import { onMutationExecuted } from "firebase-functions/dataconnect";
+import { logger } from "firebase-functions";
+
+export const onNewReview = onMutationExecuted(
+  {
+    service: "myAppService",
+    connector: "reviews",
+    operation: "CreateReview",
+  },
+  (event) => {
+    // Extract input variables passed to the mutation
+    const inputVariables = event.data.payload.variables;
+
+    // Extract returned fields from the database write
+    const returnedFields = event.data.payload.data;
+
+    logger.info(`Processed review ${returnedFields.review_insert.id} for movie ${inputVariables.movieId}`);
+  }
+);
+```

package/dist/global-skills/firebase-data-connect/reference/config.md

@@ -0,0 +1,271 @@
+# Configuration Reference
+
+## Contents
+
+- [Project Structure](#project-structure)
+- [dataconnect.yaml](#dataconnectyaml)
+- [connector.yaml](#connectoryaml)
+- [Firebase CLI Commands](#firebase-cli-commands)
+- [Emulator](#emulator)
+- [Deployment](#deployment)
+
+______________________________________________________________________
+
+## Project Structure
+
+```
+project-root/
+├── firebase.json           # Firebase project config
+└── dataconnect/
+    ├── dataconnect.yaml    # Service configuration
+    ├── schema/
+    │   └── schema.gql      # Data model (types, relationships)
+    └── connector/
+        ├── connector.yaml  # Connector config + SDK generation
+        ├── queries.gql     # Query operations
+        └── mutations.gql   # Mutation operations (optional separate file)
+```
+
+______________________________________________________________________
+
+## dataconnect.yaml
+
+Main SQL Connect service configuration:
+
+```yaml
+specVersion: "v1"
+serviceId: "my-service"
+location: "us-central1"
+schemaValidation: "STRICT" # or "COMPATIBLE"
+schema:
+  source: "./schema"
+  datasource:
+    postgresql:
+      database: "fdcdb"
+      cloudSql:
+        instanceId: "my-instance"
+connectorDirs: ["./connector"]
+```
+
+| Field               | Description                                                                              |
+| ------------------- | ---------------------------------------------------------------------------------------- |
+| `specVersion`       | Always `"v1"`                                                                            |
+| `serviceId`         | Unique identifier for the service                                                        |
+| `location`          | GCP region (us-central1, us-east4, europe-west1, etc.)                                   |
+| `schemaValidation`  | Deployment mode: `"STRICT"` (must match exactly) or `"COMPATIBLE"` (backward compatible) |
+| `schema.source`     | Path to schema directory                                                                 |
+| `schema.datasource` | PostgreSQL connection config                                                             |
+| `connectorDirs`     | List of connector directories                                                            |
+
+### Cloud SQL Configuration
+
+```yaml
+schema:
+  datasource:
+    postgresql:
+      database: "my-database"      # Database name
+      cloudSql:
+        instanceId: "my-instance"  # Cloud SQL instance ID
+```
+
+______________________________________________________________________
+
+## connector.yaml
+
+Connector configuration and SDK generation:
+
+```yaml
+connectorId: "default"
+generate:
+  javascriptSdk:
+    outputDir: "../web/src/lib/dataconnect"
+    package: "@myapp/dataconnect"
+  kotlinSdk:
+    outputDir: "../android/app/src/main/kotlin/com/myapp/dataconnect"
+    package: "com.myapp.dataconnect"
+  swiftSdk:
+    outputDir: "../ios/MyApp/DataConnect"
+```
+
+### SDK Generation Options
+
+| SDK             | Fields                                 |
+| --------------- | -------------------------------------- |
+| `javascriptSdk` | `outputDir`, `package`                 |
+| `kotlinSdk`     | `outputDir`, `package`                 |
+| `swiftSdk`      | `outputDir`                            |
+| `nodeAdminSdk`  | `outputDir`, `package` (for Admin SDK) |
+
+______________________________________________________________________
+
+## Firebase CLI Commands
+
+### Initialize SQL Connect
+
+```bash
+# Interactive setup
+npx -y firebase-tools@latest init dataconnect
+
+# Set project
+npx -y firebase-tools@latest use <project-id>
+```
+
+### Local Development
+
+```bash
+# Start emulator
+npx -y firebase-tools@latest emulators:start --only dataconnect
+
+# Start with database seed data
+npx -y firebase-tools@latest emulators:start --only dataconnect --import=./seed-data
+
+# Generate SDKs
+npx -y firebase-tools@latest dataconnect:sdk:generate
+
+# Watch for schema changes (auto-regenerate)
+npx -y firebase-tools@latest dataconnect:sdk:generate --watch
+```
+
+### Schema Management
+
+```bash
+# Compare local schema to production
+npx -y firebase-tools@latest dataconnect:sql:diff
+
+
+# Apply migration
+npx -y firebase-tools@latest dataconnect:sql:migrate
+```
+
+### Deployment
+
+```bash
+# Deploy SQL Connect service
+npx -y firebase-tools@latest deploy --only dataconnect
+
+# Deploy specific connector
+npx -y firebase-tools@latest deploy --only dataconnect:connector-id
+
+# Deploy with schema migration
+npx -y firebase-tools@latest deploy --only dataconnect --force
+```
+
+______________________________________________________________________
+
+## Emulator
+
+### Start Emulator
+
+```bash
+npx -y firebase-tools@latest emulators:start --only dataconnect
+```
+
+Default ports:
+
+- SQL Connect: `9399`
+- PostgreSQL: `9939` (local PostgreSQL instance)
+
+### Emulator Configuration (firebase.json)
+
+```json
+{
+  "emulators": {
+    "dataconnect": {
+      "port": 9399
+    }
+  }
+}
+```
+
+### Connect from SDK
+
+```typescript
+// Web
+import { connectDataConnectEmulator } from 'firebase/data-connect';
+connectDataConnectEmulator(dc, 'localhost', 9399);
+
+// Android
+connector.dataConnect.useEmulator("10.0.2.2", 9399)
+
+// iOS
+connector.useEmulator(host: "localhost", port: 9399)
+
+
+```
+
+### Seed Data
+
+Create seed data files and import:
+
+```bash
+# Export current emulator data
+npx -y firebase-tools@latest emulators:export ./seed-data
+
+# Start with seed data
+npx -y firebase-tools@latest emulators:start --only dataconnect --import=./seed-data
+```
+
+______________________________________________________________________
+
+## Deployment
+
+### Deploy Workflow
+
+1. **Test locally** with emulator
+1. **Generate SQL diff**: `npx -y firebase-tools@latest dataconnect:sql:diff`
+1. **Review migration**: Check breaking changes
+1. **Deploy**: `npx -y firebase-tools@latest deploy --only dataconnect`
+
+### Schema Migrations
+
+SQL Connect auto-generates PostgreSQL migrations:
+
+```bash
+# Preview migration
+npx -y firebase-tools@latest dataconnect:sql:diff
+
+# Apply migration (interactive)
+npx -y firebase-tools@latest dataconnect:sql:migrate
+
+# Force migration (non-interactive)
+npx -y firebase-tools@latest dataconnect:sql:migrate --force
+```
+
+### Breaking Changes
+
+Some schema changes require special handling:
+
+- Removing required fields
+- Changing field types
+- Removing tables
+
+Use `--force` flag to acknowledge breaking changes during deploy.
+
+### CI/CD Integration
+
+```yaml
+# GitHub Actions example
+- name: Deploy SQL Connect
+  run: |
+    npx -y firebase-tools@latest deploy --only dataconnect --token ${{ secrets.FIREBASE_TOKEN }} --force
+```
+
+______________________________________________________________________
+
+## VS Code Extension
+
+Install "Firebase SQL Connect" extension for:
+
+- Schema intellisense and validation
+- GraphQL operation testing
+- Emulator integration
+- SDK generation on save
+
+### Extension Settings
+
+```json
+{
+  "firebase.dataConnect.autoGenerateSdk": true,
+  "firebase.dataConnect.emulator.port": 9399
+}
+```

package/dist/global-skills/firebase-data-connect/reference/data_seeding.md

@@ -0,0 +1,185 @@
+# Data Seeding & Bulk Operations Reference
+
+Use this reference to populate local development databases for prototyping,
+execute CI/CD tests, and perform bulk data migrations in production
+environments.
+
+______________________________________________________________________
+
+## 1. Local Prototyping: Data Seeding
+
+Local database seeding allows developer agents to test queries, mutations,
+complex joins, and role-based access control (RBAC) under realistic conditions.
+
+### The `seed_data.gql` Workflow
+
+**Always write prototyping seed mutations to `dataconnect/seed_data.gql`**
+(located at the project root, not inside `connector/`). This file is excluded
+from production deployments and client SDK generation.
+
+#### ⚠️ Seeding Directives Rule
+
+**Do not declare `@auth` directives inside `seed_data.gql` mutations.** Since
+this file runs locally to establish a test state and is not an exposed API
+connector endpoint, authorization directives are completely unnecessary and
+should be omitted.
+
+### Seeding Independent Tables (FK Order)
+
+When executing standard bulk insertions (`_insertMany`) across multiple tables,
+**always insert parent tables before referencing them in child or join tables.**
+
+```graphql
+# dataconnect/seed_data.gql
+mutation SeedIndependentTables @transaction {
+  # Step 1: Seed parent tables
+  movie_insertMany(data: [
+    { id: "m-1", title: "Inception", genre: "sci-fi" },
+    { id: "m-2", title: "The Matrix", genre: "action" }
+  ])
+
+  actor_insertMany(data: [
+    { id: "a-1", name: "Leonardo DiCaprio" },
+    { id: "a-2", name: "Keanu Reeves" }
+  ])
+
+  # Step 2: Seed join table (depends on pre-existing parent IDs)
+  movieActor_insertMany(data: [
+    { movie: { id: "m-1" }, actor: { id: "a-1" }, role: "main" },
+    { movie: { id: "m-2" }, actor: { id: "a-2" }, role: "main" }
+  ])
+}
+```
+
+### Seeding Related Tables (Nested Relational Inserts)
+
+**To seed parent-child relationships atomically, perform a nested relational
+insert using literal payloads.** This avoids the need to manage foreign keys
+manually.
+
+- **Omit Parent Foreign Keys**: **Do not specify the parent foreign key** (e.g.
+  `movieId`) inside the nested child objects. The database engine automatically
+  maps and resolves them.
+
+```graphql
+# dataconnect/seed_data.gql
+mutation SeedMoviesAndReviews @transaction {
+  movie_insert(data: {
+    id: "m-1",
+    title: "Inception",
+    genre: "sci-fi",
+    # Nested reviews are inserted atomically without manual movieId mapping
+    reviews_on_movie: [
+      {
+        id: "r-1",
+        rating: 5,
+        reviewText: "Mind-bending masterpiece!",
+        user: { id: "user-123" } # Links to pre-existing user
+      },
+      {
+        id: "r-2",
+        rating: 4,
+        reviewText: "Visually stunning but complex.",
+        user: { id: "user-456" }
+      }
+    ]
+  })
+}
+```
+
+### Resetting Seed Data
+
+For continuous testing or CI/CD flows, return the database to a zero state using
+one of the following strategies:
+
+- **Strategy A: Upsert Many (Idempotent)**: Re-run seeds using `_upsertMany`
+  mutations. This overrides existing records or inserts missing ones in a single
+  step.
+- **Strategy B: Delete and Re-Insert**: Call `_deleteMany(all: true)` on your
+  tables in **reverse foreign key order** (child/join tables first, then parent
+  tables) followed by your seed `_insertMany` operations.
+
+```graphql
+# dataconnect/seed_data.gql
+mutation ResetDatabaseToOriginalState @transaction {
+  # Delete child tables first to prevent FK constraint violations
+  movieActor_deleteMany(all: true)
+  actor_deleteMany(all: true)
+  movie_deleteMany(all: true)
+  # (Optional) Follow up with new _insertMany steps
+}
+```
+
+______________________________________________________________________
+
+## 2. Production: Admin SDK Bulk Operations
+
+**Use the Firebase Admin SDK for Node.js for bulk data loading and production
+migrations.** Avoid running large mutations directly via raw GraphQL endpoints
+in production.
+
+The Admin SDK provides direct, type-safe methods: `dc.insert`, `dc.insertMany`,
+`dc.upsert`, and `dc.upsertMany`.
+
+### SDK Bulk APIs Features:
+
+- **No Manual GraphQL Strings**: Do not write raw `mutation {...}` strings when
+  executing privileged batch operations. Pass Javascript objects directly.
+- **Relational Support**: The bulk helper methods natively support nested 1:Many
+  relationships inside the input arrays.
+
+### SDK Bulk Operations Example
+
+```typescript
+import { initializeApp } from 'firebase-admin/app';
+import { getDataConnect } from 'firebase-admin/data-connect';
+
+const app = initializeApp();
+const dc = getDataConnect({ location: "us-west2", serviceId: "my-service" });
+
+const bulkMoviesData = [
+  {
+    id: "m-1",
+    title: "Inception",
+    genre: "sci-fi",
+    // Atomic nested relational inserts are fully supported
+    reviews_on_movie: [
+      {
+        rating: 5,
+        reviewText: "Incredible concept.",
+        user: { id: "user-123" }
+      }
+    ]
+  },
+  {
+    id: "m-2",
+    title: "The Matrix",
+    genre: "action",
+    reviews_on_movie: [
+      {
+        rating: 5,
+        reviewText: "A classic.",
+        user: { id: "user-456" }
+      }
+    ]
+  }
+];
+
+// Atomically load thousands of records (parent and child tables combined)
+const response = await dc.insertMany("movie", bulkMoviesData);
+```
+
+______________________________________________________________________
+
+## 3. Production: Bulk Operations via raw SQL
+
+When working with a stable schema in production, you can use standard SQL tools
+(like `psql` or Cloud SQL import pipelines) to execute bulk data updates
+directly on the PostgreSQL instance.
+
+### 🚨 Critical SQL Operations Constraint
+
+**Never modify your database schema directly using SQL tools.** Direct schema
+alterations (`ALTER TABLE`, `CREATE INDEX`, etc.) outside of your `schema.gql`
+file will bypass SQL Connect's schema compiler, breaking connector mappings, and
+causing active client SDK integrations to fail.