mathpix 0.1.0

data/lib/mathpix/configuration.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Configuration class with security defaults and validation
+  # Seed: 1069 - Deterministic configuration values
+  class Configuration
+    # Security constants
+    HTTPS_ONLY = true
+    MAX_FILE_SIZE_MB = 10
+    MAX_PATH_LENGTH = 1024
+    ALLOWED_SCHEMES = %w[https].freeze
+
+    # Resource limits
+    MIN_LIMIT = 1
+    MAX_LIMIT = 100
+    DEFAULT_LIMIT = 10
+
+    # Confidence thresholds (balanced ternary seed 1069)
+    CONFIDENCE_HIGH = 0.9
+    CONFIDENCE_MEDIUM = 0.7
+    CONFIDENCE_LOW = 0.5
+
+    # Rate limiting (requests per minute)
+    RATE_LIMIT_DEFAULT = 60
+    RATE_LIMIT_BURST = 10
+
+    attr_accessor :app_id, :app_key, :api_url, :timeout, :default_formats,
+                  :user_agent, :enforce_https, :max_file_size_mb, :logger, :seed
+
+    attr_reader :rate_limit, :confidence_thresholds
+
+    # Alias endpoint for api_url (for consistency with Python mpxpy)
+    alias endpoint api_url
+    alias endpoint= api_url=
+
+    def initialize
+      @app_id = ENV.fetch('MATHPIX_APP_ID', nil)
+      @app_key = ENV.fetch('MATHPIX_APP_KEY', nil)
+      @api_url = ENV.fetch('MATHPIX_API_URL', 'https://api.mathpix.com/v3')
+      @timeout = ENV.fetch('MATHPIX_TIMEOUT', '30').to_i
+      @default_formats = [:latex_styled]
+      @user_agent = "mathpix-ruby/#{Mathpix::VERSION}"
+
+      # Security settings
+      @enforce_https = HTTPS_ONLY
+      @max_file_size_mb = MAX_FILE_SIZE_MB
+      @max_path_length = MAX_PATH_LENGTH
+
+      # Resource limits
+      @min_limit = MIN_LIMIT
+      @max_limit = MAX_LIMIT
+      @default_limit = DEFAULT_LIMIT
+
+      # Confidence thresholds
+      @confidence_thresholds = {
+        high: CONFIDENCE_HIGH,
+        medium: CONFIDENCE_MEDIUM,
+        low: CONFIDENCE_LOW
+      }
+
+      # Rate limiting
+      @rate_limit = RATE_LIMIT_DEFAULT
+
+      # Structured logging
+      @logger = nil  # Can be set to Logger instance
+    end
+
+    def validate!
+      raise ConfigurationError, 'app_id is required' if app_id.nil? || app_id.empty?
+      raise ConfigurationError, 'app_key is required' if app_key.nil? || app_key.empty?
+
+      # Validate API URL uses HTTPS
+      if enforce_https && !api_url.start_with?('https://')
+        raise ConfigurationError, 'API URL must use HTTPS'
+      end
+
+      # Validate timeout
+      if timeout <= 0 || timeout > 300
+        raise ConfigurationError, 'Timeout must be between 1 and 300 seconds'
+      end
+
+      true
+    end
+
+    # Sanitize limit to be within bounds
+    #
+    # @param limit [Integer] requested limit
+    # @return [Integer] clamped limit
+    def sanitize_limit(limit)
+      [[limit.to_i, @min_limit].max, @max_limit].min
+    end
+
+    # Check if URL is allowed (HTTPS only)
+    #
+    # @param url [String] URL to validate
+    # @return [Boolean]
+    def valid_url?(url)
+      return false unless url.is_a?(String)
+      return false if url.length > @max_path_length
+
+      uri = URI.parse(url)
+
+      # Must be HTTP(S) scheme
+      return false unless %w[http https].include?(uri.scheme)
+
+      # Enforce HTTPS if enabled
+      return false if enforce_https && uri.scheme != 'https'
+
+      # Must have a host
+      return false if uri.host.nil? || uri.host.empty?
+
+      # Block localhost and private IPs
+      return false if uri.host.match?(/^(localhost|127\.|0\.0\.0\.0|::1)/)
+      return false if uri.host.match?(/^(10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.)/)
+
+      true
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # Auto-upgrade HTTP to HTTPS for remote URLs (feature parity with mpxpy)
+    #
+    # Python mpxpy automatically upgrades http:// to https://
+    # This provides the same behavior for seamless URL support
+    #
+    # @param url [String] URL that may be HTTP or HTTPS
+    # @return [String] URL with https:// scheme
+    # @example
+    #   upgrade_to_https('http://example.com/img.png')
+    #   # => 'https://example.com/img.png'
+    def upgrade_to_https(url)
+      return url unless url.is_a?(String)
+      return url unless url.start_with?('http://')
+
+      url.sub(/^http:\/\//, 'https://')
+    end
+
+    # Sanitize file path to prevent directory traversal
+    #
+    # @param path [String] file path
+    # @return [String, nil] sanitized path or nil if invalid
+    def sanitize_path(path)
+      return nil unless path.is_a?(String)
+      return nil if path.length > @max_path_length
+
+      # Remove null bytes
+      path = path.tr("\0", '')
+
+      # Normalize path
+      normalized = File.expand_path(path)
+
+      # Check for directory traversal attempts
+      return nil if normalized.include?('../')
+      return nil if normalized.match?(/\.\.[\/\\]/)
+
+      # Check file exists (for local paths)
+      return nil unless File.exist?(normalized)
+
+      # Check file size
+      size_mb = File.size(normalized).to_f / (1024 * 1024)
+      return nil if size_mb > @max_file_size_mb
+
+      normalized
+    rescue StandardError
+      nil
+    end
+
+    # Log structured message
+    #
+    # @param level [Symbol] log level (:debug, :info, :warn, :error)
+    # @param message [String] log message
+    # @param data [Hash] structured data
+    def log(level, message, data = {})
+      return unless @logger
+
+      structured_message = {
+        timestamp: Time.now.utc.iso8601,
+        level: level,
+        message: message,
+        seed: 1069,
+        **data
+      }.to_json
+
+      @logger.send(level, structured_message)
+    end
+  end
+end

data/lib/mathpix/configuration.rb.backup

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'fileutils'
+
+module Mathpix
+  # Configuration for Mathpix client
+  # The geodesic path: simple, explicit, block-based
+  #
+  # Priority order (feature parity with mpxpy):
+  # 1. Direct assignment (config.app_id = ...)
+  # 2. Config file (~/.mathpix/config)
+  # 3. Environment variables (MATHPIX_APP_ID, MATHPIX_APP_KEY)
+  class Configuration
+    attr_accessor :app_id, :app_key, :endpoint, :timeout, :seed
+    attr_accessor :default_formats, :default_confidence
+    attr_accessor :auto_retry, :max_retries, :user_agent
+    attr_accessor :config_file_path
+
+    DEFAULT_CONFIG_PATH = File.expand_path('~/.mathpix/config').freeze
+
+    def initialize
+      @endpoint = 'https://api.mathpix.com/v3'
+      @timeout = 30
+      @seed = 1069  # Balanced ternary determinism
+      @default_formats = %i[text latex_styled]
+      @default_confidence = 0.85
+      @auto_retry = true
+      @max_retries = 3
+      @user_agent = "mathpix-ruby/#{Mathpix::VERSION}"
+      @config_file_path = DEFAULT_CONFIG_PATH
+
+      # Load in priority order: direct > file > env
+      load_from_file if File.exist?(@config_file_path)
+      load_from_env
+    end
+
+    # Validate configuration
+    # @raise [ConfigurationError] if invalid
+    def validate!
+      raise ConfigurationError, 'app_id required' unless app_id
+      raise ConfigurationError, 'app_key required' unless app_key
+    end
+
+    # Enable seed-based determinism
+    # @param seed [Integer] random seed
+    def with_seed(seed)
+      @seed = seed
+      srand(seed)
+      self
+    end
+
+    # Set balanced ternary pattern
+    # @return [Array<Integer>] the pattern [+1, -1, -1, +1, +1, +1, +1]
+    def balanced_ternary_pattern
+      [+1, -1, -1, +1, +1, +1, +1]
+    end
+
+    # Load configuration from file (feature parity with mpxpy)
+    #
+    # Config file format (YAML):
+    #   app_id: your_app_id
+    #   app_key: your_app_key
+    #   endpoint: https://api.mathpix.com/v3
+    #   timeout: 30
+    #
+    # @param path [String] config file path
+    # @return [self]
+    def load_from_file(path = @config_file_path)
+      return self unless File.exist?(path)
+
+      config = YAML.load_file(path)
+
+      # Only set if not already set (lower priority than direct assignment)
+      @app_id ||= config['app_id']
+      @app_key ||= config['app_key']
+      @endpoint = config['endpoint'] if config['endpoint']
+      @timeout = config['timeout'] if config['timeout']
+      @seed = config['seed'] if config['seed']
+
+      self
+    rescue => e
+      warn "Failed to load config from #{path}: #{e.message}"
+      self
+    end
+
+    # Load configuration from environment variables
+    #
+    # Environment variables:
+    #   MATHPIX_APP_ID
+    #   MATHPIX_APP_KEY
+    #   MATHPIX_ENDPOINT
+    #   MATHPIX_TIMEOUT
+    #
+    # @return [self]
+    def load_from_env
+      # Only set if not already set (lowest priority)
+      @app_id ||= ENV['MATHPIX_APP_ID']
+      @app_key ||= ENV['MATHPIX_APP_KEY']
+      @endpoint = ENV['MATHPIX_ENDPOINT'] if ENV['MATHPIX_ENDPOINT']
+      @timeout = ENV['MATHPIX_TIMEOUT'].to_i if ENV['MATHPIX_TIMEOUT']
+
+      self
+    end
+
+    # Save current configuration to file
+    #
+    # @param path [String] config file path
+    # @return [self]
+    def save_to_file(path = @config_file_path)
+      FileUtils.mkdir_p(File.dirname(path))
+
+      config = {
+        'app_id' => @app_id,
+        'app_key' => @app_key,
+        'endpoint' => @endpoint,
+        'timeout' => @timeout,
+        'seed' => @seed
+      }
+
+      File.write(path, YAML.dump(config))
+      self
+    end
+  end
+end

data/lib/mathpix/conversion.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module Mathpix
+  # Mathpix Markdown (MMD) conversion to multiple formats
+  # Handles async conversion via POST /v3/converter
+  class Conversion
+    attr_reader :conversion_id, :mmd, :formats, :client
+
+    # Conversion status states
+    STATUS_QUEUED = 'queued'
+    STATUS_PROCESSING = 'processing'
+    STATUS_COMPLETED = 'completed'
+    STATUS_ERROR = 'error'
+
+    # Supported output formats (verified from Mathpix API docs)
+    SUPPORTED_FORMATS = %w[
+      md docx tex.zip html pdf latex_pdf pptx
+      mmd.zip md.zip html.zip
+    ].freeze
+
+    def initialize(client, conversion_id: nil, mmd: nil, formats: nil)
+      @client = client
+      @conversion_id = conversion_id
+      @mmd = mmd
+      @formats = formats
+      @status_data = nil
+    end
+
+    # Check conversion status
+    #
+    # @return [String] status (queued, processing, completed, error)
+    def status
+      refresh_status unless @status_data
+      @status_data['status']
+    end
+
+    # Check if conversion is complete
+    #
+    # @return [Boolean]
+    def completed?
+      status == STATUS_COMPLETED
+    end
+
+    # Check if conversion is still processing
+    #
+    # @return [Boolean]
+    def processing?
+      [STATUS_QUEUED, STATUS_PROCESSING].include?(status)
+    end
+
+    # Check if conversion failed
+    #
+    # @return [Boolean]
+    def error?
+      status == STATUS_ERROR
+    end
+
+    # Get error message if conversion failed
+    #
+    # @return [String, nil]
+    def error_message
+      @status_data&.dig('error')
+    end
+
+    # Wait until conversion is complete
+    #
+    # @param max_wait [Integer] maximum seconds to wait (default: 300 = 5 minutes)
+    # @param poll_interval [Float] seconds between status checks (default: 2.0)
+    # @return [self]
+    # @raise [TimeoutError] if max_wait exceeded
+    # @raise [ConversionError] if conversion fails
+    def wait_until_complete(max_wait: 300, poll_interval: 2.0)
+      start_time = Time.now
+
+      loop do
+        refresh_status
+
+        return self if completed?
+
+        if error?
+          raise ConversionError, "Conversion failed: #{error_message}"
+        end
+
+        elapsed = Time.now - start_time
+        if elapsed > max_wait
+          raise TimeoutError, "Conversion timed out after #{max_wait}s (status: #{status})"
+        end
+
+        sleep poll_interval if processing?
+      end
+    end
+
+    # Poll until complete (alias for wait_until_complete)
+    #
+    # @param max_wait [Integer] maximum seconds to wait
+    # @param poll_interval [Float] seconds between checks
+    # @return [self]
+    def poll_until_ready(max_wait: 300, poll_interval: 2.0)
+      wait_until_complete(max_wait: max_wait, poll_interval: poll_interval)
+    end
+
+    # Get converted output for a specific format
+    #
+    # @param format [String, Symbol] output format (e.g., 'pdf', :docx)
+    # @return [String] file content as bytes
+    # @raise [Error] if conversion not complete
+    def output(format)
+      raise Error, "Conversion not complete (status: #{status})" unless completed?
+
+      format_str = format.to_s
+      url = output_url(format_str)
+
+      client.download(url)
+    end
+
+    # Save output to file
+    #
+    # @param format [String, Symbol] output format
+    # @param path [String] destination file path
+    # @return [String] path to saved file
+    def save_output(format, path)
+      content = output(format)
+      File.binwrite(path, content)
+      path
+    end
+
+    # --- Format-specific convenience methods (mpxpy parity) ---
+
+    # Get PDF output as bytes
+    # @return [String] binary PDF content
+    def to_pdf_bytes
+      output(:pdf)
+    end
+
+    # Save PDF to file
+    # @param path [String] destination path
+    # @return [String] path
+    def to_pdf_file(path)
+      save_output(:pdf, path)
+    end
+
+    # Get DOCX output as bytes
+    # @return [String] binary DOCX content
+    def to_docx_bytes
+      output(:docx)
+    end
+
+    # Save DOCX to file
+    # @param path [String] destination path
+    # @return [String] path
+    def to_docx_file(path)
+      save_output(:docx, path)
+    end
+
+    # Get HTML output as text
+    # @return [String] HTML content
+    def to_html_text
+      output(:html)
+    end
+
+    # Save HTML to file
+    # @param path [String] destination path
+    # @return [String] path
+    def to_html_file(path)
+      save_output(:html, path)
+    end
+
+    # Get Markdown output as text
+    # @return [String] Markdown content
+    def to_md_text
+      output(:md)
+    end
+
+    alias to_markdown_text to_md_text
+
+    # Save Markdown to file
+    # @param path [String] destination path
+    # @return [String] path
+    def to_md_file(path)
+      save_output(:md, path)
+    end
+
+    alias to_markdown_file to_md_file
+
+    # Get LaTeX ZIP as bytes
+    # @return [String] binary ZIP content
+    def to_tex_zip_bytes
+      output(:'tex.zip')
+    end
+
+    # Save LaTeX ZIP to file
+    # @param path [String] destination path
+    # @return [String] path
+    def to_tex_zip_file(path)
+      save_output(:'tex.zip', path)
+    end
+
+    # Get LaTeX PDF as bytes
+    # @return [String] binary PDF content
+    def to_latex_pdf_bytes
+      output(:latex_pdf)
+    end
+
+    # Save LaTeX PDF to file
+    # @param path [String] destination path
+    # @return [String] path
+    def to_latex_pdf_file(path)
+      save_output(:latex_pdf, path)
+    end
+
+    # Get PowerPoint as bytes
+    # @return [String] binary PPTX content
+    def to_pptx_bytes
+      output(:pptx)
+    end
+
+    # Save PowerPoint to file
+    # @param path [String] destination path
+    # @return [String] path
+    def to_pptx_file(path)
+      save_output(:pptx, path)
+    end
+
+    # Get all available outputs
+    #
+    # @return [Hash<Symbol, String>] format => url mapping
+    def available_outputs
+      refresh_status unless completed?
+      return {} unless @status_data&.dig('outputs')
+
+      @status_data['outputs'].transform_keys(&:to_sym)
+    end
+
+    # Inspect
+    # @return [String]
+    def inspect
+      "#<Mathpix::Conversion id=#{conversion_id} status=#{status}>"
+    end
+
+    private
+
+    # Refresh status from API
+    def refresh_status
+      @status_data = client.get_conversion_status(conversion_id)
+    end
+
+    # Get output URL for format
+    #
+    # @param format [String] format name
+    # @return [String] download URL
+    def output_url(format)
+      urls = @status_data&.dig('outputs') || {}
+      urls[format] || urls[format.to_s] ||
+        raise(Error, "Output format '#{format}' not available. Available: #{urls.keys.join(', ')}")
+    end
+  end
+end