smsflow 0.1.0__py3-none-any.whl

smsflow/__init__.py

@@ -0,0 +1,3 @@
+from .client import SmsFlowClient, SmsFlowError
+
+__all__ = ["SmsFlowClient", "SmsFlowError"]

smsflow/client.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, Iterable
+
+try:
+    import requests
+except ImportError:  # pragma: no cover - exercised only when dependencies are not installed.
+    requests = None
+
+
+class SmsFlowError(Exception):
+    def __init__(self, message: str, *, status_code: int | None = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+@dataclass
+class _CachedAuth:
+    token: str
+    refresh_at: datetime
+
+
+class SmsFlowClient:
+    def __init__(
+        self,
+        *,
+        client_id: str,
+        client_secret: str,
+        base_url: str = "https://portal.smsflow.co.za/",
+        session: Any = None,
+        timeout: int = 30,
+    ) -> None:
+        if not client_id or not client_secret:
+            raise SmsFlowError("SMSFlow client_id and client_secret are required.")
+
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.base_url = base_url.rstrip("/")
+        if session is None and requests is None:
+            raise SmsFlowError("The requests package is required when no custom session is supplied.")
+
+        self.session = session or requests.Session()
+        self.timeout = timeout
+        self._cached_auth: _CachedAuth | None = None
+
+    def authenticate(self) -> dict[str, Any]:
+        response = self.session.get(
+            f"{self.base_url}/api/integration/authentication",
+            auth=(self.client_id, self.client_secret),
+            timeout=self.timeout,
+        )
+        body = _read_body(response)
+
+        if not response.ok:
+            raise SmsFlowError("SMSFlow authentication failed.", status_code=response.status_code, body=body)
+
+        token = body.get("token")
+        expires_in = int(body.get("expiresInMinutes", 1))
+        if not token:
+            raise SmsFlowError("SMSFlow authentication did not return a token.")
+
+        self._cached_auth = _CachedAuth(
+            token=token,
+            refresh_at=datetime.now(timezone.utc) + timedelta(minutes=max(expires_in - 5, 1)),
+        )
+        return body
+
+    def send_sms(
+        self,
+        *,
+        campaign_name: str,
+        messages: Iterable[dict[str, str]],
+        start_delivery_utc: str | None = None,
+        check_opt_outs: bool = True,
+    ) -> dict[str, Any]:
+        message_list = list(messages)
+        if not message_list:
+            raise SmsFlowError("At least one SMS message is required.")
+
+        response = self.session.post(
+            f"{self.base_url}/api/integration/BulkMessages",
+            headers={"Authorization": f"Bearer {self._get_token()}"},
+            json={
+                "SendOptions": {
+                    "startDeliveryUtc": start_delivery_utc,
+                    "campaignName": campaign_name,
+                    "checkOptOuts": check_opt_outs,
+                },
+                "messages": [
+                    {
+                        "content": message["content"],
+                        "destination": message["destination"],
+                    }
+                    for message in message_list
+                ],
+            },
+            timeout=self.timeout,
+        )
+        body = _read_body(response)
+
+        if not response.ok:
+            raise SmsFlowError("SMSFlow send failed.", status_code=response.status_code, body=body)
+
+        return body
+
+    def get_balance(self) -> dict[str, Any]:
+        response = self.session.get(
+            f"{self.base_url}/api/integration/Balance",
+            headers={"Authorization": f"Bearer {self._get_token()}"},
+            timeout=self.timeout,
+        )
+        body = _read_body(response)
+
+        if not response.ok:
+            raise SmsFlowError("SMSFlow balance request failed.", status_code=response.status_code, body=body)
+
+        return body
+
+    def _get_token(self) -> str:
+        if self._cached_auth and datetime.now(timezone.utc) < self._cached_auth.refresh_at:
+            return self._cached_auth.token
+
+        auth = self.authenticate()
+        return auth["token"]
+
+
+def _read_body(response: Any) -> Any:
+    if not response.content:
+        return None
+
+    try:
+        return response.json()
+    except ValueError:
+        return response.text

smsflow-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: smsflow
+Version: 0.1.0
+Summary: Python client library for the SMSFlow HTTPS API.
+Author: SMSFlow
+License-Expression: MIT
+Project-URL: Documentation, https://docs.smsflow.co.za/
+Project-URL: Repository, https://github.com/SMSFlow-ZA/smsflow-python
+Project-URL: Issues, https://github.com/SMSFlow-ZA/smsflow-python/issues
+Keywords: sms,sms-api,smsflow,notifications
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Dynamic: license-file
+
+# SMSFlow Python SDK
+
+The SMSFlow Python SDK makes it easy to send SMS messages and check SMS credit balance from backend Python applications, automation scripts, scheduled jobs, CRM integrations, ERP integrations, and operational tooling.
+
+Documentation: https://docs.smsflow.co.za/
+
+## Install
+
+Package publishing is not enabled yet. During development, install locally:
+
+```bash
+pip install smsflow
+```
+
+## Configuration
+
+Store credentials in environment variables or your platform's secret manager.
+
+```bash
+export SMSFLOW_CLIENT_ID="YOUR_CLIENT_ID"
+export SMSFLOW_CLIENT_SECRET="YOUR_CLIENT_SECRET"
+```
+
+Do not put SMSFlow Client Secrets in source code, logs, notebooks, screenshots, or public issues.
+
+## Usage
+
+```python
+import os
+from smsflow import SmsFlowClient
+
+client = SmsFlowClient(
+    client_id=os.environ["SMSFLOW_CLIENT_ID"],
+    client_secret=os.environ["SMSFLOW_CLIENT_SECRET"],
+)
+
+response = client.send_sms(
+    campaign_name="Python SDK example",
+    messages=[
+        {
+            "destination": "27000000000",
+            "content": "Your SMSFlow Python test message was sent successfully.",
+        }
+    ],
+)
+
+print(response["sendResponse"]["eventId"])
+```
+
+## Features
+
+- Get and cache SMSFlow login tokens.
+- Send one or more SMS messages.
+- Schedule SMS messages using UTC delivery time.
+- Respect opt-out checks by default.
+- Check account balance.
+- Raise structured exceptions when the API returns an error.
+
+## Local test send
+
+This command sends a real SMS and may consume test credits:
+
+```bash
+export SMSFLOW_CLIENT_ID="YOUR_CLIENT_ID"
+export SMSFLOW_CLIENT_SECRET="YOUR_CLIENT_SECRET"
+export SMSFLOW_DESTINATION="27000000000"
+PYTHONPATH=src python examples/send_sms.py
+```
+
+## Security
+
+Never commit real credentials. Use environment variables or a secret manager.
+
+## License
+
+MIT

smsflow-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+smsflow/__init__.py,sha256=MeEAMCx9auJfmoYCwwTpleyaZCU72UmWjawwdHTYWi0,93
+smsflow/client.py,sha256=0WpqWdjiple-eyg8-CTAsXIhnjhhEGb_SUGVQLo3TJ0,4334
+smsflow-0.1.0.dist-info/licenses/LICENSE,sha256=HP9VFmKJEGCkw-hkbQTlV1vlUTnUBU9tsWfgRmu_wiY,1064
+smsflow-0.1.0.dist-info/METADATA,sha256=K1a7ko-9-6PWHlHKMsiWmeutsZ8eXkS9oAP01HrmQQs,2853
+smsflow-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+smsflow-0.1.0.dist-info/top_level.txt,sha256=5mzoEvmA8Y6TwzmXlH9dYuViuzt7Y4q7TCeEz3mAwcI,8
+smsflow-0.1.0.dist-info/RECORD,,

smsflow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

smsflow-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SMSFlow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smsflow-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+smsflow