smplkit 1.0.5

data/lib/smplkit/flags/models.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Flags
+    # A constrained value entry on a +Flag+.
+    #
+    # Lives in +Flag#values+. Frozen — author values via +Flag#add_value+ /
+    # +Flag#remove_value+ / +Flag#clear_values+.
+    FlagValue = Data.define(:name, :value)
+
+    # A single targeting rule on a +Flag+.
+    #
+    # Lives in +FlagEnvironment#rules+. Frozen — author rules via the
+    # +Smplkit::Rule+ fluent builder and pass through +Flag#add_rule+.
+    #
+    # Attributes:
+    #   - logic: JSON Logic predicate. Empty Hash means "always match".
+    #   - value: Value to serve when +logic+ evaluates truthy.
+    #   - description: Human-readable label (optional).
+    class FlagRule
+      attr_reader :logic, :value, :description
+
+      def initialize(logic:, value: nil, description: nil)
+        @logic = logic
+        @value = value
+        @description = description
+        freeze
+      end
+
+      def ==(other)
+        other.is_a?(FlagRule) && logic == other.logic && value == other.value && description == other.description
+      end
+      alias eql? ==
+
+      def hash = [logic, value, description].hash
+    end
+
+    # Per-environment configuration on a +Flag+.
+    #
+    # Lives at +flag.environments[env_name]+. Frozen — mutate via +Flag#add_rule+
+    # / +Flag#enable_rules+ / +Flag#disable_rules+ / +Flag#set_default+ /
+    # +Flag#clear_rules+ (with +environment:+).
+    #
+    # Attributes:
+    #   - enabled: Whether the flag is active in this environment.
+    #   - default: Environment-specific default override (+nil+ means no override).
+    #   - rules: Targeting rules to evaluate, in order.
+    class FlagEnvironment
+      attr_reader :enabled, :default, :rules
+
+      def initialize(enabled: true, default: nil, rules: [])
+        @enabled = enabled
+        @default = default
+        @rules = rules.is_a?(Array) ? rules.dup.freeze : rules
+        freeze
+      end
+
+      def enabled? = @enabled
+
+      # Return a new FlagEnvironment with the given fields replaced.
+      def with(**changes)
+        self.class.new(
+          enabled: changes.fetch(:enabled, @enabled),
+          default: changes.fetch(:default, @default),
+          rules: changes.fetch(:rules, @rules)
+        )
+      end
+
+      def ==(other)
+        other.is_a?(FlagEnvironment) && enabled == other.enabled && default == other.default && rules == other.rules
+      end
+      alias eql? ==
+
+      def hash = [enabled, default, rules].hash
+    end
+
+    # A flag resource.
+    #
+    # Provides management operations (save, add_rule, environment settings)
+    # and runtime evaluation via +get+.
+    #
+    # Use typed variants (BooleanFlag, StringFlag, NumberFlag, JsonFlag)
+    # for type-safe +get+ return values.
+    class Flag
+      attr_accessor :id, :name, :type, :default, :description, :created_at, :updated_at
+
+      def initialize(client = nil, name:, type:, default:, id: nil, values: nil,
+                     description: nil, environments: nil, created_at: nil, updated_at: nil)
+        @client = client
+        @id = id
+        @name = name
+        @type = type
+        @default = default
+        @values = values&.dup
+        @description = description
+        @environments = environments ? environments.dup : {}
+        @created_at = created_at
+        @updated_at = updated_at
+      end
+
+      # Read-only view of constrained values. +nil+ means unconstrained.
+      def values
+        @values&.dup
+      end
+
+      # Read-only view of per-environment configuration.
+      def environments
+        @environments.dup
+      end
+
+      # Persist this flag to the server.
+      #
+      # Creates a new flag if unsaved, or updates the existing one. Requires a
+      # management client (i.e. the flag was constructed via +mgmt.flags.new_*+
+      # or returned from +mgmt.flags.get/list+).
+      def save
+        raise "Flag was constructed without a client; cannot save" if @client.nil?
+
+        updated =
+          if @created_at.nil?
+            @client._create_flag(self)
+          else
+            @client._update_flag(self)
+          end
+        _apply(updated)
+        self
+      end
+      alias save! save
+
+      def delete
+        raise "Flag was constructed without a client or id; cannot delete" if @client.nil? || @id.nil?
+
+        @client.delete(@id)
+      end
+      alias delete! delete
+
+      # Append a rule to a specific environment.
+      #
+      # The +built_rule+ Hash must include an +"environment"+ key.
+      # Call +save+ to persist.
+      def add_rule(built_rule)
+        env_key = built_rule["environment"]
+        if env_key.nil?
+          raise ArgumentError,
+                "Built rule must include 'environment' key. " \
+                "Use Smplkit::Rule.new(..., environment: 'env_key').when(...).serve(...)"
+        end
+
+        flag_rule = FlagRule.new(
+          logic: (built_rule["logic"] || {}).dup,
+          value: built_rule["value"],
+          description: built_rule["description"]
+        )
+        existing = @environments[env_key] || FlagEnvironment.new
+        @environments[env_key] = existing.with(rules: (existing.rules + [flag_rule]).freeze)
+        self
+      end
+
+      def enable_rules(environment: nil)
+        scoped(environment) { |k| @environments[k] = (@environments[k] || FlagEnvironment.new).with(enabled: true) }
+        self
+      end
+
+      def disable_rules(environment: nil)
+        scoped(environment) { |k| @environments[k] = (@environments[k] || FlagEnvironment.new).with(enabled: false) }
+        self
+      end
+
+      def clear_rules(environment: nil)
+        scoped(environment) do |k|
+          @environments[k] = (@environments[k] || FlagEnvironment.new).with(rules: [].freeze)
+        end
+        self
+      end
+
+      def set_default(value, environment:)
+        @environments[environment] = (@environments[environment] || FlagEnvironment.new).with(default: value)
+        self
+      end
+
+      def clear_default(environment:)
+        @environments[environment] = (@environments[environment] || FlagEnvironment.new).with(default: nil)
+        self
+      end
+
+      def add_value(flag_value)
+        @values ||= []
+        @values << flag_value
+        self
+      end
+
+      def remove_value(name)
+        return self unless @values
+
+        @values = @values.reject { |v| v.name == name }
+        self
+      end
+
+      def clear_values
+        @values = []
+        self
+      end
+
+      def _apply(other)
+        @id = other.id
+        @name = other.name
+        @type = other.type
+        @default = other.default
+        @description = other.description
+        @values = other.instance_variable_get(:@values)&.dup
+        @environments = other.instance_variable_get(:@environments).dup
+        @created_at = other.created_at
+        @updated_at = other.updated_at
+      end
+
+      private
+
+      def scoped(environment, &)
+        if environment.nil?
+          @environments.each_key(&)
+        else
+          yield(environment)
+        end
+      end
+    end
+
+    class BooleanFlag < Flag
+      def get(context: nil)
+        raw = @client._evaluate_handle(@id, @default, context)
+        !!raw
+      end
+    end
+
+    class StringFlag < Flag
+      def get(context: nil)
+        raw = @client._evaluate_handle(@id, @default, context)
+        raw.to_s
+      end
+    end
+
+    class NumberFlag < Flag
+      def get(context: nil)
+        @client._evaluate_handle(@id, @default, context)
+      end
+    end
+
+    class JsonFlag < Flag
+      def get(context: nil)
+        @client._evaluate_handle(@id, @default, context)
+      end
+    end
+  end
+
+  # Top-level re-exports for convenience.
+  FlagValue = Flags::FlagValue
+  FlagRule = Flags::FlagRule
+  FlagEnvironment = Flags::FlagEnvironment
+end

data/lib/smplkit/flags/types.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Smplkit
+  # Operators supported by +Smplkit::Rule#when+.
+  #
+  # Customers should prefer +Smplkit::Op::EQ+ etc. over raw strings so the IDE
+  # can validate calls. Raw strings are still accepted for backward
+  # compatibility.
+  module Op
+    EQ = "=="
+    NEQ = "!="
+    LT = "<"
+    LTE = "<="
+    GT = ">"
+    GTE = ">="
+    IN = "in"
+    CONTAINS = "contains"
+
+    ALL = [EQ, NEQ, LT, LTE, GT, GTE, IN, CONTAINS].freeze
+  end
+
+  # A typed entity referenced by targeting rules and registered with smplkit.
+  #
+  # Represents a single entity (user, account, device, etc.). The +type+ and
+  # +key+ identify the entity; +attributes+ (provided as a hash and/or keyword
+  # arguments) carry the data that targeting rules evaluate against.
+  #
+  # Used for both authoring (+flag.get(context: [...])+,
+  # +client.set_context([...])+, +mgmt.contexts.register([...])+) and reading
+  # (+mgmt.contexts.list/get+ return populated +Context+ instances with
+  # +save+ / +delete+ ready to call).
+  #
+  # Examples:
+  #
+  #   Smplkit::Context.new("user", "user-123", plan: "enterprise")
+  #   Smplkit::Context.new("account", "acme-corp", { "region" => "us" }, employee_count: 500)
+  class Context
+    CONTEXT_FIELDS = %i[type key name attributes created_at updated_at].freeze
+
+    attr_reader :type, :key, :attributes
+    attr_accessor :name, :created_at, :updated_at
+
+    def initialize(type, key, attributes = nil, name: nil, created_at: nil, updated_at: nil, **kwargs)
+      raise TypeError, "Context type must be a String, got #{type.class}: #{type.inspect}" unless type.is_a?(String)
+      unless key.is_a?(String)
+        raise TypeError,
+              "Context key must be a String, got #{key.class}: #{key.inspect}. " \
+              "If your identifier is numeric, stringify it at the SDK boundary."
+      end
+
+      @type = type
+      @key = key
+      @name = name
+      @attributes = stringify_keys(merge_attributes(attributes, kwargs))
+      @created_at = created_at
+      @updated_at = updated_at
+      @client = nil
+    end
+
+    # Composite "{type}:{key}" identifier.
+    def id
+      "#{@type}:#{@key}"
+    end
+
+    # Bulk-replace attributes. Forces String keys to match the wire format.
+    def attributes=(new_attrs)
+      @attributes = stringify_keys(new_attrs || {})
+    end
+
+    # Internal: associate a management client with this context so save/delete
+    # can route through it.
+    def _bind_client(client)
+      @client = client
+      self
+    end
+
+    def _client
+      @client
+    end
+
+    # Persist this context to the server (create or update).
+    def save
+      raise "Context was constructed without a client; cannot save" if @client.nil?
+
+      updated = @client._save_context(self)
+      _apply(updated)
+      self
+    end
+    alias save! save
+
+    # Delete this context from the server.
+    def delete
+      raise "Context was constructed without a client; cannot delete" if @client.nil?
+
+      @client.delete(id)
+    end
+    alias delete! delete
+
+    def to_eval_hash
+      { "key" => @key, **@attributes }
+    end
+
+    def ==(other)
+      other.is_a?(Context) && other.type == @type && other.key == @key && other.attributes == @attributes
+    end
+
+    def hash
+      [@type, @key, @attributes].hash
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def inspect
+      "#<Smplkit::Context type=#{@type.inspect} key=#{@key.inspect} " \
+        "name=#{@name.inspect} attributes=#{@attributes.inspect}>"
+    end
+
+    def _apply(other)
+      @type = other.type
+      @key = other.key
+      @name = other.name
+      @attributes = other.attributes.dup
+      @created_at = other.created_at
+      @updated_at = other.updated_at
+    end
+
+    private
+
+    def merge_attributes(attrs, kwargs)
+      base = attrs ? attrs.dup : {}
+      kwargs.each { |k, v| base[k] = v }
+      base
+    end
+
+    def stringify_keys(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+  end
+
+  # Describes a flag declaration for buffered registration.
+  #
+  # Used by +Smplkit::ManagementClient#flags#register+ to queue declarations
+  # for bulk registration. +service+ and +environment+ default to +nil+; the
+  # runtime client fills them from the active +Smplkit::Client+ when it
+  # forwards declarations.
+  class FlagDeclaration
+    attr_reader :id, :type, :default, :service, :environment
+
+    def initialize(id:, type:, default:, service: nil, environment: nil)
+      @id = id
+      @type = type
+      @default = default
+      @service = service
+      @environment = environment
+      freeze
+    end
+
+    def ==(other)
+      other.is_a?(FlagDeclaration) && id == other.id && type == other.type && default == other.default &&
+        service == other.service && environment == other.environment
+    end
+    alias eql? ==
+
+    def hash = [id, type, default, service, environment].hash
+  end
+
+  # Fluent builder for flag targeting rules.
+  #
+  #   Smplkit::Rule.new("Enable for enterprise users", environment: "staging")
+  #     .when("user.plan", Smplkit::Op::EQ, "enterprise")
+  #     .serve(true)
+  #
+  # Multiple +.when+ calls are AND'd. +environment:+ is required so the target
+  # environment is unambiguous when the rule is passed to +Flag#add_rule+.
+  # +.serve+ finalizes the rule and returns the built Hash ready to pass to
+  # +add_rule+.
+  class Rule
+    def initialize(description, environment:)
+      @description = description
+      @environment = environment
+      @conditions = []
+    end
+
+    # Add a condition. Multiple calls are AND'd at the top level.
+    #
+    # Two forms:
+    #   - +when(var, op, value)+ - convenience for simple comparisons.
+    #     +op+ accepts an +Op+ constant (preferred) or a raw string
+    #     (e.g. +"=="+, +"contains"+).
+    #   - +when(expr)+ - escape hatch accepting an arbitrary JSON Logic
+    #     expression (use this for OR, nested AND/OR, +if+, etc.).
+    #     See https://jsonlogic.com/ for the full expression grammar.
+    def when(*args)
+      if args.length == 1 && args[0].is_a?(Hash)
+        @conditions << args[0]
+        return self
+      end
+
+      if args.length == 3
+        var, op, value = args
+        op_str = op.to_s
+        @conditions << if op_str == "contains"
+                         { "in" => [value, { "var" => var }] }
+                       else
+                         { op_str => [{ "var" => var }, value] }
+                       end
+        return self
+      end
+
+      raise ArgumentError,
+            "Rule#when takes either (var, op, value) or a single JSON Logic Hash; got args=#{args.inspect}"
+    end
+
+    # Finalize the rule with +value+ served on match and return the built Hash.
+    def serve(value)
+      logic =
+        case @conditions.length
+        when 0 then {}
+        when 1 then @conditions[0]
+        else { "and" => @conditions }
+        end
+
+      {
+        "description" => @description,
+        "logic" => logic,
+        "value" => value,
+        "environment" => @environment
+      }
+    end
+  end
+end

data/lib/smplkit/generators/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Smplkit
+  module Generators
+    # Generates +config/initializers/smplkit.rb+ for Rails apps.
+    #
+    #   rails generate smplkit:install
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer_file
+        create_file "config/initializers/smplkit.rb", initializer_contents
+      end
+
+      def initializer_contents
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # smplkit configuration. Anything you don't set here resolves through
+          # the standard SMPLKIT_* env vars or the ~/.smplkit profile file.
+          Rails.application.configure do
+            config.smplkit.environment = Rails.env
+            config.smplkit.service = "your-service-name"
+            # config.smplkit.api_key = ENV["SMPLKIT_API_KEY"]
+
+            # Optional: per-request context. The provider receives the Rack env
+            # and returns an Array of Smplkit::Context. Returning nil/[] is fine.
+            #
+            # config.smplkit.context_provider = ->(env) {
+            #   user = env["warden"]&.user
+            #   next [] unless user
+            #
+            #   [Smplkit::Context.new("user", user.id.to_s, plan: user.plan)]
+            # }
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/smplkit/helpers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Helpers
+    module_function
+
+    # Convert a slug-style key to a human-readable display name.
+    #
+    #   key_to_display_name("checkout-v2")    # => "Checkout V2"
+    #   key_to_display_name("user_service")   # => "User Service"
+    def key_to_display_name(key)
+      key.tr("-_", "  ").split.map(&:capitalize).join(" ")
+    end
+  end
+end

data/lib/smplkit/log_level.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Smplkit
+  # Log severity levels used by the Smpl Logging service.
+  #
+  # Acts as a string-valued enum: each constant equals its name when used in
+  # string contexts, and supports comparison via the +ordinal+.
+  class LogLevel
+    NAMES = %w[TRACE DEBUG INFO WARN ERROR FATAL SILENT].freeze
+
+    attr_reader :name, :ordinal
+
+    def initialize(name, ordinal)
+      @name = name.freeze
+      @ordinal = ordinal
+      freeze
+    end
+
+    def to_s = @name
+    def to_str = @name
+    def inspect = "#<Smplkit::LogLevel #{@name}>"
+    def ==(other) = other.is_a?(LogLevel) ? @ordinal == other.ordinal : @name == other
+    def hash = @ordinal.hash
+    def eql?(other) = self == other
+    def <=>(other) = other.is_a?(LogLevel) ? @ordinal <=> other.ordinal : nil
+
+    include Comparable
+
+    TRACE  = new("TRACE", 0)
+    DEBUG  = new("DEBUG", 1)
+    INFO   = new("INFO", 2)
+    WARN   = new("WARN", 3)
+    ERROR  = new("ERROR", 4)
+    FATAL  = new("FATAL", 5)
+    SILENT = new("SILENT", 6)
+
+    ALL = [TRACE, DEBUG, INFO, WARN, ERROR, FATAL, SILENT].freeze
+
+    BY_NAME = ALL.to_h { |lvl| [lvl.name, lvl] }.freeze
+
+    def self.from_string(value)
+      raise ArgumentError, "log level cannot be nil" if value.nil?
+
+      key = value.to_s.upcase
+      level = BY_NAME[key]
+      raise ArgumentError, "unknown log level: #{value.inspect}" unless level
+
+      level
+    end
+
+    def self.coerce(value)
+      return value if value.is_a?(LogLevel)
+
+      from_string(value)
+    end
+  end
+end

data/lib/smplkit/logging/adapters/base.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Logging
+    module Adapters
+      # Contract for pluggable logging framework integration.
+      #
+      # Adapters bridge the smplkit logging runtime to a specific logging
+      # framework (e.g., stdlib +Logger+, +semantic_logger+). Implement this
+      # interface to add support for a new logging framework.
+      class Base
+        # Human-readable adapter name for diagnostics
+        # (e.g., +"stdlib-logger"+).
+        def name
+          raise NotImplementedError
+        end
+
+        # Scan the runtime for existing loggers.
+        #
+        # Returns an Array of triples
+        # +[logger_name, explicit_level_or_nil, effective_level]+ where the
+        # levels are +Smplkit::LogLevel+ instances.
+        #
+        #   - +explicit_level_or_nil+: the level the logger was explicitly
+        #     set to, or +nil+ if it inherits from parent / framework default.
+        #   - +effective_level+: the resolved level the framework uses for
+        #     this logger, accounting for inheritance. Always non-nil.
+        def discover
+          raise NotImplementedError
+        end
+
+        # Set the level on a specific logger.
+        #
+        # +level+ is a +Smplkit::LogLevel+ instance; the adapter converts to
+        # its framework's native level representation.
+        def apply_level(_logger_name, _level)
+          raise NotImplementedError
+        end
+
+        # Install continuous discovery hook.
+        #
+        # The block is invoked with
+        # +(logger_name, explicit_level_or_nil, effective_level)+ whenever a
+        # new logger is created in the framework.
+        #
+        # May be a no-op if the framework doesn't support creation
+        # interception.
+        def install_hook(&)
+          raise NotImplementedError
+        end
+
+        # Remove the hook installed by +install_hook+. Called on
+        # +client.logging.close+.
+        def uninstall_hook
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+
+  # Top-level re-export.
+  LoggingAdapter = Logging::Adapters::Base
+end