feat: add objects, move preferences, add bulk apis (#5)

* feat: add objects, move preferences, add bulk apis

* feat: add bulk_set_preferences method

* fix: update readme

* fix: bulk delete

Author: cjbell

README.md

@@ -68,6 +68,7 @@ client.notify(
 )
 
 ```
+
 ### Getting and setting channel data
 
 ```python
@@ -107,14 +108,14 @@ from knockapi import Knock
 client = Knock(api_key="sk_12345")
 
 # Replaces the preferences for the user
-client.preferences.update(
+client.users.set_preferences(
   user_id="jhammond",
   channel_types={'email': True},
   workflows={'dinosaurs-loose': False}
 )
 
 # Retrieve the current preferences
-client.preferences.get(user_id="jhammond")
+client.users.get_preferences(user_id="jhammond")
 ```
 
 ### Signing JWTs

knockapi/client.py

@@ -53,6 +53,17 @@ def preferences(self):
         from .resources import Preferences
         return Preferences(self)
 
+    @property
+    def objects(self):
+        from .resources import Objects
+        return Objects(self)
+
+    @property
+    def bulk_operations(self):
+        from .resources import BulkOperations
+        return BulkOperations(self)
+
+    # Defined at the top level here for convienience
     def notify(self, key, actor, recipients, data={}, cancellation_key=None, tenant=None):
         """
         Triggers a workflow.

knockapi/resources/__init__.py

@@ -1,3 +1,5 @@
 from .users import User
 from .workflows import Workflows
 from .preferences import Preferences
+from .objects import Objects
+from .bulk_operations import BulkOperations

knockapi/resources/bulk_operations.py

@@ -0,0 +1,18 @@
+from .service import Service
+
+default_set_id = "default"
+
+
+class BulkOperations(Service):
+    def get(self, id):
+        """
+        Returns an bulk operation.
+
+        Args:
+            id (str): The id of the bulk operation
+
+        Returns:
+            dict: A Knock BulkOperation
+        """
+        endpoint = '/bulk_operations/{}'.format(id)
+        return self.client.request('get', endpoint)

knockapi/resources/objects.py

@@ -0,0 +1,114 @@
+from .service import Service
+
+default_set_id = "default"
+
+
+class Objects(Service):
+    def get(self, collection, id):
+        """
+        Returns an object in a collection with the id given.
+
+        Args:
+            collection (str): The collection the object belongs to
+            id (str): The id of the object in the collection
+
+        Returns:
+            dict: A Knock Object
+        """
+        endpoint = '/objects/{}/{}'.format(collection, id)
+        return self.client.request('get', endpoint)
+
+    # NOTE: This is `set_object` as `set` is a reserved keyword
+    def set_object(self, collection, id, data = {}):
+        """
+        Returns an object in a collection with the id given.
+
+        Args:
+            collection (str): The collection the object belongs to
+            id (str): The id of the object in the collection
+            data (dict): The data to set on the object
+
+        Returns:
+            dict: A Knock Object
+        """
+        endpoint = '/objects/{}/{}'.format(collection, id)
+        return self.client.request('put', endpoint, payload = data)
+
+    def bulk_set(self, collection, objects):
+        """
+        Bulk sets up to 100 objects in a collection.
+
+        Args:
+            collection (str): The collection the object belongs to
+            objects (array): The list of object dictionaries to set
+
+        Returns:
+            dict: BulkOperation from Knock
+        """
+        data = { 'objects': objects }
+        endpoint = '/objects/{}/bulk/set'.format(collection)
+        return self.client.request('post', endpoint, payload=data)
+
+    def delete(self, collection, id):
+        """
+        Deletes the given object.
+
+        Args:
+            collection (str): The collection the object belongs to
+            id (str): The id of the object in the collection
+
+        Returns:
+            None: No response
+        """
+        endpoint = '/objects/{}/{}'.format(collection, id)
+        return self.client.request('delete', endpoint)
+
+    def bulk_delete(self, collection, object_ids):
+        """
+        Bulk deletes up to 100 objects in a collection.
+
+        Args:
+            collection (str): The collection the object belongs to
+            object_ids (array): The list of object ids to delete
+
+        Returns:
+            dict: BulkOperation from Knock
+        """
+        data = { 'object_ids': object_ids }
+        endpoint = '/objects/{}/bulk/delete'.format(collection)
+        return self.client.request('post', endpoint, payload=data)
+
+    ##
+    # Channel data
+    ##
+
+    def get_channel_data(self, collection, id, channel_id):
+        """
+        Get user's channel data for the given channel id.
+
+        Args:
+            collection (str): The collection the object belongs to
+            id (str): The id of the object in the collection
+            channel_id (str): Target channel ID
+
+        Returns:
+            dict: Channel data from Knock.
+        """
+        endpoint = '/objects/{}/{}/channel_data/{}'.format(collection, id, channel_id)
+        return self.client.request('get', endpoint)
+
+    def set_channel_data(self, collection, id, channel_id, channel_data):
+        """
+        Upserts user's channel data for the given channel id.
+
+        Args:
+            collection (str): The collection the object belongs to
+            id (str): The id of the object in the collection
+            channel_id (str): Target channel ID
+            channel_data (dict): Channel data
+
+        Returns:
+            dict: Channel data from Knock.
+        """
+        endpoint = '/objects/{}/{}/channel_data/{}'.format(collection, id, channel_id)
+        return self.client.request('put', endpoint, payload={'data': channel_data})

knockapi/resources/preferences.py

@@ -1,184 +1,39 @@
 from .service import Service
-
-default_set_id = "default"
-
+from warnings import warn
 
 class Preferences(Service):
     def get_all(self, user_id):
-        """
-        Get a users full set of preferences
-
-        Args:
-            user_id: The users ID
-
-        Returns:
-            dict: User response from Knock.
-        """
-        endpoint = '/users/{}/preferences'.format(user_id)
-        return self.client.request('get', endpoint)
+        warn("This method is deprecated. Use users.get_all_preferences instead.", DeprecationWarning, stacklevel=2)
+        return self.client.users.get_all_preferences(user_id)
 
     def get(self, user_id, options={}):
-        """
-        Get a users preference set
-
-        Args:
-            user_id (str): The users ID
-            options (dict):
-                preference_set (str): The preference set to retrieve (defaults to "default")
-
-        Returns:
-            dict: User response from Knock.
-        """
-        preference_set_id = options.get('preference_set', default_set_id)
-        endpoint = '/users/{}/preferences/{}'.format(
-            user_id, preference_set_id)
-
-        return self.client.request('get', endpoint)
+        warn("This method is deprecated. Use users.get_preferences instead.", DeprecationWarning, stacklevel=2)
+        return self.client.users.get_preferences(user_id, options)
 
     def update(self, user_id, channel_types=None, categories=None, workflows=None, options={}):
-        """
-        Sets the preference set for the user
-
-        Args:
-            user_id (str): The users ID
-            channel_types (dict): A dictionary of channel type preferences
-            categories (dict): A dictionary of category preferences
-            workflows (dict): A dictionary of workflow preferences
-            options (dict): A dictionary of options
-
-        Returns:
-            dict: User response from Knock.
-        """
-        preference_set_id = options.get('preference_set', default_set_id)
-
-        endpoint = '/users/{}/preferences/{}'.format(
-            user_id, preference_set_id)
-
-        params = {
-            'channel_types': channel_types,
-            'categories': categories,
-            'workflows': workflows
-        }
-
-        return self.client.request('put', endpoint, payload=params)
+        warn("This method is deprecated. Use users.set_preferences instead.", DeprecationWarning, stacklevel=2)
+        return self.client.users.set_preferences(user_id, channel_types=channel_types, categories=categories, workflows=workflows, options=options)
 
     def set_channel_types(self, user_id, preferences, options={}):
-        """
-        Sets the channel type preferences for the user
-
-        Args:
-            user_id (str): The users ID
-            preferences (dict): A dictionary of channel type preferences
-            options (dict): A dictionary of options
-
-        Returns:
-            dict: User response from Knock.
-        """
-        preference_set_id = options.get('preference_set', default_set_id)
-
-        endpoint = '/users/{}/preferences/{}/channel_types'.format(
-            user_id, preference_set_id)
-
-        return self.client.request('put', endpoint, payload=preferences)
+        warn("This method is deprecated. Use users.set_channel_types_preferences instead.", DeprecationWarning, stacklevel=2)
+        return self.client.users.set_channel_types_preferences(user_id, preferences, options=options)
 
     def set_channel_type(self, user_id, channel_type, setting, options={}):
-        """
-        Sets the channel type preference for the user
-
-        Args:
-            user_id (str): The users ID
-            channel_type (str): The channel_type to set
-            setting (boolean): The preference setting 
-            options (dict): A dictionary of options
-
-        Returns:
-            dict: User response from Knock.
-        """
-        preference_set_id = options.get('preference_set', default_set_id)
-
-        endpoint = '/users/{}/preferences/{}/channel_types/{}'.format(
-            user_id, preference_set_id, channel_type)
-
-        return self.client.request('put', endpoint, payload={'subscribed': setting})
+        warn("This method is deprecated. Use users.set_channel_type_preferences instead.", DeprecationWarning, stacklevel=2)
+        return self.client.users.set_channel_types_preferences(user_id, channel_type, setting, options=options)
 
     def set_workflows(self, user_id, preferences, options={}):
-        """
-        Sets the workflow preferences for the user
-
-        Args:
-            user_id (str): The users ID
-            preferences (dict): A dictionary of workflow preferences
-            options (dict): A dictionary of options
-
-        Returns:
-            dict: User response from Knock.
-        """
-        preference_set_id = options.get('preference_set', default_set_id)
-
-        endpoint = '/users/{}/preferences/{}/workflows'.format(
-            user_id, preference_set_id)
-
-        return self.client.request('put', endpoint, payload=preferences)
+        warn("This method is deprecated. Use users.set_workflows_preferences instead.", DeprecationWarning, stacklevel=2)
+        return self.client.users.set_workflows_preferences(user_id, preferences, options=options)
 
     def set_workflow(self, user_id, key, setting, options={}):
-        """
-        Sets the workflow preferences for the user
-
-        Args:
-            user_id (str): The users ID
-            key (str): The workflow key
-            setting (boolean or dict): The preference setting 
-            options (dict): A dictionary of options
-
-        Returns:
-            dict: User response from Knock.
-        """
-        preference_set_id = options.get('preference_set', default_set_id)
-
-        endpoint = '/users/{}/preferences/{}/workflows/{}'.format(
-            user_id, preference_set_id, key)
-
-        params = setting if type(setting) is dict else {'subscribed': setting}
-
-        return self.client.request('put', endpoint, payload=params)
+        warn("This method is deprecated. Use users.set_workflow_preferences instead.", DeprecationWarning, stacklevel=2)
+        return self.client.users.set_workflow_preferences(user_id, key, setting, setting, options=options)
 
     def set_categories(self, user_id, preferences, options={}):
-        """
-        Sets the categories preferences for the user
-
-        Args:
-            user_id (str): The users ID
-            preferences (dict): A dictionary of category preferences
-            options (dict): A dictionary of options
-
-        Returns:
-            dict: User response from Knock.
-        """
-        preference_set_id = options.get('preference_set', default_set_id)
-
-        endpoint = '/users/{}/preferences/{}/categories'.format(
-            user_id, preference_set_id)
-
-        return self.client.request('put', endpoint, payload=preferences)
-
+        warn("This method is deprecated. Use users.set_categories_preferences instead.", DeprecationWarning, stacklevel=2)
+        return self.client.users.set_categories_preferences(user_id, preferences, options=options)
+        
     def set_category(self, user_id, key, setting, options={}):
-        """
-        Sets the category preferences for the user
-
-        Args:
-            user_id (str): The users ID
-            key (str): The category key
-            setting (boolean or dict): The preference setting 
-            options (dict): A dictionary of options
-
-        Returns:
-            dict: User response from Knock.
-        """
-        preference_set_id = options.get('preference_set', default_set_id)
-
-        endpoint = '/users/{}/preferences/{}/categories/{}'.format(
-            user_id, preference_set_id, key)
-
-        params = setting if type(setting) is dict else {'subscribed': setting}
-
-        return self.client.request('put', endpoint, payload=params)
+        warn("This method is deprecated. Use users.set_category_preferences instead.", DeprecationWarning, stacklevel=2)
+        return self.client.users.set_category_preferences(user_id, key, setting, setting, options=options)