From 0174e440dd8ad396b1f806e4b4a20e1833f888a1 Mon Sep 17 00:00:00 2001
From: cappy-dev <cappy-dev@users.noreply.github.com>
Date: Thu, 16 Jul 2026 05:05:20 +0000
Subject: [PATCH] docs: document full StatboticsClient API surface and retry
 behavior

The README only listed getEvents and getEventTeams, but the client exposes
five public methods (getEvent, getEvents, getEventTeams, getEventTeamsBasic,
getEventMatches). Add an installation section, an API reference table
covering all five methods with their endpoints and return types, the
per-method sort order, and a section on the transient-retry backoff and
the close() lifecycle method.
---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/README.md b/README.md
index 9c88a97..d1843f9 100644
--- a/README.md
+++ b/README.md
@@ -8,10 +8,71 @@ import 'package:statbotics_client/statbotics_client.dart';
 final client = StatboticsClient();
 final events = await client.getEvents(2026);
 final teams = await client.getEventTeams('2026txhou');
+client.close();
 ```
 
 No API key needed. Transient server errors are retried with a pluggable `sleep` (inject a no-op in tests); non-transient failures throw `StatboticsApiException` with the status code.
 
+## Installation
+
+Add the dependency in `pubspec.yaml`:
+
+```yaml
+dependencies:
+  statbotics_client: ^0.1.0
+```
+
+Or pull the latest from Git:
+
+```yaml
+dependencies:
+  statbotics_client:
+    git: https://github.com/Project516/statbotics_client.git
+```
+
+## API reference
+
+`StatboticsClient` targets `https://api.statbotics.io/v3`. It needs no auth key.
+Single-object endpoints return `null` on 404; list endpoints return an empty
+list. Anything else outside 2xx throws `StatboticsApiException`. Remember to
+call `close()` when you are done so the underlying HTTP client is released.
+
+| Method | Endpoint | Returns |
+| --- | --- | --- |
+| `getEvent(eventKey)` | `GET /event/{eventKey}` | `StatboticsEvent?` |
+| `getEvents(year)` | `GET /events?year={year}` | `List<StatboticsEvent>` |
+| `getEventTeams(eventKey)` | `GET /team_events?event={eventKey}` | `List<StatboticsTeamEvent>` |
+| `getEventTeamsBasic(eventKey)` | `GET /teams?event={eventKey}` | `List<StatboticsTeamBasic>` |
+| `getEventMatches(eventKey)` | `GET /matches?event={eventKey}` | `List<StatboticsMatch>` |
+
+- `getEventTeams` sorts results by rank ascending.
+- `getEvents` sorts results by week then name.
+- `getEventMatches` sorts results by comp level (`qm`, `ef`, `qf`, `sf`, `f`)
+  then match number.
+- `getEventTeamsBasic` returns basic team info (number + nickname) and returns
+  an empty list if the endpoint is unavailable.
+
+The API is public and read-only, so models only decode the fields each endpoint
+exposes (EPA means and standard deviations on `StatboticsTeamEvent`, alliance
+teams on `StatboticsMatch`, dates and location on `StatboticsEvent`). Each model
+also round-trips through `toJson` for caching.
+
+## Retries and backoff
+
+The Statbotics API returns occasional 500s under load. `StatboticsClient`
+retries transient responses (HTTP 429 and any 5xx) up to `maxAttempts` times
+(default 3) with exponential backoff (`300 * attempt^2` ms) before surfacing
+the error. 404 and other 4xx are returned or thrown immediately, with no retry.
+
+```dart
+final client = StatboticsClient(
+  maxAttempts: 5,
+  sleep: (duration) async {
+    // use your own sleeper (e.g. a fake clock in tests)
+  },
+);
+```
+
 ## License
 
 AGPL-3.0