currency_sdk 1.0.0

Offline-first currency conversion SDK with 160+ currencies, powered by Cloudflare Workers edge computing. Real-time exchange rates updated every 2 hours with automatic caching.

Currency SDK

Offline-first currency conversion SDK with 160+ currencies, powered by Cloudflare Workers edge computing.

Real-time exchange rates updated every 2 hours with automatic caching for instant offline access.

✨ Features

• 🌍 160+ Currencies - All major currencies plus obscure ones (TVD, FJD, etc.)
• 📱 Offline-First - Instant response with Hive caching, works without internet
• ⚡ Edge-Powered - Cloudflare Workers for <50ms response times globally
• 🔒 Secure - API key authentication with rate limiting
• 💰 Free Tier - 10,000 requests/month, no credit card required
• 🔄 Auto-Updates - Exchange rates refresh every 2 hours via cron jobs
• 📦 Zero Config - Works out of the box, no API key needed for free tier

🚀 Quick Start

Installation

Add to your pubspec.yaml:

dependencies:
  currency_sdk: ^1.0.0

Or install via command line:

flutter pub add currency_sdk

Basic Usage

import 'package:currency_sdk/currency_sdk.dart';

void main() async {
  // Initialize (free tier - no API key needed)
  final client = CurrencyClient();
  await client.initialize();

  // Convert currency
  final amount = await client.convert(
    amount: 100,
    from: 'USD',
    to: 'EUR',
  );
  print('100 USD = $amount EUR');

  // Get all rates for a base currency
  final rates = await client.getRates('USD');
  print(rates.convert(100, 'GBP')); // Convert to any currency
  print(rates.conversionRates['JPY']); // Access raw rates
}

📖 Documentation

Initialize SDK

final client = CurrencyClient();
await client.initialize();

Must be called before using any other methods. Safe to call multiple times.

Convert Currency

// Simple conversion
final eurAmount = await client.convert(
  amount: 100,
  from: 'USD',
  to: 'EUR',
);

// Get full rate data
final usdRates = await client.getRates('USD');
final gbpAmount = usdRates.convert(100, 'GBP');
final jpyRate = usdRates.conversionRates['JPY'];

Offline Support

The SDK automatically caches exchange rates locally:

// Check connectivity
if (client.isOnline) {
  print('Using live data');
} else {
  print('Using cached data');
}

// Listen to connectivity changes
client.connectivityStream.listen((isOnline) {
  print(isOnline ? 'Connected' : 'Offline');
});

// Preload cache before going offline
await client.syncCurrencies(['USD', 'EUR', 'GBP']);

Get Supported Currencies

final currencies = await client.getSupportedCurrencies();
print('${currencies.length} currencies available'); // 160+
print(currencies); // ['AED', 'AFN', 'ALL', ..., 'ZMW', 'ZWL']

Error Handling

try {
  final amount = await client.convert(
    amount: 100,
    from: 'USD',
    to: 'INVALID',
  );
} on UnsupportedCurrencyException catch (e) {
  print('Currency not supported: ${e.currencyCode}');
} on NoCachedDataException catch (e) {
  print('Offline and no cached data for ${e.baseCurrency}');
} on RateLimitExceededException catch (e) {
  print('Rate limit exceeded. Resets at: ${e.resetAt}');
} on CurrencySDKException catch (e) {
  print('SDK error: ${e.message}');
}

💎 Paid Plans

Get Your API Key

For higher limits and priority support:

final client = CurrencyClient(apiKey: 'your_api_key');
await client.initialize();

Plans:

• Free: 10,000 requests/month
• Basic: 100,000 requests/month - $9/month
• Pro: 1,000,000 requests/month - $49/month

Get your API key at: https://dashboard.currency-sdk.com

Enterprise

Custom Cloudflare Workers for large teams:

final client = CurrencyClient.enterprise(
  apiKey: 'ent_abc123',
  workerUrl: 'https://your-company.workers.dev',
);
await client.initialize();

Contact sales for enterprise pricing.

🏗️ Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   Flutter   │────▶│   Currency SDK   │────▶│ Hive Cache  │
│     App     │     │   (This Package) │     │  (Offline)  │
└─────────────┘     └──────────────────┘     └─────────────┘
                             │
                             │ Online
                             ▼
                    ┌──────────────────┐
                    │ Cloudflare Worker│
                    │   (Edge Global)  │
                    └──────────────────┘
                             │
                    ┌────────┴────────┐
                    │  KV Cache (2h)  │
                    └─────────────────┘
                             │
                    ┌────────┴────────┐
                    │ ExchangeRate API│
                    │  (Cron: 2 hrs)  │
                    └─────────────────┘

Data Flow:

1. SDK checks Hive cache first (instant offline response)
2. If online and cache stale (>2h), fetches from Worker
3. Worker serves from KV cache (updated every 2h by cron)
4. Cache updated atomically (single source of truth)

🧪 Example App

See the example directory for a complete Flutter app demonstrating:

• Real-time currency conversion
• Offline mode indicator
• Error handling
• Connectivity monitoring
• Full UI implementation

Run the example:

cd example
flutter run

🔧 Advanced Usage

Manual Cache Management

// Check if cached data exists
if (client.hasCachedData('USD')) {
  print('USD rates cached');
}

// Clear all cached data
await client.clearCache();

// Listen to cache updates
client.cacheUpdateStream.listen((baseCurrency) {
  print('Cache updated for $baseCurrency');
});

Cleanup

// Dispose when done to prevent memory leaks
client.dispose();

📊 Supported Currencies (160+)

USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, SEK, NZD, MXN, SGD, HKD, NOK, KRW, TRY, INR, BRL, ZAR, DKK, PLN, THB, IDR, HUF, CZK, ILS, CLP, PHP, AED, COP, SAR, MYR, RON, and 127 more...

Including obscure currencies: TVD (Tuvalu Dollar), FJD (Fijian Dollar), etc.

🤝 Contributing

Contributions welcome! Please open an issue or PR on GitHub.

📄 License

MIT License - see LICENSE file for details.

🐛 Issues

Report bugs at: https://github.com/yourusername/currency_sdk/issues

📞 Support

• Documentation: https://github.com/yourusername/currency_sdk#readme
• Email: [e-mail]
• Discord: https://discord.gg/currency-sdk

---

Built with ❤️ using Flutter and Cloudflare Workers