bml-connect-python 1.0.0__py3-none-any.whl

bml_connect/__init__.py

@@ -0,0 +1,79 @@
+"""
+BML Connect Python SDK
+=====================
+
+Python SDK for Bank of Maldives Connect API with synchronous and asynchronous support.
+
+Features:
+- Create, retrieve, and list transactions
+- Verify webhook signatures
+- Supports both production and sandbox environments
+- Full sync/async compatibility
+
+Basic Usage:
+    from bml_connect import BMLConnect, Environment
+
+    # Sync client
+    client = BMLConnect('your-api-key', 'your-app-id', Environment.SANDBOX)
+    transaction = client.transactions.create_transaction({...})
+
+    # Async client
+    async_client = BMLConnect('your-api-key', 'your-app-id', Environment.SANDBOX, async_mode=True)
+    transaction = await async_client.transactions.create_transaction({...})
+
+For detailed documentation and examples, visit:
+https://github.com/quillfires/bml-connect-python
+"""
+
+__version__ = "1.0.0"
+__author__ = "Ali Fayaz"
+__email__ = "fayaz.quill@gmail.com"
+
+from .client import (
+    BMLConnect,
+    Transaction,
+    QRCode,
+    PaginatedResponse,
+    Environment,
+    SignMethod,
+    TransactionState,
+    BMLConnectError,
+    AuthenticationError,
+    ValidationError,
+    NotFoundError,
+    ServerError,
+    RateLimitError,
+    SignatureUtils
+)
+
+__all__ = [
+    'BMLConnect',
+    'Transaction',
+    'QRCode',
+    'PaginatedResponse',
+    'Environment',
+    'SignMethod',
+    'TransactionState',
+    'BMLConnectError',
+    'AuthenticationError',
+    'ValidationError',
+    'NotFoundError',
+    'ServerError',
+    'RateLimitError',
+    'SignatureUtils'
+]
+
+BMLConnect.__module__ = "bml_connect"
+Transaction.__module__ = "bml_connect"
+QRCode.__module__ = "bml_connect"
+PaginatedResponse.__module__ = "bml_connect"
+Environment.__module__ = "bml_connect"
+SignMethod.__module__ = "bml_connect"
+TransactionState.__module__ = "bml_connect"
+BMLConnectError.__module__ = "bml_connect"
+AuthenticationError.__module__ = "bml_connect"
+ValidationError.__module__ = "bml_connect"
+NotFoundError.__module__ = "bml_connect"
+ServerError.__module__ = "bml_connect"
+RateLimitError.__module__ = "bml_connect"
+SignatureUtils.__module__ = "bml_connect"

bml_connect/client.py

@@ -0,0 +1,536 @@
+"""
+BML Connect Python SDK
+======================
+
+Robust Python SDK for Bank of Maldives Connect API with comprehensive sync/async support.
+"""
+
+import hashlib
+import hmac
+import base64
+import json
+import uuid
+from typing import Optional, Dict, Any, Union, List
+from urllib.parse import urlencode
+import requests
+import aiohttp
+from dataclasses import dataclass
+from enum import Enum
+import logging
+
+logger = logging.getLogger("bml_connect")
+logger.addHandler(logging.NullHandler())
+
+SDK_VERSION = "1.0.0"
+USER_AGENT = f"BML-Connect-Python/{SDK_VERSION}"
+
+
+class Environment(Enum):
+    SANDBOX = "sandbox"
+    PRODUCTION = "production"
+    
+    @property
+    def base_url(self) -> str:
+        return {
+            Environment.SANDBOX: "https://api.uat.merchants.bankofmaldives.com.mv/public",
+            Environment.PRODUCTION: "https://api.merchants.bankofmaldives.com.mv/public"
+        }[self]
+
+
+class SignMethod(Enum):
+    SHA1 = "sha1"
+    MD5 = "md5"
+    
+    @classmethod
+    def _missing_(cls, value: str) -> 'SignMethod':
+        value = value.lower()
+        for member in cls:
+            if member.value == value:
+                return member
+        return cls.SHA1  # Default to SHA1
+
+
+class TransactionState(Enum):
+    CREATED = "CREATED"
+    QR_CODE_GENERATED = "QR_CODE_GENERATED"
+    CONFIRMED = "CONFIRMED"
+    CANCELLED = "CANCELLED"
+    FAILED = "FAILED"
+    EXPIRED = "EXPIRED"
+
+
+@dataclass
+class QRCode:
+    url: str
+    image: Optional[str] = None  # Base64 encoded image if available
+
+
+@dataclass
+class Transaction:
+    transaction_id: Optional[str] = None
+    local_id: Optional[str] = None
+    customer_reference: Optional[str] = None
+    amount: Optional[int] = None
+    currency: Optional[str] = None
+    provider: Optional[str] = None
+    state: Optional[TransactionState] = None
+    created: Optional[str] = None
+    signature: Optional[str] = None
+    url: Optional[str] = None
+    qr_code: Optional[QRCode] = None
+    redirect_url: Optional[str] = None
+    app_version: Optional[str] = None
+    api_version: Optional[str] = None
+    device_id: Optional[str] = None
+    sign_method: Optional[SignMethod] = None
+    expires_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Transaction':
+        qr_code = None
+        qr_data = data.get('qrCode', {})
+        if qr_data and 'url' in qr_data:
+            qr_code = QRCode(
+                url=qr_data['url'],
+                image=qr_data.get('image')
+            )
+        
+        # Parse state enum
+        state = None
+        if 'state' in data:
+            try:
+                state = TransactionState(data['state'])
+            except ValueError:
+                logger.warning(f"Unknown transaction state: {data['state']}")
+                state = None
+        
+        # Parse sign method enum
+        sign_method = None
+        if 'signMethod' in data:
+            try:
+                sign_method = SignMethod(data['signMethod'])
+            except ValueError:
+                logger.warning(f"Unknown sign method: {data['signMethod']}")
+                sign_method = None
+        
+        return cls(
+            transaction_id=data.get('transactionId'),
+            local_id=data.get('localId'),
+            customer_reference=data.get('customerReference'),
+            amount=data.get('amount'),
+            currency=data.get('currency'),
+            provider=data.get('provider'),
+            state=state,
+            created=data.get('created'),
+            signature=data.get('signature'),
+            url=data.get('url'),
+            qr_code=qr_code,
+            redirect_url=data.get('redirectUrl'),
+            app_version=data.get('appVersion'),
+            api_version=data.get('apiVersion'),
+            device_id=data.get('deviceId'),
+            sign_method=sign_method,
+            expires_at=data.get('expiresAt')
+        )
+
+
+@dataclass
+class PaginatedResponse:
+    count: int
+    items: List[Transaction]
+    current_page: int
+    total_pages: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'PaginatedResponse':
+        items = [Transaction.from_dict(item) for item in data.get('items', [])]
+        return cls(
+            count=data.get('count', 0),
+            items=items,
+            current_page=data.get('currentPage', 1),
+            total_pages=data.get('totalPages', 1)
+        )
+
+
+class BMLConnectError(Exception):
+    """Base exception for BML Connect errors"""
+    def __init__(self, message: str, code: Optional[str] = None, status_code: Optional[int] = None):
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        if self.code:
+            return f"[{self.code}] {self.message}"
+        return self.message
+
+
+class AuthenticationError(BMLConnectError):
+    pass
+
+
+class ValidationError(BMLConnectError):
+    pass
+
+
+class NotFoundError(BMLConnectError):
+    pass
+
+
+class ServerError(BMLConnectError):
+    pass
+
+
+class RateLimitError(BMLConnectError):
+    pass
+
+
+class SignatureUtils:
+    @staticmethod
+    def generate_signature(data: Dict[str, Any], api_key: str, method: Union[SignMethod, str] = SignMethod.SHA1) -> str:
+        """Generate signature with proper key sorting and encoding"""
+        if isinstance(method, str):
+            try:
+                method = SignMethod(method)
+            except ValueError:
+                method = SignMethod.SHA1
+                logger.warning(f"Invalid sign method '{method}', defaulting to SHA1")
+        
+        # Filtering None values and empty strings
+        filtered_data = {k: v for k, v in data.items() if v is not None and v != ""}
+        
+        sorted_params = sorted(filtered_data.items(), key=lambda x: x[0].lower())
+        query_string = urlencode(sorted_params, doseq=True)
+        
+        signature_string = f"{query_string}&apiKey={api_key}"
+        
+        if method == SignMethod.SHA1:
+            return hashlib.sha1(signature_string.encode('utf-8')).hexdigest()
+        elif method == SignMethod.MD5:
+            return base64.b64encode(hashlib.md5(signature_string.encode('utf-8')).digest()).decode()
+        else:
+            raise ValueError(f"Unsupported signature method: {method}")
+
+    @staticmethod
+    def verify_signature(data: Dict[str, Any], signature: str, api_key: str, method: Union[SignMethod, str] = SignMethod.SHA1) -> bool:
+        """Secure signature verification with constant-time comparison"""
+        expected = SignatureUtils.generate_signature(data, api_key, method)
+        return hmac.compare_digest(expected, signature)
+
+
+class BaseClient:
+    def __init__(self, api_key: str, app_id: str, environment: Environment = Environment.PRODUCTION):
+        self.api_key = api_key
+        self.app_id = app_id
+        self.environment = environment
+        self.base_url = environment.base_url
+        self.session = None  # Will be set in child classes
+        logger.info(f"Initialized BML Client for {environment.name} environment")
+
+    def _get_headers(self) -> Dict[str, str]:
+        return {
+            'Authorization': f"Bearer {self.api_key}",
+            'Content-Type': 'application/json',
+            'User-Agent': USER_AGENT,
+            'X-App-Id': self.app_id
+        }
+
+    def _prepare_transaction_data(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Prepare transaction data with required defaults"""
+        prepared = data.copy()
+        prepared.setdefault('apiVersion', '2.0')
+        prepared.setdefault('signMethod', 'sha1')
+        prepared.setdefault('appVersion', USER_AGENT)
+        prepared.setdefault('deviceId', str(uuid.uuid4()))
+        return prepared
+
+    def _handle_response(self, response: Union[requests.Response, aiohttp.ClientResponse], response_data: Dict[str, Any]):
+        """Handle API response with proper error mapping"""
+        status_code = response.status if isinstance(response, aiohttp.ClientResponse) else response.status_code
+        message = response_data.get('message', 'Unknown error')
+        code = response_data.get('code')
+        
+        logger.debug(f"API Response: {status_code} - {message}")
+        
+        if status_code == 400:
+            raise ValidationError(message, code, status_code)
+        elif status_code == 401:
+            raise AuthenticationError(message, code, status_code)
+        elif status_code == 404:
+            raise NotFoundError(message, code, status_code)
+        elif status_code == 429:
+            raise RateLimitError(message, code, status_code)
+        elif status_code >= 500:
+            raise ServerError(message, code, status_code)
+        elif status_code >= 400:
+            raise BMLConnectError(message, code, status_code)
+
+
+class SyncClient(BaseClient):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.session = requests.Session()
+        self.session.headers.update(self._get_headers())
+        logger.debug("Initialized synchronous HTTP session")
+
+    def _request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
+        url = f"{self.base_url}{endpoint}"
+        logger.debug(f"Request: {method} {url} {kwargs.get('params')}")
+        
+        try:
+            response = self.session.request(
+                method,
+                url,
+                timeout=30,
+                **kwargs
+            )
+            
+            try:
+                response_data = response.json()
+            except json.JSONDecodeError:
+                logger.error(f"Invalid JSON response: {response.text[:500]}")
+                raise ServerError("Invalid JSON response", status_code=response.status_code)
+            
+            logger.debug(f"Response: {response.status_code} - {response_data}")
+            
+            if not response.ok:
+                self._handle_response(response, response_data)
+                
+            return response_data
+        except requests.exceptions.RequestException as e:
+            logger.error(f"Network error: {str(e)}")
+            raise BMLConnectError(f"Network error: {str(e)}")
+
+    def create_transaction(self, data: Dict[str, Any]) -> Transaction:
+        logger.info("Creating new transaction")
+        data = self._prepare_transaction_data(data)
+        
+        try:
+            sign_method = SignMethod(data.get('signMethod', 'sha1'))
+        except ValueError:
+            sign_method = SignMethod.SHA1
+            logger.warning(f"Invalid sign method, defaulting to SHA1")
+        
+        data['signature'] = SignatureUtils.generate_signature(data, self.api_key, sign_method)
+        
+        response = self._request('POST', '/transactions', json=data)
+        return Transaction.from_dict(response)
+
+    def get_transaction(self, transaction_id: str) -> Transaction:
+        logger.info(f"Fetching transaction: {transaction_id}")
+        response = self._request('GET', f'/transactions/{transaction_id}')
+        return Transaction.from_dict(response)
+
+    def list_transactions(
+        self, 
+        page: int = 1, 
+        per_page: int = 20,
+        state: Optional[str] = None,
+        provider: Optional[str] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None
+    ) -> PaginatedResponse:
+        logger.info(f"Listing transactions: page={page}, per_page={per_page}")
+        params = {'page': page, 'perPage': per_page}
+        
+        # Add filters
+        if state:
+            params['state'] = state
+        if provider:
+            params['provider'] = provider
+        if start_date:
+            params['startDate'] = start_date
+        if end_date:
+            params['endDate'] = end_date
+        
+        response = self._request('GET', '/transactions', params=params)
+        return PaginatedResponse.from_dict(response)
+    
+    def close(self):
+        """Close the HTTP session"""
+        if self.session:
+            self.session.close()
+            logger.debug("Closed synchronous HTTP session")
+
+
+class AsyncClient(BaseClient):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.session = aiohttp.ClientSession(
+            headers=self._get_headers(),
+            timeout=aiohttp.ClientTimeout(total=30)
+        )
+        logger.debug("Initialized asynchronous HTTP session")
+
+    async def _request(self, method: str, endpoint: str, **kwargs) -> Dict[str, Any]:
+        url = f"{self.base_url}{endpoint}"
+        logger.debug(f"Async Request: {method} {url} {kwargs.get('params')}")
+        
+        try:
+            async with self.session.request(method, url, **kwargs) as response:
+                try:
+                    response_data = await response.json()
+                except aiohttp.ContentTypeError:
+                    text = await response.text()
+                    logger.error(f"Invalid JSON response: {text[:500]}")
+                    raise ServerError(f"Invalid JSON: {text[:200]}", status_code=response.status)
+                
+                logger.debug(f"Async Response: {response.status} - {response_data}")
+                
+                if not response.ok:
+                    self._handle_response(response, response_data)
+                    
+                return response_data
+        except aiohttp.ClientError as e:
+            logger.error(f"Network error: {str(e)}")
+            raise BMLConnectError(f"Network error: {str(e)}")
+
+    async def create_transaction(self, data: Dict[str, Any]) -> Transaction:
+        logger.info("Creating new transaction (async)")
+        data = self._prepare_transaction_data(data)
+        
+        try:
+            sign_method = SignMethod(data.get('signMethod', 'sha1'))
+        except ValueError:
+            sign_method = SignMethod.SHA1
+            logger.warning(f"Invalid sign method, defaulting to SHA1")
+        
+        data['signature'] = SignatureUtils.generate_signature(data, self.api_key, sign_method)
+        
+        response = await self._request('POST', '/transactions', json=data)
+        return Transaction.from_dict(response)
+
+    async def get_transaction(self, transaction_id: str) -> Transaction:
+        logger.info(f"Fetching transaction (async): {transaction_id}")
+        response = await self._request('GET', f'/transactions/{transaction_id}')
+        return Transaction.from_dict(response)
+
+    async def list_transactions(
+        self, 
+        page: int = 1, 
+        per_page: int = 20,
+        state: Optional[str] = None,
+        provider: Optional[str] = None,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None
+    ) -> PaginatedResponse:
+        logger.info(f"Listing transactions (async): page={page}, per_page={per_page}")
+        params = {'page': page, 'perPage': per_page}
+        
+        # Add filters
+        if state:
+            params['state'] = state
+        if provider:
+            params['provider'] = provider
+        if start_date:
+            params['startDate'] = start_date
+        if end_date:
+            params['endDate'] = end_date
+        
+        response = await self._request('GET', '/transactions', params=params)
+        return PaginatedResponse.from_dict(response)
+    
+    async def close(self):
+        """Close the HTTP session"""
+        if self.session and not self.session.closed:
+            await self.session.close()
+            logger.debug("Closed asynchronous HTTP session")
+
+
+class BMLConnect:
+    def __init__(
+        self,
+        api_key: str,
+        app_id: str,
+        environment: Union[Environment, str] = Environment.PRODUCTION,
+        async_mode: bool = False
+    ):
+        """
+        Initialize BML Connect client
+        
+        Args:
+            api_key: Your API key from BML merchant portal
+            app_id: Your application ID from BML merchant portal
+            environment: 'production' or 'sandbox' (default: production)
+            async_mode: Whether to use async operations (default: False)
+        """
+        self.api_key = api_key
+        self.app_id = app_id
+        
+        if isinstance(environment, str):
+            try:
+                self.environment = Environment[environment.upper()]
+            except KeyError:
+                raise ValueError(f"Invalid environment: {environment}. Use 'production' or 'sandbox'")
+        else:
+            self.environment = environment
+            
+        self.async_mode = async_mode
+        
+        if async_mode:
+            self.client = AsyncClient(api_key, app_id, self.environment)
+        else:
+            self.client = SyncClient(api_key, app_id, self.environment)
+    
+    @property
+    def transactions(self):
+        return self.client
+
+    def verify_webhook_signature(
+        self,
+        payload: Union[Dict[str, Any], str],
+        signature: str,
+        method: Union[SignMethod, str] = SignMethod.SHA1
+    ) -> bool:
+        """
+        Verify webhook signature for data integrity
+        
+        Args:
+            payload: Webhook payload data (dict or JSON string)
+            signature: Received signature to verify
+            method: Signature method (default: SHA1)
+            
+        Returns:
+            bool: True if signature is valid, False otherwise
+        """
+        if isinstance(payload, str):
+            try:
+                payload = json.loads(payload)
+            except json.JSONDecodeError:
+                raise ValidationError("Invalid JSON payload")
+                
+        # Create a copy and remove signature if present
+        verification_payload = payload.copy()
+        if 'signature' in verification_payload:
+            del verification_payload['signature']
+            
+        return SignatureUtils.verify_signature(verification_payload, signature, self.api_key, method)
+    
+    def close(self):
+        """Clean up resources (synchronous)"""
+        if not self.async_mode and hasattr(self.client, 'close'):
+            self.client.close()
+    
+    async def aclose(self):
+        """Clean up resources (asynchronous)"""
+        if self.async_mode and hasattr(self.client, 'close'):
+            await self.client.close()
+
+
+__all__ = [
+    'BMLConnect',
+    'Transaction',
+    'QRCode',
+    'PaginatedResponse',
+    'Environment',
+    'SignMethod',
+    'TransactionState',
+    'BMLConnectError',
+    'AuthenticationError',
+    'ValidationError',
+    'NotFoundError',
+    'ServerError',
+    'RateLimitError',
+    'SignatureUtils'
+]

bml_connect_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: bml-connect-python
+Version: 1.0.0
+Summary: Python SDK for Bank of Maldives Connect API with sync/async support
+Author-email: Ali Fayaz <fayaz.quill@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/quillfires/bml-connect-python
+Project-URL: Documentation, https://bml-connect-python.readthedocs.io
+Project-URL: Repository, https://github.com/quillfires/bml-connect-python
+Project-URL: Issues, https://github.com/quillfires/bml-connect-python/issues
+Project-URL: Changelog, https://github.com/quillfires/bml-connect-python/releases
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: aiohttp>=3.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=5.0.0; extra == "dev"
+Requires-Dist: mypy>=0.990; extra == "dev"
+Requires-Dist: pre-commit>=2.20.0; extra == "dev"
+Requires-Dist: types-requests>=2.28.0; extra == "dev"
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == "django"
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == "flask"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.68.0; extra == "fastapi"
+Requires-Dist: uvicorn>=0.15.0; extra == "fastapi"
+Provides-Extra: sanic
+Requires-Dist: sanic>=22.0.0; extra == "sanic"
+Dynamic: license-file
+
+# BML Connect Python SDK
+
+[![PyPI Version](https://img.shields.io/pypi/v/bml-connect-python.svg)](https://pypi.org/project/bml-connect-python/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/bml-connect-python.svg)](https://pypi.org/project/bml-connect-python/)
+[![License](https://img.shields.io/pypi/l/bml-connect-python.svg)](https://opensource.org/licenses/MIT)
+
+Python SDK for Bank of Maldives Connect API with synchronous and asynchronous support.  
+Compatible with all Python frameworks including Django, Flask, FastAPI, and Sanic.
+
+---
+
+## Features
+
+- **Sync/Async Support:** Choose your preferred programming style
+- **Full API Coverage:** Transactions, webhooks, and signature verification
+- **Type Annotations:** Full type hint support for better development experience
+- **Error Handling:** Comprehensive error hierarchy for easy debugging
+- **Framework Agnostic:** Works with any Python web framework
+- **MIT Licensed:** Open source and free to use
+
+---
+
+## Installation
+
+```bash
+pip install bml-connect-python
+```
+
+---
+
+## Quick Start
+
+### Synchronous Client
+
+```python
+from bml_connect import BMLConnect, Environment
+
+client = BMLConnect(
+    api_key="your_api_key",
+    app_id="your_app_id",
+    environment=Environment.SANDBOX
+)
+
+try:
+    transaction = client.transactions.create_transaction({
+        "amount": 1500,  # 15.00 MVR
+        "currency": "MVR",
+        "provider": "alipay",
+        "redirectUrl": "https://yourstore.com/success",
+        "localId": "order_123",
+        "customerReference": "Customer #456"
+    })
+    print(f"Transaction ID: {transaction.transaction_id}")
+    print(f"Payment URL: {transaction.url}")
+except Exception as e:
+    print(f"Error: {e}")
+finally:
+    client.close()
+```
+
+### Asynchronous Client
+
+```python
+import asyncio
+from bml_connect import BMLConnect, Environment
+
+async def main():
+    client = BMLConnect(
+        api_key="your_api_key",
+        app_id="your_app_id",
+        environment=Environment.SANDBOX,
+        async_mode=True
+    )
+    try:
+        transaction = await client.transactions.create_transaction({
+            "amount": 2000,
+            "currency": "MVR",
+            "provider": "wechat",
+            "redirectUrl": "https://yourstore.com/success"
+        })
+        print(f"Transaction ID: {transaction.transaction_id}")
+    finally:
+        await client.aclose()
+
+asyncio.run(main())
+```
+
+---
+
+## Webhook Verification
+
+### Flask Example
+
+```python
+from flask import Flask, request, jsonify
+from bml_connect import BMLConnect
+
+app = Flask(__name__)
+client = BMLConnect(api_key="your_api_key", app_id="your_app_id")
+
+@app.route('/webhook', methods=['POST'])
+def webhook():
+    payload = request.get_json()
+    signature = payload.get('signature')
+    if client.verify_webhook_signature(payload, signature):
+        # Process webhook
+        return jsonify({"status": "success"}), 200
+    else:
+        return jsonify({"error": "Invalid signature"}), 403
+```
+
+### FastAPI Example
+
+```python
+from fastapi import FastAPI, Request, HTTPException
+from bml_connect import BMLConnect
+
+app = FastAPI()
+client = BMLConnect(api_key="your_api_key", app_id="your_app_id")
+
+@app.post("/webhook")
+async def handle_webhook(request: Request):
+    payload = await request.json()
+    signature = payload.get("signature")
+    if client.verify_webhook_signature(payload, signature):
+        return {"status": "success"}
+    else:
+        raise HTTPException(403, "Invalid signature")
+```
+
+### Sanic Example
+
+```python
+from sanic import Sanic, response
+from bml_connect import BMLConnect
+
+app = Sanic("BMLWebhook")
+client = BMLConnect(api_key="your_api_key", app_id="your_app_id")
+
+@app.post('/webhook')
+async def webhook(request):
+    payload = request.json
+    signature = payload.get('signature')
+    if client.verify_webhook_signature(payload, signature):
+        return response.json({"status": "success"})
+    else:
+        return response.json({"error": "Invalid signature"}, status=403)
+```
+
+---
+
+## API Reference
+
+### Main Classes
+
+- `BMLConnect`: Main entry point for the SDK.
+- `Transaction`: Transaction object.
+- `QRCode`: QR code details.
+- `PaginatedResponse`: For paginated transaction lists.
+- `Environment`: Enum for `SANDBOX` and `PRODUCTION`.
+- `SignMethod`: Enum for signature methods.
+- `TransactionState`: Enum for transaction states.
+
+### Error Classes
+
+- `BMLConnectError`
+- `AuthenticationError`
+- `ValidationError`
+- `NotFoundError`
+- `ServerError`
+- `RateLimitError`
+
+### Utilities
+
+- `SignatureUtils.generate_signature(data, api_key, method)`
+- `SignatureUtils.verify_signature(data, signature, api_key, method)`
+
+---
+
+## Development
+
+### Requirements
+
+- Python 3.7+
+- See `requirements.txt` and `requirements-dev.txt` for dependencies.
+
+### Testing
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+### Formatting & Linting
+
+```bash
+black .
+flake8 .
+mypy .
+```
+
+---
+
+## Packaging
+
+- Uses `pyproject.toml` for build configuration.
+- Source code is in `src/bml_connect/`.
+- Examples in `examples/`.
+- Tests in `tests/`.
+
+---
+
+## License
+
+MIT License. See `LICENSE` for details.
+
+---
+
+## Links
+
+- [Homepage](https://github.com/bankofmaldives/bml-connect-python)
+- [Documentation](https://bml-connect-python.readthedocs.io)
+- [API Reference](docs/api_reference.md)
+- [Changelog](https://github.com/bankofmaldives/bml-connect-python/releases)
+
+---
+
+## Contributing
+
+Pull requests and issues are welcome! See the documentation for guidelines.

bml_connect_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+bml_connect/__init__.py,sha256=7dAgLGnl8f3GclavYhbyPsJY9KHskuKrDam59FTm1hE,2080
+bml_connect/client.py,sha256=sEsO4pqBIs91f8AH0UJJLOlDZtqXARmT5KKIj4vym8U,18430
+bml_connect_python-1.0.0.dist-info/licenses/LICENSE,sha256=CB2PmSDOuvgp-Rts5KdYBPZrjg5Vi2qkeoMMTGj1WiE,1104
+bml_connect_python-1.0.0.dist-info/METADATA,sha256=q5RwJkQ6L24clG35tRsEsn8oCsLECtYrXyesWWTq1KY,7907
+bml_connect_python-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+bml_connect_python-1.0.0.dist-info/top_level.txt,sha256=VfPbi_18vywwgVjitexLr0B1g1z0jjyAipDXCl_zh8I,12
+bml_connect_python-1.0.0.dist-info/RECORD,,

bml_connect_python-1.0.0.dist-info/WHEEL

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

bml_connect_python-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Ali Fayaz (Quill) (quillfires)
+
+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.

bml_connect_python-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bml_connect