Class: Html2img::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/html2img/client.rb

Overview

Client for the html2img.com API.

Render HTML documents you control, capture live URLs, or render named templates, each returning a RenderResponse. Every failure surfaces as an Error; no raw Net::HTTP exception escapes.

client = Html2img::Client.new           # reads HTML2IMG_API_KEY
response = client.html("<h1>Hello</h1>", width: 1200, height: 630)
response.url # => "https://i.html2img.com/abc123.png"

A client is cheap to build and safe to share between threads.

Constant Summary collapse

HTML_PATH = 
"/api/html"
SCREENSHOT_PATH = 
"/api/screenshot"
TEMPLATE_PATH = 
"/api/v1/templates"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key: nil, base_url: nil, timeout: nil, transport: nil) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String, nil) (defaults to: nil) —

    defaults to Html2img.configuration, which itself defaults to the HTML2IMG_API_KEY environment variable

  • base_url (String, nil) (defaults to: nil) —

    override only for testing or a private deployment

  • timeout (Numeric, nil) (defaults to: nil) —

    request timeout in seconds

  • transport (#call, nil) (defaults to: nil) —

    see Transport



40
41
42
43
44
45
46
47
 
# File 'lib/html2img/client.rb', line 40

def initialize(api_key: nil, base_url: nil, timeout: nil, transport: nil)
  config = Html2img.configuration

  @api_key = resolve_api_key(api_key || config.api_key)
  @base_url = resolve_base_url(base_url || config.base_url)
  @timeout = resolve_timeout(timeout || config.timeout)
  @transport = transport || config.transport || Transport.new
end

Instance Attribute Details

#base_url ⇒ String (readonly)

Returns the API base URL in use.

Returns:

  • (String) —

    the API base URL in use



30
31
32
 
# File 'lib/html2img/client.rb', line 30

def base_url
  @base_url
end

#timeout ⇒ Float (readonly)

Returns the per-request timeout in seconds.

Returns:

  • (Float) —

    the per-request timeout in seconds



33
34
35
 
# File 'lib/html2img/client.rb', line 33

def timeout
  @timeout
end

Instance Method Details

#download(image) ⇒ String

Download the rendered bytes from a render's CDN URL.

Parameters:

Returns:

  • (String) —

    the binary body

Raises:

  • (Html2img::Error) —

    if the render has no URL yet, or the download fails



95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/html2img/client.rb', line 95

def download(image)
  url = url_for(image)

  status, body = @transport.call(
    method: "GET",
    url: url,
    headers: { "Accept" => "*/*", "User-Agent" => user_agent },
    body: nil,
    timeout: timeout
  )

  if status >= 400
    raise Error.new("Could not download the render from #{url}: HTTP #{status}.",
                    status_code: status)
  end

  body
end

#html(html, **options) ⇒ RenderResponse

Render an HTML document to an image or PDF (POST /api/html).

client.html(document, width: 1200, height: 630, dpi: 2)
client.html(document, format: "pdf")

Parameters:

  • html (String) —

    a complete HTML document

Returns:

Raises:



57
58
59
 
# File 'lib/html2img/client.rb', line 57

def html(html, **options)
  post(HTML_PATH, Request.html_body(html, options))
end

#inspect ⇒ Object 



132
133
134
 
# File 'lib/html2img/client.rb', line 132

def inspect
  "#<Html2img::Client base_url=#{base_url.inspect} timeout=#{timeout.inspect}>"
end

#save(image, path) ⇒ String

Download a render and write it to a local file.

Parent directories are created for you.

client.save(response, "og/post-42.png")

Returns:

  • (String) —

    the path written

Raises:

  • (Html2img::Error) —

    if the render has no URL yet, or the download fails



122
123
124
125
126
127
128
129
130
 
# File 'lib/html2img/client.rb', line 122

def save(image, path)
  require "fileutils"

  contents = download(image)
  FileUtils.mkdir_p(File.dirname(path))
  File.binwrite(path, contents)

  path
end

#screenshot(url, **options) ⇒ RenderResponse

Capture a screenshot of a live URL (POST /api/screenshot).

client.screenshot("https://example.com", fullpage: true, selector: "#hero")

Parameters:

  • url (String) —

    a publicly reachable URL

Returns:

Raises:



68
69
70
 
# File 'lib/html2img/client.rb', line 68

def screenshot(url, **options)
  post(SCREENSHOT_PATH, Request.screenshot_body(url, options))
end

#template(slug, data = {}, **fields) ⇒ RenderResponse

Render a named template from a data payload.

client.template("invoice-image", number: 1042, amount: "£240.00")
client.template("invoice-image", { "number" => 1042 })

The data is validated server-side per template. Templates output PNG only.

Parameters:

  • slug (String) —

    the template slug, for example "invoice-image"

  • data (Hash) (defaults to: {}) —

    template data

  • fields (Hash) —

    template data as keyword arguments, merged over data

Returns:

Raises:



84
85
86
87
88
 
# File 'lib/html2img/client.rb', line 84

def template(slug, data = {}, **fields)
  Request.required_string!("slug", slug)

  post("#{TEMPLATE_PATH}/#{encode(slug)}", data.merge(fields))
end