flip_api.user_services.register_user
====================================

.. py:module:: flip_api.user_services.register_user


Attributes
----------

.. autoapisummary::

   flip_api.user_services.register_user.router


Functions
---------

.. autoapisummary::

   flip_api.user_services.register_user._rollback_cognito_on_audit_failure
   flip_api.user_services.register_user.register_user


Module Contents
---------------

.. py:data:: router

.. py:function:: _rollback_cognito_on_audit_failure(email: str, user_pool_id: str, original_err: Exception) -> None

   Delete the just-created Cognito user after a failed audit-row write.

   The audit commit owns the failure path; this helper just attempts the
   Cognito-side rollback and translates a rollback failure into the more
   explicit "manual cleanup required" 500. Callers handle the post-rollback
   "Please try again" 500 themselves so the success-path 500 stays at the
   main call site.

   Mirrors the ``_rollback_after_role_failure`` pattern in
   ``register_user_step_function`` so the two rollback shapes look the same.

   :param email: Email of the Cognito user to delete (the username).
   :param user_pool_id: Cognito user pool ID.
   :param original_err: The audit-write exception, chained as ``__cause__`` if
                        this helper raises so the operator sees the original trigger.

   :raises HTTPException: 500 with a "manual cleanup required" detail iff the
       ``delete_cognito_user`` call itself fails. A successful rollback
       returns cleanly; the caller then raises the "Please try again"
       500.


.. py:function:: register_user(user_data: flip_api.domain.interfaces.user.IRegisterUser, request: fastapi.Request, db: sqlmodel.Session = Depends(get_session), token_id: uuid.UUID = Depends(verify_token))

   Register a new user in Cognito.

   Cognito is the source of truth for user identity; we do not mirror users
   in a local table. Role assignment is a separate step (handled by
   ``/api/step/users``). This endpoint writes a ``UsersAudit`` row keyed by
   the new Cognito sub on success.

   :param user_data: The user data to register (email + roles).
   :type user_data: IRegisterUser
   :param request: The FastAPI request object.
   :type request: Request
   :param db: The database session.
   :type db: Session
   :param token_id: ID of the authenticated user making the request.
   :type token_id: UUID

   :returns: Created user data including the new Cognito sub.
   :rtype: IUserResponse

   :raises HTTPException: If the user does not have permission to register a
   :raises user, if the email is already registered, or if Cognito rejects the:
   :raises create.: