htmlcsstoimage-api 0.1.4 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/workflows/ruby.yml +2 -0
- data/Gemfile.lock +3 -1
- data/README.md +299 -10
- data/htmlcsstoimage.gemspec +4 -2
- data/lib/htmlcsstoimage/client.rb +36 -0
- data/lib/htmlcsstoimage/images.rb +193 -0
- data/lib/htmlcsstoimage/recordings.rb +108 -0
- data/lib/htmlcsstoimage/request_override_resource_type.rb +33 -0
- data/lib/htmlcsstoimage/signed_urls.rb +130 -0
- data/lib/htmlcsstoimage/templates.rb +100 -0
- data/lib/htmlcsstoimage/version.rb +2 -1
- data/lib/htmlcsstoimage.rb +9 -151
- metadata +26 -29
- data/cassettes/HTMLCSSToImage/_create_image/accepts_additional_params.yml +0 -66
- data/cassettes/HTMLCSSToImage/_create_image/creates_an_image.yml +0 -64
- data/cassettes/HTMLCSSToImage/_create_template/creates_a_new_template.yml +0 -62
- data/cassettes/HTMLCSSToImage/_delete_image/deletes_an_image.yml +0 -60
- data/cassettes/HTMLCSSToImage/_templates/retrieves_templates.yml +0 -110
- data/cassettes/HTMLCSSToImage/_url_to_image/accepts_additional_params.yml +0 -64
- data/cassettes/HTMLCSSToImage/_url_to_image/creates_an_image_from_a_url.yml +0 -64
- data/docs/HTMLCSSToImage/ApiResponse.html +0 -124
- data/docs/HTMLCSSToImage.html +0 -1340
- data/docs/_config.yml +0 -1
- data/docs/_index.html +0 -122
- data/docs/class_list.html +0 -51
- data/docs/css/common.css +0 -1
- data/docs/css/full_list.css +0 -58
- data/docs/css/style.css +0 -496
- data/docs/file.README.html +0 -187
- data/docs/file_list.html +0 -56
- data/docs/frames.html +0 -17
- data/docs/index.html +0 -187
- data/docs/js/app.js +0 -314
- data/docs/js/full_list.js +0 -216
- data/docs/js/jquery.js +0 -4
- data/docs/method_list.html +0 -107
- data/docs/top-level-namespace.html +0 -110
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
class HTMLCSSToImage
|
|
2
|
+
# Records an HTML document or fragment with optional CSS and Google Fonts.
|
|
3
|
+
# Returns the recording ID, status URL, and media URL. The `recording_url` can
|
|
4
|
+
# be embedded or requested directly; a request waits until the recording is
|
|
5
|
+
# ready, so checking status is optional. Optional settings use the API defaults.
|
|
6
|
+
#
|
|
7
|
+
# @see https://docs.htmlcsstoimage.com/getting-started/recordings/
|
|
8
|
+
# @see https://docs.htmlcsstoimage.com/parameters/actions/
|
|
9
|
+
# @see https://docs.htmlcsstoimage.com/parameters/trigger/
|
|
10
|
+
# @see https://docs.htmlcsstoimage.com/parameters/output/
|
|
11
|
+
#
|
|
12
|
+
# @param html [String] HTML to record, as a fragment or a complete document
|
|
13
|
+
# @param params [Hash] browser, timeline, and output options passed to the API
|
|
14
|
+
# @option params [Integer] :duration_ms Required recording duration in milliseconds: 500–30000, or up to 90000 in target mode.
|
|
15
|
+
# @option params [String] :css CSS used to style the recording.
|
|
16
|
+
# @option params [String] :google_fonts Google Fonts to load, separated by `|`. Set font-family in the CSS to use them.
|
|
17
|
+
# @option params [Numeric] :device_scale Capture pixel density. HTML/CSS defaults to 2; URL recordings default to 1.
|
|
18
|
+
# @option params [Integer] :viewport_height Chrome viewport height in CSS pixels. Supply both viewport dimensions to set the recording size.
|
|
19
|
+
# @option params [Integer] :viewport_width Chrome viewport width in CSS pixels. Supply both viewport dimensions to set the recording size.
|
|
20
|
+
# @option params [Boolean] :disable_twemoji True disables Twemoji for HTML/CSS. URL recordings inject Twemoji only when explicitly false.
|
|
21
|
+
# @option params [Integer] :dedupe_duration_s Reuse an identical recent recording for this many seconds. Set to 0 to disable deduplication.
|
|
22
|
+
# @option params [String] :color_scheme Chrome's preferred color scheme: `light` or `dark`.
|
|
23
|
+
# @option params [String] :timezone Browser timezone as an IANA identifier, such as `America/New_York`.
|
|
24
|
+
# @option params [Boolean] :viewport_mobile Enable mobile viewport behavior, including the page's viewport meta tag.
|
|
25
|
+
# @option params [Boolean] :viewport_landscape Emulate landscape orientation.
|
|
26
|
+
# @option params [Boolean] :viewport_touch Emulate touch support.
|
|
27
|
+
# @option params [String] :media_type CSS media type used while recording: `print` or `screen`.
|
|
28
|
+
# @option params [String] :proxy_id Configured organization proxy to use while recording.
|
|
29
|
+
# @option params [String] :storage_destination_id Configured storage destination to receive the recording.
|
|
30
|
+
# @option params [Array<Hash>] :request_overrides Browser request block rules. Requires a paid plan.
|
|
31
|
+
# @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`.
|
|
32
|
+
# @option params [Array<Hash>] :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.
|
|
33
|
+
# @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.
|
|
34
|
+
# @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.
|
|
35
|
+
# @option params [Boolean] :defer_render Wait to render until media or storage is requested. Defaults to false; does not reset deduplicated recordings.
|
|
36
|
+
# @option params [Boolean] :skip_scroll_preload Skip the preparation scroll that loads lazy content. Scrolling actions still run. Defaults to false.
|
|
37
|
+
# @return [HTMLCSSToImage::ApiResponse] recording details at `.id`, `.status_url`, and `.recording_url`
|
|
38
|
+
def create_html_css_recording(html, params = {})
|
|
39
|
+
body = { html: html }.merge(params).to_json
|
|
40
|
+
|
|
41
|
+
self.class.post("/v1/recording", basic_auth: @auth, body: body)
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
# Records a public HTTP or HTTPS webpage.
|
|
45
|
+
#
|
|
46
|
+
# Accepts the browser, timeline, and output options documented on
|
|
47
|
+
# {#create_html_css_recording}. CSS is injected into the page after it loads.
|
|
48
|
+
#
|
|
49
|
+
# @see #create_html_css_recording
|
|
50
|
+
# @see https://docs.htmlcsstoimage.com/guides/recordings/scrolling-video/
|
|
51
|
+
#
|
|
52
|
+
# @param url [String] public HTTP or HTTPS URL to record
|
|
53
|
+
# @param params [Hash] recording options, including the required `duration_ms`
|
|
54
|
+
# @option params [Boolean] :block_consent_banners Attempt to hide cookie and consent banners before recording.
|
|
55
|
+
# @option params [Boolean] :identify_as_hcti Add `X-HCTI-SCREENSHOT: 1` to the top-level navigation.
|
|
56
|
+
# @option params [Hash{String => String}] :headers Custom HTTP headers for top-level navigations to the URL's origin and additional_header_origins.
|
|
57
|
+
# @option params [Array<String>] :additional_header_origins Additional exact HTTP or HTTPS origins allowed to receive custom headers.
|
|
58
|
+
# @option params [Boolean] :include_headers_on_subrequests Also send custom headers with subrequests to allowed origins. Defaults to false.
|
|
59
|
+
# @return [HTMLCSSToImage::ApiResponse] recording details at `.id`, `.status_url`, and `.recording_url`
|
|
60
|
+
def create_url_recording(url, params = {})
|
|
61
|
+
body = { url: url }.merge(params).to_json
|
|
62
|
+
|
|
63
|
+
self.class.post("/v1/recording", basic_auth: @auth, body: body)
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
# Fetches a recording's current lifecycle state once. Checking status is
|
|
67
|
+
# optional: requesting the `recording_url` directly waits until it is ready.
|
|
68
|
+
# HTTP 200 and 202 both return status information. The states `ready`,
|
|
69
|
+
# `failed`, and `cancelled` are terminal; an error can also describe an
|
|
70
|
+
# earlier, retryable attempt. `.status` is the raw API string: treat values
|
|
71
|
+
# not listed here, which newer API versions may add, as unknown; the client
|
|
72
|
+
# passes them through as-is.
|
|
73
|
+
#
|
|
74
|
+
# @see https://docs.htmlcsstoimage.com/management-api/recordings/
|
|
75
|
+
#
|
|
76
|
+
# @param recording_id [String] the recording ID returned by creation
|
|
77
|
+
# @return [HTMLCSSToImage::ApiResponse] `.id`, `.status`, `.attempt_count`, `.status_entered_at`, `.stored_duration_ms`, `.storage_destination_hcti_storage_disabled`, `.recording_url`, and optional `.error`
|
|
78
|
+
def fetch_recording_status(recording_id)
|
|
79
|
+
self.class.get("/v1/recordings/#{recording_id}/status", basic_auth: @auth)
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
# Deletes a recording and clears its media from the CDN.
|
|
83
|
+
#
|
|
84
|
+
# @param recording_id [String] the recording ID to delete
|
|
85
|
+
# @return [true, HTTParty::Response] true when accepted, or the API response on failure
|
|
86
|
+
def delete_recording(recording_id)
|
|
87
|
+
response = self.class.delete("/v1/recordings/#{recording_id}", basic_auth: @auth)
|
|
88
|
+
|
|
89
|
+
response.success? ? true : response
|
|
90
|
+
end
|
|
91
|
+
|
|
92
|
+
# Deletes several recordings in one API request.
|
|
93
|
+
# Empty lists succeed without calling the API, as with {#delete_image_batch}.
|
|
94
|
+
#
|
|
95
|
+
# @param recording_ids [Array<String>] the recording IDs to delete
|
|
96
|
+
# @return [true, HTTParty::Response] true when accepted, or the API response on failure
|
|
97
|
+
def delete_recording_batch(recording_ids)
|
|
98
|
+
return true if recording_ids.empty?
|
|
99
|
+
|
|
100
|
+
response = self.class.delete(
|
|
101
|
+
"/v1/recordings/batch",
|
|
102
|
+
basic_auth: @auth,
|
|
103
|
+
body: { ids: recording_ids }.to_json
|
|
104
|
+
)
|
|
105
|
+
|
|
106
|
+
response.success? ? true : response
|
|
107
|
+
end
|
|
108
|
+
end
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Named browser resource types for request_overrides rules.
|
|
2
|
+
class HTMLCSSToImage
|
|
3
|
+
class RequestOverrideResourceType
|
|
4
|
+
attr_reader :value
|
|
5
|
+
|
|
6
|
+
def initialize(value)
|
|
7
|
+
@value = value.freeze
|
|
8
|
+
freeze
|
|
9
|
+
end
|
|
10
|
+
private_class_method :new
|
|
11
|
+
|
|
12
|
+
def to_json(*args)
|
|
13
|
+
@value.to_json(*args)
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
Beacon = new("beacon")
|
|
17
|
+
Document = new("document")
|
|
18
|
+
Stylesheet = new("stylesheet")
|
|
19
|
+
Image = new("image")
|
|
20
|
+
ImageSet = new("image_set")
|
|
21
|
+
Media = new("media")
|
|
22
|
+
Font = new("font")
|
|
23
|
+
Script = new("script")
|
|
24
|
+
TextTrack = new("text_track")
|
|
25
|
+
Xhr = new("xhr")
|
|
26
|
+
Fetch = new("fetch")
|
|
27
|
+
EventSource = new("event_source")
|
|
28
|
+
Manifest = new("manifest")
|
|
29
|
+
Ping = new("ping")
|
|
30
|
+
Img = new("img")
|
|
31
|
+
Other = new("other")
|
|
32
|
+
end
|
|
33
|
+
end
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
class HTMLCSSToImage
|
|
2
|
+
# Generates a signed URL for rendering an image from a saved template.
|
|
3
|
+
#
|
|
4
|
+
# This method makes no network requests. Hashes and arrays in
|
|
5
|
+
# `template_values` are encoded as JSON before the query string is signed.
|
|
6
|
+
#
|
|
7
|
+
# @see https://docs.htmlcsstoimage.com/getting-started/create-and-render/
|
|
8
|
+
#
|
|
9
|
+
# @param template_id [String] the saved template ID
|
|
10
|
+
# @param template_values [Hash] values to substitute into the template
|
|
11
|
+
# @param template_version [Integer, nil] a specific template version, or the latest when omitted
|
|
12
|
+
# @param format [String, nil] output format appended to the signed URL path: `png`, `jpg`, `webp`, or `pdf`
|
|
13
|
+
# @param keyword_values [Hash] template values passed as Ruby keyword arguments
|
|
14
|
+
# @return [HTMLCSSToImage::ApiResponse] signed URL available at `.url`
|
|
15
|
+
def generate_templated_image_url(
|
|
16
|
+
template_id,
|
|
17
|
+
template_values = {},
|
|
18
|
+
template_version: nil,
|
|
19
|
+
format: nil,
|
|
20
|
+
**keyword_values
|
|
21
|
+
)
|
|
22
|
+
template_values = template_values.merge(keyword_values)
|
|
23
|
+
pairs = []
|
|
24
|
+
pairs << ["template_version", template_version.to_s] unless template_version.nil?
|
|
25
|
+
|
|
26
|
+
template_values.sort_by { |key, _value| key.to_s }.each do |key, value|
|
|
27
|
+
next if value.nil?
|
|
28
|
+
|
|
29
|
+
pairs << [key.to_s, signed_value(value)]
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
query = Addressable::URI.form_encode(pairs)
|
|
33
|
+
token = generate_hmac_token(query)
|
|
34
|
+
separator = query.empty? ? "" : "?"
|
|
35
|
+
format_path = format.nil? ? "" : "/#{format}"
|
|
36
|
+
|
|
37
|
+
ApiResponse.new(
|
|
38
|
+
url: "https://hcti.io/v1/image/#{template_id}/#{token}#{format_path}#{separator}#{query}"
|
|
39
|
+
)
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
# Compatibility proxy for {#generate_templated_image_url}.
|
|
43
|
+
#
|
|
44
|
+
# The third positional hash was accepted by previous versions but was not
|
|
45
|
+
# used. Its `template_version` value is now honored when present.
|
|
46
|
+
#
|
|
47
|
+
# @deprecated Use {#generate_templated_image_url} instead.
|
|
48
|
+
# @param template_id [String] the saved template ID
|
|
49
|
+
# @param template_values [Hash] values to substitute into the template
|
|
50
|
+
# @param params [Hash] legacy options; only `template_version` is used
|
|
51
|
+
# @param template_version [Integer, nil] a specific template version
|
|
52
|
+
# @param format [String, nil] output format appended to the signed URL path: `png`, `jpg`, `webp`, or `pdf`
|
|
53
|
+
# @param keyword_values [Hash] template values passed as Ruby keyword arguments
|
|
54
|
+
# @return [HTMLCSSToImage::ApiResponse] signed URL available at `.url`
|
|
55
|
+
def create_image_from_template(
|
|
56
|
+
template_id,
|
|
57
|
+
template_values = {},
|
|
58
|
+
params = {},
|
|
59
|
+
template_version: nil,
|
|
60
|
+
format: nil,
|
|
61
|
+
**keyword_values
|
|
62
|
+
)
|
|
63
|
+
params ||= {}
|
|
64
|
+
template_values = template_values.merge(keyword_values)
|
|
65
|
+
legacy_version =
|
|
66
|
+
if params.is_a?(Hash)
|
|
67
|
+
params[:template_version] || params["template_version"]
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
options = { template_version: template_version || legacy_version }
|
|
71
|
+
options[:format] = format unless format.nil?
|
|
72
|
+
|
|
73
|
+
generate_templated_image_url(template_id, template_values, **options)
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# Generates a signed create-and-render URL for a URL screenshot.
|
|
77
|
+
#
|
|
78
|
+
# This method makes no network requests. PDF options are omitted because the
|
|
79
|
+
# create-and-render endpoint does not support them. `dedupe_duration_s` is
|
|
80
|
+
# omitted because deduplication applies only to standard POST requests. False
|
|
81
|
+
# boolean values are omitted except for `transparent_background`, where both
|
|
82
|
+
# values are meaningful.
|
|
83
|
+
#
|
|
84
|
+
# @see https://docs.htmlcsstoimage.com/getting-started/create-and-render/
|
|
85
|
+
#
|
|
86
|
+
# @param url [String] the fully qualified URL to capture
|
|
87
|
+
# @param params [Hash] URL screenshot options; `format` may be `png`, `jpg`, `webp`, or `pdf` and is appended to the signed URL path instead of the query string
|
|
88
|
+
# @return [HTMLCSSToImage::ApiResponse] signed URL available at `.url`
|
|
89
|
+
def generate_create_and_render_url(url, params = {})
|
|
90
|
+
pairs = [["url", url.to_s]]
|
|
91
|
+
format = params[:format] || params["format"]
|
|
92
|
+
|
|
93
|
+
params
|
|
94
|
+
.reject do |key, _value|
|
|
95
|
+
%w[url format pdf_options dedupe_duration_s request_overrides].include?(key.to_s)
|
|
96
|
+
end
|
|
97
|
+
.sort_by { |key, _value| key.to_s }
|
|
98
|
+
.each do |key, value|
|
|
99
|
+
next if value.nil?
|
|
100
|
+
next if value == false && key.to_s != "transparent_background"
|
|
101
|
+
|
|
102
|
+
case key.to_s
|
|
103
|
+
when "headers"
|
|
104
|
+
value.each { |name, header_value| pairs << ["headers", "#{name}:#{header_value}"] }
|
|
105
|
+
when "additional_header_origins"
|
|
106
|
+
value.each { |origin| pairs << ["additional_header_origins", origin.to_s] }
|
|
107
|
+
else
|
|
108
|
+
pairs << [key.to_s, signed_value(value)]
|
|
109
|
+
end
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
query = Addressable::URI.form_encode(pairs)
|
|
113
|
+
token = generate_hmac_token(query)
|
|
114
|
+
format_path = format.nil? ? "" : "/#{format}"
|
|
115
|
+
|
|
116
|
+
ApiResponse.new(
|
|
117
|
+
url: "https://hcti.io/v1/image/create-and-render/#{@auth[:username]}/#{token}#{format_path}?#{query}"
|
|
118
|
+
)
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
private
|
|
122
|
+
|
|
123
|
+
def generate_hmac_token(query)
|
|
124
|
+
OpenSSL::HMAC.hexdigest("sha256", @auth[:password], query)
|
|
125
|
+
end
|
|
126
|
+
|
|
127
|
+
def signed_value(value)
|
|
128
|
+
value.is_a?(Array) || value.is_a?(Hash) ? JSON.generate(value) : value.to_s
|
|
129
|
+
end
|
|
130
|
+
end
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
class HTMLCSSToImage
|
|
2
|
+
# Retrieves saved templates.
|
|
3
|
+
#
|
|
4
|
+
# @see https://docs.htmlcsstoimage.com/getting-started/templates/
|
|
5
|
+
#
|
|
6
|
+
# @param params [Hash] pagination options
|
|
7
|
+
# @option params [Integer] :count number of templates to return, up to 100
|
|
8
|
+
# @option params [Integer] :max_version pagination cursor returned by the previous request
|
|
9
|
+
# @return [HTMLCSSToImage::ApiResponse] paginated template response
|
|
10
|
+
def list_templates(params = {})
|
|
11
|
+
self.class.get(
|
|
12
|
+
"/v1/template",
|
|
13
|
+
basic_auth: @auth,
|
|
14
|
+
query: params
|
|
15
|
+
)
|
|
16
|
+
end
|
|
17
|
+
|
|
18
|
+
# Compatibility proxy for {#list_templates}.
|
|
19
|
+
#
|
|
20
|
+
# @param params [Hash] pagination options
|
|
21
|
+
# @return [HTMLCSSToImage::ApiResponse] paginated template response
|
|
22
|
+
def templates(params = {})
|
|
23
|
+
list_templates(params)
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
# Retrieves versions of a saved template.
|
|
27
|
+
#
|
|
28
|
+
# @see https://docs.htmlcsstoimage.com/getting-started/templates/
|
|
29
|
+
#
|
|
30
|
+
# @param template_id [String] the saved template ID
|
|
31
|
+
# @param params [Hash] pagination options
|
|
32
|
+
# @option params [Integer] :count number of versions to return, up to 100
|
|
33
|
+
# @option params [Integer] :max_version pagination cursor returned by the previous request
|
|
34
|
+
# @return [HTMLCSSToImage::ApiResponse] paginated template version response
|
|
35
|
+
def list_template_versions(template_id, params = {})
|
|
36
|
+
self.class.get(
|
|
37
|
+
"/v1/template/#{template_id}",
|
|
38
|
+
basic_auth: @auth,
|
|
39
|
+
query: params
|
|
40
|
+
)
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
# Creates an image template.
|
|
44
|
+
#
|
|
45
|
+
# @see https://docs.htmlcsstoimage.com/getting-started/templates/
|
|
46
|
+
#
|
|
47
|
+
# @param html [String] HTML for the template
|
|
48
|
+
# @param params [Hash] template and rendering options
|
|
49
|
+
# @option params [String] :name A short name to identify the template. Maximum length: 64.
|
|
50
|
+
# @option params [String] :description A description of the template. Maximum length: 1024.
|
|
51
|
+
# @option params [String] :css The CSS for the template.
|
|
52
|
+
# @option params [Numeric] :device_scale The pixel ratio for the screenshot. Minimum: `0.1`, Maximum: `3`.
|
|
53
|
+
# @option params [String] :google_fonts Google Fonts to load. Separate multiple fonts with `|`.
|
|
54
|
+
# @option params [Integer] :max_wait_ms The maximum time to wait before taking the screenshot. Minimum: `500`, Maximum: `10000`.
|
|
55
|
+
# @option params [Integer] :ms_delay Extra time in milliseconds to wait before taking the screenshot. Maximum: `10000`.
|
|
56
|
+
# @option params [Boolean] :render_when_ready Wait until `ScreenshotReady()` is called from JavaScript before taking the screenshot.
|
|
57
|
+
# @option params [Boolean] :max_render_once Ensure images created from the template are only rendered and saved once.
|
|
58
|
+
# @option params [String] :selector A CSS selector for the element to capture.
|
|
59
|
+
# @option params [Integer] :viewport_height The Chrome viewport height. Both viewport dimensions must be set if using either.
|
|
60
|
+
# @option params [Integer] :viewport_width The Chrome viewport width. Both viewport dimensions must be set if using either.
|
|
61
|
+
# @option params [Boolean] :disable_twemoji Templates use Twemoji by default; true uses supplied or native emoji fonts instead.
|
|
62
|
+
# @option params [String] :color_scheme Render using the `light` or `dark` browser color scheme.
|
|
63
|
+
# @option params [String] :timezone The browser timezone as an IANA timezone identifier, such as `America/New_York`.
|
|
64
|
+
# @option params [Boolean] :viewport_mobile Whether to honor the page's mobile viewport behavior.
|
|
65
|
+
# @option params [Boolean] :viewport_landscape Whether to render the viewport in landscape mode.
|
|
66
|
+
# @option params [Boolean] :viewport_touch Whether the viewport supports touch events.
|
|
67
|
+
# @option params [String] :media_type Render using `print` or `screen` media.
|
|
68
|
+
# @option params [Integer] :jumbo_max_height Maximum output height in jumbo mode. Requires `jumbo_max_width`.
|
|
69
|
+
# @option params [Integer] :jumbo_max_width Maximum output width in jumbo mode. Requires `jumbo_max_height`.
|
|
70
|
+
# @option params [String] :proxy_id The ID of an organization proxy to use for the render.
|
|
71
|
+
# @option params [Array<Hash>] :request_overrides Browser request block rules. Use `RequestOverrideResourceType` values in `resource_types`.
|
|
72
|
+
# @option params [String] :storage_destination_id The ID of an organization storage destination inherited by images created from the template.
|
|
73
|
+
# @option params [Boolean] :transparent_background Whether images created from the template should use a transparent background.
|
|
74
|
+
# @return [HTMLCSSToImage::ApiResponse] created template details
|
|
75
|
+
def create_template(html, params = {})
|
|
76
|
+
create_template_at_path("/v1/template", html, params)
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
# Creates a new version of a saved template.
|
|
80
|
+
#
|
|
81
|
+
# Accepts the same options as {#create_template}.
|
|
82
|
+
#
|
|
83
|
+
# @see https://docs.htmlcsstoimage.com/getting-started/templates/
|
|
84
|
+
#
|
|
85
|
+
# @param template_id [String] the saved template ID
|
|
86
|
+
# @param html [String] HTML for the new template version
|
|
87
|
+
# @param params [Hash] template and rendering options
|
|
88
|
+
# @return [HTMLCSSToImage::ApiResponse] created template version details
|
|
89
|
+
def create_template_version(template_id, html, params = {})
|
|
90
|
+
create_template_at_path("/v1/template/#{template_id}", html, params)
|
|
91
|
+
end
|
|
92
|
+
|
|
93
|
+
private
|
|
94
|
+
|
|
95
|
+
def create_template_at_path(path, html, params)
|
|
96
|
+
body = { html: html }.merge(params).to_json
|
|
97
|
+
|
|
98
|
+
self.class.post(path, basic_auth: @auth, body: body)
|
|
99
|
+
end
|
|
100
|
+
end
|
data/lib/htmlcsstoimage.rb
CHANGED
|
@@ -1,155 +1,13 @@
|
|
|
1
1
|
require "htmlcsstoimage/version"
|
|
2
|
+
require "json"
|
|
3
|
+
require "openssl"
|
|
2
4
|
require "httparty"
|
|
3
|
-
require "addressable"
|
|
5
|
+
require "addressable/uri"
|
|
4
6
|
require "ostruct"
|
|
5
7
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
SIGNED_URL_TEMPLATE = Addressable::Template.new("https://hcti.io/v1/image/{template_id}/{signed_token}{/format*}{?query*}")
|
|
13
|
-
|
|
14
|
-
class ApiResponse < OpenStruct
|
|
15
|
-
end
|
|
16
|
-
|
|
17
|
-
parser(
|
|
18
|
-
proc do |body, format|
|
|
19
|
-
case format
|
|
20
|
-
when :json
|
|
21
|
-
JSON.parse(body, object_class: ApiResponse)
|
|
22
|
-
else
|
|
23
|
-
body
|
|
24
|
-
end
|
|
25
|
-
end
|
|
26
|
-
)
|
|
27
|
-
|
|
28
|
-
# Creates an instance of HTMLCSSToImage with API credentials.
|
|
29
|
-
# If credentials are not provided, will try to use environment variables.
|
|
30
|
-
# `HCTI_USER_ID` and `HCTI_API_KEY`.
|
|
31
|
-
#
|
|
32
|
-
# @see https://htmlcsstoimage.com/dashboard
|
|
33
|
-
#
|
|
34
|
-
# @param user_id [String] the user_id for the account.
|
|
35
|
-
# @param api_key [String] the api_key for the account.
|
|
36
|
-
# @return [HTMLCSSToImage] an instance of the api client.
|
|
37
|
-
def initialize(user_id: ENV["HCTI_USER_ID"], api_key: ENV["HCTI_API_KEY"])
|
|
38
|
-
@auth = { username: user_id, password: api_key }
|
|
39
|
-
end
|
|
40
|
-
|
|
41
|
-
# Converts HTML/CSS to an image with the API
|
|
42
|
-
#
|
|
43
|
-
# @see https://docs.htmlcsstoimage.com/getting-started/using-the-api
|
|
44
|
-
#
|
|
45
|
-
# @param html [String] This is the HTML you want to render. You can send an HTML snippet (`<div>Your content</div>`) or an entire webpage.
|
|
46
|
-
#
|
|
47
|
-
# @option params [String] :css The CSS for your image.
|
|
48
|
-
# @option params [String] :google_fonts [Google fonts](https://docs.htmlcsstoimage.com/guides/using-google-fonts/) to be loaded. Example: `Roboto`. Multiple fonts can be loaded like this: `Roboto|Open Sans`
|
|
49
|
-
# @option params [String] :selector A CSS selector for an element on the webpage. We'll crop the image to this specific element. For example: `section#complete-toolkit.container-lg`
|
|
50
|
-
# @option params [Integer] :ms_delay The number of milliseconds the API should delay before generating the image. This is useful when waiting for JavaScript. We recommend starting with `500`. Large values slow down the initial render time.
|
|
51
|
-
# @option params [Double] :device_scale This adjusts the pixel ratio for the screenshot. Minimum: `1`, Maximum: `3`.
|
|
52
|
-
# @option params [Boolean] :render_when_ready Set to true to control when the image is generated. Call `ScreenshotReady()` from JavaScript to generate the image. [Learn more](https://docs.htmlcsstoimage.com/guides/render-when-ready/).
|
|
53
|
-
# @option params [Integer] :viewport_width Set the width of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.
|
|
54
|
-
# @option params [Integer] :viewport_height Set the height of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.
|
|
55
|
-
#
|
|
56
|
-
# @return [HTMLCSSToImage::ApiResponse] image URL available at `.url`.
|
|
57
|
-
def create_image(html, params = {})
|
|
58
|
-
body = { html: html }.merge(params).to_json
|
|
59
|
-
options = { basic_auth: @auth, body: body, query: { includeId: true } }
|
|
60
|
-
|
|
61
|
-
self.class.post("/v1/image", options)
|
|
62
|
-
end
|
|
63
|
-
|
|
64
|
-
# Deletes an image
|
|
65
|
-
#
|
|
66
|
-
# @see https://docs.htmlcsstoimage.com/getting-started/using-the-api
|
|
67
|
-
#
|
|
68
|
-
# @param image_id [String] The ID for the image you would like to delete
|
|
69
|
-
def delete_image(image_id)
|
|
70
|
-
response = self.class.delete("/v1/image/#{image_id}", basic_auth: @auth)
|
|
71
|
-
|
|
72
|
-
return true if response.success?
|
|
73
|
-
|
|
74
|
-
response
|
|
75
|
-
end
|
|
76
|
-
|
|
77
|
-
# Creates a signed URL for generating an image from a template
|
|
78
|
-
# This URL contains the template_values in it. It is signed with HMAC so that it cannot be changed
|
|
79
|
-
# by anyone without the API Key.
|
|
80
|
-
#
|
|
81
|
-
# Does not make any network requests.
|
|
82
|
-
#
|
|
83
|
-
# @see https://docs.htmlcsstoimage.com/getting-started/using-the-api
|
|
84
|
-
#
|
|
85
|
-
# @param template_id [String] The ID for the template
|
|
86
|
-
# @param template_values [Hash] A hash containing the values to replace in the template
|
|
87
|
-
def create_image_from_template(template_id, template_values = {}, params = {})
|
|
88
|
-
template = SIGNED_URL_TEMPLATE.partial_expand({
|
|
89
|
-
template_id: template_id,
|
|
90
|
-
query: template_values
|
|
91
|
-
})
|
|
92
|
-
|
|
93
|
-
query = Addressable::URI.parse(template.expand(signed_token: nil).to_s).query
|
|
94
|
-
digest = OpenSSL::Digest.new('sha256')
|
|
95
|
-
signed_token = OpenSSL::HMAC.hexdigest(digest, @auth[:password], CGI.unescape(query))
|
|
96
|
-
|
|
97
|
-
url = template.expand({
|
|
98
|
-
signed_token: signed_token
|
|
99
|
-
}).to_s
|
|
100
|
-
|
|
101
|
-
ApiResponse.new(url: url)
|
|
102
|
-
end
|
|
103
|
-
|
|
104
|
-
# Generate a screenshot of a URL
|
|
105
|
-
#
|
|
106
|
-
# @see https://docs.htmlcsstoimage.com/getting-started/url-to-image/
|
|
107
|
-
#
|
|
108
|
-
# @param url [String] The fully qualified URL to a public webpage. Such as https://htmlcsstoimage.com.
|
|
109
|
-
# @option params [String] :css The CSS for your image. Gets injected into the webpage.
|
|
110
|
-
# @option params [String] :selector A CSS selector for an element on the webpage. We'll crop the image to this specific element. For example: `section#complete-toolkit.container-lg`
|
|
111
|
-
# @option params [Integer] :ms_delay The number of milliseconds the API should delay before generating the image. This is useful when waiting for JavaScript. We recommend starting with `500`. Large values slow down the initial render time.
|
|
112
|
-
# @option params [Double] :device_scale This adjusts the pixel ratio for the screenshot. Minimum: `1`, Maximum: `3`.
|
|
113
|
-
# @option params [Boolean] :render_when_ready Set to true to control when the image is generated. Call `ScreenshotReady()` from JavaScript to generate the image. [Learn more](https://docs.htmlcsstoimage.com/guides/render-when-ready/).
|
|
114
|
-
# @option params [Integer] :viewport_width Set the width of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.
|
|
115
|
-
# @option params [Integer] :viewport_height Set the height of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.
|
|
116
|
-
def url_to_image(url, params = {})
|
|
117
|
-
body = { url: url }.merge(params).to_json
|
|
118
|
-
options = { basic_auth: @auth, body: body, query: { includeId: true } }
|
|
119
|
-
|
|
120
|
-
self.class.post("/v1/image", options)
|
|
121
|
-
end
|
|
122
|
-
|
|
123
|
-
# Retrieves all available templates
|
|
124
|
-
#
|
|
125
|
-
# @see https://docs.htmlcsstoimage.com/getting-started/templates/
|
|
126
|
-
def templates(params = {})
|
|
127
|
-
options = params.merge({ basic_auth: @auth })
|
|
128
|
-
self.class.get("/v1/template", options)
|
|
129
|
-
end
|
|
130
|
-
|
|
131
|
-
# Creates an image template
|
|
132
|
-
#
|
|
133
|
-
# @see https://docs.htmlcsstoimage.com/getting-started/templates/
|
|
134
|
-
#
|
|
135
|
-
# @param html [String] This is the HTML you want to render. You can send an HTML snippet (`<div>Your content</div>`) or an entire webpage.
|
|
136
|
-
#
|
|
137
|
-
# @option params [String] :name A short name to identify your template max length 64
|
|
138
|
-
# @option params [String] :description Description to elaborate on the use of your template max length 1024
|
|
139
|
-
# @option params [String] :css The CSS for your image.
|
|
140
|
-
# @option params [String] :google_fonts [Google fonts](https://docs.htmlcsstoimage.com/guides/using-google-fonts/) to be loaded. Example: `Roboto`. Multiple fonts can be loaded like this: `Roboto|Open Sans`
|
|
141
|
-
# @option params [String] :selector A CSS selector for an element on the webpage. We'll crop the image to this specific element. For example: `section#complete-toolkit.container-lg`
|
|
142
|
-
# @option params [Integer] :ms_delay The number of milliseconds the API should delay before generating the image. This is useful when waiting for JavaScript. We recommend starting with `500`. Large values slow down the initial render time.
|
|
143
|
-
# @option params [Double] :device_scale This adjusts the pixel ratio for the screenshot. Minimum: `1`, Maximum: `3`.
|
|
144
|
-
# @option params [Boolean] :render_when_ready Set to true to control when the image is generated. Call `ScreenshotReady()` from JavaScript to generate the image. [Learn more](https://docs.htmlcsstoimage.com/guides/render-when-ready/).
|
|
145
|
-
# @option params [Integer] :viewport_width Set the width of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.
|
|
146
|
-
# @option params [Integer] :viewport_height Set the height of Chrome's viewport. This will disable automatic cropping. Both height and width parameters must be set if using either.
|
|
147
|
-
#
|
|
148
|
-
# @return [HTMLCSSToImage::ApiResponse] image URL available at `.url`.
|
|
149
|
-
def create_template(html, params = {})
|
|
150
|
-
body = { html: html }.merge(params).to_json
|
|
151
|
-
options = { basic_auth: @auth, body: body }
|
|
152
|
-
|
|
153
|
-
self.class.post("/v1/template", options)
|
|
154
|
-
end
|
|
155
|
-
end
|
|
8
|
+
require "htmlcsstoimage/client"
|
|
9
|
+
require "htmlcsstoimage/request_override_resource_type"
|
|
10
|
+
require "htmlcsstoimage/images"
|
|
11
|
+
require "htmlcsstoimage/recordings"
|
|
12
|
+
require "htmlcsstoimage/signed_urls"
|
|
13
|
+
require "htmlcsstoimage/templates"
|
metadata
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: htmlcsstoimage-api
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 1.0.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Mike Coutermarsh
|
|
@@ -9,7 +9,7 @@ authors:
|
|
|
9
9
|
autorequire:
|
|
10
10
|
bindir: exe
|
|
11
11
|
cert_chain: []
|
|
12
|
-
date:
|
|
12
|
+
date: 2026-11-16 00:00:00.000000000 Z
|
|
13
13
|
dependencies:
|
|
14
14
|
- !ruby/object:Gem::Dependency
|
|
15
15
|
name: httparty
|
|
@@ -137,8 +137,23 @@ dependencies:
|
|
|
137
137
|
- - ">="
|
|
138
138
|
- !ruby/object:Gem::Version
|
|
139
139
|
version: '0'
|
|
140
|
-
|
|
141
|
-
|
|
140
|
+
- !ruby/object:Gem::Dependency
|
|
141
|
+
name: yard
|
|
142
|
+
requirement: !ruby/object:Gem::Requirement
|
|
143
|
+
requirements:
|
|
144
|
+
- - "~>"
|
|
145
|
+
- !ruby/object:Gem::Version
|
|
146
|
+
version: '0.9'
|
|
147
|
+
type: :development
|
|
148
|
+
prerelease: false
|
|
149
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
150
|
+
requirements:
|
|
151
|
+
- - "~>"
|
|
152
|
+
- !ruby/object:Gem::Version
|
|
153
|
+
version: '0.9'
|
|
154
|
+
description: 'Ruby client for the HTML/CSS to Image API. Generate PNG, JPG, WebP,
|
|
155
|
+
or PDF images and MP4, WebM, or GIF recordings with Ruby. Renders exactly like Google
|
|
156
|
+
Chrome. '
|
|
142
157
|
email:
|
|
143
158
|
- support@htmlcsstoimage.com
|
|
144
159
|
executables: []
|
|
@@ -158,32 +173,14 @@ files:
|
|
|
158
173
|
- Rakefile
|
|
159
174
|
- bin/console
|
|
160
175
|
- bin/setup
|
|
161
|
-
- cassettes/HTMLCSSToImage/_create_image/accepts_additional_params.yml
|
|
162
|
-
- cassettes/HTMLCSSToImage/_create_image/creates_an_image.yml
|
|
163
|
-
- cassettes/HTMLCSSToImage/_create_template/creates_a_new_template.yml
|
|
164
|
-
- cassettes/HTMLCSSToImage/_delete_image/deletes_an_image.yml
|
|
165
|
-
- cassettes/HTMLCSSToImage/_templates/retrieves_templates.yml
|
|
166
|
-
- cassettes/HTMLCSSToImage/_url_to_image/accepts_additional_params.yml
|
|
167
|
-
- cassettes/HTMLCSSToImage/_url_to_image/creates_an_image_from_a_url.yml
|
|
168
|
-
- docs/HTMLCSSToImage.html
|
|
169
|
-
- docs/HTMLCSSToImage/ApiResponse.html
|
|
170
|
-
- docs/_config.yml
|
|
171
|
-
- docs/_index.html
|
|
172
|
-
- docs/class_list.html
|
|
173
|
-
- docs/css/common.css
|
|
174
|
-
- docs/css/full_list.css
|
|
175
|
-
- docs/css/style.css
|
|
176
|
-
- docs/file.README.html
|
|
177
|
-
- docs/file_list.html
|
|
178
|
-
- docs/frames.html
|
|
179
|
-
- docs/index.html
|
|
180
|
-
- docs/js/app.js
|
|
181
|
-
- docs/js/full_list.js
|
|
182
|
-
- docs/js/jquery.js
|
|
183
|
-
- docs/method_list.html
|
|
184
|
-
- docs/top-level-namespace.html
|
|
185
176
|
- htmlcsstoimage.gemspec
|
|
186
177
|
- lib/htmlcsstoimage.rb
|
|
178
|
+
- lib/htmlcsstoimage/client.rb
|
|
179
|
+
- lib/htmlcsstoimage/images.rb
|
|
180
|
+
- lib/htmlcsstoimage/recordings.rb
|
|
181
|
+
- lib/htmlcsstoimage/request_override_resource_type.rb
|
|
182
|
+
- lib/htmlcsstoimage/signed_urls.rb
|
|
183
|
+
- lib/htmlcsstoimage/templates.rb
|
|
187
184
|
- lib/htmlcsstoimage/version.rb
|
|
188
185
|
homepage: https://docs.htmlcsstoimage.com/example-code/ruby
|
|
189
186
|
licenses:
|
|
@@ -197,7 +194,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
|
197
194
|
requirements:
|
|
198
195
|
- - ">="
|
|
199
196
|
- !ruby/object:Gem::Version
|
|
200
|
-
version:
|
|
197
|
+
version: 2.7.0
|
|
201
198
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
202
199
|
requirements:
|
|
203
200
|
- - ">="
|