screentake 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d6fe6b26493d9070ad6db10fd5accd18b1ada36cd60eccc157c0378cc24d28f1
+  data.tar.gz: 94b23b9f579ad1d7cbc4244d5d54260d692bf94e88a15384c1573bfb8602b62f
+SHA512:
+  metadata.gz: aecb55173a821838fe18c495b38c0f2caa34415d8b0685925403ccbdd96fb891d3905887d206256e6dc632b506f5fcf342f8de2f73249d9a2265f63a105fea63
+  data.tar.gz: 4d34057305663ca48d3e520ed25d213b12271f13e35ebb28dc541ebf0f9382ce364d52730148adf6d816f76c6c811e65627cf034a7194d15f1d198b4543394a1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Maful Prayoga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,519 @@
+# Screentake
+
+A Ruby gem for capturing web page screenshots with a clean, keyword-driven API. Supports both the Cloudflare Browser Rendering API and a local Ferrum (headless Chrome) driver.
+
+## Overview
+
+Screentake provides a simple interface for turning URLs or raw HTML into PNG, JPEG, or WebP screenshots. It handles viewport configuration, device scale factors, full-page captures, element-specific screenshots, and various wait strategies out of the box.
+
+The gem ships with two interchangeable drivers. The **Cloudflare** driver sends rendering requests to the [Cloudflare Browser Rendering API](https://developers.cloudflare.com/browser-rendering/) -- no local browser required. The **Ferrum** driver uses headless Chrome on your own machine via the [Ferrum](https://github.com/rubycdp/ferrum) gem. Both drivers share the same options interface, so switching between them is a one-line configuration change.
+
+## Features
+
+- **URL and HTML rendering** -- pass a URL or an HTML string
+- **Multiple output formats** -- PNG, JPEG, WebP
+- **Viewport control** -- width, height, and device scale factor (1-4x)
+- **Full-page capture** -- screenshot the entire scrollable page
+- **Element targeting** -- capture a specific CSS selector
+- **Clip regions** -- crop to an arbitrary rectangle
+- **Transparent backgrounds** -- omit the default white background
+- **Wait strategies** -- wait for load, DOMContentLoaded, network idle, a selector, or a fixed timeout
+- **Automatic retries** -- Cloudflare driver retries on 429 rate limits with exponential backoff
+- **Three output methods** -- raw binary, Base64, or save directly to a file
+- **Rails auto-integration** -- Railtie loaded automatically when Rails is present
+- **Driver pattern** -- swap between Cloudflare and Ferrum without changing application code
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "screentake"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install screentake
+```
+
+If you plan to use the Ferrum driver, also add:
+
+```ruby
+gem "ferrum", "~> 0.15"
+```
+
+### Rails Installation
+
+After adding screentake to your Gemfile, run the install generator:
+
+```bash
+bundle install
+rails generate screentake:install
+```
+
+This creates `config/initializers/screentake.rb` with default configuration. Set your Cloudflare credentials via environment variables (`CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`) or edit the initializer directly.
+
+## Quick Start
+
+```ruby
+require "screentake"
+
+Screentake.configure do |config|
+  config.cloudflare_account_id = ENV["CLOUDFLARE_ACCOUNT_ID"]
+  config.cloudflare_api_token  = ENV["CLOUDFLARE_API_TOKEN"]
+end
+
+# Take a screenshot and save it
+screenshot = Screentake.take(url: "https://example.com")
+screenshot.save("example.png")
+
+# Or get the binary data directly
+binary = screenshot.capture
+
+# Or get Base64 for embedding in HTML/JSON
+encoded = screenshot.base64
+```
+
+## Configuration
+
+Configure Screentake globally with `Screentake.configure`:
+
+```ruby
+Screentake.configure do |config|
+  # Driver selection (:cloudflare or :ferrum)
+  config.driver = :cloudflare
+
+  # Cloudflare credentials (required for :cloudflare driver)
+  config.cloudflare_account_id = ENV["CLOUDFLARE_ACCOUNT_ID"]
+  config.cloudflare_api_token  = ENV["CLOUDFLARE_API_TOKEN"]
+
+  # Default viewport dimensions
+  config.default_viewport = { width: 1280, height: 800 }
+
+  # Device scale factor (1-4, default: 2)
+  config.default_scale = 2
+
+  # Default image format (:png, :jpeg, :webp)
+  config.default_format = :png
+
+  # Navigation timeout in milliseconds (default: 30000)
+  config.timeout = 30_000
+
+  # Logger instance for debug/retry output (default: nil)
+  config.logger = Rails.logger
+
+  # Ferrum browser options (only used with :ferrum driver)
+  config.ferrum_options = { headless: true }
+end
+```
+
+### Configuration Defaults
+
+| Option | Default | Description |
+|---|---|---|
+| `driver` | `:cloudflare` | Which rendering backend to use |
+| `cloudflare_account_id` | `nil` | Your Cloudflare account ID |
+| `cloudflare_api_token` | `nil` | Your Cloudflare API token |
+| `default_viewport` | `{ width: 1280, height: 800 }` | Browser viewport size |
+| `default_scale` | `2` | Device scale factor (Retina) |
+| `default_format` | `:png` | Output image format |
+| `timeout` | `30000` | Navigation timeout (ms) |
+| `logger` | `nil` | Logger for debug output |
+| `ferrum_options` | `{ headless: true }` | Options passed to `Ferrum::Browser.new` |
+
+## Usage Examples
+
+### Basic URL Screenshot
+
+```ruby
+screenshot = Screentake.take(url: "https://example.com")
+screenshot.save("output.png")
+```
+
+### HTML Content Screenshot
+
+```ruby
+html = <<~HTML
+  <html>
+    <body style="background: #1a1a2e; color: #eee; padding: 40px;">
+      <h1>Hello from Screentake</h1>
+    </body>
+  </html>
+HTML
+
+screenshot = Screentake.take(html: html)
+screenshot.save("rendered.png")
+```
+
+Note: `url:` and `html:` are mutually exclusive. Passing both raises `ArgumentError`.
+
+### Full-Page Capture
+
+```ruby
+screenshot = Screentake.take(
+  url: "https://example.com/long-page",
+  full_page: true,
+)
+screenshot.save("full_page.png")
+```
+
+### Custom Viewport and Scale
+
+```ruby
+# Using width: and height:
+screenshot = Screentake.take(
+  url: "https://example.com",
+  width: 1920,
+  height: 1080,
+  scale: 3,
+)
+
+# Using size: shorthand
+screenshot = Screentake.take(
+  url: "https://example.com",
+  size: [375, 812],  # iPhone viewport
+  scale: 3,
+)
+```
+
+### Selector-Based Screenshot
+
+Capture only a specific element:
+
+```ruby
+screenshot = Screentake.take(
+  url: "https://example.com",
+  selector: "#hero-section",
+)
+screenshot.save("hero.png")
+```
+
+### Clip Region
+
+Crop to an arbitrary rectangle:
+
+```ruby
+screenshot = Screentake.take(
+  url: "https://example.com",
+  clip: { x: 0, y: 0, width: 600, height: 400 },
+)
+screenshot.save("cropped.png")
+```
+
+### Different Formats
+
+```ruby
+# JPEG with quality setting
+screenshot = Screentake.take(
+  url: "https://example.com",
+  format: :jpeg,
+  quality: 85,
+)
+screenshot.save("output.jpg")
+
+# WebP with quality setting
+screenshot = Screentake.take(
+  url: "https://example.com",
+  format: :webp,
+  quality: 90,
+)
+screenshot.save("output.webp")
+```
+
+Note: `quality:` is only valid for JPEG and WebP. Passing it with PNG format raises `InvalidOptionError`.
+
+The `.save` method also infers format from the file extension. Saving to `output.jpg` will produce a JPEG regardless of the `format:` option.
+
+### Transparent Background
+
+```ruby
+screenshot = Screentake.take(
+  url: "https://example.com",
+  transparent: true,
+  format: :png,
+)
+screenshot.save("transparent.png")
+```
+
+### Wait Strategies
+
+```ruby
+# Wait until there are zero network connections for 500ms
+screenshot = Screentake.take(
+  url: "https://example.com",
+  wait_until: :networkidle0,
+)
+
+# Wait for a specific element to appear
+screenshot = Screentake.take(
+  url: "https://example.com",
+  wait_for_selector: ".chart-loaded",
+)
+
+# Add a fixed delay (in milliseconds, 1-30000)
+screenshot = Screentake.take(
+  url: "https://example.com",
+  wait_for_timeout: 2000,
+)
+```
+
+Available `wait_until` values:
+
+| Value | Description |
+|---|---|
+| `:load` | Wait for the `load` event |
+| `:domcontentloaded` | Wait for `DOMContentLoaded` event |
+| `:networkidle0` | Wait until zero network connections for 500ms (default) |
+| `:networkidle2` | Wait until two or fewer network connections for 500ms |
+
+### Output Methods
+
+Every `Screentake.take` call returns a `Screenshot` object with three output methods:
+
+```ruby
+screenshot = Screentake.take(url: "https://example.com")
+
+# Raw binary data
+binary = screenshot.capture
+
+# Base64-encoded string
+encoded = screenshot.base64
+
+# Save to file (creates parent directories automatically, returns the path)
+path = screenshot.save("screenshots/example.png")
+```
+
+### Debugging
+
+Inspect the resolved options for a screenshot:
+
+```ruby
+screenshot = Screentake.take(url: "https://example.com", full_page: true)
+pp screenshot.debug
+# {
+#   source_type: :url,
+#   source: "https://example.com",
+#   width: 1280,
+#   height: 800,
+#   scale: 2,
+#   format: :png,
+#   quality: nil,
+#   full_page: true,
+#   selector: nil,
+#   clip: nil,
+#   transparent: false,
+#   wait_until: :networkidle0,
+#   wait_for_selector: nil,
+#   wait_for_timeout: nil,
+#   driver: :cloudflare,
+# }
+```
+
+## Drivers
+
+### Cloudflare (Default)
+
+The Cloudflare driver sends requests to the [Cloudflare Browser Rendering API](https://developers.cloudflare.com/browser-rendering/). No local browser installation needed.
+
+```ruby
+Screentake.configure do |config|
+  config.driver = :cloudflare
+  config.cloudflare_account_id = ENV["CLOUDFLARE_ACCOUNT_ID"]
+  config.cloudflare_api_token  = ENV["CLOUDFLARE_API_TOKEN"]
+end
+```
+
+**Rate limits:** Cloudflare enforces 2 browsers per minute and 2 concurrent requests. The driver automatically retries up to 3 times on HTTP 429 responses with exponential backoff (1s, 2s, 4s).
+
+### Ferrum (Local Chrome)
+
+The Ferrum driver runs a local headless Chrome instance via the [Ferrum](https://github.com/rubycdp/ferrum) gem. It requires Chrome or Chromium installed on the machine.
+
+```ruby
+# Gemfile
+gem "ferrum", "~> 0.15"
+```
+
+```ruby
+Screentake.configure do |config|
+  config.driver = :ferrum
+  config.ferrum_options = {
+    headless: true,
+    # browser_path: "/usr/bin/chromium",  # custom Chrome path
+    # timeout: 60,                        # Ferrum process timeout
+  }
+end
+```
+
+The Ferrum driver lazily starts the browser on the first screenshot, reuses it for subsequent requests (each screenshot gets its own browser context), and automatically shuts it down on process exit.
+
+### Choosing a Driver
+
+| | Cloudflare | Ferrum |
+|---|---|---|
+| **Setup** | API credentials only | Chrome/Chromium installed locally |
+| **Infrastructure** | No local browser needed | Runs on your server |
+| **Rate limits** | 2/min, 2 concurrent | Limited by your hardware |
+| **Cost** | Cloudflare pricing applies | Free (your compute) |
+| **Best for** | Production, serverless | Development, CI, high volume |
+
+## API Reference
+
+### `Screentake.take(**options)`
+
+Creates a `Screenshot` instance. Validates all options eagerly -- invalid options raise immediately, before any network request.
+
+**Source options** (exactly one required):
+
+| Option | Type | Description |
+|---|---|---|
+| `url:` | `String` | URL to capture (http/https only) |
+| `html:` | `String` | Raw HTML content to render |
+
+**Viewport options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `width:` | `Integer` | `1280` | Viewport width (1-10000) |
+| `height:` | `Integer` | `800` | Viewport height (1-10000) |
+| `size:` | `Array` | -- | Shorthand `[width, height]` |
+| `scale:` | `Numeric` | `2` | Device scale factor (1-4) |
+
+**Capture options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `format:` | `Symbol` | `:png` | `:png`, `:jpeg`, or `:webp` |
+| `quality:` | `Integer` | `nil` | 1-100, JPEG/WebP only |
+| `full_page:` | `Boolean` | `false` | Capture full scrollable page |
+| `selector:` | `String` | `nil` | CSS selector to capture |
+| `clip:` | `Hash` | `nil` | `{ x:, y:, width:, height: }` |
+| `transparent:` | `Boolean` | `false` | Transparent background |
+
+**Wait options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `wait_until:` | `Symbol` | `:networkidle0` | Page load strategy |
+| `wait_for_selector:` | `String` | `nil` | Wait for this CSS selector |
+| `wait_for_timeout:` | `Numeric` | `nil` | Fixed delay in ms (1-30000) |
+
+### `Screenshot#capture`
+
+Returns raw binary image data as a `String`.
+
+### `Screenshot#base64`
+
+Returns the screenshot as a Base64-encoded `String` (strict encoding, no newlines).
+
+### `Screenshot#save(path)`
+
+Writes the screenshot to `path`, creating parent directories as needed. Infers format from the file extension (`.jpg`/`.jpeg` to JPEG, `.webp` to WebP, `.png` to PNG). Returns the path as a `String`.
+
+### `Screenshot#debug`
+
+Returns a `Hash` of all resolved options for inspection.
+
+### `Screentake.configure { |config| ... }`
+
+Yields the global `Configuration` object for setting defaults.
+
+### `Screentake.reset_configuration!`
+
+Resets all configuration to defaults and shuts down the current driver. Useful in tests.
+
+## Error Handling
+
+All Screentake errors inherit from `Screentake::Error`, so you can rescue broadly or handle specific cases:
+
+```ruby
+begin
+  screenshot = Screentake.take(url: "https://example.com")
+  screenshot.save("output.png")
+rescue Screentake::RateLimitError
+  # Cloudflare 429 after all retries exhausted
+  retry_later
+rescue Screentake::AuthenticationError => e
+  # Invalid Cloudflare credentials
+  Rails.logger.error("Screentake auth failed: #{e.message}")
+rescue Screentake::TimeoutError
+  # Page took too long to load
+  handle_timeout
+rescue Screentake::ElementNotFoundError
+  # Selector matched no elements
+  use_fallback_image
+rescue Screentake::Error => e
+  # Catch-all for any Screentake error
+  Rails.logger.error("Screenshot failed: #{e.message}")
+end
+```
+
+### Error Hierarchy
+
+```
+Screentake::Error
+  Screentake::NotImplementedError
+  Screentake::InvalidUrlError
+  Screentake::InvalidHtmlError
+  Screentake::InvalidDimensionError
+  Screentake::InvalidOptionError
+  Screentake::InvalidClipError
+  Screentake::ElementNotFoundError
+  Screentake::TimeoutError
+  Screentake::RenderError
+  Screentake::DriverError
+    Screentake::CloudflareError
+      Screentake::RateLimitError
+      Screentake::AuthenticationError
+    Screentake::FerrumError
+      Screentake::BrowserNotFoundError
+      Screentake::BrowserCrashedError
+```
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/maful/screentake.git
+cd screentake
+bin/setup
+```
+
+### Running Tests
+
+```bash
+rake test              # Run all tests
+rake rubocop           # Run linter
+rake                   # Run tests + rubocop (default)
+```
+
+### Interactive Console
+
+```bash
+bin/console
+```
+
+### Requirements
+
+- Ruby >= 3.1
+- Chrome or Chromium (for Ferrum driver only)
+
+### Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/maful/screentake](https://github.com/maful/screentake). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/maful/screentake/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Screentake project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/maful/screentake/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: [:test, :rubocop]

data/lib/generators/screentake/install/install_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Screentake
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Screentake initializer file."
+
+      def copy_initializer
+        template("screentake.rb", "config/initializers/screentake.rb")
+      end
+    end
+  end
+end

data/lib/generators/screentake/install/templates/screentake.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+Screentake.configure do |config|
+  # Driver to use for capturing screenshots.
+  # :cloudflare and :ferrum is supported.
+  config.driver = :cloudflare
+
+  # Cloudflare Browser Rendering API credentials.
+  # You can also set these via environment variables:
+  #   CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN
+  config.cloudflare_account_id = ENV.fetch("CLOUDFLARE_ACCOUNT_ID", nil)
+  config.cloudflare_api_token = ENV.fetch("CLOUDFLARE_API_TOKEN", nil)
+
+  # Default viewport dimensions (pixels).
+  # config.default_viewport = { width: 1280, height: 800 }
+
+  # Default device scale factor (1-4). 2 produces retina-quality output.
+  # config.default_scale = 2
+
+  # Default image format (:png, :jpeg, :webp).
+  # config.default_format = :png
+
+  # Request timeout in milliseconds.
+  # config.timeout = 30_000
+end

data/lib/screentake/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Screentake
+  class Configuration
+    attr_accessor :driver,
+      :cloudflare_account_id,
+      :cloudflare_api_token,
+      :default_viewport,
+      :default_scale,
+      :default_format,
+      :timeout,
+      :logger,
+      :ferrum_options
+
+    def initialize
+      @driver = :cloudflare
+      @cloudflare_account_id = nil
+      @cloudflare_api_token = nil
+      @default_viewport = { width: 1280, height: 800 }
+      @default_scale = 2
+      @default_format = :png
+      @timeout = 30_000
+      @logger = nil
+      @ferrum_options = { headless: true }
+    end
+  end
+end

data/lib/screentake/drivers/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Screentake
+  module Drivers
+    # Abstract base class for screenshot drivers.
+    # All drivers must inherit from this class and implement #screenshot.
+    class Base
+      # Capture a screenshot and return binary image data.
+      #
+      # @param source [String] the URL or HTML content
+      # @param type [Symbol] :url or :html
+      # @param options [Hash] screenshot options (viewport, format, etc.)
+      # @return [String] binary image data
+      def screenshot(source:, type:, options:)
+        raise NotImplementedError, "#{self.class}#screenshot must be implemented"
+      end
+    end
+  end
+end