licensechain_ruby_sdk 1.0.1

data/README.md

@@ -0,0 +1,492 @@
+# LicenseChain Ruby SDK
+
+[![License](https://img.shields.io/badge/license-Elastic--2.0-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/Ruby-3.0+-red.svg)](https://www.ruby-lang.org/)
+[![Gem](https://img.shields.io/gem/v/licensechain-sdk)](https://rubygems.org/gems/licensechain-sdk)
+[![Downloads](https://img.shields.io/gem/dt/licensechain-sdk)](https://rubygems.org/gems/licensechain-sdk)
+
+Official Ruby SDK for LicenseChain - Secure license management for Ruby applications.
+
+## 🚀 Features
+
+- **🔐 Secure Authentication** - User registration, login, and session management
+- **📜 License Management** - Create, validate, update, and revoke licenses
+- **🛡️ Hardware ID Validation** - Prevent license sharing and unauthorized access
+- **🔔 Webhook Support** - Real-time license events and notifications
+- **📊 Analytics Integration** - Track license usage and performance metrics
+- **⚡ High Performance** - Optimized for production workloads
+- **🔄 Async Operations** - Non-blocking HTTP requests and data processing
+- **🛠️ Easy Integration** - Simple API with comprehensive documentation
+
+## 📦 Installation
+
+### Method 1: RubyGems (Recommended)
+
+```bash
+# Install via gem
+gem install licensechain-sdk
+
+# Or add to Gemfile
+gem 'licensechain-sdk', '~> 1.0'
+```
+
+### Method 2: Bundler
+
+```bash
+# Add to Gemfile
+gem 'licensechain-sdk', '~> 1.0'
+
+# Install dependencies
+bundle install
+```
+
+### Method 3: Manual Installation
+
+1. Download the latest release from [GitHub Releases](https://github.com/LicenseChain/LicenseChain-Ruby-SDK/releases)
+2. Extract to your project directory
+3. Install dependencies
+
+## 🚀 Quick Start
+
+### Basic Setup
+
+```ruby
+require 'licensechain-sdk'
+
+# Initialize the client
+client = LicenseChain::Client.new(
+  api_key: 'your-api-key',
+  app_name: 'your-app-name',
+  version: '1.0.0'
+)
+
+# Connect to LicenseChain
+begin
+  client.connect
+  puts "Connected to LicenseChain successfully!"
+rescue => e
+  puts "Failed to connect: #{e.message}"
+end
+```
+
+### User Authentication
+
+```ruby
+# Register a new user
+begin
+  user = client.register('username', 'password', 'email@example.com')
+  puts "User registered successfully!"
+  puts "User ID: #{user.id}"
+rescue => e
+  puts "Registration failed: #{e.message}"
+end
+
+# Login existing user
+begin
+  user = client.login('username', 'password')
+  puts "User logged in successfully!"
+  puts "Session ID: #{user.session_id}"
+rescue => e
+  puts "Login failed: #{e.message}"
+end
+```
+
+### License Management
+
+```ruby
+# Validate a license
+begin
+  license = client.validate_license('LICENSE-KEY-HERE')
+  puts "License is valid!"
+  puts "License Key: #{license.key}"
+  puts "Status: #{license.status}"
+  puts "Expires: #{license.expires}"
+  puts "Features: #{license.features.join(', ')}"
+  puts "User: #{license.user}"
+rescue => e
+  puts "License validation failed: #{e.message}"
+end
+
+# Get user's licenses
+begin
+  licenses = client.get_user_licenses
+  puts "Found #{licenses.length} licenses:"
+  licenses.each_with_index do |license, index|
+    puts "  #{index + 1}. #{license.key} - #{license.status} (Expires: #{license.expires})"
+  end
+rescue => e
+  puts "Failed to get licenses: #{e.message}"
+end
+```
+
+### Hardware ID Validation
+
+```ruby
+# Get hardware ID (automatically generated)
+hardware_id = client.get_hardware_id
+puts "Hardware ID: #{hardware_id}"
+
+# Validate hardware ID with license
+begin
+  is_valid = client.validate_hardware_id('LICENSE-KEY-HERE', hardware_id)
+  if is_valid
+    puts "Hardware ID is valid for this license!"
+  else
+    puts "Hardware ID is not valid for this license."
+  end
+rescue => e
+  puts "Hardware ID validation failed: #{e.message}"
+end
+```
+
+### Webhook Integration
+
+```ruby
+# Set up webhook handler
+client.set_webhook_handler do |event, data|
+  puts "Webhook received: #{event}"
+  
+  case event
+  when 'license.created'
+    puts "New license created: #{data['licenseKey']}"
+  when 'license.updated'
+    puts "License updated: #{data['licenseKey']}"
+  when 'license.revoked'
+    puts "License revoked: #{data['licenseKey']}"
+  end
+end
+
+# Start webhook listener
+client.start_webhook_listener
+```
+
+## 📚 API Endpoints
+
+Use the canonical API base URL `https://api.licensechain.app/v1`. The SDK also accepts the root host and normalizes requests to the same API version.
+
+### Base URL
+- **Production**: `https://api.licensechain.app/v1`
+- **Development**: `https://api.licensechain.app/v1`
+
+### Available Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/v1/health` | Health check |
+| `POST` | `/v1/auth/login` | User login |
+| `POST` | `/v1/auth/register` | User registration |
+| `GET` | `/v1/apps` | List applications |
+| `POST` | `/v1/apps` | Create application |
+| `GET` | `/v1/licenses` | List licenses |
+| `POST` | `/v1/licenses/verify` | Verify license |
+| `GET` | `/v1/webhooks` | List webhooks |
+| `POST` | `/v1/webhooks` | Create webhook |
+| `GET` | `/v1/analytics` | Get analytics |
+
+**Note**: The SDK accepts either the root host or the canonical `/v1` base and normalizes endpoint requests automatically.
+
+## 📚 API Reference
+
+### LicenseChain::Client
+
+#### Constructor
+
+```ruby
+client = LicenseChain::Client.new(
+  api_key: 'your-api-key',
+  app_name: 'your-app-name',
+  version: '1.0.0',
+  base_url: 'https://api.licensechain.app/v1'  # Optional
+)
+```
+
+#### Methods
+
+##### Connection Management
+
+```ruby
+# Connect to LicenseChain
+client.connect
+
+# Disconnect from LicenseChain
+client.disconnect
+
+# Check connection status
+is_connected = client.connected?
+```
+
+##### User Authentication
+
+```ruby
+# Register a new user
+user = client.register(username, password, email)
+
+# Login existing user
+user = client.login(username, password)
+
+# Logout current user
+client.logout
+
+# Get current user info
+user = client.get_current_user
+```
+
+##### License Management
+
+```ruby
+# Validate a license
+license = client.validate_license(license_key)
+
+# Get user's licenses
+licenses = client.get_user_licenses
+
+# Create a new license
+license = client.create_license(user_id, features, expires)
+
+# Update a license
+license = client.update_license(license_key, updates)
+
+# Revoke a license
+client.revoke_license(license_key)
+
+# Extend a license
+license = client.extend_license(license_key, days)
+```
+
+##### Hardware ID Management
+
+```ruby
+# Get hardware ID
+hardware_id = client.get_hardware_id
+
+# Validate hardware ID
+is_valid = client.validate_hardware_id(license_key, hardware_id)
+
+# Bind hardware ID to license
+client.bind_hardware_id(license_key, hardware_id)
+```
+
+##### Webhook Management
+
+```ruby
+# Set webhook handler
+client.set_webhook_handler(handler)
+
+# Start webhook listener
+client.start_webhook_listener
+
+# Stop webhook listener
+client.stop_webhook_listener
+```
+
+##### Analytics
+
+```ruby
+# Track event
+client.track_event(event_name, properties)
+
+# Get analytics data
+analytics = client.get_analytics(time_range)
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+Set these in your environment or through your build process:
+
+```bash
+# Required
+export LICENSECHAIN_API_KEY=your-api-key
+export LICENSECHAIN_APP_NAME=your-app-name
+export LICENSECHAIN_APP_VERSION=1.0.0
+
+# Optional
+export LICENSECHAIN_BASE_URL=https://api.licensechain.app/v1
+export LICENSECHAIN_DEBUG=true
+```
+
+### Advanced Configuration
+
+```ruby
+client = LicenseChain::Client.new(
+  api_key: 'your-api-key',
+  app_name: 'your-app-name',
+  version: '1.0.0',
+  base_url: 'https://api.licensechain.app/v1',
+  timeout: 30,        # Request timeout in seconds
+  retries: 3,         # Number of retry attempts
+  debug: false,       # Enable debug logging
+  user_agent: 'MyApp/1.0.0'  # Custom user agent
+)
+```
+
+## 🛡️ Security Features
+
+### Hardware ID Protection
+
+The SDK automatically generates and manages hardware IDs to prevent license sharing:
+
+```ruby
+# Hardware ID is automatically generated and stored
+hardware_id = client.get_hardware_id
+
+# Validate against license
+is_valid = client.validate_hardware_id(license_key, hardware_id)
+```
+
+### Secure Communication
+
+- All API requests use HTTPS
+- API keys are securely stored and transmitted
+- Session tokens are automatically managed
+- Webhook signatures are verified
+
+### License Validation
+
+- Real-time license validation
+- Hardware ID binding
+- Expiration checking
+- Feature-based access control
+
+## 📊 Analytics and Monitoring
+
+### Event Tracking
+
+```ruby
+# Track custom events
+client.track_event('app.started', {
+  level: 1,
+  playerCount: 10
+})
+
+# Track license events
+client.track_event('license.validated', {
+  licenseKey: 'LICENSE-KEY',
+  features: 'premium,unlimited'
+})
+```
+
+### Performance Monitoring
+
+```ruby
+# Get performance metrics
+metrics = client.get_performance_metrics
+puts "API Response Time: #{metrics.average_response_time}ms"
+puts "Success Rate: #{(metrics.success_rate * 100).round(2)}%"
+puts "Error Count: #{metrics.error_count}"
+```
+
+## 🔄 Error Handling
+
+### Custom Exception Types
+
+```ruby
+begin
+  license = client.validate_license('invalid-key')
+rescue LicenseChain::InvalidLicenseError
+  puts "License key is invalid"
+rescue LicenseChain::ExpiredLicenseError
+  puts "License has expired"
+rescue LicenseChain::NetworkError => e
+  puts "Network connection failed: #{e.message}"
+rescue LicenseChain::LicenseChainError => e
+  puts "LicenseChain error: #{e.message}"
+end
+```
+
+### Retry Logic
+
+```ruby
+# Automatic retry for network errors
+client = LicenseChain::Client.new(
+  api_key: 'your-api-key',
+  app_name: 'your-app-name',
+  version: '1.0.0',
+  retries: 3,        # Retry up to 3 times
+  timeout: 30        # Wait 30 seconds for each request
+)
+```
+
+## 🧪 Testing
+
+### Unit Tests
+
+```bash
+# Run tests
+rspec
+
+# Run tests with coverage
+rspec --format documentation
+
+# Run specific test
+rspec spec/client_spec.rb
+```
+
+### Integration Tests
+
+```bash
+# Test with real API
+rspec spec/integration/
+```
+
+## License assertion JWT (RS256 + JWKS)
+
+When Core API returns **`license_token`** and **`license_jwks_uri`**, verify offline with **`LicenseChain::LicenseAssertion.verify_license_assertion_jwt`** (`jwt` gem + JWKS fetch; claim **`token_use`** = **`licensechain_license_v1`**). A minimal **JWKS-only** CLI (no prior `verify` call in-process) is **[`examples/jwks_only.rb`](examples/jwks_only.rb)** — set **`LICENSECHAIN_LICENSE_TOKEN`** and **`LICENSECHAIN_LICENSE_JWKS_URI`** (optional **`LICENSECHAIN_EXPECTED_APP_ID`**), then `ruby examples/jwks_only.rb` (same env names as Go/Rust/PHP; [JWKS_EXAMPLE_PRIORITY](https://docs.licensechain.app/)).
+
+## 📝 Examples
+
+See the `examples/` directory for complete examples:
+
+- `basic_usage.rb` - Basic SDK usage
+- `advanced_features.rb` - Advanced features and configuration
+- `webhook_integration.rb` - Webhook handling
+- `jwks_only.rb` — RS256 `license_token` via JWKS only ([JWKS_EXAMPLE_PRIORITY](https://docs.licensechain.app/))
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Clone the repository
+2. Install Ruby 3.0 or later
+3. Install dependencies: `bundle install`
+4. Build: `gem build licensechain-sdk.gemspec`
+5. Test: `rspec`
+
+## 📄 License
+
+This project is licensed under the Elastic License 2.0 (ELv2) — see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- **Documentation**: [https://docs.licensechain.app/ruby](https://docs.licensechain.app/ruby)
+- **Issues**: [GitHub Issues](https://github.com/LicenseChain/LicenseChain-Ruby-SDK/issues)
+- **Discord**: [LicenseChain Discord](https://discord.gg/licensechain)
+- **Email**: support@licensechain.app
+
+## 🔗 Related Projects
+
+- [LicenseChain JavaScript SDK](https://github.com/LicenseChain/LicenseChain-JavaScript-SDK)
+- [LicenseChain Python SDK](https://github.com/LicenseChain/LicenseChain-Python-SDK)
+- [LicenseChain Node.js SDK](https://github.com/LicenseChain/LicenseChain-NodeJS-SDK)
+---
+
+**Made with ❤️ for the Ruby community**
+
+## LicenseChain API (v1)
+
+This SDK targets the **LicenseChain HTTP API v1** implemented by the LicenseChain API service.
+
+- **Production base URL:** https://api.licensechain.app/v1
+- **API reference:** [docs.licensechain.app](https://docs.licensechain.app/)
+- **Baseline REST mapping (documented for integrators):**
+  - GET /health
+  - POST /auth/register
+  - POST /licenses/verify
+  - PATCH /licenses/:id/revoke
+  - PATCH /licenses/:id/activate
+  - PATCH /licenses/:id/extend
+  - GET /analytics/stats
+

data/ROADMAP.md

@@ -0,0 +1,13 @@
+# LicenseChain Ruby SDK Roadmap
+
+## Current Focus
+
+- Keep default API base aligned with `https://api.licensechain.app/v1`.
+- Maintain `verify_with_details` and JWT/JWKS helper compatibility.
+- Preserve contract parity for verification responses and license assertions.
+
+## Next Operational Tasks
+
+- Re-run conformance after Core API contract updates.
+- Keep docs links and examples synchronized with canonical docs.
+- Record release-impacting changes in `CHANGELOG.md`.

data/examples/basic_usage.rb

@@ -0,0 +1,190 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/licensechain_ruby_sdk'
+
+# Configure the SDK
+LicenseChainRubySdk.configure do |config|
+  config.api_key = 'your-api-key-here'
+  config.base_url = 'https://api.licensechain.app/v1'
+  config.timeout = 30
+  config.retries = 3
+end
+
+# Initialize the client
+client = LicenseChainRubySdk.client
+
+puts "🚀 LicenseChain Ruby SDK - Basic Usage Example\n"
+
+begin
+  # 1. License Management
+  puts "🔑 License Management:"
+  
+  # Create a license
+  metadata = {
+    'platform' => 'ruby',
+    'version' => '1.0.0',
+    'features' => ['validation', 'webhooks']
+  }
+  
+  license = client.licenses.create('user123', 'product456', metadata)
+  puts "✅ License created: #{license.id}"
+  puts "   License Key: #{license.license_key}"
+  puts "   Status: #{license.status}"
+  
+  # Validate a license
+  license_key = LicenseChain::Utils.generate_license_key
+  puts "\n🔍 Validating license key: #{license_key}"
+  
+  is_valid = client.licenses.validate(license_key)
+  if is_valid
+    puts "✅ License is valid"
+  else
+    puts "❌ License is invalid"
+  end
+  
+  # Get license stats
+  stats = client.licenses.stats
+  puts "\n📊 License Statistics:"
+  puts "   Total: #{stats.total}"
+  puts "   Active: #{stats.active}"
+  puts "   Expired: #{stats.expired}"
+  puts "   Revenue: $#{stats.revenue}"
+  
+  # 2. User Management
+  puts "\n👤 User Management:"
+  
+  # Create a user
+  user_metadata = {
+    'source' => 'ruby-sdk',
+    'plan' => 'premium'
+  }
+  
+  user = client.users.create('user@example.com', 'John Doe', user_metadata)
+  puts "✅ User created: #{user.id}"
+  puts "   Email: #{user.email}"
+  puts "   Name: #{user.name}"
+  
+  # Get user stats
+  user_stats = client.users.stats
+  puts "\n📊 User Statistics:"
+  puts "   Total: #{user_stats.total}"
+  puts "   Active: #{user_stats.active}"
+  puts "   Inactive: #{user_stats.inactive}"
+  
+  # 3. Product Management
+  puts "\n📦 Product Management:"
+  
+  # Create a product
+  product_metadata = {
+    'category' => 'software',
+    'tags' => ['premium', 'enterprise']
+  }
+  
+  product = client.products.create(
+    'My Software Product',
+    'A great software product',
+    99.99,
+    'USD',
+    product_metadata
+  )
+  puts "✅ Product created: #{product.id}"
+  puts "   Name: #{product.name}"
+  puts "   Price: $#{product.price} #{product.currency}"
+  
+  # Get product stats
+  product_stats = client.products.stats
+  puts "\n📊 Product Statistics:"
+  puts "   Total: #{product_stats.total}"
+  puts "   Active: #{product_stats.active}"
+  puts "   Revenue: $#{product_stats.revenue}"
+  
+  # 4. Webhook Management
+  puts "\n🔗 Webhook Management:"
+  
+  # Create a webhook
+  events = [
+    LicenseChain::WebhookEvents::LICENSE_CREATED,
+    LicenseChain::WebhookEvents::LICENSE_UPDATED,
+    LicenseChain::WebhookEvents::USER_CREATED
+  ]
+  
+  webhook = client.webhooks.create('https://example.com/webhook', events, 'webhook-secret')
+  puts "✅ Webhook created: #{webhook.id}"
+  puts "   URL: #{webhook.url}"
+  puts "   Events: #{webhook.events.join(', ')}"
+  
+  # 5. Webhook Processing
+  puts "\n🔄 Webhook Processing:"
+  
+  webhook_handler = LicenseChain::WebhookHandler.new('webhook-secret')
+  
+  # Simulate a webhook event
+  webhook_event = {
+    id: 'evt_123',
+    type: LicenseChain::WebhookEvents::LICENSE_CREATED,
+    data: {
+      id: 'lic_123',
+      user_id: 'user_123',
+      product_id: 'prod_123',
+      license_key: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345',
+      status: 'active',
+      created_at: '2023-01-01T00:00:00Z'
+    },
+    timestamp: '2023-01-01T00:00:00Z',
+    signature: 'signature_here'
+  }
+  
+  webhook_handler.process_event(webhook_event)
+  puts "✅ Webhook event processed successfully"
+  
+  # 6. Utility Functions
+  puts "\n🛠️ Utility Functions:"
+  
+  # Email validation
+  email = 'test@example.com'
+  puts "Email '#{email}' is valid: #{LicenseChain::Utils.validate_email(email)}"
+  
+  # License key validation
+  license_key = LicenseChain::Utils.generate_license_key
+  puts "License key '#{license_key}' is valid: #{LicenseChain::Utils.validate_license_key(license_key)}"
+  
+  # Generate UUID
+  uuid = LicenseChain::Utils.generate_uuid
+  puts "Generated UUID: #{uuid}"
+  
+  # Format bytes
+  bytes = 1024 * 1024
+  puts "#{bytes} bytes = #{LicenseChain::Utils.format_bytes(bytes)}"
+  
+  # Format duration
+  seconds = 3661
+  puts "Duration: #{LicenseChain::Utils.format_duration(seconds)}"
+  
+  # String utilities
+  text = 'Hello World'
+  puts "Capitalize first: #{LicenseChain::Utils.capitalize_first(text)}"
+  puts "To snake_case: #{LicenseChain::Utils.to_snake_case('HelloWorld')}"
+  puts "To PascalCase: #{LicenseChain::Utils.to_pascal_case('hello_world')}"
+  puts "Slugify: #{LicenseChain::Utils.slugify('Hello World!')}"
+  
+  # 7. Error Handling
+  puts "\n🛡️ Error Handling:"
+  
+  begin
+    client.licenses.get('invalid-id')
+  rescue LicenseChain::ValidationError => e
+    puts "✅ Caught expected validation error: #{e.message}"
+  end
+  
+  begin
+    client.users.create('invalid-email', 'John Doe')
+  rescue LicenseChain::ValidationError => e
+    puts "✅ Caught expected validation error: #{e.message}"
+  end
+  
+  puts "\n✅ Basic usage example completed successfully!"
+  
+rescue => e
+  puts "❌ Error: #{e.class} - #{e.message}"
+  puts e.backtrace if ENV['DEBUG']
+end

data/examples/jwks_only.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# JWKS-only: verify license_token with token + JWKS URI (parity with Go/Rust/PHP jwks_only).
+#   export LICENSECHAIN_LICENSE_TOKEN="eyJ..."
+#   export LICENSECHAIN_LICENSE_JWKS_URI="https://api.licensechain.app/v1/licenses/jwks"
+#   # optional: LICENSECHAIN_EXPECTED_APP_ID=<uuid>
+#   ruby examples/jwks_only.rb
+
+require 'json'
+require_relative '../lib/licensechain_ruby_sdk'
+
+token = ENV.fetch('LICENSECHAIN_LICENSE_TOKEN', '').strip
+jwks = ENV.fetch('LICENSECHAIN_LICENSE_JWKS_URI', '').strip
+if token.empty? || jwks.empty?
+  warn 'Set LICENSECHAIN_LICENSE_TOKEN and LICENSECHAIN_LICENSE_JWKS_URI'
+  exit 1
+end
+
+opts = {}
+app = ENV['LICENSECHAIN_EXPECTED_APP_ID']&.strip
+opts[:expected_app_id] = app unless app.nil? || app.empty?
+
+payload = LicenseChain::LicenseAssertion.verify_license_assertion_jwt(token, jwks, **opts)
+puts JSON.pretty_generate(payload)