Contents #

Features #

• 🔄 Automatic token refresh with queue-safe retry
• ⚙️ onBeforeRefreshRequest to mutate refresh payload
• 🛠 Parsing responses into models or lists using INetKitModel
• 🧪 Configurable base URLs for development and production
• 🌐 Internationalization support for error messages
• 📦 Multipart upload support
• 📋 Extensible logger integration

Sponsors #

A big thanks to our awesome sponsors for keeping this project going!️ Want to help out? Consider becoming a sponsor!

Getting started #

Initialize #

Initialize the NetKitManager with the parameters:

import 'package:net_kit/net_kit.dart';

final netKitManager = NetKitManager(
  baseUrl: 'https://api.<URL>.com',
  devBaseUrl: 'https://dev.<URL>.com',
  // ... other parameters
);

Extend the model #

Requests such as: requestModel andrequestList require the model to extend INetKitModel in order to be used with the NetKitManager. By extending, INetKitModel fromJson and toJson methods will be needed to be implemented, so the model can be serialized and deserialized.

class TodoModel extends INetKitModel {}

Custom Void Models in Uploading #

⚠️ Custom Void Models: If you want to handle endpoints that return no data (i.e., void/empty responses) using your own model, your model must implement VoidModel from this package.

Example:

class AppVoidModel implements INetKitModel, VoidModel {
  @override
  Map<String, dynamic> toJson() => {};

  @override
  AppVoidModel fromJson(Map<String, dynamic> json) => AppVoidModel();
}

Without implementing VoidModel, void requests will not be recognized correctly and may throw exceptions.

Sending requests #

NetKitManager provides several methods for making HTTP requests. Each method is designed for specific use cases and response types.

Available Request Methods #

Request Examples #

• 📋 Request a Single Model →
• 📋 Request a List of Models →
• 📋 Send a Void Request →
• 📋 Request Model with Metadata →
• 📋 Request List with Metadata (Pagination) →
• 📋 Upload Multipart Data (Single File) →
• 📋 Upload Form Data →

Why DataKey is Used #

Many APIs return responses in a wrapped format where the actual data is nested under a specific key. For example:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "message": "User retrieved successfully"
}

Without DataKey configuration, you would need to manually extract the data from the data field in every response. NetKit's DataKey feature automatically handles this extraction, making your code cleaner and more maintainable.

DataKey Configuration #

The useDataKey parameter (default: true) allows you to control whether to use the configured dataKey wrapper for individual requests. This is useful when you have different API endpoints that return data in different formats.

• When useDataKey: true (default): Uses the configured dataKey to extract data from the response
• When useDataKey: false: Uses response.data directly, ignoring the dataKey configuration
• Note: This parameter has no effect if dataKey is not set in the NetKitManager configuration

Available on all request methods: requestModel, requestModelMeta, requestList, requestListMeta, uploadMultipartData, and uploadFormData.

Advanced Examples #

For more detailed examples including pagination, error handling, and real-world use cases, see EXAMPLES.md.

Setting Tokens #

The NetKitManager allows you to set and manage access and refresh tokens, which are essential for authenticated API requests. Below are the methods provided to set, update, and remove tokens.

Setting Access and Refresh Tokens

To set the access and refresh tokens, use the setAccessToken and setRefreshToken methods. The accessToken token will be added to the headers of every request made by the NetKitManager. Note: these should be set on every app launch or when the user logs in.

/// Your method to set the tokens
void setTokens(String accessToken, String refreshToken) {
  netKitManager.setAccessToken(accessToken);
  netKitManager.setRefreshToken(refreshToken);
}

User Logout #

When a user logs out, you should remove the access and refresh tokens using the removeAccessToken and removeRefreshToken methods.

Example:

/// Method to log out the user
void logoutUser() {
  netKitManager.removeAccessToken();
  netKitManager.removeRefreshToken();
}

Token Management #

NetKitManager provides comprehensive token management including automatic refresh, secure storage, and RFC-compliant authentication flows.

Quick Token Setup #

final netKitManager = NetKitManager(
  baseUrl: 'https://api.example.com',
  refreshTokenPath: '/auth/refresh-token',
  onTokenRefreshed: (authToken) async {
    await secureStorage.saveTokens(
      accessToken: authToken.accessToken,
      refreshToken: authToken.refreshToken,
    );
  },
);

Comprehensive Token Management #

For detailed token management documentation including:

• RFC Compliance (OAuth 2.0, Bearer Token, HTTP Authentication)
• Token Refresh Configuration with advanced options
• Secure Token Storage best practices
• Error Handling for token operations
• Security Considerations and best practices

📋 View Complete Token Management Guide →

Logger Integration #

The NetKitManager uses a logger internally, for example, during the refresh token stages. To add custom logging, you need to create a class that implements the INetKitLogger interface. Below is an example of how to create a NetworkLogger class:

You can find the full example of NetworkLogger here.

final netKitManager = NetKitManager(
  baseUrl: 'https://api.<URL>.com',
  logger: NetworkLogger(),
  // ... other parameters
);

Migration Guidance #

➡️ For detailed upgrade steps and breaking changes, see the full Migration Guide.

Feature Status #

Contributing #

Contributions are welcome! Please open an issue or submit a pull request.

License #

This project is licensed under the MIT License.