xache 5.0.0__py3-none-any.whl

xache/services/royalty.py

@@ -0,0 +1,290 @@
+"""
+Royalty Service - Revenue tracking and earnings management
+"""
+
+from typing import List, Dict, Optional
+from dataclasses import dataclass
+from ..types import DID
+
+
+@dataclass
+class HeuristicRevenue:
+    """Revenue for a single heuristic"""
+    heuristic_id: str
+    pattern: str
+    domain: str
+    earned_usd: str
+    usage_count: int
+
+
+@dataclass
+class MonthlyEarning:
+    """Monthly earnings"""
+    month: str
+    earned_usd: str
+
+
+@dataclass
+class RevenueStats:
+    """Revenue statistics for an agent"""
+    agent_did: DID
+    total_earned_usd: str
+    heuristic_count: int
+    top_heuristics: List[HeuristicRevenue]
+    earnings_by_domain: Dict[str, str]
+    monthly_earnings: List[MonthlyEarning]
+
+
+@dataclass
+class PendingPayout:
+    """Pending payout information"""
+    heuristic_id: str
+    heuristic_key: str
+    pending_amount: str
+    last_query_at: str
+    query_count: int
+
+
+@dataclass
+class PlatformRevenue:
+    """Platform-wide revenue statistics"""
+    total_revenue: str
+    total_agents: int
+    total_heuristics: int
+    total_queries: int
+    average_revenue_per_agent: str
+
+
+@dataclass
+class TopEarner:
+    """Top earner information"""
+    rank: int
+    agent_did: DID
+    total_earned_usd: str
+    heuristic_count: int
+    reputation_score: float
+
+
+class RoyaltyService:
+    """
+    Royalty service for revenue tracking and earnings management
+
+    Track royalties earned from heuristic contributions and pending payouts.
+    """
+
+    def __init__(self, client):
+        self.client = client
+
+    async def get_revenue_stats(self, agent_did: DID) -> RevenueStats:
+        """
+        Get revenue statistics for an agent
+
+        Args:
+            agent_did: Agent DID to get stats for
+
+        Returns:
+            Revenue statistics
+
+        Example:
+            ```python
+            stats = await client.royalty.get_revenue_stats("did:agent:evm:0x1234...")
+
+            print(f"Total earned: ${stats.total_earned_usd}")
+            print(f"Heuristics: {stats.heuristic_count}")
+
+            for h in stats.top_heuristics:
+                print(f"  {h.domain}: ${h.earned_usd} ({h.usage_count} uses)")
+            ```
+        """
+        from urllib.parse import quote
+
+        response = await self.client.request(
+            "GET", f"/v1/royalty/revenue/{quote(agent_did, safe='')}"
+        )
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to get revenue stats")
+                if response.error
+                else "Failed to get revenue stats"
+            )
+
+        data = response.data
+        return RevenueStats(
+            agent_did=data["agentDID"],
+            total_earned_usd=data["totalEarnedUSD"],
+            heuristic_count=data["heuristicCount"],
+            top_heuristics=[
+                HeuristicRevenue(
+                    heuristic_id=h["heuristicId"],
+                    pattern=h["pattern"],
+                    domain=h["domain"],
+                    earned_usd=h["earnedUSD"],
+                    usage_count=h["usageCount"],
+                )
+                for h in data.get("topHeuristics", [])
+            ],
+            earnings_by_domain=data.get("earningsByDomain", {}),
+            monthly_earnings=[
+                MonthlyEarning(month=m["month"], earned_usd=m["earnedUSD"])
+                for m in data.get("monthlyEarnings", [])
+            ],
+        )
+
+    async def get_pending_payouts(self, agent_did: DID) -> Dict:
+        """
+        Get pending payouts for an agent
+
+        Args:
+            agent_did: Agent DID
+
+        Returns:
+            Pending payouts with total amount
+
+        Example:
+            ```python
+            result = await client.royalty.get_pending_payouts("did:agent:evm:0x1234...")
+
+            print(f"Total pending: ${result['total_pending_amount']}")
+            for p in result['pending_payouts']:
+                print(f"  {p.heuristic_key}: ${p.pending_amount}")
+            ```
+        """
+        from urllib.parse import quote
+
+        response = await self.client.request(
+            "GET", f"/v1/royalty/payouts/{quote(agent_did, safe='')}"
+        )
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to get pending payouts")
+                if response.error
+                else "Failed to get pending payouts"
+            )
+
+        data = response.data
+        return {
+            "agent_did": data["agentDID"],
+            "pending_payouts": [
+                PendingPayout(
+                    heuristic_id=p["heuristicId"],
+                    heuristic_key=p["heuristicKey"],
+                    pending_amount=p["pendingAmount"],
+                    last_query_at=p["lastQueryAt"],
+                    query_count=p["queryCount"],
+                )
+                for p in data.get("pendingPayouts", [])
+            ],
+            "total_pending_count": data.get("totalPendingCount", 0),
+            "total_pending_amount": data.get("totalPendingAmount", "0"),
+        }
+
+    async def get_platform_revenue(self) -> PlatformRevenue:
+        """
+        Get platform-wide revenue statistics
+
+        Returns:
+            Platform revenue statistics
+
+        Example:
+            ```python
+            platform = await client.royalty.get_platform_revenue()
+
+            print(f"Platform revenue: ${platform.total_revenue}")
+            print(f"Active agents: {platform.total_agents}")
+            print(f"Total heuristics: {platform.total_heuristics}")
+            ```
+        """
+        response = await self.client.request("GET", "/v1/royalty/platform")
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to get platform revenue")
+                if response.error
+                else "Failed to get platform revenue"
+            )
+
+        data = response.data
+        return PlatformRevenue(
+            total_revenue=data["totalRevenue"],
+            total_agents=data["totalAgents"],
+            total_heuristics=data["totalHeuristics"],
+            total_queries=data["totalQueries"],
+            average_revenue_per_agent=data["averageRevenuePerAgent"],
+        )
+
+    async def get_top_earners(self, limit: int = 20) -> Dict:
+        """
+        Get top earning agents
+
+        Args:
+            limit: Number of top earners to return (default: 20)
+
+        Returns:
+            List of top earners
+
+        Example:
+            ```python
+            result = await client.royalty.get_top_earners(10)
+
+            for earner in result['top_earners']:
+                print(f"#{earner.rank} {earner.agent_did}")
+                print(f"   Earned: ${earner.total_earned_usd}")
+            ```
+        """
+        response = await self.client.request(
+            "GET", f"/v1/royalty/top-earners?limit={limit}"
+        )
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to get top earners")
+                if response.error
+                else "Failed to get top earners"
+            )
+
+        data = response.data
+        return {
+            "top_earners": [
+                TopEarner(
+                    rank=e["rank"],
+                    agent_did=e["agentDID"],
+                    total_earned_usd=e["totalEarnedUSD"],
+                    heuristic_count=e["heuristicCount"],
+                    reputation_score=e["reputationScore"],
+                )
+                for e in data.get("topEarners", [])
+            ],
+            "total": data.get("total", 0),
+        }
+
+    async def get_my_revenue(self) -> RevenueStats:
+        """
+        Get revenue stats for the current authenticated agent
+
+        Returns:
+            Revenue statistics for authenticated agent
+
+        Example:
+            ```python
+            my_stats = await client.royalty.get_my_revenue()
+            print(f"My earnings: ${my_stats.total_earned_usd}")
+            ```
+        """
+        return await self.get_revenue_stats(self.client.did)
+
+    async def get_my_pending_payouts(self) -> Dict:
+        """
+        Get pending payouts for the current authenticated agent
+
+        Returns:
+            Pending payouts for authenticated agent
+
+        Example:
+            ```python
+            result = await client.royalty.get_my_pending_payouts()
+            print(f"Pending: ${result['total_pending_amount']}")
+            ```
+        """
+        return await self.get_pending_payouts(self.client.did)

xache/services/sessions.py

@@ -0,0 +1,268 @@
+"""
+Session Service - x402 v2 wallet session management
+"""
+
+from typing import Optional, List
+from dataclasses import dataclass
+
+
+@dataclass
+class WalletSession:
+    """Wallet session for pre-authorized payments"""
+    session_id: str
+    wallet_address: str
+    chain: str
+    network: str
+    created_at: str
+    expires_at: str
+    max_amount: str
+    spent_amount: str
+    remaining_amount: str
+    scope: List[str]
+    active: bool
+
+
+@dataclass
+class SessionValidation:
+    """Session validation result"""
+    valid: bool
+    session_id: str
+    has_budget: bool
+    remaining_amount: str
+    reason: Optional[str] = None
+
+
+@dataclass
+class CreateSessionOptions:
+    """Options for creating a session"""
+    wallet_address: str
+    chain: str
+    network: str
+    duration_seconds: int = 3600  # 1 hour default
+    max_amount: Optional[str] = None
+    scope: Optional[List[str]] = None
+
+
+class SessionService:
+    """
+    Session service for x402 v2 wallet session management
+
+    Sessions allow pre-authorized payments within a budget and time limit,
+    reducing the need for per-request wallet signatures.
+    """
+
+    def __init__(self, client):
+        self.client = client
+
+    async def create(self, options: CreateSessionOptions) -> WalletSession:
+        """
+        Create a new wallet session for pre-authorized payments
+
+        Args:
+            options: Session creation options
+
+        Returns:
+            Created wallet session
+
+        Example:
+            ```python
+            from xache.services.sessions import CreateSessionOptions
+
+            session = await client.sessions.create(CreateSessionOptions(
+                wallet_address="0x1234...",
+                chain="evm",
+                network="base-sepolia",
+                duration_seconds=3600,  # 1 hour
+                max_amount="10000000",  # 10 USDC
+                scope=["memory:store", "memory:retrieve"]
+            ))
+
+            print(f"Session ID: {session.session_id}")
+            print(f"Expires: {session.expires_at}")
+            ```
+        """
+        body = {
+            "walletAddress": options.wallet_address,
+            "chain": options.chain,
+            "network": options.network,
+            "durationSeconds": options.duration_seconds,
+        }
+
+        if options.max_amount:
+            body["maxAmount"] = options.max_amount
+        if options.scope:
+            body["scope"] = options.scope
+
+        response = await self.client.request("POST", "/v1/sessions", body)
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to create session")
+                if response.error
+                else "Failed to create session"
+            )
+
+        return self._parse_session(response.data.get("session", response.data))
+
+    async def get(self, session_id: str) -> Optional[WalletSession]:
+        """
+        Get session by ID
+
+        Args:
+            session_id: Session identifier
+
+        Returns:
+            Wallet session or None if not found
+
+        Example:
+            ```python
+            session = await client.sessions.get("sess_abc123")
+            if session:
+                print(f"Remaining: {session.remaining_amount}")
+            ```
+        """
+        response = await self.client.request("GET", f"/v1/sessions/{session_id}")
+
+        if not response.success:
+            if response.error and response.error.get("code") == "NOT_FOUND":
+                return None
+            raise Exception(
+                response.error.get("message", "Failed to get session")
+                if response.error
+                else "Failed to get session"
+            )
+
+        if not response.data:
+            return None
+
+        return self._parse_session(response.data.get("session", response.data))
+
+    async def validate(
+        self, session_id: str, amount: str, scope: Optional[str] = None
+    ) -> SessionValidation:
+        """
+        Validate session for a specific operation
+
+        Args:
+            session_id: Session identifier
+            amount: Amount to validate (in smallest unit, e.g., microcents)
+            scope: Operation scope to validate (e.g., "memory:store")
+
+        Returns:
+            Validation result
+
+        Example:
+            ```python
+            validation = await client.sessions.validate(
+                "sess_abc123",
+                amount="1000",
+                scope="memory:store"
+            )
+
+            if validation.valid and validation.has_budget:
+                print("Session is valid for this operation")
+            else:
+                print(f"Invalid: {validation.reason}")
+            ```
+        """
+        body = {"amount": amount}
+        if scope:
+            body["scope"] = scope
+
+        response = await self.client.request(
+            "POST", f"/v1/sessions/{session_id}/validate", body
+        )
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to validate session")
+                if response.error
+                else "Failed to validate session"
+            )
+
+        data = response.data
+        return SessionValidation(
+            valid=data.get("valid", False),
+            session_id=data.get("sessionId", session_id),
+            has_budget=data.get("hasBudget", False),
+            remaining_amount=data.get("remainingAmount", "0"),
+            reason=data.get("reason"),
+        )
+
+    async def revoke(self, session_id: str) -> bool:
+        """
+        Revoke a session
+
+        Args:
+            session_id: Session identifier
+
+        Returns:
+            True if successfully revoked
+
+        Example:
+            ```python
+            revoked = await client.sessions.revoke("sess_abc123")
+            if revoked:
+                print("Session revoked successfully")
+            ```
+        """
+        response = await self.client.request("DELETE", f"/v1/sessions/{session_id}")
+
+        if not response.success:
+            raise Exception(
+                response.error.get("message", "Failed to revoke session")
+                if response.error
+                else "Failed to revoke session"
+            )
+
+        return True
+
+    async def list_active(self, wallet_address: Optional[str] = None) -> List[WalletSession]:
+        """
+        List active sessions
+
+        Args:
+            wallet_address: Optional wallet address to filter by
+
+        Returns:
+            List of active sessions
+
+        Example:
+            ```python
+            sessions = await client.sessions.list_active()
+            print(f"Active sessions: {len(sessions)}")
+            for s in sessions:
+                print(f"  {s.session_id}: expires {s.expires_at}")
+            ```
+        """
+        endpoint = "/v1/sessions"
+        if wallet_address:
+            endpoint += f"?walletAddress={wallet_address}"
+
+        response = await self.client.request("GET", endpoint)
+
+        if not response.success or not response.data:
+            raise Exception(
+                response.error.get("message", "Failed to list sessions")
+                if response.error
+                else "Failed to list sessions"
+            )
+
+        sessions_data = response.data.get("sessions", [])
+        return [self._parse_session(s) for s in sessions_data]
+
+    def _parse_session(self, data: dict) -> WalletSession:
+        """Parse session data into WalletSession object"""
+        return WalletSession(
+            session_id=data["sessionId"],
+            wallet_address=data["walletAddress"],
+            chain=data["chain"],
+            network=data["network"],
+            created_at=data["createdAt"],
+            expires_at=data["expiresAt"],
+            max_amount=data.get("maxAmount", "0"),
+            spent_amount=data.get("spentAmount", "0"),
+            remaining_amount=data.get("remainingAmount", "0"),
+            scope=data.get("scope", []),
+            active=data.get("active", True),
+        )