[TOOLSLIBS-2437] SMS Field Updates (#220)

* add new fields

* new version updates

Author: aschuman0

CHANGELOG

@@ -1,5 +1,16 @@
 # urbanairship changelog
 
+## 7.2.0
+
+- Adds new fields to the SMS class for enhanced opt-in management:
+  - `opted_out`: Optional datetime for tracking when users opt out of SMS messages
+  - `opt_in_mode`: Optional string ("classic" or "double") for opt-in mode configuration
+  - `properties`: Optional dict for event properties used with double opt-in
+- Updates SMS payload structure to properly handle different API contexts:
+  - Registration payloads exclude opt_in_mode, properties, and opted_out
+  - Update payloads include opted_out but exclude opt_in_mode and properties
+  - Create-and-send audience includes all fields including ua_opted_out
+
 ## 7.1.1
 
 - Fixes a bug where the EmailAttachment class was not properly encoding file data.

tests/devices/test_sms.py

@@ -17,9 +17,7 @@ def test_sms_channel_reg(self):
 
         with mock.patch.object(ua.Airship, "_request") as mock_request:
             response = requests.Response()
-            response._content = json.dumps({"ok": True, "status": "pending"}).encode(
-                "utf-8"
-            )
+            response._content = json.dumps({"ok": True, "status": "pending"}).encode("utf-8")
             response.status_code = 202
             mock_request.return_value = response
 
@@ -38,9 +36,7 @@ def test_sms_channel_reg_with_optin(self):
 
         with mock.patch.object(ua.Airship, "_request") as mock_request:
             response = requests.Response()
-            response._content = json.dumps(
-                {"ok": True, "channel_id": channel_id}
-            ).encode("utf-8")
+            response._content = json.dumps({"ok": True, "channel_id": channel_id}).encode("utf-8")
             response.status_code = 201
             mock_request.return_value = response
 
@@ -90,7 +86,7 @@ def test_sms_registration_payload_property(self):
             airship=ua.Airship(TEST_KEY, TEST_SECRET),
             sender="12345",
             msisdn="15035556789",
-            opted_in="2018-02-13T11:58:59",
+            opted_in=datetime(2018, 2, 13, 11, 58, 59),
             locale_country="us",
             locale_language="en",
             timezone="America/Los_Angeles",
@@ -146,6 +142,157 @@ def test_sms_lookup(self):
 
             self.assertTrue(r.ok)
 
+    def test_sms_registration_payload_with_new_fields(self):
+        """Test SMS registration payload with new fields: opted_out, opt_in_mode, properties."""
+        sms = ua.Sms(
+            airship=ua.Airship(TEST_KEY, TEST_SECRET),
+            sender="12345",
+            msisdn="15035556789",
+            opted_in=datetime(2018, 2, 13, 11, 58, 59),
+            opted_out=datetime(2018, 3, 15, 14, 30, 0),
+            opt_in_mode="double",
+            properties={"source": "web_form", "campaign": "summer_2023"},
+            locale_country="us",
+            locale_language="en",
+            timezone="America/Los_Angeles",
+        )
+
+        self.assertEqual(
+            sms._registration_payload,
+            {
+                "sender": "12345",
+                "msisdn": "15035556789",
+                "locale_language": "en",
+                "locale_country": "us",
+                "timezone": "America/Los_Angeles",
+                "opted_in": "2018-02-13T11:58:59",
+            },
+        )
+
+    def test_sms_update_payload(self):
+        """Test SMS update payload excludes opt_in_mode and properties."""
+        sms = ua.Sms(
+            airship=ua.Airship(TEST_KEY, TEST_SECRET),
+            sender="12345",
+            msisdn="15035556789",
+            opted_in=datetime(2018, 2, 13, 11, 58, 59),
+            opted_out=datetime(2018, 3, 15, 14, 30, 0),
+            opt_in_mode="double",
+            properties={"source": "web_form"},
+            locale_country="us",
+            locale_language="en",
+            timezone="America/Los_Angeles",
+        )
+
+        self.assertEqual(
+            sms._update_payload,
+            {
+                "sender": "12345",
+                "msisdn": "15035556789",
+                "locale_language": "en",
+                "locale_country": "us",
+                "timezone": "America/Los_Angeles",
+                "opted_in": "2018-02-13T11:58:59",
+                "opted_out": "2018-03-15T14:30:00",
+            },
+        )
+
+    def test_sms_create_and_send_audience_with_new_fields(self):
+        """Test SMS create and send audience includes new fields."""
+        sms = ua.Sms(
+            airship=ua.Airship(TEST_KEY, TEST_SECRET),
+            sender="12345",
+            msisdn="15035556789",
+            opted_in=datetime(2018, 2, 13, 11, 58, 59),
+            opted_out=datetime(2018, 3, 15, 14, 30, 0),
+            template_fields={"name": "John Doe", "preference": "text"},
+        )
+
+        audience = sms.create_and_send_audience
+        self.assertEqual(audience["ua_sender"], "12345")
+        self.assertEqual(audience["ua_msisdn"], "15035556789")
+        self.assertEqual(audience["ua_opted_in"], datetime(2018, 2, 13, 11, 58, 59))
+        self.assertEqual(audience["ua_opted_out"], datetime(2018, 3, 15, 14, 30, 0))
+        self.assertEqual(audience["name"], "John Doe")
+        self.assertEqual(audience["preference"], "text")
+
+    def test_sms_create_and_send_audience_without_opted_in_raises(self):
+        """Test SMS create and send audience raises error without opted_in."""
+        sms = ua.Sms(
+            airship=ua.Airship(TEST_KEY, TEST_SECRET),
+            sender="12345",
+            msisdn="15035556789",
+        )
+
+        with self.assertRaises(ValueError) as context:
+            sms.create_and_send_audience
+
+        self.assertIn("must include opt-in datestamps", str(context.exception))
+
+    def test_sms_opt_in_mode_validation(self):
+        """Test SMS opt_in_mode validation."""
+        # Valid values
+        sms = ua.Sms(
+            airship=ua.Airship(TEST_KEY, TEST_SECRET),
+            sender="12345",
+            msisdn="15035556789",
+            opt_in_mode="classic",
+        )
+        self.assertEqual(sms.opt_in_mode, "classic")
+
+        sms.opt_in_mode = "double"
+        self.assertEqual(sms.opt_in_mode, "double")
+
+        sms.opt_in_mode = None
+        self.assertIsNone(sms.opt_in_mode)
+
+        # Invalid value
+        with self.assertRaises(ValueError) as context:
+            sms.opt_in_mode = "invalid"
+        self.assertIn("must be one of: 'classic' or 'double'", str(context.exception))
+
+    def test_sms_properties_validation(self):
+        """Test SMS properties validation."""
+        # Valid dict
+        sms = ua.Sms(
+            airship=ua.Airship(TEST_KEY, TEST_SECRET),
+            sender="12345",
+            msisdn="15035556789",
+            properties={"key": "value"},
+        )
+        self.assertEqual(sms.properties, {"key": "value"})
+
+        # None value
+        sms.properties = None
+        self.assertIsNone(sms.properties)
+
+        # Invalid type
+        with self.assertRaises(TypeError) as context:
+            sms.properties = "not_a_dict"
+        self.assertIn("must be a dict", str(context.exception))
+
+    def test_sms_opted_out_datetime_handling(self):
+        """Test SMS opted_out datetime handling."""
+        sms = ua.Sms(
+            airship=ua.Airship(TEST_KEY, TEST_SECRET),
+            sender="12345",
+            msisdn="15035556789",
+        )
+
+        # Set opted_out
+        opted_out_dt = datetime(2018, 3, 15, 14, 30, 0)
+        sms.opted_out = opted_out_dt
+        self.assertEqual(sms.opted_out, opted_out_dt)
+
+        # Clear opted_out
+        sms.opted_out = None
+        self.assertIsNone(sms.opted_out)
+
+        # Test in update payload (opted_out is only included in updates, not registration)
+        sms.opted_out = opted_out_dt
+        update_payload = sms._update_payload
+        self.assertEqual(update_payload["opted_out"], "2018-03-15T14:30:00")
+
 
 class TestSmsKeywordInteraction(unittest.TestCase):
     def setUp(self):

urbanairship/__about__.py

@@ -1 +1 @@
-__version__ = "7.1.1"
+__version__ = "7.2.0"

urbanairship/devices/sms.py

@@ -27,6 +27,16 @@ class Sms(object):
     :param opted_in: A datetime.datetime object that represents the
         date and time when explicit permission was received from the user to
         receive messages. This is required for use with CreateAndSend.
+    :param opted_out: Optional. A datetime.datetime object that represents the
+        date and time when a user opted out of SMS messages.
+    :param opt_in_mode: Optional. The opt-in mode for registering the channel.
+        `classic` is the default when unspecified, `double` creates a
+        `double_opt_in` event.
+    :param properties: Optional. An object containing event properties. You can
+        use these properties to filter the double opt-in event and reference
+        them in your message content by using handlebars. Items in the
+        `properties` object are limited to a 255-character maximum string
+        length.
     :param template_fields: For use with CreateAndSend with inline templates.
         A dict of template field names and their substitution values.
     :param locale_country: The ISO 3166 two-character country code. The value for this
@@ -43,6 +53,9 @@ def __init__(
         sender: str,
         msisdn: str,
         opted_in: Optional[datetime] = None,
+        opted_out: Optional[datetime] = None,
+        opt_in_mode: Optional[str] = None,
+        properties: Optional[Dict] = None,
         template_fields: Optional[Dict] = None,
         locale_country: Optional[str] = None,
         locale_language: Optional[str] = None,
@@ -52,6 +65,9 @@ def __init__(
         self.sender = sender
         self.msisdn = msisdn
         self.opted_in = opted_in
+        self.opted_out = opted_out
+        self.opt_in_mode = opt_in_mode
+        self.properties = properties
         self.template_fields = template_fields
         self.locale_country = locale_country
         self.locale_language = locale_language
@@ -81,6 +97,40 @@ def opted_in(self, value: Optional[datetime]) -> None:
 
         self._opted_in = value
 
+    @property
+    def opted_out(self) -> Optional[datetime]:
+        return self._opted_out
+
+    @opted_out.setter
+    def opted_out(self, value: Optional[datetime]) -> None:
+        if not value:
+            self._opted_out = None
+            return
+
+        self._opted_out = value
+
+    @property
+    def opt_in_mode(self) -> Optional[str]:
+        return self._opt_in_mode
+
+    @opt_in_mode.setter
+    def opt_in_mode(self, value: Optional[str]) -> None:
+        if value not in ["classic", "double"] and value is not None:
+            raise ValueError("opt_in_mode must be one of: 'classic' or 'double'")
+
+        self._opt_in_mode = value
+
+    @property
+    def properties(self) -> Optional[Dict]:
+        return self._properties
+
+    @properties.setter
+    def properties(self, value: Optional[Dict]) -> None:
+        if not isinstance(value, (dict, type(None))):
+            raise TypeError("properties must be a dict")
+
+        self._properties = value
+
     @property
     def locale_language(self) -> Optional[str]:
         return self._locale_language
@@ -135,22 +185,66 @@ def msisdn(self, value: str) -> None:
     def common_payload(self) -> Dict:
         return {"sender": self.sender, "msisdn": self.msisdn}
 
+    @property
+    def _full_payload(self) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"sender": self.sender, "msisdn": self.msisdn}
+
+        reg_payload_keys = [
+            "locale_language",
+            "locale_country",
+            "timezone",
+            "opted_in",
+            "opt_in_mode",
+            "properties",
+        ]
+
+        for key in reg_payload_keys:
+            if getattr(self, key) is not None:
+                if isinstance(getattr(self, key), datetime):
+                    payload[key] = getattr(self, key).strftime("%Y-%m-%dT%H:%M:%S")
+                else:
+                    payload[key] = getattr(self, key)
+
+        return payload
+
     @property
     def _registration_payload(self) -> Dict:
+        # SMS API registration only supports basic fields
         payload = self.common_payload
 
         reg_payload_keys = [
             "locale_language",
             "locale_country",
             "timezone",
-            "template_fields",
             "opted_in",
         ]
 
         for key in reg_payload_keys:
             if getattr(self, key) is not None:
                 if isinstance(getattr(self, key), datetime):
-                    payload[key] = datetime.strptime(getattr(self, key), "%Y-%m-%dT%H:%M:%S")
+                    payload[key] = getattr(self, key).strftime("%Y-%m-%dT%H:%M:%S")
+                else:
+                    payload[key] = getattr(self, key)
+
+        return payload
+
+    @property
+    def _update_payload(self) -> Dict:
+        # SMS API update supports opted_out but not opt_in_mode/properties
+        payload = self.common_payload
+
+        update_payload_keys = [
+            "locale_language",
+            "locale_country",
+            "timezone",
+            "opted_in",
+            "opted_out",
+        ]
+
+        for key in update_payload_keys:
+            if getattr(self, key) is not None:
+                if isinstance(getattr(self, key), datetime):
+                    payload[key] = getattr(self, key).strftime("%Y-%m-%dT%H:%M:%S")
                 else:
                     payload[key] = getattr(self, key)
 
@@ -160,12 +254,14 @@ def _registration_payload(self) -> Dict:
     def create_and_send_audience(self) -> Dict:
         audience: Dict[str, Any] = {"ua_sender": self.sender, "ua_msisdn": self.msisdn}
 
+        if self.opted_in:
+            audience["ua_opted_in"] = self.opted_in
+        if self.opted_out:
+            audience["ua_opted_out"] = self.opted_out
         if self.template_fields:
             audience.update(self.template_fields)
 
-        if self.opted_in:
-            audience["ua_opted_in"] = self.opted_in
-        else:
+        if not self.opted_in:
             raise ValueError("sms objects for create and send must include opt-in datestamps")
         return audience
 
@@ -219,7 +315,7 @@ def update(self, channel_id: Optional[str] = None) -> Response:
 
         response = self.airship.request(
             method="PUT",
-            body=json.dumps(self._registration_payload).encode("utf-8"),
+            body=json.dumps(self._update_payload).encode("utf-8"),
             url=self.airship.urls.get("sms_url") + self.channel_id,
             version=3,
         )