nilva-django-sms 0.2.0__tar.gz

nilva_django_sms-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Nilva
+
+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.

nilva_django_sms-0.2.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: nilva-django-sms
+Version: 0.2.0
+Summary: Nilva house SMS/OTP toolkit — one engine interface over Pishgam, Magfa, Kavenegar and MCI Pardis with fallback chains, typed errors, cooldown-throttled OTP and Celery delivery
+Author-email: Nilva <dev@nilva.ai>
+License-Expression: MIT
+Project-URL: homepage, https://gitlab.nilva.ai/nilva/dev-assets/django/nilva-django-sms
+Project-URL: repository, https://gitlab.nilva.ai/nilva/dev-assets/django/nilva-django-sms
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32
+Provides-Extra: django
+Requires-Dist: django>=6.0; extra == "django"
+Provides-Extra: celery
+Requires-Dist: celery>=5.4; extra == "celery"
+Dynamic: license-file
+
+# nilva-django-sms
+
+Nilva's house SMS / OTP toolkit for Django and plain-Python services. One
+engine interface over every provider used across the Nilva backends —
+**Pishgam/Pishgaman Rayan, Magfa, Kavenegar, MCI Pardis** — plus **console**
+and **memory** engines for development and tests. Replaces the copy-pasted
+`SMSService` / `OTPService` clients that had drifted across Cheshmeh, Etka,
+Selfcare, Ghadir, Shop and Tiran.
+
+What it standardizes:
+
+* **Typed errors** — `SMSTransientError` (retry can help) vs
+  `SMSPermanentError` (it can't); Celery retry policies key off the split.
+* **Fallback chains** — primary engine plus ordered fallbacks.
+* **OTP cooldown throttling** — previously only Tiran had it; now default.
+* **Success normalization** — no `statusCode = 32` hacks leaking to callers.
+* **One vendored Kavenegar SDK** (`nilva_django_sms.kavenegar_sdk`, the
+  timeout/proxy-patched fork) instead of a copy per repo.
+
+Importing the package pulls neither Django, `requests` nor Celery — engines
+and the OTP service load lazily. Only `requests` is a hard install
+dependency.
+
+## Install
+
+```bash
+uv add nilva-django-sms                # engines + registry + facade
+uv add "nilva-django-sms[django]"      # + OTP service (Django cache)
+uv add "nilva-django-sms[celery]"      # + queued delivery with retries
+```
+
+## Configure — `NILVA_SMS`
+
+```python
+# settings.py
+NILVA_SMS = {
+    "ENGINE": "pishgam",                  # default engine ("console" if unset)
+    "FALLBACK_ENGINES": ("magfa",),       # tried in order when pishgam raises
+    "PROXY": SETTINGS.SOCKS5_PROXY,       # shared by all HTTP engines
+    "TIMEOUT": 5.0,
+
+    "PISHGAM": {
+        "GATEWAY_URL": "https://gw.pishgamrayan.com",
+        "TOKEN": "...", "GATEWAY_TOKEN": "...",
+        "SENDER": "3000...", "OTP_ID": 123,
+        # OTP template parameters; "{code}" is substituted:
+        "OTP_PARAMS": ("myapp", "{code}", "myapp.ir"),
+    },
+    "MAGFA": {"USERNAME": "...", "DOMAIN": "...", "PASSWORD": "...", "SENDER": "9800..."},
+    "KAVENEGAR": {"API_KEY": "...", "OTP_TEMPLATE": "login-otp"},
+    "PARDIS": {"BASE_URL": "...", "AUTH_HOST": "...", "BULK_HOST": "...",
+               "CLIENT_ID": "...", "USERNAME": "...", "PASSWORD": "...", "SOURCE": "98..."},
+
+    # OTP service
+    "OTP_LENGTH": 6,
+    "OTP_TTL": 300,
+    "OTP_COOLDOWN": 60,
+    "OTP_STATIC_CODE": None,              # staging bypass code; None disables
+
+    # Celery delivery
+    "USE_CELERY": True,
+    "CELERY_QUEUE": "low",
+}
+```
+
+Engine blocks merge over their defaults, so set only what you have. Every
+setting is read through `nilva_django_sms.settings.sms_settings` (the
+`nilva-django-logger` settings-object pattern) and works without Django too.
+
+## Send
+
+```python
+from nilva_django_sms import send_sms, send_otp
+
+send_sms("پیام شما", "09123456789")                 # walks ENGINE + fallbacks
+send_otp("123456", "09123456789")                    # OTP_ENGINE (or ENGINE) first
+send_sms("...", "0912...", engine="kavenegar")       # explicit engine
+send_sms("...", "0912...", fail_silently=True)       # SendResult(success=False) instead of raising
+```
+
+Queued delivery with transient-error retries (backoff + jitter, 4 attempts):
+
+```python
+from nilva_django_sms.tasks import queue_send_sms, queue_send_otp
+queue_send_sms("پیام", "09123456789", delay=10)   # sync fallback without Celery
+```
+
+## OTP
+
+```python
+from nilva_django_sms.otp import otp_service
+
+otp_service.send("09123456789")          # generate + cache + deliver
+# raises OTPCooldownError(retry_after=…) inside the cooldown window
+
+otp_service.verify("09123456789", "۱۲۳۴۵۶")   # True once — single-use,
+                                               # Persian/Arabic digits accepted
+```
+
+Codes are `secrets`-random, stored in the Django cache
+(`OTP_CACHE_ALIAS`/`OTP_CACHE_PREFIX`), consumed on first successful verify.
+`OTP_STATIC_CODE` enables the staging bypass the projects hacked in
+individually.
+
+## Engines
+
+| name        | provider                | OTP mechanism                                  |
+|-------------|-------------------------|------------------------------------------------|
+| `pishgam`   | Pishgam / Pishgaman     | `/Messages/SendOtp` template, or gateway `/Authenticate/Send` with `USE_GATEWAY_OTP` |
+| `magfa`     | Magfa v2 HTTP           | plain send with `OTP_MESSAGE` template          |
+| `kavenegar` | Kavenegar               | `verify_lookup` template (`url=` → `token2`); `HOST`/`VERIFY_SSL` support the kavenegar.nilva.ai mirror |
+| `pardis`    | MCI Bulk Sender P2P     | plain send with `OTP_MESSAGE` (OAuth token cached) |
+| `console`   | logs only (default)     | logs the code                                   |
+| `memory`    | in-process outbox       | for tests; `{"FAIL": True}` to exercise fallbacks |
+
+Project-specific engines: subclass `nilva_django_sms.SmsEngine` and register
+via `NILVA_SMS["EXTRA_ENGINES"] = {"myengine": "myapp.sms.MyEngine"}`.
+
+## Testing your app
+
+```python
+from nilva_django_sms.engines.memory import MemoryEngine
+
+@override_settings(NILVA_SMS={"ENGINE": "memory"})
+def test_signup_sends_otp(self):
+    ...
+    kind, recipient, code = MemoryEngine.outbox[-1]
+```
+
+## Development
+
+```bash
+uv sync --group dev
+./run_tests.sh          # ./run_tests.sh -c for coverage
+uv run ruff check .
+```

nilva_django_sms-0.2.0/README.md

@@ -0,0 +1,136 @@
+# nilva-django-sms
+
+Nilva's house SMS / OTP toolkit for Django and plain-Python services. One
+engine interface over every provider used across the Nilva backends —
+**Pishgam/Pishgaman Rayan, Magfa, Kavenegar, MCI Pardis** — plus **console**
+and **memory** engines for development and tests. Replaces the copy-pasted
+`SMSService` / `OTPService` clients that had drifted across Cheshmeh, Etka,
+Selfcare, Ghadir, Shop and Tiran.
+
+What it standardizes:
+
+* **Typed errors** — `SMSTransientError` (retry can help) vs
+  `SMSPermanentError` (it can't); Celery retry policies key off the split.
+* **Fallback chains** — primary engine plus ordered fallbacks.
+* **OTP cooldown throttling** — previously only Tiran had it; now default.
+* **Success normalization** — no `statusCode = 32` hacks leaking to callers.
+* **One vendored Kavenegar SDK** (`nilva_django_sms.kavenegar_sdk`, the
+  timeout/proxy-patched fork) instead of a copy per repo.
+
+Importing the package pulls neither Django, `requests` nor Celery — engines
+and the OTP service load lazily. Only `requests` is a hard install
+dependency.
+
+## Install
+
+```bash
+uv add nilva-django-sms                # engines + registry + facade
+uv add "nilva-django-sms[django]"      # + OTP service (Django cache)
+uv add "nilva-django-sms[celery]"      # + queued delivery with retries
+```
+
+## Configure — `NILVA_SMS`
+
+```python
+# settings.py
+NILVA_SMS = {
+    "ENGINE": "pishgam",                  # default engine ("console" if unset)
+    "FALLBACK_ENGINES": ("magfa",),       # tried in order when pishgam raises
+    "PROXY": SETTINGS.SOCKS5_PROXY,       # shared by all HTTP engines
+    "TIMEOUT": 5.0,
+
+    "PISHGAM": {
+        "GATEWAY_URL": "https://gw.pishgamrayan.com",
+        "TOKEN": "...", "GATEWAY_TOKEN": "...",
+        "SENDER": "3000...", "OTP_ID": 123,
+        # OTP template parameters; "{code}" is substituted:
+        "OTP_PARAMS": ("myapp", "{code}", "myapp.ir"),
+    },
+    "MAGFA": {"USERNAME": "...", "DOMAIN": "...", "PASSWORD": "...", "SENDER": "9800..."},
+    "KAVENEGAR": {"API_KEY": "...", "OTP_TEMPLATE": "login-otp"},
+    "PARDIS": {"BASE_URL": "...", "AUTH_HOST": "...", "BULK_HOST": "...",
+               "CLIENT_ID": "...", "USERNAME": "...", "PASSWORD": "...", "SOURCE": "98..."},
+
+    # OTP service
+    "OTP_LENGTH": 6,
+    "OTP_TTL": 300,
+    "OTP_COOLDOWN": 60,
+    "OTP_STATIC_CODE": None,              # staging bypass code; None disables
+
+    # Celery delivery
+    "USE_CELERY": True,
+    "CELERY_QUEUE": "low",
+}
+```
+
+Engine blocks merge over their defaults, so set only what you have. Every
+setting is read through `nilva_django_sms.settings.sms_settings` (the
+`nilva-django-logger` settings-object pattern) and works without Django too.
+
+## Send
+
+```python
+from nilva_django_sms import send_sms, send_otp
+
+send_sms("پیام شما", "09123456789")                 # walks ENGINE + fallbacks
+send_otp("123456", "09123456789")                    # OTP_ENGINE (or ENGINE) first
+send_sms("...", "0912...", engine="kavenegar")       # explicit engine
+send_sms("...", "0912...", fail_silently=True)       # SendResult(success=False) instead of raising
+```
+
+Queued delivery with transient-error retries (backoff + jitter, 4 attempts):
+
+```python
+from nilva_django_sms.tasks import queue_send_sms, queue_send_otp
+queue_send_sms("پیام", "09123456789", delay=10)   # sync fallback without Celery
+```
+
+## OTP
+
+```python
+from nilva_django_sms.otp import otp_service
+
+otp_service.send("09123456789")          # generate + cache + deliver
+# raises OTPCooldownError(retry_after=…) inside the cooldown window
+
+otp_service.verify("09123456789", "۱۲۳۴۵۶")   # True once — single-use,
+                                               # Persian/Arabic digits accepted
+```
+
+Codes are `secrets`-random, stored in the Django cache
+(`OTP_CACHE_ALIAS`/`OTP_CACHE_PREFIX`), consumed on first successful verify.
+`OTP_STATIC_CODE` enables the staging bypass the projects hacked in
+individually.
+
+## Engines
+
+| name        | provider                | OTP mechanism                                  |
+|-------------|-------------------------|------------------------------------------------|
+| `pishgam`   | Pishgam / Pishgaman     | `/Messages/SendOtp` template, or gateway `/Authenticate/Send` with `USE_GATEWAY_OTP` |
+| `magfa`     | Magfa v2 HTTP           | plain send with `OTP_MESSAGE` template          |
+| `kavenegar` | Kavenegar               | `verify_lookup` template (`url=` → `token2`); `HOST`/`VERIFY_SSL` support the kavenegar.nilva.ai mirror |
+| `pardis`    | MCI Bulk Sender P2P     | plain send with `OTP_MESSAGE` (OAuth token cached) |
+| `console`   | logs only (default)     | logs the code                                   |
+| `memory`    | in-process outbox       | for tests; `{"FAIL": True}` to exercise fallbacks |
+
+Project-specific engines: subclass `nilva_django_sms.SmsEngine` and register
+via `NILVA_SMS["EXTRA_ENGINES"] = {"myengine": "myapp.sms.MyEngine"}`.
+
+## Testing your app
+
+```python
+from nilva_django_sms.engines.memory import MemoryEngine
+
+@override_settings(NILVA_SMS={"ENGINE": "memory"})
+def test_signup_sends_otp(self):
+    ...
+    kind, recipient, code = MemoryEngine.outbox[-1]
+```
+
+## Development
+
+```bash
+uv sync --group dev
+./run_tests.sh          # ./run_tests.sh -c for coverage
+uv run ruff check .
+```

nilva_django_sms-0.2.0/nilva_django_sms/__init__.py

@@ -0,0 +1,52 @@
+"""Nilva Django SMS — the Nilva house SMS / OTP toolkit.
+
+One engine interface over every SMS provider used across the Nilva backends
+(Pishgam/Pishgaman, Magfa, Kavenegar, MCI Pardis) plus console and in-memory
+engines for development and tests. Ships a registry with fallback chains,
+typed transient/permanent errors, a cache-backed OTP service with cooldown
+throttling, and optional Celery delivery.
+
+Configuration follows the house ``NILVA_*`` settings-dict pattern (see
+``nilva_django_sms.settings``). Importing this package pulls neither Django
+nor ``requests`` — engines and the OTP service load lazily.
+"""
+
+__version__ = "0.2.0"
+
+from .base import SendResult, SmsEngine
+from .exceptions import (
+    OTPCooldownError,
+    SMSConfigurationError,
+    SMSError,
+    SMSPermanentError,
+    SMSTransientError,
+)
+
+__all__ = [
+    "__version__",
+    "SendResult",
+    "SmsEngine",
+    "SMSError",
+    "SMSConfigurationError",
+    "SMSPermanentError",
+    "SMSTransientError",
+    "OTPCooldownError",
+    "get_engine",
+    "send_sms",
+    "send_otp",
+]
+
+_LAZY = {
+    "get_engine": "registry",
+    "send_sms": "api",
+    "send_otp": "api",
+}
+
+
+def __getattr__(name):
+    module_name = _LAZY.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    return getattr(import_module(f".{module_name}", __name__), name)

nilva_django_sms-0.2.0/nilva_django_sms/api.py

@@ -0,0 +1,45 @@
+"""Send facade — walks the engine fallback chain.
+
+Each engine in the chain is tried in order; the last engine's error
+propagates when all fail (with every attempt logged), preserving the
+transient/permanent type for retry policies. ``fail_silently=True`` returns a
+failed :class:`SendResult` instead of raising.
+"""
+
+import logging
+
+from .base import SendResult
+from .exceptions import SMSError
+from .registry import engine_chain, get_engine
+
+logger = logging.getLogger(__name__)
+
+
+def _send(method: str, args: tuple, kwargs: dict, engine: str | None, fail_silently: bool, for_otp: bool):
+    errors = []
+    for name in engine_chain(engine, for_otp=for_otp):
+        try:
+            result = getattr(get_engine(name), method)(*args, **kwargs)
+            if errors:
+                logger.warning("sms sent via fallback engine", extra={"engine": name, "failed": len(errors)})
+            return result
+        except SMSError as exc:
+            logger.error("sms engine failed", extra={"engine": name, "error_info": str(exc)})
+            errors.append((name, exc))
+    if fail_silently:
+        return SendResult(success=False, raw={"errors": [(n, str(e)) for n, e in errors]})
+    raise errors[-1][1]
+
+
+def send_sms(message: str, recipient: str, engine: str | None = None, fail_silently: bool = False) -> SendResult:
+    """Send a plain SMS through the configured engine chain."""
+    return _send("send_sms", (message, recipient), {}, engine, fail_silently, for_otp=False)
+
+
+def send_otp(code: str, recipient: str, engine: str | None = None, fail_silently: bool = False, **kwargs) -> SendResult:
+    """Send an OTP through the configured engine chain (``OTP_ENGINE`` first).
+
+    Extra ``kwargs`` reach the engine (e.g. Kavenegar's ``url`` second token,
+    Pishgam's ``is_dashboard``-style template switches via ``otp_id``).
+    """
+    return _send("send_otp", (code, recipient), kwargs, engine, fail_silently, for_otp=True)

nilva_django_sms-0.2.0/nilva_django_sms/base.py

@@ -0,0 +1,67 @@
+"""Engine interface (Cheshmeh's ``SmsEngine`` ABC, made config-injectable).
+
+An engine either returns a :class:`SendResult` or raises a typed error from
+:mod:`nilva_django_sms.exceptions` — success is never signalled by a magic
+provider status code leaking to the caller.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class SendResult:
+    success: bool = True
+    engine: str = ""
+    raw: Any = None
+    message_ids: list = field(default_factory=list)
+
+
+class SmsEngine(ABC):
+    """Base engine. ``config`` defaults to the engine's block in ``NILVA_SMS``
+    (e.g. ``NILVA_SMS["PISHGAM"]``); pass a dict explicitly in tests."""
+
+    #: registry key and the ``NILVA_SMS`` block name (upper-cased).
+    name = ""
+
+    def __init__(self, config: dict | None = None):
+        from .settings import sms_settings
+
+        if config is None:
+            block = self.name.upper()
+            # Engines outside DEFAULTS (memory, EXTRA_ENGINES) still get their
+            # NILVA_SMS[block] dict.
+            config = getattr(sms_settings, block, None) or sms_settings.user_settings.get(block) or {}
+        self.config = dict(config)
+        self.proxy = self.config.get("PROXY", sms_settings.PROXY)
+        self.timeout = self.config.get("TIMEOUT", sms_settings.TIMEOUT)
+
+    @property
+    def proxies(self) -> dict | None:
+        if not self.proxy:
+            return None
+        return {"http": self.proxy, "https": self.proxy}
+
+    def require(self, key: str):
+        """Config value or :class:`SMSConfigurationError` naming the setting."""
+        value = self.config.get(key)
+        if value in (None, ""):
+            from .exceptions import SMSConfigurationError
+
+            raise SMSConfigurationError(f"NILVA_SMS[{self.name.upper()!r}][{key!r}] is required for {self.name}")
+        return value
+
+    def otp_message(self, code: str) -> str:
+        """Plain-text OTP body for providers without OTP templates."""
+        from .settings import sms_settings
+
+        return str(sms_settings.OTP_MESSAGE).format(code=code)
+
+    @abstractmethod
+    def send_sms(self, message: str, recipient: str) -> SendResult:
+        raise NotImplementedError
+
+    @abstractmethod
+    def send_otp(self, code: str, recipient: str, **kwargs) -> SendResult:
+        raise NotImplementedError

nilva_django_sms-0.2.0/nilva_django_sms/engines/console.py

@@ -0,0 +1,23 @@
+"""Development engine: logs instead of sending (Tiran's console mode).
+
+The default engine, so a fresh project never sends real SMS until it
+explicitly configures a provider.
+"""
+
+import logging
+
+from ..base import SendResult, SmsEngine
+
+logger = logging.getLogger(__name__)
+
+
+class ConsoleEngine(SmsEngine):
+    name = "console"
+
+    def send_sms(self, message: str, recipient: str) -> SendResult:
+        logger.info("SMS to %s: %s", recipient, message)
+        return SendResult(engine=self.name)
+
+    def send_otp(self, code: str, recipient: str, **kwargs) -> SendResult:
+        logger.info("OTP for %s: %s", recipient, code)
+        return SendResult(engine=self.name)

nilva_django_sms-0.2.0/nilva_django_sms/engines/kavenegar.py

@@ -0,0 +1,61 @@
+"""Kavenegar engine — wraps the vendored SDK (``nilva_django_sms.kavenegar_sdk``,
+the timeout/proxy-patched copy Shop and Selfcare each vendored separately)
+so the fleet ships exactly one blessed copy.
+
+OTPs use ``verify_lookup`` with the configured template (``token``; an extra
+``url=`` kwarg becomes ``token2``, Shop's pattern); plain SMS uses
+``sms_send``.
+"""
+
+import logging
+
+from ..base import SendResult, SmsEngine
+from ..exceptions import SMSPermanentError, SMSTransientError
+from ..kavenegar_sdk import APIException, HTTPException, KavenegarAPI
+
+logger = logging.getLogger(__name__)
+
+
+class KavenegarEngine(SmsEngine):
+    name = "kavenegar"
+
+    def __init__(self, config: dict | None = None):
+        super().__init__(config)
+        # HOST supports the kavenegar.nilva.ai mirror (InternetAccess pattern)
+        # when api.kavenegar.com is unreachable from the cluster; mirrors
+        # usually need VERIFY_SSL off.
+        self._api = KavenegarAPI(
+            self.require("API_KEY"),
+            timeout=self.timeout,
+            proxies=self.proxies,
+            host=self.config.get("HOST"),
+            verify=self.config.get("VERIFY_SSL", True),
+        )
+
+    def _call(self, method: str, params: dict) -> list:
+        try:
+            return getattr(self._api, method)(params)
+        except APIException as exc:
+            raise SMSPermanentError(f"kavenegar api error: {exc}") from exc
+        except HTTPException as exc:
+            raise SMSTransientError(f"kavenegar connection failure: {exc}") from exc
+
+    def _check_entry(self, entries: list) -> SendResult:
+        entry = entries[0] if entries else None
+        statuses = tuple(self.config.get("SUCCESS_STATUSES") or (5,))
+        if not entry or entry.get("status") not in statuses:
+            raise SMSPermanentError(f"kavenegar rejected send with status {(entry or {}).get('status')!r}")
+        return SendResult(engine=self.name, raw=entry, message_ids=[str(entry.get("messageid", ""))])
+
+    def send_sms(self, message: str, recipient: str) -> SendResult:
+        params = {"receptor": recipient, "message": message}
+        sender = self.config.get("SENDER")
+        if sender:
+            params["sender"] = sender
+        return self._check_entry(self._call("sms_send", params))
+
+    def send_otp(self, code: str, recipient: str, url: str | None = None, **kwargs) -> SendResult:
+        params = {"receptor": recipient, "template": self.require("OTP_TEMPLATE"), "token": str(code)}
+        if url:
+            params["token2"] = url
+        return self._check_entry(self._call("verify_lookup", params))

nilva_django_sms-0.2.0/nilva_django_sms/engines/magfa.py

@@ -0,0 +1,51 @@
+"""Magfa engine (HTTP v2 send API, basic auth ``username/domain:password``).
+
+Consolidates the ``MagfaSMSService`` copies in Cheshmeh, Etka, Selfcare and
+Ghadir. Magfa has no OTP-template endpoint, so OTPs are plain sends using the
+``NILVA_SMS["OTP_MESSAGE"]`` template.
+"""
+
+import logging
+
+import requests
+
+from ..base import SendResult, SmsEngine
+from ..exceptions import SMSPermanentError, SMSTransientError
+
+logger = logging.getLogger(__name__)
+
+SUCCESS_STATUS = 0
+
+
+class MagfaEngine(SmsEngine):
+    name = "magfa"
+
+    def send_sms(self, message: str, recipient: str) -> SendResult:
+        sender = self.require("SENDER")
+        payload = {"senders": [sender], "messages": [message], "recipients": [recipient]}
+        url = f"{str(self.require('SERVER_URL')).rstrip('/')}/http/sms/v2/send"
+        auth = (f"{self.require('USERNAME')}/{self.require('DOMAIN')}", self.require("PASSWORD"))
+        headers = {"accept": "application/json", "cache-control": "no-cache"}
+        try:
+            response = requests.post(
+                url, headers=headers, auth=auth, json=payload, proxies=self.proxies, timeout=self.timeout
+            )
+        except requests.Timeout as exc:
+            raise SMSTransientError("magfa request timed out") from exc
+        except requests.RequestException as exc:
+            raise SMSTransientError(f"magfa request failed: {exc}") from exc
+        if response.status_code >= 500:
+            raise SMSTransientError(f"magfa returned {response.status_code}: {response.text}")
+        if response.status_code >= 400:
+            raise SMSPermanentError(f"magfa rejected request with {response.status_code}: {response.text}")
+        try:
+            raw = response.json()
+        except ValueError as exc:
+            raise SMSTransientError(f"magfa returned a non-JSON response: {response.text}") from exc
+        if raw.get("status") != SUCCESS_STATUS:
+            raise SMSPermanentError(f"magfa rejected send with status {raw.get('status')!r}")
+        logger.info("magfa sms sent", extra={"engine": self.name})
+        return SendResult(engine=self.name, raw=raw)
+
+    def send_otp(self, code: str, recipient: str, **kwargs) -> SendResult:
+        return self.send_sms(self.otp_message(code), recipient)

nilva_django_sms-0.2.0/nilva_django_sms/engines/memory.py

@@ -0,0 +1,38 @@
+"""Test engine: records every send in a class-level outbox.
+
+Configure ``{"FAIL": True}`` (or ``{"FAIL": "transient"}``) to make it raise,
+for exercising fallback chains and retry paths.
+"""
+
+from ..base import SendResult, SmsEngine
+from ..exceptions import SMSPermanentError, SMSTransientError
+
+
+class MemoryEngine(SmsEngine):
+    name = "memory"
+
+    #: [(kind, recipient, payload), ...] — shared across instances, like
+    #: django.core.mail.outbox. Clear it between tests.
+    outbox: list[tuple[str, str, str]] = []
+
+    def _maybe_fail(self):
+        fail = self.config.get("FAIL")
+        if not fail:
+            return
+        if fail == "transient":
+            raise SMSTransientError("memory engine configured to fail (transient)")
+        raise SMSPermanentError("memory engine configured to fail")
+
+    def send_sms(self, message: str, recipient: str) -> SendResult:
+        self._maybe_fail()
+        self.outbox.append(("sms", recipient, message))
+        return SendResult(engine=self.name)
+
+    def send_otp(self, code: str, recipient: str, **kwargs) -> SendResult:
+        self._maybe_fail()
+        self.outbox.append(("otp", recipient, code))
+        return SendResult(engine=self.name)
+
+    @classmethod
+    def clear(cls):
+        cls.outbox.clear()