xache 5.0.0__py3-none-any.whl

xache/payment/handler.py

@@ -0,0 +1,244 @@
+"""
+Payment Handler for 402 Payment Flow per LLD §2.3
+"""
+
+import asyncio
+from typing import Dict, Optional, Any
+
+
+class PaymentHandler:
+    """Payment handler for 402 payment flow"""
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        self.config = config or {}
+        self.pending_payments: Dict[str, Dict[str, Any]] = {}
+
+    async def handle_payment(
+        self,
+        challenge_id: str,
+        amount: str,
+        chain_hint: str,
+        pay_to: str,
+        description: str,
+    ) -> Dict[str, Any]:
+        """
+        Handle 402 payment challenge
+
+        Args:
+            challenge_id: Payment challenge ID
+            amount: Amount in USD
+            chain_hint: Blockchain hint (solana or base)
+            pay_to: Payment recipient address
+            description: Payment description
+
+        Returns:
+            Payment result with success status
+        """
+        # Check if payment already processed
+        if challenge_id in self.pending_payments:
+            return self.pending_payments[challenge_id]
+
+        try:
+            # Handle payment based on provider type
+            provider_type = self.config.get("type", "manual")
+
+            if provider_type == "manual":
+                result = await self._handle_manual_payment(
+                    challenge_id, amount, chain_hint, pay_to, description
+                )
+            elif provider_type == "coinbase-commerce":
+                result = await self._handle_coinbase_payment(
+                    challenge_id, amount, chain_hint, pay_to, description
+                )
+            else:
+                result = {
+                    "success": False,
+                    "error": f"Unknown payment provider: {provider_type}",
+                }
+
+            # Cache result
+            if result["success"]:
+                self.pending_payments[challenge_id] = result
+
+            return result
+
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+    async def _handle_manual_payment(
+        self,
+        challenge_id: str,
+        amount: str,
+        chain_hint: str,
+        pay_to: str,
+        description: str,
+    ) -> Dict[str, Any]:
+        """Handle manual payment"""
+        print("\n╔════════════════════════════════════════════════════════════╗")
+        print("║            PAYMENT REQUIRED                                 ║")
+        print("╚════════════════════════════════════════════════════════════╝")
+        print("")
+        print(f"Description: {description}")
+        print(f"Amount:      {amount} USD")
+        print(f"Chain:       {chain_hint}")
+        print(f"Pay To:      {pay_to}")
+        print(f"Challenge:   {challenge_id}")
+        print("")
+        print("Please complete the payment manually and then press Enter to continue...")
+        print("(Or press Ctrl+C to cancel)")
+        print("")
+
+        # Wait for user confirmation
+        await asyncio.sleep(2)
+
+        # Return success assuming user completed payment
+        # The server will verify the actual blockchain transaction
+        return {
+            "success": True,
+            "transaction_hash": f"manual-{challenge_id}",
+        }
+
+    async def _handle_coinbase_payment(
+        self,
+        challenge_id: str,
+        amount: str,
+        chain_hint: str,
+        pay_to: str,
+        description: str,
+    ) -> Dict[str, Any]:
+        """Handle Coinbase Commerce payment"""
+        import aiohttp
+
+        api_key = self.config.get("api_key")
+        if not api_key:
+            return {"success": False, "error": "Coinbase Commerce API key not configured"}
+
+        try:
+            # Create charge via Coinbase Commerce API
+            charge = await self._create_coinbase_charge(
+                challenge_id, amount, description, chain_hint
+            )
+
+            print("\n╔════════════════════════════════════════════════════════════╗")
+            print("║            PAYMENT REQUIRED                                 ║")
+            print("╚════════════════════════════════════════════════════════════╝")
+            print("")
+            print(f"Description: {description}")
+            print(f"Amount:      {amount} USD")
+            print(f"Chain:       {chain_hint}")
+            print("")
+            print(f"Payment URL: {charge['hosted_url']}")
+            print("")
+            print("Please complete the payment and wait for confirmation...")
+            print("")
+
+            # Poll for payment confirmation
+            confirmed = await self._poll_coinbase_payment(charge["id"])
+
+            if confirmed:
+                return {
+                    "success": True,
+                    "transaction_hash": charge["id"],
+                }
+            else:
+                return {
+                    "success": False,
+                    "error": "Payment not confirmed",
+                }
+
+        except Exception as e:
+            return {
+                "success": False,
+                "error": f"Coinbase Commerce error: {str(e)}",
+            }
+
+    async def _create_coinbase_charge(
+        self, challenge_id: str, amount: str, description: str, chain_hint: str
+    ) -> Dict[str, Any]:
+        """Create Coinbase Commerce charge"""
+        import aiohttp
+
+        api_key = self.config.get("api_key")
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                "https://api.commerce.coinbase.com/charges",
+                headers={
+                    "Content-Type": "application/json",
+                    "X-CC-Api-Key": api_key,
+                    "X-CC-Version": "2018-03-22",
+                },
+                json={
+                    "name": description,
+                    "description": f"Xache Protocol payment - Challenge: {challenge_id}",
+                    "pricing_type": "fixed_price",
+                    "local_price": {
+                        "amount": amount,
+                        "currency": "USD",
+                    },
+                    "metadata": {
+                        "challengeId": challenge_id,
+                        "chainHint": chain_hint,
+                    },
+                },
+            ) as response:
+                if response.status != 200 and response.status != 201:
+                    error_text = await response.text()
+                    raise Exception(f"Coinbase API error: {error_text}")
+
+                data = await response.json()
+                return data["data"]
+
+    async def _poll_coinbase_payment(
+        self, charge_id: str, max_attempts: int = 60
+    ) -> bool:
+        """Poll Coinbase Commerce for payment confirmation"""
+        import aiohttp
+
+        api_key = self.config.get("api_key")
+
+        for _ in range(max_attempts):
+            try:
+                async with aiohttp.ClientSession() as session:
+                    async with session.get(
+                        f"https://api.commerce.coinbase.com/charges/{charge_id}",
+                        headers={
+                            "X-CC-Api-Key": api_key,
+                            "X-CC-Version": "2018-03-22",
+                        },
+                    ) as response:
+                        if response.status != 200:
+                            await asyncio.sleep(5)
+                            continue
+
+                        data = await response.json()
+                        timeline = data["data"]["timeline"]
+
+                        if timeline:
+                            status = timeline[-1].get("status")
+
+                            if status in ["COMPLETED", "RESOLVED"]:
+                                return True
+
+                            if status in ["EXPIRED", "CANCELED"]:
+                                return False
+
+                        # Wait 5 seconds before next poll
+                        await asyncio.sleep(5)
+
+            except Exception as e:
+                print(f"Error polling payment status: {e}")
+                await asyncio.sleep(5)
+
+        return False
+
+    def mark_payment_complete(self, challenge_id: str, transaction_hash: str):
+        """Mark payment as completed (for testing)"""
+        self.pending_payments[challenge_id] = {
+            "success": True,
+            "transaction_hash": transaction_hash,
+        }
+
+    def clear_cache(self):
+        """Clear payment cache"""
+        self.pending_payments.clear()

xache/services/__init__.py

@@ -0,0 +1,29 @@
+"""Service modules"""
+
+from .identity import IdentityService
+from .memory import MemoryService
+from .collective import CollectiveService
+from .budget import BudgetService
+from .receipts import ReceiptsService
+from .reputation import ReputationService
+from .extraction import ExtractionService
+from .facilitator import FacilitatorService
+from .sessions import SessionService
+from .royalty import RoyaltyService
+from .workspaces import WorkspaceService
+from .owner import OwnerService
+
+__all__ = [
+    "IdentityService",
+    "MemoryService",
+    "CollectiveService",
+    "BudgetService",
+    "ReceiptsService",
+    "ReputationService",
+    "ExtractionService",
+    "FacilitatorService",
+    "SessionService",
+    "RoyaltyService",
+    "WorkspaceService",
+    "OwnerService",
+]

xache/services/budget.py

@@ -0,0 +1,285 @@
+"""Budget Service - Manage monthly spending budgets with alert support per HLD §2.2 Budget Guardian"""
+
+from typing import List, Callable, Union
+from datetime import datetime
+from ..types import BudgetStatus, BudgetAlert, BudgetAlertLevel, BudgetAlertHandler
+
+
+class BudgetService:
+    """Budget service for spending management with proactive alerts"""
+
+    def __init__(self, client):
+        self.client = client
+        self._alert_handlers: List[BudgetAlertHandler] = []
+        self._last_alerted_threshold = 0
+        self.DEFAULT_THRESHOLDS = [50, 80, 100]  # Per HLD §2.2
+
+    async def get_status(self) -> BudgetStatus:
+        """
+        Get current budget status and check alert thresholds (free)
+
+        Example:
+            ```python
+            budget = await client.budget.get_status()
+            print(f"Limit: ${budget.limit_cents / 100}")
+            print(f"Spent: ${budget.spent_cents / 100}")
+            print(f"Usage: {budget.percentage_used:.1f}%")
+            ```
+        """
+        response = await self.client.request("GET", "/v1/budget")
+
+        if not response.success or not response.data:
+            raise Exception("Failed to get budget status")
+
+        data = response.data
+        status = BudgetStatus(
+            limit_cents=data["limitCents"],
+            spent_cents=data["spentCents"],
+            remaining_cents=data["remainingCents"],
+            percentage_used=data["percentageUsed"],
+            current_period=data["currentPeriod"],
+        )
+
+        # Check for budget alerts per HLD §2.2
+        await self._check_and_trigger_alerts(status)
+
+        return status
+
+    async def update_limit(self, limit_cents: int) -> dict:
+        """Update monthly budget limit (free)"""
+        self._validate_limit(limit_cents)
+
+        response = await self.client.request(
+            "PUT",
+            "/v1/budget",
+            {"limitCents": limit_cents},
+        )
+
+        if not response.success or not response.data:
+            raise Exception("Failed to update budget limit")
+
+        return response.data
+
+    async def can_afford(self, operation_cost_cents: int) -> bool:
+        """Check if operation is within budget"""
+        status = await self.get_status()
+        return status.remaining_cents >= operation_cost_cents
+
+    def on_alert(self, handler: BudgetAlertHandler):
+        """
+        Register an alert handler for budget threshold notifications
+        Per PRD FR-021: Usage Alerts at 50%, 80%, 100%
+
+        Args:
+            handler: Callback function to handle budget alerts
+
+        Example:
+            ```python
+            def handle_alert(alert: BudgetAlert):
+                print(f"Budget Alert: {alert.level.value}")
+                print(f"  Message: {alert.message}")
+                print(f"  Usage: {alert.percentage_used:.1f}%")
+                print(f"  Remaining: ${alert.remaining_cents / 100}")
+
+                if alert.level == BudgetAlertLevel.CRITICAL_100:
+                    # Take action - pause operations, notify admin, etc.
+                    print("CRITICAL: Budget limit reached!")
+
+            client.budget.on_alert(handle_alert)
+            ```
+        """
+        self._alert_handlers.append(handler)
+
+    async def get_active_alerts(self) -> List[BudgetAlert]:
+        """
+        Get all currently active budget alerts
+
+        Returns:
+            List of active alerts based on current budget status
+
+        Example:
+            ```python
+            active_alerts = await client.budget.get_active_alerts()
+            if active_alerts:
+                print(f"{len(active_alerts)} active budget alerts")
+                for alert in active_alerts:
+                    print(f"- {alert.level.value}: {alert.message}")
+            ```
+        """
+        status = await self.get_status()
+        return self._check_thresholds(status)
+
+    async def is_threshold_crossed(self, threshold: float) -> bool:
+        """
+        Check if a specific threshold has been crossed
+
+        Args:
+            threshold: Threshold percentage to check (50, 80, or 100)
+
+        Returns:
+            True if threshold has been crossed
+
+        Example:
+            ```python
+            if await client.budget.is_threshold_crossed(80):
+                print("80% budget threshold crossed!")
+            ```
+        """
+        status = await self.get_status()
+        return status.percentage_used >= threshold
+
+    def _check_thresholds(self, status: BudgetStatus) -> List[BudgetAlert]:
+        """Check budget thresholds and return active alerts"""
+        alerts = []
+
+        for threshold in self.DEFAULT_THRESHOLDS:
+            if status.percentage_used >= threshold:
+                alerts.append(self._create_alert(status, threshold))
+
+        return alerts
+
+    async def _check_and_trigger_alerts(self, status: BudgetStatus):
+        """Check thresholds and trigger alert handlers"""
+        # Find the highest crossed threshold
+        highest_crossed_threshold = 0
+        for threshold in self.DEFAULT_THRESHOLDS:
+            if status.percentage_used >= threshold:
+                highest_crossed_threshold = threshold
+
+        # Only trigger if we've crossed a new threshold
+        if highest_crossed_threshold > self._last_alerted_threshold:
+            alert = self._create_alert(status, highest_crossed_threshold)
+
+            # Trigger all registered handlers
+            for handler in self._alert_handlers:
+                try:
+                    # Handle both sync and async handlers
+                    import inspect
+                    if inspect.iscoroutinefunction(handler):
+                        await handler(alert)
+                    else:
+                        handler(alert)
+                except Exception as e:
+                    # Log error but don't throw - allow other handlers to execute
+                    if self.client.debug:
+                        print(f"Budget alert handler error: {e}")
+
+            # Update last alerted threshold
+            self._last_alerted_threshold = highest_crossed_threshold
+
+    def _create_alert(self, status: BudgetStatus, threshold: float) -> BudgetAlert:
+        """Create a budget alert object"""
+        if threshold >= 100:
+            level = BudgetAlertLevel.CRITICAL_100
+            message = "CRITICAL: Monthly budget limit reached (100%). Operations may be throttled."
+        elif threshold >= 80:
+            level = BudgetAlertLevel.WARN_80
+            message = "WARNING: Approaching budget limit (80%). Consider reviewing spending or increasing limit."
+        else:
+            level = BudgetAlertLevel.WARN_50
+            message = "NOTICE: Half of monthly budget consumed (50%). Monitor spending closely."
+
+        return BudgetAlert(
+            level=level,
+            threshold=threshold,
+            percentage_used=status.percentage_used,
+            spent_cents=status.spent_cents,
+            limit_cents=status.limit_cents,
+            remaining_cents=status.remaining_cents,
+            message=message,
+            timestamp=datetime.utcnow().isoformat() + "Z",
+        )
+
+    def _validate_limit(self, limit_cents: int):
+        """Validate budget limit"""
+        if not isinstance(limit_cents, int):
+            raise ValueError("limit_cents must be an integer")
+        if limit_cents < 0:
+            raise ValueError("limit_cents must be non-negative")
+        if limit_cents > 1000000:
+            raise ValueError("limit_cents cannot exceed 1,000,000 ($10,000)")
+
+    # ========== Fleet Budget (Owner Only) ==========
+
+    async def get_fleet_status(self) -> dict:
+        """
+        Get fleet budget status for authenticated owner.
+        Returns aggregated spending across all owned agents.
+        Requires owner authentication (did:owner:...)
+
+        Returns:
+            Fleet budget status with per-agent breakdown
+
+        Example:
+            ```python
+            fleet = await client.budget.get_fleet_status()
+
+            print(f"Fleet Cap: ${fleet['fleet_budget_cap_usd']}")
+            print(f"Total Spent: ${fleet['total_spent_usd']}")
+            print(f"Usage: {fleet['percentage_used']:.1f}%")
+
+            for agent in fleet['agents']:
+                print(f"  {agent['name']}: ${agent['spent_cents'] / 100}")
+            ```
+        """
+        response = await self.client.request("GET", "/v1/budget/fleet")
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to get fleet budget status")
+                if response.error
+                else "Failed to get fleet budget status"
+            )
+
+        data = response.data
+        return {
+            "owner_did": data["ownerDID"],
+            "fleet_budget_cap_cents": data.get("fleetBudgetCapCents"),
+            "fleet_budget_cap_usd": data.get("fleetBudgetCapUSD"),
+            "total_spent_cents": data["totalSpentCents"],
+            "total_spent_usd": data["totalSpentUSD"],
+            "remaining_cents": data.get("remainingCents"),
+            "remaining_usd": data.get("remainingUSD"),
+            "percentage_used": data.get("percentageUsed"),
+            "agent_count": data["agentCount"],
+            "total_agent_limits_cents": data["totalAgentLimitsCents"],
+            "agents": data.get("agents", []),
+        }
+
+    async def update_fleet_cap(self, fleet_cap_cents: int | None) -> dict:
+        """
+        Update fleet budget cap for authenticated owner.
+        Set to None for unlimited.
+        Requires owner authentication (did:owner:...)
+
+        Args:
+            fleet_cap_cents: Budget cap in cents, or None for unlimited
+
+        Returns:
+            Update confirmation
+
+        Example:
+            ```python
+            # Set fleet cap to $500
+            result = await client.budget.update_fleet_cap(50000)
+
+            # Remove fleet cap (unlimited)
+            result = await client.budget.update_fleet_cap(None)
+            ```
+        """
+        if fleet_cap_cents is not None:
+            if not isinstance(fleet_cap_cents, int) or fleet_cap_cents < 0:
+                raise ValueError("fleet_cap_cents must be a positive integer or None")
+
+        response = await self.client.request(
+            "PUT", "/v1/budget/fleet", {"fleetCapCents": fleet_cap_cents}
+        )
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to update fleet budget cap")
+                if response.error
+                else "Failed to update fleet budget cap"
+            )
+
+        return response.data