bml-connect-python 1.0.0__tar.gz

bml_connect_python-1.0.0/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/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md
+include LICENSE
+include requirements.txt
+include requirements-dev.txt
+include pyproject.toml
+
+recursive-include src *.py
+recursive-include tests *.py
+recursive-include examples *.py
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

bml_connect_python-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,230 @@
+# 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/examples/basic_async.py

@@ -0,0 +1,52 @@
+"""
+Basic Asynchronous Usage Example
+===============================
+
+This example shows how to use the BML Connect SDK in asynchronous mode.
+"""
+
+import asyncio
+from bml_connect import BMLConnect, Environment
+
+async def main():
+    # Initialize async client
+    client = BMLConnect(
+        api_key="your_api_key_here",
+        app_id="your_app_id_here",
+        environment=Environment.SANDBOX,
+        async_mode=True
+    )
+    
+    try:
+        # Create a transaction
+        transaction = await client.transactions.create_transaction({
+            "amount": 2000,  # 20.00 MVR
+            "currency": "MVR",
+            "provider": "wechat",
+            "redirectUrl": "https://yourstore.com/success"
+        })
+        
+        print(f"Created transaction: {transaction.transaction_id}")
+        print(f"QR Code URL: {transaction.qr_code.url if transaction.qr_code else 'N/A'}")
+        
+        # Get transaction details
+        details = await client.transactions.get_transaction(transaction.transaction_id)
+        print(f"Current status: {details.state.value if details.state else 'N/A'}")
+        
+        # List transactions with filters
+        print("\nListing confirmed transactions...")
+        transactions = await client.transactions.list_transactions(
+            page=1,
+            per_page=5,
+            state="CONFIRMED"
+        )
+        print(f"Found {transactions.count} confirmed transactions")
+        
+    except Exception as e:
+        print(f"Error: {str(e)}")
+    finally:
+        # Clean up async resources
+        await client.aclose()
+
+if __name__ == "__main__":
+    asyncio.run(main())

bml_connect_python-1.0.0/examples/basic_sync.py

@@ -0,0 +1,50 @@
+"""
+Basic Synchronous Usage Example
+===============================
+
+This example shows how to use the BML Connect SDK in synchronous mode.
+"""
+
+from bml_connect import BMLConnect, Environment
+
+# Initialize client
+client = BMLConnect(
+    api_key="your_api_key_here",
+    app_id="your_app_id_here",
+    environment=Environment.SANDBOX
+)
+
+try:
+    # Create a transaction
+    transaction = client.transactions.create_transaction({
+        "amount": 1500,  # 15.00 MVR
+        "currency": "MVR",
+        "provider": "alipay",
+        "redirectUrl": "https://yourstore.com/success",
+        "localId": "order_12345",
+        "customerReference": "Customer #789"
+    })
+    
+    print("Transaction created successfully!")
+    print(f"ID: {transaction.transaction_id}")
+    print(f"Amount: {transaction.amount / 100:.2f} {transaction.currency}")
+    print(f"Status: {transaction.state.value if transaction.state else 'N/A'}")
+    print(f"Payment URL: {transaction.url}")
+    
+    # Retrieve the same transaction
+    print("\nFetching transaction details...")
+    fetched = client.transactions.get_transaction(transaction.transaction_id)
+    print(f"Fetched status: {fetched.state.value if fetched.state else 'N/A'}")
+    
+    # List recent transactions
+    print("\nListing recent transactions...")
+    transactions = client.transactions.list_transactions(page=1, per_page=3)
+    print(f"Found {transactions.count} transactions (showing first 3):")
+    for txn in transactions.items:
+        print(f"- {txn.transaction_id}: {txn.amount/100:.2f} {txn.currency} ({txn.state.value})")
+        
+except Exception as e:
+    print(f"Error: {str(e)}")
+finally:
+    # Clean up resources
+    client.close()

bml_connect_python-1.0.0/examples/webhook_fastapi.py

@@ -0,0 +1,43 @@
+"""
+FastAPI Webhook Handler Example
+===============================
+
+This example shows how to handle BML Connect webhooks with FastAPI.
+"""
+
+from fastapi import FastAPI, Request, HTTPException
+from bml_connect import BMLConnect
+import uvicorn
+
+app = FastAPI(title="BML Connect Webhook Handler")
+client = BMLConnect(api_key="your_api_key_here", app_id="your_app_id_here")
+
+@app.post("/webhook")
+async def handle_webhook(request: Request):
+    try:
+        payload = await request.json()
+        signature = payload.get("signature")
+        
+        if not signature:
+            raise HTTPException(400, "Missing signature header")
+        
+        if client.verify_webhook_signature(payload, signature):
+            # Process verified webhook
+            transaction_id = payload.get("transactionId")
+            status = payload.get("status")
+            amount = payload.get("amount", 0) / 100
+            currency = payload.get("currency", "MVR")
+            
+            print(f"Received webhook for transaction {transaction_id}")
+            print(f"Status: {status}, Amount: {amount:.2f} {currency}")
+            
+            # Add your business logic here (update database, send notification, etc.)
+            
+            return {"status": "success"}
+        else:
+            raise HTTPException(403, "Invalid signature")
+    except Exception as e:
+        raise HTTPException(400, str(e))
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)