From 33b652c9e727ff8dcb28ba7e8253ed92e8a7b068 Mon Sep 17 00:00:00 2001
From: Ricardo Boss <mail@ricardoboss.de>
Date: Wed, 20 Mar 2024 03:46:22 +0100
Subject: [PATCH] More documentation; reduced public API surface of
 SeqHttpClient

---
 CHANGELOG.md                 |  8 ++++++++
 lib/src/seq_event.dart       |  6 ++++++
 lib/src/seq_http_client.dart | 13 +++++++------
 3 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e40011f..297f72d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,11 @@
+## Unreleased
+
+* More documentation
+* Made methods in `SeqHttpClient` private:
+  * `collapseEvents`
+  * `sendRequest`
+  * `handleResponse`
+
 ## 1.0.0
 
 * First stable release 🎉
diff --git a/lib/src/seq_event.dart b/lib/src/seq_event.dart
index d308819..7227647 100644
--- a/lib/src/seq_event.dart
+++ b/lib/src/seq_event.dart
@@ -19,6 +19,12 @@ class SeqEvent {
     this.context,
   );
 
+  /// Creates an event from the given [map]. The map should be compatible with
+  /// the GELF logging format. The timestamp is parsed from the map, and the
+  /// message, message template, level, exception, and id are read from the map
+  /// as strings. The renderings are read as a map of strings, and the context
+  /// is read as a map of strings to dynamic.
+  /// If the map does not contain a timestamp, the current time is used.
   factory SeqEvent.fromMap(Map<String, dynamic> map) {
     DateTime? timestamp;
     String? message;
diff --git a/lib/src/seq_http_client.dart b/lib/src/seq_http_client.dart
index 17b6b0e..d92230f 100644
--- a/lib/src/seq_http_client.dart
+++ b/lib/src/seq_http_client.dart
@@ -3,6 +3,7 @@ import 'dart:convert';
 import 'package:dart_seq/dart_seq.dart';
 import 'package:http/http.dart' as http;
 
+/// Calculates a linearly increasing duration to based on the number of [tries].
 Duration linearBackoff(int tries) => Duration(milliseconds: tries * 100);
 
 /// A HTTP ingestion client for Seq. Implements the [SeqClient] interface.
@@ -36,7 +37,7 @@ class SeqHttpClient implements SeqClient {
 
   @override
   Future<void> sendEvents(List<SeqEvent> events) async {
-    final body = collapseEvents(events);
+    final body = _collapseEvents(events);
     if (body.isEmpty) {
       SeqLogger.diagnosticLog(SeqLogLevel.verbose, 'No events to send.');
 
@@ -45,18 +46,18 @@ class SeqHttpClient implements SeqClient {
 
     http.Response response;
     try {
-      response = await sendRequest(body);
+      response = await _sendRequest(body);
     } catch (e, stack) {
       throw SeqClientException('Failed to send request', e, stack);
     }
 
-    await handleResponse(response);
+    await _handleResponse(response);
   }
 
-  String collapseEvents(List<SeqEvent> events) =>
+  String _collapseEvents(List<SeqEvent> events) =>
       events.reversed.map(jsonEncode).join('\n');
 
-  Future<http.Response> sendRequest(String body) async {
+  Future<http.Response> _sendRequest(String body) async {
     http.Response? response;
     Exception? lastException;
 
@@ -94,7 +95,7 @@ class SeqHttpClient implements SeqClient {
     return response!;
   }
 
-  Future<void> handleResponse(http.Response response) async {
+  Future<void> _handleResponse(http.Response response) async {
     final json = jsonDecode(response.body);
     if (json is! Map<String, dynamic>) {
       throw SeqClientException('The response body was not a JSON object');