smplkit 3.0.95 → 3.0.97

data/lib/smplkit/config/helpers.rb

@@ -2,10 +2,19 @@
 
 module Smplkit
   module Config
+    # Internal conversion and resolution helpers shared by the config client.
+    #
+    # @api private
     module Helpers
       module_function
 
       # Translate a JSON:API resource Hash into a Config domain model.
+      #
+      # @api private
+      # @param client [ConfigClient, nil] The owning client, or +nil+ for a
+      #   detached model.
+      # @param resource [Hash{String => Object}] The JSON:API resource Hash.
+      # @return [Config] The constructed config domain model.
       def config_from_json(client, resource)
         attrs = resource["attributes"] || {}
         items = (attrs["items"] || {}).map do |name, item|
@@ -22,8 +31,8 @@ module Smplkit
         end
 
         environments = (attrs["environments"] || {}).each_with_object({}) do |(env, env_data), out|
-          # Per ADR-024 §2.4 env_data is already the flat override map
-          # +{key: rawValue}+ — the old +{values: {...}}+ envelope is gone.
+          # env_data is already the flat override map +{key: rawValue}+ — the
+          # old +{values: {...}}+ envelope is gone.
           env_values = env_data.is_a?(Hash) ? env_data : {}
           out[env] = ConfigEnvironment.new(values: env_values)
         end
@@ -44,6 +53,12 @@ module Smplkit
 
       # Deep-merge two Hashes, with +override+ winning. Mirrors the Python
       # +deep_merge+ helper used by the resolver.
+      #
+      # @api private
+      # @param base [Hash{String => Object}] The base Hash.
+      # @param override [Hash{String => Object}] The Hash whose values win on
+      #   conflict.
+      # @return [Hash{String => Object}] A new merged Hash.
       def deep_merge(base, override)
         result = base.dup
         override.each do |key, value|
@@ -57,6 +72,10 @@ module Smplkit
       end
 
       # Unwrap typed items +{ key => { value, type, desc } }+ to +{ key => raw }+.
+      #
+      # @api private
+      # @param items [Hash{String => Object}] Typed items keyed by item key.
+      # @return [Hash{String => Object}] The items as +{ key => raw_value }+.
       def unwrap_items(items)
         items.each_with_object({}) do |(k, v), out|
           out[k] = v.is_a?(Hash) && v.key?("value") ? v["value"] : v
@@ -66,6 +85,13 @@ module Smplkit
       # Build the parent chain (child-first, root-last) for a +Config+,
       # walking +parent_id+ pointers across the +by_id+ map. Mirrors the
       # Python SDK's client-side chain construction.
+      #
+      # @api private
+      # @param target [Config] The config to build the chain for.
+      # @param by_id [Hash{String => Config}] Pre-fetched configs keyed by id,
+      #   used to look up parents without extra network calls.
+      # @return [Array<Hash{String => Object}>] Chain entries from child to
+      #   root.
       def build_chain(target, by_id)
         chain = []
         current = target
@@ -84,14 +110,19 @@ module Smplkit
 
       # Build a single chain entry (the +id+/+items+/+environments+ Hash
       # shape used by +resolve_chain+) from a +Config+ domain model.
+      #
+      # @api private
+      # @param config [Config] The config to convert.
+      # @return [Hash{String => Object}] An +id+/+items+/+environments+ chain
+      #   entry.
       def config_to_chain_entry(config)
         items_hash = config.items.to_h do |item|
           [item.name,
            { "value" => item.value, "type" => item.type, "description" => item.description }.compact]
         end
         environments = config.environments.each_with_object({}) do |(env_key, env_obj), out|
-          # Per ADR-024 §2.4 env entries are flat +{key: rawValue}+ maps —
-          # no +values+ envelope, no per-key type wrapper.
+          # Env entries are flat +{key: rawValue}+ maps — no +values+
+          # envelope, no per-key type wrapper.
           out[env_key] = env_obj.values
         end
         { "id" => config.id, "items" => items_hash, "environments" => environments }
@@ -101,13 +132,20 @@ module Smplkit
       #
       # Walks from root (last element) to child (first element), accumulating
       # values via deep merge so child configs override parent configs.
+      #
+      # @api private
+      # @param chain [Array<Hash{String => Object}>] Chain entries from child
+      #   to root.
+      # @param environment [String, nil] The environment whose overrides to
+      #   apply, or +nil+ for base values only.
+      # @return [Hash{String => Object}] The resolved +{key => value}+ map.
       def resolve_chain(chain, environment)
         accumulated = {}
         chain.reverse_each do |config_data|
           raw_items = config_data["items"] || config_data["values"] || {}
           base_values = unwrap_items(raw_items)
-          # Per ADR-024 §2.4 env entries are flat +{key: rawValue}+ maps —
-          # the resolver reads the env entry directly as the override map.
+          # Env entries are flat +{key: rawValue}+ maps — the resolver reads
+          # the env entry directly as the override map.
           env_data = (config_data["environments"] || {})[environment] || {}
           env_values = env_data.is_a?(Hash) ? env_data : {}
           config_resolved = deep_merge(base_values, env_values)

data/lib/smplkit/config/models.rb

@@ -16,6 +16,13 @@ module Smplkit
     class ConfigItem
       attr_accessor :name, :value, :type, :description
 
+      # Create a typed config item.
+      #
+      # @param name [String] The item key within its config.
+      # @param value [Object] The item's value.
+      # @param type [String] The item value type — one of +"STRING"+,
+      #   +"NUMBER"+, +"BOOLEAN"+, or +"JSON"+.
+      # @param description [String, nil] Optional human-readable description.
       def initialize(name:, value:, type:, description: nil)
         @name = name
         @value = value
@@ -23,6 +30,8 @@ module Smplkit
         @description = description
       end
 
+      # @return [Hash{String => Object}] The item as a plain Hash, omitting a
+      #   +nil+ description.
       def to_h
         { "name" => @name, "value" => @value, "type" => @type, "description" => @description }.compact
       end
@@ -42,10 +51,13 @@ module Smplkit
     # setters with +environment:+ (e.g.
     # +cfg.set_string("k", "v", environment: "production")+).
     #
-    # Per ADR-024 §2.4 the wire shape for env overrides is flat —
-    # +{env: {key: rawValue}}+ — so the in-memory representation is
-    # simply a Hash of raw values, with no typed wrapper.
+    # An override stores only the raw value; the declared type and description
+    # come from the base item, so an item's type and description are ignored
+    # when an environment override is supplied.
     class ConfigEnvironment
+      # @param values [Hash{String => Object}, nil] Initial overrides as a flat
+      #   +{key => raw_value}+ map. A legacy +{key => {"value" => raw}}+ wrapper
+      #   is unwrapped to the raw value.
       def initialize(values: nil)
         @values_raw = {}
         return unless values
@@ -58,6 +70,9 @@ module Smplkit
       end
 
       # Returns overrides as a plain Hash +{ "key" => raw_value }+.
+      #
+      # @return [Hash{String => Object}] A read-only shallow copy of the
+      #   overrides.
       def values
         @values_raw.dup
       end
@@ -65,6 +80,9 @@ module Smplkit
       # Returns overrides as a plain Hash +{ "key" => raw_value }+. Retained
       # as a separate accessor for backward compatibility; identical to
       # +values+ now that env overrides are stored flat.
+      #
+      # @return [Hash{String => Object}] A read-only shallow copy of the
+      #   overrides.
       def values_raw
         @values_raw.dup
       end
@@ -82,6 +100,20 @@ module Smplkit
     class Config
       attr_accessor :id, :key, :name, :description, :parent_id, :created_at, :updated_at
 
+      # @param client [ConfigClient, nil] The owning client, or +nil+ for a
+      #   detached model that cannot save or delete.
+      # @param key [String] The config identifier (slug).
+      # @param id [String, nil] The server-assigned id, or +nil+ for an unsaved
+      #   config.
+      # @param name [String, nil] Display name.
+      # @param description [String, nil] Optional description.
+      # @param parent_id [String, nil] Parent config id (slug), or +nil+ for a
+      #   root config.
+      # @param items [Array<ConfigItem>, nil] Base items.
+      # @param environments [Hash{String => ConfigEnvironment}, nil]
+      #   Per-environment overrides keyed by environment id.
+      # @param created_at [Object, nil] Creation timestamp.
+      # @param updated_at [Object, nil] Last-modified timestamp.
       def initialize(client = nil, key:, id: nil, name: nil, description: nil,
                      parent_id: nil, items: nil, environments: nil,
                      created_at: nil, updated_at: nil)
@@ -97,14 +129,25 @@ module Smplkit
         @updated_at = updated_at
       end
 
+      # @return [Array<ConfigItem>] A read-only shallow copy of the base items.
       def items
         @items.dup
       end
 
+      # @return [Hash{String => ConfigEnvironment}] A read-only shallow copy of
+      #   the per-environment overrides keyed by environment id.
       def environments
         @environments.dup
       end
 
+      # Persist this config to the server. Creates a new config if unsaved, or
+      # updates the existing one.
+      #
+      # @return [self]
+      # @raise [Smplkit::NotFoundError] If the config no longer exists
+      #   (update).
+      # @raise [Smplkit::ValidationError] If the server rejects the request.
+      # @raise [RuntimeError] If the model was constructed without a client.
       def save
         raise "Config was constructed without a client; cannot save" if @client.nil?
 
@@ -119,6 +162,10 @@ module Smplkit
       end
       alias save! save
 
+      # Delete this config from the server.
+      #
+      # @return [void]
+      # @raise [RuntimeError] If the model was constructed without a client.
       def delete
         raise "Config was constructed without a client; cannot delete" if @client.nil?
 
@@ -126,26 +173,86 @@ module Smplkit
       end
       alias delete! delete
 
+      # Set (or replace) an item. When +environment:+ is given, sets an
+      # override on that environment.
+      #
+      # An environment override stores only the raw value; the declared type and
+      # description come from the base item, so the +ConfigItem+'s type and
+      # description are ignored when +environment:+ is supplied.
+      #
+      # @param item [ConfigItem] The item to set; its +name+ is the item key.
+      # @param environment [String, nil] When given, set the value as an
+      #   override on this environment rather than on the base config.
+      # @return [self]
+      def set(item, environment: nil)
+        set_typed(item.name, item.value, item.type, environment: environment, description: item.description)
+      end
+
+      # Convenience: set a STRING item (or environment override).
+      #
+      # @param name [String] The item key to set.
+      # @param value [String] The string value.
+      # @param environment [String, nil] When given, set the value as an
+      #   override on this environment rather than on the base config.
+      # @param description [String, nil] Optional human-readable description.
+      #   Ignored when setting an environment override.
+      # @return [self]
       def set_string(name, value, environment: nil, description: nil)
         set_typed(name, value, ItemType::STRING, environment: environment, description: description)
       end
 
+      # Convenience: set a NUMBER item (or environment override).
+      #
+      # @param name [String] The item key to set.
+      # @param value [Integer, Float] The numeric value.
+      # @param environment [String, nil] When given, set the value as an
+      #   override on this environment rather than on the base config.
+      # @param description [String, nil] Optional human-readable description.
+      #   Ignored when setting an environment override.
+      # @return [self]
       def set_number(name, value, environment: nil, description: nil)
         set_typed(name, value, ItemType::NUMBER, environment: environment, description: description)
       end
 
+      # Convenience: set a BOOLEAN item (or environment override).
+      #
+      # @param name [String] The item key to set.
+      # @param value [Boolean] The boolean value.
+      # @param environment [String, nil] When given, set the value as an
+      #   override on this environment rather than on the base config.
+      # @param description [String, nil] Optional human-readable description.
+      #   Ignored when setting an environment override.
+      # @return [self]
       def set_boolean(name, value, environment: nil, description: nil)
         set_typed(name, value, ItemType::BOOLEAN, environment: environment, description: description)
       end
 
+      # Convenience: set a JSON item (or environment override).
+      #
+      # @param name [String] The item key to set.
+      # @param value [Object] Any JSON-serializable value (Hash, Array, or
+      #   primitive).
+      # @param environment [String, nil] When given, set the value as an
+      #   override on this environment rather than on the base config.
+      # @param description [String, nil] Optional human-readable description.
+      #   Ignored when setting an environment override.
+      # @return [self]
       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)
+      # Remove an item by name. When +environment:+ is given, removes the
+      # per-environment override only. Removing an item that isn't present is a
+      # no-op.
+      #
+      # @param name [String] The item key to remove.
+      # @param environment [String, nil] When given, remove only this
+      #   environment's override for +name+, leaving the base item intact.
+      # @return [self]
+      def remove(name, environment: nil)
         if environment
           env = @environments[environment]
-          return unless env
+          return self unless env
 
           raw = env.values_raw
           raw.delete(name)
@@ -181,8 +288,8 @@ module Smplkit
             @items << ConfigItem.new(name: name, value: value, type: type, description: description)
           end
         else
-          # Per ADR-024 §2.4 env overrides carry the raw value only — type
-          # and description live on the base item, not on the override.
+          # Env overrides carry the raw value only — type and description live
+          # on the base item, not on the override.
           env = (@environments[environment] ||= ConfigEnvironment.new)
           raw = env.values_raw
           raw[name] = value

data/lib/smplkit/config_resolution.rb

@@ -4,6 +4,8 @@ require_relative "errors"
 
 module Smplkit
   # SDK configuration resolution: defaults -> file -> env vars -> constructor args.
+  #
+  # @api private
   module ConfigResolution
     CONFIG_KEYS = {
       "api_key" => "SMPLKIT_API_KEY",
@@ -33,8 +35,8 @@ module Smplkit
       keyword_init: true
     )
 
-    ResolvedManagementConfig = Struct.new(
-      :api_key, :base_domain, :scheme, :debug,
+    ResolvedClientConfig = Struct.new(
+      :api_key, :base_domain, :scheme, :debug, :extra_headers,
       keyword_init: true
     )
 
@@ -136,23 +138,29 @@ module Smplkit
       }
       ctor.each { |k, v| resolved[k] = v unless v.nil? }
 
-      missing_required(resolved, "environment", active_profile)
-      missing_required(resolved, "service", active_profile)
+      # Validate required fields.
+      #
+      # +environment+ and +service+ are OPTIONAL: an audit-only or jobs-only
+      # customer needs neither, and when +environment+ is absent the server
+      # derives it from the API key (the key can be scoped to an environment).
+      # config/flags/logging simply send no environment signal when it's unset.
+      # +api_key+ remains required.
       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,
+        # Preserve nil rather than coercing to the literal string "".
+        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)
+    def resolve_client_config(profile: nil, api_key: nil, base_domain: nil,
+                              scheme: nil, debug: nil, home_dir: nil)
       resolved = {
         "api_key" => nil,
         "base_domain" => "smplkit.com",
@@ -185,7 +193,7 @@ module Smplkit
 
       missing_required(resolved, "api_key", active_profile)
 
-      ResolvedManagementConfig.new(
+      ResolvedClientConfig.new(
         api_key: resolved["api_key"].to_s,
         base_domain: resolved["base_domain"].to_s,
         scheme: resolved["scheme"].to_s,

data/lib/smplkit/errors.rb

@@ -6,9 +6,9 @@ module Smplkit
   # A single error object from the server's JSON:API +errors+ array.
   #
   # +code+ is the application-specific machine-readable error code (e.g.
-  # +environment_unmanaged+); per JSON:API §7 and ADR-014, smplkit sets
-  # this on every error so callers can branch without string-matching
-  # the human +detail+. +meta+ carries additional structured context
+  # +environment_unmanaged+); smplkit sets this on every error so callers
+  # can branch without string-matching the human +detail+. +meta+ carries
+  # additional structured context
   # (e.g. <tt>{"environment" => "staging"}</tt>).
   class ApiErrorDetail
     attr_reader :status, :code, :title, :detail, :source, :meta
@@ -62,6 +62,7 @@ module Smplkit
       end
     end
 
+    # @api private — Build a human-readable message from a list of error details.
     def self.derive_message(errors)
       return "An API error occurred" if errors.nil? || errors.empty?
 
@@ -84,6 +85,16 @@ module Smplkit
   # subscription plan does not include the required entitlement.
   class PaymentRequiredError < Error; end
 
+  # Raised when a logging operation is attempted before +install+.
+  #
+  # Smpl Logging monkey-patches the standard logging framework, so it stays
+  # opt-in: its live surface requires an explicit +LoggingClient#install+
+  # first. Config and flags connect lazily on first live use and never raise
+  # this.
+  class NotInstalledError < Error; end
+
+  # @api private — Internal helpers that parse JSON:API error bodies and map
+  #   HTTP status codes onto the error classes above.
   module Errors
     module_function