kleya 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 272b77784c8f74811be0db9402ff4694220c0a212ca4d6af53e6b61ff2398df0
-  data.tar.gz: bb4451a8bb5bea56482ef1c48ae02b321da627218569fcca09ecd5c3d0b18b69
+  metadata.gz: f9d67fbb3a7754b0af20ff18f877da9f7fe8eb1c1f2885c94a17ab8f8c0ab85c
+  data.tar.gz: 6ead13010ce66ca8d0f96e07b5df9abab103c3014ad66d1584d22d16981a5e13
 SHA512:
-  metadata.gz: 74262f4d700dc1d2d1c3e5e224801e8e95bdb55d47326167ba6a4d8154139e89a08d92a2a8ddd95b3e4af2ef01d5bf0ff12d5529213f57f963771864ffb363c4
-  data.tar.gz: e1635c52e75051a00528aa59f4b70d58a28d7993ab1f1d414f60de869ed569198b3ccd726182393fc5169d31d1af4317aa0ab2a7d1b67c4f6c8b0a3d8db524da
+  metadata.gz: c9a46f780e038d591dd60d2172258cbd12128ce2342c672a4fdb5d92d93efc903f1e045cbc5375379f5beb7b696e6723a845fb3a3368ef8fed3dcc44ed290be1
+  data.tar.gz: cf575c64b78b13c15f5a654725c7b4779b2ce15f0a71a8b641f01ff54d19500e59f7c6b1695f571566f6b92d7b62bb9328ca50d9ea0478ee1b49cef1832d50fb

data/README.md

@@ -30,6 +30,12 @@ The simplest way to capture a screenshot and save it can look like this,
 Kleya.capture('https://www.hellotext.com').save
 ```
 
+Or directly via the CLI
+
+```bash
+kleya https://www.hellotext.com
+```
+
 ## Usage
 
 ```ruby
@@ -52,11 +58,32 @@ puts artifact.content_type  # "image/jpeg"
 browser.quit
 ```
 
+## CLI Usage
+
+Kleya includes a command-line interface for quick screenshot captures:
+
+```bash
+# Basic usage
+kleya https://www.hellotext.com
+
+# With options
+kleya https://www.hellotext.com --format png --quality 95 --area page
+```
+
+CLI Options
+
+- `--format`, `-f` - Image format (jpeg, png). Default: jpeg
+- `--quality`, `-q` - Image quality (1-100). Default: 90
+- `--area`, `-a` - Capture area (viewport, page). Default: viewport
+- `--encoding`, `-e` - Output encoding (binary, base64). Default: base64
+- `--output`, `-o` - Output destination, defaults to the current directory.
+- `--help`, `-h` - Show help message
+
 ### Presets
 
 Kleya includes convenient viewport presets for social media platforms and common devices. You can pass any of the following values when initializing a browser instance.
 
-- `desktop`: default (1920x1080)
+- `desktop` default (1920x1080)
 
 - `x` (1200x675)
 - `facebook` (1200x630)
@@ -109,9 +136,10 @@ Kleya.capture('https://www.hellotext.com')
 
 Alongside the options you pass for the instance, there's some extra configurable settings you can tweak to your usecase.
 
-- `format`: specifies the format of the image captures, i.e `jpeg` or `png`.
-- `encoding`: specifies the encoding of the image, possible options is `binary` or `base64` (default). Regardless, the `Kleya::Artifact` object responds to `#binary` and `base64` when needed.
-- `quality`: an integer between 1 - 100 that determines the quality of the final image, higher quality images result in bigger sizes and may not work correctly in some situations such as the Open Graph (OG) protocol, you can tweak and test this. Defaults to `90`.
+- `format` specifies the format of the image captures, i.e `jpeg` or `png`.
+- `encoding` specifies the encoding of the image, possible options is `binary` or `base64` (default). Regardless, the `Kleya::Artifact` object responds to `#binary` and `base64` when needed.
+- `quality` an integer between 1 - 100 that determines the quality of the final image, higher quality images result in bigger sizes and may not work correctly in some situations such as the Open Graph (OG) protocol, you can tweak and test this. Defaults to `90`.
+- `area` specifies the area of the browser to capture, defaults to `viewport` for capturing only the visible part of the page. Supported values are `viewport` and `page` for full-page screenshots.
 
 ```ruby
 artifact = browser.capture('https://example.com', format: :jpeg, quality: 85, encoding: :base64)
@@ -181,14 +209,11 @@ end
 ## Roadmap
 
 - Wait strategies (`wait_for: '.element'`, `wait_until: :network_idle`)
-- Full page screenshots (not just viewport)
 - Built-in retry mechanism with configurable delays
 
 - Memory usage optimization for large batches
 - Request blocking (ads, analytics, fonts)
-- Custom user agents for mobile rendering
 
-- CLI tool for quick captures (`kleya capture https://example.com`)
 - Debug mode with browser preview
 - Capture metrics (timing, size, errors)
 

data/bin/kleya

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'kleya'
+
+options = {
+  format: :jpeg,
+  quality: 90,
+  area: :viewport,
+  encoding: :base64,
+  output: nil
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: kleya [url] [options]'
+
+  opts.on('-f', '--format FORMAT', [:jpeg, :png], 'Image format (jpeg, png)') do |format|
+    options[:format] = format
+  end
+
+  opts.on('-q', '--quality QUALITY', Integer, 'Image quality (0-100)') do |quality|
+    options[:quality] = quality
+  end
+
+  opts.on('-a', '--area AREA', [:viewport, :full], 'Area to capture (viewport, full)') do |area|
+    options[:area] = area
+  end
+
+  opts.on('-e', '--encoding ENCODING', [:base64, :binary], 'Encoding (base64, binary)') do |encoding|
+    options[:encoding] = encoding
+  end
+
+  opts.on('-o', '--output OUTPUT', String, 'Output file path') do |output|
+    options[:output] = output
+  end
+
+  opts.on('-h', '--help', 'Show this message') do
+    puts opts
+    exit
+  end
+end
+
+parser.parse!
+
+if ARGV.empty?
+  puts "Error: URL is required"
+  puts parser
+  exit 1
+end
+
+Kleya.capture(ARGV[0], **options).save(options[:output])

data/lib/kleya/artifact.rb

@@ -39,6 +39,8 @@ module Kleya
         path = filename
       elsif File.directory?(path)
         path = File.join(path, filename)
+      elsif File.extname(path).empty?
+        path = "#{path}.#{@format}"
       end
 
       File.write(path, binary, mode: 'wb').then { path }

data/lib/kleya/browser.rb

@@ -30,6 +30,7 @@ module Kleya
     # @option options [Symbol] :format (:jpeg) image format (:jpeg, :png)
     # @option options [Integer] :quality (90) JPEG quality (1-100)
     # @option options [Symbol] :encoding (:base64) output encoding
+    # @option options [Symbol] :area (:viewport) the area to capture (:viewport, :page)
     # @return [Artifact] the screenshot artifact
     # @example Taking a X-optimized screenshot
     #   browser = Kleya::Browser.new(
@@ -43,12 +44,9 @@ module Kleya
       format = options[:format] || :jpeg
       quality = options[:quality] || 90
       encoding = options[:encoding] || :base64
+      full = options[:area] == :page
 
-      data = browser.screenshot(
-        format: format,
-        quality: quality,
-        encoding: encoding
-      )
+      data = browser.screenshot(format:, quality:, encoding:, full:)
 
       Artifact.new(data:, url:, viewport: @viewport, format:, quality:, encoding:)
     rescue Ferrum::TimeoutError

data/test/artifact_test.rb

@@ -11,6 +11,11 @@ class ArtifactTest < Minitest::Test
     )
   end
 
+  def teardown
+    FileUtils.rm_f('test.jpg')
+    FileUtils.rm_f('appends_extension.jpeg')
+  end
+
   def test_artifact_size
     assert_equal(4, @artifact.size)
   end
@@ -19,6 +24,16 @@ class ArtifactTest < Minitest::Test
     assert_runs_without_errors do
       @artifact.save('test.jpg')
     end
+
+    assert File.exist?('test.jpg')
+  end
+
+  def test_artifact_save_with_content_type_extension
+    assert_runs_without_errors do
+      @artifact.save('appends_extension')
+    end
+
+    assert File.exist?('appends_extension.jpeg')
   end
 
   def test_artifact_base64

data/test/browser_test.rb

@@ -61,7 +61,7 @@ class BrowserTest < Minitest::Test
       @mock_ferrum.expect :goto, nil, ['https://example.com']
       # The screenshot method receives keyword arguments as a hash
       @mock_ferrum.expect :screenshot, 'fake_image_data' do |args|
-        args == { format: :jpeg, quality: 90, encoding: :base64 }
+        args == { format: :jpeg, quality: 90, encoding: :base64, full: false }
       end
 
       artifact = browser.capture('https://example.com')
@@ -84,7 +84,7 @@ class BrowserTest < Minitest::Test
       @mock_ferrum.expect :goto, nil, ['https://example.com']
       # The screenshot method receives keyword arguments as a hash
       @mock_ferrum.expect :screenshot, 'fake_png_data' do |args|
-        args == { format: :png, quality: 100, encoding: :binary }
+        args == { format: :png, quality: 100, encoding: :binary, full: false }
       end
 
       artifact = browser.capture('https://example.com',
@@ -100,6 +100,25 @@ class BrowserTest < Minitest::Test
 
     @mock_ferrum.verify
   end
+  
+  def test_capture_with_full_area
+    browser = Kleya::Browser.new
+
+    Ferrum::Browser.stub :new, @mock_ferrum do
+      @mock_ferrum.expect :goto, nil, ['https://example.com']
+      # The screenshot method receives keyword arguments as a hash
+      @mock_ferrum.expect :screenshot, 'fake_full_image_data' do |args|
+        args == { format: :jpeg, quality: 90, encoding: :base64, full: true }
+      end
+
+      artifact = browser.capture('https://example.com', area: :page)
+
+      assert_instance_of Kleya::Artifact, artifact
+      assert_equal('fake_full_image_data', artifact.instance_variable_get(:@data))
+    end
+
+    @mock_ferrum.verify
+  end
 
   def test_capture_handles_timeout_error
     browser = Kleya::Browser.new

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kleya
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Hellotext
 - Ahmed Khattab
 bindir: bin
 cert_chain: []
-date: 2025-07-21 00:00:00.000000000 Z
+date: 2025-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -81,12 +81,14 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.17'
 description: Screenshots, made easy.
-executables: []
+executables:
+- kleya
 extensions: []
 extra_rdoc_files: []
 files:
 - README.md
 - Rakefile
+- bin/kleya
 - lib/kleya.rb
 - lib/kleya/artifact.rb
 - lib/kleya/browser.rb