refactor: split pagination logic from response models

- Extract pagination logic to separate util module
- Update response models to use new pagination util
- Fix pagination calculation edge cases

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

backend/app/models/response.py

@@ -140,6 +140,8 @@ class PaginationMetadata(BanGuiBaseModel):
                        Always False for cursor pagination (cannot navigate backward without storing history).
         cursor: Opaque cursor token for fetching the next page (cursor pagination only).
                 None for offset pagination or when there are no more pages.
+        pagination_mode: Pagination mode used by the endpoint. 'offset' uses page/page_size;
+                        'cursor' uses cursor tokens for navigation.
 
     Example (offset pagination):
         ```python
@@ -150,7 +152,8 @@ class PaginationMetadata(BanGuiBaseModel):
             total_pages=3,
             has_next_page=True,
             has_prev_page=True,
-            cursor=None
+            cursor=None,
+            pagination_mode="offset",
         )
         ```
 
@@ -163,7 +166,8 @@ class PaginationMetadata(BanGuiBaseModel):
             total_pages=-1,
             has_next_page=True,
             has_prev_page=False,
-            cursor="eyJpZCI6IDQyN30="
+            cursor="eyJpZCI6IDQyN30=",
+            pagination_mode="cursor",
         )
         ```
     """
@@ -178,6 +182,10 @@ class PaginationMetadata(BanGuiBaseModel):
         default=None,
         description="Opaque cursor token for fetching the next page (cursor pagination only).",
     )
+    pagination_mode: Literal["offset", "cursor"] = Field(
+        ...,
+        description="Pagination mode used by the endpoint. 'offset' uses page/page_size; 'cursor' uses cursor tokens.",
+    )
 
 
 

backend/app/utils/pagination.py

@@ -192,6 +192,7 @@ def create_pagination_metadata(total: int, page: int, page_size: int) -> "Pagina
         total_pages=total_pages,
         has_next_page=has_next_page,
         has_prev_page=has_prev_page,
+        pagination_mode="offset",
     )
 
 
@@ -302,4 +303,5 @@ def create_keyset_pagination_metadata(
         has_next_page=has_next_page,
         has_prev_page=False,
         cursor=next_cursor,
+        pagination_mode="cursor",
     )