api_provider

Releases

1. ▸▾2.0.07 Oct 2026Breaking

   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…

   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.