fype-sdk-beta 1.0.0__py3-none-any.whl

fype/__init__.py

@@ -0,0 +1,17 @@
+from fype.client import Fype
+from fype.errors import (
+    ApiConnectionError,
+    AuthenticationError,
+    FypeError,
+    InvalidRequestError,
+    SignatureVerificationError,
+)
+
+__all__ = [
+    "ApiConnectionError",
+    "AuthenticationError",
+    "Fype",
+    "FypeError",
+    "InvalidRequestError",
+    "SignatureVerificationError",
+]

fype/client.py

@@ -0,0 +1,110 @@
+from typing import Any
+
+import httpx
+
+from fype.errors import ApiConnectionError, AuthenticationError, FypeError, InvalidRequestError
+from fype.resources import (
+    EntitlementsResource,
+    PaymentsResource,
+    PlansResource,
+    RefundsResource,
+    SubscriptionsResource,
+    UsageResource,
+    WebhooksResource,
+)
+
+
+class Fype:
+    """
+    The official Fype Python client SDK.
+    Provides type-safe access to payments, refunds, and webhook verification resources.
+    """
+
+    def __init__(self, api_key: str, base_url: str = "http://localhost:8000/v1"):
+        if not api_key:
+            raise ValueError("Fype API Key must be supplied.")
+
+        self.api_key = api_key
+        # Enforce clean suffix formatting on base url
+        self.base_url = base_url.rstrip("/")
+
+        # Initialize resources
+        self.payments = PaymentsResource(self)
+        self.refunds = RefundsResource(self)
+        self.webhooks = WebhooksResource()
+        self.subscriptions = SubscriptionsResource(self)
+        self.plans = PlansResource(self)
+        self.entitlements = EntitlementsResource(self)
+        self.usage = UsageResource(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """
+        Helper handler that signs and executes HTTP request and
+        translates responses/exceptions.
+        """
+        url = f"{self.base_url}{path}"
+
+        request_headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "Fype-PythonSDK/v1.0",
+        }
+        if headers:
+            request_headers.update(headers)
+
+        try:
+            with httpx.Client(timeout=15.0) as client:
+                response = client.request(
+                    method=method,
+                    url=url,
+                    params=params,
+                    json=json,
+                    headers=request_headers,
+                )
+
+                # Check for client and server error codes
+                if 400 <= response.status_code < 600:
+                    self._handle_error_response(response)
+
+                return response.json()
+        except httpx.RequestError as e:
+            raise ApiConnectionError(
+                f"Fype connection error: {e!s}",
+            ) from e
+
+    def _handle_error_response(self, response: httpx.Response):
+        """Map HTTP error status codes to dedicated Python exception classes."""
+        status_code = response.status_code
+        text = response.text
+
+        try:
+            error_data = response.json()
+            message = error_data.get("message") or error_data.get("detail") or text
+        except Exception:
+            message = text
+
+        if status_code == 401:
+            raise AuthenticationError(
+                f"Authentication failed (API Key is invalid or expired): {message}",
+                status_code,
+                text,
+            )
+        elif status_code in (400, 422, 404, 409):
+            raise InvalidRequestError(
+                f"Invalid request parameters: {message}",
+                status_code,
+                text,
+            )
+        else:
+            raise FypeError(
+                f"Fype server error (HTTP {status_code}): {message}",
+                status_code,
+                text,
+            )

fype/errors.py

@@ -0,0 +1,37 @@
+class FypeError(Exception):
+    """Base error class for all Fype SDK exceptions."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        response_body: str | None = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class AuthenticationError(FypeError):
+    """Exception raised when API authentication fails."""
+
+    pass
+
+
+class InvalidRequestError(FypeError):
+    """Exception raised when the request contains invalid parameters."""
+
+    pass
+
+
+class ApiConnectionError(FypeError):
+    """Exception raised when communication with the Fype servers fails."""
+
+    pass
+
+
+class SignatureVerificationError(FypeError):
+    """Exception raised when webhook signature verification fails."""
+
+    pass

fype/resources.py

@@ -0,0 +1,234 @@
+import hashlib
+import hmac
+from typing import Any
+
+
+class PaymentsResource:
+    """Helper resource class for creating, fetching, and listing payments."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def create(
+        self,
+        amount: int,
+        currency: str,
+        customer_email: str,
+        success_url: str,
+        cancel_url: str,
+        reference_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Create a new payment order.
+        Returns the created Payment dictionary containing visual checkout_url.
+        """
+        payload = {
+            "amount": amount,
+            "currency": currency,
+            "customer_email": customer_email,
+            "success_url": success_url,
+            "cancel_url": cancel_url,
+        }
+        if reference_id is not None:
+            payload["reference_id"] = reference_id
+        if metadata is not None:
+            payload["metadata"] = metadata
+
+        return self._client._request("POST", "/payments", json=payload)
+
+    def retrieve(self, payment_id: str) -> dict[str, Any]:
+        """Retrieve details for a specific Fype payment ID."""
+        return self._client._request("GET", f"/payments/{payment_id}")
+
+    def list(self, limit: int = 20, offset: int = 0) -> list[dict[str, Any]]:
+        """List paginated payments (separate test/live lists based on key authorization)."""
+        params = {"limit": limit, "offset": offset}
+        return self._client._request("GET", "/payments", params=params)
+
+
+class RefundsResource:
+    """Helper resource class for executing refunds."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def create(self, payment_id: str, amount: int | None = None) -> dict[str, Any]:
+        """
+        Initiate a refund for a successful payment.
+        If amount is not specified, performs a full refund.
+        """
+        payload = {}
+        if amount is not None:
+            payload["amount"] = amount
+        return self._client._request("POST", f"/payments/{payment_id}/refund", json=payload)
+
+
+class WebhooksResource:
+    """Helper utility for webhook validation and parsing."""
+
+    @staticmethod
+    def verify_signature(raw_payload: bytes, signature_header: str, secret: str) -> bool:
+        """
+        Verify incoming webhook X-Fype-Signature header against the configured webhook secret.
+        Returns True if signature is valid, raises SignatureVerificationError otherwise.
+        """
+        from fype.errors import SignatureVerificationError
+
+        if not signature_header:
+            raise SignatureVerificationError("Webhook signature header is missing.")
+
+        mac = hmac.new(
+            secret.encode("utf-8"),
+            msg=raw_payload,
+            digestmod=hashlib.sha256,
+        )
+        expected_signature = mac.hexdigest()
+
+        if not hmac.compare_digest(expected_signature, signature_header):
+            raise SignatureVerificationError("Webhook signature verification failed.")
+
+        return True
+
+
+class SubscriptionsResource:
+    """Helper resource class for managing subscriptions."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def create(
+        self,
+        customer_id: str,
+        plan_id: str,
+        price_id: str,
+        quantity: int = 1,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Creates a subscription and returns its checkout session or mandate details."""
+        payload = {
+            "customer_id": customer_id,
+            "plan_id": plan_id,
+            "price_id": price_id,
+            "quantity": quantity,
+        }
+        if metadata is not None:
+            payload["metadata"] = metadata
+        return self._client._request("POST", "/subscriptions", json=payload)
+
+    def retrieve(self, subscription_id: str) -> dict[str, Any]:
+        """Retrieve details for a specific Fype subscription ID."""
+        return self._client._request("GET", f"/subscriptions/{subscription_id}")
+
+    def list(
+        self,
+        limit: int = 20,
+        cursor: str | None = None,
+        customer_id: str | None = None,
+    ) -> dict[str, Any]:
+        """List paginated subscriptions for the merchant, optionally filtered by customer_id."""
+        params: dict[str, Any] = {"limit": limit}
+        if cursor is not None:
+            params["cursor"] = cursor
+        if customer_id is not None:
+            params["customer_id"] = customer_id
+        return self._client._request("GET", "/subscriptions", params=params)
+
+    def cancel(self, subscription_id: str, cancel_at_period_end: bool = False) -> dict[str, Any]:
+        """Cancels a subscription immediately or at the end of the current period."""
+        params = {"cancel_at_period_end": str(cancel_at_period_end).lower()}
+        return self._client._request(
+            "POST", f"/subscriptions/{subscription_id}/cancel", params=params
+        )
+
+    def pause(self, subscription_id: str) -> dict[str, Any]:
+        """Pauses billing cycles for an active subscription."""
+        return self._client._request("POST", f"/subscriptions/{subscription_id}/pause")
+
+    def resume(self, subscription_id: str) -> dict[str, Any]:
+        """Resumes billing cycles for a paused subscription."""
+        return self._client._request("POST", f"/subscriptions/{subscription_id}/resume")
+
+    def change_plan(self, subscription_id: str, plan_id: str, price_id: str) -> dict[str, Any]:
+        """Upgrades or downgrades a subscription plan/price mid-cycle with proration."""
+        payload = {"plan_id": plan_id, "price_id": price_id}
+        return self._client._request(
+            "POST", f"/subscriptions/{subscription_id}/change-plan", json=payload
+        )
+
+    def get_events(self, subscription_id: str) -> "list[dict[str, Any]]":
+        """Retrieves the complete state transition history for a subscription."""
+        return self._client._request("GET", f"/subscriptions/{subscription_id}/events")
+
+
+class PlansResource:
+    """Helper resource class for plans catalog management."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def create(
+        self,
+        product_id: str,
+        name: str,
+        description: str | None = None,
+        billing_frequency: str = "monthly",
+        billing_interval: int = 1,
+        trial_period_days: int = 0,
+        metadata_json: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Create a new billing plan under a product."""
+        payload = {
+            "name": name,
+            "billing_frequency": billing_frequency,
+            "billing_interval": billing_interval,
+            "trial_period_days": trial_period_days,
+        }
+        if description is not None:
+            payload["description"] = description
+        if metadata_json is not None:
+            payload["metadata_json"] = metadata_json
+        return self._client._request("POST", f"/products/{product_id}/plans", json=payload)
+
+    def retrieve(self, plan_id: str) -> dict[str, Any]:
+        """Retrieve a specific plan configuration."""
+        return self._client._request("GET", f"/plans/{plan_id}")
+
+
+class EntitlementsResource:
+    """Helper resource class for verifying feature gates/entitlements."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def check(self, customer_id: str, entitlement_identifier: str) -> bool:
+        """Verifies if a customer has an active entitlement."""
+        res = self._client._request("GET", f"/subscriptions/customer/{customer_id}/entitlements")
+        active_entitlements = res.get("active_entitlements", [])
+        return entitlement_identifier in active_entitlements
+
+
+class UsageResource:
+    """Helper resource class for reporting metered usage."""
+
+    def __init__(self, client):
+        self._client = client
+
+    def report(
+        self,
+        subscription_id: str,
+        event_type: str,
+        quantity: float,
+        unit: str = "tokens",
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Reports a metered usage event for a subscription."""
+        payload = {
+            "subscription_id": subscription_id,
+            "event_type": event_type,
+            "quantity": quantity,
+            "unit": unit,
+        }
+        if metadata is not None:
+            payload["metadata"] = metadata
+        return self._client._request("POST", "/usage/events", json=payload)

fype_sdk_beta-1.0.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: fype-sdk-beta
+Version: 1.0.0
+Summary: Official Python SDK for Fype Payments Layer
+Author-email: Fype Engineering <engineering@fype.dev>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.23.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
+
+# Fype Python Client SDK
+
+The official Python client library for the [Fype Payments Orchestration Layer](https://fype.dev). Fully type-safe, async-friendly, and lightweight, it simplifies payment creations, refunds, and signed webhook signature verifications under a unified API interface.
+
+---
+
+## Installation
+
+Install the package directly from your local virtual environment:
+```bash
+pip install -e packages/python-sdk
+```
+
+*(Or via PyPI once distributed)*:
+```bash
+pip install fype
+```
+
+---
+
+## Quick Start
+
+### 1. Initialize Client
+Expose your Fype developer API key (use test key for sandbox or live key for production):
+```python
+from fype import Fype
+
+# Initialize the client
+fype = Fype(api_key="fype_test_your_secret_api_key_here")
+```
+
+### 2. Create Hosted Checkout Session
+Initiate a payment order. Fype will automatically contact gateway adapters under the hood and return a public buyer-facing checkout URL:
+```python
+payment = fype.payments.create(
+    amount=25000,                           # Amount in paise (₹250.00 INR)
+    currency="INR",
+    customer_email="buyer@email.com",
+    success_url="https://yourwebsite.com/payment/success",
+    cancel_url="https://yourwebsite.com/payment/cancel",
+    reference_id="order_ref_1092",          # Optional merchant order ID
+    provider="cashfree"                     # Optional: Explicitly choose gateway (razorpay/cashfree)
+)
+
+print(f"Transaction ID: {payment['id']}")
+print(f"Checkout URL: {payment['checkout_url']}")
+```
+
+### 3. Dynamic Redirect Placeholders
+Like Stripe, Fype natively supports dynamic placeholders inside `success_url` and `cancel_url` redirect strings. This allows you to build frictionless, stateless checkout loops (e.g. for login-free purchases). 
+
+Fype will automatically replace these placeholders before redirecting the buyer back to your website:
+* **`{CHECKOUT_SESSION_ID}`**: Replaced with the actual Fype Checkout Session UUID.
+* **`{PAYMENT_ID}`**: Replaced with the actual Fype Payment UUID (useful for direct API validation).
+
+**Example:**
+```python
+payment = fype.payments.create(
+    amount=25000,
+    currency="INR",
+    customer_email="buyer@email.com",
+    success_url="https://yourwebsite.com/payment/success?fype_session_id={PAYMENT_ID}",
+    cancel_url="https://yourwebsite.com/payment/cancel"
+)
+```
+
+---
+
+## 4. Retrieve Payment Details
+Audit checkout session status at any time:
+```python
+payment = fype.payments.retrieve("pay_test_abc123")
+print(f"Current Status: {payment['status']}")  # 'created', 'succeeded', 'failed'
+```
+
+### 4. Issue a Refund
+Perform partial or full refunds for successful payments:
+```python
+# Full Refund (omit amount parameter)
+refund = fype.refunds.create(payment_id="pay_test_abc123")
+
+# Partial Refund (specify amount in paise)
+partial_refund = fype.refunds.create(payment_id="pay_test_abc123", amount=5000)
+```
+
+---
+
+## Webhook Signature Verification
+
+Incoming HTTP webhook events are cryptographically signed by Fype. Always verify signatures against your webhook signing secret (`whsec_...`) to prevent spoofing. The SDK handles constant-time HMAC comparison internally to guard against side-channel timing analysis attacks:
+
+```python
+from fype.errors import SignatureVerificationError
+
+raw_body = request.body()  # Get raw request bytes
+signature = request.headers.get("X-Fype-Signature")
+secret = "whsec_your_webhook_signing_secret"
+
+try:
+    fype.webhooks.verify_signature(raw_body, signature, secret)
+    print("Webhook signature is valid and authentic!")
+    # Proceed to handle events (e.g. payment.succeeded)
+except SignatureVerificationError as e:
+    print(f"Webhook signature mismatch: {e}")
+```
+
+---
+
+## Error Handling
+
+The SDK exposes explicit, catchable exception classes to let you handle failures gracefully:
+
+```python
+from fype.errors import AuthenticationError, InvalidRequestError, ApiConnectionError, FypeError
+
+try:
+    payment = fype.payments.create(...)
+except AuthenticationError:
+    # Handle bad API keys
+    print("Invalid Fype API key.")
+except InvalidRequestError as e:
+    # Handle validation errors (e.g. invalid currency, negative amount)
+    print(f"Request failed validation: {e}")
+except ApiConnectionError:
+    # Handle network timeouts or unreachable hosts
+    print("Connection to Fype server timed out.")
+except FypeError as e:
+    # Handle server-side errors
+    print(f"Fype gateway error: {e}")
+```

fype_sdk_beta-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+fype/__init__.py,sha256=Pr381WnL1dALziXLNQ9wt3Y2lkH62_Y81ECN19pUtv4,336
+fype/client.py,sha256=kpv1_nUP62uk6AVdxwCxiydf1Wa0iYPOzYBrhDPcyKQ,3474
+fype/errors.py,sha256=hS1-iqaJIsGhPzOjzqyLJ1ERA7WFTVQ79t0v65oqjxM,857
+fype/resources.py,sha256=2e4I5jC1F4xr2aK4X2vKMaPe_zEAozemcOz_4Fk4hE8,8472
+fype_sdk_beta-1.0.0.dist-info/METADATA,sha256=6mkpcZHTytwoRbMPkqJVAbgGsOscljk9tc6A-M44dIQ,4907
+fype_sdk_beta-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fype_sdk_beta-1.0.0.dist-info/top_level.txt,sha256=YW9pJqQELeT-cEOCXG2__k6tPyBy-6GGT4WSqfsY2-0,5
+fype_sdk_beta-1.0.0.dist-info/RECORD,,

fype_sdk_beta-1.0.0.dist-info/WHEEL

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

fype_sdk_beta-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fype