brainzlab 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97098a98bb87f20519522678294b7872e1ff75c9a340dc85c0681bce794bdc27
-  data.tar.gz: 8842b97cc1d4f27c772df7463c2bca85b13b4d0cf91a0d2fd46b00f900e813f5
+  metadata.gz: 85a5cf3a64e256a569be39f7caa1ec6268755616ac6037db51f1543ee74dd50c
+  data.tar.gz: '09c531bb0793d26db1f62faf41f9ead294130a7036f6e5f6ab270fd8c6c46040'
 SHA512:
-  metadata.gz: 1f940b97715f5b5592a834fbedcf409888d31f8421c35ad6435c71bde91068d351270092e816b26f6a1d97bc274bcb457bc612a3599b8bba143478be23564d0a
-  data.tar.gz: ba2d7b3de3190e84ac3301173a0c2f4f6db3acc7bcbec5c84d73844cbb6f8b745db5d9a5c8c7064a4f6a2bb8a556b998df2d4ae1dfad044ecd9e9c46542ccfe0
+  metadata.gz: 28c2f10fc4457d4f2f34c5bcf4d63c14a062d4fcd8437b13cbcebc1a062976361b2014f5567e0fff82682a054fa83363f7e955a23d3d59ae285a9f06500c79e6
+  data.tar.gz: 5d130bf7242d57c3149803649262995daf298483c406002ab99e01495efb14df7a6874b8eb485daa90c79da8903ad37f6516ba0ca7e2c8930ff069a1b536a206

data/README.md

@@ -47,12 +47,21 @@ bundle config set --global rubygems.pkg.github.com USERNAME:TOKEN
 
 ## Quick Start
 
+### Get Your API Key
+
+1. Sign up at [platform.brainzlab.ai](https://platform.brainzlab.ai)
+2. Create or select a project
+3. Copy your API key (`sk_live_xxx` or `sk_test_xxx`)
+4. Set it as `BRAINZLAB_SECRET_KEY` environment variable
+
+**One key, all products**: Your Platform API key works across Recall, Reflex, Pulse, and all BrainzLab products. No separate keys needed.
+
 ### Configuration
 
 ```ruby
 # config/initializers/brainzlab.rb
 BrainzLab.configure do |config|
-  # Authentication (required)
+  # Authentication (required) - Your Platform API key
   config.secret_key = ENV['BRAINZLAB_SECRET_KEY']
 
   # Environment
@@ -289,6 +298,8 @@ end
 | `BRAINZLAB_SERVICE` | Service name |
 | `BRAINZLAB_APP_NAME` | App name for auto-provisioning |
 | `BRAINZLAB_DEBUG` | Enable debug logging (`true`/`false`) |
+| `BRAINZLAB_MODE` | SDK mode: `production` (default) or `development` (offline) |
+| `BRAINZLAB_DEV_DB_PATH` | SQLite database path for development mode |
 | `RECALL_URL` | Custom Recall endpoint |
 | `REFLEX_URL` | Custom Reflex endpoint |
 | `PULSE_URL` | Custom Pulse endpoint |
@@ -303,12 +314,217 @@ config.scrub_fields = [:password, :password_confirmation, :token, :api_key, :sec
 
 ## Debug Mode
 
-Enable debug mode to see SDK activity:
+Debug mode provides detailed visibility into SDK operations, including all API requests and responses with timing information. This is invaluable for troubleshooting integration issues.
+
+### Enabling Debug Mode
+
+```ruby
+# In your initializer
+BrainzLab.configure do |config|
+  config.debug = true
+end
+
+# Or via environment variable
+# BRAINZLAB_DEBUG=true
+```
+
+### Debug Output Format
+
+When debug mode is enabled, you'll see colorized output in your terminal:
+
+```
+[BrainzLab] 12:34:56 -> Recall POST /api/v1/logs (count: 5)
+[BrainzLab] 12:34:56 <- Recall 200 OK (45ms)
+
+[BrainzLab] 12:34:57 -> Reflex POST /api/v1/errors (exception: RuntimeError)
+[BrainzLab] 12:34:57 <- Reflex 201 Created (23ms)
+
+[BrainzLab] 12:34:58 -> Pulse POST /api/v1/traces (name: GET /users)
+[BrainzLab] 12:34:58 <- Pulse 200 OK (18ms)
+```
+
+The output includes:
+- Timestamp for each operation
+- Service name (Recall, Reflex, Pulse, etc.)
+- Request method and path
+- Payload summary (log count, exception type, etc.)
+- Response status code and message
+- Request duration with color coding (green < 100ms, yellow < 1s, red > 1s)
+
+### Custom Logger
+
+You can provide your own logger to capture debug output:
+
+```ruby
+BrainzLab.configure do |config|
+  config.debug = true
+  config.logger = Rails.logger
+  # Or any Logger-compatible object
+  config.logger = Logger.new('log/brainzlab.log')
+end
+```
+
+### Debug Callbacks
+
+For advanced debugging and monitoring, you can hook into SDK operations:
+
+```ruby
+BrainzLab.configure do |config|
+  # Called before each API request
+  config.on_send = ->(service, method, path, payload) {
+    Rails.logger.debug "[BrainzLab] Sending to #{service}: #{method} #{path}"
+
+    # You can use this to:
+    # - Log all outgoing requests
+    # - Send metrics to your monitoring system
+    # - Add custom tracing
+  }
+
+  # Called when an SDK error occurs
+  config.on_error = ->(error, context) {
+    Rails.logger.error "[BrainzLab] Error in #{context[:service]}: #{error.message}"
+
+    # You can use this to:
+    # - Alert on SDK failures
+    # - Track error rates
+    # - Fallback to alternative logging
+
+    # Note: This is for SDK errors, not application errors
+    # Application errors are sent to Reflex as normal
+  }
+end
+```
+
+### Programmatic Debug Logging
+
+You can also use the Debug module directly:
+
+```ruby
+# Log a debug message (only outputs when debug=true)
+BrainzLab::Debug.log("Custom message", level: :info)
+BrainzLab::Debug.log("Something went wrong", level: :error, error_code: 500)
+
+# Measure operation timing
+BrainzLab::Debug.measure(:custom, "expensive_operation") do
+  # Your code here
+end
+
+# Check if debug mode is enabled
+if BrainzLab::Debug.enabled?
+  # Perform additional debug operations
+end
+```
+
+### Debug Output Levels
+
+Debug messages are color-coded by level:
+- **DEBUG** (gray) - Verbose internal operations
+- **INFO** (cyan) - Normal operations
+- **WARN** (yellow) - Potential issues
+- **ERROR** (red) - Failed operations
+
+## Development Mode
+
+Development mode allows you to use the SDK without a BrainzLab server connection. Events are logged to stdout in a readable format and stored locally in a SQLite database.
+
+### Configuration
+
+```ruby
+# config/initializers/brainzlab.rb
+BrainzLab.configure do |config|
+  # Enable development mode (works offline)
+  config.mode = :development
+
+  # Optional: customize the SQLite database path (default: tmp/brainzlab.sqlite3)
+  config.development_db_path = 'tmp/brainzlab_dev.sqlite3'
+
+  # Other settings still apply
+  config.environment = Rails.env
+  config.service = 'my-app'
+end
+```
+
+Or use the environment variable:
+
+```bash
+export BRAINZLAB_MODE=development
+```
+
+### Features
+
+In development mode:
+
+- **No server connection required** - Works completely offline
+- **Stdout logging** - All events are pretty-printed to the console with colors
+- **Local storage** - Events are stored in SQLite at `tmp/brainzlab.sqlite3`
+- **Queryable** - Use `BrainzLab.development_events` to query stored events
+
+### Querying Events
 
 ```ruby
-config.debug = true
-# Or set BRAINZLAB_DEBUG=true
+# Get all events
+events = BrainzLab.development_events
+
+# Filter by service
+logs = BrainzLab.development_events(service: :recall)
+errors = BrainzLab.development_events(service: :reflex)
+traces = BrainzLab.development_events(service: :pulse)
+
+# Filter by event type
+BrainzLab.development_events(event_type: 'log')
+BrainzLab.development_events(event_type: 'error')
+BrainzLab.development_events(event_type: 'trace')
+
+# Filter by time
+BrainzLab.development_events(since: 1.hour.ago)
+
+# Limit results
+BrainzLab.development_events(limit: 10)
+
+# Combine filters
+BrainzLab.development_events(
+  service: :recall,
+  since: 30.minutes.ago,
+  limit: 50
+)
+
+# Get stats by service
+BrainzLab.development_stats
+# => { recall: 42, reflex: 3, pulse: 15 }
+
+# Clear all stored events
+BrainzLab.clear_development_events!
+```
+
+### Console Output
+
+In development mode, events are pretty-printed to stdout:
+
 ```
+[14:32:15.123] [RECALL] log [INFO] User signed up
+  user_id: 123
+  data: {email: "user@example.com"}
+
+[14:32:16.456] [REFLEX] error RuntimeError: Something went wrong
+  error_class: "RuntimeError"
+  environment: "development"
+  request_id: "abc-123"
+
+[14:32:17.789] [PULSE] trace GET /users (45.2ms)
+  request_method: "GET"
+  request_path: "/users"
+  status: 200
+  db_ms: 12.3
+```
+
+### Use Cases
+
+Development mode is useful for:
+
+- **Local development** without setting up a BrainzLab account
+- **Testing** SDK integration in CI/CD pipelines
+- **Debugging** to inspect exactly what events would be sent
+- **Offline development** when working without internet access
 
 ## Self-Hosted
 

data/lib/brainzlab/beacon/client.rb

@@ -200,7 +200,27 @@ module BrainzLab
       end
 
       def log_error(operation, error)
-        BrainzLab.debug_log("[Beacon::Client] #{operation} failed: #{error.message}")
+        structured_error = ErrorHandler.wrap(error, service: 'Beacon', operation: operation)
+        BrainzLab.debug_log("[Beacon::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Beacon', operation: operation })
+        end
+      end
+
+      def handle_response_error(response, operation)
+        return if response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPCreated) || response.is_a?(Net::HTTPNoContent)
+
+        structured_error = ErrorHandler.from_response(response, service: 'Beacon', operation: operation)
+        BrainzLab.debug_log("[Beacon::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Beacon', operation: operation })
+        end
+
+        structured_error
       end
     end
   end

data/lib/brainzlab/configuration.rb

@@ -7,6 +7,9 @@ module BrainzLab
     # recall_min_level has a custom setter with validation
     attr_reader :recall_min_level
 
+    # mode has a custom setter with validation
+    attr_reader :mode
+
     attr_accessor :secret_key,
                   :environment,
                   :service,
@@ -106,6 +109,8 @@ module BrainzLab
                   :synapse_auto_provision,
                   :scrub_fields,
                   :logger,
+                  :on_error,
+                  :on_send,
                   :instrument_http,
                   :instrument_active_record,
                   :instrument_redis,
@@ -150,7 +155,9 @@ module BrainzLab
                   :devtools_asset_path,
                   :devtools_panel_position,
                   :devtools_expand_by_default,
-                  :rails_instrumentation_handled_externally
+                  :rails_instrumentation_handled_externally,
+                  :development_db_path,
+                  :development_log_output
 
     # Services that should not track themselves to avoid circular dependencies
     SELF_TRACKING_SERVICES = {
@@ -180,6 +187,13 @@ module BrainzLab
       # Debug mode - enables verbose logging
       @debug = ENV['BRAINZLAB_DEBUG'] == 'true'
 
+      # SDK mode - :production (default) or :development (offline, local storage)
+      @mode = ENV['BRAINZLAB_MODE']&.to_sym || :production
+
+      # Development mode settings
+      @development_db_path = ENV['BRAINZLAB_DEV_DB_PATH'] || 'tmp/brainzlab.sqlite3'
+      @development_log_output = $stdout
+
       # Disable self-tracking - prevents services from tracking to themselves
       # e.g., Recall won't log to itself, Reflex won't track errors to itself
       @disable_self_tracking = ENV.fetch('BRAINZLAB_DISABLE_SELF_TRACKING', 'true') == 'true'
@@ -306,6 +320,12 @@ module BrainzLab
       # Internal logger for debugging SDK issues
       @logger = nil
 
+      # Debug callbacks
+      # Called when an SDK error occurs (lambda/proc receiving error object and context hash)
+      @on_error = nil
+      # Called before each API request (lambda/proc receiving service, method, path, and payload)
+      @on_send = nil
+
       # Instrumentation
       @instrument_http = true # Enable HTTP client instrumentation (Net::HTTP, Faraday, HTTParty)
       @instrument_active_record = true # AR breadcrumbs for Reflex
@@ -363,11 +383,40 @@ module BrainzLab
 
     def recall_min_level=(level)
       level = level.to_sym
-      raise ArgumentError, "Invalid level: #{level}" unless LEVELS.include?(level)
+      unless LEVELS.include?(level)
+        raise ValidationError.new(
+          "Invalid log level: #{level}",
+          hint: "Valid log levels are: #{LEVELS.join(', ')}",
+          code: 'invalid_log_level',
+          field: 'recall_min_level',
+          context: { provided: level, valid_values: LEVELS }
+        )
+      end
 
       @recall_min_level = level
     end
 
+    MODES = %i[production development].freeze
+
+    def mode=(mode)
+      mode = mode.to_sym
+      unless MODES.include?(mode)
+        raise ValidationError.new(
+          "Invalid mode: #{mode}",
+          hint: "Valid modes are: #{MODES.join(', ')}. Use :development for offline mode with local storage.",
+          code: 'invalid_mode',
+          field: 'mode',
+          context: { provided: mode, valid_values: MODES }
+        )
+      end
+
+      @mode = mode
+    end
+
+    def development_mode?
+      @mode == :development
+    end
+
     def level_enabled?(level)
       LEVELS.index(level.to_sym) >= LEVELS.index(@recall_min_level)
     end

data/lib/brainzlab/cortex/client.rb

@@ -132,7 +132,27 @@ module BrainzLab
       end
 
       def log_error(operation, error)
-        BrainzLab.debug_log("[Cortex::Client] #{operation} failed: #{error.message}")
+        structured_error = ErrorHandler.wrap(error, service: 'Cortex', operation: operation)
+        BrainzLab.debug_log("[Cortex::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Cortex', operation: operation })
+        end
+      end
+
+      def handle_response_error(response, operation)
+        return if response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPCreated) || response.is_a?(Net::HTTPNoContent)
+
+        structured_error = ErrorHandler.from_response(response, service: 'Cortex', operation: operation)
+        BrainzLab.debug_log("[Cortex::Client] #{operation} failed: #{structured_error.message}")
+
+        # Call on_error callback if configured
+        if @config.on_error
+          @config.on_error.call(structured_error, { service: 'Cortex', operation: operation })
+        end
+
+        structured_error
       end
     end
   end