flip_api.trusts_services.utils.audit_helper
===========================================

.. py:module:: flip_api.trusts_services.utils.audit_helper


Functions
---------

.. autoapisummary::

   flip_api.trusts_services.utils.audit_helper.audit_trust_action


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

.. py:function:: audit_trust_action(trust_id: uuid.UUID, trust_name: str, action: flip_api.domain.schemas.actions.TrustAuditAction, user_id: uuid.UUID | None, session: sqlmodel.Session) -> flip_api.db.models.main_models.TrustsAudit

   Insert an audit log row for a trust-registry mutation.

   Mirrors the project / model audit helpers in pattern — the caller is
   responsible for the surrounding transaction commit.

   :param trust_id: ID of the trust being audited. Stored as a bare
                    UUID (no FK) so the row survives hard-delete of the trust.
   :type trust_id: UUID
   :param trust_name: Human-readable name at the time of the action.
                      Denormalised here so audit queries remain meaningful after
                      hard-delete.
   :type trust_name: str
   :param action: The action performed.
   :type action: TrustAuditAction
   :param user_id: Cognito sub of the authenticated admin
                   (UI path), or ``None`` when called from the deploy CLI.
   :type user_id: UUID | None
   :param session: SQLModel session — the helper does NOT commit.
   :type session: Session

   :returns: The newly-flushed audit row.
   :rtype: TrustsAudit

   :raises ValueError: If the audit row cannot be persisted.