llm_dart_transport

Shared transport abstractions and Dio-based transport helpers for llm_dart.

What This Package Owns

This package owns transport-level concerns that should not live in providers, chat runtime code, or Flutter adapters:

transport request/response abstractions
transport exceptions and diagnostics
retry helpers for transport operations
request middleware for custom fetch-style hooks
Dio client configuration and factory helpers
SSE and UTF-8 decoding utilities
JSON object response decoding and log sanitization
small HTTP body utilities such as multipart/form-data encoding

Dependencies

This package depends on:

llm_dart_provider
dio
logging

That dependency direction is intentional:

shared contracts stay in llm_dart_provider
transport implementations build on those contracts
higher layers such as llm_dart_chat depend on transport, not the other way around

What This Package Does Not Own

This package does not own:

provider-specific request shaping or feature policy
chat/session state
Flutter controller/widget logic
provider-specific custom parts or message mappers

Use:

provider packages for provider-native behavior
llm_dart_chat for session/runtime orchestration
llm_dart_flutter for Flutter adapter behavior

Typical Consumers

Use llm_dart_transport when you are:

implementing a provider client on top of Dio
building multipart upload requests for provider-owned file or audio endpoints
building an HTTP/SSE boundary below provider or runtime code
writing transport-level diagnostics, retry helpers, or request middleware

Platform Notes

The main package:llm_dart_transport/llm_dart_transport.dart entrypoint is intended to stay Flutter Web-safe. IO-specific Dio adapter setup is selected through conditional imports, and browser builds use the web adapter path.

Advanced HTTP options such as proxy configuration, custom certificates, and SSL verification bypass are only available on dart:io platforms. On Web, those options are reported as unsupported because the browser owns that network stack.

Use package:llm_dart_transport/dio_io.dart only from IO-only code. It exports package:dio/io.dart directly and must not be imported by Flutter Web targets.

Request Hooks, Retry, And Diagnostics

DioTransportClient accepts an injected Dio, optional diagnostics, and a transport retry policy. A single request can override retry count with TransportRequest.maxRetries; provider calls expose the same idea through CallOptions.maxRetries.

Use MiddlewareTransportClient when you want a provider-agnostic equivalent of a custom fetch: add headers, rewrite requests, observe responses, or map errors without depending on Dio interceptors.

final events = <TransportDiagnosticsEvent>[];

final transport = MiddlewareTransportClient(
  inner: DioTransportClient(
    dio: myDio,
    diagnostics: CallbackTransportDiagnostics(events.add),
    diagnosticsOptions: const TransportDiagnosticsOptions(
      includeHeaders: true,
    ),
  ),
  middlewares: [
    TransportMiddleware(
      onRequest: (request) => request.copyWith(
        headers: {
          ...request.headers,
          'x-client-trace-id': 'trace-1',
        },
      ),
    ),
  ],
);

If you only need the chat/session layer, start with llm_dart_chat instead of this package directly.