SDKs behind application-owned contracts

Every dependency that crosses the application boundary is wrapped behind a contract the application owns. Feature code depends on contracts, never on SDKs.

Why

• Replaceable. Vendors change (PostHog → Amplitude, Sentry → Crashlytics). When only one adapter file imports the SDK, a migration touches one file.
• Testable. Tests override a provider with a fake; no platform channel, no MissingPluginException, no SDK initialisation in widget tests.
• Narrow. The contract exposes what the app needs (track(event)), not the SDK's whole surface, so features cannot misuse it.

The recipe

For a capability Foo (analytics, error tracking, clipboard, storage…):

1. Contract — abstract interface class FooService in core/foo/. Only app-owned types in its signatures. Document why on the methods whose behaviour is surprising.
2. App-owned vocabulary — if the SDK takes free-form input, close it: a sealed class AnalyticsEvent instead of track(String, Map).
3. Adapter — FirebaseFooService implements FooService. The only file that imports the SDK. It translates SDK errors into AppFailure (see flutter-result-errors) or swallows them if the contract says "never throws".
4. No-op — NoOpFooService for tests and disabled builds.
5. Provider — expose the contract, never the adapter:

   final fooServiceProvider = Provider<FooService>((ref) {
     final config = ref.watch(fooConfigProvider);
     return config.isEnabled ? SdkFooService(config) : const NoOpFooService();
   });

6. Test double — a recording fake in test/helpers/ (see assets/recording_analytics_service.dart). Prefer recording fakes to mocks: assertions read as "this event was tracked".

Naming: <Capability>Service. Adapter: <Vendor><Capability>Service.

Contract design rules

• No SDK types in parameters, return types or thrown exceptions.
• Fallible → AsyncResult<Unit> (or a typed value). Fire-and-forget reporting → Future<void> that never throws: reporting a failure must not fail the operation that caused it (ErrorTrackingService).
• Low-cardinality payloads. Never put tokens or emails in tags, properties or breadcrumbs.
• Keep one capability per contract. Do not make an AnalyticsAndCrash god interface.

Config and wiring

• A required config provider throws until overridden at the composition root, so a missing override fails loudly at startup:

  final networkConfigProvider = Provider<NetworkConfig>(
    (ref) => throw UnimplementedError('override in bootstrap'),
  );

• An optional capability defaults to disabled (AnalyticsConfig.disabled()) so widget and provider tests never initialise a platform SDK. Bootstrap overrides it for real runs.
• Feature code never calls Firebase…instance, Sentry.captureException or Dio(). Only adapters and provider files do.

Several destinations, one contract

When the same event must reach several vendors, compose behind the same contract (assets/composite_analytics_service.dart). Rules: call every destination even after one fails, and return the first failure so partial delivery stays visible. The provider picks 0 / 1 / many with a switch on the list length; features never learn the count.

The HTTP boundary (worked example)

assets/api_client.dart, dio_api_client.dart and the ApiException hierarchy (from flutter-result-errors) are the reference implementation:

• ApiClient speaks decoded JSON maps and throws only ApiExceptions.
• DioApiClient is the only file allowed to know Dio's API; it maps DioException types to ApiConnectionException / ApiResponseException / ApiUnknownException.
• Remote data sources depend on ApiClient and run through guard(...).

Interceptor order matters when you build the Dio in a provider:

• Put the logger before the auth interceptor, so request headers are logged before the Authorization header is attached and tokens never hit the console. Enable it in debug builds only.
• Put the breadcrumb/error-reporting interceptor last, so a 401 that the refresh interceptor is about to retry successfully reads as one line.
• Use a second Dio with no interceptors for the token-refresh call. Refreshing through the main client re-enters the refresh interceptor, and since it is queued the nested call waits behind the very request it should unblock.

Verifying the boundary

Run from the project root; each should print nothing:

# SDKs must not be imported by feature code
grep -rnE "package:(dio|firebase_[a-z_]+|sentry[a-z_]*|posthog_flutter|purchases_flutter|shared_preferences|flutter_secure_storage)/" lib/features

# Static singletons must not be reached from features
grep -rnE "(Firebase[A-Za-z]*\.instance|Sentry\.capture|SharedPreferences\.getInstance|Dio\()" lib/features

Adapters under lib/core/ and the provider files that construct them are the only legitimate importers. Tune the package list to your pubspec.

Review checklist

• New SDK import appears in exactly one adapter file
• Contract signatures contain no SDK types
• A NoOp and a recording fake exist
• Provider returns the contract type (Provider<FooService>), not the adapter
• Optional capability defaults to disabled; required config throws until overridden
• Nothing sensitive goes into tags, properties or breadcrumbs