temper-rb 0.5.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 053faaf3ac47a6d158e0b6b01f1ee9b676721480efdb0d37da4a5a78c4852d13
+  data.tar.gz: 916b5ba30ee421ec644905e3dedafb900c6189536fe0afd3b1bf8fa561584f7e
+SHA512:
+  metadata.gz: 7ee3400fe23a21d1ed53d766001502080c5c01b719a0b40602c8205f83ea7ba612b5c855fb3264955784c238df67e94505e27fb89d2b7cd1b1d4b0f142cc9128
+  data.tar.gz: c92c7ad413560450bdc8801f49a6c5c52cb5140e2452b8564aee7bd9c7d072233758056025218617d63728767214e94e2b86dd7731df07096ffdb7fbcc12352c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tasker Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,291 @@
+# temper-rb
+
+A pure-Ruby SDK for the [Temper](https://temperkb.io) knowledge-base API.
+
+There is no native extension: one source gem, no compiler on the install box, no
+platform matrix. The client core is generated from the API's `openapi.json` and
+committed, so building and testing this gem needs neither Docker nor a JVM.
+
+> **The integration how-to lives in the repo:**
+> [docs/sdks/temper-rb.md](https://github.com/tasker-systems/temper/blob/main/docs/sdks/temper-rb.md).
+> It covers the two callers, both machine-credential mint paths, the token
+> lifecycle, attribution across the enqueue boundary, the error taxonomy, and
+> going live. This README is the quickstart.
+
+## Install
+
+```ruby
+gem 'temper-rb'
+```
+
+Ruby >= 3.1.
+
+## Configure
+
+```ruby
+Temper.configure do |c|
+  c.base_url  = ENV.fetch('TEMPER_API_URL')
+  c.device_id = ENV['TEMPER_DEVICE_ID']   # optional; sets X-Temper-Device-Id
+end
+```
+
+The connection is **process-global**. The **token is per call**. Constructing a
+`Temper::Client` does no I/O, so build one per request if you like.
+
+## Puma — a token the caller already holds
+
+```ruby
+client = Temper::Client.new(
+  credentials: Temper::Credentials::BearerToken.new(session_token))
+
+client.resources.create(
+  title: 'Postmortem', context_ref: '@dana/incidents',
+  doc_type_name: 'note', content: markdown,
+  act: Temper::Act.new(confidence: :probable, reasoning: 'summarised the incident'))
+```
+
+A `BearerToken` does no I/O and **cannot refresh** — `refresh!` raises. A user's
+token is not the app's to re-mint.
+
+`Temper::Act` refuses to be built with `reasoning`, `rationale`, `persona`, or
+`model` unless you also give `confidence` — the server would reject it with a
+400, so the gem rejects it locally instead.
+
+## Sidekiq — a machine principal
+
+```ruby
+CREDENTIALS = Temper::Credentials::ClientCredentials.new(
+  token_url:     ENV.fetch('TEMPER_M2M_TOKEN_URL'),
+  client_id:     ENV.fetch('TEMPER_M2M_CLIENT_ID'),
+  client_secret: ENV.fetch('TEMPER_M2M_CLIENT_SECRET'),
+  audience:      ENV['TEMPER_M2M_AUDIENCE'])   # Auth0 only — omit for temper-issued
+```
+
+It caches the token until 60 seconds before its absolute expiry, mints under a
+mutex (Puma threads race a cold cache), and re-mints once on a 401 — because a job
+that holds a token across a long unit of work can outlive it, and
+refresh-ahead-of-expiry alone does not save you there.
+
+### Two mint paths
+
+The token request is form-encoded on both (RFC 6749 §4). Only the config differs.
+
+| | Auth0-issued (`temper admin machine provision`) | Temper-issued (`temper admin machine issue`) |
+|---|---|---|
+| `client_id` | your Auth0 M2M app's client id | minted by temper, prefixed `tmpr_` |
+| `client_secret` | from Auth0 | printed **once** at `issue` |
+| `token_url` | your Auth0 tenant's `/oauth/token` | **your own instance's** `/oauth/token` |
+| `audience` | **required** — must equal the API's `AUTH_AUDIENCE` | **omit it** |
+
+Temper's own authorization server mints with its server-side `AS_AUDIENCE` and
+ignores a request-supplied one, so the SDK leaves `audience` off the wire entirely
+rather than sending an empty string.
+
+## Correlation across the enqueue boundary
+
+The Puma request writes as the signed-in user; the Sidekiq job it enqueues writes
+as the **machine profile**. Two authors, honestly — the machine really did make the
+second write. A correlation id stitches them together in the event ledger.
+
+```ruby
+correlation = SecureRandom.uuid
+PostmortemJob.perform_async(correlation)
+# ...and in the worker:
+act = Temper::Act.new(confidence: :probable, correlation: correlation)
+```
+
+Correlation is provenance, never authorization. Nothing gates on it, and an act
+that supplies none self-roots to its own event id — so you may always omit it.
+
+## Errors
+
+```
+Temper::Error
+├─ Temper::TransientError          # let it escape → Sidekiq retries
+│  ├─ RateLimited      (429, #retry_after)
+│  ├─ ServerError      (5xx)
+│  └─ ConnectionError  (timeout / refused)
+└─ Temper::PermanentError          # rescue it → dead-letter
+   ├─ Unauthorized     (401)
+   ├─ Forbidden        (403)
+   │  └─ SystemAccessRequired
+   ├─ NotFound         (404)
+   ├─ Conflict         (409)
+   └─ BadRequest       (400 / 422)
+```
+
+Every exception carries `#status`, `#code`, `#message`, and `#details`.
+
+`SystemAccessRequired` adds `#refusal` — a **typed** reason the server refused,
+which is what lets a worker tell "never granted" from "granted and then revoked"
+without matching on the message string:
+
+```ruby
+rescue Temper::SystemAccessRequired => e
+  case e.refusal
+  when Temper::Generated::Denied    then request_access!  # never granted — ask
+  when Temper::Generated::Requested then wait             # asked, pending review
+  when Temper::Generated::Revoked   then alert_operator!  # had it, lost it
+  else log.warn("refused: #{e.refusal_kind}")             # a reason newer than this gem
+  end
+```
+
+Data-bearing refusals carry their payload: an `IllegalTransition` names the `act`
+it refused and the standing it refused it `from`. `#refusal` is `nil` when the
+reason is one this gem was not generated against — `#refusal_kind` still returns
+the name the server used, so an unfamiliar refusal is logged rather than lost.
+
+The split is load-bearing, not decorative: Sidekiq retries a job whose exception
+escapes, so a 409 classified transient would spin forever and a 503 classified
+permanent would be silently dropped.
+
+Idempotent reads retry three times on 5xx and transport failures. **Writes are
+never auto-retried.** The SDK classifies; it does not decide to re-submit.
+
+## Composition bounds raise before the request `[2026-08-28]`
+
+`/api/query`'s contract publishes ceilings on what one composition may declare, and the
+generated models enforce them in their attribute writers — which `initialize` calls — so
+these raise `ArgumentError` locally rather than returning a `BadRequest` with a typed
+refusal. The writers are **not** gated on `client_side_validation`, so this cannot be
+switched off.
+
+| field | ceiling |
+|---|---|
+| `Composition#stages` | 64 |
+| `Intention#query` | 4096 |
+| `IdSet#ids` | 256 |
+| `ResourceFilter#doc_type` / `#tags`, `EdgeFilter#labels` | 256 |
+
+**This is a behaviour change for code that already builds large plans**: a 300-id `IdSet`
+used to construct fine and reach the server. It now raises before any HTTP call.
+
+**The gem counts characters; the server counts bytes.** A 4096-character CJK question is
+8192 bytes — it constructs cleanly here and is refused server-side as `intention_too_long`.
+The skew is one-directional (a UTF-8 string is never fewer bytes than characters), so the
+gem can only under-enforce, never refuse something the server would have run.
+
+The per-stage predicate and probe caps and the aggregate embed budget
+(`intention_budget_exceeded`) are deliberately not enforced here — neither is a contract
+fact — and arrive as refusals.
+
+
+## Going live
+
+Authentication is not authorization. A valid M2M token does **not** get you in on
+its own: temper keeps a registration allowlist, so your `client_id` must be
+registered before your first call. An unregistered (or revoked) client
+authenticates cleanly at its issuer and is then rejected with a terminal
+`Unauthorized` — `client 'X' is not registered with this instance` — which the SDK
+classifies as a `PermanentError` (a Sidekiq worker dead-letters it rather than
+retrying). Registered but un-granted, you then get a `SystemAccessRequired` 403.
+Those are the two walls, in that order.
+
+Registration and reach happen in one command, on whichever mint path you chose:
+
+```bash
+# Auth0-issued: register the M2M application you already created
+temper admin machine provision \
+  --client-id "$TEMPER_M2M_CLIENT_ID" --label "acme-worker" \
+  --owner-team acme-eng --team acme-eng:member --cogmap <map-ref>
+
+# Temper-issued: temper mints the client id and secret; the secret prints once
+temper admin machine issue \
+  --label "acme-worker" \
+  --owner-team acme-eng --team acme-eng:member --cogmap <map-ref>
+```
+
+Each `--team` gives **team membership** for read reach; each `--cogmap` applies a
+**cogmap write grant**. Both are repeatable — reach is plural and explicit, and is
+never inferred from `--owner-team` (which records the machine's owner only).
+
+This need not be an operator ticket: minting is authorized for a system admin **or
+the owner of the team that will own the machine**, so a team owner can register
+their own team's machine. A teamless machine is admin-only.
+
+**Rotation.** `temper admin machine rotate-secret` rolls a temper-issued **secret**
+(same `client_id`), keeping the previous one valid for a grace window while you
+redeploy the app with the new secret. `temper admin machine rebind` is a different
+operation: a **new `client_id`** bound to the same agent profile, for rotating the
+Auth0 application behind a machine — and it is system-admin only. Rotating an Auth0
+*secret* needs no temper action at all.
+
+See
+[docs/guides/machine-credentials.md](https://github.com/tasker-systems/temper/blob/main/docs/guides/machine-credentials.md)
+for the operator's side.
+
+Assert it worked at boot rather than discovering it on the first write:
+
+```ruby
+Temper::Client.new(credentials: CREDENTIALS).whoami
+```
+
+An unregistered client surfaces as `Unauthorized` naming the client id; a
+registered-but-under-granted one surfaces as `Forbidden` / `SystemAccessRequired`
+naming the missing grant — both from the server's `error.details`, not a bare 4xx.
+
+## Forking
+
+The connection holds sockets. Call `Temper.reset_connection!` in a forked worker:
+
+```ruby
+# config/puma.rb
+on_worker_boot { Temper.reset_connection! }
+
+# config/initializers/sidekiq.rb
+Sidekiq.configure_server { |_| Temper.reset_connection! }
+```
+
+Strictly speaking the sockets are already safe: `connection_pool` (>= 2.4, which
+`net-http-persistent` pools through) drops them from a `Process._fork` hook, and
+this gem's test suite proves a forked child opens its own socket. The hooks above
+clear *this gem's* memoized client rather than relying on a transitive
+dependency's default. Keep them.
+
+## Addressing
+
+Resources are addressed by **ref**: a bare UUID, or the decorated
+`sluggify(title)-<uuid>` form. Resolution is trailing-UUID-only, so a stale slug
+half is harmless.
+
+```ruby
+client.resources.show('p4-design-the-gem-019f4912-3f20-7fd3-814f-13a5ddbe3cd7')
+client.resources.show('019f4912-3f20-7fd3-814f-13a5ddbe3cd7')  # identical
+```
+
+`Temper.parse_ref` is available directly, and never touches the network.
+
+## Cognitive maps
+
+The SDK authors into a map incrementally — `cognitive_maps.author` (ingest with
+`home_cogmap_id`), `assert_relationship`, and `set_facet` — all paths where the
+server chunks and embeds for you.
+
+**Bulk reconcile is not exposed.** `PUT /api/cognitive-maps/{id}` takes a
+pre-embedded desired-state manifest: its `chunks_packed` is a required,
+client-computed 768-dimension BGE embedding, carried verbatim with no server-side
+fallback. Ruby has no embedder, so that path is physically out of reach. It is a
+CLI operator's job, not a Rails request's. If you truly need it, reach
+`Temper::Generated::CognitiveMapsApi#reconcile` and pack the chunks yourself.
+
+## Versioning
+
+`Temper::VERSION` is the gem's own SemVer. `Temper::CONTRACT_VERSION` names the
+`openapi.json` it was generated against. They answer different questions and are
+not forced to agree.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake          # rubocop + rspec
+bundle exec rake generate # regenerate lib/temper/generated/** (needs Docker)
+bundle exec rake drift    # fail if the committed core drifts from the contract
+```
+
+`rake generate` is the only writer of `lib/temper/generated/**`. Never hand-edit
+that tree; the hand-written skin lives beside it, in `lib/temper/*.rb`.
+
+## License
+
+MIT.

data/lib/temper/act.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Temper
+  # Act context for a write. Optional on every call.
+  #
+  # The constructor invariant mirrors ActInput::into_act_context: Rust's
+  # AgentAuthorship.confidence is non-Option, so authorship without confidence is
+  # a 400. Rejecting it here is the parse-don't-validate answer -- an invalid Act
+  # cannot be constructed, so no call site can send one.
+  #
+  # `correlation` and `invocation` are exempt: correlation is provenance, never
+  # authorship, and an act with no supplied correlation self-roots to its own
+  # event id. Nothing gates on it, so the gem may always omit it.
+  class Act
+    AUTHORSHIP_FIELDS = %i[reasoning rationale persona model].freeze
+
+    def initialize(confidence: nil, reasoning: nil, rationale: nil, persona: nil, model: nil,
+                   correlation: nil, invocation: nil)
+      authorship = { reasoning: reasoning, rationale: rationale, persona: persona, model: model }
+      require_confidence!(confidence, authorship)
+
+      @fields = authorship.merge(
+        confidence: confidence&.to_s,
+        correlation_id: correlation,
+        invocation_id: invocation
+      ).compact.freeze
+    end
+
+    # Symbol-keyed, nils omitted: the server distinguishes an absent key from null.
+    # These are the seven ActInput wire keys, which flatten into ~30 write bodies
+    # and onto the query string of DELETE /api/resources/{id}.
+    def to_h
+      @fields.dup
+    end
+
+    private
+
+    def require_confidence!(confidence, authorship)
+      return unless confidence.nil?
+
+      supplied = authorship.compact.keys
+      return if supplied.empty?
+
+      raise ArgumentError, "Temper::Act requires `confidence:` when supplying #{supplied.join(', ')}"
+    end
+  end
+end

data/lib/temper/client.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Temper
+  # A cheap façade over the process-global connection. Holds a credential and
+  # nothing else; constructing one does no I/O, so a Puma request can build one
+  # per user and a Sidekiq process can memoize one.
+  class Client
+    MAX_READ_ATTEMPTS = 3
+    # 200ms, 400ms -- mirroring MAX_ATTEMPTS and the backoff in
+    # crates/temper-client/src/http.rs.
+    DEFAULT_BACKOFF = ->(attempt) { sleep(0.2 * (2**(attempt - 1))) }
+
+    def initialize(credentials:, backoff: DEFAULT_BACKOFF)
+      @credentials = credentials
+      @backoff = backoff
+    end
+
+    # Assert the machine profile resolved, and report what it can reach, rather
+    # than discovering it on the first write.
+    #
+    # Authentication is not authorization. A minted M2M token does not even yield a
+    # profile on its own: the client_id must already be registered (lookup-or-401 --
+    # there is no JIT-create branch), and then, without a cogmap write grant and team
+    # membership, every call authenticates cleanly and 403s.
+    def whoami
+      call(idempotent: true) { |api| Generated::ProfileApi.new(api).get_profile }
+    end
+
+    def resources
+      @resources ||= Resources.new(self)
+    end
+
+    def contexts
+      @contexts ||= Contexts.new(self)
+    end
+
+    def cognitive_maps
+      @cognitive_maps ||= CognitiveMaps.new(self)
+    end
+
+    # SearchParams names the field `query`, not `q`.
+    def search(query, **opts)
+      params = Generated::SearchParams.new({ query: query }.merge(opts))
+      call(idempotent: true) { |api| Generated::SearchApi.new(api).search(params) }
+    end
+
+    def graph
+      Generated::GraphApi.new(Temper.api_client)
+    end
+
+    # The one seam every surface module goes through.
+    #
+    #   idempotent: true  => a safe method. 5xx and transport failures retry.
+    #   idempotent: false => a write. NEVER auto-retried.
+    #
+    # A 401 is repaired once, for reads and writes alike: re-authenticating is not
+    # re-submitting. BearerToken#refresh! raises, so a bearer caller makes exactly
+    # one request and the Unauthorized propagates out of refresh! itself.
+    def call(idempotent: false, &block)
+      attempt = 0
+      reminted = false
+
+      begin
+        attempt += 1
+        Temper.with_token(@credentials.token) { block.call(Temper.api_client) }
+      rescue Generated::ApiError => e
+        error = ErrorMapper.call(e)
+
+        if repair_credentials?(error, reminted)
+          reminted = true
+          retry
+        end
+
+        raise error unless retryable_read?(error, idempotent, attempt)
+
+        @backoff.call(attempt)
+        retry
+      end
+    end
+
+    private
+
+    # BearerToken#refresh! raises Unauthorized, so a bearer caller never reaches
+    # the retry -- the raise propagates straight out of refresh!.
+    def repair_credentials?(error, reminted)
+      return false unless error.is_a?(Unauthorized) && !reminted
+
+      @credentials.refresh!
+      true
+    end
+
+    def retryable_read?(error, idempotent, attempt)
+      idempotent && error.is_a?(TransientError) && attempt < MAX_READ_ATTEMPTS
+    end
+  end
+end

data/lib/temper/cognitive_maps.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Temper
+  # Incremental cognitive-map authoring (D9).
+  #
+  # Every path here is server-recompute: the server chunks and embeds. Bulk
+  # reconcile (PUT /api/cognitive-maps/{id}) is deliberately absent -- its
+  # ReconcileEntry.chunks_packed is a required, PRE-EMBEDDED String, carried
+  # verbatim with no server-side ONNX fallback, so a Ruby client cannot physically
+  # reach it without a 768-dim BGE embedder. It is a CLI operator's job, not a
+  # Rails request's. Reach Generated::CognitiveMapsApi#reconcile directly if you
+  # hand-pack chunks.
+  class CognitiveMaps
+    DEFAULT_POLARITY = 'forward'
+
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /api/cognitive-maps -> 200 CreateCogmapOutcome.
+    #
+    # Genesis takes an Option<ReconcileTelos>, so a charter-less map is creatable
+    # -- but CreateCogmapRequest still requires `telos_title`. Charter-less is not
+    # title-less. CreateCogmapRequest carries no act keys.
+    def create(name:, telos_title:, telos: nil, cogmap_id: nil, telos_resource_id: nil)
+      attrs = { name: name, telos_title: telos_title }
+      attrs[:telos] = telos unless telos.nil?
+      attrs[:cogmap_id] = cogmap_id unless cogmap_id.nil?
+      attrs[:telos_resource_id] = telos_resource_id unless telos_resource_id.nil?
+
+      body = Generated::CreateCogmapRequest.new(attrs)
+      @client.call { |api| Generated::CognitiveMapsApi.new(api).genesis(body) }
+    end
+
+    # A map node is a NEW resource that distills from its sources; ingest with
+    # home_cogmap_id is how it is born. The server chunks and embeds.
+    def author(cogmap_ref, title:, content:, context_ref:, doc_type_name:, act: nil, **opts)
+      @client.resources.create(
+        title: title, context_ref: context_ref, doc_type_name: doc_type_name,
+        content: content, act: act, home_cogmap_id: Temper.parse_ref(cogmap_ref), **opts
+      )
+    end
+
+    # POST /api/relationships (not /api/relationships/assert). The contract requires
+    # all of source, target, edge_kind, polarity, label, weight; the seven act keys
+    # flatten on, as they do on IngestPayload.
+    #
+    # edge_kind is one of express, contains, leads_to, near.
+    def assert_relationship(source:, target:, edge_kind:, label:, weight:,
+                            polarity: DEFAULT_POLARITY, act: nil)
+      body = Generated::AssertRelationshipRequest.new(
+        { source: Temper.parse_ref(source), target: Temper.parse_ref(target),
+          edge_kind: edge_kind, polarity: polarity, label: label, weight: weight }
+          .merge(act_hash(act))
+      )
+      @client.call { |api| Generated::RelationshipsApi.new(api).assert(body) }
+    end
+
+    # POST /api/facets (not /api/facets/set). `values` is plural, and is the
+    # facet's typed value payload.
+    def set_facet(resource:, values:, weight: nil, act: nil)
+      attrs = { resource: Temper.parse_ref(resource), values: values }
+      attrs[:weight] = weight unless weight.nil?
+
+      body = Generated::FacetSetRequest.new(attrs.merge(act_hash(act)))
+      @client.call { |api| Generated::FacetsApi.new(api).set_facet(body) }
+    end
+
+    private
+
+    def act_hash(act)
+      act.nil? ? {} : act.to_h
+    end
+  end
+end

data/lib/temper/connection.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/gzip'
+require 'faraday/net_http_persistent'
+require 'uri'
+
+module Temper
+  # Thread.current[] is FIBER-local in Ruby (Thread#thread_variable_get is the
+  # thread-local one). Fiber[] would read better but arrived in 3.2, and the
+  # gem's floor is 3.1.
+  TOKEN_KEY = :temper_access_token
+  private_constant :TOKEN_KEY
+
+  class << self
+    # One ApiClient per process => one Faraday connection => one
+    # net-http-persistent per-thread pool.
+    #
+    # A fresh Configuration + ApiClient per request is the obvious fix for the
+    # generated singletons' single shared access_token, and it is a trap: fresh
+    # client, fresh connection, TLS handshake per request. Instead the connection
+    # is process-global and the TOKEN is call-scoped, via access_token_getter.
+    def api_client
+      connection_mutex.synchronize { @api_client ||= build_api_client }
+    end
+
+    # Call from Puma's on_worker_boot and from Sidekiq.configure_server, so a
+    # forked worker never inherits its parent's sockets.
+    def reset_connection!
+      connection_mutex.synchronize { @api_client = nil }
+      nil
+    end
+
+    def current_token
+      Thread.current[TOKEN_KEY]
+    end
+
+    def with_token(token)
+      previous = Thread.current[TOKEN_KEY]
+      Thread.current[TOKEN_KEY] = token
+      yield
+    ensure
+      Thread.current[TOKEN_KEY] = previous
+    end
+
+    private
+
+    def connection_mutex
+      @connection_mutex ||= Mutex.new
+    end
+
+    def build_api_client
+      generated = build_generated_config
+      Generated::ApiClient.new(generated).tap do |client|
+        client.default_headers['X-Temper-Surface'] = 'sdk'
+        client.default_headers['X-Temper-Device-Id'] = config.device_id if config.device_id
+      end
+    end
+
+    def build_generated_config
+      Generated::Configuration.new.tap do |c|
+        apply_endpoint(c, base_uri)
+        c.access_token_getter = -> { Temper.current_token }
+        configure_faraday(c)
+      end
+    end
+
+    def base_uri
+      raise ArgumentError, 'Temper.config.base_url is not set' if config.base_url.nil?
+
+      # Every request puts the bearer token on this URL, so the scheme is
+      # checked where the client is built, not per request. The opt-in is
+      # configuration here (not a kwarg) because the gem's URL is process-wide.
+      Validate.require_endpoint(config.base_url, name: 'base_url',
+                                                 allow_insecure_http: config.allow_insecure_http)
+    end
+
+    def apply_endpoint(generated_config, base)
+      generated_config.scheme = base.scheme
+      generated_config.host = host_with_port(base)
+      generated_config.base_path = base.path
+    end
+
+    # `configure_faraday_connection` REGISTERS the block; `configure_connection` is
+    # the invoker the generated ApiClient calls with the connection.
+    #
+    # It runs AFTER build_connection sets conn.adapter(Faraday.default_adapter), so
+    # setting the adapter here replaces it. An adapter set via `configure_middleware`
+    # runs BEFORE, and would be silently overwritten by the default -- costing a TLS
+    # handshake per request while nothing fails.
+    #
+    # `conn.request :gzip` installs faraday-gzip's decompression middleware. It sets
+    # Accept-Encoding: gzip,deflate and inflates the response in Faraday's
+    # on_complete -- OUTSIDE Net::HTTP. That is the whole point: the
+    # net_http_persistent adapter bypasses Net::HTTP's transparent gzip handling, so
+    # without this a `Content-Encoding: gzip` body reaches the deserializer as raw
+    # compressed bytes and every read returns nil (issue #446). Order is irrelevant
+    # -- Faraday keeps the adapter last regardless of call order -- but registering
+    # the request middleware before the adapter reads in stack order.
+    def configure_faraday(generated_config)
+      generated_config.configure_faraday_connection do |conn|
+        conn.request :gzip
+        conn.adapter :net_http_persistent, pool_size: 5
+      end
+    end
+
+    def host_with_port(base)
+      return base.host if base.port.nil? || base.port == base.default_port
+
+      "#{base.host}:#{base.port}"
+    end
+  end
+end