stellwerk-ruby 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 796b4095b7fea502bbfacb3e03aa62ab11fd85234c69e5ee2ebd867e82b1586b
-  data.tar.gz: ef32afa830843674ef9e83175538181c087910be20fd7b9406a927ee192f1bd7
+  metadata.gz: 53518cb9a1c9f94bd19252dcecf8fce62e4cc808e926ee51bf05dd5aa93a3826
+  data.tar.gz: '0797c9b22de3cc4fdd6cdea65b117abd90437b9c80703577060e2765ccf0d2ca'
 SHA512:
-  metadata.gz: 882b4adabe5be8af497114eefbd7e0454c145de3b98235de44e77db01e40e588fb56ffc21bc2741ba307cf4b2987a8b5ad6d4d6525ef6c394e1813f7cedb2c70
-  data.tar.gz: 9ed76a0cfc751cb41fcc46c02d2a2fb97e48dcc0ac24ed8570bbe5bb5cbfddf8fdb762d125356db014e5ba963e9f35f442e0b6b7b24f43eac2aaf2f1f0fbb55d
+  metadata.gz: 169634b2e34156ab8f7742611fdf8739973b94be79c6458aa5b7bda06b7e8c42ec54d358e9e0fd44b683b6b6e3e34eff51bf0b23c1b1907dde72feebf1af9663
+  data.tar.gz: a196cf2f9ec2f44238af3d90d68838d5d0fdc36b4df47b5895b97100dc86f77d1e8b2ec9d029016ce09dcebfe746ce1be3a7ee198e09983bfb6f6f73a0d26968

data/CHANGELOG.md

@@ -5,6 +5,53 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-02-02
+
+### Changed
+
+- Updated default API URL to `https://stellwerk.io`
+- Updated license validation endpoint to `POST /api/v1/sdk/validate`
+- Updated API response parsing to use `limits.monthly_executions` and `limits.current_count`
+
+### Added
+
+- `verify_ssl` configuration option to disable SSL verification for development
+
+## [0.2.0] - 2026-02-01
+
+### Added
+
+- **License validation**: API key required for all flow executions
+  - Lazy validation on first execution with result caching
+  - Configurable cache TTL from server response
+- **Execution metering**: Track and report flow executions
+  - Batch reporting at configurable intervals (default: 60 seconds)
+  - Automatic sync with Stellwerk API
+- **Offline grace period**: Continue operating when server is unreachable
+  - Default: 24 hours or 100 executions
+  - Configurable via `offline_grace_period` and `offline_grace_executions`
+- **New configuration options**:
+  - `api_key` - Required API key for license validation
+  - `api_url` - API endpoint (default: https://stellwerk.io)
+  - `sync_interval` - Batch reporting interval in seconds
+  - `offline_grace_period` - Offline operation allowance in seconds
+  - `offline_grace_executions` - Max offline executions
+- **New error classes**:
+  - `LicenseError` - Raised when API key is missing or invalid
+  - `QuotaExceededError` - Raised when execution limit is reached
+  - `ApiError` - Raised on server communication failures
+- **New helper methods**:
+  - `Stellwerk.licensed?` - Check if SDK is properly licensed
+  - `Stellwerk.license` - Access license details (plan, limits, usage)
+  - `Stellwerk.metering` - Access metering system
+- Thread-safe license and metering implementations using Mutex
+
+### Changed
+
+- `Stellwerk.configure` now yields a `Configuration` object instead of the module
+- `Flow#execute` now enforces license validation and tracks executions
+- Improved documentation with comprehensive troubleshooting guide
+
 ## [0.1.0] - 2026-01-31
 
 ### Added

data/README.md

@@ -2,6 +2,12 @@
 
 A standalone Ruby gem for evaluating pre-compiled Stellwerk flows without any Rails or ActiveRecord dependencies.
 
+## What is Stellwerk?
+
+[Stellwerk](https://stellwerk.io) is a visual platform for building decision flows and business logic without code. Design complex calculations, conditional branching, and data transformations using an intuitive drag-and-drop interface, then export your flows as compiled JSON to run anywhere.
+
+This gem lets you execute those compiled flows in any Ruby application.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -22,55 +28,209 @@ Or install it yourself as:
 gem install stellwerk-ruby
 ```
 
-## Usage
-
-### Simple Usage
+## Quick Start
 
 ```ruby
 require 'stellwerk'
 
-# Load a compiled flow from a JSON file
-flow = Stellwerk::Flow.load('pricing.compiled.json')
+# Configure your API key (required)
+Stellwerk.configure do |config|
+  config.api_key = ENV['STELLWERK_API_KEY']
+end
 
-# Execute with input parameters
+# Load and execute a flow
+flow = Stellwerk::Flow.load('pricing.compiled.json')
 result = flow.execute(quantity: 10, price: 25.00)
 
 if result.success?
-  puts result.outputs[:total]
+  puts "Total: #{result.outputs[:total]}"
+else
+  puts "Errors: #{result.errors}"
+end
+```
+
+## Configuration
+
+### Required: API Key
+
+All flow executions require a valid API key. Get your key from [stellwerk.io](https://stellwerk.io).
+
+Stellwerk provides two types of API keys:
+
+| Key Type | Prefix | Purpose | Quota |
+|----------|--------|---------|-------|
+| **Test** | `sk_test_...` | Development and testing | Not counted |
+| **Live** | `sk_live_...` | Production use | Counted against plan |
+
+Use test keys during development to avoid consuming your quota. Switch to live keys when deploying to production.
+
+```ruby
+Stellwerk.configure do |config|
+  # Use test key in development, live key in production
+  config.api_key = ENV['STELLWERK_API_KEY']
+end
+
+# Or use the shorthand
+Stellwerk.api_key = ENV['STELLWERK_API_KEY']
+```
+
+**Tip**: Set different environment variables per environment:
+```bash
+# .env.development
+STELLWERK_API_KEY=sk_test_your_test_key
+
+# .env.production
+STELLWERK_API_KEY=sk_live_your_live_key
+```
+
+### Full Configuration Options
+
+```ruby
+Stellwerk.configure do |config|
+  # Required: Your API key from stellwerk.io
+  config.api_key = ENV['STELLWERK_API_KEY']
+
+  # Optional: API endpoint (default: https://stellwerk.io)
+  config.api_url = 'https://stellwerk.io'
+
+  # Optional: Interval for batch reporting executions (default: 60 seconds)
+  config.sync_interval = 60
+
+  # Optional: How long to allow offline operation (default: 86400 = 24 hours)
+  config.offline_grace_period = 86_400
+
+  # Optional: Max executions during offline grace period (default: 100)
+  config.offline_grace_executions = 100
+
+  # Optional: Logger for debugging
+  config.logger = Logger.new(STDOUT)
+end
+```
+
+## Usage Examples
+
+### Basic Execution
+
+```ruby
+flow = Stellwerk::Flow.load('calculator.compiled.json')
+result = flow.execute(x: 10, y: 20)
+
+puts result.outputs[:sum]  # => 30
+```
+
+### Error Handling
+
+```ruby
+flow = Stellwerk::Flow.load('pricing.compiled.json')
+
+begin
+  result = flow.execute(params)
+
+  if result.success?
+    process(result.outputs)
+  else
+    # Flow executed but returned errors (validation, business logic)
+    log_errors(result.errors)
+  end
+rescue Stellwerk::LicenseError => e
+  # API key missing or invalid
+  puts "License error: #{e.message}"
+rescue Stellwerk::QuotaExceededError => e
+  # Execution limit reached
+  puts "Quota exceeded: #{e.message}"
+rescue Stellwerk::ApiError => e
+  # Server communication error
+  puts "API error: #{e.message} (status: #{e.status_code})"
+end
+```
+
+### Batch Processing
+
+```ruby
+flow = Stellwerk::Flow.load('invoice.compiled.json')
+
+invoices.each do |invoice|
+  result = flow.execute(invoice.to_h)
+
+  if result.success?
+    invoice.update!(
+      subtotal: result.outputs[:subtotal],
+      tax: result.outputs[:tax],
+      total: result.outputs[:total]
+    )
+  end
+end
+
+# Executions are batched and reported automatically
+```
+
+### Checking License Status
+
+```ruby
+# Check if properly licensed before processing
+if Stellwerk.licensed?
+  process_flows
 else
-  puts result.errors
+  puts "Please configure a valid API key"
 end
+
+# Access license details
+license = Stellwerk.license
+puts "Plan: #{license.plan}"
+puts "Limit: #{license.execution_limit}"
+puts "Used: #{license.executions_used}"
 ```
 
 ### Direct Evaluator Usage
 
-For more control, you can use the evaluator directly:
+For advanced use cases, you can use the evaluator directly:
 
 ```ruby
-require 'stellwerk'
 require 'json'
 
 json = JSON.parse(File.read('flow.json'))
 result = Stellwerk::Evaluator.call(
   compiled_json: json,
-  params: { x: 10, y: 20 }
+  params: { x: 10, y: 20 },
+  metadata: { source: 'api', user_id: 123 }
 )
 
-puts result.outputs
-puts result.context
-puts result.applied_nodes
+puts result.outputs       # Output values
+puts result.context       # Full execution context
+puts result.applied_nodes # Executed node IDs
 ```
 
-### Configuration
+## Offline Mode
 
-```ruby
-require 'logger'
+If the Stellwerk server becomes unreachable after a successful license validation, the SDK enters an offline grace period:
 
-Stellwerk.configure do |config|
-  config.logger = Logger.new(STDOUT)
+- **Default duration**: 24 hours
+- **Default execution limit**: 100 executions
+
+During offline mode, executions are tracked locally and reported when connectivity is restored.
+
+```ruby
+# Check if operating in offline mode
+if Stellwerk.license.offline?
+  puts "Operating in offline mode"
 end
 ```
 
+## Result Object
+
+Execution returns a `Stellwerk::Result` object:
+
+```ruby
+result = flow.execute(params)
+
+result.success?       # => true/false
+result.failure?       # => true/false
+result.outputs        # => Hash of output values
+result.errors         # => Array of error messages/hashes
+result.applied_nodes  # => Array of executed node IDs
+result.context        # => Full execution context
+```
+
 ## Compiled JSON Format
 
 The gem expects compiled flow JSON in this structure:
@@ -135,21 +295,67 @@ The gem includes collection functions for use in formulas:
 - `SUMIF(array, "predicate", "projection")` - Conditional sum
 - `COUNTIF(array, "predicate")` - Conditional count
 
-## Result Object
+## Troubleshooting
 
-Execution returns a `Stellwerk::Result` object:
+### "API key is required"
+
+You must configure an API key before executing flows:
 
 ```ruby
-result = flow.execute(params)
+Stellwerk.configure do |config|
+  config.api_key = ENV['STELLWERK_API_KEY']
+end
+```
 
-result.success?       # => true/false
-result.failure?       # => true/false
-result.outputs        # => Hash of output values
-result.errors         # => Array of error messages/hashes
-result.applied_nodes  # => Array of executed nodes
-result.context        # => Full execution context
+Get your API key from [stellwerk.io](https://stellwerk.io).
+
+### "Invalid API key"
+
+Your API key is not recognized. Verify:
+- The key is correctly copied (no extra spaces)
+- The key is active in your Stellwerk dashboard
+- You're using the correct key type (`sk_test_...` for development, `sk_live_...` for production)
+
+### "Execution limit reached"
+
+You've exceeded your plan's monthly execution quota. Options:
+- Wait for the next billing cycle
+- Upgrade your plan at [stellwerk.io](https://stellwerk.io)
+
+### "Offline execution limit reached"
+
+During offline mode, you've exceeded the allowed offline executions. Restore network connectivity to continue.
+
+### Debug Mode
+
+Enable logging to see detailed execution information:
+
+```ruby
+Stellwerk.configure do |config|
+  config.api_key = ENV['STELLWERK_API_KEY']
+  config.logger = Logger.new(STDOUT)
+  config.logger.level = Logger::DEBUG
+end
+```
+
+### Flow Validation Errors
+
+If `result.failure?` returns true, check `result.errors` for details:
+
+```ruby
+result = flow.execute(params)
+if result.failure?
+  result.errors.each do |error|
+    puts "Error: #{error}"
+  end
+end
 ```
 
+Common causes:
+- Missing required input parameters
+- Invalid data types
+- Formula evaluation errors
+
 ## Development
 
 After checking out the repo, run:

data/lib/stellwerk/api_client.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "openssl"
+
+module Stellwerk
+  # HTTP client wrapper for Stellwerk API communication
+  #
+  # Uses net/http from Ruby stdlib for zero external dependencies.
+  # Handles authentication, retries, timeouts, and JSON parsing.
+  #
+  class ApiClient
+    # Default timeout for HTTP requests (seconds)
+    DEFAULT_TIMEOUT = 10
+
+    # Maximum total attempts for transient failures (initial + retries)
+    MAX_ATTEMPTS = 3
+
+    # Delay between retries (seconds)
+    RETRY_DELAY = 1
+
+    # @param api_url [String] Base URL for the API
+    # @param api_key [String] API key for authentication
+    # @param timeout [Integer] Request timeout in seconds
+    # @param verify_ssl [Boolean] Whether to verify SSL certificates
+    def initialize(api_url:, api_key:, timeout: DEFAULT_TIMEOUT, verify_ssl: true)
+      @api_url = api_url.chomp("/")
+      @api_key = api_key
+      @timeout = timeout
+      @verify_ssl = verify_ssl
+    end
+
+    # Make a GET request
+    #
+    # @param path [String] API endpoint path
+    # @return [Hash] Parsed JSON response
+    # @raise [ApiError] On request failure
+    def get(path)
+      request(:get, path)
+    end
+
+    # Make a POST request
+    #
+    # @param path [String] API endpoint path
+    # @param body [Hash] Request body (will be JSON encoded)
+    # @return [Hash] Parsed JSON response
+    # @raise [ApiError] On request failure
+    def post(path, body = {})
+      request(:post, path, body)
+    end
+
+    private
+
+    def request(method, path, body = nil)
+      uri = URI.parse("#{@api_url}#{path}")
+      retries = 0
+
+      begin
+        response = execute_request(method, uri, body)
+        handle_response(response)
+      rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, Errno::ENETUNREACH,
+             Net::OpenTimeout, Net::ReadTimeout, SocketError => e
+        retries += 1
+        if retries < MAX_ATTEMPTS
+          sleep(RETRY_DELAY * retries)
+          retry
+        end
+        raise ApiError.new(
+          "Failed to connect to Stellwerk API: #{e.message}",
+          status_code: nil,
+          response_body: nil
+        )
+      end
+    end
+
+    def execute_request(method, uri, body)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.verify_mode = @verify_ssl ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request = build_request(method, uri, body)
+      http.request(request)
+    end
+
+    def build_request(method, uri, body)
+      request_class = method == :get ? Net::HTTP::Get : Net::HTTP::Post
+      request = request_class.new(uri.request_uri)
+
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["User-Agent"] = "stellwerk-ruby/#{Stellwerk::VERSION}"
+
+      request.body = JSON.generate(body) if body && method == :post
+
+      request
+    end
+
+    def handle_response(response)
+      case response.code.to_i
+      when 200..299
+        parse_json(response.body)
+      when 401
+        raise ApiError.new(
+          "Invalid API key",
+          status_code: 401,
+          response_body: response.body
+        )
+      when 403
+        raise ApiError.new(
+          "API key not authorized for this operation",
+          status_code: 403,
+          response_body: response.body
+        )
+      when 429
+        raise ApiError.new(
+          "Rate limit exceeded",
+          status_code: 429,
+          response_body: response.body
+        )
+      when 500..599
+        raise ApiError.new(
+          "Stellwerk API server error",
+          status_code: response.code.to_i,
+          response_body: response.body
+        )
+      else
+        raise ApiError.new(
+          "Unexpected API response: #{response.code}",
+          status_code: response.code.to_i,
+          response_body: response.body
+        )
+      end
+    end
+
+    def parse_json(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise ApiError.new(
+        "Invalid JSON response from API: #{e.message}",
+        status_code: nil,
+        response_body: body
+      )
+    end
+  end
+end

data/lib/stellwerk/configuration.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Stellwerk
+  # Configuration class for Stellwerk SDK settings
+  #
+  # @example
+  #   Stellwerk.configure do |config|
+  #     config.api_key = 'sk_stellwerk_...'
+  #     config.api_url = 'https://stellwerk.io'
+  #   end
+  #
+  class Configuration
+    # API key for license validation and metering
+    # @return [String, nil]
+    attr_accessor :api_key
+
+    # Base URL for the Stellwerk API
+    # @return [String]
+    attr_accessor :api_url
+
+    # Interval in seconds between batch metering reports
+    # @return [Integer]
+    attr_accessor :sync_interval
+
+    # Maximum seconds to allow offline operation when server is unreachable
+    # @return [Integer]
+    attr_accessor :offline_grace_period
+
+    # Maximum executions allowed during offline grace period
+    # @return [Integer]
+    attr_accessor :offline_grace_executions
+
+    # Logger instance
+    # @return [Logger]
+    attr_accessor :logger
+
+    # Whether to verify SSL certificates (disable for development only)
+    # @return [Boolean]
+    attr_accessor :verify_ssl
+
+    # Default API URL
+    DEFAULT_API_URL = "https://stellwerk.io"
+
+    # Default sync interval (60 seconds)
+    DEFAULT_SYNC_INTERVAL = 60
+
+    # Default offline grace period (24 hours)
+    DEFAULT_OFFLINE_GRACE_PERIOD = 86_400
+
+    # Default offline grace executions
+    DEFAULT_OFFLINE_GRACE_EXECUTIONS = 100
+
+    def initialize
+      @api_key = nil
+      @api_url = DEFAULT_API_URL
+      @sync_interval = DEFAULT_SYNC_INTERVAL
+      @offline_grace_period = DEFAULT_OFFLINE_GRACE_PERIOD
+      @offline_grace_executions = DEFAULT_OFFLINE_GRACE_EXECUTIONS
+      @logger = nil
+      @verify_ssl = true
+    end
+
+    # Check if an API key is configured
+    # @return [Boolean]
+    def api_key?
+      !@api_key.nil? && !@api_key.empty?
+    end
+
+    # Reset configuration to defaults
+    def reset!
+      @api_key = nil
+      @api_url = DEFAULT_API_URL
+      @sync_interval = DEFAULT_SYNC_INTERVAL
+      @offline_grace_period = DEFAULT_OFFLINE_GRACE_PERIOD
+      @offline_grace_executions = DEFAULT_OFFLINE_GRACE_EXECUTIONS
+      @logger = nil
+      @verify_ssl = true
+    end
+  end
+end

data/lib/stellwerk/errors.rb

@@ -15,4 +15,21 @@ module Stellwerk
 
   # Raised when a required input is missing
   class MissingInputError < Error; end
+
+  # Raised when API key is missing or invalid
+  class LicenseError < Error; end
+
+  # Raised when execution limit is reached
+  class QuotaExceededError < Error; end
+
+  # Raised when API communication fails
+  class ApiError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code: nil, response_body: nil)
+      super(message)
+      @status_code = status_code
+      @response_body = response_body
+    end
+  end
 end

data/lib/stellwerk/flow.rb

@@ -41,13 +41,32 @@ module Stellwerk
     # @param sub_flows [Hash] Additional sub-flows for map nodes
     # @param metadata [Hash] Additional metadata to merge into context
     # @return [Stellwerk::Result]
+    # @raise [LicenseError] If API key is not configured or invalid
+    # @raise [QuotaExceededError] If execution limit is exceeded
     def execute(params = {}, sub_flows: {}, metadata: {})
-      Evaluator.call(
-        compiled_json: @compiled_json,
-        params: params,
-        sub_flows: sub_flows,
-        metadata: metadata
-      )
+      enforce_license!
+      check_quota!
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+      status = "success"
+
+      begin
+        result = Evaluator.call(
+          compiled_json: @compiled_json,
+          params: params,
+          sub_flows: sub_flows,
+          metadata: metadata
+        )
+
+        status = "error" unless result.success?
+        result
+      rescue StandardError
+        status = "error"
+        raise
+      ensure
+        duration_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - start_time
+        track_execution(duration_ms, status)
+      end
     end
 
     # Get the flow version from compiled JSON
@@ -73,6 +92,52 @@ module Stellwerk
 
     private
 
+    def enforce_license!
+      license = Stellwerk.license
+
+      # Try to validate if not yet validated or cache expired
+      unless license.valid?
+        license.validate!
+      end
+
+      # Check again after validation attempt
+      unless license.valid?
+        raise LicenseError, "Invalid or expired license"
+      end
+    end
+
+    def check_quota!
+      license = Stellwerk.license
+
+      unless license.within_limits?
+        if license.offline?
+          raise QuotaExceededError,
+                "Offline execution limit reached. Connect to the network to continue."
+        else
+          raise QuotaExceededError,
+                "Execution limit reached for your plan. Upgrade at https://stellwerk.io"
+        end
+      end
+    end
+
+    def track_execution(duration_ms, status)
+      license = Stellwerk.license
+
+      # Record offline execution if in grace period
+      license.record_offline_execution if license.offline?
+
+      # Track in metering system
+      Stellwerk.metering.track(
+        flow_id: flow_id,
+        duration_ms: duration_ms,
+        status: status
+      )
+    end
+
+    def flow_id
+      @compiled_json["id"] || @compiled_json[:id] || @path || "unknown"
+    end
+
     def validate!
       nodes = @compiled_json["nodes"] || @compiled_json[:nodes]
       unless nodes.is_a?(Hash)

data/lib/stellwerk/license.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Stellwerk
+  # License validation and caching
+  #
+  # Validates API keys against the Stellwerk server and caches the result.
+  # Supports offline grace periods when the server is unreachable.
+  #
+  # Thread-safe via Mutex.
+  #
+  class License
+    # Cached license data attributes
+    attr_reader :plan, :execution_limit, :executions_used, :expires_at
+
+    def initialize
+      @mutex = Mutex.new
+      @validated = false
+      @valid = false
+      @plan = nil
+      @execution_limit = 0
+      @executions_used = 0
+      @expires_at = nil
+      @offline_since = nil
+      @offline_executions = 0
+    end
+
+    # Validate the API key against the server
+    #
+    # @return [Boolean] Whether the license is valid
+    # @raise [LicenseError] If API key is missing
+    # @raise [ApiError] On server communication failure (after grace period)
+    def validate!
+      @mutex.synchronize do
+        validate_internal!
+      end
+    end
+
+    # Check if the current license is valid (cached)
+    #
+    # @return [Boolean]
+    def valid?
+      @mutex.synchronize do
+        return false unless @validated
+        return @valid if within_cache_ttl?
+        return in_offline_grace? if @offline_since
+
+        @valid
+      end
+    end
+
+    # Refresh the license if TTL has expired
+    #
+    # @return [Boolean] Whether the license is valid after refresh
+    def refresh_if_needed
+      @mutex.synchronize do
+        return @valid if within_cache_ttl?
+
+        validate_internal!
+      end
+    end
+
+    # Check if executions are within allowed limits
+    #
+    # @param pending_count [Integer] Number of pending executions to check
+    # @return [Boolean]
+    def within_limits?(pending_count = 1)
+      @mutex.synchronize do
+        return false unless @valid || in_offline_grace?
+
+        if @offline_since
+          @offline_executions + pending_count <= offline_grace_executions
+        else
+          @executions_used + pending_count <= @execution_limit
+        end
+      end
+    end
+
+    # Record an offline execution during grace period
+    def record_offline_execution
+      @mutex.synchronize do
+        @offline_executions += 1
+      end
+    end
+
+    # Update execution count from server response
+    #
+    # @param count [Integer] Current execution count from server
+    def update_executions_used(count)
+      @mutex.synchronize do
+        @executions_used = count
+      end
+    end
+
+    # Check if in offline mode
+    #
+    # @return [Boolean]
+    def offline?
+      @mutex.synchronize do
+        !@offline_since.nil?
+      end
+    end
+
+    # Reset the license state
+    def reset!
+      @mutex.synchronize do
+        @validated = false
+        @valid = false
+        @plan = nil
+        @execution_limit = 0
+        @executions_used = 0
+        @expires_at = nil
+        @offline_since = nil
+        @offline_executions = 0
+      end
+    end
+
+    private
+
+    def validate_internal!
+      config = Stellwerk.configuration
+
+      unless config.api_key?
+        raise LicenseError, "API key is required. Set Stellwerk.configuration.api_key"
+      end
+
+      begin
+        client = ApiClient.new(api_url: config.api_url, api_key: config.api_key, verify_ssl: config.verify_ssl)
+        response = client.post("/api/v1/sdk/validate")
+
+        apply_validation_response(response)
+        clear_offline_state
+        @validated = true
+        @valid
+      rescue ApiError => e
+        handle_validation_error(e)
+      end
+    end
+
+    def apply_validation_response(response)
+      @valid = response["valid"] == true
+      @plan = response["plan"]
+
+      limits = response["limits"] || {}
+      @execution_limit = limits["monthly_executions"].to_i
+      @executions_used = limits["current_count"].to_i
+
+      cache_ttl = response["cache_ttl"].to_i
+      cache_ttl = 3600 if cache_ttl <= 0
+      @expires_at = Time.now + cache_ttl
+    end
+
+    def handle_validation_error(error)
+      if error.status_code == 401
+        @valid = false
+        @validated = true
+        raise LicenseError, "Invalid API key"
+      end
+
+      # Server unreachable - enter or continue offline grace period
+      if @validated && @valid
+        enter_offline_grace unless @offline_since
+        Stellwerk.logger.warn("License server unreachable, operating in offline grace mode")
+        return in_offline_grace?
+      end
+
+      # Never validated successfully - cannot enter grace period
+      raise LicenseError, "Unable to validate license: #{error.message}"
+    end
+
+    def enter_offline_grace
+      @offline_since = Time.now
+      @offline_executions = 0
+    end
+
+    def clear_offline_state
+      @offline_since = nil
+      @offline_executions = 0
+    end
+
+    def within_cache_ttl?
+      @expires_at && Time.now < @expires_at
+    end
+
+    def in_offline_grace?
+      return false unless @offline_since
+
+      within_time = (Time.now - @offline_since) < offline_grace_period
+      within_executions = @offline_executions < offline_grace_executions
+
+      within_time && within_executions
+    end
+
+    def offline_grace_period
+      Stellwerk.configuration.offline_grace_period
+    end
+
+    def offline_grace_executions
+      Stellwerk.configuration.offline_grace_executions
+    end
+  end
+end

data/lib/stellwerk/metering.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Stellwerk
+  # Execution metering and batch reporting
+  #
+  # Tracks flow executions locally and periodically reports them
+  # to the Stellwerk server in batches for efficiency.
+  #
+  # Thread-safe via Mutex.
+  #
+  class Metering
+    # Execution record structure
+    Execution = Struct.new(:flow_id, :timestamp, :duration_ms, :status, keyword_init: true)
+
+    def initialize
+      @mutex = Mutex.new
+      @pending_executions = []
+      @last_flush_at = Time.now
+      @background_thread = nil
+      @running = false
+    end
+
+    # Track a flow execution
+    #
+    # @param flow_id [String] Identifier for the flow
+    # @param duration_ms [Integer] Execution duration in milliseconds
+    # @param status [String] Execution status ('success', 'error')
+    def track(flow_id:, duration_ms:, status:)
+      execution = Execution.new(
+        flow_id: flow_id,
+        timestamp: Time.now.utc.iso8601,
+        duration_ms: duration_ms,
+        status: status
+      )
+
+      @mutex.synchronize do
+        @pending_executions << execution
+      end
+
+      auto_flush_if_needed
+    end
+
+    # Flush pending executions to the server
+    #
+    # @return [Hash, nil] Server response or nil if nothing to flush
+    def flush
+      executions_to_send = nil
+
+      @mutex.synchronize do
+        return nil if @pending_executions.empty?
+
+        executions_to_send = @pending_executions.dup
+        @pending_executions.clear
+        @last_flush_at = Time.now
+      end
+
+      send_executions(executions_to_send)
+    rescue ApiError => e
+      # Re-queue executions on failure
+      @mutex.synchronize do
+        @pending_executions = executions_to_send + @pending_executions
+      end
+      Stellwerk.logger.error("Failed to report executions: #{e.message}")
+      nil
+    end
+
+    # Get count of pending executions
+    #
+    # @return [Integer]
+    def pending_count
+      @mutex.synchronize do
+        @pending_executions.length
+      end
+    end
+
+    # Start background auto-flush thread
+    #
+    # @return [Thread]
+    def start_background_flush
+      @mutex.synchronize do
+        return @background_thread if @running
+
+        @running = true
+        @background_thread = Thread.new { background_flush_loop }
+      end
+    end
+
+    # Stop background auto-flush thread
+    def stop_background_flush
+      @mutex.synchronize do
+        @running = false
+      end
+      @background_thread&.join(5)
+      @background_thread = nil
+    end
+
+    # Check if background flush is running
+    #
+    # @return [Boolean]
+    def background_flush_running?
+      @mutex.synchronize do
+        @running && @background_thread&.alive?
+      end
+    end
+
+    # Reset metering state
+    def reset!
+      stop_background_flush
+      @mutex.synchronize do
+        @pending_executions.clear
+        @last_flush_at = Time.now
+      end
+    end
+
+    private
+
+    def auto_flush_if_needed
+      should_flush = @mutex.synchronize do
+        time_since_flush = Time.now - @last_flush_at
+        time_since_flush >= sync_interval
+      end
+
+      flush if should_flush
+    end
+
+    def background_flush_loop
+      while @mutex.synchronize { @running }
+        sleep(sync_interval)
+        flush if @mutex.synchronize { @running }
+      end
+    rescue StandardError => e
+      Stellwerk.logger.error("Background flush error: #{e.message}")
+      @mutex.synchronize { @running = false }
+    end
+
+    def send_executions(executions)
+      config = Stellwerk.configuration
+      return nil unless config.api_key?
+
+      client = ApiClient.new(api_url: config.api_url, api_key: config.api_key, verify_ssl: config.verify_ssl)
+
+      body = {
+        executions: executions.map do |exec|
+          {
+            flow_id: exec.flow_id,
+            timestamp: exec.timestamp,
+            duration_ms: exec.duration_ms,
+            status: exec.status
+          }
+        end
+      }
+
+      response = client.post("/api/v1/executions/report", body)
+
+      # Update license with current usage from response
+      limits = response["limits"] || {}
+      if limits["current_count"]
+        Stellwerk.license.update_executions_used(limits["current_count"])
+      end
+
+      response
+    end
+
+    def sync_interval
+      Stellwerk.configuration.sync_interval
+    end
+  end
+end

data/lib/stellwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stellwerk
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/stellwerk.rb

@@ -4,6 +4,10 @@ require "logger"
 
 require_relative "stellwerk/version"
 require_relative "stellwerk/errors"
+require_relative "stellwerk/configuration"
+require_relative "stellwerk/api_client"
+require_relative "stellwerk/license"
+require_relative "stellwerk/metering"
 require_relative "stellwerk/result"
 require_relative "stellwerk/functions"
 require_relative "stellwerk/evaluator"
@@ -37,24 +41,83 @@ require_relative "stellwerk/flow"
 #
 module Stellwerk
   class << self
-    # Configuration options
-    attr_writer :logger
+    # Returns the configuration instance
+    #
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure Stellwerk
+    #
+    # @yield [Configuration] Yields the configuration instance
+    # @example
+    #   Stellwerk.configure do |config|
+    #     config.api_key = 'sk_stellwerk_...'
+    #     config.logger = Logger.new(STDOUT)
+    #   end
+    def configure
+      yield configuration
+    end
+
+    # Convenience setter for API key
+    #
+    # @param key [String] The API key
+    def api_key=(key)
+      configuration.api_key = key
+    end
 
     # Returns the configured logger (defaults to a null logger)
+    #
+    # @return [Logger]
     def logger
-      @logger ||= Logger.new(File::NULL)
+      configuration.logger || @default_logger ||= Logger.new(File::NULL)
     end
 
-    # Configure Stellwerk
+    # Set the logger
     #
-    # @yield [self] Yields self for configuration
-    def configure
-      yield self
+    # @param logger [Logger]
+    def logger=(logger)
+      configuration.logger = logger
     end
 
-    # Reset configuration to defaults
+    # Returns the license instance
+    #
+    # @return [License]
+    def license
+      @license ||= License.new
+    end
+
+    # Returns the metering instance
+    #
+    # @return [Metering]
+    def metering
+      @metering ||= Metering.new
+    end
+
+    # Check if the SDK is properly licensed
+    #
+    # Validates the API key on first call and caches the result.
+    #
+    # @return [Boolean]
+    def licensed?
+      return false unless configuration.api_key?
+
+      license.valid? || license.validate!
+    rescue LicenseError, ApiError
+      false
+    end
+
+    # Reset all state to defaults
+    #
+    # Resets configuration, license, and metering state.
     def reset!
-      @logger = nil
+      metering.reset!
+      license.reset!
+      @configuration = nil
+      @license = nil
+      @metering = nil
+      @default_logger = nil
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stellwerk-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Roadwerk
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-31 00:00:00.000000000 Z
+date: 2026-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dentaku
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
 description: |
   Stellwerk is a standalone Ruby gem for evaluating pre-compiled flow JSON
   without any Rails or ActiveRecord dependencies. It provides a fast, portable
@@ -80,10 +94,14 @@ files:
 - LICENSE.txt
 - README.md
 - lib/stellwerk.rb
+- lib/stellwerk/api_client.rb
+- lib/stellwerk/configuration.rb
 - lib/stellwerk/errors.rb
 - lib/stellwerk/evaluator.rb
 - lib/stellwerk/flow.rb
 - lib/stellwerk/functions.rb
+- lib/stellwerk/license.rb
+- lib/stellwerk/metering.rb
 - lib/stellwerk/result.rb
 - lib/stellwerk/version.rb
 homepage: https://github.com/roadwerk/stellwerk-ruby