bidi2pdf 0.1.13 → 0.1.15

data/sig/bidi2pdf/bidi/session.rbs

@@ -1,52 +1,165 @@
+# Represents a session for managing browser interactions and communication
+# using the Bidi2pdf library. This class handles the setup, configuration,
+# and execution of browser-related workflows, including session creation,
+# WebSocket communication, and browser management.
+#
+# @example Creating and starting a session
+#   session = Bidi2pdf::Bidi::Session.new(session_url: "http://example.com/session", headless: true)
+#   session.start
+#
+# @example Retrieving user contexts
+#   session.user_contexts
+#
+# @example Closing the session
+#   session.close
+#
+# @param [String] session_url The URL for the session.
+# @param [Boolean] headless Whether to run the browser in headless mode. Defaults to true.
+# @param [Array<String>] chrome_args Additional Chrome arguments. Defaults to predefined arguments.
 module Bidi2pdf
   module Bidi
     class Session
-      @browser: Bidi2pdf::Bidi::Browser
-      @session_id: String?
-      @contexts: Array[String]
-      @timeout: Integer
-      @event_manager: Bidi2pdf::Bidi::EventManager?
-      @network_events: Bidi2pdf::Bidi::NetworkEvents?
+      @session_uri: untyped
 
-      attr_reader browser: Bidi2pdf::Bidi::Browser
-      attr_reader session_id: String?
-      attr_reader contexts: Array[String]
+      @headless: untyped
 
-      def initialize: (
-          browser: Bidi2pdf::Bidi::Browser,
-          ?session_id: String?,
-          ?timeout: Integer
-        ) -> void
+      @started: untyped
 
-      def create: () -> String
+      @chrome_args: untyped
 
-      def attach: (session_id: String) -> String
+      @client: untyped
 
-      def detach: () -> void
+      @browser: untyped
 
-      def execute_command: [T] (String method, ?Hash[Symbol, untyped] params) -> T
+      @websocket_url: untyped
 
-      def navigate_to: (String url) -> void
+      # Events to subscribe to during the session.
+      SUBSCRIBE_EVENTS: ::Array["script"]
 
-      def evaluate: [T] (String script) -> T
+      # Default Chrome arguments for the session.
+      DEFAULT_CHROME_ARGS: ::Array["--allow-pre-commit-input" | "--disable-dev-shm-usage" | "--disable-gpu" | "--disable-popup-blocking" | "--disable-hang-monitor" | "--disable-background-networking" | "--disable-background-timer-throttling" | "--disable-client-side-phishing-detection" | "--disable-component-extensions-with-background-pages" | "--disable-crash-reporter" | "--disable-default-apps" | "--disable-infobars" | "--disable-ipc-flooding-protection" | "--disable-prompt-on-repost" | "--disable-renderer-backgrounding" | "--disable-search-engine-choice-screen" | "--disable-sync" | "--enable-automation" | "--export-tagged-pdf" | "--force-color-profile=srgb" | "--generate-pdf-document-outline" | "--metrics-recording-only" | "--no-first-run" | "--password-store=basic" | "--use-mock-keychain" | "--disable-backgrounding-occluded-windows" | "--disable-breakpad" | "--enable-features=PdfOopif" | "--disable-features=Translate,AcceptCHFrame,MediaRouter,OptimizationHints,ProcessPerSiteUpToMainFrameThreshold,IsolateSandboxedIframes" | "--disable-extensions"]
 
-      def wait_for_load: (?timeout: Integer?) -> void
+      # @return [URI] The URI of the session.
+      attr_reader session_uri: untyped
 
-      def network_events: () -> Bidi2pdf::Bidi::NetworkEvents
+      # @return [Boolean] Whether the session has started.
+      attr_reader started: untyped
 
-      def capture_screenshot: (?path: String?) -> String
+      # @return [Array<String>] The Chrome arguments for the session.
+      attr_reader chrome_args: untyped
 
-      def print_to_pdf: (
-          ?Hash[Symbol, untyped] parameters
-        ) -> String
+      # Initializes a new session.
+      #
+      # @param [String] session_url The URL for the session.
+      # @param [Boolean] headless Whether to run the browser in headless mode. Defaults to true.
+      # @param [Array<String>] chrome_args Additional Chrome arguments. Defaults to predefined arguments.
+      def initialize: (session_url: untyped, ?headless: bool, ?chrome_args: untyped) -> void
 
-      def close: () -> void
+      # Starts the session and initializes the client.
+      #
+      # @raise [StandardError] If an error occurs during session start.
+      def start: () -> untyped
 
-      private
+      # Returns the WebSocket client for the session.
+      #
+      # @return [Bidi2pdf::Bidi::Client, nil] The WebSocket client, or nil if the session is not started.
+      def client: () -> untyped
+
+      # Returns the browser instance for the session.
+      #
+      # @return [Bidi2pdf::Bidi::Browser] The browser instance.
+      def browser: () -> untyped
+
+      # Closes the session and cleans up resources.
+      # rubocop:disable Metrics/AbcSize
+      def close: () -> untyped
+
+      # Retrieves user contexts for the session.
+      def user_contexts: () -> untyped
 
-      def ensure_session: () -> String
+      # Retrieves the status of the session.
+      def status: () -> untyped
+
+      # Checks if the session has started.
+      #
+      # @return [Boolean] True if the session has started, false otherwise.
+      def started?: () -> untyped
+
+      # Retrieves the WebSocket URL for the session.
+      #
+      # @return [String] The WebSocket URL.
+      def websocket_url: () -> untyped
+
+      private
 
-      def setup_event_listeners: () -> void
+      # Sends a command to the WebSocket client.
+      #
+      # @param [Object] command The command to send.
+      # @yield [response] A block to handle the response.
+      def send_cmd: (untyped command) { (?) -> untyped } -> untyped
+
+      # Creates a new browser instance.
+      #
+      # @return [Bidi2pdf::Bidi::Browser] The browser instance.
+      # rubocop:disable Metrics/AbcSize
+      def create_browser: () -> untyped
+
+      # Creates a new WebSocket client.
+      #
+      # @return [Bidi2pdf::Bidi::Client] The WebSocket client.
+      def create_client: () -> untyped
+
+      # Creates a new session and retrieves the WebSocket URL.
+      #
+      # @return [String] The WebSocket URL.
+      def create_new_session: () -> untyped
+
+      # Builds the session request payload.
+      #
+      # @return [Hash] The session request payload.
+      def session_request: () -> { "capabilities" => { "alwaysMatch" => { "browserName" => "chrome", "goog:chromeOptions" => { "args" => untyped }, "goog:prerenderingDisabled" => true, "unhandledPromptBehavior" => { default: "ignore" }, "acceptInsecureCerts" => true, "webSocketUrl" => true } } }
+
+      # Executes an API call with the given payload.
+      #
+      # @param [Hash] payload The payload for the API call.
+      # @return [Hash] The parsed response data.
+      def exec_api_call: (untyped payload) -> untyped
+
+      # Logs an API error.
+      #
+      # @param [String] message The error message.
+      # @param [Integer] code The response code.
+      # @param [String] body The response body.
+      def log_api_error: (untyped message, untyped code, untyped body) -> untyped
+
+      # Determines the error category based on the exception.
+      #
+      # @param [Exception] exception The exception to categorize.
+      # @return [String] The error category.
+      def error_category: (untyped exception) -> untyped
+
+      # Retrieves the error description for a given error type.
+      #
+      # @param [String] type The error type.
+      # @return [String] The error description.
+      def error_description: (untyped type) -> untyped
+
+      # Builds an error response.
+      #
+      # @param [String] error The error type.
+      # @param [String] message The error message.
+      # @param [Array<String>, nil] backtrace The error backtrace.
+      # @return [Hash] The error response.
+      def build_error: (untyped error, untyped message, ?untyped? backtrace) -> { "value" => untyped }
+
+      # Handles an error response from the session.
+      #
+      # @param [Hash] value The error response value.
+      # @raise [SessionNotStartedError] If the session could not be started.
+      def handle_error: (untyped value) -> (nil | untyped)
+
+      # Cleans up resources associated with the session.
+      def cleanup: () -> untyped
     end
   end
-end
+end

data/sig/bidi2pdf/bidi/user_context.rbs

@@ -1,50 +1,69 @@
 module Bidi2pdf
   module Bidi
+    # Represents a user context for managing browser interactions and cookies
+    # using the Bidi2pdf library. This class provides methods for creating
+    # user contexts, setting cookies, and creating browser windows.
+    #
+    # @example Creating a user context
+    #   user_context = Bidi2pdf::Bidi::UserContext.new(client)
+    #
+    # @example Setting a cookie
+    #   user_context.set_cookie(
+    #     name: "session",
+    #     value: "abc123",
+    #     domain: "example.com",
+    #     source_origin: "http://example.com"
+    #   )
+    #
+    # @example Creating a browser window
+    #   browser_window = user_context.create_browser_window
+    #
+    # @param [Object] client The WebSocket client for communication.
     class UserContext
-      @browser: Bidi2pdf::Bidi::Browser
-      @context_id: String
-      @session_id: String?
-      @event_manager: Bidi2pdf::Bidi::EventManager?
-      @network_events: Bidi2pdf::Bidi::NetworkEvents?
-      @closed: bool
-
-      attr_reader context_id: String
-      attr_reader browser: Bidi2pdf::Bidi::Browser
-      attr_reader session_id: String?
-
-      def initialize: (
-          browser: Bidi2pdf::Bidi::Browser,
-          context_id: String,
-          ?session_id: String?
-        ) -> void
-
-      def create_session: () -> String
-
-      def attach_session: (session_id: String) -> String
-
-      def execute_command: [T] (String method, ?Hash[Symbol, untyped] params) -> T
-
-      def navigate_to: (String url) -> void
-
-      def evaluate: [T] (String script) -> T
-
-      def wait_for_load: (?timeout: Integer?) -> void
-
-      def network_events: () -> Bidi2pdf::Bidi::NetworkEvents
-
-      def capture_screenshot: (?path: String?) -> String
-
-      def print_to_pdf: (?Hash[Symbol, untyped] parameters) -> String
-
-      def close: () -> void
-
-      def closed?: () -> bool
-
-      private
-
-      def ensure_open: () -> void
-
-      def setup_event_listeners: () -> void
+      @client: untyped
+
+      @context_id: untyped
+
+      # @return [Object] The WebSocket client.
+      attr_reader client: untyped
+
+      # Initializes a new user context.
+      #
+      # @param [Object] client The WebSocket client for communication.
+      def initialize: (untyped client) -> void
+
+      # Retrieves the user context ID, creating it if it does not exist.
+      #
+      # @return [String] The user context ID.
+      # @raise [RuntimeError] If an error occurs while creating the user context.
+      def context_id: () -> untyped
+
+      # Sets a cookie in the user context.
+      #
+      # @param [String] name The name of the cookie.
+      # @param [String] value The value of the cookie.
+      # @param [String] domain The domain for the cookie.
+      # @param [String] source_origin The source origin for the cookie.
+      # @param [String] path The path for the cookie. Defaults to "/".
+      # @param [Boolean] secure Whether the cookie is secure. Defaults to true.
+      # @param [Boolean] http_only Whether the cookie is HTTP-only. Defaults to false.
+      # @param [String] same_site The SameSite attribute for the cookie. Defaults to "strict".
+      # @param [Integer] ttl The time-to-live for the cookie in seconds. Defaults to 30.
+      def set_cookie: (name: untyped, value: untyped, domain: untyped, source_origin: untyped, ?path: ::String, ?secure: bool, ?http_only: bool, ?same_site: ::String, ?ttl: ::Integer) -> untyped
+
+      # Creates a new browser window in the user context.
+      #
+      # @return [BrowserTab] The newly created browser tab.
+      def create_browser_window: () -> untyped
+
+      # Closes the user context.
+      #
+      # This method removes the user context from the browser, effectively cleaning up
+      # any associated resources. If the user context does not exist, the method does nothing.
+      #
+      # @return [nil]
+      # @raise [RuntimeError] If an error occurs while removing the user context.
+      def close: () -> (nil | untyped)
     end
   end
-end
+end

data/sig/bidi2pdf/bidi/web_socket_dispatcher.rbs

@@ -1,53 +1,45 @@
 module Bidi2pdf
   module Bidi
     class WebSocketDispatcher
-      @url: String
-      @socket: WebSocket::Driver
-      @connection: TCPSocket
-      @pending_requests: Hash[Integer, Concurrent::Promises::ResolvableFuture]
-      @message_id: Integer
-      @listeners: Hash[String, Array[Proc]]
-      @thread: Thread?
-      @mutex: Mutex
-      @connected: bool
-      @logger: Logger?
+      @socket: untyped
 
-      attr_reader url: String
-      attr_reader connected: bool
+      @socket_events: untyped
 
-      def initialize: (String url, ?logger: Logger?) -> void
+      @session_events: untyped
 
-      def connect: () -> bool
+      attr_reader socket_events: untyped
 
-      def disconnect: () -> void
+      attr_reader session_events: untyped
 
-      def send_command: [T] (String method, ?Hash[Symbol, untyped] params) -> T
+      def initialize: (untyped socket) -> void
 
-      def send_message: (Hash[Symbol, untyped] message) -> Integer
+      def start_listening: () -> untyped
 
-      def add_event_listener: (String event_name) { (Hash[String, untyped]) -> void } -> void
+      def on_message: () { (?) -> untyped } -> untyped
 
-      def remove_event_listener: (String event_name, ?Proc? callback) -> void
+      def on_event: (*untyped event_names) { (?) -> untyped } -> untyped
 
-      def connected?: () -> bool
+      def on_open: () { (?) -> untyped } -> untyped
 
-      private
+      def on_close: () { (?) -> untyped } -> untyped
+
+      def on_error: () { (?) -> untyped } -> untyped
 
-      def generate_message_id: () -> Integer
+      def remove_message_listener: (untyped block) -> untyped
 
-      def create_socket: () -> WebSocket::Driver
+      def remove_event_listener: (untyped name, untyped listener) -> untyped
 
-      def handle_open: () -> void
+      def remove_open_listener: (untyped listener) -> untyped
 
-      def handle_message: (String data) -> void
+      def remove_close_listener: (untyped listener) -> untyped
 
-      def handle_close: () -> void
+      def remove_error_listener: (untyped listener) -> untyped
 
-      def handle_error: (Exception error) -> void
+      private
 
-      def dispatch_event: (String event_name, Hash[String, untyped] params) -> void
+      def setup_message_handler: () -> untyped
 
-      def listen_for_messages: () -> void
+      def setup_connection_lifecycle_handlers: () -> untyped
     end
   end
-end
+end

data/sig/bidi2pdf/chromedriver_manager.rbs

@@ -1,42 +1,81 @@
 module Bidi2pdf
   class ChromedriverManager
-    @port: Integer
-    @headless: bool
+    @port: untyped
+
+    @headless: untyped
+
     @session: untyped
-    @pid: Integer?
 
-    attr_reader port: Integer
-    attr_reader pid: Integer?
-    attr_reader session: untyped
+    @started: untyped
+
+    @chrome_args: untyped
+
+    @shutdown_mutex: untyped
+
+    @pid: untyped
+
+    include Chromedriver::Binary::Platform
+
+    attr_reader port: untyped
+
+    attr_reader pid: untyped
+
+    attr_reader started: untyped
+
+    attr_reader headless: untyped
 
-    def initialize: (?port: Integer, ?headless: bool) -> void
+    attr_reader chrome_args: untyped
 
-    def start: () -> self
+    attr_reader shutdown_mutex: untyped
 
-    def stop: (?timeout: Integer) -> bool
+    attr_accessor reader_thread: untyped
+
+    def initialize: (?port: ::Integer, ?headless: bool, ?chrome_args: untyped) -> void
+
+    def start: () -> untyped
+
+    def session: () -> (nil | untyped)
+
+    def session_url: () -> (nil | ::String)
+
+    # rubocop: disable Metrics/AbcSize
+    def stop: (?timeout: ::Integer) -> untyped
 
     private
 
-    # rubocop:disable Metrics/AbcSize
-    def detect_zombie_processes: () -> Array[Integer]?
+    def spawn_process: (untyped cmd) -> untyped
+
+    def detect_zombie_processes: (untyped old_childprocesses) -> (nil | untyped)
+
+    def term_zombie_processes: (untyped zombie_processes) -> untyped
+
+    def debug_show_all_children: () -> untyped
+
+    def close_session: () -> untyped
+
+    def term_chromedriver: () -> untyped
 
-    def debug_show_all_children: () -> void
+    def kill_chromedriver: (?timeout: ::Integer) -> untyped
 
-    def close_session: () -> void
+    def build_cmd: () -> untyped
 
-    def term_chromedriver: () -> bool
+    # Chromedriver's own internal log verbosity is independent from this app's - defaults to
+    # mirroring Bidi2pdf.logger.level for backward compatibility, but Bidi2pdf.chromedriver_log_level
+    # lets a consumer quiet chromedriver's own (often much more verbose, e.g. full BiDi command/
+    # response dumps at its own INFO level) output without changing their app's own log level.
+    def chromedriver_log_level: () -> untyped
 
-    def kill_chromedriver: (?timeout: Integer) -> bool
+    def user_data_dir_arg: () -> (untyped | ::String)
 
-    def build_cmd: () -> Array[String]
+    def process_chrome_args: () -> (::Array[untyped] | untyped)
 
-    def update_chromedriver: () -> void
+    def update_chromedriver: () -> untyped
 
-    # rubocop:disable Metrics/AbcSize
-    def parse_port_from_output: (IO io, ?timeout: Integer) -> Integer?
+    # rubocop: disable Metrics/AbcSize
+    def parse_port_from_output: (untyped io, ?timeout: ::Integer) -> (nil | untyped)
 
-    def process_alive?: (?pid: Integer?) -> bool
+    def process_alive?: (?untyped pid) -> (false | untyped)
 
-    def wait_until_chromedriver_ready: (?timeout: Integer) -> bool
+    def wait_until_chromedriver_ready: (?timeout: ::Integer) -> (true | untyped)
   end
-end
+end

data/sig/bidi2pdf/cli.rbs

@@ -1,13 +1,31 @@
 module Bidi2pdf
+  # rubocop:disable Metrics/AbcSize
   class CLI < Thor
-    # rubocop:disable Layout/BeginEndAlignment
     @launcher: untyped
 
+    def self.exit_on_failure?: () -> true
+
     def render: () -> untyped
 
+    def version: () -> untyped
+
+    def template: () -> untyped
+
     private
 
-    # rubocop:disable  Metrics/AbcSize
+    def load_config: () -> (nil | untyped)
+
+    def validate_required_options!: () -> (untyped | untyped | nil)
+
+    def validate_print_options: (untyped opts) -> untyped
+
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def print_options: () -> untyped
+
+    def option_provided?: (untyped key) -> untyped
+
+    def assign_if_provided: (untyped hash, untyped key, ?untyped option_key) -> (untyped | nil)
+
     def launcher: () -> untyped
 
     def configure: () -> untyped
@@ -17,5 +35,7 @@ module Bidi2pdf
     def parse_key_values: (untyped pairs) -> untyped
 
     def parse_auth: (untyped auth_string) -> ::Array[untyped]
+
+    def merged_options: () -> untyped
   end
 end

data/sig/bidi2pdf/dsl.rbs

@@ -0,0 +1,34 @@
+module Bidi2pdf
+  module DSL
+    # rubocop: disable  Metrics/AbcSize
+    #
+    # Executes a block of code within the context of a browser tab.
+    #
+    # This method handles the setup and teardown of a browser session, user context,
+    # browser window, and tab. It ensures that resources are properly cleaned up
+    # after the block is executed.
+    #
+    # @param [String, nil] remote_browser_url The URL of a remote browser to connect to.
+    #   If provided, the session will connect to this browser in headless mode.
+    # @param [Integer] port The port to use for the local browser session. Defaults to 0 (chooses a random port).
+    # @param [Boolean] headless Whether to run the browser in headless mode. Defaults to true.
+    # @param [Array<String>] chrome_args Additional arguments to pass to the Chrome browser.
+    #   Defaults to the `DEFAULT_CHROME_ARGS` from the `Bidi2pdf::Bidi::Session` class.
+    #
+    # @yield [tab] The browser tab created within the session.
+    # @yieldparam [Object] tab The browser tab object.
+    #
+    # @example Using a local browser session
+    #   Bidi2pdf::DSL.with_tab(port: 9222, headless: false) do |tab|
+    #     # Perform actions with the tab
+    #   end
+    #
+    # @example Using a remote browser session
+    #   Bidi2pdf::DSL.with_tab(remote_browser_url: "http://remote-browser:9222/session") do |tab|
+    #     # Perform actions with the tab
+    #   end
+    #
+    # @return [void]
+    def self.with_tab: (?remote_browser_url: untyped?, ?port: ::Integer, ?headless: bool, ?chrome_args: untyped) { (untyped) -> untyped } -> untyped
+  end
+end

data/sig/bidi2pdf/launcher.rbs

@@ -1,7 +1,39 @@
 module Bidi2pdf
+  # Represents a launcher for managing browser sessions and executing tasks
+  # using the Bidi2pdf library. This class handles the setup and teardown
+  # of browser sessions, as well as the execution of tasks within those sessions.
+  #
+  # @example Launching a session
+  #   launcher = Bidi2pdf::Launcher.new(
+  #     url: "http://example.com",
+  #     inputfile: "input.pdf",
+  #     output: "output.pdf",
+  #     cookies: [],
+  #     headers: {},
+  #     auth: nil,
+  #     headless: true
+  #   )
+  #   launcher.launch
+  #   launcher.stop
+  #
+  # @param [String] url The URL to navigate to in the browser session.
+  # @param [String] inputfile The path to the input file to be processed.
+  # @param [String] output The path to the output file to be generated.
+  # @param [Array<Hash>] cookies An array of cookies to set in the browser session.
+  # @param [Hash] headers A hash of HTTP headers to include in the browser session.
+  # @param [Hash, nil] auth Authentication credentials (e.g., username and password).
+  # @param [Boolean] headless Whether to run the browser in headless mode. Defaults to true.
+  # @param [Integer] port The port to use for the browser session. Defaults to 0.
+  # @param [Boolean] wait_window_loaded Whether to wait for the window to fully load. Defaults to false.
+  # @param [Boolean] wait_network_idle Whether to wait for the network to become idle. Defaults to false.
+  # @param [Hash] print_options Options for printing the page. Defaults to an empty hash.
+  # @param [String, nil] remote_browser_url The URL of a remote browser to connect to. Defaults to nil.
+  # @param [Symbol] network_log_format The format for network logs. Defaults to :console.
   class Launcher
     @url: untyped
 
+    @inputfile: untyped
+
     @port: untyped
 
     @headless: untyped
@@ -24,8 +56,14 @@ module Bidi2pdf
 
     @remote_browser_url: untyped
 
+    @custom_session: untyped
+
+    @network_log_format: untyped
+
+    @chrome_args: untyped
+
     # rubocop:disable Metrics/ParameterLists
-    def initialize: (url: untyped, output: untyped, cookies: untyped, headers: untyped, auth: untyped, ?headless: bool, ?port: ::Integer, ?wait_window_loaded: bool, ?wait_network_idle: bool, ?print_options: ::Hash[untyped, untyped], ?remote_browser_url: untyped?) -> void
+    def initialize: (url: untyped, inputfile: untyped, output: untyped, cookies: untyped, headers: untyped, auth: untyped, ?headless: bool, ?port: ::Integer, ?wait_window_loaded: bool, ?wait_network_idle: bool, ?print_options: ::Hash[untyped, untyped], ?remote_browser_url: untyped?, ?network_log_format: ::Symbol, ?chrome_args: untyped) -> void
 
     def launch: () -> untyped
 

data/sig/bidi2pdf/notifications/event.rbs

@@ -0,0 +1,40 @@
+module Bidi2pdf
+  # rubocop: disable Lint/RescueException
+  module Notifications
+    class Event
+      @name: untyped
+
+      @payload: untyped
+
+      @time: untyped
+
+      @transaction_id: untyped
+
+      @end: untyped
+
+      attr_reader name: untyped
+
+      attr_reader transaction_id: untyped
+
+      attr_accessor payload: untyped
+
+      def initialize: (untyped name, untyped start, untyped ending, untyped transaction_id, untyped payload) -> void
+
+      def record: () ?{ (untyped) -> untyped } -> untyped
+
+      def start!: () -> untyped
+
+      def finish!: () -> untyped
+
+      def duration: () -> untyped
+
+      def time: () -> (untyped | nil)
+
+      def end: () -> (untyped | nil)
+
+      private
+
+      def now: () -> untyped
+    end
+  end
+end