subscription-sdk 1.0.0__tar.gz

subscription_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: subscription-sdk
+Version: 1.0.0
+Summary: Python Client SDK for Subscription Platform
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: urllib3>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: flask>=2.0.0; extra == "dev"
+Requires-Dist: fastapi>=0.80.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Requires-Dist: uvicorn>=0.15.0; extra == "dev"
+
+# subscription-sdk-python
+
+Python SDK for the Subscription and Entitlements Platform.
+
+## Installation
+
+```bash
+pip install subscription-sdk
+```
+
+## Middleware Adapters
+
+### Flask
+
+```python
+from flask import Flask, request, jsonify
+from subscription_sdk.adapters.flask_adapter import subscription_flask
+
+app = Flask(__name__)
+
+# Apply Flask Middleware
+subscription_flask(
+    app,
+    api_key="sub_live_...",
+    base_url="https://api.infosub.io",
+    get_org_id=lambda: request.headers.get("X-Org-Id")
+)
+
+@app.route("/api/v1/employees", methods=["GET"])
+def get_employees():
+    return jsonify({"data": []}), 200
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from subscription_sdk.adapters.fastapi_adapter import SubscriptionMiddleware
+
+app = FastAPI()
+
+# Apply FastAPI Middleware
+app.add_middleware(
+    SubscriptionMiddleware,
+    api_key="sub_live_...",
+    base_url="https://api.infosub.io",
+    get_org_id=lambda req: req.headers.get("x-org-id")
+)
+
+@app.get("/api/v1/employees")
+def get_employees(request: Request):
+    return {"data": []}
+```
+
+## Manual Client Usage
+
+```python
+from subscription_sdk import SubscriptionClient
+
+client = SubscriptionClient(api_key="sub_live_...", base_url="https://api.infosub.io")
+client.start()  # Starts background poller thread
+
+mapping = client.match_route("GET", "/api/v1/employees")
+if mapping:
+    check = client.check_entitlement(
+        organization_external_id="tenant-acme",
+        resource_mapping_id=mapping.id,
+        quantity=1.0
+    )
+    if check.allowed:
+        try:
+            # Execute business logic...
+            
+            client.commit_reservation(check.reservationId)
+        except Exception:
+            client.cancel_reservation(check.reservationId)
+```
+
+Alternatively, you can simplify the manual transaction pattern using `.execute(...)`, which handles the check-reserve-commit-cancel flow automatically.
+
+**Basic Example:**
+```python
+# The execute method takes a callback function to run
+result = client.execute(
+    organization_id="tenant-acme",
+    resource_mapping_id=mapping.id,
+    callback=lambda: save_employee(employee),
+    quantity=1.0
+)
+```
+
+**Flask / FastAPI Route Handler Example:**
+```python
+@app.route("/employees-manual", methods=["POST"])
+def create_employee_manual():
+    org_id = request.headers.get("X-Org-Id") or request.args.get("orgId")
+    mapping = client.match_route("POST", "/employees")
+    
+    if not mapping:
+        return jsonify({"error": "Mapping not found"}), 500
+        
+    try:
+        result = client.execute(
+            organization_id=org_id,
+            resource_mapping_id=mapping.id,
+            quantity=1.0,
+            callback=lambda: {
+                "status": "success",
+                "message": "Employee created successfully via manual execute wrapper."
+            }
+        )
+        return jsonify(result), 200
+    except PermissionError as err:
+        # Throws PermissionError if entitlement check is denied (check.allowed is False)
+        return jsonify({"status": "error", "message": str(err)}), 403
+    except Exception as err:
+        return jsonify({"status": "error", "message": str(err)}), 500
+```
+

subscription_sdk-1.0.0/README.md

@@ -0,0 +1,119 @@
+# subscription-sdk-python
+
+Python SDK for the Subscription and Entitlements Platform.
+
+## Installation
+
+```bash
+pip install subscription-sdk
+```
+
+## Middleware Adapters
+
+### Flask
+
+```python
+from flask import Flask, request, jsonify
+from subscription_sdk.adapters.flask_adapter import subscription_flask
+
+app = Flask(__name__)
+
+# Apply Flask Middleware
+subscription_flask(
+    app,
+    api_key="sub_live_...",
+    base_url="https://api.infosub.io",
+    get_org_id=lambda: request.headers.get("X-Org-Id")
+)
+
+@app.route("/api/v1/employees", methods=["GET"])
+def get_employees():
+    return jsonify({"data": []}), 200
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI, Request
+from subscription_sdk.adapters.fastapi_adapter import SubscriptionMiddleware
+
+app = FastAPI()
+
+# Apply FastAPI Middleware
+app.add_middleware(
+    SubscriptionMiddleware,
+    api_key="sub_live_...",
+    base_url="https://api.infosub.io",
+    get_org_id=lambda req: req.headers.get("x-org-id")
+)
+
+@app.get("/api/v1/employees")
+def get_employees(request: Request):
+    return {"data": []}
+```
+
+## Manual Client Usage
+
+```python
+from subscription_sdk import SubscriptionClient
+
+client = SubscriptionClient(api_key="sub_live_...", base_url="https://api.infosub.io")
+client.start()  # Starts background poller thread
+
+mapping = client.match_route("GET", "/api/v1/employees")
+if mapping:
+    check = client.check_entitlement(
+        organization_external_id="tenant-acme",
+        resource_mapping_id=mapping.id,
+        quantity=1.0
+    )
+    if check.allowed:
+        try:
+            # Execute business logic...
+            
+            client.commit_reservation(check.reservationId)
+        except Exception:
+            client.cancel_reservation(check.reservationId)
+```
+
+Alternatively, you can simplify the manual transaction pattern using `.execute(...)`, which handles the check-reserve-commit-cancel flow automatically.
+
+**Basic Example:**
+```python
+# The execute method takes a callback function to run
+result = client.execute(
+    organization_id="tenant-acme",
+    resource_mapping_id=mapping.id,
+    callback=lambda: save_employee(employee),
+    quantity=1.0
+)
+```
+
+**Flask / FastAPI Route Handler Example:**
+```python
+@app.route("/employees-manual", methods=["POST"])
+def create_employee_manual():
+    org_id = request.headers.get("X-Org-Id") or request.args.get("orgId")
+    mapping = client.match_route("POST", "/employees")
+    
+    if not mapping:
+        return jsonify({"error": "Mapping not found"}), 500
+        
+    try:
+        result = client.execute(
+            organization_id=org_id,
+            resource_mapping_id=mapping.id,
+            quantity=1.0,
+            callback=lambda: {
+                "status": "success",
+                "message": "Employee created successfully via manual execute wrapper."
+            }
+        )
+        return jsonify(result), 200
+    except PermissionError as err:
+        # Throws PermissionError if entitlement check is denied (check.allowed is False)
+        return jsonify({"status": "error", "message": str(err)}), 403
+    except Exception as err:
+        return jsonify({"status": "error", "message": str(err)}), 500
+```
+

subscription_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "subscription-sdk"
+version = "1.0.0"
+description = "Python Client SDK for Subscription Platform"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "urllib3>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.20.0",
+    "responses>=0.23.0",
+    "flask>=2.0.0",
+    "fastapi>=0.80.0",
+    "httpx>=0.24.0",
+    "uvicorn>=0.15.0",
+]

subscription_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

subscription_sdk-1.0.0/subscription_sdk/__init__.py

@@ -0,0 +1,24 @@
+from .types import Mapping, SdkConfig, EntitlementCheckResponse
+from .config_manager import ConfigManager
+from .poller import Poller
+from .route_matcher import RouteMatcher
+from .client import SubscriptionClient
+
+# Export flask and fastapi adapters dynamically to avoid hard dependencies if users don't have those libraries installed
+def get_flask_adapter():
+    from .adapters.flask_adapter import subscription_flask
+    return subscription_flask
+
+def get_fastapi_middleware():
+    from .adapters.fastapi_adapter import SubscriptionMiddleware
+    return SubscriptionMiddleware
+
+__all__ = [
+    'Mapping',
+    'SdkConfig',
+    'EntitlementCheckResponse',
+    'ConfigManager',
+    'Poller',
+    'RouteMatcher',
+    'SubscriptionClient',
+]

subscription_sdk-1.0.0/subscription_sdk/adapters/fastapi_adapter.py

@@ -0,0 +1,105 @@
+import inspect
+import os
+from typing import Callable, Optional, Union, Awaitable
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response, JSONResponse
+from ..client import SubscriptionClient
+
+class SubscriptionMiddleware(BaseHTTPMiddleware):
+    def __init__(
+        self,
+        app,
+        client: Optional[SubscriptionClient] = None,
+        get_org_id: Optional[Union[Callable[[Request], str], Callable[[Request], Awaitable[str]]]] = None,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None
+    ):
+        super().__init__(app)
+        if not get_org_id:
+            raise ValueError("get_org_id callback is required")
+        
+        self.get_org_id = get_org_id
+        
+        if client is None:
+            key = api_key or os.environ.get("SUBSCRIPTION_API_KEY")
+            url = base_url or os.environ.get("SUBSCRIPTION_BASE_URL")
+            if not key or not url:
+                raise ValueError("Subscription API Key and Base URL are required when client is not provided")
+            self.client = SubscriptionClient(key, url)
+            self.client.start()
+        else:
+            self.client = client
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        path = request.url.path
+        method = request.method
+        
+        mapping = self.client.match_route(method, path)
+        if not mapping:
+            return await call_next(request)
+
+        # Resolve org identifier
+        if inspect.iscoroutinefunction(self.get_org_id):
+            org_id = await self.get_org_id(request)
+        else:
+            org_id = self.get_org_id(request)
+
+        if not org_id:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "title": "Organization Identity Missing",
+                    "status": 400,
+                    "detail": "No organization external identifier resolved for the matching route."
+                }
+            )
+
+        try:
+            check_result = self.client.check_entitlement(org_id, mapping.id, 1.0)
+        except Exception as e:
+            return JSONResponse(
+                status_code=500,
+                content={
+                    "title": "Entitlement Resolution Error",
+                    "status": 500,
+                    "detail": str(e)
+                }
+            )
+
+        if not check_result.allowed:
+            detail = check_result.detail or f"Subscription limit reached or feature not enabled: {check_result.featureCode}"
+            code = check_result.code or "ENTITLEMENT_DENIED"
+            return JSONResponse(
+                status_code=403,
+                content={
+                    "title": "Entitlement Denied",
+                    "status": 403,
+                    "detail": detail,
+                    "code": code
+                }
+            )
+
+        # Attach reservation context to request state
+        request.state.subscription_reservation_id = check_result.reservationId
+
+        success = False
+        try:
+            response = await call_next(request)
+            if response.status_code < 400:
+                success = True
+            return response
+        finally:
+            reservation_id = getattr(request.state, 'subscription_reservation_id', None)
+            if reservation_id:
+                try:
+                    if success:
+                        self.client.commit_reservation(reservation_id)
+                    else:
+                        self.client.cancel_reservation(reservation_id)
+                except Exception as e:
+                    import sys
+                    print(
+                        f"[SubscriptionSDK] Failed to {'commit' if success else 'cancel'} reservation {reservation_id}: {e}",
+                        file=sys.stderr
+                    )

subscription_sdk-1.0.0/subscription_sdk/adapters/flask_adapter.py

@@ -0,0 +1,84 @@
+import os
+from typing import Callable, Optional
+from flask import request, jsonify, g
+from ..client import SubscriptionClient
+
+def subscription_flask(
+    app,
+    client: Optional[SubscriptionClient] = None,
+    get_org_id: Optional[Callable[[], Optional[str]]] = None,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None
+) -> SubscriptionClient:
+    
+    if not get_org_id:
+        raise ValueError("get_org_id callback is required")
+        
+    if client is None:
+        key = api_key or os.environ.get("SUBSCRIPTION_API_KEY")
+        url = base_url or os.environ.get("SUBSCRIPTION_BASE_URL")
+        if not key or not url:
+            raise ValueError("Subscription API Key and Base URL are required when client is not provided")
+        client = SubscriptionClient(key, url)
+        client.start()
+
+    @app.before_request
+    def before_req():
+        path = request.path
+        method = request.method
+        
+        mapping = client.match_route(method, path)
+        if not mapping:
+            return None  # Bypass
+            
+        org_id = get_org_id()
+        if not org_id:
+            return jsonify({
+                "title": "Organization Identity Missing",
+                "status": 400,
+                "detail": "No organization external identifier resolved for the matching route."
+            }), 400
+            
+        try:
+            check_result = client.check_entitlement(org_id, mapping.id, 1.0)
+        except Exception as e:
+            return jsonify({
+                "title": "Entitlement Resolution Error",
+                "status": 500,
+                "detail": str(e)
+            }), 500
+
+        if not check_result.allowed:
+            detail = check_result.detail or f"Subscription limit reached or feature not enabled: {check_result.featureCode}"
+            code = check_result.code or "ENTITLEMENT_DENIED"
+            return jsonify({
+                "title": "Entitlement Denied",
+                "status": 403,
+                "detail": detail,
+                "code": code
+            }), 403
+
+        # Attach reservation context to request state
+        g.subscription_reservation_id = check_result.reservationId
+        request.subscription_reservation_id = check_result.reservationId
+        return None
+
+    @app.after_request
+    def after_req(response):
+        reservation_id = getattr(g, 'subscription_reservation_id', None)
+        if reservation_id:
+            success = response.status_code < 400
+            try:
+                if success:
+                    client.commit_reservation(reservation_id)
+                else:
+                    client.cancel_reservation(reservation_id)
+            except Exception as e:
+                import sys
+                print(
+                    f"[SubscriptionSDK] Failed to {'commit' if success else 'cancel'} reservation {reservation_id}: {e}",
+                    file=sys.stderr
+                )
+        return response
+
+    return client