screenshotscout 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a4b2c581974498206ab874e1e4cfaf78906b16ab7c3c5924332e71d8919c244d
4
- data.tar.gz: 6f306fd3cf1f62be26e8a0da90b42a0a719a0987d71e9e64a59b3c52a60e860d
3
+ metadata.gz: 4e93c918de44836d046ca2fe268686f69c5e1d73c2d45dd0f373d5685c54c2f4
4
+ data.tar.gz: 25e763ee17224809101fee88d4da0282f71531b720a0ddfe0891ee0ad3b34600
5
5
  SHA512:
6
- metadata.gz: bdfe6741ed611e68ca8388ede177ad21438dcac59aa836b51c7a561c73f7d708ef976ee03c0539359472c50ba02127210e9ac1e5492e384657d24c2c8ef3cb46
7
- data.tar.gz: 2584fbe9013650194b7193dc20c1ae3ffd7ce4e11ad1a8ed64a068fd8b28b42c639da09be360315584d4713c7275985033b4c3545da4dcbfbe87d7f748b4a52f
6
+ metadata.gz: '049d9252ab97e01b11780fd12bbdbb5c3097c1c9e561035d0ba8770645289e697c2ed9ca631fe7a3a0ee917c6e2dcf38b71b3ff7b9ac8c84aa8dd4c8cbe75882'
7
+ data.tar.gz: 54a5193365aaea42b2e7ec7a353e60e5f9addb3bdfd3f00368036772106eb9b6634b6ce0ba8c4ccf1936d0388fa2536e50fbc427c42edab4060fbffeb0d23983
data/README.md CHANGED
@@ -25,12 +25,11 @@ gem install screenshotscout
25
25
  ## Get your API credentials
26
26
 
27
27
  [Sign up for Screenshot Scout](https://screenshotscout.com/auth/signup) or sign in, then open the
28
- [API Keys page](https://screenshotscout.com/app/api-keys). Copy the access key and secret key and
29
- store them securely. The access key is required. The secret key is optional and enables
30
- [signed requests](#signed-requests).
28
+ [API Keys page](https://screenshotscout.com/app/api-keys) and copy the access key. You only need the
29
+ secret key for [signed requests](#signed-requests).
31
30
 
32
- The examples below read `SCREENSHOTSCOUT_ACCESS_KEY` and, where they sign,
33
- `SCREENSHOTSCOUT_SECRET_KEY` from environment variables.
31
+ Set the access key as the `SCREENSHOTSCOUT_ACCESS_KEY` environment variable, or
32
+ [pass it in code](#pass-the-keys-yourself).
34
33
 
35
34
  ## Capture a screenshot
36
35
 
@@ -40,7 +39,7 @@ the full page and saves the returned image:
40
39
  ```ruby
41
40
  require "screenshotscout"
42
41
 
43
- client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
42
+ client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY
44
43
  response = client.capture(
45
44
  "https://example.com",
46
45
  ScreenshotScout::CaptureOptions.new(full_page: true)
@@ -50,8 +49,8 @@ File.binwrite("screenshot.png", response.bytes)
50
49
  puts response.screenshot_url
51
50
  ```
52
51
 
53
- `capture` uses POST by default and returns a `BinaryCaptureResponse` when `response_type` is
54
- omitted or set to `CaptureResponseType::BINARY`.
52
+ `capture` uses POST by default, or GET when the client has a secret key. It returns a
53
+ `BinaryCaptureResponse` when `response_type` is omitted or set to `CaptureResponseType::BINARY`.
55
54
 
56
55
  ## Request a JSON result
57
56
 
@@ -61,7 +60,7 @@ image or PDF output:
61
60
  ```ruby
62
61
  require "screenshotscout"
63
62
 
64
- client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
63
+ client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY
65
64
  options = ScreenshotScout::CaptureOptions.new(
66
65
  response_type: ScreenshotScout::CaptureResponseType::JSON
67
66
  )
@@ -74,15 +73,13 @@ Unrecognized JSON result fields are retained in `response.result.additional_fiel
74
73
 
75
74
  ## Use GET
76
75
 
77
- POST is used by default. Pass `CaptureHttpMethod::GET` when you need a GET request:
76
+ POST is the default, or GET when the client has a secret key. Pass `CaptureHttpMethod::GET` when
77
+ you need a GET request:
78
78
 
79
79
  ```ruby
80
80
  require "screenshotscout"
81
81
 
82
- client = ScreenshotScout::Client.new(
83
- access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
84
- secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
85
- )
82
+ client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY
86
83
  options = ScreenshotScout::CaptureOptions.new(format: ScreenshotScout::CaptureFormat::WEBP)
87
84
  response = client.capture(
88
85
  "https://example.com",
@@ -101,41 +98,51 @@ load the screenshot directly. It creates the URL without sending an API request:
101
98
  ```ruby
102
99
  require "screenshotscout"
103
100
 
104
- client = ScreenshotScout::Client.new(
105
- access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
106
- secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
107
- )
101
+ client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY
108
102
  options = ScreenshotScout::CaptureOptions.new(full_page: true, block_ads: true)
109
103
  capture_url = client.build_capture_url("https://example.com", options)
110
104
  puts capture_url
111
105
  ```
112
106
 
113
- The generated URL contains the access key. Treat it as sensitive. Before exposing generated URLs
107
+ The generated URL contains the access key. When the client has a secret key, the URL is signed
108
+ automatically; otherwise it is unsigned. Treat it as sensitive. Before exposing generated URLs
114
109
  to browsers or users, configure a secret key and enable **Require signed requests** for the API key
115
110
  on the [API Keys page](https://screenshotscout.com/app/api-keys).
116
111
 
117
112
  ## Signed requests
118
113
 
119
- Pass the API key's secret key to sign generated capture URLs and GET requests automatically. The
120
- secret is used locally and is never transmitted. POST requests can't be signed, so capture with
121
- `method: CaptureHttpMethod::GET`:
114
+ Set the API key's secret key as the `SCREENSHOTSCOUT_SECRET_KEY` environment variable. The client
115
+ then signs its capture requests and the capture URLs it builds, with no change to your code:
122
116
 
123
117
  ```ruby
124
118
  require "screenshotscout"
125
119
 
126
- client = ScreenshotScout::Client.new(
127
- access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
128
- secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY")
129
- )
120
+ client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY and SCREENSHOTSCOUT_SECRET_KEY
130
121
 
131
- response = client.capture(
132
- "https://example.com",
133
- method: ScreenshotScout::CaptureHttpMethod::GET
134
- )
122
+ response = client.capture("https://example.com")
135
123
  File.binwrite("signed-screenshot.png", response.bytes)
136
124
  ```
137
125
 
138
- See the [signed requests guide](https://screenshotscout.com/docs/signed-requests) for details.
126
+ The secret key is used locally and is never transmitted. See the
127
+ [signed requests guide](https://screenshotscout.com/docs/signed-requests) for details.
128
+
129
+ ## Pass the keys yourself
130
+
131
+ To use keys from somewhere other than the environment, such as a secrets manager or per-customer
132
+ settings, pass them to the client:
133
+
134
+ ```ruby
135
+ require "screenshotscout"
136
+
137
+ client = ScreenshotScout::Client.new(
138
+ access_key: config.access_key,
139
+ secret_key: config.secret_key # optional
140
+ )
141
+ ```
142
+
143
+ If you pass either key, the client reads neither environment variable. If you pass no key, for
144
+ example because the variable holding it is `nil`, the client reads both environment variables
145
+ instead.
139
146
 
140
147
  ## Capture options
141
148
 
@@ -162,7 +169,7 @@ Use the provided constants for documented values, or pass a string:
162
169
  ```ruby
163
170
  require "screenshotscout"
164
171
 
165
- client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
172
+ client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY
166
173
  options = ScreenshotScout::CaptureOptions.new(
167
174
  format: ScreenshotScout::CaptureFormat::WEBP,
168
175
  wait_until: ScreenshotScout::CaptureWaitUntil::LOAD
@@ -234,10 +241,8 @@ class ApplicationTransport
234
241
  end
235
242
  end
236
243
 
237
- client = ScreenshotScout::Client.new(
238
- access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
239
- transport: ApplicationTransport.new(open_timeout: 10, read_timeout: 300)
240
- )
244
+ transport = ApplicationTransport.new(open_timeout: 10, read_timeout: 300)
245
+ client = ScreenshotScout::Client.new(transport: transport) # Reads SCREENSHOTSCOUT_ACCESS_KEY
241
246
 
242
247
  response = client.capture("https://example.com")
243
248
  File.binwrite("screenshot.png", response.bytes)
@@ -251,7 +256,7 @@ headers, content type, and body. `APIError` provides the same response details.
251
256
  ```ruby
252
257
  require "screenshotscout"
253
258
 
254
- client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
259
+ client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY
255
260
 
256
261
  begin
257
262
  client.capture("https://example.com")
data/examples/README.md CHANGED
@@ -14,21 +14,21 @@ From the repository root, install the dependencies:
14
14
  bundle install
15
15
  ```
16
16
 
17
- Set your access key. To sign the URL that `capture_url.rb` prints, also set the optional secret
18
- key.
17
+ Set your access key. If you also set the optional secret key, the client signs its requests and the
18
+ URL that `capture_url.rb` prints.
19
19
 
20
20
  PowerShell:
21
21
 
22
22
  ```powershell
23
23
  $env:SCREENSHOTSCOUT_ACCESS_KEY = "YOUR_ACCESS_KEY"
24
- $env:SCREENSHOTSCOUT_SECRET_KEY = "YOUR_SECRET_KEY" # Optional, used by capture_url.rb
24
+ $env:SCREENSHOTSCOUT_SECRET_KEY = "YOUR_SECRET_KEY" # Optional
25
25
  ```
26
26
 
27
27
  macOS or Linux:
28
28
 
29
29
  ```shell
30
30
  export SCREENSHOTSCOUT_ACCESS_KEY="YOUR_ACCESS_KEY"
31
- export SCREENSHOTSCOUT_SECRET_KEY="YOUR_SECRET_KEY" # Optional, used by capture_url.rb
31
+ export SCREENSHOTSCOUT_SECRET_KEY="YOUR_SECRET_KEY" # Optional
32
32
  ```
33
33
 
34
34
  Run any example:
data/examples/binary.rb CHANGED
@@ -2,8 +2,7 @@
2
2
 
3
3
  require "screenshotscout"
4
4
 
5
- access_key = ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY")
6
- client = ScreenshotScout::Client.new(access_key: access_key)
5
+ client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY
7
6
  options = ScreenshotScout::CaptureOptions.new(full_page: true)
8
7
  response = client.capture("https://example.com", options)
9
8
 
@@ -2,9 +2,8 @@
2
2
 
3
3
  require "screenshotscout"
4
4
 
5
- access_key = ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY")
6
- secret_key = ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
7
- client = ScreenshotScout::Client.new(access_key: access_key, secret_key: secret_key)
5
+ # Reads SCREENSHOTSCOUT_ACCESS_KEY, and SCREENSHOTSCOUT_SECRET_KEY if it's set
6
+ client = ScreenshotScout::Client.new
8
7
  options = ScreenshotScout::CaptureOptions.new(full_page: true, block_ads: true)
9
8
 
10
9
  puts client.build_capture_url("https://example.com", options)
data/examples/json.rb CHANGED
@@ -2,8 +2,7 @@
2
2
 
3
3
  require "screenshotscout"
4
4
 
5
- access_key = ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY")
6
- client = ScreenshotScout::Client.new(access_key: access_key)
5
+ client = ScreenshotScout::Client.new # Reads SCREENSHOTSCOUT_ACCESS_KEY
7
6
  options = ScreenshotScout::CaptureOptions.new(
8
7
  response_type: ScreenshotScout::CaptureResponseType::JSON
9
8
  )
@@ -7,25 +7,29 @@ module ScreenshotScout
7
7
  class Client
8
8
  CAPTURE_ENDPOINT = "https://api.screenshotscout.com/v1/capture"
9
9
  ACCESS_KEY_PATTERN = %r{\A[A-Za-z0-9\-._~+/]+=*\z}
10
- MISSING_ACCESS_KEY = Object.new.freeze
11
10
 
12
- def initialize(access_key: MISSING_ACCESS_KEY, secret_key: nil, transport: nil)
13
- validate_access_key(access_key)
14
- validate_secret_key(secret_key)
11
+ # Creates a client. When no key is passed, the client reads SCREENSHOTSCOUT_ACCESS_KEY and, if it's set,
12
+ # SCREENSHOTSCOUT_SECRET_KEY. Passing either key means neither variable is read.
13
+ def initialize(access_key: nil, secret_key: nil, transport: nil)
14
+ credentials = Internal::Credentials.resolve(access_key, secret_key, environment: ENV)
15
+ validate_access_key(credentials.access_key)
16
+ validate_secret_key(credentials.secret_key)
15
17
  validate_transport(transport)
16
18
 
17
- @access_key = access_key.dup.freeze
18
- @secret_key = secret_key&.dup&.freeze
19
+ @access_key = credentials.access_key.dup.freeze
20
+ @secret_key = credentials.secret_key&.dup&.freeze
21
+ @secret_key_from_environment = credentials.from_environment && !@secret_key.nil?
19
22
  @transport = transport || NetHttpTransport.new
20
23
  end
21
24
 
22
- # Sends one GET or POST request and waits for the final inline response. A client with a secret key
23
- # signs GET requests and raises ConfigurationError for POST, because POST requests can't be signed.
24
- def capture(url, options = nil, method: CaptureHttpMethod::POST)
25
+ # Sends one GET or POST request and waits for the final inline response. The method defaults to POST,
26
+ # or GET when the client has a secret key, because POST requests can't be signed. A client with a secret
27
+ # key signs GET requests and raises ConfigurationError for an explicit POST.
28
+ def capture(url, options = nil, method: nil)
25
29
  serialized = Internal::Serializer.serialize(url, options)
26
- method = CaptureHttpMethod::POST if method.nil?
27
- validate_method(method)
30
+ validate_method(method) unless method.nil?
28
31
  reject_signed_post(method)
32
+ method ||= @secret_key.nil? ? CaptureHttpMethod::POST : CaptureHttpMethod::GET
29
33
  expected_kind = expected_response_kind(options)
30
34
  signature = create_signature(serialized.pairs)
31
35
  request = create_request(serialized, method, signature)
@@ -45,6 +49,11 @@ module ScreenshotScout
45
49
  "#{CAPTURE_ENDPOINT}?#{Internal::Serializer.encode_query(pairs)}"
46
50
  end
47
51
 
52
+ # Leaves out the keys, so that printing or logging a client doesn't reveal them.
53
+ def inspect
54
+ "#<#{self.class.name}>"
55
+ end
56
+
48
57
  private
49
58
 
50
59
  def validate_access_key(access_key)
@@ -81,9 +90,10 @@ module ScreenshotScout
81
90
  def reject_signed_post(method)
82
91
  return if @secret_key.nil? || method != CaptureHttpMethod::POST
83
92
 
93
+ source = @secret_key_from_environment ? " from #{Internal::Credentials::SECRET_KEY_VARIABLE}" : ""
84
94
  raise ConfigurationError,
85
- "POST requests can't be signed. This client has a secret key: send this capture with method GET, " \
86
- "or use a client without a secret key and an API key that doesn't require signed requests."
95
+ "POST requests can't be signed. This client has a secret key#{source}: send this capture with " \
96
+ "method GET, or use a client without a secret key and an API key that doesn't require signed requests."
87
97
  end
88
98
 
89
99
  def create_signature(pairs)
@@ -233,6 +243,6 @@ module ScreenshotScout
233
243
  media_type == "application/json" || media_type.end_with?("+json")
234
244
  end
235
245
 
236
- private_constant :CAPTURE_ENDPOINT, :ACCESS_KEY_PATTERN, :MISSING_ACCESS_KEY
246
+ private_constant :CAPTURE_ENDPOINT, :ACCESS_KEY_PATTERN
237
247
  end
238
248
  end
@@ -0,0 +1,43 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ScreenshotScout
4
+ module Internal
5
+ # Picks the keys a client uses: the keys passed to it, or else the environment variables.
6
+ module Credentials
7
+ ACCESS_KEY_VARIABLE = "SCREENSHOTSCOUT_ACCESS_KEY"
8
+ SECRET_KEY_VARIABLE = "SCREENSHOTSCOUT_SECRET_KEY"
9
+
10
+ # The keys to validate, and whether they were read from the environment.
11
+ Resolved = Data.define(:access_key, :secret_key, :from_environment)
12
+
13
+ module_function
14
+
15
+ # Keys passed to the client always win: if either one is passed, neither variable is read. Only when
16
+ # both are nil are both read, as environment[name], which ENV, a Hash and a lambda all support.
17
+ def resolve(access_key, secret_key, environment:)
18
+ unless access_key.nil? && secret_key.nil?
19
+ return Resolved.new(access_key: access_key, secret_key: secret_key, from_environment: false)
20
+ end
21
+
22
+ environment_access_key = read_variable(environment, ACCESS_KEY_VARIABLE)
23
+ environment_secret_key = read_variable(environment, SECRET_KEY_VARIABLE)
24
+ if environment_access_key.nil?
25
+ raise ConfigurationError,
26
+ "A non-blank Screenshot Scout access key is required. Pass one, or set #{ACCESS_KEY_VARIABLE}."
27
+ end
28
+
29
+ Resolved.new(access_key: environment_access_key, secret_key: environment_secret_key, from_environment: true)
30
+ end
31
+
32
+ # Returns nil for a variable that is unset or empty.
33
+ def read_variable(environment, name)
34
+ value = environment[name]
35
+ return nil if value.nil? || value.empty?
36
+ raise ConfigurationError, "#{name} is set but blank." if value.strip.empty?
37
+
38
+ value
39
+ end
40
+ private_class_method :read_variable
41
+ end
42
+ end
43
+ end
@@ -17,6 +17,13 @@ module ScreenshotScout
17
17
  @body = body&.dup&.freeze
18
18
  freeze
19
19
  end
20
+
21
+ # Shows the Authorization header, which carries the access key, as [FILTERED].
22
+ def inspect
23
+ headers = @headers.to_h { |name, value| [name, name.casecmp?("Authorization") ? "[FILTERED]" : value] }
24
+ "#<#{self.class.name} method=#{@method.inspect} url=#{@url.inspect} headers=#{headers.inspect} " \
25
+ "body=#{@body.inspect}>"
26
+ end
20
27
  end
21
28
 
22
29
  # Small default adapter. It owns each Net::HTTP session that it opens.
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module ScreenshotScout
4
- VERSION = "0.4.1"
4
+ VERSION = "0.5.0"
5
5
  end
@@ -6,6 +6,7 @@ require_relative "screenshotscout/errors"
6
6
  require_relative "screenshotscout/capture_options"
7
7
  require_relative "screenshotscout/responses"
8
8
  require_relative "screenshotscout/transport"
9
+ require_relative "screenshotscout/internal/credentials"
9
10
  require_relative "screenshotscout/internal/ecma_script_number_formatter"
10
11
  require_relative "screenshotscout/internal/json_codec"
11
12
  require_relative "screenshotscout/internal/serializer"
@@ -286,6 +286,8 @@ module ScreenshotScout
286
286
  headers: Hash[String, String],
287
287
  ?body: String?
288
288
  ) -> void
289
+
290
+ def inspect: () -> String
289
291
  end
290
292
 
291
293
  interface _Transport
@@ -298,7 +300,7 @@ module ScreenshotScout
298
300
 
299
301
  class Client
300
302
  def initialize: (
301
- access_key: String,
303
+ ?access_key: String?,
302
304
  ?secret_key: String?,
303
305
  ?transport: _Transport?
304
306
  ) -> void
@@ -310,6 +312,8 @@ module ScreenshotScout
310
312
  ) -> CaptureResponse
311
313
 
312
314
  def build_capture_url: (String url, ?CaptureOptions? options) -> String
315
+
316
+ def inspect: () -> String
313
317
  end
314
318
 
315
319
  class Error < StandardError
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: screenshotscout
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.4.1
4
+ version: 0.5.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Oleksii Velykyi
@@ -82,6 +82,7 @@ files:
82
82
  - lib/screenshotscout/capture_values.rb
83
83
  - lib/screenshotscout/client.rb
84
84
  - lib/screenshotscout/errors.rb
85
+ - lib/screenshotscout/internal/credentials.rb
85
86
  - lib/screenshotscout/internal/ecma_script_number_formatter.rb
86
87
  - lib/screenshotscout/internal/json_codec.rb
87
88
  - lib/screenshotscout/internal/serializer.rb