docs(client): enforce xml docs and annotate public api

Author: Agash

src/GoAffPro.Client/Events/AffiliateDetectedEventArgs.cs

@@ -2,7 +2,22 @@
 
 namespace GoAffPro.Client.Events;
 
-public sealed class AffiliateDetectedEventArgs(GoAffProAffiliate affiliate) : EventArgs
+/// <summary>
+/// Event arguments for <see cref="GoAffProEventDetector.AffiliateDetected"/>.
+/// </summary>
+public sealed class AffiliateDetectedEventArgs : EventArgs
 {
-    public GoAffProAffiliate Affiliate { get; } = affiliate;
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AffiliateDetectedEventArgs"/> class.
+    /// </summary>
+    /// <param name="affiliate">Detected affiliate payload.</param>
+    public AffiliateDetectedEventArgs(GoAffProAffiliate affiliate)
+    {
+        Affiliate = affiliate;
+    }
+
+    /// <summary>
+    /// Gets the detected affiliate payload.
+    /// </summary>
+    public GoAffProAffiliate Affiliate { get; }
 }

src/GoAffPro.Client/Events/AffiliateEvent.cs

@@ -2,7 +2,27 @@
 
 namespace GoAffPro.Client.Events;
 
-public sealed record AffiliateEvent(GoAffProAffiliate Affiliate)
+/// <summary>
+/// Represents a detected affiliate/traffic feed event.
+/// </summary>
+public sealed record AffiliateEvent
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AffiliateEvent"/> record.
+    /// </summary>
+    /// <param name="affiliate">The detected affiliate payload.</param>
+    public AffiliateEvent(GoAffProAffiliate affiliate)
+    {
+        Affiliate = affiliate;
+    }
+
+    /// <summary>
+    /// Gets the strongly typed affiliate payload.
+    /// </summary>
+    public GoAffProAffiliate Affiliate { get; init; }
+
+    /// <summary>
+    /// Gets the unique event identifier.
+    /// </summary>
     public string Id => Affiliate.Id;
 }

src/GoAffPro.Client/Events/GoAffProEventDetector.cs

@@ -3,6 +3,12 @@
 
 namespace GoAffPro.Client.Events;
 
+/// <summary>
+/// Polling-based event detector for GoAffPro feed endpoints.
+/// </summary>
+/// <remarks>
+/// The detector keeps in-memory seen ID sets and does not persist state.
+/// </remarks>
 public sealed class GoAffProEventDetector
 {
     private readonly IGoAffProClient _client;
@@ -11,6 +17,12 @@ public sealed class GoAffProEventDetector
     private readonly HashSet<string> _seenAffiliateIds = [];
     private readonly HashSet<string> _seenOrderIds = [];
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GoAffProEventDetector"/> class.
+    /// </summary>
+    /// <param name="client">Client used for feed polling operations.</param>
+    /// <param name="pollingInterval">Polling interval. Defaults to 30 seconds.</param>
+    /// <param name="pageSize">Number of feed records requested per poll. Must be greater than zero.</param>
     public GoAffProEventDetector(
         IGoAffProClient client,
         TimeSpan? pollingInterval = null,
@@ -27,13 +39,30 @@ public GoAffProEventDetector(
         _pageSize = pageSize;
     }
 
+    /// <summary>
+    /// Raised when a new order item is detected.
+    /// </summary>
     public event EventHandler<OrderDetectedEventArgs>? OrderDetected;
 
+    /// <summary>
+    /// Raised when a new affiliate/traffic item is detected.
+    /// </summary>
     public event EventHandler<AffiliateDetectedEventArgs>? AffiliateDetected;
 
+    /// <summary>
+    /// Raised when a new reward item is detected.
+    /// </summary>
+    /// <remarks>
+    /// Currently disabled because <c>/user/feed/rewards</c> is returning HTTP 404
+    /// as observed on 2026-02-18.
+    /// </remarks>
     [Obsolete("Disabled because /user/feed/rewards currently returns HTTP 404 (observed on 2026-02-18).")]
     public event EventHandler<RewardDetectedEventArgs>? RewardDetected;
 
+    /// <summary>
+    /// Starts continuous polling and raises events when new items are found.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token used to stop polling.</param>
     public async Task StartAsync(CancellationToken cancellationToken = default)
     {
         // Referenced intentionally so the temporarily-disabled event remains part of the public surface.
@@ -57,6 +86,11 @@ public async Task StartAsync(CancellationToken cancellationToken = default)
         }
     }
 
+    /// <summary>
+    /// Streams newly detected order events.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token used to stop polling.</param>
+    /// <returns>An async stream of new order events.</returns>
     public async IAsyncEnumerable<OrderEvent> NewOrdersAsync([EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
         while (!cancellationToken.IsCancellationRequested)
@@ -71,6 +105,11 @@ public async IAsyncEnumerable<OrderEvent> NewOrdersAsync([EnumeratorCancellation
         }
     }
 
+    /// <summary>
+    /// Streams newly detected affiliate events.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token used to stop polling.</param>
+    /// <returns>An async stream of new affiliate events.</returns>
     public async IAsyncEnumerable<AffiliateEvent> NewAffiliatesAsync([EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
         while (!cancellationToken.IsCancellationRequested)
@@ -85,6 +124,15 @@ public async IAsyncEnumerable<AffiliateEvent> NewAffiliatesAsync([EnumeratorCanc
         }
     }
 
+    /// <summary>
+    /// Streams newly detected reward events.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token used to stop polling.</param>
+    /// <returns>An async stream of reward events.</returns>
+    /// <remarks>
+    /// Currently disabled because <c>/user/feed/rewards</c> is returning HTTP 404
+    /// as observed on 2026-02-18.
+    /// </remarks>
     [Obsolete("Disabled because /user/feed/rewards currently returns HTTP 404 (observed on 2026-02-18).")]
     public async IAsyncEnumerable<RewardEvent> NewRewardsAsync([EnumeratorCancellation] CancellationToken cancellationToken = default)
     {

src/GoAffPro.Client/Events/OrderDetectedEventArgs.cs

@@ -2,7 +2,22 @@
 
 namespace GoAffPro.Client.Events;
 
-public sealed class OrderDetectedEventArgs(GoAffProOrder order) : EventArgs
+/// <summary>
+/// Event arguments for <see cref="GoAffProEventDetector.OrderDetected"/>.
+/// </summary>
+public sealed class OrderDetectedEventArgs : EventArgs
 {
-    public GoAffProOrder Order { get; } = order;
+    /// <summary>
+    /// Initializes a new instance of the <see cref="OrderDetectedEventArgs"/> class.
+    /// </summary>
+    /// <param name="order">Detected order payload.</param>
+    public OrderDetectedEventArgs(GoAffProOrder order)
+    {
+        Order = order;
+    }
+
+    /// <summary>
+    /// Gets the detected order payload.
+    /// </summary>
+    public GoAffProOrder Order { get; }
 }

src/GoAffPro.Client/Events/OrderEvent.cs

@@ -2,7 +2,27 @@
 
 namespace GoAffPro.Client.Events;
 
-public sealed record OrderEvent(GoAffProOrder Order)
+/// <summary>
+/// Represents a detected order feed event.
+/// </summary>
+public sealed record OrderEvent
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="OrderEvent"/> record.
+    /// </summary>
+    /// <param name="order">The detected order payload.</param>
+    public OrderEvent(GoAffProOrder order)
+    {
+        Order = order;
+    }
+
+    /// <summary>
+    /// Gets the strongly typed order payload.
+    /// </summary>
+    public GoAffProOrder Order { get; init; }
+
+    /// <summary>
+    /// Gets the unique event identifier.
+    /// </summary>
     public string Id => Order.Id;
 }

src/GoAffPro.Client/Events/RewardDetectedEventArgs.cs

@@ -2,7 +2,26 @@
 
 namespace GoAffPro.Client.Events;
 
-public sealed class RewardDetectedEventArgs(GoAffProReward reward) : EventArgs
+/// <summary>
+/// Event arguments for <see cref="GoAffProEventDetector.RewardDetected"/>.
+/// </summary>
+/// <remarks>
+/// Reward feed detection is currently disabled because <c>/user/feed/rewards</c>
+/// is returning HTTP 404 as observed on 2026-02-18.
+/// </remarks>
+public sealed class RewardDetectedEventArgs : EventArgs
 {
-    public GoAffProReward Reward { get; } = reward;
+    /// <summary>
+    /// Initializes a new instance of the <see cref="RewardDetectedEventArgs"/> class.
+    /// </summary>
+    /// <param name="reward">Detected reward payload.</param>
+    public RewardDetectedEventArgs(GoAffProReward reward)
+    {
+        Reward = reward;
+    }
+
+    /// <summary>
+    /// Gets the detected reward payload.
+    /// </summary>
+    public GoAffProReward Reward { get; }
 }

src/GoAffPro.Client/Events/RewardEvent.cs

@@ -2,7 +2,31 @@
 
 namespace GoAffPro.Client.Events;
 
-public sealed record RewardEvent(GoAffProReward Reward)
+/// <summary>
+/// Represents a detected reward feed event.
+/// </summary>
+/// <remarks>
+/// Reward feed detection is currently disabled because <c>/user/feed/rewards</c>
+/// is returning HTTP 404 as observed on 2026-02-18.
+/// </remarks>
+public sealed record RewardEvent
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="RewardEvent"/> record.
+    /// </summary>
+    /// <param name="reward">The detected reward payload.</param>
+    public RewardEvent(GoAffProReward reward)
+    {
+        Reward = reward;
+    }
+
+    /// <summary>
+    /// Gets the strongly typed reward payload.
+    /// </summary>
+    public GoAffProReward Reward { get; init; }
+
+    /// <summary>
+    /// Gets the unique event identifier.
+    /// </summary>
     public string Id => Reward.Id;
 }

src/GoAffPro.Client/Exceptions/GoAffProApiException.cs

@@ -2,30 +2,61 @@
 
 namespace GoAffPro.Client.Exceptions;
 
+/// <summary>
+/// Represents an error returned by the GoAffPro API.
+/// </summary>
 public sealed class GoAffProApiException : Exception
 {
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GoAffProApiException"/> class.
+    /// </summary>
     public GoAffProApiException()
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GoAffProApiException"/> class
+    /// with a specified error message.
+    /// </summary>
+    /// <param name="message">Exception message.</param>
     public GoAffProApiException(string message)
         : base(message)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GoAffProApiException"/> class
+    /// with a specified error message and inner exception.
+    /// </summary>
+    /// <param name="message">Exception message.</param>
+    /// <param name="innerException">Inner exception that caused this failure.</param>
     public GoAffProApiException(string message, Exception innerException)
         : base(message, innerException)
     {
     }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GoAffProApiException"/> class
+    /// with status and response information.
+    /// </summary>
+    /// <param name="message">Exception message.</param>
+    /// <param name="statusCode">HTTP status code returned by the API.</param>
+    /// <param name="responseBody">Raw response body returned by the API, when available.</param>
+    /// <param name="innerException">Underlying exception, when available.</param>
     public GoAffProApiException(string message, HttpStatusCode statusCode, string? responseBody = null, Exception? innerException = null)
         : base(message, innerException)
     {
         StatusCode = statusCode;
         ResponseBody = responseBody;
     }
 
+    /// <summary>
+    /// Gets the HTTP status code returned by the API.
+    /// </summary>
     public HttpStatusCode StatusCode { get; }
 
+    /// <summary>
+    /// Gets the raw response body returned by the API, when available.
+    /// </summary>
     public string? ResponseBody { get; }
 }

src/GoAffPro.Client/GoAffPro.Client.csproj

@@ -5,6 +5,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
     <IsPackable>true</IsPackable>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
     <PackageId>GoAffPro.Client</PackageId>
     <MinVerTagPrefix>v</MinVerTagPrefix>
     <Description>A modern .NET client for the GoAffPro Affiliate Marketing API with automatic code generation and event detection.</Description>