html2img-client 1.0.0

data/lib/html2img/render_response.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Html2img
+  # The result of a successful render call.
+  #
+  # Covers both the synchronous envelope (`url` populated) and the asynchronous
+  # acceptance envelope returned when a `webhook_url` was supplied (`status` is
+  # "processing" and `url` is nil until the webhook fires).
+  class RenderResponse
+    # @return [Boolean]
+    attr_reader :success
+
+    # @return [String, nil] the render id
+    attr_reader :id
+
+    # @return [String, nil] the CDN URL of the render
+    attr_reader :url
+
+    # @return [String, nil] when a hosted render expires, as an ISO 8601 string.
+    #   Nil on paid plans, where renders stay hosted permanently; set on
+    #   free-tier renders, which are hosted for seven days.
+    attr_reader :expires_at
+
+    # @return [Integer, nil] credits left after this call
+    attr_reader :credits_remaining
+
+    # @return [String, nil] "processing" for async jobs
+    attr_reader :status
+
+    # @return [String, nil]
+    attr_reader :message
+
+    # @return [String, nil] the template slug, when applicable
+    attr_reader :template
+
+    # @return [Hash] the full decoded JSON payload
+    attr_reader :raw
+
+    # Build a response from a decoded JSON payload.
+    def self.from_hash(data)
+      data = {} unless data.is_a?(Hash)
+
+      new(
+        success: data["success"] ? true : false,
+        id: string_or_nil(data["id"]),
+        url: string_or_nil(data["url"]),
+        expires_at: string_or_nil(data["expires_at"]),
+        credits_remaining: integer_or_nil(data["credits_remaining"]),
+        status: string_or_nil(data["status"]),
+        message: string_or_nil(data["message"]),
+        template: string_or_nil(data["template"]),
+        raw: data
+      )
+    end
+
+    def self.string_or_nil(value)
+      return nil if value.nil? || value.is_a?(Hash) || value.is_a?(Array)
+
+      value.to_s
+    end
+
+    def self.integer_or_nil(value)
+      return value if value.is_a?(Integer)
+      return value.to_i if value.is_a?(Float)
+      return Integer(value, exception: false) if value.is_a?(String)
+
+      nil
+    end
+
+    private_class_method :string_or_nil, :integer_or_nil
+
+    def initialize(success: false, id: nil, url: nil, expires_at: nil, credits_remaining: nil,
+                   status: nil, message: nil, template: nil, raw: {})
+      @success = success
+      @id = id
+      @url = url
+      @expires_at = expires_at
+      @credits_remaining = credits_remaining
+      @status = status
+      @message = message
+      @template = template
+      @raw = raw
+      freeze
+    end
+
+    # Whether this is an async job still being rendered.
+    #
+    # When true, the final URL is delivered to the request's `webhook_url`
+    # rather than being available on this response.
+    def processing?
+      status == "processing"
+    end
+
+    # Whether the render came back as a PDF rather than an image.
+    def pdf?
+      return false if url.nil?
+
+      url.to_s.split("?").first.to_s.downcase.end_with?(".pdf")
+    end
+
+    def success?
+      success
+    end
+
+    # The URL, so a response drops straight into string interpolation.
+    def to_s
+      url.to_s
+    end
+
+    def inspect
+      "#<Html2img::RenderResponse url=#{url.inspect} status=#{status.inspect} " \
+        "credits_remaining=#{credits_remaining.inspect}>"
+    end
+  end
+end

data/lib/html2img/request.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Html2img
+  # Builds and validates the JSON bodies sent to the render endpoints.
+  #
+  # The range checks mirror the server-side validation rules, so an obvious
+  # mistake fails fast with a clear message before a request is sent, and
+  # before a credit is spent. Any option left nil is omitted from the body, so
+  # the server applies its own default.
+  #
+  # @api private
+  module Request
+    MIN_DIMENSION = 1
+    MAX_DIMENSION = 5000
+    MIN_DPI = 1
+    MAX_DPI = 4
+    MIN_MS_DELAY = 1
+    MAX_MS_DELAY = 5000
+
+    FORMATS = %w[png pdf].freeze
+
+    # Options accepted by both render endpoints.
+    COMMON_OPTIONS = %i[
+      css width height fullpage dpi webhook_url ms_delay wait_for_selector format scale_to_fit
+    ].freeze
+
+    # `selector` crops a screenshot to one element. There is no equivalent for
+    # an HTML render, since you control the markup.
+    SCREENSHOT_OPTIONS = (COMMON_OPTIONS + %i[selector]).freeze
+
+    module_function
+
+    # Build the body for POST /api/html.
+    #
+    # @param html [String] a complete HTML document
+    # @return [Hash]
+    def html_body(html, options)
+      validate_keys!(options, COMMON_OPTIONS)
+
+      body = { "html" => required_string!("html", html) }
+
+      body.merge(common(options)).compact
+    end
+
+    # Build the body for POST /api/screenshot.
+    #
+    # @param url [String] a publicly reachable URL
+    # @return [Hash]
+    def screenshot_body(url, options)
+      validate_keys!(options, SCREENSHOT_OPTIONS)
+
+      body = { "url" => required_string!("url", url) }
+      body["selector"] = optional_string!("selector", options[:selector])
+
+      body.merge(common(options)).compact
+    end
+
+    # The options shared by both endpoints, mapped onto their API field names.
+    def common(options)
+      {
+        "css" => optional_string!("css", options[:css]),
+        "width" => dimension!("width", options[:width]),
+        "height" => dimension!("height", options[:height]),
+        "fullpage" => boolean!("fullpage", options[:fullpage]),
+        "dpi" => dpi!(options[:dpi]),
+        "webhook_url" => optional_string!("webhook_url", options[:webhook_url]),
+        "ms_delay" => ms_delay!(options[:ms_delay]),
+        "wait_for_selector" => optional_string!("wait_for_selector", options[:wait_for_selector]),
+        "format" => format!(options[:format]),
+        "scale_to_fit" => boolean!("scale_to_fit", options[:scale_to_fit])
+      }
+    end
+
+    def validate_keys!(options, allowed)
+      unknown = options.keys - allowed
+
+      return if unknown.empty?
+
+      raise ArgumentError,
+            "Unknown option(s): #{unknown.join(", ")}. " \
+            "Valid options are: #{allowed.sort.join(", ")}."
+    end
+
+    def required_string!(name, value)
+      raise ArgumentError, "The #{name} must be a String, got #{value.class}." unless value.is_a?(String)
+
+      raise ArgumentError, "The #{name} must not be empty." if value.empty?
+
+      value
+    end
+
+    def optional_string!(name, value)
+      return nil if value.nil?
+
+      raise ArgumentError, "The #{name} must be a String, got #{value.class}." unless value.is_a?(String)
+
+      value
+    end
+
+    def boolean!(name, value)
+      return nil if value.nil?
+      return value if [true, false].include?(value)
+
+      raise ArgumentError, "The #{name} must be true or false, got #{value.inspect}."
+    end
+
+    def dimension!(name, value)
+      integer_in_range!(name, value, MIN_DIMENSION, MAX_DIMENSION)
+    end
+
+    def dpi!(value)
+      integer_in_range!("dpi", value, MIN_DPI, MAX_DPI)
+    end
+
+    def ms_delay!(value)
+      integer_in_range!("ms_delay", value, MIN_MS_DELAY, MAX_MS_DELAY)
+    end
+
+    def integer_in_range!(name, value, low, high)
+      return nil if value.nil?
+
+      raise ArgumentError, "The #{name} must be an Integer, got #{value.class}." unless value.is_a?(Integer)
+
+      unless value.between?(low, high)
+        raise ArgumentError, "The #{name} must be between #{low} and #{high}, got #{value}."
+      end
+
+      value
+    end
+
+    def format!(value)
+      return nil if value.nil?
+
+      normalised = value.to_s.downcase
+
+      return normalised if FORMATS.include?(normalised)
+
+      raise ArgumentError, "The format must be one of: #{FORMATS.join(", ")}. Got #{value.inspect}."
+    end
+  end
+end

data/lib/html2img/transport.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module Html2img
+  # HTTP transport for the client.
+  #
+  # The default is built on Net::HTTP from the standard library, so the gem has
+  # no runtime dependencies. Anything responding to #call with the same
+  # signature can be passed to {Client} as `transport:`, which is the seam for
+  # Faraday, HTTPX, a proxy, retry middleware, or a stub in your tests.
+  #
+  # A transport returns the raw [status, body] pair for *any* HTTP response,
+  # including 4xx and 5xx. Mapping a status onto a typed error is the client's
+  # job. A transport only raises when no response was received at all.
+  class Transport
+    # @param method [String] "POST" or "GET"
+    # @param url [String] the absolute URL
+    # @param headers [Hash{String => String}]
+    # @param body [String, nil] the request body
+    # @param timeout [Float] seconds
+    # @return [Array(Integer, String)] status and body
+    def call(method:, url:, headers:, body:, timeout:)
+      uri = URI.parse(url)
+      request = build_request(method, uri, headers, body)
+
+      response = http(uri, timeout).request(request)
+
+      [response.code.to_i, response.body.to_s]
+    # Net::OpenTimeout and Net::ReadTimeout both descend from Timeout::Error.
+    rescue Timeout::Error => e
+      raise TimeoutError, "The request to #{url} timed out after #{timeout} seconds: #{e.message}"
+    rescue SocketError, SystemCallError, OpenSSL::SSL::SSLError, IOError, Net::HTTPBadResponse => e
+      raise ConnectionError, "Could not reach the html2img API: #{e.message}"
+    end
+
+    private
+
+    def http(uri, timeout)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+      http
+    end
+
+    def build_request(method, uri, headers, body)
+      request =
+        case method.to_s.upcase
+        when "POST" then Net::HTTP::Post.new(uri)
+        when "GET" then Net::HTTP::Get.new(uri)
+        else raise ArgumentError, "Unsupported HTTP method: #{method}"
+        end
+
+      headers.each { |name, value| request[name] = value }
+      request.body = body if body
+
+      request
+    end
+  end
+end

data/lib/html2img/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Html2img
+  # Single source of truth for the gem version.
+  VERSION = "1.0.0"
+end

data/lib/html2img-client.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name, so `gem "html2img-client"` works with
+# Bundler's default require. Everything lives under html2img/.
+require "html2img/client"

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: html2img-client
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- html2img
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  Render HTML and CSS to images, capture screenshots of live URLs, render named
+  templates and export A4 PDFs, all in real Chrome. Zero runtime dependencies.
+email:
+- info@html2img.com
+executables:
+- html2img
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/html2img
+- lib/html2img-client.rb
+- lib/html2img/cli.rb
+- lib/html2img/client.rb
+- lib/html2img/configuration.rb
+- lib/html2img/errors.rb
+- lib/html2img/render_response.rb
+- lib/html2img/request.rb
+- lib/html2img/transport.rb
+- lib/html2img/version.rb
+homepage: https://html2img.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://html2img.com
+  source_code_uri: https://github.com/html2img/html2img-ruby
+  changelog_uri: https://github.com/html2img/html2img-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/html2img/html2img-ruby/issues
+  documentation_uri: https://html2img.com/docs/usage/ruby
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby client for the html2img HTML to Image API.
+test_files: []