smplkit 1.0.5

data/lib/smplkit/config/models.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Config
+    # Type of a +ConfigItem+ value.
+    module ItemType
+      STRING = "STRING"
+      NUMBER = "NUMBER"
+      BOOLEAN = "BOOLEAN"
+      JSON = "JSON"
+
+      ALL = [STRING, NUMBER, BOOLEAN, JSON].freeze
+    end
+
+    # A single typed item in a +Config+.
+    class ConfigItem
+      attr_accessor :name, :value, :type, :description
+
+      def initialize(name:, value:, type:, description: nil)
+        @name = name
+        @value = value
+        @type = type
+        @description = description
+      end
+
+      def to_h
+        { "name" => @name, "value" => @value, "type" => @type, "description" => @description }.compact
+      end
+
+      def ==(other)
+        other.is_a?(ConfigItem) && other.name == @name && other.value == @value &&
+          other.type == @type && other.description == @description
+      end
+      alias eql? ==
+
+      def hash = [@name, @value, @type, @description].hash
+    end
+
+    # Per-environment value overrides for a +Config+.
+    #
+    # Read-only inspection container. Mutation is performed via +Config+'s
+    # setters with +environment:+ (e.g.
+    # +cfg.set_string("k", "v", environment: "production")+).
+    class ConfigEnvironment
+      def initialize(values: nil)
+        @values_raw = {}
+        return unless values
+
+        values.each do |k, v|
+          @values_raw[k] = v.is_a?(Hash) && v.key?("value") ? v : { "value" => v }
+        end
+      end
+
+      # Returns overrides as a plain Hash +{ "key" => raw_value }+.
+      def values
+        @values_raw.transform_values { |v| v["value"] }
+      end
+
+      # Returns the full typed overrides
+      # +{ "key" => { "value" => v, "type" => t, "description" => d } }+
+      # (read-only deep copy).
+      def values_raw
+        @values_raw.transform_values { |v| v.is_a?(Hash) ? v.dup : v }
+      end
+
+      def _replace_raw(values)
+        @values_raw = values
+      end
+    end
+
+    # A configuration resource — a typed bag of items with per-environment
+    # overrides.
+    #
+    # Provides management operations (save, set_string/set_number/...) and
+    # runtime evaluation via +get+ on the parent +ConfigClient+.
+    class Config
+      attr_accessor :id, :key, :name, :description, :parent_id, :created_at, :updated_at
+
+      def initialize(client = nil, key:, id: nil, name: nil, description: nil,
+                     parent_id: nil, items: nil, environments: nil,
+                     created_at: nil, updated_at: nil)
+        @client = client
+        @id = id
+        @key = key
+        @name = name
+        @description = description
+        @parent_id = parent_id
+        @items = items ? items.dup : []
+        @environments = environments ? environments.dup : {}
+        @created_at = created_at
+        @updated_at = updated_at
+      end
+
+      def items
+        @items.dup
+      end
+
+      def environments
+        @environments.dup
+      end
+
+      def save
+        raise "Config was constructed without a client; cannot save" if @client.nil?
+
+        updated =
+          if @created_at.nil?
+            @client._create_config(self)
+          else
+            @client._update_config(self)
+          end
+        _apply(updated)
+        self
+      end
+      alias save! save
+
+      def delete
+        raise "Config was constructed without a client; cannot delete" if @client.nil?
+
+        @client.delete(@key)
+      end
+      alias delete! delete
+
+      def set_string(name, value, environment: nil, description: nil)
+        set_typed(name, value, ItemType::STRING, environment: environment, description: description)
+      end
+
+      def set_number(name, value, environment: nil, description: nil)
+        set_typed(name, value, ItemType::NUMBER, environment: environment, description: description)
+      end
+
+      def set_boolean(name, value, environment: nil, description: nil)
+        set_typed(name, value, ItemType::BOOLEAN, environment: environment, description: description)
+      end
+
+      def set_json(name, value, environment: nil, description: nil)
+        set_typed(name, value, ItemType::JSON, environment: environment, description: description)
+      end
+
+      def remove_item(name, environment: nil)
+        if environment
+          env = @environments[environment]
+          return unless env
+
+          raw = env.values_raw
+          raw.delete(name)
+          env._replace_raw(raw)
+        else
+          @items.reject! { |i| i.name == name }
+        end
+        self
+      end
+
+      def _apply(other)
+        @id = other.id
+        @key = other.key
+        @name = other.name
+        @description = other.description
+        @parent_id = other.parent_id
+        @items = other.items
+        @environments = other.environments
+        @created_at = other.created_at
+        @updated_at = other.updated_at
+      end
+
+      private
+
+      def set_typed(name, value, type, environment:, description: nil)
+        if environment.nil?
+          existing = @items.find { |i| i.name == name }
+          if existing
+            existing.value = value
+            existing.type = type
+            existing.description = description if description
+          else
+            @items << ConfigItem.new(name: name, value: value, type: type, description: description)
+          end
+        else
+          env = (@environments[environment] ||= ConfigEnvironment.new)
+          raw = env.values_raw
+          raw[name] = { "value" => value, "type" => type, "description" => description }.compact
+          env._replace_raw(raw)
+        end
+        self
+      end
+    end
+  end
+
+  # Top-level re-exports.
+  ConfigItem = Config::ConfigItem
+  ConfigEnvironment = Config::ConfigEnvironment
+  ItemType = Config::ItemType
+end

data/lib/smplkit/config_resolution.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Smplkit
+  # SDK configuration resolution: defaults -> file -> env vars -> constructor args.
+  module ConfigResolution
+    CONFIG_KEYS = {
+      "api_key" => "SMPLKIT_API_KEY",
+      "base_domain" => "SMPLKIT_BASE_DOMAIN",
+      "scheme" => "SMPLKIT_SCHEME",
+      "environment" => "SMPLKIT_ENVIRONMENT",
+      "service" => "SMPLKIT_SERVICE",
+      "debug" => "SMPLKIT_DEBUG",
+      "telemetry" => "SMPLKIT_TELEMETRY"
+    }.freeze
+
+    BOOL_TRUE = %w[true 1 yes].freeze
+    BOOL_FALSE = %w[false 0 no].freeze
+
+    DEFAULTS = {
+      "api_key" => nil,
+      "base_domain" => "smplkit.com",
+      "scheme" => "https",
+      "environment" => nil,
+      "service" => nil,
+      "debug" => false,
+      "telemetry" => true
+    }.freeze
+
+    ResolvedConfig = Data.define(
+      :api_key, :base_domain, :scheme, :environment, :service, :debug, :telemetry
+    )
+
+    ResolvedManagementConfig = Data.define(
+      :api_key, :base_domain, :scheme, :debug
+    )
+
+    module_function
+
+    def parse_bool(value, key)
+      lower = value.to_s.strip.downcase
+      return true if BOOL_TRUE.include?(lower)
+      return false if BOOL_FALSE.include?(lower)
+
+      raise Error,
+            "Invalid boolean value for #{key}: #{value.inspect}. " \
+            "Expected one of: true, false, 1, 0, yes, no"
+    end
+
+    # Build a service URL: {scheme}://{subdomain}.{base_domain}
+    def service_url(scheme, subdomain, base_domain)
+      "#{scheme}://#{subdomain}.#{base_domain}"
+    end
+
+    # Minimal INI parser. Returns { section_name => { key => value, ... } }.
+    def parse_ini(text)
+      sections = {}
+      current = nil
+      text.each_line do |line|
+        line = line.strip
+        next if line.empty? || line.start_with?("#", ";")
+
+        if line.start_with?("[") && line.end_with?("]")
+          name = line[1..-2].strip
+          current = (sections[name] ||= {})
+        elsif current
+          key, _, value = line.partition("=")
+          next if value.empty? && !line.include?("=")
+
+          current[key.strip] = value.strip
+        end
+      end
+      sections
+    end
+
+    def read_config_file(profile, home_dir: nil)
+      home_dir ||= Dir.home
+      path = File.join(home_dir, ".smplkit")
+      return {} unless File.file?(path)
+
+      sections =
+        begin
+          parse_ini(File.read(path))
+        rescue StandardError
+          return {}
+        end
+
+      values = {}
+      sections.fetch("common", {}).each { |k, v| values[k] = v unless v.empty? }
+
+      if sections.key?(profile)
+        sections[profile].each { |k, v| values[k] = v unless v.empty? }
+      else
+        non_common = sections.keys.reject { |s| s == "common" }
+        if !non_common.empty? && profile != "default"
+          raise Error,
+                "Profile [#{profile}] not found in ~/.smplkit. Available profiles: #{non_common.join(", ")}"
+        end
+      end
+
+      values
+    end
+
+    def resolve_config(profile: nil, api_key: nil, base_domain: nil, scheme: nil,
+                       environment: nil, service: nil, debug: nil, telemetry: nil,
+                       home_dir: nil)
+      resolved = DEFAULTS.dup
+
+      active_profile = profile || ENV["SMPLKIT_PROFILE"] || "default"
+
+      file_values = read_config_file(active_profile, home_dir: home_dir)
+      CONFIG_KEYS.each_key do |key|
+        next unless file_values.key?(key)
+
+        val = file_values[key]
+        resolved[key] = %w[debug telemetry].include?(key) ? parse_bool(val, key) : val
+      end
+
+      CONFIG_KEYS.each do |key, env_var|
+        env_val = ENV.fetch(env_var, "")
+        next if env_val.empty?
+
+        resolved[key] = %w[debug telemetry].include?(key) ? parse_bool(env_val, env_var) : env_val
+      end
+
+      ctor = {
+        "api_key" => api_key, "base_domain" => base_domain, "scheme" => scheme,
+        "environment" => environment, "service" => service,
+        "debug" => debug, "telemetry" => telemetry
+      }
+      ctor.each { |k, v| resolved[k] = v unless v.nil? }
+
+      missing_required(resolved, "environment", active_profile)
+      missing_required(resolved, "service", active_profile)
+      missing_required(resolved, "api_key", active_profile)
+
+      ResolvedConfig.new(
+        api_key: resolved["api_key"].to_s,
+        base_domain: resolved["base_domain"].to_s,
+        scheme: resolved["scheme"].to_s,
+        environment: resolved["environment"].to_s,
+        service: resolved["service"].to_s,
+        debug: resolved["debug"] ? true : false,
+        telemetry: resolved["telemetry"] ? true : false
+      )
+    end
+
+    def resolve_management_config(profile: nil, api_key: nil, base_domain: nil,
+                                  scheme: nil, debug: nil, home_dir: nil)
+      resolved = {
+        "api_key" => nil,
+        "base_domain" => "smplkit.com",
+        "scheme" => "https",
+        "debug" => false
+      }
+
+      active_profile = profile || ENV["SMPLKIT_PROFILE"] || "default"
+
+      file_values = read_config_file(active_profile, home_dir: home_dir)
+      %w[api_key base_domain scheme debug].each do |key|
+        next unless file_values.key?(key)
+
+        val = file_values[key]
+        resolved[key] = key == "debug" ? parse_bool(val, key) : val
+      end
+
+      [
+        %w[api_key SMPLKIT_API_KEY], %w[base_domain SMPLKIT_BASE_DOMAIN],
+        %w[scheme SMPLKIT_SCHEME], %w[debug SMPLKIT_DEBUG]
+      ].each do |key, env_var|
+        env_val = ENV.fetch(env_var, "")
+        next if env_val.empty?
+
+        resolved[key] = key == "debug" ? parse_bool(env_val, env_var) : env_val
+      end
+
+      ctor = { "api_key" => api_key, "base_domain" => base_domain, "scheme" => scheme, "debug" => debug }
+      ctor.each { |k, v| resolved[k] = v unless v.nil? }
+
+      missing_required(resolved, "api_key", active_profile)
+
+      ResolvedManagementConfig.new(
+        api_key: resolved["api_key"].to_s,
+        base_domain: resolved["base_domain"].to_s,
+        scheme: resolved["scheme"].to_s,
+        debug: resolved["debug"] ? true : false
+      )
+    end
+
+    def missing_required(resolved, key, profile)
+      return if resolved[key]
+
+      env_var = CONFIG_KEYS[key]
+      raise Error,
+            "No #{key} provided. Set one of:\n  " \
+            "1. Pass #{key} to the constructor\n  " \
+            "2. Set the #{env_var} environment variable\n  " \
+            "3. Add #{key} to the [#{profile}] section in ~/.smplkit"
+    end
+  end
+end

data/lib/smplkit/context.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Smplkit
+  # Per-request context stash for context-sensitive evaluation (flags today,
+  # likely more later).
+  #
+  # Backed by per-Fiber storage (Ruby 3.2+) which falls through to per-Thread
+  # storage when not running under a Fiber scheduler. This gives proper
+  # per-request isolation under both threaded and fiber-based concurrency.
+  module RequestContext
+    KEY = :smplkit_request_context
+
+    module_function
+
+    def get
+      Thread.current[KEY] || []
+    end
+
+    def set(contexts)
+      previous = Thread.current[KEY]
+      Thread.current[KEY] = contexts.dup.freeze
+      previous
+    end
+
+    def reset(previous)
+      Thread.current[KEY] = previous
+    end
+  end
+
+  # Returned by +Smplkit::Client#set_context+.
+  #
+  # Optional to use — bare +client.set_context([...])+ is fire-and-forget
+  # (typical middleware pattern). Holding the return value or using the block
+  # form auto-reverts to the prior context on exit, useful for scoped
+  # overrides like impersonation.
+  class ContextScope
+    def initialize(previous)
+      @previous = previous
+      @exited = false
+    end
+
+    # Block form support: +client.set_context([...]) { ... }+.
+    def call
+      yield self
+    ensure
+      exit
+    end
+
+    # Restores the prior context. Idempotent — subsequent calls no-op.
+    def exit
+      return if @exited
+
+      @exited = true
+      RequestContext.reset(@previous)
+    end
+  end
+
+  module_function
+
+  def set_request_context(contexts)
+    previous = RequestContext.set(contexts)
+    ContextScope.new(previous)
+  end
+
+  def request_context
+    RequestContext.get
+  end
+end

data/lib/smplkit/debug.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Smplkit
+  # Internal debug logging for the smplkit SDK.
+  #
+  # Controlled by the +SMPLKIT_DEBUG+ environment variable. When enabled
+  # (+SMPLKIT_DEBUG=1+, +true+, or +yes+, case-insensitive), the SDK emits
+  # timestamped diagnostic lines to stderr covering every meaningful internal
+  # operation.
+  #
+  # Debug output goes directly to +$stderr.write+ — never through Ruby's
+  # +Logger+ — to avoid interfering with the managed logging framework the SDK
+  # controls.
+  module Debug
+    TRUTHY = %w[1 true yes].freeze
+
+    @enabled = TRUTHY.include?(ENV.fetch("SMPLKIT_DEBUG", "").strip.downcase)
+
+    class << self
+      attr_accessor :enabled
+
+      def enable!
+        @enabled = true
+      end
+
+      def enabled?
+        @enabled
+      end
+
+      def emit(subsystem, message)
+        return unless @enabled
+
+        ts = Time.now.utc.iso8601(6)
+        $stderr.write("[smplkit:#{subsystem}] #{ts} #{message}\n")
+      end
+    end
+  end
+
+  module_function
+
+  def debug(subsystem, message)
+    Debug.emit(subsystem, message)
+  end
+
+  def enable_debug
+    Debug.enable!
+  end
+end

data/lib/smplkit/errors.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Smplkit
+  # A single error object from the server's JSON:API +errors+ array.
+  class ApiErrorDetail
+    attr_reader :status, :title, :detail, :source
+
+    def initialize(status: nil, title: nil, detail: nil, source: nil)
+      @status = status
+      @title = title
+      @detail = detail
+      @source = source || {}
+    end
+
+    def to_h
+      h = {}
+      h["status"] = @status unless @status.nil?
+      h["title"] = @title unless @title.nil?
+      h["detail"] = @detail unless @detail.nil?
+      h["source"] = @source unless @source.empty?
+      h
+    end
+
+    def to_json(*)
+      JSON.generate(to_h, *)
+    end
+  end
+
+  # Base exception for all smplkit SDK errors.
+  class Error < StandardError
+    attr_reader :errors, :status_code
+
+    def initialize(message = nil, errors: nil, status_code: nil)
+      @errors = errors || []
+      @status_code = status_code
+      message ||= self.class.derive_message(@errors)
+      super(message)
+    end
+
+    def to_s
+      base = super
+      return base if @errors.empty?
+
+      if @errors.length == 1
+        "#{base}\nError: #{@errors[0].to_json}"
+      else
+        lines = [base, "Errors:"]
+        @errors.each_with_index { |err, i| lines << "  [#{i}] #{err.to_json}" }
+        lines.join("\n")
+      end
+    end
+
+    def self.derive_message(errors)
+      return "An API error occurred" if errors.nil? || errors.empty?
+
+      first = errors[0]
+      msg = first.detail || first.title || first.status || "An API error occurred"
+      extra = errors.length - 1
+      msg += " (and 1 more error)" if extra == 1
+      msg += " (and #{extra} more errors)" if extra > 1
+      msg
+    end
+  end
+
+  class ConnectionError < Error; end
+  class TimeoutError < Error; end
+  class NotFoundError < Error; end
+  class ConflictError < Error; end
+  class ValidationError < Error; end
+
+  module Errors
+    module_function
+
+    def parse_error_body(content)
+      body = JSON.parse(content)
+      raw_errors = body.is_a?(Hash) ? body["errors"] : nil
+      return [] unless raw_errors.is_a?(Array)
+
+      raw_errors.filter_map do |item|
+        next unless item.is_a?(Hash)
+
+        ApiErrorDetail.new(
+          status: item["status"],
+          title: item["title"],
+          detail: item["detail"],
+          source: item["source"] || {}
+        )
+      end
+    rescue JSON::ParserError, EncodingError
+      []
+    end
+
+    # Parse a non-2xx response and raise the appropriate SDK exception.
+    # Raises nothing if status is 2xx.
+    def raise_for_status(status_code, content)
+      return if (200..299).cover?(status_code)
+
+      errors = parse_error_body(content)
+      message = errors.empty? ? "HTTP #{status_code}" : Error.derive_message(errors)
+
+      exc_cls =
+        case status_code
+        when 404 then NotFoundError
+        when 409 then ConflictError
+        when 400, 422 then ValidationError
+        else Error
+        end
+
+      raise exc_cls.new(message, errors: errors, status_code: status_code)
+    end
+  end
+end