screenshotscout 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9d728fc9965f9d5d7821a429288aaec98c8f802be65afec9b85e57979f5a865
-  data.tar.gz: 85c40db2478f3f8302ed41a412994bf56c777ec4d0097b575a0fe1d29143fc83
+  metadata.gz: 8a670447d2ee6dc8b14865d9161623661cdcd7f8ca0139a5741d61872821d05a
+  data.tar.gz: 9c514cbb7f1f5e0eabc76669c7a83faffbcff07501689749238c6f527dbaa6cb
 SHA512:
-  metadata.gz: 409cf55714fe4190fa3ec809c5736499288f913762a08a54cbc34a517e83dd743ea3b9b3a8e2518da21d0a1e178e77a2fe01181b8f0347be189ee6fd12466e1b
-  data.tar.gz: 7312bc75e5a225910031eb2021a476ec23754169de29580c42bf724cd46d9beec24a72c419098ec8f1f083882618a918796780052eb0242229e6579f47b1fb79
+  metadata.gz: d3606891244c9ec6eb473af8eda9ff48d07b4990ff7263e577920ddf8db12abc787a177bccf8448d3e64f9396640378a2a2e16e0c57f3e78e330d06dbaac5066
+  data.tar.gz: 4e07a85d4ed239504f3629f4d897f93585cbc32c5279898e4819f3b3346c1a6cc4eadecabe5b652504b26d775af5aeb9990dc690f8bbb470a13c51927c159378

data/README.md

@@ -29,7 +29,7 @@ gem install screenshotscout
 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,
+The examples below read `SCREENSHOTSCOUT_ACCESS_KEY` and, where they sign,
 `SCREENSHOTSCOUT_SECRET_KEY` from environment variables.
 
 ## Capture a screenshot
@@ -40,10 +40,7 @@ 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)
-)
+client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
 response = client.capture(
   "https://example.com",
   ScreenshotScout::CaptureOptions.new(full_page: true)
@@ -64,10 +61,7 @@ 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)
-)
+client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
 options = ScreenshotScout::CaptureOptions.new(
   response_type: ScreenshotScout::CaptureResponseType::JSON
 )
@@ -122,8 +116,9 @@ 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.
+Pass the API key's secret key to sign generated capture URLs and GET requests automatically. The
+secret is used locally and is never transmitted. POST requests can't be signed, so capture with
+`method: CaptureHttpMethod::GET`:
 
 ```ruby
 require "screenshotscout"
@@ -133,7 +128,10 @@ client = ScreenshotScout::Client.new(
   secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY")
 )
 
-response = client.capture("https://example.com")
+response = client.capture(
+  "https://example.com",
+  method: ScreenshotScout::CaptureHttpMethod::GET
+)
 File.binwrite("signed-screenshot.png", response.bytes)
 ```
 
@@ -155,7 +153,7 @@ capture:
 - 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`
+- 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`, `pdf_page_ranges`
 - Caching: `cache`, `cache_ttl`, `cache_key`
 - Storage: `storage_mode`, `storage_endpoint`, `storage_bucket`, `storage_region`, `storage_object_key`
 
@@ -164,10 +162,7 @@ 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)
-)
+client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
 options = ScreenshotScout::CaptureOptions.new(
   format: ScreenshotScout::CaptureFormat::WEBP,
   wait_until: ScreenshotScout::CaptureWaitUntil::LOAD
@@ -240,7 +235,6 @@ 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)
 )
 
@@ -256,10 +250,7 @@ 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)
-)
+client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
 
 begin
   client.capture("https://example.com")

data/examples/README.md

@@ -14,22 +14,21 @@ From the repository root, install the dependencies:
 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.
+Set your access key. To sign the URL that `capture_url.rb` prints, also set the optional secret
+key.
 
 PowerShell:
 
 ```powershell
 $env:SCREENSHOTSCOUT_ACCESS_KEY = "YOUR_ACCESS_KEY"
-$env:SCREENSHOTSCOUT_SECRET_KEY = "YOUR_SECRET_KEY"
+$env:SCREENSHOTSCOUT_SECRET_KEY = "YOUR_SECRET_KEY" # Optional, used by capture_url.rb
 ```
 
 macOS or Linux:
 
 ```shell
 export SCREENSHOTSCOUT_ACCESS_KEY="YOUR_ACCESS_KEY"
-export SCREENSHOTSCOUT_SECRET_KEY="YOUR_SECRET_KEY"
+export SCREENSHOTSCOUT_SECRET_KEY="YOUR_SECRET_KEY" # Optional, used by capture_url.rb
 ```
 
 Run any example:

data/examples/binary.rb

@@ -3,8 +3,7 @@
 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)
+client = ScreenshotScout::Client.new(access_key: access_key)
 options = ScreenshotScout::CaptureOptions.new(full_page: true)
 response = client.capture("https://example.com", options)
 

data/examples/json.rb

@@ -3,8 +3,7 @@
 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)
+client = ScreenshotScout::Client.new(access_key: access_key)
 options = ScreenshotScout::CaptureOptions.new(
   response_type: ScreenshotScout::CaptureResponseType::JSON
 )

data/lib/screenshotscout/capture_options.rb

@@ -13,9 +13,9 @@ module ScreenshotScout
       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
+      pdf_margin pdf_margin_top pdf_margin_right pdf_margin_bottom pdf_margin_left pdf_scale
+      pdf_page_ranges cache cache_ttl cache_key storage_mode storage_endpoint storage_bucket
+      storage_region storage_object_key
     ].freeze
 
     attr_reader(*ATTRIBUTE_NAMES)

data/lib/screenshotscout/capture_values.rb

@@ -60,7 +60,8 @@ module ScreenshotScout
   module CapturePdfPaperFormat
     A3 = "a3"
     A4 = "a4"
-    CONTENT = "content"
+    A5 = "a5"
+    A6 = "a6"
     LEGAL = "legal"
     LETTER = "letter"
     TABLOID = "tabloid"

data/lib/screenshotscout/client.rb

@@ -19,11 +19,13 @@ module ScreenshotScout
       @transport = transport || NetHttpTransport.new
     end
 
-    # Sends one GET or POST request and waits for the final inline response.
+    # Sends one GET or POST request and waits for the final inline response. A client with a secret key
+    # signs GET requests and raises ConfigurationError for POST, because POST requests can't be signed.
     def capture(url, options = nil, method: CaptureHttpMethod::POST)
       serialized = Internal::Serializer.serialize(url, options)
       method = CaptureHttpMethod::POST if method.nil?
       validate_method(method)
+      reject_signed_post(method)
       expected_kind = expected_response_kind(options)
       signature = create_signature(serialized.pairs)
       request = create_request(serialized, method, signature)
@@ -76,6 +78,14 @@ module ScreenshotScout
       )
     end
 
+    def reject_signed_post(method)
+      return if @secret_key.nil? || method != CaptureHttpMethod::POST
+
+      raise ConfigurationError,
+            "POST requests can't be signed. This client has a secret key: send this capture with method GET, " \
+            "or use a client without a secret key and an API key that doesn't require signed requests."
+    end
+
     def create_signature(pairs)
       return nil if @secret_key.nil?
 
@@ -95,14 +105,12 @@ module ScreenshotScout
         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)
+          body: Internal::JsonCodec.encode_wire_object(serialized.body)
         )
       end
     rescue Error

data/lib/screenshotscout/internal/serializer.rb

@@ -67,6 +67,7 @@ module ScreenshotScout
         pdf_margin_bottom: "pdf_margin_bottom",
         pdf_margin_left: "pdf_margin_left",
         pdf_scale: "pdf_scale",
+        pdf_page_ranges: "pdf_page_ranges",
         cache: "cache",
         cache_ttl: "cache_ttl",
         cache_key: "cache_key",
@@ -121,7 +122,7 @@ module ScreenshotScout
       end
 
       def encode_query(pairs)
-        pairs.map { |pair| "#{form_encode(pair.name)}=#{form_encode(pair.value)}" }.join("&")
+        pairs.map { |pair| "#{rfc3986_encode(pair.name)}=#{rfc3986_encode(pair.value)}" }.join("&")
       end
 
       def append_repeated(pairs, body, property, wire_name, value)
@@ -198,7 +199,11 @@ module ScreenshotScout
           raise SerializationError.new(message, option: property)
         end
 
-        value.encode(Encoding::UTF_8)
+        string = value.encode(Encoding::UTF_8)
+        # encode doesn't check the bytes of a string that is already tagged as UTF-8.
+        raise Encoding::InvalidByteSequenceError, "invalid byte sequence in UTF-8" unless string.valid_encoding?
+
+        string
       rescue EncodingError => e
         message = if target
                     "The capture target URL must contain valid UTF-8."
@@ -209,19 +214,18 @@ module ScreenshotScout
       end
       private_class_method :string_value
 
-      def form_encode(value)
+      # Percent-encodes UTF-8 bytes, leaving only the RFC 3986 unreserved characters as they are.
+      def rfc3986_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.between?(48, 57) || [45, 46, 95, 126].include?(byte)
             byte.chr
-          elsif byte == 32
-            "+"
           else
             format("%%%02X", byte)
           end
         end.join
       end
-      private_class_method :form_encode
+      private_class_method :rfc3986_encode
     end
   end
 end

data/lib/screenshotscout/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ScreenshotScout
-  VERSION = "0.1.0"
+  VERSION = "0.4.0"
 end

data/sig/screenshotscout.rbs

@@ -64,7 +64,8 @@ module ScreenshotScout
   module CapturePdfPaperFormat
     A3: String
     A4: String
-    CONTENT: String
+    A5: String
+    A6: String
     LEGAL: String
     LETTER: String
     TABLOID: String
@@ -135,6 +136,7 @@ module ScreenshotScout
     attr_reader pdf_margin_bottom: String?
     attr_reader pdf_margin_left: String?
     attr_reader pdf_scale: number?
+    attr_reader pdf_page_ranges: String?
     attr_reader cache: bool?
     attr_reader cache_ttl: Integer?
     attr_reader cache_key: String?
@@ -204,6 +206,7 @@ module ScreenshotScout
       ?pdf_margin_bottom: String?,
       ?pdf_margin_left: String?,
       ?pdf_scale: number?,
+      ?pdf_page_ranges: String?,
       ?cache: bool?,
       ?cache_ttl: Integer?,
       ?cache_key: String?,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: screenshotscout
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Oleksii Velykyi