api_result_kit 1.0.0

A typed Result/Error handling kit for Flutter apps. Normalizes errors from FastAPI, Express, and generic REST backends into a consistent ApiResult<T> type, with ready-made widgets for consistent UI er [...]

Changelog

1.0.0

Initial release.

Data layer

• ApiResult<T> — a sealed ApiSuccess<T> / ApiFailure<T> result type, with when, maybeWhen, map, flatMap, tap, dataOrNull, and errorOrNull. No code generation, no freezed dependency.
• ApiException — a normalized error shape with type, message, statusCode, fieldErrors, raw, retryable, and a suggestedDisplay recommendation for how to surface it in the UI.
• ApiErrorType — the seven error categories every failure is bucketed into: network, auth, validation, notFound, server, cancelled, unknown.
• ApiErrorParser — converts any caught error, including a DioException, into a normalized ApiException. Understands FastAPI's detail shape and Express's message / errors shapes out of the box. Extensible via addMessageParser and addFieldErrorParser for other backend conventions.

Calling your API

• Dio.safeRequest — wraps a single Dio call, returning an ApiResult<T> instead of throwing.
• Dio.safeRequestWithRetry — same as above, with automatic retry according to a RetryPolicy.
• RetryPolicy — configurable maxAttempts, initialDelay, backoffFactor, and an optional retryIf predicate. Ships with a RetryPolicy.none preset.
• SafeDioInterceptor — attach once to a Dio instance to get automatic retry and error normalization on every request made through it, with no per-call-site code required. Exposes onApiError and onRetry hooks.

Automatic error UI

• ApiResultKitNavigator — a global navigator key so non-widget code (like the interceptor) can reach a BuildContext.
• showDefaultErrorSnackbar — a ready-made onApiError callback that shows a themed RichSnackbar automatically, with sensible skip rules for validation and cancelled errors.
• withDefaultErrorSnackbar — composes the default snackbar with a custom callback, for example to redirect to a login screen on an auth failure.
• ApiErrorHandler — a BuildContext-based alternative for screens that already have a context in hand, with a configurable onAuthFailure redirect.
• Dio.safeRequestHandled — like safeRequest, but shows the appropriate error UI automatically via ApiErrorHandler.

Widgets

• ApiResultBuilder<T> — declaratively renders the success or failure branch of an ApiResult<T>.
• DefaultErrorWidget — a theme-aware fallback error view used by ApiResultBuilder, with an icon per error type, a field-error summary, and a conditional retry button.
• RichSnackbar — an Overlay-based snackbar system with top/bottom placement, four layouts (floatingSmall, floatingLarge, bannerSmall, bannerLarge), four entrance/exit animations, and icon, asset, network, or SVG leading visuals. Snackbars queue independently per screen edge and return a RichSnackbarHandle for early dismissal.

Testing

• Full test coverage for ApiResult, ApiException, ApiErrorParser, RetryPolicy, and SafeDioInterceptor, including every supported error shape, retry/backoff behavior, and edge cases around custom parser registration.