hermes-client 0.0.0 → 0.1.0

data/lib/hermes_agent/client/errors.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "json"
+
+module HermesAgent
+  class Client
+    ##
+    # Base class for all errors raised by the client. Rescue this to catch
+    # every failure mode the client can produce.
+    #
+    class Error < ::StandardError
+    end
+
+    ##
+    # Raised when the client cannot reach the server at all: a socket, DNS, or
+    # TLS failure that produced no HTTP response.
+    #
+    class ConnectionError < Error
+    end
+
+    ##
+    # Raised when a request exceeds the configured open or read timeout.
+    #
+    class TimeoutError < Error
+    end
+
+    ##
+    # Raised when the server returns a body the client expected to be JSON but
+    # could not parse — a malformed payload on an otherwise successful
+    # response, or a malformed streamed SSE frame. Distinct from {APIError}:
+    # the HTTP request itself succeeded; only the body was unparseable. The
+    # unparseable text is available as {#body}, and the underlying
+    # `JSON::ParserError` is preserved as the exception's `#cause`.
+    #
+    class MalformedResponseError < Error
+      ##
+      # Create a malformed-response error.
+      #
+      # @param message [String] The human-readable error message.
+      # @param body [String, nil] The raw text that could not be parsed.
+      #
+      # @private
+      def initialize(message, body: nil)
+        super(message)
+        @body = body
+      end
+
+      ##
+      # The raw text that could not be parsed.
+      # @return [String, nil]
+      #
+      attr_reader :body
+    end
+
+    ##
+    # Raised when the server returns a non-2xx HTTP response.
+    #
+    # The concrete class reflects the HTTP status: {BadRequestError},
+    # {AuthenticationError}, {PermissionError}, {NotFoundError},
+    # {RateLimitError}, or {ServerError}. A bare {APIError} is raised for any
+    # status that maps to none of those.
+    #
+    # ## Error payloads
+    #
+    # The server uses three distinct error formats, all of which the client
+    # handles when building the error. Application-level errors (authentication,
+    # body validation, missing resources on the `/v1` surface) return an
+    # OpenAI-style JSON body of the form `{"error": {"message", "type",
+    # "param"?, "code"?}}`, and {#error} exposes that inner hash. The jobs
+    # surface (`/api/jobs`) instead returns a **flat** `{"error": "<message>"}`
+    # for its business errors (`400`/`404`/`500`); the message is still surfaced
+    # on the exception message, but {#error} is `nil` (there is no inner hash).
+    # Router-level
+    # errors (an unrouted path, a wrong method) return a bare text body such as
+    # `"404: Not Found"`; for those too {#error} is `nil` and only {#body} is
+    # meaningful.
+    #
+    # Even within the JSON family the field set is inconsistent — `message` and
+    # `type` are always present, but `param` and `code` may be null or absent —
+    # so treat {#error} entries as best-effort. Do not switch on `type`/`code`
+    # to classify a failure (the server returns `type: "invalid_request_error"`
+    # even for `401`s); branch on the HTTP {#status} or the error subclass.
+    #
+    class APIError < Error
+      ##
+      # Build the {APIError} subclass that matches an HTTP error response,
+      # extracting the structured payload when the server provides one.
+      #
+      # @param status [Integer] The HTTP status code.
+      # @param body [String] The raw response body.
+      # @param headers [Hash] The response headers.
+      # @return [APIError] An instance of the subclass matching the status.
+      #
+      # @private
+      def self.from_response(status:, body:, headers: {})
+        inner = error_field(body)
+        error = inner if inner.is_a?(::Hash)
+        message = (error && error["message"]) ||
+                  (inner if inner.is_a?(::String)) ||
+                  "Unexpected HTTP status #{status}"
+        class_for_status(status).new(message, status: status, body: body,
+                                              headers: headers, error: error)
+      end
+
+      # Pick the {APIError} subclass that represents an HTTP status code.
+      def self.class_for_status(status)
+        case status
+        when 400, 422 then BadRequestError
+        when 401 then AuthenticationError
+        when 403 then PermissionError
+        when 404 then NotFoundError
+        when 429 then RateLimitError
+        when 500..599 then ServerError
+        else APIError
+        end
+      end
+      private_class_method :class_for_status
+
+      # Pull the body's top-level `error` field out in a single JSON parse: the
+      # inner hash for the OpenAI-style envelope (`{"error":{...}}`) or the flat
+      # string for the jobs business errors (`{"error":"..."}`). The caller
+      # branches on the returned type. Returns nil when the body carries no
+      # `error` field or is a non-JSON (router-level) error body.
+      def self.error_field(body)
+        parsed = ::JSON.parse(body.to_s)
+        parsed["error"] if parsed.is_a?(::Hash)
+      rescue ::JSON::ParserError
+        nil
+      end
+      private_class_method :error_field
+
+      ##
+      # Create an API error. Prefer `from_response`, which selects the correct
+      # subclass and parses the payload for you.
+      #
+      # @param message [String] The human-readable error message.
+      # @param status [Integer] The HTTP status code.
+      # @param body [String] The raw response body.
+      # @param headers [Hash] The response headers.
+      # @param error [Hash, nil] The parsed structured error hash, if the body
+      #     carried one.
+      #
+      # @private
+      def initialize(message, status:, body:, headers: {}, error: nil)
+        super(message)
+        @status = status
+        @body = body
+        @headers = headers
+        @error = error
+      end
+
+      ##
+      # The HTTP status code of the error response.
+      # @return [Integer]
+      #
+      attr_reader :status
+
+      ##
+      # The raw response body.
+      # @return [String]
+      #
+      attr_reader :body
+
+      ##
+      # The response headers, keyed by downcased name (the same normalized
+      # shape the success path exposes, so e.g. `headers["retry-after"]` works
+      # regardless of the casing the server sent).
+      # @return [Hash{String=>String}]
+      #
+      attr_reader :headers
+
+      ##
+      # The structured error payload (the inner `error` object), or `nil` when
+      # the server returned a non-JSON body. Field set is best-effort: expect
+      # `message` and `type`, but `param` and `code` may be missing.
+      # @return [Hash, nil]
+      #
+      attr_reader :error
+    end
+
+    ##
+    # Raised on a `400` or `422` response: the request was malformed or failed
+    # server-side validation.
+    #
+    class BadRequestError < APIError
+    end
+
+    ##
+    # Raised on a `401` response: the bearer token was missing or invalid.
+    #
+    class AuthenticationError < APIError
+    end
+
+    ##
+    # Raised on a `403` response: the token is valid but not permitted to
+    # perform the request.
+    #
+    class PermissionError < APIError
+    end
+
+    ##
+    # Raised on a `404` response: the requested resource does not exist.
+    #
+    class NotFoundError < APIError
+    end
+
+    ##
+    # Raised on a `429` response: the request was refused for exceeding a
+    # server-side limit. In practice the server raises this only when a new run
+    # would exceed its fixed ceiling of concurrent runs; the limit clears as
+    # in-flight runs finish, not after a fixed interval.
+    #
+    # The server sends **no `Retry-After` header or other timing hint**, so the
+    # client does not retry automatically — whether and when to retry is left to
+    # the caller. Because the limit is concurrency- rather than time-based, a
+    # short pause (or simply retrying once an in-flight run completes) is more
+    # apt than fixed exponential backoff.
+    #
+    class RateLimitError < APIError
+    end
+
+    ##
+    # Raised on a `5xx` response: the server failed to handle the request.
+    #
+    class ServerError < APIError
+    end
+  end
+end

data/lib/hermes_agent/client/resources/capabilities.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "hermes_agent/client/entities/capabilities"
+
+module HermesAgent
+  class Client
+    module Resources
+      ##
+      # The capabilities resource: the server's self-description of the
+      # endpoints and features it supports (`/v1/capabilities`).
+      #
+      class Capabilities
+        ##
+        # Create the resource.
+        #
+        # @param transport [Transport] The transport used to issue requests.
+        #
+        # @private
+        def initialize(transport)
+          @transport = transport
+        end
+
+        ##
+        # Fetch the server's advertised capabilities.
+        #
+        # @return [Entities::Capabilities] The capabilities document.
+        #
+        def get
+          Entities::Capabilities.new(@transport.get("/v1/capabilities"))
+        end
+      end
+    end
+  end
+end

data/lib/hermes_agent/client/resources/chat.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "hermes_agent/client/entities/chat_completion"
+require "hermes_agent/client/util"
+
+module HermesAgent
+  class Client
+    module Resources
+      ##
+      # The chat resource: OpenAI-compatible chat completions
+      # (`POST /v1/chat/completions`). This endpoint is stateless — each call
+      # is independent — and, on a server configured with an API key, requires
+      # a bearer token (see {Client} / {Configuration}).
+      #
+      class Chat
+        ##
+        # The SSE `event:` name of the server's custom tool-progress frames,
+        # which are routed to {Entities::ChatToolProgress} rather than treated
+        # as completion chunks.
+        #
+        TOOL_PROGRESS_EVENT = "hermes.tool.progress"
+
+        ##
+        # Create the resource.
+        #
+        # @param transport [Transport] The transport used to issue requests.
+        #
+        # @private
+        def initialize(transport)
+          @transport = transport
+        end
+
+        ##
+        # Create a chat completion.
+        #
+        # No `model` is sent: the model is configured server-side and the
+        # server ignores a client-supplied one. (A caller who really wants to
+        # send fields we have not modeled — including `model` — can pass them
+        # through `extra`.)
+        #
+        # @param messages [Array<Hash>] The OpenAI-style message array. Each
+        #     message is a hash such as `{role: "user", content: "…"}`;
+        #     content may include `image_url` parts for inline images.
+        # @param session_id [String, nil] A session id to continue, sent as the
+        #     `X-Hermes-Session-ID` request header. When omitted, the server
+        #     generates a fresh one (returned on {Entities::SessionHeaders#session_id}).
+        # @param session_key [String, nil] A session key, sent as the
+        #     `X-Hermes-Session-Key` request header.
+        # @param idempotency_key [String, nil] An idempotency key, sent as the
+        #     `Idempotency-Key` request header. The server caches the result for
+        #     ~5 minutes and replays it for a repeat call carrying the same key
+        #     and an equivalent request, so a retry does not re-run the model.
+        #     The replay is **transparent**: the response is indistinguishable
+        #     from a fresh one (same status, no replay header, and a freshly
+        #     regenerated `id`), so there is no way — here or in the returned
+        #     entity — to tell whether a given call was served from the cache.
+        #     Reusing a key with a *different* request silently recomputes (no
+        #     error) and overwrites the cached entry. Honored only on this
+        #     non-streaming endpoint (not on {#stream_create}).
+        # @param extra [Hash] Additional request-body fields (e.g. sampling
+        #     parameters) merged into the body as-is.
+        # @return [Entities::ChatCompletion] The completion, carrying the
+        #     session headers returned by the server.
+        # @raise [APIError] If the server returns a non-2xx response.
+        #
+        def create(messages:, session_id: nil, session_key: nil, idempotency_key: nil, **extra)
+          body = {messages: messages, **extra}
+          headers = session_request_headers(session_id, session_key)
+          headers["Idempotency-Key"] = idempotency_key if idempotency_key
+          result = @transport.post("/v1/chat/completions", body, headers: headers)
+          Entities::ChatCompletion.new(result.body, **Util.session_headers(result.headers))
+        end
+
+        ##
+        # Create a chat completion, streaming the response.
+        #
+        # While the server agent executes tools it interleaves custom
+        # `hermes.tool.progress` frames; these are surfaced as
+        # {Entities::ChatToolProgress} events (distinct from the text
+        # {Entities::ChatCompletionChunk}s) and are not folded into the
+        # assembled completion.
+        #
+        # With a block, each event is yielded as it arrives and the assembled
+        # {Entities::ChatCompletion} is returned once the stream closes. Without
+        # a block, a {Stream} is returned for the caller to iterate; its
+        # {Stream#result} is the assembled completion.
+        #
+        # @param messages [Array<Hash>] The OpenAI-style message array (see
+        #     {#create}).
+        # @param session_id [String, nil] A session id to continue, sent as the
+        #     `X-Hermes-Session-ID` request header (see {#create}).
+        # @param session_key [String, nil] A session key, sent as the
+        #     `X-Hermes-Session-Key` request header (see {#create}).
+        # @param extra [Hash] Additional request-body fields merged into the
+        #     body as-is.
+        # @yieldparam event [Entities::ChatCompletionChunk, Entities::ChatToolProgress]
+        #     Each streamed event: a text chunk, or a tool-progress frame.
+        # @return [Entities::ChatCompletion, Stream] The assembled completion
+        #     (carrying the server's session headers) when a block is given,
+        #     otherwise the {Stream}.
+        # @raise [APIError] If the server returns a non-2xx response.
+        #
+        def stream_create(messages:, session_id: nil, session_key: nil, **extra, &block)
+          body = {messages: messages, stream: true, **extra}
+          result = @transport.stream_post("/v1/chat/completions", body,
+                                          headers: session_request_headers(session_id, session_key))
+          session = Util.session_headers(result.headers)
+          event_class = lambda do |name|
+            name == TOOL_PROGRESS_EVENT ? Entities::ChatToolProgress : Entities::ChatCompletionChunk
+          end
+          stream = Stream.new(result.body, event_class: event_class, terminator: "[DONE]") do |events|
+            Entities::ChatCompletion.from_chunks(events, **session)
+          end
+          return stream unless block
+
+          stream.each(&block)
+          stream.result
+        end
+
+        private
+
+        ##
+        # Build the session-continuity request headers, omitting either header
+        # the caller did not supply. Returns an empty hash when neither is set.
+        #
+        # @param session_id [String, nil] The session id, if any.
+        # @param session_key [String, nil] The session key, if any.
+        # @return [Hash{String=>String}]
+        #
+        def session_request_headers(session_id, session_key)
+          headers = {}
+          headers["X-Hermes-Session-ID"] = session_id if session_id
+          headers["X-Hermes-Session-Key"] = session_key if session_key
+          headers
+        end
+      end
+    end
+  end
+end

data/lib/hermes_agent/client/resources/health.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "hermes_agent/client/entities/health"
+
+module HermesAgent
+  class Client
+    ##
+    # Resource groups, each exposing the verb methods for one area of the API.
+    # Reached through accessors on {Client}, such as {Client#health}.
+    #
+    module Resources
+      ##
+      # The health resource. Health endpoints live at the server root, not
+      # under the `/v1` prefix.
+      #
+      class Health
+        ##
+        # Create the resource.
+        #
+        # @param transport [Transport] The transport used to issue requests.
+        #
+        # @private
+        def initialize(transport)
+          @transport = transport
+        end
+
+        ##
+        # Check whether the server is healthy.
+        #
+        # @return [Entities::Health] The health result; {Entities::Health#status}
+        #     is `"ok"` on a healthy server.
+        #
+        def check
+          Entities::Health.new(@transport.get("/health"))
+        end
+
+        ##
+        # Fetch detailed server health, including gateway state, per-platform
+        # connection status, and the active-agent count.
+        #
+        # @return [Entities::HealthDetails] The detailed health result.
+        #
+        def detailed
+          Entities::HealthDetails.new(@transport.get("/health/detailed"))
+        end
+      end
+    end
+  end
+end

data/lib/hermes_agent/client/resources/jobs.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "hermes_agent/client/entities/job"
+
+module HermesAgent
+  class Client
+    module Resources
+      ##
+      # The jobs resource: the Jobs API (`/api/jobs`) for scheduled background
+      # work — cron-like recurring tasks, one-shot deferred tasks, and watchdog
+      # scripts. On a server configured with an API key, these calls require a
+      # bearer token (see {Client} / {Configuration}).
+      #
+      # Note this resource lives under `/api/jobs`, **not** `/v1`, and is **not**
+      # advertised in `/v1/capabilities` — it may be gated, versioned
+      # separately, or absent in some builds; confirm against a server that
+      # exposes it.
+      #
+      # **No terminal state to poll.** The server **deletes** a job once it is
+      # exhausted: a one-shot (`once`) job is gone after its single run, and a
+      # `repeat`-capped job is gone after its final run. After that, {#get} (and
+      # {#trigger}) raise {NotFoundError} — a client cannot poll such a job for
+      # its outcome once it completes.
+      #
+      class Jobs
+        ##
+        # Create the resource.
+        #
+        # @param transport [Transport] The transport used to issue requests.
+        #
+        # @private
+        def initialize(transport)
+          @transport = transport
+        end
+
+        ##
+        # List the scheduled jobs. By default the server returns only enabled
+        # jobs; pass `include_disabled: true` to include paused/disabled ones.
+        # (The list is never paginated — the full set is always returned.)
+        #
+        # @param include_disabled [Boolean] Whether to include disabled
+        #     (paused) jobs. Defaults to `false` (enabled jobs only).
+        # @return [Array<Entities::Job>] The jobs (empty when there are none).
+        # @raise [APIError] If the server returns a non-2xx response.
+        #
+        def list(include_disabled: false)
+          path = include_disabled ? "/api/jobs?include_disabled=true" : "/api/jobs"
+          body = @transport.get(path)
+          Array(body["jobs"]).map { |raw| Entities::Job.new(raw) }
+        end
+
+        ##
+        # Create a scheduled job. `name` and `schedule` are required.
+        #
+        # `schedule` is a string parsed server-side into a `once` / `interval` /
+        # `cron` schedule: a bare duration (`"30m"`), an absolute timestamp
+        # (`"2027-02-03T14:00:00"`), an interval (`"every 30m"`), or a cron
+        # expression (`"0 9 * * *"`). The override slots (`model`, `provider`,
+        # `base_url`, `workdir`, `profile`, `context_from`) are **not** writable
+        # via this API and so are not parameters — they are silently ignored if
+        # sent. A caller who really wants to send unmodeled fields can pass them
+        # through `extra`.
+        #
+        # @param name [String] The job name (required).
+        # @param schedule [String] The schedule string (required; see above).
+        # @param prompt [String, nil] The task instruction. Omitted when `nil`.
+        # @param repeat [Integer, nil] The maximum number of runs (`nil` =
+        #     unbounded). Omitted when `nil`.
+        # @param deliver [String, nil] The delivery target (defaults server-side
+        #     to `"local"`). Omitted when `nil`. Not validated on write.
+        # @param skills [Array<String>, nil] Attached skill names. Omitted when
+        #     `nil`.
+        # @param script [String, nil] A script path under `~/.hermes/scripts/`.
+        #     Omitted when `nil`. **Note:** the reference gateway's create
+        #     handler silently drops this field (it stays `null`); kept as a
+        #     parameter for forward-compatibility and other deployments.
+        # @param no_agent [Boolean, nil] Whether to skip the LLM and deliver the
+        #     script's stdout verbatim. Omitted when `nil` (so `false` is sent).
+        #     **Note:** like `script`, silently dropped by the reference
+        #     gateway's create handler (stays `false`).
+        # @param extra [Hash] Additional request-body fields merged in as-is.
+        # @return [Entities::Job] The created job.
+        # @raise [BadRequestError] On a missing `name`/`schedule` (`400`).
+        # @raise [ServerError] On an **unparseable `schedule`** — the server
+        #     returns `500`, not `400`, even though it is really invalid input.
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def create(name:, schedule:, prompt: nil, repeat: nil, deliver: nil,
+                   skills: nil, script: nil, no_agent: nil, **extra)
+          body = {name: name, schedule: schedule, **extra}
+          body[:prompt] = prompt unless prompt.nil?
+          body[:repeat] = repeat unless repeat.nil?
+          body[:deliver] = deliver unless deliver.nil?
+          body[:skills] = skills unless skills.nil?
+          body[:script] = script unless script.nil?
+          body[:no_agent] = no_agent unless no_agent.nil?
+          Entities::Job.new(@transport.post("/api/jobs", body).body["job"])
+        end
+
+        ##
+        # Retrieve a job by id.
+        #
+        # @param job_id [String] The job id (12 hex characters).
+        # @return [Entities::Job] The current job state.
+        # @raise [NotFoundError] If no such job exists — including a job the
+        #     server already deleted because it was exhausted (a `once` job after
+        #     its run, or a capped job after its final run).
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def get(job_id)
+          Entities::Job.new(@transport.get("/api/jobs/#{job_id}")["job"])
+        end
+
+        ##
+        # Update a job (a partial merge over the writable fields). Sent fields
+        # are merged onto the existing job; a sent `schedule` is re-parsed and
+        # `next_run_at` recomputed. The override slots are **not** writable here
+        # either (silently ignored), so they are not parameters.
+        #
+        # @param job_id [String] The job id (12 hex characters).
+        # @param name [String, nil] A new name. Omitted when `nil`.
+        # @param schedule [String, nil] A new schedule string (re-parsed).
+        #     Omitted when `nil`.
+        # @param prompt [String, nil] A new prompt. Omitted when `nil`.
+        # @param repeat [Integer, nil] A new run cap. Omitted when `nil`.
+        # @param deliver [String, nil] A new delivery target. Omitted when `nil`.
+        # @param skills [Array<String>, nil] New skill names. Omitted when `nil`.
+        # @param script [String, nil] A new script path. Omitted when `nil`.
+        #     **Note:** silently dropped by the reference gateway (see {#create}).
+        # @param no_agent [Boolean, nil] A new `no_agent` flag. Omitted when
+        #     `nil`. **Note:** silently dropped by the reference gateway (see
+        #     {#create}).
+        # @param extra [Hash] Additional request-body fields merged in as-is.
+        # @return [Entities::Job] The updated job.
+        # @raise [NotFoundError] If no such job exists.
+        # @raise [ServerError] On an **unparseable `schedule`** (`500`, not
+        #     `400`; see {#create}).
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def update(job_id, name: nil, schedule: nil, prompt: nil, repeat: nil,
+                   deliver: nil, skills: nil, script: nil, no_agent: nil, **extra)
+          body = {**extra}
+          body[:name] = name unless name.nil?
+          body[:schedule] = schedule unless schedule.nil?
+          body[:prompt] = prompt unless prompt.nil?
+          body[:repeat] = repeat unless repeat.nil?
+          body[:deliver] = deliver unless deliver.nil?
+          body[:skills] = skills unless skills.nil?
+          body[:script] = script unless script.nil?
+          body[:no_agent] = no_agent unless no_agent.nil?
+          Entities::Job.new(@transport.patch("/api/jobs/#{job_id}", body)["job"])
+        end
+
+        ##
+        # Delete a job (also cancels any in-flight run).
+        #
+        # @param job_id [String] The job id (12 hex characters).
+        # @return [Boolean] `true` (mapped from the server's `{"ok": true}`).
+        # @raise [NotFoundError] If no such job exists.
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def delete(job_id)
+          @transport.delete("/api/jobs/#{job_id}")["ok"] == true
+        end
+
+        ##
+        # Pause a job without deleting it (sets `enabled: false`). Idempotent:
+        # pausing an already-paused job is not an error.
+        #
+        # @param job_id [String] The job id (12 hex characters).
+        # @return [Entities::Job] The paused job.
+        # @raise [NotFoundError] If no such job exists.
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def pause(job_id)
+          Entities::Job.new(@transport.post("/api/jobs/#{job_id}/pause", {}).body["job"])
+        end
+
+        ##
+        # Resume a paused job (recomputes `next_run_at` from the resume time).
+        # Idempotent: resuming an already-scheduled job is not an error.
+        #
+        # @param job_id [String] The job id (12 hex characters).
+        # @return [Entities::Job] The resumed job.
+        # @raise [NotFoundError] If no such job exists.
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def resume(job_id)
+          Entities::Job.new(@transport.post("/api/jobs/#{job_id}/resume", {}).body["job"])
+        end
+
+        ##
+        # Trigger a job to run out of schedule.
+        #
+        # This is **asynchronous**: it advances the job's `next_run_at` to "now"
+        # so the scheduler picks it up on its next tick, then returns the job
+        # immediately — it does **not** block on or return the run's result, and
+        # `last_run_at` / `last_status` / `repeat.completed` are not yet updated
+        # when it returns. (For a one-shot or final-run job, the job may be
+        # deleted once it fires, so it cannot be polled afterward — see {#get}.)
+        #
+        # @param job_id [String] The job id (12 hex characters).
+        # @return [Entities::Job] The job, with `next_run_at` advanced.
+        # @raise [NotFoundError] If no such job exists.
+        # @raise [APIError] If the server returns another non-2xx response.
+        #
+        def trigger(job_id)
+          Entities::Job.new(@transport.post("/api/jobs/#{job_id}/run", {}).body["job"])
+        end
+      end
+    end
+  end
+end