feat(folders): add curser and the normalized way to get foler's item list. add reverse order

src/application/dtos/folder_dto.rs

@@ -1,8 +1,13 @@
 use std::sync::Arc;
 
+use crate::application::dtos::cursor::{CursorListResponse, CursorQuery, PageCursor};
+use crate::application::dtos::grant_dto::{ResourceContentDto, ResourceTypeDto};
 use crate::domain::entities::folder::Folder;
+use crate::domain::services::authorization::ResourceKind;
+use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
-use utoipa::ToSchema;
+use utoipa::{IntoParams, ToSchema};
+use uuid::Uuid;
 
 /// DTO for folder creation requests
 #[derive(Debug, Deserialize, ToSchema)]
@@ -145,3 +150,138 @@ impl Default for FolderDto {
         Self::empty()
     }
 }
+
+// ════════════════════════════════════════════════════════════════════════════
+// Cursor-paginated folder resources  (GET /api/folders/{id}/resources)
+// ════════════════════════════════════════════════════════════════════════════
+
+/// Raw row returned by the UNION ALL query that combines `storage.folders` and
+/// `storage.files` for a given parent folder.  Used internally between the
+/// repository and service/handler layers — never serialised directly.
+pub struct FolderResourceRow {
+    pub resource_type: String, // "folder" | "file"
+    pub id: Uuid,
+    pub name: String,
+    /// Parent folder UUID (for both resource types).
+    pub parent_id: Option<Uuid>,
+    /// `None` for folders.
+    pub mime_type: Option<String>,
+    /// `-1` sentinel for folders (no physical size).
+    pub size: i64,
+    pub created_at: DateTime<Utc>,
+    pub modified_at: DateTime<Utc>,
+    pub owner_id: Uuid,
+    // Pre-computed sort fields — returned by the SQL for cursor construction.
+    /// `LOWER(name)` used by `name`/`type` sorts.
+    pub sort_str: String,
+    /// `category_order` for files, `0` for folders.
+    pub type_order: i64,
+    /// `0` for folders, `1` for files (used by `name` sort to keep folders first).
+    pub folder_first: i32,
+}
+
+/// Opaque keyset-pagination cursor for `/api/folders/{id}/resources`.
+///
+/// Encoded as base64url-JSON (same scheme as [`GrantCursor`]).
+/// Fields are sparse: only the sort-relevant ones are serialised.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FolderResourceCursor {
+    /// Sort dimension active when this cursor was produced.
+    #[serde(default = "FolderResourceCursor::default_order")]
+    pub order_by: String,
+    /// UUID of the last item on the previous page (tie-breaker).
+    pub resource_id: Uuid,
+    /// `LOWER(name)` for `name`/`type` sorts.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sort_str: Option<String>,
+    /// Multipurpose integer sort key:
+    /// - `name`:  `folder_first` (0 = folder, 1 = file)
+    /// - `type`:  `category_order` (0 = Folder, 100 = Image …)
+    /// - `size`:  file size in bytes, -1 for folders
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sort_int: Option<i64>,
+    /// Timestamp for `modified_at` / `created_at` sorts.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sort_ts: Option<DateTime<Utc>>,
+    /// Whether the result set was reversed when this cursor was produced.
+    /// Must be passed unchanged on subsequent page requests.
+    #[serde(default)]
+    pub reverse: bool,
+}
+
+impl FolderResourceCursor {
+    fn default_order() -> String {
+        "name".to_owned()
+    }
+}
+
+impl PageCursor for FolderResourceCursor {}
+
+/// Query parameters for `GET /api/folders/{id}/resources`.
+#[derive(Debug, Deserialize, IntoParams)]
+pub struct FolderResourcesQuery {
+    /// Maximum items per page (1–200, default 50).
+    #[serde(default = "CursorQuery::default_limit")]
+    pub limit: u32,
+    /// Opaque cursor from a previous response. Omit to start from the top.
+    pub cursor: Option<String>,
+    /// Sort / group-by dimension. Supported: `"name"` (default), `"type"`,
+    /// `"modified_at"`, `"created_at"`, `"size"`.
+    pub order_by: Option<String>,
+    /// Comma-separated resource types to include, e.g. `"file,folder"`.
+    /// Omit to include both.
+    pub resource_types: Option<String>,
+    /// Reverse the sort order. Default `false` (normal order).
+    /// Must be the same on all pages of the same result set — the cursor
+    /// carries this flag so the server can validate consistency.
+    #[serde(default)]
+    pub reverse: bool,
+}
+
+impl FolderResourcesQuery {
+    /// Returns `limit` clamped to `[1, 200]`.
+    pub fn limit_clamped(&self) -> usize {
+        self.limit.clamp(1, 200) as usize
+    }
+
+    /// Decode the optional cursor string. Invalid cursor → start from top.
+    pub fn decode_cursor(&self) -> Option<FolderResourceCursor> {
+        self.cursor
+            .as_deref()
+            .and_then(FolderResourceCursor::decode)
+    }
+
+    /// Parse `resource_types` into a `Vec<ResourceKind>`.
+    /// Returns `None` when the field is absent (= include all types).
+    pub fn resource_kinds(&self) -> Option<Vec<ResourceKind>> {
+        self.resource_types.as_deref().map(|s| {
+            s.split(',')
+                .filter_map(|t| ResourceKind::parse(t.trim()))
+                .collect()
+        })
+    }
+}
+
+/// Options for [`FolderService::list_resources_paged_with_perms`].
+///
+/// Groups the optional parameters so the function stays within clippy's
+/// `too_many_arguments` limit while remaining easy to extend.
+pub struct ListResourcesOptions<'a> {
+    pub limit: usize,
+    pub cursor: Option<FolderResourceCursor>,
+    pub order_by: &'a str,
+    pub kinds: Option<&'a [ResourceKind]>,
+    pub reverse: bool,
+}
+
+/// One item in a `/resources` page — a file or folder with a `resource_type` tag.
+/// Re-uses [`ResourceContentDto`] so the shape is identical to `SharedWithMeItemDto.resource`.
+#[derive(Debug, Serialize, ToSchema)]
+pub struct FolderResourceItemDto {
+    pub resource_type: ResourceTypeDto,
+    /// Full resource details. Shape is determined by `resource_type`.
+    pub resource: ResourceContentDto,
+}
+
+/// Response envelope for `GET /api/folders/{id}/resources`.
+pub type FolderResourcesDto = CursorListResponse<FolderResourceItemDto>;

src/application/dtos/grant_dto.rs

@@ -252,6 +252,11 @@ pub struct SharedWithMeQuery {
     /// Comma-separated resource types to include, e.g. `file,folder`.
     /// Omit to return all known types.
     pub resource_types: Option<String>,
+    /// Reverse the sort order. Default `false` (normal order).
+    /// Must be the same on all pages of the same result set — the cursor
+    /// carries this flag so the server can validate consistency.
+    #[serde(default)]
+    pub reverse: bool,
 }
 
 impl SharedWithMeQuery {

src/application/ports/authorization_ports.rs

@@ -86,6 +86,7 @@ pub trait AuthorizationEngine: Send + Sync + 'static {
         limit: u32,
         cursor: Option<GrantCursor>,
         sort_by: &str,
+        reverse: bool,
     ) -> Result<(Vec<IncomingGrantSummary>, Option<GrantCursor>), DomainError>;
 
     /// All grants on a specific resource (for "Manage sharing" UI). Caller

src/application/services/folder_service.rs

@@ -1,5 +1,7 @@
+use crate::application::dtos::cursor::PageCursor;
 use crate::application::dtos::folder_dto::{
-    CreateFolderDto, FolderDto, MoveFolderDto, RenameFolderDto,
+    CreateFolderDto, FolderDto, FolderResourceCursor, FolderResourceRow, ListResourcesOptions,
+    MoveFolderDto, RenameFolderDto,
 };
 use crate::application::ports::authorization_ports::AuthorizationEngine;
 use crate::application::ports::folder_ports::FolderUseCase;
@@ -582,3 +584,109 @@ impl FolderUseCase for FolderService {
         })
     }
 }
+
+// ── FolderService — cursor-paginated resource listing ────────────────────────
+
+impl FolderService {
+    /// Cursor-paginated listing of sub-folders **and** files inside `parent_id`.
+    ///
+    /// Enforces `Permission::Read` on the parent folder before querying.
+    /// `order_by` controls both the SQL `ORDER BY` and the cursor encoding.
+    /// `kinds` filters the result to only the specified resource types.
+    pub async fn list_resources_paged_with_perms(
+        &self,
+        parent_id: &str,
+        caller_id: Uuid,
+        opts: ListResourcesOptions<'_>,
+    ) -> Result<(Vec<FolderResourceRow>, Option<String>), DomainError> {
+        // 1. AuthZ — same check as list_folders_with_perms
+        self.authz
+            .require(
+                Subject::User(caller_id),
+                Permission::Read,
+                Self::folder_resource(parent_id)?,
+            )
+            .await?;
+
+        let pid =
+            Uuid::parse_str(parent_id).map_err(|_| DomainError::not_found("Folder", parent_id))?;
+
+        let ListResourcesOptions {
+            limit,
+            cursor,
+            order_by,
+            kinds,
+            reverse,
+        } = opts;
+
+        // 2. Fetch limit+1 rows so we can detect has_next
+        let mut rows = self
+            .folder_storage
+            .list_resources_paged(pid, limit + 1, cursor.as_ref(), order_by, kinds, reverse)
+            .await?;
+
+        // 3. Detect has_next, build encoded next cursor
+        let next_cursor = if rows.len() > limit {
+            let last = &rows[limit - 1];
+            let c = build_folder_resource_cursor(last, order_by, reverse);
+            rows.truncate(limit);
+            Some(c.encode())
+        } else {
+            None
+        };
+
+        Ok((rows, next_cursor))
+    }
+}
+
+/// Build the next-page cursor from the last row of the current page.
+/// `reverse` is stored in the cursor so subsequent pages use the same order.
+fn build_folder_resource_cursor(
+    row: &FolderResourceRow,
+    order_by: &str,
+    reverse: bool,
+) -> FolderResourceCursor {
+    match order_by {
+        "type" => FolderResourceCursor {
+            order_by: "type".to_owned(),
+            resource_id: row.id,
+            sort_str: Some(row.sort_str.clone()),
+            sort_int: Some(row.type_order),
+            sort_ts: None,
+            reverse,
+        },
+        "modified_at" => FolderResourceCursor {
+            order_by: "modified_at".to_owned(),
+            resource_id: row.id,
+            sort_str: None,
+            sort_int: None,
+            sort_ts: Some(row.modified_at),
+            reverse,
+        },
+        "created_at" => FolderResourceCursor {
+            order_by: "created_at".to_owned(),
+            resource_id: row.id,
+            sort_str: None,
+            sort_int: None,
+            sort_ts: Some(row.created_at),
+            reverse,
+        },
+        "size" => FolderResourceCursor {
+            order_by: "size".to_owned(),
+            resource_id: row.id,
+            sort_str: None,
+            sort_int: Some(row.size),
+            sort_ts: None,
+            reverse,
+        },
+        _ => FolderResourceCursor {
+            // "name" (default): sort_int = folder_first (0 or 1)
+            order_by: "name".to_owned(),
+            resource_id: row.id,
+            sort_str: Some(row.sort_str.clone()),
+            sort_int: Some(i64::from(row.folder_first)),
+            sort_ts: None,
+            reverse,
+        },
+    }
+}