agentspay 0.1.0 → 0.2.0

package/sdk-python/agentspay/services.py

@@ -0,0 +1,198 @@
+"""Service operations for AgentPay SDK"""
+
+from typing import Optional, List
+import requests
+from .types import Service, ServiceQuery
+from .exceptions import ServiceError
+
+
+class ServiceOperations:
+    """Handles service registration and discovery"""
+    
+    def __init__(self, base_url: str, api_key: Optional[str] = None):
+        self.base_url = base_url
+        self.api_key = api_key
+    
+    def _get_headers(self) -> dict:
+        """Get request headers with API key if available"""
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+    
+    def register_service(
+        self,
+        agent_id: str,
+        name: str,
+        description: str,
+        price: int,
+        endpoint: str,
+        category: str = "general",
+        currency: str = "BSV",
+        method: str = "POST",
+        timeout: int = 30,
+        dispute_window: int = 30,
+        input_schema: Optional[dict] = None,
+        output_schema: Optional[dict] = None
+    ) -> Service:
+        """
+        Register a new service
+        
+        Args:
+            agent_id: Provider wallet ID
+            name: Service name
+            description: Service description
+            price: Price per execution (satoshis for BSV, cents for MNEE)
+            endpoint: Service endpoint URL
+            category: Service category
+            currency: "BSV" or "MNEE"
+            method: HTTP method ("POST" or "GET")
+            timeout: Max execution time in seconds
+            dispute_window: Dispute window in minutes
+            input_schema: Optional JSON schema for input validation
+            output_schema: Optional JSON schema for output validation
+            
+        Returns:
+            Service: The registered service
+            
+        Raises:
+            ServiceError: If registration fails
+        """
+        payload = {
+            "agentId": agent_id,
+            "name": name,
+            "description": description,
+            "category": category,
+            "price": price,
+            "currency": currency.upper(),
+            "endpoint": endpoint,
+            "method": method.upper(),
+            "timeout": timeout,
+            "disputeWindow": dispute_window
+        }
+        
+        if input_schema:
+            payload["inputSchema"] = input_schema
+        if output_schema:
+            payload["outputSchema"] = output_schema
+        
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/services",
+                json=payload,
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            service_data = data.get("service")
+            if not service_data:
+                raise ServiceError("Invalid response: missing service data")
+            
+            return self._parse_service(service_data)
+        except requests.RequestException as e:
+            raise ServiceError(f"Failed to register service: {str(e)}") from e
+    
+    def search_services(
+        self,
+        keyword: Optional[str] = None,
+        category: Optional[str] = None,
+        max_price: Optional[int] = None,
+        min_rating: Optional[float] = None,
+        limit: int = 20,
+        offset: int = 0
+    ) -> List[Service]:
+        """
+        Search for services
+        
+        Args:
+            keyword: Search keyword
+            category: Filter by category
+            max_price: Maximum price filter
+            min_rating: Minimum rating filter
+            limit: Max results to return
+            offset: Result offset for pagination
+            
+        Returns:
+            List[Service]: List of matching services
+            
+        Raises:
+            ServiceError: If search fails
+        """
+        params = {}
+        if keyword:
+            params["q"] = keyword
+        if category:
+            params["category"] = category
+        if max_price is not None:
+            params["maxPrice"] = str(max_price)
+        if min_rating is not None:
+            params["minRating"] = str(min_rating)
+        if limit:
+            params["limit"] = str(limit)
+        if offset:
+            params["offset"] = str(offset)
+        
+        try:
+            response = requests.get(
+                f"{self.base_url}/api/services",
+                params=params,
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            services_data = data.get("services", [])
+            return [self._parse_service(s) for s in services_data]
+        except requests.RequestException as e:
+            raise ServiceError(f"Failed to search services: {str(e)}") from e
+    
+    def get_service(self, service_id: str) -> Service:
+        """
+        Get service by ID
+        
+        Args:
+            service_id: Service ID
+            
+        Returns:
+            Service: The service
+            
+        Raises:
+            ServiceError: If service not found or request fails
+        """
+        try:
+            response = requests.get(
+                f"{self.base_url}/api/services/{service_id}",
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            service_data = data.get("service")
+            if not service_data:
+                raise ServiceError(f"Service {service_id} not found")
+            
+            return self._parse_service(service_data)
+        except requests.RequestException as e:
+            raise ServiceError(f"Failed to get service: {str(e)}") from e
+    
+    def _parse_service(self, data: dict) -> Service:
+        """Parse service data from API response"""
+        return Service(
+            id=data["id"],
+            agent_id=data["agentId"],
+            name=data["name"],
+            description=data["description"],
+            category=data["category"],
+            price=data["price"],
+            currency=data["currency"],
+            endpoint=data["endpoint"],
+            method=data["method"],
+            active=data["active"],
+            timeout=data.get("timeout", 30),
+            dispute_window=data.get("disputeWindow", 30),
+            created_at=data["createdAt"],
+            updated_at=data["updatedAt"],
+            input_schema=data.get("inputSchema"),
+            output_schema=data.get("outputSchema")
+        )

package/sdk-python/agentspay/types.py

@@ -0,0 +1,154 @@
+"""AgentPay SDK Type Definitions"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Literal, Dict, Any
+from datetime import datetime
+
+
+Currency = Literal["BSV", "MNEE"]
+PaymentStatus = Literal["pending", "escrowed", "released", "disputed", "refunded"]
+DisputeStatus = Literal["open", "under_review", "resolved_refund", "resolved_release", "resolved_split", "expired"]
+DisputeResolution = Literal["refund", "release", "split"]
+ExecutionStatus = Literal["success", "error"]
+HttpMethod = Literal["POST", "GET"]
+
+
+@dataclass
+class AgentWallet:
+    """Agent wallet representation"""
+    id: str
+    public_key: str
+    address: str
+    created_at: str
+    balance: Optional[int] = None  # satoshis (BSV)
+    balance_mnee: Optional[int] = None  # cents (MNEE)
+
+
+@dataclass
+class Service:
+    """Service registration"""
+    id: str
+    agent_id: str
+    name: str
+    description: str
+    category: str
+    price: int  # satoshis for BSV, cents for MNEE
+    currency: Currency
+    endpoint: str
+    method: HttpMethod
+    active: bool
+    timeout: int  # seconds
+    dispute_window: int  # minutes
+    created_at: str
+    updated_at: str
+    input_schema: Optional[Dict[str, Any]] = None
+    output_schema: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class Payment:
+    """Payment record"""
+    id: str
+    service_id: str
+    buyer_wallet_id: str
+    seller_wallet_id: str
+    amount: int
+    platform_fee: int
+    currency: Currency
+    status: PaymentStatus
+    created_at: str
+    dispute_status: Optional[str] = None
+    tx_id: Optional[str] = None
+    completed_at: Optional[str] = None
+
+
+@dataclass
+class ExecutionRequest:
+    """Service execution request"""
+    service_id: str
+    buyer_wallet_id: str
+    input: Dict[str, Any]
+
+
+@dataclass
+class ExecutionResult:
+    """Service execution result"""
+    payment_id: str
+    service_id: str
+    output: Dict[str, Any]
+    execution_time_ms: int
+    status: ExecutionStatus
+    receipt: Optional['ExecutionReceipt'] = None
+    payment: Optional[Payment] = None
+
+
+@dataclass
+class ExecutionReceipt:
+    """Cryptographic execution receipt"""
+    id: str
+    payment_id: str
+    service_id: str
+    input_hash: str
+    output_hash: str
+    timestamp: int
+    execution_time_ms: int
+    provider_signature: str
+    platform_signature: str
+    receipt_hash: str
+    blockchain_tx_id: Optional[str] = None
+    blockchain_anchored_at: Optional[str] = None
+
+
+@dataclass
+class ReputationScore:
+    """Agent reputation metrics"""
+    agent_id: str
+    total_jobs: int
+    success_rate: float  # 0-1
+    avg_response_time_ms: float
+    total_earned: int  # satoshis
+    total_spent: int  # satoshis
+    rating: float  # 1-5
+
+
+@dataclass
+class Dispute:
+    """Dispute record"""
+    id: str
+    payment_id: str
+    buyer_wallet_id: str
+    provider_wallet_id: str
+    reason: str
+    status: DisputeStatus
+    created_at: str
+    evidence: Optional[str] = None
+    resolution: Optional[DisputeResolution] = None
+    split_percent: Optional[float] = None
+    resolved_at: Optional[str] = None
+
+
+@dataclass
+class Webhook:
+    """Webhook registration"""
+    id: str
+    url: str
+    events: list[str]
+    active: bool
+    created_at: str
+    secret: Optional[str] = None
+
+
+@dataclass
+class ServiceQuery:
+    """Service search query"""
+    category: Optional[str] = None
+    keyword: Optional[str] = None
+    max_price: Optional[int] = None
+    min_rating: Optional[float] = None
+    limit: Optional[int] = 20
+    offset: Optional[int] = 0
+
+
+# Constants
+PLATFORM_FEE_RATE = 0.02  # 2%
+MIN_PRICE_SATOSHIS = 1

package/sdk-python/agentspay/wallet.py

@@ -0,0 +1,113 @@
+"""Wallet operations for AgentPay SDK"""
+
+from typing import Optional
+import requests
+from .types import AgentWallet
+from .exceptions import WalletError, APIError
+
+
+class WalletOperations:
+    """Handles wallet-related operations"""
+    
+    def __init__(self, base_url: str, api_key: Optional[str] = None):
+        self.base_url = base_url
+        self.api_key = api_key
+    
+    def _get_headers(self) -> dict:
+        """Get request headers with API key if available"""
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+    
+    def create_wallet(self) -> AgentWallet:
+        """
+        Create a new agent wallet
+        
+        Returns:
+            AgentWallet: The created wallet
+            
+        Raises:
+            WalletError: If wallet creation fails
+        """
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/wallets",
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            wallet_data = data.get("wallet")
+            if not wallet_data:
+                raise WalletError("Invalid response: missing wallet data")
+            
+            return AgentWallet(
+                id=wallet_data["id"],
+                public_key=wallet_data["publicKey"],
+                address=wallet_data["address"],
+                created_at=wallet_data["createdAt"],
+                balance=wallet_data.get("balance"),
+                balance_mnee=wallet_data.get("balanceMnee")
+            )
+        except requests.RequestException as e:
+            raise WalletError(f"Failed to create wallet: {str(e)}") from e
+    
+    def get_wallet(self, wallet_id: str) -> AgentWallet:
+        """
+        Get wallet by ID
+        
+        Args:
+            wallet_id: Wallet ID
+            
+        Returns:
+            AgentWallet: The wallet
+            
+        Raises:
+            WalletError: If wallet not found or request fails
+        """
+        try:
+            response = requests.get(
+                f"{self.base_url}/api/wallets/{wallet_id}",
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            wallet_data = data.get("wallet")
+            if not wallet_data:
+                raise WalletError(f"Wallet {wallet_id} not found")
+            
+            return AgentWallet(
+                id=wallet_data["id"],
+                public_key=wallet_data["publicKey"],
+                address=wallet_data["address"],
+                created_at=wallet_data["createdAt"],
+                balance=wallet_data.get("balance"),
+                balance_mnee=wallet_data.get("balanceMnee")
+            )
+        except requests.RequestException as e:
+            raise WalletError(f"Failed to get wallet: {str(e)}") from e
+    
+    def get_balance(self, wallet_id: str, currency: str = "BSV") -> int:
+        """
+        Get wallet balance for a specific currency
+        
+        Args:
+            wallet_id: Wallet ID
+            currency: "BSV" or "MNEE"
+            
+        Returns:
+            int: Balance in satoshis (BSV) or cents (MNEE)
+            
+        Raises:
+            WalletError: If balance cannot be retrieved
+        """
+        wallet = self.get_wallet(wallet_id)
+        
+        if currency.upper() == "BSV":
+            return wallet.balance or 0
+        elif currency.upper() == "MNEE":
+            return wallet.balance_mnee or 0
+        else:
+            raise WalletError(f"Invalid currency: {currency}")

package/sdk-python/agentspay/webhooks.py

@@ -0,0 +1,195 @@
+"""Webhook management for AgentPay SDK"""
+
+from typing import Optional, List
+import requests
+from .types import Webhook
+from .exceptions import WebhookError
+
+
+class WebhookOperations:
+    """Handles webhook registration and management"""
+    
+    def __init__(self, base_url: str, api_key: Optional[str] = None):
+        self.base_url = base_url
+        self.api_key = api_key
+    
+    def _get_headers(self) -> dict:
+        """Get request headers with API key if available"""
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+    
+    def register_webhook(
+        self,
+        url: str,
+        events: List[str]
+    ) -> Webhook:
+        """
+        Register a new webhook
+        
+        Args:
+            url: Webhook endpoint URL
+            events: List of events to subscribe to
+                   (e.g., ["payment.completed", "payment.failed", "dispute.opened"])
+            
+        Returns:
+            Webhook: The registered webhook
+            
+        Raises:
+            WebhookError: If registration fails
+        """
+        payload = {
+            "url": url,
+            "events": events
+        }
+        
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/webhooks",
+                json=payload,
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            webhook_data = data.get("webhook")
+            if not webhook_data:
+                raise WebhookError("Invalid response: missing webhook data")
+            
+            return self._parse_webhook(webhook_data)
+        except requests.RequestException as e:
+            raise WebhookError(f"Failed to register webhook: {str(e)}") from e
+    
+    def get_webhook(self, webhook_id: str) -> Webhook:
+        """
+        Get webhook by ID
+        
+        Args:
+            webhook_id: Webhook ID
+            
+        Returns:
+            Webhook: The webhook
+            
+        Raises:
+            WebhookError: If webhook not found or request fails
+        """
+        try:
+            response = requests.get(
+                f"{self.base_url}/api/webhooks/{webhook_id}",
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            webhook_data = data.get("webhook")
+            if not webhook_data:
+                raise WebhookError(f"Webhook {webhook_id} not found")
+            
+            return self._parse_webhook(webhook_data)
+        except requests.RequestException as e:
+            raise WebhookError(f"Failed to get webhook: {str(e)}") from e
+    
+    def list_webhooks(self) -> List[Webhook]:
+        """
+        List all registered webhooks
+        
+        Returns:
+            List[Webhook]: List of webhooks
+            
+        Raises:
+            WebhookError: If request fails
+        """
+        try:
+            response = requests.get(
+                f"{self.base_url}/api/webhooks",
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            webhooks_data = data.get("webhooks", [])
+            return [self._parse_webhook(w) for w in webhooks_data]
+        except requests.RequestException as e:
+            raise WebhookError(f"Failed to list webhooks: {str(e)}") from e
+    
+    def delete_webhook(self, webhook_id: str) -> bool:
+        """
+        Delete a webhook
+        
+        Args:
+            webhook_id: Webhook ID
+            
+        Returns:
+            bool: True if deleted successfully
+            
+        Raises:
+            WebhookError: If deletion fails
+        """
+        try:
+            response = requests.delete(
+                f"{self.base_url}/api/webhooks/{webhook_id}",
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            return True
+        except requests.RequestException as e:
+            raise WebhookError(f"Failed to delete webhook: {str(e)}") from e
+    
+    def update_webhook(
+        self,
+        webhook_id: str,
+        url: Optional[str] = None,
+        events: Optional[List[str]] = None,
+        active: Optional[bool] = None
+    ) -> Webhook:
+        """
+        Update a webhook
+        
+        Args:
+            webhook_id: Webhook ID
+            url: New URL (optional)
+            events: New events list (optional)
+            active: Active status (optional)
+            
+        Returns:
+            Webhook: Updated webhook
+            
+        Raises:
+            WebhookError: If update fails
+        """
+        payload = {}
+        if url is not None:
+            payload["url"] = url
+        if events is not None:
+            payload["events"] = events
+        if active is not None:
+            payload["active"] = active
+        
+        try:
+            response = requests.patch(
+                f"{self.base_url}/api/webhooks/{webhook_id}",
+                json=payload,
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            webhook_data = data.get("webhook")
+            if not webhook_data:
+                raise WebhookError("Invalid response: missing webhook data")
+            
+            return self._parse_webhook(webhook_data)
+        except requests.RequestException as e:
+            raise WebhookError(f"Failed to update webhook: {str(e)}") from e
+    
+    def _parse_webhook(self, data: dict) -> Webhook:
+        """Parse webhook data from API response"""
+        return Webhook(
+            id=data["id"],
+            url=data["url"],
+            events=data["events"],
+            active=data["active"],
+            created_at=data["createdAt"],
+            secret=data.get("secret")
+        )