smplkit 3.0.112 → 3.0.114

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e838dad6d55b34ff943e6098ef70867585eaacfdf3598bbebdfaa04c41243be
-  data.tar.gz: bb246e8ac29688fc37d4ebc687d31a1231a2be1eb0625c18e453a31e4ea4a0e2
+  metadata.gz: ac8fe2c97dbe9e809353ffa9240572f0b8121322dce79d599308dba14bf89654
+  data.tar.gz: '04689fee543ee875c6d8b0ba68ed3cbd67242a490bee6ed3dafd5b33e030348e'
 SHA512:
-  metadata.gz: b0b3291a8c8f129f16b36f0e271c6c9519c0ac6f4a40bf3b391501c512c22e069e6500c60e95b3c03ea9c0211af2f6b5a0c227f84a3b161c64e5803b4e378024
-  data.tar.gz: d9c58b7d15d2b49810ffd56a2d900ff9c17dd9818ad6176baae8178ad1957107b610efc375951b0f43b18ea652681eb14d32147da000a3af62932d084db9af11
+  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,12 +215,12 @@ module SmplkitGeneratedClient::Jobs
     end
 
     # List Jobs
-    # List this account's jobs.  Default sort is `name` ascending. Sort by `name`, `created_at`, `updated_at`, `next_run_at`, or `enabled`, ascending or descending (prefix `-` for descending). Filter with `filter[enabled]` (enabled in at least one environment), `filter[recurring]`, and `filter[name]` (case-insensitive substring match on the name); filters compose with AND. A scoped caller sees each job's `environments` 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_enabled 
-    # @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`, `enabled`, `-enabled`, `name`, `-name`, `next_run_at`, `-next_run_at`, `updated_at`, `-updated_at`. (default to 'name')
+    # @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)
     # @option opts [Integer] :page_size Number of items per page. Optional; defaults to `1000` when omitted. Must be between `1` and `1000` inclusive — requests outside that range are rejected with a 400 error. (default to 1000)
     # @option opts [Boolean] :meta_total When `true`, the response's `meta.pagination` block includes `total` (the total number of matching items across all pages) and `total_pages`. Computing these requires an extra `COUNT` query, so omit (or pass `false`) when the totals are not needed. Defaults to `false`. (default to false)
@@ -231,12 +231,12 @@ module SmplkitGeneratedClient::Jobs
     end
 
     # List Jobs
-    # List this account's jobs.  Default sort is `name` ascending. Sort by `name`, `created_at`, `updated_at`, `next_run_at`, or `enabled`, ascending or descending (prefix `-` for descending). Filter with `filter[enabled]` (enabled in at least one environment), `filter[recurring]`, and `filter[name]` (case-insensitive substring match on the name); filters compose with AND. A scoped caller sees each job's `environments` 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_enabled 
-    # @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`, `enabled`, `-enabled`, `name`, `-name`, `next_run_at`, `-next_run_at`, `updated_at`, `-updated_at`. (default to 'name')
+    # @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)
     # @option opts [Integer] :page_size Number of items per page. Optional; defaults to `1000` when omitted. Must be between `1` and `1000` inclusive — requests outside that range are rejected with a 400 error. (default to 1000)
     # @option opts [Boolean] :meta_total When `true`, the response's `meta.pagination` block includes `total` (the total number of matching items across all pages) and `total_pages`. Computing these requires an extra `COUNT` query, so omit (or pass `false`) when the totals are not needed. Defaults to `false`. (default to false)
@@ -245,7 +245,7 @@ module SmplkitGeneratedClient::Jobs
       if @api_client.config.debugging
         @api_client.config.logger.debug 'Calling API: JobsApi.list_jobs ...'
       end
-      allowable_values = ["created_at", "-created_at", "enabled", "-enabled", "name", "-name", "next_run_at", "-next_run_at", "updated_at", "-updated_at"]
+      allowable_values = ["created_at", "-created_at", "name", "-name", "updated_at", "-updated_at"]
       if @api_client.config.client_side_validation && opts[:'sort'] && !allowable_values.include?(opts[:'sort'])
         fail ArgumentError, "invalid value for \"sort\", must be one of #{allowable_values}"
       end
@@ -254,8 +254,8 @@ module SmplkitGeneratedClient::Jobs
 
       # query parameters
       query_params = opts[:query_params] || {}
-      query_params[:'filter[enabled]'] = opts[:'filter_enabled'] if !opts[:'filter_enabled'].nil?
-      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?
@@ -297,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.
@@ -308,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.
@@ -363,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. Editing the schedule recomputes the next fire time; changing only which environments are enabled preserves the 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
@@ -375,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. Editing the schedule recomputes the next fire time; changing only which environments are enabled preserves the 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 currently-enabled jobs.
+    # 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 currently-enabled jobs.
+    # 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 is enabled per environment: set `environments[<env>].enabled` to schedule runs there. A recurring (cron) job may be enabled in several environments at once and fires once per enabled environment; 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
@@ -22,29 +22,23 @@ module SmplkitGeneratedClient::Jobs
     # Free-text description for the job.
     attr_accessor :description
 
-    # Whether the job is enabled in at least one environment. Read-only roll-up of `environments[*].enabled`; set enablement per environment via `environments`.
-    attr_accessor :enabled
-
     # Job type. Only `http` is supported today.
     attr_accessor :type
 
-    # When the job runs. 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) and an optional `configuration` override (omit to inherit the base `configuration`). A job with no entry for an environment is disabled there. For a recurring 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.
+    # 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
 
-    # The next scheduled fire time. `null` once a one-off job has fired.
-    attr_accessor :next_run_at
-
-    # 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 `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
@@ -85,14 +79,12 @@ module SmplkitGeneratedClient::Jobs
       {
         :'name' => :'name',
         :'description' => :'description',
-        :'enabled' => :'enabled',
         :'type' => :'type',
         :'schedule' => :'schedule',
         :'configuration' => :'configuration',
         :'environments' => :'environments',
         :'concurrency_policy' => :'concurrency_policy',
-        :'next_run_at' => :'next_run_at',
-        :'recurring' => :'recurring',
+        :'kind' => :'kind',
         :'created_at' => :'created_at',
         :'updated_at' => :'updated_at',
         :'deleted_at' => :'deleted_at',
@@ -115,14 +107,12 @@ module SmplkitGeneratedClient::Jobs
       {
         :'name' => :'String',
         :'description' => :'String',
-        :'enabled' => :'Boolean',
         :'type' => :'String',
         :'schedule' => :'String',
         :'configuration' => :'JobHttpConfiguration',
         :'environments' => :'Hash<String, JobEnvironment>',
         :'concurrency_policy' => :'String',
-        :'next_run_at' => :'Time',
-        :'recurring' => :'Boolean',
+        :'kind' => :'String',
         :'created_at' => :'Time',
         :'updated_at' => :'Time',
         :'deleted_at' => :'Time',
@@ -134,9 +124,8 @@ module SmplkitGeneratedClient::Jobs
     def self.openapi_nullable
       Set.new([
         :'description',
-        :'enabled',
-        :'next_run_at',
-        :'recurring',
+        :'schedule',
+        :'kind',
         :'created_at',
         :'updated_at',
         :'deleted_at',
@@ -170,10 +159,6 @@ module SmplkitGeneratedClient::Jobs
         self.description = attributes[:'description']
       end
 
-      if attributes.key?(:'enabled')
-        self.enabled = attributes[:'enabled']
-      end
-
       if attributes.key?(:'type')
         self.type = attributes[:'type']
       else
@@ -182,8 +167,6 @@ module SmplkitGeneratedClient::Jobs
 
       if attributes.key?(:'schedule')
         self.schedule = attributes[:'schedule']
-      else
-        self.schedule = nil
       end
 
       if attributes.key?(:'configuration')
@@ -204,12 +187,8 @@ module SmplkitGeneratedClient::Jobs
         self.concurrency_policy = 'ALLOW'
       end
 
-      if attributes.key?(:'next_run_at')
-        self.next_run_at = attributes[:'next_run_at']
-      end
-
-      if attributes.key?(:'recurring')
-        self.recurring = attributes[:'recurring']
+      if attributes.key?(:'kind')
+        self.kind = attributes[:'kind']
       end
 
       if attributes.key?(:'created_at')
@@ -250,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
@@ -271,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
 
@@ -316,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)
@@ -346,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)
@@ -353,14 +329,12 @@ module SmplkitGeneratedClient::Jobs
       self.class == o.class &&
           name == o.name &&
           description == o.description &&
-          enabled == o.enabled &&
           type == o.type &&
           schedule == o.schedule &&
           configuration == o.configuration &&
           environments == o.environments &&
           concurrency_policy == o.concurrency_policy &&
-          next_run_at == o.next_run_at &&
-          recurring == o.recurring &&
+          kind == o.kind &&
           created_at == o.created_at &&
           updated_at == o.updated_at &&
           deleted_at == o.deleted_at &&
@@ -376,7 +350,7 @@ module SmplkitGeneratedClient::Jobs
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [name, description, enabled, type, schedule, configuration, environments, concurrency_policy, next_run_at, 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

@@ -14,19 +14,27 @@ require 'date'
 require 'time'
 
 module SmplkitGeneratedClient::Jobs
-  # Per-environment override for a job's enablement and configuration.
+  # Per-environment override for a job's enablement, schedule, and configuration.
   class JobEnvironment < ApiModelBase
     # 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 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.
     attr_accessor :configuration
 
+    # The next scheduled fire time in this environment. `null` when the environment is not enabled, or once a one-off run has fired.
+    attr_accessor :next_run_at
+
     # Attribute mapping from ruby-style variable name to JSON key.
     def self.attribute_map
       {
         :'enabled' => :'enabled',
-        :'configuration' => :'configuration'
+        :'schedule' => :'schedule',
+        :'configuration' => :'configuration',
+        :'next_run_at' => :'next_run_at'
       }
     end
 
@@ -44,14 +52,18 @@ module SmplkitGeneratedClient::Jobs
     def self.openapi_types
       {
         :'enabled' => :'Boolean',
-        :'configuration' => :'JobHttpConfiguration'
+        :'schedule' => :'String',
+        :'configuration' => :'JobHttpConfiguration',
+        :'next_run_at' => :'Time'
       }
     end
 
     # List of attributes with nullable: true
     def self.openapi_nullable
       Set.new([
-        :'configuration'
+        :'schedule',
+        :'configuration',
+        :'next_run_at'
       ])
     end
 
@@ -77,9 +89,17 @@ module SmplkitGeneratedClient::Jobs
         self.enabled = false
       end
 
+      if attributes.key?(:'schedule')
+        self.schedule = attributes[:'schedule']
+      end
+
       if attributes.key?(:'configuration')
         self.configuration = attributes[:'configuration']
       end
+
+      if attributes.key?(:'next_run_at')
+        self.next_run_at = attributes[:'next_run_at']
+      end
     end
 
     # Show invalid properties with the reasons. Usually used together with valid?
@@ -103,7 +123,9 @@ module SmplkitGeneratedClient::Jobs
       return true if self.equal?(o)
       self.class == o.class &&
           enabled == o.enabled &&
-          configuration == o.configuration
+          schedule == o.schedule &&
+          configuration == o.configuration &&
+          next_run_at == o.next_run_at
     end
 
     # @see the `==` method
@@ -115,7 +137,7 @@ module SmplkitGeneratedClient::Jobs
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [enabled, configuration].hash
+      [enabled, schedule, configuration, next_run_at].hash
     end
 
     # Builds the object from hash

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 currently-enabled jobs.
+    # Number of permanent jobs (recurring and manual) counted against the plan's job limit.
     attr_accessor :active_jobs
 
-    # Maximum enabled 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,12 +71,12 @@ 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`, `updated_at`, `next_run_at`, or `enabled`, ascending or descending (prefix `-` for descending). Filter with `filter[enabled]` (enabled in at least one environment), `filter[recurring]`, and `filter[name]` (case-insensitive substring match on the name); filters compose with AND. A scoped caller sees each job's `environments` 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_enabled 
-  # @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`, `enabled`, `-enabled`, `name`, `-name`, `next_run_at`, `-next_run_at`, `updated_at`, `-updated_at`.
+  # @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.
   # @option opts [Integer] :page_size Number of items per page. Optional; defaults to `1000` when omitted. Must be between `1` and `1000` inclusive — requests outside that range are rejected with a 400 error.
   # @option opts [Boolean] :meta_total When `true`, the response's `meta.pagination` block includes `total` (the total number of matching items across all pages) and `total_pages`. Computing these requires an extra `COUNT` query, so omit (or pass `false`) when the totals are not needed. Defaults to `false`.
@@ -89,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.
@@ -102,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. Editing the schedule recomputes the next fire time; changing only which environments are enabled preserves the 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 currently-enabled jobs.
+  # 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_environment_spec.rb

@@ -33,10 +33,22 @@ describe SmplkitGeneratedClient::Jobs::JobEnvironment do
     end
   end
 
+  describe 'test attribute "schedule"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
   describe 'test attribute "configuration"' do
     it 'should work' do
       # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
     end
   end
 
+  describe 'test attribute "next_run_at"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
 end

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

@@ -39,12 +39,6 @@ describe SmplkitGeneratedClient::Jobs::Job do
     end
   end
 
-  describe 'test attribute "enabled"' do
-    it 'should work' do
-      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
-    end
-  end
-
   describe 'test attribute "type"' do
     it 'should work' do
       # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
@@ -83,15 +77,13 @@ describe SmplkitGeneratedClient::Jobs::Job do
     end
   end
 
-  describe 'test attribute "next_run_at"' do
-    it 'should work' do
-      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
-    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,61 +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 +: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 enabled [Boolean, nil] Filter to jobs matching this enabled state
-      #   (the server-derived roll-up across environments).
-      # @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(enabled: nil, 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_enabled] = enabled unless enabled.nil?
-        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?
@@ -271,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)
@@ -316,14 +373,34 @@ 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
-      # +configuration+ override is sent as a full {HttpConfig} payload only when
-      # present (omit to inherit the base configuration).
+      # Each entry's +enabled+ is always written; a per-environment +schedule+
+      # (cron) override and +configuration+ override are each sent only when
+      # present (omit to inherit the job's base +schedule+ / +configuration+).
+      # The read-only per-environment +next_run_at+ is never written.
       def environments_to_wire(environments)
         (environments || {}).each_with_object({}) do |(env_key, env), out|
           attrs = { enabled: env.enabled }
+          attrs[:schedule] = env.schedule unless env.schedule.nil?
           attrs[:configuration] = HttpConfig.to_wire(env.configuration) unless env.configuration.nil?
           out[env_key.to_s] = SmplkitGeneratedClient::Jobs::JobEnvironment.new(attrs)
         end

data/lib/smplkit/jobs/models.rb

@@ -6,15 +6,18 @@ 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 +enabled+ is a read-only,
-  # server-derived roll-up (+true+ when enabled in at least one environment).
+  # 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
     # +Smplkit::Error+ hierarchy. Connection-level failures (no response
@@ -73,10 +76,10 @@ module Smplkit
     # Coerce a caller's +environments+ map to {JobEnvironment} instances.
     #
     # Accepts either {JobEnvironment} values or plain hashes
-    # (+{ enabled: true, configuration: HttpConfig.new(...) }+) so callers can
-    # use the lightweight hash form without importing the model. A dict-form
-    # +configuration+ override is coerced to an {HttpConfig} so it serializes on
-    # save.
+    # (+{ enabled: true, schedule: "0 3 * * *", configuration: HttpConfig.new(...) }+)
+    # so callers can use the lightweight hash form without importing the model. A
+    # dict-form +configuration+ override is coerced to an {HttpConfig} so it
+    # serializes on save; an optional +schedule+ cron override passes through.
     #
     # @api private
     def self.normalize_environments(environments)
@@ -90,12 +93,40 @@ module Smplkit
                               cfg = HttpConfig.new(**cfg) if cfg.is_a?(Hash)
                               JobEnvironment.new(
                                 enabled: value[:enabled] || value["enabled"] || false,
+                                schedule: value[:schedule] || value["schedule"],
                                 configuration: cfg
                               )
                             end
       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
@@ -244,23 +275,34 @@ module Smplkit
     end
     # rubocop:enable Lint/StructNewOverride
 
-    # Per-environment enablement and optional configuration override for a job.
+    # 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)
+    #     inherits the job's base {Job#schedule}. When present, it must be a
+    #     5-field UTC cron expression and is only meaningful on a recurring job —
+    #     it cannot turn a one-off job recurring or vice-versa.
     # @!attribute [rw] configuration
     #   @return [HttpConfig, nil] Optional per-environment request configuration
     #     that fully replaces the job's base {Job#configuration} for this
     #     environment. +nil+ (the default) inherits the base configuration. As
     #     with the base configuration, header values are returned in plaintext on
     #     reads, so a get-mutate-put round-trip preserves them.
-    JobEnvironment = Struct.new(:enabled, :configuration, keyword_init: true) do
-      def initialize(enabled: false, configuration: nil)
+    # @!attribute [rw] next_run_at
+    #   @return [String, nil] Read-only. The next scheduled fire time in this
+    #     environment. +nil+ when the environment is not enabled, or once a
+    #     one-off run has fired. Never written back on save.
+    JobEnvironment = Struct.new(:enabled, :schedule, :configuration, :next_run_at, keyword_init: true) do
+      def initialize(enabled: false, schedule: nil, configuration: nil, next_run_at: nil)
         super
       end
 
@@ -275,23 +317,29 @@ module Smplkit
         cfg = src.configuration
         new(
           enabled: src.enabled.nil? ? false : src.enabled,
-          configuration: cfg.nil? ? nil : HttpConfig.from_wire(cfg)
+          schedule: src.schedule,
+          configuration: cfg.nil? ? nil : HttpConfig.from_wire(cfg),
+          next_run_at: src.next_run_at
         )
       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 read-only roll-up. The schedule is
-    # environment-agnostic — one cron / datetime / +now+ shared across every
-    # environment the job runs in.
+    # 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
@@ -304,11 +352,13 @@ module Smplkit
       # @return [String, nil] Free-text description. +nil+ when unset.
       attr_accessor :description
 
-      # @return [Boolean] Read-only, server-derived roll-up: +true+ when the job
-      #   is enabled in at least one environment. Set enablement per environment
-      #   via {#set_enabled} / {#environments}; mutating this field directly has
-      #   no effect on the server (it is never written).
-      attr_accessor :enabled
+      # @return [Boolean] Derived roll-up: +true+ when the job is enabled in at
+      #   least one environment. Computed from {#environments} rather than read
+      #   from the wire — the API no longer carries a top-level +enabled+. Set
+      #   enablement per environment via {#set_enabled} / {#environments}.
+      def enabled
+        (@environments || {}).each_value.any?(&:enabled)
+      end
 
       # @return [Hash{String => JobEnvironment}] Per-environment overrides keyed
       #   by environment key (e.g. +"production"+). The writable surface for
@@ -318,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.
@@ -341,10 +394,6 @@ module Smplkit
       #   value) permits them.
       attr_accessor :concurrency_policy
 
-      # @return [String, nil] The next scheduled fire time. +nil+ once a one-off
-      #   job has fired.
-      attr_accessor :next_run_at
-
       # @return [String, nil] ISO-8601 timestamp of first persist. +nil+ for an
       #   unsaved instance.
       attr_accessor :created_at
@@ -362,27 +411,26 @@ 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:,
-                     description: nil, environments: nil, enabled: false,
-                     recurring: nil, type: "http", concurrency_policy: "ALLOW",
-                     birth_environment: nil, next_run_at: nil, created_at: nil,
+      def initialize(client = nil, id:, name:, configuration:, schedule: nil,
+                     description: nil, environments: nil,
+                     kind: nil, type: "http", concurrency_policy: "ALLOW",
+                     birth_environment: nil, created_at: nil,
                      updated_at: nil, deleted_at: nil, version: nil)
         @client = client
         @id = id
         @name = name
         @description = description
         @environments = environments || {}
-        @enabled = enabled
-        @recurring = recurring
+        @kind = kind
         @type = type
         @schedule = schedule
         @configuration = configuration
         @concurrency_policy = concurrency_policy
         @birth_environment = birth_environment
-        @next_run_at = next_run_at
         @created_at = created_at
         @updated_at = updated_at
         @deleted_at = deleted_at
@@ -394,8 +442,8 @@ module Smplkit
       # Upsert behavior is driven by {#created_at}: a job with no +created_at+
       # is created (POST); otherwise it's full-replace updated (PUT). After the
       # call, every field is refreshed from the server response (including
-      # newly-assigned +created_at+, +version+, +next_run_at+, and the derived
-      # +enabled+ roll-up).
+      # newly-assigned +created_at+, +version+, and per-environment +next_run_at+
+      # inside {#environments}).
       #
       # @return [self]
       def save
@@ -440,7 +488,7 @@ module Smplkit
       #   roll-up across every environment.
       # @return [Boolean]
       def is_enabled(environment: nil)
-        return @enabled if environment.nil?
+        return enabled if environment.nil?
 
         override = @environments[environment]
         return false if override.nil?
@@ -448,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.
       #
@@ -485,17 +554,30 @@ module Smplkit
         @configuration
       end
 
-      # Set the job's schedule.
+      # Set the job's schedule — base (+environment+ omitted) or per-environment.
       #
-      # The schedule is environment-agnostic — a job has a single cron /
-      # datetime / +"now"+ schedule shared across every environment it runs in
-      # (each enabled environment fires on the same cadence). There is no
-      # per-environment schedule, so this setter takes no +environment+.
+      # With +environment+ omitted (the default), sets the base {#schedule} —
+      # an ISO-8601 datetime, a 5-field UTC cron expression, or the literal
+      # +"now"+ — which every environment inherits unless it overrides it.
+      #
+      # With +environment+ given, sets that environment's per-environment cron
+      # +schedule+ override on {#environments}, creating the override entry if it
+      # doesn't exist yet (preserving any already-set +enabled+ / +configuration+
+      # on it). A per-environment override is a cron expression only and varies
+      # the cadence within that environment; it cannot turn a one-off job
+      # recurring or vice-versa. Call {#save} to persist.
       #
       # @param schedule [String] An ISO-8601 datetime, a 5-field UTC cron
-      #   expression, or the literal +"now"+.
-      def set_schedule(schedule)
-        @schedule = schedule
+      #   expression, or the literal +"now"+ (base); a 5-field UTC cron
+      #   expression (per-environment).
+      # @param environment [String, nil] An environment key for a per-environment
+      #   override, or +nil+ to set the base schedule.
+      def set_schedule(schedule, environment: nil)
+        if environment.nil?
+          @schedule = schedule
+        else
+          _environment_override(environment).schedule = schedule
+        end
       end
 
       # Trigger one immediate, manual run of this job (a +MANUAL+ run).
@@ -547,14 +629,12 @@ module Smplkit
         @id = other.id
         @name = other.name
         @description = other.description
-        @enabled = other.enabled
         @environments = other.environments
-        @recurring = other.recurring
+        @kind = other.kind
         @type = other.type
         @schedule = other.schedule
         @configuration = other.configuration
         @concurrency_policy = other.concurrency_policy
-        @next_run_at = other.next_run_at
         @created_at = other.created_at
         @updated_at = other.updated_at
         @deleted_at = other.deleted_at
@@ -577,16 +657,14 @@ module Smplkit
           id: resource.id,
           name: a.name,
           description: a.description,
-          # The base +enabled+ is a server-derived roll-up; round-trip whatever
-          # the server returned without assuming a default of true.
-          enabled: a.enabled.nil? ? false : a.enabled,
+          # 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),
           concurrency_policy: a.concurrency_policy || "ALLOW",
-          next_run_at: a.next_run_at,
           created_at: a.created_at,
           updated_at: a.updated_at,
           deleted_at: a.deleted_at,
@@ -613,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.112
+  version: 3.0.114
 platform: ruby
 authors:
 - Smpl Solutions LLC