Skip to main content

smart_refresh_token 0.2.0 copy "smart_refresh_token: ^0.2.0" to clipboard
smart_refresh_token: ^0.2.0 copied to clipboard

Race-free automatic access/refresh token handling for Dio. Single-flight refresh, request replay, proactive JWT expiry refresh, logout-safe, and pluggable secure storage on every platform.

0.2.0 - 2026-11-10 #

A rewrite of the refresh engine focused on correctness under concurrency. Breaking: see "Migrating from 0.1.x" in the README.

Fixed #

  • Concurrent 401s triggered one refresh per request (serialised by a lock); now exactly one refresh runs and all waiting requests share its result.
  • A request sent with an old token after a refresh had already finished triggered another refresh; it is now just replayed with the current token.
  • Any refresh error (offline, timeout, 5xx) deleted the tokens and logged the user out; only a rejected refresh token (400/401/403, null, InvalidRefreshTokenException) ends the session now.
  • Passing the intercepted Dio as refreshDio deadlocked until the refresh timeout; refresher requests now bypass the interceptor automatically.
  • Logout during a refresh could be undone when the refresh completed.
  • Retries used a brand-new Dio(), losing the app's adapter, interceptors and certificate pinning; replays now go through the same Dio.
  • Requests made while logged out were rejected with a misleading cancel error and called onAuthFailure every time.
  • import 'dart:io' broke Flutter web; the package now has no dart:io.
  • The refresh timeout timer leaked, and a late refresh result after a timeout was lost (fatal with refresh-token rotation); it is now adopted.
  • RetryConfig retried non-idempotent requests (e.g. POST) and kept retrying after cancellation; RetryPolicy ignored its shouldRetry argument.
  • A FormData body could not be replayed.
  • Credentials.toString() printed the first 10 characters of each token.
  • refreshHeaders permanently mutated the user's refreshDio.
  • A failing TokenStorage.write after a refresh lost the new tokens.

Added #

  • authStatus stream (AuthStatus.unknown/authenticated/unauthenticated) for StreamBuilder, plus currentAuthStatus and isRefreshing.
  • setCredentials, validCredentials, refreshIfNeeded, dispose.
  • TokenRefreshLifecycleObserver: refresh on app resume.
  • Credentials.fromOAuthJson (RFC 6749 responses, rotation-aware), tokenType, JWT exp fallback (expiresAt), accessTokenClaims, nullable refreshToken for cookie-based refresh.
  • Jwt.tryDecodeClaims / Jwt.tryReadExpiry.
  • RefreshConfig.isAuthFailure, isRefreshTokenRejected, headerBuilder.
  • RefreshTokenException with RefreshFailureType, isSessionEnded, isTransient; InvalidRefreshTokenException.
  • Options().skipAuth() extension.
  • Cancellation support while waiting for a refresh.
  • RetryConfig.retryableMethods, RetryConfig.none().
  • Logger output sink; clock injection for tests.
  • Platforms declared in pubspec; 67 tests including concurrency and race tests.

Changed #

  • RefreshTokenInterceptor requires dio; tokenStorage (in-memory default) and onAuthFailure are optional.
  • TokenRefresher is now (Credentials current, Dio client).
  • OnAuthFailure receives the RefreshTokenException.
  • Default expirationBuffer is 1 minute (capped at half a token's lifetime); default header key is Authorization.
  • Network retries are opt-in.
  • Removed parallelRefresh, refreshHeaders, enableLogging, retryDio, RetryPolicy, TokenStorage.hasCredentials.
  • Dropped the synchronized and equatable dependencies.
  • Minimum SDK lowered to Dart 3.5 / Flutter 3.24.

0.1.2 - 2026-07-01 #

  • Updated to latest Flutter and Dart versions.
  • Upgraded dependencies: dio, synchronized, equatable.
  • Exported logger.dart for public use.
  • Fixed various linting issues and improved code quality.

0.1.1 - 2026-02-20 #

  • Compatible with latest Dart version

0.1.0 - 2026-02-05 #

Added #

  • Added InMemoryTokenStorage for quick starts and tests.
  • Added RefreshTokenInterceptor.skipAuthKey support to bypass auth injection/refresh for public endpoints.
  • Added retryDio option so retries can use a dedicated Dio instance.

Improved #

  • Improved refresh lock behavior: parallelRefresh now controls whether requests share the refresh lock.
  • Improved retry delay calculation to true exponential backoff with optional jitter.
  • Safer Credentials.toString() for short token strings.

Fixed #

  • Fixed README/API mismatch for refresh configuration and skip-auth usage.
  • Fixed metadata parsing in Credentials.fromJson for loosely typed maps.

0.0.3 - 2025-11-27 #

Added #

  • Dynamic retry logic (configurable backoff, max attempts).
  • Comprehensive examples demonstrating refresh + retry flows.
  • New RetryConfig for runtime retry customization.

Improved #

  • More stable token refresh interceptor.
  • Clearer documentation and example structure.

Fixed #

  • Missing platform folders in example project.

0.0.2 - 2025-10-08 #

Added #

  • Initial release of smart_refresh_token package.
  • Automatic Dio token refresh handling.
  • Support for secure token storage using flutter_secure_storage.

0.0.1 - 2025-10-08 #

Added #

  • Initial release of smart_refresh_token package.
2
likes
150
points
116
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Race-free automatic access/refresh token handling for Dio. Single-flight refresh, request replay, proactive JWT expiry refresh, logout-safe, and pluggable secure storage on every platform.

Repository (GitHub)
View/report issues

Topics

#dio #authentication #jwt #oauth #interceptor

License

MIT (license)

Dependencies

dio, flutter

More

Packages that depend on smart_refresh_token