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.
Files changed (38) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/ruby.yml +2 -0
  3. data/Gemfile.lock +3 -1
  4. data/README.md +299 -10
  5. data/htmlcsstoimage.gemspec +4 -2
  6. data/lib/htmlcsstoimage/client.rb +36 -0
  7. data/lib/htmlcsstoimage/images.rb +193 -0
  8. data/lib/htmlcsstoimage/recordings.rb +108 -0
  9. data/lib/htmlcsstoimage/request_override_resource_type.rb +33 -0
  10. data/lib/htmlcsstoimage/signed_urls.rb +130 -0
  11. data/lib/htmlcsstoimage/templates.rb +100 -0
  12. data/lib/htmlcsstoimage/version.rb +2 -1
  13. data/lib/htmlcsstoimage.rb +9 -151
  14. metadata +26 -29
  15. data/cassettes/HTMLCSSToImage/_create_image/accepts_additional_params.yml +0 -66
  16. data/cassettes/HTMLCSSToImage/_create_image/creates_an_image.yml +0 -64
  17. data/cassettes/HTMLCSSToImage/_create_template/creates_a_new_template.yml +0 -62
  18. data/cassettes/HTMLCSSToImage/_delete_image/deletes_an_image.yml +0 -60
  19. data/cassettes/HTMLCSSToImage/_templates/retrieves_templates.yml +0 -110
  20. data/cassettes/HTMLCSSToImage/_url_to_image/accepts_additional_params.yml +0 -64
  21. data/cassettes/HTMLCSSToImage/_url_to_image/creates_an_image_from_a_url.yml +0 -64
  22. data/docs/HTMLCSSToImage/ApiResponse.html +0 -124
  23. data/docs/HTMLCSSToImage.html +0 -1340
  24. data/docs/_config.yml +0 -1
  25. data/docs/_index.html +0 -122
  26. data/docs/class_list.html +0 -51
  27. data/docs/css/common.css +0 -1
  28. data/docs/css/full_list.css +0 -58
  29. data/docs/css/style.css +0 -496
  30. data/docs/file.README.html +0 -187
  31. data/docs/file_list.html +0 -56
  32. data/docs/frames.html +0 -17
  33. data/docs/index.html +0 -187
  34. data/docs/js/app.js +0 -314
  35. data/docs/js/full_list.js +0 -216
  36. data/docs/js/jquery.js +0 -4
  37. data/docs/method_list.html +0 -107
  38. 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
@@ -1,3 +1,4 @@
1
1
  class HTMLCSSToImage
2
- VERSION = "0.1.4"
2
+ # Current version of the Ruby client gem.
3
+ VERSION = "1.0.0"
3
4
  end
@@ -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
- class HTMLCSSToImage
7
- include HTTParty
8
- base_uri 'https://hcti.io'
9
- headers 'Content-Type' => 'application/json'
10
- format :json
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.1.4
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: 2024-11-08 00:00:00.000000000 Z
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
- description: 'Ruby client for the HTML/CSS to Image API. Generate a png, jpg or webp
141
- images with Ruby. Renders exactly like Google Chrome. '
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: '0'
197
+ version: 2.7.0
201
198
  required_rubygems_version: !ruby/object:Gem::Requirement
202
199
  requirements:
203
200
  - - ">="