[livetennisapi] Address second review round (wborn)

- Pagination: MatchListResponse now parses meta; the client pages the
  live-match list forward on meta.has_more (capped at 5 pages) instead
  of treating the first page as a complete snapshot, and logs when it
  deliberately truncates. Falls back to the page-fill heuristic only
  when meta is absent.
- Tournament retry: the transient retry runs on its own retryJob rather
  than scheduleInfoRefresh, which gated on infoJob — the currently
  executing job — and so could never schedule. dispose() cancels it.
- Break point at 40-40 is now UNDEF: the REST API does not expose the
  scoring format, so 40-40 is undeterminable (break point under no-ad,
  deuce under advantage). Only the determinable cases are asserted.
- Usage read decoupled from the live poll: live data is published first
  and a failing /usage call no longer discards it.
- Disposal: handlers carry a disposed flag and no longer publish state
  or status after dispose().
- Player detail overlap: an in-progress guard stops the periodic,
  ONLINE-triggered and retry refreshes from running concurrently and
  wasting quota; the tournament fetch gets the same guard.
- Defaults raised so a bridge plus one player fit the free tier: bridge
  1800 s (48/day) + player 7200 s (24/day) = 72/day; README math fixed.
- New player detailRefreshEnabled switch to disable the ranking and
  next-match refresh entirely, lowering 429 risk.
- Tests added for the 40-40 UNDEF behaviour and for the paging loop.

Signed-off-by: Ben <118375461+bensynapse@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: bensynapse

bundles/org.openhab.binding.livetennisapi/README.md

@@ -33,14 +33,15 @@ Configure a `player` thing with a doubles team's id to track that team exactly a
 | Parameter         | Type      | Required | Default | Description                                                                                                                                          |
 |-------------------|-----------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------|
 | `apiKey`          | `text`    | yes      | —       | API key for the Live Tennis API                                                                                                                     |
-| `refreshInterval` | `integer` | no       | 900     | How often to poll the live match snapshot in seconds (min: 60). The default stays within the free tier's daily quota; lower values need a paid tier. |
+| `refreshInterval` | `integer` | no       | 1800    | How often to poll the live match snapshot in seconds (min: 60). The default keeps the bridge plus one player thing within the free tier's daily quota; lower values need a paid tier. |
 
 ### `player` Thing
 
 | Parameter               | Type      | Required | Default | Description                                                                                        |
 |-------------------------|-----------|----------|---------|----------------------------------------------------------------------------------------------------|
 | `playerId`              | `integer` | yes      | —       | The player's or doubles team's id in the Live Tennis API; look it up with `GET /players?search=name` |
-| `detailRefreshInterval` | `integer` | no       | 3600    | How often to refresh the next match and ranking in seconds (min: 300); two API requests per cycle   |
+| `detailRefreshEnabled`  | `boolean` | no       | `true`  | Whether to refresh the next match and ranking. Turn it off to track only live match state (pushed by the bridge at no extra cost) and spend no quota of this thing's own |
+| `detailRefreshInterval` | `integer` | no       | 7200    | How often to refresh the next match and ranking in seconds when enabled (min: 300); two API requests per cycle |
 
 ### `tournament` Thing
 
@@ -78,7 +79,7 @@ All `live` channels are `UNDEF` while the player has no match in progress.
 | `live#sets`              | `String`   | Sets won, e.g. `1-0`                                                                                                                         |
 | `live#points`            | `String`   | In-game points, e.g. `40-15` or `AD-40`; `UNDEF` when the feed states no points                                                             |
 | `live#serving`           | `Switch`   | `ON` while the tracked player is serving; `UNDEF` when no game is in progress                                                                |
-| `live#break-point`       | `Switch`   | `ON` while the current game stands at break point (receiver at `AD`, or receiver at `40` with the server at `0`/`15`/`30`); never `ON` in a tiebreak; `UNDEF` when the score state does not allow deriving it |
+| `live#break-point`       | `Switch`   | `ON` while the current game stands at break point (receiver at `AD`, or receiver at `40` with the server at `0`/`15`/`30`); never `ON` in a tiebreak; `UNDEF` when the score state does not allow deriving it, including at `40-40` where the API does not state whether advantage or no-advantage scoring is in play |
 | `live#tiebreak`          | `Switch`   | `ON` while a tiebreak is being played                                                                                                        |
 | `next-match#opponent`    | `String`   | Opponent in the next scheduled match                                                                                                        |
 | `next-match#start-time`  | `DateTime` | Scheduled start of the next match; `UNDEF` until the order of play assigns a time                                                            |
@@ -110,20 +111,22 @@ Match channels show the tournament's first listed live match.
 ## Request Budget and the Free Tier
 
 The free tier allows 100 requests per day.
-The bridge makes one counted request per refresh cycle (the usage read is quota-exempt), shared by all player and tournament things, so at the default 900 s interval the bridge uses 96 requests per day.
-Each player thing additionally makes two requests per detail refresh cycle — 48 per day at the default 3600 s interval.
+The bridge makes one counted request per refresh cycle (the usage read is quota-exempt), shared by all player and tournament things, so at the default 1800 s interval the bridge uses 48 requests per day.
+Each player thing additionally makes two requests per detail refresh cycle — 24 per day at the default 7200 s interval; setting `detailRefreshEnabled=false` drops those to zero and the thing then tracks only live match state.
 
-A free key therefore fits the bridge alone at the defaults, or the bridge plus one player thing with slower settings (for example `refreshInterval=1800` and `detailRefreshInterval=7200`, together 72 requests per day).
+At the defaults a free key therefore fits the bridge plus one player thing (48 + 24 = 72 requests per day, within the 100 per day allowance).
 For several player things or faster live updates, a paid tier with a higher daily quota is required.
 The API answers requests over quota with HTTP 429; the bridge then goes `OFFLINE` with a communication error until a later poll succeeds, and the child things retry their own detail requests with a short backoff.
 
+The live match list is paginated. The bridge reads the `meta.has_more` flag and pages forward until the snapshot is complete, so more than 200 concurrent live matches are not silently dropped; in practice the whole live board is well under one page, so this remains a single request per cycle.
+
 ## Full Example
 
 ### `livetennisapi.things`
 
 ```java
-Bridge livetennisapi:account:myaccount "Live Tennis API" [ apiKey="XXXX", refreshInterval=900 ] {
-    Thing player alcaraz "Carlos Alcaraz" [ playerId=1234, detailRefreshInterval=3600 ]
+Bridge livetennisapi:account:myaccount "Live Tennis API" [ apiKey="XXXX", refreshInterval=1800 ] {
+    Thing player alcaraz "Carlos Alcaraz" [ playerId=1234, detailRefreshInterval=7200 ]
     Thing tournament cincinnati "Cincinnati Open" [ tournamentId="atp-cincinnati" ]
 }
 ```

bundles/org.openhab.binding.livetennisapi/src/main/java/org/openhab/binding/livetennisapi/internal/MatchStateMapper.java

@@ -109,9 +109,14 @@ private MatchStateMapper() {
     }
 
     /**
-     * Derives whether the current game stands at break point: the receiver holds AD, or the receiver holds 40 while
-     * the server holds 0, 15 or 30. There are no break points in a tiebreak. Returns null (unknown) when the server
-     * or the points are not stated.
+     * Derives whether the current game stands at break point, only in the cases the data determines unambiguously:
+     * the receiver holds AD, or the receiver holds 40 while the server holds 0, 15 or 30. There are no break points in
+     * a tiebreak.
+     *
+     * Returns null (unknown) when the server or points are not stated, and — importantly — at 40-40: the API does not
+     * expose the scoring format, so 40-40 is a break point under no-advantage scoring (a deciding point) but merely
+     * deuce under advantage scoring. That is genuinely undeterminable from the data, so it is reported as unknown
+     * rather than asserted either way.
      */
     public static @Nullable Boolean isBreakPoint(@Nullable Score score) {
         if (score == null) {
@@ -130,6 +135,10 @@ private MatchStateMapper() {
         if (serverPoints == null || receiverPoints == null) {
             return null;
         }
+        if ("40".equals(serverPoints) && "40".equals(receiverPoints)) {
+            // 40-40: no-advantage vs advantage scoring diverge here and the API does not state which is in use.
+            return null;
+        }
         return "AD".equals(receiverPoints) || ("40".equals(receiverPoints)
                 && ("0".equals(serverPoints) || "15".equals(serverPoints) || "30".equals(serverPoints)));
     }

bundles/org.openhab.binding.livetennisapi/src/main/java/org/openhab/binding/livetennisapi/internal/api/LiveTennisApiClient.java

@@ -12,6 +12,7 @@
  */
 package org.openhab.binding.livetennisapi.internal.api;
 
+import java.util.ArrayList;
 import java.util.Comparator;
 import java.util.List;
 import java.util.concurrent.ExecutionException;
@@ -50,7 +51,10 @@ public class LiveTennisApiClient {
     private static final String API_BASE = "https://api.livetennisapi.com/api/public/v1";
     private static final String API_KEY_HEADER = "X-API-Key";
     private static final int TIMEOUT_S = 20;
-    private static final int LIVE_MATCH_LIMIT = 200;
+    private static final int LIVE_MATCH_PAGE_SIZE = 200;
+    // Cap the live snapshot at a handful of pages: real concurrent live-match counts are far below this, so in
+    // practice a single request is made, but a pathological page count can never fan out unbounded requests.
+    private static final int MAX_LIVE_PAGES = 5;
     private static final int UPCOMING_MATCH_LIMIT = 10;
 
     private final Logger logger = LoggerFactory.getLogger(LiveTennisApiClient.class);
@@ -73,18 +77,50 @@ public Usage getUsage() throws LiveTennisApiException {
         return get("/usage", Usage.class);
     }
 
-    /** Returns all matches currently in progress, with their latest score. */
+    /**
+     * Returns all matches currently in progress, with their latest score. The endpoint is paginated: this reads the
+     * {@code meta.has_more} flag and pages forward until the snapshot is complete (or the page cap is reached), so
+     * matches beyond the first page are not silently dropped.
+     */
     public List<Match> getLiveMatches() throws LiveTennisApiException {
-        MatchListResponse response = get("/matches?status=live&limit=" + LIVE_MATCH_LIMIT, MatchListResponse.class);
-        List<Match> matches = response.data;
-        if (matches == null) {
-            return List.of();
-        }
-        if (matches.size() >= LIVE_MATCH_LIMIT) {
-            logger.warn("The live match snapshot hit the page limit of {}; any matches beyond it are not tracked",
-                    LIVE_MATCH_LIMIT);
+        return collectLiveMatches(offset -> get(
+                "/matches?status=live&limit=" + LIVE_MATCH_PAGE_SIZE + "&offset=" + offset, MatchListResponse.class));
+    }
+
+    /**
+     * A single page fetch of the live-match list, keyed by offset. Extracted so the paging loop can be exercised in a
+     * unit test without a live HTTP endpoint.
+     */
+    @FunctionalInterface
+    interface LiveMatchPageFetcher {
+        MatchListResponse fetch(int offset) throws LiveTennisApiException;
+    }
+
+    /**
+     * Pages forward through the live-match list, honouring {@code meta.has_more} rather than guessing from page size,
+     * and stops at {@link #MAX_LIVE_PAGES}. When the API still reports more matches at the cap the snapshot is
+     * truncated deliberately and that truncation is logged, never hidden.
+     */
+    List<Match> collectLiveMatches(LiveMatchPageFetcher fetcher) throws LiveTennisApiException {
+        List<Match> all = new ArrayList<>();
+        for (int page = 0; page < MAX_LIVE_PAGES; page++) {
+            MatchListResponse response = fetcher.fetch(all.size());
+            List<Match> data = response.data;
+            if (data == null || data.isEmpty()) {
+                return all;
+            }
+            all.addAll(data);
+            MatchListResponse.Meta meta = response.meta;
+            // has_more is authoritative; only when it is absent do we fall back to the page-fill heuristic.
+            boolean hasMore = meta != null ? Boolean.TRUE.equals(meta.hasMore) : data.size() >= LIVE_MATCH_PAGE_SIZE;
+            if (!hasMore) {
+                return all;
+            }
         }
-        return matches;
+        logger.warn(
+                "The live match snapshot still reports more results after {} pages of {}; matches beyond {} are not tracked this cycle",
+                MAX_LIVE_PAGES, LIVE_MATCH_PAGE_SIZE, MAX_LIVE_PAGES * LIVE_MATCH_PAGE_SIZE);
+        return all;
     }
 
     /** Returns the given player's next upcoming match, or null if none is scheduled. */

bundles/org.openhab.binding.livetennisapi/src/main/java/org/openhab/binding/livetennisapi/internal/api/dto/MatchListResponse.java

@@ -24,4 +24,18 @@
 public class MatchListResponse {
 
     public @Nullable List<Match> data;
+    public @Nullable Meta meta;
+
+    /**
+     * Pagination metadata. {@code has_more} is authoritative for whether further pages exist and must be read rather
+     * than comparing {@code count} to the requested {@code limit}.
+     */
+    public static class Meta {
+
+        public @Nullable Integer limit;
+        public @Nullable Integer offset;
+        public @Nullable Integer count;
+        public @Nullable Integer total;
+        public @Nullable Boolean hasMore;
+    }
 }

bundles/org.openhab.binding.livetennisapi/src/main/java/org/openhab/binding/livetennisapi/internal/config/LiveTennisApiAccountConfiguration.java

@@ -23,5 +23,5 @@
 public class LiveTennisApiAccountConfiguration {
 
     public String apiKey = "";
-    public int refreshInterval = 900;
+    public int refreshInterval = 1800;
 }

bundles/org.openhab.binding.livetennisapi/src/main/java/org/openhab/binding/livetennisapi/internal/config/LiveTennisApiPlayerConfiguration.java

@@ -23,5 +23,6 @@
 public class LiveTennisApiPlayerConfiguration {
 
     public long playerId = -1;
-    public int detailRefreshInterval = 3600;
+    public int detailRefreshInterval = 7200;
+    public boolean detailRefreshEnabled = true;
 }

bundles/org.openhab.binding.livetennisapi/src/main/java/org/openhab/binding/livetennisapi/internal/handler/LiveTennisApiAccountHandler.java

@@ -61,6 +61,7 @@ public class LiveTennisApiAccountHandler extends BaseBridgeHandler {
 
     private @Nullable LiveTennisApiClient apiClient;
     private @Nullable ScheduledFuture<?> pollingJob;
+    private volatile boolean disposed;
 
     private List<Match> lastLiveMatches = List.of();
     private @Nullable Usage lastUsage;
@@ -85,6 +86,7 @@ public void initialize() {
             return;
         }
 
+        disposed = false;
         apiClient = new LiveTennisApiClient(httpClient, config.apiKey);
         updateStatus(ThingStatus.UNKNOWN);
 
@@ -94,6 +96,7 @@ public void initialize() {
 
     @Override
     public void dispose() {
+        disposed = true;
         ScheduledFuture<?> job = pollingJob;
         if (job != null) {
             job.cancel(true);
@@ -150,22 +153,37 @@ private void poll() {
         if (client == null) {
             return;
         }
+        List<Match> liveMatches;
         try {
-            List<Match> liveMatches = client.getLiveMatches();
-            Usage usage = client.getUsage();
-            lastLiveMatches = liveMatches;
-            lastUsage = usage;
-            updateUsageChannels(usage);
-            if (getThing().getStatus() != ThingStatus.ONLINE) {
-                updateStatus(ThingStatus.ONLINE);
-            }
-            notifyChildHandlers(liveMatches);
+            liveMatches = client.getLiveMatches();
         } catch (LiveTennisApiAuthenticationException e) {
             logger.debug("Authentication failed", e);
             updateStatus(ThingStatus.OFFLINE, ThingStatusDetail.CONFIGURATION_ERROR, e.getMessage());
+            return;
         } catch (LiveTennisApiException e) {
             logger.debug("Polling failed", e);
             updateStatus(ThingStatus.OFFLINE, ThingStatusDetail.COMMUNICATION_ERROR, e.getMessage());
+            return;
+        }
+        if (disposed) {
+            return;
+        }
+        lastLiveMatches = liveMatches;
+        if (getThing().getStatus() != ThingStatus.ONLINE) {
+            updateStatus(ThingStatus.ONLINE);
+        }
+        notifyChildHandlers(liveMatches);
+
+        // The usage read is optional telemetry: a failure here must never discard the live data published above.
+        try {
+            Usage usage = client.getUsage();
+            if (disposed) {
+                return;
+            }
+            lastUsage = usage;
+            updateUsageChannels(usage);
+        } catch (LiveTennisApiException e) {
+            logger.debug("Usage read failed; the live match data for this cycle was still published", e);
         }
     }