snippe 0.1.0__tar.gz

snippe-0.1.0/.claude/settings.local.json

@@ -0,0 +1,6 @@
+{
+  "disabledMcpjsonServers": [
+    "shadcn",
+    "icons8mcp"
+  ]
+}

snippe-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+.venv
+sdk.md

snippe-0.1.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: snippe
+Version: 0.1.0
+Summary: Official Python SDK for Snippe Payment API
+Project-URL: Homepage, https://snippe.sh
+Project-URL: Documentation, https://documenter.getpostman.com/view/36488510/2sBXViiWAV#6beb6d54-34a1-4c9c-8a19-acd92a865711
+Project-URL: Repository, https://github.com/Neurotech-HQ/snippe-python-sdk
+Author-email: Nassdaq <mwaijegakelvin@gmail.com>
+License-Expression: MIT
+Keywords: Tanzania Payment,africa,fintech,mobile-money,snippe
+Classifier: Development Status :: 4 - Beta
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Snippe Python SDK
+
+Official Python SDK for [Snippe Payment API](https://snippe.sh) - Accept payments via mobile money, card, and QR code in East Africa.
+
+## Installation
+
+```bash
+pip install snippe
+```
+
+## Quick Start
+
+```python
+from snippe import Snippe, Customer
+
+client = Snippe("your_api_key")
+
+# Create a mobile money payment
+payment = client.create_mobile_payment(
+    amount=1000,
+    currency="TZS",
+    phone_number="0788500000",
+    customer=Customer(firstname="John", lastname="Doe"),
+)
+
+print(f"Payment reference: {payment.reference}")
+print(f"Status: {payment.status}")
+```
+
+## Payment Types
+
+### Mobile Money (USSD Push)
+
+Customer receives a USSD prompt on their phone to confirm payment.
+
+```python
+payment = client.create_mobile_payment(
+    amount=5000,
+    currency="TZS",
+    phone_number="0712345678",
+    customer=Customer(
+        firstname="Jane",
+        lastname="Doe",
+        email="jane@example.com"  # optional
+    ),
+    webhook_url="https://yourapp.com/webhooks",  # optional
+    metadata={"order_id": "ORD-123"},  # optional
+)
+```
+
+### Card Payment
+
+Returns a `payment_url` to redirect the customer to complete payment.
+
+```python
+payment = client.create_card_payment(
+    amount=50000,
+    currency="TZS",
+    phone_number="0712345678",
+    customer=Customer(
+        firstname="John",
+        lastname="Doe",
+        email="john@example.com",
+        address="123 Main Street",
+        city="Dar es Salaam",
+        state="DSM",
+        postcode="14101",
+        country="TZ",
+    ),
+    callback_url="https://yourapp.com/callback",  # required for card
+    webhook_url="https://yourapp.com/webhooks",
+)
+
+# Redirect customer to this URL
+print(payment.payment_url)
+```
+
+### QR Code Payment
+
+Returns a QR code for the customer to scan.
+
+```python
+payment = client.create_qr_payment(
+    amount=25000,
+    currency="TZS",
+    phone_number="0712345678",
+    customer=Customer(firstname="John", lastname="Doe"),
+)
+
+# Display this QR code to customer
+print(payment.payment_qr_code)
+print(payment.payment_token)
+```
+
+## Check Payment Status
+
+```python
+payment = client.get_payment("payment_reference")
+print(f"Status: {payment.status}")  # pending, completed, failed, expired, voided
+```
+
+## List Payments
+
+```python
+result = client.list_payments(limit=20, offset=0)
+for payment in result.payments:
+    print(f"{payment.reference}: {payment.status}")
+```
+
+## Check Balance
+
+```python
+balance = client.get_balance()
+print(f"Available: {balance.available_balance} {balance.currency}")
+```
+
+## Webhooks
+
+Verify and parse webhook events from Snippe.
+
+```python
+from snippe import verify_webhook, WebhookVerificationError
+
+# In your webhook endpoint
+try:
+    payload = verify_webhook(
+        body=request.body.decode(),
+        signature=request.headers["X-Webhook-Signature"],
+        timestamp=request.headers["X-Webhook-Timestamp"],
+        signing_key="your_webhook_signing_key",
+    )
+
+    if payload.event == "payment.completed":
+        print(f"Payment {payload.reference} completed!")
+        # Fulfill the order
+    elif payload.event == "payment.failed":
+        print(f"Payment {payload.reference} failed")
+        # Notify customer
+
+except WebhookVerificationError as e:
+    print(f"Invalid webhook: {e}")
+```
+
+### Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `payment.completed` | Payment successful |
+| `payment.failed` | Payment declined or failed |
+| `payment.expired` | Payment timed out |
+| `payment.voided` | Payment cancelled |
+
+## Async Support
+
+For async applications (FastAPI, aiohttp, etc.):
+
+```python
+from snippe import AsyncSnippe, Customer
+
+async def create_payment():
+    async with AsyncSnippe("your_api_key") as client:
+        payment = await client.create_mobile_payment(
+            amount=1000,
+            currency="TZS",
+            phone_number="0788500000",
+            customer=Customer(firstname="John", lastname="Doe"),
+        )
+        return payment
+```
+
+## Idempotency
+
+Prevent duplicate payments by providing an idempotency key:
+
+```python
+payment = client.create_mobile_payment(
+    amount=1000,
+    currency="TZS",
+    phone_number="0788500000",
+    customer=Customer(firstname="John", lastname="Doe"),
+    idempotency_key="unique_order_id_123",  # Your unique identifier
+)
+```
+
+## Error Handling
+
+```python
+from snippe import (
+    Snippe,
+    AuthenticationError,
+    ValidationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+try:
+    payment = client.create_mobile_payment(...)
+except AuthenticationError:
+    print("Invalid API key")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except NotFoundError:
+    print("Payment not found")
+except RateLimitError:
+    print("Too many requests, slow down")
+except ServerError:
+    print("Snippe server error, try again later")
+```
+
+## Supported Currencies
+
+| Currency | Country |
+|----------|---------|
+| TZS | Tanzania |
+| KES | Kenya |
+| UGX | Uganda |
+
+## License
+
+MIT

snippe-0.1.0/README.md

@@ -0,0 +1,221 @@
+# Snippe Python SDK
+
+Official Python SDK for [Snippe Payment API](https://snippe.sh) - Accept payments via mobile money, card, and QR code in East Africa.
+
+## Installation
+
+```bash
+pip install snippe
+```
+
+## Quick Start
+
+```python
+from snippe import Snippe, Customer
+
+client = Snippe("your_api_key")
+
+# Create a mobile money payment
+payment = client.create_mobile_payment(
+    amount=1000,
+    currency="TZS",
+    phone_number="0788500000",
+    customer=Customer(firstname="John", lastname="Doe"),
+)
+
+print(f"Payment reference: {payment.reference}")
+print(f"Status: {payment.status}")
+```
+
+## Payment Types
+
+### Mobile Money (USSD Push)
+
+Customer receives a USSD prompt on their phone to confirm payment.
+
+```python
+payment = client.create_mobile_payment(
+    amount=5000,
+    currency="TZS",
+    phone_number="0712345678",
+    customer=Customer(
+        firstname="Jane",
+        lastname="Doe",
+        email="jane@example.com"  # optional
+    ),
+    webhook_url="https://yourapp.com/webhooks",  # optional
+    metadata={"order_id": "ORD-123"},  # optional
+)
+```
+
+### Card Payment
+
+Returns a `payment_url` to redirect the customer to complete payment.
+
+```python
+payment = client.create_card_payment(
+    amount=50000,
+    currency="TZS",
+    phone_number="0712345678",
+    customer=Customer(
+        firstname="John",
+        lastname="Doe",
+        email="john@example.com",
+        address="123 Main Street",
+        city="Dar es Salaam",
+        state="DSM",
+        postcode="14101",
+        country="TZ",
+    ),
+    callback_url="https://yourapp.com/callback",  # required for card
+    webhook_url="https://yourapp.com/webhooks",
+)
+
+# Redirect customer to this URL
+print(payment.payment_url)
+```
+
+### QR Code Payment
+
+Returns a QR code for the customer to scan.
+
+```python
+payment = client.create_qr_payment(
+    amount=25000,
+    currency="TZS",
+    phone_number="0712345678",
+    customer=Customer(firstname="John", lastname="Doe"),
+)
+
+# Display this QR code to customer
+print(payment.payment_qr_code)
+print(payment.payment_token)
+```
+
+## Check Payment Status
+
+```python
+payment = client.get_payment("payment_reference")
+print(f"Status: {payment.status}")  # pending, completed, failed, expired, voided
+```
+
+## List Payments
+
+```python
+result = client.list_payments(limit=20, offset=0)
+for payment in result.payments:
+    print(f"{payment.reference}: {payment.status}")
+```
+
+## Check Balance
+
+```python
+balance = client.get_balance()
+print(f"Available: {balance.available_balance} {balance.currency}")
+```
+
+## Webhooks
+
+Verify and parse webhook events from Snippe.
+
+```python
+from snippe import verify_webhook, WebhookVerificationError
+
+# In your webhook endpoint
+try:
+    payload = verify_webhook(
+        body=request.body.decode(),
+        signature=request.headers["X-Webhook-Signature"],
+        timestamp=request.headers["X-Webhook-Timestamp"],
+        signing_key="your_webhook_signing_key",
+    )
+
+    if payload.event == "payment.completed":
+        print(f"Payment {payload.reference} completed!")
+        # Fulfill the order
+    elif payload.event == "payment.failed":
+        print(f"Payment {payload.reference} failed")
+        # Notify customer
+
+except WebhookVerificationError as e:
+    print(f"Invalid webhook: {e}")
+```
+
+### Webhook Events
+
+| Event | Description |
+|-------|-------------|
+| `payment.completed` | Payment successful |
+| `payment.failed` | Payment declined or failed |
+| `payment.expired` | Payment timed out |
+| `payment.voided` | Payment cancelled |
+
+## Async Support
+
+For async applications (FastAPI, aiohttp, etc.):
+
+```python
+from snippe import AsyncSnippe, Customer
+
+async def create_payment():
+    async with AsyncSnippe("your_api_key") as client:
+        payment = await client.create_mobile_payment(
+            amount=1000,
+            currency="TZS",
+            phone_number="0788500000",
+            customer=Customer(firstname="John", lastname="Doe"),
+        )
+        return payment
+```
+
+## Idempotency
+
+Prevent duplicate payments by providing an idempotency key:
+
+```python
+payment = client.create_mobile_payment(
+    amount=1000,
+    currency="TZS",
+    phone_number="0788500000",
+    customer=Customer(firstname="John", lastname="Doe"),
+    idempotency_key="unique_order_id_123",  # Your unique identifier
+)
+```
+
+## Error Handling
+
+```python
+from snippe import (
+    Snippe,
+    AuthenticationError,
+    ValidationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+)
+
+try:
+    payment = client.create_mobile_payment(...)
+except AuthenticationError:
+    print("Invalid API key")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except NotFoundError:
+    print("Payment not found")
+except RateLimitError:
+    print("Too many requests, slow down")
+except ServerError:
+    print("Snippe server error, try again later")
+```
+
+## Supported Currencies
+
+| Currency | Country |
+|----------|---------|
+| TZS | Tanzania |
+| KES | Kenya |
+| UGX | Uganda |
+
+## License
+
+MIT

snippe-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "snippe"
+version = "0.1.0"
+description = "Official Python SDK for Snippe Payment API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Nassdaq", email = "mwaijegakelvin@gmail.com" }
+]
+keywords = ["Tanzania Payment", "mobile-money", "snippe", "fintech", "africa"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "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 :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.24.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "respx>=0.20.0",
+]
+
+[project.urls]
+Homepage = "https://snippe.sh"
+Documentation = "https://documenter.getpostman.com/view/36488510/2sBXViiWAV#6beb6d54-34a1-4c9c-8a19-acd92a865711"
+Repository = "https://github.com/Neurotech-HQ/snippe-python-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["snippe"]

snippe-0.1.0/snippe/__init__.py

@@ -0,0 +1,67 @@
+"""
+Snippe - Python SDK for Snippe Payment API.
+
+Accept payments via mobile money, card, and QR code.
+
+Usage:
+    >>> from snippe import Snippe, Customer
+    >>> client = Snippe("your_api_key")
+    >>> payment = client.create_mobile_payment(
+    ...     amount=1000,
+    ...     currency="TZS",
+    ...     phone_number="0788500000",
+    ...     customer=Customer(firstname="John", lastname="Doe")
+    ... )
+    >>> print(payment.reference)
+"""
+
+from .client import AsyncSnippe, Snippe
+from .exceptions import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    SnippeError,
+    ValidationError,
+    WebhookVerificationError,
+)
+from .models import (
+    Balance,
+    Customer,
+    Payment,
+    PaymentDetails,
+    PaymentList,
+    WebhookPayload,
+)
+from .types import Currency, PaymentStatus, PaymentType, WebhookEvent
+from .webhooks import WebhookHandler, verify_webhook
+
+__version__ = "0.1.0"
+__all__ = [
+    # Clients
+    "Snippe",
+    "AsyncSnippe",
+    # Models
+    "Customer",
+    "Payment",
+    "PaymentDetails",
+    "PaymentList",
+    "Balance",
+    "WebhookPayload",
+    # Types
+    "PaymentType",
+    "PaymentStatus",
+    "Currency",
+    "WebhookEvent",
+    # Webhooks
+    "WebhookHandler",
+    "verify_webhook",
+    # Exceptions
+    "SnippeError",
+    "AuthenticationError",
+    "ValidationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "WebhookVerificationError",
+]