typesafe-sdk-ruby 0.6.0.1 → 0.7.0

data/lib/typesafe/sdk/assets.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "securerandom"
+
+module Typesafe
+  module SDK
+    # A PNG or JPEG image asset, created by {SDK.image} or {Image.from_base64}.
+    #
+    # Place it in `state`, question instructions, or criteria, join it into text with
+    # {SDK.with_assets}, or pass it in `assets:` under a name of your choice.
+    class Image
+      # The file signatures that PNG (PNG spec §5.2) and JPEG (ITU T.81 SOI marker) files start
+      # with, and the content type each identifies.
+      CONTENT_TYPES = [
+        ["image/png", "\x89PNG\r\n\x1A\n".b],
+        ["image/jpeg", "\xFF\xD8\xFF".b]
+      ].freeze
+
+      # The asset type sent to the API.
+      def type
+        "image"
+      end
+
+      # The frozen binary file bytes, or a `Pathname` read when the request is sent.
+      attr_reader :data
+
+      # @param data [String, Pathname, #read] file bytes, a path to read when the request is
+      #   sent, or an IO read now.
+      # @raise [TypeSafeError] `data` is empty, unreadable, or not a supported type.
+      def initialize(data)
+        @data = coerce(data)
+        size = @data.is_a?(Pathname) ? file_size(@data) : @data.bytesize
+        raise TypeSafeError, "Image data is empty." if size.zero?
+
+        @reference = "<image:#{SecureRandom.hex(16)}>".freeze
+      end
+
+      # Create an image from base64-encoded file bytes, decoding them now.
+      #
+      # @param text [String] the file bytes, base64-encoded, without a `data:` URL prefix.
+      #   ASCII whitespace and missing padding are accepted, as by JavaScript's `atob`.
+      # @raise [TypeSafeError] `text` isn't valid base64 or decodes to no bytes.
+      def self.from_base64(text)
+        raise TypeSafeError, "Image data must contain valid base64 text." unless text.is_a?(String)
+
+        # The forgiving-base64 decode that `atob` uses (WHATWG Infra Standard).
+        compact = text.b.delete(" \t\n\f\r")
+        compact = compact.sub(/={1,2}\z/, "") if (compact.length % 4).zero?
+        unless compact.match?(%r{\A[A-Za-z0-9+/]*\z}) && compact.length % 4 != 1
+          raise TypeSafeError, "Image data must contain valid base64 text."
+        end
+
+        new("#{compact}#{'=' * (-compact.length % 4)}".unpack1("m"))
+      end
+
+      # The bytes to send, reading `Pathname` data.
+      # @param name [String] the asset's name or reference, for error messages.
+      def read(name)
+        return @data unless @data.is_a?(Pathname)
+
+        File.binread(@data).freeze
+      rescue SystemCallError, IOError => e
+        raise TypeSafeError.new("Asset #{name.inspect} could not be read: #{e.message}", cause: e)
+      end
+
+      # The unique reference this image is sent under, for referencing it inside text.
+      def to_s
+        @reference
+      end
+
+      # The reference, written wherever the image appears in JSON.
+      def to_json(*args)
+        @reference.to_json(*args)
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} #{@reference}>"
+      end
+
+      # The content type whose signature `bytes` start with, or `application/octet-stream`.
+      def self.content_type_of(bytes)
+        CONTENT_TYPES.each { |type, signature| return type if bytes.b.start_with?(signature) }
+        "application/octet-stream"
+      end
+
+      private
+
+      def coerce(data)
+        case data
+        when String then data.b.freeze
+        when Pathname then data
+        else
+          unless data.respond_to?(:read)
+            raise TypeSafeError,
+                  "Image data must be file bytes (a String), a Pathname, or an IO; got #{data.class}."
+          end
+
+          bytes = data.read
+          raise TypeSafeError, "Image data read from #{data.class} must be a String." unless bytes.is_a?(String)
+
+          bytes.b.freeze
+        end
+      end
+
+      def file_size(path)
+        File.size(path)
+      rescue SystemCallError => e
+        raise TypeSafeError.new("Image file could not be read: #{e.message}", cause: e)
+      end
+    end
+
+    # Text from {SDK.with_assets} or {SDK.join_assets}, with the assets written into it.
+    class TextWithAssets
+      # The text, with each asset written as its reference.
+      attr_reader :text
+      # The assets written into the text, including those in nested `TextWithAssets`.
+      attr_reader :assets
+
+      def initialize(text, assets)
+        @text = text.dup.freeze
+        @assets = assets.dup.freeze
+      end
+
+      def to_s
+        @text
+      end
+
+      # The text, written wherever this value appears in JSON.
+      def to_json(*args)
+        @text.to_json(*args)
+      end
+
+      def inspect # :nodoc:
+        "#<#{self.class.name} #{@text.inspect}>"
+      end
+
+      # Join `parts` into text, as an interpolated string would, and attach the assets among them.
+      def self.build(*parts)
+        attach(parts.map { |part| stringify(part) }.join, parts)
+      end
+
+      # Join `values` with `separator` and attach the assets among them.
+      def self.join(values, separator = ",")
+        values = values.to_a
+        attach(values.map { |value| stringify(value) }.join(separator.to_s), values)
+      end
+
+      # `text` with the assets in `values` whose references it contains, in order of appearance.
+      def self.attach(text, values)
+        interpolated = {}
+        collect(values, interpolated, {}.compare_by_identity)
+        assets = {}
+        text.scan(Assets::REFERENCE) do |reference|
+          asset = interpolated[reference]
+          assets[reference] = asset if asset
+        end
+        new(text, assets.values)
+      end
+
+      def self.stringify(value)
+        value.is_a?(TextWithAssets) ? value.text : value.to_s
+      end
+
+      # Add the images in `value`, including those in `TextWithAssets`, to `found` by reference.
+      def self.collect(value, found, visited)
+        case value
+        when Image then found[value.to_s] = value
+        when TextWithAssets then value.assets.each { |asset| found[asset.to_s] = asset }
+        when Hash, Array
+          return if visited.key?(value)
+
+          visited[value] = true
+          (value.is_a?(Hash) ? value.values : value).each { |item| collect(item, found, visited) }
+        end
+      end
+    end
+
+    # A `multipart/form-data` request body (RFC 7578) whose first part is a JSON payload.
+    class MultipartBody
+      # The JSON payload, sent as the `request` part.
+      attr_reader :payload
+      # The `Content-Type` header value, including the boundary.
+      attr_reader :content_type
+      # The encoded binary body.
+      attr_reader :content
+
+      # @param parts [Array<Hash>] `name`, `content_type`, `content`, and optional `filename`.
+      def initialize(payload, parts)
+        # A random boundary, as browsers use, is practically certain not to occur in the content.
+        boundary = SecureRandom.hex(16)
+        content = String.new(encoding: Encoding::BINARY)
+        [{ name: "request", content_type: "application/json", content: JSON.generate(payload) }, *parts]
+          .each do |part|
+          disposition = %(name="#{part[:name]}")
+          disposition += %(; filename="#{part[:filename]}") if part[:filename]
+          content << "--#{boundary}\r\nContent-Disposition: form-data; #{disposition}\r\n" \
+                     "Content-Type: #{part[:content_type]}\r\n\r\n".b << part[:content].b << "\r\n"
+        end
+        content << "--#{boundary}--\r\n"
+        @payload = payload
+        @content_type = "multipart/form-data; boundary=#{boundary}"
+        @content = content.freeze
+      end
+    end
+
+    # Request serialization and `multipart/form-data` encoding for assets.
+    module Assets
+      # Matches `Image#to_s`: the reference an image is sent under.
+      REFERENCE = /<image:[0-9a-f]{32}>/
+
+      module_function
+
+      # Validate `assets:` and return it with string names, preserving order.
+      def normalize(assets)
+        return {} if assets.nil?
+        raise TypeSafeError, "`assets` must be a Hash of names to images." unless assets.is_a?(Hash)
+
+        assets.each_with_object({}) do |(name, asset), normalized|
+          key = name.to_s
+          raise TypeSafeError, "Asset names must be nonempty." if key.empty?
+          unless asset.is_a?(Image)
+            raise TypeSafeError,
+                  "Asset #{key.inspect} must be an image created with Typesafe::SDK.image, got #{asset.class}."
+          end
+
+          normalized[key] = asset
+        end
+      end
+
+      # Serialize `payload` to JSON, writing each image as its name in `assets`, or else as its
+      # reference, and collect the assets the request sends.
+      #
+      # The assets are those in `assets`, then each image whose reference appears in the JSON, in
+      # order of appearance. Non-finite floats are sent as the strings `NaN`, `Infinity`, and
+      # `-Infinity`, as the JavaScript SDK does.
+      #
+      # @return [Array(String, Hash{String => Image}, nil)] the JSON and the assets to send.
+      # @raise [TypeSafeError] the payload holds a cycle, a reference of an image not attached to
+      #   the request, or doesn't contain the name of an image in `assets`.
+      def serialize_request(payload, assets = {})
+        # An image under several names is written as the last one.
+        names = {}.compare_by_identity
+        assets.each { |name, asset| names[asset] = name }
+        known = assets.values.to_h { |asset| [asset.to_s, asset] }
+        json = JSON.generate(prepare(payload, names, known, {}.compare_by_identity))
+
+        unreferenced = assets.keys.reject { |name| json.include?(JSON.generate(name)[1..-2]) }
+        unless unreferenced.empty?
+          raise TypeSafeError,
+                "Assets not referenced in the request: #{unreferenced.join(', ')}. " \
+                "Write each name in `assets` into `state`, question instructions, or criteria."
+        end
+
+        sent = assets.dup
+        missing = []
+        json.scan(REFERENCE) do |reference|
+          next if sent.key?(reference)
+
+          asset = known[reference]
+          asset ? sent[reference] = asset : missing << reference
+        end
+        unless missing.empty?
+          raise TypeSafeError,
+                "Image references without an attached image: #{missing.uniq.join(', ')}. " \
+                "Join images into text with Typesafe::SDK.with_assets instead of string interpolation."
+        end
+
+        [json, sent.empty? ? nil : sent]
+      end
+
+      # A JSON-ready copy of `value` with assets written as names or references.
+      def prepare(value, names, known, path)
+        case value
+        when Image
+          name = names[value]
+          return name if name
+
+          known[value.to_s] = value
+          value.to_s
+        when TextWithAssets
+          value.assets.reduce(value.text) do |text, asset|
+            name = names[asset]
+            known[asset.to_s] = asset unless name
+            name ? text.gsub(asset.to_s) { name } : text
+          end
+        when Float
+          value.finite? ? value : value.to_s
+        when Hash, Array
+          raise TypeSafeError, "The request contains a circular reference." if path.key?(value)
+
+          path[value] = true
+          begin
+            if value.is_a?(Hash)
+              value.to_h { |key, item| [key.to_s, prepare(item, names, known, path)] }
+            else
+              value.map { |item| prepare(item, names, known, path) }
+            end
+          ensure
+            path.delete(value)
+          end
+        else
+          value
+        end
+      end
+
+      # A multipart body whose `request` part is `payload` with `assets` added, followed by each
+      # asset's file bytes in its own part. The API accepts each part for only one asset, so an
+      # image under several references is sent once per reference.
+      #
+      # @raise [TypeSafeError] a `Pathname` image can't be read.
+      def encode(payload, assets)
+        parts = []
+        entries = {}
+        assets.each do |name, asset|
+          bytes = asset.read(name)
+          part = "asset-#{parts.length}"
+          parts << { name: part, content_type: Image.content_type_of(bytes), content: bytes, filename: part }
+          entries[name] = { "type" => asset.type, "part" => part }
+        end
+        MultipartBody.new(payload.merge("assets" => entries), parts)
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/client.rb

@@ -15,7 +15,7 @@ module Typesafe
     # Client for the TypeSafe AI API.
     class Client
       attr_reader :base_url, :default_model, :log_level, :logger, :retry, :timeout,
-                  :default_headers, :models
+                  :default_headers, :compression, :models
 
       # Create a client for the TypeSafe AI API.
       #
@@ -30,11 +30,15 @@ module Typesafe
       # @param retry_policy [Hash, nil] overrides for {Retry::DEFAULT_RETRY_POLICY}.
       # @param timeout [Float, nil] timeout per attempt in seconds. Default: 10.
       # @param default_headers [Hash, nil] additional request headers.
+      # @param compression [Symbol, false, nil] request body compression, sent as `Content-Encoding`.
+      #   Default: `:zstd` when the optional `zstd-ruby` gem can be loaded, otherwise `false`.
+      #   Bodies under 1 KiB are always sent uncompressed.
       # @param http [Object] HTTP adapter responding to `request`. Default: {HTTP}.
-      # @raise [TypeSafeError] the API key is missing or configuration is invalid.
+      # @raise [TypeSafeError] the API key is missing, configuration is invalid, or zstd
+      #   compression is requested without the `zstd-ruby` gem.
       def initialize(api_key: nil, base_url: nil, default_model: nil, log_level: nil,
                      logger: nil, retry_policy: nil, timeout: nil, default_headers: nil,
-                     http: nil, env: ::ENV)
+                     compression: nil, http: nil, env: ::ENV)
         @api_key = validate_api_key(api_key.nil? ? env[ENV::API_KEY] : api_key)
 
         @base_url = strip_trailing_slashes(
@@ -48,21 +52,30 @@ module Typesafe
         @retry = resolve_retry_policy(Retry::DEFAULT_RETRY_POLICY, retry_policy)
         @timeout = assert_positive("timeout", timeout || Retry::DEFAULT_TIMEOUT_S)
         @default_headers = (default_headers || {}).dup.freeze
+        @compression = Compression.resolve(compression)
         @http = http || HTTP.new
         @models = Resources::Models.new(self)
         @request_count = 0
       end
 
-      # Answer named questions about text or structured state.
+      # Answer named questions about text, structured state, or images.
       #
-      # @param state [String, Hash, Array] the content to evaluate.
+      # Images in `state`, question content, or {SDK.with_assets} text are sent under their
+      # references; requests with images are sent as `multipart/form-data`.
+      #
+      # @param state [String, Hash, Array, Image, TextWithAssets] the content to evaluate.
       # @param questions [Hash{Symbol, String => Hash}] nonempty questions keyed by name.
       # @param model [String, nil] model override; omitted values inherit `default_model`.
+      # @param assets [Hash{String => Image}, nil] images keyed by names of your choice, matched
+      #   literally in strings within `state`, question instructions, or criteria. Every name must
+      #   appear in the request.
       # @param extra_body [Hash] additional JSON fields; named request arguments take precedence.
       # @param with_response [Boolean] return data with HTTP metadata and request ID.
       # @param options [Hash] per-call `timeout`, `retry_policy`, `headers`, and `signal` settings.
       # @return [SystemOneResult, WithResponse] answers keyed by question name, with model and token usage.
-      # @raise [TypeSafeError] state or questions violate the locally checked API constraints.
+      # @raise [TypeSafeError] state or questions violate the locally checked API constraints,
+      #   the request holds a cycle, a string holds the reference of an image not attached to the
+      #   request, a name in `assets` doesn't appear in the request, or an image can't be read.
       # @raise [APIError] the server returns a non-2xx response after retries.
       # @raise [APIConnectionError] the request cannot connect or times out after retries.
       # @raise [APIUserAbortError] the caller cancels the request.
@@ -73,12 +86,18 @@ module Typesafe
       #     questions: { billing: Typesafe::SDK.noul("Is this about billing?") },
       #   )
       #   response[:billing].noul # => 0.93
-      def system_one(state:, questions:, model: nil, extra_body: {}, with_response: false, **options)
+      def system_one(state:, questions:, model: nil, assets: nil, extra_body: {}, with_response: false,
+                     **options)
         Questions.validate_state!(state)
         Questions.validate!(questions)
-        body = extra_body.transform_keys(&:to_s).merge(
+        named = Assets.normalize(assets)
+        request_body = extra_body.transform_keys(&:to_s).merge(
           "state" => state, "questions" => questions, "model" => model || @default_model
         )
+        # Serialized now, so changes to the request after this call don't change what is sent.
+        json, sent = Assets.serialize_request(request_body, named)
+        payload = JSON.parse(json)
+        body = sent.nil? ? payload : -> { Assets.encode(payload, sent) }
         response = request(:post, "/v1/systemone", body: body, **options)
         result = SystemOneResult.new(response.body)
         with_response ? WithResponse.new(result, response) : result
@@ -86,6 +105,9 @@ module Typesafe
 
       # Send a request and parse its response body. Internal; used by API resources.
       #
+      # `body` is a JSON-ready object, or a callable returning one or an {MultipartBody},
+      # called once before the first attempt.
+      #
       # @return [Response] the parsed response, with `body`, `status`, `headers`, and `request_id`.
       def request(method, path, body: nil, headers: {}, timeout: nil, retry_policy: nil,
                   signal: nil)
@@ -251,27 +273,29 @@ module Typesafe
       # Retry eligible failures, logging attempt summaries at `info` and details at `debug`.
       def fetch_with_retries(tag, req)
         url = "#{@base_url}#{req[:path]}"
-        # User-supplied headers go first so they can't clobber auth or the JSON content type.
+        multipart, payload, encoded, encoding, body = prepare_body(tag, req)
+        # User-supplied headers go first so they can't clobber auth, the content type, or the encoding.
         headers = merge_headers(req[:headers], {
                                   "Authorization" => "Bearer #{@api_key}",
                                   "Accept" => "application/json",
                                   "User-Agent" => "typesafe-sdk-ruby/#{VERSION}",
                                   "X-TypeSafe-SDK" => "typesafe-sdk-ruby/#{VERSION}",
                                   "X-TypeSafe-Runtime" => "ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})",
-                                  "Content-Type" => req[:body].nil? ? nil : "application/json",
+                                  "Content-Type" => multipart&.content_type ||
+                                                    (encoded.nil? ? nil : "application/json"),
+                                  "Content-Encoding" => (encoding.to_s if encoding),
                                   "X-TypeSafe-Retry-Count" => nil
                                 })
-        payload = req[:body].nil? ? nil : JSON.generate(req[:body])
 
         attempt = 0
         loop do
           retries_left = req[:retry][:max_retries] - attempt
           attempt_headers = attempt.zero? ? headers : headers.merge("X-TypeSafe-Retry-Count" => attempt.to_s)
-          @logger.debug("#{tag} -> #{url}", headers: Redaction.redact_headers(attempt_headers), body: req[:body])
+          @logger.debug("#{tag} -> #{url}", headers: Redaction.redact_headers(attempt_headers), body: payload)
 
           started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           begin
-            response = attempt_request(tag, url, req[:method], attempt_headers, payload, req)
+            response = attempt_request(tag, url, req[:method], attempt_headers, body, req)
           rescue APIUserAbortError
             raise
           rescue APIConnectionError => e
@@ -296,6 +320,26 @@ module Typesafe
         end
       end
 
+      # Resolve, encode, and compress the body once; every attempt sends the same bytes.
+      # The logs show the uncompressed payload.
+      def prepare_body(tag, req)
+        resolved = req[:body]
+        if resolved.respond_to?(:call)
+          req[:signal]&.check!
+          resolved = resolved.call
+          if req[:signal]&.canceled?
+            @logger.info("#{tag} aborted by caller while reading assets")
+            raise APIUserAbortError
+          end
+        end
+        multipart = resolved.is_a?(MultipartBody) ? resolved : nil
+        payload = multipart ? multipart.payload : resolved
+        encoded = multipart&.content || (payload.nil? ? nil : JSON.generate(payload))
+        encoding = encoded && encoded.bytesize >= Compression::MIN_COMPRESSED_BODY_BYTES ? @compression : false
+        body = encoding ? Compression.compress(encoded) : encoded
+        [multipart, payload, encoded, encoding, body]
+      end
+
       def retryable_connection_error?(error, policy)
         return policy[:api_timeout_error] if error.is_a?(APITimeoutError)
 

data/lib/typesafe/sdk/compression.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Typesafe
+  module SDK
+    # Request body compression with zstd, provided by the optional `zstd-ruby` gem.
+    module Compression
+      # Bodies below this many bytes fit in a single TCP segment, so they are sent uncompressed.
+      MIN_COMPRESSED_BODY_BYTES = 1024
+
+      module_function
+
+      # Whether the `zstd-ruby` gem can be loaded. Checked once per process.
+      def available?
+        return @available unless @available.nil?
+
+        @available = begin
+          require "zstd-ruby"
+          true
+        rescue LoadError
+          false
+        end
+      end
+
+      # Resolve the `compression:` option to the `Content-Encoding` request bodies are sent with:
+      # `:zstd` when the runtime has it, otherwise `false`.
+      #
+      # @raise [TypeSafeError] the value isn't a supported option, or zstd is unavailable.
+      def resolve(compression)
+        return available? ? :zstd : false if compression.nil?
+        return false if compression == false
+
+        unless [:zstd, "zstd"].include?(compression)
+          raise TypeSafeError, "`compression` must be :zstd or false, got #{compression.inspect}."
+        end
+        unless available?
+          raise TypeSafeError,
+                "zstd compression requires the zstd-ruby gem. Add it to your Gemfile or pass " \
+                "`compression: false` instead."
+        end
+
+        :zstd
+      end
+
+      # Compress a request body with zstd.
+      def compress(body)
+        Zstd.compress(body).b
+      end
+    end
+  end
+end

data/lib/typesafe/sdk/errors.rb

@@ -26,14 +26,17 @@ module Typesafe
       attr_reader :request_id
 
       def initialize(status, body, headers, message = nil)
-        super(message || APIError.describe(status, body))
+        super(message || APIError.describe(status, body, headers))
         @status = status
         @body = body
         @headers = headers
         @request_id = headers[Typesafe::SDK::REQUEST_ID_HEADER]
       end
 
-      def self.describe(status, body)
+      def self.describe(status, body, headers = nil)
+        edge = describe_edge_block(status, body, headers)
+        return edge if edge
+
         detail = extract_message(body)
         return "#{status} #{detail}" if detail && !detail.empty?
         return "#{status} status code (no body)" if body.nil?
@@ -81,6 +84,20 @@ module Typesafe
         nil
       end
 
+      # Describe an HTML page from Cloudflare, which answers before the request reaches the API,
+      # for example when its firewall matches text such as shell commands in the request.
+      def self.describe_edge_block(status, body, headers)
+        return nil unless headers && body.is_a?(String) && body.match?(/\A\s*<(?:!doctype|html)/i)
+
+        ray = headers["cf-ray"]
+        return nil unless ray || headers["server"].to_s.match?(/cloudflare/i)
+
+        "#{status} The response is a Cloudflare HTML page, not a TypeSafe API error" \
+          "#{" (cf-ray #{ray})" if ray}. An edge firewall may have blocked the request before it " \
+          "reached the API; content such as shell commands in the request can trigger it. " \
+          "Report the ray ID to TypeSafe support if the request is valid."
+      end
+
       # Format validation errors as semicolon-separated `path: message` entries.
       def self.describe_validation_errors(errors)
         parts = errors.filter_map do |e|

data/lib/typesafe/sdk/http.rb

@@ -66,7 +66,8 @@ module Typesafe
       # @param method [Symbol] `:get` or `:post`.
       # @param url [String] absolute URL.
       # @param headers [Hash{String => String}] request headers.
-      # @param body [String, nil] JSON-encoded request body.
+      # @param body [String, nil] encoded request body: JSON, or `multipart/form-data` when the
+      #   request has images, compressed when `Content-Encoding` is set. Send it as-is.
       # @param timeout [Numeric] timeout in seconds.
       # @param signal [Signal, nil] cancellation handle.
       # @return [Response]

data/lib/typesafe/sdk/logging.rb

@@ -76,20 +76,28 @@ module Typesafe
     # Credential headers that retain a key suffix for identification.
     module Redaction
       KEY_HEADERS = %w[authorization proxy-authorization x-api-key].freeze
+      # Headers whose values may start with an authentication scheme such as `Bearer`.
+      SCHEME_HEADERS = %w[authorization proxy-authorization].freeze
       OPAQUE_HEADERS = %w[cookie set-cookie].freeze
+      # An alphabetic scheme followed by a nonempty credential (RFC 9110 §11.4).
+      SCHEMED = /\A([A-Za-z]+)[ \t]+(\S.*)\z/m
 
       module_function
 
-      # Mask a key, preserving its scheme and the last four characters of secrets longer than eight.
-      def redact_key(value)
-        scheme, secret = value.include?(" ") ? value.split(/\s+/, 2) : [nil, value]
-        tail = secret && secret.length > 8 ? secret[-4..] : ""
-        "#{"#{scheme} " if scheme}***#{tail}"
+      # Mask a key, keeping the last four characters of secrets longer than eight. An alphabetic
+      # leading scheme, such as `Bearer`, is kept only when `scheme` is true and a credential
+      # follows it; otherwise the whole value is masked, so a secret is never shown as a scheme.
+      def redact_key(value, scheme: true)
+        value = value.to_s
+        match = scheme ? SCHEMED.match(value) : nil
+        prefix, secret = match ? ["#{match[1]} ", match[2].strip] : ["", value.strip]
+        tail = secret.length > 8 ? secret[-4..] : ""
+        "#{prefix}***#{tail}"
       end
 
       def redact(name, value)
         lower = name.downcase
-        return redact_key(value) if KEY_HEADERS.include?(lower)
+        return redact_key(value, scheme: SCHEME_HEADERS.include?(lower)) if KEY_HEADERS.include?(lower)
         return "***" if OPAQUE_HEADERS.include?(lower)
 
         value

data/lib/typesafe/sdk/questions.rb

@@ -2,7 +2,7 @@
 
 module Typesafe
   module SDK
-    # Builders and validation for the three question types.
+    # Builders and validation for the noul, score, choice, and box question types.
     module Questions
       MAX_SCORE_LEVELS = 10
       MAX_CHOICE_OPTIONS = 255
@@ -10,7 +10,7 @@ module Typesafe
       module_function
 
       # Create a yes/no question. Supply instructions or at least one outcome description.
-      # @param instructions [String, Hash, Array, nil]
+      # @param instructions [String, Hash, Array, Image, TextWithAssets, nil]
       # @param criteria [Hash, nil] optional true/false outcome descriptions.
       def noul(instructions = nil, criteria: nil)
         question = { type: "noul", instructions: instructions, criteria: criteria }
@@ -31,10 +31,19 @@ module Typesafe
         { type: "choice", instructions: instructions, criteria: criteria }
       end
 
+      # Create a question that locates what its instructions describe in the request's image.
+      # Use the `jev-preview` model for box questions.
+      # @param instructions [String, Hash, Array, Image, TextWithAssets, nil] what to locate.
+      def box(instructions = nil)
+        { type: "box", instructions: instructions }
+      end
+
+      STATE_TYPES = [String, Hash, Array, Image, TextWithAssets].freeze
+
       def validate_state!(state)
-        return if state.is_a?(String) || state.is_a?(Hash) || state.is_a?(Array)
+        return if STATE_TYPES.any? { |type| state.is_a?(type) }
 
-        raise TypeSafeError, "`state` must be a string, object, or array; nil is not supported."
+        raise TypeSafeError, "`state` must be a string, object, array, or image; nil is not supported."
       end
 
       # Validate builders and raw JSON-style questions without altering the caller's data.
@@ -55,6 +64,10 @@ module Typesafe
       end
 
       def validate_noul!(instructions, criteria, name)
+        unless criteria.nil? || criteria.is_a?(Hash)
+          raise TypeSafeError, "Noul question #{name.inspect} criteria must be an object."
+        end
+
         descriptions = criteria.is_a?(Hash) ? criteria.transform_keys(&:to_s) : {}
         return unless instructions.nil? && %w[true false].all? { |key| descriptions[key].nil? }