simple_network_handler_supabase library

Supabase integration for the simple_network_handler family.

Provides SupabaseHandler and SupabaseErrorRegistry for mapping Supabase exceptions (AuthException, PostgrestException, StorageException, FunctionException) to typed Failures, following the same patterns as the Dio package.

Usage:

import 'package:simple_network_handler_supabase/simple_network_handler_supabase.dart';

// Create your error registry
class MySupabaseErrorRegistry extends SupabaseErrorRegistry {
  @override
  SupabaseAuthErrorRegistry get authErrorRegistry => {
    'invalid_credentials': (e) => const InvalidCredentialsFailure(),
  };

  @override
  Failure get genericError => const GenericSupabaseFailure();
}

// Create once at app startup and inject it
final handler = SupabaseHandler(MySupabaseErrorRegistry());

// Use in repositories
Future<Result<User>> getCurrentUser() {
  return handler.safeCall(
    () => supabase.auth.getUser(),
  );
}

Classes

AuthFailure
Failure for authentication-related errors.
DuplicateEntryFailure
Failure for unique constraint violations (duplicate entries).
EmailNotConfirmedFailure
Failure for unverified email addresses.
Err<T>
Failed outcome carrying failure.
ExceptionMatcher
Predicate-based exception → Failure mapping.
Failure
Base class for all failures produced by this package.
FileNotFoundFailure
Failure for when a file/object is not found in storage.
FunctionFailure
Failure for Edge Function errors.
GenericSupabaseFailure
Generic Supabase failure for unhandled errors.
InvalidCredentialsFailure
Failure for invalid login credentials.
Ok<T>
Successful outcome carrying value.
PermissionDeniedFailure
Failure for permission/authorization errors.
PostgrestFailure
Failure for database/PostgREST errors.
RateLimitFailure
Failure for rate limiting errors.
RealtimeFailure
Failure for realtime/websocket connection errors.
RecordNotFoundFailure
Failure for when a database row/record is not found.
RequestCancelledFailure
The failure produced for a cancelled request.
Result<T>
The outcome of a network operation: either Ok with a value of type T or Err with a Failure.
SessionExpiredFailure
Failure for expired or invalid sessions.
StorageFailure
Failure for storage-related errors.
SupabaseErrorRegistry
Abstract error registry for Supabase-specific error handling
SupabaseFailure
Base class for Supabase-specific failures.
SupabaseHandler
Instance-based handler for safely executing Supabase operations with centralized error handling.
SupabaseNetworkFailure
Failure for network connectivity issues.
UserNotFoundSupabaseFailure
Failure for user not found scenarios.

Mixins

CancelledFailure
Marker for failures meaning "the caller aborted this request" — the user navigated away, typed a new search query, or signed out. Not an error: UIs should silently ignore it, and Result.mapBusiness lets it pass through repository mappers unchanged (like TransportFailure).
LocalizedFailure
Flutter-layer contract for failures that carry their own localized copy.
TransportFailure
Marker for failures representing a transport-level problem (the request never reached the backend / backend unreachable) rather than a business rule. Lets UIs and observers special-case connectivity once, regardless of feature.

Typedefs

FailureObserver = void Function(Failure failure, Object error, StackTrace stackTrace)
Observability hook: invoked with every failure a handler produces, together with the exception that caused it and its stack trace. Wire your error tracker (Sentry, Crashlytics, ...) here in one line:
SupabaseAuthErrorRegistry = Map<String, Failure Function(AuthException exception)>
Registry mapping AuthException error codes to failure factories
SupabaseErrorCodeRegistry = Map<String, SupabaseFailureFactory>
Registry mapping Supabase error codes to failure factories Key is the error code string (e.g., 'PGRST116', 'invalid_credentials')
SupabaseFailureFactory = Failure Function(Object error, String? message, int? statusCode)
Factory function that creates a Failure from a Supabase error
SupabaseFunctionErrorRegistry = Map<int, Failure Function(FunctionException exception)>
Registry mapping FunctionException status codes to failure factories
SupabaseGeneralErrorRegistry = Map<Type, Failure Function(Object exception)>
Registry mapping general exception types to failures
SupabaseStatusCodeRegistry = Map<int, SupabaseFailureFactory>
Registry mapping PostgrestException status codes to failure factories
SupabaseStorageErrorRegistry = Map<String, Failure Function(StorageException exception)>
Registry mapping StorageException error codes to failure factories

Exceptions / Errors

AuthException
FunctionException
PostgrestException
A Postgrest response exception
StorageException