Add license testing script and improve get_license documentation

- Add test_licenses.py: Test script for validating provided license keys
  - Tests all 8 example licenses from dashboard
  - Provides detailed validation results
  - Shows response times and error handling
  - Comprehensive test summary

- Improve get_license documentation:
  - Clarify that it supports both ID and license key
  - Document all returned fields
  - Explain API response structure

Author: VoxHash

examples/test_licenses.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""
+LicenseChain Python SDK - License Testing Script
+
+This script tests license validation using the provided example licenses
+to ensure the SDK and API endpoints are working correctly.
+"""
+
+import asyncio
+import os
+import sys
+from datetime import datetime
+from typing import Dict, Any, List
+
+# Add the parent directory to the path so we can import the SDK
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
+
+from licensechain.client import LicenseChainClient
+from licensechain.exceptions import (
+    AuthenticationError,
+    ValidationError,
+    NetworkError,
+    LicenseChainException,
+)
+
+
+# Test license keys from the dashboard
+TEST_LICENSES = [
+    "LC-ZFVUPU-QR4DIU-4QPUFD",
+    "LC-WGVCU0-MH6QO5-SJF7ZE",
+    "LC-DBQ88O-M181MU-9RYRU7",
+    "LC-MDC1AM-V1N53V-BUXIB0",
+    "LC-08QGAA-RRCTZC-RWU6N7",
+    "LC-U1N96E-T3RPVG-R7VT3D",
+    "LC-CFYX1L-VCP9JD-KE7F06",
+    "LC-AILF6U-4Z623N-B1JHSE",
+]
+
+
+async def test_license_validation(client: LicenseChainClient, license_key: str) -> Dict[str, Any]:
+    """
+    Test validation of a single license key.
+    
+    Returns:
+        Dictionary with test results
+    """
+    result = {
+        "license_key": license_key,
+        "valid": False,
+        "status": None,
+        "error": None,
+        "response_time": None,
+        "details": None,
+    }
+    
+    try:
+        start_time = datetime.now()
+        response = await client.validate_license(license_key=license_key)
+        elapsed = (datetime.now() - start_time).total_seconds()
+        
+        result["response_time"] = elapsed
+        result["valid"] = response.get("valid", False)
+        result["status"] = response.get("status", "UNKNOWN")
+        result["details"] = {
+            "expiresAt": response.get("expiresAt"),
+            "email": response.get("email"),
+            "metadata": response.get("metadata"),
+        }
+        
+    except ValidationError as e:
+        result["error"] = f"ValidationError: {str(e)}"
+    except AuthenticationError as e:
+        result["error"] = f"AuthenticationError: {str(e)}"
+    except NetworkError as e:
+        result["error"] = f"NetworkError: {str(e)}"
+    except LicenseChainException as e:
+        result["error"] = f"LicenseChainException: {str(e)}"
+    except Exception as e:
+        result["error"] = f"Unexpected error: {type(e).__name__}: {str(e)}"
+    
+    return result
+
+
+async def test_all_licenses(client: LicenseChainClient) -> List[Dict[str, Any]]:
+    """Test all provided license keys."""
+    print("🔍 Testing license validation for all provided licenses...\n")
+    
+    results = []
+    for i, license_key in enumerate(TEST_LICENSES, 1):
+        print(f"[{i}/{len(TEST_LICENSES)}] Testing: {license_key}")
+        result = await test_license_validation(client, license_key)
+        results.append(result)
+        
+        if result["error"]:
+            print(f"   ❌ Error: {result['error']}")
+        elif result["valid"]:
+            print(f"   ✅ Valid - Status: {result['status']}")
+            if result["details"]["expiresAt"]:
+                print(f"      Expires: {result['details']['expiresAt']}")
+            if result["details"]["email"]:
+                print(f"      Email: {result['details']['email']}")
+        else:
+            print(f"   ❌ Invalid - Status: {result['status']}")
+        print(f"   ⏱️  Response time: {result['response_time']:.3f}s\n")
+    
+    return results
+
+
+async def print_summary(results: List[Dict[str, Any]]):
+    """Print test summary."""
+    print("="*60)
+    print("Test Summary")
+    print("="*60)
+    
+    valid_count = sum(1 for r in results if r["valid"])
+    invalid_count = sum(1 for r in results if not r["valid"] and not r["error"])
+    error_count = sum(1 for r in results if r["error"])
+    
+    print(f"Total Licenses Tested: {len(results)}")
+    print(f"✅ Valid: {valid_count}")
+    print(f"❌ Invalid: {invalid_count}")
+    print(f"⚠️  Errors: {error_count}")
+    
+    if results:
+        avg_response_time = sum(r["response_time"] or 0 for r in results) / len(results)
+        print(f"⏱️  Average Response Time: {avg_response_time:.3f}s")
+    
+    print("\n" + "="*60)
+    print("Detailed Results")
+    print("="*60)
+    
+    for result in results:
+        status_icon = "✅" if result["valid"] else ("⚠️" if result["error"] else "❌")
+        print(f"\n{status_icon} {result['license_key']}")
+        print(f"   Status: {result['status'] or 'N/A'}")
+        if result["error"]:
+            print(f"   Error: {result['error']}")
+        if result["details"]["expiresAt"]:
+            print(f"   Expires: {result['details']['expiresAt']}")
+        if result["details"]["email"]:
+            print(f"   Email: {result['details']['email']}")
+        if result["response_time"]:
+            print(f"   Response Time: {result['response_time']:.3f}s")
+
+
+async def main():
+    """Main test function."""
+    print("="*60)
+    print("LicenseChain Python SDK - License Testing")
+    print("="*60)
+    print(f"Timestamp: {datetime.now().isoformat()}\n")
+    
+    # Get API key from environment
+    api_key = os.getenv("LICENSECHAIN_API_KEY")
+    if not api_key:
+        print("❌ ERROR: LICENSECHAIN_API_KEY environment variable not set")
+        print("\nTo run this test:")
+        print("  export LICENSECHAIN_API_KEY='your-api-key'")
+        print("  python examples/test_licenses.py")
+        return False
+    
+    # Optional: Get app ID
+    app_id = os.getenv("LICENSECHAIN_APP_ID")
+    
+    # Initialize client
+    client = LicenseChainClient(
+        api_key=api_key,
+        base_url="https://api.licensechain.app",
+        timeout=30,
+    )
+    
+    try:
+        # Test all licenses
+        results = await test_all_licenses(client)
+        
+        # Print summary
+        await print_summary(results)
+        
+        # Overall result
+        all_passed = all(r["valid"] or r["error"] for r in results)
+        if all_passed:
+            print("\n✅ All licenses processed successfully!")
+            return True
+        else:
+            print("\n⚠️  Some licenses failed validation")
+            return False
+            
+    except Exception as e:
+        print(f"\n❌ Test failed with error: {type(e).__name__}: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+    finally:
+        await client.close()
+
+
+if __name__ == "__main__":
+    success = asyncio.run(main())
+    sys.exit(0 if success else 1)