smplkit 3.0.95 → 3.0.96

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:
   #
@@ -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/{management/jobs.rb → jobs/client.rb}

@@ -1,39 +1,149 @@
 # 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 Management
-    # Smpl Jobs management surface — accessed via +mgmt.jobs+.
+  module Jobs
+    # +client.jobs.runs.*+ — read-only run history plus the cancel / rerun run
+    # actions.
+    class RunsClient
+      def initialize(api)
+        @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.
+      #
+      # @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>]
+      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 id.
+      #
+      # @param run_id [String]
+      # @return [Smplkit::Jobs::Run]
+      def get(run_id)
+        resp = Jobs.call_api { @api.get_run(run_id) }
+        Run.from_resource(resp.data)
+      end
+
+      # Cancel a pending run.
+      #
+      # @param run_id [String]
+      # @return [Smplkit::Jobs::Run]
+      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.
+      #
+      # @param run_id [String]
+      # @return [Smplkit::Jobs::Run]
+      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
-    # the management client. Defining a job, triggering a run, and reading run
-    # history are all plain request/response calls here:
+    # one client. Defining a job, triggering a run, and reading run history are
+    # all plain request/response calls here:
     #
-    #   mgmt.jobs.{new,get,list,delete,run,usage}
-    #   mgmt.jobs.runs.{list,get,cancel,rerun}
+    #   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_management_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(
+        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}.
-    class JobsNamespace
-      # @return [RunsNamespace] Run history and run actions (+mgmt.jobs.runs+).
+    # 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
 
-      def initialize(api_client)
-        @api = SmplkitGeneratedClient::Jobs::JobsApi.new(api_client)
-        @runs = RunsNamespace.new(
-          SmplkitGeneratedClient::Jobs::RunsApi.new(api_client)
+      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
         )
-        @usage_api = SmplkitGeneratedClient::Jobs::UsageApi.new(api_client)
+        @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 namespace. Call
+      # 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 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"+.
@@ -46,7 +156,7 @@ module Smplkit
       # @return [Smplkit::Jobs::Job]
       def new(id, name:, schedule:, configuration:, description: nil,
               enabled: true, concurrency_policy: "ALLOW")
-        Smplkit::Jobs::Job.new(
+        Job.new(
           self,
           id: id,
           name: name,
@@ -70,18 +180,18 @@ module Smplkit
         opts[:page_number] = page_number unless page_number.nil?
         opts[:page_size] = page_size unless page_size.nil?
 
-        resp = Smplkit::Jobs.call_api { @api.list_jobs(opts) }
-        (resp.data || []).map { |r| Smplkit::Jobs::Job.from_resource(r, client: self) }
+        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
-      # namespace, so +job.save+ and +job.delete+ work.
+      # 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 = Smplkit::Jobs.call_api { @api.get_job(id) }
-        Smplkit::Jobs::Job.from_resource(resp.data, client: self)
+        resp = Jobs.call_api { @api.get_job(id) }
+        Job.from_resource(resp.data, client: self)
       end
 
       # Soft-delete a job.
@@ -89,7 +199,7 @@ module Smplkit
       # @param id [String]
       # @return [nil]
       def delete(id)
-        Smplkit::Jobs.call_api { @api.delete_job(id) }
+        Jobs.call_api { @api.delete_job(id) }
         nil
       end
 
@@ -98,16 +208,16 @@ module Smplkit
       # @param id [String]
       # @return [Smplkit::Jobs::Run]
       def run(id)
-        resp = Smplkit::Jobs.call_api { @api.run_job_now(id) }
-        Smplkit::Jobs::Run.from_resource(resp.data)
+        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 = Smplkit::Jobs.call_api { @usage_api.get_usage }
-        Smplkit::Jobs::Usage.from_resource(resp.data)
+        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
@@ -116,8 +226,8 @@ module Smplkit
       def _create_job(job)
         raise ArgumentError, "Job.id is required on create (caller-supplied key)" if job.id.nil? || job.id.empty?
 
-        resp = Smplkit::Jobs.call_api { @api.create_job(build_create_body(job)) }
-        Smplkit::Jobs::Job.from_resource(resp.data, client: self)
+        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
@@ -129,8 +239,8 @@ module Smplkit
       def _update_job(job)
         raise ArgumentError, "cannot update a Job with no id" if job.id.nil?
 
-        resp = Smplkit::Jobs.call_api { @api.update_job(job.id, build_body(job)) }
-        Smplkit::Jobs::Job.from_resource(resp.data, client: self)
+        resp = Jobs.call_api { @api.update_job(job.id, build_body(job)) }
+        Job.from_resource(resp.data, client: self)
       end
 
       private
@@ -142,7 +252,7 @@ module Smplkit
           enabled: job.enabled,
           type: job.type,
           schedule: job.schedule,
-          configuration: Smplkit::Jobs::HttpConfig.to_wire(job.configuration),
+          configuration: HttpConfig.to_wire(job.configuration),
           concurrency_policy: job.concurrency_policy
         )
       end
@@ -169,58 +279,7 @@ module Smplkit
         SmplkitGeneratedClient::Jobs::JobRequest.new(data: resource)
       end
     end
-
-    # +mgmt.jobs.runs.*+ — read-only run history plus the cancel / rerun run
-    # actions.
-    class RunsNamespace
-      def initialize(api)
-        @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.
-      #
-      # @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>]
-      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 = Smplkit::Jobs.call_api { @api.list_runs(opts) }
-        (resp.data || []).map { |r| Smplkit::Jobs::Run.from_resource(r) }
-      end
-
-      # Fetch a single run by id.
-      #
-      # @param run_id [String]
-      # @return [Smplkit::Jobs::Run]
-      def get(run_id)
-        resp = Smplkit::Jobs.call_api { @api.get_run(run_id) }
-        Smplkit::Jobs::Run.from_resource(resp.data)
-      end
-
-      # Cancel a pending run.
-      #
-      # @param run_id [String]
-      # @return [Smplkit::Jobs::Run]
-      def cancel(run_id)
-        resp = Smplkit::Jobs.call_api { @api.cancel_run(run_id) }
-        Smplkit::Jobs::Run.from_resource(resp.data)
-      end
-
-      # Re-run a prior run, spawning a new +RERUN+ run.
-      #
-      # @param run_id [String]
-      # @return [Smplkit::Jobs::Run]
-      def rerun(run_id)
-        resp = Smplkit::Jobs.call_api { @api.rerun_run(run_id) }
-        Smplkit::Jobs::Run.from_resource(resp.data)
-      end
-    end
   end
+
+  JobsClient = Jobs::JobsClient
 end