From 78ab8ecdde1d3728a1077f4156d5db4e554939e7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Mon, 1 Jun 2026 17:40:53 -0500
Subject: [PATCH 01/18] Feat: Implement search and download client interfaces
 for TikTok video fetching

---
 .../Fetchers/Search/ISearchFetcher.cs         |  6 ++++
 .../Fetchers/Search/SearchFetchResult.cs      | 13 +++++++
 .../Domain/Abstractions/IDownloadClient.cs    | 34 +++++++++++++++++++
 .../Domain/Abstractions/ISearchClient.cs      |  8 +++++
 .../Domain/Abstractions/IVideoClient.cs       | 27 +--------------
 5 files changed, 62 insertions(+), 26 deletions(-)
 create mode 100644 TiktokExplode.Infrastructure/Fetchers/Search/ISearchFetcher.cs
 create mode 100644 TiktokExplode.Infrastructure/Fetchers/Search/SearchFetchResult.cs
 create mode 100644 TiktokExplode/Domain/Abstractions/IDownloadClient.cs
 create mode 100644 TiktokExplode/Domain/Abstractions/ISearchClient.cs

diff --git a/TiktokExplode.Infrastructure/Fetchers/Search/ISearchFetcher.cs b/TiktokExplode.Infrastructure/Fetchers/Search/ISearchFetcher.cs
new file mode 100644
index 0000000..3e2b964
--- /dev/null
+++ b/TiktokExplode.Infrastructure/Fetchers/Search/ISearchFetcher.cs
@@ -0,0 +1,6 @@
+namespace TiktokExplode.Infrastructure.Fetchers.Search;
+
+public interface ISearchFetcher
+{
+    IAsyncEnumerable<SearchFetchResult> FetchSearchAsync(string keyword, CancellationToken cancellationToken = default);
+}
diff --git a/TiktokExplode.Infrastructure/Fetchers/Search/SearchFetchResult.cs b/TiktokExplode.Infrastructure/Fetchers/Search/SearchFetchResult.cs
new file mode 100644
index 0000000..13ed170
--- /dev/null
+++ b/TiktokExplode.Infrastructure/Fetchers/Search/SearchFetchResult.cs
@@ -0,0 +1,13 @@
+namespace TiktokExplode.Infrastructure.Fetchers.Search;
+
+public sealed record SearchFetchResult
+{
+    /// <summary>The raw JSON content of the search results returned by TikTok's search API.</summary>
+    public required string JsonContent { get; init; }
+
+    /// <summary>
+    /// Session cookies captured during the page fetch.
+    /// These are injected into the download client to authenticate CDN video requests.
+    /// </summary>
+    public required IReadOnlyList<CookieData> Cookies { get; init; }
+}
diff --git a/TiktokExplode/Domain/Abstractions/IDownloadClient.cs b/TiktokExplode/Domain/Abstractions/IDownloadClient.cs
new file mode 100644
index 0000000..287818c
--- /dev/null
+++ b/TiktokExplode/Domain/Abstractions/IDownloadClient.cs
@@ -0,0 +1,34 @@
+using TiktokExplode.Domain.Entities;
+using TiktokExplode.Domain.ValueObjects;
+
+namespace TiktokExplode.Domain.Abstractions;
+
+/// <summary>
+/// Defines an interface for downloading TikTok videos, both with and without watermarks.
+/// </summary>
+public interface IDownloadClient : IAsyncDisposable
+{
+    /// <summary>
+    /// Downloads the video without watermark and returns a <see cref="StreamInfo"/> with the open stream.
+    /// The caller is responsible for disposing the returned <see cref="StreamInfo"/>.
+    /// </summary>
+    /// <param name="video">The <see cref="Video"/> whose download URL will be used.</param>
+    /// <param name="cancellationToken">Token to cancel the operation.</param>
+    /// <returns>
+    /// A <see cref="StreamInfo"/> containing the open video stream and its exact size in bytes
+    /// as reported by the CDN <c>Content-Length</c> header.
+    /// </returns>
+    Task<StreamInfo> DownloadAsync(Video video, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Downloads the video with TikTok's watermark overlay and returns a <see cref="StreamInfo"/> with the open stream.
+    /// The caller is responsible for disposing the returned <see cref="StreamInfo"/>.
+    /// </summary>
+    /// <param name="video">The <see cref="Video"/> whose watermarked download URL will be used.</param>
+    /// <param name="cancellationToken">Token to cancel the operation.</param>
+    /// <returns>
+    /// A <see cref="StreamInfo"/> containing the open watermarked video stream and its exact size in bytes
+    /// as reported by the CDN <c>Content-Length</c> header.
+    /// </returns>
+    Task<StreamInfo> DownloadWatermarkedAsync(Video video, CancellationToken cancellationToken = default);
+}
\ No newline at end of file
diff --git a/TiktokExplode/Domain/Abstractions/ISearchClient.cs b/TiktokExplode/Domain/Abstractions/ISearchClient.cs
new file mode 100644
index 0000000..f1c03b3
--- /dev/null
+++ b/TiktokExplode/Domain/Abstractions/ISearchClient.cs
@@ -0,0 +1,8 @@
+using TiktokExplode.Domain.Entities;
+
+namespace TiktokExplode.Domain.Abstractions;
+
+public interface ISearchClient : IDownloadClient
+{
+    IAsyncEnumerable<Video> SearchVideosAsync(string query, CancellationToken cancellationToken = default);
+}
\ No newline at end of file
diff --git a/TiktokExplode/Domain/Abstractions/IVideoClient.cs b/TiktokExplode/Domain/Abstractions/IVideoClient.cs
index b718e4a..1565903 100644
--- a/TiktokExplode/Domain/Abstractions/IVideoClient.cs
+++ b/TiktokExplode/Domain/Abstractions/IVideoClient.cs
@@ -1,5 +1,4 @@
 using TiktokExplode.Domain.Entities;
-using TiktokExplode.Domain.ValueObjects;
 
 namespace TiktokExplode.Domain.Abstractions;
 
@@ -7,7 +6,7 @@ namespace TiktokExplode.Domain.Abstractions;
 /// Defines the contract for a TikTok video client capable of retrieving metadata
 /// and downloading video content.
 /// </summary>
-public interface IVideoClient : IAsyncDisposable
+public interface IVideoClient : IDownloadClient
 {
     /// <summary>
     /// Retrieves full metadata for the TikTok video at <paramref name="url"/>.
@@ -20,28 +19,4 @@ public interface IVideoClient : IAsyncDisposable
     /// <exception cref="Exceptions.VideoNotFoundException">Thrown when the video does not exist or is private.</exception>
     /// <exception cref="Exceptions.TiktokParsingException">Thrown when the page structure cannot be parsed.</exception>
     Task<Video> GetVideoAsync(string url, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Downloads the video without watermark and returns a <see cref="StreamInfo"/> with the open stream.
-    /// The caller is responsible for disposing the returned <see cref="StreamInfo"/>.
-    /// </summary>
-    /// <param name="video">The <see cref="Video"/> whose download URL will be used.</param>
-    /// <param name="cancellationToken">Token to cancel the operation.</param>
-    /// <returns>
-    /// A <see cref="StreamInfo"/> containing the open video stream and its exact size in bytes
-    /// as reported by the CDN <c>Content-Length</c> header.
-    /// </returns>
-    Task<StreamInfo> DownloadAsync(Video video, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Downloads the video with TikTok's watermark overlay and returns a <see cref="StreamInfo"/> with the open stream.
-    /// The caller is responsible for disposing the returned <see cref="StreamInfo"/>.
-    /// </summary>
-    /// <param name="video">The <see cref="Video"/> whose watermarked download URL will be used.</param>
-    /// <param name="cancellationToken">Token to cancel the operation.</param>
-    /// <returns>
-    /// A <see cref="StreamInfo"/> containing the open watermarked video stream and its exact size in bytes
-    /// as reported by the CDN <c>Content-Length</c> header.
-    /// </returns>
-    Task<StreamInfo> DownloadWatermarkedAsync(Video video, CancellationToken cancellationToken = default);
 }

From 05a421e9a3bdc8f5779b0685d861ac2e65ac50f1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Mon, 1 Jun 2026 23:49:37 -0500
Subject: [PATCH 02/18] Refactor and extend TikTok search functionality

Refactored `TikTokBrowser` constructor for improved readability. Added `GetSearchPageAsync` and `GetSearchNextPageAsync` methods to handle TikTok search requests and pagination. Introduced `CreatePageAsync` for page creation in the browser context.

Implemented `PlaywrightSearchFetcher` to manage TikTok searches, including browser initialization, result fetching, and resource disposal. Added `TikTokSearchParser` to parse search JSON into `Video` objects.

Changed `ParseVideo` in `TikTokVideoParser` from private to internal for broader accessibility. Updated `ISearchClient` to rename `query` parameter to `keyword` for consistency.
---
 .../Browser/TikTokBrowser.cs                  | 75 +++++++++++++++++-
 .../Search/PlaywrightSearchFetcher.cs         | 78 +++++++++++++++++++
 .../Parsers/TikTokSearchParser.cs             | 27 +++++++
 .../Parsers/TikTokVideoParser.cs              |  2 +-
 .../Domain/Abstractions/ISearchClient.cs      |  2 +-
 5 files changed, 181 insertions(+), 3 deletions(-)
 create mode 100644 TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
 create mode 100644 TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs

diff --git a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
index 53f46ec..a1df122 100644
--- a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
+++ b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
@@ -28,7 +28,11 @@ internal sealed class TikTokBrowser : IAsyncDisposable
     private readonly PlaywrightFetcherOptions _options;
 
     /// <summary>Private constructor — use <see cref="CreateAsync"/> to instantiate.</summary>
-    private TikTokBrowser(IPlaywright playwright, IBrowser browser, IBrowserContext context, PlaywrightFetcherOptions options)
+    private TikTokBrowser(
+        IPlaywright playwright, 
+        IBrowser browser, 
+        IBrowserContext context, 
+        PlaywrightFetcherOptions options)
     {
         _playwright = playwright;
         _browser = browser;
@@ -119,6 +123,72 @@ await page.RouteAsync("**/*", async route =>
         }
     }
 
+    public async Task<string> GetSearchPageAsync(string keyword)
+    {
+        var page = await _context.NewPageAsync();
+
+        try
+        {
+            var responseTask = page.WaitForResponseAsync(
+               r => r.Url.Contains("/api/search/general/full/"),
+               new PageWaitForResponseOptions { Timeout = _options.PageTimeoutMs });
+
+            var pageResponse = await page.GotoAsync(
+                $"https://www.tiktok.com/search?q={Uri.EscapeDataString(keyword)}", new PageGotoOptions
+                {
+                    WaitUntil = WaitUntilState.DOMContentLoaded,
+                    Timeout = _options.PageTimeoutMs
+                });
+
+            if (pageResponse is null || !pageResponse.Ok)
+                throw new TiktokParsingException($"Failed to load page. Status: {pageResponse?.Status}");
+
+            var content = await page.ContentAsync();
+
+            if (content.Contains("_wafchallengeid", StringComparison.OrdinalIgnoreCase))
+                throw new TiktokWafException("TikTok WAF challenge detected.");
+
+            IResponse response;
+            try
+            {
+                response = await responseTask;
+            }
+            catch (TimeoutException)
+            {
+                throw new TiktokParsingException("Search API request was not intercepted within the timeout period. TikTok may not have issued the search request.");
+            }
+
+            if (!response.Ok)
+                throw new TiktokParsingException($"Failed to load search results. Status: {response.Status}");
+
+            return await response.TextAsync();
+        }
+        finally
+        {
+            await page.CloseAsync();
+        }
+
+    }
+
+    public async Task<string> GetSearchNextPageAsync(
+        string keyword,
+        long cursor,
+        IPage page)
+    {
+        return await page.EvaluateAsync<string>("""
+        async (args) => {
+            const url = new URL('/api/search/general/full/', 'https://www.tiktok.com');
+            url.searchParams.set('keyword', args.keyword);
+            url.searchParams.set('cursor', args.cursor);
+            url.searchParams.set('offset', args.cursor);
+            url.searchParams.set('count', '12');
+            url.searchParams.set('from_page', 'search');
+            const res = await fetch(url.toString(), { credentials: 'include' });
+            return await res.text();
+        }
+        """, new { keyword, cursor });
+    }
+
     /// <summary>
     /// Returns all cookies currently set in the browser context as a list of
     /// <see cref="CookieData"/> records, ready to be injected into the download client.
@@ -136,6 +206,9 @@ public async Task<IReadOnlyList<CookieData>> GetCookiesAsync()
             })];
     }
 
+    internal async Task<IPage> CreatePageAsync()
+        => await _context.NewPageAsync();
+
     /// <summary>
     /// Disposes the browser context, the browser process, and the Playwright instance
     /// in the correct reverse-dependency order.
diff --git a/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs b/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
new file mode 100644
index 0000000..7c4c384
--- /dev/null
+++ b/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
@@ -0,0 +1,78 @@
+using System.Text.Json.Nodes;
+using TiktokExplode.Infrastructure.Browser;
+using TiktokExplode.Infrastructure.Options;
+
+namespace TiktokExplode.Infrastructure.Fetchers.Search;
+
+public sealed class PlaywrightSearchFetcher(PlaywrightFetcherOptions options) 
+    : ISearchFetcher, IAsyncDisposable
+{
+
+    private TikTokBrowser? _browser;
+
+    /// <summary>Semaphore that serializes the one-time browser initialization across concurrent callers.</summary>
+    private readonly SemaphoreSlim _initLock = new(1, 1);
+
+    /// <summary>
+    /// Volatile flag indicating whether <see cref="_browser"/> has been fully initialized.
+    /// Read outside the lock for a fast-path check; written inside the lock after init completes.
+    /// </summary>
+    private volatile bool _initialized = false;
+
+    public PlaywrightSearchFetcher() : this(new PlaywrightFetcherOptions()) { }
+
+    public async IAsyncEnumerable<SearchFetchResult> FetchSearchAsync(
+        string keyword, 
+        CancellationToken cancellationToken = default)
+    {
+        if (!_initialized)
+        {
+            await _initLock.WaitAsync(cancellationToken);
+            try
+            {
+                if (!_initialized)
+                {
+                    _browser ??= await TikTokBrowser.CreateAsync(options);
+                    _initialized = true;
+                }
+            }
+            finally
+            {
+                _initLock.Release();
+            }
+        }
+
+        var json = await _browser!.GetSearchPageAsync(keyword);
+        var cookies = await _browser.GetCookiesAsync();
+
+        yield return new SearchFetchResult { JsonContent = json, Cookies = cookies };
+
+        var root = JsonNode.Parse(json);
+        var hasMore = root?["has_more"]?.GetValue<int>() ?? 0;
+        var cursor = root?["cursor"]?.GetValue<long>() ?? 0;
+
+        var page = await _browser.CreatePageAsync();
+
+        while(hasMore == 1 && !cancellationToken.IsCancellationRequested)
+        {
+            var nextJson = await _browser.GetSearchNextPageAsync(keyword, cursor, page);
+            yield return new SearchFetchResult { JsonContent = nextJson, Cookies = cookies };
+
+            var nextRoot = JsonNode.Parse(nextJson);
+            hasMore = nextRoot?["has_more"]?.GetValue<int>() ?? 0;
+            cursor = nextRoot?["cursor"]?.GetValue<long>() ?? 0;
+        }
+
+        await page.CloseAsync();
+    }
+
+    public async ValueTask DisposeAsync()
+    {
+        if (_browser is not null)
+        {
+            await _browser.DisposeAsync();
+            _browser = null;
+        }
+        _initLock.Dispose();
+    }
+}
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
new file mode 100644
index 0000000..0da3178
--- /dev/null
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
@@ -0,0 +1,27 @@
+using System.Text.Json.Nodes;
+using TiktokExplode.Domain.Entities;
+using TiktokExplode.Domain.Exceptions;
+
+namespace TiktokExplode.Infrastructure.Parsers;
+
+internal sealed class TikTokSearchParser
+{
+    internal static IEnumerable<Video> Parse(string jsonContent)
+    {
+        var root = JsonNode.Parse(jsonContent)
+            ?? throw new TiktokParsingException("Failed to parse search JSON.");
+
+        var data = root["data"]?.AsArray()
+            ?? throw new TiktokParsingException("Search JSON does not contain 'data' array.");
+
+        foreach(var entry in data)
+        {
+            if (entry?["type"]?.GetValue<int>() != 1) continue;
+
+            var item = entry["item"]
+                ?? throw new TiktokParsingException("'item' node not found in search entry.");
+
+            yield return TikTokVideoParser.ParseVideo(item);
+        }
+    }
+}
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
index 8c77a4f..e39351c 100644
--- a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
@@ -65,7 +65,7 @@ private static JsonNode ExtractItemStruct(IElement html)
     }
 
     /// <summary>Maps a top-level <c>itemStruct</c> JSON node to a <see cref="Video"/> domain object.</summary>
-    private static Video ParseVideo(JsonNode node)
+    internal static Video ParseVideo(JsonNode node)
     {
         var videoNode = node["video"]
             ?? throw new TiktokParsingException("Video information not found in the JSON content.");
diff --git a/TiktokExplode/Domain/Abstractions/ISearchClient.cs b/TiktokExplode/Domain/Abstractions/ISearchClient.cs
index f1c03b3..5ed799f 100644
--- a/TiktokExplode/Domain/Abstractions/ISearchClient.cs
+++ b/TiktokExplode/Domain/Abstractions/ISearchClient.cs
@@ -4,5 +4,5 @@ namespace TiktokExplode.Domain.Abstractions;
 
 public interface ISearchClient : IDownloadClient
 {
-    IAsyncEnumerable<Video> SearchVideosAsync(string query, CancellationToken cancellationToken = default);
+    IAsyncEnumerable<Video> SearchVideosAsync(string keyword, CancellationToken cancellationToken = default);
 }
\ No newline at end of file

From 8033c69a0c41e81b97c06ac50c8798ad35ce04a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Tue, 2 Jun 2026 00:23:49 -0500
Subject: [PATCH 03/18] Add TiktokSearchClient and improve search robustness

Introduced a new `TiktokSearchClient` implementing `ISearchClient`
to enable keyword-based TikTok video searches using Playwright.
Added methods for downloading videos with and without watermarks.

Updated `PlaywrightSearchFetcher` to support `TikTokOptions`
and added retry logic for WAF challenges with linear backoff.
Refactored `FetchSearchAsync` to improve handling of paginated
search results. Added detailed documentation for clarity.

Renamed `SearchVideosAsync` to `SearchAsync` in `ISearchClient`
for simplicity. Updated `TiktokClientExtensions` to reflect
changes in the download client interface.

These changes enhance the architecture for searching and
downloading TikTok videos, improving extensibility and resilience.
---
 .../Clients/TiktokSearchClient.cs             | 82 +++++++++++++++++++
 .../Common/TiktokClientExtensions.cs          |  2 +-
 .../Search/PlaywrightSearchFetcher.cs         | 76 +++++++++++++++--
 .../Domain/Abstractions/ISearchClient.cs      |  2 +-
 4 files changed, 151 insertions(+), 11 deletions(-)
 create mode 100644 TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs

diff --git a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
new file mode 100644
index 0000000..f435fee
--- /dev/null
+++ b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
@@ -0,0 +1,82 @@
+using System.Runtime.CompilerServices;
+using TiktokExplode.Domain.Abstractions;
+using TiktokExplode.Domain.Entities;
+using TiktokExplode.Domain.ValueObjects;
+using TiktokExplode.Infrastructure.Fetchers.Search;
+using TiktokExplode.Infrastructure.Http;
+using TiktokExplode.Infrastructure.Options;
+using TiktokExplode.Infrastructure.Parsers;
+
+namespace TiktokExplode.Infrastructure.Clients;
+
+/// <summary>
+/// An <see cref="ISearchClient"/> implementation that searches TikTok by keyword using
+/// a Playwright-powered browser fetcher and streams the results as <see cref="Video"/> objects.
+/// </summary>
+public sealed class TiktokSearchClient(
+    ISearchFetcher fetcher) : ISearchClient
+{
+    private readonly TikTokDownloadClient _downloadClient = new();
+
+    /// <summary>Initializes a new <see cref="TiktokSearchClient"/> with default options.</summary>
+    public TiktokSearchClient() : this(new PlaywrightSearchFetcher()) { }
+    /// <inheritdoc/>
+    public async IAsyncEnumerable<Video> SearchAsync(
+        string keyword,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        await foreach (var result in fetcher.FetchSearchAsync(keyword, cancellationToken))
+        {
+            _downloadClient.InjectCookies(result.Cookies);
+
+            foreach (var video in TikTokSearchParser.Parse(result.JsonContent))
+            {
+                yield return video;
+            }
+        }
+    }
+
+    /// <inheritdoc/>
+    public async Task<StreamInfo> DownloadAsync(Video video, CancellationToken cancellationToken = default)
+    {
+        return await DownloadCoreAsync(video.Info.DownloadLinks.OriginalUrl, cancellationToken);
+    }
+
+    /// <inheritdoc/>
+    public async Task<StreamInfo> DownloadWatermarkedAsync(Video video, CancellationToken cancellationToken = default)
+    {
+        return await DownloadCoreAsync(video.Info.DownloadLinks.WatermarkedUrl, cancellationToken);
+    }
+
+    /// <summary>
+    /// Core download helper that delegates to <see cref="TikTokDownloadClient"/>.
+    /// Exposed as <c>internal</c> to allow unit-testing without a full <see cref="Video"/> graph.
+    /// </summary>
+    /// <param name="url">The CDN URL to stream from.</param>
+    /// <param name="cancellationToken">Token to cancel the operation.</param>
+    internal Task<StreamInfo> DownloadCoreAsync(
+        string url,
+        CancellationToken cancellationToken = default)
+        => _downloadClient.DownloadVideoAsync(url, cancellationToken);
+
+    /// <inheritdoc/>
+    public async ValueTask DisposeAsync()
+    {
+        _downloadClient.Dispose();
+        if (fetcher is IAsyncDisposable d) await d.DisposeAsync();
+        else if (fetcher is IDisposable d2) d2.Dispose();
+    }
+
+    /// <summary>
+    /// Factory method to create a <see cref="TiktokSearchClient"/> with a Playwright-based fetcher.
+    /// </summary>
+    /// <param name="browserOptions">Options for the Playwright browser.</param>
+    /// <param name="options">Options for the TikTok client.</param>
+    /// <returns>A new instance of <see cref="TiktokSearchClient"/>.</returns>
+    public static TiktokSearchClient CreateWithBrowser(
+        PlaywrightFetcherOptions? browserOptions = null, 
+        TikTokOptions? options = null)
+        => new(new PlaywrightSearchFetcher(
+            browserOptions ?? new PlaywrightFetcherOptions(), 
+            options ?? new TikTokOptions()));
+}
diff --git a/TiktokExplode.Infrastructure/Common/TiktokClientExtensions.cs b/TiktokExplode.Infrastructure/Common/TiktokClientExtensions.cs
index b6f0313..15795bb 100644
--- a/TiktokExplode.Infrastructure/Common/TiktokClientExtensions.cs
+++ b/TiktokExplode.Infrastructure/Common/TiktokClientExtensions.cs
@@ -12,7 +12,7 @@ public static class TiktokClientExtensions
 {
     private static readonly HttpClient _httpClient = new();
 
-    extension(IVideoClient client)
+    extension(IDownloadClient client)
     {
         /// <summary>
         /// Downloads the video without watermark directly to a file at <paramref name="filePath"/>.
diff --git a/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs b/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
index 7c4c384..31ea21a 100644
--- a/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
+++ b/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
@@ -1,10 +1,19 @@
-using System.Text.Json.Nodes;
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+using System.Text.Json.Nodes;
+using Microsoft.Playwright;
+using TiktokExplode.Domain.Exceptions;
 using TiktokExplode.Infrastructure.Browser;
 using TiktokExplode.Infrastructure.Options;
 
 namespace TiktokExplode.Infrastructure.Fetchers.Search;
 
-public sealed class PlaywrightSearchFetcher(PlaywrightFetcherOptions options) 
+/// <summary>
+/// An <see cref="ISearchFetcher"/> implementation that uses a real Chromium browser via
+/// Microsoft Playwright to search TikTok. Intercepts the internal search API response on
+/// the first page, then fetches subsequent pages via in-browser <c>fetch()</c> calls.
+/// </summary>
+public sealed class PlaywrightSearchFetcher(PlaywrightFetcherOptions options, TikTokOptions tikTokOptions)
     : ISearchFetcher, IAsyncDisposable
 {
 
@@ -19,11 +28,20 @@ public sealed class PlaywrightSearchFetcher(PlaywrightFetcherOptions options)
     /// </summary>
     private volatile bool _initialized = false;
 
-    public PlaywrightSearchFetcher() : this(new PlaywrightFetcherOptions()) { }
+    /// <summary>Initializes a new <see cref="PlaywrightSearchFetcher"/> with default options.</summary>
+    public PlaywrightSearchFetcher() : this(new PlaywrightFetcherOptions(), new TikTokOptions()) { }
 
+    /// <summary>
+    /// Asynchronously streams pages of raw search results for <paramref name="keyword"/>.
+    /// The browser is initialized lazily on the first call. WAF challenges are retried
+    /// up to <see cref="TikTokOptions.MaxWafRetries"/> times with linear back-off.
+    /// </summary>
+    /// <param name="keyword">The search term to query.</param>
+    /// <param name="cancellationToken">Token to cancel the operation.</param>
+    /// <returns>An async sequence of <see cref="SearchFetchResult"/> — one per API page.</returns>
     public async IAsyncEnumerable<SearchFetchResult> FetchSearchAsync(
-        string keyword, 
-        CancellationToken cancellationToken = default)
+        string keyword,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
         if (!_initialized)
         {
@@ -42,8 +60,8 @@ public async IAsyncEnumerable<SearchFetchResult> FetchSearchAsync(
             }
         }
 
-        var json = await _browser!.GetSearchPageAsync(keyword);
-        var cookies = await _browser.GetCookiesAsync();
+        var json = await FetchFirstPageWithRetryAsync(keyword, cancellationToken);
+        var cookies = await _browser!.GetCookiesAsync();
 
         yield return new SearchFetchResult { JsonContent = json, Cookies = cookies };
 
@@ -53,9 +71,9 @@ public async IAsyncEnumerable<SearchFetchResult> FetchSearchAsync(
 
         var page = await _browser.CreatePageAsync();
 
-        while(hasMore == 1 && !cancellationToken.IsCancellationRequested)
+        while (hasMore == 1 && !cancellationToken.IsCancellationRequested)
         {
-            var nextJson = await _browser.GetSearchNextPageAsync(keyword, cursor, page);
+            var nextJson = await FetchNextPageWithRetryAsync(keyword, cursor, page, cancellationToken);
             yield return new SearchFetchResult { JsonContent = nextJson, Cookies = cookies };
 
             var nextRoot = JsonNode.Parse(nextJson);
@@ -66,6 +84,46 @@ public async IAsyncEnumerable<SearchFetchResult> FetchSearchAsync(
         await page.CloseAsync();
     }
 
+    private async Task<string> FetchFirstPageWithRetryAsync(string keyword, CancellationToken cancellationToken)
+    {
+        for (int attempt = 0; attempt <= tikTokOptions.MaxWafRetries; attempt++)
+        {
+            try
+            {
+                return await _browser!.GetSearchPageAsync(keyword);
+            }
+            catch (TiktokWafException) when (attempt < tikTokOptions.MaxWafRetries)
+            {
+                await Task.Delay(tikTokOptions.RetryBaseDelay * (attempt + 1), cancellationToken);
+            }
+        }
+        throw new UnreachableException();
+    }
+
+    private async Task<string> FetchNextPageWithRetryAsync(
+        string keyword,
+        long cursor,
+        IPage page,
+        CancellationToken cancellationToken)
+    {
+        for (int attempt = 0; attempt <= tikTokOptions.MaxWafRetries; attempt++)
+        {
+            try
+            {
+                return await _browser!.GetSearchNextPageAsync(keyword, cursor, page);
+            }
+            catch (TiktokWafException) when (attempt < tikTokOptions.MaxWafRetries)
+            {
+                await Task.Delay(tikTokOptions.RetryBaseDelay * (attempt + 1), cancellationToken);
+            }
+        }
+        throw new UnreachableException();
+    }
+
+    /// <summary>
+    /// Disposes the underlying browser and Playwright instance,
+    /// and releases the initialization semaphore.
+    /// </summary>
     public async ValueTask DisposeAsync()
     {
         if (_browser is not null)
diff --git a/TiktokExplode/Domain/Abstractions/ISearchClient.cs b/TiktokExplode/Domain/Abstractions/ISearchClient.cs
index 5ed799f..f6d63a4 100644
--- a/TiktokExplode/Domain/Abstractions/ISearchClient.cs
+++ b/TiktokExplode/Domain/Abstractions/ISearchClient.cs
@@ -4,5 +4,5 @@ namespace TiktokExplode.Domain.Abstractions;
 
 public interface ISearchClient : IDownloadClient
 {
-    IAsyncEnumerable<Video> SearchVideosAsync(string keyword, CancellationToken cancellationToken = default);
+    IAsyncEnumerable<Video> SearchAsync(string keyword, CancellationToken cancellationToken = default);
 }
\ No newline at end of file

From 855373ffe0f0b221c5ce67e06a45d2daad34f6bc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Tue, 2 Jun 2026 00:49:55 -0500
Subject: [PATCH 04/18] Add ISearchClient support with Playwright fetcher

Updated README to document ISearchClient integration, including usage examples and service registration details. Adjusted `TiktokExplodeBuilder` to register `ISearchClient` and `ISearchFetcher` when using Playwright. Added warnings about unavailability with HTTP fetcher. Minor adjustments in `TikTokBrowser` and `TiktokSearchClient` for consistency.
---
 README.md                                     | 65 +++++++++++++++----
 .../README.md                                 | 49 ++++++++------
 .../TiktokExplodeBuilder.cs                   |  9 +++
 .../Browser/TikTokBrowser.cs                  |  6 +-
 .../Clients/TiktokSearchClient.cs             |  4 +-
 5 files changed, 95 insertions(+), 38 deletions(-)

diff --git a/README.md b/README.md
index 56e51ad..b4e88fe 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ The library follows **Clean Architecture**: the domain layer (`TiktokExplode`) h
 - Fetch full video metadata: author, stats, duration, language, location, bitrates, and more
 - Download videos without watermark or with watermark
 - Download the static cover image (JPEG) or the animated cover (WebP)
+- **Search videos by keyword** — streams results lazily via `IAsyncEnumerable<Video>`
 - Progress reporting during download via `IProgress<double>`
 - Automatic WAF/bot-detection retry with configurable backoff
 - **Strategy pattern** — choose between Playwright (reliable) or HTTP-only (lightweight) page fetching
@@ -123,14 +124,44 @@ await using var client = new TiktokClient(myFetcher, new TikTokOptions());
 
 `TiktokClient` implements `IAsyncDisposable` — always use `await using`.
 
+---
+
+### `TiktokSearchClient`
+
+`TiktokSearchClient` searches TikTok by keyword and streams results as `Video` objects using `IAsyncEnumerable<Video>`. It **requires Playwright** because TikTok's search API signs requests with dynamic tokens that can only be generated by a real browser session.
+
+```csharp
+await using var client = TiktokSearchClient.CreateWithBrowser();
+
+await foreach (var video in client.SearchAsync("funny cats"))
+{
+    Console.WriteLine($"{video.Author.UniqueId}: {video.Description}");
+
+    // You can also download directly from ISearchClient
+    await client.DownloadAsync(video, $"{video.Id}.mp4");
+}
+```
+
+> **Note:** `TiktokSearchClient` implements `ISearchClient`, which extends `IDownloadClient`. This means all extension methods (`DownloadAsync(filePath)`, `DownloadWatermarkedAsync(filePath)`, `DownloadImageAsync`, `DownloadAnimatedImageAsync`) are available directly on the search client — no need for a separate `TiktokClient` instance.
+
+#### Methods
+
+| Method                                               | Returns                   | Description                                                           |
+| ---------------------------------------------------- | ------------------------- | --------------------------------------------------------------------- |
+| `SearchAsync(string keyword, CancellationToken)`     | `IAsyncEnumerable<Video>` | Streams video results for the given keyword, paginating automatically |
+| `DownloadAsync(Video, CancellationToken)`            | `StreamInfo`              | Downloads video without watermark                                     |
+| `DownloadWatermarkedAsync(Video, CancellationToken)` | `StreamInfo`              | Downloads video with watermark                                        |
+
+`TiktokSearchClient` implements `IAsyncDisposable` — always use `await using`.
+
 #### Extension methods (via `TiktokClientExtensions`)
 
-| Method | Description |
-| --- | --- |
-| `DownloadAsync(video, filePath, progress?, ct)` | Downloads video without watermark to a file, with optional progress |
-| `DownloadWatermarkedAsync(video, filePath, progress?, ct)` | Downloads video with watermark to a file, with optional progress |
-| `DownloadImageAsync(video, filePath, ct)` | Downloads the static cover image (JPEG) |
-| `DownloadAnimatedImageAsync(video, filePath, ct)` | Downloads the animated cover (WebP) |
+| Method                                                     | Description                                                         |
+| ---------------------------------------------------------- | ------------------------------------------------------------------- |
+| `DownloadAsync(video, filePath, progress?, ct)`            | Downloads video without watermark to a file, with optional progress |
+| `DownloadWatermarkedAsync(video, filePath, progress?, ct)` | Downloads video with watermark to a file, with optional progress    |
+| `DownloadImageAsync(video, filePath, ct)`                  | Downloads the static cover image (JPEG)                             |
+| `DownloadAnimatedImageAsync(video, filePath, ct)`          | Downloads the animated cover (WebP)                                 |
 
 ```csharp
 // Download to file path with optional progress
@@ -227,6 +258,7 @@ services.AddTiktokExplode(b => b
     .UsePlaywrightFetcher(o => o.Headless = false));
 
 // HTTP fetcher — lighter, no browser dependency
+// Note: ISearchClient is NOT available with HTTP fetcher (see below)
 services.AddTiktokExplode(b => b
     .UseHttpFetcher(o => o.WarmupDelay = TimeSpan.Zero)
     .ConfigureTiktok(o => o.MaxWafRetries = 5));
@@ -234,12 +266,16 @@ services.AddTiktokExplode(b => b
 
 Registered services:
 
-| Service | Implementation | Lifetime |
-| --- | --- | --- |
-| `IVideoClient` | `TiktokClient` | Singleton |
-| `IPageFetcher` | `PlaywrightFetcher` or `HttpFetcher` | Singleton |
-| `TikTokOptions` | — | Singleton |
-| `PlaywrightFetcherOptions` or `HttpFetcherOptions` | — | Singleton |
+| Service                                            | Implementation                       | Lifetime  | Fetcher             |
+| -------------------------------------------------- | ------------------------------------ | --------- | ------------------- |
+| `IVideoClient`                                     | `TiktokClient`                       | Singleton | Both                |
+| `ISearchClient`                                    | `TiktokSearchClient`                 | Singleton | **Playwright only** |
+| `IPageFetcher`                                     | `PlaywrightFetcher` or `HttpFetcher` | Singleton | Both                |
+| `ISearchFetcher`                                   | `PlaywrightSearchFetcher`            | Singleton | **Playwright only** |
+| `TikTokOptions`                                    | —                                    | Singleton | Both                |
+| `PlaywrightFetcherOptions` or `HttpFetcherOptions` | —                                    | Singleton | Both                |
+
+> **Important:** `ISearchClient` and `ISearchFetcher` are only registered when using the Playwright fetcher (the default). If you call `UseHttpFetcher()`, these services will **not** be present in the container. Attempting to inject `ISearchClient` with an HTTP-configured builder will throw a DI resolution error at runtime. This is by design — TikTok's search API requires a real browser to generate signed requests.
 
 ```csharp
 // Consume in your services via constructor injection
@@ -296,11 +332,12 @@ TiktokExplode/                # Domain — zero external dependencies
     Utilities/                # URL validation
 
 TiktokExplode.Infrastructure/ # HTTP + browser automation (Playwright + AngleSharp)
-  Clients/                    # TiktokClient : IVideoClient
+  Clients/                    # TiktokClient : IVideoClient, TiktokSearchClient : ISearchClient
   Fetchers/                   # IPageFetcher, PlaywrightFetcher, HttpFetcher
+  Fetchers/Search/            # ISearchFetcher, PlaywrightSearchFetcher
   Http/                       # TikTokDownloadClient — CDN download management
   Browser/                    # TikTokBrowser — internal Playwright wrapper
-  Parsers/                    # TikTokVideoParser — JSON extraction from hydration script
+  Parsers/                    # TikTokVideoParser, TikTokSearchParser — JSON extraction
   Options/                    # TikTokOptions, PlaywrightFetcherOptions, HttpFetcherOptions
   Common/                     # StreamExtensions, TiktokClientExtensions
 
diff --git a/TiktokExplode.Extensions.DependencyInjection/README.md b/TiktokExplode.Extensions.DependencyInjection/README.md
index 4f66be2..a048578 100644
--- a/TiktokExplode.Extensions.DependencyInjection/README.md
+++ b/TiktokExplode.Extensions.DependencyInjection/README.md
@@ -6,7 +6,7 @@
 
 `Microsoft.Extensions.DependencyInjection` integration for [TiktokExplode](https://github.com/Ts-Pytham/TiktokExplode).
 
-Provides `AddTiktokExplode()` — a fluent extension method on `IServiceCollection` that registers `IVideoClient` and lets you choose between the Playwright (default) or HTTP fetcher strategy.
+Provides `AddTiktokExplode()` — a fluent extension method on `IServiceCollection` that registers `IVideoClient` and `ISearchClient`, and lets you choose between the Playwright (default) or HTTP fetcher strategy.
 
 ---
 
@@ -29,21 +29,28 @@ services.AddTiktokExplode(b => b
     .UsePlaywrightFetcher(o => o.Headless = false));
 
 // HTTP fetcher — no browser dependency, lighter footprint
+// Note: ISearchClient is NOT registered with this strategy (requires Playwright)
 services.AddTiktokExplode(b => b
     .UseHttpFetcher(o => o.WarmupDelay = TimeSpan.Zero)
     .ConfigureTiktok(o => o.MaxWafRetries = 5));
 ```
 
-Then inject `IVideoClient` normally:
+Then inject `IVideoClient` or `ISearchClient` normally:
 
 ```csharp
-public class MyService(IVideoClient client)
+public class MyService(IVideoClient client, ISearchClient search)
 {
     public async Task<string> GetTitleAsync(string url)
     {
         var video = await client.GetVideoAsync(url);
         return video.Description;
     }
+
+    public async IAsyncEnumerable<string> SearchTitlesAsync(string keyword)
+    {
+        await foreach (var video in search.SearchAsync(keyword))
+            yield return video.Description;
+    }
 }
 ```
 
@@ -51,22 +58,26 @@ public class MyService(IVideoClient client)
 
 ## Registered services
 
-| Service | Implementation | Lifetime |
-| --- | --- | --- |
-| `IVideoClient` | `TiktokClient` | Singleton |
-| `IPageFetcher` | `PlaywrightFetcher` or `HttpFetcher` | Singleton |
-| `TikTokOptions` | — | Singleton |
-| `PlaywrightFetcherOptions` or `HttpFetcherOptions` | — | Singleton |
+| Service                                            | Implementation                       | Lifetime  | Fetcher             |
+| -------------------------------------------------- | ------------------------------------ | --------- | ------------------- |
+| `IVideoClient`                                     | `TiktokClient`                       | Singleton | Both                |
+| `ISearchClient`                                    | `TiktokSearchClient`                 | Singleton | **Playwright only** |
+| `IPageFetcher`                                     | `PlaywrightFetcher` or `HttpFetcher` | Singleton | Both                |
+| `ISearchFetcher`                                   | `PlaywrightSearchFetcher`            | Singleton | **Playwright only** |
+| `TikTokOptions`                                    | —                                    | Singleton | Both                |
+| `PlaywrightFetcherOptions` or `HttpFetcherOptions` | —                                    | Singleton | Both                |
+
+> **Important:** `ISearchClient` and `ISearchFetcher` are only registered when using the Playwright fetcher. TikTok's search API requires a real browser to sign requests — it cannot be replicated with plain HTTP. If you call `UseHttpFetcher()` and attempt to inject `ISearchClient`, the DI container will throw a resolution error at runtime.
 
 ---
 
 ## Builder API
 
-| Method | Description |
-| --- | --- |
-| `ConfigureTiktok(Action<TikTokOptions>?)` | Configures WAF retry count and base delay |
-| `UsePlaywrightFetcher(Action<PlaywrightFetcherOptions>?)` | Uses a real Chromium browser via Playwright (default) |
-| `UseHttpFetcher(Action<HttpFetcherOptions>?)` | Uses a plain `HttpClient` — faster start, may be WAF-blocked |
+| Method                                                    | Description                                                                                                |
+| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `ConfigureTiktok(Action<TikTokOptions>?)`                 | Configures WAF retry count and base delay                                                                  |
+| `UsePlaywrightFetcher(Action<PlaywrightFetcherOptions>?)` | Uses a real Chromium browser via Playwright (default). Also registers `ISearchClient` and `ISearchFetcher` |
+| `UseHttpFetcher(Action<HttpFetcherOptions>?)`             | Uses a plain `HttpClient` — faster start, may be WAF-blocked. `ISearchClient` is **not** available         |
 
 > **Note:** `UsePlaywrightFetcher` and `UseHttpFetcher` are mutually exclusive — the last one called wins.
 
@@ -74,11 +85,11 @@ public class MyService(IVideoClient client)
 
 ## Related packages
 
-| Package | Description |
-| --- | --- |
-| [`TiktokExplode`](https://www.nuget.org/packages/TiktokExplode) | Domain layer — models, interfaces, exceptions |
-| [`TiktokExplode.Infrastructure`](https://www.nuget.org/packages/TiktokExplode.Infrastructure) | HTTP + Playwright fetchers, parser, download client |
-| [`TiktokExplode.All`](https://www.nuget.org/packages/TiktokExplode.All) | Meta-package — installs domain + infrastructure together |
+| Package                                                                                       | Description                                              |
+| --------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| [`TiktokExplode`](https://www.nuget.org/packages/TiktokExplode)                               | Domain layer — models, interfaces, exceptions            |
+| [`TiktokExplode.Infrastructure`](https://www.nuget.org/packages/TiktokExplode.Infrastructure) | HTTP + Playwright fetchers, parser, download client      |
+| [`TiktokExplode.All`](https://www.nuget.org/packages/TiktokExplode.All)                       | Meta-package — installs domain + infrastructure together |
 
 ---
 
diff --git a/TiktokExplode.Extensions.DependencyInjection/TiktokExplodeBuilder.cs b/TiktokExplode.Extensions.DependencyInjection/TiktokExplodeBuilder.cs
index 45d034f..dbb6058 100644
--- a/TiktokExplode.Extensions.DependencyInjection/TiktokExplodeBuilder.cs
+++ b/TiktokExplode.Extensions.DependencyInjection/TiktokExplodeBuilder.cs
@@ -2,6 +2,7 @@
 using TiktokExplode.Domain.Abstractions;
 using TiktokExplode.Infrastructure.Clients;
 using TiktokExplode.Infrastructure.Fetchers;
+using TiktokExplode.Infrastructure.Fetchers.Search;
 using TiktokExplode.Infrastructure.Options;
 
 namespace TiktokExplode.Extensions.DependencyInjection;
@@ -31,6 +32,12 @@ public TiktokExplodeBuilder ConfigureTiktok(Action<TikTokOptions>? options = nul
     /// Configures the Playwright-based page fetcher as the active <see cref="IPageFetcher"/>.
     /// This is the default strategy — call this only when you need to customise the options.
     /// </summary>
+    /// <remarks>
+    /// Registering this fetcher also makes <see cref="ISearchClient"/> and <see cref="ISearchFetcher"/>
+    /// available in the container, because TikTok's search API requires a real browser session
+    /// to generate signed requests. These services are <b>not</b> registered when
+    /// <see cref="UseHttpFetcher"/> is used instead.
+    /// </remarks>
     /// <param name="options">Delegate that mutates a <see cref="PlaywrightFetcherOptions"/> instance.</param>
     /// <returns>The same builder for chaining.</returns>
     public TiktokExplodeBuilder UsePlaywrightFetcher(Action<PlaywrightFetcherOptions>? options = null)
@@ -75,6 +82,8 @@ private static Action<IServiceCollection> RegisterPlaywright(PlaywrightFetcherOp
         {
             services.AddSingleton(options);
             services.AddSingleton<IPageFetcher, PlaywrightFetcher>();
+            services.AddSingleton<ISearchFetcher, PlaywrightSearchFetcher>();
+            services.AddSingleton<ISearchClient, TiktokSearchClient>();
         };
     }
 
diff --git a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
index a1df122..a8237e2 100644
--- a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
+++ b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
@@ -29,9 +29,9 @@ internal sealed class TikTokBrowser : IAsyncDisposable
 
     /// <summary>Private constructor — use <see cref="CreateAsync"/> to instantiate.</summary>
     private TikTokBrowser(
-        IPlaywright playwright, 
-        IBrowser browser, 
-        IBrowserContext context, 
+        IPlaywright playwright,
+        IBrowser browser,
+        IBrowserContext context,
         PlaywrightFetcherOptions options)
     {
         _playwright = playwright;
diff --git a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
index f435fee..513c4f3 100644
--- a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
+++ b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
@@ -74,9 +74,9 @@ public async ValueTask DisposeAsync()
     /// <param name="options">Options for the TikTok client.</param>
     /// <returns>A new instance of <see cref="TiktokSearchClient"/>.</returns>
     public static TiktokSearchClient CreateWithBrowser(
-        PlaywrightFetcherOptions? browserOptions = null, 
+        PlaywrightFetcherOptions? browserOptions = null,
         TikTokOptions? options = null)
         => new(new PlaywrightSearchFetcher(
-            browserOptions ?? new PlaywrightFetcherOptions(), 
+            browserOptions ?? new PlaywrightFetcherOptions(),
             options ?? new TikTokOptions()));
 }

From 76afaac04974bb1a807eabc92205eaf9fa6c5cf1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Tue, 2 Jun 2026 00:58:13 -0500
Subject: [PATCH 05/18] Refactor: standardize TikTok naming conventions

Renamed classes, methods, and variables to use the `Tiktok`
naming convention instead of `TikTok` for consistency. Updated
references across the codebase, including constructors, static
methods, and documentation.
---
 .../TiktokExplodeBuilder.cs                   |  8 +--
 .../Browser/TikTokBrowser.cs                  | 10 ++--
 .../Clients/TiktokClient.cs                   | 22 +++----
 .../Clients/TiktokSearchClient.cs             | 10 ++--
 .../Fetchers/PlaywrightFetcher.cs             |  4 +-
 .../Fetchers/Search/ISearchFetcher.cs         | 15 +++++
 .../Search/PlaywrightSearchFetcher.cs         | 10 ++--
 .../Fetchers/Search/SearchFetchResult.cs      |  5 ++
 .../Http/TikTokDownloadClient.cs              | 10 ++--
 .../Options/TiktokOptions.cs                  |  2 +-
 .../Parsers/TikTokSearchParser.cs             |  6 +-
 .../Parsers/TikTokVideoParser.cs              | 42 +++++++-------
 .../Utilities/TikTokUrlValidatorTests.cs      | 58 +++++++++----------
 .../Clients/TiktokClientTests.cs              |  8 +--
 .../Parsers/TikTokVideoParserTests.cs         |  2 +-
 .../Domain/Abstractions/ISearchClient.cs      | 14 +++++
 .../Domain/Utilities/TikTokUrlValidator.cs    |  2 +-
 17 files changed, 131 insertions(+), 97 deletions(-)

diff --git a/TiktokExplode.Extensions.DependencyInjection/TiktokExplodeBuilder.cs b/TiktokExplode.Extensions.DependencyInjection/TiktokExplodeBuilder.cs
index dbb6058..ffbb2c4 100644
--- a/TiktokExplode.Extensions.DependencyInjection/TiktokExplodeBuilder.cs
+++ b/TiktokExplode.Extensions.DependencyInjection/TiktokExplodeBuilder.cs
@@ -14,15 +14,15 @@ namespace TiktokExplode.Extensions.DependencyInjection;
 /// </summary>
 public sealed class TiktokExplodeBuilder(IServiceCollection services)
 {
-    private readonly TikTokOptions _tiktokOptions = new();
+    private readonly TiktokOptions _tiktokOptions = new();
     private Action<IServiceCollection> _fetcherRegistration = RegisterPlaywright(new());
 
     /// <summary>
     /// Configures the WAF-retry behaviour of <c>TiktokClient</c>.
     /// </summary>
-    /// <param name="options">Delegate that mutates a <see cref="TikTokOptions"/> instance.</param>
+    /// <param name="options">Delegate that mutates a <see cref="TiktokOptions"/> instance.</param>
     /// <returns>The same builder for chaining.</returns>
-    public TiktokExplodeBuilder ConfigureTiktok(Action<TikTokOptions>? options = null)
+    public TiktokExplodeBuilder ConfigureTiktok(Action<TiktokOptions>? options = null)
     {
         options?.Invoke(_tiktokOptions);
         return this;
@@ -64,7 +64,7 @@ public TiktokExplodeBuilder UseHttpFetcher(Action<HttpFetcherOptions>? options =
 
     /// <summary>
     /// Applies all pending registrations to the underlying <see cref="IServiceCollection"/>.
-    /// Registers <see cref="TikTokOptions"/>, the chosen <see cref="IPageFetcher"/>,
+    /// Registers <see cref="TiktokOptions"/>, the chosen <see cref="IPageFetcher"/>,
     /// and <see cref="IVideoClient"/> as singletons.
     /// </summary>
     /// <returns>The service collection for further chaining.</returns>
diff --git a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
index a8237e2..c82ae67 100644
--- a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
+++ b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
@@ -11,7 +11,7 @@ namespace TiktokExplode.Infrastructure.Browser;
 /// Resource-heavy assets (images, media, fonts, stylesheets) are intercepted and aborted
 /// to speed up page load times.
 /// </summary>
-internal sealed class TikTokBrowser : IAsyncDisposable
+internal sealed class TiktokBrowser : IAsyncDisposable
 {
     /// <summary>The top-level Playwright instance. Must be disposed last.</summary>
     private readonly IPlaywright _playwright;
@@ -28,7 +28,7 @@ internal sealed class TikTokBrowser : IAsyncDisposable
     private readonly PlaywrightFetcherOptions _options;
 
     /// <summary>Private constructor — use <see cref="CreateAsync"/> to instantiate.</summary>
-    private TikTokBrowser(
+    private TiktokBrowser(
         IPlaywright playwright,
         IBrowser browser,
         IBrowserContext context,
@@ -41,12 +41,12 @@ private TikTokBrowser(
     }
 
     /// <summary>
-    /// Creates and fully initializes a new <see cref="TikTokBrowser"/> instance.
+    /// Creates and fully initializes a new <see cref="TiktokBrowser"/> instance.
     /// Launches Chromium with the settings from <paramref name="options"/> and creates
     /// a new browser context with a realistic user-agent and locale.
     /// </summary>
     /// <param name="options">Browser launch and navigation options.</param>
-    public static async Task<TikTokBrowser> CreateAsync(PlaywrightFetcherOptions options)
+    public static async Task<TiktokBrowser> CreateAsync(PlaywrightFetcherOptions options)
     {
         var playwright = await Playwright.CreateAsync();
 
@@ -66,7 +66,7 @@ public static async Task<TikTokBrowser> CreateAsync(PlaywrightFetcherOptions opt
             }
         });
 
-        return new TikTokBrowser(playwright, browser, context, options);
+        return new TiktokBrowser(playwright, browser, context, options);
     }
 
     /// <summary>
diff --git a/TiktokExplode.Infrastructure/Clients/TiktokClient.cs b/TiktokExplode.Infrastructure/Clients/TiktokClient.cs
index d21fd3a..fb113b5 100644
--- a/TiktokExplode.Infrastructure/Clients/TiktokClient.cs
+++ b/TiktokExplode.Infrastructure/Clients/TiktokClient.cs
@@ -14,23 +14,23 @@ namespace TiktokExplode.Infrastructure.Clients;
 /// <summary>
 /// Default implementation of <see cref="IVideoClient"/> that fetches and parses TikTok video pages,
 /// then streams video files from TikTok's CDN.
-/// Supports automatic WAF-retry logic configured via <see cref="TikTokOptions"/>.
+/// Supports automatic WAF-retry logic configured via <see cref="TiktokOptions"/>.
 /// </summary>
 /// <param name="fetcher">The strategy used to fetch TikTok video page HTML.</param>
 /// <param name="options">Retry and delay settings for WAF bypass attempts.</param>
-public sealed class TiktokClient(IPageFetcher fetcher, TikTokOptions options) : IVideoClient, IAsyncDisposable
+public sealed class TiktokClient(IPageFetcher fetcher, TiktokOptions options) : IVideoClient, IAsyncDisposable
 {
     /// <summary>Reusable HTTP client for CDN video downloads. Receives cookies from the fetcher.</summary>
-    private readonly TikTokDownloadClient _downloadClient = new();
+    private readonly TiktokDownloadClient _downloadClient = new();
 
     /// <summary>Stateless parser that extracts a <see cref="Video"/> from raw page HTML.</summary>
-    private readonly TikTokVideoParser _parser = new();
+    private readonly TiktokVideoParser _parser = new();
 
     /// <summary>
     /// Initializes a new <see cref="TiktokClient"/> with a Playwright-based page fetcher
     /// and default retry options.
     /// </summary>
-    public TiktokClient() : this(new PlaywrightFetcher(), new TikTokOptions()) { }
+    public TiktokClient() : this(new PlaywrightFetcher(), new TiktokOptions()) { }
 
     /// <inheritdoc/>
     /// <remarks>
@@ -40,7 +40,7 @@ public sealed class TiktokClient(IPageFetcher fetcher, TikTokOptions options) :
     /// </remarks>
     public async Task<Video> GetVideoAsync(string url, CancellationToken cancellationToken = default)
     {
-        TikTokUrlValidator.Validate(url);
+        TiktokUrlValidator.Validate(url);
 
         for (int attempt = 0; attempt <= options.MaxWafRetries; attempt++)
         {
@@ -60,7 +60,7 @@ public async Task<Video> GetVideoAsync(string url, CancellationToken cancellatio
     }
 
     /// <summary>
-    /// Core download helper that delegates to <see cref="TikTokDownloadClient"/>.
+    /// Core download helper that delegates to <see cref="TiktokDownloadClient"/>.
     /// Exposed as <c>internal</c> to allow unit-testing without a full <see cref="Video"/> graph.
     /// </summary>
     /// <param name="url">The CDN URL to stream from.</param>
@@ -106,8 +106,8 @@ public async ValueTask DisposeAsync()
     /// </summary>
     /// <param name="browserOptions">Browser launch and navigation options. Uses defaults when <see langword="null"/>.</param>
     /// <param name="options">Retry and delay settings. Uses defaults when <see langword="null"/>.</param>
-    public static TiktokClient CreateWithBrowser(PlaywrightFetcherOptions? browserOptions = null, TikTokOptions? options = null)
-        => new(new PlaywrightFetcher(browserOptions ?? new PlaywrightFetcherOptions()), options ?? new TikTokOptions());
+    public static TiktokClient CreateWithBrowser(PlaywrightFetcherOptions? browserOptions = null, TiktokOptions? options = null)
+        => new(new PlaywrightFetcher(browserOptions ?? new PlaywrightFetcherOptions()), options ?? new TiktokOptions());
 
     /// <summary>
     /// Creates a <see cref="TiktokClient"/> that uses a plain <see cref="System.Net.Http.HttpClient"/>
@@ -115,6 +115,6 @@ public static TiktokClient CreateWithBrowser(PlaywrightFetcherOptions? browserOp
     /// </summary>
     /// <param name="httpOptions">HTTP fetch options. Uses defaults when <see langword="null"/>.</param>
     /// <param name="options">Retry and delay settings. Uses defaults when <see langword="null"/>.</param>
-    public static TiktokClient CreateWithHttp(HttpFetcherOptions? httpOptions = null, TikTokOptions? options = null)
-        => new(new HttpFetcher(httpOptions ?? new HttpFetcherOptions()), options ?? new TikTokOptions());
+    public static TiktokClient CreateWithHttp(HttpFetcherOptions? httpOptions = null, TiktokOptions? options = null)
+        => new(new HttpFetcher(httpOptions ?? new HttpFetcherOptions()), options ?? new TiktokOptions());
 }
\ No newline at end of file
diff --git a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
index 513c4f3..06e68cb 100644
--- a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
+++ b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
@@ -16,7 +16,7 @@ namespace TiktokExplode.Infrastructure.Clients;
 public sealed class TiktokSearchClient(
     ISearchFetcher fetcher) : ISearchClient
 {
-    private readonly TikTokDownloadClient _downloadClient = new();
+    private readonly TiktokDownloadClient _downloadClient = new();
 
     /// <summary>Initializes a new <see cref="TiktokSearchClient"/> with default options.</summary>
     public TiktokSearchClient() : this(new PlaywrightSearchFetcher()) { }
@@ -29,7 +29,7 @@ public async IAsyncEnumerable<Video> SearchAsync(
         {
             _downloadClient.InjectCookies(result.Cookies);
 
-            foreach (var video in TikTokSearchParser.Parse(result.JsonContent))
+            foreach (var video in TiktokSearchParser.Parse(result.JsonContent))
             {
                 yield return video;
             }
@@ -49,7 +49,7 @@ public async Task<StreamInfo> DownloadWatermarkedAsync(Video video, Cancellation
     }
 
     /// <summary>
-    /// Core download helper that delegates to <see cref="TikTokDownloadClient"/>.
+    /// Core download helper that delegates to <see cref="TiktokDownloadClient"/>.
     /// Exposed as <c>internal</c> to allow unit-testing without a full <see cref="Video"/> graph.
     /// </summary>
     /// <param name="url">The CDN URL to stream from.</param>
@@ -75,8 +75,8 @@ public async ValueTask DisposeAsync()
     /// <returns>A new instance of <see cref="TiktokSearchClient"/>.</returns>
     public static TiktokSearchClient CreateWithBrowser(
         PlaywrightFetcherOptions? browserOptions = null,
-        TikTokOptions? options = null)
+        TiktokOptions? options = null)
         => new(new PlaywrightSearchFetcher(
             browserOptions ?? new PlaywrightFetcherOptions(),
-            options ?? new TikTokOptions()));
+            options ?? new TiktokOptions()));
 }
diff --git a/TiktokExplode.Infrastructure/Fetchers/PlaywrightFetcher.cs b/TiktokExplode.Infrastructure/Fetchers/PlaywrightFetcher.cs
index 4b2d24b..f17ffe7 100644
--- a/TiktokExplode.Infrastructure/Fetchers/PlaywrightFetcher.cs
+++ b/TiktokExplode.Infrastructure/Fetchers/PlaywrightFetcher.cs
@@ -14,7 +14,7 @@ public sealed class PlaywrightFetcher(PlaywrightFetcherOptions options) : IPageF
     /// The underlying browser wrapper. Lazily initialized on the first
     /// <see cref="FetchPageAsync"/> call via the double-check lock pattern.
     /// </summary>
-    private TikTokBrowser? _browser;
+    private TiktokBrowser? _browser;
 
     /// <summary>Semaphore that serializes the one-time browser initialization across concurrent callers.</summary>
     private readonly SemaphoreSlim _initLock = new(1, 1);
@@ -44,7 +44,7 @@ public async Task<PageFetchResult> FetchPageAsync(string url, CancellationToken
             {
                 if (!_initialized)
                 {
-                    _browser = await TikTokBrowser.CreateAsync(options);
+                    _browser = await TiktokBrowser.CreateAsync(options);
                     _initialized = true;
                 }
             }
diff --git a/TiktokExplode.Infrastructure/Fetchers/Search/ISearchFetcher.cs b/TiktokExplode.Infrastructure/Fetchers/Search/ISearchFetcher.cs
index 3e2b964..e1c297b 100644
--- a/TiktokExplode.Infrastructure/Fetchers/Search/ISearchFetcher.cs
+++ b/TiktokExplode.Infrastructure/Fetchers/Search/ISearchFetcher.cs
@@ -1,6 +1,21 @@
 namespace TiktokExplode.Infrastructure.Fetchers.Search;
 
+/// <summary>
+/// Defines the strategy for fetching paginated TikTok search results by keyword.
+/// Implementations may use a real browser (Playwright) or a plain HTTP client.
+/// </summary>
 public interface ISearchFetcher
 {
+    /// <summary>
+    /// Asynchronously streams paginated search result pages for the given <paramref name="keyword"/>.
+    /// Each yielded <see cref="SearchFetchResult"/> contains the raw JSON for one page
+    /// together with the browser cookies needed to authenticate CDN downloads.
+    /// </summary>
+    /// <param name="keyword">The search term to query on TikTok.</param>
+    /// <param name="cancellationToken">Token to cancel the enumeration.</param>
+    /// <returns>
+    /// An <see cref="IAsyncEnumerable{T}"/> of <see cref="SearchFetchResult"/> values,
+    /// one per API page, until no further results are available.
+    /// </returns>
     IAsyncEnumerable<SearchFetchResult> FetchSearchAsync(string keyword, CancellationToken cancellationToken = default);
 }
diff --git a/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs b/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
index 31ea21a..e4c4e75 100644
--- a/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
+++ b/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
@@ -13,11 +13,11 @@ namespace TiktokExplode.Infrastructure.Fetchers.Search;
 /// Microsoft Playwright to search TikTok. Intercepts the internal search API response on
 /// the first page, then fetches subsequent pages via in-browser <c>fetch()</c> calls.
 /// </summary>
-public sealed class PlaywrightSearchFetcher(PlaywrightFetcherOptions options, TikTokOptions tikTokOptions)
+public sealed class PlaywrightSearchFetcher(PlaywrightFetcherOptions options, TiktokOptions tikTokOptions)
     : ISearchFetcher, IAsyncDisposable
 {
 
-    private TikTokBrowser? _browser;
+    private TiktokBrowser? _browser;
 
     /// <summary>Semaphore that serializes the one-time browser initialization across concurrent callers.</summary>
     private readonly SemaphoreSlim _initLock = new(1, 1);
@@ -29,12 +29,12 @@ public sealed class PlaywrightSearchFetcher(PlaywrightFetcherOptions options, Ti
     private volatile bool _initialized = false;
 
     /// <summary>Initializes a new <see cref="PlaywrightSearchFetcher"/> with default options.</summary>
-    public PlaywrightSearchFetcher() : this(new PlaywrightFetcherOptions(), new TikTokOptions()) { }
+    public PlaywrightSearchFetcher() : this(new PlaywrightFetcherOptions(), new TiktokOptions()) { }
 
     /// <summary>
     /// Asynchronously streams pages of raw search results for <paramref name="keyword"/>.
     /// The browser is initialized lazily on the first call. WAF challenges are retried
-    /// up to <see cref="TikTokOptions.MaxWafRetries"/> times with linear back-off.
+    /// up to <see cref="TiktokOptions.MaxWafRetries"/> times with linear back-off.
     /// </summary>
     /// <param name="keyword">The search term to query.</param>
     /// <param name="cancellationToken">Token to cancel the operation.</param>
@@ -50,7 +50,7 @@ public async IAsyncEnumerable<SearchFetchResult> FetchSearchAsync(
             {
                 if (!_initialized)
                 {
-                    _browser ??= await TikTokBrowser.CreateAsync(options);
+                    _browser ??= await TiktokBrowser.CreateAsync(options);
                     _initialized = true;
                 }
             }
diff --git a/TiktokExplode.Infrastructure/Fetchers/Search/SearchFetchResult.cs b/TiktokExplode.Infrastructure/Fetchers/Search/SearchFetchResult.cs
index 13ed170..9680e59 100644
--- a/TiktokExplode.Infrastructure/Fetchers/Search/SearchFetchResult.cs
+++ b/TiktokExplode.Infrastructure/Fetchers/Search/SearchFetchResult.cs
@@ -1,5 +1,10 @@
 namespace TiktokExplode.Infrastructure.Fetchers.Search;
 
+/// <summary>
+/// Represents a single page of raw search data returned by <see cref="ISearchFetcher"/>.
+/// Contains the JSON payload from TikTok's search API and the browser session cookies
+/// required to authenticate subsequent CDN video downloads.
+/// </summary>
 public sealed record SearchFetchResult
 {
     /// <summary>The raw JSON content of the search results returned by TikTok's search API.</summary>
diff --git a/TiktokExplode.Infrastructure/Http/TikTokDownloadClient.cs b/TiktokExplode.Infrastructure/Http/TikTokDownloadClient.cs
index 39e00d4..2c79acd 100644
--- a/TiktokExplode.Infrastructure/Http/TikTokDownloadClient.cs
+++ b/TiktokExplode.Infrastructure/Http/TikTokDownloadClient.cs
@@ -9,7 +9,7 @@ namespace TiktokExplode.Infrastructure.Http;
 /// Maintains a <see cref="CookieContainer"/> that is populated with browser session cookies
 /// before each download to satisfy TikTok's authentication requirements.
 /// </summary>
-public sealed class TikTokDownloadClient : IDisposable
+public sealed class TiktokDownloadClient : IDisposable
 {
     /// <summary>Shared cookie container for all requests made by this client.</summary>
     private readonly CookieContainer _cookies = new();
@@ -21,10 +21,10 @@ public sealed class TikTokDownloadClient : IDisposable
     private readonly HttpClient _httpClient;
 
     /// <summary>
-    /// Initializes a new <see cref="TikTokDownloadClient"/>, configuring the socket handler
+    /// Initializes a new <see cref="TiktokDownloadClient"/>, configuring the socket handler
     /// with connection pooling, automatic decompression, and browser-like default headers.
     /// </summary>
-    public TikTokDownloadClient()
+    public TiktokDownloadClient()
     {
         _handler = new SocketsHttpHandler
         {
@@ -110,7 +110,7 @@ private void ConfigureDefaultHeaders()
             "\"Windows\"");
     }
 
-    
+
     /// <summary>
     /// Initiates a streaming GET request to the CDN URL and returns a <see cref="StreamInfo"/>
     /// wrapping the open response stream and the exact byte length from the
@@ -157,7 +157,7 @@ public async Task<StreamInfo> DownloadVideoAsync(
         {
             Stream          = stream,
             ContentLength   = contentLength
-        }; 
+        };
     }
 
     /// <summary>
diff --git a/TiktokExplode.Infrastructure/Options/TiktokOptions.cs b/TiktokExplode.Infrastructure/Options/TiktokOptions.cs
index 6e1333d..88301d1 100644
--- a/TiktokExplode.Infrastructure/Options/TiktokOptions.cs
+++ b/TiktokExplode.Infrastructure/Options/TiktokOptions.cs
@@ -3,7 +3,7 @@ namespace TiktokExplode.Infrastructure.Options;
 /// <summary>
 /// Configuration options that control the retry and request behaviour of <c>TiktokClient</c>.
 /// </summary>
-public sealed class TikTokOptions
+public sealed class TiktokOptions
 {
     /// <summary>
     /// The maximum number of times the client will retry a request after detecting a WAF challenge.
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
index 0da3178..ef7df0c 100644
--- a/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
@@ -4,7 +4,7 @@
 
 namespace TiktokExplode.Infrastructure.Parsers;
 
-internal sealed class TikTokSearchParser
+internal sealed class TiktokSearchParser
 {
     internal static IEnumerable<Video> Parse(string jsonContent)
     {
@@ -14,14 +14,14 @@ internal static IEnumerable<Video> Parse(string jsonContent)
         var data = root["data"]?.AsArray()
             ?? throw new TiktokParsingException("Search JSON does not contain 'data' array.");
 
-        foreach(var entry in data)
+        foreach (var entry in data)
         {
             if (entry?["type"]?.GetValue<int>() != 1) continue;
 
             var item = entry["item"]
                 ?? throw new TiktokParsingException("'item' node not found in search entry.");
 
-            yield return TikTokVideoParser.ParseVideo(item);
+            yield return TiktokVideoParser.ParseVideo(item);
         }
     }
 }
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
index e39351c..022581b 100644
--- a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
@@ -15,7 +15,7 @@ namespace TiktokExplode.Infrastructure.Parsers;
 /// Extracts the JSON hydration data embedded in the <c>#__UNIVERSAL_DATA_FOR_REHYDRATION__</c>
 /// script tag and maps each field to its corresponding value object.
 /// </summary>
-internal sealed class TikTokVideoParser
+internal sealed class TiktokVideoParser
 {
     /// <summary>AngleSharp HTML parser used to query the hydration script element.</summary>
     private readonly HtmlParser _htmlParser = new();
@@ -31,7 +31,7 @@ internal sealed class TikTokVideoParser
     /// <exception cref="Domain.Exceptions.VideoNotFoundException">
     /// Thrown if the <c>itemStruct</c> node is absent, indicating the video does not exist.
     /// </exception>
-    public async Task<Video> ParseAsync(string htmlContent) 
+    public async Task<Video> ParseAsync(string htmlContent)
     {
         var document = await _htmlParser.ParseDocumentAsync(htmlContent);
 
@@ -39,7 +39,7 @@ public async Task<Video> ParseAsync(string htmlContent)
             ?? throw new TiktokParsingException("Hydration script not found in the HTML content.");
 
         var node = ExtractItemStruct(script);
-        
+
         return ParseVideo(node);
     }
 
@@ -48,7 +48,7 @@ private static JsonNode ExtractItemStruct(IElement html)
     {
         var root = JsonNode.Parse(html.TextContent)
             ?? throw new TiktokParsingException("Failed to parse JSON content from the hydration script.");
-            
+
         var defaultScope = root["__DEFAULT_SCOPE__"]
             ?? throw new TiktokParsingException("Default scope not found in the JSON content.");
 
@@ -115,15 +115,15 @@ private static Author ParseAuthor(JsonNode node)
 
         return new Author
         {
-            Id          = author.GetString("id"),
-            UniqueId    = author.GetString("uniqueId"),
-            Name        = author.GetString("nickname"),
+            Id = author.GetString("id"),
+            UniqueId = author.GetString("uniqueId"),
+            Name = author.GetString("nickname"),
             Description = author.GetStringOrEmpty("signature"),
-            IsVerified  = author.GetBool("verified"),
-            IsPrivate   = author.GetBool("privateAccount"),
-            CreatedAt   = DateTimeOffset.FromUnixTimeSeconds(author.GetNumber<long>("createTime")),
-            Avatar      = ParseProfileImageVariants(author),
-            Stats       = ParseAuthorStats(authorStatsNode),
+            IsVerified = author.GetBool("verified"),
+            IsPrivate = author.GetBool("privateAccount"),
+            CreatedAt = DateTimeOffset.FromUnixTimeSeconds(author.GetNumber<long>("createTime")),
+            Avatar = ParseProfileImageVariants(author),
+            Stats = ParseAuthorStats(authorStatsNode),
         };
     }
 
@@ -132,11 +132,11 @@ private static AuthorStats ParseAuthorStats(JsonNode authorStatsNode)
     {
         return new AuthorStats
         {
-            Followers     = authorStatsNode.GetNumber<long>("followerCount"),
-            Following     = authorStatsNode.GetNumber<long>("followingCount"),
-            Friends       = authorStatsNode.GetNumber<long>("friendCount"),
+            Followers = authorStatsNode.GetNumber<long>("followerCount"),
+            Following = authorStatsNode.GetNumber<long>("followingCount"),
+            Friends = authorStatsNode.GetNumber<long>("friendCount"),
             LikesReceived = authorStatsNode.GetNumber<long>("heartCount"),
-            VideoCount    = authorStatsNode.GetNumber<long>("videoCount"),
+            VideoCount = authorStatsNode.GetNumber<long>("videoCount"),
         };
     }
 
@@ -147,7 +147,7 @@ private static ProfileImageVariants ParseProfileImageVariants(JsonNode author)
         {
             Larger = author.GetString("avatarLarger"),
             Medium = author.GetString("avatarMedium"),
-            Small  = author.GetString("avatarThumb")
+            Small = author.GetString("avatarThumb")
         };
     }
 
@@ -173,9 +173,9 @@ private static VideoDownloadLinks ParseDownloadLinks(JsonNode node)
     {
         return new VideoDownloadLinks
         {
-            OriginalUrl     = node.GetString("playAddr"),
-            WatermarkedUrl  = node.GetString("downloadAddr"),
-            OriginalSizeInBytes     = node.GetNumber<long>("size")
+            OriginalUrl = node.GetString("playAddr"),
+            WatermarkedUrl = node.GetString("downloadAddr"),
+            OriginalSizeInBytes = node.GetNumber<long>("size")
         };
     }
 
@@ -235,7 +235,7 @@ private static VideoCover ParseVideoCover(JsonNode node)
         return new VideoCover
         {
             AnimatedUrl = node.GetString("dynamicCover"),
-            StaticUrl   = node.GetString("cover")
+            StaticUrl = node.GetString("cover")
         };
     }
 }
\ No newline at end of file
diff --git a/TiktokExplode.Tests/Domain/Utilities/TikTokUrlValidatorTests.cs b/TiktokExplode.Tests/Domain/Utilities/TikTokUrlValidatorTests.cs
index 34e044f..909b1f4 100644
--- a/TiktokExplode.Tests/Domain/Utilities/TikTokUrlValidatorTests.cs
+++ b/TiktokExplode.Tests/Domain/Utilities/TikTokUrlValidatorTests.cs
@@ -6,61 +6,61 @@ namespace TiktokExplode.Tests.Domain.Utilities;
 public class TikTokUrlValidatorTests
 {
     [Theory]
-    [InlineData("https://www.tiktok.com/@user/video/1234567890123456789",        "standard www video")]
-    [InlineData("https://tiktok.com/@user/video/1234567890123456789",            "no-www video")]
-    [InlineData("https://vm.tiktok.com/ZMkAbCdEf/",                             "vm short link")]
-    [InlineData("https://vt.tiktok.com/ZMkAbCdEf/",                             "vt short link")]
-    [InlineData("https://www.tiktok.com/@user/video/1234567890123456789?lang=en","with query string")]
-    [InlineData("https://www.tiktok.com/@user/video/1234567890123456789#comments","with fragment")]
-    [InlineData("https://www.tiktok.com/@user.name/video/1234567890123456789",   "username with dots")]
-    [InlineData("https://www.tiktok.com/@user_123/video/1234567890123456789",    "username with underscores")]
+    [InlineData("https://www.tiktok.com/@user/video/1234567890123456789", "standard www video")]
+    [InlineData("https://tiktok.com/@user/video/1234567890123456789", "no-www video")]
+    [InlineData("https://vm.tiktok.com/ZMkAbCdEf/", "vm short link")]
+    [InlineData("https://vt.tiktok.com/ZMkAbCdEf/", "vt short link")]
+    [InlineData("https://www.tiktok.com/@user/video/1234567890123456789?lang=en", "with query string")]
+    [InlineData("https://www.tiktok.com/@user/video/1234567890123456789#comments", "with fragment")]
+    [InlineData("https://www.tiktok.com/@user.name/video/1234567890123456789", "username with dots")]
+    [InlineData("https://www.tiktok.com/@user_123/video/1234567890123456789", "username with underscores")]
     [InlineData("https://www.tiktok.com/@user/video/1234567890123456789?lang=en&source=share", "multiple query params")]
     public void Should_NotThrow_When_UrlIsValid(string url, string _)
     {
-        var act = () => TikTokUrlValidator.Validate(url);
+        var act = () => TiktokUrlValidator.Validate(url);
 
         act.Should().NotThrow();
     }
 
     [Theory]
-    [InlineData("http://www.tiktok.com/@user/video/123",  "plain HTTP")]
-    [InlineData("ftp://www.tiktok.com/@user/video/123",   "FTP")]
-    [InlineData("ws://www.tiktok.com/@user/video/123",    "WebSocket")]
+    [InlineData("http://www.tiktok.com/@user/video/123", "plain HTTP")]
+    [InlineData("ftp://www.tiktok.com/@user/video/123", "FTP")]
+    [InlineData("ws://www.tiktok.com/@user/video/123", "WebSocket")]
     [InlineData("file:///www.tiktok.com/@user/video/123", "file scheme")]
     public void Should_ThrowArgumentException_When_SchemeIsNotHttps(string url, string _)
     {
-        var act = () => TikTokUrlValidator.Validate(url);
+        var act = () => TiktokUrlValidator.Validate(url);
 
         act.Should().ThrowExactly<ArgumentException>()
             .WithParameterName(nameof(url));
     }
 
     [Theory]
-    [InlineData("https://youtube.com/watch?v=abc",                   "YouTube")]
-    [InlineData("https://instagram.com/reel/abc",                    "Instagram")]
-    [InlineData("https://twitter.com/user/status/123",               "Twitter")]
-    [InlineData("https://tiktok.com.evil.com/@user/video/123",       "domain spoofing suffix")]
-    [InlineData("https://eviltiktok.com/@user/video/123",            "domain spoofing prefix")]
-    [InlineData("https://subdomain.tiktok.com/@user/video/123",      "unknown subdomain")]
-    [InlineData("https://subdomain.www.tiktok.com/@user/video/123",  "double subdomain")]
-    [InlineData("https://m.tiktok.com/@user/video/123",              "mobile subdomain (not registered)")]
+    [InlineData("https://youtube.com/watch?v=abc", "YouTube")]
+    [InlineData("https://instagram.com/reel/abc", "Instagram")]
+    [InlineData("https://twitter.com/user/status/123", "Twitter")]
+    [InlineData("https://tiktok.com.evil.com/@user/video/123", "domain spoofing suffix")]
+    [InlineData("https://eviltiktok.com/@user/video/123", "domain spoofing prefix")]
+    [InlineData("https://subdomain.tiktok.com/@user/video/123", "unknown subdomain")]
+    [InlineData("https://subdomain.www.tiktok.com/@user/video/123", "double subdomain")]
+    [InlineData("https://m.tiktok.com/@user/video/123", "mobile subdomain (not registered)")]
     public void Should_ThrowArgumentException_When_HostIsNotRecognizedTikTokDomain(string url, string _)
     {
-        var act = () => TikTokUrlValidator.Validate(url);
+        var act = () => TiktokUrlValidator.Validate(url);
 
         act.Should().ThrowExactly<ArgumentException>()
             .WithParameterName(nameof(url));
     }
 
     [Theory]
-    [InlineData("not-a-url",          "plain string")]
-    [InlineData("/relative/path",     "relative path")]
-    [InlineData("@user/video/123",    "relative tiktok-like path")]
-    [InlineData("",                   "empty string")]
-    [InlineData("   ",                "whitespace only")]
+    [InlineData("not-a-url", "plain string")]
+    [InlineData("/relative/path", "relative path")]
+    [InlineData("@user/video/123", "relative tiktok-like path")]
+    [InlineData("", "empty string")]
+    [InlineData("   ", "whitespace only")]
     public void Should_ThrowArgumentException_When_UrlIsNotAbsolute(string url, string _)
     {
-        var act = () => TikTokUrlValidator.Validate(url);
+        var act = () => TiktokUrlValidator.Validate(url);
 
         act.Should().ThrowExactly<ArgumentException>()
             .WithParameterName(nameof(url));
@@ -69,7 +69,7 @@ public void Should_ThrowArgumentException_When_UrlIsNotAbsolute(string url, stri
     [Fact]
     public void Should_ThrowArgumentException_When_UrlIsNull()
     {
-        var act = () => TikTokUrlValidator.Validate(null!);
+        var act = () => TiktokUrlValidator.Validate(null!);
 
         act.Should().ThrowExactly<ArgumentException>()
             .WithParameterName("url");
diff --git a/TiktokExplode.Tests/Infrastructure/Clients/TiktokClientTests.cs b/TiktokExplode.Tests/Infrastructure/Clients/TiktokClientTests.cs
index 8b8b2dd..fe97f0d 100644
--- a/TiktokExplode.Tests/Infrastructure/Clients/TiktokClientTests.cs
+++ b/TiktokExplode.Tests/Infrastructure/Clients/TiktokClientTests.cs
@@ -17,7 +17,7 @@ public class TiktokClientTests
     public async Task Should_ThrowArgumentException_When_UrlIsInvalid()
     {
         var fetcher = Substitute.For<IPageFetcher>();
-        await using var client = new TiktokClient(fetcher, new TikTokOptions());
+        await using var client = new TiktokClient(fetcher, new TiktokOptions());
 
         var act = async () => await client.GetVideoAsync("not-a-tiktok-url");
 
@@ -31,7 +31,7 @@ public async Task Should_ThrowArgumentException_When_UrlIsInvalid()
     public async Task Should_RetryAndSucceed_When_FetcherThrowsWafOnFirstAttemptOnly()
     {
         var fetcher = Substitute.For<IPageFetcher>();
-        var options = new TikTokOptions { MaxWafRetries = 2, RetryBaseDelay = TimeSpan.Zero };
+        var options = new TiktokOptions { MaxWafRetries = 2, RetryBaseDelay = TimeSpan.Zero };
 
         fetcher.FetchPageAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
                .Returns(
@@ -51,7 +51,7 @@ public async Task Should_RetryAndSucceed_When_FetcherThrowsWafOnFirstAttemptOnly
     public async Task Should_ThrowTiktokWafException_When_AllRetriesAreExhausted()
     {
         var fetcher = Substitute.For<IPageFetcher>();
-        var options = new TikTokOptions { MaxWafRetries = 2, RetryBaseDelay = TimeSpan.Zero };
+        var options = new TiktokOptions { MaxWafRetries = 2, RetryBaseDelay = TimeSpan.Zero };
 
         fetcher.FetchPageAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
                .Returns(Task.FromException<PageFetchResult>(new TiktokWafException()));
@@ -72,7 +72,7 @@ public async Task Should_CallFetcherExactlyMaxRetriesPlusOneTimes_When_WafAlways
         int expectedCalls)
     {
         var fetcher = Substitute.For<IPageFetcher>();
-        var options = new TikTokOptions { MaxWafRetries = maxWafRetries, RetryBaseDelay = TimeSpan.Zero };
+        var options = new TiktokOptions { MaxWafRetries = maxWafRetries, RetryBaseDelay = TimeSpan.Zero };
 
         fetcher.FetchPageAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
                .Returns(Task.FromException<PageFetchResult>(new TiktokWafException()));
diff --git a/TiktokExplode.Tests/Infrastructure/Parsers/TikTokVideoParserTests.cs b/TiktokExplode.Tests/Infrastructure/Parsers/TikTokVideoParserTests.cs
index 9fd1932..d5ccb25 100644
--- a/TiktokExplode.Tests/Infrastructure/Parsers/TikTokVideoParserTests.cs
+++ b/TiktokExplode.Tests/Infrastructure/Parsers/TikTokVideoParserTests.cs
@@ -12,7 +12,7 @@ public class TikTokVideoParserTests
 {
     private const string ValidUrl = "https://www.tiktok.com/@js_nightwave/video/7579504710961548565";
 
-    private static readonly TikTokOptions NoRetry = new()
+    private static readonly TiktokOptions NoRetry = new()
     {
         MaxWafRetries = 0,
         RetryBaseDelay = TimeSpan.Zero
diff --git a/TiktokExplode/Domain/Abstractions/ISearchClient.cs b/TiktokExplode/Domain/Abstractions/ISearchClient.cs
index f6d63a4..83226e0 100644
--- a/TiktokExplode/Domain/Abstractions/ISearchClient.cs
+++ b/TiktokExplode/Domain/Abstractions/ISearchClient.cs
@@ -2,7 +2,21 @@
 
 namespace TiktokExplode.Domain.Abstractions;
 
+/// <summary>
+/// Defines the contract for a TikTok search client that queries videos by keyword
+/// and can stream their content from TikTok's CDN.
+/// </summary>
 public interface ISearchClient : IDownloadClient
 {
+    /// <summary>
+    /// Asynchronously streams <see cref="Video"/> results for the given <paramref name="keyword"/>,
+    /// lazily fetching additional pages as the sequence is consumed.
+    /// </summary>
+    /// <param name="keyword">The search term to query on TikTok.</param>
+    /// <param name="cancellationToken">Token to cancel the enumeration.</param>
+    /// <returns>
+    /// An <see cref="IAsyncEnumerable{T}"/> of <see cref="Video"/> values
+    /// ordered by TikTok's default relevance ranking.
+    /// </returns>
     IAsyncEnumerable<Video> SearchAsync(string keyword, CancellationToken cancellationToken = default);
 }
\ No newline at end of file
diff --git a/TiktokExplode/Domain/Utilities/TikTokUrlValidator.cs b/TiktokExplode/Domain/Utilities/TikTokUrlValidator.cs
index 4ce6626..1317e25 100644
--- a/TiktokExplode/Domain/Utilities/TikTokUrlValidator.cs
+++ b/TiktokExplode/Domain/Utilities/TikTokUrlValidator.cs
@@ -3,7 +3,7 @@ namespace TiktokExplode.Domain.Utilities;
 /// <summary>
 /// Validates TikTok video URLs before they are used for network requests.
 /// </summary>
-public static class TikTokUrlValidator
+public static class TiktokUrlValidator
 {
     /// <summary>
     /// Set of recognized TikTok hostnames, including short-link variants

From cbb584f669215eaafa1c9ab1eb9dfeb8b6b66cb2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Mon, 8 Jun 2026 12:23:32 -0500
Subject: [PATCH 06/18] Refactor console and add video music metadata

Transformed the console app to support two modes: video download by URL and video search by keyword. Added helper methods for fetching, searching, and downloading videos.

Enhanced `TiktokBrowser` to reuse signed URLs for search pagination and improved response handling with JavaScript.

Introduced `GetOptionalNumber<T>` in `JsonNodeExtensions` for flexible numeric parsing. Updated `TikTokVideoParser` to handle precise durations and added support for video music metadata, including title, author, album, and artwork.

Added new tests in `TikTokVideoParserTests` for music metadata and adjusted existing tests for duration changes. Updated fixtures in `TikTokFixtures` to include music-related data.

Made `CreatedAt` optional in `Author.cs` and added a `Music` field in `Video.cs`. Created `MediaDuration` and `VideoMusic` classes to represent music and duration details.

Reorganized project structure in `TiktokExplode.NET.slnx` and adjusted packaging paths in `TiktokExplode.csproj`.
---
 TiktokExplode.Console/Program.cs              | 178 +++++++++++++-----
 .../Browser/TikTokBrowser.cs                  |  54 ++++--
 .../Common/JsonNodeExtensions.cs              |  28 +++
 .../Parsers/TikTokVideoParser.cs              | 130 ++++++++-----
 TiktokExplode.NET.slnx                        |   9 +-
 .../Parsers/TikTokVideoParserTests.cs         |  19 +-
 .../Infrastructure/TikTokFixtures.cs          |  16 +-
 TiktokExplode/Domain/Entities/Author.cs       |   4 +-
 TiktokExplode/Domain/Entities/Video.cs        |   5 +
 .../ValueObjects/Videos/MediaDuration.cs      |  19 ++
 .../ValueObjects/Videos/VideoDuration.cs      |   4 +-
 .../Domain/ValueObjects/Videos/VideoMusic.cs  |  48 +++++
 TiktokExplode/TiktokExplode.csproj            |   4 +-
 13 files changed, 400 insertions(+), 118 deletions(-)
 create mode 100644 TiktokExplode/Domain/ValueObjects/Videos/MediaDuration.cs
 create mode 100644 TiktokExplode/Domain/ValueObjects/Videos/VideoMusic.cs

diff --git a/TiktokExplode.Console/Program.cs b/TiktokExplode.Console/Program.cs
index 59581ca..5411c25 100644
--- a/TiktokExplode.Console/Program.cs
+++ b/TiktokExplode.Console/Program.cs
@@ -1,83 +1,163 @@
+using TiktokExplode.Domain.Abstractions;
+using TiktokExplode.Domain.Entities;
 using TiktokExplode.Domain.Exceptions;
 using TiktokExplode.Infrastructure.Clients;
 using TiktokExplode.Infrastructure.Common;
 using TiktokExplode.Infrastructure.Options;
 
-const string Separator = "─────────────────────────────────────────";
-const string DefaultUrl = "https://www.tiktok.com/@js_nightwave/video/7579504710961548565";
+const string Sep = "─────────────────────────────────────────";
 
-Console.WriteLine("TiktokExplode — Video Downloader");
-Console.WriteLine(Separator);
-Console.Write("Video URL (press Enter for default): ");
-var url = Console.ReadLine();
+Console.WriteLine("TiktokExplode — Test Console");
+Console.WriteLine(Sep);
+Console.WriteLine("  [1] Get video by URL");
+Console.WriteLine("  [2] Search by keyword");
+Console.WriteLine(Sep);
+Console.Write("Choose (1/2): ");
+var mode = Console.ReadLine()?.Trim();
 
-if (string.IsNullOrWhiteSpace(url))
+Console.WriteLine(Sep);
+
+var browserOptions = new PlaywrightFetcherOptions { BrowserChannel = "msedge" };
+
+if (mode == "1")
 {
-    url = DefaultUrl;
-    Console.WriteLine($"Using default: {url}");
+    const string DefaultUrl = "https://www.tiktok.com/@js_nightwave/video/7579504710961548565";
+    Console.Write($"Video URL (Enter for default): ");
+    var url = Console.ReadLine();
+    if (string.IsNullOrWhiteSpace(url))
+    {
+        url = DefaultUrl;
+        Console.WriteLine($"Using default: {url}");
+    }
+
+    await using var client = TiktokClient.CreateWithBrowser(browserOptions);
+    await FetchAndDownloadAsync(client, url);
 }
+else if (mode == "2")
+{
+    Console.Write("Keyword: ");
+    var keyword = Console.ReadLine()?.Trim();
+    if (string.IsNullOrWhiteSpace(keyword))
+    {
+        Console.WriteLine("No keyword entered.");
+        return;
+    }
 
-Console.WriteLine(Separator);
+    Console.Write("Max results (Enter for 5): ");
+    var maxStr = Console.ReadLine()?.Trim();
+    var maxResults = int.TryParse(maxStr, out var n) && n > 0 ? n : 5;
 
-await using var client = TiktokClient.CreateWithBrowser(new PlaywrightFetcherOptions
+    await using var searchClient = TiktokSearchClient.CreateWithBrowser(browserOptions);
+    await SearchAndDownloadAsync(searchClient, keyword, maxResults);
+}
+else
 {
-    BrowserChannel = "msedge"
-});
+    Console.WriteLine("Invalid option.");
+}
+
+// ── helpers ────────────────────────────────────────────────────────────────
 
-try
+static async Task FetchAndDownloadAsync(IVideoClient client, string url)
 {
-    Console.Write("Fetching video metadata...");
-    var video = await client.GetVideoAsync(url);
-    Console.WriteLine(" done.");
-    Console.WriteLine(Separator);
+    const string Sep = "─────────────────────────────────────────";
+    try
+    {
+        Console.WriteLine(Sep);
+        Console.Write("Fetching video metadata...");
+        var video = await client.GetVideoAsync(url);
+        Console.WriteLine(" done.");
+        PrintVideo(video, 1, 1);
+        await PromptDownloadAsync((IDownloadClient)client, video);
+    }
+    catch (TiktokWafException ex)  { Console.WriteLine($"\n[WAF] {ex.Message}"); }
+    catch (VideoNotFoundException ex) { Console.WriteLine($"\n[404] {ex.Message}"); }
+    catch (TiktokException ex)     { Console.WriteLine($"\n[Error] {ex.Message}"); }
+}
+
+static async Task SearchAndDownloadAsync(ISearchClient client, string keyword, int maxResults)
+{
+    const string Sep = "─────────────────────────────────────────";
+    var videos = new List<Video>();
+
+    try
+    {
+        Console.Write($"Searching for \"{keyword}\"...");
+        await foreach (var video in client.SearchAsync(keyword))
+        {
+            videos.Add(video);
+            if (videos.Count >= maxResults) break;
+        }
+        Console.WriteLine($" found {videos.Count} result(s).");
+    }
+    catch (TiktokWafException ex) { Console.WriteLine($"\n[WAF] {ex.Message}"); return; }
+    catch (TiktokException ex)    { Console.WriteLine($"\n[Error] {ex.Message}"); return; }
+
+    if (videos.Count == 0)
+    {
+        Console.WriteLine("No results.");
+        return;
+    }
+
+    Console.WriteLine(Sep);
+    for (int i = 0; i < videos.Count; i++)
+        PrintVideo(videos[i], i + 1, videos.Count);
+
+    Console.Write($"\nDownload which video? (1-{videos.Count}, or Enter to skip): ");
+    var pick = Console.ReadLine()?.Trim();
+    if (!int.TryParse(pick, out var idx) || idx < 1 || idx > videos.Count)
+    {
+        Console.WriteLine("Skipping download.");
+        return;
+    }
 
+    await PromptDownloadAsync(client, videos[idx - 1]);
+}
+
+static void PrintVideo(Video video, int index, int total)
+{
+    const string Sep = "─────────────────────────────────────────";
+    Console.WriteLine(Sep);
+    if (total > 1) Console.WriteLine($"  [{index}/{total}]");
     Console.WriteLine($"  ID          {video.Id}");
     Console.WriteLine($"  Author      {video.Author.Name} (@{video.Author.UniqueId})");
     Console.WriteLine($"  Duration    {video.Duration.Seconds}s");
     Console.WriteLine($"  Views       {video.Stats.Views:N0}");
     Console.WriteLine($"  Likes       {video.Stats.Likes:N0}");
     Console.WriteLine($"  Size        {video.Info.DownloadLinks.OriginalSizeInBytes / (1_024 * 1_024):F2} MB");
-    Console.WriteLine(Separator);
-
-    Console.Write("Download with watermark? [Y/n]: ");
-    var watermarkChoice = Console.ReadLine()?.Trim();
-    var isWatermarked = string.IsNullOrEmpty(watermarkChoice) ||
-                        watermarkChoice.Equals("y", StringComparison.OrdinalIgnoreCase);
+}
 
+static async Task PromptDownloadAsync(IDownloadClient client, Video video)
+{
+    const string Sep = "─────────────────────────────────────────";
+    Console.WriteLine(Sep);
     Console.Write("Download? [Y/n]: ");
-    var downloadChoice = Console.ReadLine()?.Trim();
-    if (!string.IsNullOrEmpty(downloadChoice) && !downloadChoice.Equals("y", StringComparison.OrdinalIgnoreCase))
+    var dl = Console.ReadLine()?.Trim();
+    if (!string.IsNullOrEmpty(dl) && !dl.Equals("y", StringComparison.OrdinalIgnoreCase))
     {
-        Console.WriteLine("Download cancelled.");
+        Console.WriteLine("Skipped.");
         return;
     }
 
+    Console.Write("With watermark? [Y/n]: ");
+    var wm = Console.ReadLine()?.Trim();
+    var isWatermarked = string.IsNullOrEmpty(wm) || wm.Equals("y", StringComparison.OrdinalIgnoreCase);
+
     var suffix = isWatermarked ? "watermarked" : "original";
     var fileName = $"{video.Id}_{video.Author.UniqueId}_{suffix}.mp4";
-
     Console.WriteLine($"Saving to: {fileName}");
 
-    IProgress<double> progress = new Progress<double>(p =>
-        Console.Write($"\r  Downloading... {p:P0}   ")
-    );
+    IProgress<double> progress = new Progress<double>(p => Console.Write($"\r  Downloading... {p:P0}   "));
 
-    if (isWatermarked)
-        await client.DownloadWatermarkedAsync(video, fileName, progress);
-    else
-        await client.DownloadAsync(video, fileName, progress);
+    try
+    {
+        if (isWatermarked)
+            await client.DownloadWatermarkedAsync(video, fileName, progress);
+        else
+            await client.DownloadAsync(video, fileName, progress);
 
-    Console.WriteLine($"\n  Saved: {fileName}");
-    Console.WriteLine(Separator);
-}
-catch (TiktokWafException ex)
-{
-    Console.WriteLine($"\n[WAF] Bot detection triggered: {ex.Message}");
-}
-catch (VideoNotFoundException ex)
-{
-    Console.WriteLine($"\n[404] Video not found: {ex.Message}");
-}
-catch (TiktokException ex)
-{
-    Console.WriteLine($"\n[Error] {ex.Message}");
+        Console.WriteLine($"\n  Saved: {fileName}");
+    }
+    catch (TiktokException ex) { Console.WriteLine($"\n[Error] {ex.Message}"); }
+
+    Console.WriteLine(Sep);
 }
diff --git a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
index c82ae67..740882a 100644
--- a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
+++ b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
@@ -27,6 +27,12 @@ internal sealed class TiktokBrowser : IAsyncDisposable
     /// <summary>Browser launch and navigation options.</summary>
     private readonly PlaywrightFetcherOptions _options;
 
+    /// <summary>
+    /// The full URL (including X-Bogus and other signature params) of the last intercepted
+    /// search API request. Stored on the first page so subsequent pages can reuse the signature.
+    /// </summary>
+    private string? _lastSearchApiUrl;
+
     /// <summary>Private constructor — use <see cref="CreateAsync"/> to instantiate.</summary>
     private TiktokBrowser(
         IPlaywright playwright,
@@ -129,14 +135,18 @@ public async Task<string> GetSearchPageAsync(string keyword)
 
         try
         {
+            // Set up listener BEFORE navigating so we don't miss the response.
+            // No trailing slash — the actual URL may or may not have one.
             var responseTask = page.WaitForResponseAsync(
-               r => r.Url.Contains("/api/search/general/full/"),
+               r => r.Url.Contains("/api/search/general/full"),
                new PageWaitForResponseOptions { Timeout = _options.PageTimeoutMs });
 
+            // Use Load (not DOMContentLoaded): TikTok is a React SPA — the API call
+            // fires only after JS initialises, which happens after DOMContentLoaded.
             var pageResponse = await page.GotoAsync(
                 $"https://www.tiktok.com/search?q={Uri.EscapeDataString(keyword)}", new PageGotoOptions
                 {
-                    WaitUntil = WaitUntilState.DOMContentLoaded,
+                    WaitUntil = WaitUntilState.Load,
                     Timeout = _options.PageTimeoutMs
                 });
 
@@ -161,7 +171,23 @@ public async Task<string> GetSearchPageAsync(string keyword)
             if (!response.Ok)
                 throw new TiktokParsingException($"Failed to load search results. Status: {response.Status}");
 
-            return await response.TextAsync();
+            // Save the signed URL (X-Bogus included) for use in subsequent pages.
+            _lastSearchApiUrl = response.Url;
+
+            // Do NOT use response.TextAsync() — Playwright returns "" for already-consumed
+            // streaming bodies. Instead re-fetch from JS with credentials:include so the browser
+            // sends cookies + the original signature params (X-Bogus) that TikTok requires.
+            var data = await page.EvaluateAsync<string>("""
+                async (url) => {
+                    const resp = await fetch(url, {
+                        credentials: 'include',
+                        headers: { 'accept': 'application/json, text/plain, */*' }
+                    });
+                    return await resp.text();
+                }
+                """, _lastSearchApiUrl);
+
+            return data;
         }
         finally
         {
@@ -175,18 +201,24 @@ public async Task<string> GetSearchNextPageAsync(
         long cursor,
         IPage page)
     {
+        if (_lastSearchApiUrl is null)
+            throw new TiktokParsingException("No signed search API URL available. Call GetSearchPageAsync first.");
+
+        // Reuse the signed URL from the first page (preserves X-Bogus and other signature params).
+        // Only update keyword, cursor, and offset in JS — the browser handles credentials via cookies.
         return await page.EvaluateAsync<string>("""
         async (args) => {
-            const url = new URL('/api/search/general/full/', 'https://www.tiktok.com');
+            const url = new URL(args.baseUrl);
             url.searchParams.set('keyword', args.keyword);
-            url.searchParams.set('cursor', args.cursor);
-            url.searchParams.set('offset', args.cursor);
-            url.searchParams.set('count', '12');
-            url.searchParams.set('from_page', 'search');
-            const res = await fetch(url.toString(), { credentials: 'include' });
-            return await res.text();
+            url.searchParams.set('cursor', String(args.cursor));
+            url.searchParams.set('offset', String(args.cursor));
+            const resp = await fetch(url.toString(), {
+                credentials: 'include',
+                headers: { 'accept': 'application/json, text/plain, */*' }
+            });
+            return await resp.text();
         }
-        """, new { keyword, cursor });
+        """, new { baseUrl = _lastSearchApiUrl, keyword, cursor });
     }
 
     /// <summary>
diff --git a/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs b/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs
index d0e45f7..c9ecfcf 100644
--- a/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs
+++ b/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs
@@ -66,6 +66,34 @@ public static T GetNumber<T>(this JsonNode node, string field) where T : INumber
         };
     }
 
+    /// <summary>
+    /// Returns the numeric value of <paramref name="field"/> in <paramref name="node"/> as
+    /// <typeparamref name="T"/>, or <see langword="null"/> if the field is absent.
+    /// JSON strings that parse as a valid number are also accepted.
+    /// </summary>
+    /// <typeparam name="T">Any value type numeric type that implements <see cref="INumber{TSelf}"/>.</typeparam>
+    /// <exception cref="TiktokParsingException">
+    /// Thrown if the field is present but is not a number or numeric string, or the string
+    /// cannot be parsed as <typeparamref name="T"/>.
+    /// </exception>
+    public static T? GetOptionalNumber<T>(this JsonNode node, string field)
+        where T : struct, INumber<T>
+    {
+        var value = node[field];
+
+        if (value is null)
+            return null;
+
+        return value.GetValueKind() switch
+        {
+            JsonValueKind.Number => value.GetValue<T>(),
+            JsonValueKind.String => T.TryParse(value.GetValue<string>(), null, out var result)
+                ? result
+                : throw new TiktokParsingException($"Field '{field}' has an invalid numeric value."),
+            _ => throw new TiktokParsingException($"Field '{field}' has an unexpected type.")
+        };
+    }
+
     /// <summary>
     /// Returns the boolean value of <paramref name="field"/> in <paramref name="node"/>.
     /// </summary>
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
index 022581b..5cabb86 100644
--- a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
@@ -82,7 +82,8 @@ internal static Video ParseVideo(JsonNode node)
             Author      = ParseAuthor(node),
             Info        = ParseVideoInfo(videoNode),
             Stats       = ParseVideoStats(statsNode),
-            Duration    = ParseVideoDuration(musicNode),
+            Duration    = ParseVideoDuration(videoNode),
+            Music       = ParseVideoMusic(musicNode),
             Language    = ParseVideoLanguage(node),
             Cover       = ParseVideoCover(videoNode),
             Description = node.GetStringOrEmpty("desc"),
@@ -91,16 +92,15 @@ internal static Video ParseVideo(JsonNode node)
         };
     }
 
-    /// <summary>Maps the <c>music.preciseDuration</c> sub-tree to a <see cref="VideoDuration"/>.</summary>
+    /// <summary>Maps the <c>video.duration</c> fields to a <see cref="VideoDuration"/>.</summary>
     private static VideoDuration ParseVideoDuration(JsonNode node)
     {
-        var videoDurationNode = node["preciseDuration"]
-            ?? throw new TiktokParsingException("Precise duration information not found in the JSON content.");
+        var seconds = node.GetNumber<int>("duration");
 
         return new VideoDuration
         {
-            Seconds = node.GetNumber<int>("duration"),
-            PreciseSeconds = videoDurationNode.GetNumber<double>("preciseDuration")
+            Seconds         = seconds,
+            PreciseSeconds  = node.GetOptionalNumber<double>("preciseDuration") ?? seconds
         };
     }
 
@@ -113,16 +113,17 @@ private static Author ParseAuthor(JsonNode node)
         var authorStatsNode = node["authorStatsV2"]
             ?? throw new TiktokParsingException("Author stats not found in the JSON content.");
 
+        var createdAtUnix = author.GetOptionalNumber<long>("createTime");
         return new Author
         {
-            Id = author.GetString("id"),
-            UniqueId = author.GetString("uniqueId"),
-            Name = author.GetString("nickname"),
+            Id          = author.GetString("id"),
+            UniqueId    = author.GetString("uniqueId"),
+            Name        = author.GetString("nickname"),
             Description = author.GetStringOrEmpty("signature"),
-            IsVerified = author.GetBool("verified"),
-            IsPrivate = author.GetBool("privateAccount"),
-            CreatedAt = DateTimeOffset.FromUnixTimeSeconds(author.GetNumber<long>("createTime")),
-            Avatar = ParseProfileImageVariants(author),
+            IsVerified  = author.GetBool("verified"),
+            IsPrivate   = author.GetBool("privateAccount"),
+            CreatedAt   = createdAtUnix is not null ? DateTimeOffset.FromUnixTimeSeconds(createdAtUnix.Value) : null,
+            Avatar      = ParseProfileImageVariants(author),
             Stats = ParseAuthorStats(authorStatsNode),
         };
     }
@@ -132,11 +133,11 @@ private static AuthorStats ParseAuthorStats(JsonNode authorStatsNode)
     {
         return new AuthorStats
         {
-            Followers = authorStatsNode.GetNumber<long>("followerCount"),
-            Following = authorStatsNode.GetNumber<long>("followingCount"),
-            Friends = authorStatsNode.GetNumber<long>("friendCount"),
-            LikesReceived = authorStatsNode.GetNumber<long>("heartCount"),
-            VideoCount = authorStatsNode.GetNumber<long>("videoCount"),
+            Followers       = authorStatsNode.GetNumber<long>("followerCount"),
+            Following       = authorStatsNode.GetNumber<long>("followingCount"),
+            Friends         = authorStatsNode.GetNumber<long>("friendCount"),
+            LikesReceived   = authorStatsNode.GetNumber<long>("heartCount"),
+            VideoCount      = authorStatsNode.GetNumber<long>("videoCount"),
         };
     }
 
@@ -145,9 +146,9 @@ private static ProfileImageVariants ParseProfileImageVariants(JsonNode author)
     {
         return new ProfileImageVariants
         {
-            Larger = author.GetString("avatarLarger"),
-            Medium = author.GetString("avatarMedium"),
-            Small = author.GetString("avatarThumb")
+            Larger  = author.GetString("avatarLarger"),
+            Medium  = author.GetString("avatarMedium"),
+            Small   = author.GetString("avatarThumb")
         };
     }
 
@@ -159,12 +160,12 @@ private static VideoInfo ParseVideoInfo(JsonNode node)
 
         return new VideoInfo
         {
-            Ratio = node.GetString("ratio"),
-            VideoQuality = node.GetString("videoQuality"),
-            Width = node.GetNumber<int>("width"),
-            Height = node.GetNumber<int>("height"),
-            Bitrates = ParseBitrates(bitrateInfoNode),
-            DownloadLinks = ParseDownloadLinks(node),
+            Ratio           = node.GetString("ratio"),
+            VideoQuality    = node.GetString("videoQuality"),
+            Width           = node.GetNumber<int>("width"),
+            Height          = node.GetNumber<int>("height"),
+            Bitrates        = ParseBitrates(bitrateInfoNode),
+            DownloadLinks   = ParseDownloadLinks(node),
         };
     }
 
@@ -173,8 +174,8 @@ private static VideoDownloadLinks ParseDownloadLinks(JsonNode node)
     {
         return new VideoDownloadLinks
         {
-            OriginalUrl = node.GetString("playAddr"),
-            WatermarkedUrl = node.GetString("downloadAddr"),
+            OriginalUrl         = node.GetString("playAddr"),
+            WatermarkedUrl      = node.GetString("downloadAddr"),
             OriginalSizeInBytes = node.GetNumber<long>("size")
         };
     }
@@ -184,12 +185,12 @@ private static VideoStats ParseVideoStats(JsonNode node)
     {
         return new VideoStats
         {
-            Views = node.GetNumber<long>("playCount"),
-            Likes = node.GetNumber<long>("diggCount"),
-            Comments = node.GetNumber<long>("commentCount"),
-            Shares = node.GetNumber<long>("shareCount"),
-            Favorites = node.GetNumber<long>("collectCount"),
-            Reposts = node.GetNumber<long>("repostCount")
+            Views       = node.GetNumber<long>("playCount"),
+            Likes       = node.GetNumber<long>("diggCount"),
+            Comments    = node.GetNumber<long>("commentCount"),
+            Shares      = node.GetNumber<long>("shareCount"),
+            Favorites   = node.GetNumber<long>("collectCount"),
+            Reposts     = node.GetNumber<long>("repostCount")
         };
     }
 
@@ -200,11 +201,11 @@ private static Bitrate[] ParseBitrates(JsonNode node)
             .OfType<JsonNode>()
             .Select(bitrateNode => new Bitrate
             {
-                Value = bitrateNode.GetNumber<int>("Bitrate"),
-                FPS = bitrateNode.GetNumber<int>("BitrateFPS"),
-                Format = ParseBitrateFormat(bitrateNode),
-                RawFormat = bitrateNode.GetString("Format"),
-                CodecType = bitrateNode.GetString("CodecType")
+                Value       = bitrateNode.GetNumber<int>("Bitrate"),
+                FPS         = bitrateNode.GetNumber<int>("BitrateFPS"),
+                Format      = ParseBitrateFormat(bitrateNode),
+                RawFormat   = bitrateNode.GetString("Format"),
+                CodecType   = bitrateNode.GetString("CodecType")
             })];
     }
 
@@ -226,16 +227,59 @@ private static VideoLanguage ParseVideoLanguage(JsonNode node)
         return new VideoLanguage
         {
             PrimaryLanguage = node.GetStringOrEmpty("textLanguage"),
-            IsTranslatable = node.GetBool("textTranslatable")
+            IsTranslatable  = node.GetBool("textTranslatable")
         };
     }
 
+    /// <summary>Maps the <c>cover</c> and <c>dynamicCover</c> fields to a <see cref="VideoCover"/>.</summary>
     private static VideoCover ParseVideoCover(JsonNode node)
     {
         return new VideoCover
         {
             AnimatedUrl = node.GetString("dynamicCover"),
-            StaticUrl = node.GetString("cover")
+            StaticUrl   = node.GetString("cover")
         };
     }
-}
\ No newline at end of file
+
+    /// <summary>Maps the <c>music</c> sub-tree to a <see cref="VideoMusic"/>.</summary>
+    private static VideoMusic ParseVideoMusic(JsonNode node)
+    {
+        return new VideoMusic
+        {
+            Id              = node.GetString("id"),
+            Title           = node.GetString("title"),
+            AuthorName      = node.GetString("authorName"),
+            AlbumName       = node.GetStringOrEmpty("album"),
+            Images          = ParseMusicImageVariants(node),
+            Duration        = ParseMediaDuration(node),
+            IsCopyrighted   = node.GetBool("isCopyrighted"),
+            IsOriginal      = node.GetBool("original"),
+            IsPrivate       = node.GetBool("private"),
+            PlayUrl         = node.GetString("playUrl"),
+        };
+    }
+
+    /// <summary>Extracts the music duration information, handling both precise and non-precise formats.</summary>
+    private static MediaDuration ParseMediaDuration(JsonNode node)
+    {
+        var seconds = node.GetNumber<int>("duration");
+        var preciseDurationNode = node["preciseDuration"];
+
+        return new MediaDuration
+        {
+            Seconds         = seconds,
+            PreciseSeconds  = preciseDurationNode?.GetOptionalNumber<double>("preciseDuration") ?? seconds
+        };
+    }
+
+    /// <summary>Extracts the three music cover URL variants (<c>Large</c>, <c>Medium</c>, <c>Thumb</c>) from the music node.</summary>
+    private static ProfileImageVariants ParseMusicImageVariants(JsonNode music)
+    {
+        return new ProfileImageVariants
+        {
+            Larger  = music.GetString("coverLarge"),
+            Medium  = music.GetString("coverMedium"),
+            Small   = music.GetString("coverThumb")
+        };
+    }
+}
diff --git a/TiktokExplode.NET.slnx b/TiktokExplode.NET.slnx
index c36b719..49db7b8 100644
--- a/TiktokExplode.NET.slnx
+++ b/TiktokExplode.NET.slnx
@@ -1,8 +1,9 @@
 <Solution>
-  <Project Path="TiktokExplode/TiktokExplode.csproj" />
-  <Project Path="TiktokExplode.Infrastructure/TiktokExplode.Infrastructure.csproj" />
-  <Project Path="TiktokExplode.Extensions.DependencyInjection/TiktokExplode.Extensions.DependencyInjection.csproj" />
+  <Project Path="../LiaProgramacion/LiaProgramacion/LiaProgramacion.csproj" />
   <Project Path="TiktokExplode.All/TiktokExplode.All.csproj" />
-  <Project Path="TiktokExplode.Tests/TiktokExplode.Tests.csproj" />
   <Project Path="TiktokExplode.Console/TiktokExplode.Console.csproj" />
+  <Project Path="TiktokExplode.Extensions.DependencyInjection/TiktokExplode.Extensions.DependencyInjection.csproj" />
+  <Project Path="TiktokExplode.Infrastructure/TiktokExplode.Infrastructure.csproj" />
+  <Project Path="TiktokExplode.Tests/TiktokExplode.Tests.csproj" />
+  <Project Path="TiktokExplode/TiktokExplode.csproj" />
 </Solution>
diff --git a/TiktokExplode.Tests/Infrastructure/Parsers/TikTokVideoParserTests.cs b/TiktokExplode.Tests/Infrastructure/Parsers/TikTokVideoParserTests.cs
index d5ccb25..08521d8 100644
--- a/TiktokExplode.Tests/Infrastructure/Parsers/TikTokVideoParserTests.cs
+++ b/TiktokExplode.Tests/Infrastructure/Parsers/TikTokVideoParserTests.cs
@@ -84,8 +84,23 @@ public async Task Should_MapAllFields_When_HtmlContainsValidVideoData()
         video.Stats.Reposts.Should().Be(50);
 
         // Duration
-        video.Duration.Seconds.Should().Be(15);
-        video.Duration.PreciseSeconds.Should().BeApproximately(15.123, precision: 0.001);
+        video.Duration.Seconds.Should().Be(12);
+        video.Duration.PreciseSeconds.Should().BeApproximately(12.345, precision: 0.001);
+
+        // Music
+        video.Music.Id.Should().Be("9000000000000000001");
+        video.Music.Title.Should().Be("Midnight Synth Loop");
+        video.Music.AuthorName.Should().Be("Nightwave Audio");
+        video.Music.AlbumName.Should().Be("Synthetic Fixtures");
+        video.Music.PlayUrl.Should().Be("https://cdn.example.com/music/audio.mp3");
+        video.Music.Images.Larger.Should().Be("https://cdn.example.com/music/cover_large.jpg");
+        video.Music.Images.Medium.Should().Be("https://cdn.example.com/music/cover_medium.jpg");
+        video.Music.Images.Small.Should().Be("https://cdn.example.com/music/cover_thumb.jpg");
+        video.Music.Duration.Seconds.Should().Be(15);
+        video.Music.Duration.PreciseSeconds.Should().Be(15);
+        video.Music.IsCopyrighted.Should().BeFalse();
+        video.Music.IsOriginal.Should().BeTrue();
+        video.Music.IsPrivate.Should().BeFalse();
 
         // Cover
         video.Cover.StaticUrl.Should().Be("https://cdn.example.com/cover_static.jpg");
diff --git a/TiktokExplode.Tests/Infrastructure/TikTokFixtures.cs b/TiktokExplode.Tests/Infrastructure/TikTokFixtures.cs
index cf1a38f..0f7a1f9 100644
--- a/TiktokExplode.Tests/Infrastructure/TikTokFixtures.cs
+++ b/TiktokExplode.Tests/Infrastructure/TikTokFixtures.cs
@@ -51,6 +51,8 @@ private static string Wrap(string json) =>
                     "videoQuality": "normal",
                     "width": 1080,
                     "height": 1920,
+                    "duration": 12,
+                    "preciseDuration": 12.345,
                     "cover": "https://cdn.example.com/cover_static.jpg",
                     "dynamicCover": "https://cdn.example.com/cover_animated.webp",
                     "playAddr": "https://cdn.example.com/play/video.mp4",
@@ -66,10 +68,18 @@ private static string Wrap(string json) =>
                     ]
                   },
                   "music": {
+                    "id": "9000000000000000001",
+                    "title": "Midnight Synth Loop",
+                    "playUrl": "https://cdn.example.com/music/audio.mp3",
+                    "coverThumb": "https://cdn.example.com/music/cover_thumb.jpg",
+                    "coverMedium": "https://cdn.example.com/music/cover_medium.jpg",
+                    "coverLarge": "https://cdn.example.com/music/cover_large.jpg",
+                    "authorName": "Nightwave Audio",
+                    "album": "Synthetic Fixtures",
+                    "original": true,
+                    "private": false,
                     "duration": 15,
-                    "preciseDuration": {
-                      "preciseDuration": 15.123
-                    }
+                    "isCopyrighted": false
                   },
                   "statsV2": {
                     "playCount": "100000",
diff --git a/TiktokExplode/Domain/Entities/Author.cs b/TiktokExplode/Domain/Entities/Author.cs
index 1b39847..f7b9872 100644
--- a/TiktokExplode/Domain/Entities/Author.cs
+++ b/TiktokExplode/Domain/Entities/Author.cs
@@ -34,8 +34,8 @@ public sealed class Author
     /// </summary>
     public bool IsPrivate { get; init; }
 
-    /// <summary>The date and time (UTC) when the account was created.</summary>
-    public DateTimeOffset CreatedAt { get; init; }
+    /// <summary>The date and time (UTC) when the account was created, if available.</summary>
+    public DateTimeOffset? CreatedAt { get; init; }
 
     /// <summary>Avatar image URLs in multiple resolutions.</summary>
     public ProfileImageVariants Avatar { get; init; } = new();
diff --git a/TiktokExplode/Domain/Entities/Video.cs b/TiktokExplode/Domain/Entities/Video.cs
index 61efa5f..ab9bd52 100644
--- a/TiktokExplode/Domain/Entities/Video.cs
+++ b/TiktokExplode/Domain/Entities/Video.cs
@@ -37,4 +37,9 @@ public sealed class Video
 
     /// <summary>Cover thumbnail URLs for this video — static frame and animated (looping) preview.</summary>
     public VideoCover Cover { get; init; } = new();
+
+    /// <summary>
+    /// The music or sound associated with the video, including track metadata and artwork.
+    /// </summary>
+    public VideoMusic Music { get; init; } = new();
 }
diff --git a/TiktokExplode/Domain/ValueObjects/Videos/MediaDuration.cs b/TiktokExplode/Domain/ValueObjects/Videos/MediaDuration.cs
new file mode 100644
index 0000000..421f550
--- /dev/null
+++ b/TiktokExplode/Domain/ValueObjects/Videos/MediaDuration.cs
@@ -0,0 +1,19 @@
+namespace TiktokExplode.Domain.ValueObjects.Videos;
+
+/// <summary>
+/// Represents the duration of a TikTok media resource, including a whole-second value
+/// and a precise fractional value when TikTok provides one.
+/// </summary>
+public readonly record struct MediaDuration
+{
+    /// <summary>
+    /// Gets the duration in whole seconds.
+    /// </summary>
+    public int Seconds { get; init; }
+
+    /// <summary>
+    /// Gets the duration in seconds, including fractional precision when TikTok provides it;
+    /// otherwise the same value as <see cref="Seconds"/>.
+    /// </summary>
+    public double PreciseSeconds { get; init; }
+}
diff --git a/TiktokExplode/Domain/ValueObjects/Videos/VideoDuration.cs b/TiktokExplode/Domain/ValueObjects/Videos/VideoDuration.cs
index 4fd7659..348e624 100644
--- a/TiktokExplode/Domain/ValueObjects/Videos/VideoDuration.cs
+++ b/TiktokExplode/Domain/ValueObjects/Videos/VideoDuration.cs
@@ -9,8 +9,8 @@ public readonly record struct VideoDuration
     public int Seconds { get; init; }
 
     /// <summary>
-    /// Precise playback duration in seconds as a fractional value (e.g. <c>15.48</c>).
-    /// Sourced from the <c>music.preciseDuration.preciseDuration</c> field in TikTok's JSON.
+    /// Precise playback duration in seconds when TikTok provides fractional precision;
+    /// otherwise the same value as <see cref="Seconds"/>.
     /// </summary>
     public double PreciseSeconds { get; init; }
 }
diff --git a/TiktokExplode/Domain/ValueObjects/Videos/VideoMusic.cs b/TiktokExplode/Domain/ValueObjects/Videos/VideoMusic.cs
new file mode 100644
index 0000000..69a8119
--- /dev/null
+++ b/TiktokExplode/Domain/ValueObjects/Videos/VideoMusic.cs
@@ -0,0 +1,48 @@
+using TiktokExplode.Domain.ValueObjects.Authors;
+
+namespace TiktokExplode.Domain.ValueObjects.Videos;
+
+/// <summary>
+/// Represents the music or sound associated with a TikTok video.
+/// </summary>
+public sealed class VideoMusic
+{
+    /// <summary>The unique TikTok-assigned identifier for the music or sound.</summary>
+    public string Id { get; init; } = string.Empty;
+
+    /// <summary>The album name associated with the music, if available.</summary>
+    public string AlbumName { get; init; } = string.Empty;
+
+    /// <summary>The title of the music or original sound.</summary>
+    public string Title { get; init; } = string.Empty;
+
+    /// <summary>The display name of the music author or original sound creator.</summary>
+    public string AuthorName { get; init; } = string.Empty;
+
+    /// <summary>Image URLs associated with the music in multiple resolutions.</summary>
+    public ProfileImageVariants Images { get; init; } = new();
+
+    /// <summary>The duration of the associated music or sound.</summary>
+    public MediaDuration Duration { get; init; }
+
+    /// <summary>
+    /// <see langword="true"/> if TikTok marks the music as copyrighted;
+    /// otherwise <see langword="false"/>.
+    /// </summary>
+    public bool IsCopyrighted { get; init; }
+
+    /// <summary>
+    /// <see langword="true"/> if this is an original sound;
+    /// otherwise <see langword="false"/>.
+    /// </summary>
+    public bool IsOriginal { get; init; }
+
+    /// <summary>
+    /// <see langword="true"/> if the music is private or unavailable;
+    /// otherwise <see langword="false"/>.
+    /// </summary>
+    public bool IsPrivate { get; init; }
+
+    /// <summary>CDN URL used to play the music or sound audio, if available.</summary>
+    public string PlayUrl { get; init; } = string.Empty;
+}
diff --git a/TiktokExplode/TiktokExplode.csproj b/TiktokExplode/TiktokExplode.csproj
index 293199c..d3e4735 100644
--- a/TiktokExplode/TiktokExplode.csproj
+++ b/TiktokExplode/TiktokExplode.csproj
@@ -25,8 +25,8 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <None Include="..\README.md" Pack="true" PackagePath="\"/>
-    <None Include="..\assets\icon.png" Pack="true" PackagePath="\"/>
+    <None Include="..\README.md" Pack="true" PackagePath="\" />
+    <None Include="..\assets\icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
 </Project>

From 5be85782aa7b92667efac3da7fec425d58550397 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Mon, 8 Jun 2026 16:45:58 -0500
Subject: [PATCH 07/18] Validate download URLs and handle optional fields

Added validation in `TiktokClient` and `TiktokSearchClient` to ensure download URLs are not null or empty, throwing `TiktokException` when invalid. Introduced `GetOptionalString` in `JsonNodeExtensions` to handle optional JSON fields. Updated `TiktokVideoParser` to handle missing `bitrateInfo` and use safer methods for parsing optional fields. Documented potential exceptions in `IDownloadClient`. Modified `Bitrate` structure to support nullable `FPS` and `RawFormat`, reflecting partial metadata from TikTok.
---
 .../Clients/TiktokClient.cs                   |  6 ++++++
 .../Clients/TiktokSearchClient.cs             |  7 +++++++
 .../Common/JsonNodeExtensions.cs              | 21 +++++++++++++++++++
 .../Parsers/TikTokVideoParser.cs              | 16 +++++++-------
 .../Domain/Abstractions/IDownloadClient.cs    |  3 +++
 .../Domain/ValueObjects/Videos/Bitrate.cs     | 13 +++++++-----
 6 files changed, 53 insertions(+), 13 deletions(-)

diff --git a/TiktokExplode.Infrastructure/Clients/TiktokClient.cs b/TiktokExplode.Infrastructure/Clients/TiktokClient.cs
index fb113b5..0a80ec5 100644
--- a/TiktokExplode.Infrastructure/Clients/TiktokClient.cs
+++ b/TiktokExplode.Infrastructure/Clients/TiktokClient.cs
@@ -73,12 +73,18 @@ internal Task<StreamInfo> DownloadCoreAsync(
     /// <inheritdoc/>
     public async Task<StreamInfo> DownloadAsync(Video video, CancellationToken cancellationToken = default)
     {
+        if(string.IsNullOrEmpty(video.Info.DownloadLinks.OriginalUrl))
+            throw new TiktokException("Video does not contain a valid original download URL.");
+
         return await DownloadCoreAsync(video.Info.DownloadLinks.OriginalUrl, cancellationToken);
     }
 
     /// <inheritdoc/>
     public async Task<StreamInfo> DownloadWatermarkedAsync(Video video, CancellationToken cancellationToken = default)
     {
+        if (string.IsNullOrEmpty(video.Info.DownloadLinks.WatermarkedUrl))
+            throw new TiktokException("Video does not contain a valid watermarked download URL.");
+
         return await DownloadCoreAsync(video.Info.DownloadLinks.WatermarkedUrl, cancellationToken);
     }
 
diff --git a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
index 06e68cb..cd75a0b 100644
--- a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
+++ b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
@@ -1,6 +1,7 @@
 using System.Runtime.CompilerServices;
 using TiktokExplode.Domain.Abstractions;
 using TiktokExplode.Domain.Entities;
+using TiktokExplode.Domain.Exceptions;
 using TiktokExplode.Domain.ValueObjects;
 using TiktokExplode.Infrastructure.Fetchers.Search;
 using TiktokExplode.Infrastructure.Http;
@@ -39,12 +40,18 @@ public async IAsyncEnumerable<Video> SearchAsync(
     /// <inheritdoc/>
     public async Task<StreamInfo> DownloadAsync(Video video, CancellationToken cancellationToken = default)
     {
+        if(string.IsNullOrWhiteSpace(video.Info.DownloadLinks.OriginalUrl))
+            throw new TiktokException("Original download URL is not available for this video.");
+
         return await DownloadCoreAsync(video.Info.DownloadLinks.OriginalUrl, cancellationToken);
     }
 
     /// <inheritdoc/>
     public async Task<StreamInfo> DownloadWatermarkedAsync(Video video, CancellationToken cancellationToken = default)
     {
+        if (string.IsNullOrWhiteSpace(video.Info.DownloadLinks.WatermarkedUrl))
+            throw new TiktokException("Watermarked download URL is not available for this video.");
+
         return await DownloadCoreAsync(video.Info.DownloadLinks.WatermarkedUrl, cancellationToken);
     }
 
diff --git a/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs b/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs
index c9ecfcf..1f6b83c 100644
--- a/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs
+++ b/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs
@@ -27,6 +27,27 @@ public static string GetString(this JsonNode node, string field)
         return value.GetValue<string>();
     }
 
+    /// <summary>
+    /// Returns the string value of <paramref name="field"/> in <paramref name="node"/>,
+    /// or <see langword="null"/> if the field is absent.
+    /// </summary>
+    /// <param name="node"> The <see cref="JsonNode"/> to read from.</param>
+    /// <param name="field">The name of the field to read.</param>
+    /// <returns>The string value of the field, or <see langword="null"/> if absent.</returns>
+    /// <exception cref="TiktokParsingException">Thrown if the field is present but not a JSON string.</exception>
+    public static string? GetOptionalString(this JsonNode node, string field)
+    {
+        var value = node[field];
+
+        if (value is null)
+            return null;
+
+        if (value.GetValueKind() != JsonValueKind.String)
+            throw new TiktokParsingException($"Field '{field}' has an unexpected type.");
+
+        return value.GetValue<string>();
+    }
+
     /// <summary>
     /// Returns the string value of <paramref name="field"/> in <paramref name="node"/>,
     /// or <see cref="string.Empty"/> if the field is absent or not a JSON string.
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
index 5cabb86..4316ff7 100644
--- a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
@@ -155,8 +155,7 @@ private static ProfileImageVariants ParseProfileImageVariants(JsonNode author)
     /// <summary>Maps the <c>video</c> sub-tree to a <see cref="VideoInfo"/>.</summary>
     private static VideoInfo ParseVideoInfo(JsonNode node)
     {
-        var bitrateInfoNode = node["bitrateInfo"]
-            ?? throw new TiktokParsingException("Video bitrate information not found in the JSON content.");
+        var bitrateInfoNode = node["bitrateInfo"];
 
         return new VideoInfo
         {
@@ -164,7 +163,7 @@ private static VideoInfo ParseVideoInfo(JsonNode node)
             VideoQuality    = node.GetString("videoQuality"),
             Width           = node.GetNumber<int>("width"),
             Height          = node.GetNumber<int>("height"),
-            Bitrates        = ParseBitrates(bitrateInfoNode),
+            Bitrates        = bitrateInfoNode is null ? [] : ParseBitrates(bitrateInfoNode),
             DownloadLinks   = ParseDownloadLinks(node),
         };
     }
@@ -174,8 +173,8 @@ private static VideoDownloadLinks ParseDownloadLinks(JsonNode node)
     {
         return new VideoDownloadLinks
         {
-            OriginalUrl         = node.GetString("playAddr"),
-            WatermarkedUrl      = node.GetString("downloadAddr"),
+            OriginalUrl         = node.GetStringOrEmpty("playAddr"),
+            WatermarkedUrl      = node.GetStringOrEmpty("downloadAddr"),
             OriginalSizeInBytes = node.GetNumber<long>("size")
         };
     }
@@ -202,9 +201,9 @@ private static Bitrate[] ParseBitrates(JsonNode node)
             .Select(bitrateNode => new Bitrate
             {
                 Value       = bitrateNode.GetNumber<int>("Bitrate"),
-                FPS         = bitrateNode.GetNumber<int>("BitrateFPS"),
+                FPS         = bitrateNode.GetOptionalNumber<int>("BitrateFPS"),
                 Format      = ParseBitrateFormat(bitrateNode),
-                RawFormat   = bitrateNode.GetString("Format"),
+                RawFormat   = bitrateNode.GetOptionalString("Format"),
                 CodecType   = bitrateNode.GetString("CodecType")
             })];
     }
@@ -215,7 +214,8 @@ private static Bitrate[] ParseBitrates(JsonNode node)
     /// </summary>
     private static BitrateFormat ParseBitrateFormat(JsonNode bitrateNode)
     {
-        var raw = bitrateNode.GetString("Format");
+        var raw = bitrateNode.GetOptionalString("Format");
+
         return Enum.TryParse<BitrateFormat>(raw, ignoreCase: true, out var format)
             ? format
             : BitrateFormat.Unknown;
diff --git a/TiktokExplode/Domain/Abstractions/IDownloadClient.cs b/TiktokExplode/Domain/Abstractions/IDownloadClient.cs
index 287818c..b9107c7 100644
--- a/TiktokExplode/Domain/Abstractions/IDownloadClient.cs
+++ b/TiktokExplode/Domain/Abstractions/IDownloadClient.cs
@@ -18,6 +18,9 @@ public interface IDownloadClient : IAsyncDisposable
     /// A <see cref="StreamInfo"/> containing the open video stream and its exact size in bytes
     /// as reported by the CDN <c>Content-Length</c> header.
     /// </returns>
+    /// <exception cref="Exceptions.TiktokException">
+    /// Thrown if the video does not contain a valid download URL.
+    /// </exception>
     Task<StreamInfo> DownloadAsync(Video video, CancellationToken cancellationToken = default);
 
     /// <summary>
diff --git a/TiktokExplode/Domain/ValueObjects/Videos/Bitrate.cs b/TiktokExplode/Domain/ValueObjects/Videos/Bitrate.cs
index 348a90d..d2f79bc 100644
--- a/TiktokExplode/Domain/ValueObjects/Videos/Bitrate.cs
+++ b/TiktokExplode/Domain/ValueObjects/Videos/Bitrate.cs
@@ -4,24 +4,27 @@ namespace TiktokExplode.Domain.ValueObjects.Videos;
 
 /// <summary>
 /// Describes a single encoding variant available for a TikTok video.
-/// Each video typically has multiple bitrate entries at different quality levels.
+/// TikTok may return partial bitrate metadata depending on the source endpoint.
 /// </summary>
 public readonly record struct Bitrate
 {
     /// <summary>The bitrate of this encoding variant in bits per second.</summary>
     public int Value { get; init; }
 
-    /// <summary>The frames-per-second rate of this encoding variant.</summary>
-    public int FPS { get; init; }
+    /// <summary>
+    /// The frames-per-second rate of this encoding variant, if TikTok provides it.
+    /// </summary>
+    public int? FPS { get; init; }
 
     /// <summary>The parsed container format of this encoding variant.</summary>
     public BitrateFormat Format { get; init; }
 
     /// <summary>
-    /// The raw format string as returned by TikTok's API (e.g. <c>"mp4"</c>, <c>"mp3"</c>).
+    /// The raw format string as returned by TikTok's API, if available
+    /// (e.g. <c>"mp4"</c>, <c>"mp3"</c>).
     /// Use this when <see cref="Format"/> returns <see cref="BitrateFormat.Unknown"/>.
     /// </summary>
-    public string RawFormat { get; init; }
+    public string? RawFormat { get; init; }
 
     /// <summary>The codec type identifier string (e.g. <c>"h264"</c>).</summary>
     public string CodecType { get; init; }

From 050ed82de3f817db4e90f756a3f704f554404909 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Wed, 10 Jun 2026 00:17:13 -0500
Subject: [PATCH 08/18] Add support for TikTok carousels in search results

Refactor the `Video` model to inherit from a new `Media` base class, enabling shared properties for both videos and carousels. Introduce the `Carousel` model and supporting value objects (`CarouselPost`, `CarouselImage`) to handle slideshow posts with full metadata.

Update `TiktokSearchClient` to return `IAsyncEnumerable<Media>` instead of `Video`, allowing the processing of both media types. Modify `TiktokSearchParser` to differentiate between videos and carousels using pattern matching.

Rename and generalize value objects (`VideoStats`, `VideoLanguage`, etc.) to `MediaStats`, `MediaLanguage`, and similar, for broader applicability. Remove obsolete video-specific classes.

Update documentation to reflect API changes, including examples for carousels and a new section on search pagination limitations. Reorganize project structure to align with the new class hierarchy.

Enhance `TiktokBrowser` to handle signed URLs and preserve parameters for carousel data. Add new exceptions and validations for JSON parsing of carousels.
---
 README.md                                     | 89 ++++++++++++++-----
 .../Browser/TikTokBrowser.cs                  | 10 ---
 .../Clients/TiktokSearchClient.cs             |  3 +-
 .../Parsers/TikTokSearchParser.cs             | 80 ++++++++++++++++-
 .../Parsers/TikTokVideoParser.cs              | 29 +++---
 .../Domain/Abstractions/ISearchClient.cs      |  8 +-
 TiktokExplode/Domain/Entities/Carousel.cs     |  8 ++
 TiktokExplode/Domain/Entities/Media.cs        | 40 +++++++++
 TiktokExplode/Domain/Entities/Video.cs        | 32 +------
 .../ValueObjects/Carousels/CarouselImage.cs   |  8 ++
 .../ValueObjects/Carousels/CarouselPost.cs    |  8 ++
 .../VideoCover.cs => Media/MediaCover.cs}     |  6 +-
 .../{Videos => Media}/MediaDuration.cs        |  2 +-
 .../MediaLanguage.cs}                         | 10 +--
 .../VideoMusic.cs => Media/MediaMusic.cs}     |  6 +-
 .../Domain/ValueObjects/Media/MediaStats.cs   | 25 ++++++
 .../Domain/ValueObjects/Videos/VideoStats.cs  | 25 ------
 17 files changed, 270 insertions(+), 119 deletions(-)
 create mode 100644 TiktokExplode/Domain/Entities/Carousel.cs
 create mode 100644 TiktokExplode/Domain/Entities/Media.cs
 create mode 100644 TiktokExplode/Domain/ValueObjects/Carousels/CarouselImage.cs
 create mode 100644 TiktokExplode/Domain/ValueObjects/Carousels/CarouselPost.cs
 rename TiktokExplode/Domain/ValueObjects/{Videos/VideoCover.cs => Media/MediaCover.cs} (87%)
 rename TiktokExplode/Domain/ValueObjects/{Videos => Media}/MediaDuration.cs (91%)
 rename TiktokExplode/Domain/ValueObjects/{Videos/VideoLanguage.cs => Media/MediaLanguage.cs} (63%)
 rename TiktokExplode/Domain/ValueObjects/{Videos/VideoMusic.cs => Media/MediaMusic.cs} (91%)
 create mode 100644 TiktokExplode/Domain/ValueObjects/Media/MediaStats.cs
 delete mode 100644 TiktokExplode/Domain/ValueObjects/Videos/VideoStats.cs

diff --git a/README.md b/README.md
index b4e88fe..46d00a3 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,8 @@ The library follows **Clean Architecture**: the domain layer (`TiktokExplode`) h
 - Fetch full video metadata: author, stats, duration, language, location, bitrates, and more
 - Download videos without watermark or with watermark
 - Download the static cover image (JPEG) or the animated cover (WebP)
-- **Search videos by keyword** — streams results lazily via `IAsyncEnumerable<Video>`
+- **Search TikTok by keyword** — streams results lazily via `IAsyncEnumerable<Media>` (videos and carousels)
+- **Carousel/slideshow support** — `Carousel` entity with full image collection metadata
 - Progress reporting during download via `IProgress<double>`
 - Automatic WAF/bot-detection retry with configurable backoff
 - **Strategy pattern** — choose between Playwright (reliable) or HTTP-only (lightweight) page fetching
@@ -128,29 +129,39 @@ await using var client = new TiktokClient(myFetcher, new TikTokOptions());
 
 ### `TiktokSearchClient`
 
-`TiktokSearchClient` searches TikTok by keyword and streams results as `Video` objects using `IAsyncEnumerable<Video>`. It **requires Playwright** because TikTok's search API signs requests with dynamic tokens that can only be generated by a real browser session.
+`TiktokSearchClient` searches TikTok by keyword and streams results as `Media` objects (either `Video` or `Carousel`) using `IAsyncEnumerable<Media>`. It **requires Playwright** because TikTok's search API signs requests with dynamic tokens that can only be generated by a real browser session.
 
 ```csharp
 await using var client = TiktokSearchClient.CreateWithBrowser();
 
-await foreach (var video in client.SearchAsync("funny cats"))
+await foreach (var media in client.SearchAsync("funny cats"))
 {
-    Console.WriteLine($"{video.Author.UniqueId}: {video.Description}");
+    Console.WriteLine($"{media.Author.UniqueId}: {media.Description}");
 
-    // You can also download directly from ISearchClient
-    await client.DownloadAsync(video, $"{video.Id}.mp4");
+    if (media is Video video)
+    {
+        // Standard video post
+        await client.DownloadAsync(video, $"{video.Id}.mp4");
+    }
+    else if (media is Carousel carousel)
+    {
+        // Slideshow post — contains a collection of images
+        Console.WriteLine($"Carousel with {carousel.Post.Images.Count} images");
+    }
 }
 ```
 
 > **Note:** `TiktokSearchClient` implements `ISearchClient`, which extends `IDownloadClient`. This means all extension methods (`DownloadAsync(filePath)`, `DownloadWatermarkedAsync(filePath)`, `DownloadImageAsync`, `DownloadAnimatedImageAsync`) are available directly on the search client — no need for a separate `TiktokClient` instance.
 
+> **Search scope:** The current implementation returns results from the **first page** of TikTok's search API (~10–20 results). Multi-page pagination is under active investigation — see the [Known Limitations](#known-limitations) section.
+
 #### Methods
 
-| Method                                               | Returns                   | Description                                                           |
-| ---------------------------------------------------- | ------------------------- | --------------------------------------------------------------------- |
-| `SearchAsync(string keyword, CancellationToken)`     | `IAsyncEnumerable<Video>` | Streams video results for the given keyword, paginating automatically |
-| `DownloadAsync(Video, CancellationToken)`            | `StreamInfo`              | Downloads video without watermark                                     |
-| `DownloadWatermarkedAsync(Video, CancellationToken)` | `StreamInfo`              | Downloads video with watermark                                        |
+| Method                                               | Returns                   | Description                                                     |
+| ---------------------------------------------------- | ------------------------- | --------------------------------------------------------------- |
+| `SearchAsync(string keyword, CancellationToken)`     | `IAsyncEnumerable<Media>` | Streams media results (videos and carousels) for the keyword    |
+| `DownloadAsync(Video, CancellationToken)`            | `StreamInfo`              | Downloads video without watermark                               |
+| `DownloadWatermarkedAsync(Video, CancellationToken)` | `StreamInfo`              | Downloads video with watermark                                  |
 
 `TiktokSearchClient` implements `IAsyncDisposable` — always use `await using`.
 
@@ -214,21 +225,37 @@ Returned by `DownloadAsync` and `DownloadWatermarkedAsync`. Implements `IAsyncDi
 
 ---
 
-### `Video` model
+### `Media` model (base)
+
+All search results are `Media` objects. Use pattern matching (`is Video`, `is Carousel`) to access type-specific properties.
 
 | Property      | Type             | Description                                        |
 | ------------- | ---------------- | -------------------------------------------------- |
-| `Id`          | `string`         | TikTok video ID                                    |
+| `Id`          | `string`         | TikTok post ID                                     |
 | `Description` | `string`         | Caption / description                              |
 | `Author`      | `Author`         | Author entity                                      |
-| `Duration`    | `VideoDuration`  | Duration in seconds and precise seconds            |
-| `Stats`       | `VideoStats`     | Views, likes, comments, shares, favorites, reposts |
-| `Info`        | `VideoInfo`      | Technical info, bitrates, and download URLs        |
-| `Language`    | `VideoLanguage`  | Detected content language                          |
+| `Stats`       | `MediaStats`     | Views, likes, comments, shares, favorites, reposts |
+| `Language`    | `MediaLanguage`  | Detected content language                          |
 | `Location`    | `string`         | Location tag (if any)                              |
-| `Cover`       | `VideoCover`     | Static (JPEG) and animated (WebP) cover image URLs |
+| `Cover`       | `MediaCover`     | Static (JPEG) and animated (WebP) cover image URLs |
+| `Music`       | `MediaMusic`     | Track metadata and artwork                         |
 | `CreatedAt`   | `DateTimeOffset` | Upload date                                        |
 
+### `Video : Media` model
+
+| Property   | Type            | Description                                 |
+| ---------- | --------------- | ------------------------------------------- |
+| `Info`     | `VideoInfo`     | Technical info, bitrates, and download URLs |
+| `Duration` | `VideoDuration` | Duration in seconds and precise seconds     |
+
+### `Carousel : Media` model
+
+Represents a TikTok slideshow post (multiple images + audio).
+
+| Property | Type          | Description                             |
+| -------- | ------------- | --------------------------------------- |
+| `Post`   | `CarouselPost` | Collection of images with their URLs   |
+
 ### `Author` model
 
 | Property      | Type                   | Description                                                |
@@ -325,9 +352,13 @@ catch (TiktokException ex)
 ```
 TiktokExplode/                # Domain — zero external dependencies
   Domain/
-    Entities/                 # Video, Author
-    ValueObjects/             # VideoInfo, StreamInfo, VideoStats, VideoDuration, etc.
-    Abstractions/             # IVideoClient
+    Entities/                 # Media (abstract), Video, Carousel, Author
+    ValueObjects/
+      Media/                  # MediaStats, MediaLanguage, MediaCover, MediaMusic, MediaDuration
+      Videos/                 # VideoInfo, VideoDuration, VideoDownloadLinks, Bitrate
+      Carousels/              # CarouselPost and related types
+      Authors/                # AuthorStats, ProfileImageVariants
+    Abstractions/             # IVideoClient, ISearchClient, IDownloadClient
     Exceptions/               # TiktokException hierarchy
     Utilities/                # URL validation
 
@@ -348,6 +379,22 @@ TiktokExplode.Extensions.DependencyInjection/  # AddTiktokExplode() for Microsof
 
 ---
 
+## Known Limitations
+
+### Search pagination
+
+`SearchAsync` currently returns only the **first page** of results (~10–20 items depending on TikTok's response).
+
+Multi-page pagination requires triggering TikTok's internal IntersectionObserver inside the live browser session. Every new page request is signed with a fresh **X-Bogus** token that covers all query parameters — modifying `cursor` or any other param after the fact invalidates the signature and returns an empty response. Approaches tried so far:
+
+- `Mouse.WheelAsync` — dispatches a `WheelEvent` but does not guarantee `scrollTop` changes on TikTok's custom scroll container.
+- `window.scrollTo()` / `document.scrollingElement.scrollTop = scrollHeight` — effective only if the scroll container is `<html>` or `<body>`; TikTok uses an internal `<div>`.
+- `route.FetchAsync()` — bypasses the browser's HTTP/TLS stack; TikTok detects the different fingerprint and returns empty body.
+
+This is a planned feature. Contributions welcome.
+
+---
+
 ## Acknowledgements
 
 This library was heavily inspired by [**YoutubeExplode**](https://github.com/Tyrrrz/YoutubeExplode) by [Tyrrrz](https://github.com/Tyrrrz). His work showed me how a well-designed, clean .NET library for a media platform should look and feel. Without that reference, TiktokExplode would not exist. Thank you.
diff --git a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
index 740882a..7f2f835 100644
--- a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
+++ b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
@@ -135,14 +135,10 @@ public async Task<string> GetSearchPageAsync(string keyword)
 
         try
         {
-            // Set up listener BEFORE navigating so we don't miss the response.
-            // No trailing slash — the actual URL may or may not have one.
             var responseTask = page.WaitForResponseAsync(
                r => r.Url.Contains("/api/search/general/full"),
                new PageWaitForResponseOptions { Timeout = _options.PageTimeoutMs });
 
-            // Use Load (not DOMContentLoaded): TikTok is a React SPA — the API call
-            // fires only after JS initialises, which happens after DOMContentLoaded.
             var pageResponse = await page.GotoAsync(
                 $"https://www.tiktok.com/search?q={Uri.EscapeDataString(keyword)}", new PageGotoOptions
                 {
@@ -171,12 +167,8 @@ public async Task<string> GetSearchPageAsync(string keyword)
             if (!response.Ok)
                 throw new TiktokParsingException($"Failed to load search results. Status: {response.Status}");
 
-            // Save the signed URL (X-Bogus included) for use in subsequent pages.
             _lastSearchApiUrl = response.Url;
 
-            // Do NOT use response.TextAsync() — Playwright returns "" for already-consumed
-            // streaming bodies. Instead re-fetch from JS with credentials:include so the browser
-            // sends cookies + the original signature params (X-Bogus) that TikTok requires.
             var data = await page.EvaluateAsync<string>("""
                 async (url) => {
                     const resp = await fetch(url, {
@@ -204,8 +196,6 @@ public async Task<string> GetSearchNextPageAsync(
         if (_lastSearchApiUrl is null)
             throw new TiktokParsingException("No signed search API URL available. Call GetSearchPageAsync first.");
 
-        // Reuse the signed URL from the first page (preserves X-Bogus and other signature params).
-        // Only update keyword, cursor, and offset in JS — the browser handles credentials via cookies.
         return await page.EvaluateAsync<string>("""
         async (args) => {
             const url = new URL(args.baseUrl);
diff --git a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
index cd75a0b..23fc11f 100644
--- a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
+++ b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
@@ -21,8 +21,9 @@ public sealed class TiktokSearchClient(
 
     /// <summary>Initializes a new <see cref="TiktokSearchClient"/> with default options.</summary>
     public TiktokSearchClient() : this(new PlaywrightSearchFetcher()) { }
+
     /// <inheritdoc/>
-    public async IAsyncEnumerable<Video> SearchAsync(
+    public async IAsyncEnumerable<Media> SearchAsync(
         string keyword,
         [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
index ef7df0c..f7d654a 100644
--- a/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
@@ -1,12 +1,14 @@
 using System.Text.Json.Nodes;
 using TiktokExplode.Domain.Entities;
 using TiktokExplode.Domain.Exceptions;
+using TiktokExplode.Domain.ValueObjects.Carousels;
+using TiktokExplode.Infrastructure.Common;
 
 namespace TiktokExplode.Infrastructure.Parsers;
 
 internal sealed class TiktokSearchParser
 {
-    internal static IEnumerable<Video> Parse(string jsonContent)
+    internal static IEnumerable<Media> Parse(string jsonContent)
     {
         var root = JsonNode.Parse(jsonContent)
             ?? throw new TiktokParsingException("Failed to parse search JSON.");
@@ -21,7 +23,81 @@ internal static IEnumerable<Video> Parse(string jsonContent)
             var item = entry["item"]
                 ?? throw new TiktokParsingException("'item' node not found in search entry.");
 
-            yield return TiktokVideoParser.ParseVideo(item);
+            var imagePost = item["imagePost"];
+
+            if(imagePost is null)
+            {
+                yield return TiktokVideoParser.ParseVideo(item);
+                continue;
+            }
+
+
+            yield return ParseCarousel(item, imagePost);
         }
     }
+
+    private static Carousel ParseCarousel(JsonNode node, JsonNode postNode)
+    {
+        var videoNode = node["video"]
+            ?? throw new TiktokParsingException("Video information not found in the JSON content.");
+
+        var musicNode = node["music"]
+            ?? throw new TiktokParsingException("Music information not found in the JSON content.");
+
+        var statsNode = node["statsV2"]
+            ?? throw new TiktokParsingException("Video stats not found in the JSON content.");
+
+        return new Carousel
+        {
+            Id          = node.GetString("id"),
+            Author      = TiktokVideoParser.ParseAuthor(node),
+            Stats       = TiktokVideoParser.ParseVideoStats(statsNode),
+            Music       = TiktokVideoParser.ParseVideoMusic(musicNode),
+            Post        = ParseCarouselPost(postNode),
+            Language    = TiktokVideoParser.ParseVideoLanguage(node),
+            Cover       = TiktokVideoParser.ParseVideoCover(videoNode),
+            Description = node.GetStringOrEmpty("desc"),
+            Location    = node.GetStringOrEmpty("locationCreated"),
+            CreatedAt   = DateTimeOffset.FromUnixTimeSeconds(node.GetNumber<long>("createTime")),
+        };
+    }
+
+    private static CarouselPost ParseCarouselPost(JsonNode node)
+    {
+        var coverNode = node["cover"]
+            ?? throw new TiktokParsingException("Carousel cover information not found in the JSON content.");
+
+        var imageNode = node["images"]
+            ?? throw new TiktokParsingException("Carousel images information not found in the JSON content.");
+
+        var images = imageNode.AsArray()
+            .OfType<JsonNode>()
+            .Select(ParseCarouselImage)
+            .ToList();
+
+        return new CarouselPost
+        {
+            Title       = node.GetString("title"),
+            Cover       = ParseCarouselImage(coverNode),
+            Images      = images
+        };
+    }
+
+    private static CarouselImage ParseCarouselImage(JsonNode node)
+    {
+        var imageUrlNode = node["imageURL"]
+            ?? throw new TiktokParsingException("Carousel cover URLs not found in the JSON content.");
+
+        var urls = imageUrlNode["urlList"]?.AsArray()
+            .OfType<JsonNode>()
+            .Select(urlNode => urlNode.GetValue<string>())
+            .ToList();
+
+        return new CarouselImage
+        {
+            Width   = node.GetNumber<uint>("imageWidth"),
+            Height  = node.GetNumber<uint>("imageHeight"),
+            Urls    = urls ?? []
+        };
+    }
 }
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
index 4316ff7..8aac4c8 100644
--- a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
@@ -5,6 +5,7 @@
 using TiktokExplode.Domain.Enums;
 using TiktokExplode.Domain.Exceptions;
 using TiktokExplode.Domain.ValueObjects.Authors;
+using TiktokExplode.Domain.ValueObjects.Media;
 using TiktokExplode.Domain.ValueObjects.Videos;
 using TiktokExplode.Infrastructure.Common;
 
@@ -105,7 +106,7 @@ private static VideoDuration ParseVideoDuration(JsonNode node)
     }
 
     /// <summary>Maps the <c>author</c> and <c>authorStatsV2</c> sub-trees to an <see cref="Author"/>.</summary>
-    private static Author ParseAuthor(JsonNode node)
+    internal static Author ParseAuthor(JsonNode node)
     {
         var author = node["author"]
             ?? throw new TiktokParsingException("Author information not found in the JSON content.");
@@ -179,10 +180,10 @@ private static VideoDownloadLinks ParseDownloadLinks(JsonNode node)
         };
     }
 
-    /// <summary>Maps the <c>statsV2</c> node to a <see cref="VideoStats"/>.</summary>
-    private static VideoStats ParseVideoStats(JsonNode node)
+    /// <summary>Maps the <c>statsV2</c> node to a <see cref="MediaStats"/>.</summary>
+    internal static MediaStats ParseVideoStats(JsonNode node)
     {
-        return new VideoStats
+        return new MediaStats
         {
             Views       = node.GetNumber<long>("playCount"),
             Likes       = node.GetNumber<long>("diggCount"),
@@ -221,30 +222,30 @@ private static BitrateFormat ParseBitrateFormat(JsonNode bitrateNode)
             : BitrateFormat.Unknown;
     }
 
-    /// <summary>Maps the <c>textLanguage</c> and <c>textTranslatable</c> fields to a <see cref="VideoLanguage"/>.</summary>
-    private static VideoLanguage ParseVideoLanguage(JsonNode node)
+    /// <summary>Maps the <c>textLanguage</c> and <c>textTranslatable</c> fields to a <see cref="MediaLanguage"/>.</summary>
+    internal static MediaLanguage ParseVideoLanguage(JsonNode node)
     {
-        return new VideoLanguage
+        return new MediaLanguage
         {
             PrimaryLanguage = node.GetStringOrEmpty("textLanguage"),
             IsTranslatable  = node.GetBool("textTranslatable")
         };
     }
 
-    /// <summary>Maps the <c>cover</c> and <c>dynamicCover</c> fields to a <see cref="VideoCover"/>.</summary>
-    private static VideoCover ParseVideoCover(JsonNode node)
+    /// <summary>Maps the <c>cover</c> and <c>dynamicCover</c> fields to a <see cref="MediaCover"/>.</summary>
+    internal static MediaCover ParseVideoCover(JsonNode node)
     {
-        return new VideoCover
+        return new MediaCover
         {
-            AnimatedUrl = node.GetString("dynamicCover"),
+            AnimatedUrl = node.GetStringOrEmpty("dynamicCover"),
             StaticUrl   = node.GetString("cover")
         };
     }
 
-    /// <summary>Maps the <c>music</c> sub-tree to a <see cref="VideoMusic"/>.</summary>
-    private static VideoMusic ParseVideoMusic(JsonNode node)
+    /// <summary>Maps the <c>music</c> sub-tree to a <see cref="MediaMusic"/>.</summary>
+    internal static MediaMusic ParseVideoMusic(JsonNode node)
     {
-        return new VideoMusic
+        return new MediaMusic
         {
             Id              = node.GetString("id"),
             Title           = node.GetString("title"),
diff --git a/TiktokExplode/Domain/Abstractions/ISearchClient.cs b/TiktokExplode/Domain/Abstractions/ISearchClient.cs
index 83226e0..7398241 100644
--- a/TiktokExplode/Domain/Abstractions/ISearchClient.cs
+++ b/TiktokExplode/Domain/Abstractions/ISearchClient.cs
@@ -3,20 +3,20 @@
 namespace TiktokExplode.Domain.Abstractions;
 
 /// <summary>
-/// Defines the contract for a TikTok search client that queries videos by keyword
+/// Defines the contract for a TikTok search client that queries media by keyword
 /// and can stream their content from TikTok's CDN.
 /// </summary>
 public interface ISearchClient : IDownloadClient
 {
     /// <summary>
-    /// Asynchronously streams <see cref="Video"/> results for the given <paramref name="keyword"/>,
+    /// Asynchronously streams <see cref="Media"/> results for the given <paramref name="keyword"/>,
     /// lazily fetching additional pages as the sequence is consumed.
     /// </summary>
     /// <param name="keyword">The search term to query on TikTok.</param>
     /// <param name="cancellationToken">Token to cancel the enumeration.</param>
     /// <returns>
-    /// An <see cref="IAsyncEnumerable{T}"/> of <see cref="Video"/> values
+    /// An <see cref="IAsyncEnumerable{T}"/> of <see cref="Media"/> values
     /// ordered by TikTok's default relevance ranking.
     /// </returns>
-    IAsyncEnumerable<Video> SearchAsync(string keyword, CancellationToken cancellationToken = default);
+    IAsyncEnumerable<Media> SearchAsync(string keyword, CancellationToken cancellationToken = default);
 }
\ No newline at end of file
diff --git a/TiktokExplode/Domain/Entities/Carousel.cs b/TiktokExplode/Domain/Entities/Carousel.cs
new file mode 100644
index 0000000..6375bea
--- /dev/null
+++ b/TiktokExplode/Domain/Entities/Carousel.cs
@@ -0,0 +1,8 @@
+using TiktokExplode.Domain.ValueObjects.Carousels;
+
+namespace TiktokExplode.Domain.Entities;
+
+public sealed class Carousel : Media
+{
+    public CarouselPost Post { get; init; }
+}
diff --git a/TiktokExplode/Domain/Entities/Media.cs b/TiktokExplode/Domain/Entities/Media.cs
new file mode 100644
index 0000000..4d7eb41
--- /dev/null
+++ b/TiktokExplode/Domain/Entities/Media.cs
@@ -0,0 +1,40 @@
+using TiktokExplode.Domain.ValueObjects.Media;
+
+namespace TiktokExplode.Domain.Entities;
+
+/// <summary>
+/// Base type for all TikTok media content, exposing metadata shared across videos
+/// and slideshow (carousel) posts.
+/// </summary>
+public abstract class Media
+{
+    /// <summary>The unique TikTok-assigned numeric identifier for this video.</summary>
+    public string Id { get; init; } = string.Empty;
+
+    /// <summary>The caption or description text of the video, as written by the author.</summary>
+    public string Description { get; init; } = string.Empty;
+
+    /// <summary>The author who posted the video.</summary>
+    public Author Author { get; init; } = new();
+
+    /// <summary>The detected primary language of the video's text content.</summary>
+    public MediaLanguage Language { get; init; } = new();
+
+    /// <summary>Engagement statistics for this video (views, likes, comments, etc.).</summary>
+    public MediaStats Stats { get; init; } = new();
+
+    /// <summary>The location tag associated with the video. Empty string if not set.</summary>
+    public string Location { get; init; } = string.Empty;
+
+    /// <summary>The date and time (UTC) when the video was published.</summary>
+    public DateTimeOffset CreatedAt { get; init; }
+
+    /// <summary>Cover thumbnail URLs for this video — static frame and animated (looping) preview.</summary>
+    public MediaCover Cover { get; init; } = new();
+
+    /// <summary>
+    /// The music or sound associated with the video, including track metadata and artwork.
+    /// </summary>
+    public MediaMusic Music { get; init; } = new();
+
+}
diff --git a/TiktokExplode/Domain/Entities/Video.cs b/TiktokExplode/Domain/Entities/Video.cs
index ab9bd52..59761a4 100644
--- a/TiktokExplode/Domain/Entities/Video.cs
+++ b/TiktokExplode/Domain/Entities/Video.cs
@@ -1,3 +1,4 @@
+using TiktokExplode.Domain.ValueObjects.Media;
 using TiktokExplode.Domain.ValueObjects.Videos;
 
 namespace TiktokExplode.Domain.Entities;
@@ -6,40 +7,11 @@ namespace TiktokExplode.Domain.Entities;
 /// Represents a TikTok video with all its associated metadata.
 /// This is the root entity returned by <c>IVideoClient.GetVideoAsync</c>.
 /// </summary>
-public sealed class Video
+public sealed class Video : Media
 {
-    /// <summary>The unique TikTok-assigned numeric identifier for this video.</summary>
-    public string Id { get; init; } = string.Empty;
-
-    /// <summary>The caption or description text of the video, as written by the author.</summary>
-    public string Description { get; init; } = string.Empty;
-
-    /// <summary>The author who posted the video.</summary>
-    public Author Author { get; init; } = new();
-
-    /// <summary>The detected primary language of the video's text content.</summary>
-    public VideoLanguage Language { get; init; } = new();
-
-    /// <summary>Engagement statistics for this video (views, likes, comments, etc.).</summary>
-    public VideoStats Stats { get; init; } = new();
-
     /// <summary>Technical information about the video (resolution, bitrates, download URLs).</summary>
     public VideoInfo Info { get; init; } = new();
 
-    /// <summary>The location tag associated with the video. Empty string if not set.</summary>
-    public string Location { get; init; } = string.Empty;
-
-    /// <summary>The date and time (UTC) when the video was published.</summary>
-    public DateTimeOffset CreatedAt { get; init; }
-
     /// <summary>The playback duration of the video.</summary>
     public VideoDuration Duration { get; init; }
-
-    /// <summary>Cover thumbnail URLs for this video — static frame and animated (looping) preview.</summary>
-    public VideoCover Cover { get; init; } = new();
-
-    /// <summary>
-    /// The music or sound associated with the video, including track metadata and artwork.
-    /// </summary>
-    public VideoMusic Music { get; init; } = new();
 }
diff --git a/TiktokExplode/Domain/ValueObjects/Carousels/CarouselImage.cs b/TiktokExplode/Domain/ValueObjects/Carousels/CarouselImage.cs
new file mode 100644
index 0000000..00501c7
--- /dev/null
+++ b/TiktokExplode/Domain/ValueObjects/Carousels/CarouselImage.cs
@@ -0,0 +1,8 @@
+namespace TiktokExplode.Domain.ValueObjects.Carousels;
+
+public sealed class CarouselImage
+{
+    public uint Width { get; init; }
+    public uint Height { get; init; }
+    public IReadOnlyList<string> Urls { get; init; } = [];
+}
diff --git a/TiktokExplode/Domain/ValueObjects/Carousels/CarouselPost.cs b/TiktokExplode/Domain/ValueObjects/Carousels/CarouselPost.cs
new file mode 100644
index 0000000..f66b504
--- /dev/null
+++ b/TiktokExplode/Domain/ValueObjects/Carousels/CarouselPost.cs
@@ -0,0 +1,8 @@
+namespace TiktokExplode.Domain.ValueObjects.Carousels;
+
+public sealed class CarouselPost
+{
+    public string Title { get; init; } = string.Empty;
+    public CarouselImage Cover { get; init; }
+    public IReadOnlyList<CarouselImage> Images { get; init; } = [];
+}
diff --git a/TiktokExplode/Domain/ValueObjects/Videos/VideoCover.cs b/TiktokExplode/Domain/ValueObjects/Media/MediaCover.cs
similarity index 87%
rename from TiktokExplode/Domain/ValueObjects/Videos/VideoCover.cs
rename to TiktokExplode/Domain/ValueObjects/Media/MediaCover.cs
index 689672f..d3e9238 100644
--- a/TiktokExplode/Domain/ValueObjects/Videos/VideoCover.cs
+++ b/TiktokExplode/Domain/ValueObjects/Media/MediaCover.cs
@@ -1,11 +1,11 @@
-namespace TiktokExplode.Domain.ValueObjects.Videos;
+namespace TiktokExplode.Domain.ValueObjects.Media;
 
 /// <summary>
-/// Represents the cover images for a video, including both static and animated versions.
+/// Represents the cover images for a media, including both static and animated versions.
 /// </summary>
 /// <remarks>The StaticUrl property holds the URL for the static cover image, while the AnimatedUrl property holds
 /// the URL for the animated cover image. Both properties are initialized to empty strings.</remarks>
-public sealed record VideoCover
+public sealed record MediaCover
 {
     /// <summary>
     /// Gets the URL for static resources used by the application.
diff --git a/TiktokExplode/Domain/ValueObjects/Videos/MediaDuration.cs b/TiktokExplode/Domain/ValueObjects/Media/MediaDuration.cs
similarity index 91%
rename from TiktokExplode/Domain/ValueObjects/Videos/MediaDuration.cs
rename to TiktokExplode/Domain/ValueObjects/Media/MediaDuration.cs
index 421f550..d18dc98 100644
--- a/TiktokExplode/Domain/ValueObjects/Videos/MediaDuration.cs
+++ b/TiktokExplode/Domain/ValueObjects/Media/MediaDuration.cs
@@ -1,4 +1,4 @@
-namespace TiktokExplode.Domain.ValueObjects.Videos;
+namespace TiktokExplode.Domain.ValueObjects.Media;
 
 /// <summary>
 /// Represents the duration of a TikTok media resource, including a whole-second value
diff --git a/TiktokExplode/Domain/ValueObjects/Videos/VideoLanguage.cs b/TiktokExplode/Domain/ValueObjects/Media/MediaLanguage.cs
similarity index 63%
rename from TiktokExplode/Domain/ValueObjects/Videos/VideoLanguage.cs
rename to TiktokExplode/Domain/ValueObjects/Media/MediaLanguage.cs
index ec01bd5..b713ce5 100644
--- a/TiktokExplode/Domain/ValueObjects/Videos/VideoLanguage.cs
+++ b/TiktokExplode/Domain/ValueObjects/Media/MediaLanguage.cs
@@ -1,18 +1,18 @@
-namespace TiktokExplode.Domain.ValueObjects.Videos;
+namespace TiktokExplode.Domain.ValueObjects.Media;
 
 /// <summary>
-/// Represents the language properties detected for a TikTok video's text content.
+/// Represents the language properties detected for a TikTok media's text content.
 /// </summary>
-public sealed record VideoLanguage
+public sealed record MediaLanguage
 {
     /// <summary>
-    /// The BCP-47 language code of the primary language detected in the video
+    /// The BCP-47 language code of the primary language detected in the media
     /// (e.g. <c>"en"</c>, <c>"es"</c>). Empty string if not detected.
     /// </summary>
     public string PrimaryLanguage { get; init; } = string.Empty;
 
     /// <summary>
-    /// <see langword="true"/> if TikTok considers the video's text eligible
+    /// <see langword="true"/> if TikTok considers the media's text eligible
     /// for automatic translation; otherwise <see langword="false"/>.
     /// </summary>
     public bool IsTranslatable { get; init; }
diff --git a/TiktokExplode/Domain/ValueObjects/Videos/VideoMusic.cs b/TiktokExplode/Domain/ValueObjects/Media/MediaMusic.cs
similarity index 91%
rename from TiktokExplode/Domain/ValueObjects/Videos/VideoMusic.cs
rename to TiktokExplode/Domain/ValueObjects/Media/MediaMusic.cs
index 69a8119..61ac24d 100644
--- a/TiktokExplode/Domain/ValueObjects/Videos/VideoMusic.cs
+++ b/TiktokExplode/Domain/ValueObjects/Media/MediaMusic.cs
@@ -1,11 +1,11 @@
 using TiktokExplode.Domain.ValueObjects.Authors;
 
-namespace TiktokExplode.Domain.ValueObjects.Videos;
+namespace TiktokExplode.Domain.ValueObjects.Media;
 
 /// <summary>
-/// Represents the music or sound associated with a TikTok video.
+/// Represents the music or sound associated with a TikTok media.
 /// </summary>
-public sealed class VideoMusic
+public sealed class MediaMusic
 {
     /// <summary>The unique TikTok-assigned identifier for the music or sound.</summary>
     public string Id { get; init; } = string.Empty;
diff --git a/TiktokExplode/Domain/ValueObjects/Media/MediaStats.cs b/TiktokExplode/Domain/ValueObjects/Media/MediaStats.cs
new file mode 100644
index 0000000..dd1056f
--- /dev/null
+++ b/TiktokExplode/Domain/ValueObjects/Media/MediaStats.cs
@@ -0,0 +1,25 @@
+namespace TiktokExplode.Domain.ValueObjects.Media;
+
+/// <summary>
+/// Aggregated engagement statistics for a TikTok media.
+/// </summary>
+public sealed record MediaStats
+{
+    /// <summary>Total number of times the media has been played.</summary>
+    public long Views { get; init; }
+
+    /// <summary>Total number of likes ("hearts") the media has received.</summary>
+    public long Likes { get; init; }
+
+    /// <summary>Total number of comments posted on the media.</summary>
+    public long Comments { get; init; }
+
+    /// <summary>Total number of times the media has been shared.</summary>
+    public long Shares { get; init; }
+
+    /// <summary>Total number of times the media has been saved to a favorites collection.</summary>
+    public long Favorites { get; init; }
+
+    /// <summary>Total number of times the media has been reposted by other users.</summary>
+    public long Reposts { get; init; }
+}
diff --git a/TiktokExplode/Domain/ValueObjects/Videos/VideoStats.cs b/TiktokExplode/Domain/ValueObjects/Videos/VideoStats.cs
deleted file mode 100644
index a1833e4..0000000
--- a/TiktokExplode/Domain/ValueObjects/Videos/VideoStats.cs
+++ /dev/null
@@ -1,25 +0,0 @@
-namespace TiktokExplode.Domain.ValueObjects.Videos;
-
-/// <summary>
-/// Aggregated engagement statistics for a TikTok video.
-/// </summary>
-public sealed record VideoStats
-{
-    /// <summary>Total number of times the video has been played.</summary>
-    public long Views { get; init; }
-
-    /// <summary>Total number of likes ("hearts") the video has received.</summary>
-    public long Likes { get; init; }
-
-    /// <summary>Total number of comments posted on the video.</summary>
-    public long Comments { get; init; }
-
-    /// <summary>Total number of times the video has been shared.</summary>
-    public long Shares { get; init; }
-
-    /// <summary>Total number of times the video has been saved to a favorites collection.</summary>
-    public long Favorites { get; init; }
-
-    /// <summary>Total number of times the video has been reposted by other users.</summary>
-    public long Reposts { get; init; }
-}

From d51d7e96fc8125e903d66b0fd907a192886c77d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Wed, 10 Jun 2026 11:38:12 -0500
Subject: [PATCH 09/18] Refactor TikTok search handling logic

Refactored `TiktokBrowser` to improve robustness in handling TikTok search pages:
- Rewrote `GetSearchPageAsync` to include WAF detection, better error handling, and manual fallback for API responses.
- Added `GetSearchNextPageAsync` to handle pagination and API response validation.
- Removed `_lastSearchApiUrl` and replaced it with direct API response handling.

Updated `PlaywrightSearchFetcher` to use the new `SearchPageResult` class for encapsulating JSON content and Playwright pages. Improved resource management by ensuring pages are closed properly.

Introduced `SearchPageResult` class to structure search results. Updated `TiktokSearchParser` to handle missing `data` arrays gracefully.
---
 .../Browser/TikTokBrowser.cs                  | 191 ++++++++++++------
 .../Search/PlaywrightSearchFetcher.cs         |  37 ++--
 .../Fetchers/Search/SearchPageResult.cs       |  10 +
 .../Parsers/TikTokSearchParser.cs             |   2 +-
 4 files changed, 160 insertions(+), 80 deletions(-)
 create mode 100644 TiktokExplode.Infrastructure/Fetchers/Search/SearchPageResult.cs

diff --git a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
index 7f2f835..4e984d5 100644
--- a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
+++ b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
@@ -1,6 +1,8 @@
 using Microsoft.Playwright;
+using System.Diagnostics;
 using TiktokExplode.Domain.Exceptions;
 using TiktokExplode.Infrastructure.Fetchers;
+using TiktokExplode.Infrastructure.Fetchers.Search;
 using TiktokExplode.Infrastructure.Options;
 
 namespace TiktokExplode.Infrastructure.Browser;
@@ -27,12 +29,6 @@ internal sealed class TiktokBrowser : IAsyncDisposable
     /// <summary>Browser launch and navigation options.</summary>
     private readonly PlaywrightFetcherOptions _options;
 
-    /// <summary>
-    /// The full URL (including X-Bogus and other signature params) of the last intercepted
-    /// search API request. Stored on the first page so subsequent pages can reuse the signature.
-    /// </summary>
-    private string? _lastSearchApiUrl;
-
     /// <summary>Private constructor — use <see cref="CreateAsync"/> to instantiate.</summary>
     private TiktokBrowser(
         IPlaywright playwright,
@@ -129,86 +125,155 @@ await page.RouteAsync("**/*", async route =>
         }
     }
 
-    public async Task<string> GetSearchPageAsync(string keyword)
+    /// <summary>
+    /// Opens a new page in the shared context, navigates to the search results page for <paramref name="keyword"/>,
+    /// and returns the full HTML content of the loaded page.
+    /// </summary>
+    /// <param name="keyword">The search keyword to query on TikTok.</param>
+    /// <returns>The full HTML content of the search results page.</returns>
+    /// <exception cref="TiktokParsingException">Thrown if the page fails to load (non-OK HTTP status).</exception>
+    /// <exception cref="TiktokWafException">Thrown if WAF challenge markers are found in the page content.</exception>
+    public async Task<SearchPageResult> GetSearchPageAsync(string keyword)
     {
         var page = await _context.NewPageAsync();
 
+        await page.GotoAsync(
+            $"https://www.tiktok.com/search?q={Uri.EscapeDataString(keyword)}",
+            new PageGotoOptions
+            {
+                WaitUntil = WaitUntilState.Load,
+                Timeout = _options.PageTimeoutMs
+            });
+
+        await page.WaitForFunctionAsync(
+        """
+        () => document.cookie.includes('msToken')
+        """,
+        new PageWaitForFunctionOptions
+        {
+            Timeout = _options.PageTimeoutMs
+        });
+
+        var responseTask = page.WaitForResponseAsync(
+            r => r.Url.Contains("/api/search/general/full"),
+            new PageWaitForResponseOptions
+            {
+                Timeout = _options.PageTimeoutMs
+            });
+
+        var pageResponse = await page.ReloadAsync(
+            new PageReloadOptions
+            {
+                WaitUntil = WaitUntilState.Load,
+                Timeout = _options.PageTimeoutMs
+            });
+
+        if (pageResponse is null || !pageResponse.Ok)
+            throw new TiktokParsingException($"Failed to load page. Status: {pageResponse?.Status}");
+
+        var content = await page.ContentAsync();
+
+        if (content.Contains("_wafchallengeid", StringComparison.OrdinalIgnoreCase))
+            throw new TiktokWafException("TikTok WAF challenge detected.");
+
+        IResponse response;
         try
         {
-            var responseTask = page.WaitForResponseAsync(
-               r => r.Url.Contains("/api/search/general/full"),
-               new PageWaitForResponseOptions { Timeout = _options.PageTimeoutMs });
-
-            var pageResponse = await page.GotoAsync(
-                $"https://www.tiktok.com/search?q={Uri.EscapeDataString(keyword)}", new PageGotoOptions
-                {
-                    WaitUntil = WaitUntilState.Load,
-                    Timeout = _options.PageTimeoutMs
-                });
+            response = await responseTask;
+        }
+        catch (TimeoutException)
+        {
+            throw new TiktokParsingException("Search API request was not intercepted within the timeout period. TikTok may not have issued the search request.");
+        }
 
-            if (pageResponse is null || !pageResponse.Ok)
-                throw new TiktokParsingException($"Failed to load page. Status: {pageResponse?.Status}");
+        if (!response.Ok)
+            throw new TiktokParsingException($"Failed to load search results. Status: {response.Status}");
 
-            var content = await page.ContentAsync();
+        var result = await response.TextAsync();
 
-            if (content.Contains("_wafchallengeid", StringComparison.OrdinalIgnoreCase))
-                throw new TiktokWafException("TikTok WAF challenge detected.");
+        if (string.IsNullOrWhiteSpace(result))
+        {
+            result = await page.EvaluateAsync<string>(
+                """
+            async (url) => {
+                const resp = await fetch(url, {
+                    credentials: 'include',
+                    headers: {
+                        accept: 'application/json, text/plain, */*'
+                    }
+                });
 
-            IResponse response;
-            try
-            {
-                response = await responseTask;
-            }
-            catch (TimeoutException)
-            {
-                throw new TiktokParsingException("Search API request was not intercepted within the timeout period. TikTok may not have issued the search request.");
+                return await resp.text();
             }
+            """,
+                response.Url);
+        }
 
-            if (!response.Ok)
-                throw new TiktokParsingException($"Failed to load search results. Status: {response.Status}");
+        return new SearchPageResult
+        {
+            JsonContent = result,
+            Page = page
+        };
+    }
 
-            _lastSearchApiUrl = response.Url;
+    /// <summary>
+    /// Scrolls the search results container to trigger loading of the next page of results, waits for the API response,
+    /// </summary>
+    /// <param name="page">The page containing the search results. Must be the same page returned 
+    /// by <see cref="GetSearchPageAsync"/>.</param>
+    /// <returns>The raw JSON string returned by the search API for the next page of results.</returns>
+    /// <exception cref="TiktokParsingException"> Thrown if the search results container is not found, if the API response 
+    /// is not OK, or if the API response cannot be retrieved within the timeout period.</exception>
+    public async Task<string> GetSearchNextPageAsync(IPage page)
+    {
+        var responseTask = page.WaitForResponseAsync(
+            r => r.Url.Contains("/api/search/general/full"),
+            new PageWaitForResponseOptions
+            {
+                Timeout = _options.PageTimeoutMs
+            });
 
-            var data = await page.EvaluateAsync<string>("""
-                async (url) => {
-                    const resp = await fetch(url, {
-                        credentials: 'include',
-                        headers: { 'accept': 'application/json, text/plain, */*' }
-                    });
-                    return await resp.text();
-                }
-                """, _lastSearchApiUrl);
+        var scrolled = await page.EvaluateAsync<bool>(
+        """
+        () => {
+            const main = document.querySelector('#grid-main');
+
+            if (!main)
+                return false;
 
-            return data;
+            main.scrollTop = main.scrollHeight;
+            return true;
         }
-        finally
+        """);
+
+        if (!scrolled)
         {
-            await page.CloseAsync();
+            throw new TiktokParsingException(
+                "Search results container '#grid-main' was not found.");
         }
 
-    }
+        var response = await responseTask;
 
-    public async Task<string> GetSearchNextPageAsync(
-        string keyword,
-        long cursor,
-        IPage page)
-    {
-        if (_lastSearchApiUrl is null)
-            throw new TiktokParsingException("No signed search API URL available. Call GetSearchPageAsync first.");
-
-        return await page.EvaluateAsync<string>("""
-        async (args) => {
-            const url = new URL(args.baseUrl);
-            url.searchParams.set('keyword', args.keyword);
-            url.searchParams.set('cursor', String(args.cursor));
-            url.searchParams.set('offset', String(args.cursor));
-            const resp = await fetch(url.toString(), {
+        if (!response.Ok)
+        {
+            throw new TiktokParsingException(
+                $"Failed to load next search page. Status: {response.Status}");
+        }
+
+        return await page.EvaluateAsync<string>(
+        """
+        async (url) => {
+            const resp = await fetch(url, {
                 credentials: 'include',
-                headers: { 'accept': 'application/json, text/plain, */*' }
+                headers: {
+                    accept: 'application/json, text/plain, */*'
+                }
             });
+
             return await resp.text();
         }
-        """, new { baseUrl = _lastSearchApiUrl, keyword, cursor });
+        """,
+        response.Url);
     }
 
     /// <summary>
diff --git a/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs b/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
index e4c4e75..bbd028d 100644
--- a/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
+++ b/TiktokExplode.Infrastructure/Fetchers/Search/PlaywrightSearchFetcher.cs
@@ -60,31 +60,38 @@ public async IAsyncEnumerable<SearchFetchResult> FetchSearchAsync(
             }
         }
 
-        var json = await FetchFirstPageWithRetryAsync(keyword, cancellationToken);
+        var firstPageResult = await FetchFirstPageWithRetryAsync(keyword, cancellationToken);
+
+        var json = firstPageResult.JsonContent;
+        var page = firstPageResult.Page;
+
         var cookies = await _browser!.GetCookiesAsync();
 
         yield return new SearchFetchResult { JsonContent = json, Cookies = cookies };
 
         var root = JsonNode.Parse(json);
         var hasMore = root?["has_more"]?.GetValue<int>() ?? 0;
-        var cursor = root?["cursor"]?.GetValue<long>() ?? 0;
-
-        var page = await _browser.CreatePageAsync();
 
-        while (hasMore == 1 && !cancellationToken.IsCancellationRequested)
+        try
         {
-            var nextJson = await FetchNextPageWithRetryAsync(keyword, cursor, page, cancellationToken);
-            yield return new SearchFetchResult { JsonContent = nextJson, Cookies = cookies };
+            while (hasMore == 1 && !cancellationToken.IsCancellationRequested)
+            {
+                var nextJson = await FetchNextPageWithRetryAsync(page, cancellationToken);
+                yield return new SearchFetchResult { JsonContent = nextJson, Cookies = cookies };
 
-            var nextRoot = JsonNode.Parse(nextJson);
-            hasMore = nextRoot?["has_more"]?.GetValue<int>() ?? 0;
-            cursor = nextRoot?["cursor"]?.GetValue<long>() ?? 0;
+                var nextRoot = JsonNode.Parse(nextJson);
+                hasMore = nextRoot?["has_more"]?.GetValue<int>() ?? 0;
+            }
+        }
+        finally
+        {
+            await page.CloseAsync();
         }
-
-        await page.CloseAsync();
     }
 
-    private async Task<string> FetchFirstPageWithRetryAsync(string keyword, CancellationToken cancellationToken)
+    private async Task<SearchPageResult> FetchFirstPageWithRetryAsync(
+        string keyword, 
+        CancellationToken cancellationToken)
     {
         for (int attempt = 0; attempt <= tikTokOptions.MaxWafRetries; attempt++)
         {
@@ -101,8 +108,6 @@ private async Task<string> FetchFirstPageWithRetryAsync(string keyword, Cancella
     }
 
     private async Task<string> FetchNextPageWithRetryAsync(
-        string keyword,
-        long cursor,
         IPage page,
         CancellationToken cancellationToken)
     {
@@ -110,7 +115,7 @@ private async Task<string> FetchNextPageWithRetryAsync(
         {
             try
             {
-                return await _browser!.GetSearchNextPageAsync(keyword, cursor, page);
+                return await _browser!.GetSearchNextPageAsync(page);
             }
             catch (TiktokWafException) when (attempt < tikTokOptions.MaxWafRetries)
             {
diff --git a/TiktokExplode.Infrastructure/Fetchers/Search/SearchPageResult.cs b/TiktokExplode.Infrastructure/Fetchers/Search/SearchPageResult.cs
new file mode 100644
index 0000000..0913e7f
--- /dev/null
+++ b/TiktokExplode.Infrastructure/Fetchers/Search/SearchPageResult.cs
@@ -0,0 +1,10 @@
+using Microsoft.Playwright;
+
+namespace TiktokExplode.Infrastructure.Fetchers.Search;
+
+internal sealed class SearchPageResult
+{
+    public required string JsonContent { get; init; }
+
+    public required IPage Page { get; init; }
+}
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
index f7d654a..6c04e94 100644
--- a/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
@@ -14,7 +14,7 @@ internal static IEnumerable<Media> Parse(string jsonContent)
             ?? throw new TiktokParsingException("Failed to parse search JSON.");
 
         var data = root["data"]?.AsArray()
-            ?? throw new TiktokParsingException("Search JSON does not contain 'data' array.");
+            ?? [];
 
         foreach (var entry in data)
         {

From 9f25c32785f0a7815970d0b4580c58af627e8b08 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Wed, 10 Jun 2026 20:21:16 -0500
Subject: [PATCH 10/18] Optimize TikTokBrowser and add Playwright tests

- Changed `WaitUntilState` in `TikTokBrowser` to improve load times.
- Refactored `page.WaitForFunctionAsync` for better readability.
- Added error handling for `response.TextAsync` in `TikTokBrowser`.
- Documented and modularized parsing logic in `TiktokSearchParser`.
- Introduced `PlaywrightFixture` for integration test setup.
- Added `PlaywrightSearchFetcherTests` and `TiktokSearchClientTests`.
- Configured integration tests project for .NET 9.0.
- Added `global using` directives for common namespaces.
---
 .../Browser/TikTokBrowser.cs                  | 27 +++++---
 .../Parsers/TikTokSearchParser.cs             | 56 +++++++++++++++++
 .../Fixtures/PlaywrightFixture.cs             | 40 ++++++++++++
 .../PlaywrightCollection.cs                   |  6 ++
 .../Search/PlaywrightSearchFetcherTests.cs    | 62 +++++++++++++++++++
 .../Search/TiktokSearchClientTests.cs         | 25 ++++++++
 .../TiktokExplode.IntegrationTests.csproj     | 28 +++++++++
 TiktokExplode.IntegrationTests/Usings.cs      |  6 ++
 TiktokExplode.NET.slnx                        |  1 +
 9 files changed, 242 insertions(+), 9 deletions(-)
 create mode 100644 TiktokExplode.IntegrationTests/Fixtures/PlaywrightFixture.cs
 create mode 100644 TiktokExplode.IntegrationTests/PlaywrightCollection.cs
 create mode 100644 TiktokExplode.IntegrationTests/Search/PlaywrightSearchFetcherTests.cs
 create mode 100644 TiktokExplode.IntegrationTests/Search/TiktokSearchClientTests.cs
 create mode 100644 TiktokExplode.IntegrationTests/TiktokExplode.IntegrationTests.csproj
 create mode 100644 TiktokExplode.IntegrationTests/Usings.cs

diff --git a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
index 4e984d5..993ad62 100644
--- a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
+++ b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
@@ -141,18 +141,18 @@ await page.GotoAsync(
             $"https://www.tiktok.com/search?q={Uri.EscapeDataString(keyword)}",
             new PageGotoOptions
             {
-                WaitUntil = WaitUntilState.Load,
+                WaitUntil = WaitUntilState.DOMContentLoaded,
                 Timeout = _options.PageTimeoutMs
             });
 
         await page.WaitForFunctionAsync(
-        """
-        () => document.cookie.includes('msToken')
-        """,
-        new PageWaitForFunctionOptions
-        {
-            Timeout = _options.PageTimeoutMs
-        });
+            """
+            () => document.cookie.includes('msToken')
+            """,
+            new PageWaitForFunctionOptions
+            {
+                Timeout = _options.PageTimeoutMs
+            });
 
         var responseTask = page.WaitForResponseAsync(
             r => r.Url.Contains("/api/search/general/full"),
@@ -189,7 +189,16 @@ await page.WaitForFunctionAsync(
         if (!response.Ok)
             throw new TiktokParsingException($"Failed to load search results. Status: {response.Status}");
 
-        var result = await response.TextAsync();
+        string result;
+
+        try
+        {
+            result = await response.TextAsync();
+        }
+        catch
+        {
+            result = string.Empty;
+        }
 
         if (string.IsNullOrWhiteSpace(result))
         {
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
index 6c04e94..5b523f4 100644
--- a/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokSearchParser.cs
@@ -6,8 +6,25 @@
 
 namespace TiktokExplode.Infrastructure.Parsers;
 
+/// <summary>
+/// Parses TikTok search API responses into domain <see cref="Media"/> objects.
+/// Supports both standard video posts and image carousel posts,
+/// automatically dispatching each search result to the appropriate parser.
+/// </summary>
 internal sealed class TiktokSearchParser
 {
+    /// <summary>
+    /// Parses a TikTok search response and returns the media items contained in the result set.
+    /// </summary>
+    /// <param name="jsonContent">
+    /// Raw JSON payload returned by the TikTok search endpoint.
+    /// </param>
+    /// <returns>
+    /// A sequence of <see cref="Media"/> objects representing videos or carousels.
+    /// </returns>
+    /// <exception cref="TiktokParsingException">
+    /// Thrown if the JSON payload cannot be parsed or required nodes are missing.
+    /// </exception>
     internal static IEnumerable<Media> Parse(string jsonContent)
     {
         var root = JsonNode.Parse(jsonContent)
@@ -36,6 +53,21 @@ internal static IEnumerable<Media> Parse(string jsonContent)
         }
     }
 
+    /// <summary>
+    /// Parses a TikTok carousel post from a search result item.
+    /// </summary>
+    /// <param name="node">
+    /// Root search item node containing metadata, author, stats, and media information.
+    /// </param>
+    /// <param name="postNode">
+    /// The <c>imagePost</c> node containing carousel-specific content.
+    /// </param>
+    /// <returns>
+    /// A fully populated <see cref="Carousel"/> instance.
+    /// </returns>
+    /// <exception cref="TiktokParsingException">
+    /// Thrown if required carousel nodes are missing.
+    /// </exception>
     private static Carousel ParseCarousel(JsonNode node, JsonNode postNode)
     {
         var videoNode = node["video"]
@@ -62,6 +94,18 @@ private static Carousel ParseCarousel(JsonNode node, JsonNode postNode)
         };
     }
 
+    /// <summary>
+    /// Parses the carousel content section, including cover image and image collection.
+    /// </summary>
+    /// <param name="node">
+    /// The <c>imagePost</c> node from the TikTok payload.
+    /// </param>
+    /// <returns>
+    /// A populated <see cref="CarouselPost"/> instance.
+    /// </returns>
+    /// <exception cref="TiktokParsingException">
+    /// Thrown if the cover image or image collection nodes are missing.
+    /// </exception>
     private static CarouselPost ParseCarouselPost(JsonNode node)
     {
         var coverNode = node["cover"]
@@ -83,6 +127,18 @@ private static CarouselPost ParseCarouselPost(JsonNode node)
         };
     }
 
+    /// <summary>
+    /// Parses a carousel image definition and extracts its dimensions and URLs.
+    /// </summary>
+    /// <param name="node">
+    /// Image node from the carousel payload.
+    /// </param>
+    /// <returns>
+    /// A populated <see cref="CarouselImage"/> instance.
+    /// </returns>
+    /// <exception cref="TiktokParsingException">
+    /// Thrown if the image URL collection is missing.
+    /// </exception>
     private static CarouselImage ParseCarouselImage(JsonNode node)
     {
         var imageUrlNode = node["imageURL"]
diff --git a/TiktokExplode.IntegrationTests/Fixtures/PlaywrightFixture.cs b/TiktokExplode.IntegrationTests/Fixtures/PlaywrightFixture.cs
new file mode 100644
index 0000000..2326e41
--- /dev/null
+++ b/TiktokExplode.IntegrationTests/Fixtures/PlaywrightFixture.cs
@@ -0,0 +1,40 @@
+namespace TiktokExplode.IntegrationTests.Fixtures;
+
+public sealed class PlaywrightFixture
+{
+    public PlaywrightFixture()
+    {
+        try
+        {
+            using var playwright = Microsoft.Playwright.Playwright.CreateAsync()
+                .GetAwaiter()
+                .GetResult();
+
+            var browser = playwright.Chromium
+                .LaunchAsync(new()
+                {
+                    Headless = true
+                })
+                .GetAwaiter()
+                .GetResult();
+
+            browser.CloseAsync()
+                .GetAwaiter()
+                .GetResult();
+        }
+        catch (Exception ex)
+        {
+            throw new InvalidOperationException(
+                """
+                Playwright is installed but Chromium is missing.
+
+                Run:
+
+                    pwsh playwright.ps1 install
+
+                before executing integration tests.
+                """,
+                ex);
+        }
+    }
+}
diff --git a/TiktokExplode.IntegrationTests/PlaywrightCollection.cs b/TiktokExplode.IntegrationTests/PlaywrightCollection.cs
new file mode 100644
index 0000000..54518cb
--- /dev/null
+++ b/TiktokExplode.IntegrationTests/PlaywrightCollection.cs
@@ -0,0 +1,6 @@
+namespace TiktokExplode.IntegrationTests;
+
+[CollectionDefinition("Playwright")]
+public sealed class PlaywrightCollection : ICollectionFixture<PlaywrightFixture>
+{
+}
diff --git a/TiktokExplode.IntegrationTests/Search/PlaywrightSearchFetcherTests.cs b/TiktokExplode.IntegrationTests/Search/PlaywrightSearchFetcherTests.cs
new file mode 100644
index 0000000..2afd5dc
--- /dev/null
+++ b/TiktokExplode.IntegrationTests/Search/PlaywrightSearchFetcherTests.cs
@@ -0,0 +1,62 @@
+namespace TiktokExplode.IntegrationTests.Search;
+
+[Collection("Playwright")]
+public class PlaywrightSearchFetcherTests()
+{
+    [Fact]
+    public async Task FetchSearchAsync_Should_Return_First_Page()
+    {
+        var fetcher = new PlaywrightSearchFetcher();
+
+        await foreach (var page in fetcher.FetchSearchAsync("lalala"))
+        {
+            page.JsonContent.Should().NotBeNullOrWhiteSpace();
+
+            var root = JsonNode.Parse(page.JsonContent);
+
+            root.Should().NotBeNull();
+
+            break;
+        }
+    }
+
+    [Fact]
+    public async Task FetchSearchAsync_Should_Load_Next_Page_When_HasMore_Is_True()
+    {
+        var fetcher = new PlaywrightSearchFetcher();
+
+        var pages = new List<SearchFetchResult>();
+
+        await foreach (var page in fetcher.FetchSearchAsync("lalala"))
+        {
+            pages.Add(page);
+
+            if (pages.Count >= 2)
+                break;
+        }
+
+        var firstRoot = JsonNode.Parse(pages[0].JsonContent);
+
+        var hasMore = firstRoot?["has_more"]?.GetValue<int>() ?? 0;
+
+        if (hasMore == 1)
+        {
+            pages.Should().HaveCountGreaterThan(1);
+        }
+    }
+
+    [Fact]
+    public async Task FetchSearchAsync_Should_Return_Cookies()
+    {
+        var fetcher = new PlaywrightSearchFetcher();
+
+        await foreach (var page in fetcher.FetchSearchAsync("lalala"))
+        {
+            page.Cookies.Should().NotBeEmpty();
+            page.Cookies.Should().Contain(
+                c => c.Name.Equals("msToken", StringComparison.OrdinalIgnoreCase));
+
+            break;
+        }
+    }
+}
diff --git a/TiktokExplode.IntegrationTests/Search/TiktokSearchClientTests.cs b/TiktokExplode.IntegrationTests/Search/TiktokSearchClientTests.cs
new file mode 100644
index 0000000..c8fa3cc
--- /dev/null
+++ b/TiktokExplode.IntegrationTests/Search/TiktokSearchClientTests.cs
@@ -0,0 +1,25 @@
+namespace TiktokExplode.IntegrationTests.Search;
+
+[Collection("Playwright")]
+public class TiktokSearchClientTests
+{
+    [Fact]
+    public async Task SearchAsync_Should_Return_Media()
+    {
+        var client = new TiktokSearchClient();
+
+        var media = new List<Media>();
+
+        await foreach (var item in client.SearchAsync("lalala"))
+        {
+            media.Add(item);
+
+            if (media.Count >= 5)
+                break;
+        }
+
+        media.Should().NotBeEmpty();
+        media.Should().OnlyContain(m =>
+            !string.IsNullOrWhiteSpace(m.Id));
+    }
+}
diff --git a/TiktokExplode.IntegrationTests/TiktokExplode.IntegrationTests.csproj b/TiktokExplode.IntegrationTests/TiktokExplode.IntegrationTests.csproj
new file mode 100644
index 0000000..4b908a4
--- /dev/null
+++ b/TiktokExplode.IntegrationTests/TiktokExplode.IntegrationTests.csproj
@@ -0,0 +1,28 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" Version="6.0.2" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0" />
+    <PackageReference Include="xunit" Version="2.9.2" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" />
+	<PackageReference Include="Microsoft.Playwright" Version="1.59.0" />
+	<PackageReference Include="FluentAssertions" Version="6.*" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+    <ItemGroup>
+		<ProjectReference Include="..\TiktokExplode\TiktokExplode.csproj" />
+		<ProjectReference Include="..\TiktokExplode.Infrastructure\TiktokExplode.Infrastructure.csproj" />
+	</ItemGroup>
+
+</Project>
diff --git a/TiktokExplode.IntegrationTests/Usings.cs b/TiktokExplode.IntegrationTests/Usings.cs
new file mode 100644
index 0000000..fa76cd1
--- /dev/null
+++ b/TiktokExplode.IntegrationTests/Usings.cs
@@ -0,0 +1,6 @@
+global using FluentAssertions;
+global using TiktokExplode.Domain.Entities;
+global using System.Text.Json.Nodes;
+global using TiktokExplode.Infrastructure.Fetchers.Search;
+global using TiktokExplode.IntegrationTests.Fixtures;
+global using TiktokExplode.Infrastructure.Clients;
\ No newline at end of file
diff --git a/TiktokExplode.NET.slnx b/TiktokExplode.NET.slnx
index 49db7b8..f3b753f 100644
--- a/TiktokExplode.NET.slnx
+++ b/TiktokExplode.NET.slnx
@@ -4,6 +4,7 @@
   <Project Path="TiktokExplode.Console/TiktokExplode.Console.csproj" />
   <Project Path="TiktokExplode.Extensions.DependencyInjection/TiktokExplode.Extensions.DependencyInjection.csproj" />
   <Project Path="TiktokExplode.Infrastructure/TiktokExplode.Infrastructure.csproj" />
+  <Project Path="TiktokExplode.IntegrationTests/TiktokExplode.IntegrationTests.csproj" Id="15d5c0e4-8fe1-4142-99ca-22f2da34fff1" />
   <Project Path="TiktokExplode.Tests/TiktokExplode.Tests.csproj" />
   <Project Path="TiktokExplode/TiktokExplode.csproj" />
 </Solution>

From 5648e59bdfa854c37af8592ec0d6ecaa504e95b7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Wed, 10 Jun 2026 20:58:49 -0500
Subject: [PATCH 11/18] Update TikTokSearchClient docs and add parser tests

Updated the `README.md` to reflect the available methods in `TiktokSearchClient`, fixed table formatting, and removed the "Known Limitations" section about pagination. Added unit tests in `TikTokSearchParserTests.cs` to validate the behavior of `TiktokSearchClient` for handling `Video` and `Carousel` results, as well as edge cases like empty or missing data.

Introduced helper methods for creating mock clients and collecting async results. Added JSON fixtures in `TikTokFixtures.cs` to simulate various API responses, including valid videos, carousels, mixed results, and error scenarios. Reusable blocks for authors, music, and stats were added to simplify fixture creation.

Implemented specific tests to ensure correct type identification, full field mapping, handling of invalid entries, and proper exception handling for parsing errors.
---
 README.md                                     |  34 +-
 .../Parsers/TikTokSearchParserTests.cs        | 274 ++++++++++++++
 .../Infrastructure/TikTokFixtures.cs          | 351 ++++++++++++++++++
 3 files changed, 634 insertions(+), 25 deletions(-)
 create mode 100644 TiktokExplode.Tests/Infrastructure/Parsers/TikTokSearchParserTests.cs

diff --git a/README.md b/README.md
index 46d00a3..7c3bb3c 100644
--- a/README.md
+++ b/README.md
@@ -153,15 +153,15 @@ await foreach (var media in client.SearchAsync("funny cats"))
 
 > **Note:** `TiktokSearchClient` implements `ISearchClient`, which extends `IDownloadClient`. This means all extension methods (`DownloadAsync(filePath)`, `DownloadWatermarkedAsync(filePath)`, `DownloadImageAsync`, `DownloadAnimatedImageAsync`) are available directly on the search client — no need for a separate `TiktokClient` instance.
 
-> **Search scope:** The current implementation returns results from the **first page** of TikTok's search API (~10–20 results). Multi-page pagination is under active investigation — see the [Known Limitations](#known-limitations) section.
+> **Search scope:** The current implementation returns results from the **first page** of TikTok's search API (~10–20 results).
 
 #### Methods
 
-| Method                                               | Returns                   | Description                                                     |
-| ---------------------------------------------------- | ------------------------- | --------------------------------------------------------------- |
-| `SearchAsync(string keyword, CancellationToken)`     | `IAsyncEnumerable<Media>` | Streams media results (videos and carousels) for the keyword    |
-| `DownloadAsync(Video, CancellationToken)`            | `StreamInfo`              | Downloads video without watermark                               |
-| `DownloadWatermarkedAsync(Video, CancellationToken)` | `StreamInfo`              | Downloads video with watermark                                  |
+| Method                                               | Returns                   | Description                                                  |
+| ---------------------------------------------------- | ------------------------- | ------------------------------------------------------------ |
+| `SearchAsync(string keyword, CancellationToken)`     | `IAsyncEnumerable<Media>` | Streams media results (videos and carousels) for the keyword |
+| `DownloadAsync(Video, CancellationToken)`            | `StreamInfo`              | Downloads video without watermark                            |
+| `DownloadWatermarkedAsync(Video, CancellationToken)` | `StreamInfo`              | Downloads video with watermark                               |
 
 `TiktokSearchClient` implements `IAsyncDisposable` — always use `await using`.
 
@@ -252,9 +252,9 @@ All search results are `Media` objects. Use pattern matching (`is Video`, `is Ca
 
 Represents a TikTok slideshow post (multiple images + audio).
 
-| Property | Type          | Description                             |
-| -------- | ------------- | --------------------------------------- |
-| `Post`   | `CarouselPost` | Collection of images with their URLs   |
+| Property | Type           | Description                          |
+| -------- | -------------- | ------------------------------------ |
+| `Post`   | `CarouselPost` | Collection of images with their URLs |
 
 ### `Author` model
 
@@ -379,22 +379,6 @@ TiktokExplode.Extensions.DependencyInjection/  # AddTiktokExplode() for Microsof
 
 ---
 
-## Known Limitations
-
-### Search pagination
-
-`SearchAsync` currently returns only the **first page** of results (~10–20 items depending on TikTok's response).
-
-Multi-page pagination requires triggering TikTok's internal IntersectionObserver inside the live browser session. Every new page request is signed with a fresh **X-Bogus** token that covers all query parameters — modifying `cursor` or any other param after the fact invalidates the signature and returns an empty response. Approaches tried so far:
-
-- `Mouse.WheelAsync` — dispatches a `WheelEvent` but does not guarantee `scrollTop` changes on TikTok's custom scroll container.
-- `window.scrollTo()` / `document.scrollingElement.scrollTop = scrollHeight` — effective only if the scroll container is `<html>` or `<body>`; TikTok uses an internal `<div>`.
-- `route.FetchAsync()` — bypasses the browser's HTTP/TLS stack; TikTok detects the different fingerprint and returns empty body.
-
-This is a planned feature. Contributions welcome.
-
----
-
 ## Acknowledgements
 
 This library was heavily inspired by [**YoutubeExplode**](https://github.com/Tyrrrz/YoutubeExplode) by [Tyrrrz](https://github.com/Tyrrrz). His work showed me how a well-designed, clean .NET library for a media platform should look and feel. Without that reference, TiktokExplode would not exist. Thank you.
diff --git a/TiktokExplode.Tests/Infrastructure/Parsers/TikTokSearchParserTests.cs b/TiktokExplode.Tests/Infrastructure/Parsers/TikTokSearchParserTests.cs
new file mode 100644
index 0000000..06e2e15
--- /dev/null
+++ b/TiktokExplode.Tests/Infrastructure/Parsers/TikTokSearchParserTests.cs
@@ -0,0 +1,274 @@
+using FluentAssertions;
+using NSubstitute;
+using System.Runtime.CompilerServices;
+using TiktokExplode.Domain.Entities;
+using TiktokExplode.Domain.Exceptions;
+using TiktokExplode.Infrastructure.Clients;
+using TiktokExplode.Infrastructure.Fetchers.Search;
+
+namespace TiktokExplode.Tests.Infrastructure.Parsers;
+
+public class TikTokSearchParserTests
+{
+    // ── Helpers ───────────────────────────────────────────────────────────────
+
+    private static TiktokSearchClient CreateClient(string jsonContent)
+    {
+        var fetcher = Substitute.For<ISearchFetcher>();
+        fetcher
+            .FetchSearchAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
+            .Returns(YieldResult(new SearchFetchResult { JsonContent = jsonContent, Cookies = [] }));
+        return new TiktokSearchClient(fetcher);
+    }
+
+    private static async IAsyncEnumerable<SearchFetchResult> YieldResult(
+        SearchFetchResult result,
+        [EnumeratorCancellation] CancellationToken _ = default)
+    {
+        await Task.Yield();
+        yield return result;
+    }
+
+    private static async Task<List<Media>> CollectAsync(IAsyncEnumerable<Media> source)
+    {
+        var list = new List<Media>();
+        await foreach (var item in source)
+            list.Add(item);
+        return list;
+    }
+
+    // ── Type dispatch ─────────────────────────────────────────────────────────
+
+    [Fact]
+    public async Task Should_ReturnVideo_When_SearchItemHasNoImagePost()
+    {
+        await using var client = CreateClient(TikTokFixtures.ValidVideoSearchJson);
+
+        var results = await CollectAsync(client.SearchAsync("test"));
+
+        results.Should().ContainSingle()
+               .Which.Should().BeOfType<Video>();
+    }
+
+    [Fact]
+    public async Task Should_ReturnCarousel_When_SearchItemHasImagePost()
+    {
+        await using var client = CreateClient(TikTokFixtures.ValidCarouselSearchJson);
+
+        var results = await CollectAsync(client.SearchAsync("test"));
+
+        results.Should().ContainSingle()
+               .Which.Should().BeOfType<Carousel>();
+    }
+
+    // ── Full field mapping — Video ────────────────────────────────────────────
+
+    [Fact]
+    public async Task Should_MapAllVideoFields_When_SearchResultIsVideo()
+    {
+        await using var client = CreateClient(TikTokFixtures.ValidVideoSearchJson);
+
+        var results = await CollectAsync(client.SearchAsync("test"));
+        var video = results.Should().ContainSingle().Which.Should().BeOfType<Video>().Subject;
+
+        // Root fields
+        video.Id.Should().Be("1111111111111111111");
+        video.Description.Should().Be("Search video description");
+        video.Location.Should().Be("MX");
+        video.CreatedAt.Should().Be(DateTimeOffset.FromUnixTimeSeconds(1_700_100_000));
+
+        // Language
+        video.Language.PrimaryLanguage.Should().Be("es");
+        video.Language.IsTranslatable.Should().BeFalse();
+
+        // Author
+        video.Author.UniqueId.Should().Be("search_user");
+        video.Author.Name.Should().Be("Search User");
+        video.Author.Description.Should().Be("Search bio");
+        video.Author.IsVerified.Should().BeTrue();
+        video.Author.IsPrivate.Should().BeFalse();
+        video.Author.Avatar.Larger.Should().Be("https://example.com/sv_avatar_large.jpg");
+        video.Author.Avatar.Medium.Should().Be("https://example.com/sv_avatar_medium.jpg");
+        video.Author.Avatar.Small.Should().Be("https://example.com/sv_avatar_thumb.jpg");
+
+        // Author stats
+        video.Author.Stats.Followers.Should().Be(2_000);
+        video.Author.Stats.Following.Should().Be(300);
+        video.Author.Stats.Friends.Should().Be(25);
+        video.Author.Stats.LikesReceived.Should().Be(75_000);
+        video.Author.Stats.VideoCount.Should().Be(50);
+
+        // Stats
+        video.Stats.Views.Should().Be(200_000);
+        video.Stats.Likes.Should().Be(8_000);
+        video.Stats.Comments.Should().Be(500);
+        video.Stats.Shares.Should().Be(2_000);
+        video.Stats.Favorites.Should().Be(600);
+        video.Stats.Reposts.Should().Be(100);
+
+        // Cover
+        video.Cover.StaticUrl.Should().Be("https://cdn.example.com/sv_cover.jpg");
+        video.Cover.AnimatedUrl.Should().Be("https://cdn.example.com/sv_cover.webp");
+
+        // Video-specific info
+        video.Duration.Seconds.Should().Be(20);
+        video.Duration.PreciseSeconds.Should().BeApproximately(20.75, precision: 0.001);
+        video.Info.Width.Should().Be(1_080);
+        video.Info.Height.Should().Be(1_920);
+        video.Info.Ratio.Should().Be("1080p");
+        video.Info.DownloadLinks.OriginalUrl.Should().Be("https://cdn.example.com/sv_play.mp4");
+        video.Info.DownloadLinks.WatermarkedUrl.Should().Be("https://cdn.example.com/sv_download.mp4");
+        video.Info.DownloadLinks.OriginalSizeInBytes.Should().Be(5_242_880);
+
+        // Bitrate
+        video.Info.Bitrates.Should().ContainSingle();
+        video.Info.Bitrates[0].Value.Should().Be(2_000_000);
+        video.Info.Bitrates[0].FPS.Should().Be(60);
+        video.Info.Bitrates[0].CodecType.Should().Be("h265");
+
+        // Music
+        video.Music.Id.Should().Be("7000000000000000001");
+        video.Music.Title.Should().Be("Search Track");
+        video.Music.AuthorName.Should().Be("Search Artist");
+        video.Music.AlbumName.Should().Be("Search Album");
+        video.Music.IsCopyrighted.Should().BeTrue();
+        video.Music.IsOriginal.Should().BeFalse();
+    }
+
+    // ── Full field mapping — Carousel ─────────────────────────────────────────
+
+    [Fact]
+    public async Task Should_MapAllCarouselFields_When_SearchResultIsCarousel()
+    {
+        await using var client = CreateClient(TikTokFixtures.ValidCarouselSearchJson);
+
+        var results = await CollectAsync(client.SearchAsync("slides"));
+        var carousel = results.Should().ContainSingle().Which.Should().BeOfType<Carousel>().Subject;
+
+        // Root fields
+        carousel.Id.Should().Be("2222222222222222222");
+        carousel.Description.Should().Be("Search carousel description");
+        carousel.Location.Should().Be("US");
+        carousel.CreatedAt.Should().Be(DateTimeOffset.FromUnixTimeSeconds(1_700_200_000));
+
+        // Language
+        carousel.Language.PrimaryLanguage.Should().Be("en");
+        carousel.Language.IsTranslatable.Should().BeTrue();
+
+        // Author
+        carousel.Author.UniqueId.Should().Be("carousel_user");
+        carousel.Author.Name.Should().Be("Carousel User");
+        carousel.Author.IsVerified.Should().BeFalse();
+        carousel.Author.Stats.Followers.Should().Be(3_000);
+
+        // Stats
+        carousel.Stats.Views.Should().Be(50_000);
+        carousel.Stats.Likes.Should().Be(2_000);
+        carousel.Stats.Comments.Should().Be(100);
+
+        // Video cover (sourced from the item's "video" node)
+        carousel.Cover.StaticUrl.Should().Be("https://cdn.example.com/cu_video_cover.jpg");
+        carousel.Cover.AnimatedUrl.Should().Be("https://cdn.example.com/cu_video_animated.webp");
+
+        // Music
+        carousel.Music.Id.Should().Be("6000000000000000001");
+        carousel.Music.Title.Should().Be("Carousel Track");
+        carousel.Music.IsOriginal.Should().BeTrue();
+        carousel.Music.IsCopyrighted.Should().BeFalse();
+
+        // Carousel post
+        carousel.Post.Title.Should().Be("Carousel Title");
+
+        // Cover image
+        carousel.Post.Cover.Width.Should().Be(1_080u);
+        carousel.Post.Cover.Height.Should().Be(1_920u);
+        carousel.Post.Cover.Urls.Should().ContainSingle()
+            .Which.Should().Be("https://cdn.example.com/carousel_cover.jpg");
+
+        // Images collection
+        carousel.Post.Images.Should().HaveCount(2);
+
+        var first = carousel.Post.Images[0];
+        first.Width.Should().Be(1_080u);
+        first.Height.Should().Be(1_920u);
+        first.Urls.Should().ContainSingle()
+            .Which.Should().Be("https://cdn.example.com/slide1.jpg");
+
+        var second = carousel.Post.Images[1];
+        second.Width.Should().Be(720u);
+        second.Height.Should().Be(1_280u);
+        second.Urls.Should().HaveCount(2);
+        second.Urls.Should().Contain("https://cdn.example.com/slide2.jpg");
+        second.Urls.Should().Contain("https://cdn.example.com/slide2_fallback.jpg");
+    }
+
+    // ── Filtering ─────────────────────────────────────────────────────────────
+
+    [Fact]
+    public async Task Should_SkipEntry_When_TypeIsNotOne()
+    {
+        await using var client = CreateClient(TikTokFixtures.SearchJsonWithNonTypeOneEntry);
+
+        var results = await CollectAsync(client.SearchAsync("test"));
+
+        results.Should().ContainSingle("only the type=1 entry should be returned");
+        results[0].Id.Should().Be("1111111111111111111");
+    }
+
+    [Fact]
+    public async Task Should_ReturnBothTypes_When_DataHasMixedVideoAndCarousel()
+    {
+        await using var client = CreateClient(TikTokFixtures.MixedVideoAndCarouselSearchJson);
+
+        var results = await CollectAsync(client.SearchAsync("mixed"));
+
+        results.Should().HaveCount(2);
+        results.Should().ContainSingle(m => m is Video);
+        results.Should().ContainSingle(m => m is Carousel);
+    }
+
+    // ── Empty / missing data ──────────────────────────────────────────────────
+
+    [Fact]
+    public async Task Should_ReturnEmptySequence_When_DataArrayIsEmpty()
+    {
+        await using var client = CreateClient(TikTokFixtures.EmptyDataSearchJson);
+
+        var results = await CollectAsync(client.SearchAsync("test"));
+
+        results.Should().BeEmpty();
+    }
+
+    [Fact]
+    public async Task Should_ReturnEmptySequence_When_DataNodeIsMissing()
+    {
+        await using var client = CreateClient(TikTokFixtures.MissingDataSearchJson);
+
+        var results = await CollectAsync(client.SearchAsync("test"));
+
+        results.Should().BeEmpty();
+    }
+
+    // ── Error cases ───────────────────────────────────────────────────────────
+
+    [Fact]
+    public async Task Should_ThrowTiktokParsingException_When_ItemNodeIsMissing()
+    {
+        await using var client = CreateClient(TikTokFixtures.MissingItemSearchJson);
+
+        var act = async () => await CollectAsync(client.SearchAsync("test"));
+
+        await act.Should().ThrowAsync<TiktokParsingException>();
+    }
+
+    [Fact]
+    public async Task Should_ThrowTiktokParsingException_When_JsonRootIsNull()
+    {
+        // JsonNode.Parse("null") returns null → the parser wraps it as TiktokParsingException.
+        await using var client = CreateClient("null");
+
+        var act = async () => await CollectAsync(client.SearchAsync("test"));
+
+        await act.Should().ThrowAsync<TiktokParsingException>();
+    }
+}
diff --git a/TiktokExplode.Tests/Infrastructure/TikTokFixtures.cs b/TiktokExplode.Tests/Infrastructure/TikTokFixtures.cs
index 0f7a1f9..dce7028 100644
--- a/TiktokExplode.Tests/Infrastructure/TikTokFixtures.cs
+++ b/TiktokExplode.Tests/Infrastructure/TikTokFixtures.cs
@@ -121,4 +121,355 @@ private static string Wrap(string json) =>
 
   /// <summary>JSON root without <c>__DEFAULT_SCOPE__</c> → <see cref="Domain.Exceptions.TiktokParsingException"/>.</summary>
   public static readonly string MissingDefaultScopeHtml = Wrap("""{"other":"data"}""");
+
+  // ── Search fixtures ───────────────────────────────────────────────────────
+
+  /// <summary>A synthetic author block reused across search fixtures.</summary>
+  private const string SearchAuthorBlock = """
+        "author": {
+          "id": "888888888",
+          "uniqueId": "search_user",
+          "nickname": "Search User",
+          "signature": "Search bio",
+          "verified": true,
+          "privateAccount": false,
+          "createTime": 1600000000,
+          "avatarLarger": "https://example.com/sv_avatar_large.jpg",
+          "avatarMedium": "https://example.com/sv_avatar_medium.jpg",
+          "avatarThumb":  "https://example.com/sv_avatar_thumb.jpg"
+        },
+        "authorStatsV2": {
+          "followerCount": "2000",
+          "followingCount": "300",
+          "friendCount": "25",
+          "heartCount": "75000",
+          "videoCount": "50"
+        }
+        """;
+
+  /// <summary>A synthetic music block reused across search fixtures.</summary>
+  private const string SearchMusicBlock = """
+        "music": {
+          "id": "7000000000000000001",
+          "title": "Search Track",
+          "playUrl": "https://cdn.example.com/sv_music.mp3",
+          "coverThumb":  "https://cdn.example.com/sv_music_thumb.jpg",
+          "coverMedium": "https://cdn.example.com/sv_music_medium.jpg",
+          "coverLarge":  "https://cdn.example.com/sv_music_large.jpg",
+          "authorName": "Search Artist",
+          "album": "Search Album",
+          "original": false,
+          "private": false,
+          "duration": 20,
+          "isCopyrighted": true
+        }
+        """;
+
+  /// <summary>A synthetic stats block reused across search fixtures.</summary>
+  private const string SearchStatsBlock = """
+        "statsV2": {
+          "playCount":   "200000",
+          "diggCount":   "8000",
+          "commentCount":"500",
+          "shareCount":  "2000",
+          "collectCount":"600",
+          "repostCount": "100"
+        }
+        """;
+
+  /// <summary>Search JSON payload containing a single video result.</summary>
+  public static readonly string ValidVideoSearchJson = $$"""
+        {
+          "data": [
+            {
+              "type": 1,
+              "item": {
+                "id": "1111111111111111111",
+                "desc": "Search video description",
+                "createTime": 1700100000,
+                "textLanguage": "es",
+                "textTranslatable": false,
+                "locationCreated": "MX",
+                {{SearchAuthorBlock}},
+                "video": {
+                  "ratio": "1080p",
+                  "videoQuality": "normal",
+                  "width": 1080,
+                  "height": 1920,
+                  "duration": 20,
+                  "preciseDuration": 20.75,
+                  "cover": "https://cdn.example.com/sv_cover.jpg",
+                  "dynamicCover": "https://cdn.example.com/sv_cover.webp",
+                  "playAddr":    "https://cdn.example.com/sv_play.mp4",
+                  "downloadAddr":"https://cdn.example.com/sv_download.mp4",
+                  "size": "5242880",
+                  "bitrateInfo": [
+                    {
+                      "Bitrate": 2000000,
+                      "BitrateFPS": 60,
+                      "Format": "mp4",
+                      "CodecType": "h265"
+                    }
+                  ]
+                },
+                {{SearchMusicBlock}},
+                {{SearchStatsBlock}}
+              }
+            }
+          ]
+        }
+        """;
+
+  /// <summary>Search JSON payload containing a single carousel (slideshow) result.</summary>
+  public static readonly string ValidCarouselSearchJson = $$"""
+        {
+          "data": [
+            {
+              "type": 1,
+              "item": {
+                "id": "2222222222222222222",
+                "desc": "Search carousel description",
+                "createTime": 1700200000,
+                "textLanguage": "en",
+                "textTranslatable": true,
+                "locationCreated": "US",
+                "author": {
+                  "id": "777777777",
+                  "uniqueId": "carousel_user",
+                  "nickname": "Carousel User",
+                  "signature": "Carousel bio",
+                  "verified": false,
+                  "privateAccount": false,
+                  "createTime": 1610000000,
+                  "avatarLarger": "https://example.com/cu_avatar_large.jpg",
+                  "avatarMedium": "https://example.com/cu_avatar_medium.jpg",
+                  "avatarThumb":  "https://example.com/cu_avatar_thumb.jpg"
+                },
+                "authorStatsV2": {
+                  "followerCount": "3000",
+                  "followingCount": "150",
+                  "friendCount": "10",
+                  "heartCount": "20000",
+                  "videoCount": "30"
+                },
+                "video": {
+                  "cover": "https://cdn.example.com/cu_video_cover.jpg",
+                  "dynamicCover": "https://cdn.example.com/cu_video_animated.webp"
+                },
+                "music": {
+                  "id": "6000000000000000001",
+                  "title": "Carousel Track",
+                  "playUrl": "https://cdn.example.com/cu_music.mp3",
+                  "coverThumb":  "https://cdn.example.com/cu_music_thumb.jpg",
+                  "coverMedium": "https://cdn.example.com/cu_music_medium.jpg",
+                  "coverLarge":  "https://cdn.example.com/cu_music_large.jpg",
+                  "authorName": "Carousel Artist",
+                  "album": "Carousel Album",
+                  "original": true,
+                  "private": false,
+                  "duration": 30,
+                  "isCopyrighted": false
+                },
+                "statsV2": {
+                  "playCount":   "50000",
+                  "diggCount":   "2000",
+                  "commentCount":"100",
+                  "shareCount":  "500",
+                  "collectCount":"150",
+                  "repostCount": "20"
+                },
+                "imagePost": {
+                  "title": "Carousel Title",
+                  "cover": {
+                    "imageWidth": 1080,
+                    "imageHeight": 1920,
+                    "imageURL": {
+                      "urlList": ["https://cdn.example.com/carousel_cover.jpg"]
+                    }
+                  },
+                  "images": [
+                    {
+                      "imageWidth": 1080,
+                      "imageHeight": 1920,
+                      "imageURL": {
+                        "urlList": ["https://cdn.example.com/slide1.jpg"]
+                      }
+                    },
+                    {
+                      "imageWidth": 720,
+                      "imageHeight": 1280,
+                      "imageURL": {
+                        "urlList": ["https://cdn.example.com/slide2.jpg", "https://cdn.example.com/slide2_fallback.jpg"]
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        }
+        """;
+
+  /// <summary>
+  /// Search JSON with a type=1 video entry plus a type=2 entry that must be skipped.
+  /// Expected parsed count: 1 (only the type=1 item).
+  /// </summary>
+  public static readonly string SearchJsonWithNonTypeOneEntry = $$"""
+        {
+          "data": [
+            {
+              "type": 2,
+              "item": { "id": "should_be_skipped" }
+            },
+            {
+              "type": 1,
+              "item": {
+                "id": "1111111111111111111",
+                "desc": "Search video description",
+                "createTime": 1700100000,
+                "textLanguage": "es",
+                "textTranslatable": false,
+                "locationCreated": "MX",
+                {{SearchAuthorBlock}},
+                "video": {
+                  "ratio": "1080p",
+                  "videoQuality": "normal",
+                  "width": 1080,
+                  "height": 1920,
+                  "duration": 20,
+                  "preciseDuration": 20.75,
+                  "cover": "https://cdn.example.com/sv_cover.jpg",
+                  "dynamicCover": "https://cdn.example.com/sv_cover.webp",
+                  "playAddr":    "https://cdn.example.com/sv_play.mp4",
+                  "downloadAddr":"https://cdn.example.com/sv_download.mp4",
+                  "size": "5242880",
+                  "bitrateInfo": [
+                    { "Bitrate": 2000000, "BitrateFPS": 60, "Format": "mp4", "CodecType": "h265" }
+                  ]
+                },
+                {{SearchMusicBlock}},
+                {{SearchStatsBlock}}
+              }
+            }
+          ]
+        }
+        """;
+
+  /// <summary>Search JSON with both a video and a carousel entry (both type=1).</summary>
+  public static readonly string MixedVideoAndCarouselSearchJson = $$"""
+        {
+          "data": [
+            {
+              "type": 1,
+              "item": {
+                "id": "1111111111111111111",
+                "desc": "Search video description",
+                "createTime": 1700100000,
+                "textLanguage": "es",
+                "textTranslatable": false,
+                "locationCreated": "MX",
+                {{SearchAuthorBlock}},
+                "video": {
+                  "ratio": "1080p",
+                  "videoQuality": "normal",
+                  "width": 1080,
+                  "height": 1920,
+                  "duration": 20,
+                  "preciseDuration": 20.75,
+                  "cover": "https://cdn.example.com/sv_cover.jpg",
+                  "dynamicCover": "https://cdn.example.com/sv_cover.webp",
+                  "playAddr":    "https://cdn.example.com/sv_play.mp4",
+                  "downloadAddr":"https://cdn.example.com/sv_download.mp4",
+                  "size": "5242880",
+                  "bitrateInfo": [
+                    { "Bitrate": 2000000, "BitrateFPS": 60, "Format": "mp4", "CodecType": "h265" }
+                  ]
+                },
+                {{SearchMusicBlock}},
+                {{SearchStatsBlock}}
+              }
+            },
+            {
+              "type": 1,
+              "item": {
+                "id": "2222222222222222222",
+                "desc": "Search carousel description",
+                "createTime": 1700200000,
+                "textLanguage": "en",
+                "textTranslatable": true,
+                "locationCreated": "US",
+                "author": {
+                  "id": "777777777",
+                  "uniqueId": "carousel_user",
+                  "nickname": "Carousel User",
+                  "signature": "",
+                  "verified": false,
+                  "privateAccount": false,
+                  "createTime": 1610000000,
+                  "avatarLarger": "https://example.com/cu_avatar_large.jpg",
+                  "avatarMedium": "https://example.com/cu_avatar_medium.jpg",
+                  "avatarThumb":  "https://example.com/cu_avatar_thumb.jpg"
+                },
+                "authorStatsV2": {
+                  "followerCount": "3000",
+                  "followingCount": "150",
+                  "friendCount": "10",
+                  "heartCount": "20000",
+                  "videoCount": "30"
+                },
+                "video": {
+                  "cover": "https://cdn.example.com/cu_video_cover.jpg",
+                  "dynamicCover": "https://cdn.example.com/cu_video_animated.webp"
+                },
+                "music": {
+                  "id": "6000000000000000001",
+                  "title": "Carousel Track",
+                  "playUrl": "https://cdn.example.com/cu_music.mp3",
+                  "coverThumb":  "https://cdn.example.com/cu_music_thumb.jpg",
+                  "coverMedium": "https://cdn.example.com/cu_music_medium.jpg",
+                  "coverLarge":  "https://cdn.example.com/cu_music_large.jpg",
+                  "authorName": "Carousel Artist",
+                  "album": "Carousel Album",
+                  "original": true,
+                  "private": false,
+                  "duration": 30,
+                  "isCopyrighted": false
+                },
+                "statsV2": {
+                  "playCount":   "50000",
+                  "diggCount":   "2000",
+                  "commentCount":"100",
+                  "shareCount":  "500",
+                  "collectCount":"150",
+                  "repostCount": "20"
+                },
+                "imagePost": {
+                  "title": "Carousel Title",
+                  "cover": {
+                    "imageWidth": 1080,
+                    "imageHeight": 1920,
+                    "imageURL": { "urlList": ["https://cdn.example.com/carousel_cover.jpg"] }
+                  },
+                  "images": [
+                    {
+                      "imageWidth": 1080,
+                      "imageHeight": 1920,
+                      "imageURL": { "urlList": ["https://cdn.example.com/slide1.jpg"] }
+                    }
+                  ]
+                }
+              }
+            }
+          ]
+        }
+        """;
+
+  /// <summary>Search JSON with an empty <c>data</c> array → no results.</summary>
+  public static readonly string EmptyDataSearchJson = """{ "data": [] }""";
+
+  /// <summary>Search JSON without a <c>data</c> node → no results (parser falls back to empty array).</summary>
+  public static readonly string MissingDataSearchJson = """{ "other": "value" }""";
+
+  /// <summary>Search JSON with a type=1 entry that is missing its <c>item</c> node → <see cref="Domain.Exceptions.TiktokParsingException"/>.</summary>
+  public static readonly string MissingItemSearchJson = """{ "data": [{ "type": 1 }] }""";
 }

From ececa1a3cd6d67f201e11fa43c3beeb4292ad57b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Thu, 11 Jun 2026 00:12:46 -0500
Subject: [PATCH 12/18] Enhanced the `Media` class with an abstract `Url`
 property, implemented in `Video` and `Carousel` to generate TikTok-specific
 URLs.

XML documentation has been added to the missing classes
---
 TiktokExplode.Console/Program.cs              | 47 ++++++++++++++-----
 TiktokExplode/Domain/Entities/Carousel.cs     | 13 ++++-
 TiktokExplode/Domain/Entities/Media.cs        |  3 ++
 TiktokExplode/Domain/Entities/Video.cs        |  3 ++
 .../ValueObjects/Carousels/CarouselImage.cs   | 15 ++++++
 .../ValueObjects/Carousels/CarouselPost.cs    | 17 ++++++-
 6 files changed, 84 insertions(+), 14 deletions(-)

diff --git a/TiktokExplode.Console/Program.cs b/TiktokExplode.Console/Program.cs
index 5411c25..08c5b52 100644
--- a/TiktokExplode.Console/Program.cs
+++ b/TiktokExplode.Console/Program.cs
@@ -77,40 +77,47 @@ static async Task FetchAndDownloadAsync(IVideoClient client, string url)
 static async Task SearchAndDownloadAsync(ISearchClient client, string keyword, int maxResults)
 {
     const string Sep = "─────────────────────────────────────────";
-    var videos = new List<Video>();
+    var mediaList = new List<Media>();
 
     try
     {
         Console.Write($"Searching for \"{keyword}\"...");
-        await foreach (var video in client.SearchAsync(keyword))
+        await foreach (var media in client.SearchAsync(keyword))
         {
-            videos.Add(video);
-            if (videos.Count >= maxResults) break;
+            mediaList.Add(media);
+            if (mediaList.Count >= maxResults) break;
         }
-        Console.WriteLine($" found {videos.Count} result(s).");
+        Console.WriteLine($" found {mediaList.Count} result(s).");
     }
     catch (TiktokWafException ex) { Console.WriteLine($"\n[WAF] {ex.Message}"); return; }
     catch (TiktokException ex)    { Console.WriteLine($"\n[Error] {ex.Message}"); return; }
 
-    if (videos.Count == 0)
+    if (mediaList.Count == 0)
     {
         Console.WriteLine("No results.");
         return;
     }
 
     Console.WriteLine(Sep);
-    for (int i = 0; i < videos.Count; i++)
-        PrintVideo(videos[i], i + 1, videos.Count);
+    for (int i = 0; i < mediaList.Count; i++)
+    {
+        var media = mediaList[i];
+        if(media is Video video)
+            PrintVideo(video, i + 1, mediaList.Count);
+        else if (media is Carousel carousel)
+            PrintCarousel(carousel, i + 1, mediaList.Count);
+    }
+        
 
-    Console.Write($"\nDownload which video? (1-{videos.Count}, or Enter to skip): ");
+    Console.Write($"\nDownload which video? (1-{mediaList.Count}, or Enter to skip): ");
     var pick = Console.ReadLine()?.Trim();
-    if (!int.TryParse(pick, out var idx) || idx < 1 || idx > videos.Count)
+    if (!int.TryParse(pick, out var idx) || idx < 1 || idx > mediaList.Count)
     {
         Console.WriteLine("Skipping download.");
         return;
     }
-
-    await PromptDownloadAsync(client, videos[idx - 1]);
+    if (mediaList[idx - 1] is Video video2)
+        await PromptDownloadAsync(client, video2);
 }
 
 static void PrintVideo(Video video, int index, int total)
@@ -118,6 +125,8 @@ static void PrintVideo(Video video, int index, int total)
     const string Sep = "─────────────────────────────────────────";
     Console.WriteLine(Sep);
     if (total > 1) Console.WriteLine($"  [{index}/{total}]");
+    Console.WriteLine($"  Type        Video");
+    Console.WriteLine($"  URL         {video.Url}");
     Console.WriteLine($"  ID          {video.Id}");
     Console.WriteLine($"  Author      {video.Author.Name} (@{video.Author.UniqueId})");
     Console.WriteLine($"  Duration    {video.Duration.Seconds}s");
@@ -126,6 +135,20 @@ static void PrintVideo(Video video, int index, int total)
     Console.WriteLine($"  Size        {video.Info.DownloadLinks.OriginalSizeInBytes / (1_024 * 1_024):F2} MB");
 }
 
+static void PrintCarousel(Carousel carousel, int index, int total)
+{
+    const string Sep = "─────────────────────────────────────────";
+    Console.WriteLine(Sep);
+    if (total > 1) Console.WriteLine($"  [{index}/{total}]");
+    Console.WriteLine($"  Type        Carousel");
+    Console.WriteLine($"  URL         {carousel.Url}");
+    Console.WriteLine($"  ID          {carousel.Id}");
+    Console.WriteLine($"  Author      {carousel.Author.Name} (@{carousel.Author.UniqueId})");
+    Console.WriteLine($"  Views       {carousel.Stats.Views:N0}");
+    Console.WriteLine($"  Likes       {carousel.Stats.Likes:N0}");
+    Console.WriteLine($"  Carousel items: {carousel.Post.Images.Count}");
+}
+
 static async Task PromptDownloadAsync(IDownloadClient client, Video video)
 {
     const string Sep = "─────────────────────────────────────────";
diff --git a/TiktokExplode/Domain/Entities/Carousel.cs b/TiktokExplode/Domain/Entities/Carousel.cs
index 6375bea..ebcfd8f 100644
--- a/TiktokExplode/Domain/Entities/Carousel.cs
+++ b/TiktokExplode/Domain/Entities/Carousel.cs
@@ -2,7 +2,18 @@
 
 namespace TiktokExplode.Domain.Entities;
 
+/// <summary>
+/// Represents a TikTok image carousel post, which contains multiple images in a single post.
+/// </summary>
 public sealed class Carousel : Media
 {
-    public CarouselPost Post { get; init; }
+    /// <summary>
+    /// The content of the carousel post, including all images and related metadata
+    /// such as the total number of images, the index of the currently displayed image,
+    /// and any captions or descriptions for each image.
+    /// </summary>
+    public CarouselPost Post { get; init; } = new();
+
+    /// <summary>The URL of the carousel post on TikTok's website.</summary>
+    public override string Url => $"https://www.tiktok.com/@{Author.UniqueId}/photo/{Id}";
 }
diff --git a/TiktokExplode/Domain/Entities/Media.cs b/TiktokExplode/Domain/Entities/Media.cs
index 4d7eb41..401ada5 100644
--- a/TiktokExplode/Domain/Entities/Media.cs
+++ b/TiktokExplode/Domain/Entities/Media.cs
@@ -11,6 +11,9 @@ public abstract class Media
     /// <summary>The unique TikTok-assigned numeric identifier for this video.</summary>
     public string Id { get; init; } = string.Empty;
 
+    /// <summary>The URL of the media on TikTok's website.</summary>
+    public abstract string Url { get; }
+
     /// <summary>The caption or description text of the video, as written by the author.</summary>
     public string Description { get; init; } = string.Empty;
 
diff --git a/TiktokExplode/Domain/Entities/Video.cs b/TiktokExplode/Domain/Entities/Video.cs
index 59761a4..0b2d94f 100644
--- a/TiktokExplode/Domain/Entities/Video.cs
+++ b/TiktokExplode/Domain/Entities/Video.cs
@@ -14,4 +14,7 @@ public sealed class Video : Media
 
     /// <summary>The playback duration of the video.</summary>
     public VideoDuration Duration { get; init; }
+
+    /// <summary>The URL of the video on TikTok's website.</summary>
+    public override string Url => $"https://www.tiktok.com/@{Author.UniqueId}/video/{Id}";
 }
diff --git a/TiktokExplode/Domain/ValueObjects/Carousels/CarouselImage.cs b/TiktokExplode/Domain/ValueObjects/Carousels/CarouselImage.cs
index 00501c7..f378774 100644
--- a/TiktokExplode/Domain/ValueObjects/Carousels/CarouselImage.cs
+++ b/TiktokExplode/Domain/ValueObjects/Carousels/CarouselImage.cs
@@ -1,8 +1,23 @@
 namespace TiktokExplode.Domain.ValueObjects.Carousels;
 
+/// <summary>
+/// Represents an individual image within a TikTok carousel post, 
+/// including its dimensions and available URLs for different resolutions.
+/// </summary>
 public sealed class CarouselImage
 {
+    /// <summary>
+    /// The width of the image in pixels. This can be used to determine the aspect ratio.
+    /// </summary>
     public uint Width { get; init; }
+
+    /// <summary>
+    /// The height of the image in pixels. This can be used to determine the aspect ratio.
+    /// </summary>
     public uint Height { get; init; }
+
+    /// <summary>
+    /// A list of URLs for the image at different resolutions.
+    /// </summary>
     public IReadOnlyList<string> Urls { get; init; } = [];
 }
diff --git a/TiktokExplode/Domain/ValueObjects/Carousels/CarouselPost.cs b/TiktokExplode/Domain/ValueObjects/Carousels/CarouselPost.cs
index f66b504..3167710 100644
--- a/TiktokExplode/Domain/ValueObjects/Carousels/CarouselPost.cs
+++ b/TiktokExplode/Domain/ValueObjects/Carousels/CarouselPost.cs
@@ -1,8 +1,23 @@
 namespace TiktokExplode.Domain.ValueObjects.Carousels;
 
+/// <summary>
+/// Represents the content of a TikTok image carousel post, including all images and related metadata
+/// </summary>
 public sealed class CarouselPost
 {
+    /// <summary>
+    /// The total number of images in the carousel. This indicates how many images are included in the post.
+    /// </summary>
     public string Title { get; init; } = string.Empty;
-    public CarouselImage Cover { get; init; }
+
+    /// <summary>
+    /// The index of the currently displayed image in the carousel. This is a 1-based index 
+    /// indicating which image is currently being viewed by the user.
+    /// </summary>
+    public CarouselImage Cover { get; init; } = new();
+
+    /// <summary>
+    /// A list of all images included in the carousel post, along with their metadata such as dimensions and URLs.
+    /// </summary>
     public IReadOnlyList<CarouselImage> Images { get; init; } = [];
 }

From 40fb1151565cc7831d17c0842a94ef1e1c230cf7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Thu, 11 Jun 2026 00:13:14 -0500
Subject: [PATCH 13/18] Add integration tests and update package versions

Updated the CI pipeline to include integration tests, which run on pull requests targeting the `master` branch.

Renamed the `Build & Test` job to `Build & Unit Tests` for clarity.

Bumped package versions in `.csproj` files:
- `TiktokExplode.All.csproj`: 1.1.1 -> 1.2.0
- `TiktokExplode.Extensions.DependencyInjection.csproj`: 1.0.0 -> 1.1.0
- `TiktokExplode.Infrastructure.csproj`: 1.1.1 -> 1.2.0
- `TiktokExplode.csproj`: 1.1.1 -> 1.2.0
---
 .github/workflows/ci.yml                      | 33 +++++++++++++++++--
 TiktokExplode.All/TiktokExplode.All.csproj    |  2 +-
 ...lode.Extensions.DependencyInjection.csproj |  2 +-
 .../TiktokExplode.Infrastructure.csproj       |  2 +-
 TiktokExplode/TiktokExplode.csproj            |  2 +-
 5 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 38d9787..dcd741e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -4,12 +4,13 @@ on:
   push:
     branches: ["master"]
     tags: ["v*"]
+
   pull_request:
     branches: ["master"]
 
 jobs:
   build-and-test:
-    name: Build & Test
+    name: Build & Unit Tests
     runs-on: ubuntu-latest
 
     steps:
@@ -29,9 +30,37 @@ jobs:
       - name: Build
         run: dotnet build TiktokExplode.NET.slnx --no-restore --configuration Release
 
-      - name: Run tests
+      - name: Run Unit Tests
         run: dotnet test TiktokExplode.Tests/TiktokExplode.Tests.csproj --no-build --configuration Release --logger "console;verbosity=normal"
 
+  integration-tests:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: |
+            8.0.x
+            9.0.x
+
+      - name: Restore dependencies
+        run: dotnet restore TiktokExplode.NET.slnx
+
+      - name: Build
+        run: dotnet build TiktokExplode.NET.slnx --no-restore --configuration Release
+
+      - name: Install Playwright Browsers
+        run: pwsh TiktokExplode.IntegrationTests/bin/Release/net9.0/playwright.ps1 install
+
+      - name: Run Integration Tests
+        run: dotnet test TiktokExplode.IntegrationTests/TiktokExplode.IntegrationTests.csproj --no-build --configuration Release --logger "console;verbosity=normal"
+
   publish:
     name: Publish to NuGet
     runs-on: ubuntu-latest
diff --git a/TiktokExplode.All/TiktokExplode.All.csproj b/TiktokExplode.All/TiktokExplode.All.csproj
index a08d921..763b0c4 100644
--- a/TiktokExplode.All/TiktokExplode.All.csproj
+++ b/TiktokExplode.All/TiktokExplode.All.csproj
@@ -10,7 +10,7 @@
 
   <PropertyGroup>
     <PackageId>TiktokExplode.All</PackageId>
-    <Version>1.1.1</Version>
+    <Version>1.2.0</Version>
     <Authors>Ts-Pytham</Authors>
     <Owners>Ts-Pytham</Owners>
     <Description>Meta-package that installs TiktokExplode (domain layer) and TiktokExplode.Infrastructure (HTTP/browser fetchers, parser, download client) in a single command.</Description>
diff --git a/TiktokExplode.Extensions.DependencyInjection/TiktokExplode.Extensions.DependencyInjection.csproj b/TiktokExplode.Extensions.DependencyInjection/TiktokExplode.Extensions.DependencyInjection.csproj
index 21ac446..af76ab9 100644
--- a/TiktokExplode.Extensions.DependencyInjection/TiktokExplode.Extensions.DependencyInjection.csproj
+++ b/TiktokExplode.Extensions.DependencyInjection/TiktokExplode.Extensions.DependencyInjection.csproj
@@ -12,7 +12,7 @@
 
   <PropertyGroup>
     <PackageId>TiktokExplode.Extensions.DependencyInjection</PackageId>
-    <Version>1.0.0</Version>
+    <Version>1.1.0</Version>
     <Authors>Ts-Pytham</Authors>
     <Owners>Ts-Pytham</Owners>
     <Description>Microsoft.Extensions.DependencyInjection integration for TiktokExplode. Provides AddTiktokExplode() with a fluent builder to register IVideoClient and choose between Playwright or HTTP fetcher strategies.</Description>
diff --git a/TiktokExplode.Infrastructure/TiktokExplode.Infrastructure.csproj b/TiktokExplode.Infrastructure/TiktokExplode.Infrastructure.csproj
index 45a3b5c..d26eba5 100644
--- a/TiktokExplode.Infrastructure/TiktokExplode.Infrastructure.csproj
+++ b/TiktokExplode.Infrastructure/TiktokExplode.Infrastructure.csproj
@@ -12,7 +12,7 @@
 
   <PropertyGroup>
     <PackageId>TiktokExplode.Infrastructure</PackageId>
-    <Version>1.1.1</Version>
+    <Version>1.2.0</Version>
     <Authors>Ts-Pytham</Authors>
     <Owners>Ts-Pytham</Owners>
     <Description>Infrastructure layer for TiktokExplode: HTTP and Playwright-based page fetchers, TikTok video parser, CDN download client, and WAF-retry logic.</Description>
diff --git a/TiktokExplode/TiktokExplode.csproj b/TiktokExplode/TiktokExplode.csproj
index d3e4735..44620ea 100644
--- a/TiktokExplode/TiktokExplode.csproj
+++ b/TiktokExplode/TiktokExplode.csproj
@@ -11,7 +11,7 @@
 
   <PropertyGroup>
     <PackageId>TiktokExplode</PackageId>
-    <Version>1.1.1</Version>
+    <Version>1.2.0</Version>
     <Authors>Ts-Pytham</Authors>
     <Owners>Ts-Pytham</Owners>
     <Description>Domain layer for TiktokExplode: strongly-typed models, interfaces, and utilities for working with TikTok video metadata. Zero external dependencies.</Description>

From 941ab699b5403e2f0377fb06f94942973b3119fb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Thu, 11 Jun 2026 00:17:26 -0500
Subject: [PATCH 14/18] Remove LiaProgramacion project reference

---
 TiktokExplode.NET.slnx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/TiktokExplode.NET.slnx b/TiktokExplode.NET.slnx
index f3b753f..d4d0750 100644
--- a/TiktokExplode.NET.slnx
+++ b/TiktokExplode.NET.slnx
@@ -1,5 +1,4 @@
 <Solution>
-  <Project Path="../LiaProgramacion/LiaProgramacion/LiaProgramacion.csproj" />
   <Project Path="TiktokExplode.All/TiktokExplode.All.csproj" />
   <Project Path="TiktokExplode.Console/TiktokExplode.Console.csproj" />
   <Project Path="TiktokExplode.Extensions.DependencyInjection/TiktokExplode.Extensions.DependencyInjection.csproj" />

From 67f3bff03815b2a3df80462f4573b09333945d59 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Thu, 11 Jun 2026 09:35:11 -0500
Subject: [PATCH 15/18] Eliminate integration testing in CI

---
 .github/workflows/ci.yml | 28 ----------------------------
 1 file changed, 28 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index dcd741e..97d24a0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -33,34 +33,6 @@ jobs:
       - name: Run Unit Tests
         run: dotnet test TiktokExplode.Tests/TiktokExplode.Tests.csproj --no-build --configuration Release --logger "console;verbosity=normal"
 
-  integration-tests:
-    name: Integration Tests
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup .NET
-        uses: actions/setup-dotnet@v4
-        with:
-          dotnet-version: |
-            8.0.x
-            9.0.x
-
-      - name: Restore dependencies
-        run: dotnet restore TiktokExplode.NET.slnx
-
-      - name: Build
-        run: dotnet build TiktokExplode.NET.slnx --no-restore --configuration Release
-
-      - name: Install Playwright Browsers
-        run: pwsh TiktokExplode.IntegrationTests/bin/Release/net9.0/playwright.ps1 install
-
-      - name: Run Integration Tests
-        run: dotnet test TiktokExplode.IntegrationTests/TiktokExplode.IntegrationTests.csproj --no-build --configuration Release --logger "console;verbosity=normal"
-
   publish:
     name: Publish to NuGet
     runs-on: ubuntu-latest

From 08258e9600f6f9948be5ac469e6e3e757fe6dad5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Thu, 11 Jun 2026 18:47:16 -0500
Subject: [PATCH 16/18] feat: add carousel image download support

Add support for downloading TikTok carousel images.

- Implement DownloadImageAsync
- Implement DownloadCarouselImagesAsync
- Add progress reporting support
- Rename PromptDownloadAsync
- Add PromptDownloadCarouselAsync
- Generalize media download abstractions
- Improve URL handling and parsers
---
 TiktokExplode.Console/Program.cs              | 52 ++++++++++-
 .../Clients/TiktokClient.cs                   | 12 ++-
 .../Clients/TiktokSearchClient.cs             | 12 ++-
 ...ensions.cs => DownloadClientExtensions.cs} | 87 ++++++++++++++++++-
 .../Http/TikTokDownloadClient.cs              | 29 ++++---
 .../Parsers/TikTokVideoParser.cs              |  2 +-
 .../Domain/Abstractions/IDownloadClient.cs    | 13 +++
 7 files changed, 184 insertions(+), 23 deletions(-)
 rename TiktokExplode.Infrastructure/Common/{TiktokClientExtensions.cs => DownloadClientExtensions.cs} (58%)

diff --git a/TiktokExplode.Console/Program.cs b/TiktokExplode.Console/Program.cs
index 08c5b52..74065da 100644
--- a/TiktokExplode.Console/Program.cs
+++ b/TiktokExplode.Console/Program.cs
@@ -67,7 +67,7 @@ static async Task FetchAndDownloadAsync(IVideoClient client, string url)
         var video = await client.GetVideoAsync(url);
         Console.WriteLine(" done.");
         PrintVideo(video, 1, 1);
-        await PromptDownloadAsync((IDownloadClient)client, video);
+        await PromptDownloadVideoAsync(client, video);
     }
     catch (TiktokWafException ex)  { Console.WriteLine($"\n[WAF] {ex.Message}"); }
     catch (VideoNotFoundException ex) { Console.WriteLine($"\n[404] {ex.Message}"); }
@@ -117,7 +117,9 @@ static async Task SearchAndDownloadAsync(ISearchClient client, string keyword, i
         return;
     }
     if (mediaList[idx - 1] is Video video2)
-        await PromptDownloadAsync(client, video2);
+        await PromptDownloadVideoAsync(client, video2);
+    else if (mediaList[idx - 1] is Carousel carousel2)
+        await PromptDownloadCarouselAsync(client, carousel2);
 }
 
 static void PrintVideo(Video video, int index, int total)
@@ -149,7 +151,7 @@ static void PrintCarousel(Carousel carousel, int index, int total)
     Console.WriteLine($"  Carousel items: {carousel.Post.Images.Count}");
 }
 
-static async Task PromptDownloadAsync(IDownloadClient client, Video video)
+static async Task PromptDownloadVideoAsync(IDownloadClient client, Video video)
 {
     const string Sep = "─────────────────────────────────────────";
     Console.WriteLine(Sep);
@@ -184,3 +186,47 @@ static async Task PromptDownloadAsync(IDownloadClient client, Video video)
 
     Console.WriteLine(Sep);
 }
+
+static async Task PromptDownloadCarouselAsync(
+    IDownloadClient client,
+    Carousel carousel)
+{
+    const string Sep = "─────────────────────────────────────────";
+
+    Console.WriteLine(Sep);
+
+    Console.Write("Download images? [Y/n]: ");
+    var dl = Console.ReadLine()?.Trim();
+
+    if (!string.IsNullOrEmpty(dl) &&
+        !dl.Equals("y", StringComparison.OrdinalIgnoreCase))
+    {
+        Console.WriteLine("Skipped.");
+        return;
+    }
+
+    var directoryName =
+        $"{carousel.Id}_{carousel.Author.UniqueId}_images";
+
+    Console.WriteLine($"Saving to: {directoryName}");
+
+    IProgress<double> progress =
+        new Progress<double>(p =>
+            Console.Write($"\r  Downloading... {p:P0}   "));
+
+    try
+    {
+        await client.DownloadCarouselImagesAsync(
+            carousel,
+            directoryName,
+            progress);
+
+        Console.WriteLine($"\n  Saved: {directoryName}");
+    }
+    catch (TiktokException ex)
+    {
+        Console.WriteLine($"\n[Error] {ex.Message}");
+    }
+
+    Console.WriteLine(Sep);
+}
\ No newline at end of file
diff --git a/TiktokExplode.Infrastructure/Clients/TiktokClient.cs b/TiktokExplode.Infrastructure/Clients/TiktokClient.cs
index 0a80ec5..d7c6552 100644
--- a/TiktokExplode.Infrastructure/Clients/TiktokClient.cs
+++ b/TiktokExplode.Infrastructure/Clients/TiktokClient.cs
@@ -4,6 +4,7 @@
 using TiktokExplode.Domain.Exceptions;
 using TiktokExplode.Domain.Utilities;
 using TiktokExplode.Domain.ValueObjects;
+using TiktokExplode.Domain.ValueObjects.Carousels;
 using TiktokExplode.Infrastructure.Fetchers;
 using TiktokExplode.Infrastructure.Http;
 using TiktokExplode.Infrastructure.Options;
@@ -68,7 +69,7 @@ public async Task<Video> GetVideoAsync(string url, CancellationToken cancellatio
     internal Task<StreamInfo> DownloadCoreAsync(
         string url,
         CancellationToken cancellationToken = default)
-        => _downloadClient.DownloadVideoAsync(url, cancellationToken);
+        => _downloadClient.DownloadAsync(url, cancellationToken);
 
     /// <inheritdoc/>
     public async Task<StreamInfo> DownloadAsync(Video video, CancellationToken cancellationToken = default)
@@ -88,6 +89,15 @@ public async Task<StreamInfo> DownloadWatermarkedAsync(Video video, Cancellation
         return await DownloadCoreAsync(video.Info.DownloadLinks.WatermarkedUrl, cancellationToken);
     }
 
+    /// <inheritdoc/>
+    public Task<StreamInfo> DownloadImageAsync(CarouselImage image, CancellationToken cancellationToken = default)
+    {
+        var url = image.Urls.FirstOrDefault(u => !string.IsNullOrEmpty(u)) 
+            ?? throw new TiktokException("Image does not contain a valid download URL.");
+
+        return DownloadCoreAsync(url, cancellationToken);
+    }
+
     /// <summary>
     /// Disposes the download client and the page fetcher (supporting both
     /// <see cref="IAsyncDisposable"/> and <see cref="IDisposable"/> fetchers).
diff --git a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
index 23fc11f..b52c5e9 100644
--- a/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
+++ b/TiktokExplode.Infrastructure/Clients/TiktokSearchClient.cs
@@ -3,6 +3,7 @@
 using TiktokExplode.Domain.Entities;
 using TiktokExplode.Domain.Exceptions;
 using TiktokExplode.Domain.ValueObjects;
+using TiktokExplode.Domain.ValueObjects.Carousels;
 using TiktokExplode.Infrastructure.Fetchers.Search;
 using TiktokExplode.Infrastructure.Http;
 using TiktokExplode.Infrastructure.Options;
@@ -56,6 +57,15 @@ public async Task<StreamInfo> DownloadWatermarkedAsync(Video video, Cancellation
         return await DownloadCoreAsync(video.Info.DownloadLinks.WatermarkedUrl, cancellationToken);
     }
 
+    /// <inheritdoc/>
+    public Task<StreamInfo> DownloadImageAsync(CarouselImage image, CancellationToken cancellationToken = default)
+    {
+        var url = image.Urls.FirstOrDefault(u => !string.IsNullOrEmpty(u))
+            ?? throw new TiktokException("Image does not contain a valid download URL.");
+
+        return DownloadCoreAsync(url, cancellationToken);
+    }
+
     /// <summary>
     /// Core download helper that delegates to <see cref="TiktokDownloadClient"/>.
     /// Exposed as <c>internal</c> to allow unit-testing without a full <see cref="Video"/> graph.
@@ -65,7 +75,7 @@ public async Task<StreamInfo> DownloadWatermarkedAsync(Video video, Cancellation
     internal Task<StreamInfo> DownloadCoreAsync(
         string url,
         CancellationToken cancellationToken = default)
-        => _downloadClient.DownloadVideoAsync(url, cancellationToken);
+        => _downloadClient.DownloadAsync(url, cancellationToken);
 
     /// <inheritdoc/>
     public async ValueTask DisposeAsync()
diff --git a/TiktokExplode.Infrastructure/Common/TiktokClientExtensions.cs b/TiktokExplode.Infrastructure/Common/DownloadClientExtensions.cs
similarity index 58%
rename from TiktokExplode.Infrastructure/Common/TiktokClientExtensions.cs
rename to TiktokExplode.Infrastructure/Common/DownloadClientExtensions.cs
index 15795bb..67bf071 100644
--- a/TiktokExplode.Infrastructure/Common/TiktokClientExtensions.cs
+++ b/TiktokExplode.Infrastructure/Common/DownloadClientExtensions.cs
@@ -1,14 +1,17 @@
-using TiktokExplode.Domain.Abstractions;
+using AngleSharp.Dom;
+using TiktokExplode.Domain.Abstractions;
 using TiktokExplode.Domain.Entities;
 using TiktokExplode.Domain.Exceptions;
+using TiktokExplode.Domain.ValueObjects;
+using TiktokExplode.Domain.ValueObjects.Carousels;
 
 namespace TiktokExplode.Infrastructure.Common;
 
 /// <summary>
-/// Extension methods on <see cref="IVideoClient"/> for file-path-based downloads
+/// Extension methods on <see cref="IDownloadClient"/> for file-path-based downloads
 /// with optional progress reporting.
 /// </summary>
-public static class TiktokClientExtensions
+public static class DownloadClientExtensions
 {
     private static readonly HttpClient _httpClient = new();
 
@@ -52,9 +55,87 @@ public async Task DownloadWatermarkedAsync(
             await using var destination = File.Create(filePath);
             await using var streamInfo = await client.DownloadWatermarkedAsync(
                 video, cancellationToken);
+
+            await streamInfo.Stream.CopyToAsync(destination, streamInfo.ContentLength, progress, cancellationToken);
+        }
+
+        /// <summary>
+        /// Downloads the carousel image directly to a file at <paramref name="filePath"/>.
+        /// Reports download progress as a 0.0–1.0 fraction via <paramref name="progress"/> if provided.
+        /// </summary>
+        /// <param name="image">The carousel image to download.</param>
+        /// <param name="filePath">Path to the output file. The file is created or overwritten.</param>
+        /// <param name="progress">Optional callback for progress updates (0.0 = start, 1.0 = complete).</param>
+        /// <param name="cancellationToken">Token to cancel the operation.</param>
+        public async Task DownloadImageAsync(
+            CarouselImage image,
+            string filePath = "image.jpg",
+            IProgress<double>? progress = null,
+            CancellationToken cancellationToken = default)
+        {
+            await using var destination = File.Create(filePath);
+            await using var streamInfo = await client.DownloadImageAsync(image, cancellationToken);
+
             await streamInfo.Stream.CopyToAsync(destination, streamInfo.ContentLength, progress, cancellationToken);
         }
 
+        /// <summary>
+        /// Downloads all images of the carousel to files in <paramref name="directoryPath"/>.
+        /// Files are named <c>image_1.jpg</c>, <c>image_2.jpg</c>, etc. The directory is created if it doesn't exist.
+        /// Reports overall download progress as a 0.0–1.0 fraction via <paramref name="progress"/> if provided.
+        /// </summary>
+        /// <param name="carousel">The carousel containing the images to download.</param>
+        /// <param name="directoryPath">Path to the directory where images will be saved.</param>
+        /// <param name="progress">Optional callback for progress updates (0.0 = start, 1.0 = complete).</param>
+        /// <param name="cancellationToken">Token to cancel the operation.</param>
+        public async Task DownloadCarouselImagesAsync(
+            Carousel carousel,
+            string directoryPath,
+            IProgress<double>? progress = null,
+            CancellationToken cancellationToken = default)
+        {
+            Directory.CreateDirectory(directoryPath);
+
+            var images = carousel.Post.Images;
+
+            if (images.Count == 0)
+            {
+                progress?.Report(1.0);
+                return;
+            }
+
+            for (int i = 0; i < images.Count; i++)
+            {
+                var image = images[i];
+                var filePath = Path.Combine(directoryPath, $"image_{i + 1}.jpg");
+
+                var completedImages = i;
+
+                var imageProgress = progress is null
+                    ? null
+                    : new Progress<double>(p =>
+                    {
+                        var overallProgress =
+                            (completedImages + p) / images.Count;
+
+                        progress.Report(overallProgress);
+                    });
+
+                await using var destination = File.Create(filePath);
+
+                await using var streamInfo =
+                    await client.DownloadImageAsync(image, cancellationToken);
+
+                await streamInfo.Stream.CopyToAsync(
+                    destination,
+                    streamInfo.ContentLength,
+                    imageProgress,
+                    cancellationToken);
+            }
+
+            progress?.Report(1.0);
+        }
+
         /// <summary>
         /// Downloads the static cover image of <paramref name="video"/> to a file at <paramref name="filePath"/>.
         /// </summary>
diff --git a/TiktokExplode.Infrastructure/Http/TikTokDownloadClient.cs b/TiktokExplode.Infrastructure/Http/TikTokDownloadClient.cs
index 2c79acd..bfc76d0 100644
--- a/TiktokExplode.Infrastructure/Http/TikTokDownloadClient.cs
+++ b/TiktokExplode.Infrastructure/Http/TikTokDownloadClient.cs
@@ -9,7 +9,7 @@ namespace TiktokExplode.Infrastructure.Http;
 /// Maintains a <see cref="CookieContainer"/> that is populated with browser session cookies
 /// before each download to satisfy TikTok's authentication requirements.
 /// </summary>
-public sealed class TiktokDownloadClient : IDisposable
+internal sealed class TiktokDownloadClient : IDisposable
 {
     /// <summary>Shared cookie container for all requests made by this client.</summary>
     private readonly CookieContainer _cookies = new();
@@ -117,42 +117,43 @@ private void ConfigureDefaultHeaders()
     /// <c>Content-Length</c> response header.
     /// The caller is responsible for disposing the returned <see cref="StreamInfo"/>.
     /// </summary>
-    /// <param name="url">The CDN download URL for the video.</param>
+    /// <param name="url">The CDN download URL for the media.</param>
     /// <param name="cancellationToken">Token to cancel the operation.</param>
     /// <returns>
     /// A <see cref="StreamInfo"/> where <see cref="StreamInfo.ContentLength"/> is the value of
     /// the CDN <c>Content-Length</c> header, or <c>-1</c> if not present.
     /// </returns>
-    /// <exception cref="System.Net.Http.HttpRequestException">
+    /// <exception cref="HttpRequestException">
     /// Thrown if the CDN returns a non-success status code.
     /// </exception>
-    public async Task<StreamInfo> DownloadVideoAsync(
+    internal async Task<StreamInfo> DownloadAsync(
         string url,
         CancellationToken cancellationToken = default)
     {
-        var videoRequest = new HttpRequestMessage(
+        var request = new HttpRequestMessage(
             HttpMethod.Get,
             url)
         {
             Version = HttpVersion.Version11
         };
 
-        videoRequest.Headers.Referrer = new Uri("https://www.tiktok.com/");
+        request.Headers.Referrer = new Uri("https://www.tiktok.com/");
 
-        var videoResponse = await _httpClient.SendAsync(
-            videoRequest,
+        var response = await _httpClient.SendAsync(
+            request,
             HttpCompletionOption.ResponseHeadersRead,
             cancellationToken);
 
-        if (!videoResponse.IsSuccessStatusCode)
+        if (!response.IsSuccessStatusCode)
         {
-            videoResponse.Dispose();
+            response.Dispose();
             throw new HttpRequestException(
-                $"Failed to download video. Status code: {videoResponse.StatusCode}");
+                $"Failed to download media. Status code: {response.StatusCode}");
         }
 
-        var contentLength = videoResponse.Content.Headers.ContentLength ?? -1;
-        var stream = await videoResponse.Content.ReadAsStreamAsync(cancellationToken);
+        var contentLength = response.Content.Headers.ContentLength ?? -1;
+        var stream = await response.Content.ReadAsStreamAsync(cancellationToken);
+
         return new StreamInfo
         {
             Stream          = stream,
@@ -163,7 +164,7 @@ public async Task<StreamInfo> DownloadVideoAsync(
     /// <summary>
     /// Injects cookies with their correct domain into the session cookie container.
     /// </summary>
-    public void InjectCookies(IReadOnlyList<CookieData> cookies)
+    internal void InjectCookies(IReadOnlyList<CookieData> cookies)
     {
         foreach (var cookie in cookies)
         {
diff --git a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
index 8aac4c8..7d11888 100644
--- a/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
+++ b/TiktokExplode.Infrastructure/Parsers/TikTokVideoParser.cs
@@ -256,7 +256,7 @@ internal static MediaMusic ParseVideoMusic(JsonNode node)
             IsCopyrighted   = node.GetBool("isCopyrighted"),
             IsOriginal      = node.GetBool("original"),
             IsPrivate       = node.GetBool("private"),
-            PlayUrl         = node.GetString("playUrl"),
+            PlayUrl         = node.GetStringOrEmpty("playUrl"),
         };
     }
 
diff --git a/TiktokExplode/Domain/Abstractions/IDownloadClient.cs b/TiktokExplode/Domain/Abstractions/IDownloadClient.cs
index b9107c7..0b956c7 100644
--- a/TiktokExplode/Domain/Abstractions/IDownloadClient.cs
+++ b/TiktokExplode/Domain/Abstractions/IDownloadClient.cs
@@ -1,5 +1,6 @@
 using TiktokExplode.Domain.Entities;
 using TiktokExplode.Domain.ValueObjects;
+using TiktokExplode.Domain.ValueObjects.Carousels;
 
 namespace TiktokExplode.Domain.Abstractions;
 
@@ -34,4 +35,16 @@ public interface IDownloadClient : IAsyncDisposable
     /// as reported by the CDN <c>Content-Length</c> header.
     /// </returns>
     Task<StreamInfo> DownloadWatermarkedAsync(Video video, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Downloads a carousel image and returns a <see cref="StreamInfo"/> with the open stream.
+    /// The caller is responsible for disposing the returned <see cref="StreamInfo"/>.
+    /// </summary>
+    /// <param name="image">The <see cref="CarouselImage"/> whose download URL will be used.</param>
+    /// <param name="cancellationToken">Token to cancel the operation.</param>
+    /// <returns>
+    /// A <see cref="StreamInfo"/> containing the open image stream and its exact size in bytes
+    /// as reported by the CDN <c>Content-Length</c> header.
+    /// </returns>
+    Task<StreamInfo> DownloadImageAsync(CarouselImage image, CancellationToken cancellationToken = default);
 }
\ No newline at end of file

From 4133dd091f4d20e0e0af8b0a14575727e067e8e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Thu, 11 Jun 2026 19:10:45 -0500
Subject: [PATCH 17/18] Updated Documentation

---
 README.md | 53 ++++++++++++++++++++++++++++++++---------------------
 1 file changed, 32 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 7c3bb3c..e895282 100644
--- a/README.md
+++ b/README.md
@@ -117,11 +117,12 @@ await using var client = new TiktokClient(myFetcher, new TikTokOptions());
 
 #### Methods
 
-| Method                                               | Returns      | Description                       |
-| ---------------------------------------------------- | ------------ | --------------------------------- |
-| `GetVideoAsync(string url, CancellationToken)`       | `Video`      | Fetches full video metadata       |
-| `DownloadAsync(Video, CancellationToken)`            | `StreamInfo` | Downloads video without watermark |
-| `DownloadWatermarkedAsync(Video, CancellationToken)` | `StreamInfo` | Downloads video with watermark    |
+| Method                                                       | Returns      | Description                             |
+| ------------------------------------------------------------ | ------------ | --------------------------------------- |
+| `GetVideoAsync(string url, CancellationToken)`               | `Video`      | Fetches full video metadata             |
+| `DownloadAsync(Video, CancellationToken)`                    | `StreamInfo` | Downloads video without watermark       |
+| `DownloadWatermarkedAsync(Video, CancellationToken)`         | `StreamInfo` | Downloads video with watermark          |
+| `DownloadImageAsync(CarouselImage, CancellationToken)`       | `StreamInfo` | Downloads a carousel image stream       |
 
 `TiktokClient` implements `IAsyncDisposable` — always use `await using`.
 
@@ -151,37 +152,47 @@ await foreach (var media in client.SearchAsync("funny cats"))
 }
 ```
 
-> **Note:** `TiktokSearchClient` implements `ISearchClient`, which extends `IDownloadClient`. This means all extension methods (`DownloadAsync(filePath)`, `DownloadWatermarkedAsync(filePath)`, `DownloadImageAsync`, `DownloadAnimatedImageAsync`) are available directly on the search client — no need for a separate `TiktokClient` instance.
+> **Note:** `TiktokSearchClient` implements `ISearchClient`, which extends `IDownloadClient`. This means all extension methods (`DownloadAsync(filePath)`, `DownloadWatermarkedAsync(filePath)`, `DownloadImageAsync`, `DownloadAnimatedImageAsync`, `DownloadCarouselImagesAsync`) are available directly on the search client — no need for a separate `TiktokClient` instance.
 
 > **Search scope:** The current implementation returns results from the **first page** of TikTok's search API (~10–20 results).
 
 #### Methods
 
-| Method                                               | Returns                   | Description                                                  |
-| ---------------------------------------------------- | ------------------------- | ------------------------------------------------------------ |
-| `SearchAsync(string keyword, CancellationToken)`     | `IAsyncEnumerable<Media>` | Streams media results (videos and carousels) for the keyword |
-| `DownloadAsync(Video, CancellationToken)`            | `StreamInfo`              | Downloads video without watermark                            |
-| `DownloadWatermarkedAsync(Video, CancellationToken)` | `StreamInfo`              | Downloads video with watermark                               |
+| Method                                                         | Returns                   | Description                                                  |
+| -------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------ |
+| `SearchAsync(string keyword, CancellationToken)`               | `IAsyncEnumerable<Media>` | Streams media results (videos and carousels) for the keyword |
+| `DownloadAsync(Video, CancellationToken)`                      | `StreamInfo`              | Downloads video without watermark                            |
+| `DownloadWatermarkedAsync(Video, CancellationToken)`           | `StreamInfo`              | Downloads video with watermark                               |
+| `DownloadImageAsync(CarouselImage, CancellationToken)`         | `StreamInfo`              | Downloads a carousel image stream                            |
 
 `TiktokSearchClient` implements `IAsyncDisposable` — always use `await using`.
 
-#### Extension methods (via `TiktokClientExtensions`)
+#### Extension methods (via `DownloadClientExtensions`)
 
-| Method                                                     | Description                                                         |
-| ---------------------------------------------------------- | ------------------------------------------------------------------- |
-| `DownloadAsync(video, filePath, progress?, ct)`            | Downloads video without watermark to a file, with optional progress |
-| `DownloadWatermarkedAsync(video, filePath, progress?, ct)` | Downloads video with watermark to a file, with optional progress    |
-| `DownloadImageAsync(video, filePath, ct)`                  | Downloads the static cover image (JPEG)                             |
-| `DownloadAnimatedImageAsync(video, filePath, ct)`          | Downloads the animated cover (WebP)                                 |
+| Method                                                                  | Description                                                              |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `DownloadAsync(video, filePath, progress?, ct)`                         | Downloads video without watermark to a file, with optional progress      |
+| `DownloadWatermarkedAsync(video, filePath, progress?, ct)`              | Downloads video with watermark to a file, with optional progress         |
+| `DownloadImageAsync(image, filePath, progress?, ct)`                    | Downloads a single carousel image to a file, with optional progress      |
+| `DownloadCarouselImagesAsync(carousel, directoryPath, progress?, ct)`   | Downloads all carousel images to a directory with overall progress       |
+| `DownloadImageAsync(video, filePath, ct)`                               | Downloads the static cover image of a video (JPEG)                       |
+| `DownloadAnimatedImageAsync(video, filePath, ct)`                       | Downloads the animated cover of a video (WebP)                           |
 
 ```csharp
-// Download to file path with optional progress
-await client.DownloadAsync(video, "output.mp4", progress, cancellationToken);
-await client.DownloadWatermarkedAsync(video, "output_wm.mp4", progress, cancellationToken);
+// Download video to file with optional progress
+IProgress<double> progress = new Progress<double>(p => Console.Write($"\rProgress: {p:P0}"));
+await client.DownloadAsync(video, "output.mp4", progress);
+await client.DownloadWatermarkedAsync(video, "output_wm.mp4", progress);
 
 // Download cover images
 await client.DownloadImageAsync(video, "cover.jpg");
 await client.DownloadAnimatedImageAsync(video, "cover.webp");
+
+// Download a single carousel image
+await client.DownloadImageAsync(carousel.Post.Images[0], "image_1.jpg", progress);
+
+// Download all carousel images to a directory (named image_1.jpg, image_2.jpg, ...)
+await client.DownloadCarouselImagesAsync(carousel, "my_carousel_folder", progress);
 ```
 
 > **Note:** Animated covers are served by TikTok as animated WebP files. Not all videos have an animated cover — if `Cover.AnimatedUrl` is empty, the video only has a static cover.

From e73870b38381d43b8d3ee3c5b2cd06c1fd63b608 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johan=20S=C3=A1nchez?= <johansanchezal@unimagdalena.edu.co>
Date: Thu, 11 Jun 2026 19:31:14 -0500
Subject: [PATCH 18/18] - Added XML Documentation - Eliminate unnecessary
 usings

---
 .../Browser/TikTokBrowser.cs                         |  5 ++++-
 .../Common/DownloadClientExtensions.cs               |  4 +---
 .../Common/JsonNodeExtensions.cs                     |  2 +-
 .../Fetchers/Search/SearchPageResult.cs              | 12 ++++++++++++
 TiktokExplode/Domain/Abstractions/IVideoClient.cs    |  2 +-
 TiktokExplode/Domain/Entities/Video.cs               |  1 -
 6 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
index 993ad62..b18f4a3 100644
--- a/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
+++ b/TiktokExplode.Infrastructure/Browser/TikTokBrowser.cs
@@ -1,5 +1,4 @@
 using Microsoft.Playwright;
-using System.Diagnostics;
 using TiktokExplode.Domain.Exceptions;
 using TiktokExplode.Infrastructure.Fetchers;
 using TiktokExplode.Infrastructure.Fetchers.Search;
@@ -302,6 +301,10 @@ public async Task<IReadOnlyList<CookieData>> GetCookiesAsync()
             })];
     }
 
+    /// <summary>
+    /// Creates and returns a new page in the shared browser context for manual navigation and interaction.
+    /// </summary>
+    /// <returns></returns>
     internal async Task<IPage> CreatePageAsync()
         => await _context.NewPageAsync();
 
diff --git a/TiktokExplode.Infrastructure/Common/DownloadClientExtensions.cs b/TiktokExplode.Infrastructure/Common/DownloadClientExtensions.cs
index 67bf071..b5f3e59 100644
--- a/TiktokExplode.Infrastructure/Common/DownloadClientExtensions.cs
+++ b/TiktokExplode.Infrastructure/Common/DownloadClientExtensions.cs
@@ -1,8 +1,6 @@
-using AngleSharp.Dom;
-using TiktokExplode.Domain.Abstractions;
+using TiktokExplode.Domain.Abstractions;
 using TiktokExplode.Domain.Entities;
 using TiktokExplode.Domain.Exceptions;
-using TiktokExplode.Domain.ValueObjects;
 using TiktokExplode.Domain.ValueObjects.Carousels;
 
 namespace TiktokExplode.Infrastructure.Common;
diff --git a/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs b/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs
index 1f6b83c..b74c472 100644
--- a/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs
+++ b/TiktokExplode.Infrastructure/Common/JsonNodeExtensions.cs
@@ -6,7 +6,7 @@
 namespace TiktokExplode.Infrastructure.Common;
 
 /// <summary>
-/// Internal extension methods for <see cref="System.Text.Json.Nodes.JsonNode"/> that perform
+/// Internal extension methods for <see cref="JsonNode"/> that perform
 /// type-checked field reads and throw <see cref="TiktokParsingException"/> on missing or
 /// mistyped values.
 /// </summary>
diff --git a/TiktokExplode.Infrastructure/Fetchers/Search/SearchPageResult.cs b/TiktokExplode.Infrastructure/Fetchers/Search/SearchPageResult.cs
index 0913e7f..2c5c7a9 100644
--- a/TiktokExplode.Infrastructure/Fetchers/Search/SearchPageResult.cs
+++ b/TiktokExplode.Infrastructure/Fetchers/Search/SearchPageResult.cs
@@ -2,9 +2,21 @@
 
 namespace TiktokExplode.Infrastructure.Fetchers.Search;
 
+/// <summary>
+/// Represents the result of fetching a search page, containing the raw JSON content of the page
+/// and the corresponding Playwright <see cref="IPage"/> instance for any necessary cookie extraction or further interactions.
+/// </summary>
 internal sealed class SearchPageResult
 {
+    /// <summary>
+    /// The raw JSON content extracted from the search page, which contains the data needed to parse 
+    /// and construct <see cref="Domain.Entities.Video"/> objects.
+    /// </summary>
     public required string JsonContent { get; init; }
 
+    /// <summary>
+    /// The Playwright <see cref="IPage"/> instance associated with the search page, which can be 
+    /// used for any necessary cookie extraction or further interactions.
+    /// </summary>
     public required IPage Page { get; init; }
 }
diff --git a/TiktokExplode/Domain/Abstractions/IVideoClient.cs b/TiktokExplode/Domain/Abstractions/IVideoClient.cs
index 1565903..fd066a4 100644
--- a/TiktokExplode/Domain/Abstractions/IVideoClient.cs
+++ b/TiktokExplode/Domain/Abstractions/IVideoClient.cs
@@ -14,7 +14,7 @@ public interface IVideoClient : IDownloadClient
     /// <param name="url">The absolute TikTok video URL (e.g. <c>https://www.tiktok.com/@user/video/123</c>).</param>
     /// <param name="cancellationToken">Token to cancel the operation.</param>
     /// <returns>A <see cref="Video"/> instance containing all available metadata.</returns>
-    /// <exception cref="System.ArgumentException">Thrown when <paramref name="url"/> is not a valid TikTok URL.</exception>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="url"/> is not a valid TikTok URL.</exception>
     /// <exception cref="Exceptions.TiktokWafException">Thrown when all WAF retry attempts are exhausted.</exception>
     /// <exception cref="Exceptions.VideoNotFoundException">Thrown when the video does not exist or is private.</exception>
     /// <exception cref="Exceptions.TiktokParsingException">Thrown when the page structure cannot be parsed.</exception>
diff --git a/TiktokExplode/Domain/Entities/Video.cs b/TiktokExplode/Domain/Entities/Video.cs
index 0b2d94f..ee27e32 100644
--- a/TiktokExplode/Domain/Entities/Video.cs
+++ b/TiktokExplode/Domain/Entities/Video.cs
@@ -1,4 +1,3 @@
-using TiktokExplode.Domain.ValueObjects.Media;
 using TiktokExplode.Domain.ValueObjects.Videos;
 
 namespace TiktokExplode.Domain.Entities;