smplkit 3.0.113 → 3.0.114

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a17d3fa81a862f3b33087a957eab5c99db055027b39c914d2c1cbac05854961
-  data.tar.gz: ee3716c54c5d56ae8e956bf672774b494e0f1698ed795dec829c30365fea0dce
+  metadata.gz: ac8fe2c97dbe9e809353ffa9240572f0b8121322dce79d599308dba14bf89654
+  data.tar.gz: '04689fee543ee875c6d8b0ba68ed3cbd67242a490bee6ed3dafd5b33e030348e'
 SHA512:
-  metadata.gz: f10c44c9a4c8e784e55f630b8c136ec3f53a1cf2d42b3284e47e37cf218f579e730bb4dfe483deaff75ea165c8be5460cd45b53e7fb1c03cc717e92f98b18d6c
-  data.tar.gz: 0daec91acc15dc5cb3b7c7041a9765237d8a71bc59ea8f41df58fe657bf9b67e37b66184bfb2c7b0f4f0eb6c9326402a2f660629000ca97f02bcf9aa39fce705
+  metadata.gz: 1f26e6bec44ef6259a7d384ce5cd80c99eba77116a73bd22c3be814fcf683712a6a8b2fd1774e3a0e76cfe58bf28fc0184edcd91266ce3b453db60dd1a6e7fea
+  data.tar.gz: bee0e18d7f5d8f4b9bbe64085da2782888ecd82fff072c92d4f81c4379c27f21dfc82643d26261d7a7c0af809b58d112239ae12e840c11b989331dd22317fd29

data/lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/api/jobs_api.rb

@@ -20,7 +20,7 @@ module SmplkitGeneratedClient::Jobs
       @api_client = api_client
     end
     # Create Job
-    # Create a job for this account.  The caller supplies the job's id as `data.id`. Ids are unique within an account and immutable. A recurring job supplies `environments` to choose where it runs and begins scheduling immediately in each enabled environment. A one-off job is created in the environment named by the `X-Smplkit-Environment` header (implied when the credential is scoped to a single environment).
+    # Create a job for this account.  The caller supplies the job's id as `data.id`. Ids are unique within an account and immutable. The job's kind follows from its `schedule`: omit the schedule for a permanent **manual** job (triggered on demand), give a cron expression for a **recurring** job, or a datetime / `now` for a **one-off** job. A recurring or manual job supplies `environments` to choose where it runs; a recurring job begins scheduling immediately in each enabled environment. A one-off job is created in the environment named by the `X-Smplkit-Environment` header (implied when the credential is scoped to a single environment); a `now` one-off enqueues its single run immediately.
     # @param job_create_request [JobCreateRequest] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :x_smplkit_environment The environment to operate in. Names the single environment a one-off job is born in (or a manual run executes in). Optional when the credential is scoped to a single environment (which is then implied); required when the credential can reach several environments and the choice is otherwise ambiguous. Ignored for a recurring job, whose environments come from its `environments` map.
@@ -31,7 +31,7 @@ module SmplkitGeneratedClient::Jobs
     end
 
     # Create Job
-    # Create a job for this account.  The caller supplies the job's id as `data.id`. Ids are unique within an account and immutable. A recurring job supplies `environments` to choose where it runs and begins scheduling immediately in each enabled environment. A one-off job is created in the environment named by the `X-Smplkit-Environment` header (implied when the credential is scoped to a single environment).
+    # Create a job for this account.  The caller supplies the job's id as `data.id`. Ids are unique within an account and immutable. The job's kind follows from its `schedule`: omit the schedule for a permanent **manual** job (triggered on demand), give a cron expression for a **recurring** job, or a datetime / `now` for a **one-off** job. A recurring or manual job supplies `environments` to choose where it runs; a recurring job begins scheduling immediately in each enabled environment. A one-off job is created in the environment named by the `X-Smplkit-Environment` header (implied when the credential is scoped to a single environment); a `now` one-off enqueues its single run immediately.
     # @param job_create_request [JobCreateRequest] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :x_smplkit_environment The environment to operate in. Names the single environment a one-off job is born in (or a manual run executes in). Optional when the credential is scoped to a single environment (which is then implied); required when the credential can reach several environments and the choice is otherwise ambiguous. Ignored for a recurring job, whose environments come from its `environments` map.
@@ -215,9 +215,10 @@ module SmplkitGeneratedClient::Jobs
     end
 
     # List Jobs
-    # List this account's jobs.  Default sort is `name` ascending. Sort by `name`, `created_at`, or `updated_at`, ascending or descending (prefix `-` for descending). Filter with `filter[recurring]` and `filter[name]` (case-insensitive substring match on the name); filters compose with AND. Each job reports its per-environment enablement and `next_run_at` inside its `environments` map; a scoped caller sees that map narrowed to the environments it may access.
+    # List this account's jobs.  Default sort is `name` ascending. Sort by `name`, `created_at`, or `updated_at`, ascending or descending (prefix `-` for descending). By default the list omits transient one-off jobs (request `filter[kind]=one_off` to see them). Filter with `filter[kind]` (`recurring` / `manual` / `one_off`), `filter[scheduled]` (jobs with an upcoming fire in some environment — the feed for an upcoming-runs view, which includes one-offs), and `filter[name]` (case-insensitive substring); filters compose with AND. Each job reports its per-environment enablement and `next_run_at` inside its `environments` map; a scoped caller sees that map narrowed to the environments it may access.
     # @param [Hash] opts the optional parameters
-    # @option opts [Boolean] :filter_recurring 
+    # @option opts [String] :filter_kind Restrict to a single job kind: `recurring`, `manual`, or `one_off`. By default one-off jobs are omitted (they are transient and short-lived); request `filter[kind]=one_off` to list them.
+    # @option opts [Boolean] :filter_scheduled When `true`, list only jobs that have an upcoming fire in at least one environment (a recurring job's next occurrence, or a pending future one-off) — the feed for an upcoming-runs view; this includes one-off jobs. When `false`, list only jobs with no upcoming fire.
     # @option opts [String] :filter_name Case-insensitive substring match on the job `name` (matches when the name contains the given text).
     # @option opts [String] :sort Field to sort by. Prefix with `-` for descending order. Default: `name`. Allowed values: `created_at`, `-created_at`, `name`, `-name`, `updated_at`, `-updated_at`. (default to 'name')
     # @option opts [Integer] :page_number 1-based page number to return. Optional; defaults to `1` when omitted. Must be `>= 1` — requests with a smaller value are rejected with a 400 error. (default to 1)
@@ -230,9 +231,10 @@ module SmplkitGeneratedClient::Jobs
     end
 
     # List Jobs
-    # List this account's jobs.  Default sort is `name` ascending. Sort by `name`, `created_at`, or `updated_at`, ascending or descending (prefix `-` for descending). Filter with `filter[recurring]` and `filter[name]` (case-insensitive substring match on the name); filters compose with AND. Each job reports its per-environment enablement and `next_run_at` inside its `environments` map; a scoped caller sees that map narrowed to the environments it may access.
+    # List this account's jobs.  Default sort is `name` ascending. Sort by `name`, `created_at`, or `updated_at`, ascending or descending (prefix `-` for descending). By default the list omits transient one-off jobs (request `filter[kind]=one_off` to see them). Filter with `filter[kind]` (`recurring` / `manual` / `one_off`), `filter[scheduled]` (jobs with an upcoming fire in some environment — the feed for an upcoming-runs view, which includes one-offs), and `filter[name]` (case-insensitive substring); filters compose with AND. Each job reports its per-environment enablement and `next_run_at` inside its `environments` map; a scoped caller sees that map narrowed to the environments it may access.
     # @param [Hash] opts the optional parameters
-    # @option opts [Boolean] :filter_recurring 
+    # @option opts [String] :filter_kind Restrict to a single job kind: `recurring`, `manual`, or `one_off`. By default one-off jobs are omitted (they are transient and short-lived); request `filter[kind]=one_off` to list them.
+    # @option opts [Boolean] :filter_scheduled When `true`, list only jobs that have an upcoming fire in at least one environment (a recurring job's next occurrence, or a pending future one-off) — the feed for an upcoming-runs view; this includes one-off jobs. When `false`, list only jobs with no upcoming fire.
     # @option opts [String] :filter_name Case-insensitive substring match on the job `name` (matches when the name contains the given text).
     # @option opts [String] :sort Field to sort by. Prefix with `-` for descending order. Default: `name`. Allowed values: `created_at`, `-created_at`, `name`, `-name`, `updated_at`, `-updated_at`. (default to 'name')
     # @option opts [Integer] :page_number 1-based page number to return. Optional; defaults to `1` when omitted. Must be `>= 1` — requests with a smaller value are rejected with a 400 error. (default to 1)
@@ -252,7 +254,8 @@ module SmplkitGeneratedClient::Jobs
 
       # query parameters
       query_params = opts[:query_params] || {}
-      query_params[:'filter[recurring]'] = opts[:'filter_recurring'] if !opts[:'filter_recurring'].nil?
+      query_params[:'filter[kind]'] = opts[:'filter_kind'] if !opts[:'filter_kind'].nil?
+      query_params[:'filter[scheduled]'] = opts[:'filter_scheduled'] if !opts[:'filter_scheduled'].nil?
       query_params[:'filter[name]'] = opts[:'filter_name'] if !opts[:'filter_name'].nil?
       query_params[:'sort'] = opts[:'sort'] if !opts[:'sort'].nil?
       query_params[:'page[number]'] = opts[:'page_number'] if !opts[:'page_number'].nil?
@@ -294,7 +297,7 @@ module SmplkitGeneratedClient::Jobs
     end
 
     # Run Job Now
-    # Trigger one immediate run of the job (a `MANUAL` run).  The job's schedule and enabled state are untouched. The run executes in the environment named by the `X-Smplkit-Environment` header; when the job is enabled in exactly one environment that environment is used, and a single-environment credential implies it. The run executes the job's effective configuration for that environment. It is enqueued and executed by the worker; if the account is over its run allotment the run will fail with reason `QUOTA_EXCEEDED` rather than being rejected here.
+    # Trigger one immediate run of the job in a specified environment (a `MANUAL` run).  This is the primary execution path for a manual job and is also usable ad hoc for a recurring job (\"run now\"). The job's schedule and enabled state are untouched. The run executes in the environment named by the `X-Smplkit-Environment` header; when the job is enabled in exactly one environment that environment is used, and a single-environment credential implies it. The environment must be one the job is **enabled** in (409 otherwise). The run executes the job's effective configuration for that environment. It is enqueued and executed by the worker; if the account is over its run allotment the run will fail with reason `QUOTA_EXCEEDED` rather than being rejected here.
     # @param job_id [String] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :x_smplkit_environment The environment to operate in. Names the single environment a one-off job is born in (or a manual run executes in). Optional when the credential is scoped to a single environment (which is then implied); required when the credential can reach several environments and the choice is otherwise ambiguous. Ignored for a recurring job, whose environments come from its `environments` map.
@@ -305,7 +308,7 @@ module SmplkitGeneratedClient::Jobs
     end
 
     # Run Job Now
-    # Trigger one immediate run of the job (a `MANUAL` run).  The job's schedule and enabled state are untouched. The run executes in the environment named by the `X-Smplkit-Environment` header; when the job is enabled in exactly one environment that environment is used, and a single-environment credential implies it. The run executes the job's effective configuration for that environment. It is enqueued and executed by the worker; if the account is over its run allotment the run will fail with reason `QUOTA_EXCEEDED` rather than being rejected here.
+    # Trigger one immediate run of the job in a specified environment (a `MANUAL` run).  This is the primary execution path for a manual job and is also usable ad hoc for a recurring job (\"run now\"). The job's schedule and enabled state are untouched. The run executes in the environment named by the `X-Smplkit-Environment` header; when the job is enabled in exactly one environment that environment is used, and a single-environment credential implies it. The environment must be one the job is **enabled** in (409 otherwise). The run executes the job's effective configuration for that environment. It is enqueued and executed by the worker; if the account is over its run allotment the run will fail with reason `QUOTA_EXCEEDED` rather than being rejected here.
     # @param job_id [String] 
     # @param [Hash] opts the optional parameters
     # @option opts [String] :x_smplkit_environment The environment to operate in. Names the single environment a one-off job is born in (or a manual run executes in). Optional when the credential is scoped to a single environment (which is then implied); required when the credential can reach several environments and the choice is otherwise ambiguous. Ignored for a recurring job, whose environments come from its `environments` map.
@@ -360,7 +363,7 @@ module SmplkitGeneratedClient::Jobs
     end
 
     # Update Job
-    # Replace an existing job. Every writable field is overwritten.  Set enablement per environment via the `environments` map (a recurring job), or by recreating a one-off job in the desired environment. Each environment may carry its own cron `schedule` override. Editing an environment's effective schedule recomputes its next fire time; an edit that leaves an environment's schedule unchanged preserves its existing cadence.
+    # Replace an existing job. Every writable field is overwritten.  The job's kind is re-derived from the new `schedule` (omit it for a manual job). Set enablement per environment via the `environments` map (a recurring or manual job), or by recreating a one-off job in the desired environment. Each environment may carry its own cron `schedule` override (recurring jobs only). Editing a recurring environment's effective schedule recomputes its next fire time; an edit that leaves it unchanged preserves the existing cadence.
     # @param job_id [String] 
     # @param job_request [JobRequest] 
     # @param [Hash] opts the optional parameters
@@ -372,7 +375,7 @@ module SmplkitGeneratedClient::Jobs
     end
 
     # Update Job
-    # Replace an existing job. Every writable field is overwritten.  Set enablement per environment via the `environments` map (a recurring job), or by recreating a one-off job in the desired environment. Each environment may carry its own cron `schedule` override. Editing an environment's effective schedule recomputes its next fire time; an edit that leaves an environment's schedule unchanged preserves its existing cadence.
+    # Replace an existing job. Every writable field is overwritten.  The job's kind is re-derived from the new `schedule` (omit it for a manual job). Set enablement per environment via the `environments` map (a recurring or manual job), or by recreating a one-off job in the desired environment. Each environment may carry its own cron `schedule` override (recurring jobs only). Editing a recurring environment's effective schedule recomputes its next fire time; an edit that leaves it unchanged preserves the existing cadence.
     # @param job_id [String] 
     # @param job_request [JobRequest] 
     # @param [Hash] opts the optional parameters

data/lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/api/usage_api.rb

@@ -20,7 +20,7 @@ module SmplkitGeneratedClient::Jobs
       @api_client = api_client
     end
     # Get Usage
-    # Report this account's current-period usage against its plan allotments.  `runs_used` is the number of runs metered so far this calendar month; `active_jobs` is the number of recurring (scheduled) jobs, which is what the plan's job limit bounds.
+    # Report this account's current-period usage against its plan allotments.  `runs_used` is the number of runs metered so far this calendar month; `active_jobs` is the number of permanent jobs (recurring + manual), which is what the plan's job limit bounds (one-off jobs do not count).
     # @param [Hash] opts the optional parameters
     # @option opts [String] :filter_period  (default to 'current')
     # @return [UsageResponse]
@@ -30,7 +30,7 @@ module SmplkitGeneratedClient::Jobs
     end
 
     # Get Usage
-    # Report this account's current-period usage against its plan allotments.  `runs_used` is the number of runs metered so far this calendar month; `active_jobs` is the number of recurring (scheduled) jobs, which is what the plan's job limit bounds.
+    # Report this account's current-period usage against its plan allotments.  `runs_used` is the number of runs metered so far this calendar month; `active_jobs` is the number of permanent jobs (recurring + manual), which is what the plan's job limit bounds (one-off jobs do not count).
     # @param [Hash] opts the optional parameters
     # @option opts [String] :filter_period  (default to 'current')
     # @return [Array<(UsageResponse, Integer, Hash)>] UsageResponse data, response status code and response headers

data/lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/job.rb

@@ -14,7 +14,7 @@ require 'date'
 require 'time'
 
 module SmplkitGeneratedClient::Jobs
-  # A scheduled unit of work: an HTTP request run on a schedule.  The job is the definition; each time it fires the service records a run capturing the request, response, timing, and outcome. A job runs per environment: set `environments[<env>].enabled` to schedule runs there, and optionally give that environment its own `schedule` or `configuration`. A recurring (cron) job may be enabled in several environments at once and fires once per enabled environment, each on its own next-fire schedule; a one-off (`now` or future datetime) job runs a single time in the environment it was created in.
+  # A unit of work: an HTTP request, run on a schedule or triggered on demand.  The job is the definition; each time it fires the service records a run capturing the request, response, timing, and outcome. A job runs per environment: set `environments[<env>].enabled` to enable it there, and optionally give that environment its own `schedule` or `configuration`.  A job's `kind` follows from its `schedule`: a **recurring** (cron) job may be enabled in several environments at once and fires once per enabled environment, each on its own next-fire schedule; a **manual** job (no schedule) is permanent and never auto-fires — it runs only when triggered; a **one-off** (`now` or a future datetime) job runs a single time in the environment it was created in and is then spent.
   class Job < ApiModelBase
     # Human-readable name for the job.
     attr_accessor :name
@@ -25,20 +25,20 @@ module SmplkitGeneratedClient::Jobs
     # Job type. Only `http` is supported today.
     attr_accessor :type
 
-    # The base schedule every environment inherits unless it overrides it. One of: an ISO-8601 datetime (a one-off run at that instant), a 5-field cron expression evaluated in **UTC** (recurring), or the literal `now` (run once, as soon as possible). A datetime or `now` job disables itself after it fires.
+    # The base schedule every environment inherits unless it overrides it, and the field that determines the job's `kind`. Omit it (or send `null`) to create a permanent **manual** job that never auto-fires and runs only when triggered. Provide a 5-field cron expression evaluated in **UTC** for a **recurring** job, an ISO-8601 datetime for a **one-off** run at that instant, or the literal `now` for a one-off run as soon as possible. A datetime or `now` job disables itself after it fires.
     attr_accessor :schedule
 
     # The HTTP request to perform, including method, url, headers, body, and timeout.
     attr_accessor :configuration
 
-    # Per-environment overrides keyed by environment key (e.g. `production`, `staging`). Each entry sets `enabled` (whether the job schedules runs in that environment), an optional `schedule` override (a cron expression for recurring jobs; omit to inherit the base `schedule`), and an optional `configuration` override (omit to inherit the base `configuration`); it also reports the read-only `next_run_at` for that environment. A job with no entry for an environment is disabled there. For a recurring job, supply this map to choose where and how it runs. For a one-off job, the environment it is created in is recorded here automatically — name it with the `X-Smplkit-Environment` header. Every referenced environment must exist for the account.
+    # Per-environment overrides keyed by environment key (e.g. `production`, `staging`). Each entry sets `enabled` (whether the job is enabled — scheduled, for a recurring job, or triggerable, for a manual job — in that environment), an optional `schedule` override (a cron expression for recurring jobs; omit to inherit the base `schedule`), and an optional `configuration` override (omit to inherit the base `configuration`); it also reports the read-only `next_run_at` for that environment. A job with no entry for an environment is disabled there. For a recurring or manual job, supply this map to choose where it runs. For a one-off job, the environment it is created in is recorded here automatically — name it with the `X-Smplkit-Environment` header. Every referenced environment must exist for the account.
     attr_accessor :environments
 
     # How overlapping runs are handled. `ALLOW` (the only value today) permits them.
     attr_accessor :concurrency_policy
 
-    # Whether the job runs on a repeating schedule. `true` for a cron schedule; `false` for a one-off datetime or `now` schedule, which runs a single time. Derived from the base `schedule`.
-    attr_accessor :recurring
+    # How the job runs, derived from its base `schedule`: `recurring` for a cron schedule (fires on a repeating cadence), `manual` for no schedule (never auto-fires; runs only when triggered), or `one_off` for a `now` or datetime schedule (runs a single time, then is spent).
+    attr_accessor :kind
 
     # When the job was created.
     attr_accessor :created_at
@@ -84,7 +84,7 @@ module SmplkitGeneratedClient::Jobs
         :'configuration' => :'configuration',
         :'environments' => :'environments',
         :'concurrency_policy' => :'concurrency_policy',
-        :'recurring' => :'recurring',
+        :'kind' => :'kind',
         :'created_at' => :'created_at',
         :'updated_at' => :'updated_at',
         :'deleted_at' => :'deleted_at',
@@ -112,7 +112,7 @@ module SmplkitGeneratedClient::Jobs
         :'configuration' => :'JobHttpConfiguration',
         :'environments' => :'Hash<String, JobEnvironment>',
         :'concurrency_policy' => :'String',
-        :'recurring' => :'Boolean',
+        :'kind' => :'String',
         :'created_at' => :'Time',
         :'updated_at' => :'Time',
         :'deleted_at' => :'Time',
@@ -124,7 +124,8 @@ module SmplkitGeneratedClient::Jobs
     def self.openapi_nullable
       Set.new([
         :'description',
-        :'recurring',
+        :'schedule',
+        :'kind',
         :'created_at',
         :'updated_at',
         :'deleted_at',
@@ -166,8 +167,6 @@ module SmplkitGeneratedClient::Jobs
 
       if attributes.key?(:'schedule')
         self.schedule = attributes[:'schedule']
-      else
-        self.schedule = nil
       end
 
       if attributes.key?(:'configuration')
@@ -188,8 +187,8 @@ module SmplkitGeneratedClient::Jobs
         self.concurrency_policy = 'ALLOW'
       end
 
-      if attributes.key?(:'recurring')
-        self.recurring = attributes[:'recurring']
+      if attributes.key?(:'kind')
+        self.kind = attributes[:'kind']
       end
 
       if attributes.key?(:'created_at')
@@ -230,10 +229,6 @@ module SmplkitGeneratedClient::Jobs
         invalid_properties.push('invalid value for "description", the character length must be smaller than or equal to 2000.')
       end
 
-      if @schedule.nil?
-        invalid_properties.push('invalid value for "schedule", schedule cannot be nil.')
-      end
-
       if @configuration.nil?
         invalid_properties.push('invalid value for "configuration", configuration cannot be nil.')
       end
@@ -251,10 +246,11 @@ module SmplkitGeneratedClient::Jobs
       return false if !@description.nil? && @description.to_s.length > 2000
       type_validator = EnumAttributeValidator.new('String', ["http"])
       return false unless type_validator.valid?(@type)
-      return false if @schedule.nil?
       return false if @configuration.nil?
       concurrency_policy_validator = EnumAttributeValidator.new('String', ["ALLOW"])
       return false unless concurrency_policy_validator.valid?(@concurrency_policy)
+      kind_validator = EnumAttributeValidator.new('String', ["recurring", "manual", "one_off"])
+      return false unless kind_validator.valid?(@kind)
       true
     end
 
@@ -296,16 +292,6 @@ module SmplkitGeneratedClient::Jobs
       @type = type
     end
 
-    # Custom attribute writer method with validation
-    # @param [Object] schedule Value to be assigned
-    def schedule=(schedule)
-      if schedule.nil?
-        fail ArgumentError, 'schedule cannot be nil'
-      end
-
-      @schedule = schedule
-    end
-
     # Custom attribute writer method with validation
     # @param [Object] configuration Value to be assigned
     def configuration=(configuration)
@@ -326,6 +312,16 @@ module SmplkitGeneratedClient::Jobs
       @concurrency_policy = concurrency_policy
     end
 
+    # Custom attribute writer method checking allowed values (enum).
+    # @param [Object] kind Object to be assigned
+    def kind=(kind)
+      validator = EnumAttributeValidator.new('String', ["recurring", "manual", "one_off"])
+      unless validator.valid?(kind)
+        fail ArgumentError, "invalid value for \"kind\", must be one of #{validator.allowable_values}."
+      end
+      @kind = kind
+    end
+
     # Checks equality by comparing each attribute.
     # @param [Object] Object to be compared
     def ==(o)
@@ -338,7 +334,7 @@ module SmplkitGeneratedClient::Jobs
           configuration == o.configuration &&
           environments == o.environments &&
           concurrency_policy == o.concurrency_policy &&
-          recurring == o.recurring &&
+          kind == o.kind &&
           created_at == o.created_at &&
           updated_at == o.updated_at &&
           deleted_at == o.deleted_at &&
@@ -354,7 +350,7 @@ module SmplkitGeneratedClient::Jobs
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [name, description, type, schedule, configuration, environments, concurrency_policy, recurring, created_at, updated_at, deleted_at, version].hash
+      [name, description, type, schedule, configuration, environments, concurrency_policy, kind, created_at, updated_at, deleted_at, version].hash
     end
 
     # Builds the object from hash

data/lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/job_environment.rb

@@ -19,7 +19,7 @@ module SmplkitGeneratedClient::Jobs
     # Whether the job schedules runs in this environment. A job runs in an environment only via this field; it is disabled in every environment by default.
     attr_accessor :enabled
 
-    # Per-environment schedule override. Omit to inherit the job's base `schedule`. When present, it must be a 5-field cron expression evaluated in **UTC** (e.g. `0 3 * * *`), and is only allowed on a recurring (cron) job — it varies the cadence within that environment, it cannot turn a one-off job recurring or vice-versa.
+    # Per-environment schedule override. Omit to inherit the job's base `schedule`. When present, it must be a 5-field cron expression evaluated in **UTC** (e.g. `0 3 * * *`), and is only allowed on a recurring (cron) job — it varies the cadence within that environment. It cannot appear on a manual or one-off job, and cannot change a job's kind.
     attr_accessor :schedule
 
     # Per-environment HTTP request override. Omit to inherit the job's base `configuration`. When present, it fully replaces the base configuration for runs in this environment.

data/lib/smplkit/_generated/jobs/lib/smplkit_jobs_client/models/usage.rb

@@ -25,10 +25,10 @@ module SmplkitGeneratedClient::Jobs
     # Runs included in the plan this period (`-1` means unlimited).
     attr_accessor :runs_included
 
-    # Number of recurring (scheduled) jobs.
+    # Number of permanent jobs (recurring and manual) counted against the plan's job limit.
     attr_accessor :active_jobs
 
-    # Maximum recurring jobs the plan allows (`-1` means unlimited).
+    # Maximum permanent jobs the plan allows (`-1` means unlimited).
     attr_accessor :active_jobs_limit
 
     # Attribute mapping from ruby-style variable name to JSON key.

data/lib/smplkit/_generated/jobs/spec/api/jobs_api_spec.rb

@@ -34,7 +34,7 @@ describe 'JobsApi' do
 
   # unit tests for create_job
   # Create Job
-  # Create a job for this account.  The caller supplies the job's id as `data.id`. Ids are unique within an account and immutable. A recurring job supplies `environments` to choose where it runs and begins scheduling immediately in each enabled environment. A one-off job is created in the environment named by the `X-Smplkit-Environment` header (implied when the credential is scoped to a single environment).
+  # Create a job for this account.  The caller supplies the job's id as `data.id`. Ids are unique within an account and immutable. The job's kind follows from its `schedule`: omit the schedule for a permanent **manual** job (triggered on demand), give a cron expression for a **recurring** job, or a datetime / `now` for a **one-off** job. A recurring or manual job supplies `environments` to choose where it runs; a recurring job begins scheduling immediately in each enabled environment. A one-off job is created in the environment named by the `X-Smplkit-Environment` header (implied when the credential is scoped to a single environment); a `now` one-off enqueues its single run immediately.
   # @param job_create_request 
   # @param [Hash] opts the optional parameters
   # @option opts [String] :x_smplkit_environment The environment to operate in. Names the single environment a one-off job is born in (or a manual run executes in). Optional when the credential is scoped to a single environment (which is then implied); required when the credential can reach several environments and the choice is otherwise ambiguous. Ignored for a recurring job, whose environments come from its `environments` map.
@@ -71,9 +71,10 @@ describe 'JobsApi' do
 
   # unit tests for list_jobs
   # List Jobs
-  # List this account's jobs.  Default sort is `name` ascending. Sort by `name`, `created_at`, or `updated_at`, ascending or descending (prefix `-` for descending). Filter with `filter[recurring]` and `filter[name]` (case-insensitive substring match on the name); filters compose with AND. Each job reports its per-environment enablement and `next_run_at` inside its `environments` map; a scoped caller sees that map narrowed to the environments it may access.
+  # List this account's jobs.  Default sort is `name` ascending. Sort by `name`, `created_at`, or `updated_at`, ascending or descending (prefix `-` for descending). By default the list omits transient one-off jobs (request `filter[kind]=one_off` to see them). Filter with `filter[kind]` (`recurring` / `manual` / `one_off`), `filter[scheduled]` (jobs with an upcoming fire in some environment — the feed for an upcoming-runs view, which includes one-offs), and `filter[name]` (case-insensitive substring); filters compose with AND. Each job reports its per-environment enablement and `next_run_at` inside its `environments` map; a scoped caller sees that map narrowed to the environments it may access.
   # @param [Hash] opts the optional parameters
-  # @option opts [Boolean] :filter_recurring 
+  # @option opts [String] :filter_kind Restrict to a single job kind: `recurring`, `manual`, or `one_off`. By default one-off jobs are omitted (they are transient and short-lived); request `filter[kind]=one_off` to list them.
+  # @option opts [Boolean] :filter_scheduled When `true`, list only jobs that have an upcoming fire in at least one environment (a recurring job's next occurrence, or a pending future one-off) — the feed for an upcoming-runs view; this includes one-off jobs. When `false`, list only jobs with no upcoming fire.
   # @option opts [String] :filter_name Case-insensitive substring match on the job `name` (matches when the name contains the given text).
   # @option opts [String] :sort Field to sort by. Prefix with `-` for descending order. Default: `name`. Allowed values: `created_at`, `-created_at`, `name`, `-name`, `updated_at`, `-updated_at`.
   # @option opts [Integer] :page_number 1-based page number to return. Optional; defaults to `1` when omitted. Must be `>= 1` — requests with a smaller value are rejected with a 400 error.
@@ -88,7 +89,7 @@ describe 'JobsApi' do
 
   # unit tests for run_job_now
   # Run Job Now
-  # Trigger one immediate run of the job (a `MANUAL` run).  The job's schedule and enabled state are untouched. The run executes in the environment named by the `X-Smplkit-Environment` header; when the job is enabled in exactly one environment that environment is used, and a single-environment credential implies it. The run executes the job's effective configuration for that environment. It is enqueued and executed by the worker; if the account is over its run allotment the run will fail with reason `QUOTA_EXCEEDED` rather than being rejected here.
+  # Trigger one immediate run of the job in a specified environment (a `MANUAL` run).  This is the primary execution path for a manual job and is also usable ad hoc for a recurring job (\"run now\"). The job's schedule and enabled state are untouched. The run executes in the environment named by the `X-Smplkit-Environment` header; when the job is enabled in exactly one environment that environment is used, and a single-environment credential implies it. The environment must be one the job is **enabled** in (409 otherwise). The run executes the job's effective configuration for that environment. It is enqueued and executed by the worker; if the account is over its run allotment the run will fail with reason `QUOTA_EXCEEDED` rather than being rejected here.
   # @param job_id 
   # @param [Hash] opts the optional parameters
   # @option opts [String] :x_smplkit_environment The environment to operate in. Names the single environment a one-off job is born in (or a manual run executes in). Optional when the credential is scoped to a single environment (which is then implied); required when the credential can reach several environments and the choice is otherwise ambiguous. Ignored for a recurring job, whose environments come from its `environments` map.
@@ -101,7 +102,7 @@ describe 'JobsApi' do
 
   # unit tests for update_job
   # Update Job
-  # Replace an existing job. Every writable field is overwritten.  Set enablement per environment via the `environments` map (a recurring job), or by recreating a one-off job in the desired environment. Each environment may carry its own cron `schedule` override. Editing an environment's effective schedule recomputes its next fire time; an edit that leaves an environment's schedule unchanged preserves its existing cadence.
+  # Replace an existing job. Every writable field is overwritten.  The job's kind is re-derived from the new `schedule` (omit it for a manual job). Set enablement per environment via the `environments` map (a recurring or manual job), or by recreating a one-off job in the desired environment. Each environment may carry its own cron `schedule` override (recurring jobs only). Editing a recurring environment's effective schedule recomputes its next fire time; an edit that leaves it unchanged preserves the existing cadence.
   # @param job_id 
   # @param job_request 
   # @param [Hash] opts the optional parameters

data/lib/smplkit/_generated/jobs/spec/api/usage_api_spec.rb

@@ -34,7 +34,7 @@ describe 'UsageApi' do
 
   # unit tests for get_usage
   # Get Usage
-  # Report this account's current-period usage against its plan allotments.  `runs_used` is the number of runs metered so far this calendar month; `active_jobs` is the number of recurring (scheduled) jobs, which is what the plan's job limit bounds.
+  # Report this account's current-period usage against its plan allotments.  `runs_used` is the number of runs metered so far this calendar month; `active_jobs` is the number of permanent jobs (recurring + manual), which is what the plan's job limit bounds (one-off jobs do not count).
   # @param [Hash] opts the optional parameters
   # @option opts [String] :filter_period 
   # @return [UsageResponse]

data/lib/smplkit/_generated/jobs/spec/models/job_spec.rb

@@ -77,9 +77,13 @@ describe SmplkitGeneratedClient::Jobs::Job do
     end
   end
 
-  describe 'test attribute "recurring"' do
+  describe 'test attribute "kind"' do
     it 'should work' do
       # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+      # validator = Petstore::EnumTest::EnumAttributeValidator.new('String', ["recurring", "manual", "one_off"])
+      # validator.allowable_values.each do |value|
+      #   expect { instance.kind = value }.not_to raise_error
+      # end
     end
   end
 

data/lib/smplkit/jobs/client.rb

@@ -1,22 +1,25 @@
 # frozen_string_literal: true
 
+require "time"
+
 # 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.
+# Smpl Jobs runs HTTP calls — on a schedule or on demand — 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.{new_recurring_job,new_manual_job,schedule,get,list,delete,run,usage}
 #   client.jobs.runs.{list,get,cancel,rerun}
 #   Job#{save,delete,trigger,list_runs}
 #   Run#{rerun,cancel}
 #
 # A job is enabled per environment: a recurring (cron) job may be enabled in
-# several environments at once, a one-off (+now+ / future datetime) job is born
-# in exactly one. A client-level +environment+ default supplies the one-off
-# birth environment on create, the run-now environment, and the +runs.list+
+# several environments at once, a manual job (no schedule) runs only when
+# triggered, and a one-off (+now+ / future datetime) job is born in exactly
+# one. A client-level +environment+ default supplies the one-off birth
+# environment on create, the run-now environment, and the +runs.list+
 # +filter[environment]+ scope.
 #
 # The shared model classes (+Job+, +JobEnvironment+, +Run+, +Usage+,
@@ -98,7 +101,7 @@ module Smplkit
     # 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.{new_recurring_job,new_manual_job,schedule,get,list,delete,run,usage}
     #   client.jobs.runs.{list,get,cancel,rerun}
     #   Job#{save,delete,trigger,list_runs}
     #   Run#{rerun,cancel}
@@ -125,9 +128,10 @@ module Smplkit
       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}.
+    # The active-record entry points are {#new_recurring_job}, {#new_manual_job},
+    # and {#schedule}: 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.
@@ -179,58 +183,113 @@ module Smplkit
         end
       end
 
-      # Construct an unsaved {Smplkit::Jobs::Job} bound to this client. Call
-      # +#save+ on the returned instance to create it.
+      # Construct an unsaved recurring {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"+. The schedule is environment-agnostic.
-      # @param configuration [Smplkit::Jobs::HttpConfig] The base HTTP request
-      #   the job performs.
+      # @param schedule [String] The base cadence — a 5-field cron expression
+      #   evaluated in UTC (e.g. +"0 2 * * *"+) — that every environment inherits
+      #   unless it sets its own override.
+      # @param configuration [Smplkit::Jobs::HttpConfig] The HTTP request the job
+      #   sends each time it fires.
       # @param description [String, nil] Optional free-text description.
       # @param environments [Hash{String => Smplkit::Jobs::JobEnvironment, Hash}, nil]
-      #   Per-environment overrides for a recurring job, keyed by environment key
-      #   — each a {Smplkit::Jobs::JobEnvironment}, or a plain hash
-      #   (+{ enabled: true }+, optionally with a +:schedule+ cron override and/or
-      #   a +:configuration+ {Smplkit::Jobs::HttpConfig} override). A recurring
-      #   job fires only in environments enabled here. Ignored for a one-off job,
-      #   which is born in +environment+ below.
+      #   Per-environment overrides keyed by environment key — each a
+      #   {Smplkit::Jobs::JobEnvironment}, or a plain hash (+{ enabled: true }+,
+      #   optionally with a +:schedule+ cron override and/or a +:configuration+
+      #   {Smplkit::Jobs::HttpConfig} override). The job is scheduled only in
+      #   environments enabled here.
       # @param concurrency_policy [String] How overlapping runs are handled.
       #   Defaults to +"ALLOW"+.
-      # @param environment [String, nil] For a one-off job (+"now"+ / datetime
-      #   schedule), the environment it is born in. Defaults to the client's
-      #   configured environment. Ignored for a recurring job.
       # @return [Smplkit::Jobs::Job]
-      def new(id, name:, schedule:, configuration:, description: nil,
-              environments: nil, concurrency_policy: "ALLOW", environment: nil)
-        Job.new(
-          self,
-          id: id,
-          name: name,
-          schedule: schedule,
-          configuration: configuration,
-          description: description,
-          environments: Jobs.normalize_environments(environments),
-          concurrency_policy: concurrency_policy,
-          birth_environment: environment.nil? ? @environment : environment
+      def new_recurring_job(id, name:, schedule:, configuration:, description: nil,
+                            environments: nil, concurrency_policy: "ALLOW")
+        _new_job(
+          id, name: name, schedule: schedule, configuration: configuration,
+              description: description, environments: environments,
+              concurrency_policy: concurrency_policy, environment: nil
+        )
+      end
+
+      # Construct an unsaved manual {Smplkit::Jobs::Job} bound to this client.
+      # Call +#save+ on the returned instance to create it.
+      #
+      # A manual job has no schedule — it never auto-fires and runs only when
+      # triggered via {#run} / {Smplkit::Jobs::Job#trigger}.
+      #
+      # @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 configuration [Smplkit::Jobs::HttpConfig] The HTTP request the job
+      #   sends each time it runs.
+      # @param description [String, nil] Optional free-text description.
+      # @param environments [Hash{String => Smplkit::Jobs::JobEnvironment, Hash}, nil]
+      #   Per-environment overrides keyed by environment key — each a
+      #   {Smplkit::Jobs::JobEnvironment}, or a plain hash (+{ enabled: true }+,
+      #   optionally with a +:configuration+ {Smplkit::Jobs::HttpConfig}
+      #   override). The job is triggerable only in environments enabled here.
+      # @param concurrency_policy [String] How overlapping runs are handled.
+      #   Defaults to +"ALLOW"+.
+      # @return [Smplkit::Jobs::Job]
+      def new_manual_job(id, name:, configuration:, description: nil,
+                         environments: nil, concurrency_policy: "ALLOW")
+        _new_job(
+          id, name: name, schedule: nil, configuration: configuration,
+              description: description, environments: environments,
+              concurrency_policy: concurrency_policy, environment: nil
+        )
+      end
+
+      # Construct an unsaved one-off {Smplkit::Jobs::Job} bound to this client.
+      # Call +#save+ on the returned instance to create it.
+      #
+      # A one-off job runs a single time at +schedule+ and is then spent.
+      #
+      # @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 [Time] The instant the single run fires.
+      # @param configuration [Smplkit::Jobs::HttpConfig] The HTTP request the job
+      #   sends when it runs.
+      # @param description [String, nil] Optional free-text description.
+      # @param concurrency_policy [String] How overlapping runs are handled.
+      #   Defaults to +"ALLOW"+.
+      # @param environment [String, nil] The environment the job is born in.
+      #   Defaults to the client's configured environment.
+      # @return [Smplkit::Jobs::Job]
+      def schedule(id, name:, schedule:, configuration:, description: nil,
+                   concurrency_policy: "ALLOW", environment: nil)
+        _new_job(
+          id, name: name, schedule: schedule.iso8601, configuration: configuration,
+              description: description, environments: nil,
+              concurrency_policy: concurrency_policy, environment: environment
         )
       end
 
       # List jobs for the authenticated account.
       #
-      # @param recurring [Boolean, nil] Filter to recurring (+true+) or one-off
-      #   (+false+) jobs. +nil+ lists both.
+      # @param kind [String, nil] Filter to a single {Smplkit::Jobs::JobKind}
+      #   (+JobKind::RECURRING+ / +JobKind::MANUAL+ / +JobKind::ONE_OFF+). +nil+
+      #   lists recurring and manual jobs; one-off jobs are omitted unless you
+      #   pass +JobKind::ONE_OFF+.
+      # @param scheduled [Boolean, nil] Filter to jobs that have an upcoming fire
+      #   in some environment (+true+) or none (+false+) — the feed for an
+      #   upcoming-runs view, which includes one-offs. +nil+ does not filter on
+      #   scheduling.
       # @param name [String, nil] Filter to jobs whose name contains this text
       #   (case-insensitive). +nil+ lists all.
       # @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(recurring: nil, name: nil, page_number: nil, page_size: nil)
+      def list(kind: nil, scheduled: nil, name: nil, page_number: nil, page_size: nil)
         opts = {}
-        opts[:filter_recurring] = recurring unless recurring.nil?
+        opts[:filter_kind] = kind unless kind.nil?
+        opts[:filter_scheduled] = scheduled unless scheduled.nil?
         opts[:filter_name] = name unless name.nil?
         opts[:page_number] = page_number unless page_number.nil?
         opts[:page_size] = page_size unless page_size.nil?
@@ -268,7 +327,8 @@ module Smplkit
       # @param environment [String, nil] Environment the manual run executes in.
       #   Defaults to the client's configured environment; when the job is
       #   enabled in exactly one environment that environment is used, and a
-      #   single-environment credential implies it.
+      #   single-environment credential implies it. The job must be enabled in
+      #   the chosen environment.
       # @return [Smplkit::Jobs::Run] The run that was started, with +trigger+
       #   set to +MANUAL+.
       def run(id, environment: nil)
@@ -313,6 +373,24 @@ module Smplkit
 
       private
 
+      # Build an unsaved {Smplkit::Jobs::Job} bound to this client. The three
+      # public constructors ({#new_recurring_job}, {#new_manual_job}, {#schedule})
+      # funnel through here.
+      def _new_job(id, name:, schedule:, configuration:, description:,
+                   environments:, concurrency_policy:, environment:)
+        Job.new(
+          self,
+          id: id,
+          name: name,
+          schedule: schedule,
+          configuration: configuration,
+          description: description,
+          environments: Jobs.normalize_environments(environments),
+          concurrency_policy: concurrency_policy,
+          birth_environment: environment.nil? ? @environment : environment
+        )
+      end
+
       # Convert the wrapper +environments+ map to the generated model hash.
       #
       # Each entry's +enabled+ is always written; a per-environment +schedule+

data/lib/smplkit/jobs/models.rb

@@ -6,15 +6,17 @@ module Smplkit
   # Unlike Config/Flags/Logging, Jobs has no live "phone-home" agent — no
   # 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,
+  # +client.jobs.new_recurring_job(...)+ / +new_manual_job(...)+ /
+  # +schedule(...)+, set fields, and call {Job#save} (create when new,
   # full-replace update when it already exists) or {Job#delete}. Runs are
   # read-only views with +rerun+ / +cancel+ actions; run history lives on
   # +client.jobs.runs+.
   #
   # A job is enabled per environment: a recurring (cron) job may run in several
-  # environments at once, a one-off (+now+ / future datetime) job runs a single
-  # time in the environment it was created in. Base {Job#enabled} is a derived
-  # roll-up (+true+ when enabled in at least one environment), computed from the
+  # environments at once, a manual job (no schedule) runs only when triggered,
+  # and a one-off (+now+ / future datetime) job runs a single time in the
+  # environment it was created in. Base {Job#enabled} is a derived roll-up
+  # (+true+ when enabled in at least one environment), computed from the
   # per-environment {Job#environments} map.
   module Jobs
     # Wrap a generated-jobs-API call and translate +ApiError+ into the
@@ -98,6 +100,33 @@ module Smplkit
       end
     end
 
+    # How a job runs, derived from its schedule (read-only).
+    #
+    # - +MANUAL+: No schedule — never auto-fires; runs only when triggered.
+    # - +ONE_OFF+: A +now+ or datetime schedule — runs a single time, then is
+    #   spent.
+    # - +RECURRING+: A cron schedule — fires on a repeating cadence.
+    module JobKind
+      MANUAL = "manual"
+      ONE_OFF = "one_off"
+      RECURRING = "recurring"
+
+      VALUES = [MANUAL, ONE_OFF, RECURRING].freeze
+    end
+
+    # What started a run (read-only).
+    #
+    # - +MANUAL+: A +run+ / +trigger+ call started it on demand.
+    # - +RERUN+: It repeats an earlier run.
+    # - +SCHEDULE+: The job's schedule fired.
+    module RunTrigger
+      MANUAL = "MANUAL"
+      RERUN = "RERUN"
+      SCHEDULE = "SCHEDULE"
+
+      VALUES = [MANUAL, RERUN, SCHEDULE].freeze
+    end
+
     # HTTP verb a job uses when it fires.
     #
     # Mirrors the jobs spec's method enum so a job's
@@ -248,13 +277,14 @@ module Smplkit
 
     # Per-environment enablement, schedule, and configuration override for a job.
     #
-    # A recurring job fires in a given environment only when that environment
-    # has an entry in {Job#environments} with +enabled: true+; an environment
-    # with no entry (or +enabled: false+) does not fire there.
+    # A job runs in a given environment only when that environment has an entry
+    # in {Job#environments} with +enabled: true+ (scheduled there for a
+    # recurring job, triggerable there for a manual one); an environment with no
+    # entry (or +enabled: false+) is disabled there.
     #
     # @!attribute [rw] enabled
-    #   @return [Boolean] Whether the job fires in this environment. Defaults to
-    #     +false+.
+    #   @return [Boolean] Whether the job is enabled in this environment.
+    #     Defaults to +false+.
     # @!attribute [rw] schedule
     #   @return [String, nil] Optional per-environment cron schedule override
     #     that varies the cadence in this environment. +nil+ (the default)
@@ -294,19 +324,22 @@ module Smplkit
       end
     end
 
-    # A scheduled unit of work: an HTTP request run on a schedule.
+    # A unit of work: an HTTP request, run on a schedule or triggered on demand.
     #
-    # 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 in plaintext on reads, so
-    # fetching a job, mutating it, and calling {#save} preserves its header
-    # values without re-entering secrets.
+    # Active-record style: instantiate via +client.jobs.new_recurring_job(...)+,
+    # +new_manual_job(...)+, or +schedule(...)+, mutate fields directly, and call
+    # {#save} to persist or {#delete} to remove. Header 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.
     #
-    # Enablement is per environment, set via {#set_enabled} (and read via
-    # {#is_enabled}); base {#enabled} is a derived roll-up over {#environments}.
-    # The base schedule is environment-agnostic — one cron / datetime / +now+
-    # shared across every environment the job runs in — while each environment
-    # may carry its own cron {#set_schedule} override.
+    # A job's {#kind} follows from its {#schedule}: a recurring (cron) job, a
+    # manual job (no schedule, runs only when triggered), or a one-off (+now+ /
+    # datetime) job that runs a single time. Enablement is per environment, set
+    # via {#set_enabled} (and read via {#is_enabled}); base {#enabled} is a
+    # derived roll-up over {#environments}. The base schedule is
+    # environment-agnostic, while each environment may carry its own cron
+    # {#set_schedule} override.
     class Job
       # @return [String] Caller-supplied unique identifier for the job (the
       #   resource +id+). Unique within the account and immutable; the service
@@ -335,19 +368,22 @@ module Smplkit
       #   Every referenced environment must exist and be managed for the account.
       attr_accessor :environments
 
-      # @return [Boolean, nil] Read-only. +true+ for a recurring (cron) schedule,
-      #   +false+ for a one-off datetime / +now+ schedule. Derived from
-      #   {#schedule} by the server.
-      attr_accessor :recurring
+      # @return [String, nil] Read-only. How the job runs, derived from its
+      #   {#schedule} by the server: one of {JobKind::RECURRING},
+      #   {JobKind::MANUAL}, or {JobKind::ONE_OFF}. +nil+ on an unsaved instance.
+      attr_accessor :kind
 
       # @return [String] Job type. Only +"http"+ is supported today.
       attr_accessor :type
 
-      # @return [String] When the job runs: an ISO-8601 datetime (a one-off
-      #   run), a 5-field cron expression evaluated in UTC (recurring), or the
-      #   literal +"now"+ (run once, as soon as possible). A datetime or +"now"+
-      #   job disables itself after it fires. The schedule is environment-agnostic
-      #   — set it with {#set_schedule}.
+      # @return [String, nil] The base schedule every environment inherits, and
+      #   the field that determines the job's {#kind}: +nil+ (omitted) for a
+      #   permanent manual job that never auto-fires; a 5-field cron expression
+      #   evaluated in UTC for a recurring job; an ISO-8601 datetime for a
+      #   one-off run at that instant; or the literal +"now"+ for a one-off run
+      #   as soon as possible. A datetime or +"now"+ job disables itself after it
+      #   fires. The schedule is environment-agnostic — set it with
+      #   {#set_schedule}.
       attr_accessor :schedule
 
       # @return [HttpConfig] The base HTTP request to perform when the job fires.
@@ -375,12 +411,13 @@ module Smplkit
 
       # @api private — For a one-off job, the environment it is born in, sent as
       #   the +X-Smplkit-Environment+ header by {JobsClient#_create_job}. Ignored
-      #   for a recurring job, whose environments come from {#environments}.
+      #   for recurring and manual jobs, whose environments come from
+      #   {#environments}.
       attr_accessor :birth_environment
 
-      def initialize(client = nil, id:, name:, schedule:, configuration:,
+      def initialize(client = nil, id:, name:, configuration:, schedule: nil,
                      description: nil, environments: nil,
-                     recurring: nil, type: "http", concurrency_policy: "ALLOW",
+                     kind: nil, type: "http", concurrency_policy: "ALLOW",
                      birth_environment: nil, created_at: nil,
                      updated_at: nil, deleted_at: nil, version: nil)
         @client = client
@@ -388,7 +425,7 @@ module Smplkit
         @name = name
         @description = description
         @environments = environments || {}
-        @recurring = recurring
+        @kind = kind
         @type = type
         @schedule = schedule
         @configuration = configuration
@@ -459,6 +496,27 @@ module Smplkit
         override.enabled
       end
 
+      # Whether this is a recurring (cron-scheduled) job.
+      #
+      # @return [Boolean]
+      def is_recurring
+        @kind == JobKind::RECURRING
+      end
+
+      # Whether this is a manual job — no schedule; runs only when triggered.
+      #
+      # @return [Boolean]
+      def is_manual
+        @kind == JobKind::MANUAL
+      end
+
+      # Whether this is a one-off job — a single +now+ / datetime run.
+      #
+      # @return [Boolean]
+      def is_one_off
+        @kind == JobKind::ONE_OFF
+      end
+
       # Set the job's configuration — base (+environment+ omitted) or
       # per-environment.
       #
@@ -572,7 +630,7 @@ module Smplkit
         @name = other.name
         @description = other.description
         @environments = other.environments
-        @recurring = other.recurring
+        @kind = other.kind
         @type = other.type
         @schedule = other.schedule
         @configuration = other.configuration
@@ -602,7 +660,7 @@ module Smplkit
           # The base +enabled+ roll-up is derived from +environments+, not read
           # from the wire — the API no longer carries a top-level +enabled+.
           environments: environments,
-          recurring: a.recurring,
+          kind: a.kind,
           type: a.type || "http",
           schedule: a.schedule,
           configuration: HttpConfig.from_wire(a.configuration),
@@ -633,7 +691,8 @@ module Smplkit
     #     inherits the firing job-environment; a manual run uses the environment
     #     named on the run-now request; a rerun copies its source run's environment.
     # @!attribute [rw] trigger
-    #   @return [String] Why the run exists: +SCHEDULE+, +MANUAL+ (run now), or +RERUN+.
+    #   @return [String] Why the run exists — a raw string equal to one of the
+    #     {RunTrigger} constants: +SCHEDULE+, +MANUAL+ (run now), or +RERUN+.
     # @!attribute [rw] rerun_of
     #   @return [String, nil] The source run's id; set only when +trigger+ is +RERUN+.
     # @!attribute [rw] scheduled_for

metadata

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