django-mimsms 0.1.0__tar.gz

django_mimsms-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: django-mimsms
+Version: 0.1.0
+Summary: Production-ready Django & Python package for MiMSMS.com bulk SMS API. Features async support, type safety, and seamless Bangladesh SMS gateway integration.
+Author: Mimsms Integration Team
+Project-URL: Homepage, https://github.com/sharf-shawon/django-mimsms
+Project-URL: Bug Tracker, https://github.com/sharf-shawon/django-mimsms/issues
+Project-URL: Documentation, https://github.com/sharf-shawon/django-mimsms#readme
+Project-URL: Repository, https://github.com/sharf-shawon/django-mimsms
+Keywords: django-mimsms,mimsms sms api,django sms integration,bulk sms bangladesh,mimsms.com python,dynamic sms api,sms gateway django
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: django>=5.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: rich>=15.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-django>=4.8.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Requires-Dist: respx>=0.20.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.3.0; extra == "dev"
+Requires-Dist: mypy>=1.9.0; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: rich>=13.0.0; extra == "dev"
+Requires-Dist: django-mimsms[test]; extra == "dev"
+Requires-Dist: python-semantic-release>=9.0.0; extra == "dev"
+
+# django-mimsms: MiMSMS SMS API Integration for Django & Python
+
+[![PyPI version](https://img.shields.io/pypi/v/django-mimsms.svg)](https://pypi.org/project/django-mimsms/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI Status](https://github.com/mimsms/django-mimsms/actions/workflows/ci.yml/badge.svg)](https://github.com/mimsms/django-mimsms/actions)
+
+Seamlessly integrate **MiMSMS.com SMS API** into your Django and Python applications. This package provides a robust, type-safe, and asynchronous client for sending SMS, bulk messages, and tracking delivery reports in Bangladesh.
+
+## Key Features
+
+- **Strict Type Safety**: Fully typed with `mypy` strict checks and Pydantic v2 validation.
+- **Async Support**: Efficient non-blocking I/O using `httpx`.
+- **Django Integration**: Configuration via standard Django settings.
+- **100% Test Coverage**: Comprehensive test suite with deterministic network isolation (`respx`).
+- **Multiple API Support**: Single SMS, Bulk SMS (One-to-Many), and Dynamic SMS (DSMS).
+
+## Installation
+
+Install the package via `pip` or `uv`:
+
+```bash
+# Using pip
+pip install django-mimsms
+
+# Using uv
+uv add django-mimsms
+```
+
+## Django Integration
+
+### 1. Add to `INSTALLED_APPS`
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...,
+    "django_mimsms",
+]
+```
+
+### 2. Configure Settings
+
+Add your MiMSMS credentials to your `settings.py`:
+
+```python
+# settings.py
+MIMSMS_API_KEY = "your_api_key"
+MIMSMS_SENDER_ID = "your_sender_id"
+MIMSMS_USERNAME = "your_username"
+```
+
+### 3. Usage
+
+```python
+from django_mimsms import send_sms
+
+# Send a simple SMS
+response = send_sms(
+    to="88017XXXXXXXX",
+    message="Hello from Django!",
+)
+
+print(response.trxnId)
+```
+
+## Plain Python Usage
+
+If you're not using Django, you can use the `MiMSMSClient` directly:
+
+```python
+import asyncio
+from django_mimsms import MiMSMSClient
+
+async def main():
+    client = MiMSMSClient(
+        api_key="your_api_key",
+        username="your_username",
+        sender_id="your_sender_id"
+    )
+    
+    response = await client.send_sms(
+        to="88017XXXXXXXX",
+        message="Hello from Python!",
+    )
+    print(response.trxnId)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Advanced Features
+
+### Bulk SMS
+Send the same message to multiple recipients:
+
+```python
+from django_mimsms import send_bulk_sms
+
+send_bulk_sms(
+    numbers=["88017XXXXXXXX", "88018XXXXXXXX"],
+    message="Bulk message testing",
+)
+```
+
+### Dynamic SMS
+Send different messages to different recipients in one call:
+
+```python
+from django_mimsms import send_dynamic_sms
+
+messages = [
+    {"to": "88017XXXXXXXX", "message": "Hi Alice!"},
+    {"to": "88018XXXXXXXX", "message": "Hi Bob!"},
+]
+
+send_dynamic_sms(messages)
+```
+
+## License
+
+MIT

django_mimsms-0.1.0/README.md

@@ -0,0 +1,121 @@
+# django-mimsms: MiMSMS SMS API Integration for Django & Python
+
+[![PyPI version](https://img.shields.io/pypi/v/django-mimsms.svg)](https://pypi.org/project/django-mimsms/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI Status](https://github.com/mimsms/django-mimsms/actions/workflows/ci.yml/badge.svg)](https://github.com/mimsms/django-mimsms/actions)
+
+Seamlessly integrate **MiMSMS.com SMS API** into your Django and Python applications. This package provides a robust, type-safe, and asynchronous client for sending SMS, bulk messages, and tracking delivery reports in Bangladesh.
+
+## Key Features
+
+- **Strict Type Safety**: Fully typed with `mypy` strict checks and Pydantic v2 validation.
+- **Async Support**: Efficient non-blocking I/O using `httpx`.
+- **Django Integration**: Configuration via standard Django settings.
+- **100% Test Coverage**: Comprehensive test suite with deterministic network isolation (`respx`).
+- **Multiple API Support**: Single SMS, Bulk SMS (One-to-Many), and Dynamic SMS (DSMS).
+
+## Installation
+
+Install the package via `pip` or `uv`:
+
+```bash
+# Using pip
+pip install django-mimsms
+
+# Using uv
+uv add django-mimsms
+```
+
+## Django Integration
+
+### 1. Add to `INSTALLED_APPS`
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    ...,
+    "django_mimsms",
+]
+```
+
+### 2. Configure Settings
+
+Add your MiMSMS credentials to your `settings.py`:
+
+```python
+# settings.py
+MIMSMS_API_KEY = "your_api_key"
+MIMSMS_SENDER_ID = "your_sender_id"
+MIMSMS_USERNAME = "your_username"
+```
+
+### 3. Usage
+
+```python
+from django_mimsms import send_sms
+
+# Send a simple SMS
+response = send_sms(
+    to="88017XXXXXXXX",
+    message="Hello from Django!",
+)
+
+print(response.trxnId)
+```
+
+## Plain Python Usage
+
+If you're not using Django, you can use the `MiMSMSClient` directly:
+
+```python
+import asyncio
+from django_mimsms import MiMSMSClient
+
+async def main():
+    client = MiMSMSClient(
+        api_key="your_api_key",
+        username="your_username",
+        sender_id="your_sender_id"
+    )
+    
+    response = await client.send_sms(
+        to="88017XXXXXXXX",
+        message="Hello from Python!",
+    )
+    print(response.trxnId)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Advanced Features
+
+### Bulk SMS
+Send the same message to multiple recipients:
+
+```python
+from django_mimsms import send_bulk_sms
+
+send_bulk_sms(
+    numbers=["88017XXXXXXXX", "88018XXXXXXXX"],
+    message="Bulk message testing",
+)
+```
+
+### Dynamic SMS
+Send different messages to different recipients in one call:
+
+```python
+from django_mimsms import send_dynamic_sms
+
+messages = [
+    {"to": "88017XXXXXXXX", "message": "Hi Alice!"},
+    {"to": "88018XXXXXXXX", "message": "Hi Bob!"},
+]
+
+send_dynamic_sms(messages)
+```
+
+## License
+
+MIT

django_mimsms-0.1.0/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "django-mimsms"
+version = "0.1.0"
+authors = [
+  { name="Mimsms Integration Team" },
+]
+description = "Production-ready Django & Python package for MiMSMS.com bulk SMS API. Features async support, type safety, and seamless Bangladesh SMS gateway integration."
+readme = "README.md"
+requires-python = ">=3.12"
+keywords = [
+    "django-mimsms",
+    "mimsms sms api",
+    "django sms integration",
+    "bulk sms bangladesh",
+    "mimsms.com python",
+    "dynamic sms api",
+    "sms gateway django",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Framework :: Django",
+    "Framework :: Django :: 5.0",
+]
+dependencies = [
+    "django>=5.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.6.0",
+    "rich>=15.0.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/sharf-shawon/django-mimsms"
+"Bug Tracker" = "https://github.com/sharf-shawon/django-mimsms/issues"
+"Documentation" = "https://github.com/sharf-shawon/django-mimsms#readme"
+"Repository" = "https://github.com/sharf-shawon/django-mimsms"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0.0",
+    "pytest-django>=4.8.0",
+    "pytest-cov>=4.1.0",
+    "pytest-asyncio>=0.23.0",
+    "respx>=0.20.0",
+]
+dev = [
+    "ruff>=0.3.0",
+    "mypy>=1.9.0",
+    "build",
+    "rich>=13.0.0",
+    "django-mimsms[test]",
+    "python-semantic-release>=9.0.0",
+]
+
+
+
+
+
+[tool.semantic_release]
+vcs_provider = "github"
+version_variable = [
+    "src/django_mimsms/version.py:__version__",
+]
+version_toml = [
+    "pyproject.toml:project.version",
+]
+branch = "main"
+upload_to_pypi = false
+upload_to_release = true
+build_command = "python -m pip install build && python -m build"
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "C4", "DTZ", "SIM", "TID"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+ignore_missing_imports = true
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra -q --cov=src/django_mimsms --cov-report=term-missing --cov-fail-under=100"
+testpaths = [
+    "tests",
+]
+pythonpath = [".", "src"]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+
+[tool.setuptools.packages.find]
+where = ["src"]

django_mimsms-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

django_mimsms-0.1.0/src/django_mimsms/__init__.py

@@ -0,0 +1,3 @@
+from django_mimsms.version import __version__
+
+__all__ = ["__version__"]

django_mimsms-0.1.0/src/django_mimsms/client.py

@@ -0,0 +1,280 @@
+from typing import Any
+
+from pydantic import ValidationError
+
+from django_mimsms.config import MiMSMSConfig
+from django_mimsms.exceptions import MiMSMSResponseParseError, MiMSMSValidationError
+from django_mimsms.models import (
+    BulkSmsRequest,
+    DlrRequest,
+    DlrResponse,
+    DynamicSmsItem,
+    DynamicSmsRequest,
+    MiMSMSBaseRequest,
+    MiMSMSResponse,
+    SingleSmsRequest,
+)
+from django_mimsms.transport import Transport
+
+
+class MiMSMSClient:
+    """Core client for the MiMSMS API."""
+
+    def __init__(
+        self,
+        username: str,
+        apikey: str,
+        sender_name: str,
+        **options: Any,
+    ) -> None:
+        self.config = MiMSMSConfig(username=username, apikey=apikey, sender_name=sender_name, **options)
+        self.transport = Transport(self.config)
+
+    def send_sms(
+        self,
+        number: str,
+        message: str,
+        transaction_type: str | None = None,
+        campaign_id: str | None = None,
+    ) -> MiMSMSResponse:
+        """Send a single SMS via JSON POST."""
+        try:
+            payload = SingleSmsRequest(
+                username=self.config.username,
+                apikey=self.config.apikey,
+                mobile_number=number,
+                sender_name=self.config.sender_name,
+                transaction_type=transaction_type or self.config.default_transaction_type,
+                message=message,
+                campaign_id=campaign_id or self.config.campaign_id,
+            )
+        except ValidationError as e:
+            raise MiMSMSValidationError(str(e)) from e
+
+        data = self.transport.request(
+            "POST",
+            "/api/SmsSending/SMS",
+            json=payload.model_dump(by_alias=True, exclude_none=True),
+        )
+
+        try:
+            return MiMSMSResponse.model_validate(data)
+        except ValidationError as e:
+            raise MiMSMSResponseParseError(str(e)) from e
+
+    def send_sms_get(
+        self,
+        number: str,
+        message: str,
+        transaction_type: str | None = None,
+        campaign_id: str | None = None,
+    ) -> MiMSMSResponse:
+        """Send a single SMS via query-string GET."""
+        try:
+            payload = SingleSmsRequest(
+                username=self.config.username,
+                apikey=self.config.apikey,
+                mobile_number=number,
+                sender_name=self.config.sender_name,
+                transaction_type=transaction_type or self.config.default_transaction_type,
+                message=message,
+                campaign_id=campaign_id or self.config.campaign_id,
+            )
+        except ValidationError as e:
+            raise MiMSMSValidationError(str(e)) from e
+
+        data = self.transport.request(
+            "GET",
+            "/api/SmsSending/Send",
+            params=payload.model_dump(by_alias=True, exclude_none=True),
+        )
+
+        try:
+            return MiMSMSResponse.model_validate(data)
+        except ValidationError as e:
+            raise MiMSMSResponseParseError(str(e)) from e
+
+    def send_one_to_many(
+        self,
+        numbers: list[str] | str,
+        message: str,
+        transaction_type: str | None = None,
+        campaign_id: str | None = None,
+    ) -> MiMSMSResponse:
+        """Send bulk SMS via JSON POST."""
+        numbers_str = ",".join(numbers) if isinstance(numbers, list) else numbers
+
+        try:
+            payload = BulkSmsRequest(
+                username=self.config.username,
+                apikey=self.config.apikey,
+                mobile_number=numbers_str,
+                sender_name=self.config.sender_name,
+                transaction_type=transaction_type or self.config.default_transaction_type,
+                message=message,
+                campaign_id=campaign_id or self.config.campaign_id,
+            )
+        except ValidationError as e:
+            raise MiMSMSValidationError(str(e)) from e
+
+        data = self.transport.request(
+            "POST",
+            "/api/SmsSending/OneToMany",
+            json=payload.model_dump(by_alias=True, exclude_none=True),
+        )
+
+        try:
+            return MiMSMSResponse.model_validate(data)
+        except ValidationError as e:
+            raise MiMSMSResponseParseError(str(e)) from e
+
+    def send_one_to_many_get(
+        self,
+        numbers: list[str] | str,
+        message: str,
+        transaction_type: str | None = None,
+        campaign_id: str | None = None,
+    ) -> MiMSMSResponse:
+        """Send bulk SMS via query-string GET."""
+        numbers_str = ",".join(numbers) if isinstance(numbers, list) else numbers
+
+        try:
+            payload = BulkSmsRequest(
+                username=self.config.username,
+                apikey=self.config.apikey,
+                mobile_number=numbers_str,
+                sender_name=self.config.sender_name,
+                transaction_type=transaction_type or self.config.default_transaction_type,
+                message=message,
+                campaign_id=campaign_id or self.config.campaign_id,
+            )
+        except ValidationError as e:
+            raise MiMSMSValidationError(str(e)) from e
+
+        data = self.transport.request(
+            "GET",
+            "/api/SmsSending/SendOneToMany",
+            params=payload.model_dump(by_alias=True, exclude_none=True),
+        )
+
+        try:
+            return MiMSMSResponse.model_validate(data)
+        except ValidationError as e:
+            raise MiMSMSResponseParseError(str(e)) from e
+
+    def send_dynamic_sms(
+        self,
+        messages: list[dict[str, str]],
+        transaction_type: str = "D",
+    ) -> MiMSMSResponse:
+        """Send dynamic SMS via JSON POST."""
+        try:
+            sms_data = [DynamicSmsItem(mobile_number=m["number"], message=m["text"]) for m in messages]
+            payload = DynamicSmsRequest(
+                username=self.config.username,
+                apikey=self.config.apikey,
+                sender_name=self.config.sender_name,
+                sms_data=sms_data,
+                transaction_type=transaction_type,
+            )
+        except ValidationError as e:
+            raise MiMSMSValidationError(str(e)) from e
+
+        data = self.transport.request(
+            "POST",
+            "/api/SmsSending/DSMS",
+            json=payload.model_dump(by_alias=True, exclude_none=True),
+        )
+
+        try:
+            return MiMSMSResponse.model_validate(data)
+        except ValidationError as e:
+            raise MiMSMSResponseParseError(str(e)) from e
+
+    def check_balance(self) -> float:
+        """Check account balance via JSON POST."""
+        payload = MiMSMSBaseRequest(
+            username=self.config.username,
+            apikey=self.config.apikey,
+        )
+        data = self.transport.request(
+            "POST",
+            "/api/SmsSending/balanceCheck",
+            json=payload.model_dump(by_alias=True, exclude_none=True),
+        )
+        try:
+            val = float(data.get("responseResult", 0.0))
+            import math
+
+            return val if not math.isnan(val) else 0.0
+        except (ValueError, TypeError):
+            return 0.0
+
+    def check_balance_get(self) -> float:
+        """Check account balance via query-string GET."""
+        payload = MiMSMSBaseRequest(
+            username=self.config.username,
+            apikey=self.config.apikey,
+        )
+        data = self.transport.request(
+            "GET",
+            "/api/SmsSending/balanceCheck",
+            params=payload.model_dump(by_alias=True, exclude_none=True),
+        )
+        try:
+            val = float(data.get("responseResult", 0.0))
+            import math
+
+            return val if not math.isnan(val) else 0.0
+        except (ValueError, TypeError):
+            return 0.0
+
+    def check_dlr(self, trxn_id: str, number: str) -> DlrResponse:
+        """Check delivery report for a transaction."""
+        try:
+            payload = DlrRequest(
+                username=self.config.username,
+                apikey=self.config.apikey,
+                mobile_number=number,
+                trxn_id=trxn_id,
+            )
+        except ValidationError as e:
+            raise MiMSMSValidationError(str(e)) from e
+
+        data = self.transport.request(
+            "POST",
+            "/api/SmsSending/DlrApi",
+            json=payload.model_dump(by_alias=True, exclude_none=True),
+        )
+
+        try:
+            return DlrResponse.model_validate(data)
+        except ValidationError as e:
+            raise MiMSMSResponseParseError(str(e)) from e
+
+    def _get_auth_params(self) -> dict[str, str]:
+        """Get authentication parameters."""
+        return {
+            "UserName": self.config.username,
+            "ApiKey": self.config.apikey,
+        }
+
+    def close(self) -> None:
+        """Close the underlying transport."""
+        self.transport.close()
+
+    async def aclose(self) -> None:
+        """Close the underlying transport asynchronously."""
+        await self.transport.aclose()
+
+    def __enter__(self) -> "MiMSMSClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    async def __aenter__(self) -> "MiMSMSClient":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.aclose()

django_mimsms-0.1.0/src/django_mimsms/config.py

@@ -0,0 +1,16 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class MiMSMSConfig(BaseModel):
+    """Configuration model for MiMSMS integration."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    username: str
+    apikey: str
+    sender_name: str
+    base_url: str = "https://api.mimsms.com"
+    timeout: float = 30.0
+    verify_ssl: bool = True
+    default_transaction_type: str = "T"
+    campaign_id: str | None = None