bidi2pdf 0.1.13 → 0.1.15

data/sig/bidi2pdf/bidi/auth_interceptor.rbs

@@ -1,17 +1,42 @@
 module Bidi2pdf
   module Bidi
     class AuthInterceptor
-      @credentials: Hash[Symbol, String]?
+      @url_patterns: untyped
 
-      def initialize: (?credentials: Hash[Symbol, String]?) -> void
+      @context: untyped
 
-      def intercept: (untyped request) -> untyped
+      @username: untyped
 
-      private
+      @password: untyped
+
+      @network_ids: untyped
+
+      include Interceptor
+
+      def self.phases: () -> ::Array[untyped]
+
+      def self.events: () -> ::Array["network.authRequired"]
+
+      attr_reader headers: untyped
+
+      attr_reader url_patterns: untyped
 
-      def add_auth_header: (untyped request) -> void
+      attr_reader context: untyped
+
+      attr_reader username: untyped
+
+      attr_reader password: untyped
+
+      attr_reader network_ids: untyped
+
+      def initialize: (username: untyped, password: untyped, url_patterns: untyped, context: untyped) -> void
+
+      def process_interception: (untyped _event_response, untyped navigation_id, untyped network_id, untyped url) -> untyped
+
+      private
 
-      def auth_header_value: () -> String?
+      # rubocop:disable Naming/PredicateMethod
+      def handled_bad_credentials: (untyped navigation_id, untyped network_id, untyped url) -> (false | true)
     end
   end
-end
+end

data/sig/bidi2pdf/bidi/browser.rbs

@@ -1,38 +1,11 @@
 module Bidi2pdf
   module Bidi
     class Browser
-      @url: String
-      @chromedriver_manager: Bidi2pdf::ChromedriverManager
-      @browser: untyped
-      @timeout: Integer
-      @debug: bool
+      @client: untyped
 
-      attr_reader browser: untyped
-      attr_reader timeout: Integer
+      def initialize: (untyped client) -> void
 
-      def initialize: (
-          url: String,
-          chromedriver_manager: Bidi2pdf::ChromedriverManager,
-          ?timeout: Integer,
-          ?debug: bool
-        ) -> void
-
-      def navigate: (?reload: bool) -> void
-
-      def current_url: -> String
-
-      def wait_until: [T] (
-          ?timeout: Integer,
-          ?message: String
-        ) { () -> T? } -> T
-
-      def close: () -> void
-
-      private
-
-      def connect: () -> untyped
-
-      def setup_browser: () -> untyped
+      def create_user_context: () -> untyped
     end
   end
-end
+end

data/sig/bidi2pdf/bidi/browser_console_logger.rbs

@@ -0,0 +1,59 @@
+module Bidi2pdf
+  module Bidi
+    class BrowserConsoleLoggerSuggar
+      @browser_console_logger: untyped
+
+      @level: untyped
+
+      @prefix: untyped
+
+      @timestamp: untyped
+
+      @text: untyped
+
+      @args: untyped
+
+      @stack_trace: untyped
+
+      attr_reader browser_console_logger: untyped
+
+      def initialize: (untyped browser_console_logger) -> void
+
+      def with_level: (untyped level) -> self
+
+      def with_prefix: (untyped prefix) -> self
+
+      def with_timestamp: (untyped timestamp) -> self
+
+      def with_text: (untyped text) -> self
+
+      def with_args: (untyped args) -> self
+
+      def with_stack_trace: (untyped stack_trace) -> self
+
+      def log_event: () -> untyped
+
+      def prefix: () -> untyped
+    end
+
+    class BrowserConsoleLogger
+      @logger: untyped
+
+      include JsLoggerHelper
+
+      attr_accessor logger: untyped
+
+      def initialize: (untyped logger) -> void
+
+      def builder: () -> untyped
+
+      def log_message: (untyped level, untyped prefix, untyped text) -> (nil | untyped)
+
+      def log_args: (untyped prefix, untyped args) -> (nil | untyped)
+
+      def log_stack_trace: (untyped prefix, untyped trace) -> untyped
+
+      def self.format_timestamp: (untyped timestamp) -> ("N/A" | untyped)
+    end
+  end
+end

data/sig/bidi2pdf/bidi/browser_tab.rbs

@@ -1,42 +1,286 @@
+# Represents a browser tab for managing interactions and communication
+# using the Bidi2pdf library. This class provides methods for creating
+# browser tabs, managing cookies, navigating to URLs, executing scripts,
+# and handling network events.
+#
+# @example Creating a browser tab
+#   browser_tab = Bidi2pdf::Bidi::BrowserTab.new(client, browsing_context_id, user_context_id)
+#   browser_tab.create_browser_tab
+#
+# @example Navigating to a URL
+#   browser_tab.navigate_to("http://example.com")
+#
+# @example Setting a cookie
+#   browser_tab.set_cookie(
+#     name: "session",
+#     value: "abc123",
+#     domain: "example.com"
+#   )
+#
+# @param [Object] client The WebSocket client for communication.
+# @param [String] browsing_context_id The ID of the browsing context.
+# @param [String] user_context_id The ID of the user context.
 module Bidi2pdf
   module Bidi
+    # Represents a browser tab for managing interactions and communication
+    # using the Bidi2pdf library. This class provides methods for creating
+    # browser tabs, managing cookies, navigating to URLs, executing scripts,
+    # handling network events, and general tab lifecycle management.
+    #
     class BrowserTab
-      @browser: Bidi2pdf::Bidi::Browser
-      @tab_id: String?
-      @session_id: String?
-      @timeout: Integer
+      @client: untyped
 
-      attr_reader browser: Bidi2pdf::Bidi::Browser
-      attr_reader tab_id: String?
-      attr_reader session_id: String?
+      @browsing_context_id: untyped
 
-      def initialize: (
-          browser: Bidi2pdf::Bidi::Browser,
-          ?tab_id: String?,
-          ?timeout: Integer
-        ) -> void
+      @user_context_id: untyped
 
-      def navigate_to: (String url) -> void
+      @tabs: untyped
 
-      def execute_script: [T] (String script, *untyped args) -> T
+      @network_events: untyped
 
-      def wait_for_navigation: (?timeout: Integer) -> void
+      @logger_events: untyped
 
-      def wait_for_element: (
-          selector: String,
-          ?visible: bool,
-          ?timeout: Integer
-        ) -> untyped
+      @navigation_failed_events: untyped
 
-      def capture_screenshot: (?path: String?) -> String
+      @open: untyped
 
-      def close: () -> void
+      @header_interceptor: untyped
+
+      @basic_auth_interceptor: untyped
+
+      @cdp_session: untyped
+
+      @event_handlers_registered: untyped
+
+      @listener_refs: untyped
+
+      include JsLoggerHelper
+
+      # @return [Object] The WebSocket client.
+      attr_reader client: untyped
+
+      # @return [String] The browsing context ID.
+      attr_reader browsing_context_id: untyped
+
+      # @return [String] The user context ID.
+      attr_reader user_context_id: untyped
+
+      # @return [Array<BrowserTab>] The list of tabs.
+      attr_reader tabs: untyped
+
+      # @return [NetworkEvents] The network events handler.
+      attr_reader network_events: untyped
+
+      # @return [Boolean] Whether the tab is open.
+      attr_reader open: untyped
+
+      # @return [LoggerEvents] The logger events handler.
+      attr_reader logger_events: untyped
+
+      # @return [NavigationFailedEvents] The navigation failed events handler.
+      attr_reader navigation_failed_events: untyped
+
+      # Initializes a new browser tab.
+      #
+      # @param [Object] client The WebSocket client for communication.
+      # @param [String] browsing_context_id The ID of the browsing context.
+      # @param [String] user_context_id The ID of the user context.
+      def initialize: (untyped client, untyped browsing_context_id, untyped user_context_id) -> void
+
+      # Creates a new browser tab.
+      #
+      # @return [BrowserTab] The newly created browser tab.
+      def create_browser_tab: () -> untyped
+
+      # Sets a cookie in the browser tab.
+      #
+      # @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] 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, ?path: ::String, ?secure: bool, ?http_only: bool, ?same_site: ::String, ?ttl: ::Integer) -> untyped
+
+      # Adds headers to requests in the browser tab.
+      #
+      # @param [Hash] headers The headers to add.
+      # @param [Array<String>] url_patterns The URL patterns to match.
+      # @return [AddHeadersInterceptor] The interceptor instance.
+      def add_headers: (headers: untyped, url_patterns: untyped) -> untyped
+
+      # Configures basic authentication for requests in the browser tab.
+      #
+      # @param [String] username The username for authentication.
+      # @param [String] password The password for authentication.
+      # @param [Array<String>] url_patterns The URL patterns to match.
+      # @return [AuthInterceptor] The interceptor instance.
+      def basic_auth: (username: untyped, password: untyped, url_patterns: untyped) -> untyped
+
+      # Navigates the browser tab to a specified URL.
+      #
+      # This method registers necessary event listeners and sends a navigation
+      # command to the browser tab, instructing it to load the specified URL.
+      # It validates that the URL is properly formatted before attempting navigation.
+      #
+      # @param [String] url The URL to navigate to.
+      # @raise [NavigationError] If the URL is invalid or improperly formatted.
+      # @example
+      #   browser_tab.navigate_to("https://example.com")
+      def navigate_to: (untyped url, ?wait: ::String) -> untyped
+
+      # Renders HTML content in the browser tab.
+      #
+      # @param [String] html_content The HTML content to render.
+      # rubocop:disable  Metrics/BlockLength
+      def render_html_content: (untyped html_content, ?wait: ::String) -> untyped
+
+      # Executes a script in the browser tab.
+      #
+      # This method allows you to execute JavaScript code within the context of the browser tab.
+      # Optionally, the script can be wrapped in a JavaScript Promise to handle asynchronous operations.
+      #
+      # @param [String] script The JavaScript code to execute.
+      #   - This can be any valid JavaScript code that you want to run in the browser tab.
+      # @param [Boolean] wrap_in_promise Whether to wrap the script in a Promise. Defaults to false.
+      #   - If true, the script will be wrapped in a Promise to handle asynchronous execution.
+      #   - Use this option when the script involves asynchronous operations like network requests.
+      #     You can use the predefined variable result to store the result of the script.
+      # @return [Object] The result of the script execution.
+      #   - If the script executes successfully, the result of the last evaluated expression is returned.
+      #   - If the script fails, an error or exception details may be returned.
+      def execute_script: (untyped script, ?wrap_in_promise: bool) -> untyped
+
+      # Injects a JavaScript script element into the page, either from a URL or with inline content.
+      #
+      # @param [String, nil] url The URL of the script to load (optional).
+      # @param [String, nil] content The JavaScript content to inject (optional).
+      # @param [String, nil] id The ID attribute for the script element (optional).
+      # @return [Object] The result from the script creation promise.
+      def inject_script: (?url: untyped?, ?content: untyped?, ?id: untyped?) -> untyped
+
+      # Injects a CSS style element into the page, either from a URL or with inline content.
+      #
+      # @param [String, nil] url The URL of the stylesheet to load (optional).
+      # @param [String, nil] content The CSS content to inject (optional).
+      # @param [String, nil] id The ID attribute for the style element (optional).
+      # @return [Object] The result from the style creation promise.
+      def inject_style: (?url: untyped?, ?content: untyped?, ?id: untyped?) -> untyped
+
+      # Waits until the network is idle in the browser tab.
+      #
+      # @param [Integer] timeout The timeout duration in seconds. Defaults to 10.
+      # @param [Float] poll_interval The polling interval in seconds. Defaults to 0.1.
+      def wait_until_network_idle: (?timeout: ::Integer, ?poll_interval: ::Float) -> untyped
+
+      # Waits until the page is fully loaded in the browser tab.
+      #
+      # This method executes a JavaScript script that checks if the page
+      # has finished loading.
+      #
+      # @param [String] check_script The JavaScript code to check if the page is loaded.
+      #   - Defaults to a script that polls the `window.loaded` property.
+      # @return [Object] The result of the script execution.
+      #   - If the page is loaded successfully, the Promise resolves with the value `'done'`.
+      #   - If the script fails, an error or exception details may be returned.
+      def wait_until_page_loaded: (?check_script: untyped?) -> untyped
+
+      # Logs network traffic in the browser tab.
+      #
+      # @param [Symbol] format The format for logging (:console or :pdf). Defaults to :console.
+      # @param [String, nil] output The output file for PDF logging. Defaults to nil.
+      # @param [Hash] print_options Options for printing. Defaults to { background: true }.
+      # @yield [pdf_base64] A block to handle the PDF content.
+      def log_network_traffic: (?format: ::Symbol, ?output: untyped?, ?print_options: ::Hash[untyped, untyped]) { (?) -> untyped } -> (nil | untyped)
+
+      # Closes the browser tab and its associated resources.
+      def close: () -> (nil | untyped)
+
+      # Prints the content of the browser tab.
+      #
+      # @param [String, nil] outputfile The output file for the PDF. Defaults to nil.
+      # @param [Hash] print_options Options for printing. Defaults to { background: true }.
+      # @yield [pdf_base64] A block to handle the PDF content.
+      # @return [String, nil] The base64-encoded PDF content, or nil if outputfile or block is provided.
+      # rubocop:disable Metrics/AbcSize, Metrics/PerceivedComplexity
+      def print: (?untyped? outputfile, ?print_options: ::Hash[untyped, untyped]) ?{ (?) -> untyped } -> untyped
+
+      # Captures a screenshot of the browser tab, mirroring #print's own
+      # file/block/base64-return trichotomy.
+      #
+      # @param [String, nil] outputfile The output file for the PNG. Defaults to nil.
+      # @param [String] origin "document" (default) or "viewport" - see browsingContext.captureScreenshot.
+      # @param [String, nil] format Image format override, e.g. "image/png". Defaults to the browser's own default.
+      # @param [Hash, nil] clip A clip rectangle/element, passed through verbatim. Defaults to nil (full capture).
+      # @yield [png_base64] A block to handle the PNG content.
+      # @return [String, nil] The base64-encoded PNG content, or nil if outputfile or block is provided.
+      # rubocop:disable Metrics/AbcSize
+      def screenshot: (?untyped? outputfile, ?origin: ::String, ?format: untyped?, ?clip: untyped?) ?{ (?) -> untyped } -> untyped
+
+      # Sets the browsing context's viewport - makes a headless render deterministic across
+      # machines, unlike leaving it at the browser's own default.
+      #
+      # @param [Integer] width
+      # @param [Integer] height
+      # @param [Float, nil] device_pixel_ratio Defaults to nil (browser default).
+      def set_viewport: (width: untyped, height: untyped, ?device_pixel_ratio: untyped?) -> untyped
 
       private
 
-      def ensure_tab_active: () -> void
+      def build_command_and_extractor: (untyped print_options) -> ::Array[untyped]
+
+      def cdp_session: () -> untyped
+
+      def navigate_with_listeners: (untyped url, ?wait: ::String) -> untyped
+
+      def raise_navigation_error_for: (untyped url, untyped error) -> untyped
+
+      # browsingContext.navigate's own response never carries an HTTP status - only a
+      # network.responseCompleted event does, correlated back to this specific navigation via its
+      # "navigation" field (a Chrome/redirect-chain-wide ID, not the network request's own id).
+      # register_event_listeners already ran above, so network_events has been tracking since
+      # before the navigate command was even sent. Deliberately conservative: with no navigation
+      # ID, or no correlated *completed* request found, this stays silent rather than guessing -
+      # only a positively confirmed >= 400 status raises. max_by(&:start_timestamp) picks the last
+      # hop of a redirect chain (every hop shares the same navigation ID), matching the page the
+      # browser actually ended up on.
+      def check_navigation_http_status: (untyped url, untyped navigation_id) -> (nil | untyped)
+
+      # The last hop of a redirect chain (every hop shares the same navigation ID) - the page the
+      # browser actually ended up on, not wherever the chain started.
+      def correlated_navigation_response: (untyped navigation_id) -> untyped
+
+      def register_event_listeners: () -> (nil | untyped)
+
+      def handle_injection_exception: (untyped response, untyped url, untyped exception_class) -> untyped
+
+      # Generates JavaScript code for creating a script element with given parameters.
+      #
+      # @param [String, nil] url The URL of the script to load (optional).
+      # @param [String, nil] content The JavaScript content for the script (optional).
+      # @param [String, nil] id The ID attribute for the script element (optional).
+      # @return [String] JavaScript code that creates a script element.
+      def generate_script_element_code: (?url: untyped?, ?content: untyped?, ?id: untyped?) -> ::String
+
+      # Generates JavaScript code for creating a style element with given parameters.
+      #
+      # @param [String, nil] url The URL of the stylesheet to load (optional).
+      # @param [String, nil] content The CSS content for the style (optional).
+      # @param [String, nil] id The ID attribute for the style element (optional).
+      # @return [String] JavaScript code that creates a style element.
+      def generate_style_element_code: (?url: untyped?, ?content: untyped?, ?id: untyped?) -> ::String
+
+      # Closes the browsing context.
+      def close_context: () -> untyped
+
+      # Removes event listeners for the browser tab.
+      # rubocop:disable Metrics/AbcSize
+      def remove_event_listeners: () -> (nil | untyped)
 
-      def connect_to_tab: () -> String?
+      # Closes all tabs associated with the browser tab.
+      def close_tabs: () -> untyped
     end
   end
-end
+end

data/sig/bidi2pdf/bidi/buffered_web_socket_client.rbs

@@ -0,0 +1,81 @@
+module Bidi2pdf
+  module Bidi
+    # A threaded WebSocket client on the `websocket` gem's framing - the same shape Selenium's Ruby
+    # BiDi client uses. It replaces websocket-client-simple, whose reader pulled one byte at a time
+    # (`getc`, then a frame-parse attempt per byte): a printed PDF comes back as one base64 message
+    # and every network event for a `data:` navigation echoes the whole URL, so that loop ran
+    # millions of times per render - ~730 ms to decode a 700 KB frame, against ~0.5 ms in 16 KB
+    # chunks.
+    #
+    # Emits :open, :message (a WebSocket frame, payload in #data), :error and :close.
+    class BufferedWebSocketClient
+      @listeners: untyped
+
+      @listeners_mutex: untyped
+
+      @write_mutex: untyped
+
+      # Re-entrant: a failed write inside #close closes again.
+      @close_monitor: untyped
+
+      @handshaked: untyped
+
+      @closed: untyped
+
+      @url: untyped
+
+      @socket: untyped
+
+      @handshake: untyped
+
+      @thread: untyped
+
+      READ_CHUNK_BYTES: 16384
+
+      attr_reader url: untyped
+
+      def self.connect: (untyped url, ?::Hash[untyped, untyped] options) ?{ (untyped) -> untyped } -> untyped
+
+      def initialize: () -> void
+
+      def on: (untyped event) { (?) -> untyped } -> untyped
+
+      def connect: (untyped url, ?::Hash[untyped, untyped] options) -> (nil | untyped)
+
+      # Commands are sent from whichever thread issues them. On a plain TCP socket one IO#write is
+      # already atomic, but OpenSSL::SSL::SSLSocket#write is not, so writes share a lock for wss://.
+      def send: (untyped data, ?type: ::Symbol) -> untyped
+
+      # Safe from any thread, including the reader's own: the reader sees the peer hang up and
+      # closes from inside its loop, so it must neither race a caller closing at the same moment
+      # nor be killed before :close has been emitted.
+      def close: (?untyped? error) -> untyped
+
+      def open?: () -> untyped
+
+      def closed?: () -> untyped
+
+      private
+
+      def emit: (untyped event, *untyped) -> untyped
+
+      def write: (untyped bytes) -> untyped
+
+      def say_goodbye: () -> untyped
+
+      def open_socket: (untyped uri, untyped options) -> untyped
+
+      def ssl_context: (untyped options) -> untyped
+
+      def read_loop: (untyped socket, untyped frame) -> untyped
+
+      def consume: (untyped chunk, untyped frame) -> (nil | untyped)
+
+      # WebSocket control frames (ping/pong/close) must never reach a JSON-parsing consumer -
+      # WebSocketDispatcher tries to parse every :message payload as JSON, so a raw close frame
+      # would raise JSON::ParserError, and an unanswered ping can make chromedriver or an
+      # intermediate proxy tear down an otherwise healthy connection on its own keepalive timeout.
+      def dispatch_frame: (untyped message) -> untyped
+    end
+  end
+end