browshot 1.16.0 → 1.32.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
- SHA1:
3
- metadata.gz: b028681c4d0960152ecc9202204806a51fe50c46
4
- data.tar.gz: 40fd0ccc8878200afe4f52d56c1d275f8a446d2f
2
+ SHA256:
3
+ metadata.gz: 317dbeba50f7f1752fc19e9a70276f960e392c16625b4b7e93b0da5480f2c553
4
+ data.tar.gz: c9d5da63d1b89c23042f3d42a815741278ea2616ab999d8406f1d082e687e889
5
5
  SHA512:
6
- metadata.gz: c05b5fb8570efe864ec45acb4afb0d9c73aaac3dcfdc5b06ad8241e9e26df40eda540b4d7800748156a478aacfc92b7e0154b2a5715aedfeeb1e78d8a9544326
7
- data.tar.gz: 19cdc44a170a87d70cbddba7141102ee2c957aca6946506de600a403018626508959d4a77978711a34999fbfab2afff965bf0ac812546fa4c27f8045fc99738a
6
+ metadata.gz: b173a7d24fafdc88d438111ba7406d2438f8b85eaaec0acff8bdc3150f8cac41dd6d5f6a058aeb46fc8a69b026aff115023acfb27aa61593cebc77d12c84067e
7
+ data.tar.gz: c7be1e20220a454eaca0dded39158eafa89eb616d1df0172df557e1e7d82b885813dfe797a3ae5f2b504c36f74768cccd8be3b3bdb075720f363ff97274e1be7
data/CHANGELOG.rdoc ADDED
@@ -0,0 +1,12 @@
1
+ = Changelog
2
+
3
+ == 1.32.0
4
+
5
+ * Add +screenshot_pdf+, +screenshot_pdf_file+, +screenshot_video+, and
6
+ +screenshot_video_file+ for PDF, WebM, MP4, and GIF downloads.
7
+ * Pass the API 1.32 options through existing capture methods. Fix the batch
8
+ upload content type and allow the crawl starting URL in its options hash.
9
+ * Encode API keys and accept either symbol or string keys for repeated URL
10
+ and instance options.
11
+ * Document the options, credit costs, and native country instance IDs.
12
+ * Add offline artifact tests and opt-in live tests with an environment key.
data/Gemfile CHANGED
@@ -1,9 +1,3 @@
1
- source "http://rubygems.org"
2
- # Dependencies required to use browshot
1
+ source "https://rubygems.org"
3
2
 
4
- gem "json", ">= 0"
5
- gem "url", ">= 0"
6
-
7
- group :test do
8
- gem 'shoulda'
9
- end
3
+ gemspec
data/LICENSE.txt ADDED
@@ -0,0 +1,20 @@
1
+ Copyright (c) 2011 Julien Sobrier
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining
4
+ a copy of this software and associated documentation files (the
5
+ "Software"), to deal in the Software without restriction, including
6
+ without limitation the rights to use, copy, modify, merge, publish,
7
+ distribute, sublicense, and/or sell copies of the Software, and to
8
+ permit persons to whom the Software is furnished to do so, subject to
9
+ the following conditions:
10
+
11
+ The above copyright notice and this permission notice shall be
12
+ included in all copies or substantial portions of the Software.
13
+
14
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
15
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
16
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
17
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
18
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
19
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
20
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.rdoc ADDED
@@ -0,0 +1,94 @@
1
+ = browshot
2
+
3
+ Browshot (http://www.browshot.com/) is a web service to easily make screenshots of web pages in any screen size, as any device: iPhone©, iPad©, Android©, Nook©, PC, etc. Browshot has full Flash, JavaScript, CSS, & HTML5 support.
4
+
5
+ The latest API version is detailed at http://browshot.com/api/documentation. browshot follows the API documentation very closely: the function names are similar to the URLs used (screenshot/create becomes screenshot_create(), instance/list becomes instance_list(), etc.), the request arguments are exactly the same, etc.
6
+
7
+ The library version matches closely the API version it handles: browshot 1.0.0 is the first release for the API 1.0, browshot 1.1.1 is the second release for the API 1.1, etc.
8
+
9
+ browshot can handle most the API updates within the same major version, e.g. browshot 1.0.0 should be compatible with the API 1.1 or 1.2.
10
+
11
+ Browshot gem is availabe at rubygems: https://rubygems.org/gems/browshot
12
+
13
+ == Build and install browshot
14
+
15
+ git clone https://github.com/juliensobrier/browshot-ruby
16
+ gem build browshot.gemspec
17
+ gem install --dev browshot-<version>.gem
18
+ rake test
19
+ rake rdoc
20
+
21
+ Or
22
+
23
+ gem install browshot
24
+
25
+ == API 1.32
26
+
27
+ Pass capture options in the existing parameter hash.
28
+
29
+ require 'browshot'
30
+
31
+ client = Browshot.new(ENV.fetch('BROWSHOT_API_KEY'))
32
+ capture = client.screenshot_create('https://example.com/',
33
+ instance_id: 373, pdf: 1, pdf_format: 'a4', pdf_margin: '10mm',
34
+ device_scale: 2, hide_ads: 1)
35
+
36
+ Poll +screenshot_info(capture['id'])+ until its status is +finished+.
37
+ Use +screenshot_pdf(capture['id'])+ to read the PDF bytes or
38
+ +screenshot_pdf_file(capture['id'], 'example.pdf')+ to save them.
39
+
40
+ For a video or animated GIF, request the recording when creating the capture.
41
+
42
+ recording = client.screenshot_create('https://example.com/',
43
+ instance_id: 373, video: 1, video_format: 'gif',
44
+ video_duration: 5, video_scale: 0.5)
45
+
46
+ Once the capture finishes, use +screenshot_video(recording['id'])+ for the
47
+ bytes or +screenshot_video_file(recording['id'], 'example.gif')+ to save the
48
+ file. The video formats are WebM (default), MP4, and GIF. MP4 can fall back to
49
+ WebM, and the file helper uses the supplied path and extension. Download
50
+ methods return binary strings, and file helpers return the path on success.
51
+ Both return an empty string on failure.
52
+
53
+ PDF options include paper format (+letter+, +a4+, or +legal+), background,
54
+ landscape, one-page output, and PDF margins. Video options include duration
55
+ (1 to 30 seconds), quality (0 to 63), frame rate (1 to 30), and scale
56
+ (0.1 to 1). GIF uses 20 frames per second.
57
+
58
+ Choose a country with +instance_id+. The new instances below are listed in
59
+ order Chrome, Firefox, iPhone 12, and Samsung S20.
60
+
61
+ France 373 374 375 376
62
+ India 377 378 379 380
63
+ Finland 381 382 383 384
64
+ United Kingdom 385 386 387 388
65
+
66
+ Each instance costs one credit before options. PDF adds one credit, and a
67
+ recording adds one credit for every started five seconds of requested duration.
68
+ PDF and video require a paid Chrome-based instance. Recording requires
69
+ +device_scale=1+. Retina (+device_scale=2+), ad blocking (+hide_ads=1+), and
70
+ downloads add no credits.
71
+
72
+ == Tests
73
+
74
+ Run +bundle install+ and +bundle exec rake test+. The offline tests use a
75
+ loopback HTTP server. Set +BROWSHOT_API_KEY+ to run live tests. Use
76
+ +BROWSHOT_SCREENSHOT_ID+ for an owned finished screenshot and
77
+ +BROWSHOT_RETINA_ID+ for one with retina and ad blocking enabled. The PDF,
78
+ WebM, MP4, and GIF checks use +BROWSHOT_PDF_ID+, +BROWSHOT_WEBM_ID+,
79
+ +BROWSHOT_MP4_ID+, and +BROWSHOT_GIF_ID+ for finished captures in your account.
80
+
81
+ == Contributing to browshot
82
+
83
+ * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
84
+ * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
85
+ * Fork the project
86
+ * Start a feature/bugfix branch
87
+ * Commit and push until you are happy with your contribution
88
+ * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
89
+ * Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
90
+
91
+ == Copyright
92
+
93
+ Copyright (c) 2014 Julien Sobrier. See LICENSE.txt for
94
+ further details.
data/VERSION ADDED
@@ -0,0 +1 @@
1
+ 1.32.0
data/browshot.gemspec ADDED
@@ -0,0 +1,20 @@
1
+ Gem::Specification.new do |s|
2
+ s.name = 'browshot'
3
+ s.version = File.read(File.expand_path('VERSION', File.dirname(__FILE__))).strip
4
+ s.summary = "Take website screenshots with Browshot"
5
+ s.description = "Library for the Browshot API"
6
+ s.authors = ["Julien Sobrier"]
7
+ s.email = 'julien@sobrier.net'
8
+ s.files = ["Gemfile", "Rakefile", "README.rdoc", "CHANGELOG.rdoc", "LICENSE.txt", "VERSION", "browshot.gemspec", "lib/browshot.rb"]
9
+ s.require_paths = ["lib"]
10
+ s.test_files = Dir["test/*.rb"]
11
+ s.homepage = 'https://browshot.com/'
12
+ s.license = 'MIT'
13
+ s.add_dependency "json"
14
+ s.add_dependency "url"
15
+ s.add_development_dependency "rake"
16
+ s.add_development_dependency "shoulda-context"
17
+ s.add_development_dependency "yard"
18
+ s.add_development_dependency 'test-unit'
19
+ s.add_development_dependency 'webrick'
20
+ end
data/lib/browshot.rb CHANGED
@@ -16,6 +16,8 @@ require 'net/https'
16
16
  require "cgi"
17
17
 
18
18
  class Browshot
19
+ VERSION = '1.32.0'
20
+
19
21
  # @!attribute [r]
20
22
  # API key
21
23
  attr_reader :key
@@ -39,7 +41,7 @@ class Browshot
39
41
 
40
42
  # Return the API version handled by the library. Note that this library can usually handle new arguments in requests without requiring an update.
41
43
  def api_version()
42
- return "1.16"
44
+ return VERSION.split('.')[0, 2].join('.')
43
45
  end
44
46
 
45
47
  # Retrieve a screenshot with one call. See {https://browshot.com/api/documentation#simple} for the full list of possible arguments.
@@ -211,6 +213,34 @@ class Browshot
211
213
  end
212
214
 
213
215
 
216
+ # Download the PDF generated by a finished screenshot requested with pdf=1.
217
+ #
218
+ # @param id [Integer, String] Screenshot ID
219
+ # @return [String] PDF bytes, or an empty string on failure
220
+ def screenshot_pdf(id=0, parameters={})
221
+ return screenshot_artifact('pdf', id, parameters, ['application/pdf'])
222
+ end
223
+
224
+ # Download the WebM, MP4, or GIF generated by a finished screenshot requested with video=1.
225
+ #
226
+ # @param id [Integer, String] Screenshot ID
227
+ # @return [String] Recording bytes, or an empty string on failure
228
+ def screenshot_video(id=0, parameters={})
229
+ return screenshot_artifact('video', id, parameters, ['video/webm', 'video/mp4', 'image/gif'])
230
+ end
231
+
232
+ # Save a PDF to a local file and return its name, or an empty string on failure.
233
+ def screenshot_pdf_file(id=0, file='', parameters={})
234
+ return save_artifact(:screenshot_pdf, id, file, parameters)
235
+ end
236
+
237
+ # Save a video to a local file and return its name, or an empty string on failure.
238
+ # MP4 requests can produce WebM. The file name stays as supplied.
239
+ def screenshot_video_file(id=0, file='', parameters={})
240
+ return save_artifact(:screenshot_video, id, file, parameters)
241
+ end
242
+
243
+
214
244
  # Request multiple screenshots. See http://browshot.com/api/documentation#screenshot_multiple for the response format.
215
245
  #
216
246
  # See http://browshot.com/api/documentation#screenshot_multiple for the full list of possible arguments.
@@ -242,6 +272,32 @@ class Browshot
242
272
  return return_reply('batch/info', parameters)
243
273
  end
244
274
 
275
+ # Crawl a domain. See https://browshot.com/api/documentation#crawl_create.
276
+ #
277
+ # @param id [Integer] Instance ID
278
+ # @param domain [String] Domain to crawl
279
+ # @param parameters [Hash] Capture options, including an optional :url to start with
280
+ def crawl_create(id=0, domain='', parameters={})
281
+ parameters = parameters.merge(:instance_id => id)
282
+ unless domain.empty?
283
+ parameters.delete('domain')
284
+ parameters[:domain] = domain
285
+ end
286
+
287
+ return return_reply('crawl/create', parameters)
288
+ end
289
+
290
+ # Get information about a screenshot crawl requested previously. See {https://browshot.com/api/documentation#crawl_info} for the response format.
291
+ #
292
+ # See http://browshot.com/api/documentation#crawl_info for the full list of possible arguments.
293
+ #
294
+ # @param id [Integer] Crawl ID
295
+ def crawl_info(id=0, parameters={})
296
+ parameters[:id] = id
297
+
298
+ return return_reply('crawl/info', parameters)
299
+ end
300
+
245
301
 
246
302
  # Return information about the user account. See {https://browshot.com/api/documentation#account_info} for the response format.
247
303
  def account_info(parameters={})
@@ -250,21 +306,61 @@ class Browshot
250
306
 
251
307
  private
252
308
 
309
+ def screenshot_artifact(kind, id, parameters, content_types)
310
+ return ''.b unless id.to_s =~ /\A[1-9][0-9]{0,18}\z/
311
+
312
+ query = parameters.reject { |key, _| key.to_s == 'id' }
313
+ query[:id] = id
314
+ url = URI(make_url('screenshot/' + kind, query))
315
+ request = Net::HTTP::Get.new(url.request_uri, {
316
+ 'Accept-Encoding' => 'identity', 'User-Agent' => "Browshot Ruby #{VERSION}"
317
+ })
318
+ response = Net::HTTP.start(url.host, url.port, :use_ssl => url.scheme == 'https') do |http|
319
+ http.request(request)
320
+ end
321
+ return ''.b unless response.code == '200'
322
+
323
+ type = response['content-type'].to_s.partition(';').first.strip.downcase
324
+ return ''.b unless content_types.include?(type)
325
+
326
+ body = response.body.to_s.b
327
+ length = response['content-length']
328
+ return ''.b if length && length.to_i != body.bytesize
329
+
330
+ return body
331
+ rescue IOError, SystemCallError, SocketError, Timeout::Error, OpenSSL::SSL::SSLError,
332
+ Net::HTTPBadResponse, Net::ProtocolError
333
+ return ''.b
334
+ end
335
+
336
+ def save_artifact(method, id, file, parameters)
337
+ return '' unless file.is_a?(String) || file.respond_to?(:to_path)
338
+ return '' if file == ''
339
+
340
+ content = public_send(method, id, parameters)
341
+ return '' if content.empty?
342
+
343
+ File.binwrite(file, content)
344
+ return file
345
+ rescue IOError, SystemCallError, ArgumentError
346
+ return ''
347
+ end
348
+
253
349
  def make_url(action='', parameters={})
254
- url = "#{@base}#{action}?key=#{@key}"
350
+ url = "#{@base}#{action}?key=#{CGI::escape(@key.to_s)}"
255
351
 
256
352
 
257
353
  parameters.each_pair do |key, value|
258
- if (key == 'urls')
354
+ if (key.to_s == 'urls')
259
355
  value.each { |val|
260
356
  url += '&url=' + CGI::escape(val.to_s)
261
357
  }
262
- elsif (key == 'instances')
358
+ elsif (key.to_s == 'instances')
263
359
  value.each { |instance|
264
360
  url += '&instance_id=' + CGI::escape(instance.to_s)
265
361
  }
266
362
  else
267
- url += "&#{key}=" + CGI::escape(value.to_s)
363
+ url += "&#{CGI::escape(key.to_s)}=" + CGI::escape(value.to_s)
268
364
  end
269
365
  end
270
366
 
@@ -342,7 +438,7 @@ class Browshot
342
438
  http.open_timeout = 240
343
439
  http.read_timeout = 240
344
440
 
345
- request = Net::HTTP::Get.new(uri.request_uri, {'User-Agent' => 'Browshot Ruby 1.14'})
441
+ request = Net::HTTP::Get.new(uri.request_uri, {'User-Agent' => "Browshot Ruby #{VERSION}"})
346
442
  if (uri.scheme == 'https')
347
443
  http.use_ssl = true
348
444
  http.verify_mode = OpenSSL::SSL::VERIFY_NONE
@@ -377,9 +473,9 @@ class Browshot
377
473
  post_body << File.read(file)
378
474
  post_body << "\r\n--#{boundary}--\r\n"
379
475
 
380
- request = Net::HTTP::Post.new(uri.request_uri, {'User-Agent' => 'Browshot Ruby 1.14'})
476
+ request = Net::HTTP::Post.new(uri.request_uri, {'User-Agent' => "Browshot Ruby #{VERSION}"})
381
477
  request.body = post_body.join
382
- request["Content-Type"] = "multipart/form-data, boundary=#{boundary}"
478
+ request["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
383
479
 
384
480
  if (uri.scheme == 'https')
385
481
  http.use_ssl = true
data/test/helper.rb CHANGED
@@ -1,22 +1,19 @@
1
- require 'rubygems'
2
- require 'shoulda'
3
- require 'bundler'
4
-
5
- begin
6
- Bundler.setup(:default, :development)
7
- rescue Bundler::BundlerError => e
8
- $stderr.puts e.message
9
- $stderr.puts "Run `bundle install` to install missing gems"
10
- exit e.status_code
11
- end
12
-
13
- require 'rubygems'
14
1
  require 'test/unit'
15
- # require 'shoulda'
2
+ require 'shoulda/context'
16
3
 
17
- $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
18
- $LOAD_PATH.unshift(File.dirname(__FILE__))
19
- require 'browshot'
4
+ require_relative '../lib/browshot'
20
5
 
21
6
  class Test::Unit::TestCase
7
+ def live_browshot
8
+ key = ENV['BROWSHOT_API_KEY']
9
+ omit('Set BROWSHOT_API_KEY for live tests') if key.nil? || key.empty?
10
+ Browshot.new(key)
11
+ end
12
+
13
+ def fixture_id(name)
14
+ variable = "BROWSHOT_#{name.upcase}_ID"
15
+ id = ENV[variable]
16
+ omit("Set #{variable} to an owned test capture ID") if id.nil? || id.empty?
17
+ id
18
+ end
22
19
  end