screenshotscout 0.1.0.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 33024a0bca4f826f2c6c4fe20c6d8d7e9fe744b060b71bfb9f92b8ee99563127
+  data.tar.gz: '097bc01284677214c5adeee702b90f31b26240446520e838f87c295e220eddd6'
+SHA512:
+  metadata.gz: cd4bd68c1234dccd18df205d029722dec9ee862f614af686e0823d13c345ad6ce6194ccb4bdc4a4cd7fa28c6f05b2daa59651d47314c7e0c05b135acaa8eaf11
+  data.tar.gz: 683c78838871e5175676bbac26a02d14a7ade33f4e70a4fa6f9074e9ea634697989e09fc7d8b086bcb5c0d56b142f837a6d79644e1e6fbe10e2ff0b1df4f2905

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksii Velykyi
+
+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,286 @@
+# Screenshot Scout Ruby SDK
+
+The official Ruby SDK for the [Screenshot Scout](https://screenshotscout.com/) screenshot API.
+
+Capture website screenshots from Ruby applications.
+
+## Requirements
+
+- Ruby 3.4 or newer
+
+## Installation
+
+Add the gem to your bundle:
+
+```shell
+bundle add screenshotscout
+```
+
+Or install it directly:
+
+```shell
+gem install screenshotscout
+```
+
+## Get your API credentials
+
+[Sign up for Screenshot Scout](https://screenshotscout.com/auth/signup) or sign in, then open the
+[API Keys page](https://screenshotscout.com/app/api-keys). Copy the access key and secret key and
+store them securely. The access key is required. The secret key is optional and enables
+[signed requests](#signed-requests).
+
+The examples below read `SCREENSHOTSCOUT_ACCESS_KEY` and, when available,
+`SCREENSHOTSCOUT_SECRET_KEY` from environment variables.
+
+## Capture a screenshot
+
+Create a client and call `capture` with the page URL and any capture options. This example captures
+the full page and saves the returned image:
+
+```ruby
+require "screenshotscout"
+
+client = ScreenshotScout::Client.new(
+  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
+  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
+)
+response = client.capture(
+  "https://example.com",
+  ScreenshotScout::CaptureOptions.new(full_page: true)
+)
+
+File.binwrite("screenshot.png", response.bytes)
+puts response.screenshot_url
+```
+
+`capture` uses POST by default and returns a `BinaryCaptureResponse` when `response_type` is
+omitted or set to `CaptureResponseType::BINARY`.
+
+## Request a JSON result
+
+Set `response_type` to `CaptureResponseType::JSON` to receive capture metadata instead of binary
+image or PDF output:
+
+```ruby
+require "screenshotscout"
+
+client = ScreenshotScout::Client.new(
+  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
+  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
+)
+options = ScreenshotScout::CaptureOptions.new(
+  response_type: ScreenshotScout::CaptureResponseType::JSON
+)
+response = client.capture("https://example.com", options)
+
+puts response.result.screenshot_url
+```
+
+Unrecognized JSON result fields are retained in `response.result.additional_fields`.
+
+## Use GET
+
+POST is used by default. Pass `CaptureHttpMethod::GET` when you need a GET request:
+
+```ruby
+require "screenshotscout"
+
+client = ScreenshotScout::Client.new(
+  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
+  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
+)
+options = ScreenshotScout::CaptureOptions.new(format: ScreenshotScout::CaptureFormat::WEBP)
+response = client.capture(
+  "https://example.com",
+  options,
+  method: ScreenshotScout::CaptureHttpMethod::GET
+)
+
+File.binwrite("screenshot.webp", response.bytes)
+```
+
+## Build a capture URL
+
+Use `build_capture_url` when a browser, an HTML `<img>` element, or another application needs to
+load the screenshot directly. It creates the URL without sending an API request:
+
+```ruby
+require "screenshotscout"
+
+client = ScreenshotScout::Client.new(
+  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
+  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
+)
+options = ScreenshotScout::CaptureOptions.new(full_page: true, block_ads: true)
+capture_url = client.build_capture_url("https://example.com", options)
+puts capture_url
+```
+
+The generated URL contains the access key. Treat it as sensitive. Before exposing generated URLs
+to browsers or users, configure a secret key and enable **Require signed requests** for the API key
+on the [API Keys page](https://screenshotscout.com/app/api-keys).
+
+## Signed requests
+
+Pass the API key's secret key to sign GET requests, POST requests, and generated capture URLs
+automatically. The secret is used locally and is never transmitted.
+
+```ruby
+require "screenshotscout"
+
+client = ScreenshotScout::Client.new(
+  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
+  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY")
+)
+
+response = client.capture("https://example.com")
+File.binwrite("signed-screenshot.png", response.bytes)
+```
+
+See the [signed requests guide](https://screenshotscout.com/docs/signed-requests) for details.
+
+## Capture options
+
+The target URL is the first argument to `capture`. Use snake_case keywords to customize the
+capture:
+
+- Output: `format`, `response_type`
+- Network and location: `country`, `proxy`, `geolocation_latitude`, `geolocation_longitude`, `geolocation_accuracy`
+- Cookies and webpage headers: `cookies`, `headers`
+- Timing: `timeout`, `wait_until`, `navigation_timeout`, `delay`
+- Device emulation: `device`, `device_viewport_width`, `device_viewport_height`, `device_scale_factor`, `device_is_mobile`, `device_has_touch`, `device_user_agent`
+- Page behavior: `timezone`, `media_type`, `color_scheme`, `reduced_motion`
+- Full page: `full_page`, `full_page_pre_scroll`, `full_page_pre_scroll_step`, `full_page_pre_scroll_step_delay`, `full_page_max_height`
+- Blocking: `block_cookie_banners`, `block_ads`, `block_chat_widgets`
+- DOM changes: `hide_selectors`, `click_selectors`, `click_all_selectors`, `inject_css`, `inject_js`, `bypass_csp`
+- Framing: `selector`, `clip_x`, `clip_y`, `clip_width`, `clip_height`
+- Image output: `image_width`, `image_height`, `image_mode`, `image_anchor`, `image_allow_upscale`, `image_background`, `image_quality`
+- PDF: `pdf_paper_format`, `pdf_landscape`, `pdf_print_background`, `pdf_margin`, `pdf_margin_top`, `pdf_margin_right`, `pdf_margin_bottom`, `pdf_margin_left`, `pdf_scale`
+- Caching: `cache`, `cache_ttl`, `cache_key`
+- Storage: `storage_mode`, `storage_endpoint`, `storage_bucket`, `storage_region`, `storage_object_key`
+
+Use the provided constants for documented values, or pass a string:
+
+```ruby
+require "screenshotscout"
+
+client = ScreenshotScout::Client.new(
+  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
+  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
+)
+options = ScreenshotScout::CaptureOptions.new(
+  format: ScreenshotScout::CaptureFormat::WEBP,
+  wait_until: ScreenshotScout::CaptureWaitUntil::LOAD
+)
+response = client.capture("https://example.com", options)
+File.binwrite("screenshot.webp", response.bytes)
+```
+
+Options such as `cookies`, `headers`, selectors, CSS, and JavaScript accept arrays of strings.
+
+See the [Screenshot Scout option reference](https://screenshotscout.com/docs/screenshot-options)
+for service behavior and allowed values.
+
+## HTTP timeouts and customization
+
+The `timeout` capture option controls how long Screenshot Scout may spend capturing the page. It
+does not configure your application's HTTP timeout.
+
+Most applications can use the default `NetHttpTransport`. To customize HTTP timeouts, proxies,
+TLS, or logging, pass an object with a `call(request)` method. It receives a `TransportRequest` and
+returns a `RawResponse`:
+
+```ruby
+require "net/http"
+require "screenshotscout"
+require "uri"
+
+class ApplicationTransport
+  def initialize(open_timeout:, read_timeout:)
+    @open_timeout = open_timeout
+    @read_timeout = read_timeout
+  end
+
+  def call(request)
+    uri = URI.parse(request.url)
+    http_request = build_request(uri, request)
+    http = Net::HTTP.new(uri.host, uri.port, nil)
+    http.use_ssl = uri.scheme == "https"
+    http.open_timeout = @open_timeout
+    http.read_timeout = @read_timeout
+    http.max_retries = 0
+    response = http.start { |session| session.request(http_request) }
+
+    ScreenshotScout::RawResponse.new(
+      status: response.code.to_i,
+      reason_phrase: response.message.to_s,
+      headers: response.to_hash,
+      content_type: response["content-type"],
+      body: response.body.to_s.b
+    )
+  end
+
+  private
+
+  def build_request(uri, request)
+    http_request = case request.method
+                   when ScreenshotScout::CaptureHttpMethod::GET
+                     Net::HTTP::Get.new(uri)
+                   when ScreenshotScout::CaptureHttpMethod::POST
+                     Net::HTTP::Post.new(uri)
+                   else
+                     raise ArgumentError, "Unsupported HTTP method #{request.method.inspect}."
+                   end
+
+    request.headers.each { |name, value| http_request[name] = value }
+    http_request.body = request.body unless request.body.nil?
+    http_request
+  end
+end
+
+client = ScreenshotScout::Client.new(
+  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
+  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil),
+  transport: ApplicationTransport.new(open_timeout: 10, read_timeout: 300)
+)
+
+response = client.capture("https://example.com")
+File.binwrite("screenshot.png", response.bytes)
+```
+
+## Raw responses and errors
+
+Every successful response exposes `raw_response`, containing the HTTP status, reason phrase,
+headers, content type, and body. `APIError` provides the same response details.
+
+```ruby
+require "screenshotscout"
+
+client = ScreenshotScout::Client.new(
+  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
+  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
+)
+
+begin
+  client.capture("https://example.com")
+  puts "Capture succeeded."
+rescue ScreenshotScout::APIError => error
+  warn [error.status, error.error_code, error.error_message].inspect
+  warn error.errors.inspect
+  warn error.response_body.inspect if error.response_body?
+  warn error.raw_response.body.inspect
+rescue ScreenshotScout::TransportError => error
+  warn error.cause.inspect
+rescue ScreenshotScout::ConfigurationError,
+       ScreenshotScout::SerializationError,
+       ScreenshotScout::ResponseDecodingError => error
+  warn error.message
+end
+```
+
+All SDK exceptions inherit from `ScreenshotScout::Error`, which you can rescue to handle any SDK
+error.
+
+## License
+
+Licensed under the [MIT License](LICENSE).

data/examples/README.md

@@ -0,0 +1,43 @@
+# Examples
+
+- [`binary.rb`](binary.rb) captures a full-page screenshot, saves it as `screenshot.png`, and
+  prints the returned screenshot URL.
+- [`json.rb`](json.rb) requests a JSON response and prints the screenshot URL.
+- [`capture_url.rb`](capture_url.rb) creates and prints a capture URL without sending an API
+  request.
+
+## Run the examples
+
+From the repository root, install the dependencies:
+
+```shell
+bundle install
+```
+
+Set your access key. Set the optional secret key to use
+[signed requests](../README.md#signed-requests) and signed capture URLs. The secret key is required
+when **Require signed requests** is enabled for the API key.
+
+PowerShell:
+
+```powershell
+$env:SCREENSHOTSCOUT_ACCESS_KEY = "YOUR_ACCESS_KEY"
+$env:SCREENSHOTSCOUT_SECRET_KEY = "YOUR_SECRET_KEY"
+```
+
+macOS or Linux:
+
+```shell
+export SCREENSHOTSCOUT_ACCESS_KEY="YOUR_ACCESS_KEY"
+export SCREENSHOTSCOUT_SECRET_KEY="YOUR_SECRET_KEY"
+```
+
+Run any example:
+
+```shell
+bundle exec ruby -Ilib examples/binary.rb
+bundle exec ruby -Ilib examples/json.rb
+bundle exec ruby -Ilib examples/capture_url.rb
+```
+
+Generated capture URLs contain the access key and should be treated as sensitive.

data/examples/binary.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "screenshotscout"
+
+access_key = ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY")
+secret_key = ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
+client = ScreenshotScout::Client.new(access_key: access_key, secret_key: secret_key)
+options = ScreenshotScout::CaptureOptions.new(full_page: true)
+response = client.capture("https://example.com", options)
+
+File.binwrite("screenshot.png", response.bytes)
+puts response.screenshot_url

data/examples/capture_url.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "screenshotscout"
+
+access_key = ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY")
+secret_key = ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
+client = ScreenshotScout::Client.new(access_key: access_key, secret_key: secret_key)
+options = ScreenshotScout::CaptureOptions.new(full_page: true, block_ads: true)
+
+puts client.build_capture_url("https://example.com", options)

data/examples/json.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "screenshotscout"
+
+access_key = ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY")
+secret_key = ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
+client = ScreenshotScout::Client.new(access_key: access_key, secret_key: secret_key)
+options = ScreenshotScout::CaptureOptions.new(
+  response_type: ScreenshotScout::CaptureResponseType::JSON
+)
+response = client.capture("https://example.com", options)
+
+puts response.result.screenshot_url

data/lib/screenshotscout/capture_options.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ScreenshotScout
+  # Keyword-initialized options for one Screenshot Scout capture.
+  class CaptureOptions
+    ATTRIBUTE_NAMES = %i[
+      format response_type country proxy geolocation_latitude geolocation_longitude
+      geolocation_accuracy cookies headers timeout wait_until navigation_timeout delay
+      device device_viewport_width device_viewport_height device_scale_factor device_is_mobile
+      device_has_touch device_user_agent timezone media_type color_scheme reduced_motion
+      full_page full_page_pre_scroll full_page_pre_scroll_step full_page_pre_scroll_step_delay
+      full_page_max_height block_cookie_banners block_ads block_chat_widgets hide_selectors
+      click_selectors click_all_selectors inject_css inject_js bypass_csp selector clip_x clip_y
+      clip_width clip_height image_width image_height image_mode image_anchor image_allow_upscale
+      image_background image_quality pdf_paper_format pdf_landscape pdf_print_background
+      pdf_margin pdf_margin_top pdf_margin_right pdf_margin_bottom pdf_margin_left pdf_scale cache
+      cache_ttl cache_key storage_mode storage_endpoint storage_bucket storage_region
+      storage_object_key
+    ].freeze
+
+    attr_reader(*ATTRIBUTE_NAMES)
+
+    def initialize(**options)
+      unknown = options.keys - ATTRIBUTE_NAMES
+      unless unknown.empty?
+        option = unknown.first
+        raise SerializationError.new("Unknown capture option \"#{option}\".", option: option)
+      end
+
+      ATTRIBUTE_NAMES.each do |name|
+        instance_variable_set("@#{name}", options[name])
+      end
+    end
+
+    private_constant :ATTRIBUTE_NAMES
+  end
+end

data/lib/screenshotscout/capture_values.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ScreenshotScout
+  module CaptureHttpMethod
+    GET = "GET"
+    POST = "POST"
+  end
+
+  module CaptureFormat
+    GIF = "gif"
+    JPEG = "jpeg"
+    JPG = "jpg"
+    PDF = "pdf"
+    PNG = "png"
+    TIFF = "tiff"
+    WEBP = "webp"
+  end
+
+  module CaptureResponseType
+    BINARY = "binary"
+    JSON = "json"
+  end
+
+  module CaptureWaitUntil
+    DOM_CONTENT_LOADED = "domcontentloaded"
+    LOAD = "load"
+    NETWORK_IDLE_0 = "networkidle0"
+    NETWORK_IDLE_2 = "networkidle2"
+  end
+
+  module CaptureMediaType
+    PRINT = "print"
+    SCREEN = "screen"
+  end
+
+  module CaptureColorScheme
+    AUTO = "auto"
+    DARK = "dark"
+    LIGHT = "light"
+  end
+
+  module CaptureImageMode
+    FILL = "fill"
+    FIT = "fit"
+    STRETCH = "stretch"
+  end
+
+  module CaptureImageAnchor
+    BOTTOM = "bottom"
+    BOTTOM_LEFT = "bottom_left"
+    BOTTOM_RIGHT = "bottom_right"
+    CENTER = "center"
+    LEFT = "left"
+    RIGHT = "right"
+    TOP = "top"
+    TOP_LEFT = "top_left"
+    TOP_RIGHT = "top_right"
+  end
+
+  module CapturePdfPaperFormat
+    A3 = "a3"
+    A4 = "a4"
+    CONTENT = "content"
+    LEGAL = "legal"
+    LETTER = "letter"
+    TABLOID = "tabloid"
+  end
+
+  module CaptureStorageMode
+    EXTERNAL = "external"
+    MANAGED = "managed"
+  end
+end