PLAT-10531 Signal service implementation (#138)

Author: symphony-mariacristina

docsrc/index.md

@@ -8,6 +8,7 @@ Contents
 * [Stream service](markdown/stream_service.md)
 * [Connection service](markdown/connection_service.md)
 * [Application service](markdown/application_service.md)
+* [Signal service](markdown/signal_service.md)
 * [Datafeed](markdown/datafeed.md)
 * [Presence service](markdown/presence_service.md)
 
@@ -35,7 +36,8 @@ The reference documentation consists of the following sections:
 * [Message service](markdown/message_service.md): Sending or searching messages, usage of templates
 * [Stream service](markdown/stream_service.md): Creating, searching streams, manage stream membership
 * [Connection service](markdown/connection_service.md): Managing connections between users
-* [Datafeed](markdown/datafeed.md): Listening and reacting to real-time events
+* [Signal service](markdown/signal_service.md): Managing signals, subscribing/unsubscribing to signals
+* [Datafeed](markdown/datafeed.md): Listening and reacting to real-time events 
 * [Presence service](markdown/presence_service.md): Reacting and managing presences
 ### Technical Documentation
 * Information on how we generate client side code from swagger specs in the

docsrc/markdown/signal_service.md

@@ -0,0 +1,30 @@
+# Signal Service
+
+The Signal Service is a component at the service layer of the BDK which aims to cover the Signal part of the [REST API documentation](https://developers.symphony.com/restapi/reference).
+More precisely:
+* [List signals](https://developers.symphony.com/restapi/reference#list-signals)
+* [Get a signal](https://developers.symphony.com/restapi/reference#get-signal)
+* [Create a signal](https://developers.symphony.com/restapi/reference#create-signal)
+* [Update a signal](https://developers.symphony.com/restapi/reference#update-signal)
+* [Delete a signal](https://developers.symphony.com/restapi/reference#delete-signal)
+* [Subscribe Signal](https://developers.symphony.com/restapi/reference#subscribe-signal)
+* [Unsubscribe Signal](https://developers.symphony.com/restapi/reference#unsubscribe-signal)
+* [Subscribers](https://developers.symphony.com/restapi/reference#subscribers)
+
+
+## How to use
+The central component for the Signal Service is the `SignalService` class.
+This class exposes the user-friendly service APIs which serve all the services mentioned above
+and is accessible from the `SymphonyBdk` object by calling the `signals()` method:
+```python
+class ApplicationMain:
+    @staticmethod
+    async def run():
+        bdk_config = BdkConfigLoader.load_from_file("path/to/config.yaml")
+        async with SymphonyBdk(bdk_config) as bdk:
+            signal_service = bdk.signals()
+            signal_list = await signal_service.list_signals()
+            print(signal_list)
+if __name__ == "__main__":
+    asyncio.run(ApplicationMain.run())
+```

examples/signals.py

@@ -0,0 +1,42 @@
+import asyncio
+import logging
+
+from symphony.bdk.core.config.loader import BdkConfigLoader
+from symphony.bdk.core.symphony_bdk import SymphonyBdk
+from symphony.bdk.gen.agent_model.base_signal import BaseSignal
+
+
+async def run():
+    config = BdkConfigLoader.load_from_symphony_dir("config.yaml")
+
+    async with SymphonyBdk(config) as bdk:
+        signal_service = bdk.signals()
+        attribute_map = {
+            'name': 'Testing signal',
+            'query': 'HASHTAG:hashtag',
+            'visible_on_profile': False,
+            'company_wide': False
+        }
+        logging.info('Creating new signal.')
+        signal = await signal_service.create_signal(BaseSignal(**attribute_map))
+        logging.info(signal)
+        await signal_service.list_signals(0, 3)
+        attribute_map_update = {
+            'name': 'Testing signal updated',
+            'query': 'HASHTAG:hashtag',
+            'visible_on_profile': False,
+            'company_wide': False
+        }
+        logging.info('Updating signal.')
+        await signal_service.update_signal(signal.id, BaseSignal(**attribute_map_update))
+        logging.info(await signal_service.get_signal(signal.id))
+        logging.info('Add a subscriber to the signal.')
+        await signal_service.subscribe_users_to_signal(signal.id, True, [13056700580913])
+        logging.info(await signal_service.list_subscribers(signal.id))
+        logging.info('Unsubscribe added user to the signal.')
+        await signal_service.unsubscribe_users_to_signal(signal.id, [13056700580913])
+        logging.info(await signal_service.list_subscribers(signal.id))
+        logging.info(await signal_service.delete_signal(signal.id))
+
+logging.basicConfig(level=logging.DEBUG)
+asyncio.run(run())

symphony/bdk/core/service/presence/presence_service.py

@@ -53,7 +53,7 @@ async def get_all_presence(self, last_user_id: int, limit: int) -> List[V2Presen
         See: `Get All Presence <https://developers.symphony.com/restapi/reference#get-all-presence>`_.
 
         :param last_user_id: Last user ID retrieved, used for paging. If provided, results skip users with IDs less
-        than this parameter.
+          than this parameter.
         :param limit: Maximum number of records to return. The maximum supported value is 5000.
         :return: Presence info of the looked up user.
         """
@@ -67,8 +67,8 @@ async def get_user_presence(self, user_id: int, local: bool) -> V2Presence:
 
         :param user_id: User Id
         :param local: If true then Perform a local query and set the presence to OFFLINE for  users who are not local to
-        the calling user’s pod. If false or absent then query the presence of all local  and external users who are
-        connected to the calling user.
+          the calling user’s pod. If false or absent then query the presence of all local  and external users who are
+          connected to the calling user.
         :return: Presence info of the looked up user.
         """
         return await self._presence_api.v3_user_uid_presence_get(uid=user_id,
@@ -77,8 +77,8 @@ async def get_user_presence(self, user_id: int, local: bool) -> V2Presence:
 
     async def external_presence_interest(self, user_ids: List[int]):
         """ Register interest in a list of external users to get their presence info.
-        See: `External Presence Interest <https://developers.symphony.com/restapi/reference#register-user-presence
-        -interest>`_.
+        See: `External Presence Interest
+        <https://developers.symphony.com/restapi/reference#register-user-presence-interest>`_.
 
         :param user_ids: List of user ids to be registered.
         """
@@ -90,12 +90,12 @@ async def set_presence(self, status: PresenceStatus, soft: bool) -> V2Presence:
         See: `Set Presence <https://developers.symphony.com/restapi/reference#set-presence>`_.
 
         :param status: The new presence state for the user.
-        Possible values are AVAILABLE, BUSY, AWAY, ON_THE_PHONE, BE_RIGHT_BACK, IN_A_MEETING, OUT_OF_OFFICE, OFF_WORK.
+          Possible values are AVAILABLE, BUSY, AWAY, ON_THE_PHONE, BE_RIGHT_BACK, IN_A_MEETING, OUT_OF_OFFICE, OFF_WORK.
         :param soft: If true, the user's current status is taken into consideration. If the user is currently OFFLINE,
-        the user's presence will still be OFFLINE, but the new presence will take effect when the user comes online. If
-        the user is currently online, the user's activity state will be applied to the presence if applicable. (e.g. if
-        you are setting their presence to AVAILABLE, but the user is currently idle, their status will be represented as
-        AWAY)
+          the user's presence will still be OFFLINE, but the new presence will take effect when the user comes online. If
+          the user is currently online, the user's activity state will be applied to the presence if applicable. (e.g. if
+          you are setting their presence to AVAILABLE, but the user is currently idle, their status will be represented as
+          AWAY)
         :return: Presence info of the calling user.
         """
         presence_status: V2PresenceStatus = V2PresenceStatus(category=status.name)
@@ -121,7 +121,7 @@ async def read_presence_feed(self, feed_id: str) -> List[V2Presence]:
         See: `Read Presence Feed <https://developers.symphony.com/restapi/reference#read-presence-feed>`_.
 
         :param feed_id: The presence feed id to be read.
-        :return:The list of user presences has changed since the last presence read.
+        :return: The list of user presences has changed since the last presence read.
         """
         return await self._presence_api.v1_presence_feed_feed_id_read_get(
             session_token=await self._auth_session.session_token,
@@ -145,12 +145,12 @@ async def set_user_presence(self, user_id: int, status: PresenceStatus, soft: bo
 
         :param user_id: The id of the specified user.
         :param status: Presence state to set.
-        Possible values are AVAILABLE, BUSY, AWAY, ON_THE_PHONE, BE_RIGHT_BACK, IN_A_MEETING, OUT_OF_OFFICE, OFF_WORK.
+          Possible values are AVAILABLE, BUSY, AWAY, ON_THE_PHONE, BE_RIGHT_BACK, IN_A_MEETING, OUT_OF_OFFICE, OFF_WORK.
         :param soft: If true, the user's current status is taken into consideration. If the user is currently OFFLINE,
-        the user's presence will still be OFFLINE, but the new presence will take effect when the user comes online. If
-        the user is currently online, the user's activity state will be applied to the presence if applicable. (e.g. if
-        you are setting their presence to AVAILABLE, but the user is currently idle, their status will be represented as
-        AWAY)
+          the user's presence will still be OFFLINE, but the new presence will take effect when the user comes online. If
+          the user is currently online, the user's activity state will be applied to the presence if applicable. (e.g. if
+          you are setting their presence to AVAILABLE, but the user is currently idle, their status will be represented as
+          AWAY)
         :return: The presence info of the specified user.
         """
         user_presence: V2UserPresence = V2UserPresence(category=status.name, user_id=user_id)

symphony/bdk/core/service/signal/__init__.py

@@ -0,0 +1,153 @@
+from symphony.bdk.core.auth.auth_session import AuthSession
+from symphony.bdk.gen.agent_api.signals_api import SignalsApi
+from symphony.bdk.gen.agent_model.base_signal import BaseSignal
+from symphony.bdk.gen.agent_model.channel_subscriber import ChannelSubscriber
+from symphony.bdk.gen.agent_model.channel_subscription_response import ChannelSubscriptionResponse
+from symphony.bdk.gen.agent_model.signal import Signal
+from symphony.bdk.gen.agent_model.signal_list import SignalList
+
+
+class OboSignalService:
+    """Service class exposing OBO-enabled endpoints to manage signal information.
+
+    This service is used for listing signals related to the OBO user, get information of a specified signal
+    or perform some actions related to the signal like:
+
+    * List signals
+    * Get a signal
+    * Create a signal
+    * Update a signal
+    * Delete a signal
+    * Subscribe or unsubscribe a signal
+    """
+
+    def __init__(self, signals_api: SignalsApi, auth_session: AuthSession):
+        self._signals_api = signals_api
+        self._auth_session = auth_session
+
+    async def list_signals(self, skip: int = 0, limit: int = 50) -> SignalList:
+        """ Lists signals on behalf of the user. The response includes signals that the user has created and
+        public signals to which they have subscribed.
+
+        See: 'List signals <https://developers.symphony.com/restapi/reference#list-signals>'_
+
+        :param skip: The number of signals to skip.
+        :param limit: Maximum number of signals to return. Default is 50, maximum value is 500.
+        :return: List of signals found.
+        """
+
+        return await self._signals_api.v1_signals_list_get(
+            skip=skip, limit=limit, session_token=await self._auth_session.session_token,
+            key_manager_token=await self._auth_session.key_manager_token)
+
+    async def get_signal(self, signal_id: str) -> Signal:
+        """ Gets details about the specified signal.
+
+        See: 'Get signal <https://developers.symphony.com/restapi/reference#get-signal>'_
+
+        :param signal_id: Id of the signal to display.
+        :return: The signal found.
+        """
+
+        return await self._signals_api.v1_signals_id_get_get(
+            id=signal_id, session_token=await self._auth_session.session_token,
+            key_manager_token=await self._auth_session.key_manager_token)
+
+    async def create_signal(self, signal: BaseSignal) -> Signal:
+        """ Creates a new Signal.
+
+        See: 'Create signal <https://developers.symphony.com/restapi/reference#create-signal>'_
+
+        :param signal: The new Signal object to be created.
+        :return: The signal created.
+        """
+
+        return await self._signals_api.v1_signals_create_post(
+            signal=signal, session_token=await self._auth_session.session_token,
+            key_manager_token=await self._auth_session.key_manager_token)
+
+    async def update_signal(self, signal_id: str, signal: BaseSignal) -> Signal:
+        """ Updates an existing Signal.
+
+        See: 'Update signal <https://developers.symphony.com/restapi/reference#update-signal>'_
+
+        :param signal_id: The Id of the signal to be modified.
+        :param signal: The Signal object to be updated.
+        :return: The updated signal.
+        """
+
+        return await self._signals_api.v1_signals_id_update_post(
+            id=signal_id, signal=signal, session_token=await self._auth_session.session_token,
+            key_manager_token=await self._auth_session.key_manager_token)
+
+    async def delete_signal(self, signal_id: str) -> None:
+        """ Deletes an existing Signal.
+
+        See: 'Delete signal <https://developers.symphony.com/restapi/reference#delete-signal>'_
+
+        :param signal_id: The Id of the existing signal to be deleted.
+        """
+
+        return await self._signals_api.v1_signals_id_delete_post(
+            id=signal_id, session_token=await self._auth_session.session_token,
+            key_manager_token=await self._auth_session.key_manager_token)
+
+    async def subscribe_users_to_signal(self, signal_id: str, pushed: bool,
+                                        user_ids: [int]) -> ChannelSubscriptionResponse:
+        """ Subscribe an array of users to a Signal.
+
+        See: 'Subscribe signal <https://developers.symphony.com/restapi/reference#subscribe-signal>'_
+
+        :param signal_id: The Id of the signal to be subscribed.
+        :param pushed: Prevents the user from unsubscribing from the Signal
+        :param user_ids: An array of User Ids to subscribe to the Signal
+        :return: Result of the bulk subscriptions
+        """
+
+        return await self._signals_api.v1_signals_id_subscribe_post(
+            id=signal_id, pushed=pushed, users=user_ids, session_token=await self._auth_session.session_token,
+            key_manager_token=await self._auth_session.key_manager_token)
+
+    async def unsubscribe_users_to_signal(self, signal_id: str, user_ids: [int]) -> ChannelSubscriptionResponse:
+        """ Unsubscribes an array of users from the specified Signal.
+
+        See: 'Unsubscribe signal <https://developers.symphony.com/restapi/reference#unsubscribe-signal>'_
+
+        :param signal_id: The Id of the signal to be subscribed.
+        :param user_ids: An array of User Ids to subscribe to the Signal
+        :return: Result of the bulk unsubscriptions
+        """
+
+        return await self._signals_api.v1_signals_id_unsubscribe_post(
+            id=signal_id, users=user_ids, session_token=await self._auth_session.session_token,
+            key_manager_token=await self._auth_session.key_manager_token)
+
+    async def list_subscribers(self, signal_id: str, skip: int = 0, limit: int = 50) -> [ChannelSubscriber]:
+        """ Gets the subscribers for the specified signal.
+
+        See: 'Subscribers <https://developers.symphony.com/restapi/reference#subscribers>'_
+
+        :param signal_id: The Id of the signal.
+        :param skip: The number of results to skip.
+        :param limit: The maximum number of subscribers to return. The maximum value accepted for this parameter is 100
+          and the default value is 50.
+        :return: The list of users subscribed to the signal.
+        """
+
+        return await self._signals_api.v1_signals_id_subscribers_get(
+            id=signal_id, skip=skip, limit=limit, session_token=await self._auth_session.session_token,
+            key_manager_token=await self._auth_session.key_manager_token)
+
+
+class SignalService(OboSignalService):
+    """Service class for managing signal information.
+    This service is used for listing signals related to the user, get information of a specified signal
+    or perform some actions related to the signal like:
+
+    * List signals
+    * Get a signal
+    * Create a signal
+    * Update a signal
+    * Delete a signal
+    * Subscribe or unsubscribe a signal
+    """