togglit_sdk 0.0.3

Dart SDK for accessing configuration from ToggLit

ToggLit SDK (Flutter / Dart)

A lightweight Dart SDK for fetching configuration from ToggLit — the JSON Config-as-a-Service platform — with fallback support and environment-based versioning.

Installation

Add the package to your pubspec.yaml:

dependencies:
  togglit_sdk: ^0.0.1

Then run:

flutter pub get

Or with Dart:

dart pub get

Quick Start

import 'package:togglit_sdk/togglit_sdk.dart';

void main() async {
  final config = await TogglitConfig.getConfig(
    apiKey: "tk_live_xxxxxxx",
    projectId: "togglit-demo",
    env: "production",
    version: 1,
    fallback: {
      "feature_flag": false,
      "api_url": "https://api.fallback.com",
    },
  );

  print(config);
}

API Reference

TogglitConfig.getConfig({...})

Fetches configuration from ToggLit with automatic fallback support and comprehensive error handling.

Parameters

Parameter	Type	Required	Description
apiKey	String	✅	Your Togglit API key
projectId	String	✅	Your project identifier
env	String	✅	Environment name (e.g., 'production', 'dev')
version	int?	❌	Specific configuration version to fetch
fallback	Map<String, dynamic>?	❌	Fallback configuration object (default: {})

Returns

Future<Map<String, dynamic>> - The configuration object or fallback if request fails.

Example

// Basic usage
final config = await TogglitConfig.getConfig(
  apiKey: "tk_live_xxxxxxx",
  projectId: "my-app",
  env: "production",
);

// With fallback configuration
final config = await TogglitConfig.getConfig(
  apiKey: "tk_live_xxxxxxx",
  projectId: "my-app",
  env: "production",
  fallback: {
    "enableBetaFeatures": false,
    "maintenanceMode": false,
    "apiUrl": "https://fallback.example.com",
    "timeout": 5000,
  },
);

// With specific version
final config = await TogglitConfig.getConfig(
  apiKey: "tk_live_xxxxxxx",
  projectId: "my-app",
  env: "production",
  version: 2,
);

Features

• Seamless Configuration Management: Fetch configurations with simple method calls
• Version Control: Access specific versions of your configuration
• Fallback Support: Automatic fallback configurations for resilience
• Environment-Specific: Multi-environment support (dev, staging, production)
• Minimal Dependencies: Uses only http and dart:convert
• Null Safety: Fully null-safe and works with latest Dart SDK
• Cross-Platform: Works in Flutter mobile, web, desktop, and Dart server apps

Environment Configuration

The SDK fetches configuration from:

https://togglit.dev/api/config

Make sure your project is published and accessible through ToggLit with proper API key authentication.

Usage Examples

Basic Workflow

import 'package:togglit_sdk/togglit_sdk.dart';

void main() async {
  // 1. Fetch configuration
  final config = await TogglitConfig.getConfig(
    apiKey: "tk_live_xxxxxxx",
    projectId: "my-app",
    env: "production",
    fallback: {
      "enableBetaFeatures": false,
      "maintenanceMode": false,
    },
  );

  // 2. Use configuration in your app
  if (config["enableBetaFeatures"] == true) {
    // Show beta features
  }

  if (config["maintenanceMode"] == true) {
    // Show maintenance screen
  }
}

Feature Flags

final config = await TogglitConfig.getConfig(
  apiKey: "tk_live_xxxxxxx",
  projectId: "my-app",
  env: "production",
  fallback: {
    "enableBetaFeatures": false,
    "enableDarkMode": true,
    "showOnboarding": true,
    "enablePushNotifications": false,
  },
);

// Use feature flags throughout your app
class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: config["enableDarkMode"] ? ThemeData.dark() : ThemeData.light(),
      home: config["showOnboarding"] ? OnboardingScreen() : HomeScreen(),
    );
  }
}

API Configuration

final config = await TogglitConfig.getConfig(
  apiKey: "tk_live_xxxxxxx",
  projectId: "my-service",
  env: "production",
  fallback: {
    "apiUrl": "https://fallback.example.com",
    "timeout": 5000,
    "retryCount": 3,
    "enableLogging": false,
  },
);

// Configure API client
final apiClient = ApiClient(
  baseUrl: config["apiUrl"],
  timeout: Duration(milliseconds: config["timeout"]),
  retryCount: config["retryCount"],
  enableLogging: config["enableLogging"],
);

Environment-Specific Configuration

// Development environment
final devConfig = await TogglitConfig.getConfig(
  apiKey: "tk_dev_xxxxxxx",
  projectId: "my-app",
  env: "development",
  fallback: {
    "debug": true,
    "apiUrl": "https://dev-api.example.com",
    "enableAnalytics": false,
  },
);

// Production environment
final prodConfig = await TogglitConfig.getConfig(
  apiKey: "tk_live_xxxxxxx",
  projectId: "my-app",
  env: "production",
  fallback: {
    "debug": false,
    "apiUrl": "https://api.example.com",
    "enableAnalytics": true,
  },
);

Version Management

// Get latest configuration
final latestConfig = await TogglitConfig.getConfig(
  apiKey: "tk_live_xxxxxxx",
  projectId: "my-app",
  env: "production",
);

// Get specific version
final specificConfig = await TogglitConfig.getConfig(
  apiKey: "tk_live_xxxxxxx",
  projectId: "my-app",
  env: "production",
  version: 2,
);

// Rollback to previous version
final rollbackConfig = await TogglitConfig.getConfig(
  apiKey: "tk_live_xxxxxxx",
  projectId: "my-app",
  env: "production",
  version: 1,
);

Error Handling

The SDK includes comprehensive error handling to ensure your app continues to function even when configuration fetching fails:

• Network errors: Graceful handling of connectivity issues
• Authentication errors: Clear error messages for invalid API keys
• Configuration errors: Validation of project and environment parameters
• Automatic fallback: Returns fallback configuration when primary fetch fails

final config = await TogglitConfig.getConfig(
  apiKey: "invalid-key",
  projectId: "my-app",
  env: "production",
  fallback: {
    "feature_flag": false,
    "retry_limit": 3,
    "maintenance_mode": false,
  },
);

// Even with invalid API key, config will contain the fallback values
// Your app continues to work with sensible defaults

Configuration Priority

The SDK uses the following priority order when resolving configuration:

1. Remote configuration (fetched from ToggLit API)
2. Fallback configuration (provided in method parameters)
3. Empty configuration (if no fallback is provided)

Performance Considerations

• Async Loading: Use FutureBuilder or similar patterns for loading configurations in Flutter
• Background Refresh: Implement periodic configuration refresh for long-running apps

// Example with FutureBuilder in Flutter
class ConfiguredApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return FutureBuilder<Map<String, dynamic>>(
      future: TogglitConfig.getConfig(
        apiKey: "tk_live_xxxxxxx",
        projectId: "my-app",
        env: "production",
        fallback: {"loading": false},
      ),
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          return CircularProgressIndicator();
        }

        final config = snapshot.data ?? {};
        return MyApp(config: config);
      },
    );
  }
}

Platform Support

The ToggLit SDK works across all Dart/Flutter platforms:

• Flutter Mobile: iOS and Android apps
• Flutter Web: Web applications
• Flutter Desktop: Windows, macOS, and Linux applications
• Dart Server: Server-side Dart applications
• Dart CLI: Command-line tools and scripts

Security Considerations

• API Key Protection: Never expose API keys in client-side code for production apps
• Environment Variables: Use environment variables or secure storage for API keys
• Fallback Security: Ensure fallback configurations don't contain sensitive data

Null Safety

This SDK is fully null-safe and compatible with:

• Dart SDK 2.12+
• Flutter 2.0+
• All null-safe Flutter and Dart packages

License

MIT

Support

• 📘 Documentation: https://togglit.dev/docs
• 🎯 Pricing: https://togglit.dev/pricing

---

Made with ❤️ by the ToggLit team