### Automated Setup Script for Convex Flutter

Source: https://github.com/jkuldev/convex_flutter/blob/main/ARCHITECTURE.md

This example demonstrates a potential automated setup script for convex_flutter. The script aims to simplify the installation process by detecting the OS, installing Rust and necessary platform tools, configuring the environment, and running a test build.

```bash
# Example setup script
curl -sSf https://raw.githubusercontent.com/jkuldev/convex_flutter/main/setup.sh | sh

# Script would:
# 1. Detect OS (macOS, Linux, Windows)
# 2. Install Rust if missing
# 3. Install platform tools (NDK, Xcode, etc.)
# 4. Configure environment
# 5. Run test build
```

--------------------------------

### Clone Repository and Install Rust

Source: https://github.com/jkuldev/convex_flutter/blob/main/CONTRIBUTING.md

Initial setup steps for cloning the repository and installing the Rust toolchain if needed for native development.

```bash
# 1. Clone your fork
git clone https://github.com/YOUR_USERNAME/convex_flutter.git
cd convex_flutter

# 2. Install Rust (skip if only working on web)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 3. Install dependencies
flutter pub get

# 4. Run example app
cd example
flutter pub get
flutter run -d chrome  # For web
# OR
flutter run -d macos   # For native
```

--------------------------------

### Run Example App

Source: https://github.com/jkuldev/convex_flutter/blob/main/README.md

Navigate to the example directory and run the Flutter application to see the Convex client in action.

```bash
cd example
flutter run
```

--------------------------------

### Run iOS Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/NATIVE_PLATFORM_FIX.md

Navigate to the example directory and run the Flutter app on iOS to test connectivity.

```bash
cd example
flutter run -d ios
```

--------------------------------

### Run Android Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/NATIVE_PLATFORM_FIX.md

Navigate to the example directory and run the Flutter app on Android to test connectivity.

```bash
cd example
flutter run -d android
```

--------------------------------

### Rust Installation and Setup for Convex Flutter

Source: https://github.com/jkuldev/convex_flutter/blob/main/ARCHITECTURE.md

This bash script outlines the steps required to install Rust and necessary platform tools for the initial setup of the convex_flutter package. It details the commands for installing Rust, and platform-specific tools for Android, iOS, macOS, Windows, and Linux.

```bash
# 1. Install Rust (5-10 minutes)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# 2. Install platform tools
# Android: Install NDK via Android SDK Manager
# iOS/macOS: xcode-select --install
# Windows: Install Visual Studio Build Tools
# Linux: sudo apt-get install build-essential clang pkg-config

# 3. Add package to Flutter project
flutter pub add convex_flutter

# 4. First build (slow - compiles Rust)
flutter run  # Takes 2-5 minutes on first build

# 5. Subsequent builds (faster - uses cache)
flutter run  # Takes 30-60 seconds
```

--------------------------------

### Run macOS Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/NATIVE_PLATFORM_FIX.md

Navigate to the example directory and run the Flutter app on macOS to test connectivity.

```bash
cd example
flutter run -d macos
```

--------------------------------

### Build Example App for Web

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Compile the example application for the web platform. This step verifies that the web build process is successful.

```bash
cd example && flutter build web
```

--------------------------------

### Run Example App on macOS

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Launch the example application on a macOS device. This is essential for testing native macOS functionality.

```bash
cd example && flutter run -d macos
```

--------------------------------

### Run example app on all platforms

Source: https://github.com/jkuldev/convex_flutter/blob/main/MIGRATION_v3.md

Instructions to run the example application on various platforms including web, macOS, iOS, Android, Windows, and Linux.

```bash
cd example

# Run on any platform
flutter run -d chrome      # Web
flutter run -d macos        # macOS
flutter run -d ios          # iOS Simulator
flutter run -d android      # Android Emulator
flutter run -d windows      # Windows
flutter run -d linux        # Linux
```

--------------------------------

### Build Example App for Windows

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Compile the example application for the Windows platform. This ensures compatibility and functionality on Windows.

```bash
cd example && flutter build windows
```

--------------------------------

### Installation Rules for Application Bundle

Source: https://github.com/jkuldev/convex_flutter/blob/main/example/linux/CMakeLists.txt

Configures the installation process to create a relocatable application bundle. It cleans the bundle directory, installs the executable, data files, libraries, and assets.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)

set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)

set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Install Rust

Source: https://github.com/jkuldev/convex_flutter/blob/main/README.md

Install Rust using the official script. This is required for native platforms and not for web.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

--------------------------------

### Install Rust Toolchain

Source: https://github.com/jkuldev/convex_flutter/blob/main/ARCHITECTURE.md

Commands to install the Rust toolchain and verify its installation. Includes notes on platform-specific tools required for development.

```bash
# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify installation
rustc --version
cargo --version

# Platform-specific tools
# Android: NDK (via Android SDK Manager)
# iOS/macOS: Xcode Command Line Tools
# Windows: Visual Studio Build Tools (C++)
# Linux: build-essential, clang, pkg-config
```

--------------------------------

### Build Example App for Linux

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Compile the example application for the Linux platform. This verifies the build process and prepares for Linux testing.

```bash
cd example && flutter build linux
```

--------------------------------

### Build Example App for macOS

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Compile the example application for the macOS platform. This ensures the application can be built and run on macOS.

```bash
cd example && flutter build macos
```

--------------------------------

### Run Example App on Chrome

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Launch the example application in Chrome. This allows for interactive testing of web-specific features and behavior.

```bash
cd example && flutter run -d chrome
```

--------------------------------

### Run Example App on Android Emulator

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Launch the example application on an Android emulator. This facilitates testing of Android-specific features and integrations.

```bash
cd example && flutter run -d emulator
```

--------------------------------

### Build for All Platforms

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Build the project for various platforms from the example directory.

```bash
cd example
flutter build web
flutter build apk
flutter build ios --no-codesign
flutter build macos
```

--------------------------------

### Run Example App on iOS Simulator

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Launch the example application on an iOS simulator. This allows for testing iOS-specific features and UI.

```bash
cd example && flutter run -d "iPhone 15"
```

--------------------------------

### Verify Rust Installation

Source: https://github.com/jkuldev/convex_flutter/blob/main/README.md

Check if Rust and Cargo are installed correctly by verifying their versions.

```bash
rustc --version
cargo --version
```

--------------------------------

### Build Example App for Android

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Compile the example application for the Android platform, generating an APK. This is necessary for testing on emulators or physical devices.

```bash
cd example && flutter build apk
```

--------------------------------

### Test Example App on Platforms

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_PREPARATION_SUMMARY.md

Run the example application on different platforms to ensure functionality. Use specific platform flags for `flutter run`.

```bash
# Test example on platforms
cd example
flutter run -d chrome   # Web
flutter run -d macos     # macOS
flutter run -d android   # Android (if available)
```

--------------------------------

### Build Example App for iOS

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Compile the example application for the iOS platform, excluding code signing. This is a prerequisite for running on simulators or devices.

```bash
cd example && flutter build ios --no-codesign
```

--------------------------------

### Install and Initialize Convex Flutter

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_NOTES_v3.0.0.md

Install the package using flutter pub add. Configure platforms if necessary, then initialize the client with your deployment URL. Use ConvexClient.instance to access the client.

```bash
# Install
flutter pub add convex_flutter

# Configure platforms (if using macOS or Android)
# See PLATFORM_CONFIGURATION.md

# Initialize in your app
await ConvexClient.initialize(
  ConvexConfig(
    deploymentUrl: 'https://your-app.convex.cloud',
  ),
);

# Use anywhere
final client = ConvexClient.instance;
final data = await client.query('myQuery', {});
```

--------------------------------

### Kotlin/Swift EventChannel Subscription Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Sets up an EventChannel on the native side to receive subscription updates.

```kotlin
Create EventChannel("convex_flutter/subscription/1")
```

```kotlin
Start Flow/Publisher collection
```

```kotlin
On each update → eventSink.success({type: "update", data: "..."})
```

--------------------------------

### Comparing Convex Flutter Build Times to Pure Dart

Source: https://github.com/jkuldev/convex_flutter/blob/main/ARCHITECTURE.md

This comparison highlights the significant difference in setup and build times between the convex_flutter FFI plugin and a typical pure Dart package. It shows the extended time required for Rust setup and compilation versus the near-instantaneous setup of Dart packages.

```bash
# Pure Dart package (e.g., http, provider, riverpod)
flutter pub add http  # Done in 5 seconds
flutter run           # Builds in 30 seconds

# convex_flutter (FFI plugin)
flutter pub add convex_flutter  # Requires Rust setup (10 minutes)
flutter run                      # Builds in 3-5 minutes (first time)
```

--------------------------------

### Kotlin/Swift Set Authentication Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Applies the authentication token to the native Convex client.

```kotlin
convexClient.setAuth(token)
```

--------------------------------

### Client Initialization

Source: https://github.com/jkuldev/convex_flutter/blob/main/README.md

Initializes the Convex client as a singleton. This should be done once at the start of your application.

```APIDOC
## Initialize the Client

```dart
import 'package:convex_flutter/convex_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize the client once (singleton)
  await ConvexClient.initialize(
    ConvexConfig(
      deploymentUrl: 'https://my-app.convex.cloud',
      clientId: 'flutter-app-1.0',
      operationTimeout: Duration(seconds: 30), // Optional, defaults to 30s
      healthCheckQuery: 'health:ping', // Optional, for connection checks (requires health.ts)
    ),
  );

  runApp(MyApp());
}
```
```

--------------------------------

### Example Commit Message: Feature

Source: https://github.com/jkuldev/convex_flutter/blob/main/CONTRIBUTING.md

An example of a commit message for adding a new feature, including a detailed explanation and an issue reference.

```git
feat(web): Add web platform support with pure Dart implementation

Implemented Convex WebSocket protocol in pure Dart for web platform.
Includes UUID generation, protocol messages, and subscription handling.

Fixes #123
```

--------------------------------

### Dart Authentication with Refresh Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Sets up authentication with a token refresh callback in the Dart client.

```dart
client.setAuthWithRefresh(fetchToken: () => getJWT())
```

--------------------------------

### Install Rust Toolchain for Native Platforms

Source: https://context7.com/jkuldev/convex_flutter/llms.txt

Ensure the Rust toolchain is installed for native platform support on Android, iOS, macOS, Windows, and Linux.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
```

--------------------------------

### Browser DevTools WebSocket Capture Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/doc/CONVEX_PROTOCOL.md

Example JavaScript code to be run in a browser's developer console to capture WebSocket messages and send a test query.

```javascript
// In browser console
const ws = new WebSocket('wss://your-deployment.convex.cloud/ws');
ws.onmessage = (event) => {
  console.log('RECEIVED:', event.data);
};
ws.send(JSON.stringify({
  type: 'query',
  id: '1',
  name: 'messages:list',
  args: {}
}));
```

--------------------------------

### Enable Flutter Web Support and Build

Source: https://github.com/jkuldev/convex_flutter/blob/main/MIGRATION_v3.md

Commands to enable Flutter web support, clean the project, get dependencies, and build the web version.

```bash
flutter config --enable-web
flutter clean
flutter pub get
flutter build web
```

--------------------------------

### Dart/Web WebSocket Setup

Source: https://github.com/jkuldev/convex_flutter/blob/main/doc/CONVEX_PROTOCOL.md

Initializes a WebSocket connection for the Convex client in a Dart/Web environment. Ensure `deploymentUrl` is correctly configured.

```dart
// Dart/Web implementation
import 'package:web/web.dart' as web;

final wsUrl = deploymentUrl.replaceFirst('https', 'wss');
final ws = web.WebSocket('$wsUrl/ws');
```

--------------------------------

### Kotlin/Swift Query Operation Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Executes a query on the native Convex client in Kotlin or Swift.

```kotlin
convexClient.query("messages:list", parseArgs({}))
```

--------------------------------

### Run Flutter App on macOS

Source: https://github.com/jkuldev/convex_flutter/blob/main/WEB_PLATFORM_STATUS.md

Command to run the Flutter example application on a macOS native platform.

```bash
flutter run -d macos
```

--------------------------------

### Kotlin/Swift Subscription Cleanup Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Cleans up resources associated with a subscription on the native side upon cancellation.

```kotlin
Cancel Job/AnyCancellable, clean up EventChannel
```

--------------------------------

### Dart Subscription Operation Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Initiates a subscription operation from the Dart client, providing a callback for updates.

```dart
client.subscribe(name: "messages:list", onUpdate: callback)
```

--------------------------------

### Test Convex Flutter on Different Platforms

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_NOTES_v3.0.0.md

Run the example app on various platforms to test functionality. Use 'flutter run -d <platform>' to specify the target device.

```bash
cd example
flutter run -d chrome      # Test web
flutter run -d macos        # Test macOS
flutter run -d android      # Test Android
```

--------------------------------

### Initialize Convex Client and Example Usage

Source: https://github.com/jkuldev/convex_flutter/blob/main/README.md

Initialize the Convex client once with configuration details. Access the client instance to perform queries, mutations, and subscriptions. Handles operations with optional timeouts and real-time updates.

```dart
import 'package:convex_flutter/convex_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize the client once (singleton)
  await ConvexClient.initialize(
    ConvexConfig(
      deploymentUrl: 'https://my-app.convex.cloud',
      clientId: 'flutter-app-1.0',
      operationTimeout: Duration(seconds: 30), // Optional, defaults to 30s
      healthCheckQuery: 'health:ping', // Optional, for connection checks (requires health.ts)
    ),
  );

  runApp(MyApp());
}

// Access the client anywhere in your app
void example() async {
  final client = ConvexClient.instance;

  // Optional: authenticate (see Authentication section below)
  await client.setAuth(token: 'YOUR_AUTH_TOKEN');

  // Query (with timeout)
  try {
    final users = await client.query('users:list', {'limit': '10'});
    print('Users: $users');
  } on TimeoutException {
    print('Connection timeout!');
  }

  // Subscribe to real-time updates
  final sub = await client.subscribe(
    name: 'messages:list',
    args: {},
    onUpdate: (value) => print('Update: $value'),
    onError: (message, value) => print('Error: $message ${value ?? ''}'),
  );

  // Mutation
  await client.mutation(
    name: 'messages:send',
    args: {'body': 'Hello!', 'author': 'User123'},
  );

  // Action (if you have actions defined)
  // final res = await client.action(name: 'files:upload', args: {...});

  // Later, when done
  sub.cancel();
}
```

--------------------------------

### Build Flutter Web App

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_NOTES_v3.0.0.md

Use this command to build your Flutter web application. No Rust installation is required for web builds.

```bash
# No Rust installation needed!
flutter build web
```

--------------------------------

### Dart Code Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/CONTRIBUTING.md

Example of a Dart function for executing a Convex query. Includes documentation comments explaining parameters, return values, and potential exceptions.

```dart
/// Executes a Convex query with the given [name] and [args].
///
/// Returns a JSON string containing the query result.
/// Throws [TimeoutException] if the operation exceeds [operationTimeout].
///
/// Example:
/// ```dart
/// final result = await client.query('users:list', {'limit': '10'});
/// final users = jsonDecode(result);
/// ```
Future<String> query(String name, Map<String, String> args) async {
  // Implementation
}
```

--------------------------------

### Platform Channel Subscription Operation Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Invokes the subscribe method via MethodChannel, passing the subscription details.

```dart
MethodChannel.invokeMethod('subscribe', {subscriptionId: 1, name: "messages:list"})
```

--------------------------------

### Run Flutter App on Chrome

Source: https://github.com/jkuldev/convex_flutter/blob/main/WEB_PLATFORM_STATUS.md

Command to run the Flutter example application on the Chrome browser for web testing.

```bash
cd example
flutter run -d chrome
```

--------------------------------

### Dart Query Operation Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Initiates a query operation from the Dart client to the platform channel.

```dart
client.query("messages:list", {})
```

--------------------------------

### Platform Channel Set Authentication Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Sets the authentication token via MethodChannel to the native side.

```dart
MethodChannel.invokeMethod('setAuth', {token: "..."})
```

--------------------------------

### Trigger Auto-Connect on App Startup

Source: https://github.com/jkuldev/convex_flutter/blob/main/README.md

Initiate the WebSocket connection immediately when your application starts by triggering a lightweight query. This improves user experience by ensuring the connection is ready.

```dart
// In your home screen or app initialization
@override
void initState() {
  super.initState();
  // Trigger connection immediately with health check
  ConvexClient.instance.query('health:ping', {});
}
```

```dart
// Use any existing query to trigger connection
ConvexClient.instance.query('users:list', {'limit': '1'});
```

--------------------------------

### Dart Token Fetch and Parse Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Fetches and parses a JWT token for authentication, including expiry.

```dart
token = await fetchToken()
```

```dart
Parse JWT expiry
```

--------------------------------

### Platform Channel Query Operation Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Handles a query operation invoked via MethodChannel on the platform side.

```dart
MethodChannel.invokeMethod('query', {name: "messages:list", args: {}})
```

--------------------------------

### Rust SDK to Dart Data Type Conversion Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/doc/CONVEX_PROTOCOL.md

Illustrates the mapping between Rust SDK's HashMap/String to BTreeMap/Value and Dart's Map<String, String> to Map<String, dynamic> for web implementations.

```rust
// Rust SDK (from our codebase)
HashMap<String, String> → BTreeMap<String, Value>

// Dart (for web implementation)
Map<String, String> → Map<String, dynamic>
```

--------------------------------

### FatalError JSON Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/WEB_IMPLEMENTATION_COMPLETE.md

Example of a FatalError JSON object that indicates a protocol issue. This should no longer occur after protocol fixes.

```json
{"type":"FatalError","error":"unknown variant `subscribe`"}
```

--------------------------------

### Example Commit Message: Fix

Source: https://github.com/jkuldev/convex_flutter/blob/main/CONTRIBUTING.md

An example of a commit message for a bug fix, detailing the problem and the solution, along with an issue reference.

```git
fix(macos): Add missing network entitlements

Added com.apple.security.network.client entitlement to fix
WebSocket connection issues on macOS.

Fixes #456
```

--------------------------------

### Accessing the Client and Basic Operations

Source: https://github.com/jkuldev/convex_flutter/blob/main/README.md

Demonstrates how to access the singleton client instance and perform common operations like querying, subscribing, and mutating data.

```APIDOC
## Accessing the Client and Basic Operations

```dart
// Access the client anywhere in your app
void example() async {
  final client = ConvexClient.instance;

  // Optional: authenticate (see Authentication section below)
  await client.setAuth(token: 'YOUR_AUTH_TOKEN');

  // Query (with timeout)
  try {
    final users = await client.query('users:list', {'limit': '10'});
    print('Users: $users');
  } on TimeoutException {
    print('Connection timeout!');
  }

  // Subscribe to real-time updates
  final sub = await client.subscribe(
    name: 'messages:list',
    args: {},
    onUpdate: (value) => print('Update: $value'),
    onError: (message, value) => print('Error: $message ${value ?? ''}'),
  );

  // Mutation
  await client.mutation(
    name: 'messages:send',
    args: {'body': 'Hello!', 'author': 'User123'},
  );

  // Action (if you have actions defined)
  // final res = await client.action(name: 'files:upload', args: {...});

  // Later, when done
  sub.cancel();
}
```
```

--------------------------------

### Web Build Time Comparison

Source: https://github.com/jkuldev/convex_flutter/blob/main/MIGRATION_v3.md

Compares build times for the initial web build versus subsequent builds, highlighting the speed improvement after the first compilation.

```bash
# First build
flutter build web  # ~1-2 minutes

# Subsequent builds
flutter build web  # ~30-60 seconds
```

--------------------------------

### WebSocket Close Code Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/WEB_IMPLEMENTATION_COMPLETE.md

Example of a WebSocket close code logged in the browser console. Code 1005 after a FatalError suggests a protocol violation.

```text
=== [WebConvexClient] Close code: 1005, reason: "", wasClean: true ===
```

--------------------------------

### Find and check system libraries with PkgConfig

Source: https://github.com/jkuldev/convex_flutter/blob/main/example/linux/flutter/CMakeLists.txt

Uses PkgConfig to find and check for required system libraries like GTK, GLIB, and GIO, making them available for the build. Ensures these libraries are available and configured correctly.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
pkg_check_modules(GLIB REQUIRED IMPORTED_TARGET glib-2.0)
pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)
```

--------------------------------

### ConvexClient.initialize

Source: https://github.com/jkuldev/convex_flutter/blob/main/README.md

Initializes the singleton Convex client with the provided configuration. This must be called before using other client methods.

```APIDOC
## ConvexClient.initialize(ConvexConfig)

### Description
Initialize singleton client with configuration.

### Method
`ConvexClient.initialize`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (ConvexConfig) - Required - The configuration object for the Convex client.
```

--------------------------------

### Login to pub.dev

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Authenticate with pub.dev to publish packages.

```bash
dart pub login
```

--------------------------------

### Dart Subscription Cancellation Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Cancels an active subscription via MethodChannel.

```dart
sub.cancel() → MethodChannel.invokeMethod('cancelSubscription', {subscriptionId: 1})
```

--------------------------------

### Run All Tests

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Execute all unit and integration tests locally. Ensure this command passes before proceeding with the release.

```bash
flutter test
```

--------------------------------

### Initialize Convex Client with Alternative Query

Source: https://github.com/jkuldev/convex_flutter/blob/main/example/HEALTH_CHECK.md

Demonstrates initializing the Convex client with an existing lightweight query as the health check. This is an alternative to creating a dedicated health check endpoint.

```dart
// Use any existing query
await ConvexClient.initialize(
  ConvexConfig(
    healthCheckQuery: "users:count", // Any lightweight query
  ),
);
```

--------------------------------

### Add convex_flutter to Flutter Project

Source: https://github.com/jkuldev/convex_flutter/blob/main/README.md

Install the convex_flutter package using Flutter's package manager.

```bash
flutter pub add convex_flutter
```

--------------------------------

### Dart Scheduled Token Refresh Example

Source: https://github.com/jkuldev/convex_flutter/blob/main/native impl.md

Schedules a timer for automatic token refresh based on expiry.

```dart
Schedule Timer for (expiry - 60s)
```

```dart
Timer fires → repeat from step 3
```

--------------------------------

### Publish Package to pub.dev

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_PREPARATION_SUMMARY.md

Perform a dry run to review the package contents before publishing. Then, publish the package to pub.dev.

```bash
# Dry run
flutter pub publish --dry-run

# Review output, then publish
flutter pub publish
```

--------------------------------

### Run Tests, Analyze, and Format Code

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_PREPARATION_SUMMARY.md

Execute tests, analyze code for quality, and format the codebase. Ensure all checks pass before proceeding with the release.

```bash
# Run tests
flutter test

# Analyze code
flutter analyze

# Format code
dart format . --set-exit-if-changed
```

--------------------------------

### Create Git Tag

Source: https://github.com/jkuldev/convex_flutter/blob/main/PUB_DEPLOY_GUIDE.md

Create a lightweight Git tag for the release version and push it to the remote repository.

```bash
git tag v2.2.0
git push origin v2.2.0
```

--------------------------------

### Native Build Time Comparison

Source: https://github.com/jkuldev/convex_flutter/blob/main/MIGRATION_v3.md

Compares build times for the initial native build (including Rust compilation) versus subsequent builds where Rust is cached.

```bash
# First build (includes Rust compilation)
flutter build apk  # ~3-5 minutes

# Subsequent builds (Rust cached)
flutter build apk  # ~1-2 minutes
```

--------------------------------

### Set up a real-time subscription with ConvexClient.subscribe

Source: https://context7.com/jkuldev/convex_flutter/llms.txt

Use `ConvexClient.subscribe` for real-time data updates from Convex queries. Provide callbacks for data updates and errors. Remember to cancel the subscription in `dispose` to prevent memory leaks.

```dart
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:convex_flutter/convex_flutter.dart';

class MessageList extends StatefulWidget {
  const MessageList({super.key});
  @override
  State<MessageList> createState() => _MessageListState();
}

class _MessageListState extends State<MessageList> {
  SubscriptionHandle? _subscription;
  List<Map<String, dynamic>> _messages = [];

  @override
  void initState() {
    super.initState();
    _startSubscription();
  }

  Future<void> _startSubscription() async {
    _subscription = await ConvexClient.instance.subscribe(
      name: 'messages:list',
      args: {},                              // pass filter args here if needed
      onUpdate: (String jsonValue) {
        // Called on every backend change
        // jsonValue: '[{"body":"Hello","author":"Alice"},...]'
        final List<dynamic> parsed = jsonDecode(jsonValue);
        setState(() {
          _messages = parsed.cast<Map<String, dynamic>>();
        });
      },
      onError: (String message, String? details) {
        debugPrint('Subscription error: $message ${details ?? ""}');
      },
    );
  }

  @override
  void dispose() {
    _subscription?.cancel(); // always cancel to avoid memory leaks
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemCount: _messages.length,
      itemBuilder: (_, i) => ListTile(
        title: Text(_messages[i]['body'] as String),
        subtitle: Text(_messages[i]['author'] as String? ?? ''),
      ),
    );
  }
}
```

--------------------------------

### Convex Mutation Client Request

Source: https://github.com/jkuldev/convex_flutter/blob/main/doc/CONVEX_PROTOCOL.md

Example JSON structure for a client-initiated mutation operation. Used for modifying data on the Convex backend.

```json
{
  "type": "mutation",
  "id": "unique-request-id",
  "name": "messages:send",
  "args": {
    "body": "Hello, world!",
    "author": "user123"
  }
}
```

--------------------------------

### Convex Query Client Request

Source: https://github.com/jkuldev/convex_flutter/blob/main/doc/CONVEX_PROTOCOL.md

Example JSON structure for a client-initiated query operation. Use a unique ID for request correlation.

```json
{
  "type": "query",
  "id": "unique-request-id",
  "name": "messages:list",
  "args": {
    "limit": 10,
    "author": "user123"
  }
}
```

--------------------------------

### Login to pub.dev

Source: https://github.com/jkuldev/convex_flutter/blob/main/PUB_DEPLOY_GUIDE.md

Authenticate with pub.dev using the dart CLI before publishing.

```bash
# Login to pub.dev
dart pub login
```

--------------------------------

### Build Flutter app for web

Source: https://github.com/jkuldev/convex_flutter/blob/main/MIGRATION_v3.md

Build your Flutter application for the web platform. This command does not require a Rust toolchain.

```bash
flutter build web
```

--------------------------------

### Convex Action Client Request

Source: https://github.com/jkuldev/convex_flutter/blob/main/doc/CONVEX_PROTOCOL.md

Example JSON structure for a client-initiated action operation. Used for executing server-side logic, such as API calls.

```json
{
  "type": "action",
  "id": "unique-request-id",
  "name": "files:upload",
  "args": {
    "fileName": "document.pdf",
    "url": "https://example.com/file"
  }
}
```

--------------------------------

### Distributing Binaries: Build Rust for all targets

Source: https://github.com/jkuldev/convex_flutter/blob/main/ARCHITECTURE.md

This outlines the process of building the Rust code for various target platforms to distribute pre-compiled native binaries with the package.

```plaintext
1. Package maintainer builds Rust code for all targets:
   - Android: arm64-v8a, armeabi-v7a, x86_64, x86
   - iOS: arm64 (device), x86_64 (simulator)
   - macOS: arm64 (Apple Silicon), x86_64 (Intel)
   - Windows: x86_64
   - Linux: x86_64, arm64

2. Include all binaries in package (in android/libs/, ios/, etc.)

3. Flutter build system uses pre-built binaries instead of compiling
```

--------------------------------

### Convex Subscribe Client Request

Source: https://github.com/jkuldev/convex_flutter/blob/main/doc/CONVEX_PROTOCOL.md

Example JSON structure for a client-initiated subscription request. Used to receive real-time updates when query results change.

```json
{
  "type": "subscribe",
  "id": "subscription-id",
  "name": "messages:list",
  "args": {
    "limit": 10
  }
}
```

--------------------------------

### Enable Web and Run on Chrome

Source: https://github.com/jkuldev/convex_flutter/blob/main/MIGRATION_v3.md

Commands to enable Flutter web support and run the application on the Chrome browser.

```bash
flutter config --enable-web
flutter run -d chrome
```

--------------------------------

### Transition Message (Query Updates)

Source: https://github.com/jkuldev/convex_flutter/blob/main/doc/REAL_CONVEX_PROTOCOL.md

Received from the server to provide updates for subscribed queries. Contains start and end versions, and modifications with query results.

```json
{
  "type": "Transition",
  "startVersion": { "ts": 123, "identity": "..." },
  "endVersion": { "ts": 124, "identity": "..." },
  "modifications": [{
    "queryId": 1,
    "value": [...],  // Query result
    "logLines": []
  }]
}
```

--------------------------------

### Project Structure Overview

Source: https://github.com/jkuldev/convex_flutter/blob/main/CONTRIBUTING.md

Understand the organization of the Convex Flutter project files and directories.

```plaintext
convex_flutter/
├── lib/                          # Dart source code
│   ├── convex_flutter.dart       # Public API exports
│   ├── src/
│   │   ├── convex_client.dart    # Main client (platform-agnostic)
│   │   ├── impl/
│   │   │   ├── convex_client_web.dart     # Web implementation (pure Dart)
│   │   │   └── convex_client_native.dart  # Native implementation (FFI)
│   │   ├── rust/                 # Generated FFI bindings
│   │   ├── convex_config.dart    # Configuration class
│   │   ├── connection_status.dart
│   │   ├── app_lifecycle_*.dart
│   │   └── ...                   # Other Dart utilities
│
├── rust/                         # Rust source code (native platforms)
│   ├── Cargo.toml                # Rust dependencies
│   ├── src/
│   │   ├── lib.rs                # Main Rust implementation
│   │   └── frb_generated.rs      # Generated FFI code
│   └── target/                   # Build artifacts
│
├── example/                      # Example Flutter app
│   ├── lib/main.dart             # Example app code
│   ├── android/                  # Android configuration
│   ├── ios/                      # iOS configuration
│   ├── macos/                    # macOS configuration
│   ├── web/                      # Web configuration
│   └── ...
│
├── test/                         # Unit tests
├── ARCHITECTURE.md               # Architecture documentation
├── PLATFORM_CONFIGURATION.md     # Platform setup guide
├── CHANGELOG.md                  # Version history
└── README.md                     # Main documentation
```

--------------------------------

### Trigger Health Check on App Startup

Source: https://github.com/jkuldev/convex_flutter/blob/main/example/HEALTH_CHECK.md

Initiates a health check query automatically when the Flutter app starts. This helps establish the WebSocket connection promptly.

```dart
await ConvexClient.instance.query('health:ping', {});
```

--------------------------------

### Initialize Convex Client and Query Data

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_NOTES_v3.0.0.md

Instantiate the Convex client and make a query. This code works across web, iOS, Android, macOS, Windows, and Linux.

```dart
// One codebase, all platforms 🌐📱💻
final client = ConvexClient.instance;
final data = await client.query('myQuery', {});
// Works on web, iOS, Android, macOS, Windows, Linux!
```

--------------------------------

### Tag and Push Release to GitHub

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_PREPARATION_SUMMARY.md

Tag the release with the version number and push the release branch and tag to GitHub. This makes the release visible and accessible.

```bash
# Tag release
git tag -a v3.0.0 -m "Release version 3.0.0: Web platform support"

# Push to GitHub
git push origin release/v3.0.0
git push origin v3.0.0
```

--------------------------------

### Flutter Build Process with FFI

Source: https://github.com/jkuldev/convex_flutter/blob/main/ARCHITECTURE.md

This illustrates how the Flutter build system automatically compiles Rust code for FFI plugins when building an app, and the error encountered if the Rust toolchain is missing.

```bash
# When you run:
flutter build apk

# Flutter build system:
# 1. Detects FFI plugin (ffiPlugin: true)
# 2. Looks for Rust source in rust/ directory
# 3. Invokes `cargo build --release` for target platform
# 4. Compiles Rust code to native library (.so, .dylib, .dll)
# 5. Bundles native library into app package
# 6. ❌ FAILS if Rust toolchain not installed
```

```bash
Error: Unable to find cargo in PATH. Rust toolchain is required.
Please install Rust from https://rustup.rs
```

--------------------------------

### Mutation Protocol: Before vs. After

Source: https://github.com/jkuldev/convex_flutter/blob/main/WEB_IMPLEMENTATION_COMPLETE.md

Illustrates the difference between the incorrect 'before' and the correct 'after' formats for the Mutation operation in the Convex wire protocol. Key changes include capitalization of 'type' and the structure of 'args'.

```json
{ "type": "mutation", "id": "web-456", "name": "messages:send", "args": {"body": "Hello"} }
```

```json
{ "type": "Mutation", "requestId": "web-456", "udfPath": "messages:send", "args": [{"body": "Hello"}] }
```

--------------------------------

### Run Tests

Source: https://github.com/jkuldev/convex_flutter/blob/main/CONTRIBUTING.md

Execute the project's test suite to ensure changes do not introduce regressions.

```bash
# Run tests
flutter test
```

--------------------------------

### Run Tests with Coverage

Source: https://github.com/jkuldev/convex_flutter/blob/main/CONTRIBUTING.md

Generate a code coverage report for the project's tests.

```bash
flutter test --coverage
```

--------------------------------

### Publish Package to pub.dev

Source: https://github.com/jkuldev/convex_flutter/blob/main/PUB_DEPLOY_GUIDE.md

Publish your package to pub.dev. Ensure you are on the main branch and have pulled the latest changes. You will be prompted to log in.

```bash
git checkout main
git pull
flutter pub publish
```

--------------------------------

### Apply Standard Build Settings

Source: https://github.com/jkuldev/convex_flutter/blob/main/example/windows/runner/CMakeLists.txt

Applies a predefined set of build settings to the application target. This can be removed if custom build configurations are required.

```cmake
apply_standard_settings(${BINARY_NAME})
```

--------------------------------

### Action Message

Source: https://github.com/jkuldev/convex_flutter/blob/main/doc/REAL_CONVEX_PROTOCOL.md

Initiates an action on the server. Include a unique requestId, the udfPath, and arguments.

```json
{
  "type": "Action",
  "requestId": "req-124",
  "udfPath": "actions:processPayment",
  "args": [{ "amount": 100 }]
}
```

--------------------------------

### Create Annotated Git Tag

Source: https://github.com/jkuldev/convex_flutter/blob/main/PUB_DEPLOY_GUIDE.md

Create an annotated Git tag with release notes for the specified version and push it to the remote repository.

```bash
git tag -a v2.2.0 -m "Release v2.2.0: WebSocket Connection State Monitoring

- Real-time WebSocket connection state streams
- Fixed critical race condition in connection initialization
- Fixed connection state stuck on 'connecting'
- Enhanced documentation with health check guide
- New connection state APIs
- Comprehensive example app with 5 screens"
git push origin v2.2.0
```

--------------------------------

### Apply Standard Build Settings

Source: https://github.com/jkuldev/convex_flutter/blob/main/example/linux/runner/CMakeLists.txt

Applies a standard set of build settings to the specified target. This can be removed if custom build settings are required.

```cmake
# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})
```

--------------------------------

### Create Release Branch and Commit Changes

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_PREPARATION_SUMMARY.md

Create a new branch for the release and commit any final changes. This prepares the repository for tagging and pushing.

```bash
# Create release branch
git checkout -b release/v3.0.0

# Commit any final changes
git add .
git commit -m "chore: Prepare for v3.0.0 release"
```

--------------------------------

### Create Release Branch

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Use this command to create a new branch for the release.

```bash
git checkout -b release/v3.0.0
```

--------------------------------

### Add Dependency Libraries

Source: https://github.com/jkuldev/convex_flutter/blob/main/example/linux/runner/CMakeLists.txt

Links necessary libraries to the application target. Add any application-specific dependencies here.

```cmake
# Add dependency libraries. Add any application-specific dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter)
target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)
```

--------------------------------

### Verify macOS Network Permissions

Source: https://github.com/jkuldev/convex_flutter/blob/main/MIGRATION_v3.md

Use grep to check if 'network.client' is present in the DebugProfile.entitlements file for macOS.

```bash
grep "network.client" macos/Runner/DebugProfile.entitlements
```

--------------------------------

### Initialize ConvexClient Singleton

Source: https://context7.com/jkuldev/convex_flutter/llms.txt

Call ConvexClient.initialize once in main() before any other SDK usage. This sets up the platform-specific WebSocket client.

```dart
import 'package:flutter/material.dart';
import 'package:convex_flutter/convex_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await ConvexClient.initialize(
    ConvexConfig(
      deploymentUrl: 'https://my-app.convex.cloud', // required
      clientId: 'flutter-app-1.0',                  // optional, default: 'flutter-client'
      operationTimeout: const Duration(seconds: 30), // optional, default: 30s
      healthCheckQuery: 'health:ping',               // optional, for manual checkConnection()
    ),
  );

  runApp(const MyApp());
}

// Access the singleton from anywhere in the widget tree:
void someFunction() {
  final client = ConvexClient.instance;
  print(client.config.deploymentUrl); // https://my-app.convex.cloud
}
```

--------------------------------

### Fetch and Rebase from Main

Source: https://github.com/jkuldev/convex_flutter/blob/main/RELEASE_CHECKLIST.md

Update the local branch with the latest changes from the 'main' branch and reapply local commits on top. This ensures the branch is up-to-date and avoids merge conflicts.

```bash
git fetch origin
git rebase origin/main
```

--------------------------------

### Integrate Flutter and System Dependencies

Source: https://github.com/jkuldev/convex_flutter/blob/main/example/linux/CMakeLists.txt

Includes the Flutter build rules and finds system-level dependencies like GTK using PkgConfig.

```cmake
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})

find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)

add_subdirectory("runner")

add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Project and Build Configuration

Source: https://github.com/jkuldev/convex_flutter/blob/main/example/linux/CMakeLists.txt

Sets the minimum CMake version, project name, executable name, and application ID. It also configures build type and enables modern CMake behaviors.

```cmake
cmake_minimum_required(VERSION 3.13)
project(runner LANGUAGES CXX)

set(BINARY_NAME "convex_flutter_example")
set(APPLICATION_ID "com.example.convex_flutter")

cmake_policy(SET CMP0063 NEW)

set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")

if(FLUTTER_TARGET_PLATFORM_SYSROOT)
  set(CMAKE_SYSROOT ${FLUTTER_TARGET_PLATFORM_SYSROOT})
  set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})
  set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
  set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
endif()

if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
  set(CMAKE_BUILD_TYPE "Debug" CACHE
    STRING "Flutter build mode" FORCE)
  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
    "Debug" "Profile" "Release")
endif()
```

--------------------------------

### Plugin Configuration for FFI Platforms

Source: https://github.com/jkuldev/convex_flutter/blob/main/ARCHITECTURE.md

Configure your `pubspec.yaml` to enable FFI plugins for various native platforms.

```yaml
flutter:
  plugin:
    platforms:
      android:
        ffiPlugin: true    # ← This marks it as FFI plugin
      ios:
        ffiPlugin: true
      linux:
        ffiPlugin: true
      macos:
        ffiPlugin: true
      windows:
        ffiPlugin: true
```

--------------------------------

### Publish Package

Source: https://github.com/jkuldev/convex_flutter/blob/main/PUB_DEPLOY_GUIDE.md

Publish the Convex Flutter package to pub.dev using the flutter CLI.

```bash
flutter pub publish
```