source_license_sdk 1.0.0

data/README.md

@@ -0,0 +1,329 @@
+# Source-License Ruby SDK
+
+A Ruby gem for easy integration with the Source-License platform for license validation and activation.
+
+## Features
+
+- **Simple License Validation**: Check if a license key is valid with one method call
+- **License Activation**: Activate licenses on specific machines with automatic machine fingerprinting
+- **License Enforcement**: Automatically exit your application if license validation fails
+- **Rate Limiting Handling**: Built-in handling of API rate limits with retry information
+- **Secure Communication**: Uses HTTPS and handles all Source-License API security requirements
+- **Cross-Platform Machine Identification**: Works on Windows, macOS, and Linux
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'source_license_sdk'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install source_license_sdk
+```
+
+## Quick Start
+
+### Basic Setup
+
+```ruby
+require 'source_license_sdk'
+
+# Configure the SDK
+SourceLicenseSDK.setup(
+  server_url: 'https://your-license-server.com',
+  license_key: 'YOUR-LICENSE-KEY',
+  machine_id: 'unique-machine-identifier' # Optional, will auto-generate if not provided
+)
+```
+
+### Method 1: License Validation
+
+Check if a license is valid without activating it:
+
+```ruby
+result = SourceLicenseSDK.validate_license
+
+if result.valid?
+  puts "License is valid!"
+  puts "Expires at: #{result.expires_at}" if result.expires_at
+else
+  puts "License validation failed: #{result.error_message}"
+end
+```
+
+### Method 2: License Activation
+
+Activate a license on the current machine:
+
+```ruby
+result = SourceLicenseSDK.activate_license
+
+if result.success?
+  puts "License activated successfully!"
+  puts "Activations remaining: #{result.activations_remaining}"
+else
+  puts "Activation failed: #{result.error_message}"
+end
+```
+
+### Method 3: License Enforcement
+
+Automatically exit the application if license validation fails:
+
+```ruby
+# This will exit the program with code 1 if the license is invalid
+SourceLicenseSDK.enforce_license!
+
+# Your application code continues here only if license is valid
+puts "Application starting with valid license..."
+```
+
+## Advanced Usage
+
+### Custom Configuration
+
+```ruby
+SourceLicenseSDK.configure do |config|
+  config.server_url = 'https://your-license-server.com'
+  config.license_key = 'YOUR-LICENSE-KEY'
+  config.machine_id = 'custom-machine-id'
+  config.timeout = 30
+  config.verify_ssl = true
+  config.user_agent = 'MyApp/1.0.0'
+end
+```
+
+### Manual Machine ID Generation
+
+```ruby
+# Generate a unique machine identifier
+machine_id = SourceLicenseSDK::MachineIdentifier.generate
+puts "Machine ID: #{machine_id}"
+
+# Generate a machine fingerprint (more detailed)
+fingerprint = SourceLicenseSDK::MachineIdentifier.generate_fingerprint
+puts "Machine Fingerprint: #{fingerprint}"
+```
+
+### Error Handling
+
+```ruby
+begin
+  result = SourceLicenseSDK.validate_license
+  
+  if result.valid?
+    puts "License is valid"
+  else
+    puts "License invalid: #{result.error_message}"
+  end
+rescue SourceLicenseSDK::NetworkError => e
+  puts "Network error: #{e.message} (Code: #{e.response_code})"
+rescue SourceLicenseSDK::RateLimitError => e
+  puts "Rate limited. Retry after #{e.retry_after} seconds"
+rescue SourceLicenseSDK::ConfigurationError => e
+  puts "Configuration error: #{e.message}"
+end
+```
+
+### Working with Results
+
+```ruby
+result = SourceLicenseSDK.validate_license
+
+# Check various result properties
+puts "Valid: #{result.valid?}"
+puts "Expires at: #{result.expires_at}"
+puts "Rate limited: #{result.rate_limited?}"
+puts "Rate limit remaining: #{result.rate_limit_remaining}"
+puts "Error code: #{result.error_code}" if result.error_code
+
+# Convert to hash
+puts result.to_h
+```
+
+### Custom License Enforcement
+
+```ruby
+# Custom exit code and message
+SourceLicenseSDK.enforce_license!(
+  exit_code: 2,
+  custom_message: "This software requires a valid license to run."
+)
+
+# Use specific license key and machine ID
+SourceLicenseSDK.enforce_license!(
+  'SPECIFIC-LICENSE-KEY',
+  machine_id: 'specific-machine-id'
+)
+```
+
+## Integration Examples
+
+### Ruby on Rails Application
+
+```ruby
+# config/initializers/source_license.rb
+SourceLicenseSDK.setup(
+  server_url: Rails.application.credentials.license_server_url,
+  license_key: Rails.application.credentials.license_key
+)
+
+# In your application controller or concern
+class ApplicationController < ActionController::Base
+  before_action :validate_license
+
+  private
+
+  def validate_license
+    result = SourceLicenseSDK.validate_license
+    
+    unless result.valid?
+      render json: { error: 'Invalid license' }, status: :forbidden
+    end
+  end
+end
+```
+
+### Command Line Tool
+
+```ruby
+#!/usr/bin/env ruby
+require 'source_license_sdk'
+
+# Setup license checking
+SourceLicenseSDK.setup(
+  server_url: 'https://license.mycompany.com',
+  license_key: ARGV[0] || ENV['LICENSE_KEY']
+)
+
+# Enforce license before running
+SourceLicenseSDK.enforce_license!(
+  custom_message: "Please provide a valid license key to use this tool."
+)
+
+# Your application logic here
+puts "Tool is running with valid license!"
+```
+
+### Desktop Application
+
+```ruby
+require 'source_license_sdk'
+
+class MyApplication
+  def initialize
+    setup_licensing
+  end
+
+  private
+
+  def setup_licensing
+    SourceLicenseSDK.setup(
+      server_url: 'https://licensing.myapp.com',
+      license_key: load_license_key,
+      auto_generate_machine_id: true
+    )
+
+    # Try to activate license if not already done
+    activate_license_if_needed
+    
+    # Validate license on startup
+    validate_license!
+  end
+
+  def load_license_key
+    # Load from config file, registry, etc.
+    File.read('license.key').strip
+  rescue
+    nil
+  end
+
+  def activate_license_if_needed
+    result = SourceLicenseSDK.validate_license
+    
+    unless result.valid?
+      puts "Activating license..."
+      activation_result = SourceLicenseSDK.activate_license
+      
+      unless activation_result.success?
+        puts "Failed to activate license: #{activation_result.error_message}"
+        exit 1
+      end
+    end
+  end
+
+  def validate_license!
+    SourceLicenseSDK.enforce_license!(
+      custom_message: "This application requires a valid license."
+    )
+  end
+end
+```
+
+## Error Types
+
+The SDK defines several exception types for different error scenarios:
+
+- `SourceLicenseSDK::ConfigurationError` - Invalid SDK configuration
+- `SourceLicenseSDK::NetworkError` - HTTP/network related errors  
+- `SourceLicenseSDK::LicenseError` - General license validation errors
+- `SourceLicenseSDK::RateLimitError` - API rate limiting errors
+- `SourceLicenseSDK::LicenseNotFoundError` - License not found
+- `SourceLicenseSDK::LicenseExpiredError` - License has expired
+- `SourceLicenseSDK::ActivationError` - License activation errors
+- `SourceLicenseSDK::MachineError` - Machine identification errors
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `server_url` | String | nil | Source-License server URL (required) |
+| `license_key` | String | nil | License key to validate/activate |
+| `machine_id` | String | nil | Unique machine identifier |
+| `auto_generate_machine_id` | Boolean | true | Auto-generate machine ID if not provided |
+| `timeout` | Integer | 30 | HTTP request timeout in seconds |
+| `user_agent` | String | "SourceLicenseSDK/VERSION" | HTTP User-Agent header |
+| `verify_ssl` | Boolean | true | Verify SSL certificates |
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+```
+
+To build and install the gem locally:
+
+```bash
+gem build source_license_sdk.gemspec
+gem install source_license_sdk-*.gem
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+This gem is available as open source under the terms of the [GPL-3.0 License](LICENSE).
+
+## Support
+
+For support with this SDK, please open an issue on the [Source-License repository](https://github.com/PixelRidgeSoftworks/Source-License).
+
+For general Source-License platform support, please contact your license provider.

data/Rakefile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+task default: :build

data/lib/source_license_sdk/client.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+# HTTP client for communicating with Source-License API
+class SourceLicenseSDK::Client
+  attr_reader :config
+
+  def initialize(config)
+    @config = config
+    validate_config!
+  end
+
+  # Validate a license key
+  def validate_license(license_key, machine_id: nil, machine_fingerprint: nil)
+    machine_fingerprint ||= MachineIdentifier.generate_fingerprint if machine_id
+
+    path = "/api/license/#{license_key}/validate"
+    params = {}
+    params[:machine_id] = machine_id if machine_id
+    params[:machine_fingerprint] = machine_fingerprint if machine_fingerprint
+
+    response = make_request(:get, path, params: params)
+    LicenseValidationResult.new(response)
+  rescue NetworkError => e
+    handle_network_error(e)
+  end
+
+  # Activate a license on this machine
+  def activate_license(license_key, machine_id:, machine_fingerprint: nil)
+    machine_fingerprint ||= MachineIdentifier.generate_fingerprint
+
+    path = "/api/license/#{license_key}/activate"
+    body = {
+      machine_id: machine_id,
+      machine_fingerprint: machine_fingerprint,
+    }
+
+    response = make_request(:post, path, body: body)
+    LicenseValidationResult.new(response)
+  rescue NetworkError => e
+    handle_network_error(e)
+  end
+
+  private
+
+  def validate_config!
+    raise ConfigurationError, 'Server URL is required' unless config.server_url
+    raise ConfigurationError, 'Invalid server URL format' unless valid_url?(config.server_url)
+  end
+
+  def valid_url?(url)
+    uri = URI.parse(url)
+    uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+  rescue URI::InvalidURIError
+    false
+  end
+
+  def make_request(method, path, params: {}, body: nil)
+    uri = build_uri(path, params)
+    http = create_http_client(uri)
+    request = create_request(method, uri, body)
+
+    response = http.request(request)
+    handle_response(response)
+  end
+
+  def build_uri(path, params = {})
+    base_uri = URI.parse(config.server_url)
+    base_uri.path = path
+
+    base_uri.query = URI.encode_www_form(params) if params.any?
+
+    base_uri
+  end
+
+  def create_http_client(uri)
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == 'https'
+    http.verify_mode = config.verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+    http.read_timeout = config.timeout
+    http.open_timeout = config.timeout
+    http
+  end
+
+  def create_request(method, uri, body)
+    request_class = case method
+                    when :get then Net::HTTP::Get
+                    when :post then Net::HTTP::Post
+                    when :put then Net::HTTP::Put
+                    when :delete then Net::HTTP::Delete
+                    else raise ArgumentError, "Unsupported HTTP method: #{method}"
+                    end
+
+    request = request_class.new(uri)
+    request['User-Agent'] = config.user_agent
+    request['Accept'] = 'application/json'
+    request['Content-Type'] = 'application/json' if body
+
+    if body
+      request.body = body.is_a?(String) ? body : JSON.generate(body)
+    end
+
+    request
+  end
+
+  def handle_response(response)
+    case response.code.to_i
+    when 200..299
+      parse_json_response(response.body)
+    when 400
+      data = parse_json_response(response.body)
+      raise_license_error(data, response.code.to_i)
+    when 404
+      data = parse_json_response(response.body)
+      raise LicenseNotFoundError, data['error'] || 'License not found'
+    when 429
+      data = parse_json_response(response.body)
+      retry_after = response['Retry-After']&.to_i || data['retry_after']
+      raise RateLimitError.new(data['error'] || 'Rate limit exceeded', retry_after: retry_after)
+    when 500..599
+      raise NetworkError.new('Server error occurred', response_code: response.code.to_i, response_body: response.body)
+    else
+      raise NetworkError.new("Unexpected response: #{response.code}", response_code: response.code.to_i,
+                                                                      response_body: response.body)
+    end
+  end
+
+  def parse_json_response(body)
+    return {} if body.nil? || body.empty?
+
+    JSON.parse(body)
+  rescue JSON::ParserError
+    raise NetworkError.new('Invalid JSON response from server', response_body: body)
+  end
+
+  def raise_license_error(data, _status_code)
+    error_message = data['error'] || data['message'] || 'License validation failed'
+
+    case error_message.downcase
+    when /expired/
+      raise LicenseExpiredError, error_message
+    when /rate limit/
+      retry_after = data['retry_after']
+      raise RateLimitError.new(error_message, retry_after: retry_after)
+    when /not found/
+      raise LicenseNotFoundError, error_message
+    when /activation/
+      raise ActivationError, error_message
+    else
+      raise LicenseError.new(error_message, error_code: data['error_code'])
+    end
+  end
+
+  def handle_network_error(error)
+    # Convert network errors to license validation results for consistency
+    case error
+    when RateLimitError
+      LicenseValidationResult.new(
+        valid: false,
+        success: false,
+        error: error.message,
+        error_code: error.error_code,
+        retry_after: error.retry_after
+      )
+    when LicenseNotFoundError, LicenseExpiredError, ActivationError
+      LicenseValidationResult.new(
+        valid: false,
+        success: false,
+        error: error.message,
+        error_code: error.error_code
+      )
+    else
+      # Re-raise other network errors
+      raise error
+    end
+  end
+end

data/lib/source_license_sdk/exceptions.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SourceLicenseSDK
+  # Base exception class for all SDK errors
+  class Error < StandardError; end
+
+  # Configuration related errors
+  class ConfigurationError < Error; end
+
+  # Network and HTTP related errors
+  class NetworkError < Error
+    attr_reader :response_code, :response_body
+
+    def initialize(message, response_code: nil, response_body: nil)
+      super(message)
+      @response_code = response_code
+      @response_body = response_body
+    end
+  end
+
+  # License validation errors
+  class LicenseError < Error
+    attr_reader :error_code, :retry_after
+
+    def initialize(message, error_code: nil, retry_after: nil)
+      super(message)
+      @error_code = error_code
+      @retry_after = retry_after
+    end
+  end
+
+  # Rate limiting errors
+  class RateLimitError < LicenseError
+    def initialize(message = 'Rate limit exceeded', retry_after: nil)
+      super(message, error_code: 'RATE_LIMIT_EXCEEDED', retry_after: retry_after)
+    end
+  end
+
+  # License not found errors
+  class LicenseNotFoundError < LicenseError
+    def initialize(message = 'License not found')
+      super(message, error_code: 'LICENSE_NOT_FOUND')
+    end
+  end
+
+  # License expired errors
+  class LicenseExpiredError < LicenseError
+    def initialize(message = 'License has expired')
+      super(message, error_code: 'LICENSE_EXPIRED')
+    end
+  end
+
+  # License activation errors
+  class ActivationError < LicenseError
+    def initialize(message, error_code: 'ACTIVATION_FAILED')
+      super
+    end
+  end
+
+  # Machine ID related errors
+  class MachineError < Error; end
+end

data/lib/source_license_sdk/license_validator.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# Represents the result of a license validation or activation request
+class SourceLicenseSDK::LicenseValidationResult
+  attr_reader :valid, :success, :error_message, :error_code, :expires_at,
+              :activations_remaining, :retry_after, :token, :timestamp,
+              :rate_limit_remaining, :rate_limit_reset_at
+
+  def initialize(data)
+    @data = data
+
+    initialize_validation_fields
+    initialize_activation_fields
+    initialize_common_fields
+    initialize_rate_limit_fields
+  end
+
+  def valid?
+    @valid == true
+  end
+
+  def success?
+    @success == true
+  end
+
+  def expired?
+    return false unless @expires_at
+
+    @expires_at < Time.now
+  end
+
+  def rate_limited?
+    @error_message&.downcase&.include?('rate limit') ||
+      @error_code == 'RATE_LIMIT_EXCEEDED'
+  end
+
+  def to_h
+    {
+      valid: @valid,
+      success: @success,
+      error_message: @error_message,
+      error_code: @error_code,
+      expires_at: @expires_at,
+      activations_remaining: @activations_remaining,
+      retry_after: @retry_after,
+      token: @token,
+      timestamp: @timestamp,
+      rate_limit_remaining: @rate_limit_remaining,
+      rate_limit_reset_at: @rate_limit_reset_at,
+    }
+  end
+
+  def inspect
+    "#<#{self.class.name} valid=#{@valid} success=#{@success} error='#{@error_message}'>"
+  end
+
+  private
+
+  def initialize_validation_fields
+    @valid = extract_value(:valid, false)
+    @token = extract_value(:token)
+  end
+
+  def initialize_activation_fields
+    @success = extract_value(:success, false)
+    @activations_remaining = extract_value(:activations_remaining)
+  end
+
+  def initialize_common_fields
+    @error_message = extract_error_message
+    @error_code = extract_value(:error_code)
+    @expires_at = parse_datetime(extract_value(:expires_at))
+    @retry_after = extract_value(:retry_after)
+    @timestamp = parse_datetime(extract_value(:timestamp))
+  end
+
+  def initialize_rate_limit_fields
+    @rate_limit_remaining = extract_rate_limit_value(:remaining)
+    @rate_limit_reset_at = parse_datetime(extract_rate_limit_value(:reset_at))
+  end
+
+  def extract_value(key, default = nil)
+    @data[key] || @data[key.to_s] || default
+  end
+
+  def extract_error_message
+    extract_value(:error) || extract_value(:message)
+  end
+
+  def extract_rate_limit_value(key)
+    @data[:rate_limit]&.dig(key) || @data['rate_limit']&.dig(key.to_s)
+  end
+
+  def parse_datetime(value)
+    return nil if value.nil?
+    return value if value.is_a?(Time)
+    return Time.at(value) if value.is_a?(Numeric)
+
+    Time.parse(value.to_s)
+  rescue ArgumentError
+    nil
+  end
+end