otp-sanly 1.0.0__tar.gz

otp_sanly-1.0.0/LICENSE

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

otp_sanly-1.0.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: otp-sanly
+Version: 1.0.0
+Summary: Official Python SDK for OTP Sanly (otp.sanly.dev) — SMS & Email OTP for Turkmenistan
+Author: OTP Sanly
+License: MIT
+Project-URL: Homepage, https://otp.sanly.dev/developers
+Project-URL: Repository, https://github.com/sanly-dev/otp-sanly-python
+Project-URL: Issues, https://github.com/sanly-dev/otp-sanly-python/issues
+Keywords: otp,sms,email,verification,turkmenistan,2fa,authentication
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# OTP Sanly — Python SDK
+
+[Türkmençe](README.tk.md) | [Русский](README.ru.md) | English
+
+Official SDK for [OTP Sanly](https://otp.sanly.dev) — SMS & Email OTP authentication for Turkmenistan.
+
+## Install
+
+```bash
+pip install otp-sanly
+```
+
+## Quick start
+
+```python
+from otp_sanly import OtpSanly
+
+sanly = OtpSanly(api_key="YOUR_API_KEY")
+
+# Send an OTP
+sent = sanly.send_otp(
+    phone="+99361234567",  # Turkmenistan numbers only for SMS. Use `email=` instead for worldwide delivery.
+    project="My App",
+    lang="ru",  # "tk" | "ru" | "en" — which language to send the OTP in
+)
+print(sent.otp_id, sent.message)
+
+# Verify the code the user entered
+verified = sanly.verify_otp(phone="+99361234567", code="123456")
+if verified.success:
+    ...  # proceed — the code was correct
+```
+
+## Sandbox mode
+
+Create a **sandbox** API key in your [dashboard](https://otp.sanly.dev/dashboard/api-keys) to test your integration
+for free, without sending real SMS/email. The OTP code is returned directly in the response:
+
+```python
+sent = sanly.send_otp(phone="+99361234567")
+print(sent.code)  # only present for sandbox keys
+```
+
+## Error handling
+
+Failed requests raise `OtpSanlyError`, which includes the HTTP status and the raw response body:
+
+```python
+from otp_sanly import OtpSanly, OtpSanlyError
+
+try:
+    sanly.send_otp(phone="+99361234567")
+except OtpSanlyError as err:
+    print(err.status, err, err.body)
+```
+
+## Full API reference
+
+See [https://otp.sanly.dev/developers](https://otp.sanly.dev/developers) for the complete API reference, webhook docs,
+and framework-specific examples in other languages.
+
+## License
+
+MIT

otp_sanly-1.0.0/README.md

@@ -0,0 +1,64 @@
+# OTP Sanly — Python SDK
+
+[Türkmençe](README.tk.md) | [Русский](README.ru.md) | English
+
+Official SDK for [OTP Sanly](https://otp.sanly.dev) — SMS & Email OTP authentication for Turkmenistan.
+
+## Install
+
+```bash
+pip install otp-sanly
+```
+
+## Quick start
+
+```python
+from otp_sanly import OtpSanly
+
+sanly = OtpSanly(api_key="YOUR_API_KEY")
+
+# Send an OTP
+sent = sanly.send_otp(
+    phone="+99361234567",  # Turkmenistan numbers only for SMS. Use `email=` instead for worldwide delivery.
+    project="My App",
+    lang="ru",  # "tk" | "ru" | "en" — which language to send the OTP in
+)
+print(sent.otp_id, sent.message)
+
+# Verify the code the user entered
+verified = sanly.verify_otp(phone="+99361234567", code="123456")
+if verified.success:
+    ...  # proceed — the code was correct
+```
+
+## Sandbox mode
+
+Create a **sandbox** API key in your [dashboard](https://otp.sanly.dev/dashboard/api-keys) to test your integration
+for free, without sending real SMS/email. The OTP code is returned directly in the response:
+
+```python
+sent = sanly.send_otp(phone="+99361234567")
+print(sent.code)  # only present for sandbox keys
+```
+
+## Error handling
+
+Failed requests raise `OtpSanlyError`, which includes the HTTP status and the raw response body:
+
+```python
+from otp_sanly import OtpSanly, OtpSanlyError
+
+try:
+    sanly.send_otp(phone="+99361234567")
+except OtpSanlyError as err:
+    print(err.status, err, err.body)
+```
+
+## Full API reference
+
+See [https://otp.sanly.dev/developers](https://otp.sanly.dev/developers) for the complete API reference, webhook docs,
+and framework-specific examples in other languages.
+
+## License
+
+MIT

otp_sanly-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "otp-sanly"
+version = "1.0.0"
+description = "Official Python SDK for OTP Sanly (otp.sanly.dev) — SMS & Email OTP for Turkmenistan"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "OTP Sanly" }]
+keywords = ["otp", "sms", "email", "verification", "turkmenistan", "2fa", "authentication"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://otp.sanly.dev/developers"
+Repository = "https://github.com/sanly-dev/otp-sanly-python"
+Issues = "https://github.com/sanly-dev/otp-sanly-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

otp_sanly-1.0.0/setup.cfg

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

otp_sanly-1.0.0/src/otp_sanly/__init__.py

@@ -0,0 +1,202 @@
+"""
+OTP Sanly — Official Python SDK
+https://otp.sanly.dev/developers
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+from urllib import request as _urllib_request
+from urllib.error import HTTPError, URLError
+import json
+
+__version__ = "1.0.0"
+
+DEFAULT_BASE_URL = "https://otp.sanly.dev"
+
+
+class OtpSanlyError(Exception):
+    """Raised when the OTP Sanly API returns an error response."""
+
+    def __init__(self, message: str, status: int, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+@dataclass
+class SendOtpResult:
+    success: bool
+    otp_id: Optional[int] = None
+    target: Optional[str] = None
+    channel: Optional[str] = None
+    expires_at: Optional[str] = None
+    expires_at_tm: Optional[str] = None
+    expires_in: Optional[int] = None
+    remaining_otp: Optional[int] = None
+    attempt: Optional[int] = None
+    max_attempts: Optional[int] = None
+    auto_read: Optional[bool] = None
+    message: Optional[str] = None
+    error: Optional[str] = None
+    code: Optional[str] = None
+    sandbox: Optional[bool] = None
+    raw: dict = None  # full raw response, for any fields not modeled above
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> "SendOtpResult":
+        return cls(
+            success=bool(d.get("success")),
+            otp_id=d.get("otpId"),
+            target=d.get("target"),
+            channel=d.get("channel"),
+            expires_at=d.get("expiresAt"),
+            expires_at_tm=d.get("expiresAtTM"),
+            expires_in=d.get("expiresIn"),
+            remaining_otp=d.get("remainingOtp"),
+            attempt=d.get("attempt"),
+            max_attempts=d.get("maxAttempts"),
+            auto_read=d.get("autoRead"),
+            message=d.get("message"),
+            error=d.get("error"),
+            code=d.get("code"),
+            sandbox=d.get("sandbox"),
+            raw=d,
+        )
+
+
+@dataclass
+class VerifyOtpResult:
+    success: bool
+    message: Optional[str] = None
+    otp_id: Optional[int] = None
+    target: Optional[str] = None
+    verified_at: Optional[str] = None
+    verified_at_tm: Optional[str] = None
+    channel: Optional[str] = None
+    project: Optional[str] = None
+    error: Optional[str] = None
+    raw: dict = None
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> "VerifyOtpResult":
+        return cls(
+            success=bool(d.get("success")),
+            message=d.get("message"),
+            otp_id=d.get("otpId"),
+            target=d.get("target"),
+            verified_at=d.get("verifiedAt"),
+            verified_at_tm=d.get("verifiedAtTM"),
+            channel=d.get("channel"),
+            project=d.get("project"),
+            error=d.get("error"),
+            raw=d,
+        )
+
+
+class OtpSanly:
+    """
+    Client for the OTP Sanly API (SMS & Email OTP for Turkmenistan).
+
+    Example:
+        >>> from otp_sanly import OtpSanly
+        >>> sanly = OtpSanly(api_key="otpsanly_xxx")
+        >>> result = sanly.send_otp(phone="+99361234567", lang="ru")
+        >>> sanly.verify_otp(phone="+99361234567", code="123456")
+    """
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, timeout: float = 15.0):
+        if not api_key:
+            raise ValueError(
+                "OtpSanly: api_key is required. Get one at https://otp.sanly.dev/dashboard/api-keys"
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(self, path: str, body: dict) -> dict:
+        payload = json.dumps({"apiKey": self.api_key, **body}).encode("utf-8")
+        req = _urllib_request.Request(
+            f"{self.base_url}{path}",
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with _urllib_request.urlopen(req, timeout=self.timeout) as resp:
+                status = resp.status
+                data = json.loads(resp.read().decode("utf-8") or "{}")
+        except HTTPError as e:
+            try:
+                data = json.loads(e.read().decode("utf-8") or "{}")
+            except Exception:
+                data = {}
+            raise OtpSanlyError(
+                data.get("error") or f"Request failed with status {e.code}", e.code, data
+            ) from None
+        except URLError as e:
+            raise OtpSanlyError(f"Network error: {e.reason}", 0, None) from None
+
+        if not (200 <= status < 300) or data.get("success") is False:
+            raise OtpSanlyError(data.get("error") or f"Request failed with status {status}", status, data)
+        return data
+
+    def send_otp(
+        self,
+        phone: Optional[str] = None,
+        email: Optional[str] = None,
+        project: Optional[str] = None,
+        lang: Optional[str] = None,
+    ) -> SendOtpResult:
+        """
+        Send an OTP via SMS (Turkmenistan numbers only) or email (worldwide).
+        Provide `phone` OR `email`, not both.
+
+        `lang` selects which of the 3 configured languages ("tk" | "ru" | "en")
+        the message template uses. Since this SDK calls the API server-to-server,
+        the Accept-Language header is unreliable — always pass `lang` explicitly
+        if you support multiple end-user languages. Defaults to "tk" if omitted.
+        """
+        if not phone and not email:
+            raise ValueError("OtpSanly.send_otp: provide either 'phone' or 'email'")
+        body: dict = {}
+        if phone:
+            body["phone"] = phone
+        if email:
+            body["email"] = email
+        if project:
+            body["project"] = project
+        if lang:
+            body["lang"] = lang
+        data = self._request("/api/send-otp", body)
+        return SendOtpResult._from_dict(data)
+
+    def verify_otp(
+        self,
+        code: str,
+        phone: Optional[str] = None,
+        email: Optional[str] = None,
+        otp_id: Optional[int] = None,
+    ) -> VerifyOtpResult:
+        """
+        Verify a code the user entered. Provide `phone` OR `email` (same one used in send_otp).
+        `otp_id` is optional — pass the otpId returned by send_otp() for extra precision
+        if you have multiple pending OTPs for the same target.
+        """
+        if not phone and not email:
+            raise ValueError("OtpSanly.verify_otp: provide either 'phone' or 'email'")
+        if not code:
+            raise ValueError("OtpSanly.verify_otp: 'code' is required")
+        body: dict = {"code": code}
+        if phone:
+            body["phone"] = phone
+        if email:
+            body["email"] = email
+        if otp_id is not None:
+            body["otpId"] = otp_id
+        data = self._request("/api/verify-otp", body)
+        return VerifyOtpResult._from_dict(data)
+
+
+__all__ = ["OtpSanly", "OtpSanlyError", "SendOtpResult", "VerifyOtpResult"]

otp_sanly-1.0.0/src/otp_sanly.egg-info/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: otp-sanly
+Version: 1.0.0
+Summary: Official Python SDK for OTP Sanly (otp.sanly.dev) — SMS & Email OTP for Turkmenistan
+Author: OTP Sanly
+License: MIT
+Project-URL: Homepage, https://otp.sanly.dev/developers
+Project-URL: Repository, https://github.com/sanly-dev/otp-sanly-python
+Project-URL: Issues, https://github.com/sanly-dev/otp-sanly-python/issues
+Keywords: otp,sms,email,verification,turkmenistan,2fa,authentication
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# OTP Sanly — Python SDK
+
+[Türkmençe](README.tk.md) | [Русский](README.ru.md) | English
+
+Official SDK for [OTP Sanly](https://otp.sanly.dev) — SMS & Email OTP authentication for Turkmenistan.
+
+## Install
+
+```bash
+pip install otp-sanly
+```
+
+## Quick start
+
+```python
+from otp_sanly import OtpSanly
+
+sanly = OtpSanly(api_key="YOUR_API_KEY")
+
+# Send an OTP
+sent = sanly.send_otp(
+    phone="+99361234567",  # Turkmenistan numbers only for SMS. Use `email=` instead for worldwide delivery.
+    project="My App",
+    lang="ru",  # "tk" | "ru" | "en" — which language to send the OTP in
+)
+print(sent.otp_id, sent.message)
+
+# Verify the code the user entered
+verified = sanly.verify_otp(phone="+99361234567", code="123456")
+if verified.success:
+    ...  # proceed — the code was correct
+```
+
+## Sandbox mode
+
+Create a **sandbox** API key in your [dashboard](https://otp.sanly.dev/dashboard/api-keys) to test your integration
+for free, without sending real SMS/email. The OTP code is returned directly in the response:
+
+```python
+sent = sanly.send_otp(phone="+99361234567")
+print(sent.code)  # only present for sandbox keys
+```
+
+## Error handling
+
+Failed requests raise `OtpSanlyError`, which includes the HTTP status and the raw response body:
+
+```python
+from otp_sanly import OtpSanly, OtpSanlyError
+
+try:
+    sanly.send_otp(phone="+99361234567")
+except OtpSanlyError as err:
+    print(err.status, err, err.body)
+```
+
+## Full API reference
+
+See [https://otp.sanly.dev/developers](https://otp.sanly.dev/developers) for the complete API reference, webhook docs,
+and framework-specific examples in other languages.
+
+## License
+
+MIT

otp_sanly-1.0.0/src/otp_sanly.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+src/otp_sanly/__init__.py
+src/otp_sanly.egg-info/PKG-INFO
+src/otp_sanly.egg-info/SOURCES.txt
+src/otp_sanly.egg-info/dependency_links.txt
+src/otp_sanly.egg-info/top_level.txt
+tests/test_otp_sanly.py

otp_sanly-1.0.0/src/otp_sanly.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

otp_sanly-1.0.0/src/otp_sanly.egg-info/top_level.txt

@@ -0,0 +1 @@
+otp_sanly

otp_sanly-1.0.0/tests/test_otp_sanly.py

@@ -0,0 +1,82 @@
+import json
+import unittest
+from unittest.mock import patch, MagicMock
+
+from otp_sanly import OtpSanly, OtpSanlyError
+
+
+def _fake_response(status: int, body: dict):
+    m = MagicMock()
+    m.status = status
+    m.read.return_value = json.dumps(body).encode("utf-8")
+    m.__enter__.return_value = m
+    m.__exit__.return_value = False
+    return m
+
+
+class TestOtpSanlyInit(unittest.TestCase):
+    def test_requires_api_key(self):
+        with self.assertRaises(ValueError):
+            OtpSanly(api_key="")
+
+    def test_strips_trailing_slash(self):
+        c = OtpSanly(api_key="k", base_url="https://example.com/")
+        self.assertEqual(c.base_url, "https://example.com")
+
+
+class TestSendOtp(unittest.TestCase):
+    def setUp(self):
+        self.client = OtpSanly(api_key="otpsanly_test")
+
+    def test_requires_phone_or_email(self):
+        with self.assertRaises(ValueError):
+            self.client.send_otp()
+
+    @patch("otp_sanly._urllib_request.urlopen")
+    def test_send_otp_success(self, mock_urlopen):
+        mock_urlopen.return_value = _fake_response(
+            200,
+            {
+                "success": True,
+                "otpId": 42,
+                "target": "+99361234567",
+                "channel": "sms",
+                "expiresIn": 300,
+            },
+        )
+        result = self.client.send_otp(phone="+99361234567", lang="ru")
+        self.assertTrue(result.success)
+        self.assertEqual(result.otp_id, 42)
+        self.assertEqual(result.channel, "sms")
+
+    @patch("otp_sanly._urllib_request.urlopen")
+    def test_send_otp_raises_on_error(self, mock_urlopen):
+        mock_urlopen.return_value = _fake_response(200, {"success": False, "error": "Limit exceeded"})
+        with self.assertRaises(OtpSanlyError):
+            self.client.send_otp(email="a@b.com")
+
+
+class TestVerifyOtp(unittest.TestCase):
+    def setUp(self):
+        self.client = OtpSanly(api_key="otpsanly_test")
+
+    def test_requires_target(self):
+        with self.assertRaises(ValueError):
+            self.client.verify_otp(code="123456")
+
+    def test_requires_code(self):
+        with self.assertRaises(ValueError):
+            self.client.verify_otp(code="", phone="+99361234567")
+
+    @patch("otp_sanly._urllib_request.urlopen")
+    def test_verify_otp_success(self, mock_urlopen):
+        mock_urlopen.return_value = _fake_response(
+            200, {"success": True, "otpId": 42, "target": "+99361234567", "verifiedAt": "2026-01-01T00:00:00Z"}
+        )
+        result = self.client.verify_otp(phone="+99361234567", code="123456")
+        self.assertTrue(result.success)
+        self.assertEqual(result.otp_id, 42)
+
+
+if __name__ == "__main__":
+    unittest.main()