dio_curl_interceptor

pub package

A Flutter package with a Dio interceptor that logs HTTP requests as cURL—ideal for debugging. Includes a modern UI to view, filter, export logs, and integrate with custom interceptors.

Features

  • 🔍 Converts Dio HTTP requests to cURL commands for easy debugging and sharing.
  • 💾 Caches cURL commands and responses with filtering, search, and export options.
  • 🖥️ Modern Flutter widget for viewing and managing cURL logs (search, filter by status/date, export, clear, copy, etc).
  • 🔔 Webhook integration for remote logging and team collaboration (Discord & Telegram support, including bug and exception reporting).
  • 📝 Utility methods for custom interceptors and direct use.

For detailed screenshots of the interceptor's behavior, including simultaneous and chronological logging, please refer to the Screenshots section at the bottom of this README.

Terminal Compatibility

Below is a compatibility table for different terminals and their support for printing and ANSI colors:

-- currently being tested

Terminal/Console print/debugPrint log (dart:developer) ANSI Colors Support
VS Code Debug Console ✅ ✅ ✅
Android Studio Logcat -- -- --
Android Studio Debug Tab -- -- --
IntelliJ IDEA Console -- -- --
Flutter DevTools Console -- -- --
Terminal/CMD -- -- --
PowerShell -- -- --
Xcode Console -- -- --

Usage

Option 1: Using the CurlInterceptor

Simple add the interceptor to your Dio instance, all done for you:

final dio = Dio();
dio.interceptors.add(CurlInterceptor()); // Simple usage with default options
// or
dio.interceptors.add(CurlInterceptor.allEnabled()); // Enable all options

You can customize the interceptor with CurlOptions and CacheOptions:

dio.interceptors.add(CurlInterceptor(
  curlOptions: CurlOptions(
    status: true, // Show status codes + name in logs
    responseTime: true, // Show response timing
    convertFormData: true, // Convert FormData to JSON in cURL output
    behavior: CurlBehavior.chronological,
    onRequest: RequestDetails(
      visible: true,
      ansi: Ansi.yellow, // ANSI color for request
    ),
    onResponse: ResponseDetails(
      visible: true,
      requestHeaders: true, // Show request headers
      requestBody: true, // Show request body
      responseBody: true, // Show response body
      responseHeaders: true, // Show response headers
      limitResponseBody: null, // Limit response body length (characters), default is null (no limit)
      ansi: Ansi.green, // ANSI color for response
    ),
    onError: ErrorDetails(
      visible: true,
      requestHeaders: true,
      requestBody: true,
      responseBody: true,
      responseHeaders: true,
      limitResponseBody: null,
      ansi: Ansi.red, // ANSI color for errors
    ),
    // Configure pretty printing options
    prettyConfig: PrettyConfig(
      blockEnabled: true, // Enable pretty printing
      colorEnabled: true, // Force enable/disable colored
      emojiEnabled: true, // Enable/disable emoji
      lineLength: 100, // Set the length of separator lines
    ),
    // Custom printer function to override default logging behavior
    printer: (String text) {
      // do whatever you want with the text
      // ...
      // Your custom logging implementation
      print('Custom log: $text'); // remember to print the text
    },
  ),
  webhookInspectors: [
    DiscordInspector(
      webhookUrls: ['https://discord.com/api/webhooks/your-webhook-url'],
      inspectionStatus: [ResponseStatus.clientError, ResponseStatus.serverError],
      includeUrls: const ['/api/v1/users', 'https://example.com/data'],
      excludeUrls: const ['/api/v1/auth/login', 'https://example.com/sensitive'],
    ),
    TelegramInspector(
      webhookUrls: ['https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage'],
      inspectionStatus: [ResponseStatus.clientError, ResponseStatus.serverError],
      includeUrls: const ['/api/v1/users', 'https://example.com/data'],
      excludeUrls: const ['/api/v1/auth/login', 'https://example.com/sensitive'],
    ),
  ],
))

Option 2: Using CurlUtils directly in your own interceptor

If you prefer to use the utility methods in your own custom interceptor, you can use CurlUtils directly:

class YourInterceptor extends Interceptor {
  // Initialize webhook inspectors
  final webhookInspectors = [
    DiscordInspector(
      webhookUrls: ['https://discord.com/api/webhooks/your-webhook-url'],
      inspectionStatus: [ResponseStatus.clientError, ResponseStatus.serverError],
    ),
    TelegramInspector(
      webhookUrls: ['https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage'],
      inspectionStatus: [ResponseStatus.clientError, ResponseStatus.serverError],
    ),
  ];

  @override
  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
    // ... your request handling logic (like adding headers, modifying options, etc.)

    // for measure request time, it will add `X-Client-Time` header, then consume on response (error)
    CurlUtils.addXClientTime(options);

    CurlUtils.handleOnRequest(options);
    handler.next(options);
  }

  @override
  void onResponse(Response response, ResponseInterceptorHandler handler) {
    // ... your response handling logic
    CurlUtils.handleOnResponse(response, webhookInspectors: webhookInspectors);
    handler.next(response);
  }

  @override
  void onError(DioException err, ErrorInterceptorHandler handler) {
    // ... your error handling logic
    CurlUtils.handleOnError(err, webhookInspectors: webhookInspectors);
    handler.next(err);
  }
}

Using Multiple Webhook Inspectors

You can configure multiple webhook inspectors to send notifications to different services simultaneously. Each inspector operates independently with its own filters and configuration:

// Example of using multiple webhook inspectors
final webhookInspectors = [
  DiscordInspector(
    webhookUrls: ['https://discord.com/api/webhooks/your-discord-webhook'],
    inspectionStatus: [ResponseStatus.clientError, ResponseStatus.serverError],
    includeUrls: ['api.example.com'],
  ),
  TelegramInspector(
    webhookUrls: ['https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage'],
    inspectionStatus: [ResponseStatus.serverError], // Only server errors to Telegram
    includeUrls: ['api.example.com'],
  ),
];

// Use with CurlInterceptor
dio.interceptors.add(CurlInterceptor(
  webhookInspectors: webhookInspectors,
  // ... other options
));

Option 3: Using webhook integration

You can use webhook integration to send cURL logs to Discord channels or Telegram chats for remote logging and team collaboration:

// Using factory constructors for convenience
dio.interceptors.add(CurlInterceptor.withDiscordInspector(
  ['https://discord.com/api/webhooks/your-webhook-url'],
  includeUrls: ['api.example.com', '/users/'],
  excludeUrls: ['/healthz'],
  inspectionStatus: [ResponseStatus.clientError, ResponseStatus.serverError],
));

dio.interceptors.add(CurlInterceptor.withTelegramInspector(
  ['https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage'],
  includeUrls: ['api.example.com'],
  inspectionStatus: [ResponseStatus.serverError], // Only server errors
));

// Manual webhook sending
final discordInspector = DiscordInspector(
  webhookUrls: ['https://discord.com/api/webhooks/your-webhook-url'],
);

final telegramInspector = TelegramInspector(
  webhookUrls: ['https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage'],
);

// Send messages
await discordInspector.sendMessage(content: 'Hello from Discord!');
await telegramInspector.sendMessage(content: 'Hello from Telegram!');

// Send bug reports
await discordInspector.sendBugReport(
  error: 'Example Error',
  message: 'An example bug report.',
  extraInfo: {'userId': 'testUser', 'appVersion': '1.0.0'},
);

await telegramInspector.sendBugReport(
  error: 'Example Error',
  message: 'An example bug report.',
  extraInfo: {'userId': 'testUser', 'appVersion': '1.0.0'},
);

// Send files
await discordInspector.sendFiles(
  paths: ['/path/to/logfile.txt'],
  payload: {'message': 'Log file attached'},
);

await telegramInspector.sendFiles(
  paths: ['/path/to/logfile.txt'],
  payload: {'caption': 'Log file attached'},
);

Option 4: Using factory constructors for quick setup

For quick setup with common configurations, you can use the factory constructors:

// Discord-only setup
dio.interceptors.add(CurlInterceptor.withDiscordInspector(
  ['https://discord.com/api/webhooks/your-webhook-url'],
  includeUrls: ['api.example.com'],
  inspectionStatus: [ResponseStatus.clientError, ResponseStatus.serverError],
));

// Telegram-only setup
dio.interceptors.add(CurlInterceptor.withTelegramInspector(
  ['https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage'],
  includeUrls: ['api.example.com'],
  inspectionStatus: [ResponseStatus.serverError],
));

// Multiple webhook setup
dio.interceptors.add(CurlInterceptor.allEnabled(
  webhookInspectors: [
    DiscordInspector(webhookUrls: ['https://discord.com/api/webhooks/your-webhook-url']),
    TelegramInspector(webhookUrls: ['https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage']),
  ],
));

Option 5: Using utility functions directly

If you don't want to add a full interceptor, you can use the utility functions directly in your code:

// Generate a curl command from request options
final dio = Dio();
final response = await dio.get('https://example.com');

// Generate and log a curl command
CurlUtils.logCurl(response.requestOptions);

// Log response details
CurlUtils.handleOnResponse(response);

// Cache a successful response
CurlUtils.cacheResponse(response);

// Log error details
try {
  await dio.get('https://invalid-url.com');
} on DioException catch (e) {
  CurlUtils.handleOnError(e);

  // Cache an error response
  CurlUtils.cacheError(e);
}

## Dio Cache Storage

### Public Flutter Widget: cURL Log Viewer

Show pre-built popup cURL log viewer widget with `showCurlViewer(context)`:

```dart
ElevatedButton(
  onPressed: () => showCurlViewer(context),
  child: const Text('View cURL Logs'),
);

The log viewer supports:

  • Search and filter by status code, date range, or text
  • Export filtered logs to JSON
  • Copy cURL command
  • Clear all logs

Cache Storage Initialization

Before using caching or the log viewer, initialize storage in your main():

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await CachedCurlStorage.init();
  runApp(const MyApp());
}

Screenshots

Simultaneous (log the curl and response (error) together)

Simultaneous Screenshot

Chronological (log the curl immediately after the request is made)

Chronological Screenshot

Cached Viewer

Cached Viewer Screenshot

Inspect Bug Discord

Inspect Bug Discord Screenshot

Inspect cURL Discord

Inspect cURL Discord Screenshot

License

This project is licensed under the MIT License - see the LICENSE file for details.

  • Repository: GitHub
  • Bug Reports: Please file issues on the GitHub repository
  • Feature Requests: Feel free to suggest new features through GitHub issues

"Buy Me A Coffee"

Contributions are welcome! Please feel free to submit a Pull Request.

Libraries

dio_curl_interceptor