refactor: modularize Beam into new projects and interfaces

- Introduced modularity by splitting Beam into new projects: Beam.Abstractions, Beam.Models, and Beam.Downloaders.
- Refactored existing classes into appropriate namespaces and projects.
- Replaced specific implementations with abstractions (e.g., SourceLinkBuilder to LinkBuilder, State to IState, etc.).
- Updated interfaces: added ITemplate, IArticleData, IDownloadReport, and others for improved extensibility.
- Removed deprecated classes like SourceLinkBuilder and StateChangerFactory.
- Enhanced link handling in downloaders by refactoring to use `string` over `SourceLink`.
- Consolidated shared logic under Beam.Abstractions.

Beam.Api/ApiResponse.cs

@@ -0,0 +1,82 @@
+using Microsoft.Extensions.Logging;
+using System.Net;
+using System.Net.Http.Json;
+using System.Text;
+using System.Text.Json;
+
+namespace Beam { 
+    /// <summary>
+    /// Wrapper that lets the response body be read any number of times (even concurrently).
+    /// </summary>
+    public sealed class ApiResponse {
+        private readonly byte[] _buffer;
+
+        private ApiResponse(HttpResponseMessage response, byte[] buffer, ILogger<ApiResponse>? logger, object? requestData = null) {
+            Response = response;
+            _buffer = buffer;
+            Logger = logger;
+            RequestData = requestData;
+        }
+
+        public HttpResponseMessage Response { get; }
+        public object? RequestData { get; }
+        public ILogger<ApiResponse>? Logger { get; }
+
+        /* ---------- creation ---------- */
+
+        public static async Task<ApiResponse> CreateAsync(
+            HttpResponseMessage response,
+            ILogger<ApiResponse>? logger = null,
+            object? requestData = null,
+            CancellationToken ct = default) {
+            if (response is null) throw new ArgumentNullException(nameof(response));
+
+            var buffer = response.Content is null
+                ? []
+                : await response.Content.ReadAsByteArrayAsync(ct).ConfigureAwait(false);
+
+            return new ApiResponse(response, buffer, logger, requestData);
+        }
+
+        /* ---------- status helpers ---------- */
+
+        public bool Is404 => Response.StatusCode == HttpStatusCode.NotFound;
+        public bool Is403 => Response.StatusCode == HttpStatusCode.Forbidden;
+        public bool Is500 => Response.StatusCode == HttpStatusCode.InternalServerError;
+        public bool Is400 => Response.StatusCode == HttpStatusCode.BadRequest;
+        public bool Is200 => Response.IsSuccessStatusCode;
+
+        public ApiResponse OnError(Action<HttpStatusCode> errorHandler) {
+            if (!Is200) errorHandler(Response.StatusCode);
+            return this;
+        }
+
+        /* ---------- content helpers ---------- */
+
+        public Task<T?> AsSerializedObject<T>(CancellationToken ct = default) {
+            if (!Is200) throw new InvalidOperationException();
+            if (Response.Content?.Headers.ContentType?.MediaType != "application/json")
+                Logger?.LogWarning("Content-Type is not JSON, yet JSON deserialization was requested.");
+
+            return Task.FromResult(JsonSerializer.Deserialize<T>(_buffer));
+        }
+
+        public Task<T?> AsDynamicObject<T>(T _, CancellationToken ct = default)
+            => AsSerializedObject<T>(ct);
+
+        public Task<string> AsString(CancellationToken ct = default) {
+            if (!Is200) Logger?.LogWarning("Non-success response; attempting to read content.");
+            return Task.FromResult(Encoding.UTF8.GetString(_buffer));
+        }
+
+        public Task<byte[]> AsBinary(CancellationToken ct = default) {
+            if (!Is200) Logger?.LogWarning("Non-success response; attempting to read content.");
+            return Task.FromResult(_buffer);
+        }
+
+        public Task<Stream> AsStream(CancellationToken ct = default) {
+            if (!Is200) Logger?.LogWarning("Non-success response; attempting to read content.");
+            return Task.FromResult<Stream>(new MemoryStream(_buffer, writable: false));
+        }
+    }
+}