sendly 4.3.0__tar.gz → 4.4.0__tar.gz

{sendly-4.3.0 → sendly-4.4.0}/CHANGELOG.md

@@ -1,5 +1,15 @@
 # sendly (Python)
 
+## 4.4.0
+
+### Minor Changes
+
+- **WhatsApp to SMS fallback.** `messages.send(channel="whatsapp", fallback_to_sms=True)` (sync and async) sends `fallbackToSms`. When WhatsApp can't deliver the message, it goes as an SMS from the same number, billed as an SMS. The new `WhatsAppSmsFallback` (`channel`, `status`, `reason`, `message_id`, `credits_used`, `error`, `content_dropped`) is `WhatsAppMessage.fallback`; when the SMS went in place of the WhatsApp message, `status` is `failed` and `fallback.status` is `sent`. `Message` (from `messages.get` and `list`) gains `fallback`, `fallback_of` (on the SMS, the WhatsApp message it replaced), `message_format`, `batch_id` and `media_urls`.
+
+### Patch Changes
+
+- A WhatsApp send that WhatsApp accepted but Sendly couldn't fully record answers 201 without `whatsapp` or `createdAt`, and `messages.send` raised `invalid_response` on it. It now returns the message, with `whatsapp` and `created_at` set to `None`. That message is in flight and was charged, so don't send it again.
+
 ## 4.3.0
 
 ### Minor Changes

{sendly-4.3.0 → sendly-4.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sendly
-Version: 4.3.0
+Version: 4.4.0
 Summary: Official Sendly Python SDK for SMS messaging
 Project-URL: Homepage, https://sendly.live
 Project-URL: Documentation, https://sendly.live/docs
@@ -1072,9 +1072,10 @@ client.messages.send(
 
 Uploads accept JPEG, PNG and GIF up to 600 KB. When `content_type` is one of
 those types but the content is not, the upload raises `SendlyError` with code
-`invalid_file`; any other `content_type`, or a file over 600 KB, raises
-`internal_error` (HTTP 500) with the reason in the message. Without MMS enabled
-for your account it is `feature_disabled`.
+`invalid_file`; any other `content_type` raises `unsupported_media_type`
+(HTTP 415) with the reason in the message, and a file over 600 KB raises
+`file_too_large` (HTTP 413). Without MMS enabled for your account it is
+`feature_disabled`.
 
 ## Account & Credits
 
@@ -2592,7 +2593,6 @@ client.enterprise.workspaces.revoke_key("ws_xxx", "key_abc")
 
 # Pooled credits and auto top-up
 client.enterprise.credits.get()
-client.enterprise.credits.deposit(10000, description="Q2 top-up")
 client.enterprise.settings.update_auto_top_up(
     enabled=True, threshold=1000, amount=5000, source_workspace_id="ws_source"
 )

{sendly-4.3.0 → sendly-4.4.0}/README.md

@@ -1037,9 +1037,10 @@ client.messages.send(
 
 Uploads accept JPEG, PNG and GIF up to 600 KB. When `content_type` is one of
 those types but the content is not, the upload raises `SendlyError` with code
-`invalid_file`; any other `content_type`, or a file over 600 KB, raises
-`internal_error` (HTTP 500) with the reason in the message. Without MMS enabled
-for your account it is `feature_disabled`.
+`invalid_file`; any other `content_type` raises `unsupported_media_type`
+(HTTP 415) with the reason in the message, and a file over 600 KB raises
+`file_too_large` (HTTP 413). Without MMS enabled for your account it is
+`feature_disabled`.
 
 ## Account & Credits
 
@@ -2557,7 +2558,6 @@ client.enterprise.workspaces.revoke_key("ws_xxx", "key_abc")
 
 # Pooled credits and auto top-up
 client.enterprise.credits.get()
-client.enterprise.credits.deposit(10000, description="Q2 top-up")
 client.enterprise.settings.update_auto_top_up(
     enabled=True, threshold=1000, amount=5000, source_workspace_id="ws_source"
 )

{sendly-4.3.0 → sendly-4.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sendly"
-version = "4.3.0"
+version = "4.4.0"
 description = "Official Sendly Python SDK for SMS messaging"
 readme = "README.md"
 license = "MIT"

{sendly-4.3.0 → sendly-4.4.0}/sendly/__init__.py

@@ -29,7 +29,7 @@ Async Example:
     >>> asyncio.run(main())
 """
 
-__version__ = "4.3.0"
+__version__ = "4.4.0"
 
 # Main clients
 from .client import AsyncSendly, Sendly
@@ -160,6 +160,7 @@ from .types import (
     TenDlcThroughput,
     # WhatsApp types
     WhatsAppMessage,
+    WhatsAppSmsFallback,
     WhatsAppMessageDetails,
     WhatsAppMessageTemplate,
     WhatsAppSender,
@@ -409,6 +410,7 @@ __all__ = [
     "TenDlcThroughput",
     # WhatsApp types
     "WhatsAppMessage",
+    "WhatsAppSmsFallback",
     "WhatsAppMessageDetails",
     "WhatsAppMessageTemplate",
     "WhatsAppSender",

{sendly-4.3.0 → sendly-4.4.0}/sendly/resources/media.py

@@ -49,10 +49,11 @@ class MediaResource:
             ValidationError: If no file reached the API (code ``invalid_request``)
             SendlyError: With code ``invalid_file`` when content_type is
                 image/jpeg, image/png or image/gif but the content is not a
-                JPEG, PNG or GIF; ``internal_error`` (HTTP 500) when
-                content_type is any other type or the file is over 600 KB,
-                with the reason in the message; or ``feature_disabled`` when
-                MMS is not enabled for your account
+                JPEG, PNG or GIF; ``unsupported_media_type`` (HTTP 415) when
+                content_type is any other type, with the reason in the
+                message; ``file_too_large`` (HTTP 413) when the file is over
+                600 KB; or ``feature_disabled`` when MMS is not enabled for
+                your account
             AuthenticationError: If the API key is invalid
             RateLimitError: If rate limit is exceeded
 

{sendly-4.3.0 → sendly-4.4.0}/sendly/resources/messages.py

@@ -126,9 +126,13 @@ class MessagesResource:
                 'url': 'https://example.com/track'}}]. Card buttons go in
                 card['suggestions'] instead. Dropped (and disclosed via
                 message.rcs.suggestions_dropped) when the send falls back
-            fallback_to_sms: RCS only - deliver as SMS when the recipient
+            fallback_to_sms: RCS - deliver as SMS when the recipient
                 doesn't support RCS (default True). Pass False to get a 422
-                rcs_not_supported_for_recipient instead
+                rcs_not_supported_for_recipient instead. WhatsApp - default
+                False; True sends an SMS from the same number when WhatsApp
+                can't deliver the message (see message.fallback). The number
+                must be able to send SMS to the recipient, or the API answers
+                403 sms_fallback_unavailable
             idempotency_key: Optional key (1-255 printable ASCII characters)
                 sent as the Idempotency-Key header - retrying with the same
                 key returns the original result instead of sending again.
@@ -242,6 +246,8 @@ class MessagesResource:
                 body["template"] = template
             if metadata:
                 body["metadata"] = metadata
+            if fallback_to_sms is not None:
+                body["fallbackToSms"] = fallback_to_sms
 
             data = self._http.request(
                 method="POST",
@@ -1116,6 +1122,8 @@ class AsyncMessagesResource:
                 body["template"] = template
             if metadata:
                 body["metadata"] = metadata
+            if fallback_to_sms is not None:
+                body["fallbackToSms"] = fallback_to_sms
 
             data = await self._http.request(
                 method="POST",

{sendly-4.3.0 → sendly-4.4.0}/sendly/types.py

@@ -280,6 +280,28 @@ class Message(BaseModel):
     ai_metadata: Optional[Dict[str, Any]] = Field(
         default=None, alias="aiMetadata", description="AI classification metadata for inbound messages"
     )
+    message_format: Optional[str] = Field(
+        default=None,
+        description="The channel and format the message was sent in: sms, mms, whatsapp or rcs",
+    )
+    batch_id: Optional[str] = Field(
+        default=None, description="The batch that sent the message, for a batch message"
+    )
+    media_urls: Optional[List[str]] = Field(
+        default=None, description="The message's media URLs, when it has media"
+    )
+    fallback: Optional["WhatsAppSmsFallback"] = Field(
+        default=None,
+        description=(
+            "On a WhatsApp message sent with fallback_to_sms: what happened to "
+            "its SMS fallback"
+        ),
+    )
+    fallback_of: Optional[str] = Field(
+        default=None,
+        alias="fallbackOf",
+        description="On an SMS fallback: the id of the WhatsApp message it replaced",
+    )
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -925,6 +947,11 @@ class WebhookEventType(str, Enum):
     SHORT_CODE_REJECTED = "short_code.rejected"
     SHORT_CODE_FILED = "short_code.filed"
     SHORT_CODE_LIVE = "short_code.live"
+    SHORT_CODE_SUSPENDED = "short_code.suspended"
+    SHORT_CODE_REACTIVATED = "short_code.reactivated"
+    SHORT_CODE_CANCELLED = "short_code.cancelled"
+    SHORT_CODE_PAYMENT_SUCCEEDED = "short_code.payment_succeeded"
+    SHORT_CODE_PAYMENT_FAILED = "short_code.payment_failed"
 
 
 class ListHealthEventSource(str, Enum):
@@ -3202,6 +3229,42 @@ class WhatsAppMessageDetails(BaseModel):
     model_config = ConfigDict(populate_by_name=True)
 
 
+class WhatsAppSmsFallback(BaseModel):
+    """The SMS fallback of a WhatsApp message sent with fallback_to_sms=True"""
+
+    channel: str = Field(default="sms", description='Always "sms"')
+    status: str = Field(
+        ...,
+        description=(
+            "pending until WhatsApp's outcome is known; sent when the SMS went; "
+            "failed when the SMS was refused or credits ran out; unavailable "
+            "when the SMS could no longer be sent from this number; skipped "
+            "when the WhatsApp failure isn't one an SMS fixes"
+        ),
+    )
+    reason: Optional[str] = Field(
+        default=None,
+        description="What made it fall back: window_closed, whatsapp_refused or whatsapp_failed",
+    )
+    message_id: Optional[str] = Field(
+        default=None, alias="messageId", description="The SMS message's id, once it exists"
+    )
+    credits_used: Optional[int] = Field(
+        default=None, alias="creditsUsed", description="Credits charged for the SMS"
+    )
+    error: Optional[str] = Field(default=None, description="Why the SMS didn't go")
+    content_dropped: Optional[List[str]] = Field(
+        default=None,
+        alias="contentDropped",
+        description="Template parts with no SMS form, such as quick_replies",
+    )
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+Message.model_rebuild()
+
+
 class WhatsAppMessage(BaseModel):
     """A sent WhatsApp message"""
 
@@ -3236,13 +3299,30 @@ class WhatsAppMessage(BaseModel):
             "failed send gives its slot back"
         ),
     )
-    whatsapp: WhatsAppMessageDetails = Field(..., description="WhatsApp-specific details")
-    created_at: str = Field(
-        ..., alias="createdAt", description="When the message was created (ISO 8601)"
+    whatsapp: Optional[WhatsAppMessageDetails] = Field(
+        default=None,
+        description=(
+            "WhatsApp-specific details. None when WhatsApp accepted the message "
+            "but recording it failed: the message is in flight and was charged, "
+            "so don't send it again"
+        ),
+    )
+    created_at: Optional[str] = Field(
+        default=None,
+        alias="createdAt",
+        description="When the message was created (ISO 8601). None in the same case as whatsapp",
     )
     metadata: Optional[Dict[str, Any]] = Field(
         default=None, description="Custom JSON metadata attached to the message"
     )
+    fallback: Optional[WhatsAppSmsFallback] = Field(
+        default=None,
+        description=(
+            "Present when the send asked for fallback_to_sms. When WhatsApp "
+            "couldn't take the message and it went as an SMS, status is "
+            "failed and fallback.status is sent"
+        ),
+    )
 
     model_config = ConfigDict(populate_by_name=True)
 

{sendly-4.3.0 → sendly-4.4.0}/sendly/utils/http.py

@@ -28,7 +28,7 @@ T = TypeVar("T")
 DEFAULT_BASE_URL = "https://sendly.live/api/v1"
 DEFAULT_TIMEOUT = 30.0
 DEFAULT_MAX_RETRIES = 3
-SDK_VERSION = "4.3.0"
+SDK_VERSION = "4.4.0"
 
 
 _WAIT_AND_RETRY_CODES = (

{sendly-4.3.0 → sendly-4.4.0}/tests/test_media.py

@@ -62,26 +62,48 @@ class TestMediaUpload:
 
 
 class TestUploadRejections:
-    def test_a_type_the_route_filters_out_raises_internal_error(
+    def test_a_type_the_route_filters_out_raises_unsupported_media_type(
         self, api_key, httpx_mock: HTTPXMock
     ):
         client = Sendly(api_key)
         httpx_mock.add_response(
             url=f"{BASE}/media",
             method="POST",
-            status_code=500,
-            json={"message": "Only JPEG, PNG, and GIF images are allowed for MMS"},
+            status_code=415,
+            json={
+                "error": "unsupported_media_type",
+                "message": "Only JPEG, PNG, and GIF images are allowed for MMS",
+            },
         )
 
         with pytest.raises(SendlyError) as exc_info:
             client.media.upload(io.BytesIO(b"RIFF0000WEBP"), content_type="image/webp")
 
-        assert exc_info.value.code == "internal_error"
-        assert exc_info.value.status_code == 500
+        assert exc_info.value.code == "unsupported_media_type"
+        assert exc_info.value.status_code == 415
         assert exc_info.value.message == "Only JPEG, PNG, and GIF images are allowed for MMS"
         assert len(httpx_mock.get_requests()) == 1
         client.close()
 
+    def test_a_file_over_the_limit_raises_file_too_large(
+        self, api_key, httpx_mock: HTTPXMock
+    ):
+        client = Sendly(api_key)
+        httpx_mock.add_response(
+            url=f"{BASE}/media",
+            method="POST",
+            status_code=413,
+            json={"error": "file_too_large", "message": 'The file in field "file" is too large.'},
+        )
+
+        with pytest.raises(SendlyError) as exc_info:
+            client.media.upload(io.BytesIO(b"\xff" * 16), content_type="image/jpeg")
+
+        assert exc_info.value.code == "file_too_large"
+        assert exc_info.value.status_code == 413
+        assert len(httpx_mock.get_requests()) == 1
+        client.close()
+
     def test_content_that_is_not_the_declared_image_raises_invalid_file(
         self, api_key, httpx_mock: HTTPXMock
     ):
@@ -102,9 +124,10 @@ class TestUploadRejections:
         assert exc_info.value.code == "invalid_file"
         client.close()
 
-    def test_docs_name_both_rejections(self):
+    def test_docs_name_every_rejection(self):
         doc = MediaResource.upload.__doc__ or ""
 
-        assert "``internal_error`` (HTTP 500)" in doc
+        assert "``unsupported_media_type`` (HTTP 415)" in doc
+        assert "``file_too_large`` (HTTP 413)" in doc
         assert "600 KB" in doc
         assert "``invalid_file``" in doc

{sendly-4.3.0 → sendly-4.4.0}/tests/test_whatsapp.py

@@ -1046,3 +1046,176 @@ class TestAsyncWhatsApp:
         assert message.whatsapp.kind == "text"
 
         await client.close()
+
+
+class TestWhatsAppSmsFallback:
+    def _fallback_message(self, mock_whatsapp_message):
+        return {
+            **mock_whatsapp_message,
+            "status": "failed",
+            "creditsUsed": 0,
+            "fallback": {
+                "channel": "sms",
+                "status": "sent",
+                "reason": "window_closed",
+                "messageId": "msg_sms_1",
+                "creditsUsed": 2,
+            },
+        }
+
+    def test_sends_fallback_to_sms_and_reads_the_fallback(
+        self, api_key, mock_whatsapp_message, httpx_mock: HTTPXMock
+    ):
+        client = Sendly(api_key)
+        httpx_mock.add_response(
+            url="https://sendly.live/api/v1/messages",
+            method="POST",
+            json=self._fallback_message(mock_whatsapp_message),
+        )
+
+        message = client.messages.send(
+            channel="whatsapp",
+            to="+15551234567",
+            from_="+15559876543",
+            text="Your table is ready!",
+            fallback_to_sms=True,
+        )
+
+        payload = json.loads(httpx_mock.get_request().read().decode())
+        assert payload["fallbackToSms"] is True
+        assert message.status.value == "failed"
+        assert message.fallback is not None
+        assert message.fallback.status == "sent"
+        assert message.fallback.message_id == "msg_sms_1"
+        assert message.fallback.credits_used == 2
+
+    def test_leaves_fallback_out_by_default(
+        self, api_key, mock_whatsapp_message, httpx_mock: HTTPXMock
+    ):
+        client = Sendly(api_key)
+        httpx_mock.add_response(
+            url="https://sendly.live/api/v1/messages",
+            method="POST",
+            json=mock_whatsapp_message,
+        )
+
+        message = client.messages.send(
+            channel="whatsapp", to="+15551234567", from_="+15559876543", text="Hi"
+        )
+
+        payload = json.loads(httpx_mock.get_request().read().decode())
+        assert "fallbackToSms" not in payload
+        assert message.fallback is None
+
+    @pytest.mark.asyncio
+    async def test_async_sends_fallback_to_sms(
+        self, api_key, mock_whatsapp_message, httpx_mock: HTTPXMock
+    ):
+        httpx_mock.add_response(
+            url="https://sendly.live/api/v1/messages",
+            method="POST",
+            json=self._fallback_message(mock_whatsapp_message),
+        )
+
+        async with AsyncSendly(api_key) as client:
+            message = await client.messages.send(
+                channel="whatsapp",
+                to="+15551234567",
+                from_="+15559876543",
+                text="Your table is ready!",
+                fallback_to_sms=True,
+            )
+
+        payload = json.loads(httpx_mock.get_request().read().decode())
+        assert payload["fallbackToSms"] is True
+        assert message.fallback.status == "sent"
+
+
+class TestWhatsAppRecoveredSend:
+    def test_reads_a_send_that_was_accepted_but_not_fully_recorded(
+        self, api_key, httpx_mock: HTTPXMock
+    ):
+        client = Sendly(api_key)
+        httpx_mock.add_response(
+            url="https://sendly.live/api/v1/messages",
+            method="POST",
+            status_code=201,
+            json={
+                "id": "msg_wa_1",
+                "channel": "whatsapp",
+                "message_format": "whatsapp",
+                "messageFormat": "whatsapp",
+                "to": "+15551234567",
+                "from": "+15559876543",
+                "status": "sent",
+                "direction": "outbound",
+                "segments": 1,
+                "metadata": {},
+            },
+        )
+
+        message = client.messages.send(
+            channel="whatsapp", to="+15551234567", from_="+15559876543", text="Hi"
+        )
+
+        assert message.id == "msg_wa_1"
+        assert message.status.value == "sent"
+        assert message.whatsapp is None
+        assert message.created_at is None
+        assert len(httpx_mock.get_requests()) == 1
+
+
+class TestMessageFallbackFields:
+    def test_get_reads_the_fallback_of_a_whatsapp_message(
+        self, api_key, mock_message, httpx_mock: HTTPXMock
+    ):
+        client = Sendly(api_key)
+        httpx_mock.add_response(
+            url="https://sendly.live/api/v1/messages/msg_wa_1",
+            method="GET",
+            json={
+                **mock_message,
+                "id": "msg_wa_1",
+                "status": "failed",
+                "message_format": "whatsapp",
+                "messageFormat": "whatsapp",
+                "fallback": {
+                    "channel": "sms",
+                    "status": "sent",
+                    "reason": "whatsapp_failed",
+                    "messageId": "msg_sms_1",
+                    "creditsUsed": 2,
+                },
+            },
+        )
+
+        message = client.messages.get("msg_wa_1")
+
+        assert message.message_format == "whatsapp"
+        assert message.fallback.status == "sent"
+        assert message.fallback.message_id == "msg_sms_1"
+        assert message.fallback_of is None
+
+    def test_get_links_an_sms_fallback_to_its_whatsapp_message(
+        self, api_key, mock_message, httpx_mock: HTTPXMock
+    ):
+        client = Sendly(api_key)
+        httpx_mock.add_response(
+            url="https://sendly.live/api/v1/messages/msg_sms_1",
+            method="GET",
+            json={
+                **mock_message,
+                "id": "msg_sms_1",
+                "message_format": "sms",
+                "batch_id": "batch_1",
+                "media_urls": ["https://example.com/a.png"],
+                "fallbackOf": "msg_wa_1",
+            },
+        )
+
+        message = client.messages.get("msg_sms_1")
+
+        assert message.fallback_of == "msg_wa_1"
+        assert message.batch_id == "batch_1"
+        assert message.media_urls == ["https://example.com/a.png"]
+        assert message.fallback is None