vybekiit 0.4.0 → 0.6.0

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

@@ -0,0 +1,210 @@
+# Realtime Reference
+
+## Contents
+
+- [When to Use What](#when-to-use-what)
+- [The @refresh Directive](#the-refresh-directive)
+- [CEL Bindings in Conditions](#cel-bindings-in-conditions)
+- [Implicit Entity Refresh signals](#implicit-entity-refresh-signals)
+
+______________________________________________________________________
+
+## When to Use What
+
+SQL Connect provides three mechanisms for live data updates. Pick the right one
+based on what you're querying:
+
+| Scenario                                                    | Mechanism                | Directive Needed?                   |
+| ----------------------------------------------------------- | ------------------------ | ----------------------------------- |
+| Single-entity lookup by ID (e.g., `movie(id: $id)`)         | **Automatic refresh**    | No — SQL Connect handles it         |
+| List query that should update when a specific mutation runs | **Event-driven refresh** | `@refresh(onMutationExecuted: ...)` |
+| Any query that should poll at a fixed interval              | **Time-based polling**   | `@refresh(every: ...)`              |
+
+List queries require explicit `@refresh` to tell SQL Connect which mutations
+affect the result set.
+
+Clients consume all three using `subscribe()` instead of `execute()`. See
+[sdks.md](sdks.md) for per-platform subscribe patterns.
+
+______________________________________________________________________
+
+## The @refresh Directive
+
+`@refresh` is a **repeatable** directive applied to **queries**. It defines when
+connected subscribers should receive updated data.
+
+### Time-Based Polling (`every`)
+
+Keep the query fresh with a recommended refresh interval. Note that `every` and
+`mutation` signals can be used together; whichever signal arrives first will
+trigger the refresh.
+
+```graphql
+query MovieLeaderboard
+  @auth(level: PUBLIC)
+  @refresh(every: { seconds: 30 }) {
+  movies(orderBy: [{ rating: DESC }], limit: 10) {
+    id title rating
+  }
+}
+```
+
+**Constraints:**
+
+- The `every` argument takes a duration object: `{ seconds: Int }`
+- **Minimum**: `{ seconds: 10 }` — protects against excessive server load
+- **Maximum**: `{ hours: 1 }` (3600 seconds)
+- Values outside this range fail validation at deploy time
+
+Use time-based polling when freshness matters but you don't have a specific
+mutation to listen for (e.g., dashboards aggregating external data, stock
+tickers, activity feeds).
+
+### Explicit Mutation Signals (`onMutationExecuted`)
+
+Trigger a query refresh when a specific mutation executes. This is the most
+common pattern for keeping lists in sync.
+
+```graphql
+# Example with condition (refreshes only when the condition is met)
+query ChatRoom($roomId: UUID!) @auth(level: PUBLIC)
+  @refresh(onMutationExecuted: {
+    operation: "SendMessage",
+    condition: "mutation.variables.roomId == request.variables.roomId"
+  }) {
+  messages(where: {roomId: {eq: $roomId}}, orderBy: [{createTime: DESC}], limit: 50) {
+    author content createTime
+  }
+}
+
+# Example without condition (refreshes on any execution of the named mutation)
+query ListAllMessages
+  @auth(level: PUBLIC)
+  @refresh(onMutationExecuted: {
+    operation: "SendMessage"
+  }) {
+  messages { id content }
+}
+```
+
+**Arguments:**
+
+- **`operation`** (required): The name of the mutation operation to listen for.
+  Must match the mutation's operation name exactly.
+- **`condition`** (optional): A CEL expression that must evaluate to `true` for
+  the refresh to fire. Without a condition, every execution of the named
+  mutation triggers a refresh.
+
+It's highly recommended to define fine granular conditions. Inaccurate refresh
+policies could consume Postgres resources and make your app slower.
+
+Use conditions to scope refreshes precisely — a review list should only refresh
+when the mutation targets the same movie, not every review across the entire
+app.
+
+### Combining Multiple @refresh Directives
+
+Since `@refresh` is repeatable, you can combine strategies on a single query:
+
+```graphql
+query ActiveOrders($userId: UUID!)
+  @auth(level: USER)
+  @refresh(onMutationExecuted: {
+    operation: "UpdateOrderStatus",
+    condition: "request.variables.userId == mutation.variables.userId"
+  })
+  @refresh(every: { seconds: 60 }) {
+  orders(where: { user: { id: { eq: $userId }}, status: { ne: DELIVERED }}) {
+    id status total updatedAt
+  }
+}
+```
+
+This query refreshes whenever an order status changes for this user, *and* polls
+every 60 seconds as a fallback to catch any updates that might not have a direct
+mutation trigger.
+
+______________________________________________________________________
+
+## CEL Bindings in Conditions
+
+The `condition` expression in `onMutationExecuted` has access to two contexts:
+
+### `request` — The Query Subscription
+
+The state of the query being subscribed to.
+
+| Binding              | Description                                                  |
+| -------------------- | ------------------------------------------------------------ |
+| `request.variables`  | Variables passed to the query (e.g., `request.variables.id`) |
+| `request.auth.uid`   | UID of the user who subscribed                               |
+| `request.auth.token` | Full auth token claims of the subscriber                     |
+
+### `mutation` — The Triggering Event
+
+The mutation that just executed.
+
+| Binding               | Description                                                           |
+| --------------------- | --------------------------------------------------------------------- |
+| `mutation.variables`  | Variables passed to the mutation (e.g., `mutation.variables.movieId`) |
+| `mutation.auth.uid`   | UID of the user who executed the mutation                             |
+| `mutation.auth.token` | Full auth token claims of the mutation executor                       |
+
+### Common Patterns
+
+```text
+# Refresh only when the mutation targets the same entity
+"request.variables.id == mutation.variables.id"
+
+# Refresh only when the same user who subscribed makes a change
+"request.auth.uid == mutation.auth.uid"
+
+# Refresh when a specific field value matches a condition
+"request.auth.uid == mutation.auth.uid && mutation.variables.status == 'PUBLISHED'"
+
+# Refresh when a specific flag is set in the mutation
+"mutation.variables.isPublic == true"
+```
+
+______________________________________________________________________
+
+## Implicit Entity Refresh signals
+
+For single-entity lookups by unique identifier, SQL Connect handles refreshes
+automatically — no `@refresh` directive needed.
+
+**What qualifies:**
+
+- Queries fetching one entity by its primary key: `movie(id: $id)`,
+  `user(key: { uid: $uid })`
+- If a single-entity mutation modifies that specific entity, all active
+  subscribers automatically receive the update. Supported operations include:
+  - `_insert(data)` or `_insertMany(data)`
+  - `_upsert(data)` or `_upsertMany(data)`
+  - `_update(id)` or `_update(key)`
+  - `_delete(id)` or `_delete(key)`
+- **Note**: Bulk operations like `_updateMany` and `_deleteMany` do **not**
+  trigger automatic entity refreshes.
+
+**What does NOT qualify:**
+
+- List queries: `movies(where: {...})`, `users { id name }` — these require
+  explicit `@refresh`
+- Nested query with JOINs
+- Aggregation
+- Native SQL
+- Customized Resolver (if supported)
+
+```graphql
+# When subscribed to, this query auto-refreshes when movie data changes — no @refresh needed
+query GetMovie($id: UUID!) @auth(level: PUBLIC) {
+  movie(id: $id) {
+    id title rating description
+    reviews_on_movie { rating text user { displayName } }
+  }
+}
+```
+
+To consume automatic refreshes on the client, use `subscribe()` instead of
+`execute()` — the same client pattern works regardless of whether the refresh is
+automatic or directive-driven.

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

@@ -0,0 +1,290 @@
+# Schema Reference
+
+## Contents
+
+- [Defining Types](#defining-types)
+- [Core Directives](#core-directives)
+- [Relationships](#relationships)
+- [Data Types](#data-types)
+- [Enumerations](#enumerations)
+
+______________________________________________________________________
+
+## Defining Types
+
+Types with `@table` map to PostgreSQL tables. SQL Connect auto-generates an
+implicit `id: UUID!` primary key.
+
+```graphql
+type Movie @table {
+  # id: UUID! is auto-added
+  title: String!
+  releaseYear: Int
+  genre: String
+}
+```
+
+### Customizing Tables
+
+```graphql
+type Movie @table(name: "movies", key: "id", singular: "movie", plural: "movies") {
+  id: UUID! @col(name: "movie_id") @default(expr: "uuidV4()")
+  title: String!
+  releaseYear: Int @col(name: "release_year")
+  genre: String @col(dataType: "varchar(20)")
+}
+```
+
+### User Table with Auth
+
+```graphql
+type User @table(key: "uid") {
+  uid: String! @default(expr: "auth.uid")
+  email: String! @unique
+  displayName: String @col(dataType: "varchar(100)")
+  createdAt: Timestamp! @default(expr: "request.time")
+}
+```
+
+______________________________________________________________________
+
+## Core Directives
+
+### @table
+
+Defines a database table.
+
+| Argument   | Description                                |
+| ---------- | ------------------------------------------ |
+| `name`     | PostgreSQL table name (snake_case default) |
+| `key`      | Primary key field(s), default `["id"]`     |
+| `singular` | Singular name for generated fields         |
+| `plural`   | Plural name for generated fields           |
+
+### @col
+
+Customizes column mapping.
+
+| Argument   | Description                                           |
+| ---------- | ----------------------------------------------------- |
+| `name`     | Column name in PostgreSQL                             |
+| `dataType` | PostgreSQL type: `serial`, `varchar(n)`, `text`, etc. |
+| `size`     | Required for `Vector` type                            |
+
+### @default
+
+Sets default value for inserts.
+
+| Argument | Description                                                                                                  |
+| -------- | ------------------------------------------------------------------------------------------------------------ |
+| `value`  | Literal value: `@default(value: "draft")`                                                                    |
+| `expr`   | CEL expression: `@default(expr: "uuidV4()")`, `@default(expr: "auth.uid")`, `@default(expr: "request.time")` |
+| `sql`    | Raw SQL: `@default(sql: "now()")`                                                                            |
+
+**Common expressions:**
+
+- `uuidV4()` - Generate UUID
+- `auth.uid` - Current user's Firebase Auth UID
+- `request.time` - Server timestamp
+
+### @unique
+
+Adds unique constraint.
+
+```graphql
+type User @table {
+  email: String! @unique
+}
+
+# Composite unique
+type Review @table @unique(fields: ["movie", "user"]) {
+  movie: Movie!
+  user: User!
+  rating: Int
+}
+```
+
+### @index
+
+Creates database index for query performance.
+
+```graphql
+type Movie @table @index(fields: ["genre", "releaseYear"], order: [ASC, DESC]) {
+  title: String! @index
+  genre: String
+  releaseYear: Int
+}
+```
+
+| Argument | Description                                                   |
+| -------- | ------------------------------------------------------------- |
+| `fields` | Fields for composite index (on @table)                        |
+| `order`  | `[ASC]` or `[DESC]` for each field                            |
+| `type`   | `BTREE` (default), `GIN` (arrays), `HNSW`/`IVFFLAT` (vectors) |
+
+### @searchable
+
+Enables full-text search on String fields.
+
+```graphql
+type Post @table {
+  title: String! @searchable
+  body: String! @searchable(language: "english")
+}
+
+# Usage
+query SearchPosts($q: String!) @auth(level: PUBLIC) {
+  posts_search(query: $q) { id title body }
+}
+```
+
+______________________________________________________________________
+
+## Relationships
+
+### One-to-Many (Implicit Foreign Key)
+
+```graphql
+type Post @table {
+  id: UUID! @default(expr: "uuidV4()")
+  author: User!  # Creates authorId foreign key
+  title: String!
+}
+
+type User @table {
+  id: UUID! @default(expr: "uuidV4()")
+  name: String!
+  # Auto-generated: posts_on_author: [Post!]!
+}
+```
+
+### @ref Directive
+
+Customizes foreign key reference.
+
+```graphql
+type Post @table {
+  author: User! @ref(fields: "authorId", references: "id")
+  authorId: UUID!  # Explicit FK field
+}
+```
+
+| Argument         | Description                         |
+| ---------------- | ----------------------------------- |
+| `fields`         | Local FK field name(s)              |
+| `references`     | Target field(s) in referenced table |
+| `constraintName` | PostgreSQL constraint name          |
+
+**Cascade behavior:**
+
+- Required reference (`User!`): CASCADE DELETE (post deleted when user deleted)
+- Optional reference (`User`): SET NULL (authorId set to null when user deleted)
+
+### One-to-One
+
+Use `@unique` on the reference field:
+
+```graphql
+type User @table { id: UUID! name: String! }
+
+type UserProfile @table {
+  user: User! @unique  # One profile per user
+  bio: String
+  avatarUrl: String
+}
+
+# Query: user.userProfile_on_user
+```
+
+### Many-to-Many
+
+Use a join table with composite primary key:
+
+```graphql
+type Movie @table { id: UUID! title: String! }
+type Actor @table { id: UUID! name: String! }
+
+type MovieActor @table(key: ["movie", "actor"]) {
+  movie: Movie!
+  actor: Actor!
+  role: String!  # Extra data on relationship
+}
+
+# Generated fields:
+# - movie.actors_via_MovieActor: [Actor!]!
+# - actor.movies_via_MovieActor: [Movie!]!
+# - movie.movieActors_on_movie: [MovieActor!]!
+```
+
+______________________________________________________________________
+
+## Data Types
+
+| GraphQL Type | PostgreSQL Default | Other PostgreSQL Types      |
+| ------------ | ------------------ | --------------------------- |
+| `String`     | `text`             | `varchar(n)`, `char(n)`     |
+| `Int`        | `int4`             | `int2`, `serial`            |
+| `Int64`      | `bigint`           | `bigserial`, `numeric`      |
+| `Float`      | `float8`           | `float4`, `numeric`         |
+| `Boolean`    | `boolean`          |                             |
+| `UUID`       | `uuid`             |                             |
+| `Date`       | `date`             |                             |
+| `Timestamp`  | `timestamptz`      | Stored as UTC               |
+| `Any`        | `jsonb`            |                             |
+| `Vector`     | `vector`           | Requires `@col(size: N)`    |
+| `[Type]`     | Array              | e.g., `[String]` → `text[]` |
+
+______________________________________________________________________
+
+## Enumerations
+
+```graphql
+enum Status {
+  DRAFT
+  PUBLISHED
+  ARCHIVED
+}
+
+type Post @table {
+  status: Status! @default(value: DRAFT)
+  allowedStatuses: [Status!]
+}
+```
+
+**Rules:**
+
+- Enum names: PascalCase, no underscores
+- Enum values: UPPER_SNAKE_CASE
+- Values are ordered (for comparison operations)
+- Changing order or removing values is a breaking change
+
+______________________________________________________________________
+
+## Views (Advanced)
+
+Map custom SQL queries to GraphQL types:
+
+```graphql
+type MovieStats @view(sql: """
+  SELECT
+    movie_id,
+    COUNT(*) as review_count,
+    AVG(rating) as avg_rating
+  FROM review
+  GROUP BY movie_id
+""") {
+  movie: Movie @unique
+  reviewCount: Int
+  avgRating: Float
+}
+
+# Query movies with stats
+query TopMovies @auth(level: PUBLIC) {
+  movies(orderBy: [{ rating: DESC }]) {
+    title
+    stats: movieStats_on_movie {
+      reviewCount avgRating
+    }
+  }
+}
+```

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

@@ -0,0 +1,141 @@
+# Admin Node SDK
+
+Consult this file when writing server-side code (e.g., Cloud Functions) that
+needs elevated privileges or needs to impersonate specific users.
+
+### Best Practices for Agents
+
+- **Understand Operation Storage**: SQL Connect queries and mutations are stored
+  on the server like Cloud Functions. Clients do not submit the raw operations.
+  Therefore, **whenever you update operations, you must regenerate the SDK and
+  redeploy services** that use it.
+- **Follow Least Privilege**: Admin SDKs have unrestricted access by default.
+  Always use impersonation when possible to limit access.
+- **Impersonation**: Use the `impersonate` parameter to run operations as a
+  specific user or as an unauthenticated user.
+- **Impersonation Variables**: If you call an operation with optional variables
+  and want to pass impersonation options but without variables, you **MUST**
+  pass `undefined` as the first argument (variables) to clearly indicate no
+  variables are being provided.
+- **Admin Operations**: If you create operations intended only for
+  administration, define them with `@auth(level: NO_ACCESS)`. This ensures they
+  can only be called via the Admin SDK with unrestricted access.
+- **Resilient Enum Handling**: JavaScript/TypeScript does not enforce exhaustive
+  checks on enums. Always add a `default` branch to `switch` statements or an
+  `else` branch to handle unknown values gracefully when schemas evolve.
+
+### Configuration in `connector.yaml`
+
+To generate an Admin SDK, add the `adminNodeSdk` block to your `connector.yaml`:
+
+```yaml
+connectorId: my-connector
+generate:
+  adminNodeSdk:
+    outputDir: "./admin-sdk"
+    package: "@dataconnect/admin-generated"
+    packageJsonDir: "." # Directory containing package.json
+```
+
+### Generation
+
+Run the generation command:
+
+```bash
+npx -y firebase-tools@latest dataconnect:sdk:generate
+```
+
+### Usage Examples
+
+#### 1. Impersonating an Unauthenticated User
+
+Unauthenticated users can only run operations marked as `PUBLIC`.
+
+```typescript
+import { initializeApp } from "firebase-admin/app";
+import { getDataConnect } from "firebase-admin/data-connect";
+import { connectorConfig, getSongs } from "@dataconnect/admin-generated";
+
+const adminApp = initializeApp();
+const adminDc = getDataConnect(connectorConfig);
+
+const songs = await getSongs(
+  adminDc,
+  { limit: 4 },
+  { impersonate: { unauthenticated: true } }
+);
+```
+
+#### 2. Impersonating a Specific User (Cloud Functions)
+
+When using callable Cloud Functions, the authentication token is automatically
+verified.
+
+```typescript
+import { HttpsError, onCall } from "firebase-functions/https";
+import { getMyFavoriteSongs } from "@dataconnect/admin-generated";
+
+export const callableExample = onCall(async (req) => {
+    const authClaims = req.auth?.token;
+    if (!authClaims) {
+        throw new HttpsError("unauthenticated", "Unauthorized");
+    }
+
+    const favoriteSongs = await getMyFavoriteSongs(
+        adminDc,
+        undefined,
+        { impersonate: { authClaims } }
+    );
+
+    return favoriteSongs;
+});
+```
+
+#### 3. Impersonating a Specific User (Plain HTTP)
+
+For non-callable endpoints, you must verify the token yourself.
+
+```typescript
+import { getAuth } from "firebase-admin/auth";
+import { onRequest } from "firebase-functions/https";
+import { getMyFavoriteSongs } from "@dataconnect/admin-generated";
+
+const auth = getAuth();
+
+export const httpExample = onRequest(async (req, res) => {
+    const token = req.header("authorization")?.replace(/^bearer\s+/i, "");
+    if (!token) {
+        res.sendStatus(401);
+        return;
+    }
+    let authClaims;
+    try {
+        authClaims = await auth.verifyIdToken(token);
+    } catch {
+        res.sendStatus(401);
+        return;
+    }
+
+    const favoriteSongs = await getMyFavoriteSongs(
+        adminDc,
+        undefined,
+        { impersonate: { authClaims } }
+    );
+
+    res.send(favoriteSongs);
+});
+```
+
+#### 4. Running with Unrestricted Access
+
+Omit the `impersonate` parameter to run with full admin access. Only do this for
+true administrative tasks.
+
+```typescript
+import { upsertSong } from "@dataconnect/admin-generated";
+
+await upsertSong(adminDc, {
+  title: "New Song",
+  genre: "Rock"
+});
+```