smplkit 3.0.95 → 3.0.97

data/lib/smplkit/platform/models.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module Smplkit
+  module Platform
+    # Accept Color, hex string, or nil; reject anything else.
+    #
+    # @api private
+    def self.coerce_color(value)
+      return value if value.nil? || value.is_a?(Color)
+      return Color.new(value) if value.is_a?(String)
+
+      raise TypeError, "color must be a Color, hex string, or nil; got #{value.class}: #{value.inspect}"
+    end
+
+    # Environment resource (sync). Mutate fields, then call +save+.
+    class Environment
+      attr_accessor :id, :name, :classification, :created_at, :updated_at
+      attr_reader :color
+
+      # Create an environment instance.
+      #
+      # Prefer +client.platform.environments.new(...)+ to build an unsaved
+      # environment; this constructor is also used internally to wrap server
+      # responses.
+      #
+      # @param client [EnvironmentsClient, nil] Client used to persist and
+      #   delete this environment. +nil+ produces a detached instance that
+      #   cannot +save+.
+      # @param name [String] Display name shown in the Console.
+      # @param id [String, nil] Stable, human-readable identifier for the
+      #   environment.
+      # @param color [Color, String, nil] Accent color, as a +Color+ or a CSS
+      #   hex string. Defaults to no color.
+      # @param classification [String] Whether the environment participates in
+      #   the standard environment ordering. Defaults to
+      #   +EnvironmentClassification::STANDARD+.
+      # @param created_at [String, nil] When the environment was created. Set
+      #   on instances returned by the server; leave +nil+ for unsaved ones.
+      # @param updated_at [String, nil] When the environment was last updated.
+      #   Set on instances returned by the server; leave +nil+ for unsaved ones.
+      def initialize(client = nil, name:, id: nil, color: nil,
+                     classification: EnvironmentClassification::STANDARD,
+                     created_at: nil, updated_at: nil)
+        @client = client
+        @id = id
+        @name = name
+        @color = Platform.coerce_color(color)
+        @classification = classification
+        @created_at = created_at
+        @updated_at = updated_at
+      end
+
+      # Set the accent color, coercing the value to a +Color+.
+      #
+      # @param value [Color, String, nil] A +Color+, a CSS hex string, or +nil+
+      #   to clear the color.
+      # @return [void]
+      def color=(value)
+        @color = Platform.coerce_color(value)
+      end
+
+      # Create or update this environment on the server.
+      #
+      # @return [Environment] +self+, updated with the server response.
+      # @raise [RuntimeError] If this environment was constructed without a
+      #   client.
+      def save
+        raise "Environment was constructed without a client; cannot save" if @client.nil?
+
+        other = @created_at.nil? ? @client._create(self) : @client._update(self)
+        _apply(other)
+        self
+      end
+      alias save! save
+
+      # Delete this environment from the server.
+      #
+      # @return [void]
+      # @raise [RuntimeError] If this environment was constructed without a
+      #   client or id.
+      def delete
+        raise "Environment was constructed without a client or id; cannot delete" if @client.nil? || @id.nil?
+
+        @client.delete(@id)
+      end
+      alias delete! delete
+
+      def to_s
+        "Environment(id=#{@id.inspect}, name=#{@name.inspect}, classification=#{@classification.inspect})"
+      end
+      alias inspect to_s
+
+      # @api private
+      def _apply(other)
+        @id = other.id
+        @name = other.name
+        @color = other.color
+        @classification = other.classification
+        @created_at = other.created_at
+        @updated_at = other.updated_at
+      end
+    end
+
+    # Service resource (sync). Mutate fields, then call +save+.
+    class Service
+      attr_accessor :id, :name, :created_at, :updated_at
+
+      # Create a service instance.
+      #
+      # Prefer +client.platform.services.new(...)+ to build an unsaved service;
+      # this constructor is also used internally to wrap server responses.
+      #
+      # @param client [ServicesClient, nil] Client used to persist and delete
+      #   this service. +nil+ produces a detached instance that cannot +save+.
+      # @param name [String] Display name shown in the Console.
+      # @param id [String, nil] Stable, human-readable identifier for the
+      #   service.
+      # @param created_at [String, nil] When the service was created. Set on
+      #   instances returned by the server; leave +nil+ for unsaved ones.
+      # @param updated_at [String, nil] When the service was last updated. Set
+      #   on instances returned by the server; leave +nil+ for unsaved ones.
+      def initialize(client = nil, name:, id: nil, created_at: nil, updated_at: nil)
+        @client = client
+        @id = id
+        @name = name
+        @created_at = created_at
+        @updated_at = updated_at
+      end
+
+      # Create or update this service on the server.
+      #
+      # @return [Service] +self+, updated with the server response.
+      # @raise [RuntimeError] If this service was constructed without a client.
+      def save
+        raise "Service was constructed without a client; cannot save" if @client.nil?
+
+        other = @created_at.nil? ? @client._create(self) : @client._update(self)
+        _apply(other)
+        self
+      end
+      alias save! save
+
+      # Delete this service from the server.
+      #
+      # @return [void]
+      # @raise [RuntimeError] If this service was constructed without a client
+      #   or id.
+      def delete
+        raise "Service was constructed without a client or id; cannot delete" if @client.nil? || @id.nil?
+
+        @client.delete(@id)
+      end
+      alias delete! delete
+
+      def to_s
+        "Service(id=#{@id.inspect}, name=#{@name.inspect})"
+      end
+      alias inspect to_s
+
+      # @api private
+      def _apply(other)
+        @id = other.id
+        @name = other.name
+        @created_at = other.created_at
+        @updated_at = other.updated_at
+      end
+    end
+
+    # A context type resource (e.g. "user", "account").
+    class ContextType
+      attr_accessor :id, :name, :attributes, :created_at, :updated_at
+
+      # Create a context-type instance.
+      #
+      # Prefer +client.platform.context_types.new(...)+ to build an unsaved
+      # context type; this constructor is also used internally to wrap server
+      # responses.
+      #
+      # @param client [ContextTypesClient, nil] Client used to persist and
+      #   delete this context type. +nil+ produces a detached instance that
+      #   cannot +save+.
+      # @param name [String] Display name shown in the Console.
+      # @param id [String, nil] Stable, human-readable identifier for the
+      #   context type.
+      # @param attributes [Hash, nil] Known-attribute slots, keyed by attribute
+      #   name, with a metadata dict per slot. Defaults to no declared
+      #   attributes.
+      # @param created_at [String, nil] When the context type was created. Set
+      #   on instances returned by the server; leave +nil+ for unsaved ones.
+      # @param updated_at [String, nil] When the context type was last updated.
+      #   Set on instances returned by the server; leave +nil+ for unsaved ones.
+      def initialize(client = nil, name:, id: nil, attributes: nil, created_at: nil, updated_at: nil)
+        @client = client
+        @id = id
+        @name = name
+        @attributes = attributes ? deep_dup_attrs(attributes) : {}
+        @created_at = created_at
+        @updated_at = updated_at
+      end
+
+      # Add a known-attribute slot. Local-only; call +save+ to persist.
+      #
+      # @param name [String] Attribute name to declare on this context type.
+      # @param metadata [Hash] Arbitrary metadata stored for the attribute slot.
+      # @return [void]
+      def add_attribute(name, **metadata)
+        @attributes[name] = stringify_meta(metadata)
+      end
+
+      # Remove a known-attribute slot. Local-only; call +save+ to persist.
+      #
+      # @param name [String] Attribute name to remove. A no-op if the attribute
+      #   is not declared on this context type.
+      # @return [void]
+      def remove_attribute(name)
+        @attributes.delete(name)
+      end
+
+      # Replace a known-attribute slot's metadata. Local-only; call +save+.
+      #
+      # @param name [String] Attribute name whose metadata to replace.
+      # @param metadata [Hash] New metadata for the attribute slot, replacing
+      #   any existing metadata.
+      # @return [void]
+      def update_attribute(name, **metadata)
+        @attributes[name] = stringify_meta(metadata)
+      end
+
+      # Create or update this context type on the server.
+      #
+      # @return [ContextType] +self+, updated with the server response.
+      # @raise [RuntimeError] If this context type was constructed without a
+      #   client.
+      def save
+        raise "ContextType was constructed without a client; cannot save" if @client.nil?
+
+        other = @created_at.nil? ? @client._create(self) : @client._update(self)
+        _apply(other)
+        self
+      end
+      alias save! save
+
+      # Delete this context type from the server.
+      #
+      # @return [void]
+      # @raise [RuntimeError] If this context type was constructed without a
+      #   client or id.
+      def delete
+        raise "ContextType was constructed without a client or id; cannot delete" if @client.nil? || @id.nil?
+
+        @client.delete(@id)
+      end
+      alias delete! delete
+
+      def to_s
+        "ContextType(id=#{@id.inspect}, name=#{@name.inspect})"
+      end
+      alias inspect to_s
+
+      # @api private
+      def _apply(other)
+        @id = other.id
+        @name = other.name
+        @attributes = deep_dup_attrs(other.attributes)
+        @created_at = other.created_at
+        @updated_at = other.updated_at
+      end
+
+      private
+
+      def stringify_meta(metadata)
+        metadata.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+      end
+
+      def deep_dup_attrs(attrs)
+        attrs.each_with_object({}) do |(k, v), out|
+          out[k.to_s] = v.is_a?(Hash) ? stringify_meta(v) : v
+        end
+      end
+    end
+  end
+end

data/lib/smplkit/{management → platform}/types.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 module Smplkit
-  module Management
+  module Platform
     # Whether an environment participates in the canonical ordering.
     #
     # +STANDARD+ environments are the customer's deploy targets — production,
-    # staging, development, etc.
+    # staging, development, etc. They participate in
+    # +account.settings.environment_order+ and appear in the standard Console
+    # environment columns.
+    #
     # +AD_HOC+ environments are transient targets (preview branches, individual
     # developer sandboxes) that should not appear in the standard ordering.
     module EnvironmentClassification
@@ -28,6 +31,12 @@ module Smplkit
     class Color
       attr_reader :hex
 
+      # Build a +Color+ from a CSS hex string.
+      #
+      # @param hex [String] A CSS hex string like +"#RGB"+, +"#RRGGBB"+, or
+      #   +"#RRGGBBAA"+. Normalized to lowercase.
+      # @raise [TypeError] If +hex+ is not a String.
+      # @raise [ArgumentError] If +hex+ is not a valid CSS hex string.
       def initialize(hex)
         raise TypeError, "Color hex must be a String, got #{hex.class}: #{hex.inspect}" unless hex.is_a?(String)
         unless HEX_RE.match?(hex)
@@ -39,6 +48,14 @@ module Smplkit
         freeze
       end
 
+      # Construct a +Color+ from 0-255 RGB components.
+      #
+      # @param red [Integer] Red component, an integer in the range 0-255.
+      # @param green [Integer] Green component, an integer in the range 0-255.
+      # @param blue [Integer] Blue component, an integer in the range 0-255.
+      # @return [Color] A color with the equivalent hex value.
+      # @raise [TypeError] If any component is not an integer.
+      # @raise [ArgumentError] If any component is outside the range 0-255.
       def self.rgb(red, green, blue)
         [%w[red green blue], [red, green, blue]].transpose.each do |name, val|
           unless val.is_a?(Integer) && !val.is_a?(TrueClass) && !val.is_a?(FalseClass)
@@ -60,6 +77,6 @@ module Smplkit
     end
   end
 
-  Color = Management::Color
-  EnvironmentClassification = Management::EnvironmentClassification
+  Color = Platform::Color
+  EnvironmentClassification = Platform::EnvironmentClassification
 end

data/lib/smplkit/transport.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Smplkit
+  # Internal per-service HTTP transport construction.
+  #
+  # The top-level +Smplkit::Client+ needs one authenticated transport per
+  # backend service (app, config, flags, logging, jobs) plus a
+  # context-registration buffer that +client.platform+ owns. This module builds
+  # them in one place so the construction is side-effect-free (transports
+  # connect lazily on first call) and shared by the top-level client.
+  #
+  # There is no audit transport here — +client.audit+ owns its own.
+  #
+  # @api private
+  module Transport
+    SDK_OWNED_HEADERS = %w[authorization content-type user-agent].freeze
+
+    module_function
+
+    # Project the runtime +ResolvedConfig+ down to the transport subset.
+    #
+    # The top-level client's resolved config is a superset of what the
+    # transports need; this drops the runtime-only fields (environment,
+    # service, telemetry).
+    def to_transport_config(cfg, extra_headers = nil)
+      ConfigResolution::ResolvedClientConfig.new(
+        api_key: cfg.api_key,
+        base_domain: cfg.base_domain,
+        scheme: cfg.scheme,
+        debug: cfg.debug,
+        extra_headers: extra_headers
+      )
+    end
+
+    # The per-service authenticated transports built for a top-level client.
+    #
+    # Construction is side-effect-free: each transport connects lazily on its
+    # first call. +app_url+ is carried alongside so the account settings client
+    # and the WebSocket can reach the app service. +close+ tears down the
+    # underlying Faraday connection pools.
+    #
+    # @api private
+    ServiceTransports = Struct.new(
+      :app_url, :api_key, :app_http, :config_http, :flags_http, :logging_http, :jobs_http,
+      keyword_init: true
+    ) do
+      def close
+        # The generated ApiClient owns Faraday connections that release on GC.
+        # No explicit shutdown is exposed; this stub keeps the API stable.
+      end
+    end
+
+    # Build the five per-service transports from a resolved transport config.
+    #
+    # Side-effect-free — the underlying Faraday clients are created lazily on
+    # the first request. Smpl Jobs is JSON:API, so its transport carries the
+    # +application/vnd.api+json+ Accept header.
+    def build_service_transports(cfg)
+      app_url = ConfigResolution.service_url(cfg.scheme, "app", cfg.base_domain)
+      ServiceTransports.new(
+        app_url: app_url,
+        api_key: cfg.api_key,
+        app_http: build_api_client(SmplkitGeneratedClient::App, "app", cfg),
+        config_http: build_api_client(SmplkitGeneratedClient::Config, "config", cfg),
+        flags_http: build_api_client(SmplkitGeneratedClient::Flags, "flags", cfg),
+        logging_http: build_api_client(SmplkitGeneratedClient::Logging, "logging", cfg),
+        jobs_http: build_api_client(SmplkitGeneratedClient::Jobs, "jobs", cfg,
+                                    accept: "application/vnd.api+json")
+      )
+    end
+
+    # Build a generated +ApiClient+ for one service from a resolved config.
+    #
+    # +base_url+, when supplied, overrides the +scheme+/+host+ derived from
+    # +subdomain+/+base_domain+ (the path a standalone product client takes
+    # when handed a fully-resolved app URL).
+    def build_api_client(generated_module, subdomain, cfg, accept: nil, base_url: nil)
+      configuration = generated_module::Configuration.new
+      if base_url.nil?
+        configuration.scheme = cfg.scheme
+        configuration.host = "#{subdomain}.#{cfg.base_domain}"
+      else
+        uri = URI.parse(base_url)
+        configuration.scheme = uri.scheme
+        port_suffix = uri.port && ![80, 443].include?(uri.port) ? ":#{uri.port}" : ""
+        configuration.host = "#{uri.host}#{port_suffix}"
+      end
+      configuration.base_path = ""
+      configuration.access_token = cfg.api_key
+      configuration.debugging = cfg.debug
+      HttpPool.configure(configuration)
+      generated_module::ApiClient.new(configuration).tap do |client|
+        client.default_headers["User-Agent"] = "smplkit-ruby-sdk/#{Smplkit::VERSION}"
+        client.default_headers["Accept"] = accept if accept
+        (cfg.extra_headers || {}).each do |k, v|
+          client.default_headers[k] = v unless SDK_OWNED_HEADERS.include?(k.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/smplkit/ws.rb

@@ -19,7 +19,7 @@ module Smplkit
   # +Async+ reactor and the underlying +async-websocket+ I/O. Public
   # methods are thread-safe and non-blocking.
   #
-  # Gateway protocol (mirrors the Python reference in +smplkit._ws+):
+  # Gateway protocol:
   #
   #   - Connect to +wss://app.<base_domain>/api/ws/v1/events?api_key={key}+
   #   - Receive +{"type": "connected"}+ on success

data/lib/smplkit.rb

@@ -44,9 +44,25 @@ require_relative "smplkit/context"
 require_relative "smplkit/config_resolution"
 require_relative "smplkit/metrics"
 require_relative "smplkit/ws"
+
+# Internal foundation shared by every product client.
+require_relative "smplkit/buffers"
+require_relative "smplkit/api_support"
+require_relative "smplkit/transport"
+
+# Flags types (incl. Context) load before platform, which references Context.
 require_relative "smplkit/flags/types"
 require_relative "smplkit/flags/models"
 require_relative "smplkit/flags/helpers"
+
+# Platform + account (the cross-cutting surfaces) before the product clients
+# that borrow them.
+require_relative "smplkit/platform/types"
+require_relative "smplkit/platform/models"
+require_relative "smplkit/platform/client"
+require_relative "smplkit/account/models"
+require_relative "smplkit/account/client"
+
 require_relative "smplkit/flags/client"
 require_relative "smplkit/config/models"
 require_relative "smplkit/config/helpers"
@@ -66,14 +82,10 @@ require_relative "smplkit/audit/events"
 require_relative "smplkit/audit/resource_types"
 require_relative "smplkit/audit/event_types"
 require_relative "smplkit/audit/categories"
+require_relative "smplkit/audit/forwarders"
 require_relative "smplkit/audit/client"
 require_relative "smplkit/jobs/models"
-require_relative "smplkit/management/types"
-require_relative "smplkit/management/models"
-require_relative "smplkit/management/buffer"
-require_relative "smplkit/management/audit"
-require_relative "smplkit/management/jobs"
-require_relative "smplkit/management/client"
+require_relative "smplkit/jobs/client"
 require_relative "smplkit/client"
 
 require_relative "smplkit/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smplkit
 version: !ruby/object:Gem::Version
-  version: 3.0.95
+  version: 3.0.97
 platform: ruby
 authors:
 - Smpl Solutions LLC
@@ -879,13 +879,18 @@ files:
 - lib/smplkit/_generated/logging/spec/models/usage_list_response_spec.rb
 - lib/smplkit/_generated/logging/spec/models/usage_resource_spec.rb
 - lib/smplkit/_generated/logging/spec/spec_helper.rb
+- lib/smplkit/account/client.rb
+- lib/smplkit/account/models.rb
+- lib/smplkit/api_support.rb
 - lib/smplkit/audit/buffer.rb
 - lib/smplkit/audit/categories.rb
 - lib/smplkit/audit/client.rb
 - lib/smplkit/audit/event_types.rb
 - lib/smplkit/audit/events.rb
+- lib/smplkit/audit/forwarders.rb
 - lib/smplkit/audit/models.rb
 - lib/smplkit/audit/resource_types.rb
+- lib/smplkit/buffers.rb
 - lib/smplkit/client.rb
 - lib/smplkit/config/client.rb
 - lib/smplkit/config/helpers.rb
@@ -901,6 +906,7 @@ files:
 - lib/smplkit/generators/install_generator.rb
 - lib/smplkit/helpers.rb
 - lib/smplkit/http_pool.rb
+- lib/smplkit/jobs/client.rb
 - lib/smplkit/jobs/models.rb
 - lib/smplkit/log_level.rb
 - lib/smplkit/logging/adapters/base.rb
@@ -913,14 +919,12 @@ files:
 - lib/smplkit/logging/normalize.rb
 - lib/smplkit/logging/resolution.rb
 - lib/smplkit/logging/sources.rb
-- lib/smplkit/management/audit.rb
-- lib/smplkit/management/buffer.rb
-- lib/smplkit/management/client.rb
-- lib/smplkit/management/jobs.rb
-- lib/smplkit/management/models.rb
-- lib/smplkit/management/types.rb
 - lib/smplkit/metrics.rb
+- lib/smplkit/platform/client.rb
+- lib/smplkit/platform/models.rb
+- lib/smplkit/platform/types.rb
 - lib/smplkit/railtie.rb
+- lib/smplkit/transport.rb
 - lib/smplkit/version.rb
 - lib/smplkit/ws.rb
 - sig/smplkit.rbs