supabase / supabase-flutter / 28599569004

86%

push

github

feat(realtime): add onHeartbeat stream to RealtimeClient (#1517)

## What

Adds `RealtimeClient.onHeartbeat`, a broadcast
`Stream<RealtimeHeartbeatStatus>` that emits a status whenever a
heartbeat is pushed (`sent`), acknowledged (`ok`/`error`), or when a
prior heartbeat goes unanswered (`timeout`).

```dart
final subscription = supabase.realtime.onHeartbeat.listen((status) {
  print('heartbeat: $status');
});
```

Also adds the `RealtimeHeartbeatStatus` enum (`sent`, `ok`, `error`,
`timeout`).

## Why

SDK parity: realtime-js `RealtimeClient.onHeartbeat` exposes the same
lifecycle. The Dart client had the heartbeat machinery but no way to
observe it.

Exposing it as a `Stream` (rather than a single callback like
realtime-js) is the idiomatic Dart shape: consumers get
`listen`/`where`/`firstWhere`/`timeout`, multiple subscribers and
cancellation for free, and it matches how the auth client already
surfaces events (`onAuthStateChange`).

## Tests

- Unit tests cover each emitted status and a case where a non-matching
heartbeat reference emits nothing.
- An end-to-end test connects to a real Realtime server (both v1 and v2
protocols) and observes an actual `sent` then `ok` heartbeat cycle.

## Compliance

Marks `realtime.client.listen_heartbeats` implemented in
`sdk-compliance.yaml` and registers the `RealtimeClient.onHeartbeat` and
`RealtimeHeartbeatStatus` symbols.

Resolves SDK-1169

7 of 7 new or added lines in 1 file covered. (100.0%)

4218 of 4904 relevant lines covered (86.01%)

4.0 hits per line