api_provider 2.0.0
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.
RefreshTokenProviderwas never called, and the interceptor reacted to status360instead of401. 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 thecancelTokenyou 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
Dioyou 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:ioimport. - Request headers (the bearer token) are no longer written to the console, and logging is off in release builds.
get/post/...return a properly typedResponse<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'srefreshListenable,ValueListenableBuilder).RefreshTokenProvider.from(() async => ...)- no subclass needed.authHeader/authScheme- sendToken abc,X-Api-Key: abc, etc. instead ofAuthorization: Bearer abc.ApiErrorMessages- translate theuserMessagetexts (ApiErrorMessages.current = ...oruserMessageWith(...)), or turn off server messages withpreferServerMessage: false.serverMessagealso understands OAuth (error_description), JSON:API / GraphQLerrorsarrays, Laravel/Rails field errors and FastAPIdetail[].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.ApiProvideroptions:headers,connectTimeout/sendTimeout/receiveTimeout,enableLogging,interceptors,refreshOnStatusCodes,onUnauthorized, and your owndioinstance.skipAuth()to mark public endpoints (login, register) without touchingextraby hand.DioExceptionhelpers:userMessage,serverMessage,statusCode,isUnauthorized,isTimeout,isNetworkError,isCancelled,isMissingToken, ...ApiProvider.authToken,isAuthenticated,dio,head(),download(),close().MissingAuthTokenExceptioninstead of the string'Invalid Auth Object'.- Re-exports of the common Dio types (
Options,CancelToken,DioException,FormData, interceptor and handler types,HttpClientAdapter/ResponseBodyfor tests, ...) - no separatedioimport 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.
AuthManageris no longer a global singleton - everyApiProviderhas its own token.- Default timeouts: connect 15 s, send 30 s, receive 30 s (was 10 s / 10 s). They apply only to the
Diothe package creates; passconnectTimeoutetc. 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_storagestays 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 nowFuture<String?> onRefresh()and must return the new token (ornull).AuthManager's constructor is no longer a singleton factory; its methods were renamed (persistInteractObj->setToken,hasauthToken->load,deleteauthToken->clear,updateAuthToken->replaceToken). TheApiProvidermethods (persistToken,hasAuthToken,deleteAuthToken,updateAuthToken) are unchanged.BaseProvider.nameis optional;BaseApiClientno longer exposes a fixedDioconfiguration.- The
isSavedflag 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.