dart_acdc library

ACDC - Advanced Client for Dio Communication

A production-ready HTTP client library built on top of Dio, providing:

Authentication:

Automatic token injection and refresh (OAuth 2.1 compliant)
Proactive refresh before token expiry
Reactive refresh on 401 responses
Concurrent request queuing during refresh
Token revocation on logout
Support for custom token refresh logic

Caching:

HTTP-compliant caching with Cache-Control support
User-based cache isolation
Optional encrypted cache storage
In-memory cache layer
Offline support with stale-while-revalidate

Error Handling:

Structured exception hierarchy
Developer-friendly error messages
Automatic retry with exponential backoff
Network error classification

Logging:

Environment-aware logging (debug vs release)
Sensitive data redaction
Custom logger integration
Request duration tracking

Quick Start

Zero-config usage (minimal setup):

import 'package:dart_acdc/dart_acdc.dart';

final dio = AcdcClientBuilder()
  .withBaseUrl('https://api.example.com')
  .build();

final response = await dio.get('/users');

With authentication:

// Implement TokenProvider to store/retrieve tokens
class MyTokenProvider implements TokenProvider {
  @override
  Future<String?> getAccessToken() async => // ... load from secure storage

  @override
  Future<String?> getRefreshToken() async => // ... load from secure storage

  @override
  Future<void> setTokens({
    required String accessToken,
    String? refreshToken,
    DateTime? accessExpiry,
    DateTime? refreshExpiry,
  }) async {
    // ... save to secure storage
  }

  @override
  Future<void> clearTokens() async {
    // ... clear from secure storage
  }

  @override
  Future<DateTime?> getAccessTokenExpiry() async => // ... optional

  @override
  Future<DateTime?> getRefreshTokenExpiry() async => // ... optional
}

final dio = AcdcClientBuilder()
  .withBaseUrl('https://api.example.com')
  .withTokenProvider(MyTokenProvider())
  .withTokenRefreshEndpoint(
    url: 'https://auth.example.com/oauth/token',
    clientId: 'my-client-id',
  )
  .withTokenRevocationEndpoint('https://auth.example.com/oauth/revoke')
  .build();

// Make authenticated requests
final response = await dio.get('/protected-resource');

// Logout
await dio.auth.logout();

With custom configuration:

final dio = AcdcClientBuilder()
  .withBaseUrl('https://api.example.com')
  .withTimeout(Duration(seconds: 30))
  .withLogLevel(LogLevel.debug)
  .withCache(CacheConfig(
    ttl: Duration(hours: 2),
    encrypted: true,
  ))
  .build();

Exception Handling

All HTTP and network errors are converted to typed exceptions:

try {
  final response = await dio.get('/users');
} on AcdcAuthException catch (e) {
  // Handle 401/403 errors
  print('Authentication error: ${e.message}');
} on AcdcServerException catch (e) {
  // Handle 5xx errors
  print('Server error: ${e.message}');
} on AcdcNetworkException catch (e) {
  // Handle network failures
  print('Network error: ${e.errorType}');
} on AcdcClientException catch (e) {
  // Handle 4xx errors (other than 401/403)
  print('Client error: ${e.message}');
}

Custom Logger

Integrate with your logging system:

class MyLogDelegate implements AcdcLogDelegate {
  @override
  void log(String message, LogLevel level, Map<String, dynamic> metadata) {
    // Forward to your logging system
    myLogger.log(level, message, metadata);
  }
}

final dio = AcdcClientBuilder()
  .withLogDelegate(MyLogDelegate())
  .build();

Advanced Features

Force token refresh:

await dio.auth.refreshNow();

Clear cache:

await dio.auth.clearCache();

Custom token refresh:

final dio = AcdcClientBuilder()
  .withTokenProvider(myTokenProvider)
  .withCustomTokenRefresh((refreshToken) async {
    // Your custom refresh logic
    final response = await myCustomRefreshCall(refreshToken);
    return TokenRefreshResult(
      accessToken: response.accessToken,
      refreshToken: response.newRefreshToken,
    );
  })
  .build();

Security Best Practices

Token Storage: Use platform secure storage (iOS Keychain, Android Keystore)
OAuth 2.1: This library follows OAuth 2.1 for public clients (no client_secret)
Cache Encryption: Enable for sensitive data with CacheConfig(encrypted: true)
HTTPS Only: Always use HTTPS URLs in production

Supported Dart/Flutter Versions

Dart SDK: >=3.6.0 <4.0.0
Flutter: >=3.38.0

License

See LICENSE file for details.

dart_acdc library

Quick Start

Exception Handling

Custom Logger

Advanced Features

Security Best Practices

Supported Dart/Flutter Versions

License

Classes

Enums

Extensions

Exceptions / Errors

dart_acdc package

dart_acdc library