smplkit 3.0.96 → 3.0.97

data/lib/smplkit/platform/client.rb

@@ -26,6 +26,8 @@
 module Smplkit
   module Platform
     # Resolve the two-arg or composite-id form to +[type, key]+.
+    #
+    # @api private
     def self.split_context_id(id_or_type, key)
       return [id_or_type, key] unless key.nil?
 
@@ -42,17 +44,19 @@ module Smplkit
     #
     # +base_url+/+api_key+ are used directly when supplied (the path the
     # top-level client takes after it has already resolved them); otherwise the
-    # management config resolver fills in whatever is missing (+~/.smplkit+ /
-    # env vars / defaults).
+    # config resolver fills in whatever is missing (+~/.smplkit+ / env vars /
+    # defaults).
+    #
+    # @api private
     def self.app_transport(api_key:, base_url:, profile:, base_domain:, scheme:, debug:, extra_headers:)
-      cfg = ConfigResolution.resolve_management_config(
+      cfg = ConfigResolution.resolve_client_config(
         profile: profile, api_key: api_key, base_domain: base_domain, scheme: scheme, debug: debug
       )
       resolved_key = api_key.nil? ? cfg.api_key : api_key
       merged = {}
       merged.merge!(cfg.extra_headers || {})
       merged.merge!(extra_headers || {})
-      tcfg = ConfigResolution::ResolvedManagementConfig.new(
+      tcfg = ConfigResolution::ResolvedClientConfig.new(
         api_key: resolved_key, base_domain: cfg.base_domain, scheme: cfg.scheme,
         debug: cfg.debug, extra_headers: merged
       )
@@ -69,11 +73,28 @@ module Smplkit
         @api = SmplkitGeneratedClient::App::EnvironmentsApi.new(app_http)
       end
 
-      # Return an unsaved +Environment+. Call +.save+ to persist.
+      # Build an unsaved +Environment+; call +.save+ to persist it.
+      #
+      # @param id [String] Stable, human-readable identifier for the
+      #   environment (for example +"production"+).
+      # @param name [String] Display name shown in the Console.
+      # @param color [Color, String, nil] Accent color for the environment, 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+.
+      # @return [Environment] An unsaved environment bound to this client.
       def new(id, name:, color: nil, classification: EnvironmentClassification::STANDARD)
         Environment.new(self, id: id, name: name, color: color, classification: classification)
       end
 
+      # List environments in the account.
+      #
+      # @param page_number [Integer, nil] 1-based page to fetch. Defaults to
+      #   the first page.
+      # @param page_size [Integer, nil] Maximum number of environments per
+      #   page. Defaults to the server's page size.
+      # @return [Array<Environment>] The environments on the requested page.
       def list(page_number: nil, page_size: nil)
         opts = {}
         opts[:page_number] = page_number unless page_number.nil?
@@ -82,21 +103,32 @@ module Smplkit
         (response.data || []).map { |r| from_resource(ApiSupport::ResourceShim.from_model(r)) }
       end
 
+      # Fetch a single environment by id.
+      #
+      # @param id [String] Identifier of the environment to fetch.
+      # @return [Environment] The matching environment.
+      # @raise [Smplkit::NotFoundError] If no environment with that id exists.
       def get(id)
         response = ApiSupport::ErrorMapping.call { @api.get_environment(id) }
         from_resource(ApiSupport::ResourceShim.from_model(response.data))
       end
 
+      # Delete an environment by id.
+      #
+      # @param id [String] Identifier of the environment to delete.
+      # @return [void]
       def delete(id)
         ApiSupport::ErrorMapping.call { @api.delete_environment(id) }
         nil
       end
 
+      # @api private
       def _create(env)
         response = ApiSupport::ErrorMapping.call { @api.create_environment(body_for(env)) }
         from_resource(ApiSupport::ResourceShim.from_model(response.data))
       end
 
+      # @api private
       def _update(env)
         raise "cannot update an Environment with no id" if env.id.nil?
 
@@ -143,11 +175,22 @@ module Smplkit
         @api = SmplkitGeneratedClient::App::ServicesApi.new(app_http)
       end
 
-      # Return an unsaved +Service+. Call +.save+ to persist.
+      # Build an unsaved +Service+; call +.save+ to persist it.
+      #
+      # @param id [String] Stable, human-readable identifier for the service.
+      # @param name [String] Display name shown in the Console.
+      # @return [Service] An unsaved service bound to this client.
       def new(id, name:)
         Service.new(self, id: id, name: name)
       end
 
+      # List services in the account.
+      #
+      # @param page_number [Integer, nil] 1-based page to fetch. Defaults to
+      #   the first page.
+      # @param page_size [Integer, nil] Maximum number of services per page.
+      #   Defaults to the server's page size.
+      # @return [Array<Service>] The services on the requested page.
       def list(page_number: nil, page_size: nil)
         opts = {}
         opts[:page_number] = page_number unless page_number.nil?
@@ -156,21 +199,32 @@ module Smplkit
         (response.data || []).map { |r| from_resource(ApiSupport::ResourceShim.from_model(r)) }
       end
 
+      # Fetch a single service by id.
+      #
+      # @param id [String] Identifier of the service to fetch.
+      # @return [Service] The matching service.
+      # @raise [Smplkit::NotFoundError] If no service with that id exists.
       def get(id)
         response = ApiSupport::ErrorMapping.call { @api.get_service(id) }
         from_resource(ApiSupport::ResourceShim.from_model(response.data))
       end
 
+      # Delete a service by id.
+      #
+      # @param id [String] Identifier of the service to delete.
+      # @return [void]
       def delete(id)
         ApiSupport::ErrorMapping.call { @api.delete_service(id) }
         nil
       end
 
+      # @api private
       def _create(svc)
         response = ApiSupport::ErrorMapping.call { @api.create_service(create_body_for(svc)) }
         from_resource(ApiSupport::ResourceShim.from_model(response.data))
       end
 
+      # @api private
       def _update(svc)
         raise "cannot update a Service with no id" if svc.id.nil?
 
@@ -220,10 +274,27 @@ module Smplkit
         @api = SmplkitGeneratedClient::App::ContextTypesApi.new(app_http)
       end
 
+      # Build an unsaved +ContextType+; call +.save+ to persist it.
+      #
+      # @param id [String] Stable, human-readable identifier for the context
+      #   type (for example +"user"+).
+      # @param name [String, nil] Display name shown in the Console. Defaults
+      #   to +id+ when omitted.
+      # @param attributes [Hash, nil] Known-attribute slots, keyed by attribute
+      #   name, with a metadata dict per slot. Defaults to no declared
+      #   attributes.
+      # @return [ContextType] An unsaved context type bound to this client.
       def new(id, name: nil, attributes: nil)
         ContextType.new(self, id: id, name: name || id, attributes: attributes || {})
       end
 
+      # List context types in the account.
+      #
+      # @param page_number [Integer, nil] 1-based page to fetch. Defaults to
+      #   the first page.
+      # @param page_size [Integer, nil] Maximum number of context types per
+      #   page. Defaults to the server's page size.
+      # @return [Array<ContextType>] The context types on the requested page.
       def list(page_number: nil, page_size: nil)
         opts = {}
         opts[:page_number] = page_number unless page_number.nil?
@@ -232,21 +303,32 @@ module Smplkit
         (response.data || []).map { |r| from_resource(ApiSupport::ResourceShim.from_model(r)) }
       end
 
+      # Fetch a single context type by id.
+      #
+      # @param id [String] Identifier of the context type to fetch.
+      # @return [ContextType] The matching context type.
+      # @raise [Smplkit::NotFoundError] If no context type with that id exists.
       def get(id)
         response = ApiSupport::ErrorMapping.call { @api.get_context_type(id) }
         from_resource(ApiSupport::ResourceShim.from_model(response.data))
       end
 
+      # Delete a context type by id.
+      #
+      # @param id [String] Identifier of the context type to delete.
+      # @return [void]
       def delete(id)
         ApiSupport::ErrorMapping.call { @api.delete_context_type(id) }
         nil
       end
 
+      # @api private
       def _create(ct)
         response = ApiSupport::ErrorMapping.call { @api.create_context_type(body_for(ct)) }
         from_resource(ApiSupport::ResourceShim.from_model(response.data))
       end
 
+      # @api private
       def _update(ct)
         raise "cannot update a ContextType with no id" if ct.id.nil?
 
@@ -289,7 +371,18 @@ module Smplkit
         @buffer = buffer
       end
 
-      # Buffer contexts for registration; optionally flush immediately.
+      # Buffer one or more contexts for registration.
+      #
+      # Buffered contexts are sent in batches: a background flush kicks in once
+      # enough have accumulated, and any remainder is sent on the next explicit
+      # flush. Pass +flush: true+ to send everything buffered right away.
+      #
+      # @param items [Context, Array<Context>] A single context or a list of
+      #   contexts to register.
+      # @param flush [Boolean] When +true+, send all buffered contexts
+      #   immediately rather than waiting for the batch threshold. Defaults to
+      #   +false+.
+      # @return [void]
       def register(items, flush: false)
         batch = items.is_a?(Array) ? items : [items]
         @buffer.observe(batch)
@@ -303,6 +396,8 @@ module Smplkit
       end
 
       # Send any pending observations to the server.
+      #
+      # @return [void]
       def flush
         batch = @buffer.drain
         return if batch.empty?
@@ -312,11 +407,21 @@ module Smplkit
       end
 
       # Number of observations queued and awaiting flush.
+      #
+      # @return [Integer] The count of observations pending flush.
       def pending_count
         @buffer.pending_count
       end
 
       # List all contexts of a given type.
+      #
+      # @param type [String] Context type to list (for example +"user"+).
+      # @param page_number [Integer, nil] 1-based page to fetch. Defaults to
+      #   the first page.
+      # @param page_size [Integer, nil] Maximum number of contexts per page.
+      #   Defaults to the server's page size.
+      # @return [Array<Context>] The contexts of the given type on the
+      #   requested page.
       def list(type, page_number: nil, page_size: nil)
         opts = { filter_context_type: type }
         opts[:page_number] = page_number unless page_number.nil?
@@ -325,18 +430,38 @@ module Smplkit
         (response.data || []).map { |r| context_from_resource(ApiSupport::ResourceShim.from_model(r)) }
       end
 
+      # Fetch a single context, identified by composite id or by type and key.
+      #
+      # @param id_or_type [String] Either the composite context id +"type:key"+
+      #   (when +key+ is omitted) or just the context type (when +key+ is
+      #   supplied).
+      # @param key [String, nil] The context key. Provide it to use the
+      #   two-argument form; omit it when +id_or_type+ already carries the
+      #   composite id.
+      # @return [Context] The matching context.
+      # @raise [Smplkit::NotFoundError] If no context with that id exists.
       def get(id_or_type, key = nil)
         ctx_type, ctx_key = Platform.split_context_id(id_or_type, key)
         response = ApiSupport::ErrorMapping.call { @api.get_context("#{ctx_type}:#{ctx_key}") }
         context_from_resource(ApiSupport::ResourceShim.from_model(response.data))
       end
 
+      # Delete a single context, identified by composite id or by type and key.
+      #
+      # @param id_or_type [String] Either the composite context id +"type:key"+
+      #   (when +key+ is omitted) or just the context type (when +key+ is
+      #   supplied).
+      # @param key [String, nil] The context key. Provide it to use the
+      #   two-argument form; omit it when +id_or_type+ already carries the
+      #   composite id.
+      # @return [void]
       def delete(id_or_type, key = nil)
         ctx_type, ctx_key = Platform.split_context_id(id_or_type, key)
         ApiSupport::ErrorMapping.call { @api.delete_context("#{ctx_type}:#{ctx_key}") }
         nil
       end
 
+      # @api private
       def _save_context(ctx)
         body = ctx_to_resource(ctx)
         response = ApiSupport::ErrorMapping.call { @api.update_context(ctx.id, body) }

data/lib/smplkit/platform/models.rb

@@ -3,6 +3,8 @@
 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)
@@ -15,6 +17,27 @@ module Smplkit
       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)
@@ -27,11 +50,20 @@ module Smplkit
         @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?
 
@@ -42,6 +74,10 @@ module Smplkit
       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?
 
@@ -54,6 +90,7 @@ module Smplkit
       end
       alias inspect to_s
 
+      # @api private
       def _apply(other)
         @id = other.id
         @name = other.name
@@ -68,6 +105,20 @@ module Smplkit
     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
@@ -77,6 +128,9 @@ module Smplkit
       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?
 
@@ -87,6 +141,10 @@ module Smplkit
       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?
 
@@ -99,6 +157,7 @@ module Smplkit
       end
       alias inspect to_s
 
+      # @api private
       def _apply(other)
         @id = other.id
         @name = other.name
@@ -111,6 +170,25 @@ module Smplkit
     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
@@ -120,22 +198,39 @@ module Smplkit
         @updated_at = updated_at
       end
 
-      # Add a known-attribute slot. Local; call +save+ to persist.
+      # 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; call +save+ to persist.
+      # 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; call +save+.
+      # 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?
 
@@ -146,6 +241,10 @@ module Smplkit
       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?
 
@@ -158,6 +257,7 @@ module Smplkit
       end
       alias inspect to_s
 
+      # @api private
       def _apply(other)
         @id = other.id
         @name = other.name

data/lib/smplkit/platform/types.rb

@@ -31,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)
@@ -42,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)

data/lib/smplkit/transport.rb

@@ -12,6 +12,8 @@ module Smplkit
   # 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
 
@@ -23,7 +25,7 @@ module Smplkit
     # transports need; this drops the runtime-only fields (environment,
     # service, telemetry).
     def to_transport_config(cfg, extra_headers = nil)
-      ConfigResolution::ResolvedManagementConfig.new(
+      ConfigResolution::ResolvedClientConfig.new(
         api_key: cfg.api_key,
         base_domain: cfg.base_domain,
         scheme: cfg.scheme,
@@ -38,6 +40,8 @@ module Smplkit
     # 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

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smplkit
 version: !ruby/object:Gem::Version
-  version: 3.0.96
+  version: 3.0.97
 platform: ruby
 authors:
 - Smpl Solutions LLC