agentspay 0.1.0 → 0.2.0

package/sdk-python/agentspay/client.py

@@ -0,0 +1,256 @@
+"""AgentPay SDK Main Client"""
+
+from typing import Optional, List, Dict, Any
+from .wallet import WalletOperations
+from .services import ServiceOperations
+from .payments import PaymentOperations
+from .disputes import DisputeOperations
+from .webhooks import WebhookOperations
+from .types import (
+    AgentWallet,
+    Service,
+    ExecutionResult,
+    Payment,
+    Dispute,
+    Webhook,
+    ReputationScore
+)
+from .exceptions import AgentPayError
+import requests
+
+
+class AgentPayClient:
+    """
+    AgentPay SDK Client
+    
+    Main interface for interacting with AgentPay platform.
+    
+    Example:
+        >>> client = AgentPayClient(base_url="http://localhost:3100", api_key="your-key")
+        >>> wallet = client.create_wallet()
+        >>> service = client.register_service(
+        ...     agent_id=wallet.id,
+        ...     name="TextAnalyzer",
+        ...     description="NLP analysis",
+        ...     price=1000,
+        ...     currency="BSV",
+        ...     endpoint="https://my-agent.com/analyze",
+        ...     category="nlp"
+        ... )
+    """
+    
+    def __init__(
+        self,
+        base_url: str = "http://localhost:3100",
+        api_key: Optional[str] = None
+    ):
+        """
+        Initialize AgentPay client
+        
+        Args:
+            base_url: AgentPay API base URL
+            api_key: Optional API key for authentication
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        
+        # Initialize operation modules
+        self._wallet = WalletOperations(self.base_url, self.api_key)
+        self._services = ServiceOperations(self.base_url, self.api_key)
+        self._payments = PaymentOperations(self.base_url, self.api_key)
+        self._disputes = DisputeOperations(self.base_url, self.api_key)
+        self._webhooks = WebhookOperations(self.base_url, self.api_key)
+    
+    # Wallet Operations
+    
+    def create_wallet(self) -> AgentWallet:
+        """Create a new agent wallet"""
+        return self._wallet.create_wallet()
+    
+    def get_wallet(self, wallet_id: str) -> AgentWallet:
+        """Get wallet by ID"""
+        return self._wallet.get_wallet(wallet_id)
+    
+    def get_balance(self, wallet_id: str, currency: str = "BSV") -> int:
+        """Get wallet balance for a specific currency"""
+        return self._wallet.get_balance(wallet_id, currency)
+    
+    # Service Operations
+    
+    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"""
+        return self._services.register_service(
+            agent_id=agent_id,
+            name=name,
+            description=description,
+            price=price,
+            endpoint=endpoint,
+            category=category,
+            currency=currency,
+            method=method,
+            timeout=timeout,
+            dispute_window=dispute_window,
+            input_schema=input_schema,
+            output_schema=output_schema
+        )
+    
+    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"""
+        return self._services.search_services(
+            keyword=keyword,
+            category=category,
+            max_price=max_price,
+            min_rating=min_rating,
+            limit=limit,
+            offset=offset
+        )
+    
+    def get_service(self, service_id: str) -> Service:
+        """Get service by ID"""
+        return self._services.get_service(service_id)
+    
+    # Payment & Execution Operations
+    
+    def execute(
+        self,
+        service_id: str,
+        buyer_wallet_id: str,
+        input_data: Dict[str, Any]
+    ) -> ExecutionResult:
+        """
+        Execute a service and handle payment
+        
+        Returns execution result with payment details and cryptographic receipt
+        """
+        return self._payments.execute(service_id, buyer_wallet_id, input_data)
+    
+    def get_payment(self, payment_id: str) -> Payment:
+        """Get payment by ID"""
+        return self._payments.get_payment(payment_id)
+    
+    def get_receipt(self, receipt_id: str):
+        """Get execution receipt by ID"""
+        return self._payments.get_receipt(receipt_id)
+    
+    # Dispute Operations
+    
+    def open_dispute(
+        self,
+        payment_id: str,
+        reason: str,
+        evidence: Optional[str] = None
+    ) -> Dispute:
+        """Open a dispute for a payment"""
+        return self._disputes.open_dispute(payment_id, reason, evidence)
+    
+    def get_dispute(self, dispute_id: str) -> Dispute:
+        """Get dispute by ID"""
+        return self._disputes.get_dispute(dispute_id)
+    
+    def get_payment_disputes(self, payment_id: str) -> List[Dispute]:
+        """Get all disputes for a payment"""
+        return self._disputes.get_payment_disputes(payment_id)
+    
+    def add_dispute_evidence(self, dispute_id: str, evidence: str) -> Dispute:
+        """Add evidence to a dispute"""
+        return self._disputes.add_evidence(dispute_id, evidence)
+    
+    # Webhook Operations
+    
+    def register_webhook(
+        self,
+        url: str,
+        events: List[str]
+    ) -> Webhook:
+        """
+        Register a webhook
+        
+        Args:
+            url: Webhook endpoint URL
+            events: Events to subscribe to (e.g., ["payment.completed", "payment.failed"])
+        """
+        return self._webhooks.register_webhook(url, events)
+    
+    def get_webhook(self, webhook_id: str) -> Webhook:
+        """Get webhook by ID"""
+        return self._webhooks.get_webhook(webhook_id)
+    
+    def list_webhooks(self) -> List[Webhook]:
+        """List all registered webhooks"""
+        return self._webhooks.list_webhooks()
+    
+    def delete_webhook(self, webhook_id: str) -> bool:
+        """Delete a webhook"""
+        return self._webhooks.delete_webhook(webhook_id)
+    
+    def update_webhook(
+        self,
+        webhook_id: str,
+        url: Optional[str] = None,
+        events: Optional[List[str]] = None,
+        active: Optional[bool] = None
+    ) -> Webhook:
+        """Update a webhook"""
+        return self._webhooks.update_webhook(webhook_id, url, events, active)
+    
+    # Reputation Operations
+    
+    def get_reputation(self, agent_id: str) -> ReputationScore:
+        """
+        Get reputation score for an agent
+        
+        Args:
+            agent_id: Agent wallet ID
+            
+        Returns:
+            ReputationScore: Agent's reputation metrics
+        """
+        try:
+            headers = {"Content-Type": "application/json"}
+            if self.api_key:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+            
+            response = requests.get(
+                f"{self.base_url}/api/agents/{agent_id}/reputation",
+                headers=headers
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            rep_data = data.get("reputation")
+            if not rep_data:
+                raise AgentPayError(f"Reputation for agent {agent_id} not found")
+            
+            return ReputationScore(
+                agent_id=rep_data["agentId"],
+                total_jobs=rep_data["totalJobs"],
+                success_rate=rep_data["successRate"],
+                avg_response_time_ms=rep_data["avgResponseTimeMs"],
+                total_earned=rep_data["totalEarned"],
+                total_spent=rep_data["totalSpent"],
+                rating=rep_data["rating"]
+            )
+        except requests.RequestException as e:
+            raise AgentPayError(f"Failed to get reputation: {str(e)}") from e

package/sdk-python/agentspay/disputes.py

@@ -0,0 +1,174 @@
+"""Dispute management for AgentPay SDK"""
+
+from typing import Optional, List
+import requests
+from .types import Dispute
+from .exceptions import DisputeError
+
+
+class DisputeOperations:
+    """Handles dispute 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 open_dispute(
+        self,
+        payment_id: str,
+        reason: str,
+        evidence: Optional[str] = None
+    ) -> Dispute:
+        """
+        Open a dispute for a payment
+        
+        Args:
+            payment_id: Payment ID to dispute
+            reason: Reason for the dispute
+            evidence: Optional evidence (URL, description, etc.)
+            
+        Returns:
+            Dispute: The created dispute
+            
+        Raises:
+            DisputeError: If dispute creation fails
+        """
+        payload = {
+            "paymentId": payment_id,
+            "reason": reason
+        }
+        
+        if evidence:
+            payload["evidence"] = evidence
+        
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/disputes",
+                json=payload,
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            dispute_data = data.get("dispute")
+            if not dispute_data:
+                raise DisputeError("Invalid response: missing dispute data")
+            
+            return self._parse_dispute(dispute_data)
+        except requests.RequestException as e:
+            raise DisputeError(f"Failed to open dispute: {str(e)}") from e
+    
+    def get_dispute(self, dispute_id: str) -> Dispute:
+        """
+        Get dispute by ID
+        
+        Args:
+            dispute_id: Dispute ID
+            
+        Returns:
+            Dispute: The dispute
+            
+        Raises:
+            DisputeError: If dispute not found or request fails
+        """
+        try:
+            response = requests.get(
+                f"{self.base_url}/api/disputes/{dispute_id}",
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            dispute_data = data.get("dispute")
+            if not dispute_data:
+                raise DisputeError(f"Dispute {dispute_id} not found")
+            
+            return self._parse_dispute(dispute_data)
+        except requests.RequestException as e:
+            raise DisputeError(f"Failed to get dispute: {str(e)}") from e
+    
+    def get_payment_disputes(self, payment_id: str) -> List[Dispute]:
+        """
+        Get all disputes for a payment
+        
+        Args:
+            payment_id: Payment ID
+            
+        Returns:
+            List[Dispute]: List of disputes for the payment
+            
+        Raises:
+            DisputeError: If request fails
+        """
+        try:
+            response = requests.get(
+                f"{self.base_url}/api/payments/{payment_id}/disputes",
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            disputes_data = data.get("disputes", [])
+            return [self._parse_dispute(d) for d in disputes_data]
+        except requests.RequestException as e:
+            raise DisputeError(f"Failed to get payment disputes: {str(e)}") from e
+    
+    def add_evidence(
+        self,
+        dispute_id: str,
+        evidence: str
+    ) -> Dispute:
+        """
+        Add evidence to a dispute
+        
+        Args:
+            dispute_id: Dispute ID
+            evidence: Evidence to add
+            
+        Returns:
+            Dispute: Updated dispute
+            
+        Raises:
+            DisputeError: If evidence submission fails
+        """
+        payload = {"evidence": evidence}
+        
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/disputes/{dispute_id}/evidence",
+                json=payload,
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            dispute_data = data.get("dispute")
+            if not dispute_data:
+                raise DisputeError("Invalid response: missing dispute data")
+            
+            return self._parse_dispute(dispute_data)
+        except requests.RequestException as e:
+            raise DisputeError(f"Failed to add evidence: {str(e)}") from e
+    
+    def _parse_dispute(self, data: dict) -> Dispute:
+        """Parse dispute data from API response"""
+        return Dispute(
+            id=data["id"],
+            payment_id=data["paymentId"],
+            buyer_wallet_id=data["buyerWalletId"],
+            provider_wallet_id=data["providerWalletId"],
+            reason=data["reason"],
+            status=data["status"],
+            created_at=data["createdAt"],
+            evidence=data.get("evidence"),
+            resolution=data.get("resolution"),
+            split_percent=data.get("splitPercent"),
+            resolved_at=data.get("resolvedAt")
+        )

package/sdk-python/agentspay/exceptions.py

@@ -0,0 +1,53 @@
+"""AgentPay SDK Exceptions"""
+
+
+class AgentPayError(Exception):
+    """Base exception for all AgentPay errors"""
+    pass
+
+
+class APIError(AgentPayError):
+    """Raised when API returns an error response"""
+    
+    def __init__(self, message: str, status_code: int = None, response: dict = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+
+class ValidationError(AgentPayError):
+    """Raised when request validation fails"""
+    pass
+
+
+class WalletError(AgentPayError):
+    """Raised for wallet-related errors"""
+    pass
+
+
+class ServiceError(AgentPayError):
+    """Raised for service-related errors"""
+    pass
+
+
+class PaymentError(AgentPayError):
+    """Raised for payment-related errors"""
+    pass
+
+
+class DisputeError(AgentPayError):
+    """Raised for dispute-related errors"""
+    pass
+
+
+class WebhookError(AgentPayError):
+    """Raised for webhook-related errors"""
+    pass
+
+
+class ExecutionError(AgentPayError):
+    """Raised when service execution fails"""
+    
+    def __init__(self, message: str, execution_result: dict = None):
+        super().__init__(message)
+        self.execution_result = execution_result

package/sdk-python/agentspay/payments.py

@@ -0,0 +1,169 @@
+"""Payment and execution operations for AgentPay SDK"""
+
+from typing import Optional, Dict, Any
+import requests
+from .types import ExecutionResult, ExecutionReceipt, Payment
+from .exceptions import PaymentError, ExecutionError
+
+
+class PaymentOperations:
+    """Handles payment and service execution"""
+    
+    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 execute(
+        self,
+        service_id: str,
+        buyer_wallet_id: str,
+        input_data: Dict[str, Any]
+    ) -> ExecutionResult:
+        """
+        Execute a service and handle payment
+        
+        Args:
+            service_id: Service ID to execute
+            buyer_wallet_id: Buyer's wallet ID
+            input_data: Input data for the service
+            
+        Returns:
+            ExecutionResult: Execution result with payment and receipt
+            
+        Raises:
+            ExecutionError: If execution fails
+        """
+        payload = {
+            "buyerWalletId": buyer_wallet_id,
+            "input": input_data
+        }
+        
+        try:
+            response = requests.post(
+                f"{self.base_url}/api/execute/{service_id}",
+                json=payload,
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            # Parse receipt if available
+            receipt = None
+            if "receipt" in data and data["receipt"]:
+                receipt = self._parse_receipt(data["receipt"])
+            
+            # Parse payment if available
+            payment = None
+            if "payment" in data and data["payment"]:
+                payment = self._parse_payment(data["payment"])
+            
+            return ExecutionResult(
+                payment_id=data["paymentId"],
+                service_id=data["serviceId"],
+                output=data.get("output", {}),
+                execution_time_ms=data.get("executionTimeMs", 0),
+                status=data.get("status", "success"),
+                receipt=receipt,
+                payment=payment
+            )
+        except requests.RequestException as e:
+            raise ExecutionError(f"Service execution failed: {str(e)}") from e
+    
+    def get_payment(self, payment_id: str) -> Payment:
+        """
+        Get payment by ID
+        
+        Args:
+            payment_id: Payment ID
+            
+        Returns:
+            Payment: The payment record
+            
+        Raises:
+            PaymentError: If payment not found or request fails
+        """
+        try:
+            response = requests.get(
+                f"{self.base_url}/api/payments/{payment_id}",
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            payment_data = data.get("payment")
+            if not payment_data:
+                raise PaymentError(f"Payment {payment_id} not found")
+            
+            return self._parse_payment(payment_data)
+        except requests.RequestException as e:
+            raise PaymentError(f"Failed to get payment: {str(e)}") from e
+    
+    def get_receipt(self, receipt_id: str) -> ExecutionReceipt:
+        """
+        Get execution receipt by ID
+        
+        Args:
+            receipt_id: Receipt ID
+            
+        Returns:
+            ExecutionReceipt: The execution receipt
+            
+        Raises:
+            PaymentError: If receipt not found or request fails
+        """
+        try:
+            response = requests.get(
+                f"{self.base_url}/api/receipts/{receipt_id}",
+                headers=self._get_headers()
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            receipt_data = data.get("receipt")
+            if not receipt_data:
+                raise PaymentError(f"Receipt {receipt_id} not found")
+            
+            return self._parse_receipt(receipt_data)
+        except requests.RequestException as e:
+            raise PaymentError(f"Failed to get receipt: {str(e)}") from e
+    
+    def _parse_payment(self, data: dict) -> Payment:
+        """Parse payment data from API response"""
+        return Payment(
+            id=data["id"],
+            service_id=data["serviceId"],
+            buyer_wallet_id=data["buyerWalletId"],
+            seller_wallet_id=data["sellerWalletId"],
+            amount=data["amount"],
+            platform_fee=data["platformFee"],
+            currency=data["currency"],
+            status=data["status"],
+            created_at=data["createdAt"],
+            dispute_status=data.get("disputeStatus"),
+            tx_id=data.get("txId"),
+            completed_at=data.get("completedAt")
+        )
+    
+    def _parse_receipt(self, data: dict) -> ExecutionReceipt:
+        """Parse receipt data from API response"""
+        return ExecutionReceipt(
+            id=data["id"],
+            payment_id=data["paymentId"],
+            service_id=data["serviceId"],
+            input_hash=data["inputHash"],
+            output_hash=data["outputHash"],
+            timestamp=data["timestamp"],
+            execution_time_ms=data["executionTimeMs"],
+            provider_signature=data["providerSignature"],
+            platform_signature=data["platformSignature"],
+            receipt_hash=data["receiptHash"],
+            blockchain_tx_id=data.get("blockchainTxId"),
+            blockchain_anchored_at=data.get("blockchainAnchoredAt")
+        )