RubyGems - html2img-client - Versions diffs - 1.0.0 - Mend

html2img-client 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 (15) hide show

checksums.yaml +7 -0
data/CHANGELOG.md +34 -0
data/LICENSE +21 -0
data/README.md +472 -0
data/exe/html2img +6 -0
data/lib/html2img/cli.rb +218 -0
data/lib/html2img/client.rb +271 -0
data/lib/html2img/configuration.rb +98 -0
data/lib/html2img/errors.rb +92 -0
data/lib/html2img/render_response.rb +115 -0
data/lib/html2img/request.rb +141 -0
data/lib/html2img/transport.rb +64 -0
data/lib/html2img/version.rb +6 -0
data/lib/html2img-client.rb +5 -0
metadata +62 -0

data/lib/html2img/cli.rb ADDED Viewed

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+require "optparse"
+require "json"
+require_relative "client"
+module Html2img
+  # Command line interface, installed as the `html2img` executable.
+  #
+  #   html2img test
+  #   html2img html card.html --width 1200 --height 630 --out card.png
+  #   html2img screenshot https://example.com --fullpage --out shot.png
+  #   html2img template invoice-image --data '{"number": 1042}'
+  class CLI
+    TEST_DOCUMENT = <<~HTML.gsub(/\n\s*/, "")
+      <!doctype html><html><body style="font-family:system-ui;display:flex;align-items:center;
+      justify-content:center;height:180px;margin:0;background:#0f172a;color:#fff">
+      <h1>html2img is configured</h1></body></html>
+    HTML
+    COMMANDS = %w[test html screenshot template].freeze
+    RENDER_KEYS = %i[css width height dpi ms_delay wait_for_selector webhook_url fullpage
+                     format].freeze
+    # @return [Integer] a process exit code
+    def self.run(argv, out: $stdout, err: $stderr)
+      new(out: out, err: err).run(argv)
+    end
+    def initialize(out: $stdout, err: $stderr)
+      @out = out
+      @err = err
+      @options = {}
+    end
+    # @return [Integer] a process exit code
+    def run(argv)
+      argv = argv.dup
+      parser = build_parser
+      parser.order!(argv)
+      command = argv.shift
+      return version if @options[:version]
+      return usage(parser) if @options[:help] || command.nil?
+      return unknown(command) unless COMMANDS.include?(command)
+      parser.parse!(argv)
+      execute(command, argv)
+    rescue OptionParser::ParseError => e
+      fail_with(e.message)
+    end
+    private
+    def execute(command, argv)
+      client = Html2img::Client.new(api_key: @options[:api_key], timeout: @options[:timeout])
+      report(client, command, dispatch(client, command, argv))
+    rescue Html2img::ValidationError => e
+      fail_with("Request failed: #{e.message}")
+      e.details.each { |field, messages| messages.each { |m| @err.puts("  #{field}: #{m}") } }
+      1
+    rescue Html2img::Error => e
+      fail_with("Request failed: #{e.message}")
+    rescue ArgumentError, SystemCallError, JSON::ParserError => e
+      fail_with(e.message)
+    end
+    def dispatch(client, command, argv)
+      case command
+      when "test"
+        client.html(TEST_DOCUMENT, width: 600, height: 200)
+      when "html"
+        client.html(read_document(argv.shift), **render_options)
+      when "screenshot"
+        client.screenshot(argument!(argv.shift, "url"), **render_options(screenshot: true))
+      when "template"
+        client.template(argument!(argv.shift, "slug"), template_data)
+      end
+    end
+    def report(client, command, response)
+      @out.puts("Test render succeeded.") if command == "test"
+      if response.processing?
+        @out.puts("Accepted. The final URL will be delivered to your webhook.")
+        return 0
+      end
+      return fail_with("The API returned no image URL.") if response.url.to_s.empty?
+      @out.puts(response.url)
+      @out.puts("Saved to #{client.save(response, @options[:out])}") if @options[:out]
+      @out.puts("Credits remaining: #{response.credits_remaining}") if response.credits_remaining
+      0
+    end
+    def render_options(screenshot: false)
+      keys = screenshot ? RENDER_KEYS + %i[selector] : RENDER_KEYS
+      @options.slice(*keys)
+    end
+    def read_document(source)
+      argument!(source, "file")
+      source == "-" ? $stdin.read : File.read(source)
+    end
+    def template_data
+      raw = @options[:data]
+      return {} if raw.nil?
+      raw = $stdin.read if raw == "-"
+      raw = File.read(raw.delete_prefix("@")) if raw.start_with?("@")
+      parsed = JSON.parse(raw)
+      raise ArgumentError, "Template data must be a JSON object." unless parsed.is_a?(Hash)
+      parsed
+    end
+    def argument!(value, name)
+      raise ArgumentError, "Missing required argument: #{name}." if value.nil?
+      value
+    end
+    def usage(parser)
+      @out.puts(parser.help)
+      0
+    end
+    def version
+      @out.puts("html2img #{Html2img::VERSION}")
+      0
+    end
+    def unknown(command)
+      fail_with("Unknown command: #{command}. Expected one of: #{COMMANDS.join(", ")}.")
+    end
+    def fail_with(message)
+      @err.puts(message)
+      1
+    end
+    def build_parser
+      OptionParser.new do |opts|
+        opts.banner = banner
+        define_client_options(opts)
+        define_render_options(opts)
+        define_capture_options(opts)
+        define_meta_options(opts)
+      end
+    end
+    def banner
+      <<~BANNER
+        Render HTML, capture screenshots and export PDFs with html2img.com.
+        Usage: html2img <command> [options]
+        Commands:
+          test              Render a small test image to verify your setup (uses one credit)
+          html <file|->     Render an HTML file, or stdin, to an image or PDF
+          screenshot <url>  Capture a screenshot of a live URL
+          template <slug>   Render a named template
+        Options:
+      BANNER
+    end
+    def define_client_options(opts)
+      opts.on("--api-key KEY", "API key. Defaults to $HTML2IMG_API_KEY.") do |value|
+        @options[:api_key] = value
+      end
+      opts.on("--timeout SECONDS", Float, "Request timeout (default 35).") do |value|
+        @options[:timeout] = value
+      end
+    end
+    def define_render_options(opts)
+      opts.on("--width PIXELS", Integer, "Viewport width (1 to 5000).") { |v| @options[:width] = v }
+      opts.on("--height PIXELS", Integer, "Viewport height (1 to 5000).") { |v| @options[:height] = v }
+      opts.on("--dpi FACTOR", Integer, "Device pixel ratio (1 to 4).") { |v| @options[:dpi] = v }
+      opts.on("--fullpage", "Capture the full page height.") { @options[:fullpage] = true }
+      opts.on("--format FORMAT", %w[png pdf], "Output format: png or pdf.") { |v| @options[:format] = v }
+    end
+    def define_capture_options(opts)
+      opts.on("--css CSS", "Extra CSS injected after load.") { |v| @options[:css] = v }
+      opts.on("--selector SEL", "Crop the capture to this selector.") { |v| @options[:selector] = v }
+      opts.on("--ms-delay MS", Integer, "Delay before capture.") { |v| @options[:ms_delay] = v }
+      opts.on("--wait-for-selector SEL", "Wait for this selector.") do |value|
+        @options[:wait_for_selector] = value
+      end
+      opts.on("--webhook-url URL", "Deliver the result to this webhook.") do |value|
+        @options[:webhook_url] = value
+      end
+    end
+    def define_meta_options(opts)
+      opts.on("--data JSON", "Template data: JSON, @file.json, or - for stdin.") do |value|
+        @options[:data] = value
+      end
+      opts.on("-o", "--out PATH", "Also save the render to this path.") { |v| @options[:out] = v }
+      opts.on("-v", "--version", "Print the version.") { @options[:version] = true }
+      opts.on("-h", "--help", "Print this help.") { @options[:help] = true }
+    end
+  end
+end

data/lib/html2img/client.rb ADDED Viewed

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+require "json"
+require_relative "version"
+require_relative "errors"
+require_relative "configuration"
+require_relative "request"
+require_relative "render_response"
+require_relative "transport"
+module Html2img
+  # 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
+  # {Html2img::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.
+  class Client
+    HTML_PATH = "/api/html"
+    SCREENSHOT_PATH = "/api/screenshot"
+    TEMPLATE_PATH = "/api/v1/templates"
+    # @return [String] the API base URL in use
+    attr_reader :base_url
+    # @return [Float] the per-request timeout in seconds
+    attr_reader :timeout
+    # @param api_key [String, nil] defaults to {Html2img.configuration}, which
+    #   itself defaults to the HTML2IMG_API_KEY environment variable
+    # @param base_url [String, nil] override only for testing or a private deployment
+    # @param timeout [Numeric, nil] request timeout in seconds
+    # @param transport [#call, nil] see {Transport}
+    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
+    # 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")
+    #
+    # @param html [String] a complete HTML document
+    # @return [RenderResponse]
+    # @raise [Html2img::Error] on any API or transport failure
+    def html(html, **options)
+      post(HTML_PATH, Request.html_body(html, options))
+    end
+    # Capture a screenshot of a live URL (POST /api/screenshot).
+    #
+    #   client.screenshot("https://example.com", fullpage: true, selector: "#hero")
+    #
+    # @param url [String] a publicly reachable URL
+    # @return [RenderResponse]
+    # @raise [Html2img::Error] on any API or transport failure
+    def screenshot(url, **options)
+      post(SCREENSHOT_PATH, Request.screenshot_body(url, options))
+    end
+    # 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.
+    #
+    # @param slug [String] the template slug, for example "invoice-image"
+    # @param data [Hash] template data
+    # @param fields [Hash] template data as keyword arguments, merged over data
+    # @return [RenderResponse]
+    # @raise [Html2img::Error] on any API or transport failure
+    def template(slug, data = {}, **fields)
+      Request.required_string!("slug", slug)
+      post("#{TEMPLATE_PATH}/#{encode(slug)}", data.merge(fields))
+    end
+    # Download the rendered bytes from a render's CDN URL.
+    #
+    # @param image [RenderResponse, String] a response or a URL
+    # @return [String] the binary body
+    # @raise [Html2img::Error] if the render has no URL yet, or the download fails
+    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
+    # Download a render and write it to a local file.
+    #
+    # Parent directories are created for you.
+    #
+    #   client.save(response, "og/post-42.png")
+    #
+    # @return [String] the path written
+    # @raise [Html2img::Error] if the render has no URL yet, or the download fails
+    def save(image, path)
+      require "fileutils"
+      contents = download(image)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.binwrite(path, contents)
+      path
+    end
+    def inspect
+      "#<Html2img::Client base_url=#{base_url.inspect} timeout=#{timeout.inspect}>"
+    end
+    private
+    def post(path, body)
+      status, raw = @transport.call(
+        method: "POST",
+        url: "#{base_url}#{path}",
+        headers: headers,
+        body: JSON.generate(body),
+        timeout: timeout
+      )
+      payload = decode(raw)
+      raise error_for(status, payload) if status >= 400
+      RenderResponse.from_hash(payload)
+    end
+    def headers
+      {
+        "X-API-Key" => @api_key,
+        "Accept" => "application/json",
+        "Content-Type" => "application/json",
+        "User-Agent" => user_agent
+      }
+    end
+    def user_agent
+      "html2img-ruby/#{Html2img::VERSION}"
+    end
+    def encode(slug)
+      require "erb"
+      ERB::Util.url_encode(slug)
+    end
+    def decode(body)
+      return {} if body.nil? || body.empty?
+      parsed = JSON.parse(body)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError
+      {}
+    end
+    def url_for(image)
+      return Request.required_string!("image url", image) if image.is_a?(String)
+      unless image.respond_to?(:url)
+        raise ArgumentError, "Expected a RenderResponse or a URL String, got #{image.class}."
+      end
+      if image.url.nil? || image.url.empty?
+        raise Error, "The render has no image URL yet. Async jobs deliver their URL to the " \
+                     "configured webhook."
+      end
+      image.url
+    end
+    def resolve_api_key(key)
+      if key.nil? || key.to_s.empty?
+        raise ArgumentError,
+              "No html2img API key. Pass api_key:, set Html2img.configure, or set the " \
+              "HTML2IMG_API_KEY environment variable. Create a free key at " \
+              "https://app.html2img.com/register."
+      end
+      key.to_s
+    end
+    def resolve_base_url(value)
+      (value || DEFAULT_BASE_URL).to_s.sub(%r{/+\z}, "")
+    end
+    def resolve_timeout(value)
+      timeout = Float(value || DEFAULT_TIMEOUT)
+      raise ArgumentError, "The timeout must be positive, got #{value}." unless timeout.positive?
+      timeout
+    rescue TypeError, ArgumentError => e
+      raise ArgumentError, e.message
+    end
+    # The exception class for each status the API documents.
+    ERRORS = {
+      400 => ValidationError,
+      401 => AuthenticationError,
+      402 => InsufficientCreditsError,
+      403 => NotSubscribedError,
+      404 => NotFoundError,
+      408 => TimeoutError,
+      422 => ValidationError,
+      429 => RateLimitError,
+      504 => TimeoutError
+    }.freeze
+    private_constant :ERRORS
+    def error_for(status, payload)
+      kind = ERRORS[status] || (status >= 500 ? ServerError : Error)
+      options = {
+        status_code: status,
+        payload: payload,
+        error_code: (payload["code"] if payload["code"].is_a?(String))
+      }
+      return kind.new(message_from(payload, status), details: details_from(payload), **options) if
+        kind == ValidationError
+      kind.new(message_from(payload, status), **options)
+    end
+    def message_from(payload, status)
+      %w[error message].each do |key|
+        value = payload[key]
+        return value if value.is_a?(String) && !value.empty?
+      end
+      "The html2img API returned HTTP #{status}."
+    end
+    def details_from(payload)
+      details = payload["details"]
+      return {} unless details.is_a?(Hash)
+      details.each_with_object({}) do |(field, messages), result|
+        result[field.to_s] = Array(messages).map(&:to_s)
+      end
+    end
+  end
+end

data/lib/html2img/configuration.rb ADDED Viewed

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+# Official Ruby client for the html2img.com HTML to Image API.
+#
+# See {Html2img::Client} for the API surface, and {Html2img.configure} for
+# process-wide defaults.
+module Html2img
+  # Base URL of the API. Override only for testing or a private deployment.
+  DEFAULT_BASE_URL = "https://app.html2img.com"
+  # Request timeout in seconds, just over the 30 second synchronous render budget.
+  DEFAULT_TIMEOUT = 35.0
+  # Process-wide defaults, for applications that would rather configure once
+  # than pass a client around.
+  #
+  #   Html2img.configure do |config|
+  #     config.api_key = ENV.fetch("HTML2IMG_API_KEY")
+  #     config.timeout = 45
+  #   end
+  #
+  # In a Rails app this belongs in an initializer.
+  class Configuration
+    # @return [String, nil] sent as the `X-API-Key` header
+    attr_accessor :api_key
+    # @return [String] the API base URL
+    attr_accessor :base_url
+    # @return [Float] request timeout in seconds
+    attr_accessor :timeout
+    # @return [#call, nil] a custom transport, see {Transport}
+    attr_accessor :transport
+    def initialize
+      @api_key = ENV.fetch("HTML2IMG_API_KEY", nil)
+      @base_url = ENV.fetch("HTML2IMG_BASE_URI", nil) || DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @transport = nil
+    end
+  end
+  class << self
+    # The process-wide configuration.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    # Configure the defaults used by {Html2img.client}.
+    #
+    # @yieldparam config [Configuration]
+    def configure
+      yield(configuration) if block_given?
+      # A reconfigured process should not keep handing out the old client.
+      @client = nil
+      configuration
+    end
+    # A memoised client built from {configuration}.
+    def client
+      @client ||= Client.new
+    end
+    # Forget the configuration and the memoised client. Mostly for tests.
+    def reset!
+      @configuration = nil
+      @client = nil
+    end
+    # Render an HTML document with the default client.
+    def html(...)
+      client.html(...)
+    end
+    # Capture a screenshot with the default client.
+    def screenshot(...)
+      client.screenshot(...)
+    end
+    # Render a named template with the default client.
+    def template(...)
+      client.template(...)
+    end
+    # Download a render with the default client.
+    def download(...)
+      client.download(...)
+    end
+    # Save a render to disk with the default client.
+    def save(...)
+      client.save(...)
+    end
+  end
+end

data/lib/html2img/errors.rb ADDED Viewed

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+module Html2img
+  # Base type for every error raised by the client at request time.
+  #
+  # Rescuing this single type is enough to handle any failure originating from
+  # the gem. No raw Net::HTTP exception is ever allowed to escape the public
+  # API. Invalid arguments are reported before any request is sent, as a plain
+  # ArgumentError.
+  class Error < StandardError
+    # @return [Integer, nil] the HTTP status, when the failure came from a response
+    attr_reader :status_code
+    # @return [String, nil] the machine-readable `code` from the API body
+    attr_reader :error_code
+    # @return [Hash] the decoded JSON response body, when available
+    attr_reader :payload
+    def initialize(message, status_code: nil, payload: {}, error_code: nil)
+      super(message)
+      @status_code = status_code
+      @payload = payload || {}
+      @error_code = error_code
+    end
+    # The message with the API's error code appended, when there is one.
+    def to_s
+      error_code ? "#{super} (#{error_code})" : super
+    end
+  end
+  # Raised on a 401: the API key is missing or not recognised.
+  # The API `code` is `missing_api_key` or `invalid_api_key`.
+  class AuthenticationError < Error; end
+  # Raised on a 402: authenticated, but out of credits for the period.
+  # The API `code` is `insufficient_credits`.
+  class InsufficientCreditsError < Error
+    # @return [Integer, nil] credits left on the account. Zero on a 402.
+    def credits_remaining
+      value = payload["credits_remaining"]
+      value.is_a?(Integer) ? value : nil
+    end
+  end
+  # Raised on a 403: the key is valid but the account has no active subscription.
+  # The API `code` is `not_subscribed`.
+  class NotSubscribedError < Error; end
+  # Raised on a 404, for example when a template slug does not exist.
+  # The API `code` is `template_not_found`.
+  class NotFoundError < Error; end
+  # Raised on a 400 or 422 when one or more request fields fail validation.
+  # The API `code` is `validation_error`.
+  class ValidationError < Error
+    # @return [Hash{String => Array<String>}] per-field validation messages
+    attr_reader :details
+    def initialize(message, details: {}, **options)
+      super(message, **options)
+      @details = details || {}
+    end
+  end
+  # Raised on a 429: too many requests, or a plan quota was exceeded.
+  class RateLimitError < Error
+    # @return [Integer, nil] seconds to wait before retrying, when supplied
+    def retry_after
+      value = payload["retry_after"]
+      value.is_a?(Integer) ? value : nil
+    end
+  end
+  # Raised on a 408 or 504, or when the local timeout elapses.
+  #
+  # The API `code` is `timeout_error` or `api_timeout_error`. For captures that
+  # routinely take this long, pass a `webhook_url` to switch to asynchronous
+  # delivery.
+  class TimeoutError < Error; end
+  # Raised on a 5xx when the renderer returns an unexpected error.
+  # The API `code` is `service_error`.
+  class ServerError < Error; end
+  # Raised when the request never reaches a response: DNS failure, refused
+  # connection or a TLS error.
+  class ConnectionError < Error; end
+end