smplkit 3.0.95 → 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

@@ -26,9 +26,9 @@ module Smplkit
   # 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).
+  # +client.set_context([...])+, +client.platform.contexts.register([...])+) and
+  # reading (+client.platform.contexts.list/get+ return populated +Context+
+  # instances with +save+ / +delete+ ready to call).
   #
   # Examples:
   #
@@ -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
@@ -141,10 +141,9 @@ module Smplkit
 
   # 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.
+  # Used by +client.flags.register+ to queue declarations for bulk
+  # registration. +service+ and +environment+ default to +nil+; the client
+  # fills them from the active +Smplkit::Client+ when it forwards declarations.
   class FlagDeclaration
     attr_reader :id, :type, :default, :service, :environment
 

data/lib/smplkit/jobs/client.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+# The Smpl Jobs client — one unified +JobsClient+.
+#
+# Smpl Jobs schedules HTTP calls (cron-style +schedule+ + +http+ configuration)
+# and records their run history. Unlike Config/Flags/Logging it installs no
+# in-process machinery, so it has no runtime/management split: a single
+# +JobsClient+ exposes the full surface and is reachable as +client.jobs+ on
+# +Smplkit::Client+ or constructed directly.
+#
+#   client.jobs.{new,get,list,delete,run,usage}
+#   client.jobs.runs.{list,get,cancel,rerun}
+#   Job#{save,delete}
+#
+# The shared model classes (+Job+, +Run+, +Usage+, +HttpConfig+) live in
+# +lib/smplkit/jobs/models.rb+.
+module Smplkit
+  module Jobs
+    # +client.jobs.runs.*+ — read-only run history plus the cancel / rerun run
+    # actions.
+    class RunsClient
+      def initialize(api)
+        @api = api
+      end
+
+      # 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] 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?
+        opts[:page_size] = page_size unless page_size.nil?
+        opts[:page_after] = after unless after.nil?
+
+        resp = Jobs.call_api { @api.list_runs(opts) }
+        (resp.data || []).map { |r| Run.from_resource(r) }
+      end
+
+      # Fetch a single run by its id.
+      #
+      # @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 run that has not finished yet.
+      #
+      # @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
+
+      # Start a new run that repeats a previous one.
+      #
+      # @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)
+      end
+    end
+
+    # The Smpl Jobs client — accessed via +client.jobs+.
+    #
+    # Unlike Config/Flags/Logging, Jobs has no live "phone-home" agent — no
+    # environment registration, no WebSocket — so its entire surface lives on
+    # one client. Defining a job, triggering a run, and reading run history are
+    # all plain request/response calls here:
+    #
+    #   client.jobs.{new,get,list,delete,run,usage}
+    #   client.jobs.runs.{list,get,cancel,rerun}
+    #   Job#{save,delete}
+    #
+    # Build a standalone Smpl Jobs transport from resolved config.
+    #
+    # Reuses the config resolver (jobs is account-global and never
+    # environment-scoped) so a standalone jobs client resolves
+    # credentials/base-domain from +~/.smplkit+ / env vars / constructor args
+    # 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_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::ResolvedClientConfig.new(
+        api_key: cfg.api_key, base_domain: cfg.base_domain, scheme: cfg.scheme,
+        debug: cfg.debug, extra_headers: merged
+      )
+      Transport.build_api_client(SmplkitGeneratedClient::Jobs, "jobs", tcfg, accept: "application/vnd.api+json")
+    end
+
+    # The active-record entry point is {#new}: instantiate a draft, mutate
+    # fields, then call {Smplkit::Jobs::Job#save}. Run history and the cancel /
+    # rerun run actions live on {#runs}.
+    #
+    # Reachable as +client.jobs+ (+Smplkit::Client+) or constructed directly —
+    # +JobsClient.new+ resolves credentials from +~/.smplkit+ / env vars.
+    class JobsClient
+      # @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(
+          api_key: api_key, profile: profile, base_domain: base_domain,
+          scheme: scheme, debug: debug, extra_headers: extra_headers
+        )
+        @api = SmplkitGeneratedClient::Jobs::JobsApi.new(auth)
+        @runs = RunsClient.new(SmplkitGeneratedClient::Jobs::RunsApi.new(auth))
+        @usage_api = SmplkitGeneratedClient::Jobs::UsageApi.new(auth)
+      end
+
+      # The generated ApiClient owns Faraday connections that release on GC;
+      # there is no explicit shutdown to call.
+      def close
+        nil
+      end
+
+      # Construct, yield to the block, and close on exit.
+      def self.open(*args, **kwargs)
+        client = new(*args, **kwargs)
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      end
+
+      # Construct an unsaved {Smplkit::Jobs::Job} bound to this client. Call
+      # +#save+ on the returned instance to create it.
+      #
+      # @param id [String] Caller-supplied unique identifier for the job. Unique
+      #   within the account and immutable; the service returns 409 if another
+      #   live job already uses this id.
+      # @param name [String] Human-readable name for the job.
+      # @param schedule [String] An ISO-8601 datetime, a 5-field UTC cron
+      #   expression, or the literal +"now"+.
+      # @param configuration [Smplkit::Jobs::HttpConfig] The HTTP request the
+      #   job performs.
+      # @param description [String, nil] Optional free-text description.
+      # @param enabled [Boolean] Whether the job schedules runs. Defaults +true+.
+      # @param concurrency_policy [String] How overlapping runs are handled.
+      #   Defaults to +"ALLOW"+.
+      # @return [Smplkit::Jobs::Job]
+      def new(id, name:, schedule:, configuration:, description: nil,
+              enabled: true, concurrency_policy: "ALLOW")
+        Job.new(
+          self,
+          id: id,
+          name: name,
+          schedule: schedule,
+          configuration: configuration,
+          description: description,
+          enabled: enabled,
+          concurrency_policy: concurrency_policy
+        )
+      end
+
+      # List jobs for the authenticated account.
+      #
+      # @param enabled [Boolean, nil] Filter to jobs matching this enabled state.
+      # @param page_number [Integer, nil] 1-based page number to return.
+      # @param page_size [Integer, nil] Items per page.
+      # @return [Array<Smplkit::Jobs::Job>]
+      def list(enabled: nil, page_number: nil, page_size: nil)
+        opts = {}
+        opts[:filter_enabled] = enabled unless enabled.nil?
+        opts[:page_number] = page_number unless page_number.nil?
+        opts[:page_size] = page_size unless page_size.nil?
+
+        resp = Jobs.call_api { @api.list_jobs(opts) }
+        (resp.data || []).map { |r| Job.from_resource(r, client: self) }
+      end
+
+      # Fetch a single job by id. The returned instance is bound to this client,
+      # so +job.save+ and +job.delete+ work.
+      #
+      # @param id [String]
+      # @return [Smplkit::Jobs::Job]
+      def get(id)
+        resp = Jobs.call_api { @api.get_job(id) }
+        Job.from_resource(resp.data, client: self)
+      end
+
+      # Delete a job by its id.
+      #
+      # @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 a job, ignoring its schedule.
+      #
+      # 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)
+      end
+
+      # Current-period usage counters for the account.
+      #
+      # @return [Smplkit::Jobs::Usage]
+      def usage
+        resp = Jobs.call_api { @usage_api.get_usage }
+        Usage.from_resource(resp.data)
+      end
+
+      # @api private — POST a new job. Called by {Smplkit::Jobs::Job#save} on
+      #   unsaved instances. The jobs service requires a caller-supplied
+      #   +data.id+ on create and 409s on conflict.
+      def _create_job(job)
+        raise ArgumentError, "Job.id is required on create (caller-supplied key)" if job.id.nil? || job.id.empty?
+
+        resp = Jobs.call_api { @api.create_job(build_create_body(job)) }
+        Job.from_resource(resp.data, client: self)
+      end
+
+      # @api private — Full-replace PUT for an existing job. Called by
+      #   {Smplkit::Jobs::Job#save} on instances with +created_at+.
+      #
+      # 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?
+
+        resp = Jobs.call_api { @api.update_job(job.id, build_body(job)) }
+        Job.from_resource(resp.data, client: self)
+      end
+
+      private
+
+      def build_attrs(job)
+        SmplkitGeneratedClient::Jobs::Job.new(
+          name: job.name,
+          description: job.description,
+          enabled: job.enabled,
+          type: job.type,
+          schedule: job.schedule,
+          configuration: HttpConfig.to_wire(job.configuration),
+          concurrency_policy: job.concurrency_policy
+        )
+      end
+
+      def build_create_body(job)
+        # Create uses the distinct JobCreateRequest envelope; the jobs service
+        # requires data.id (the caller-supplied key) on create and 409s on
+        # conflict.
+        resource = SmplkitGeneratedClient::Jobs::JobCreateResource.new(
+          id: job.id.to_s,
+          type: "job",
+          attributes: build_attrs(job)
+        )
+        SmplkitGeneratedClient::Jobs::JobCreateRequest.new(data: resource)
+      end
+
+      def build_body(job)
+        # Update path uses the generic JobRequest envelope.
+        resource = SmplkitGeneratedClient::Jobs::JobResource.new(
+          id: job.id.to_s,
+          type: "job",
+          attributes: build_attrs(job)
+        )
+        SmplkitGeneratedClient::Jobs::JobRequest.new(data: resource)
+      end
+    end
+  end
+
+  JobsClient = Jobs::JobsClient
+end