jh_network_core #

A small, business-agnostic Dio client builder for applications that need shared network defaults with repository-level overrides.

The package focuses on client assembly rather than API definitions. It works with plain Dio, Retrofit, or any library that accepts a Dio instance.

Features #

• Dynamic base URL and request headers
• Shared configuration with repository-level overrides
• Configurable header merge precedence
• Provider-specific response decoding
• Business response validation
• Network error classification and custom messages
• Logging hooks without a logging framework dependency
• Custom Dio interceptor support
• Pure Dart implementation with no Flutter dependency

Installation #

dependencies:
  jh_network_core: ^0.1.0

Basic usage #

import 'package:jh_network_core/jh_network_core.dart';

final factory = NetworkClientFactory(
  NetworkClientConfig(
    baseUrlProvider: () => environment.apiBaseUrl,
    headersProvider: (request) async => {
      'accept-language': localeProvider(),
      'authorization': await tokenProvider(),
    },
    networkErrorMessageProvider: (kind, error) => switch (kind) {
      NetworkErrorKind.noConnection => 'No internet connection.',
      NetworkErrorKind.timeout => 'The request timed out.',
      _ => null,
    },
  ),
);

final dio = factory.create();

Providers are evaluated for every request, so environment, locale, and authentication changes do not require rebuilding the client.

Repository-level overrides #

Create clients with shared application defaults and local differences:

final loginDio = factory.create(
  overrides: NetworkClientOverrides(
    baseUrlProvider: () => environment.loginBaseUrl,
    headersProvider: (_) => {'x-api-module': 'login'},
    receiveTimeout: const Duration(seconds: 30),
  ),
);

final sportDio = factory.create(
  overrides: NetworkClientOverrides(
    baseUrlProvider: () => environment.sportBaseUrl,
    responseDataDecoder: decodeSportResponse,
    businessResponseValidator: validateSportResponse,
  ),
);

Configuration precedence is:

1. Shared NetworkClientConfig
2. Repository NetworkClientOverrides
3. Per-request Dio options

Shared and repository headers are merged by key. Repository headers override shared headers. Per-request headers override the merged headers by default.

To force configured headers to override per-request values:

const NetworkClientOverrides(
  headerMergePolicy: HeaderMergePolicy.commonOverridesRequest,
);

Business responses #

HTTP 200 does not always mean business success. Convert unsuccessful business responses into DioException values:

final config = NetworkClientConfig(
  baseUrlProvider: () => 'https://api.example.com',
  businessResponseValidator: (response) {
    final data = response.data;
    return data is Map<String, dynamic> && data['code'] == 0;
  },
  businessErrorMessageProvider: (response) {
    final data = response.data;
    return data is Map<String, dynamic> ? data['message'] as String? : null;
  },
);

Response decoding #

Different providers can return different envelopes. Decode the response before business validation:

NetworkClientOverrides(
  responseDataDecoder: (data, request) => decodeProviderEnvelope(data),
  businessResponseValidator: (response) {
    final envelope = response.data as ProviderEnvelope;
    return envelope.success;
  },
);

Retrofit #

Pass the configured Dio instance to a Retrofit-generated API:

final dio = factory.create(overrides: sportOverrides);
final api = SportApi(dio);

jh_network_core intentionally does not depend on Retrofit, state management, dependency injection, localization, or a logging framework.

Error messages #

The package classifies transport and HTTP failures as NetworkErrorKind. Applications provide user-facing messages, keeping localization outside the networking package.

Additional information #

Issues and feature requests are tracked on GitHub. Contributions are welcome through pull requests.

This package is distributed under the MIT License.