Added individual paginators for API endpoints

KomplexHubPlugin/CMakeLists.txt

@@ -27,6 +27,18 @@ qt_add_qml_module(
         common/logging.h
         common/fetchresult.h
         paginators/newestpackspaginator.h
+        SOURCES paginators/featuredpackspaginator.h
+        SOURCES paginators/featuredimagespaginator.h
+        SOURCES paginators/wallpaperpaginator.h
+        SOURCES paginators/searchpackspaginator.h
+        SOURCES paginators/searchimagespaginator.h
+        SOURCES paginators/newestshaderspaginator.h
+        SOURCES paginators/newestcubemapspaginator.h
+        SOURCES paginators/featuredshaderspaginator.h
+        SOURCES paginators/featuredcubemapspaginator.h
+        SOURCES paginators/searchshaderspaginator.h
+        SOURCES paginators/searchcubemapspaginator.h
+        SOURCES paginators/searchvideospaginator.h
 
 )
 

KomplexHubPlugin/common/paginator.h

@@ -20,19 +20,23 @@
 #define PAGINATOR_H
 
 #include <QObject>
+#include <QMutex>
+#include <QMutexLocker>
 
 #include "komplex_global.h"
 #include "slidingcachecontroller.h"
 
 /**
- * @brief The PaginatorNotifier class
+ * @brief The PaginationNotifier class
  *
  * Qt does not support templated QObjects. Pushing it to a notifier class
  * that the template can inherit fixes this
  */
-class KOMPLEX_EXPORT PaginatorNotifier : public QObject
+class KOMPLEX_EXPORT PaginationNotifier : public QObject
 {
     Q_OBJECT
+protected:
+    explicit PaginationNotifier(QObject *parent = nullptr) : QObject(parent) {}
 signals:
     auto dataChanged() -> void;
     auto resultsPerPageChanged() -> void;
@@ -47,9 +51,14 @@ signals:
  * the SlidingCacheController as it's backend
  */
 template<typename T>
-class KOMPLEX_EXPORT Paginator : public PaginatorNotifier
+class KOMPLEX_EXPORT Paginator : public PaginationNotifier
 {
 public:
+    explicit Paginator(QObject *parent = nullptr) : PaginationNotifier(parent)
+    {
+
+    }
+
     /**
      * @brief next
      *
@@ -58,7 +67,6 @@ public:
     auto next() const -> void
     {
         setOffset(m_offset + m_resultsPerPage);
-        Q_EMIT static_cast<PaginatorNotifier*>(this)->pageChanged();
     }
 
     /**
@@ -69,7 +77,6 @@ public:
     auto previous() const -> void
     {
         setOffset(m_offset - m_resultsPerPage);
-        Q_EMIT static_cast<PaginatorNotifier*>(this)->pageChanged();
     }
 
     /**
@@ -87,16 +94,23 @@ public:
      */
     auto setResultsPerPage(qsizetype resultsPerPage) -> void
     {
+        QMutexLocker dataLocker(&m_dataMutex);
+
+        if(resultsPerPage == m_resultsPerPage)
+        {
+            return;
+        }
+
         m_resultsPerPage = resultsPerPage;
-        Q_EMIT static_cast<PaginatorNotifier*>(this)->resultsPerPageChanged();
+        Q_EMIT static_cast<PaginationNotifier*>(this)->resultsPerPageChanged();
 
         m_data = m_cacheController.chunk(m_offset, m_resultsPerPage);
-        Q_EMIT static_cast<PaginatorNotifier*>(this)->dataChanged();
+        Q_EMIT static_cast<PaginationNotifier*>(this)->dataChanged();
     }
 
     /**
      * @brief data
-     * @return a copy of the list of pointers
+     * @return
      */
     auto data() const -> QList<T>
     {
@@ -117,8 +131,10 @@ public:
      * @param index
      * @return
      */
-    auto at(qsizetype index) const -> T
+    auto at(qsizetype index) -> T
     {
+        QMutexLocker dataLocker(&m_dataMutex);
+
         if(index < 0 || index >= m_data.count())
         {
             return {};
@@ -140,6 +156,7 @@ public:
 
     /**
      * @brief page
+     * Calculates the current page
      * @return
      */
     auto page() const -> qsizetype
@@ -151,6 +168,7 @@ public:
 
     /**
      * @brief totalPages
+     * Calculates the total number of pages available
      * @return
      */
     auto totalPages() const -> qsizetype
@@ -162,18 +180,33 @@ public:
 
 protected:
 
+    /**
+     * @brief controller
+     * Reference to the underlying cache controller
+     * @return
+     */
     auto controller() -> SlidingCacheController<T>*
     {
         return &m_cacheController;
     }
 
+    /**
+     * @brief setOffset
+     * Sets the dataset to the specified offset
+     * @param offset
+     */
     auto setOffset(qsizetype offset) -> void
     {
+        if(offset == m_offset)
+        {
+            return;
+        }
+
         m_offset = offset;
 
-        if(m_offset >= m_totalResults)
+        if(m_offset >= totalResults())
         {
-            m_offset = m_totalResults - m_resultsPerPage;
+            m_offset = totalResults() - m_resultsPerPage;
         }
 
         if(m_offset < 0)
@@ -181,28 +214,88 @@ protected:
             m_offset = 0;
         }
 
-        m_data = m_cacheController.chunk(m_offset, m_resultsPerPage);
+        QList<T> data = m_cacheController.chunk(m_offset, m_resultsPerPage);
-        Q_EMIT this->countChanged();
+        setData(data);
-        Q_EMIT this->dataChanged();
+
         Q_EMIT this->pageChanged();
-        Q_EMIT this->totalPagesChanged();
     }
 
+    /**
+     * @brief setData
+     * @param data
+     */
+    auto setData(const QList<T> &data)
+    {
+        m_dataMutex.lock();
+
+        m_data.clear();
+        m_data.append(std::move(data));
+        m_dataMutex.unlock();
+
+        Q_EMIT this->countChanged();
+        Q_EMIT this->dataChanged();
+    }
+
+    /**
+     * @brief onControllerTotalResultsChanged
+     * Slot used to forward totalResultsChanged signal
+     */
     auto onControllerTotalResultsChanged() -> void
     {
         Q_EMIT this->totalResultsChanged();
     }
 
+    /**
+     * @brief reset
+     * Resets the paginator and underlying controller
+     */
+    auto reset() -> void
+    {
+        m_dataMutex.lock();
+
+        m_offset = std::numeric_limits<qsizetype>::infinity();
+        m_data.clear();
+        controller()->reset();
+        m_dataMutex.unlock();
+
+        Q_EMIT totalPagesChanged();
+        Q_EMIT dataChanged();
+        Q_EMIT pageChanged();
+    }
+
 private:
-    qsizetype m_page = 0;
+    /**
-    qsizetype m_totalPages = 0;
+     * @brief m_offset
+     * Current absolute offset. Used in fetch operations
+     */
+    qsizetype m_offset = std::numeric_limits<qsizetype>::infinity();
 
-    qsizetype m_offset = 0;
+    /**
+     * @brief m_resultsPerPage
+     * Results per page to use when calculating current and total pages.
+     * Needs to be set by the view
+     */
     qsizetype m_resultsPerPage = 0;
-    qsizetype m_totalResults = 0;
 
+    /**
+     * @brief m_cacheController
+     * Internal cache controller.
+     *
+     * TODO: make the cache controller generic so it can be used in other projects
+     * and with other cache methods
+     */
     SlidingCacheController<T> m_cacheController;
+
+    /**
+     * @brief m_data
+     * Internal data copy
+     */
     QList<T> m_data;
+
+    /**
+     * @brief m_dataMutex
+     */
+    QMutex m_dataMutex;
 };
 
 #endif // PAGINATOR_H

KomplexHubPlugin/paginators/featuredcubemapspaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef FEATUREDCUBEMAPSPAGINATOR_H
+#define FEATUREDCUBEMAPSPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT FeaturedCubemapsPaginator : public WallpaperPaginator
+{
+public:
+    explicit FeaturedCubemapsPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/cubemaps/featured/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // FEATUREDCUBEMAPSPAGINATOR_H

KomplexHubPlugin/paginators/featuredimagespaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef FEATUREDIMAGESPAGINATOR_H
+#define FEATUREDIMAGESPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT FeaturedImagesPaginator : public WallpaperPaginator
+{
+public:
+    explicit FeaturedImagesPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/images/featured/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // FEATUREDIMAGESPAGINATOR_H

KomplexHubPlugin/paginators/featuredpackspaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef FEATUREDPACKSPAGINATOR_H
+#define FEATUREDPACKSPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT FeaturedPacksPaginator : public WallpaperPaginator
+{
+public:
+    explicit FeaturedPacksPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/packs/featured/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // FEATUREDPACKSPAGINATOR_H

KomplexHubPlugin/paginators/featuredshaderspaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef FEATUREDSHADERSPAGINATOR_H
+#define FEATUREDSHADERSPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT FeaturedShadersPaginator : public WallpaperPaginator
+{
+public:
+    explicit FeaturedShadersPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/shaders/featured/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // FEATUREDSHADERSPAGINATOR_H

KomplexHubPlugin/paginators/newestcubemapspaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef NEWESTCUBEMAPSPAGINATOR_H
+#define NEWESTCUBEMAPSPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT NewestCubemapsPaginator : public WallpaperPaginator
+{
+public:
+    explicit NewestCubemapsPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/cubemaps/newest/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // NEWESTCUBEMAPSPAGINATOR_H

KomplexHubPlugin/paginators/newestpackspaginator.h

@@ -29,170 +29,16 @@
 #include <QJsonArray>
 #include <QJsonObject>
 
-#include "common/logging.h"
+#include "wallpaperpaginator.h"
-#include "common/paginator.h"
-#include "common/wallpapercache.h"
-#include "common/coreservices.h"
 
-class KOMPLEX_EXPORT NewestPacksPaginator : public Paginator<WallpaperCache>
+class KOMPLEX_EXPORT NewestPacksPaginator : public WallpaperPaginator
 {
-
 public:
-    explicit NewestPacksPaginator() : Paginator<WallpaperCache>()
+    explicit NewestPacksPaginator() : WallpaperPaginator()
     {
-        SlidingCacheController<WallpaperCache> *controller = this->controller();
+        setUri(
-        controller->setFetch(
-            std::bind(&NewestPacksPaginator::fetch, this, std::placeholders::_1, std::placeholders::_2)
-        );
-    }
-
-protected:
-    /**
-     * @brief fetch
-     * Used to fetch results from the API endpoint
-     * for the CacheController. It is intended to be passed
-     * to the Cache Controller not meant to be called directly.
-     * @param offset Offset index to start the results from
-     * @param limit Number of results to attempt to fetch
-     * @return FetchResult<WallpaperCache>
-     */
-    auto fetch(
-        qsizetype offset,
-        qsizetype limit
-    ) const -> FetchResult<WallpaperCache>
-    {
-        QUrl url(
             QString::fromUtf8("%1/v2/packs/newest/").arg(KOMPLEX_API_HOST)
         );
-
-        QNetworkRequest request(url);
-        request.setHeaders(
-            QHttpHeaders::fromMultiMap(
-                {
-                    {
-                        QByteArray("Offset"),
-                        QString::number(offset).toUtf8()
-                    },
-                    {
-                        QByteArray("Limit"),
-                        QString::number(limit).toUtf8()
-                    },
-                    {
-                        QByteArray("SessionToken"),
-                        CoreServices::sessionToken()
-                    }
-                }
-            )
-        );
-
-        QNetworkReply *reply = getNetworkReply(request);
-
-        if(reply == nullptr)
-        {
-            return {};
-        }
-
-        QJsonDocument document = getDocument(reply);
-
-        QJsonObject rootObject = document.object();
-        const QJsonArray resultsArray = rootObject.value(QString::fromUtf8("results")).toArray();
-
-        QList<WallpaperCache> fetchedResults;
-
-        for(const auto result : resultsArray)
-        {
-            if(!result.isObject())
-            {
-                continue;
-            }
-
-            QJsonObject resultObject = result.toObject();
-
-            fetchedResults.append(
-                {
-                    resultObject.value(QString::fromUtf8("uri")).toString(),
-                    resultObject.value(QString::fromUtf8("name")).toString(),
-                    resultObject.value(QString::fromUtf8("author")).toString(),
-                    resultObject.value(QString::fromUtf8("authorId")).toString(),
-                    resultObject.value(QString::fromUtf8("description")).toString(),
-                    resultObject.value(QString::fromUtf8("thumbnail")).toString(),
-                    QDateTime::fromString(
-                        resultObject.value(QString::fromUtf8("createdDate")).toString()
-                    ),
-                    resultObject.value(QString::fromUtf8("price")).toDouble(),
-                    resultObject.value(QString::fromUtf8("currency")).toString(),
-                    static_cast<quint64>(
-                        resultObject.value(QString::fromUtf8("downloadCount")
-                    ).toInteger()),
-                    static_cast<qint8>(
-                        resultObject.value(QString::fromUtf8("description")
-                    ).toInt()),
-                }
-            );
-        }
-
-        return
-        {
-            static_cast<qsizetype>(rootObject.value(QString::fromUtf8("total_results")).toInteger()),
-            fetchedResults.count(),
-            std::move(fetchedResults)
-        };
-    }
-
-    /**
-     * @brief getNetworkReply
-     * Processes the request and blocks until completion.
-     * @param request
-     * @return
-     */
-    auto getNetworkReply(const QNetworkRequest &request) const -> QNetworkReply*
-    {
-        QEventLoop loop;
-        QWeakPointer<QNetworkAccessManager> managerReference = CoreServices::networkAccessManager();
-
-        QSharedPointer<QNetworkAccessManager> manager = managerReference.toStrongRef();
-
-        LOG_ERROR_X(!manager,
-            "NewestPacksPaginator::getNetworkReply",
-            "Network manager reference has already been deleted",
-            nullptr
-        );
-
-        QNetworkReply *reply = manager->post(request, nullptr);
-        QObject::connect(reply, &QNetworkReply::finished, &loop, &QEventLoop::quit);
-        QObject::connect(reply, &QNetworkReply::errorOccurred, &loop,
-            [&loop](QNetworkReply::NetworkError error) -> void
-            {
-                loop.quit();
-            }
-        );
-
-        if(!reply->isFinished())
-        {
-            loop.exec();
-        }
-
-        LOG_ERROR_X(reply->error() != QNetworkReply::NoError,
-            "NewestPacksPaginator::getNetworkReply",
-            reply->errorString().toStdString().c_str(),
-            nullptr
-        );
-
-        return reply;
-    }
-
-    auto getDocument(QNetworkReply *reply) const -> QJsonDocument
-    {
-        QJsonParseError documentError;
-        QJsonDocument document = QJsonDocument::fromJson(reply->readAll(), &documentError);
-
-        LOG_ERROR_X(documentError.error != QJsonParseError::NoError,
-            "NewestPacksPaginator::getDocument",
-            documentError.errorString().toStdString().c_str(),
-            {}
-        );
-
-        return document;
     }
 };
 

KomplexHubPlugin/paginators/newestshaderspaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef NEWESTSHADERSPAGINATOR_H
+#define NEWESTSHADERSPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT NewestShadersPaginator : public WallpaperPaginator
+{
+public:
+    explicit NewestShadersPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/shaders/newest/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // NEWESTSHADERSPAGINATOR_H

KomplexHubPlugin/paginators/searchcubemapspaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef SEARCHCUBEMAPSPAGINATOR_H
+#define SEARCHCUBEMAPSPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT SearchCubemapsPaginator : public WallpaperPaginator
+{
+public:
+    explicit SearchCubemapsPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/cubemaps/search/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // SEARCHCUBEMAPSPAGINATOR_H

KomplexHubPlugin/paginators/searchimagespaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef SEARCHIMAGESPAGINATOR_H
+#define SEARCHIMAGESPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT SearchImagesPaginator : public WallpaperPaginator
+{
+public:
+    explicit SearchImagesPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/images/search/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // SEARCHIMAGESPAGINATOR_H

KomplexHubPlugin/paginators/searchpackspaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef SEARCHPACKSPAGINATOR_H
+#define SEARCHPACKSPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT SearchPacksPaginator : public WallpaperPaginator
+{
+public:
+    explicit SearchPacksPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/packs/search/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // SEARCHPACKSPAGINATOR_H

KomplexHubPlugin/paginators/searchshaderspaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef SEARCHSHADERSPAGINATOR_H
+#define SEARCHSHADERSPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT SearchShadersPaginator : public WallpaperPaginator
+{
+public:
+    explicit SearchShadersPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/shaders/search/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // SEARCHSHADERSPAGINATOR_H

KomplexHubPlugin/paginators/searchvideospaginator.h

@@ -0,0 +1,45 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef SEARCHVIDEOSPAGINATOR_H
+#define SEARCHVIDEOSPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "wallpaperpaginator.h"
+
+class KOMPLEX_EXPORT SearchVideosPaginator : public WallpaperPaginator
+{
+public:
+    explicit SearchVideosPaginator() : WallpaperPaginator()
+    {
+        setUri(
+            QString::fromUtf8("%1/v2/videos/search/").arg(KOMPLEX_API_HOST)
+        );
+    }
+};
+
+#endif // SEARCHVIDEOSPAGINATOR_H

KomplexHubPlugin/paginators/wallpaperpaginator.h

@@ -0,0 +1,303 @@
+/*
+ *  Komplex Wallpaper Engine
+ *  Copyright (C) 2026 @DigitalArtifex
+ *  https://digitalartifex.dev - https://github.com/DigitalArtifex
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>
+ */
+#ifndef WALLPAPERPAGINATOR_H
+#define WALLPAPERPAGINATOR_H
+
+#include <QObject>
+#include <QNetworkAccessManager>
+#include <QNetworkReply>
+#include <QNetworkRequest>
+#include <QEventLoop>
+#include <QJsonDocument>
+#include <QJsonParseError>
+#include <QJsonArray>
+#include <QJsonObject>
+
+#include "common/logging.h"
+#include "common/paginator.h"
+#include "common/wallpapercache.h"
+#include "common/coreservices.h"
+
+/**
+ * @brief The WallpaperPaginator class
+ * Most of the media endpoints for the Komplex API have the same data structure so
+ * child classes can make use of this generic controller where possible
+ */
+class KOMPLEX_EXPORT WallpaperPaginator : public Paginator<WallpaperCache>
+{
+    Q_OBJECT
+public:
+    explicit WallpaperPaginator() : Paginator<WallpaperCache>()
+    {
+        SlidingCacheController<WallpaperCache> *controller = this->controller();
+        controller->setFetch(
+            std::bind(&WallpaperPaginator::fetch, this, std::placeholders::_1, std::placeholders::_2)
+        );
+    }
+
+    /**
+     * @brief uri
+     * URI of the API Endpoint. This is set by the child class
+     * @return
+     */
+    [[nodiscard]]
+    auto uri() const -> QString
+    {
+        return m_uri;
+    }
+
+    /**
+     * @brief query
+     * Current query string, if the API Endpoint supports queries
+     * @return
+     */
+    [[nodiscard]]
+    auto query() const -> QString
+    {
+        return m_query;
+    }
+
+    /**
+     * @brief setQuery
+     * Sets the new query string and updates the controller
+     * @param query
+     */
+    auto setQuery(const QString &query) -> void
+    {
+        if(query == m_query)
+        {
+            return;
+        }
+
+        m_query = query;
+        Q_EMIT queryChanged();
+
+        reset();
+        setOffset(0);
+    }
+
+signals:
+    /**
+     * @brief uriChanged
+     */
+    auto uriChanged() -> void;
+
+    /**
+     * @brief queryChanged
+     */
+    auto queryChanged() -> void;
+
+protected:
+    /**
+     * @brief fetch
+     * Used to fetch results from the API endpoint
+     * for the CacheController. It is intended to be passed
+     * to the Cache Controller not meant to be called directly.
+     * @param offset Offset index to start the results from
+     * @param limit Number of results to attempt to fetch
+     * @return FetchResult<WallpaperCache>
+     */
+    [[nodiscard]]
+    auto fetch(
+        qsizetype offset,
+        qsizetype limit
+    ) const -> FetchResult<WallpaperCache>
+    {
+        LOG_ERROR_X(m_uri.isEmpty(),
+            "WallpaperPaginator::fetch",
+            "Uri not set",
+            {}
+        );
+
+        QUrl url(m_uri);
+
+        QNetworkRequest request(url);
+        request.setHeaders(
+            QHttpHeaders::fromMultiMap(
+                {
+                    {
+                        QByteArray("Query"),
+                        m_query.toUtf8()
+                    },
+                    {
+                        QByteArray("Offset"),
+                        QString::number(offset).toUtf8()
+                    },
+                    {
+                        QByteArray("Limit"),
+                        QString::number(limit).toUtf8()
+                    },
+                    {
+                        QByteArray("SessionToken"),
+                        CoreServices::sessionToken()
+                    }
+                }
+            )
+        );
+
+        QNetworkReply *reply = getNetworkReply(request);
+
+        if(reply == nullptr)
+        {
+            return {};
+        }
+
+        QJsonDocument document = getDocument(reply);
+
+        QJsonObject rootObject = document.object();
+        const QJsonArray resultsArray = rootObject.value(QString::fromUtf8("results")).toArray();
+
+        QList<WallpaperCache> fetchedResults;
+
+        for(const auto result : resultsArray)
+        {
+            if(!result.isObject())
+            {
+                continue;
+            }
+
+            QJsonObject resultObject = result.toObject();
+
+            fetchedResults.append(
+                {
+                    resultObject.value(QString::fromUtf8("uri")).toString(),
+                    resultObject.value(QString::fromUtf8("name")).toString(),
+                    resultObject.value(QString::fromUtf8("author")).toString(),
+                    resultObject.value(QString::fromUtf8("authorId")).toString(),
+                    resultObject.value(QString::fromUtf8("description")).toString(),
+                    resultObject.value(QString::fromUtf8("thumbnail")).toString(),
+                    QDateTime::fromString(
+                        resultObject.value(QString::fromUtf8("createdDate")).toString()
+                    ),
+                    resultObject.value(QString::fromUtf8("price")).toDouble(),
+                    resultObject.value(QString::fromUtf8("currency")).toString(),
+                    static_cast<quint64>(
+                        resultObject.value(QString::fromUtf8("downloadCount")
+                    ).toInteger()),
+                    static_cast<qint8>(
+                        resultObject.value(QString::fromUtf8("description")
+                    ).toInt()),
+                }
+            );
+        }
+
+        return
+        {
+            static_cast<qsizetype>(rootObject.value(QString::fromUtf8("total_results")).toInteger()),
+            fetchedResults.count(),
+            std::move(fetchedResults)
+        };
+    }
+
+    /**
+     * @brief getNetworkReply
+     * Processes the request and blocks until completion.
+     * @param request
+     * @return
+     */
+    [[nodiscard]]
+    auto getNetworkReply(const QNetworkRequest &request) const -> QNetworkReply*
+    {
+        QEventLoop loop;
+        QWeakPointer<QNetworkAccessManager> managerReference = CoreServices::networkAccessManager();
+
+        QSharedPointer<QNetworkAccessManager> manager = managerReference.toStrongRef();
+
+        LOG_ERROR_X(!manager,
+            "NewestPacksPaginator::getNetworkReply",
+            "Network manager reference has already been deleted",
+            nullptr
+        );
+
+        QNetworkReply *reply = manager->post(request, nullptr);
+        QObject::connect(reply, &QNetworkReply::finished, &loop, &QEventLoop::quit);
+        QObject::connect(reply, &QNetworkReply::errorOccurred, &loop,
+            [&loop](QNetworkReply::NetworkError error) -> void
+            {
+                loop.quit();
+            }
+        );
+
+        if(!reply->isFinished())
+        {
+            loop.exec();
+        }
+
+        LOG_ERROR_X(reply->error() != QNetworkReply::NoError,
+            "NewestPacksPaginator::getNetworkReply",
+            reply->errorString().toStdString().c_str(),
+            nullptr
+        );
+
+        return reply;
+    }
+
+    /**
+     * @brief getDocument
+     * Extracts the JSON document from the server reply
+     * @param reply
+     * @return
+     */
+    [[nodiscard]]
+    auto getDocument(QNetworkReply *reply) const -> QJsonDocument
+    {
+        QJsonParseError documentError;
+        QJsonDocument document = QJsonDocument::fromJson(reply->readAll(), &documentError);
+
+        LOG_ERROR_X(documentError.error != QJsonParseError::NoError,
+            "NewestPacksPaginator::getDocument",
+            documentError.errorString().toStdString().c_str(),
+            {}
+        );
+
+        return document;
+    }
+
+    /**
+     * @brief setUri
+     * Sets the API Endpoint URI to fetch from
+     * @param uri
+     */
+    auto setUri(const QString &uri) -> void
+    {
+        if(uri == m_uri)
+        {
+            return;
+        }
+
+        m_uri = uri;
+
+        Q_EMIT uriChanged();
+    }
+
+private:
+    /**
+     * @brief m_uri
+     * API Endpoint URI
+     */
+    QString m_uri;
+
+    /**
+     * @brief m_query
+     * The query string used in fetch operations
+     */
+    QString m_query;
+};
+
+#endif // WALLPAPERPAGINATOR_H