vybekiit 0.4.0 → 0.6.0

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

@@ -0,0 +1,126 @@
+# Android SDK
+
+Consult this file when writing Android application code (Kotlin) that interacts
+with the SQL Connect backend.
+
+### Best Practices for Agents
+
+- **Understand Operation Storage**: SQL Connect queries and mutations are stored
+  on the server like Cloud Functions. **Whenever you update operations, you must
+  regenerate the SDK and redeploy services** that use it to avoid breaking
+  clients.
+- **Resilient Enum Handling**: The generated SDK forces handling of unknown
+  values by wrapping them in `EnumValue`. You must unwrap it into
+  `EnumValue.Known` or `EnumValue.Unknown` to handle schema updates gracefully.
+- **Flow Behavior**: While you can collect a Flow from a query, note that **this
+  Flow is not updated in real-time automatically** by default. It only produces
+  a result when a new query result is retrieved using a call to the query's
+  `execute()` method.
+- **Leverage Coroutines**: Call `.execute()` within a coroutine scope for
+  asynchronous operations.
+
+### Dependencies (build.gradle.kts)
+
+Ensure you have the Kotlin Serialization plugin and standard SQL Connect
+dependencies:
+
+```kotlin
+plugins {
+    kotlin("plugin.serialization") version "1.8.22" // Must match Kotlin version
+}
+
+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:34.12.0"))
+    implementation("com.google.firebase:firebase-dataconnect")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
+    implementation("org.jetbrains.kotlinx:kotlinx-serialization-core:1.5.1")
+}
+```
+
+### Initialization
+
+Retrieve the generated connector instance:
+
+```kotlin
+import com.google.firebase.dataconnect.generated.MoviesConnector
+
+val connector = MoviesConnector.instance
+
+// For local development with emulator
+// Defaults to correct host for Android emulator (10.0.2.2)
+connector.dataConnect.useEmulator()
+// Or specify a non-default port:
+// connector.dataConnect.useEmulator(port = 9999)
+```
+
+### Calling Operations
+
+#### Basic Query
+
+```kotlin
+val result = connector.listMovies.execute()
+result.data.movies.forEach { movie ->
+    println(movie.title)
+}
+```
+
+#### Mutation
+
+```kotlin
+val newMovie = connector.createMovie.execute(
+    title = "Empire Strikes Back",
+    releaseYear = 1980,
+    genre = "Sci-Fi",
+    rating = 5
+)
+```
+
+### Resilient Enum Handling
+
+Unwrap the `EnumValue` to handle known and unknown cases safely.
+
+```kotlin
+val result = connector.listMovies.execute()
+
+result.data.movies.forEach { movie ->
+    when (val aspect = movie.aspectratio) {
+        is EnumValue.Known -> println("Known aspect: ${aspect.value.name}")
+        is EnumValue.Unknown -> println("Unknown aspect: ${aspect.stringValue}")
+    }
+}
+```
+
+### Client-Side Caching
+
+Enable caching in `connector.yaml` to reduce requests and support offline
+scenarios.
+
+```yaml
+generate:
+  kotlinSdk:
+    outputDir: "../android"
+    package: "com.google.firebase.dataconnect.generated"
+    clientCache:
+      maxAge: 5s
+      storage: persistent # Default for Android is persistent
+```
+
+Use policies in code:
+
+```kotlin
+val queryResult = queryRef.execute(QueryRef.FetchPolicy.CACHE_ONLY)
+val queryResult = queryRef.execute(QueryRef.FetchPolicy.SERVER_ONLY)
+```
+
+### Data Type Mapping Reference
+
+- GraphQL `String` -> Kotlin `String`
+- GraphQL `Int` -> Kotlin `Int` (32-bit)
+- GraphQL `Float` -> Kotlin `Double` (64-bit)
+- GraphQL `Boolean` -> Kotlin `Boolean`
+- GraphQL `UUID` -> Kotlin `java.util.UUID`
+- GraphQL `Date` -> Kotlin `com.google.firebase.dataconnect.LocalDate`
+- GraphQL `Timestamp` -> Kotlin `com.google.firebase.Timestamp`
+- GraphQL `Int64` -> Kotlin `Long`
+- GraphQL `Any` -> Kotlin `com.google.firebase.dataconnect.AnyValue`

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

@@ -0,0 +1,134 @@
+# Flutter SDK
+
+Consult this file when writing Flutter application code (Dart) that interacts
+with the SQL Connect backend.
+
+### Best Practices for Agents
+
+- **Understand Operation Storage**: SQL Connect queries and mutations are stored
+  on the server like Cloud Functions. **Whenever you update operations, you must
+  regenerate the SDK and redeploy services** that use it to avoid breaking
+  clients.
+- **Resilient Enum Handling**: The generated SDK forces handling of unknown
+  values for enumerations. Client code must unwrap the `EnumValue` object into
+  either `Known` or `Unknown` to handle schema updates gracefully.
+- **Use Ref for Subscriptions**: Call `.ref()` on operation methods to get a
+  `QueryRef` for advanced usage like subscriptions.
+- **Builder Pattern for Optionals**: Use the builder pattern for mutations with
+  optional fields.
+
+### Installation
+
+```bash
+flutter pub add firebase_data_connect
+```
+
+### Imports
+
+```dart
+import 'package:firebase_data_connect/firebase_data_connect.dart';
+// Import generated connector
+import 'generated/movies.dart'; 
+```
+
+### Initialization
+
+```dart
+// For local development with emulator
+MoviesConnector.instance.dataConnect.useDataConnectEmulator('127.0.0.1', 9399);
+```
+
+### Calling Operations
+
+#### Basic Query
+
+```dart
+final response = await MoviesConnector.instance.listMovies().execute();
+print(response.data.movies);
+```
+
+#### Mutation with Optional Fields (Builder Pattern)
+
+```dart
+await MoviesConnector.instance.createMovie(
+  title: 'Empire Strikes Back', 
+  releaseYear: 1980, 
+  genre: 'Sci-Fi' 
+).rating(5).execute();
+```
+
+### Resilient Enum Handling
+
+When dealing with schema enumerations, use the forced unwrapping pattern to
+handle unknown values (e.g., when a new value is added to the backend but client
+is old).
+
+```dart
+final result = await MoviesConnector.instance.listMovies().execute();
+
+if (result.data != null && result.data!.isNotEmpty) {
+  handleEnumValue(result.data![0].aspectratio);
+}
+
+void handleEnumValue(EnumValue<AspectRatio> aspectValue) {
+  if (aspectValue.value != null) {
+    switch(aspectValue.value!) {
+      case AspectRatio.ACADEMY:
+        print("Academy aspect");
+        break;
+      case AspectRatio.WIDESCREEN:
+        print("Widescreen aspect");
+        break;
+      // Add other known cases...
+    }
+  } else {
+    print("Unknown aspect ratio detected: ${aspectValue.stringValue}");
+  }
+}
+```
+
+### Client-Side Caching
+
+Enable caching in `connector.yaml` to reduce requests and support offline
+scenarios.
+
+```yaml
+generate:
+  dartSdk: # Or the appropriate block for your project
+    outputDir: ../dart/
+    package: "dataconnect_generated"
+    clientCache:
+      maxAge: 5s
+      storage: memory # Or persistent for native
+```
+
+Use policies in code:
+
+```dart
+// Only serve cached values
+await queryRef.execute(fetchPolicy: QueryFetchPolicy.cacheOnly);
+
+// Unconditionally fetch fresh values
+await queryRef.execute(fetchPolicy: QueryFetchPolicy.serverOnly);
+```
+
+### Real-time Subscriptions
+
+```dart
+final queryRef = MoviesConnector.instance.getMovieById(id: "<MOVIE_ID>").ref();
+final subscription = queryRef.subscribe().listen((result) {
+  final movie = result.data.movie;
+  if (movie != null) {
+    updateUi(movie.title);
+  }
+});
+```
+
+### Data Type Mapping Reference
+
+- GraphQL `Timestamp` -> Dart `firebase_data_connect.Timestamp`
+- GraphQL `Int` -> Dart `int`
+- GraphQL `Date` -> Dart `DateTime`
+- GraphQL `UUID` -> Dart `string`
+- GraphQL `Float` -> Dart `double`
+- GraphQL `Boolean` -> Dart `bool`

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

@@ -0,0 +1,157 @@
+# iOS SDK
+
+Consult this file when writing iOS application code (Swift) that interacts with
+the SQL Connect backend.
+
+### Best Practices for Agents
+
+- **Understand Operation Storage**: SQL Connect queries and mutations are stored
+  on the server like Cloud Functions. **Whenever you update operations, you must
+  regenerate the SDK and redeploy services** that use it to avoid breaking
+  clients.
+- **Resilient Enum Handling**: The generated SDK forces handling of unknown
+  values by adding an `._UNKNOWN` case. Swift enforces exhaustive switch
+  statements, so you must handle this case.
+- **Observable Macro**: By default, query refs support the `@Observable` macro
+  (iOS 17+), making them ideal for binding to SwiftUI views. The bindable query
+  results are available in the `data` variable of the query ref.
+- **Handle Errors**: Use `try await` with operation execution as they are
+  asynchronous and may throw errors.
+
+### Dependencies (Package.swift or SPM)
+
+Configure the generated SDK as a package dependency in Xcode.
+
+### Initialization
+
+Retrieve the generated connector instance:
+
+```swift
+import FirebaseCore
+import FirebaseDataConnect
+
+// Assuming connector name is 'movies' in connector.yaml
+// The connector name is the lower camel case connectorId defined in connector.yaml suffixed with the word 'Connector'
+let connector = DataConnect.moviesConnector
+
+// For local development with emulator
+// Defaults to 127.0.0.1:9399
+connector.useEmulator() 
+// Or specify a non-default port:
+// connector.useEmulator(port: 9999)
+```
+
+### Calling Operations
+
+#### Basic Query
+
+```swift
+let result = try await connector.listMovies.execute()
+for movie in result.data.movies {
+    print(movie.title)
+}
+```
+
+#### Mutation
+
+```swift
+let mutationResult = try await connector.createMovieMutation.execute(
+  title: "Empire Strikes Back",
+  releaseYear: 1980,
+  genre: "Sci-Fi",
+  rating: 5
+)
+```
+
+### Resilient Enum Handling
+
+Handle generated enums exhaustively, including the `._UNKNOWN` case.
+
+```swift
+do {
+    let result = try await DataConnect.moviesConnector.listMovies.execute()
+    if let data = result.data {
+        for movie in data.movies {
+            switch movie.aspectratio {
+                case .ACADEMY: print("academy")
+                case .WIDESCREEN: print("widescreen")
+                case .ANAMORPHIC: print("anamorphic")
+                case ._UNKNOWN(let unknownAspect): print("Unknown: \(unknownAspect)")
+            }
+        }
+    }
+} catch {
+    // handle error
+}
+```
+
+### Client-Side Caching
+
+Enable caching in `connector.yaml` to reduce requests, support offline
+scenarios, enable realtime support for queries.
+
+```yaml
+generate:
+  swiftSdk:
+    outputDir: "../ios"
+    package: "FirebaseDataConnectGenerated"
+    clientCache:
+      maxAge: 5s
+      storage: persistent # Default for iOS is persistent
+```
+
+Use cache policies in code:
+
+```swift
+try await execute(fetchPolicy: .cacheOnly)
+try await execute(fetchPolicy: .serverOnly)
+```
+
+### Subscriptions (Realtime)
+
+#### SwiftUI Example
+
+```swift
+import Combine
+import SwiftUI
+
+struct ListMovieView: View {
+    // QueryRef has the Observable attribute, so its properties will
+    // automatically trigger updates on changes.
+    private var queryRef = connector.listMoviesByGenreQuery.ref(genre: "Sci-Fi")
+
+    // Store the handle to unsubscribe from query updates.
+    @State private var querySub: AnyCancellable?
+
+    var body: some View {
+        VStack {
+            // Use the query results in a View.
+            ForEach(queryRef.data?.movies ?? [], id: \.id) { movie in
+                    Text(movie.title)
+                }
+        }
+        .onAppear {
+            // Subscribe to the query for updates using the Observable macro.
+            Task {
+                do {
+                    querySub = try await queryRef.subscribe().sink { _ in }
+                } catch {
+                    print("Error subscribing to query: \(error)")
+                }
+            }
+        }
+        .onDisappear {
+          querySub?.cancel()
+        }
+    }
+}
+```
+
+### Data Type Mapping Reference
+
+- GraphQL `UUID` -> Swift `UUID`
+- GraphQL `Date` -> Swift `FirebaseDataConnect.LocalDate`
+- GraphQL `Timestamp` -> Swift `FirebaseCore.Timestamp`
+- GraphQL `Int` -> Swift `Int`
+- GraphQL `Float` -> Swift `Double`
+- GraphQL `Boolean` -> Swift `Bool`

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

@@ -0,0 +1,146 @@
+# Web SDK
+
+Consult this file when writing client-side web code (TypeScript/JavaScript) that
+interacts with the SQL Connect backend.
+
+### Best Practices for Agents
+
+- **Understand Operation Storage**: SQL Connect queries and mutations are stored
+  on the server like Cloud Functions. **Whenever you update operations, you must
+  regenerate the SDK and redeploy services** that use it to avoid breaking
+  clients.
+- **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.
+- **TanStack Query vs. Native**: You can generate hooks for React/Angular using
+  TanStack Query. Choose either TanStack or SQL Connect's built-in real-time and
+  caching support, but do not use both in the same project. SQL Connect offers
+  normalized caching and remote invalidation.
+- **Emulator Connection**: `connectDataConnectEmulator` is only required if
+  connecting to the emulator. Otherwise, the generated SDK auto-creates the
+  instance.
+
+### Installation
+
+```bash
+npm install firebase
+firebase init dataconnect:sdk
+```
+
+### Initialization
+
+```typescript
+import { connectDataConnectEmulator, getDataConnect } from 'firebase/data-connect';
+import { connectorConfig } from '@dataconnect/generated';
+
+const dataConnect = getDataConnect(connectorConfig);
+// Configure the SDK to use local emulator
+connectDataConnectEmulator(dataConnect, 'localhost', 9399);
+```
+
+### Calling Operations
+
+#### Using `executeQuery` (Preferred for clarity)
+
+```typescript
+import { executeQuery } from 'firebase/data-connect';
+import { listMoviesRef } from '@dataconnect/generated';
+
+const ref = listMoviesRef();
+const { data } = await executeQuery(ref);
+console.log(data.movies);
+```
+
+#### Using Action Shortcuts
+
+```typescript
+import { listMovies } from '@dataconnect/generated';
+
+listMovies().then(data => showInUI(data));
+```
+
+### Resilient Enum Handling
+
+Use a `default` case or check against `Object.values`.
+
+```typescript
+import { getOldestMovie } from '@dataconnect/generated';
+
+const queryResult = await getOldestMovie();
+
+if (queryResult.data) {
+  const oldestMovieAspectRatio = queryResult.data.originalAspectRatio;
+  switch (oldestMovieAspectRatio) {
+      case AspectRatio.ACADEMY:
+      case AspectRatio.WIDESCREEN:
+        console.log('Filmed in Academy or Widescreen!');
+        break;
+      default:
+        // The default case will catch FULLSCREEN, etc.
+        console.log('Not filmed in Academy or Widescreen.');
+        break;
+  }
+}
+```
+
+### Client-Side Caching
+
+Enable caching in `connector.yaml`:
+
+```yaml
+generate:
+  javascriptSdk:
+    outputDir: ../web/
+    package: "@dataconnect/generated"
+    clientCache:
+      maxAge: 5s
+      storage: memory # Only memory is supported on Web
+```
+
+Use policies in code:
+
+```typescript
+await executeQuery(queryRef, QueryFetchPolicy.CACHE_ONLY);
+await executeQuery(queryRef, QueryFetchPolicy.SERVER_ONLY);
+```
+
+### Subscriptions (Realtime)
+
+Use `subscribe()` to receive live updates.
+
+#### Web (Vanilla JS)
+
+```typescript
+import { subscribe } from 'firebase/data-connect';
+import { getMovieByIdRef } from '@dataconnect/generated';
+
+const queryRef = getMovieByIdRef({ id: "<MOVIE_ID>" });
+
+const unsubscribe = subscribe(queryRef, (result) => {
+  console.log("Updated result:", result);
+});
+```
+
+### TanStack Query Support (React)
+
+To use React hooks, re-run `firebase init dataconnect:sdk` after adding React.
+
+#### Usage
+
+```typescript
+import { useListAllMovies } from "@dataconnect/generated/react";
+
+function MyComponent() {
+  const { isLoading, data, error } = useListAllMovies();
+  // handle loading, error, and data
+}
+```
+
+### Data Type Mapping Reference
+
+- GraphQL `Timestamp` -> TypeScript `string`
+- GraphQL `Date` -> TypeScript `string`
+- GraphQL `UUID` -> TypeScript `string`
+- GraphQL `Int64` -> TypeScript `string`
+- GraphQL `Double` -> TypeScript `number`
+- GraphQL `Float` -> TypeScript `number`