paydeck 1.0.0__py3-none-any.whl

paydeck/__init__.py

@@ -0,0 +1,5 @@
+from paydeck.client import PayDeckClient
+from paydeck.exceptions import PayDeckError, PayDeckAPIError
+
+__version__ = "1.0.0"
+__all__ = ["PayDeckClient", "PayDeckError", "PayDeckAPIError"]

paydeck/client.py

@@ -0,0 +1,322 @@
+import hmac
+import hashlib
+import json
+import time
+import urllib.request
+import urllib.error
+import urllib.parse
+from typing import Any, Dict, List, Optional, Union
+
+from paydeck.exceptions import PayDeckAPIError, PayDeckError
+
+
+class PayDeckClient:
+    """Official Python SDK client for PayDeck billing microservice."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: Optional[str] = None,
+        admin_token: Optional[str] = None,
+        timeout: float = 30.0,
+        retries: int = 3,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.admin_token = admin_token
+        self.timeout = timeout
+        self.retries = retries
+
+    def _headers(self, idempotency_key: Optional[str] = None) -> Dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "PayDeck-Python-SDK/1.0.0",
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if self.admin_token:
+            headers["X-Admin-Token"] = self.admin_token
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        if params:
+            query = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
+            if query:
+                url = f"{url}?{query}"
+
+        body_bytes = None
+        if data is not None:
+            body_bytes = json.dumps(data).encode("utf-8")
+
+        headers = self._headers(idempotency_key=idempotency_key)
+        attempt = 0
+
+        while True:
+            attempt += 1
+            req = urllib.request.Request(url, data=body_bytes, headers=headers, method=method.upper())
+
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    resp_data = resp.read().decode("utf-8")
+                    return json.loads(resp_data) if resp_data else {}
+
+            except urllib.error.HTTPError as e:
+                resp_data = e.read().decode("utf-8") if e.fp else ""
+                parsed_error = {}
+                try:
+                    parsed_error = json.loads(resp_data) if resp_data else {}
+                except Exception:
+                    pass
+
+                # Extract standard error envelope fields
+                err_obj = parsed_error.get("error", {})
+                if isinstance(err_obj, str):
+                    error_msg = err_obj
+                    error_code = "API_ERROR"
+                    details = []
+                    request_id = parsed_error.get("request_id")
+                elif isinstance(err_obj, dict):
+                    error_msg = err_obj.get("message") or err_obj.get("type") or "API Error"
+                    error_code = err_obj.get("code") or err_obj.get("type") or "API_ERROR"
+                    details = err_obj.get("details", [])
+                    request_id = err_obj.get("request_id") or parsed_error.get("request_id")
+                else:
+                    error_msg = e.reason or str(e)
+                    error_code = f"HTTP_{e.code}"
+                    details = []
+                    request_id = None
+
+                # Retry on 429 rate limit or 5xx server error
+                if e.code in (429, 500, 502, 503, 504) and attempt <= self.retries:
+                    delay = 0.1 * (2 ** (attempt - 1))
+                    time.sleep(delay)
+                    continue
+
+                raise PayDeckAPIError(
+                    message=error_msg,
+                    status_code=e.code,
+                    error_code=error_code,
+                    details=details,
+                    request_id=request_id,
+                ) from e
+
+            except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+                if attempt <= self.retries:
+                    delay = 0.1 * (2 ** (attempt - 1))
+                    time.sleep(delay)
+                    continue
+                raise PayDeckError(f"Network error communicating with PayDeck: {e}") from e
+
+    # --- Consumer Billing Methods ---
+
+    def create_order(
+        self,
+        plan: Optional[str] = None,
+        amount_paise: Optional[int] = None,
+        currency: str = "INR",
+        receipt: Optional[str] = None,
+        notes: Optional[Dict[str, str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        description: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        customer_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"currency": currency}
+        if plan:
+            payload["plan"] = plan
+        if amount_paise is not None:
+            payload["amount_paise"] = amount_paise
+        if receipt:
+            payload["receipt"] = receipt
+        if notes:
+            payload["notes"] = notes
+        if metadata:
+            payload["metadata"] = metadata
+        if description:
+            payload["description"] = description
+        if customer_id:
+            payload["customer_id"] = customer_id
+
+        return self._request("POST", "/v1/orders", data=payload, idempotency_key=idempotency_key)
+
+    def verify(
+        self,
+        razorpay_order_id: str,
+        razorpay_payment_id: str,
+        razorpay_signature: str,
+    ) -> Dict[str, Any]:
+        payload = {
+            "razorpay_order_id": razorpay_order_id,
+            "razorpay_payment_id": razorpay_payment_id,
+            "razorpay_signature": razorpay_signature,
+        }
+        return self._request("POST", "/v1/verify", data=payload)
+
+    def get_payment(self, payment_id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/v1/payments/{urllib.parse.quote(payment_id)}")
+
+    def list_payments(self, limit: int = 25, offset: int = 0) -> Dict[str, Any]:
+        return self._request("GET", "/v1/payments", params={"limit": limit, "offset": offset})
+
+    def list_plans(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/plans")
+
+    def refund_payment(
+        self,
+        payment_id: str,
+        amount_paise: Optional[int] = None,
+        reason: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {}
+        if amount_paise is not None:
+            payload["amount_paise"] = amount_paise
+        if reason:
+            payload["reason"] = reason
+        return self._request("POST", f"/v1/payments/{urllib.parse.quote(payment_id)}/refund", data=payload)
+
+    # --- Customer Domain Methods ---
+
+    def create_customer(
+        self,
+        email: Optional[str] = None,
+        name: Optional[str] = None,
+        external_user_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {}
+        if email:
+            payload["email"] = email
+        if name:
+            payload["name"] = name
+        if external_user_id:
+            payload["external_user_id"] = external_user_id
+        if metadata:
+            payload["metadata"] = metadata
+        return self._request("POST", "/v1/customers", data=payload)
+
+    def list_customers(self, limit: int = 25, offset: int = 0) -> Dict[str, Any]:
+        return self._request("GET", "/v1/customers", params={"limit": limit, "offset": offset})
+
+    def list_customer_payments(self, customer_id: str, limit: int = 25, offset: int = 0) -> Dict[str, Any]:
+        return self._request("GET", f"/v1/customers/{urllib.parse.quote(customer_id)}/payments", params={"limit": limit, "offset": offset})
+
+    # --- Subscription Methods ---
+
+    def create_subscription(
+        self,
+        customer_id: str,
+        plan_id: str,
+        period_days: int = 30,
+    ) -> Dict[str, Any]:
+        payload = {
+            "customer_id": customer_id,
+            "plan_id": plan_id,
+            "period_days": period_days,
+        }
+        return self._request("POST", "/v1/subscriptions", data=payload)
+
+    def list_subscriptions(self, limit: int = 25, offset: int = 0, customer_id: Optional[str] = None) -> Dict[str, Any]:
+        params = {"limit": limit, "offset": offset}
+        if customer_id:
+            params["customer_id"] = customer_id
+        return self._request("GET", "/v1/subscriptions", params=params)
+
+    def cancel_subscription(self, subscription_id: str, immediately: bool = True) -> Dict[str, Any]:
+        return self._request("POST", f"/v1/subscriptions/{urllib.parse.quote(subscription_id)}/cancel", data={"immediately": immediately})
+
+    # --- Admin Methods ---
+
+    def create_product(self, slug: str, name: str, rate_limit_per_hour: int = 200) -> Dict[str, Any]:
+        payload = {"slug": slug, "name": name, "rate_limit_per_hour": rate_limit_per_hour}
+        return self._request("POST", "/v1/admin/products", data=payload)
+
+    def list_products(self) -> Dict[str, Any]:
+        return self._request("GET", "/v1/admin/products")
+
+    def mint_key(self, slug: str, name: Optional[str] = None, environment: str = "live") -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"environment": environment}
+        if name:
+            payload["name"] = name
+        return self._request("POST", f"/v1/admin/products/{urllib.parse.quote(slug)}/keys", data=payload)
+
+    def revoke_key(self, slug: str, key_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/v1/admin/products/{urllib.parse.quote(slug)}/keys/{urllib.parse.quote(key_id)}/revoke")
+
+    def create_plan(
+        self,
+        slug: str,
+        plan_slug: str,
+        name: str,
+        amount_paise: int,
+        currency: str = "INR",
+        interval: str = "month",
+    ) -> Dict[str, Any]:
+        payload = {
+            "slug": plan_slug,
+            "name": name,
+            "amount_paise": amount_paise,
+            "currency": currency,
+            "interval": interval,
+        }
+        return self._request("POST", f"/v1/admin/products/{urllib.parse.quote(slug)}/plans", data=payload)
+
+    def list_audit_logs(
+        self,
+        limit: int = 25,
+        offset: int = 0,
+        product_id: Optional[str] = None,
+        action: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if product_id:
+            params["product_id"] = product_id
+        if action:
+            params["action"] = action
+        return self._request("GET", "/v1/admin/audit-logs", params=params)
+
+    def list_webhooks(
+        self,
+        limit: int = 25,
+        offset: int = 0,
+        status: Optional[str] = None,
+        product_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if status:
+            params["status"] = status
+        if product_id:
+            params["product_id"] = product_id
+        return self._request("GET", "/v1/admin/webhooks", params=params)
+
+    def redeliver_webhook(self, delivery_id: str) -> Dict[str, Any]:
+        return self._request("POST", f"/v1/admin/webhooks/{urllib.parse.quote(delivery_id)}/redeliver")
+
+    # --- Static Helpers ---
+
+    @staticmethod
+    def verify_webhook_signature(
+        payload: Union[str, bytes],
+        signature: str,
+        secret: str,
+    ) -> bool:
+        """Statically verify downstream HMAC-SHA256 PayDeck webhook signatures."""
+        if not signature or not secret:
+            return False
+
+        if isinstance(payload, str):
+            payload_bytes = payload.encode("utf-8")
+        else:
+            payload_bytes = payload
+
+        expected_sig = hmac.new(secret.encode("utf-8"), payload_bytes, hashlib.sha256).hexdigest()
+        return hmac.compare_digest(expected_sig.lower(), signature.strip().lower())

paydeck/exceptions.py

@@ -0,0 +1,18 @@
+class PayDeckError(Exception):
+    """Base exception for all PayDeck SDK errors."""
+    pass
+
+
+class PayDeckAPIError(PayDeckError):
+    """Raised when the PayDeck API returns an error response."""
+
+    def __init__(self, message: str, status_code: int, error_code: str = None, details: list = None, request_id: str = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code or "API_ERROR"
+        self.details = details or []
+        self.request_id = request_id
+
+    def __repr__(self):
+        return f"PayDeckAPIError(status_code={self.status_code}, code={self.error_code!r}, message={self.message!r}, request_id={self.request_id!r})"

paydeck-1.0.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: paydeck
+Version: 1.0.0
+Summary: Official Python SDK for PayDeck billing microservice
+Author-email: PiSigma / PayDeck Team <dev@pisigma.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pisigmac/PayDeck
+Project-URL: Repository, https://github.com/pisigmac/PayDeck.git
+Keywords: paydeck,billing,razorpay,stripe,payments,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+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
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# PayDeck Python SDK
+
+Official Python SDK for the [PayDeck](https://github.com/pisigmac/PayDeck) generic billing microservice. Zero third-party runtime dependencies (uses standard library `urllib`, `json`, `hmac`, `hashlib`).
+
+## Installation
+
+```bash
+pip install paydeck
+```
+
+## Quickstart
+
+```python
+from paydeck import PayDeckClient, PayDeckAPIError
+
+# Initialize client with product API key
+client = PayDeckClient(
+    base_url="http://localhost:8787",
+    api_key="pd_live_1234567890abcdef...",
+    retries=3,
+)
+
+# 1. Create an order for a plan or custom amount
+order = client.create_order(
+    plan="pro",
+    idempotency_key="unique_checkout_session_456"
+)
+print(f"Order Created: {order['order_id']}, PayDeck ID: {order['id']}")
+
+# 2. Verify payment HMAC signature after gateway checkout
+verified = client.verify(
+    razorpay_order_id=order['order_id'],
+    razorpay_payment_id="pay_999888777",
+    razorpay_signature="signature_hash..."
+)
+print(f"Payment Status: {verified['payment']['status']}")
+
+# 3. Create a Customer & Subscription
+customer = client.create_customer(email="dev@example.com", name="Jane Developer", external_user_id="usr_42")
+subscription = client.create_subscription(customer_id=customer["id"], plan_id="plan_pro_month")
+
+# 4. Verify Downstream Webhook Signatures (Static Method)
+is_valid = PayDeckClient.verify_webhook_signature(
+    payload=raw_body_bytes_or_str,
+    signature=request_headers.get("X-PayDeck-Signature"),
+    secret="your_product_webhook_secret"
+)
+```
+
+## Admin Management
+
+```python
+admin_client = PayDeckClient(
+    base_url="http://localhost:8787",
+    admin_token="admin_secret_token",
+)
+
+# Create Product
+product = admin_client.create_product(slug="formrelay", name="FormRelay SaaS")
+
+# Mint Product API Key
+key = admin_client.mint_key(slug="formrelay", name="Production Worker Key", environment="live")
+print(f"New Key: {key['key']}")
+```

paydeck-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+paydeck/__init__.py,sha256=k2c6XZW1sJJr5JoYgiJOgqMYYSXedODe2CW2k5H14ZM,188
+paydeck/client.py,sha256=cMwc11-oqL9cqbmXYP1Z2so6ye4j-WX0U4g9ESMFiyk,11951
+paydeck/exceptions.py,sha256=OfHDNw1kGruCYcY4GMwCtqWbwya5YavKXoHE3jTTUHM,729
+paydeck-1.0.0.dist-info/METADATA,sha256=5bxLNnHeLYydK5L1pUdZxDXjfE4g8PiT8izT4GWZJAs,2729
+paydeck-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+paydeck-1.0.0.dist-info/top_level.txt,sha256=zlRMcJQYSnd4Ilg9VcwCBfcrAhX-6rKKX_KjBB7cbhM,8
+paydeck-1.0.0.dist-info/RECORD,,

paydeck-1.0.0.dist-info/WHEEL

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

paydeck-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+paydeck