bidi2pdf 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f132ccc5d9db5bb621f7e1a0adfa4150b77b4618542ba27873a602cf9c342a40
-  data.tar.gz: f3df228dc1de555d14baad4347a1b5b8d0bc8b63f88d6adfbcec86f0da571703
+  metadata.gz: b92ff566ca3ae322033cd9602818c94ae30da2594c7075bbb86f4c16351d58ce
+  data.tar.gz: 1b4d46aa7fe35c1810522a51400c3558f04d8fdc4093c7b3efa0f507a4959392
 SHA512:
-  metadata.gz: d74e6e1b505493d47f66c2f1cb4d13bc07aacfa82dbba536439e3b458395bbcd7213103e5fbed167a65945af28bbfb239f6510e93bed2838fa583b95352df8d6
-  data.tar.gz: '096bb337a61db6d5392ba64c38bf4632695ca647b2fe95a227f3d56b189241cae1b19cc65e98115dff73997bb3df1cdcc2821058611683aa449acd11db4fe66f'
+  metadata.gz: 63aa303c4dc6245510cb212adaf22523190d8e00892f4ffe9dc9ba9b65e966f74517ee748f4a232736701a3271ae086879fcbf0adc02ce9f9cd82d103ea3e70d
+  data.tar.gz: 320a0a03c399541157bd192b6389fecf5541c994cdcaa186694085887ecc8de0829b63badc2be5fa0cd2b8c9baa4ee60bfe7a2f457743d4f21506f1d4bb44850

data/CHANGELOG.md

@@ -6,10 +6,23 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.4..HEAD
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.5..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [0.1.5] - 2025-04-10
+
+### 📝 Docs
+
+- Improve README structure and update content by @dieter-medium
+- Add step-by-step usage guide to README by @dieter-medium
+
+### 🚀 Added
+
+- Add support for rendering local HTML files or in memory HTML by @dieter-medium
+- Add DSL and specs for generating PDFs with browser tabs by @dieter-medium
+- Enhance print method with block support for PDF handling by @dieter-medium
+
 ## [0.1.4] - 2025-04-10
 
 ### 🎨 Refactored

data/README.md

@@ -3,52 +3,58 @@
 [![Gem Version](https://badge.fury.io/rb/bidi2pdf.svg)](https://badge.fury.io/rb/bidi2pdf)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/6425d9893aa3a9ca243e/test_coverage)](https://codeclimate.com/github/dieter-medium/bidi2pdf/test_coverage)
 
-# Bidi2pdf
+---
 
-Bidi2pdf is a Ruby gem that generates high-quality PDFs from web pages using Chrome's BiDi (BiDirectional) protocol. It
-offers precise control over PDF generation with support for modern web technologies.
+# 📄 Bidi2pdf – Bulletproof PDF generation via Chrome's BiDi Protocol
 
-## Features
+**Bidi2pdf** is a powerful Ruby gem that transforms modern web pages into high-fidelity PDFs using Chrome’s *
+*BiDirectional (BiDi)** protocol. Whether you're automating reports, archiving websites, or shipping documentation,
+Bidi2pdf gives you **precision, flexibility, and full control**.
 
-- **Simple CLI** - Generate PDFs with a single command
-- **Rich Configuration** - Customize with cookies, headers, and authentication
-- **Waiting Conditions** - Wait for window loaded or network idle
-- **Headless Support** - Run without a visible browser
-- **Docker Ready** - Easy containerization
-- **Modern Architecture** - Uses Chrome's BiDi protocol for better control
+---
 
-## Installation
+## ✨ Key Features
 
-Add to your application's Gemfile:
+✅ **One-liner CLI** – From URL to PDF in a single command  
+✅ **Full customization** – Inject cookies, headers, auth credentials  
+✅ **Smart waiting** – Wait for complete page load or network idle  
+✅ **Headless support** – Run quietly in the background  
+✅ **Docker-ready** – Plug and play with containers  
+✅ **Modern architecture** – Built on Chrome's next-gen BiDi protocol
+
+---
+
+## 🚀 Installation
+
+### Bundler
 
 ```ruby
 gem 'bidi2pdf'
 ```
 
-Or install manually:
+### Standalone
 
 ```bash
-$ gem install bidi2pdf
+gem install bidi2pdf
 ```
 
-### Dependencies
+### Requirements
 
-- **Ruby**: 3.3 or higher
-- **Bidi2pdf** automatically manages ChromeDriver binaries through
-  the [chromedriver-binary](https://github.com/dieter-medium/chromedriver-binary) gem, which:
-  Downloads and installs the ChromeDriver version matching your installed Chrome/Chromium browser
-  Eliminates the need to manually install or update ChromeDriver
-  Ensures compatibility between Chrome and ChromeDriver versions
+- **Ruby** ≥ 3.3
+- **Chrome/Chromium**
+- Automatic ChromeDriver management via [chromedriver-binary](https://github.com/dieter-medium/chromedriver-binary)
 
-## Usage
+---
 
-### Basic Command Line Usage
+## ⚙️ Basic Usage
+
+### Command-line
 
 ```bash
 bidi2pdf render --url https://example.com --output example.pdf
 ```
 
-### Advanced Options
+### Advanced CLI Options
 
 ```bash
 bidi2pdf render \
@@ -62,14 +68,18 @@ bidi2pdf render \
   --log-level debug
 ```
 
-### Ruby API
+---
+
+## 🧠 Programmatic API
+
+### Classic Approach
 
 ```ruby
 require 'bidi2pdf'
 
 launcher = Bidi2pdf::Launcher.new(
   url: 'https://example.com',
-  output: 'example.pdf', # nil for base64 encoded string as result of launcher.launch
+  output: 'example.pdf',
   cookies: { 'session' => 'abc123' },
   headers: { 'X-API-KEY' => 'token' },
   auth: { username: 'admin', password: 'password' },
@@ -78,25 +88,90 @@ launcher = Bidi2pdf::Launcher.new(
 )
 
 launcher.launch
+```
+
+### DSL – Quick & Clean
+
+```ruby
+require "bidi2pdf"
+
+Bidi2pdf::DSL.with_tab(headless: true) do |tab|
+  tab.open_page("https://example.com")
+  tab.wait_until_all_finished
+  tab.print("example.pdf")
+end
+```
+
+---
+
+## 🧬 Deep Integration Example
+
+Get fine-grained control using Chrome sessions, tabs, and BiDi commands:
+
+<details>
+<summary>🔍 Show full example</summary>
+
+```ruby
+require "bidi2pdf"
+
+# 1. Remote or local session?
+session = Bidi2pdf::Bidi::Session.new(
+  session_url: "http://localhost:9092/session",
+  headless: true,
+)
+
+# Alternative: local session via ChromeDriver
+# manager = Bidi2pdf::ChromedriverManager.new(headless: false)
+# manager.start
+# session = manager.session
+
+session.start
+session.client.on_close { puts "WebSocket session closed" }
+
+# 2. Create browser/tab
+browser = session.browser
+context = browser.create_user_context
+window = context.create_browser_window
+tab = window.create_browser_tab
+
+# 3. Inject configuration
+tab.set_cookie(name: "auth", value: "secret", domain: "example.com", secure: true)
+tab.add_headers(url_patterns: [{ type: "pattern", protocol: "https", hostname: "example.com", port: "443" }],
+                headers: [{ name: "X-API-KEY", value: "12345678" }])
+tab.basic_auth(url_patterns: [{ type: "pattern", protocol: "https", hostname: "example.com", port: "443" }],
+               username: "username", password: "secret")
 
-# see Bidi2pdf::SessionRunner for more options
+# 4. Render PDF
+tab.open_page "https://example.com"
+
+# Alternative: send html code to the browser
+# tab.view_html_page("<html>...</html>")
+
+tab.wait_until_all_finished
+tab.print("my.pdf")
+
+# 5. Cleanup
+tab.close
+window.close
+session.close
 ```
 
-## Docker Support
+</details>
+
+---
+
+## 🐳 Docker Support
 
-Build and run with Docker:
+### Build & Run
 
 ```bash
-# Build gem and Docker image
 rake build
 docker build -t bidi2pdf -f docker/Dockerfile .
-
-# Generate PDF using Docker
 docker run -it --rm -v ./output:/reports bidi2pdf \
   bidi2pdf render --url=https://example.com --output /reports/example.pdf
 ```
 
-### Test it with docker compose
+### Docker Compose
 
 ```bash
 rake build
@@ -105,6 +180,10 @@ docker compose -f docker/docker-compose.yml up -d
 # simple example
 docker compose -f docker/docker-compose.yml exec app bidi2pdf render --url=http://nginx/sample.html --wait_window_loaded --wait_network_idle --output /reports/simple.pdf
 
+# with a local file
+docker compose -f docker/docker-compose.yml exec app bidi2pdf render --url=file:///reports/sample.html--wait_network_idle --output /reports/simple.pdf
+
+
 # basic auth example
 docker compose -f docker/docker-compose.yml exec app bidi2pdf render --url=http://nginx/basic/sample.html --auth admin:secret --wait_window_loaded --wait_network_idle --output /reports/basic.pdf
 
@@ -120,31 +199,42 @@ docker compose -f docker/docker-compose.yml exec app bidi2pdf render --url=http:
 docker compose -f docker/docker-compose.yml down
 ```
 
-## Configuration Options
+---
+
+## 🧩 Configuration Options
+
+| Flag                   | Description                                |
+|------------------------|--------------------------------------------|
+| `--url`                | Target URL (required)                      |
+| `--output`             | Output PDF file (default: output.pdf)      |
+| `--cookie`             | Set cookie in `name=value` format          |
+| `--header`             | Inject custom header `name=value`          |
+| `--auth`               | Basic auth as `user:pass`                  |
+| `--headless`           | Run Chrome headless (default: true)        |
+| `--port`               | ChromeDriver port (0 = auto)               |
+| `--wait_window_loaded` | Wait until `window.loaded` is set to true  |
+| `--wait_network_idle`  | Wait until network is idle                 |
+| `--log_level`          | Log level: debug, info, warn, error, fatal |
+| `--remote_browser_url` | Connect to remote Chrome session           |
+| `--default_timeout`    | Operation timeout (default: 60s)           |
 
-| Option                 | Description                                                                                                         |
-|------------------------|---------------------------------------------------------------------------------------------------------------------|
-| `--url`                | The URL to render (required)                                                                                        |
-| `--output`             | Output PDF filename (default: output.pdf)                                                                           |
-| `--cookie`             | Cookies in name=value format                                                                                        |
-| `--header`             | HTTP headers in name=value format                                                                                   |
-| `--auth`               | Basic auth credentials (user:pass)                                                                                  |
-| `--headless`           | Run Chrome in headless mode (default: true)                                                                         |
-| `--port`               | Port for ChromeDriver (0 = auto)                                                                                    |
-| `--wait_window_loaded` | Wait for the window to be fully loaded. You need to set a variable `window.loaded`. See ./spec/fixtures/sample.html |
-| `--wait_network_idle`  | Wait for network to be idle                                                                                         |
-| `--log_level`          | Log level (debug, info, warn, error, fatal)                                                                         |
-| `--remote_browser_url` | URL of the remote Chrome instance (default: nil)                                                                    |
-| `--default_timeout`    | Default timeout for operations (default: 60 seconds)                                                                |
+---
 
-## Development
+## 🛠 Development
 
-After checking out the repo:
+```bash
+# Setup
+bin/setup
+
+# Run tests
+rake spec
+
+# Open interactive console
+bin/console
+```
 
-1. Run `bin/setup` to install dependencies
-2. Run `rake spec` to run the tests
-3. Run `bin/console` for an interactive prompt
+---
 
-## License
+## 📜 License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).

data/lib/bidi2pdf/bidi/browser_tab.rb

@@ -88,6 +88,13 @@ module Bidi2pdf
         end
       end
 
+      def view_html_page(html_content)
+        base64_encoded = Base64.strict_encode64(html_content)
+        data_url = "data:text/html;charset=utf-8;base64,#{base64_encoded}"
+
+        open_page(data_url)
+      end
+
       def execute_script(script)
         cmd = Bidi2pdf::Bidi::Commands::ScriptEvaluate.new context: browsing_context_id, expression: script
         client.send_cmd_and_wait(cmd) do |response|
@@ -111,7 +118,8 @@ module Bidi2pdf
         @open = false
       end
 
-      def print(outputfile, print_options: { background: true })
+      # rubocop: disable Metrics/AbcSize, Metrics/PerceivedComplexity
+      def print(outputfile = nil, print_options: { background: true }, &block)
         cmd = Bidi2pdf::Bidi::Commands::BrowsingContextPrint.new context: browsing_context_id, print_options: print_options
 
         client.send_cmd_and_wait(cmd) do |response|
@@ -119,19 +127,25 @@ module Bidi2pdf
             pdf_base64 = response["result"]["data"]
 
             if outputfile
+              raise PrintError, "Folder does not exist: #{File.dirname(outputfile)}" unless File.directory?(File.dirname(outputfile))
+
               File.binwrite(outputfile, Base64.decode64(pdf_base64))
               Bidi2pdf.logger.info "PDF saved as '#{outputfile}'."
             else
               Bidi2pdf.logger.info "PDF generated successfully."
             end
 
-            return pdf_base64 unless outputfile
+            block.call(pdf_base64) if block_given?
+
+            return pdf_base64 unless outputfile || block_given?
           else
             Bidi2pdf.logger.error "Error printing: #{response}"
           end
         end
       end
 
+      # rubocop: enable Metrics/AbcSize, Metrics/PerceivedComplexity
+
       private
 
       def close_context

data/lib/bidi2pdf/bidi/commands/set_tab_cookie.rb

@@ -6,6 +6,14 @@ module Bidi2pdf
       class SetTabCookie
         include Base
 
+        class << self
+          attr_writer :time_provider
+
+          def time_provider
+            @time_provider ||= -> { Time.now }
+          end
+        end
+
         attr_reader :name, :value, :domain, :path, :secure, :http_only, :same_site, :ttl, :browsing_context_id
 
         def initialize(name:,
@@ -29,7 +37,7 @@ module Bidi2pdf
         end
 
         def expiry
-          Time.now.to_i + ttl
+          self.class.time_provider.call.to_i + ttl
         end
 
         def method_name

data/lib/bidi2pdf/cli.rb

@@ -31,6 +31,10 @@ module Bidi2pdf
     USAGE
 
     option :url, desc: "The URL to render"
+    # of course, it's possible to render a local file via: --url file:///path/to/the/file.html
+    # but this should showcase the scenario that you render a string within ruby as pdf without the need
+    # to store it on disc
+    option :html_file, desc: "The local HTML file to render"
     option :output, default: "output.pdf", desc: "Filename for the output PDF", aliases: "-o"
     option :cookie, type: :array, default: [], banner: "name=value", desc: "One or more cookies", aliases: "-C"
     option :header, type: :array, default: [], banner: "name=value", desc: "One or more custom headers", aliases: "-H"
@@ -63,7 +67,7 @@ module Bidi2pdf
     def render
       load_config
 
-      validate_required_options! :url
+      validate_required_options!
 
       configure
 
@@ -115,9 +119,11 @@ module Bidi2pdf
       YAML.load_file(options[:config]).transform_keys(&:to_sym)
     end
 
-    def validate_required_options!(*keys)
-      keys.each do |key|
-        raise Thor::Error, "Missing required option: --#{key.to_s.tr("_", "-")}" unless merged_options[key]
+    def validate_required_options!
+      if merged_options[:url].nil? && merged_options[:html_file].nil?
+        raise Thor::Error, "Missing required option --url or --html_file needs to be specified"
+      elsif merged_options[:html_file] && !File.readable?(merged_options[:html_file])
+        raise Thor::Error, "HTML file '#{merged_options[:html_file]}' not found or not readable"
       end
     end
 
@@ -182,6 +188,7 @@ module Bidi2pdf
 
                       Bidi2pdf::Launcher.new(
                         url: merged_options[:url],
+                        inputfile: merged_options[:hmtl_file],
                         output: merged_options[:output],
                         cookies: parse_key_values(merged_options[:cookie]),
                         headers: parse_key_values(merged_options[:header]),

data/lib/bidi2pdf/dsl.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "bidi2pdf"
+
+module Bidi2pdf
+  module DSL
+    # rubocop: disable  Metrics/AbcSize
+    def self.with_tab(remote_browser_url: nil, port: 0, headless: true, chrome_args: Bidi2pdf::Bidi::Session::DEFAULT_CHROME_ARGS.dup)
+      manager = nil
+      session = nil
+      tab = nil
+
+      begin
+        session = if remote_browser_url
+                    Bidi2pdf::Bidi::Session.new(
+                      session_url: remote_browser_url,
+                      headless: true, # remote is always headless
+                      chrome_args: chrome_args
+                    )
+                  else
+                    manager = Bidi2pdf::ChromedriverManager.new(port: port, headless: headless)
+                    manager.start
+                    manager.session
+                  end
+
+        session.start
+        session.client.on_close { Bidi2pdf.logger.info "WebSocket session closed" }
+
+        browser = session.browser
+        context = browser.create_user_context
+        window = context.create_browser_window
+        tab = window.create_browser_tab
+
+        yield(tab)
+      ensure
+        tab&.close
+        window&.close
+        session&.close
+        manager&.stop
+      end
+    end
+
+    # rubocop: enable  Metrics/AbcSize
+  end
+end

data/lib/bidi2pdf/launcher.rb

@@ -7,9 +7,10 @@ require_relative "bidi/session"
 module Bidi2pdf
   class Launcher
     # rubocop:disable Metrics/ParameterLists
-    def initialize(url:, output:, cookies:, headers:, auth:, headless: true, port: 0, wait_window_loaded: false,
+    def initialize(url:, inputfile:, output:, cookies:, headers:, auth:, headless: true, port: 0, wait_window_loaded: false,
                    wait_network_idle: false, print_options: {}, remote_browser_url: nil)
       @url = url
+      @inputfile = inputfile
       @port = port
       @headless = headless
       @output = output
@@ -30,6 +31,7 @@ module Bidi2pdf
       runner = SessionRunner.new(
         session: session,
         url: @url,
+        inputfile: @inputfile,
         output: @output,
         cookies: @cookies,
         headers: @headers,

data/lib/bidi2pdf/session_runner.rb

@@ -2,10 +2,11 @@
 
 module Bidi2pdf
   class SessionRunner
-    def initialize(session:, url:, output:, cookies: {}, headers: {}, auth: {}, wait_window_loaded: false,
+    def initialize(session:, url:, inputfile:, output:, cookies: {}, headers: {}, auth: {}, wait_window_loaded: false,
                    wait_network_idle: false, print_options: {})
       @session = session
       @url = url
+      @inputfile = inputfile
       @output = output
       @cookies = cookies || {}
       @headers = headers || {}
@@ -75,7 +76,13 @@ module Bidi2pdf
       @session.status
       @session.user_contexts
 
-      @tab.open_page(@url)
+      if @url
+        @tab.open_page(@url)
+      else
+        Bidi2pdf.logger.info "Loading HTML file #{@inputfile}"
+        data = File.read(@inputfile)
+        @tab.view_html_page(data)
+      end
 
       if @wait_network_idle
         Bidi2pdf.logger.info "Waiting for network idle"

data/lib/bidi2pdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
-  VERSION = "0.1.4"
+  VERSION = "0.1.5"
 end

data/lib/bidi2pdf.rb

@@ -4,6 +4,7 @@ require_relative "bidi2pdf/utils"
 require_relative "bidi2pdf/process_tree"
 require_relative "bidi2pdf/launcher"
 require_relative "bidi2pdf/bidi/session"
+require_relative "bidi2pdf/dsl"
 
 require "logger"
 
@@ -22,8 +23,10 @@ module Bidi2pdf
 
   class CmdTimeoutError < ClientError; end
 
+  class PrintError < Error; end
+
   @logger = Logger.new($stdout)
-  @logger.level = Logger::DEBUG
+  @logger.level = Logger::INFO
 
   @default_timeout = 60
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bidi2pdf
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Dieter S.
@@ -353,6 +353,7 @@ files:
 - lib/bidi2pdf/bidi/web_socket_dispatcher.rb
 - lib/bidi2pdf/chromedriver_manager.rb
 - lib/bidi2pdf/cli.rb
+- lib/bidi2pdf/dsl.rb
 - lib/bidi2pdf/launcher.rb
 - lib/bidi2pdf/process_tree.rb
 - lib/bidi2pdf/session_runner.rb