From 870431b7fb366529bd34a03e54ce72f4c2718aea Mon Sep 17 00:00:00 2001 From: jsneedles Date: Mon, 16 Nov 2026 16:11:24 -0500 Subject: [PATCH 1/2] add recordings support --- Gemfile.lock | 2 +- README.md | 101 + docs/HTMLCSSToImage.html | 2382 ++++++++++++----- docs/HTMLCSSToImage/ApiResponse.html | 4 +- .../RequestOverrideResourceType.html | 432 +++ docs/_index.html | 19 +- docs/class_list.html | 2 +- docs/file.README.html | 83 +- docs/index.html | 83 +- docs/method_list.html | 88 +- docs/top-level-namespace.html | 4 +- htmlcsstoimage.gemspec | 2 +- lib/htmlcsstoimage.rb | 1 + lib/htmlcsstoimage/client.rb | 2 +- lib/htmlcsstoimage/recordings.rb | 108 + lib/htmlcsstoimage/version.rb | 2 +- spec/recordings_spec.rb | 232 ++ 17 files changed, 2863 insertions(+), 684 deletions(-) create mode 100644 docs/HTMLCSSToImage/RequestOverrideResourceType.html create mode 100644 lib/htmlcsstoimage/recordings.rb create mode 100644 spec/recordings_spec.rb diff --git a/Gemfile.lock b/Gemfile.lock index acdb79d..38304a1 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,7 +1,7 @@ PATH remote: . specs: - htmlcsstoimage-api (0.5.0) + htmlcsstoimage-api (1.0.0) addressable (> 2.5.0) httparty (> 0.10) diff --git a/README.md b/README.md index c539de4..1a6656e 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,107 @@ images = client.create_image_batch( ) ``` +## Recordings + +Record HTML/CSS or a public webpage as MP4, WebM, or GIF. Use +`create_html_css_recording` for HTML/CSS and `create_url_recording` for a webpage: + +```ruby +recording = client.create_url_recording( + "https://example.com", + duration_ms: 10000, + viewport_width: 1280, + viewport_height: 720, + actions: [{ type: "simple_scroll" }], + output: { format: "mp4" } +) + +recording.id +recording.status_url +recording.recording_url + +animation = client.create_html_css_recording( + "

Hello

", + css: "@keyframes fade { from { opacity: 0; } to { opacity: 1; } } h1 { animation: fade 2s; font-family: Roboto; }", + google_fonts: "Roboto", + duration_ms: 3000, + duration_mode: "fixed", + output: { format: "gif", scale: 0.5 } +) +``` + +Both methods accept browser, timeline, and output options as hashes, following +the image methods. Options pass through to the API without local validation. +Omitted settings use API defaults. Recordings do not include audio. + +Triggers and actions use a `type` discriminator. For example, wait until an +element is visible, click a button, and hold the result: + +```ruby +demo = client.create_url_recording( + "https://example.com/demo", + duration_ms: 5000, + duration_mode: "fixed", + trigger: { type: "element_visible", selector: "#demo", timeout_ms: 2000 }, + actions: [ + { type: "click", selector: "#start", if_not_found: [{ type: "error" }] }, + { type: "stall", duration_ms: 1000 } + ] +) +``` + +Nested branches run on the API. For JavaScript actions, omitting `if_error` or +setting it to `nil` fails on a script error; `if_error: []` ignores errors. +Empty arrays, explicit `nil`, `false`, and zero values are preserved in JSON. + +A `scroll` action moves through ordered `steps`. Each step's `duration_ms` is +required and must be at least 1: + +```ruby +client.create_url_recording( + "https://example.com", + duration_ms: 6000, + actions: [ + { type: "scroll", steps: [ + { to: { type: "selector", selector: "#pricing" }, duration_ms: 1200, easing: "ease_in_out_cubic" }, + { to: { type: "position", position: "bottom" }, duration_ms: 1500 } + ] } + ] +) +``` + +Embed or request `recording_url` directly; the request waits until the +recording is ready, so checking status is optional. To inspect progress, fetch +the current status once with: + +```ruby +status = client.fetch_recording_status(recording.id) +puts status.status +puts status.attempt_count +``` + +HTTP 200 and 202 both return status information. The states `ready`, `failed`, +and `cancelled` are terminal. A successful status fetch can report a failed +recording, and `status.error` can describe an earlier, retryable attempt. +`status.status` is the raw API string. Treat values not listed here, which +newer API versions may add, as unknown; the client passes them through as-is. +API errors and transport failures follow the existing image-method behavior. + +Delete recordings individually or in a batch: + +```ruby +client.delete_recording("recording-id") +client.delete_recording_batch(["first-id", "second-id"]) +``` + +Deletion returns `true` when accepted, or the API response on failure. Empty +batch lists succeed without an API request, matching `delete_image_batch`. + +See the [recording guide](https://docs.htmlcsstoimage.com/getting-started/recordings/), +[actions reference](https://docs.htmlcsstoimage.com/parameters/actions/), and +[trigger reference](https://docs.htmlcsstoimage.com/parameters/trigger/) for +options and examples. + ## Signed URLs Signed URLs let another application, browser, or service render an image on diff --git a/docs/HTMLCSSToImage.html b/docs/HTMLCSSToImage.html index 5c7b0c8..274e89b 100644 --- a/docs/HTMLCSSToImage.html +++ b/docs/HTMLCSSToImage.html @@ -102,7 +102,7 @@
Defined in:
lib/htmlcsstoimage/client.rb,
- lib/htmlcsstoimage/images.rb,
lib/htmlcsstoimage/version.rb,
lib/htmlcsstoimage/templates.rb,
lib/htmlcsstoimage/signed_urls.rb
+ lib/htmlcsstoimage/images.rb,
lib/htmlcsstoimage/version.rb,
lib/htmlcsstoimage/templates.rb,
lib/htmlcsstoimage/recordings.rb,
lib/htmlcsstoimage/signed_urls.rb,
lib/htmlcsstoimage/request_override_resource_type.rb
@@ -111,7 +111,7 @@

Overview

-

Client for creating images and managing templates with HTML/CSS to Image.

+

Named browser resource types for request_overrides rules.

@@ -124,7 +124,7 @@

Overview

- Classes: ApiResponse + Classes: ApiResponse, RequestOverrideResourceType

@@ -149,7 +149,7 @@

-
"0.3.0"
+
"1.0.0"
@@ -171,6 +171,28 @@

  • + #create_html_css_recording(html, params = {}) ⇒ HTMLCSSToImage::ApiResponse + + + + + + + + + + + + + +

    Records an HTML document or fragment with optional CSS and Google Fonts.

    + +
  • + + +
  • + + #create_image(html, params = {}) ⇒ HTMLCSSToImage::ApiResponse @@ -303,6 +325,50 @@

  • + #create_templated_image_batch(variations, default_options = nil) ⇒ HTMLCSSToImage::ApiResponse + + + + + + + + + + + + + +

    Creates images from one or more templates in a single request.

    + +
  • + + +
  • + + + #create_url_recording(url, params = {}) ⇒ HTMLCSSToImage::ApiResponse + + + + + + + + + + + + + +

    Records a public HTTP or HTTPS webpage.

    + +
  • + + +
  • + + #delete_image(image_id) ⇒ Boolean, HTMLCSSToImage::ApiResponse @@ -347,6 +413,72 @@

  • + #delete_recording(recording_id) ⇒ true, HTTParty::Response + + + + + + + + + + + + + +

    Deletes a recording and clears its media from the CDN.

    + +
  • + + +
  • + + + #delete_recording_batch(recording_ids) ⇒ true, HTTParty::Response + + + + + + + + + + + + + +

    Deletes several recordings in one API request.

    + +
  • + + +
  • + + + #fetch_recording_status(recording_id) ⇒ HTMLCSSToImage::ApiResponse + + + + + + + + + + + + + +

    Fetches a recording's current lifecycle state once.

    + +
  • + + +
  • + + #generate_create_and_render_url(url, params = {}) ⇒ HTMLCSSToImage::ApiResponse @@ -600,9 +732,9 @@

    Instance Method Details

    -

    +

    - #create_image(html, params = {}) ⇒ HTMLCSSToImage::ApiResponse + #create_html_css_recording(html, params = {}) ⇒ HTMLCSSToImage::ApiResponse @@ -610,7 +742,9 @@

    -

    Converts HTML/CSS to an image with the API.

    +

    Records an HTML document or fragment with optional CSS and Google Fonts. +Returns the recording ID, status URL, and media URL while rendering can +continue in the background. Optional settings use the API defaults.

    @@ -628,7 +762,7 @@

    — -

    HTML to render, as a snippet or an entire webpage

    +

    HTML to record, as a fragment or a complete document

  • @@ -644,7 +778,7 @@

    — -

    image creation options

    +

    browser, timeline, and output options passed to the API

  • @@ -659,13 +793,13 @@

    • - :format - (String) + :duration_ms + (Integer) - —

      The format used in the initially returned URL: png, jpg, webp, or pdf. This does not change the stored image definition or prevent rendering another supported format later.

      + —

      Required recording duration in milliseconds: 500–30000, or up to 90000 in target mode.

    • @@ -676,18 +810,7 @@

      - —

      The CSS for your image.

      - - - -
    • - :device_scale - (Numeric) - - - - - —

      The pixel ratio for the screenshot. Minimum: 0.1, Maximum: 3.

      + —

      CSS used to style the recording.

    • @@ -698,238 +821,227 @@

      - —

      Google Fonts to load. Separate multiple fonts with |.

      + —

      Google Fonts to load, separated by |. Set font-family in the CSS to use them.

    • - :max_wait_ms - (Integer) + :device_scale + (Numeric) - —

      The maximum time to wait before taking the screenshot. Minimum: 500, Maximum: 10000.

      + —

      Capture pixel density. HTML/CSS defaults to 2; URL recordings default to 1.

    • - :ms_delay + :viewport_height (Integer) - —

      Extra time in milliseconds to wait before taking the screenshot. Maximum: 10000.

      + —

      Chrome viewport height in CSS pixels. Supply both viewport dimensions to set the recording size.

    • - :render_when_ready - (Boolean) + :viewport_width + (Integer) - —

      Wait until ScreenshotReady() is called from JavaScript before taking the screenshot.

      + —

      Chrome viewport width in CSS pixels. Supply both viewport dimensions to set the recording size.

    • - :selector - (String) + :disable_twemoji + (Boolean) - —

      A CSS selector for the element to capture.

      + —

      True disables Twemoji for HTML/CSS. URL recordings inject Twemoji only when explicitly false.

    • - :viewport_height + :dedupe_duration_s (Integer) - —

      The Chrome viewport height. Both viewport dimensions must be set if using either.

      + —

      Reuse an identical recent recording for this many seconds. Set to 0 to disable deduplication.

    • - :viewport_width - (Integer) + :color_scheme + (String) - —

      The Chrome viewport width. Both viewport dimensions must be set if using either.

      + —

      Chrome's preferred color scheme: light or dark.

    • - :pdf_options - (Hash) + :timezone + (String) - —

      Options for generating a PDF, including page size, margins, scale, and background printing.

      + —

      Browser timezone as an IANA identifier, such as America/New_York.

    • - :disable_twemoji + :viewport_mobile (Boolean) - —

      Disable the Twemoji fallback and use native emoji fonts.

      + —

      Enable mobile viewport behavior, including the page's viewport meta tag.

    • - :max_render_once + :viewport_landscape (Boolean) - —

      Ensure the image is only rendered and saved once.

      + —

      Emulate landscape orientation.

    • - :dedupe_duration_s - (Integer) + :viewport_touch + (Boolean) - —

      Reuse an identical image created within this many seconds. Only supported for single-image POST requests.

      + —

      Emulate touch support.

    • - :color_scheme + :media_type (String) - —

      Render using the light or dark browser color scheme.

      + —

      CSS media type used while recording: print or screen.

    • - :timezone + :proxy_id (String) - —

      The browser timezone as an IANA timezone identifier, such as America/New_York.

      + —

      Configured organization proxy to use while recording.

    • - :viewport_mobile - (Boolean) + :storage_destination_id + (String) - —

      Whether to honor the page's mobile viewport behavior.

      + —

      Configured storage destination to receive the recording.

    • - :viewport_landscape - (Boolean) + :request_overrides + (Array<Hash>) - —

      Whether to render the viewport in landscape mode.

      + —

      Browser request block rules. Requires a paid plan.

    • - :viewport_touch - (Boolean) + :trigger + (Hash) - —

      Whether the viewport supports touch events.

      + —

      Start condition: type: "immediate" (default), "element_visible" with a selector, or "function_call" to wait for window.RecordingReady(). Waiting triggers accept timeout_ms.

    • - :media_type - (String) + :actions + (Array<Hash>) - —

      Render using print or screen media.

      + —

      Ordered timeline interactions: simple_scroll, scroll, stall, click, locate_selector, execute_javascript, or error. Each action has a type discriminator. Omit or use an empty array to record without interactions.

    • - :proxy_id - (String) + :output + (Hash) - —

      The ID of an organization proxy to use for the render.

      + —

      Media format (mp4, webm, or gif), fps, and pixel scale. Defaults to MP4 at 30 fps; GIF defaults to 15 fps. Recordings have no audio.

    • - :storage_destination_id + :duration_mode (String) - —

      The ID of an organization storage destination for the rendered image.

      - -
    • - -
    • - :jumbo_max_height - (Integer) - - - - - —

      Maximum output height in jumbo mode. Requires jumbo_max_width.

      + —

      at_most (default) stops when actions finish or the duration is reached. fixed pads or cuts off at that duration. at_least lets actions finish up to 90 seconds. target adjusts playback speed to fit the duration.

    • - :jumbo_max_width - (Integer) + :defer_render + (Boolean) - —

      Maximum output width in jumbo mode. Requires jumbo_max_height.

      + —

      Wait to render until media or storage is requested. Defaults to false; does not reset deduplicated recordings.

    • - :transparent_background + :skip_scroll_preload (Boolean) - —

      Whether to render the image with a transparent background.

      + —

      Skip the preparation scroll that loads lazy content. Scrolling actions still run. Defaults to false.

    • @@ -947,7 +1059,7 @@

      — -

      image details, including .url

      +

      recording details at .id, .status_url, and .recording_url

      @@ -956,7 +1068,13 @@

      See Also:

      @@ -966,21 +1084,19 @@

       
       
      -34
      -35
      -36
       37
       38
      -39
      +39 +40 +41 -
      # File 'lib/htmlcsstoimage/images.rb', line 34
      +      
      # File 'lib/htmlcsstoimage/recordings.rb', line 37
       
      -def create_image(html, params = {})
      +def create_html_css_recording(html, params = {})
         body = { html: html }.merge(params).to_json
      -  options = { basic_auth: @auth, body: body, query: { includeId: true } }
       
      -  self.class.post("/v1/image", options)
      +  self.class.post("/v1/recording", basic_auth: @auth, body: body)
       end
      @@ -988,9 +1104,9 @@

      -

      +

      - #create_image_batch(variations, default_options = nil) ⇒ HTMLCSSToImage::ApiResponse + #create_image(html, params = {}) ⇒ HTMLCSSToImage::ApiResponse @@ -998,8 +1114,7 @@

      -

      Creates several HTML/CSS or URL images in one API request.

      -

      Templates are not supported in batch requests.

      +

      Converts HTML/CSS to an image with the API.

      @@ -1009,31 +1124,1130 @@

    • - variations + html - (Array<Hash>) + (String) — -

      per-image values

      +

      HTML to render, as a snippet or an entire webpage

    • - default_options - - - (Hash, nil) + params - (defaults to: nil) + (Hash) - — + (defaults to: {}) + + + — +

      image creation options

      + +
    • + +

    + + + + + + +

    Options Hash (params):

    +
      + +
    • + :format + (String) + + + + + —

      The format used in the initially returned URL: png, jpg, webp, or pdf. This does not change the stored image definition or prevent rendering another supported format later.

      + +
    • + +
    • + :css + (String) + + + + + —

      The CSS for your image.

      + +
    • + +
    • + :device_scale + (Numeric) + + + + + —

      The pixel ratio for the screenshot. Minimum: 0.1, Maximum: 3.

      + +
    • + +
    • + :google_fonts + (String) + + + + + —

      Google Fonts to load. Separate multiple fonts with |.

      + +
    • + +
    • + :max_wait_ms + (Integer) + + + + + —

      The maximum time to wait before taking the screenshot. Minimum: 500, Maximum: 10000.

      + +
    • + +
    • + :ms_delay + (Integer) + + + + + —

      Extra time in milliseconds to wait before taking the screenshot. Maximum: 10000.

      + +
    • + +
    • + :render_when_ready + (Boolean) + + + + + —

      Wait until ScreenshotReady() is called from JavaScript before taking the screenshot.

      + +
    • + +
    • + :selector + (String) + + + + + —

      A CSS selector for the element to capture.

      + +
    • + +
    • + :viewport_height + (Integer) + + + + + —

      The Chrome viewport height. Both viewport dimensions must be set if using either.

      + +
    • + +
    • + :viewport_width + (Integer) + + + + + —

      The Chrome viewport width. Both viewport dimensions must be set if using either.

      + +
    • + +
    • + :pdf_options + (Hash) + + + + + —

      Options for generating a PDF, including page size, margins, scale, and background printing.

      + +
    • + +
    • + :disable_twemoji + (Boolean) + + + + + —

      For HTML/CSS, true disables default Twemoji replacement. For URLs, only explicit false injects Twemoji; omitted or true leaves the page unchanged.

      + +
    • + +
    • + :max_render_once + (Boolean) + + + + + —

      Ensure the image is only rendered and saved once.

      + +
    • + +
    • + :dedupe_duration_s + (Integer) + + + + + —

      Reuse an identical image created within this many seconds. Only supported for single-image POST requests.

      + +
    • + +
    • + :color_scheme + (String) + + + + + —

      Render using the light or dark browser color scheme.

      + +
    • + +
    • + :timezone + (String) + + + + + —

      The browser timezone as an IANA timezone identifier, such as America/New_York.

      + +
    • + +
    • + :viewport_mobile + (Boolean) + + + + + —

      Whether to honor the page's mobile viewport behavior.

      + +
    • + +
    • + :viewport_landscape + (Boolean) + + + + + —

      Whether to render the viewport in landscape mode.

      + +
    • + +
    • + :viewport_touch + (Boolean) + + + + + —

      Whether the viewport supports touch events.

      + +
    • + +
    • + :media_type + (String) + + + + + —

      Render using print or screen media.

      + +
    • + +
    • + :proxy_id + (String) + + + + + —

      The ID of an organization proxy to use for the render.

      + +
    • + +
    • + :request_overrides + (Array<Hash>) + + + + + —

      Browser request block rules, such as { action: "block", resource_types: [RequestOverrideResourceType::Script] }. Requires a paid plan.

      + +
    • + +
    • + :storage_destination_id + (String) + + + + + —

      The ID of an organization storage destination for the rendered image.

      + +
    • + +
    • + :jumbo_max_height + (Integer) + + + + + —

      Maximum output height in jumbo mode. Requires jumbo_max_width.

      + +
    • + +
    • + :jumbo_max_width + (Integer) + + + + + —

      Maximum output width in jumbo mode. Requires jumbo_max_height.

      + +
    • + +
    • + :transparent_background + (Boolean) + + + + + —

      Whether to render the image with a transparent background.

      + +
    • + +
    + + +

    Returns:

    + + +

    See Also:

    + + + + + + + +
    +
    +
    +
    +35
    +36
    +37
    +38
    +39
    +40
    +
    +
    # File 'lib/htmlcsstoimage/images.rb', line 35
    +
    +def create_image(html, params = {})
    +  body = { html: html }.merge(params).to_json
    +  options = { basic_auth: @auth, body: body, query: { includeId: true } }
    +
    +  self.class.post("/v1/image", options)
    +end
    +
    + + +
    +

    + + #create_image_batch(variations, default_options = nil) ⇒ HTMLCSSToImage::ApiResponse + + + + + +

    +
    +

    Creates several HTML/CSS or URL images in one API request.

    +

    For template batches, use #create_templated_image_batch.

    + +
    +
    +
    +

    Parameters:

    +
      + +
    • + + variations + + + (Array<Hash>) + + + + — +

      per-image values

      + +
    • + +
    • + + default_options + + + (Hash, nil) + + + (defaults to: nil) + + + —

      shared values inherited by each variation; format may be png, jpg, webp, or pdf and only changes initially returned URL extensions

      + +
    • + +
    + +

    Returns:

    + + +

    See Also:

    + + +
    + + + + +
    +
    +
    +
    +129
    +130
    +131
    +132
    +133
    +134
    +135
    +136
    +137
    +138
    +139
    +140
    +
    +
    # File 'lib/htmlcsstoimage/images.rb', line 129
    +
    +def create_image_batch(variations, default_options = nil)
    +  return ApiResponse.new(images: []) if variations.empty?
    +
    +  body = { variations: variations }
    +  body[:default_options] = default_options unless default_options.nil?
    +
    +  self.class.post(
    +    "/v1/image/batch",
    +    basic_auth: @auth,
    +    body: body.to_json
    +  )
    +end
    +
    +
    + +
    +

    + + #create_image_from_template(template_id, template_values = {}, params = {}, template_version: nil, format: nil, **keyword_values) ⇒ HTMLCSSToImage::ApiResponse + + + + + +

    +
    +
    Deprecated.
    +

    Compatibility proxy for #generate_templated_image_url.

    +

    The third positional hash was accepted by previous versions but was not +used. Its template_version value is now honored when present.

    + +
    +
    +
    +

    Parameters:

    +
      + +
    • + + template_id + + + (String) + + + + — +

      the saved template ID

      + +
    • + +
    • + + template_values + + + (Hash) + + + (defaults to: {}) + + + — +

      values to substitute into the template

      + +
    • + +
    • + + params + + + (Hash) + + + (defaults to: {}) + + + — +

      legacy options; only template_version is used

      + +
    • + +
    • + + template_version + + + (Integer, nil) + + + (defaults to: nil) + + + — +

      a specific template version

      + +
    • + +
    • + + format + + + (String, nil) + + + (defaults to: nil) + + + — +

      output format appended to the signed URL path: png, jpg, webp, or pdf

      + +
    • + +
    • + + keyword_values + + + (Hash) + + + + — +

      template values passed as Ruby keyword arguments

      + +
    • + +
    + +

    Returns:

    + + +
    + + + + +
    +
    +
    +
    +55
    +56
    +57
    +58
    +59
    +60
    +61
    +62
    +63
    +64
    +65
    +66
    +67
    +68
    +69
    +70
    +71
    +72
    +73
    +74
    +
    +
    # File 'lib/htmlcsstoimage/signed_urls.rb', line 55
    +
    +def create_image_from_template(
    +  template_id,
    +  template_values = {},
    +  params = {},
    +  template_version: nil,
    +  format: nil,
    +  **keyword_values
    +)
    +  params ||= {}
    +  template_values = template_values.merge(keyword_values)
    +  legacy_version =
    +    if params.is_a?(Hash)
    +      params[:template_version] || params["template_version"]
    +    end
    +
    +  options = { template_version: template_version || legacy_version }
    +  options[:format] = format unless format.nil?
    +
    +  generate_templated_image_url(template_id, template_values, **options)
    +end
    +
    +
    + +
    +

    + + #create_template(html, params = {}) ⇒ HTMLCSSToImage::ApiResponse + + + + + +

    +
    +

    Creates an image template.

    + +
    +
    +
    +

    Parameters:

    +
      + +
    • + + html + + + (String) + + + + — +

      HTML for the template

      + +
    • + +
    • + + params + + + (Hash) + + + (defaults to: {}) + + + — +

      template and rendering options

      + +
    • + +
    + + + + + + +

    Options Hash (params):

    +
      + +
    • + :name + (String) + + + + + —

      A short name to identify the template. Maximum length: 64.

      + +
    • + +
    • + :description + (String) + + + + + —

      A description of the template. Maximum length: 1024.

      + +
    • + +
    • + :css + (String) + + + + + —

      The CSS for the template.

      + +
    • + +
    • + :device_scale + (Numeric) + + + + + —

      The pixel ratio for the screenshot. Minimum: 0.1, Maximum: 3.

      + +
    • + +
    • + :google_fonts + (String) + + + + + —

      Google Fonts to load. Separate multiple fonts with |.

      + +
    • + +
    • + :max_wait_ms + (Integer) + + + + + —

      The maximum time to wait before taking the screenshot. Minimum: 500, Maximum: 10000.

      + +
    • + +
    • + :ms_delay + (Integer) + + + + + —

      Extra time in milliseconds to wait before taking the screenshot. Maximum: 10000.

      + +
    • + +
    • + :render_when_ready + (Boolean) + + + + + —

      Wait until ScreenshotReady() is called from JavaScript before taking the screenshot.

      + +
    • + +
    • + :max_render_once + (Boolean) + + + + + —

      Ensure images created from the template are only rendered and saved once.

      + +
    • + +
    • + :selector + (String) + + + + + —

      A CSS selector for the element to capture.

      + +
    • + +
    • + :viewport_height + (Integer) + + + + + —

      The Chrome viewport height. Both viewport dimensions must be set if using either.

      + +
    • + +
    • + :viewport_width + (Integer) + + + + + —

      The Chrome viewport width. Both viewport dimensions must be set if using either.

      + +
    • + +
    • + :disable_twemoji + (Boolean) + + + + + —

      Templates use Twemoji by default; true uses supplied or native emoji fonts instead.

      + +
    • + +
    • + :color_scheme + (String) + + + + + —

      Render using the light or dark browser color scheme.

      + +
    • + +
    • + :timezone + (String) + + + + + —

      The browser timezone as an IANA timezone identifier, such as America/New_York.

      + +
    • + +
    • + :viewport_mobile + (Boolean) + + + + + —

      Whether to honor the page's mobile viewport behavior.

      + +
    • + +
    • + :viewport_landscape + (Boolean) + + + + + —

      Whether to render the viewport in landscape mode.

      + +
    • + +
    • + :viewport_touch + (Boolean) + + + + + —

      Whether the viewport supports touch events.

      + +
    • + +
    • + :media_type + (String) + + + + + —

      Render using print or screen media.

      + +
    • + +
    • + :jumbo_max_height + (Integer) + + + + + —

      Maximum output height in jumbo mode. Requires jumbo_max_width.

      + +
    • + +
    • + :jumbo_max_width + (Integer) + + + + + —

      Maximum output width in jumbo mode. Requires jumbo_max_height.

      + +
    • + +
    • + :proxy_id + (String) + + + + + —

      The ID of an organization proxy to use for the render.

      + +
    • + +
    • + :request_overrides + (Array<Hash>) + + + + + —

      Browser request block rules. Use RequestOverrideResourceType values in resource_types.

      + +
    • + +
    • + :storage_destination_id + (String) + + + + + —

      The ID of an organization storage destination inherited by images created from the template.

      + +
    • + +
    • + :transparent_background + (Boolean) + + + + + —

      Whether images created from the template should use a transparent background.

      + +
    • + +
    + + +

    Returns:

    + + +

    See Also:

    + + +
    + + + + +
    +
    +
    +
    +75
    +76
    +77
    +
    +
    # File 'lib/htmlcsstoimage/templates.rb', line 75
    +
    +def create_template(html, params = {})
    +  create_template_at_path("/v1/template", html, params)
    +end
    +
    +
    + +
    +

    + + #create_template_version(template_id, html, params = {}) ⇒ HTMLCSSToImage::ApiResponse + + + + + +

    +
    +

    Creates a new version of a saved template.

    +

    Accepts the same options as #create_template.

    + +
    +
    +
    +

    Parameters:

    +
      + +
    • + + template_id + + + (String) + + + + — +

      the saved template ID

      + +
    • + +
    • + + html + + + (String) + + + + — +

      HTML for the new template version

      + +
    • + +
    • + + params + + + (Hash) + + + (defaults to: {}) + + + — +

      template and rendering options

    • @@ -1050,7 +2264,7 @@

      — -

      batch response with images available at .images

      +

      created template version details

      @@ -1059,7 +2273,7 @@

      See Also:

      @@ -1069,33 +2283,15 @@

       
       
      -127
      -128
      -129
      -130
      -131
      -132
      -133
      -134
      -135
      -136
      -137
      -138
      +89 +90 +91 -
      # File 'lib/htmlcsstoimage/images.rb', line 127
      -
      -def create_image_batch(variations, default_options = nil)
      -  return ApiResponse.new(images: []) if variations.empty?
      -
      -  body = { variations: variations }
      -  body[:default_options] = default_options unless default_options.nil?
      +      
      # File 'lib/htmlcsstoimage/templates.rb', line 89
       
      -  self.class.post(
      -    "/v1/image/batch",
      -    basic_auth: @auth,
      -    body: body.to_json
      -  )
      +def create_template_version(template_id, html, params = {})
      +  create_template_at_path("/v1/template/#{template_id}", html, params)
       end
      @@ -1103,9 +2299,9 @@

    -

    +

    - #create_image_from_template(template_id, template_values = {}, params = {}, template_version: nil, format: nil, **keyword_values) ⇒ HTMLCSSToImage::ApiResponse + #create_templated_image(template_id, template_values = {}, template_version: nil, format: nil, **keyword_values) ⇒ HTMLCSSToImage::ApiResponse @@ -1113,10 +2309,7 @@

    -
    Deprecated.
    -

    Compatibility proxy for #generate_templated_image_url.

    -

    The third positional hash was accepted by previous versions but was not -used. Its template_version value is now honored when present.

    +

    Creates an image from a saved template with an API request.

    @@ -1154,22 +2347,6 @@

  • -
  • - - params - - - (Hash) - - - (defaults to: {}) - - - — -

    legacy options; only template_version is used

    - -
  • -
  • template_version @@ -1182,7 +2359,7 @@

    — -

    a specific template version

    +

    a specific template version, or the latest when omitted

  • @@ -1198,7 +2375,7 @@

    — -

    output format appended to the signed URL path: png, jpg, webp, or pdf

    +

    the format used in the initially returned URL: png, jpg, webp, or pdf; does not change the stored image definition

    @@ -1229,61 +2406,72 @@

    — -

    signed URL available at .url

    +

    image details, including .url

    +

    See Also:

    + + @@ -1291,9 +2479,9 @@

    -

    +

    - #create_template(html, params = {}) ⇒ HTMLCSSToImage::ApiResponse + #create_templated_image_batch(variations, default_options = nil) ⇒ HTMLCSSToImage::ApiResponse @@ -1301,7 +2489,9 @@

    -

    Creates an image template.

    +

    Creates images from one or more templates in a single request. +Objects in template_values merge recursively; arrays, scalars and null replace defaults. +Supplying template_id resets the inherited version; omit a version to use latest.

    @@ -1311,305 +2501,203 @@

  • - html + variations - (String) + (Array<Hash>) — -

    HTML for the template

    +

    per-image template options; results preserve this order

  • - params + default_options - (Hash) + (Hash, nil) - (defaults to: {}) + (defaults to: nil) — -

    template and rendering options

    +

    shared template_id, template_version, template_values and format

  • +

    Returns:

    +
      - - - - -

      Options Hash (params):

      -
        - -
      • - :name - (String) - - - - - —

        A short name to identify the template. Maximum length: 64.

        - -
      • - -
      • - :description - (String) - - - - - —

        A description of the template. Maximum length: 1024.

        - -
      • +
      • -
      • - :css - (String) - - - - - —

        The CSS for the template.

        - -
      • -
      • - :device_scale - (Numeric) - - - - - —

        The pixel ratio for the screenshot. Minimum: 0.1, Maximum: 3.

        - -
      • + (HTMLCSSToImage::ApiResponse) -
      • - :google_fonts - (String) - - - - - —

        Google Fonts to load. Separate multiple fonts with |.

        - -
      • -
      • - :max_wait_ms - (Integer) - - - - - —

        The maximum time to wait before taking the screenshot. Minimum: 500, Maximum: 10000.

        - -
      • -
      • - :ms_delay - (Integer) - - - - - —

        Extra time in milliseconds to wait before taking the screenshot. Maximum: 10000.

        - -
      • + — +

        batch response with results at .images

        -
      • - :render_when_ready - (Boolean) - - - - - —

        Wait until ScreenshotReady() is called from JavaScript before taking the screenshot.

        - -
      • + + +
      + +

     
     
    -55
    -56
    -57
    -58
    -59
    -60
    -61
    -62
    -63
    -64
    -65
    -66
    -67
    -68
    -69
    -70
    -71
    -72
    -73
    -74
    +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118
    -
    # File 'lib/htmlcsstoimage/signed_urls.rb', line 55
    +      
    # File 'lib/htmlcsstoimage/images.rb', line 97
     
    -def create_image_from_template(
    +def create_templated_image(
       template_id,
       template_values = {},
    -  params = {},
       template_version: nil,
       format: nil,
       **keyword_values
     )
    -  params ||= {}
       template_values = template_values.merge(keyword_values)
    -  legacy_version =
    -    if params.is_a?(Hash)
    -      params[:template_version] || params["template_version"]
    -    end
    -
    -  options = { template_version: template_version || legacy_version }
    -  options[:format] = format unless format.nil?
    +  body = {
    +    template_id: template_id,
    +    template_values: template_values
    +  }
    +  body[:template_version] = template_version unless template_version.nil?
    +  body[:format] = format unless format.nil?
     
    -  generate_templated_image_url(template_id, template_values, **options)
    +  self.class.post(
    +    "/v1/image",
    +    basic_auth: @auth,
    +    body: body.to_json,
    +    query: { includeId: true }
    +  )
     end
    + + + + +
    +
    +
    +
    +148
    +149
    +150
    +151
    +152
    +153
    +154
    +155
    +156
    +157
    +158
    +
    +
    # File 'lib/htmlcsstoimage/images.rb', line 148
    +
    +def create_templated_image_batch(variations, default_options = nil)
    +  return ApiResponse.new(images: []) if variations.empty?
    +
    +  body = { variations: variations }
    +  body[:default_options] = default_options unless default_options.nil?
    +  self.class.post(
    +    "/v1/image/batch/templated",
    +    basic_auth: @auth,
    +    body: body.to_json
    +  )
    +end
    +
    + + +
    +

    + + #create_url_recording(url, params = {}) ⇒ HTMLCSSToImage::ApiResponse + + + + + +

    +
    +

    Records a public HTTP or HTTPS webpage.

    +

    Accepts the browser, timeline, and output options documented on +#create_html_css_recording. CSS is injected into the page after it loads.

    + +
    +
    +
    +

    Parameters:

    +
      + +
    • -
    • - :max_render_once - (Boolean) - - - - - —

      Ensure images created from the template are only rendered and saved once.

      - -
    • + url + + + (String) -
    • - :selector - (String) - - - - - —

      A CSS selector for the element to capture.

      - -
    • -
    • - :viewport_height - (Integer) - - - - - —

      The Chrome viewport height. Both viewport dimensions must be set if using either.

      - -
    • -
    • - :viewport_width - (Integer) - - - - - —

      The Chrome viewport width. Both viewport dimensions must be set if using either.

      - -
    • + — +

      public HTTP or HTTPS URL to record

      -
    • - :disable_twemoji - (Boolean) - - - - - —

      Disable the Twemoji fallback and use native emoji fonts.

      - -
    • + + +
    • -
    • - :color_scheme - (String) - - - - - —

      Render using the light or dark browser color scheme.

      - -
    • + params -
    • - :timezone - (String) - - - - - —

      The browser timezone as an IANA timezone identifier, such as America/New_York.

      - -
    • -
    • - :viewport_mobile - (Boolean) - - - - - —

      Whether to honor the page's mobile viewport behavior.

      - -
    • + (Hash) -
    • - :viewport_landscape - (Boolean) - - - - - —

      Whether to render the viewport in landscape mode.

      - -
    • -
    • - :viewport_touch - (Boolean) - - - - - —

      Whether the viewport supports touch events.

      - -
    • + (defaults to: {}) -
    • - :media_type - (String) - - - - - —

      Render using print or screen media.

      - -
    • + + — +

      recording options, including the required duration_ms

      + + + +
    + + + + + + +

    Options Hash (params):

    +
    • - :jumbo_max_height - (Integer) + :block_consent_banners + (Boolean) - —

      Maximum output height in jumbo mode. Requires jumbo_max_width.

      + —

      Attempt to hide cookie and consent banners before recording.

    • - :jumbo_max_width - (Integer) + :identify_as_hcti + (Boolean) - —

      Maximum output width in jumbo mode. Requires jumbo_max_height.

      + —

      Add X-HCTI-SCREENSHOT: 1 to the top-level navigation.

    • - :proxy_id - (String) + :headers + (Hash{String => String}) - —

      The ID of an organization proxy to use for the render.

      + —

      Custom HTTP headers for top-level navigations to the URL's origin and additional_header_origins.

    • - :storage_destination_id - (String) + :additional_header_origins + (Array<String>) - —

      The ID of an organization storage destination inherited by images created from the template.

      + —

      Additional exact HTTP or HTTPS origins allowed to receive custom headers.

    • - :transparent_background + :include_headers_on_subrequests (Boolean) - —

      Whether images created from the template should use a transparent background.

      + —

      Also send custom headers with subrequests to allowed origins. Defaults to false.

    • @@ -1627,7 +2715,7 @@

      — -

      created template details

      +

      recording details at .id, .status_url, and .recording_url

      @@ -1636,7 +2724,9 @@

      See Also:

      @@ -1646,15 +2736,19 @@

       
       
      -74
      -75
      -76
      +59 +60 +61 +62 +63 -
      # File 'lib/htmlcsstoimage/templates.rb', line 74
      +      
      # File 'lib/htmlcsstoimage/recordings.rb', line 59
       
      -def create_template(html, params = {})
      -  create_template_at_path("/v1/template", html, params)
      +def create_url_recording(url, params = {})
      +  body = { url: url }.merge(params).to_json
      +
      +  self.class.post("/v1/recording", basic_auth: @auth, body: body)
       end
      @@ -1662,9 +2756,97 @@

    -

    +

    - #create_template_version(template_id, html, params = {}) ⇒ HTMLCSSToImage::ApiResponse + #delete_image(image_id) ⇒ Boolean, HTMLCSSToImage::ApiResponse + + + + + +

    +
    +

    Deletes an image.

    + +
    +
    +
    +

    Parameters:

    +
      + +
    • + + image_id + + + (String) + + + + — +

      the ID of the image to delete

      + +
    • + +
    + +

    Returns:

    + + +

    See Also:

    + + +
    + + + + +
    +
    +
    +
    +166
    +167
    +168
    +169
    +170
    +171
    +172
    +
    +
    # File 'lib/htmlcsstoimage/images.rb', line 166
    +
    +def delete_image(image_id)
    +  response = self.class.delete("/v1/image/#{image_id}", basic_auth: @auth)
    +
    +  return true if response.success?
    +
    +  response
    +end
    +
    +
    + +
    +

    + + #delete_image_batch(image_ids) ⇒ Boolean, HTMLCSSToImage::ApiResponse @@ -1672,8 +2854,7 @@

    -

    Creates a new version of a saved template.

    -

    Accepts the same options as #create_template.

    +

    Deletes multiple images in one request.

    @@ -1683,45 +2864,15 @@

  • - template_id - - - (String) - - - - — -

    the saved template ID

    - -
  • - -
  • - - html - - - (String) - - - - — -

    HTML for the new template version

    - -
  • - -
  • - - params - + image_ids - (Hash) + (Array<String>) - (defaults to: {}) — -

    template and rendering options

    +

    IDs of the images to delete

  • @@ -1733,12 +2884,12 @@

  • - (HTMLCSSToImage::ApiResponse) + (Boolean, HTMLCSSToImage::ApiResponse) — -

    created template version details

    +

    true on success, or the API response on failure

  • @@ -1747,7 +2898,7 @@

    See Also:

    @@ -1757,15 +2908,35 @@

     
     
    -88
    -89
    -90
    +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 -
    # File 'lib/htmlcsstoimage/templates.rb', line 88
    +      
    # File 'lib/htmlcsstoimage/images.rb', line 180
     
    -def create_template_version(template_id, html, params = {})
    -  create_template_at_path("/v1/template/#{template_id}", html, params)
    +def delete_image_batch(image_ids)
    +  return true if image_ids.empty?
    +
    +  response = self.class.delete(
    +    "/v1/image/batch",
    +    basic_auth: @auth,
    +    body: { ids: image_ids }.to_json
    +  )
    +
    +  return true if response.success?
    +
    +  response
     end
    @@ -1773,9 +2944,9 @@

    -

    +

    - #create_templated_image(template_id, template_values = {}, template_version: nil, format: nil, **keyword_values) ⇒ HTMLCSSToImage::ApiResponse + #delete_recording(recording_id) ⇒ true, HTTParty::Response @@ -1783,7 +2954,7 @@

    -

    Creates an image from a saved template with an API request.

    +

    Deletes a recording and clears its media from the CDN.

    @@ -1793,7 +2964,7 @@

  • - template_id + recording_id (String) @@ -1801,69 +2972,7 @@

    — -

    the saved template ID

    - -

  • - -
  • - - template_values - - - (Hash) - - - (defaults to: {}) - - - — -

    values to substitute into the template

    - -
  • - -
  • - - template_version - - - (Integer, nil) - - - (defaults to: nil) - - - — -

    a specific template version, or the latest when omitted

    - -
  • - -
  • - - format - - - (String, nil) - - - (defaults to: nil) - - - — -

    the format used in the initially returned URL: png, jpg, webp, or pdf; does not change the stored image definition

    - -
  • - -
  • - - keyword_values - - - (Hash) - - - - — -

    template values passed as Ruby keyword arguments

    +

    the recording ID to delete

  • @@ -1875,77 +2984,36 @@

  • - (HTMLCSSToImage::ApiResponse) + (true, HTTParty::Response) — -

    image details, including .url

    +

    true when accepted, or the API response on failure

  • -

    See Also:

    - -

    @@ -1953,9 +3021,9 @@

    -

    +

    - #delete_image(image_id) ⇒ Boolean, HTMLCSSToImage::ApiResponse + #delete_recording_batch(recording_ids) ⇒ true, HTTParty::Response @@ -1963,7 +3031,8 @@

    -

    Deletes an image.

    +

    Deletes several recordings in one API request. +Empty lists succeed without calling the API, as with #delete_image_batch.

    @@ -1973,15 +3042,15 @@

  • - image_id + recording_ids - (String) + (Array<String>) — -

    the ID of the image to delete

    +

    the recording IDs to delete

  • @@ -1993,47 +3062,48 @@

  • - (Boolean, HTMLCSSToImage::ApiResponse) + (true, HTTParty::Response) — -

    true on success, or the API response on failure

    +

    true when accepted, or the API response on failure

  • -

    See Also:

    - -

     
     
    -95
    -96
    -97
    -98
    -99
    -100
    -101
    -102
    -103
    -104
    -105
    -106
    -107
    -108
    -109
    -110
    -111
    -112
    -113
    -114
    -115
    -116
    +82 +83 +84 +85 +86
    -
    # File 'lib/htmlcsstoimage/images.rb', line 95
    +      
    # File 'lib/htmlcsstoimage/recordings.rb', line 82
     
    -def create_templated_image(
    -  template_id,
    -  template_values = {},
    -  template_version: nil,
    -  format: nil,
    -  **keyword_values
    -)
    -  template_values = template_values.merge(keyword_values)
    -  body = {
    -    template_id: template_id,
    -    template_values: template_values
    -  }
    -  body[:template_version] = template_version unless template_version.nil?
    -  body[:format] = format unless format.nil?
    +def delete_recording(recording_id)
    +  response = self.class.delete("/v1/recordings/#{recording_id}", basic_auth: @auth)
     
    -  self.class.post(
    -    "/v1/image",
    -    basic_auth: @auth,
    -    body: body.to_json,
    -    query: { includeId: true }
    -  )
    +  response.success? ? true : response
     end
    @@ -2041,9 +3111,9 @@

    -

    +

    - #delete_image_batch(image_ids) ⇒ Boolean, HTMLCSSToImage::ApiResponse + #fetch_recording_status(recording_id) ⇒ HTMLCSSToImage::ApiResponse @@ -2051,7 +3121,10 @@

    -

    Deletes multiple images in one request.

    +

    Fetches a recording's current lifecycle state once. +HTTP 200 and 202 both return status information. The states ready, +failed, and cancelled are terminal; an error can also describe an +earlier, retryable attempt. Requesting the media URL waits for processing.

    @@ -2061,15 +3134,15 @@

  • - image_ids + recording_id - (Array<String>) + (String) — -

    IDs of the images to delete

    +

    the recording ID returned by creation

  • @@ -2081,12 +3154,12 @@

  • - (Boolean, HTMLCSSToImage::ApiResponse) + (HTMLCSSToImage::ApiResponse) — -

    true on success, or the API response on failure

    +

    .status, .attempt_count, .status_entered_at, .stored_duration_ms, .recording_url, and optional .error

  • @@ -2095,7 +3168,7 @@

    See Also:

    @@ -2105,35 +3178,15 @@

     
     
    -160
    -161
    -162
    -163
    -164
    -165
    -166
    -167
    -168
    -169
    -170
    -171
    -172
    +74 +75 +76

    @@ -2267,7 +3320,7 @@

    params .reject do |key, _value| - %w[url format pdf_options dedupe_duration_s].include?(key.to_s) + %w[url format pdf_options dedupe_duration_s request_overrides].include?(key.to_s) end .sort_by { |key, _value| key.to_s } .each do |key, value| @@ -3007,7 +4060,7 @@

    - —

    Disable the Twemoji fallback and use native emoji fonts.

    + —

    For HTML/CSS, true disables default Twemoji replacement. For URLs, only explicit false injects Twemoji; omitted or true leaves the page unchanged.

    @@ -3165,6 +4218,17 @@

    +
  • + :request_overrides + (Array<Hash>) + + + + + —

    Browser request block rules, such as { action: "block", resource_types: [RequestOverrideResourceType::Script] }. Requires a paid plan.

    + +
  • +
  • :storage_destination_id (String) @@ -3242,15 +4306,15 @@

     
     
    -78
    -79
     80
     81
     82
    -83
    +83 +84 +85

  •  
     
    -146
    -147
    -148
    -149
    -150
    -151
    -152
    +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103
    -
    # File 'lib/htmlcsstoimage/images.rb', line 146
    +      
    # File 'lib/htmlcsstoimage/recordings.rb', line 93
     
    -def delete_image(image_id)
    -  response = self.class.delete("/v1/image/#{image_id}", basic_auth: @auth)
    +def delete_recording_batch(recording_ids)
    +  return true if recording_ids.empty?
     
    -  return true if response.success?
    +  response = self.class.delete(
    +    "/v1/recordings/batch",
    +    basic_auth: @auth,
    +    body: { ids: recording_ids }.to_json
    +  )
     
    -  response
    +  response.success? ? true : response
     end
    -
    # File 'lib/htmlcsstoimage/images.rb', line 160
    -
    -def delete_image_batch(image_ids)
    -  return true if image_ids.empty?
    -
    -  response = self.class.delete(
    -    "/v1/image/batch",
    -    basic_auth: @auth,
    -    body: { ids: image_ids }.to_json
    -  )
    -
    -  return true if response.success?
    +      
    # File 'lib/htmlcsstoimage/recordings.rb', line 74
     
    -  response
    +def fetch_recording_status(recording_id)
    +  self.class.get("/v1/recordings/#{recording_id}/status", basic_auth: @auth)
     end
    -
    # File 'lib/htmlcsstoimage/images.rb', line 78
    +      
    # File 'lib/htmlcsstoimage/images.rb', line 80
     
     def url_to_image(url, params = {})
       body = { url: url }.merge(params).to_json
    @@ -3268,9 +4332,9 @@ 

    diff --git a/docs/HTMLCSSToImage/ApiResponse.html b/docs/HTMLCSSToImage/ApiResponse.html index cbb64a4..8b994d6 100644 --- a/docs/HTMLCSSToImage/ApiResponse.html +++ b/docs/HTMLCSSToImage/ApiResponse.html @@ -126,9 +126,9 @@

    Overview

    diff --git a/docs/HTMLCSSToImage/RequestOverrideResourceType.html b/docs/HTMLCSSToImage/RequestOverrideResourceType.html new file mode 100644 index 0000000..45921b9 --- /dev/null +++ b/docs/HTMLCSSToImage/RequestOverrideResourceType.html @@ -0,0 +1,432 @@ + + + + + + + Class: HTMLCSSToImage::RequestOverrideResourceType + + — Documentation by YARD 0.9.45 + + + + + + + + + + + + + + + + + + + + + +
    + + +

    Class: HTMLCSSToImage::RequestOverrideResourceType + + + +

    +
    + +
    +
    Inherits:
    +
    + Object + +
      +
    • Object
    • + + + +
    + show all + +
    +
    + + + + + + + + + + + +
    +
    Defined in:
    +
    lib/htmlcsstoimage/request_override_resource_type.rb +
    +
    + +
    + + + +

    + Constant Summary + collapse +

    + +
    + +
    Beacon = + +
    +
    new("beacon")
    + +
    Document = + +
    +
    new("document")
    + +
    Stylesheet = + +
    +
    new("stylesheet")
    + +
    Image = + +
    +
    new("image")
    + +
    ImageSet = + +
    +
    new("image_set")
    + +
    Media = + +
    +
    new("media")
    + +
    Font = + +
    +
    new("font")
    + +
    Script = + +
    +
    new("script")
    + +
    TextTrack = + +
    +
    new("text_track")
    + +
    Xhr = + +
    +
    new("xhr")
    + +
    Fetch = + +
    +
    new("fetch")
    + +
    EventSource = + +
    +
    new("event_source")
    + +
    Manifest = + +
    +
    new("manifest")
    + +
    Ping = + +
    +
    new("ping")
    + +
    Img = + +
    +
    new("img")
    + +
    Other = + +
    +
    new("other")
    + +
    + + + + + +

    Instance Attribute Summary collapse

    +
      + +
    • + + + #value ⇒ Object + + + + + + + + + readonly + + + + + + + + + +

      Returns the value of attribute value.

      + +
    • + + +
    + + + + + +

    + Instance Method Summary + collapse +

    + + + + + +
    +

    Constructor Details

    + +
    +

    + + #initialize(value) ⇒ RequestOverrideResourceType + + + + + +

    +
    +

    Returns a new instance of RequestOverrideResourceType.

    + +
    +
    +
    + + +
    + + + + +
    +
    +
    +
    +6
    +7
    +8
    +9
    +
    +
    # File 'lib/htmlcsstoimage/request_override_resource_type.rb', line 6
    +
    +def initialize(value)
    +  @value = value.freeze
    +  freeze
    +end
    +
    +
    + +
    + +
    +

    Instance Attribute Details

    + + + +
    +

    + + #value ⇒ Object (readonly) + + + + + +

    +
    +

    Returns the value of attribute value.

    + +
    +
    +
    + + +
    + + + + +
    +
    +
    +
    +4
    +5
    +6
    +
    +
    # File 'lib/htmlcsstoimage/request_override_resource_type.rb', line 4
    +
    +def value
    +  @value
    +end
    +
    +
    + +
    + + +
    +

    Instance Method Details

    + + +
    +

    + + #to_json(*args) ⇒ Object + + + + + +

    + + + + +
    +
    +
    +
    +12
    +13
    +14
    +
    +
    # File 'lib/htmlcsstoimage/request_override_resource_type.rb', line 12
    +
    +def to_json(*args)
    +  @value.to_json(*args)
    +end
    +
    +
    + +
    + +
    + + + +
    + + diff --git a/docs/_index.html b/docs/_index.html index d498075..43d1563 100644 --- a/docs/_index.html +++ b/docs/_index.html @@ -105,6 +105,21 @@

    Namespace Listing A-Z

    + + +
    @@ -114,9 +129,9 @@

    Namespace Listing A-Z

    diff --git a/docs/class_list.html b/docs/class_list.html index 02128eb..e1b1c15 100644 --- a/docs/class_list.html +++ b/docs/class_list.html @@ -46,7 +46,7 @@

    Class List

    diff --git a/docs/file.README.html b/docs/file.README.html index 81bbdc7..5fa4423 100644 --- a/docs/file.README.html +++ b/docs/file.README.html @@ -132,6 +132,71 @@

    Create a batch of images

    { viewport_width: 1200, format: "webp" } ) +

    Recordings

    +

    Record HTML/CSS or a public webpage as MP4, WebM, or GIF. Use +create_html_css_recording for HTML/CSS and create_url_recording for a webpage:

    +
    recording = client.create_url_recording(
    +  "https://example.com",
    +  duration_ms: 10000,
    +  viewport_width: 1280,
    +  viewport_height: 720,
    +  actions: [{ type: "simple_scroll" }],
    +  output: { format: "mp4" }
    +)
    +
    +recording.id
    +recording.status_url
    +recording.recording_url
    +
    +animation = client.create_html_css_recording(
    +  "<h1>Hello</h1>",
    +  css: "@keyframes fade { from { opacity: 0; } to { opacity: 1; } } h1 { animation: fade 2s; font-family: Roboto; }",
    +  google_fonts: "Roboto",
    +  duration_ms: 3000,
    +  duration_mode: "fixed",
    +  output: { format: "gif", scale: 0.5 }
    +)
    +
    +

    Both methods accept browser, timeline, and output options as hashes, following +the image methods. Options pass through to the API without local validation. +Omitted settings use API defaults. Recordings do not include audio.

    +

    Triggers and actions use a type discriminator. For example, wait until an +element is visible, click a button, and hold the result:

    +
    demo = client.create_url_recording(
    +  "https://example.com/demo",
    +  duration_ms: 5000,
    +  duration_mode: "fixed",
    +  trigger: { type: "element_visible", selector: "#demo", timeout_ms: 2000 },
    +  actions: [
    +    { type: "click", selector: "#start", if_not_found: [{ type: "error" }] },
    +    { type: "stall", duration_ms: 1000 }
    +  ]
    +)
    +
    +

    Nested branches run on the API. For JavaScript actions, omitting if_error or +setting it to nil fails on a script error; if_error: [] ignores errors. +Empty arrays, explicit nil, false, and zero values are preserved in JSON.

    +

    Creation returns the recording URLs while rendering can continue in the +background. Requesting recording_url waits for processing. Fetch the current +status once with:

    +
    status = client.fetch_recording_status(recording.id)
    +puts status.status
    +puts status.attempt_count
    +
    +

    HTTP 200 and 202 both return status information. The states ready, failed, +and cancelled are terminal. A successful status fetch can report a failed +recording, and status.error can describe an earlier, retryable attempt. +API errors and transport failures follow the existing image-method behavior.

    +

    Delete recordings individually or in a batch:

    +
    client.delete_recording("recording-id")
    +client.delete_recording_batch(["first-id", "second-id"])
    +
    +

    Deletion returns true when accepted, or the API response on failure. Empty +batch lists succeed without an API request, matching delete_image_batch.

    +

    See the recording guide, +actions reference, and +trigger reference for +options and examples.

    Signed URLs

    Signed URLs let another application, browser, or service render an image on demand without exposing your API key. Generating a signed URL does not make an @@ -259,12 +324,24 @@

    Contributing

    License

    The gem is available as open source under the terms of the MIT License.

    Code of Conduct

    -

    Everyone interacting in the project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

    +

    Everyone interacting in the project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

    +

    Templated image batches

    +

    Create images from one or more templates with shared defaults and ordered variations:

    +
    result = client.create_templated_image_batch(
    +  [
    +    { template_values: { title: "First" } },
    +    { template_id: "t-other", template_values: { title: "Second" } }
    +  ],
    +  { template_id: "t-card", template_version: 3, format: "webp" }
    +)
    +
    +

    Omitted fields inherit defaults. Supplying a template ID resets the inherited version; omit its version to use latest. Template value objects merge recursively on the API; arrays, scalars, and explicit null values replace defaults. Results preserve input order and identical images reuse existing assets. Each merged values object must be nonempty and satisfy its template's required variables.

    +

    See the API reference for plan limits and examples.

    diff --git a/docs/index.html b/docs/index.html index 6e33056..b31a8f1 100644 --- a/docs/index.html +++ b/docs/index.html @@ -132,6 +132,71 @@

    Create a batch of images

    { viewport_width: 1200, format: "webp" } ) +

    Recordings

    +

    Record HTML/CSS or a public webpage as MP4, WebM, or GIF. Use +create_html_css_recording for HTML/CSS and create_url_recording for a webpage:

    +
    recording = client.create_url_recording(
    +  "https://example.com",
    +  duration_ms: 10000,
    +  viewport_width: 1280,
    +  viewport_height: 720,
    +  actions: [{ type: "simple_scroll" }],
    +  output: { format: "mp4" }
    +)
    +
    +recording.id
    +recording.status_url
    +recording.recording_url
    +
    +animation = client.create_html_css_recording(
    +  "<h1>Hello</h1>",
    +  css: "@keyframes fade { from { opacity: 0; } to { opacity: 1; } } h1 { animation: fade 2s; font-family: Roboto; }",
    +  google_fonts: "Roboto",
    +  duration_ms: 3000,
    +  duration_mode: "fixed",
    +  output: { format: "gif", scale: 0.5 }
    +)
    +
    +

    Both methods accept browser, timeline, and output options as hashes, following +the image methods. Options pass through to the API without local validation. +Omitted settings use API defaults. Recordings do not include audio.

    +

    Triggers and actions use a type discriminator. For example, wait until an +element is visible, click a button, and hold the result:

    +
    demo = client.create_url_recording(
    +  "https://example.com/demo",
    +  duration_ms: 5000,
    +  duration_mode: "fixed",
    +  trigger: { type: "element_visible", selector: "#demo", timeout_ms: 2000 },
    +  actions: [
    +    { type: "click", selector: "#start", if_not_found: [{ type: "error" }] },
    +    { type: "stall", duration_ms: 1000 }
    +  ]
    +)
    +
    +

    Nested branches run on the API. For JavaScript actions, omitting if_error or +setting it to nil fails on a script error; if_error: [] ignores errors. +Empty arrays, explicit nil, false, and zero values are preserved in JSON.

    +

    Creation returns the recording URLs while rendering can continue in the +background. Requesting recording_url waits for processing. Fetch the current +status once with:

    +
    status = client.fetch_recording_status(recording.id)
    +puts status.status
    +puts status.attempt_count
    +
    +

    HTTP 200 and 202 both return status information. The states ready, failed, +and cancelled are terminal. A successful status fetch can report a failed +recording, and status.error can describe an earlier, retryable attempt. +API errors and transport failures follow the existing image-method behavior.

    +

    Delete recordings individually or in a batch:

    +
    client.delete_recording("recording-id")
    +client.delete_recording_batch(["first-id", "second-id"])
    +
    +

    Deletion returns true when accepted, or the API response on failure. Empty +batch lists succeed without an API request, matching delete_image_batch.

    +

    See the recording guide, +actions reference, and +trigger reference for +options and examples.

    Signed URLs

    Signed URLs let another application, browser, or service render an image on demand without exposing your API key. Generating a signed URL does not make an @@ -259,12 +324,24 @@

    Contributing

    License

    The gem is available as open source under the terms of the MIT License.

    Code of Conduct

    -

    Everyone interacting in the project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

    +

    Everyone interacting in the project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

    +

    Templated image batches

    +

    Create images from one or more templates with shared defaults and ordered variations:

    +
    result = client.create_templated_image_batch(
    +  [
    +    { template_values: { title: "First" } },
    +    { template_id: "t-other", template_values: { title: "Second" } }
    +  ],
    +  { template_id: "t-card", template_version: 3, format: "webp" }
    +)
    +
    +

    Omitted fields inherit defaults. Supplying a template ID resets the inherited version; omit its version to use latest. Template value objects merge recursively on the API; arrays, scalars, and explicit null values replace defaults. Results preserve input order and identical images reuse existing assets. Each merged values object must be nonempty and satisfy its template's required variables.

    +

    See the API reference for plan limits and examples.

    diff --git a/docs/method_list.html b/docs/method_list.html index b929d9d..f4720d7 100644 --- a/docs/method_list.html +++ b/docs/method_list.html @@ -49,13 +49,21 @@

    Method List

  • +
    + #create_image + HTMLCSSToImage +
    +
  • + + +
  • #create_image_batch HTMLCSSToImage @@ -63,7 +71,7 @@

    Method List

  • -
  • +
  • #create_image_from_template HTMLCSSToImage @@ -71,7 +79,7 @@

    Method List

  • -
  • +
  • #create_template HTMLCSSToImage @@ -79,7 +87,7 @@

    Method List

  • -
  • +
  • #create_template_version HTMLCSSToImage @@ -87,7 +95,7 @@

    Method List

  • -
  • +
  • #create_templated_image HTMLCSSToImage @@ -95,15 +103,31 @@

    Method List

  • +
  • +
    + #create_templated_image_batch + HTMLCSSToImage +
    +
  • + +
  • +
    + #delete_image + HTMLCSSToImage +
    +
  • + + +
  • #delete_image_batch HTMLCSSToImage @@ -111,6 +135,30 @@

    Method List

  • +
  • +
    + #delete_recording + HTMLCSSToImage +
    +
  • + + +
  • +
    + #delete_recording_batch + HTMLCSSToImage +
    +
  • + + +
  • +
    + #fetch_recording_status + HTMLCSSToImage +
    +
  • + +
  • #generate_create_and_render_url @@ -136,6 +184,14 @@

    Method List

  • +
    + #initialize + HTMLCSSToImage::RequestOverrideResourceType +
    +
  • + + +
  • #list_template_versions HTMLCSSToImage @@ -143,7 +199,7 @@

    Method List

  • -
  • +
  • #list_templates HTMLCSSToImage @@ -151,7 +207,7 @@

    Method List

  • -
  • +
  • #templates HTMLCSSToImage @@ -159,6 +215,14 @@

    Method List

  • +
  • +
    + #to_json + HTMLCSSToImage::RequestOverrideResourceType +
    +
  • + +
  • #url_to_image @@ -167,6 +231,14 @@

    Method List

  • +
  • +
    + #value + HTMLCSSToImage::RequestOverrideResourceType +
    +
  • + + diff --git a/docs/top-level-namespace.html b/docs/top-level-namespace.html index 4d336a3..4f26b5c 100644 --- a/docs/top-level-namespace.html +++ b/docs/top-level-namespace.html @@ -102,9 +102,9 @@

    Defined Under Namespace

    diff --git a/htmlcsstoimage.gemspec b/htmlcsstoimage.gemspec index ca42ed6..077cd92 100644 --- a/htmlcsstoimage.gemspec +++ b/htmlcsstoimage.gemspec @@ -10,7 +10,7 @@ Gem::Specification.new do |spec| spec.email = ["support@htmlcsstoimage.com"] spec.summary = %q{Ruby client for the HTML/CSS to Image API.} - spec.description = %q{Ruby client for the HTML/CSS to Image API. Generate PNG, JPG, WebP, or PDF files with Ruby. Renders exactly like Google Chrome. } + spec.description = %q{Ruby client for the HTML/CSS to Image API. Generate PNG, JPG, WebP, or PDF images and MP4, WebM, or GIF recordings with Ruby. Renders exactly like Google Chrome. } spec.homepage = "https://docs.htmlcsstoimage.com/example-code/ruby" spec.license = "MIT" spec.required_ruby_version = ">= 2.7.0" diff --git a/lib/htmlcsstoimage.rb b/lib/htmlcsstoimage.rb index 0fb986e..fd61ec5 100644 --- a/lib/htmlcsstoimage.rb +++ b/lib/htmlcsstoimage.rb @@ -8,5 +8,6 @@ require "htmlcsstoimage/client" require "htmlcsstoimage/request_override_resource_type" require "htmlcsstoimage/images" +require "htmlcsstoimage/recordings" require "htmlcsstoimage/signed_urls" require "htmlcsstoimage/templates" diff --git a/lib/htmlcsstoimage/client.rb b/lib/htmlcsstoimage/client.rb index 06c2f3e..bc11573 100644 --- a/lib/htmlcsstoimage/client.rb +++ b/lib/htmlcsstoimage/client.rb @@ -1,4 +1,4 @@ -# Client for creating images and managing templates with HTML/CSS to Image. +# Client for creating images, recordings, and managing templates with HTML/CSS to Image. class HTMLCSSToImage include HTTParty diff --git a/lib/htmlcsstoimage/recordings.rb b/lib/htmlcsstoimage/recordings.rb new file mode 100644 index 0000000..766d959 --- /dev/null +++ b/lib/htmlcsstoimage/recordings.rb @@ -0,0 +1,108 @@ +class HTMLCSSToImage + # Records an HTML document or fragment with optional CSS and Google Fonts. + # Returns the recording ID, status URL, and media URL. The `recording_url` can + # be embedded or requested directly; a request waits until the recording is + # ready, so checking status is optional. Optional settings use the API defaults. + # + # @see https://docs.htmlcsstoimage.com/getting-started/recordings/ + # @see https://docs.htmlcsstoimage.com/parameters/actions/ + # @see https://docs.htmlcsstoimage.com/parameters/trigger/ + # @see https://docs.htmlcsstoimage.com/parameters/output/ + # + # @param html [String] HTML to record, as a fragment or a complete document + # @param params [Hash] browser, timeline, and output options passed to the API + # @option params [Integer] :duration_ms Required recording duration in milliseconds: 500–30000, or up to 90000 in target mode. + # @option params [String] :css CSS used to style the recording. + # @option params [String] :google_fonts Google Fonts to load, separated by `|`. Set font-family in the CSS to use them. + # @option params [Numeric] :device_scale Capture pixel density. HTML/CSS defaults to 2; URL recordings default to 1. + # @option params [Integer] :viewport_height Chrome viewport height in CSS pixels. Supply both viewport dimensions to set the recording size. + # @option params [Integer] :viewport_width Chrome viewport width in CSS pixels. Supply both viewport dimensions to set the recording size. + # @option params [Boolean] :disable_twemoji True disables Twemoji for HTML/CSS. URL recordings inject Twemoji only when explicitly false. + # @option params [Integer] :dedupe_duration_s Reuse an identical recent recording for this many seconds. Set to 0 to disable deduplication. + # @option params [String] :color_scheme Chrome's preferred color scheme: `light` or `dark`. + # @option params [String] :timezone Browser timezone as an IANA identifier, such as `America/New_York`. + # @option params [Boolean] :viewport_mobile Enable mobile viewport behavior, including the page's viewport meta tag. + # @option params [Boolean] :viewport_landscape Emulate landscape orientation. + # @option params [Boolean] :viewport_touch Emulate touch support. + # @option params [String] :media_type CSS media type used while recording: `print` or `screen`. + # @option params [String] :proxy_id Configured organization proxy to use while recording. + # @option params [String] :storage_destination_id Configured storage destination to receive the recording. + # @option params [Array] :request_overrides Browser request block rules. Requires a paid plan. + # @option params [Hash] :trigger Start condition: `type: "immediate"` (default), `"element_visible"` with a `selector`, or `"function_call"` to wait for `window.RecordingReady()`. Waiting triggers accept `timeout_ms`. + # @option params [Array] :actions Ordered timeline interactions: `simple_scroll`, `scroll`, `stall`, `click`, `locate_selector`, `execute_javascript`, or `error`. Each action has a `type` discriminator. Each `scroll` action step requires `duration_ms` of at least 1. Omit or use an empty array to record without interactions. + # @option params [Hash] :output Media `format` (`mp4`, `webm`, or `gif`), `fps`, and pixel `scale`. Defaults to MP4 at 30 fps; GIF defaults to 15 fps. Recordings have no audio. + # @option params [String] :duration_mode `at_most` (default) stops when actions finish or the duration is reached. `fixed` pads or cuts off at that duration. `at_least` lets actions finish up to 90 seconds. `target` adjusts playback speed to fit the duration. + # @option params [Boolean] :defer_render Wait to render until media or storage is requested. Defaults to false; does not reset deduplicated recordings. + # @option params [Boolean] :skip_scroll_preload Skip the preparation scroll that loads lazy content. Scrolling actions still run. Defaults to false. + # @return [HTMLCSSToImage::ApiResponse] recording details at `.id`, `.status_url`, and `.recording_url` + def create_html_css_recording(html, params = {}) + body = { html: html }.merge(params).to_json + + self.class.post("/v1/recording", basic_auth: @auth, body: body) + end + + # Records a public HTTP or HTTPS webpage. + # + # Accepts the browser, timeline, and output options documented on + # {#create_html_css_recording}. CSS is injected into the page after it loads. + # + # @see #create_html_css_recording + # @see https://docs.htmlcsstoimage.com/guides/recordings/scrolling-video/ + # + # @param url [String] public HTTP or HTTPS URL to record + # @param params [Hash] recording options, including the required `duration_ms` + # @option params [Boolean] :block_consent_banners Attempt to hide cookie and consent banners before recording. + # @option params [Boolean] :identify_as_hcti Add `X-HCTI-SCREENSHOT: 1` to the top-level navigation. + # @option params [Hash{String => String}] :headers Custom HTTP headers for top-level navigations to the URL's origin and additional_header_origins. + # @option params [Array] :additional_header_origins Additional exact HTTP or HTTPS origins allowed to receive custom headers. + # @option params [Boolean] :include_headers_on_subrequests Also send custom headers with subrequests to allowed origins. Defaults to false. + # @return [HTMLCSSToImage::ApiResponse] recording details at `.id`, `.status_url`, and `.recording_url` + def create_url_recording(url, params = {}) + body = { url: url }.merge(params).to_json + + self.class.post("/v1/recording", basic_auth: @auth, body: body) + end + + # Fetches a recording's current lifecycle state once. Checking status is + # optional: requesting the `recording_url` directly waits until it is ready. + # HTTP 200 and 202 both return status information. The states `ready`, + # `failed`, and `cancelled` are terminal; an error can also describe an + # earlier, retryable attempt. `.status` is the raw API string: treat values + # not listed here, which newer API versions may add, as unknown; the client + # passes them through as-is. + # + # @see https://docs.htmlcsstoimage.com/management-api/recordings/ + # + # @param recording_id [String] the recording ID returned by creation + # @return [HTMLCSSToImage::ApiResponse] `.id`, `.status`, `.attempt_count`, `.status_entered_at`, `.stored_duration_ms`, `.storage_destination_hcti_storage_disabled`, `.recording_url`, and optional `.error` + def fetch_recording_status(recording_id) + self.class.get("/v1/recordings/#{recording_id}/status", basic_auth: @auth) + end + + # Deletes a recording and clears its media from the CDN. + # + # @param recording_id [String] the recording ID to delete + # @return [true, HTTParty::Response] true when accepted, or the API response on failure + def delete_recording(recording_id) + response = self.class.delete("/v1/recordings/#{recording_id}", basic_auth: @auth) + + response.success? ? true : response + end + + # Deletes several recordings in one API request. + # Empty lists succeed without calling the API, as with {#delete_image_batch}. + # + # @param recording_ids [Array] the recording IDs to delete + # @return [true, HTTParty::Response] true when accepted, or the API response on failure + def delete_recording_batch(recording_ids) + return true if recording_ids.empty? + + response = self.class.delete( + "/v1/recordings/batch", + basic_auth: @auth, + body: { ids: recording_ids }.to_json + ) + + response.success? ? true : response + end +end diff --git a/lib/htmlcsstoimage/version.rb b/lib/htmlcsstoimage/version.rb index 021564e..a2a8154 100644 --- a/lib/htmlcsstoimage/version.rb +++ b/lib/htmlcsstoimage/version.rb @@ -1,4 +1,4 @@ class HTMLCSSToImage # Current version of the Ruby client gem. - VERSION = "0.5.0" + VERSION = "1.0.0" end diff --git a/spec/recordings_spec.rb b/spec/recordings_spec.rb new file mode 100644 index 0000000..e42f5d6 --- /dev/null +++ b/spec/recordings_spec.rb @@ -0,0 +1,232 @@ +require "spec_helper" + +RSpec.describe "HTMLCSSToImage recordings" do + let(:client) { HTMLCSSToImage.new(user_id: "id", api_key: "key") } + let(:authorization) { "Basic #{Base64.strict_encode64('id:key')}" } + let(:created) do + { + id: "recording-id", + status_url: "https://hcti.io/v1/recordings/recording-id/status", + recording_url: "https://hcti.io/v1/recording/recording-id.mp4" + } + end + let(:options) do + { + duration_ms: 5000, + css: "body { color: red; }", + device_scale: 2, + viewport_width: 1280, + viewport_height: 720, + disable_twemoji: false, + dedupe_duration_s: 0, + color_scheme: "dark", + timezone: "America/New_York", + viewport_mobile: false, + viewport_landscape: true, + viewport_touch: false, + media_type: "screen", + proxy_id: "proxy-id", + storage_destination_id: "storage-id", + request_overrides: [{ action: "block", resource_types: [HTMLCSSToImage::RequestOverrideResourceType::Script] }], + trigger: { type: "element_visible", selector: "#ready", timeout_ms: 1000 }, + actions: [ + { type: "locate_selector", selector: "#dialog", if_not_found: [], if_found: [ + { type: "click", selector: "#close", button: "right", count: 2, delay_ms: 0, + offset_x: 0, offset_y: -1, if_not_found: [{ type: "error" }] } + ] }, + { type: "execute_javascript", script: "await Promise.resolve();" }, + { type: "execute_javascript", script: "throw Error();", if_error: [] }, + { type: "execute_javascript", script: "throw Error();", if_error: nil }, + { type: "scroll", container_selector: "main", if_not_found: [], steps: [ + { to: { type: "position", position: "bottom" }, duration_ms: 800, easing: "ease_in_out_cubic" }, + { to: { type: "coordinates", x: 0, y: 200 }, duration_ms: 500 }, + { to: { type: "selector", selector: "#footer", offset_y: -40, if_not_found: [] }, duration_ms: 800 } + ] }, + { type: "simple_scroll", scroll_duration_ms: 800, ms_between_scrolls: 0, + scroll_distance: "90vh", easing: "ease_in_out_expo", stall_at_end_ms: 0 }, + { type: "simple_scroll", scroll_distance: 900 }, + { type: "stall", duration_ms: 0 } + ], + output: { format: "gif", fps: 15, scale: 0.5 }, + duration_mode: "at_least", + defer_render: false, + skip_scroll_preload: true + } + end + + after { WebMock.reset! } + + def stub_api(method, path, status: 200, body: nil) + WebMock.stub_request(method, "https://hcti.io#{path}").with( + headers: { "Authorization" => authorization } + ).to_return( + status: status, + body: body.nil? ? "" : JSON.generate(body), + headers: { "Content-Type" => "application/json" } + ) + end + + it "creates HTML recordings with all options and preserves nested branches without mutation" do + params = options.merge(google_fonts: "Roboto|Open Sans").freeze + before = Marshal.dump(params) + expected = JSON.parse({ html: "

    Hello

    " }.merge(params).to_json) + WebMock.stub_request(:post, "https://hcti.io/v1/recording").with do |request| + expect(request.headers["Authorization"]).to eq(authorization) + expect(request.headers["Content-Type"]).to include("application/json") + expect(JSON.parse(request.body)).to eq(expected) + true + end.to_return(status: 200, body: created.to_json, headers: { "Content-Type" => "application/json" }) + + result = client.create_html_css_recording("

    Hello

    ", params) + + expect(result.id).to eq(created[:id]) + expect(result.status_url).to eq(created[:status_url]) + expect(result.recording_url).to eq(created[:recording_url]) + expect(Marshal.dump(params)).to eq(before) + end + + it "creates URL recordings with headers and source-specific options" do + params = options.merge( + headers: { "Authorization" => "Bearer test" }, + additional_header_origins: ["https://assets.example.com"], + include_headers_on_subrequests: false, + identify_as_hcti: true, + block_consent_banners: true + ).freeze + expected = JSON.parse({ url: "https://example.com" }.merge(params).to_json) + WebMock.stub_request(:post, "https://hcti.io/v1/recording").with do |request| + expect(request.headers["Authorization"]).to eq(authorization) + expect(JSON.parse(request.body)).to eq(expected) + true + end.to_return(status: 200, body: created.to_json, headers: { "Content-Type" => "application/json" }) + + expect(client.create_url_recording("https://example.com", params).id).to eq("recording-id") + end + + [{ type: "immediate" }, { type: "function_call", timeout_ms: 1000 }].each do |trigger| + it "passes the #{trigger[:type]} trigger without adding defaults" do + stub_api(:post, "/v1/recording", body: created).with( + body: { html: "Demo", duration_ms: 1000, trigger: trigger }.to_json + ) + + expect(client.create_html_css_recording("Demo", duration_ms: 1000, trigger: trigger).id).to eq("recording-id") + end + end + + it "leaves option validation to the API" do + stub_api(:post, "/v1/recording", status: 400, body: { error: "Bad Request" }).with( + body: { html: "", duration_ms: 0 }.to_json + ) + + expect(client.create_html_css_recording("", duration_ms: 0).error).to eq("Bad Request") + end + + { + "awaiting_render" => 202, + "processing" => 202, + "pending_retry" => 202, + "ready" => 200, + "failed" => 200, + "cancelled" => 200 + }.each do |status, http_status| + it "fetches #{status} status from HTTP #{http_status}" do + data = { + id: "recording-id", recording_url: created[:recording_url], status: status, + status_entered_at: "2026-11-16T10:00:00Z", attempt_count: 2, + stored_duration_ms: status == "ready" ? 1500 : nil, + storage_destination_hcti_storage_disabled: status == "ready" ? true : nil, + error: { + code: "action_error", message: "Missing element", occurred_at: "2026-11-16T09:59:00Z", + retryable: true, action_path: "actions[1].if_found[0]" + } + } + stub_api(:get, "/v1/recordings/recording-id/status", status: http_status, body: data) + + result = client.fetch_recording_status("recording-id") + + expect(result.success?).to be true + expect(result.code).to eq(http_status) + expect(result.id).to eq("recording-id") + expect(result.status).to eq(status) + expect(result.status_entered_at).to eq(data[:status_entered_at]) + expect(result.attempt_count).to eq(2) + expect(result.stored_duration_ms).to eq(data[:stored_duration_ms]) + expect(result.storage_destination_hcti_storage_disabled).to eq(data[:storage_destination_hcti_storage_disabled]) + expect(result.error.code).to eq("action_error") + expect(result.error.retryable).to be true + expect(result.error.action_path).to eq("actions[1].if_found[0]") + end + end + + it "preserves absent attempt errors" do + stub_api(:get, "/v1/recordings/recording-id/status", status: 202, body: { + id: "recording-id", status: "processing", error: nil, stored_duration_ms: nil + }) + + expect(client.fetch_recording_status("recording-id").error).to be_nil + end + + it "returns true for accepted deletes with an empty response body" do + stub_api(:delete, "/v1/recordings/recording-id", status: 202) + + expect(client.delete_recording("recording-id")).to be true + end + + it "deletes a batch in one authenticated request" do + stub_api(:delete, "/v1/recordings/batch", status: 202).with( + body: { ids: ["first-id", "second-id"] }.to_json + ) + + expect(client.delete_recording_batch(["first-id", "second-id"])).to be true + end + + it "treats an empty delete batch as a successful no-op, like image batches" do + expect(HTMLCSSToImage).not_to receive(:delete) + + expect(client.delete_recording_batch([])).to be true + end + + { + create_html_css_recording: ["

    Hello

    ", { duration_ms: 1000 }], + create_url_recording: ["https://example.com", { duration_ms: 1000 }], + fetch_recording_status: ["recording-id"], + delete_recording: ["recording-id"], + delete_recording_batch: [["recording-id"]] + }.each do |method, arguments| + verb, path = case method + when :create_html_css_recording, :create_url_recording then [:post, "/v1/recording"] + when :fetch_recording_status then [:get, "/v1/recordings/recording-id/status"] + when :delete_recording then [:delete, "/v1/recordings/recording-id"] + else [:delete, "/v1/recordings/batch"] + end + + it "returns API errors unchanged from #{method}" do + stub_api(verb, path, status: 403, body: { + error: "Forbidden", message: "Missing permission", + validation_errors: [{ path: "duration_ms", message: "Invalid duration" }] + }) + + result = client.public_send(method, *arguments) + + expect(result.code).to eq(403) + expect(result.error).to eq("Forbidden") + expect(result.message).to eq("Missing permission") + expect(result.validation_errors.first.path).to eq("duration_ms") + end + + it "preserves raw non-JSON server responses from #{method}" do + WebMock.stub_request(verb, "https://hcti.io#{path}").to_return(status: 502, body: "Unavailable") + + result = client.public_send(method, *arguments) + + expect(result.code).to eq(502) + expect(result.body).to eq("Unavailable") + end + + it "propagates transport failures from #{method}" do + WebMock.stub_request(verb, "https://hcti.io#{path}").to_raise(Net::ReadTimeout) + + expect { client.public_send(method, *arguments) }.to raise_error(Net::ReadTimeout) + end + end +end From b07925543af96776b624274bd21979a9dc1a6641 Mon Sep 17 00:00:00 2001 From: jsneedles Date: Mon, 16 Nov 2026 16:12:50 -0500 Subject: [PATCH 2/2] Update ruby.yml --- .github/workflows/ruby.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/ruby.yml b/.github/workflows/ruby.yml index e1dca29..f4bc70b 100644 --- a/.github/workflows/ruby.yml +++ b/.github/workflows/ruby.yml @@ -15,6 +15,8 @@ jobs: - uses: actions/checkout@v4 - name: Set up Ruby uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.3' - name: Install dependencies run: bundle install - name: Run tests