screenshotscout 0.1.0.rc1

data/lib/screenshotscout/client.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module ScreenshotScout
+  # Reusable blocking client for the inline Screenshot Scout capture operation.
+  class Client
+    CAPTURE_ENDPOINT = "https://api.screenshotscout.com/v1/capture"
+    ACCESS_KEY_PATTERN = %r{\A[A-Za-z0-9\-._~+/]+=*\z}
+    MISSING_ACCESS_KEY = Object.new.freeze
+
+    def initialize(access_key: MISSING_ACCESS_KEY, secret_key: nil, transport: nil)
+      validate_access_key(access_key)
+      validate_secret_key(secret_key)
+      validate_transport(transport)
+
+      @access_key = access_key.dup.freeze
+      @secret_key = secret_key&.dup&.freeze
+      @transport = transport || NetHttpTransport.new
+    end
+
+    # Sends one GET or POST request and waits for the final inline response.
+    def capture(url, options = nil, method: CaptureHttpMethod::POST)
+      serialized = Internal::Serializer.serialize(url, options)
+      method = CaptureHttpMethod::POST if method.nil?
+      validate_method(method)
+      expected_kind = expected_response_kind(options)
+      signature = create_signature(serialized.pairs)
+      request = create_request(serialized, method, signature)
+      raw_response = execute_request(request)
+
+      raise create_api_error(raw_response) unless raw_response.status.between?(200, 299)
+
+      decode_success_response(raw_response, expected_kind)
+    end
+
+    # Builds a sensitive GET capture URL without performing network I/O.
+    def build_capture_url(url, options = nil)
+      serialized = Internal::Serializer.serialize(url, options)
+      signature = create_signature(serialized.pairs)
+      pairs = [Internal::WirePair.new(name: "access_key", value: @access_key), *serialized.pairs]
+      pairs << Internal::WirePair.new(name: "signature", value: signature) unless signature.nil?
+      "#{CAPTURE_ENDPOINT}?#{Internal::Serializer.encode_query(pairs)}"
+    end
+
+    private
+
+    def validate_access_key(access_key)
+      unless access_key.is_a?(String) && !access_key.strip.empty?
+        raise ConfigurationError, "A non-blank Screenshot Scout access key is required."
+      end
+      return if ACCESS_KEY_PATTERN.match?(access_key)
+
+      raise ConfigurationError, "The Screenshot Scout access key is not a valid Bearer credential."
+    end
+
+    def validate_secret_key(secret_key)
+      return if secret_key.nil?
+      return if secret_key.is_a?(String) && !secret_key.strip.empty?
+
+      raise ConfigurationError, "The Screenshot Scout secret key must be a non-blank string when provided."
+    end
+
+    def validate_transport(transport)
+      return if transport.nil? || transport.respond_to?(:call)
+
+      raise ConfigurationError, "The Screenshot Scout transport must respond to #call."
+    end
+
+    def validate_method(method)
+      return if [CaptureHttpMethod::GET, CaptureHttpMethod::POST].include?(method)
+
+      raise SerializationError.new(
+        "The capture method must be CaptureHttpMethod::GET or CaptureHttpMethod::POST.",
+        option: :method
+      )
+    end
+
+    def create_signature(pairs)
+      return nil if @secret_key.nil?
+
+      canonical_query = Internal::Serializer.build_canonical_query(pairs, @access_key)
+      OpenSSL::HMAC.hexdigest("SHA256", @secret_key, canonical_query)
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise SerializationError.new("The capture request could not be signed."), cause: e
+    end
+
+    def create_request(serialized, method, signature)
+      headers = { "Authorization" => "Bearer #{@access_key}" }
+      if method == CaptureHttpMethod::GET
+        pairs = serialized.pairs.dup
+        pairs << Internal::WirePair.new(name: "signature", value: signature) unless signature.nil?
+        url = "#{CAPTURE_ENDPOINT}?#{Internal::Serializer.encode_query(pairs)}"
+        TransportRequest.new(method: method, url: url, headers: headers)
+      else
+        body = serialized.body.dup
+        body["signature"] = signature unless signature.nil?
+        headers["Content-Type"] = "application/json"
+        TransportRequest.new(
+          method: method,
+          url: CAPTURE_ENDPOINT,
+          headers: headers,
+          body: Internal::JsonCodec.encode_wire_object(body)
+        )
+      end
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise SerializationError.new("The Screenshot Scout HTTP request could not be constructed."), cause: e
+    end
+
+    def execute_request(request)
+      raw_response = @transport.call(request)
+      return raw_response if raw_response.is_a?(RawResponse)
+
+      raise TypeError, "The Screenshot Scout transport must return ScreenshotScout::RawResponse."
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise TransportError, "Screenshot Scout request failed before a complete HTTP response body was received.",
+            cause: e
+    end
+
+    def expected_response_kind(options)
+      response_type = options&.response_type
+      return :binary if response_type.nil? || response_type == CaptureResponseType::BINARY
+      return :json if response_type == CaptureResponseType::JSON
+
+      nil
+    end
+
+    def decode_success_response(raw_response, expected_kind)
+      actual_kind = json_media_type?(raw_response.content_type) ? :json : :binary
+      if !expected_kind.nil? && actual_kind != expected_kind
+        message = "Screenshot Scout returned a successful #{actual_kind} response " \
+                  "when #{expected_kind} was requested."
+        cause = TypeError.new("Expected a #{expected_kind} response but received #{actual_kind}.")
+        raise ResponseDecodingError.new(message, raw_response), cause: cause
+      end
+
+      actual_kind == :json ? decode_json_response(raw_response) : decode_binary_response(raw_response)
+    end
+
+    def decode_binary_response(raw_response)
+      BinaryCaptureResponse.new(
+        raw_response: raw_response,
+        screenshot_url: raw_response.header("Screenshot-Scout-Screenshot-URL").first,
+        screenshot_url_expires_at: raw_response.header("Screenshot-Scout-Screenshot-URL-Expires-At").first,
+        cache_status: raw_response.header("Screenshot-Scout-Cache-Status").first
+      )
+    end
+
+    def decode_json_response(raw_response)
+      value = parse_json_success(raw_response)
+      unless value.is_a?(Hash)
+        cause = TypeError.new("Expected a JSON object.")
+        raise ResponseDecodingError.new(
+          "Screenshot Scout returned a successful JSON response that was not an object.",
+          raw_response
+        ), cause: cause
+      end
+
+      screenshot_url = read_optional_string(value, "screenshot_url", raw_response)
+      expires_at = read_optional_string(value, "screenshot_url_expires_at", raw_response)
+      cache_status = read_optional_string(value, "cache_status", raw_response)
+      additional_fields = value.except("screenshot_url", "screenshot_url_expires_at", "cache_status")
+      result = CaptureResult.new(
+        screenshot_url: screenshot_url,
+        screenshot_url_expires_at: expires_at,
+        cache_status: cache_status,
+        additional_fields: additional_fields
+      )
+      JsonCaptureResponse.new(result: result, raw_response: raw_response)
+    end
+
+    def parse_json_success(raw_response)
+      Internal::JsonCodec.parse(raw_response.body)
+    rescue JSON::ParserError, EncodingError => e
+      raise ResponseDecodingError.new(
+        "Screenshot Scout returned a successful JSON response that could not be decoded.",
+        raw_response
+      ), cause: e
+    end
+
+    def read_optional_string(object, key, raw_response)
+      return nil unless object.key?(key)
+      return object[key] if object[key].is_a?(String)
+
+      cause = TypeError.new("Expected \"#{key}\" to be a string.")
+      raise ResponseDecodingError.new(
+        "Screenshot Scout returned a non-string \"#{key}\" JSON field.",
+        raw_response
+      ), cause: cause
+    end
+
+    def create_api_error(raw_response)
+      available, response_body = try_parse_json(raw_response.body)
+      object = response_body if response_body.is_a?(Hash)
+      error_code = object["error_code"] if object&.fetch("error_code", nil).is_a?(String)
+      error_message = object["error_message"] if object&.fetch("error_message", nil).is_a?(String)
+      errors = object["errors"] if object&.fetch("errors", nil).is_a?(Array)
+
+      APIError.new(
+        raw_response: raw_response,
+        response_body_available: available,
+        response_body: response_body,
+        error_code: error_code,
+        error_message: error_message,
+        errors: errors
+      )
+    end
+
+    def try_parse_json(body)
+      [true, Internal::JsonCodec.parse(body)]
+    rescue JSON::ParserError, EncodingError
+      [false, nil]
+    end
+
+    def json_media_type?(content_type)
+      return false if content_type.nil?
+
+      media_type = content_type.partition(";").first.strip.downcase
+      media_type == "application/json" || media_type.end_with?("+json")
+    end
+
+    private_constant :CAPTURE_ENDPOINT, :ACCESS_KEY_PATTERN, :MISSING_ACCESS_KEY
+  end
+end

data/lib/screenshotscout/errors.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ScreenshotScout
+  # Base class for every exception raised by the SDK.
+  class Error < StandardError; end
+
+  # Raised when client credentials or capture-call controls are unusable.
+  class ConfigurationError < Error; end
+
+  # Raised when a capture option cannot be represented safely on the wire.
+  class SerializationError < Error
+    attr_reader :option
+
+    def initialize(message, option: nil)
+      super(message)
+      @option = option
+    end
+  end
+
+  # Raised when the configured transport cannot complete an HTTP exchange.
+  class TransportError < Error; end
+
+  # Raised for every non-2xx response returned by the Screenshot Scout API.
+  class APIError < Error
+    attr_reader :status, :error_code, :error_message, :errors, :response_body, :raw_response
+
+    def initialize(
+      raw_response:,
+      response_body_available:,
+      response_body: nil,
+      error_code: nil,
+      error_message: nil,
+      errors: nil
+    )
+      super(error_message || "Screenshot Scout API request failed with status #{raw_response.status}.")
+      @status = raw_response.status
+      @error_code = error_code
+      @error_message = error_message
+      @errors = errors
+      @response_body_available = response_body_available
+      @response_body = response_body
+      @raw_response = raw_response
+    end
+
+    def response_body?
+      @response_body_available
+    end
+  end
+
+  # Raised when a successful response cannot be decoded as its expected type.
+  class ResponseDecodingError < Error
+    attr_reader :raw_response
+
+    def initialize(message, raw_response)
+      super(message)
+      @raw_response = raw_response
+    end
+  end
+end

data/lib/screenshotscout/internal/ecma_script_number_formatter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ScreenshotScout
+  module Internal
+    # Formats IEEE-754 values like JavaScript String(number) and JSON.stringify.
+    module EcmaScriptNumberFormatter
+      module_function
+
+      def format(value)
+        raise ArgumentError, "Expected a finite floating-point value." unless value.finite?
+        return "0" if value.zero?
+
+        encoded = value.to_s.downcase
+        return normalize_decimal(encoded) unless encoded.include?("e")
+
+        match = /\A(-?)([0-9])(?:\.([0-9]+))?e([+-]?[0-9]+)\z/.match(encoded)
+        raise ArgumentError, "Unexpected floating-point encoding." if match.nil?
+
+        negative = match[1] == "-"
+        digits = (match[2] + match[3].to_s).sub(/0+\z/, "")
+        digits = "0" if digits.empty?
+        exponent = Integer(match[4], 10)
+        number = expand_digits(digits, exponent)
+        negative ? "-#{number}" : number
+      end
+
+      def normalize_decimal(encoded)
+        return encoded unless encoded.include?(".")
+
+        encoded.sub(/0+\z/, "").sub(/\.\z/, "")
+      end
+      private_class_method :normalize_decimal
+
+      def expand_digits(digits, exponent)
+        decimal_position = exponent + 1
+        if decimal_position.positive? && decimal_position <= 21
+          if digits.length <= decimal_position
+            digits + ("0" * (decimal_position - digits.length))
+          else
+            "#{digits[0, decimal_position]}.#{digits[decimal_position..]}"
+          end
+        elsif decimal_position > -6 && decimal_position <= 0
+          "0.#{'0' * -decimal_position}#{digits}"
+        else
+          mantissa = digits.length == 1 ? digits : "#{digits[0]}.#{digits[1..]}"
+          "#{mantissa}e#{'+' if exponent >= 0}#{exponent}"
+        end
+      end
+      private_class_method :expand_digits
+    end
+  end
+end

data/lib/screenshotscout/internal/json_codec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ScreenshotScout
+  module Internal
+    # Encodes already-validated capture values using API-compatible JSON numbers.
+    module JsonCodec
+      module_function
+
+      def encode_wire_object(object)
+        members = object.map do |name, value|
+          "#{JSON.generate(name)}:#{encode_wire_value(value)}"
+        end
+        "{#{members.join(',')}}"
+      end
+
+      def parse(body)
+        JSON.parse(body, create_additions: false)
+      end
+
+      def encode_wire_value(value)
+        case value
+        when String
+          JSON.generate(value)
+        when Integer
+          EcmaScriptNumberFormatter.format(value.to_f)
+        when Float
+          EcmaScriptNumberFormatter.format(value)
+        when true
+          "true"
+        when false
+          "false"
+        when Array
+          "[#{value.map { |item| JSON.generate(item) }.join(',')}]"
+        else
+          raise TypeError, "Unsupported JSON wire value #{value.class}."
+        end
+      end
+      private_class_method :encode_wire_value
+    end
+  end
+end

data/lib/screenshotscout/internal/serializer.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module ScreenshotScout
+  module Internal
+    WirePair = Data.define(:name, :value)
+    SerializedCaptureOptions = Data.define(:pairs, :body)
+
+    # Converts CaptureOptions into the API's exact ordered wire representation.
+    module Serializer
+      WIRE_NAMES = {
+        format: "format",
+        response_type: "response_type",
+        country: "country",
+        proxy: "proxy",
+        geolocation_latitude: "geolocation_latitude",
+        geolocation_longitude: "geolocation_longitude",
+        geolocation_accuracy: "geolocation_accuracy",
+        cookies: "cookies",
+        headers: "headers",
+        timeout: "timeout",
+        wait_until: "wait_until",
+        navigation_timeout: "navigation_timeout",
+        delay: "delay",
+        device: "device",
+        device_viewport_width: "device_viewport_width",
+        device_viewport_height: "device_viewport_height",
+        device_scale_factor: "device_scale_factor",
+        device_is_mobile: "device_is_mobile",
+        device_has_touch: "device_has_touch",
+        device_user_agent: "device_user_agent",
+        timezone: "timezone",
+        media_type: "media_type",
+        color_scheme: "color_scheme",
+        reduced_motion: "reduced_motion",
+        full_page: "full_page",
+        full_page_pre_scroll: "full_page_pre_scroll",
+        full_page_pre_scroll_step: "full_page_pre_scroll_step",
+        full_page_pre_scroll_step_delay: "full_page_pre_scroll_step_delay",
+        full_page_max_height: "full_page_max_height",
+        block_cookie_banners: "block_cookie_banners",
+        block_ads: "block_ads",
+        block_chat_widgets: "block_chat_widgets",
+        hide_selectors: "hide_selectors",
+        click_selectors: "click_selectors",
+        click_all_selectors: "click_all_selectors",
+        inject_css: "inject_css",
+        inject_js: "inject_js",
+        bypass_csp: "bypass_csp",
+        selector: "selector",
+        clip_x: "clip_x",
+        clip_y: "clip_y",
+        clip_width: "clip_width",
+        clip_height: "clip_height",
+        image_width: "image_width",
+        image_height: "image_height",
+        image_mode: "image_mode",
+        image_anchor: "image_anchor",
+        image_allow_upscale: "image_allow_upscale",
+        image_background: "image_background",
+        image_quality: "image_quality",
+        pdf_paper_format: "pdf_paper_format",
+        pdf_landscape: "pdf_landscape",
+        pdf_print_background: "pdf_print_background",
+        pdf_margin: "pdf_margin",
+        pdf_margin_top: "pdf_margin_top",
+        pdf_margin_right: "pdf_margin_right",
+        pdf_margin_bottom: "pdf_margin_bottom",
+        pdf_margin_left: "pdf_margin_left",
+        pdf_scale: "pdf_scale",
+        cache: "cache",
+        cache_ttl: "cache_ttl",
+        cache_key: "cache_key",
+        storage_mode: "storage_mode",
+        storage_endpoint: "storage_endpoint",
+        storage_bucket: "storage_bucket",
+        storage_region: "storage_region",
+        storage_object_key: "storage_object_key"
+      }.freeze
+
+      REPEATED_OPTIONS = %i[
+        cookies headers hide_selectors click_selectors click_all_selectors inject_css inject_js
+      ].freeze
+
+      module_function
+
+      def serialize(target_url, options)
+        url = string_value(target_url, :url, target: true)
+        unless options.nil? || options.is_a?(CaptureOptions)
+          raise SerializationError, "Capture options must be a ScreenshotScout::CaptureOptions instance when provided."
+        end
+
+        pairs = [WirePair.new(name: "url", value: url)]
+        body = { "url" => url }
+        WIRE_NAMES.each do |property, wire_name|
+          value = options&.public_send(property)
+          next if value.nil?
+
+          if REPEATED_OPTIONS.include?(property)
+            append_repeated(pairs, body, property, wire_name, value)
+          else
+            append_scalar(pairs, body, property, wire_name, value)
+          end
+        end
+
+        SerializedCaptureOptions.new(pairs: pairs.freeze, body: body.freeze)
+      rescue Error
+        raise
+      rescue StandardError => e
+        raise SerializationError.new("Capture options could not be serialized."), cause: e
+      end
+
+      def build_canonical_query(pairs, access_key)
+        indexed = (pairs + [WirePair.new(name: "access_key", value: access_key)]).each_with_index.map do |pair, index|
+          [pair, index]
+        end
+        indexed.sort! do |(left, left_index), (right, right_index)|
+          comparison = left.name <=> right.name
+          comparison.zero? ? left_index <=> right_index : comparison
+        end
+        encode_query(indexed.map(&:first))
+      end
+
+      def encode_query(pairs)
+        pairs.map { |pair| "#{form_encode(pair.name)}=#{form_encode(pair.value)}" }.join("&")
+      end
+
+      def append_repeated(pairs, body, property, wire_name, value)
+        unless value.is_a?(Array)
+          raise SerializationError.new(
+            "The capture option \"#{property}\" must be an array of strings.",
+            option: property
+          )
+        end
+        return if value.empty?
+
+        copied = value.map do |item|
+          string_value(item, property)
+        end
+        copied.each { |item| pairs << WirePair.new(name: wire_name, value: item) }
+        body[wire_name] = copied.freeze
+      end
+      private_class_method :append_repeated
+
+      def append_scalar(pairs, body, property, wire_name, value)
+        pair_value, body_value = scalar_value(value, property)
+        pairs << WirePair.new(name: wire_name, value: pair_value)
+        body[wire_name] = body_value
+      end
+      private_class_method :append_scalar
+
+      def scalar_value(value, property)
+        case value
+        when String
+          string = string_value(value, property)
+          [string, string]
+        when Integer
+          number = integer_value(value, property)
+          [number, value]
+        when Float
+          unless value.finite?
+            raise SerializationError.new(
+              "The capture option \"#{property}\" must be a finite number.",
+              option: property
+            )
+          end
+          [EcmaScriptNumberFormatter.format(value), value]
+        when true
+          ["true", true]
+        when false
+          ["false", false]
+        else
+          raise SerializationError.new(
+            "The capture option \"#{property}\" must be a string, finite number, or boolean.",
+            option: property
+          )
+        end
+      end
+      private_class_method :scalar_value
+
+      def integer_value(value, property)
+        float_value = value.to_f
+        return EcmaScriptNumberFormatter.format(float_value) if float_value.finite? && float_value.to_i == value
+
+        raise SerializationError.new(
+          "The capture option \"#{property}\" integer cannot be represented safely by the API.",
+          option: property
+        )
+      end
+      private_class_method :integer_value
+
+      def string_value(value, property, target: false)
+        unless value.is_a?(String)
+          message = if target
+                      "The capture target URL must be a string."
+                    else
+                      "The capture option \"#{property}\" must be a string."
+                    end
+          raise SerializationError.new(message, option: property)
+        end
+
+        value.encode(Encoding::UTF_8)
+      rescue EncodingError => e
+        message = if target
+                    "The capture target URL must contain valid UTF-8."
+                  else
+                    "The capture option \"#{property}\" must contain valid UTF-8."
+                  end
+        raise SerializationError.new(message, option: property), cause: e
+      end
+      private_class_method :string_value
+
+      def form_encode(value)
+        value.bytes.map do |byte|
+          if byte.between?(65, 90) || byte.between?(97, 122) ||
+             byte.between?(48, 57) || [42, 45, 46, 95].include?(byte)
+            byte.chr
+          elsif byte == 32
+            "+"
+          else
+            format("%%%02X", byte)
+          end
+        end.join
+      end
+      private_class_method :form_encode
+    end
+  end
+end

data/lib/screenshotscout/responses.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module ScreenshotScout
+  # Exact buffered HTTP response data retained on successes and API failures.
+  class RawResponse
+    attr_reader :status, :reason_phrase, :headers, :content_type, :body
+
+    def initialize(status:, reason_phrase:, headers:, content_type:, body:)
+      @status = status
+      @reason_phrase = reason_phrase.dup.freeze
+      @headers = copy_headers(headers)
+      @normalized_headers = @headers.to_h do |name, values|
+        [name.downcase, values]
+      end.freeze
+      @content_type = content_type&.dup&.freeze
+      @body = body.dup.freeze
+      freeze
+    end
+
+    def header(name)
+      @normalized_headers.fetch(name.downcase, EMPTY_HEADER_VALUES)
+    end
+
+    EMPTY_HEADER_VALUES = [].freeze
+    private_constant :EMPTY_HEADER_VALUES
+
+    private
+
+    def copy_headers(headers)
+      headers.to_h do |name, values|
+        copied_values = Array(values).map { |value| value.to_s.dup.freeze }.freeze
+        [name.to_s.dup.freeze, copied_values]
+      end.freeze
+    end
+  end
+
+  # Shared response base that exposes the exact buffered HTTP response.
+  class CaptureResponse
+    attr_reader :raw_response
+
+    def initialize(raw_response:)
+      @raw_response = raw_response
+    end
+  end
+
+  # Successful binary capture, including response metadata and image/PDF bytes.
+  class BinaryCaptureResponse < CaptureResponse
+    attr_reader :bytes, :screenshot_url, :screenshot_url_expires_at, :cache_status
+
+    def initialize(raw_response:, screenshot_url:, screenshot_url_expires_at:, cache_status:)
+      super(raw_response: raw_response)
+      @bytes = raw_response.body
+      @screenshot_url = screenshot_url
+      @screenshot_url_expires_at = screenshot_url_expires_at
+      @cache_status = cache_status
+      freeze
+    end
+  end
+
+  # Structured capture result returned when response_type is json.
+  class CaptureResult
+    attr_reader :screenshot_url, :screenshot_url_expires_at, :cache_status, :additional_fields
+
+    def initialize(screenshot_url:, screenshot_url_expires_at:, cache_status:, additional_fields:)
+      @screenshot_url = screenshot_url
+      @screenshot_url_expires_at = screenshot_url_expires_at
+      @cache_status = cache_status
+      @additional_fields = additional_fields.freeze
+      freeze
+    end
+  end
+
+  # Successful JSON capture response and its structured result.
+  class JsonCaptureResponse < CaptureResponse
+    attr_reader :result
+
+    def initialize(result:, raw_response:)
+      super(raw_response: raw_response)
+      @result = result
+      freeze
+    end
+  end
+end