Skip to main content

api_provider 2.0.0 copy "api_provider: ^2.0.0" to clipboard
api_provider: ^2.0.0 copied to clipboard

A thin, testable layer over Dio for Flutter apps - bearer-token auth, automatic token refresh with retry, secure token storage, and friendly error handling.

2.0.0 #

A rewrite focused on making token auth actually work and the package easy to test and use. Breaking changes are listed at the bottom - most apps only need the RefreshTokenProvider change.

Fixed #

  • Token refresh now works. RefreshTokenProvider was never called, and the interceptor reacted to status 360 instead of 401. Failed requests are replayed with the new token, keeping method, body, query and cancel token.
  • Concurrent 401s trigger a single refresh; the other requests wait for it and retry.
  • The retry path no longer hangs the request (the interceptor never completed its handler) or loops forever.
  • delete() now honours the cancelToken you pass (it was replaced by a fresh one).
  • Making an authenticated call from inside onRefresh() no longer hangs forever; it fails with the 401.
  • A Dio you pass in keeps its own timeouts and response type instead of being overwritten.
  • An unreadable keystore entry (Android after a backup restore / reinstall) no longer crashes start-up; the entry is dropped and the user signs in again.
  • Web builds: removed the nonexistent web plugin entry and the dart:io import.
  • Request headers (the bearer token) are no longer written to the console, and logging is off in release builds.
  • get/post/... return a properly typed Response<T> instead of an unchecked cast.

Added #

  • A saved login is restored automatically before the first authenticated request - forgetting hasAuthToken() on start-up no longer makes every request fail.
  • Requests started while a refresh is running wait for it instead of collecting another 401.
  • authTokenListenable - react to sign-in, refresh and sign-out (go_router's refreshListenable, ValueListenableBuilder).
  • RefreshTokenProvider.from(() async => ...) - no subclass needed.
  • authHeader / authScheme - send Token abc, X-Api-Key: abc, etc. instead of Authorization: Bearer abc.
  • ApiErrorMessages - translate the userMessage texts (ApiErrorMessages.current = ... or userMessageWith(...)), or turn off server messages with preferServerMessage: false.
  • serverMessage also understands OAuth (error_description), JSON:API / GraphQL errors arrays, Laravel/Rails field errors and FastAPI detail[].msg; HTML error pages are ignored.
  • isBadRequest, isConflict, isRateLimited (with a friendly 429 message), isClientError.
  • TokenStorage (+ SecureTokenStorage, MemoryTokenStorage) - plug in your own storage or fake it in tests.
  • ApiProvider options: headers, connectTimeout/sendTimeout/receiveTimeout, enableLogging, interceptors, refreshOnStatusCodes, onUnauthorized, and your own dio instance.
  • skipAuth() to mark public endpoints (login, register) without touching extra by hand.
  • DioException helpers: userMessage, serverMessage, statusCode, isUnauthorized, isTimeout, isNetworkError, isCancelled, isMissingToken, ...
  • ApiProvider.authToken, isAuthenticated, dio, head(), download(), close().
  • MissingAuthTokenException instead of the string 'Invalid Auth Object'.
  • Re-exports of the common Dio types (Options, CancelToken, DioException, FormData, interceptor and handler types, HttpClientAdapter/ResponseBody for tests, ...) - no separate dio import needed.
  • llms.txt - an AI-readable usage guide, so coding assistants integrate the package correctly.
  • A test suite (unit, integration through a fake HTTP adapter, and an example widget test) and CI.

Changed #

  • Now a pure Dart/Flutter package: the empty Android/iOS/Linux/macOS/Windows plugin stubs were removed.
  • AuthManager is no longer a global singleton - every ApiProvider has its own token.
  • Default timeouts: connect 15 s, send 30 s, receive 30 s (was 10 s / 10 s). They apply only to the Dio the package creates; pass connectTimeout etc. to override.
  • Minimum SDK is Dart 3.4 / Flutter 3.22. Dependencies updated (dio ^5.9, flutter_secure_storage ^10, flutter_lints ^6). flutter_secure_storage stays on 10.x on purpose: 11.x can't read data written by 9.x (what 1.x used), and 10.x migrates it, so upgrading users stay signed in.

Breaking #

  • RefreshTokenProvider.onRefresh() is now Future<String?> onRefresh() and must return the new token (or null).
  • AuthManager's constructor is no longer a singleton factory; its methods were renamed (persistInteractObj -> setToken, hasauthToken -> load, deleteauthToken -> clear, updateAuthToken -> replaceToken). The ApiProvider methods (persistToken, hasAuthToken, deleteAuthToken, updateAuthToken) are unchanged.
  • BaseProvider.name is optional; BaseApiClient no longer exposes a fixed Dio configuration.
  • The isSaved flag key is no longer written to secure storage. Tokens saved by 1.x are still read.

1.0.5 #

  • Removing and handling old dart versions.

1.0.3 #

  • Rethrowing Dio Exception for manual handling of exception according to your needs.

1.0.2 #

  • You can add your custom RefeshTokenProvider for refreshing token.

1.0.1 #

  • BaseProvider throws the error with error and cause.

1.0.0 #

  • Initial release for Api Provider many more to come.
4
likes
150
points
115
downloads

Documentation

API reference

Publisher

verified publisherperitumsolution.pk

Weekly Downloads

A thin, testable layer over Dio for Flutter apps - bearer-token auth, automatic token refresh with retry, secure token storage, and friendly error handling.

Repository (GitHub)
View/report issues

Topics

#http #dio #networking #authentication #api

Funding

Consider supporting this project:

buymeacoffee.com

License

MIT (license)

Dependencies

dio, flutter, flutter_secure_storage

More

Packages that depend on api_provider