brainzlab 0.1.11 → 0.1.20

data/lib/brainzlab/devtools/assets/devtools.js

@@ -4,6 +4,46 @@
 (function() {
   'use strict';
 
+  // ============================================
+  // DARK MODE SUPPORT
+  // ============================================
+  // Sync with brainzlab-theme localStorage key (used across all BrainzLab products)
+  function initDarkMode() {
+    const theme = localStorage.getItem('brainzlab-theme');
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+
+    if (theme === 'dark' || (!theme && prefersDark)) {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  }
+
+  // Listen for theme changes from other windows/tabs
+  function setupThemeListener() {
+    window.addEventListener('storage', function(e) {
+      if (e.key === 'brainzlab-theme') {
+        initDarkMode();
+      }
+    });
+
+    // Also listen for system preference changes
+    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function(e) {
+      // Only react if no explicit theme is set
+      if (!localStorage.getItem('brainzlab-theme')) {
+        if (e.matches) {
+          document.documentElement.classList.add('dark');
+        } else {
+          document.documentElement.classList.remove('dark');
+        }
+      }
+    });
+  }
+
+  // Initialize dark mode immediately
+  initDarkMode();
+  setupThemeListener();
+
   // Load Stimulus if not available
   let stimulusApp = null;
   let StimulusController = null;

data/lib/brainzlab/devtools/middleware/asset_server.rb

@@ -18,6 +18,7 @@ module BrainzLab
 
         def call(env)
           return @app.call(env) unless DevTools.enabled?
+          return @app.call(env) if env['REQUEST_METHOD'] == 'OPTIONS'
 
           path = env['PATH_INFO']
           asset_prefix = DevTools.asset_path

data/lib/brainzlab/devtools/middleware/debug_panel.rb

@@ -38,6 +38,7 @@ module BrainzLab
           return false unless DevTools.debug_panel_enabled?
           return false unless DevTools.allowed_environment?
           return false unless DevTools.allowed_ip?(extract_ip(env))
+          return false if env['REQUEST_METHOD'] == 'OPTIONS'
           return false if asset_request?(env['PATH_INFO'])
           return false if devtools_asset_request?(env['PATH_INFO'])
           return false if turbo_stream_request?(env)

data/lib/brainzlab/devtools/middleware/error_page.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module BrainzLab
   module DevTools
     module Middleware
@@ -10,29 +12,33 @@ module BrainzLab
         end
 
         def call(env)
+          return @app.call(env) if env['REQUEST_METHOD'] == 'OPTIONS'
           return @app.call(env) unless should_handle?(env)
 
           begin
             status, headers, body = @app.call(env)
 
             # Check if this is an error response that we should intercept
-            if status >= 400 && html_response?(headers) && !json_request?(env)
+            if status >= 400 && html_response?(headers) && !json_request?(env) && !api_path?(env)
               # Check if this looks like Rails' default error page
               body_content = collect_body(body)
               if body_content.include?('Action Controller: Exception caught') || body_content.include?('background: #C00')
                 # Extract exception info from the page
                 exception_info = extract_exception_from_html(body_content)
                 if exception_info
-                  data = collect_debug_data_from_info(env, exception_info)
-                  return render_error_page_from_info(exception_info, data)
+                  data = collect_debug_data_from_info(env, exception_info, status)
+                  return render_error_page_from_info(exception_info, data, status)
                 end
               end
             end
 
             [status, headers, body]
           rescue Exception => e
-            # Don't intercept if request wants JSON
-            return raise_exception(e) if json_request?(env)
+            # For JSON/API requests, return a proper JSON error response
+            if json_request?(env) || api_path?(env)
+              capture_to_reflex(e)
+              return json_error_response(e)
+            end
 
             # Still capture to Reflex if available
             capture_to_reflex(e)
@@ -87,7 +93,7 @@ module BrainzLab
              .gsub(' ', ' ')
         end
 
-        def collect_debug_data_from_info(env, info)
+        def collect_debug_data_from_info(env, info, status = 500)
           context = defined?(BrainzLab::Context) ? BrainzLab::Context.current : nil
           collector_data = Data::Collector.get_request_data
 
@@ -113,7 +119,7 @@ module BrainzLab
           }
         end
 
-        def render_error_page_from_info(info, data)
+        def render_error_page_from_info(info, data, status = 500)
           # Create a simple exception-like object
           exception = StandardError.new(info[:message])
           exception.define_singleton_method(:class) do
@@ -126,7 +132,7 @@ module BrainzLab
           html = @renderer.render(exception, data)
 
           [
-            500,
+            status,
             {
               'Content-Type' => 'text/html; charset=utf-8',
               'Content-Length' => html.bytesize.to_s,
@@ -169,6 +175,48 @@ module BrainzLab
             env['HTTP_X_REQUESTED_WITH'] == 'XMLHttpRequest'
         end
 
+        def api_path?(env)
+          path = env['PATH_INFO'] || ''
+          path.start_with?('/api/')
+        end
+
+        def exception_to_status(exception)
+          case exception.class.name
+          when 'ActionController::RoutingError', 'AbstractController::ActionNotFound'
+            404
+          when 'ActionController::MethodNotAllowed'
+            405
+          when 'ActionController::BadRequest', 'ActionDispatch::Http::Parameters::ParseError'
+            400
+          when 'ActionController::UnknownFormat'
+            406
+          else
+            500
+          end
+        end
+
+        def json_error_response(exception)
+          status_code = exception_to_status(exception)
+          message = case status_code
+                    when 400 then 'Bad request'
+                    when 404 then 'Not found'
+                    when 405 then 'Method not allowed'
+                    when 406 then 'Not acceptable'
+                    else 'Internal server error'
+                    end
+
+          body = JSON.generate({ error: message })
+          [
+            status_code,
+            {
+              'Content-Type' => 'application/json; charset=utf-8',
+              'Content-Length' => body.bytesize.to_s,
+              'X-Content-Type-Options' => 'nosniff'
+            },
+            [body]
+          ]
+        end
+
         def capture_to_reflex(exception)
           return unless defined?(BrainzLab::Reflex)
 

data/lib/brainzlab/errors.rb

@@ -0,0 +1,490 @@
+# frozen_string_literal: true
+
+module BrainzLab
+  # Base error class for all BrainzLab SDK errors.
+  # Provides structured error information including hints and documentation links.
+  #
+  # @example Raising a structured error
+  #   raise BrainzLab::Error.new(
+  #     "Operation failed",
+  #     hint: "Check your network connection",
+  #     docs_url: "https://docs.brainzlab.io/troubleshooting",
+  #     code: "operation_failed"
+  #   )
+  #
+  # @example Catching and inspecting errors
+  #   begin
+  #     BrainzLab::Vault.get("secret")
+  #   rescue BrainzLab::Error => e
+  #     puts e.message    # What went wrong
+  #     puts e.hint       # How to fix it
+  #     puts e.docs_url   # Where to learn more
+  #     puts e.code       # Machine-readable code
+  #   end
+  #
+  class Error < StandardError
+    # @return [String, nil] A helpful hint on how to resolve the error
+    attr_reader :hint
+
+    # @return [String, nil] URL to relevant documentation
+    attr_reader :docs_url
+
+    # @return [String, nil] Machine-readable error code for programmatic handling
+    attr_reader :code
+
+    # @return [Hash, nil] Additional context about the error
+    attr_reader :context
+
+    DOCS_BASE_URL = 'https://docs.brainzlab.io'
+
+    # Initialize a new BrainzLab error.
+    #
+    # @param message [String] The error message describing what went wrong
+    # @param hint [String, nil] A helpful hint on how to resolve the error
+    # @param docs_url [String, nil] URL to relevant documentation
+    # @param code [String, nil] Machine-readable error code
+    # @param context [Hash, nil] Additional context about the error
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil)
+      @message = message
+      @hint = hint
+      @docs_url = docs_url
+      @code = code
+      @context = context
+      super(message)
+    end
+
+    # Format the error as a detailed string with hints and documentation links.
+    #
+    # @return [String] Formatted error message
+    def to_s
+      super
+    end
+
+    # Return a detailed formatted version of the error with hints and documentation links.
+    # Use this method when you want the full structured output.
+    #
+    # @return [String] Detailed formatted error message
+    def detailed_message(highlight: false, **_kwargs)
+      # Get the base message without class name duplication
+      base_msg = @message || super
+
+      parts = ["#{self.class.name}: #{base_msg}"]
+
+      parts << "" << "Hint: #{hint}" if hint
+      parts << "Docs: #{docs_url}" if docs_url
+      parts << "Code: #{code}" if code
+
+      if context && !context.empty?
+        parts << "" << "Context:"
+        context.each do |key, value|
+          parts << "  #{key}: #{value}"
+        end
+      end
+
+      parts.join("\n")
+    end
+
+    # Inspect the error for debugging
+    #
+    # @return [String] Inspection output
+    def inspect
+      "#<#{self.class.name}: #{message}#{" (#{code})" if code}>"
+    end
+
+    # Return a hash representation of the error for logging/serialization.
+    #
+    # @return [Hash] Error details as a hash
+    def to_h
+      {
+        error_class: self.class.name,
+        message: message,
+        hint: hint,
+        docs_url: docs_url,
+        code: code,
+        context: context
+      }.compact
+    end
+
+    # Alias for to_h
+    def as_json
+      to_h
+    end
+  end
+
+  # Raised when the SDK is misconfigured or required configuration is missing.
+  #
+  # @example Missing API key
+  #   raise BrainzLab::ConfigurationError.new(
+  #     "API key is required",
+  #     hint: "Set BRAINZLAB_SECRET_KEY environment variable or configure via BrainzLab.configure",
+  #     code: "missing_api_key"
+  #   )
+  #
+  class ConfigurationError < Error
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil)
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/configuration"
+      code ||= 'configuration_error'
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context)
+    end
+  end
+
+  # Raised when authentication fails due to invalid or expired credentials.
+  #
+  # @example Invalid API key
+  #   raise BrainzLab::AuthenticationError.new(
+  #     "Invalid API key",
+  #     hint: "Check that your API key is correct and has not expired",
+  #     code: "invalid_api_key"
+  #   )
+  #
+  class AuthenticationError < Error
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil)
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/authentication"
+      code ||= 'authentication_error'
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context)
+    end
+  end
+
+  # Raised when a connection to BrainzLab services cannot be established.
+  #
+  # @example Connection timeout
+  #   raise BrainzLab::ConnectionError.new(
+  #     "Connection timed out",
+  #     hint: "Check your network connection and firewall settings",
+  #     code: "connection_timeout"
+  #   )
+  #
+  class ConnectionError < Error
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil)
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/troubleshooting#connection-issues"
+      code ||= 'connection_error'
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context)
+    end
+  end
+
+  # Raised when the rate limit for API requests has been exceeded.
+  #
+  # @example Rate limit exceeded
+  #   raise BrainzLab::RateLimitError.new(
+  #     "Rate limit exceeded",
+  #     hint: "Wait before retrying or consider upgrading your plan",
+  #     code: "rate_limit_exceeded",
+  #     context: { retry_after: 60, limit: 1000, remaining: 0 }
+  #   )
+  #
+  class RateLimitError < Error
+    # @return [Integer, nil] Seconds to wait before retrying
+    attr_reader :retry_after
+
+    # @return [Integer, nil] The rate limit ceiling
+    attr_reader :limit
+
+    # @return [Integer, nil] Remaining requests in the current window
+    attr_reader :remaining
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, retry_after: nil, limit: nil, remaining: nil)
+      @retry_after = retry_after
+      @limit = limit
+      @remaining = remaining
+
+      hint ||= retry_after ? "Wait #{retry_after} seconds before retrying" : 'Reduce request frequency or upgrade your plan'
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/rate-limits"
+      code ||= 'rate_limit_exceeded'
+
+      context ||= {}
+      context[:retry_after] = retry_after if retry_after
+      context[:limit] = limit if limit
+      context[:remaining] = remaining if remaining
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Raised when request parameters or data fail validation.
+  #
+  # @example Invalid parameter
+  #   raise BrainzLab::ValidationError.new(
+  #     "Invalid email format",
+  #     hint: "Provide a valid email address (e.g., user@example.com)",
+  #     code: "invalid_email",
+  #     context: { field: "email", value: "invalid" }
+  #   )
+  #
+  class ValidationError < Error
+    # @return [String, nil] The field that failed validation
+    attr_reader :field
+
+    # @return [Array<Hash>, nil] List of validation errors for multiple fields
+    attr_reader :errors
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, field: nil, errors: nil)
+      @field = field
+      @errors = errors
+
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/api-reference"
+      code ||= 'validation_error'
+
+      context ||= {}
+      context[:field] = field if field
+      context[:errors] = errors if errors
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Raised when a requested resource is not found.
+  #
+  # @example Resource not found
+  #   raise BrainzLab::NotFoundError.new(
+  #     "Secret 'database_url' not found",
+  #     hint: "Verify the secret name and environment",
+  #     code: "secret_not_found"
+  #   )
+  #
+  class NotFoundError < Error
+    # @return [String, nil] The type of resource that was not found
+    attr_reader :resource_type
+
+    # @return [String, nil] The identifier of the resource that was not found
+    attr_reader :resource_id
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, resource_type: nil, resource_id: nil)
+      @resource_type = resource_type
+      @resource_id = resource_id
+
+      code ||= 'not_found'
+
+      context ||= {}
+      context[:resource_type] = resource_type if resource_type
+      context[:resource_id] = resource_id if resource_id
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Raised when a server-side error occurs.
+  #
+  # @example Server error
+  #   raise BrainzLab::ServerError.new(
+  #     "Internal server error",
+  #     hint: "This is a temporary issue. Please retry your request.",
+  #     code: "internal_server_error"
+  #   )
+  #
+  class ServerError < Error
+    # @return [Integer, nil] HTTP status code from the server
+    attr_reader :status_code
+
+    # @return [String, nil] Request ID for support reference
+    attr_reader :request_id
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, status_code: nil, request_id: nil)
+      @status_code = status_code
+      @request_id = request_id
+
+      hint ||= 'This is a temporary issue. Please retry your request. If the problem persists, contact support.'
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/troubleshooting#server-errors"
+      code ||= 'server_error'
+
+      context ||= {}
+      context[:status_code] = status_code if status_code
+      context[:request_id] = request_id if request_id
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Raised when an operation times out.
+  #
+  # @example Request timeout
+  #   raise BrainzLab::TimeoutError.new(
+  #     "Request timed out after 30 seconds",
+  #     hint: "The operation took too long. Try again or increase timeout settings.",
+  #     code: "request_timeout"
+  #   )
+  #
+  class TimeoutError < Error
+    # @return [Integer, nil] Timeout duration in seconds
+    attr_reader :timeout_seconds
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, timeout_seconds: nil)
+      @timeout_seconds = timeout_seconds
+
+      hint ||= 'The operation took too long. Try again or increase timeout settings.'
+      docs_url ||= "#{DOCS_BASE_URL}/sdk/ruby/configuration#timeouts"
+      code ||= 'timeout'
+
+      context ||= {}
+      context[:timeout_seconds] = timeout_seconds if timeout_seconds
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Raised when a service is temporarily unavailable.
+  #
+  # @example Service unavailable
+  #   raise BrainzLab::ServiceUnavailableError.new(
+  #     "Vault service is currently unavailable",
+  #     hint: "The service is undergoing maintenance. Please try again later.",
+  #     code: "vault_unavailable"
+  #   )
+  #
+  class ServiceUnavailableError < Error
+    # @return [String, nil] The name of the unavailable service
+    attr_reader :service_name
+
+    def initialize(message = nil, hint: nil, docs_url: nil, code: nil, context: nil, service_name: nil)
+      @service_name = service_name
+
+      hint ||= 'The service is temporarily unavailable. Please try again later.'
+      docs_url ||= "#{DOCS_BASE_URL}/status"
+      code ||= 'service_unavailable'
+
+      context ||= {}
+      context[:service_name] = service_name if service_name
+
+      super(message, hint: hint, docs_url: docs_url, code: code, context: context.empty? ? nil : context)
+    end
+  end
+
+  # Helper module for wrapping low-level errors into structured BrainzLab errors
+  module ErrorHandler
+    module_function
+
+    # Wrap a standard error into a structured BrainzLab error.
+    #
+    # @param error [StandardError] The original error
+    # @param service [String] The service name (e.g., 'Vault', 'Cortex')
+    # @param operation [String] The operation being performed
+    # @return [BrainzLab::Error] A structured BrainzLab error
+    def wrap(error, service:, operation:)
+      case error
+      when Net::OpenTimeout, Net::ReadTimeout, Timeout::Error
+        TimeoutError.new(
+          "#{service} #{operation} timed out: #{error.message}",
+          hint: 'Check your network connection or increase timeout settings.',
+          code: "#{service.downcase}_timeout",
+          context: { service: service, operation: operation }
+        )
+      when Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::ENETUNREACH
+        ConnectionError.new(
+          "Unable to connect to #{service}: #{error.message}",
+          hint: 'Check that the service is running and accessible.',
+          code: "#{service.downcase}_connection_failed",
+          context: { service: service, operation: operation }
+        )
+      when SocketError
+        ConnectionError.new(
+          "DNS resolution failed for #{service}: #{error.message}",
+          hint: 'Check your network connection and DNS settings.',
+          code: "#{service.downcase}_dns_error",
+          context: { service: service, operation: operation }
+        )
+      when JSON::ParserError
+        ServerError.new(
+          "Invalid response from #{service}: #{error.message}",
+          hint: 'The server returned an unexpected response format.',
+          code: "#{service.downcase}_invalid_response",
+          context: { service: service, operation: operation }
+        )
+      when OpenSSL::SSL::SSLError
+        ConnectionError.new(
+          "SSL error connecting to #{service}: #{error.message}",
+          hint: 'Check SSL certificates and ensure the connection is secure.',
+          code: "#{service.downcase}_ssl_error",
+          context: { service: service, operation: operation }
+        )
+      else
+        Error.new(
+          "#{service} #{operation} failed: #{error.message}",
+          hint: 'An unexpected error occurred. Check the logs for more details.',
+          code: "#{service.downcase}_error",
+          context: { service: service, operation: operation, original_error: error.class.name }
+        )
+      end
+    end
+
+    # Convert an HTTP response to a structured error.
+    #
+    # @param response [Net::HTTPResponse] The HTTP response
+    # @param service [String] The service name
+    # @param operation [String] The operation being performed
+    # @return [BrainzLab::Error] A structured BrainzLab error
+    def from_response(response, service:, operation:)
+      status_code = response.code.to_i
+      body = parse_response_body(response)
+      message = body[:message] || body[:error] || "HTTP #{status_code}"
+      request_id = response['X-Request-Id']
+
+      case status_code
+      when 400
+        ValidationError.new(
+          message,
+          hint: body[:hint] || 'Check the request parameters.',
+          code: body[:code] || 'bad_request',
+          context: { service: service, operation: operation, status_code: status_code }
+        )
+      when 401
+        AuthenticationError.new(
+          message,
+          hint: body[:hint] || "Verify your #{service} API key is correct and active.",
+          code: body[:code] || 'unauthorized',
+          context: { service: service, operation: operation }
+        )
+      when 403
+        AuthenticationError.new(
+          message,
+          hint: body[:hint] || 'Your API key does not have permission for this operation.',
+          code: body[:code] || 'forbidden',
+          context: { service: service, operation: operation }
+        )
+      when 404
+        NotFoundError.new(
+          message,
+          hint: body[:hint] || 'The requested resource does not exist.',
+          code: body[:code] || 'not_found',
+          context: { service: service, operation: operation }
+        )
+      when 422
+        ValidationError.new(
+          message,
+          hint: body[:hint] || 'The request was well-formed but contained invalid data.',
+          code: body[:code] || 'unprocessable_entity',
+          errors: body[:errors],
+          context: { service: service, operation: operation, status_code: status_code }
+        )
+      when 429
+        RateLimitError.new(
+          message,
+          retry_after: response['Retry-After']&.to_i,
+          limit: response['X-RateLimit-Limit']&.to_i,
+          remaining: response['X-RateLimit-Remaining']&.to_i,
+          context: { service: service, operation: operation }
+        )
+      when 500..599
+        ServerError.new(
+          message,
+          hint: body[:hint] || 'A server error occurred. Please retry your request.',
+          code: body[:code] || "server_error_#{status_code}",
+          status_code: status_code,
+          request_id: request_id,
+          context: { service: service, operation: operation }
+        )
+      else
+        Error.new(
+          message,
+          hint: body[:hint],
+          code: body[:code] || "http_#{status_code}",
+          context: { service: service, operation: operation, status_code: status_code }
+        )
+      end
+    end
+
+    def parse_response_body(response)
+      JSON.parse(response.body, symbolize_names: true)
+    rescue JSON::ParserError, TypeError
+      {}
+    end
+  end
+end

data/lib/brainzlab/flux/buffer.rb

@@ -76,7 +76,7 @@ module BrainzLab
 
         @client.send_batch(events: events, metrics: metrics)
       rescue StandardError => e
-        BrainzLab.debug("[Flux] Batch send failed: #{e.message}")
+        BrainzLab.debug_log("[Flux] Batch send failed: #{e.message}")
       end
 
       def start_flush_thread
@@ -86,7 +86,7 @@ module BrainzLab
             begin
               flush! if size.positive?
             rescue StandardError => e
-              BrainzLab.debug("[Flux] Flush thread error: #{e.message}")
+              BrainzLab.debug_log("[Flux] Flush thread error: #{e.message}")
             end
           end
         end