achek-sdk 1.0.0__tar.gz

achek_sdk-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+.env
+env
+node_modules
+.env
+.env

achek_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: achek-sdk
+Version: 1.0.0
+Summary: Official Python SDK for Achek — WhatsApp OTP, AI chatbots & business messaging for Nigeria
+Project-URL: Homepage, https://achek.com.ng
+Project-URL: Documentation, https://docs.achek.com.ng
+Project-URL: Repository, https://github.com/CalebDevX/AchekVerify
+Project-URL: Issues, https://github.com/CalebDevX/AchekVerify/issues
+Author-email: Achek <dev@achek.com.ng>
+License: MIT
+Keywords: 2fa,achek,chatbot,nigeria,otp,verification,whatsapp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.28.0
+Description-Content-Type: text/markdown
+
+# achek-sdk
+
+Official Python SDK for [Achek](https://achek.com.ng) — WhatsApp OTP, AI chatbots & business messaging for Nigerian developers.
+
+## Installation
+
+```bash
+pip install achek-sdk
+```
+
+## Quick Start
+
+```python
+from achekverify import AchekConnect
+
+client = AchekConnect("your_api_key")
+
+# Send a WhatsApp OTP
+result = client.send_otp("+2348XXXXXXXXX")
+print(result["sessionId"])
+
+# Verify the OTP the user enters
+check = client.verify_otp("+2348XXXXXXXXX", otp="482910")
+print(check["valid"])  # True / False
+
+# Send a plain WhatsApp message
+client.send_message("+2348XXXXXXXXX", "Hello from Achek!")
+```
+
+## Authentication
+
+Get your API key from the [Achek dashboard](https://console.achek.com.ng).
+
+```python
+client = AchekConnect("ak_live_your_key_here")
+```
+
+## Features
+
+- **WhatsApp OTP** — Send and verify one-time passwords via WhatsApp
+- **Messaging** — Send plain and templated WhatsApp messages
+- **AI Bot** — Create and manage AI chatbot agents
+- **Webhooks** — Verify and parse incoming webhook events
+- **Broadcasts** — Send bulk messages to multiple numbers
+
+## Webhook Verification
+
+```python
+from achekverify import Webhooks
+
+wh = Webhooks("your_webhook_secret")
+payload = wh.verify(raw_body, signature_header)
+print(payload["event"])  # e.g. "otp.verified"
+```
+
+## Links
+
+- [Documentation](https://docs.achek.com.ng)
+- [Dashboard](https://console.achek.com.ng)
+- [GitHub](https://github.com/CalebDevX/AchekVerify)
+- [Support](https://achek.com.ng/support)
+
+## License
+
+MIT

achek_sdk-1.0.0/README.md

@@ -0,0 +1,65 @@
+# achek-sdk
+
+Official Python SDK for [Achek](https://achek.com.ng) — WhatsApp OTP, AI chatbots & business messaging for Nigerian developers.
+
+## Installation
+
+```bash
+pip install achek-sdk
+```
+
+## Quick Start
+
+```python
+from achekverify import AchekConnect
+
+client = AchekConnect("your_api_key")
+
+# Send a WhatsApp OTP
+result = client.send_otp("+2348XXXXXXXXX")
+print(result["sessionId"])
+
+# Verify the OTP the user enters
+check = client.verify_otp("+2348XXXXXXXXX", otp="482910")
+print(check["valid"])  # True / False
+
+# Send a plain WhatsApp message
+client.send_message("+2348XXXXXXXXX", "Hello from Achek!")
+```
+
+## Authentication
+
+Get your API key from the [Achek dashboard](https://console.achek.com.ng).
+
+```python
+client = AchekConnect("ak_live_your_key_here")
+```
+
+## Features
+
+- **WhatsApp OTP** — Send and verify one-time passwords via WhatsApp
+- **Messaging** — Send plain and templated WhatsApp messages
+- **AI Bot** — Create and manage AI chatbot agents
+- **Webhooks** — Verify and parse incoming webhook events
+- **Broadcasts** — Send bulk messages to multiple numbers
+
+## Webhook Verification
+
+```python
+from achekverify import Webhooks
+
+wh = Webhooks("your_webhook_secret")
+payload = wh.verify(raw_body, signature_header)
+print(payload["event"])  # e.g. "otp.verified"
+```
+
+## Links
+
+- [Documentation](https://docs.achek.com.ng)
+- [Dashboard](https://console.achek.com.ng)
+- [GitHub](https://github.com/CalebDevX/AchekVerify)
+- [Support](https://achek.com.ng/support)
+
+## License
+
+MIT

achek_sdk-1.0.0/achekverify/__init__.py

@@ -0,0 +1,43 @@
+"""
+AchekConnect Python SDK
+======================
+Official client for the AchekConnect API — WhatsApp OTP, messaging, and AI bots.
+
+Quick start::
+
+    from achekconnect import AchekConnect
+
+    client = AchekConnect("your-api-key")
+
+    # Send OTP
+    result = client.send_otp("+2348012345678")
+    print(result["sessionId"])
+
+    # Verify OTP
+    check = client.verify_otp("+2348012345678", otp="482910")
+    print(check["valid"])  # True / False
+"""
+
+from .client import AchekConnect
+from .errors import (
+    AchekError,
+    AuthenticationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from .webhooks import Webhooks
+
+__all__ = [
+    "AchekConnect",
+    "AchekError",
+    "AuthenticationError",
+    "RateLimitError",
+    "ValidationError",
+    "NotFoundError",
+    "NetworkError",
+    "Webhooks",
+]
+
+__version__ = "1.0.0"

achek_sdk-1.0.0/achekverify/client.py

@@ -0,0 +1,195 @@
+import time
+from typing import Any, Dict, Optional
+
+import requests
+
+from .errors import (
+    AchekError,
+    AuthenticationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from .webhooks import Webhooks
+
+DEFAULT_BASE_URL = "https://api.achek.com.ng/v1"
+DEFAULT_TIMEOUT = 30
+DEFAULT_RETRIES = 3
+SDK_VERSION = "achekconnect-python/1.0.0"
+
+
+class AchekConnect:
+    """
+    Official AchekConnect Python client.
+
+    Usage::
+
+        from achekconnect import AchekConnect
+
+        client = AchekConnect("your-api-key")
+        result = client.send_otp("+2348012345678")
+        print(result["sessionId"])
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: int = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        webhook_secret: str = "",
+    ):
+        if not api_key:
+            raise AuthenticationError("api_key is required")
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._retries = retries
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "X-SDK": SDK_VERSION,
+            }
+        )
+        self.webhooks = Webhooks(webhook_secret)
+
+    # ──────────────────────────────── Transport ────────────────────────────────
+
+    def _request(self, method: str, path: str, **kwargs) -> Dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        attempt = 0
+        while True:
+            try:
+                res = self._session.request(method, url, timeout=self._timeout, **kwargs)
+            except requests.exceptions.Timeout:
+                if attempt < self._retries:
+                    attempt += 1
+                    time.sleep(min(0.5 * 2 ** attempt, 10))
+                    continue
+                raise NetworkError("Request timed out")
+            except requests.exceptions.RequestException as exc:
+                if attempt < self._retries:
+                    attempt += 1
+                    time.sleep(min(0.5 * 2 ** attempt, 10))
+                    continue
+                raise NetworkError(str(exc)) from exc
+
+            if res.status_code == 401:
+                raise AuthenticationError()
+
+            if res.status_code == 429:
+                retry_after = int(res.headers.get("Retry-After", 60))
+                if attempt < self._retries:
+                    time.sleep(retry_after)
+                    attempt += 1
+                    continue
+                raise RateLimitError(retry_after)
+
+            data = res.json()
+
+            if not data.get("success"):
+                err = data.get("error", {})
+                msg = err.get("message", "Request failed")
+                code = err.get("code", "UNKNOWN")
+                if res.status_code == 422:
+                    raise ValidationError(msg)
+                if res.status_code == 404:
+                    raise NotFoundError(msg)
+                raise AchekError(msg, code, res.status_code)
+
+            return data
+
+    # ──────────────────────────────── OTP ─────────────────────────────────────
+
+    def send_otp(
+        self,
+        phone: str,
+        *,
+        length: int = 6,
+        expires_in: int = 600,
+        template: Optional[str] = None,
+        sender_number: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Send a WhatsApp OTP to a phone number.
+
+        Args:
+            phone:         E.164 number e.g. ``"+2348012345678"``.
+            length:        OTP digit length — 4 or 6 (default 6).
+            expires_in:    Seconds until expiry (default 600).
+            template:      Custom message with ``{{otp}}`` placeholder.
+            sender_number: Override the default sender number.
+
+        Returns:
+            dict with ``sessionId``, ``phone``, ``expiresAt``, ``remaining``.
+        """
+        body: Dict[str, Any] = {"phone": phone, "length": length, "expiresIn": expires_in}
+        if template is not None:
+            body["template"] = template
+        if sender_number is not None:
+            body["senderNumber"] = sender_number
+        return self._request("POST", "/otp/send", json=body)["data"]
+
+    def verify_otp(self, phone: str, otp: str) -> Dict[str, Any]:
+        """
+        Verify a code entered by the user.
+
+        Returns:
+            dict with ``valid`` (bool), ``phone``, ``sessionId``.
+        """
+        return self._request("POST", "/otp/verify", json={"phone": phone, "otp": otp})["data"]
+
+    # ──────────────────────────────── Messaging ────────────────────────────────
+
+    def send_message(
+        self,
+        phone: str,
+        message: str,
+        *,
+        sender_number: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Send a plain WhatsApp message."""
+        body: Dict[str, Any] = {"phone": phone, "message": message}
+        if sender_number is not None:
+            body["senderNumber"] = sender_number
+        return self._request("POST", "/messages/send", json=body)["data"]
+
+    # ──────────────────────────────── AI Agents ────────────────────────────────
+
+    def create_agent(
+        self,
+        name: str,
+        system_prompt: str,
+        *,
+        provider: str = "openai",
+        model: Optional[str] = None,
+        welcome_message: Optional[str] = None,
+        webhook_url: Optional[str] = None,
+        phone_number: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a new AI WhatsApp agent."""
+        body: Dict[str, Any] = {
+            "name": name,
+            "systemPrompt": system_prompt,
+            "provider": provider,
+        }
+        if model is not None:
+            body["model"] = model
+        if welcome_message is not None:
+            body["welcomeMessage"] = welcome_message
+        if webhook_url is not None:
+            body["webhookUrl"] = webhook_url
+        if phone_number is not None:
+            body["phoneNumber"] = phone_number
+        return self._request("POST", "/agents", json=body)["data"]
+
+    def get_agent(self, agent_id: str) -> Dict[str, Any]:
+        """Retrieve an agent by ID."""
+        return self._request("GET", f"/agents/{agent_id}")["data"]
+
+    def delete_agent(self, agent_id: str) -> Dict[str, Any]:
+        """Delete an agent permanently."""
+        return self._request("DELETE", f"/agents/{agent_id}")["data"]

achek_sdk-1.0.0/achekverify/errors.py

@@ -0,0 +1,55 @@
+class AchekError(Exception):
+    """Base exception for all AchekConnect SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "UNKNOWN",
+        status_code: int = None,
+        request_id: str = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(code={self.code!r}, message={self.message!r})"
+
+
+class AuthenticationError(AchekError):
+    """Raised when the API key is missing or invalid (HTTP 401)."""
+
+    def __init__(self, message: str = "Invalid or missing API key"):
+        super().__init__(message, "AUTHENTICATION_ERROR", 401)
+
+
+class RateLimitError(AchekError):
+    """Raised when the rate limit is exceeded (HTTP 429)."""
+
+    def __init__(self, retry_after: int = 60, message: str = "Rate limit exceeded"):
+        super().__init__(message, "RATE_LIMIT_ERROR", 429)
+        self.retry_after = retry_after
+
+
+class ValidationError(AchekError):
+    """Raised when request validation fails (HTTP 422)."""
+
+    def __init__(self, message: str, field: str = None):
+        super().__init__(message, "VALIDATION_ERROR", 422)
+        self.field = field
+
+
+class NotFoundError(AchekError):
+    """Raised when a resource is not found (HTTP 404)."""
+
+    def __init__(self, resource: str = "Resource"):
+        super().__init__(f"{resource} not found", "NOT_FOUND", 404)
+
+
+class NetworkError(AchekError):
+    """Raised for connection failures, timeouts, and other transport errors."""
+
+    def __init__(self, message: str):
+        super().__init__(message, "NETWORK_ERROR")

achek_sdk-1.0.0/achekverify/webhooks.py

@@ -0,0 +1,56 @@
+import hmac
+import hashlib
+import json
+from typing import Any, Dict
+
+
+class Webhooks:
+    """Helpers for verifying and parsing incoming AchekConnect webhook events."""
+
+    def __init__(self, secret: str):
+        self._secret = secret
+
+    def verify(self, payload: bytes, signature: str) -> bool:
+        """
+        Return True if the HMAC-SHA256 signature matches the payload.
+
+        Args:
+            payload:   Raw request body bytes.
+            signature: Value of the X-AchekConnect-Signature header.
+        """
+        if not self._secret:
+            return False
+        expected = hmac.new(
+            self._secret.encode("utf-8"), payload, hashlib.sha256
+        ).hexdigest()
+        return hmac.compare_digest(expected, signature)
+
+    def parse(self, payload: str) -> Dict[str, Any]:
+        """Parse a raw JSON payload string into a dict."""
+        return json.loads(payload)
+
+    def construct_event(self, payload: bytes, signature: str) -> Dict[str, Any]:
+        """
+        Verify the signature then parse the payload.
+
+        Use this in your webhook route handler::
+
+            @app.route("/webhook", methods=["POST"])
+            def webhook():
+                event = client.webhooks.construct_event(
+                    request.get_data(),
+                    request.headers.get("X-AchekConnect-Signature", "")
+                )
+                if event["type"] == "otp.verified":
+                    ...
+                return "", 200
+
+        Raises:
+            ValueError: If the signature does not match.
+        """
+        if not self.verify(payload, signature):
+            raise ValueError(
+                "Webhook signature verification failed. "
+                "Ensure you are passing the raw request body and the correct secret."
+            )
+        return self.parse(payload.decode("utf-8"))

achek_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "achek-sdk"
+version = "1.0.0"
+description = "Official Python SDK for Achek — WhatsApp OTP, AI chatbots & business messaging for Nigeria"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Achek", email = "dev@achek.com.ng" }]
+keywords = ["achek", "otp", "whatsapp", "nigeria", "verification", "2fa", "chatbot"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = ["requests>=2.28.0"]
+
+[project.urls]
+Homepage = "https://achek.com.ng"
+Documentation = "https://docs.achek.com.ng"
+Repository = "https://github.com/CalebDevX/AchekVerify"
+Issues = "https://github.com/CalebDevX/AchekVerify/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["achekverify"]