(20250220)

controllers_v2/core/auth_token.py

@@ -630,6 +630,41 @@ class CoreAuthTokenController(CoreBaseModel):
         # Done here:
         return [CoreAuthTokenModel(**token) for token in tokens]
 
+    async def get_first_token(
+            self,
+            mongo_data_conn: AsyncMongo,
+            must_be_active: bool = True,
+            additional_filter: dict = None
+    ) -> CoreAuthTokenModel | None:
+
+        """
+        To fetch the first auth-token that matches the given conditions. Good when you have been asked to, say, send an
+        SMS without being specific about which client to send it from. In such a case, tune your conditions such that
+        you fetch the first auth token for an SMS client and use that for the next steps.
+        :param mongo_data_conn: The database connection (MongoDB) to use to perform the action.
+        :param must_be_active: Set this to False if you want to allow pending and disabled accounts to be retrieved.
+        :param additional_filter: Any addition filters to use.
+        :return: The retrieved record that has the token, and information about the service and client if found, else
+            None when there is no matching record.
+        """
+
+        # Prepare the filter:
+        filter_json = {}
+        if self._base_filter:
+            for k, v in self._base_filter.items(): filter_json[k] = v
+        if additional_filter:
+            for k, v in additional_filter.items(): filter_json[k] = v
+        if must_be_active: filter_json["status"] = "active"
+
+        # If there is some filtering possible, we fetch the token:
+        token = await mongo_data_conn.find_one(
+            collection = self.AUTH_COLLECTION,
+            filter = mongo_data_conn.dict_to_dot_notation(filter_json)
+        )
+
+        # Done here:
+        return None if token is None else CoreAuthTokenModel(**token)
+
     async def get_batches_to_sync(
             self,
             mongo_data_conn: AsyncMongo,