renderscreenshot 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 866ece0d8812f0d70751db71d9746530c4e4b0f95a39624f569672b93688137b
-  data.tar.gz: a6d705614f59526337dc55e852075ed21030f66e2a71c17a94895db00386993a
+  metadata.gz: 31b7d11d24a55a5e7ffae6e8ba80c81433d20b81ae82d95866eb56acb3e8613f
+  data.tar.gz: d3a1dc0bb1a01470d761ff05873fdaa9d8ae402ac56c9f0349705a09d685a08b
 SHA512:
-  metadata.gz: f8a11440d6feb0739526fe945732ed2c12e0e0130476c48b6c96d544d98fa70b41c1a9d982e621a42046f42cf0d2bd4b8ffe2d1ef2c618163318a8a4e3b3355d
-  data.tar.gz: 11cc424b00ae6727181f580118644a01aa2bb29ddf7554d8a8768e7ebf6bdf410cf862b8728abee757d6d484f30d76fd7f0973ff8e4b31a349249579f1885d48
+  metadata.gz: 380f44cd4faee08b39073403dcff73167a02df5acc368b426402d412da18503dbe3b8a03c477bfa2053916f5d5820a019458aff83fd7598bb908aab453c22869
+  data.tar.gz: b756575692352f742ba194cfc653cdcd95c883e114bae180053fb3d4c983e67b3cd0a6f217d14dcb75e24030b1e0e511b8fcbed05342af95196e3ebb84f12ad7

data/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] - 2026-10-18
+
+### Added
+
+- `TakeOptions#cache_available` sets `cache.available` (GET: `cache_available`).
+  The API reuses a cached screenshot only when this is set.
+- `TakeOptions#to_query_params` returns the flat GET parameters as a hash.
+
+### Fixed
+
+- `pdf_print_background` now sends `pdf.print_background`. Before, it sent
+  `pdf.background`, which the API ignores.
+- `pdf_margin_top`/`_right`/`_bottom`/`_left` now send flat `pdf.margin_top`,
+  `pdf.margin_right`, `pdf.margin_bottom` and `pdf.margin_left`. Before, they
+  sent a nested `pdf.margin` hash, which the API drops. `pdf_margin` still
+  sends `pdf.margin`, and the per-side values can be combined with it.
+- `device` is now sent as the top-level `device` parameter, which POST and GET
+  both read. Before, it was sent as `viewport.device`.
+- `generate_url` now uses the GET parameter names (`selector`, `timeout`,
+  `block_cookies`, `pdf_paper`, ...). Before, it flattened the builder's own
+  names (`element`, `wait_for`, `block_cookie_banners`, ...), which GET does
+  not read. Options that GET cannot express are left out of the URL.
+- `to_query_string` covers every GET parameter, and its pairs are sorted and
+  encoded like Rails `to_query`.
+- Docs: `wait_for_timeout` is in seconds (the API clamps it to 1-60), not
+  milliseconds. The devices example reads `viewport.width`/`viewport.height`.
+
 ## [1.0.0] - 2026-02-24
 
 ### Added

data/README.md

@@ -120,6 +120,7 @@ options = RenderScreenshot::TakeOptions
   .wait_for('networkidle')
   .delay(500)
   .wait_for_selector('.loaded')
+  .wait_for_timeout(30)  # seconds; the API clamps it to 1-60
   # Blocking
   .block_ads
   .block_trackers
@@ -188,13 +189,40 @@ options = RenderScreenshot::TakeOptions
   .url('https://example.com')
   .preset('og_card')
 
-# URL expires in 24 hours
+# URL expires in 24 hours (the API accepts at most 30 days)
 signed_url = client.generate_url(options, expires_at: Time.now + 86400)
 
 # Use in HTML
 # <img src="#{signed_url}" />
 ```
 
+Signing needs your public key ID (`rs_pub_*`) and secret key (`rs_secret_*`):
+pass `signing_key:` and `public_key_id:` to `Client.new` or to `generate_url`.
+
+A signed URL is a `GET /v1/screenshot` request, so it carries only the options
+that GET reads as query parameters: `url`, `html`, `preset`, `device`, `width`,
+`height`, `scale`, `full_page`, `element` (sent as `selector`), `format`,
+`quality`, `delay`, `wait_for_timeout` (sent as `timeout`), `click`, `hide`,
+`remove`, `block_ads`, `block_cookie_banners` (sent as `block_cookies`),
+`dark_mode`, `user_agent`, `locale`, `timezone`, `cache_ttl`, `cache_refresh`,
+`cache_available` and the `pdf_*` options. Other options (for example `mobile`,
+`wait_for`, `wait_for_selector`, `block_trackers`, network and storage options)
+are left out of the URL. Use `take` or `take_json` (POST) for those.
+`TakeOptions#to_query_params` and `#to_query_string` give the same mapping.
+
+### Cache Reuse
+
+The API serves a previous screenshot (0 credits) only when the request sets
+`cache_available`. Otherwise every request renders a new screenshot.
+
+```ruby
+options = RenderScreenshot::TakeOptions
+  .url('https://example.com')
+  .preset('og_card')
+  .cache_available        # reuse a render with the same options
+  .cache_ttl(86_400)      # look back up to 24 hours (seconds)
+```
+
 ### Cache Management
 
 ```ruby
@@ -231,7 +259,7 @@ preset = client.preset('og_card')
 
 # List all devices
 devices = client.devices
-devices.each { |d| puts "#{d['id']}: #{d['name']} (#{d['width']}x#{d['height']})" }
+devices.each { |d| puts "#{d['id']}: #{d['name']} (#{d['viewport']['width']}x#{d['viewport']['height']})" }
 ```
 
 ### Webhook Verification
@@ -311,10 +339,13 @@ Error properties:
 | **Page** | `inject_script`, `inject_style`, `click`, `hide`, `remove` |
 | **Browser** | `dark_mode`, `reduced_motion`, `media_type`, `user_agent`, `timezone`, `locale`, `geolocation` |
 | **Network** | `headers`, `cookies`, `auth_basic`, `auth_bearer`, `bypass_csp` |
-| **Cache** | `cache_ttl`, `cache_refresh` |
+| **Cache** | `cache_ttl`, `cache_refresh`, `cache_available` |
 | **PDF** | `pdf_paper_size`, `pdf_width`, `pdf_height`, `pdf_landscape`, `pdf_margin`, `pdf_margin_top`, `pdf_margin_right`, `pdf_margin_bottom`, `pdf_margin_left`, `pdf_scale`, `pdf_print_background`, `pdf_page_ranges`, `pdf_header`, `pdf_footer`, `pdf_fit_one_page`, `pdf_prefer_css_page_size` |
 | **Storage** | `storage_enabled`, `storage_path`, `storage_acl` |
 
+Units: `delay` is in milliseconds (max 10000). `wait_for_timeout` is in seconds
+(the API clamps it to 1-60). `cache_ttl` is in seconds (3600-2592000).
+
 ## Development
 
 After checking out the repo:
@@ -349,7 +380,7 @@ The hooks include:
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/renderscreenshot/renderscreenshot-ruby.
+Bug reports and pull requests are welcome on GitHub at https://github.com/Render-Screenshot/rs-ruby.
 
 ## License
 

data/lib/renderscreenshot/client.rb

@@ -9,7 +9,7 @@ module RenderScreenshot
     attr_reader :http
 
     # Initialize a new client
-    # @param api_key [String] API key (rs_live_*, rs_test_*)
+    # @param api_key [String] API key (rs_live_*)
     # @param base_url [String, nil] Custom base URL
     # @param timeout [Integer, nil] Request timeout in seconds
     # @param signing_key [String, nil] Secret key for signed URLs (rs_secret_*)
@@ -64,11 +64,12 @@ module RenderScreenshot
         )
       end
 
-      config = options.is_a?(TakeOptions) ? options.to_h : options
+      take_options = options.is_a?(TakeOptions) ? options : TakeOptions.from(options || {})
       expires = expires_at.is_a?(Time) ? expires_at.to_i : expires_at
 
-      # Build query params in alphabetical order (required for signature verification)
-      params = build_signed_params(config, key_id, expires)
+      # Signed URLs carry only the parameters GET /v1/screenshot reads.
+      # Pairs are sorted and encoded like Rails `to_query` (required for signature verification).
+      params = take_options.to_query_params.merge('expires' => expires.to_s, 'key_id' => key_id)
       query_string = params.sort.map { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join('&')
 
       # Sign with HMAC-SHA256 using the secret key
@@ -154,48 +155,5 @@ module RenderScreenshot
         raise ValidationError.invalid_request('Options must be a TakeOptions or Hash')
       end
     end
-
-    def build_signed_params(config, key_id, expires)
-      params = {}
-
-      # Add expires first (alphabetically before key_id)
-      params['expires'] = expires
-
-      # Add key_id (public identifier)
-      params['key_id'] = key_id
-
-      # Add URL or html
-      params['url'] = config[:url] if config[:url]
-      params['html'] = config[:html] if config[:html]
-
-      # Add other params
-      flat_params = flatten_config(config)
-      flat_params.each do |key, value|
-        next if %w[url html].include?(key)
-
-        params[key] = value
-      end
-
-      params
-    end
-
-    def flatten_config(config)
-      result = {}
-      config.each do |key, value|
-        next if value.nil?
-
-        str_key = key.to_s
-        if value.is_a?(Hash)
-          value.each do |sub_key, sub_value|
-            result["#{str_key}_#{sub_key}"] = sub_value unless sub_value.nil?
-          end
-        elsif value.is_a?(Array)
-          result[str_key] = value.join(',')
-        else
-          result[str_key] = value
-        end
-      end
-      result
-    end
   end
 end

data/lib/renderscreenshot/take_options.rb

@@ -72,6 +72,7 @@ module RenderScreenshot
       with(wait_for_selector: selector)
     end
 
+    # Maximum wait time in seconds (the API clamps it to 1-60)
     def wait_for_timeout(value)
       with(wait_for_timeout: value)
     end
@@ -192,6 +193,12 @@ module RenderScreenshot
       with(cache_refresh: value)
     end
 
+    # Serve a previous screenshot with the same options when one exists.
+    # The API reuses a cached render only when this is set.
+    def cache_available(value = true)
+      with(cache_available: value)
+    end
+
     # PDF methods
     def pdf_paper_size(value)
       with(pdf_paper_size: value)
@@ -280,13 +287,13 @@ module RenderScreenshot
       result = {}
 
       # Top-level params
-      %i[url html preset].each do |key|
+      %i[url html preset device].each do |key|
         result[key] = config[key] if config.key?(key)
       end
 
       # Viewport group
       viewport = {}
-      { width: :width, height: :height, scale: :scale, mobile: :mobile, device: :device }.each do |config_key, api_key|
+      { width: :width, height: :height, scale: :scale, mobile: :mobile }.each do |config_key, api_key|
         viewport[api_key] = config[config_key] if config.key?(config_key)
       end
       result[:viewport] = viewport unless viewport.empty?
@@ -357,6 +364,7 @@ module RenderScreenshot
       cache = {}
       cache[:ttl] = config[:cache_ttl] if config[:cache_ttl]
       cache[:refresh] = config[:cache_refresh] if config.key?(:cache_refresh)
+      cache[:available] = config[:cache_available] if config.key?(:cache_available)
       result[:cache] = cache unless cache.empty?
 
       # PDF group
@@ -366,25 +374,18 @@ module RenderScreenshot
       pdf[:height] = config[:pdf_height] if config[:pdf_height]
       pdf[:landscape] = config[:pdf_landscape] if config.key?(:pdf_landscape)
       pdf[:scale] = config[:pdf_scale] if config[:pdf_scale]
-      pdf[:background] = config[:pdf_print_background] if config.key?(:pdf_print_background)
+      pdf[:print_background] = config[:pdf_print_background] if config.key?(:pdf_print_background)
       pdf[:page_ranges] = config[:pdf_page_ranges] if config[:pdf_page_ranges]
       pdf[:header] = config[:pdf_header] if config[:pdf_header]
       pdf[:footer] = config[:pdf_footer] if config[:pdf_footer]
       pdf[:fit_one_page] = config[:pdf_fit_one_page] if config.key?(:pdf_fit_one_page)
       pdf[:prefer_css_page_size] = config[:pdf_prefer_css_page_size] if config.key?(:pdf_prefer_css_page_size)
 
-      # PDF margins - supports uniform margin (string like "2cm") or individual margins (hash)
-      if config[:pdf_margin]
-        # Uniform margin specified - use directly (string or hash)
-        pdf[:margin] = config[:pdf_margin]
-      else
-        # Build margin hash from individual margin settings
-        margin = {}
-        margin[:top] = config[:pdf_margin_top] if config[:pdf_margin_top]
-        margin[:right] = config[:pdf_margin_right] if config[:pdf_margin_right]
-        margin[:bottom] = config[:pdf_margin_bottom] if config[:pdf_margin_bottom]
-        margin[:left] = config[:pdf_margin_left] if config[:pdf_margin_left]
-        pdf[:margin] = margin unless margin.empty?
+      # PDF margins: a uniform `margin` plus optional per-side overrides
+      pdf[:margin] = config[:pdf_margin] if config[:pdf_margin]
+      %i[top right bottom left].each do |side|
+        key = :"pdf_margin_#{side}"
+        pdf[:"margin_#{side}"] = config[key] if config[key]
       end
       result[:pdf] = pdf unless pdf.empty?
 
@@ -398,39 +399,44 @@ module RenderScreenshot
       result
     end
 
-    # Convert to flat query string for GET requests
-    def to_query_string
-      params = []
-
-      # Map config keys to query param names
-      query_mappings = {
-        url: 'url',
-        html: 'html',
-        preset: 'preset',
-        width: 'width',
-        height: 'height',
-        device: 'device',
-        scale: 'scale',
-        full_page: 'full_page',
-        element: 'selector',
-        format: 'format',
-        quality: 'quality',
-        delay: 'delay',
-        wait_for_timeout: 'timeout',
-        block_ads: 'block_ads',
-        block_cookie_banners: 'block_cookies',
-        dark_mode: 'dark_mode',
-        cache_ttl: 'cache_ttl'
-      }
-
-      query_mappings.each do |config_key, param_name|
-        next unless config.key?(config_key)
+    # GET /v1/screenshot query parameter names, keyed by config key
+    QUERY_PARAM_NAMES = {
+      url: 'url', html: 'html', preset: 'preset', device: 'device',
+      width: 'width', height: 'height', scale: 'scale',
+      full_page: 'full_page', element: 'selector', format: 'format', quality: 'quality',
+      delay: 'delay', wait_for_timeout: 'timeout',
+      click: 'click', hide: 'hide', remove: 'remove',
+      block_ads: 'block_ads', block_cookie_banners: 'block_cookies',
+      dark_mode: 'dark_mode', user_agent: 'user_agent', locale: 'locale', timezone: 'timezone',
+      cache_ttl: 'cache_ttl', cache_refresh: 'cache_refresh', cache_available: 'cache_available',
+      pdf_paper_size: 'pdf_paper', pdf_width: 'pdf_width', pdf_height: 'pdf_height',
+      pdf_landscape: 'pdf_landscape', pdf_scale: 'pdf_scale', pdf_fit_one_page: 'pdf_fit_one_page',
+      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_print_background: 'pdf_print_background', pdf_prefer_css_page_size: 'pdf_prefer_css_page_size',
+      pdf_page_ranges: 'pdf_page_ranges', pdf_header: 'pdf_header', pdf_footer: 'pdf_footer'
+    }.freeze
+
+    # Convert to flat query parameters for GET requests and signed URLs.
+    #
+    # Uses the parameter names that GET /v1/screenshot reads. Options with no
+    # GET equivalent (for example mobile, wait_for, wait_for_selector,
+    # block_trackers, block_urls, media_type, network, storage and page
+    # injection options) are left out. Use take / take_json (POST) for those.
+    # @return [Hash{String => String}]
+    def to_query_params
+      QUERY_PARAM_NAMES.each_with_object({}) do |(config_key, param_name), params|
+        next unless config.key?(config_key) && !config[config_key].nil?
 
         value = config[config_key]
-        params << "#{param_name}=#{CGI.escape(value.to_s)}"
+        params[param_name] = value.is_a?(Array) ? value.join(',') : value.to_s
       end
+    end
 
-      params.join('&')
+    # Convert to a flat query string for GET requests.
+    # Pairs are sorted and values are form-encoded like Rails `to_query`.
+    def to_query_string
+      to_query_params.sort.map { |k, v| "#{CGI.escape(k)}=#{CGI.escape(v)}" }.join('&')
     end
 
     private

data/lib/renderscreenshot/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RenderScreenshot
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: renderscreenshot
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
-- Michael Brooks
+- Simon Chiu
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -32,7 +32,7 @@ dependencies:
 description: A developer-friendly screenshot API for capturing web pages programmatically.
   Create social cards, link previews, documentation screenshots, and more.
 email:
-- michael@renderscreenshot.com
+- simon@renderscreenshot.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -78,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Official Ruby SDK for RenderScreenshot API
 test_files: []