Refactor user pre-registration functions to improve parameter documentation and remove unused arguments; enhance user account listing with order mapping

Author: pcrespov

services/web/server/src/simcore_service_webserver/users/_accounts_repository.py

@@ -45,15 +45,6 @@ async def create_user_pre_registration(
 ) -> int:
     """Creates a user pre-registration entry.
 
-    Args:
-        engine: Database engine
-        connection: Optional existing connection
-        email: Email address for the pre-registration
-        created_by: ID of the user creating the pre-registration (None for anonymous)
-        product_name: Product name the user is requesting access to
-        link_to_existing_user: Whether to link the pre-registration to an existing user with the same email
-        **other_values: Additional values to insert in the pre-registration entry
-
     Returns:
         ID of the created pre-registration
     """
@@ -104,15 +95,6 @@ async def list_user_pre_registrations(
 ) -> tuple[list[dict[str, Any]], int]:
     """Lists user pre-registrations with optional filters.
 
-    Args:
-        engine: Database engine
-        connection: Optional existing connection
-        filter_by_pre_email: Filter by email pattern (SQL LIKE pattern)
-        filter_by_product_name: Filter by product name
-        filter_by_account_request_status: Filter by account request status
-        pagination_limit: Maximum number of results to return
-        pagination_offset: Number of results to skip (for pagination)
-
     Returns:
         Tuple of (list of pre-registration records, total count)
     """
@@ -216,16 +198,7 @@ async def review_user_pre_registration(
     new_status: AccountRequestStatus,
     invitation_extras: dict[str, Any] | None = None,
 ) -> None:
-    """Updates the account request status of a pre-registered user.
-
-    Args:
-        engine: The database engine
-        connection: Optional existing connection
-        pre_registration_id: ID of the pre-registration record
-        reviewed_by: ID of the user who reviewed the request
-        new_status: New status (APPROVED or REJECTED)
-        invitation_extras: Optional invitation data to store in extras field
-    """
+    """Updates the account request status of a pre-registered user."""
     if new_status not in (AccountRequestStatus.APPROVED, AccountRequestStatus.REJECTED):
         msg = f"Invalid status for review: {new_status}. Must be APPROVED or REJECTED."
         raise ValueError(msg)
@@ -482,30 +455,22 @@ async def list_merged_pre_and_registered_users(
     product_name: ProductName,
     filter_any_account_request_status: Annotated[
         list[AccountRequestStatus] | None,
-        doc(
-            "If provided, only returns users with account request status in this list (only pre-registered users with any of these statuses will be included)"
-        ),
+        doc("Only returns users with these statuses (pre-registered users only)"),
     ] = None,
     filter_include_deleted: bool = False,
     pagination_limit: int = 50,
     pagination_offset: int = 0,
     order_by: Annotated[
         list[tuple[OrderKeys, OrderDirection]] | None,
-        doc(
-            'Valid fields: "email", "current_status_created". '
-            'Default: [("email", OrderDirection.ASC), ("is_pre_registered", OrderDirection.DESC), ("current_status_created", OrderDirection.DESC)]'
-        ),
+        doc('Valid fields: "email", "current_status_created"'),
     ] = None,
 ) -> tuple[list[MergedUserData], int]:
     """Retrieves and merges users from both users and pre-registration tables.
 
-    This returns:
-    1. Users who are registered with the platform (in users table)
-    2. Users who are pre-registered (in users_pre_registration_details table)
-    3. Users who are both registered and pre-registered
-
     Returns:
-        Tuple of (list of merged user data, total count)
+        1. Users registered with the platform (users table)
+        2. Users pre-registered (users_pre_registration_details table)
+        3. Users both registered and pre-registered
     """
     # Base where conditions for both queries
     pre_reg_query_conditions = [

services/web/server/src/simcore_service_webserver/users/_controller/rest/accounts_rest.py

@@ -7,6 +7,7 @@
 from models_library.api_schemas_webserver.users import (
     UserAccountApprove,
     UserAccountGet,
+    UserAccountOrderFields,
     UserAccountReject,
     UserAccountSearchQueryParams,
     UsersAccountListQueryParams,
@@ -21,6 +22,7 @@
 from servicelib.logging_utils import log_context
 from servicelib.rest_constants import RESPONSE_MODEL_POLICY
 from servicelib.utils import fire_and_forget_task
+from simcore_service_webserver.users._accounts_repository import OrderKeys
 
 from ...._meta import API_VTAG
 from ....constants import APP_FIRE_AND_FORGET_TASKS_KEY
@@ -63,16 +65,26 @@ async def list_users_accounts(request: web.Request) -> web.Response:
             AccountRequestStatus.APPROVED,
             AccountRequestStatus.REJECTED,
         ]
-    else:
-        # ALL
+    else:  # ALL
         filter_any_account_request_status = None
 
+    # Map API field names to service/repository field names
+    api_to_service_field_mapping: dict[UserAccountOrderFields, OrderKeys] = {
+        "email": "email",
+        "created_at": "current_status_created",
+    }
+
     user_accounts, total_count = await _accounts_service.list_user_accounts(
         request.app,
         product_name=req_ctx.product_name,
         filter_any_account_request_status=filter_any_account_request_status,
         pagination_limit=query_params.limit,
         pagination_offset=query_params.offset,
+        order_by=[
+            (api_to_service_field_mapping[clause.field], clause.direction)
+            for clause in query_params.order_by
+        ]
+        or None,
     )
 
     def _to_domain_model(account_details: dict[str, Any]) -> UserAccountGet:
@@ -108,6 +120,7 @@ async def search_user_accounts(request: web.Request) -> web.Response:
     req_ctx = UsersRequestContext.model_validate(request)
     assert req_ctx.product_name  # nosec
 
+    #  TODO: add sorting options
     query_params: UserAccountSearchQueryParams = parse_request_query_parameters_as(
         UserAccountSearchQueryParams, request
     )
@@ -201,6 +214,8 @@ async def approve_user_account(request: web.Request) -> web.Response:
         product_name=req_ctx.product_name,
         reviewer_id=req_ctx.user_id,
         invitation_extras=(
+            # TODO: remove invitation link
+            # TODO: use created as a reference to check whether it is expired or not
             {"invitation": invitation_result.model_dump(mode="json")}
             if invitation_result
             else None