Add the Client class and its tests

Author: Cédric Belin

src/client.cs

@@ -1,5 +1,7 @@
 namespace Belin.Akismet;
 
+using System.Net.Http.Headers;
+
 /// <summary>
 /// Submits comments to the Akismet service.
 /// </summary>
@@ -41,5 +43,85 @@ public class Client(string apiKey, Blog blog, string baseUrl = "https://rest.aki
 	/// <summary>
 	/// The user agent string to use when making requests.
 	/// </summary>
-	public string UserAgent { get; init; } = $".NET/{Environment.Version} | Akismet/{Version}";
+	public string UserAgent { get; init; } = $".NET/{Environment.Version.ToString(3)} | Akismet/{Version}";
+
+	/// <summary>
+	/// Checks the specified comment against the service database, and returns a value indicating whether it is spam.
+	/// </summary>
+	/// <param name="comment">The comment to be submitted.</param>
+	/// <param name="cancellationToken">The token to cancel the operation.</param>
+	/// <returns>A value indicating whether the specified comment is spam.</returns>
+	/// <exception cref="HttpRequestException">The remote server returned an invalid response.</exception>
+	public async Task<CheckResult> CheckComment(Comment comment, CancellationToken cancellationToken = default) {
+		using var response = await Fetch("comment-check", comment.ToJson(), cancellationToken);
+		if (await response.Content.ReadAsStringAsync(cancellationToken) == "false") return CheckResult.Ham;
+		if (!response.Headers.TryGetValues("X-akismet-pro-tip", out var proTips)) return CheckResult.Spam;
+		return proTips.First() == "discard" ? CheckResult.PervasiveSpam : CheckResult.Spam;
+	}
+
+	/// <summary>
+	/// Submits the specified comment that was incorrectly marked as spam but should not have been.
+	/// </summary>
+	/// <param name="comment">The comment to be submitted.</param>
+	/// <param name="cancellationToken">The token to cancel the operation.</param>
+	/// <returns>Completes once the comment has been submitted.</returns>
+	/// <exception cref="HttpRequestException">The remote server returned an invalid response.</exception>
+	public async Task SubmitHam(Comment comment, CancellationToken cancellationToken = default) {
+		using var response = await Fetch("1.1/submit-ham", comment.ToJson(), cancellationToken);
+		var body = await response.Content.ReadAsStringAsync(cancellationToken);
+		if (body != Success) throw new HttpRequestException("Invalid server response.");
+	}
+
+	/// <summary>
+	/// Submits the specified comment that was not marked as spam but should have been.
+	/// </summary>
+	/// <param name="comment">The comment to be submitted.</param>
+	/// <param name="cancellationToken">The token to cancel the operation.</param>
+	/// <returns>Completes once the comment has been submitted.</returns>
+	/// <exception cref="HttpRequestException">The remote server returned an invalid response.</exception>
+	public async Task SubmitSpam(Comment comment, CancellationToken cancellationToken = default) {
+		using var response = await Fetch("1.1/submit-spam", comment.ToJson(), cancellationToken);
+		var body = await response.Content.ReadAsStringAsync(cancellationToken);
+		if (body != Success) throw new HttpRequestException("Invalid server response.");
+	}
+
+	/// <summary>
+	/// Checks the API key against the service database, and returns a value indicating whether it is valid.
+	/// </summary>
+	/// <param name="cancellationToken">The token to cancel the operation.</param>
+	/// <returns><see langword="true"/> if the specified API key is valid, otherwise <see langword="false"/>.</returns>
+	public async Task<bool> VerifyKey(CancellationToken cancellationToken = default) {
+		try {
+			using var response = await Fetch("1.1/verify-key", cancellationToken: cancellationToken);
+			return await response.Content.ReadAsStringAsync(cancellationToken) == "valid";
+		}
+		catch {
+			return false;
+		}
+	}
+
+	/// <summary>
+	/// Queries the service by posting the specified fields to a given end point, and returns the response.
+	/// </summary>
+	/// <param name="endpoint">The relative URL of the end point to query.</param>
+	/// <param name="fields">The fields describing the query body.</param>
+	/// <param name="cancellationToken">The token to cancel the operation.</param>
+	/// <returns>The server response.</returns>
+	/// <exception cref="HttpRequestException">An error occurred while querying the end point.</exception>
+	private async Task<HttpResponseMessage> Fetch(string endpoint, IDictionary<string, string>? fields = null, CancellationToken cancellationToken = default) {
+		var postFields = Blog.ToJson();
+		postFields.Add("api_key", ApiKey);
+		if (IsTest) postFields.Add("is_test", "1");
+		if (fields is not null) foreach (var item in fields) postFields.Add(item.Key, item.Value);
+
+		using var request = new HttpRequestMessage(HttpMethod.Post, new Uri(BaseUrl, endpoint)) { Content = new FormUrlEncodedContent(postFields) };
+		request.Headers.Add("User-Agent", UserAgent);
+
+		using var httpClient = new HttpClient();
+		var response = await httpClient.SendAsync(request, cancellationToken);
+		response.EnsureSuccessStatusCode();
+		if (response.Headers.TryGetValues("X-akismet-alert-msg", out var alertMessages)) throw new HttpRequestException(alertMessages.First());
+		if (response.Headers.TryGetValues("X-akismet-debug-help", out var debugHelps)) throw new HttpRequestException(debugHelps.First());
+		return response;
+	}
 }

src/comment.cs

@@ -58,7 +58,7 @@ public class Comment(Author author) {
 	internal IDictionary<string, string> ToJson() {
 		var map = Author.ToJson();
 		if (!string.IsNullOrWhiteSpace(Content)) map["comment_content"] = Content;
-		// TODO if (Context.Count > 0) map["comment_context"] = Context.ToString();
+		// TODO if (Context.Count > 0) map["comment_context"] = string.Join(',', Context);
 		if (Date is not null) map["comment_date_gmt"] = Date?.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")!;
 		if (Permalink is not null) map["permalink"] = Permalink.ToString();
 		if (PostModified is not null) map["comment_post_modified_gmt"] = PostModified?.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")!;

test/client_test.cs

@@ -1 +1,80 @@
 namespace Belin.Akismet;
+
+using System;
+using System.Threading.Tasks;
+
+/// <summary>
+/// Tests the features of the <see cref="Client"/> class.
+/// </summary>
+[TestClass]
+public sealed class ClientTest {
+
+	/// <summary>
+	/// The client used to query the remote API.
+	/// </summary>
+	private readonly Client client;
+
+	/// <summary>
+	/// A comment with content marked as ham.
+	/// </summary>
+	private readonly Comment ham;
+
+	/// <summary>
+	/// A comment with content marked as spam.
+	/// </summary>
+	private readonly Comment spam;
+
+	/// <summary>
+	/// Creates a new test.
+	/// </summary>
+	public ClientTest() {
+		client = new Client(Environment.GetEnvironmentVariable("AKISMET_API_KEY")!, new Blog("https://github.com/cedx/akismet.cs")) { IsTest = true };
+
+		var hamAuthor = new Author(ipAddress: "192.168.0.1") {
+			Name = "Akismet",
+			Role = AuthorRole.Administrator,
+			Url = new Uri("https://belin.io"),
+			UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36 Edg/133.0.0.0"
+		};
+
+		ham = new Comment(hamAuthor) {
+			Content = "I'm testing out the Service API.",
+			Referrer = new Uri("https://www.nuget.org/packages/Belin.Akismet"),
+			Type = CommentType.Comment
+		};
+
+		var spamAuthor = new Author(ipAddress: "127.0.0.1") {
+			Email = "akismet-guaranteed-spam@example.com",
+			Name = "viagra-test-123",
+			UserAgent = "Spam Bot/6.6.6"
+		};
+
+		spam = new Comment(spamAuthor) { Content = "Spam!", Type = CommentType.BlogPost };
+	}
+
+	[TestMethod]
+	public async Task CheckComment() {
+		AreEqual(CheckResult.Ham, await client.CheckComment(ham));
+
+		var result = await client.CheckComment(spam);
+		IsTrue(result == CheckResult.Spam || result == CheckResult.PervasiveSpam);
+	}
+
+	[TestMethod]
+	public async Task SubmitHam() {
+		await client.SubmitHam(ham);
+	}
+
+	[TestMethod]
+	public async Task SubmitSpam() {
+		await client.SubmitSpam(spam);
+	}
+
+	[TestMethod]
+	public async Task VerifyKey() {
+		IsTrue(await client.VerifyKey());
+
+		var newClient = new Client("0123456789-ABCDEF", client.Blog) { IsTest = true };
+		IsFalse(await newClient.VerifyKey());
+	}
+}