EventFlux

1. Add EventFlux to your app

flutter pub add 'eventflux:^3.0.2'

2. Install the package skill

From your app's root directory, run:

dart run skills@ get -p eventflux

Choose your coding assistant when prompted. For Codex, use dart run skills@ get --agent codex -p eventflux.

The bundled eventflux-usage skill covers connection ownership, stream subscriptions, reconnects, authentication headers, browser setup, and v2 migration. The skills CLI requires Dart 3.10 or later and installs agent guidance without adding a runtime dependency. See the Dart package skills guide for setup details.

3. Ask your assistant to build the integration

Replace <SSE_URL> with your endpoint, then use a prompt like:

Use the eventflux-usage skill to connect this app to <SSE_URL>.
Follow the app's existing state management. Handle incoming events,
errors, and reconnects, and clean up the connection and subscription
when their owner is disposed. Include WebConfig if the app targets web.

For an existing v2 integration, ask: “Use eventflux-usage to migrate this app to EventFlux v3 and check its connection lifecycle.”

import 'package:eventflux/eventflux.dart';

void main() {
  EventFlux.instance.connect(
    EventFluxConnectionType.get,
    'https://example.com/events',
    onSuccessCallback: (EventFluxResponse? response) {
      response?.stream?.listen((EventFluxData data) {
        print('Event: ${data.event}');
        print('Data: ${data.data}');
      });
    },
    onError: (EventFluxException error) {
      print('Error: $error');
    },
    onConnectionClose: () {
      print('Connection closed');
    },
  );
}

Replace refreshAccessToken() with your app's token-refresh function. Auto-reconnect handles connection errors, stream closure, and idle timeouts; among HTTP error responses, only 5xx, 408, and 429 are retried.

import 'package:eventflux/eventflux.dart';

void main() {
  EventFlux.instance.connect(
    EventFluxConnectionType.get,
    'https://example.com/events',
    onSuccessCallback: (EventFluxResponse? response) {
      response?.stream?.listen((data) {
        print('Data: ${data.data}');
      });
    },
    onError: (error) {
      print('Error: $error');
    },
    autoReconnect: true,
    reconnectConfig: ReconnectConfig(
      mode: ReconnectMode.exponential,
      interval: Duration(seconds: 2),
      maxAttempts: 10,
      maxBackoff: Duration(seconds: 30),
      connectionTimeout: Duration(seconds: 60),
      onReconnect: (int attempt, Duration delay) {
        print('Reconnect attempt $attempt after $delay');
      },
      reconnectHeader: () async {
        String newToken = await refreshAccessToken();
        return {
          'Authorization': 'Bearer $newToken',
          'Accept': 'text/event-stream',
        };
      },
    ),
  );
}

import 'package:eventflux/eventflux.dart';
import 'package:http/http.dart';

class AuthInterceptor extends EventFluxInterceptor {
  @override
  Future<BaseRequest> onRequest(BaseRequest request) async {
    request.headers['Authorization'] = 'Bearer my-token';
    return request;
  }

  @override
  Future<StreamedResponse> onResponse(StreamedResponse response) async {
    print('Response status: ${response.statusCode}');
    return response;
  }

  @override
  Future<EventFluxException?> onError(EventFluxException exception) async {
    print('Intercepted error: $exception');
    // Return null to suppress the error, or return exception to propagate it
    return exception;
  }
}

void main() {
  EventFlux.instance.connect(
    EventFluxConnectionType.get,
    'https://example.com/events',
    interceptors: [AuthInterceptor()],
    onSuccessCallback: (EventFluxResponse? response) {
      response?.stream?.listen((data) {
        print('Data: ${data.data}');
      });
    },
    onError: (error) {
      print('Error: $error');
    },
  );
}

import 'dart:async';
import 'package:eventflux/eventflux.dart';

void main() {
  final completer = Completer<void>();

  EventFlux.instance.connect(
    EventFluxConnectionType.get,
    'https://example.com/events',
    abortTrigger: completer.future,
    onSuccessCallback: (EventFluxResponse? response) {
      response?.stream?.listen((data) {
        print('Data: ${data.data}');
      });
    },
    onError: (error) {
      print('Error: $error');
    },
  );

  // Cancel the connection at any time
  Future.delayed(Duration(seconds: 10), () {
    completer.complete();
  });
}

import 'package:eventflux/eventflux.dart';
import 'package:flutter/foundation.dart' show kIsWeb;

void main() {
  EventFlux.instance.connect(
    EventFluxConnectionType.get,
    'https://example.com/events',
    webConfig: kIsWeb
        ? WebConfig(
            mode: WebConfigRequestMode.cors,
            credentials: WebConfigRequestCredentials.omit,
          )
        : null,
    onSuccessCallback: (EventFluxResponse? response) {
      response?.stream?.listen((data) {
        print('Data: ${data.data}');
      });
    },
    onError: (error) {
      print('Error: $error');
    },
  );
}

import 'package:eventflux/eventflux.dart';

void main() {
  EventFlux e1 = EventFlux.spawn();
  EventFlux e2 = EventFlux.spawn();

  e1.connect(
    EventFluxConnectionType.get,
    'https://example.com/stream-1',
    tag: 'Stream 1',
    onSuccessCallback: (EventFluxResponse? response) {
      response?.stream?.listen((data) {
        print('Stream 1: ${data.data}');
      });
    },
    onError: (error) {
      print('Stream 1 error: $error');
    },
  );

  e2.connect(
    EventFluxConnectionType.get,
    'https://example.com/stream-2',
    tag: 'Stream 2',
    onSuccessCallback: (EventFluxResponse? response) {
      response?.stream?.listen((data) {
        print('Stream 2: ${data.data}');
      });
    },
    onError: (error) {
      print('Stream 2 error: $error');
    },
  );

  // Disconnect both when done
  // await e1.disconnect();
  // await e2.disconnect();
}

Connect

Connects to a server-sent event stream.

ReconnectConfig

EventFluxInterceptor

Subclass EventFluxInterceptor and override any of the following methods:

EventFluxStatus

Disconnect

EventFluxStatus status = await EventFlux.instance.disconnect();

Returns a Future<EventFluxStatus> indicating the disconnection status.

Spawn

EventFlux instance = EventFlux.spawn();

Returns a new independent EventFlux instance for managing parallel SSE connections.

If you're upgrading from v2, here's what changed:

Breaking

• onReconnect callback signature changed from () to (int attempt, Duration delay)
• Default request headers now include Cache-Control: no-store on native platforms; browsers use WebConfig.cache instead
• Minimum Dart SDK raised to >=3.4.0, Flutter >=3.0.0
• webConfig is now required when running on web

New in v3

• EventFluxStatus.reconnecting status value
• originalError and stackTrace fields on EventFluxException
• Request/response/error interceptors via interceptors parameter
• Mid-flight abort support via abortTrigger parameter
• Idle timeout detection via connectionTimeout on ReconnectConfig
• maxBackoff on ReconnectConfig to cap exponential backoff
• WHATWG-compliant SSE parser with persistent lastEventId, retry: field support, and U+2028 sanitization