[TOOLSLIBS-18] Add Custom Events (#190)

* adds custom event module

* more py2 rms

* properly wires class

* adds custom events url

* adds CustomEvent class

* fixes payload builder

* adds custom events tests

* cleanup for doc generation

* adds docs

* adds sphinx docs build to test run

* typo fixes

Author: aschuman0

.github/workflows/test_runner.yaml

@@ -24,3 +24,7 @@ jobs:
       - name: Test with pytest
         run: |
           nosetests -v --with-doctest
+      - name: Build Sphinx Docs
+        run: |
+          cd docs/
+          make clean html

docs/custom_events.rst

@@ -0,0 +1,5 @@
+Custom Events
+*************
+
+.. autoclass:: urbanairship.custom_events.custom_events.CustomEvent
+    :members:

docs/index.rst

@@ -104,6 +104,7 @@ Contents
    devices.rst
    audience.rst
    reports.rst
+   custom_events.rst
 
 
 Indices and tables

setup.py

@@ -23,6 +23,7 @@
         "urbanairship.reports",
         "urbanairship.automation",
         "urbanairship.experiments",
+        "urbanairship.custom_events",
     ],
     license="BSD License",
     classifiers=[

tests/custom_events/__init__.py

@@ -0,0 +1,66 @@
+import datetime
+import json
+import unittest
+import uuid
+
+import urbanairship as ua
+from tests import TEST_KEY, TEST_TOKEN
+
+
+class TestCustomEvent(unittest.TestCase):
+    def setUp(self):
+        airship = ua.Airship(key=TEST_KEY, token=TEST_TOKEN)
+
+        self.event = ua.CustomEvent(
+            airship=airship, name="test_event", user=ua.named_user("test_named_user")
+        )
+
+    def test_minimum_custom_event(self):
+        self.assertEqual(
+            self.event._payload,
+            {
+                "body": {"name": "test_event"},
+                "user": {"named_user_id": "test_named_user"},
+            },
+        )
+
+    def test_minimum_event_channel(self):
+        self.event.user = ua.channel("0617a35e-b0c2-4b1c-9c41-586ca6b081d6")
+
+        self.assertEqual(
+            self.event._payload,
+            {
+                "body": {"name": "test_event"},
+                "user": {"channel": "0617a35e-b0c2-4b1c-9c41-586ca6b081d6"},
+            },
+        )
+
+    def test_full_custom_event(self):
+        properties = {"key": "value", "nested": {"another": "pair"}}
+
+        self.event.occurred = datetime.datetime(2022, 1, 11, 11, 30, 00)
+        self.event.session_id = "0617a35e-b0c2-4b1c-9c41-586ca6b081d6"
+        self.event.interaction_id = "test_interaction_id"
+        self.event.interaction_type = "test_interaction_type"
+        self.event.value = 1234.56
+        self.event.transaction = "test_transaction"
+        self.event.properties = properties
+
+        self.maxDiff = 10000
+
+        self.assertEqual(
+            self.event._payload,
+            {
+                "occurred": "2022-01-11T11:30:00",
+                "user": {"named_user_id": "test_named_user"},
+                "body": {
+                    "name": "test_event",
+                    "session_id": "0617a35e-b0c2-4b1c-9c41-586ca6b081d6",
+                    "interaction_id": "test_interaction_id",
+                    "interaction_type": "test_interaction_type",
+                    "value": 1234.56,
+                    "transaction": "test_transaction",
+                    "properties": properties,
+                },
+            },
+        )

tests/custom_events/test_custom_events.py

@@ -4,6 +4,7 @@
 from .automation import Automation, Pipeline
 from .common import AirshipFailure, Unauthorized
 from .core import Airship
+from .custom_events import CustomEvent
 from .devices import (
     APIDList,
     Attribute,
@@ -210,6 +211,7 @@
     ExperimentReport,
     KeywordInteraction,
     SubscriptionList,
+    CustomEvent,
 ]
 
 

urbanairship/__init__.py

@@ -1,7 +1,5 @@
 import logging
 import re
-import sys
-import warnings
 
 import requests
 
@@ -36,34 +34,27 @@ def __init__(self, location=None):
         self.attributes_list_url = self.base_url + "attribute-lists/"
         self.message_center_delete_url = self.base_url + "user/messages/"
         self.subscription_lists_url = self.channel_url + "subscription_lists/"
-
         self.templates_url = self.base_url + "templates/"
         self.schedule_template_url = self.templates_url + "schedules/"
-
         self.pipelines_url = self.base_url + "pipelines/"
-
         self.named_user_url = self.base_url + "named_users/"
         self.named_user_tag_url = self.named_user_url + "tags/"
         self.named_user_disassociate_url = self.named_user_url + "disassociate/"
         self.named_user_associate_url = self.named_user_url + "associate/"
         self.named_user_uninstall_url = self.named_user_url + "uninstall/"
-
         self.sms_url = self.channel_url + "sms/"
         self.sms_opt_out_url = self.sms_url + "opt-out/"
         self.sms_uninstall_url = self.sms_url + "uninstall/"
-
         self.email_url = self.channel_url + "email/"
         self.email_tags_url = self.email_url + "tags/"
         self.email_uninstall_url = self.email_url + "uninstall/"
-
         self.create_and_send_url = self.base_url + "create-and-send/"
         self.schedule_create_and_send_url = self.schedules_url + "create-and-send/"
-
         self.experiments_url = self.base_url + "experiments/"
         self.experiments_schedule_url = self.experiments_url + "scheduled/"
         self.experiments_validate = self.experiments_url + "validate/"
-
         self.attachment_url = self.base_url + "attachments/"
+        self.custom_events_url = self.base_url + "custom-events/"
 
     def get(self, endpoint):
         url = getattr(self, endpoint, None)

urbanairship/core.py

@@ -0,0 +1 @@
+from .custom_events import CustomEvent

urbanairship/custom_events/__init__.py

@@ -0,0 +1,176 @@
+import datetime
+from typing import Dict, Optional, Union
+import json
+
+from urbanairship import Airship
+
+
+class CustomEvent:
+    def __init__(
+        self,
+        airship: Airship,
+        name: Optional[str] = None,
+        user: Optional[Dict] = None,
+        interaction_type: Optional[str] = None,
+        interaction_id: Optional[str] = None,
+        properties: Optional[Dict] = None,
+        session_id: Optional[str] = None,
+        transaction: Optional[str] = None,
+        value: Optional[Union[int, float]] = None,
+        occurred: Optional[datetime.datetime] = None,
+    ) -> None:
+        """
+        A class representing an Airship custom event. Please see the
+        documentation at https://docs.airship.com/api/ua/?http#tag-custom-events for
+        details on Custom Event usage.
+
+        :param Airship: [required] An urbanairship.Airship instance initialized with
+            bearer token authentication.
+        :param name: [required] A plain-text name for the event. Airship's analytics
+            systems will roll up events with the same name, providing counts and total
+            value associated with the event. This value cannot contain upper-case
+            characters. If the name contains upper-case characters, you will receive a
+            400 response.
+        :param user: [required] An Airship channel identifier or named user
+            for the user who triggered the event.
+        :param interaction_id: [optional] The identifier defining where the event
+            occurred.
+        :param interaction_type: [optional] Describes the type of interaction that
+            triggered the event
+        :param properties: [optional] A dict containing custom event properties.
+        :param session_id: [optional] The user session during which the event occurred.
+            You must supply and maintain session identifiers.
+        :param transaction: [optional] If the event is one in a series representing a
+            single transaction, use the transaction field to tie events together.
+        :param value: [optional] If the event is associated with a count or amount,
+            the 'value' field carries that information.
+        :param occurred: [optional The date and time when the event occurred. Events
+            must have occurred within the past 90 days. You cannot provide
+            a future datetime.
+        """
+        self.airship = airship
+        self.name = name
+        self.user = user
+        self.interaction_type = interaction_type
+        self.interaction_id = interaction_id
+        self.properties = properties
+        self.session_id = session_id
+        self.transaction = transaction
+        self.value = value
+        self.occurred = occurred
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        self._name = value
+
+    @property
+    def user(self) -> Dict:
+        if "named_user" in self._user.keys():
+            return {"named_user_id": self._user["named_user"]}
+
+        return self._user
+
+    @user.setter
+    def user(self, value: Dict) -> None:
+        self._user = value
+
+    @property
+    def interaction_id(self) -> Optional[str]:
+        return self._interaction_id
+
+    @interaction_id.setter
+    def interaction_id(self, value: str) -> None:
+        self._interaction_id = value
+
+    @property
+    def interaction_type(self) -> Optional[str]:
+        return self._interaction_type
+
+    @interaction_type.setter
+    def interaction_type(self, value: str) -> None:
+        self._interaction_type = value
+
+    @property
+    def properties(self) -> Optional[Dict]:
+        return self._properties
+
+    @properties.setter
+    def properties(self, value: Optional[Dict]) -> None:
+        self._properties = value
+
+    @property
+    def session_id(self) -> Optional[str]:
+        return self._session_id
+
+    @session_id.setter
+    def session_id(self, value: Optional[str]) -> None:
+        self._session_id = value
+
+    @property
+    def transaciton(self) -> Optional[str]:
+        return self._transaction
+
+    @transaciton.setter
+    def transaction(self, value: Optional[str]) -> None:
+        self._transaction = value
+
+    @property
+    def value(self) -> Optional[Union[int, float]]:
+        return self._value
+
+    @value.setter
+    def value(self, value: Optional[Union[int, float]]):
+        self._value = value
+
+    @property
+    def occurred(self) -> Optional[str]:
+        if not isinstance(self._occurred, datetime.datetime):
+            return self._occurred
+        return self._occurred.strftime("%Y-%m-%dT%H:%M:%S")
+
+    @occurred.setter
+    def occurred(self, value: Optional[datetime.datetime]) -> None:
+        self._occurred = value
+
+    @property
+    def _payload(self) -> Dict:
+        event_payload = {"user": self.user}
+        body = {"name": self.name}
+
+        for payload_attr in ["occurred"]:
+            if getattr(self, payload_attr) is not None:
+                event_payload[payload_attr] = getattr(self, payload_attr)
+
+        for body_attr in [
+            "value",
+            "transaction",
+            "interaction_id",
+            "interaction_type",
+            "properties",
+            "session_id",
+        ]:
+            if getattr(self, body_attr) is not None:
+                body[body_attr] = getattr(self, body_attr)
+
+        event_payload["body"] = body
+
+        return event_payload
+
+    def send(self) -> Dict:
+        """Send the Custom Event to Airship systems
+
+        :returns: API response dict
+        """
+        response = self.airship.request(
+            method="POST",
+            body=json.dumps(self._payload),
+            url=self.airship.urls.get("custom_events_url"),
+            content_type="application/json",
+            version=3,
+        )
+
+        return response.json()