basecamp-sdk 0.14.0 → 0.16.0

data/lib/basecamp/generated/types.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Auto-generated from OpenAPI spec. Do not edit manually.
-# Generated: 2026-08-07T11:12:00Z
+# Generated: 2026-09-03T02:27:36Z
 
 require "json"
 require "time"
@@ -2672,23 +2672,23 @@ module Basecamp
     # MyAssignmentAssignee
     class MyAssignmentAssignee
       include TypeHelpers
-      attr_accessor :id, :avatar_url, :name
+      attr_accessor :avatar_url, :id, :name
 
       # @return [Array<Symbol>]
       def self.required_fields
-        %i[id].freeze
+        %i[avatar_url id name].freeze
       end
 
       def initialize(data = {})
-        @id = parse_integer(data["id"])
         @avatar_url = data["avatar_url"]
+        @id = parse_integer(data["id"])
         @name = data["name"]
       end
 
       def to_h
         {
-          "id" => @id,
           "avatar_url" => @avatar_url,
+          "id" => @id,
           "name" => @name,
         }.compact
       end
@@ -2955,23 +2955,23 @@ module Basecamp
     # OutOfOfficePerson
     class OutOfOfficePerson
       include TypeHelpers
-      attr_accessor :id, :avatar_url, :name
+      attr_accessor :avatar_url, :id, :name
 
       # @return [Array<Symbol>]
       def self.required_fields
-        %i[id].freeze
+        %i[avatar_url id name].freeze
       end
 
       def initialize(data = {})
-        @id = parse_integer(data["id"])
         @avatar_url = data["avatar_url"]
+        @id = parse_integer(data["id"])
         @name = data["name"]
       end
 
       def to_h
         {
-          "id" => @id,
           "avatar_url" => @avatar_url,
+          "id" => @id,
           "name" => @name,
         }.compact
       end
@@ -3169,7 +3169,7 @@ module Basecamp
       include TypeHelpers
       # @!attribute [rw] clientside
       #   @deprecated This shape is deprecated since 2024-01: Use Client Visibility feature instead
-      attr_accessor :app_url, :created_at, :id, :name, :status, :updated_at, :url, :bookmark_url, :bookmarked, :client_company, :clients_enabled, :clientside, :description, :dock, :end_date, :purpose, :start_date
+      attr_accessor :app_url, :created_at, :id, :name, :status, :updated_at, :url, :bookmark_url, :bookmarked, :client_company, :clients_enabled, :clientside, :description, :dock, :end_date, :purpose, :star_url, :starred, :start_date
 
       # @return [Array<Symbol>]
       def self.required_fields
@@ -3193,6 +3193,8 @@ module Basecamp
         @dock = parse_array(data["dock"], "DockItem")
         @end_date = data["end_date"]
         @purpose = data["purpose"]
+        @star_url = data["star_url"]
+        @starred = parse_boolean(data["starred"])
         @start_date = data["start_date"]
       end
 
@@ -3214,6 +3216,8 @@ module Basecamp
           "dock" => @dock,
           "end_date" => @end_date,
           "purpose" => @purpose,
+          "star_url" => @star_url,
+          "starred" => @starred,
           "start_date" => @start_date,
         }.compact
       end
@@ -4025,62 +4029,114 @@ module Basecamp
     # SearchResult
     class SearchResult
       include TypeHelpers
-      attr_accessor :app_url, :content, :description, :id, :title, :type, :url, :bookmark_url, :bubble_up_url, :bucket, :content_attachments, :created_at, :creator, :description_attachments, :inherits_status, :parent, :plain_text_content, :plain_text_description, :status, :subject, :updated_at, :visible_to_clients
+      attr_accessor :content, :description, :app_download_url, :app_url, :attachments, :bookmark_url, :boosts_count, :boosts_url, :bubble_up_url, :bucket, :byte_size, :cards_count, :cards_url, :color, :comment_count, :comments_count, :comments_url, :content_attachments, :content_type, :created_at, :creator, :description_attachments, :download_url, :filename, :height, :id, :image_url, :inherits_status, :language, :on_hold, :parent, :plain_text_content, :plain_text_description, :position, :preview_url, :previewable, :sound_url, :status, :subject, :subscribers, :subscription_url, :thumbnail_url, :title, :type, :updated_at, :url, :visible_to_clients, :width
 
       # @return [Array<Symbol>]
       def self.required_fields
-        %i[app_url content description id title type url].freeze
+        %i[content description].freeze
       end
 
       def initialize(data = {})
-        @app_url = data["app_url"]
         @content = data["content"]
         @description = data["description"]
-        @id = parse_integer(data["id"])
-        @title = data["title"]
-        @type = data["type"]
-        @url = data["url"]
+        @app_download_url = data["app_download_url"]
+        @app_url = data["app_url"]
+        @attachments = parse_array(data["attachments"], "SearchResultAttachment")
         @bookmark_url = data["bookmark_url"]
+        @boosts_count = parse_integer(data["boosts_count"])
+        @boosts_url = data["boosts_url"]
         @bubble_up_url = data["bubble_up_url"]
         @bucket = parse_type(data["bucket"], "RecordingBucket")
+        @byte_size = parse_integer(data["byte_size"])
+        @cards_count = parse_integer(data["cards_count"])
+        @cards_url = data["cards_url"]
+        @color = data["color"]
+        @comment_count = parse_integer(data["comment_count"])
+        @comments_count = parse_integer(data["comments_count"])
+        @comments_url = data["comments_url"]
         @content_attachments = parse_array(data["content_attachments"], "RichTextAttachment")
+        @content_type = data["content_type"]
         @created_at = parse_datetime(data["created_at"])
         @creator = parse_type(data["creator"], "Person")
         @description_attachments = parse_array(data["description_attachments"], "RichTextAttachment")
+        @download_url = data["download_url"]
+        @filename = data["filename"]
+        @height = parse_integer(data["height"])
+        @id = parse_integer(data["id"])
+        @image_url = data["image_url"]
         @inherits_status = parse_boolean(data["inherits_status"])
+        @language = data["language"]
+        @on_hold = parse_type(data["on_hold"], "CardColumnOnHold")
         @parent = parse_type(data["parent"], "RecordingParent")
         @plain_text_content = data["plain_text_content"]
         @plain_text_description = data["plain_text_description"]
+        @position = parse_integer(data["position"])
+        @preview_url = data["preview_url"]
+        @previewable = parse_boolean(data["previewable"])
+        @sound_url = data["sound_url"]
         @status = data["status"]
         @subject = data["subject"]
+        @subscribers = parse_array(data["subscribers"], "Person")
+        @subscription_url = data["subscription_url"]
+        @thumbnail_url = data["thumbnail_url"]
+        @title = data["title"]
+        @type = data["type"]
         @updated_at = parse_datetime(data["updated_at"])
+        @url = data["url"]
         @visible_to_clients = parse_boolean(data["visible_to_clients"])
+        @width = parse_integer(data["width"])
       end
 
       def to_h
         {
-          "app_url" => @app_url,
           "content" => @content,
           "description" => @description,
-          "id" => @id,
-          "title" => @title,
-          "type" => @type,
-          "url" => @url,
+          "app_download_url" => @app_download_url,
+          "app_url" => @app_url,
+          "attachments" => @attachments,
           "bookmark_url" => @bookmark_url,
+          "boosts_count" => @boosts_count,
+          "boosts_url" => @boosts_url,
           "bubble_up_url" => @bubble_up_url,
           "bucket" => @bucket,
+          "byte_size" => @byte_size,
+          "cards_count" => @cards_count,
+          "cards_url" => @cards_url,
+          "color" => @color,
+          "comment_count" => @comment_count,
+          "comments_count" => @comments_count,
+          "comments_url" => @comments_url,
           "content_attachments" => @content_attachments,
+          "content_type" => @content_type,
           "created_at" => @created_at,
           "creator" => @creator,
           "description_attachments" => @description_attachments,
+          "download_url" => @download_url,
+          "filename" => @filename,
+          "height" => @height,
+          "id" => @id,
+          "image_url" => @image_url,
           "inherits_status" => @inherits_status,
+          "language" => @language,
+          "on_hold" => @on_hold,
           "parent" => @parent,
           "plain_text_content" => @plain_text_content,
           "plain_text_description" => @plain_text_description,
+          "position" => @position,
+          "preview_url" => @preview_url,
+          "previewable" => @previewable,
+          "sound_url" => @sound_url,
           "status" => @status,
           "subject" => @subject,
+          "subscribers" => @subscribers,
+          "subscription_url" => @subscription_url,
+          "thumbnail_url" => @thumbnail_url,
+          "title" => @title,
+          "type" => @type,
           "updated_at" => @updated_at,
+          "url" => @url,
           "visible_to_clients" => @visible_to_clients,
+          "width" => @width,
         }.reject { |k, v| v.nil? && !["content", "description"].include?(k) }
       end
 
@@ -4089,6 +4145,55 @@ module Basecamp
       end
     end
 
+    # SearchResultAttachment
+    class SearchResultAttachment
+      include TypeHelpers
+      attr_accessor :byte_size, :content_type, :download_url, :filename, :height, :id, :preview_url, :previewable, :sgid, :thumbnail_url, :title, :url, :width
+
+      # @return [Array<Symbol>]
+      def self.required_fields
+        %i[byte_size content_type download_url filename].freeze
+      end
+
+      def initialize(data = {})
+        @byte_size = parse_integer(data["byte_size"])
+        @content_type = data["content_type"]
+        @download_url = data["download_url"]
+        @filename = data["filename"]
+        @height = parse_integer(data["height"])
+        @id = parse_integer(data["id"])
+        @preview_url = data["preview_url"]
+        @previewable = parse_boolean(data["previewable"])
+        @sgid = data["sgid"]
+        @thumbnail_url = data["thumbnail_url"]
+        @title = data["title"]
+        @url = data["url"]
+        @width = parse_integer(data["width"])
+      end
+
+      def to_h
+        {
+          "byte_size" => @byte_size,
+          "content_type" => @content_type,
+          "download_url" => @download_url,
+          "filename" => @filename,
+          "height" => @height,
+          "id" => @id,
+          "preview_url" => @preview_url,
+          "previewable" => @previewable,
+          "sgid" => @sgid,
+          "thumbnail_url" => @thumbnail_url,
+          "title" => @title,
+          "url" => @url,
+          "width" => @width,
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
     # SearchType
     class SearchType
       include TypeHelpers
@@ -4188,6 +4293,99 @@ module Basecamp
       end
     end
 
+    # TemplateLibrary
+    class TemplateLibrary
+      include TypeHelpers
+      attr_accessor :bucket, :todolists, :todoset
+
+      # @return [Array<Symbol>]
+      def self.required_fields
+        %i[bucket todolists todoset].freeze
+      end
+
+      def initialize(data = {})
+        @bucket = parse_type(data["bucket"], "RecordingBucket")
+        @todolists = parse_array(data["todolists"], "Todolist")
+        @todoset = parse_type(data["todoset"], "RecordingParent")
+      end
+
+      def to_h
+        {
+          "bucket" => @bucket,
+          "todolists" => @todolists,
+          "todoset" => @todoset,
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
+    # TemplateLibraryConfirmationPerson
+    class TemplateLibraryConfirmationPerson
+      include TypeHelpers
+      attr_accessor :avatar_url, :id, :name
+
+      # @return [Array<Symbol>]
+      def self.required_fields
+        %i[avatar_url id name].freeze
+      end
+
+      def initialize(data = {})
+        @avatar_url = data["avatar_url"]
+        @id = parse_integer(data["id"])
+        @name = data["name"]
+      end
+
+      def to_h
+        {
+          "avatar_url" => @avatar_url,
+          "id" => @id,
+          "name" => @name,
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
+    # TemplateLibraryCopy
+    class TemplateLibraryCopy
+      include TypeHelpers
+      attr_accessor :destination_parent_id, :id, :source_recording_id, :status, :url, :destination_todolist
+
+      # @return [Array<Symbol>]
+      def self.required_fields
+        %i[destination_parent_id id source_recording_id status url].freeze
+      end
+
+      def initialize(data = {})
+        @destination_parent_id = parse_integer(data["destination_parent_id"])
+        @id = parse_integer(data["id"])
+        @source_recording_id = parse_integer(data["source_recording_id"])
+        @status = data["status"]
+        @url = data["url"]
+        @destination_todolist = parse_type(data["destination_todolist"], "Todolist")
+      end
+
+      def to_h
+        {
+          "destination_parent_id" => @destination_parent_id,
+          "id" => @id,
+          "source_recording_id" => @source_recording_id,
+          "status" => @status,
+          "url" => @url,
+          "destination_todolist" => @destination_todolist,
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
     # TimelineAttachment
     class TimelineAttachment
       include TypeHelpers
@@ -4722,39 +4920,53 @@ module Basecamp
     # Tool
     class Tool
       include TypeHelpers
-      attr_accessor :created_at, :enabled, :id, :name, :title, :updated_at, :app_url, :bucket, :position, :status, :url
+      attr_accessor :created_at, :creator, :id, :inherits_status, :title, :type, :updated_at, :visible_to_clients, :app_url, :bookmark_url, :bucket, :enabled, :name, :parent, :position, :status, :subscription_url, :url
 
       # @return [Array<Symbol>]
       def self.required_fields
-        %i[created_at enabled id name title updated_at].freeze
+        %i[created_at creator id inherits_status title type updated_at visible_to_clients].freeze
       end
 
       def initialize(data = {})
         @created_at = parse_datetime(data["created_at"])
-        @enabled = parse_boolean(data["enabled"])
+        @creator = parse_type(data["creator"], "Person")
         @id = parse_integer(data["id"])
-        @name = data["name"]
+        @inherits_status = parse_boolean(data["inherits_status"])
         @title = data["title"]
+        @type = data["type"]
         @updated_at = parse_datetime(data["updated_at"])
+        @visible_to_clients = parse_boolean(data["visible_to_clients"])
         @app_url = data["app_url"]
+        @bookmark_url = data["bookmark_url"]
         @bucket = parse_type(data["bucket"], "RecordingBucket")
+        @enabled = parse_boolean(data["enabled"])
+        @name = data["name"]
+        @parent = parse_type(data["parent"], "RecordingParent")
         @position = parse_integer(data["position"])
         @status = data["status"]
+        @subscription_url = data["subscription_url"]
         @url = data["url"]
       end
 
       def to_h
         {
           "created_at" => @created_at,
-          "enabled" => @enabled,
+          "creator" => @creator,
           "id" => @id,
-          "name" => @name,
+          "inherits_status" => @inherits_status,
           "title" => @title,
+          "type" => @type,
           "updated_at" => @updated_at,
+          "visible_to_clients" => @visible_to_clients,
           "app_url" => @app_url,
+          "bookmark_url" => @bookmark_url,
           "bucket" => @bucket,
+          "enabled" => @enabled,
+          "name" => @name,
+          "parent" => @parent,
           "position" => @position,
           "status" => @status,
+          "subscription_url" => @subscription_url,
           "url" => @url,
         }.compact
       end

data/lib/basecamp/http.rb

@@ -176,7 +176,11 @@ module Basecamp
     # @param url [String] absolute URL
     # @return [Response]
     def get_download(url)
-      request_with_retry(:get, url, retry_on: DOWNLOAD_RETRY_ON, accept: nil)
+      # download: true projects this flow's hooks and transport errors (SPEC
+      # §9): the caller's URL can smuggle a signed query through the rewrite
+      # into hop 1, and a transport error renders the URL it failed on. The
+      # wire request keeps the query; only the renderings are projected.
+      request_with_retry(:get, url, retry_on: DOWNLOAD_RETRY_ON, accept: nil, download: true)
     end
 
     # Fetches all pages of a paginated resource.
@@ -342,7 +346,16 @@ module Basecamp
       Http.normalize_person_ids(data)
       data
     rescue JSON::ParserError => e
-      raise Basecamp::ApiError.new("Failed to parse paginated response (page #{page}): #{Security.truncate(e.message)}")
+      # +cause+ carries the parser's own error, not just its message (#750). The
+      # message says what happened; the slot is what a caller can act on, and it
+      # is the same answer Go reaches through errors.As and Kotlin and Swift
+      # through their decodeFailure slot. Passed explicitly rather than left to
+      # Ruby's implicit +$!+ chaining because Basecamp::Error defines its own
+      # +cause+ reader.
+      raise Basecamp::ApiError.new(
+        "Failed to parse paginated response (page #{page}): #{Security.truncate(e.message)}",
+        cause: e
+      )
     end
 
     # Extracts the item array from a parsed page body: the body itself for
@@ -387,7 +400,7 @@ module Basecamp
     end
 
     def request_with_retry(method, url, params: {}, allow_cross_origin: false, operation: nil, retry_on: nil,
-      accept: "application/json")
+      accept: "application/json", download: false)
       op_retry = operation && Http.operation_retry(operation)
       # The cap is floored at one attempt on every path: whether a request
       # reaches the wire at all must not depend on whether the operation
@@ -413,7 +426,7 @@ module Basecamp
 
         begin
           return single_request(method, url, params: params, body: nil, attempt: attempt,
-            allow_cross_origin: allow_cross_origin, accept: accept, refresh_replay: false)
+            allow_cross_origin: allow_cross_origin, accept: accept, refresh_replay: false, download: download)
         rescue Basecamp::AuthError => e
           # SPEC §4: the refresh replay is a request on the wire, so it spends
           # an attempt from THIS budget rather than an uncounted one inside
@@ -465,8 +478,9 @@ module Basecamp
 
           delay = calculate_delay(attempt, error.retry_after)
 
-          @hooks.on_retry(RequestInfo.new(method: method.to_s.upcase, url: url, attempt: attempt), attempt + 1, error,
-                          delay)
+          hook_url = download ? Security.display_url(url) : url
+          @hooks.on_retry(RequestInfo.new(method: method.to_s.upcase, url: hook_url, attempt: attempt),
+                          attempt + 1, error, delay)
           sleep(delay)
         end
       end
@@ -493,21 +507,28 @@ module Basecamp
     # Memoized per-operation retry metadata, keyed by canonical operation ID.
     # Benign-race memoization: concurrent first loads compute identical values.
     def self.operation_retry(operation)
+      # UTF-8 regardless of process locale — JSON is UTF-8 (RFC 8259), and
+      # LC_ALL=C would otherwise read as US-ASCII.
       @operation_metadata ||= JSON.parse(
-        File.read(File.join(__dir__, "generated", "metadata.json"))
+        File.read(File.join(__dir__, "generated", "metadata.json"), encoding: "UTF-8")
       ).fetch("operations").freeze
       @operation_metadata.dig(operation, "retry")
     end
 
     def single_request(method, url, params:, body:, attempt:, retry_count: 0, allow_cross_origin: false,
-      accept: "application/json", refresh_replay: true)
+      accept: "application/json", refresh_replay: true, download: false)
       assert_credential_origin!(url, allow_cross_origin)
-      info = RequestInfo.new(method: method.to_s.upcase, url: url, attempt: attempt)
+      # download: the SPEC §9 projection for a URL whose query can carry a
+      # credential (download hop 1) — hooks see origin+path, and a transport
+      # error is severed below; the wire request keeps url.
+      info = RequestInfo.new(method: method.to_s.upcase, url: download ? Security.display_url(url) : url,
+                             attempt: attempt)
       @hooks.on_request_start(info)
 
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
-      begin
+      severed = nil
+      result = begin
         response = @faraday.run_request(method, url, body, request_headers(accept: accept)) do |req|
           req.params.merge!(params) if params.any?
         end
@@ -540,17 +561,29 @@ module Basecamp
             && @token_refreshed
           @token_refreshed = false
           return single_request(method, url, params: params, body: body, attempt: attempt, retry_count: retry_count + 1,
-            allow_cross_origin: allow_cross_origin, accept: accept, refresh_replay: refresh_replay)
+            allow_cross_origin: allow_cross_origin, accept: accept, refresh_replay: refresh_replay, download: download)
         end
 
-        raise error
+        # On a download, a status error is raised below the rescue too: the
+        # Faraday exception retains the request (SPEC §9), and raising here
+        # would make it MRI's implicit cause.
+        raise error unless download
+
+        severed = error
       rescue Faraday::Error => e
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        error = Basecamp::NetworkError.new("Connection failed", cause: e)
-        result = RequestResult.new(duration: duration, error: error)
-        @hooks.on_request_end(info, result)
-        raise error
+        # SPEC §9: on a download hop 1 the Faraday error can render the URL it
+        # failed on, so it is neither the cause nor the hint, and it is raised
+        # below — outside this rescue, with cause: nil — so MRI's implicit
+        # cause is severed too. Every other request keeps its diagnostic.
+        error = download ? Basecamp::NetworkError.new : Basecamp::NetworkError.new("Connection failed", cause: e)
+        @hooks.on_request_end(info, RequestResult.new(duration: duration, error: error))
+        raise error unless download
+
+        severed = error
       end
+
+      severed ? raise(severed, cause: nil) : result
     end
 
     # accept: nil is the binary-download carve-out (SPEC §14): hop 1 sends
@@ -613,38 +646,48 @@ module Basecamp
 
       retry_after = parse_retry_after(headers["Retry-After"] || headers["retry-after"])
       request_id = headers["X-Request-Id"] || headers["x-request-id"]
+      # SPEC §6 step 3: a body's error_description becomes the hint. Class
+      # defaults (AuthError, ForbiddenError) still apply when the body has none.
+      hint = Basecamp.parse_error_hint(body)
 
       err = case status
       when 401
         # Try token refresh; flag for caller to retry
         @token_refreshed = refresh_on_401 && @token_provider&.refreshable? && @token_provider.refresh
-        Basecamp::AuthError.new("Authentication failed")
+        Basecamp::AuthError.new("Authentication failed", hint: hint)
       when 403
-        Basecamp::ForbiddenError.new("Access denied")
+        Basecamp::ForbiddenError.new("Access denied", hint: hint)
       when 404
         message = Security.truncate(Basecamp.parse_error_message(body) || "Not found")
-        Basecamp::NotFoundError.new(message: message)
+        Basecamp::NotFoundError.new(message: message, hint: hint)
       when 429
-        Basecamp::RateLimitError.new(retry_after: retry_after)
+        Basecamp::RateLimitError.new(retry_after: retry_after, hint: hint)
       when 400, 422
         field_errors = Basecamp.parse_field_errors(body)
         message = Security.truncate(
           Basecamp.compose_validation_message(Basecamp.parse_error_message(body), field_errors) || "Validation failed"
         )
-        Basecamp::ValidationError.new(message, http_status: status, field_errors: field_errors)
+        people = status == 422 ? Basecamp.parse_template_library_confirmation_people(body) : nil
+        if people
+          Basecamp::PeopleConfirmationRequiredError.new(
+            message, people: people, hint: hint, http_status: status, field_errors: field_errors
+          )
+        else
+          Basecamp::ValidationError.new(message, hint: hint, http_status: status, field_errors: field_errors)
+        end
       when 507
         # A 5xx status carrying a client fact: the account is out of storage, or
         # at its webhook ceiling. Retrying cannot satisfy it, so this is decided
         # before the 5xx arms below.
         message = Security.truncate(Basecamp.parse_error_message(body) || "Account limit reached")
-        Basecamp::LimitExceededError.new(message)
+        Basecamp::LimitExceededError.new(message, hint: hint)
       when 500
-        Basecamp::ApiError.new("Server error (500)", http_status: 500, retryable: true)
+        Basecamp::ApiError.new("Server error (500)", http_status: 500, retryable: true, hint: hint)
       when 502, 503, 504
-        Basecamp::ApiError.new("Gateway error (#{status})", http_status: status, retryable: true)
+        Basecamp::ApiError.new("Gateway error (#{status})", http_status: status, retryable: true, hint: hint)
       else
         message = Security.truncate(Basecamp.parse_error_message(body) || "Request failed (HTTP #{status})")
-        Basecamp::ApiError.from_status(status || 0, message)
+        Basecamp::ApiError.from_status(status || 0, message, hint: hint)
       end
 
       err.instance_variable_set(:@request_id, request_id) if request_id
@@ -785,6 +828,32 @@ module Basecamp
     end
 
     def parse_next_link(link_header)
+      # A non-ASCII-compatible tag (UTF-16/32; only a stub or custom adapter
+      # produces one — Faraday's Net::HTTP adapter always yields ASCII-8BIT)
+      # defeats the byte scan below: "<" is 3C 00 in UTF-16LE, so the ASCII
+      # literals never match and a genuinely UTF-16LE header parsed to nil
+      # silently, where the pre-#678 character path at least crashed loudly.
+      # Transcoding to UTF-8 up front restores parsing for that case, and
+      # rebinding the local means the retag at the bottom hands back UTF-8.
+      #
+      # ASCII bytes MIStagged UTF-16LE split by bytesize parity, and both
+      # outcomes are deliberate:
+      #   - odd (the natural case): invalid UTF-16LE, encode raises, and the
+      #     fallthrough keeps today's refusal — the scan extracts the URL
+      #     still mistagged, and Security.same_origin? refuses the follow
+      #     (ApiError), so no origin-check bypass opens up.
+      #   - even: valid UTF-16LE by construction, transcodes to CJK mojibake
+      #     with no rel="next", parses to nil (was: the ApiError above).
+      #     Garbage-tagged garbage; nil is as good a refusal as a raise.
+      unless link_header.nil? || link_header.encoding.ascii_compatible?
+        begin
+          link_header = link_header.encode(Encoding::UTF_8)
+        rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError,
+               Encoding::ConverterNotFoundError
+          # Not decodable under its claimed encoding — scan the raw bytes.
+        end
+      end
+
       next_url = nil
 
       unless link_header.nil? || link_header.empty?