smplkit 3.0.96 → 3.0.97

data/lib/smplkit/flags/models.rb

@@ -99,11 +99,21 @@ module Smplkit
       end
 
       # Read-only view of constrained values. +nil+ means unconstrained.
+      #
+      # Mutate via +add_value+ / +remove_value+ / +clear_values+.
+      #
+      # @return [Array<FlagValue>, nil] the constrained values, or +nil+ when
+      #   the flag is unconstrained.
       def values
         @values&.dup
       end
 
       # Read-only view of per-environment configuration.
+      #
+      # Mutate via +add_rule+ / +enable_rules+ / +disable_rules+ /
+      # +set_default+ (with +environment:+) / +clear_rules+.
+      #
+      # @return [Hash{String => FlagEnvironment}] the per-environment configuration.
       def environments
         @environments.dup
       end
@@ -111,8 +121,10 @@ module Smplkit
       # 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+).
+      # client (i.e. the flag was constructed via +client.flags.new_*+ or
+      # returned from +client.flags.get+ / +client.flags.list+).
+      #
+      # @return [self] this flag, with server-assigned fields applied.
       def save
         raise "Flag was constructed without a client; cannot save" if @client.nil?
 
@@ -127,6 +139,10 @@ module Smplkit
       end
       alias save! save
 
+      # Delete this flag from the server.
+      #
+      # @return [void]
+      # @raise [Smplkit::NotFoundError] no flag with this id exists for the account.
       def delete
         raise "Flag was constructed without a client or id; cannot delete" if @client.nil? || @id.nil?
 
@@ -138,6 +154,12 @@ module Smplkit
       #
       # The +built_rule+ Hash must include an +"environment"+ key.
       # Call +save+ to persist.
+      #
+      # @param built_rule [Hash] the Hash produced by
+      #   +Smplkit::Rule.new(..., environment: ...).when(...).serve(...)+; must
+      #   include an +"environment"+ key naming the target environment.
+      # @return [self] this flag, so calls can be chained.
+      # @raise [ArgumentError] the +built_rule+ Hash has no +"environment"+ key.
       def add_rule(built_rule)
         env_key = built_rule["environment"]
         if env_key.nil?
@@ -156,16 +178,37 @@ module Smplkit
         self
       end
 
+      # Enable rule evaluation. Call +save+ to persist.
+      #
+      # @param environment [String, nil] name of the environment to enable; when
+      #   +nil+ (the default), enables rules in every environment configured on
+      #   this flag.
+      # @return [self] this flag, so calls can be chained.
       def enable_rules(environment: nil)
         scoped(environment) { |k| @environments[k] = (@environments[k] || FlagEnvironment.new).with(enabled: true) }
         self
       end
 
+      # Disable rule evaluation (kill switch). Call +save+ to persist.
+      #
+      # When disabled, +get+ skips rules and returns the env-specific default
+      # (or the flag's base default).
+      #
+      # @param environment [String, nil] name of the environment to disable; when
+      #   +nil+ (the default), disables rules in every environment configured on
+      #   this flag.
+      # @return [self] this flag, so calls can be chained.
       def disable_rules(environment: nil)
         scoped(environment) { |k| @environments[k] = (@environments[k] || FlagEnvironment.new).with(enabled: false) }
         self
       end
 
+      # Remove rules. Call +save+ to persist.
+      #
+      # @param environment [String, nil] name of the environment whose rules to
+      #   remove; when +nil+ (the default), removes rules from every environment
+      #   configured on this flag.
+      # @return [self] this flag, so calls can be chained.
       def clear_rules(environment: nil)
         scoped(environment) do |k|
           @environments[k] = (@environments[k] || FlagEnvironment.new).with(rules: [].freeze)
@@ -173,22 +216,44 @@ module Smplkit
         self
       end
 
+      # Set the flag's per-environment default served value. Call +save+ to persist.
+      #
+      # @param value [Object] the default value to serve when no rule matches.
+      # @param environment [String] name of the environment whose default to set.
+      # @return [self] this flag, so calls can be chained.
       def set_default(value, environment:)
         @environments[environment] = (@environments[environment] || FlagEnvironment.new).with(default: value)
         self
       end
 
+      # Clear the per-environment default override on +environment+.
+      #
+      # After clearing, the environment falls back to the flag's base default
+      # when no rule matches. Call +save+ to persist.
+      #
+      # @param environment [String] name of the environment whose default
+      #   override to clear.
+      # @return [self] this flag, so calls can be chained.
       def clear_default(environment:)
         @environments[environment] = (@environments[environment] || FlagEnvironment.new).with(default: nil)
         self
       end
 
+      # Append a constrained value to the flag's values list. Call +save+ to persist.
+      #
+      # @param flag_value [FlagValue] the value entry to allow the flag to serve.
+      # @return [self] this flag, so calls can be chained.
       def add_value(flag_value)
         @values ||= []
         @values << flag_value
         self
       end
 
+      # Remove the first values entry whose +name+ matches.
+      #
+      # @param name [String] the value-entry name to remove; the first match is
+      #   removed and others are left in place.
+      # @return [self] this flag, so calls can be chained.
       def remove_value(name)
         return self unless @values
 
@@ -196,6 +261,9 @@ module Smplkit
         self
       end
 
+      # Clear the constrained values list (unconstrained). Call +save+ to persist.
+      #
+      # @return [self] this flag, so calls can be chained.
       def clear_values
         @values = []
         self
@@ -225,28 +293,62 @@ module Smplkit
     end
 
     class BooleanFlag < Flag
+      # Evaluate this flag and return its current boolean value.
+      #
+      # @param context [Array<Smplkit::Context>, nil] optional entities to
+      #   evaluate targeting rules against; when omitted the ambient request
+      #   context (if any) is used.
+      # @return [Boolean] the evaluated boolean value, or this flag's default
+      #   when no environment override or rule applies (or the evaluated value
+      #   is not a boolean).
       def get(context: nil)
-        raw = @client._evaluate_handle(@id, @default, context)
-        !!raw
+        value = @client._evaluate_handle(@id, @default, context)
+        [true, false].include?(value) ? value : @default
       end
     end
 
     class StringFlag < Flag
+      # Evaluate this flag and return its current string value.
+      #
+      # @param context [Array<Smplkit::Context>, nil] optional entities to
+      #   evaluate targeting rules against; when omitted the ambient request
+      #   context (if any) is used.
+      # @return [String] the evaluated string value, or this flag's default
+      #   when no environment override or rule applies (or the evaluated value
+      #   is not a String).
       def get(context: nil)
-        raw = @client._evaluate_handle(@id, @default, context)
-        raw.to_s
+        value = @client._evaluate_handle(@id, @default, context)
+        value.is_a?(String) ? value : @default
       end
     end
 
     class NumberFlag < Flag
+      # Evaluate this flag and return its current numeric value.
+      #
+      # @param context [Array<Smplkit::Context>, nil] optional entities to
+      #   evaluate targeting rules against; when omitted the ambient request
+      #   context (if any) is used.
+      # @return [Numeric] the evaluated numeric value, or this flag's default
+      #   when no environment override or rule applies (or the evaluated value
+      #   is not a Numeric).
       def get(context: nil)
-        @client._evaluate_handle(@id, @default, context)
+        value = @client._evaluate_handle(@id, @default, context)
+        value.is_a?(Numeric) ? value : @default
       end
     end
 
     class JsonFlag < Flag
+      # Evaluate this flag and return its current JSON value.
+      #
+      # @param context [Array<Smplkit::Context>, nil] optional entities to
+      #   evaluate targeting rules against; when omitted the ambient request
+      #   context (if any) is used.
+      # @return [Hash] the evaluated JSON object, or this flag's default when no
+      #   environment override or rule applies (or the evaluated value is not a
+      #   Hash).
       def get(context: nil)
-        @client._evaluate_handle(@id, @default, context)
+        value = @client._evaluate_handle(@id, @default, context)
+        value.is_a?(Hash) ? value : @default
       end
     end
   end

data/lib/smplkit/flags/types.rb

@@ -67,8 +67,8 @@ module Smplkit
       @attributes = stringify_keys(new_attrs || {})
     end
 
-    # Internal: associate a management client with this context so save/delete
-    # can route through it.
+    # @api private — associate a client with this context so save/delete can
+    #   route through it.
     def _bind_client(client)
       @client = client
       self

data/lib/smplkit/jobs/client.rb

@@ -23,14 +23,17 @@ module Smplkit
         @api = api
       end
 
-      # List runs for the authenticated account, newest first. Cursor paginated
-      # (ADR-014): pass +page_size+ and the +after+ cursor from the prior page.
-      # Pass +job+ to scope to a single job's history.
+      # List past runs, most recent first. Cursor paginated: pass +page_size+
+      # and the +after+ cursor from the prior page. Pass +job+ to scope to a
+      # single job's history.
       #
-      # @param job [String, nil] Filter to a single job's run history, by job id.
-      # @param page_size [Integer, nil] Items per page (cursor pagination).
-      # @param after [String, nil] Opaque cursor token from a prior page.
-      # @return [Array<Smplkit::Jobs::Run>]
+      # @param job [String, nil] Return only runs of the job with this id.
+      #   +nil+ lists runs across all jobs in the account.
+      # @param page_size [Integer, nil] Maximum number of runs to return in this
+      #   page. +nil+ uses the server default.
+      # @param after [String, nil] Opaque cursor from a previous page; returns
+      #   the runs that follow it. +nil+ starts from the first page.
+      # @return [Array<Smplkit::Jobs::Run>] The runs in this page.
       def list(job: nil, page_size: nil, after: nil)
         opts = {}
         opts[:filter_job] = job unless job.nil?
@@ -41,28 +44,30 @@ module Smplkit
         (resp.data || []).map { |r| Run.from_resource(r) }
       end
 
-      # Fetch a single run by id.
+      # Fetch a single run by its id.
       #
-      # @param run_id [String]
-      # @return [Smplkit::Jobs::Run]
+      # @param run_id [String] Identifier of the run to fetch.
+      # @return [Smplkit::Jobs::Run] The matching run.
+      # @raise [Smplkit::NotFoundError] when no run with this id exists.
       def get(run_id)
         resp = Jobs.call_api { @api.get_run(run_id) }
         Run.from_resource(resp.data)
       end
 
-      # Cancel a pending run.
+      # Cancel a run that has not finished yet.
       #
-      # @param run_id [String]
-      # @return [Smplkit::Jobs::Run]
+      # @param run_id [String] Identifier of the run to cancel.
+      # @return [Smplkit::Jobs::Run] The updated run reflecting the cancellation.
       def cancel(run_id)
         resp = Jobs.call_api { @api.cancel_run(run_id) }
         Run.from_resource(resp.data)
       end
 
-      # Re-run a prior run, spawning a new +RERUN+ run.
+      # Start a new run that repeats a previous one.
       #
-      # @param run_id [String]
-      # @return [Smplkit::Jobs::Run]
+      # @param run_id [String] Identifier of the run to repeat.
+      # @return [Smplkit::Jobs::Run] The new run, with +rerun_of+ set to the
+      #   source +run_id+.
       def rerun(run_id)
         resp = Jobs.call_api { @api.rerun_run(run_id) }
         Run.from_resource(resp.data)
@@ -88,13 +93,13 @@ module Smplkit
     # exactly like the top-level clients do. Smpl Jobs is JSON:API, so the
     # transport carries the +application/vnd.api+json+ Accept header.
     def self.jobs_transport(api_key:, 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
       )
       merged = {}
       merged.merge!(cfg.extra_headers || {})
       merged.merge!(extra_headers || {})
-      tcfg = ConfigResolution::ResolvedManagementConfig.new(
+      tcfg = ConfigResolution::ResolvedClientConfig.new(
         api_key: cfg.api_key, base_domain: cfg.base_domain, scheme: cfg.scheme,
         debug: cfg.debug, extra_headers: merged
       )
@@ -111,6 +116,17 @@ module Smplkit
       # @return [RunsClient] Run history and run actions (+client.jobs.runs+).
       attr_reader :runs
 
+      # @param api_key [String, nil] API key. When omitted, resolved from
+      #   +SMPLKIT_API_KEY+ or +~/.smplkit+.
+      # @param profile [String, nil] Named +~/.smplkit+ profile section.
+      # @param base_domain [String, nil] Base domain for API requests
+      #   (default +"smplkit.com"+).
+      # @param scheme [String, nil] URL scheme (default +"https"+).
+      # @param debug [Boolean, nil] Enable SDK debug logging.
+      # @param extra_headers [Hash, nil] Extra headers attached to every request.
+      # @param auth_client [Object, nil] Internal — a pre-built transport
+      #   supplied by a top-level client so the jobs surface shares one
+      #   connection pool. Not for direct use.
       def initialize(api_key = nil, profile: nil, base_domain: nil, scheme: nil,
                      debug: nil, extra_headers: nil, auth_client: nil)
         auth = auth_client || Jobs.jobs_transport(
@@ -194,19 +210,24 @@ module Smplkit
         Job.from_resource(resp.data, client: self)
       end
 
-      # Soft-delete a job.
+      # Delete a job by its id.
       #
-      # @param id [String]
+      # @param id [String] Identifier of the job to delete.
       # @return [nil]
       def delete(id)
         Jobs.call_api { @api.delete_job(id) }
         nil
       end
 
-      # Trigger one immediate +MANUAL+ run of the job.
+      # Trigger one immediate, manual run of a job, ignoring its schedule.
       #
-      # @param id [String]
-      # @return [Smplkit::Jobs::Run]
+      # This starts an ad-hoc run right now in addition to any scheduled runs;
+      # it does not alter the job's schedule. To read or act on existing runs,
+      # use +client.jobs.runs+.
+      #
+      # @param id [String] Identifier of the job to run.
+      # @return [Smplkit::Jobs::Run] The run that was started, with +trigger+
+      #   set to +MANUAL+.
       def run(id)
         resp = Jobs.call_api { @api.run_job_now(id) }
         Run.from_resource(resp.data)
@@ -233,9 +254,9 @@ module Smplkit
       # @api private — Full-replace PUT for an existing job. Called by
       #   {Smplkit::Jobs::Job#save} on instances with +created_at+.
       #
-      # Header values must be re-supplied as plaintext; the GET path redacts
-      # them, so a PUT body containing the redacted placeholder would persist
-      # that literal. Track real header values client-side and round-trip them.
+      # Header values come back in plaintext on the GET path, so a fetched job
+      # round-trips through this full-replace PUT with its header values intact
+      # — no need to re-enter secrets.
       def _update_job(job)
         raise ArgumentError, "cannot update a Job with no id" if job.id.nil?
 

data/lib/smplkit/jobs/models.rb

@@ -1,15 +1,14 @@
 # frozen_string_literal: true
 
 module Smplkit
-  # Smpl Jobs surface — exposed through +mgmt.jobs.*+.
+  # Smpl Jobs surface — exposed through +client.jobs.*+.
   #
   # Unlike Config/Flags/Logging, Jobs has no live "phone-home" agent — no
-  # environment registration, no WebSocket — so its entire surface lives on
-  # the management client rather than a runtime client. A {Job} is an active
-  # record: build it with +mgmt.jobs.new(...)+, set fields, and call {Job#save}
-  # (create when new, full-replace update when it already exists) or
-  # {Job#delete}. Runs are read-only views; run actions live on
-  # +mgmt.jobs.runs+.
+  # environment registration, no WebSocket — so its entire surface lives on a
+  # single client. A {Job} is an active record: build it with
+  # +client.jobs.new(...)+, set fields, and call {Job#save} (create when new,
+  # full-replace update when it already exists) or {Job#delete}. Runs are
+  # read-only views; run actions live on +client.jobs.runs+.
   module Jobs
     # Wrap a generated-jobs-API call and translate +ApiError+ into the
     # +Smplkit::Error+ hierarchy. Connection-level failures (no response
@@ -29,7 +28,7 @@ module Smplkit
       raise
     end
 
-    # HTTP verb a job uses when it fires (ADR-049).
+    # HTTP verb a job uses when it fires.
     #
     # Mirrors the jobs spec's method enum so a job's
     # +configuration.method+ field is constrained to a known value instead
@@ -64,8 +63,8 @@ module Smplkit
     # @!attribute [rw] name
     #   @return [String] Header name (e.g. +"Authorization"+, +"Content-Type"+).
     # @!attribute [rw] value
-    #   @return [String] Header value, plaintext on writes. The jobs service
-    #     encrypts values at rest; reads return them redacted.
+    #   @return [String] Header value. Returned in plaintext on reads, so a
+    #     get-mutate-put round-trip preserves it without re-entering secrets.
     HttpHeader = Struct.new(:name, :value, keyword_init: true)
 
     # The HTTP request a job performs when it fires (the +http+ configuration).
@@ -79,7 +78,8 @@ module Smplkit
     #   @return [String] Destination URL the job requests on each run.
     # @!attribute [rw] headers
     #   @return [Array<HttpHeader>] Headers attached to every request. Values
-    #     are redacted on reads.
+    #     often carry credentials and are returned in plaintext on reads, so a
+    #     get-mutate-put round-trip preserves them without re-entering secrets.
     # @!attribute [rw] body
     #   @return [String, nil] Request body sent on each run. +nil+ (the default)
     #     sends an empty body, suitable for a connectivity ping. Sent verbatim —
@@ -118,6 +118,11 @@ module Smplkit
         )
       end
 
+      # @api private — Convert an {HttpConfig} (or a Hash with the same keys)
+      #   into the generated wire model the jobs service expects.
+      #
+      # @param src [HttpConfig, Hash] The HTTP configuration to serialize.
+      # @return [SmplkitGeneratedClient::Jobs::JobHttpConfiguration] The wire model.
       def self.to_wire(src)
         h = src.is_a?(Hash) ? new(**src) : src
         SmplkitGeneratedClient::Jobs::JobHttpConfiguration.new(
@@ -139,6 +144,13 @@ module Smplkit
         )
       end
 
+      # @api private — Build an {HttpConfig} from the generated wire model
+      #   returned by the jobs service. Header values arrive in plaintext, so a
+      #   round-trip back through {to_wire} preserves them.
+      #
+      # @param src [SmplkitGeneratedClient::Jobs::JobHttpConfiguration, nil] The
+      #   wire model, or +nil+ for an empty configuration.
+      # @return [HttpConfig] The wrapper-side configuration.
       def self.from_wire(src)
         return new if src.nil?
 
@@ -166,11 +178,11 @@ module Smplkit
 
     # A scheduled unit of work: an HTTP request run on a schedule.
     #
-    # Active-record style: instantiate via +mgmt.jobs.new(...)+, mutate fields
+    # Active-record style: instantiate via +client.jobs.new(...)+, mutate fields
     # directly, and call {#save} to persist or {#delete} to remove. Header
-    # values in +configuration.headers+ are returned redacted on reads —
-    # re-supply the real values before calling {#save}; the SDK does not cache
-    # them client-side.
+    # values in +configuration.headers+ are returned in plaintext on reads, so
+    # fetching a job, mutating it, and calling {#save} preserves its header
+    # values without re-entering secrets.
     class Job
       # @return [String] Caller-supplied unique identifier for the job (the
       #   resource +id+). Unique within the account and immutable; the service
@@ -214,7 +226,8 @@ module Smplkit
       # @return [String, nil] ISO-8601 timestamp of the most recent mutation.
       attr_accessor :updated_at
 
-      # @return [String, nil] Soft-delete timestamp. +nil+ for live jobs.
+      # @return [String, nil] Timestamp when the job was deleted; +nil+ for live
+      #   jobs.
       attr_accessor :deleted_at
 
       # @return [Integer, nil] Monotonic version counter, bumped on every
@@ -258,7 +271,7 @@ module Smplkit
       end
       alias save! save
 
-      # Soft-delete this job on the server.
+      # Delete this job on the server.
       #
       # @return [nil]
       def delete
@@ -285,6 +298,12 @@ module Smplkit
         @version = other.version
       end
 
+      # @api private — Build a {Job} from a JSON:API resource returned by the
+      #   jobs service, binding it to +client+ so {#save} and {#delete} work.
+      #
+      # @param resource [Object] The JSON:API resource (id + attributes).
+      # @param client [JobsClient, nil] Client to bind the job to.
+      # @return [Job] The hydrated job.
       def self.from_resource(resource, client: nil)
         a = resource.attributes
         new(
@@ -310,7 +329,7 @@ module Smplkit
     #
     # Runs are created and mutated by the jobs service, not by clients; clients
     # influence runs only through the +run+ / +cancel+ / +rerun+ actions on
-    # +mgmt.jobs+.
+    # +client.jobs+.
     #
     # @!attribute [rw] id
     #   @return [String] Server-assigned UUID for this run.
@@ -353,6 +372,11 @@ module Smplkit
       :total_duration_ms, :failure_reason, :error, :request, :result, :created_at,
       keyword_init: true
     ) do
+      # @api private — Build a {Run} from a JSON:API resource returned by the
+      #   jobs service.
+      #
+      # @param resource [Object] The JSON:API resource (id + attributes).
+      # @return [Run] The hydrated run.
       def self.from_resource(resource)
         a = resource.attributes
         new(
@@ -393,6 +417,11 @@ module Smplkit
       :period, :runs_used, :runs_included, :active_jobs, :active_jobs_limit,
       keyword_init: true
     ) do
+      # @api private — Build a {Usage} snapshot from a JSON:API resource
+      #   returned by the jobs service.
+      #
+      # @param resource [Object] The JSON:API resource (attributes).
+      # @return [Usage] The usage snapshot.
       def self.from_resource(resource)
         a = resource.attributes
         new(