velocity-python 0.1.94__tar.gz → 0.1.95__tar.gz

{velocity_python-0.1.94 → velocity_python-0.1.95}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.94
+Version: 0.1.95
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.94 → velocity_python-0.1.95}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.94"
+version = "0.1.95"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.94 → velocity_python-0.1.95}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.94"
+__version__ = version = "0.1.95"
 
 import importlib as _importlib
 

velocity_python-0.1.95/src/velocity/aws/sms.py

@@ -0,0 +1,237 @@
+"""AWS End User Messaging (two-way SMS/MMS) helpers.
+
+Two halves, both business-agnostic:
+
+``parse_inbound_event(event)``
+    Normalize inbound two-way SMS deliveries. AWS End User Messaging publishes
+    each inbound message to the SNS topic configured on the receiving phone
+    number; in a Lambda subscribed to that topic the payload arrives as
+    ``event["Records"][n]["Sns"]["Message"]`` (a JSON string). This accepts a
+    full Lambda SNS event, a single SNS record, a decoded payload dict, or the
+    payload's JSON string, and returns a list of :class:`InboundSms`.
+
+``SmsClient``
+    Thin wrapper over the ``pinpoint-sms-voice-v2`` API (the SDK name for AWS
+    End User Messaging): ``send_text`` / ``send_media``. The boto3 client is
+    injectable so callers and tests never need network access.
+
+Neither half reads configuration on its own: the origination identity (phone
+number, pool ARN, or sender id) and optional configuration set are constructor
+or call arguments, so applications keep ownership of where those values come
+from (env, SSM, database).
+"""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from velocity.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class InboundSms:
+    """One inbound SMS/MMS message, normalized from the SNS delivery payload.
+
+    ``keyword`` is AWS's ``messageKeyword`` (the registered keyword the
+    carrier matched, e.g. an opt-in keyword) — it is *not* the first word of
+    the body; use :attr:`first_word` for command routing.
+    """
+
+    origination_number: str = ""
+    destination_number: str = ""
+    body: str = ""
+    message_id: str = ""
+    keyword: str = ""
+    media_urls: List[str] = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def first_word(self) -> str:
+        """First whitespace-delimited token of the body, lowercased."""
+        parts = (self.body or "").split()
+        return parts[0].lower() if parts else ""
+
+    @property
+    def remainder(self) -> str:
+        """The body with the first word removed (original casing preserved)."""
+        parts = (self.body or "").split(None, 1)
+        return parts[1] if len(parts) > 1 else ""
+
+
+def _coerce_payload(value) -> Optional[Dict[str, Any]]:
+    """A payload dict from a dict or JSON string; None when neither."""
+    if isinstance(value, str):
+        try:
+            value = json.loads(value)
+        except (ValueError, TypeError):
+            return None
+    return value if isinstance(value, dict) else None
+
+
+def _payload_to_inbound(payload: Dict[str, Any]) -> Optional[InboundSms]:
+    """Map one End User Messaging inbound payload onto InboundSms.
+
+    Requires at least an origination number — anything else (delivery status
+    events, unrelated SNS traffic on a shared topic) is not an inbound message
+    and returns None.
+    """
+    origination = str(payload.get("originationNumber") or "").strip()
+    if not origination:
+        return None
+    media = payload.get("mediaUrls")
+    if isinstance(media, str):
+        media = [media]
+    if not isinstance(media, list):
+        media = []
+    return InboundSms(
+        origination_number=origination,
+        destination_number=str(payload.get("destinationNumber") or "").strip(),
+        body=str(payload.get("messageBody") or ""),
+        message_id=str(payload.get("inboundMessageId") or "").strip(),
+        keyword=str(payload.get("messageKeyword") or "").strip(),
+        media_urls=[str(u) for u in media if u],
+        raw=payload,
+    )
+
+
+def parse_inbound_event(event) -> List[InboundSms]:
+    """Normalize an inbound two-way SMS delivery into InboundSms objects.
+
+    Accepts, in order of most to least wrapped:
+
+    - a Lambda SNS event: ``{"Records": [{"Sns": {"Message": "<json>"}}]}``
+    - a single SNS record: ``{"Sns": {"Message": "<json>"}}``
+    - the decoded payload dict (or its JSON string) as published by
+      AWS End User Messaging
+
+    Records that do not look like inbound messages are skipped with a warning
+    rather than raising — one malformed record in a batch must not lose the
+    others.
+    """
+    if event is None:
+        return []
+    payload = _coerce_payload(event)
+    if payload is None:
+        return []
+
+    records = payload.get("Records")
+    if not isinstance(records, list):
+        # Single record or bare payload.
+        if "Sns" in payload:
+            records = [payload]
+        else:
+            inbound = _payload_to_inbound(payload)
+            return [inbound] if inbound else []
+
+    messages = []
+    for record in records:
+        if not isinstance(record, dict):
+            continue
+        sns = record.get("Sns")
+        message = _coerce_payload(sns.get("Message")) if isinstance(sns, dict) else None
+        inbound = _payload_to_inbound(message) if message else None
+        if inbound:
+            messages.append(inbound)
+        else:
+            logger.warning(
+                "parse_inbound_event: skipping record that is not an inbound "
+                "SMS payload",
+                extra={"record_keys": sorted(record.keys())},
+            )
+    return messages
+
+
+class SmsClient:
+    """Outbound SMS/MMS via AWS End User Messaging.
+
+    ``origination_identity`` may be a phone number in E.164 form, a phone
+    number ARN, a pool ARN, or a sender ID — whatever the account has
+    provisioned. A per-call ``origination_identity`` overrides the default.
+    """
+
+    def __init__(
+        self,
+        origination_identity: Optional[str] = None,
+        configuration_set: Optional[str] = None,
+        client=None,
+        region: Optional[str] = None,
+    ):
+        self.origination_identity = origination_identity
+        self.configuration_set = configuration_set
+        self.region = region
+        self._client = client
+
+    @property
+    def client(self):
+        if self._client is None:
+            import boto3
+
+            kwargs = {"region_name": self.region} if self.region else {}
+            self._client = boto3.client("pinpoint-sms-voice-v2", **kwargs)
+        return self._client
+
+    def _resolve(self, destination, origination_identity):
+        destination = str(destination or "").strip()
+        origination = str(origination_identity or self.origination_identity or "").strip()
+        if not destination:
+            raise ValueError("SmsClient: destination phone number is required")
+        if not origination:
+            raise ValueError(
+                "SmsClient: origination_identity is required (constructor "
+                "default or per-call argument)"
+            )
+        return destination, origination
+
+    def send_text(
+        self,
+        destination: str,
+        body: str,
+        origination_identity: Optional[str] = None,
+        message_type: str = "TRANSACTIONAL",
+        configuration_set: Optional[str] = None,
+        context: Optional[Dict[str, str]] = None,
+    ) -> str:
+        """Send an SMS; returns the AWS message id."""
+        destination, origination = self._resolve(destination, origination_identity)
+        params = {
+            "DestinationPhoneNumber": destination,
+            "OriginationIdentity": origination,
+            "MessageBody": str(body or ""),
+            "MessageType": message_type,
+        }
+        configuration_set = configuration_set or self.configuration_set
+        if configuration_set:
+            params["ConfigurationSetName"] = configuration_set
+        if context:
+            params["Context"] = context
+        response = self.client.send_text_message(**params)
+        return response.get("MessageId", "")
+
+    def send_media(
+        self,
+        destination: str,
+        body: Optional[str] = None,
+        media_urls: Optional[List[str]] = None,
+        origination_identity: Optional[str] = None,
+        configuration_set: Optional[str] = None,
+        context: Optional[Dict[str, str]] = None,
+    ) -> str:
+        """Send an MMS (``media_urls`` are s3:// URIs); returns the message id."""
+        destination, origination = self._resolve(destination, origination_identity)
+        params = {
+            "DestinationPhoneNumber": destination,
+            "OriginationIdentity": origination,
+        }
+        if body:
+            params["MessageBody"] = str(body)
+        if media_urls:
+            params["MediaUrls"] = [str(u) for u in media_urls]
+        configuration_set = configuration_set or self.configuration_set
+        if configuration_set:
+            params["ConfigurationSetName"] = configuration_set
+        if context:
+            params["Context"] = context
+        response = self.client.send_media_message(**params)
+        return response.get("MessageId", "")

velocity_python-0.1.95/src/velocity/aws/tests/test_sms.py

@@ -0,0 +1,178 @@
+"""Unit tests for velocity.aws.sms (AWS End User Messaging helpers)."""
+
+import json
+import unittest
+
+from velocity.aws.sms import InboundSms, SmsClient, parse_inbound_event
+
+
+def _payload(**overrides):
+    payload = {
+        "originationNumber": "+14255550182",
+        "destinationNumber": "+12125550101",
+        "messageKeyword": "KEYWORD_JOIN",
+        "messageBody": "receipt 42.50 office supplies",
+        "inboundMessageId": "cae173d2-66b9-564c-8309-21f858e9fb84",
+        "previousPublishedMessageId": "prev-id",
+    }
+    payload.update(overrides)
+    return payload
+
+
+def _sns_event(*payloads):
+    return {
+        "Records": [
+            {
+                "EventSource": "aws:sns",
+                "Sns": {"Message": json.dumps(p)},
+            }
+            for p in payloads
+        ]
+    }
+
+
+class TestParseInboundEvent(unittest.TestCase):
+    def test_full_lambda_sns_event(self):
+        event = _sns_event(_payload())
+        messages = parse_inbound_event(event)
+        self.assertEqual(len(messages), 1)
+        msg = messages[0]
+        self.assertEqual(msg.origination_number, "+14255550182")
+        self.assertEqual(msg.destination_number, "+12125550101")
+        self.assertEqual(msg.body, "receipt 42.50 office supplies")
+        self.assertEqual(msg.message_id, "cae173d2-66b9-564c-8309-21f858e9fb84")
+        self.assertEqual(msg.keyword, "KEYWORD_JOIN")
+        self.assertEqual(msg.media_urls, [])
+        self.assertEqual(msg.raw["previousPublishedMessageId"], "prev-id")
+
+    def test_multiple_records_including_mms(self):
+        event = _sns_event(
+            _payload(),
+            _payload(
+                inboundMessageId="mms-1",
+                mediaUrls=["s3://bucket/media/one.jpg", "s3://bucket/media/two.jpg"],
+            ),
+        )
+        messages = parse_inbound_event(event)
+        self.assertEqual(len(messages), 2)
+        self.assertEqual(messages[1].media_urls, [
+            "s3://bucket/media/one.jpg",
+            "s3://bucket/media/two.jpg",
+        ])
+
+    def test_bare_payload_dict(self):
+        messages = parse_inbound_event(_payload())
+        self.assertEqual(len(messages), 1)
+        self.assertEqual(messages[0].origination_number, "+14255550182")
+
+    def test_payload_json_string(self):
+        messages = parse_inbound_event(json.dumps(_payload()))
+        self.assertEqual(len(messages), 1)
+
+    def test_single_sns_record(self):
+        messages = parse_inbound_event({"Sns": {"Message": json.dumps(_payload())}})
+        self.assertEqual(len(messages), 1)
+
+    def test_malformed_record_skipped_others_kept(self):
+        event = _sns_event(_payload())
+        event["Records"].insert(0, {"Sns": {"Message": "not json"}})
+        event["Records"].insert(0, "not a dict")
+        messages = parse_inbound_event(event)
+        self.assertEqual(len(messages), 1)
+
+    def test_non_inbound_payload_returns_empty(self):
+        # A delivery-status style event has no originationNumber.
+        self.assertEqual(parse_inbound_event({"eventType": "TEXT_DELIVERED"}), [])
+        self.assertEqual(parse_inbound_event(None), [])
+        self.assertEqual(parse_inbound_event("not json"), [])
+        self.assertEqual(parse_inbound_event(42), [])
+
+    def test_media_urls_string_coerced_to_list(self):
+        messages = parse_inbound_event(_payload(mediaUrls="s3://bucket/only.jpg"))
+        self.assertEqual(messages[0].media_urls, ["s3://bucket/only.jpg"])
+
+    def test_first_word_and_remainder(self):
+        msg = InboundSms(body="Receipt 42.50 office supplies")
+        self.assertEqual(msg.first_word, "receipt")
+        self.assertEqual(msg.remainder, "42.50 office supplies")
+        self.assertEqual(InboundSms(body="").first_word, "")
+        self.assertEqual(InboundSms(body="help").remainder, "")
+
+
+class FakeBotoClient:
+    def __init__(self):
+        self.text_calls = []
+        self.media_calls = []
+
+    def send_text_message(self, **kwargs):
+        self.text_calls.append(kwargs)
+        return {"MessageId": "text-msg-id"}
+
+    def send_media_message(self, **kwargs):
+        self.media_calls.append(kwargs)
+        return {"MessageId": "media-msg-id"}
+
+
+class TestSmsClient(unittest.TestCase):
+    def setUp(self):
+        self.boto = FakeBotoClient()
+        self.client = SmsClient(
+            origination_identity="+18885550100",
+            configuration_set="default-set",
+            client=self.boto,
+        )
+
+    def test_send_text_uses_defaults(self):
+        message_id = self.client.send_text("+14255550182", "hello")
+        self.assertEqual(message_id, "text-msg-id")
+        call = self.boto.text_calls[0]
+        self.assertEqual(call["DestinationPhoneNumber"], "+14255550182")
+        self.assertEqual(call["OriginationIdentity"], "+18885550100")
+        self.assertEqual(call["MessageBody"], "hello")
+        self.assertEqual(call["MessageType"], "TRANSACTIONAL")
+        self.assertEqual(call["ConfigurationSetName"], "default-set")
+        self.assertNotIn("Context", call)
+
+    def test_send_text_overrides(self):
+        self.client.send_text(
+            "+14255550182",
+            "hello",
+            origination_identity="+18885550999",
+            configuration_set="other-set",
+            context={"job_id": "abc"},
+        )
+        call = self.boto.text_calls[0]
+        self.assertEqual(call["OriginationIdentity"], "+18885550999")
+        self.assertEqual(call["ConfigurationSetName"], "other-set")
+        self.assertEqual(call["Context"], {"job_id": "abc"})
+
+    def test_send_text_requires_destination_and_origination(self):
+        with self.assertRaises(ValueError):
+            self.client.send_text("", "hello")
+        bare = SmsClient(client=self.boto)
+        with self.assertRaises(ValueError):
+            bare.send_text("+14255550182", "hello")
+
+    def test_send_media(self):
+        message_id = self.client.send_media(
+            "+14255550182",
+            body="see attached",
+            media_urls=["s3://bucket/receipt.jpg"],
+        )
+        self.assertEqual(message_id, "media-msg-id")
+        call = self.boto.media_calls[0]
+        self.assertEqual(call["MediaUrls"], ["s3://bucket/receipt.jpg"])
+        self.assertEqual(call["MessageBody"], "see attached")
+
+    def test_send_media_body_optional(self):
+        self.client.send_media("+14255550182", media_urls=["s3://bucket/a.jpg"])
+        self.assertNotIn("MessageBody", self.boto.media_calls[0])
+
+    def test_no_configuration_set_when_unset(self):
+        bare = SmsClient(origination_identity="+18885550100", client=self.boto)
+        bare.send_text("+14255550182", "hi")
+        self.assertNotIn("ConfigurationSetName", self.boto.text_calls[0])
+
+
+if __name__ == "__main__":
+    unittest.main()

{velocity_python-0.1.94 → velocity_python-0.1.95}/src/velocity_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.94
+Version: 0.1.95
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.94 → velocity_python-0.1.95}/src/velocity_python.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ src/velocity/aws/amplify_build.py
 src/velocity/aws/dirty_pipeline.py
 src/velocity/aws/job_results.py
 src/velocity/aws/s3.py
+src/velocity/aws/sms.py
 src/velocity/aws/ssm_config.py
 src/velocity/aws/assets/__init__.py
 src/velocity/aws/assets/backfill.py
@@ -44,6 +45,7 @@ src/velocity/aws/tests/test_deploy_policies.py
 src/velocity/aws/tests/test_deploy_reconcile.py
 src/velocity/aws/tests/test_lambda_handler_json_serialization.py
 src/velocity/aws/tests/test_response.py
+src/velocity/aws/tests/test_sms.py
 src/velocity/db/__init__.py
 src/velocity/db/exceptions.py
 src/velocity/db/maintenance.py