klime 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 330590153e5a8620ea195eeac0af41c0eacbc5d4619f3cf22c05192fcaa071ee
-  data.tar.gz: 54cf4a7e4afb4680dcd7386c056058184ac5fb0f46132f980074a115c1f6ac47
+  metadata.gz: 1b96d506df543d39a095e29ded2bd3a55060d49669b579da2bb14a19cc1ada4f
+  data.tar.gz: c8df6be4c7ec823f7e9a3576a56c007ed0317da16620a43a7f8ed5e8d9a542d1
 SHA512:
-  metadata.gz: b89311ba42ebcc5cf409fbd331e2f77dfcf72455dc2c832a34c9392aaabe216949adedb90f2999cb4a88ae3ede702452db82074694db79a87b33dbe4c5c01a9d
-  data.tar.gz: 448ef16a67fc2ce3cf81766bce565cffc60a2ca5cb91dab198cd8a81ca825b643ec5b9c044605e436f56cdbb98ff88a4f9763b507bda1f929b3b05ca101a198a
+  metadata.gz: 7134190cf34f38279d6af0207f8646e485237df9488bc8b324de4a00881dcf56b4c111a976a14b70fa2949efdbb0c044d8821f83daebee754410640a0bfbb44d
+  data.tar.gz: 2347c49df142c0b4fc4334baf6dea7ab25faffd575fb1a9ff51586853bddb3638dfe3f1e3b8435bb2d2aa231e8bfefbea43b39fcba980da0f6a4b96d882809b4

data/README.md

@@ -56,6 +56,86 @@ client.group('org_456', user_id: 'user_123')
 client.shutdown
 ```
 
+## Installation Prompt
+
+Copy and paste this prompt into Cursor, Copilot, or your favorite AI editor to integrate Klime:
+
+```
+Integrate Klime for customer analytics. Klime tracks user activity to identify which customers are healthy vs at risk of churning.
+
+ANALYTICS MODES (determine which applies):
+- Companies & Teams: Your customers are companies with multiple team members (SaaS, enterprise tools)
+  → Use identify() + group() + track()
+- Individual Customers: Your customers are individuals with private accounts (consumer apps, creator tools)
+  → Use identify() + track() only (no group() needed)
+
+KEY CONCEPTS:
+- Every track() call requires either user_id OR group_id (no anonymous events)
+- Use group_id alone for org-level events (webhooks, cron jobs, system metrics)
+- group() links a user to a company AND sets company traits (only for Companies & Teams mode)
+- Order doesn't matter - events before identify/group still get attributed correctly
+
+BEST PRACTICES:
+- Initialize client ONCE at app startup (initializer or singleton)
+- Store write key in KLIME_WRITE_KEY environment variable
+- Call shutdown on process exit to flush remaining events (auto-registered via at_exit)
+
+Add to Gemfile: gem 'klime'
+Then run: bundle install
+
+Or install directly: gem install klime
+
+require 'klime'
+
+client = Klime::Client.new(write_key: ENV['KLIME_WRITE_KEY'])
+
+# Identify users at signup/login:
+client.identify('usr_abc123', { email: 'jane@acme.com', name: 'Jane Smith' })
+
+# Track key activities:
+client.track('Report Generated', { report_type: 'revenue' }, user_id: 'usr_abc123')
+client.track('Feature Used', { feature: 'export', format: 'csv' }, user_id: 'usr_abc123')
+client.track('Teammate Invited', { role: 'member' }, user_id: 'usr_abc123')
+
+# If Companies & Teams mode: link user to their company and set company traits
+client.group('org_456', { name: 'Acme Inc', plan: 'enterprise' }, user_id: 'usr_abc123')
+
+INTEGRATION WORKFLOW:
+
+Phase 1: Discover
+Explore the codebase to understand:
+1. What framework is used? (Rails, Sinatra, Hanami, Rack, etc.)
+2. Where is user identity available? (e.g., current_user.id, @current_user.id, session[:user_id], warden.user)
+3. Is this Companies & Teams or Individual Customers?
+   - Look for: organization, workspace, tenant, team, account models → Companies & Teams (use group())
+   - No company/org concept, just individual users → Individual Customers (skip group())
+4. Where do core user actions happen? (controllers, service objects, jobs, callbacks)
+5. Is there existing analytics? (search: segment, posthog, mixpanel, amplitude, track)
+Match your integration style to the framework's conventions.
+
+Phase 2: Instrument
+Add these calls using idiomatic patterns for the framework:
+- Initialize client once (Rails: config/initializers/klime.rb, Sinatra: before app.run, Rack: middleware)
+- identify() in auth/login success handler
+- group() when user-org association is established (Companies & Teams mode only)
+- track() for key user actions (see below)
+
+WHAT TO TRACK:
+Active engagement (primary): feature usage, resource creation, collaboration, completing flows
+Session signals (secondary): login/session start, dashboard access - distinguishes "low usage" from "churned"
+Do NOT track: every request, health checks, before_action filters, background jobs
+
+Phase 3: Verify
+Confirm: client initialized, shutdown handled, identify/group/track calls added
+
+Phase 4: Summarize
+Report what you added:
+- Files modified and what was added to each
+- Events being tracked (list event names and what triggers them)
+- How user_id is obtained (and group_id if Companies & Teams mode)
+- Any assumptions made or questions
+```
+
 ## API Reference
 
 ### Constructor
@@ -69,32 +149,37 @@ Klime::Client.new(
   max_queue_size: nil,     # Optional: Max queued events (default: 1000)
   retry_max_attempts: nil, # Optional: Max retry attempts (default: 5)
   retry_initial_delay: nil, # Optional: Initial retry delay in ms (default: 1000)
-  flush_on_shutdown: nil   # Optional: Auto-flush on exit (default: true)
+  flush_on_shutdown: nil,  # Optional: Auto-flush on exit (default: true)
+  on_error: nil,           # Optional: Callback for batch failures
+  on_success: nil          # Optional: Callback for successful sends
 )
 ```
 
 ### Methods
 
-#### `track(event_name, properties = nil, user_id: nil, group_id: nil, ip: nil)`
+#### `track(event_name, properties = nil, user_id: nil, group_id: nil)`
 
-Track a user event. A `user_id` is required for events to be useful in Klime.
+Track an event. Events can be attributed in two ways:
+- **User events**: Provide `user_id` to track user activity (most common)
+- **Group events**: Provide `group_id` without `user_id` for organization-level events
 
 ```ruby
+# User event (most common)
 client.track('Button Clicked', {
   button_name: 'Sign up',
   plan: 'pro'
 }, user_id: 'user_123')
 
-# With IP address (for geolocation)
-client.track('Button Clicked', {
-  button_name: 'Sign up',
-  plan: 'pro'
-}, user_id: 'user_123', ip: '192.168.1.1')
+# Group event (for webhooks, cron jobs, system events)
+client.track('Events Received', {
+  count: 100,
+  source: 'webhook'
+}, group_id: 'org_456')
 ```
 
-> **Advanced**: The `group_id` parameter is available for multi-tenant scenarios where a user belongs to multiple organizations and you need to specify which organization context the event occurred in.
+> **Note**: The `group_id` parameter can also be combined with `user_id` for multi-tenant scenarios where you need to specify which organization context a user event occurred in.
 
-#### `identify(user_id, traits = nil, ip: nil)`
+#### `identify(user_id, traits = nil)`
 
 Identify a user with traits.
 
@@ -102,10 +187,10 @@ Identify a user with traits.
 client.identify('user_123', {
   email: 'user@example.com',
   name: 'Stefan'
-}, ip: '192.168.1.1')
+})
 ```
 
-#### `group(group_id, traits = nil, user_id: nil, ip: nil)`
+#### `group(group_id, traits = nil, user_id: nil)`
 
 Associate a user with a group and/or set group traits.
 
@@ -147,9 +232,33 @@ client.shutdown
 - **Automatic Batching**: Events are automatically batched and sent every 2 seconds or when the batch size reaches 20 events
 - **Automatic Retries**: Failed requests are automatically retried with exponential backoff
 - **Thread-Safe**: Safe to use from multiple threads
+- **Fork-Safe**: Automatically detects Puma/Unicorn forks and restarts the worker thread
 - **Process Exit Handling**: Automatically flushes events on process exit (via `at_exit`)
 - **Zero Dependencies**: Uses only Ruby standard library
 
+## Performance
+
+When you call `track()`, `identify()`, or `group()`, the SDK:
+
+1. Adds the event to an in-memory queue (microseconds)
+2. Returns immediately without waiting for network I/O
+
+Events are sent to Klime's servers in a background thread. This means:
+
+- **No network blocking**: HTTP requests happen asynchronously in a background thread
+- **No latency impact**: Tracking calls add < 1ms to your request handling time
+- **Automatic batching**: Events are queued and sent in batches (default: every 2 seconds or 20 events)
+
+```ruby
+# This returns immediately - no HTTP request is made here
+client.track('Button Clicked', { button: 'signup' }, user_id: 'user_123')
+
+# Your code continues without waiting
+render json: { success: true }
+```
+
+The only blocking operation is `flush()`, which waits for all queued events to be sent. This is typically only called during graceful shutdown.
+
 ## Configuration
 
 ### Default Values
@@ -161,6 +270,28 @@ client.shutdown
 - `retry_initial_delay`: 1000ms
 - `flush_on_shutdown`: true
 
+### Logging
+
+```ruby
+Klime.configure do |config|
+  config.logger = Rails.logger
+end
+```
+
+### Callbacks
+
+```ruby
+Klime.configure do |config|
+  config.on_error = Proc.new { |error, batch|
+    Sentry.capture_exception(error)
+  }
+
+  config.on_success = Proc.new { |response|
+    Rails.logger.info "Sent #{response.accepted} events"
+  }
+end
+```
+
 ## Error Handling
 
 The SDK automatically handles:
@@ -169,6 +300,8 @@ The SDK automatically handles:
 - **Permanent errors** (400, 401): Logs error and drops event
 - **Rate limiting**: Respects `Retry-After` header
 
+For synchronous operations, use bang methods (`track!`, `identify!`, `group!`) which raise `Klime::SendError` on failure.
+
 ## Size Limits
 
 - Maximum event size: 200KB
@@ -183,12 +316,12 @@ Events exceeding these limits are rejected and logged.
 # config/initializers/klime.rb
 require 'klime'
 
-KLIME = Klime::Client.new(
-  write_key: ENV['KLIME_WRITE_KEY']
-)
+Klime.configure do |config|
+  config.logger = Rails.logger
+end
 
-# Ensure graceful shutdown
-at_exit { KLIME.shutdown }
+Klime.client = Klime::Client.new(write_key: ENV['KLIME_WRITE_KEY'])
+KLIME = Klime.client
 ```
 
 ```ruby
@@ -197,13 +330,21 @@ class ButtonsController < ApplicationController
   def click
     KLIME.track('Button Clicked', {
       button_name: params[:button_name]
-    }, user_id: current_user&.id&.to_s, ip: request.remote_ip)
+    }, user_id: current_user&.id&.to_s)
 
     render json: { success: true }
   end
 end
 ```
 
+For Puma with multiple workers, add to `config/puma.rb`:
+
+```ruby
+on_worker_boot do
+  Klime.restart!
+end
+```
+
 ## Sinatra Example
 
 ```ruby
@@ -217,7 +358,7 @@ post '/api/button-clicked' do
 
   client.track('Button Clicked', {
     button_name: data['buttonName']
-  }, user_id: data['userId'], ip: request.ip)
+  }, user_id: data['userId'])
 
   { success: true }.to_json
 end
@@ -226,35 +367,6 @@ end
 at_exit { client.shutdown }
 ```
 
-## Rack Middleware Example
-
-```ruby
-# lib/klime_middleware.rb
-require 'klime'
-
-class KlimeMiddleware
-  def initialize(app, write_key:)
-    @app = app
-    @client = Klime::Client.new(write_key: write_key)
-  end
-
-  def call(env)
-    status, headers, response = @app.call(env)
-
-    # Track page views for authenticated users
-    user_id = env['rack.session']&.dig('user_id')
-    if user_id && env['REQUEST_METHOD'] == 'GET' && status == 200
-      @client.track('Page View', {
-        path: env['PATH_INFO'],
-        method: env['REQUEST_METHOD']
-      }, user_id: user_id, ip: env['REMOTE_ADDR'])
-    end
-
-    [status, headers, response]
-  end
-end
-```
-
 ## Requirements
 
 - Ruby 2.6 or higher

data/lib/klime/client.rb

@@ -10,9 +10,14 @@ module Klime
   #
   # @example Basic usage
   #   client = Klime::Client.new(write_key: 'your-write-key')
-  #   client.track('Button Clicked', { button_name: 'Sign up' })
+  #   client.track('Button Clicked', { button_name: 'Sign up' }, user_id: 'user_123')
   #   client.shutdown
+  #
+  # @example Synchronous usage for debugging
+  #   client.track!('Button Clicked', { button_name: 'Sign up' }, user_id: 'user_123')
   class Client
+    include Logging
+
     DEFAULT_ENDPOINT = "https://i.klime.com"
     DEFAULT_FLUSH_INTERVAL = 2000 # milliseconds
     DEFAULT_MAX_BATCH_SIZE = 20
@@ -33,6 +38,8 @@ module Klime
     # @param retry_max_attempts [Integer] Maximum retry attempts (default: 5)
     # @param retry_initial_delay [Integer] Initial retry delay in milliseconds (default: 1000)
     # @param flush_on_shutdown [Boolean] Auto-flush on exit (default: true)
+    # @param on_error [Proc] Callback for batch send failures (overrides global config)
+    # @param on_success [Proc] Callback for successful batch sends (overrides global config)
     def initialize(
       write_key:,
       endpoint: nil,
@@ -41,7 +48,9 @@ module Klime
       max_queue_size: nil,
       retry_max_attempts: nil,
       retry_initial_delay: nil,
-      flush_on_shutdown: nil
+      flush_on_shutdown: nil,
+      on_error: nil,
+      on_success: nil
     )
       raise ConfigurationError, "write_key is required" if write_key.nil? || write_key.empty?
 
@@ -54,32 +63,33 @@ module Klime
       @retry_initial_delay = retry_initial_delay || DEFAULT_RETRY_INITIAL_DELAY
       @flush_on_shutdown = flush_on_shutdown.nil? ? true : flush_on_shutdown
 
+      # Callbacks - client-level overrides global config
+      @on_error = on_error
+      @on_success = on_success
+
       @queue = Queue.new
-      @mutex = Mutex.new
+      @worker_mutex = Mutex.new
+      @worker_thread = nil
+      @pid = Process.pid
       @shutdown = false
-      @flush_in_progress = false
-      @flush_thread = nil
+
+      logger.debug "Client initialized (endpoint: #{@endpoint}, flush_interval: #{@flush_interval}ms, pid: #{@pid})"
 
       setup_shutdown_hook if @flush_on_shutdown
-      schedule_flush
     end
 
-    # Track a user event
+    # Track a user event (async)
     #
     # @param event_name [String] Name of the event
     # @param properties [Hash] Event properties (optional)
     # @param user_id [String] User ID (optional)
     # @param group_id [String] Group ID (optional)
-    # @param ip [String] IP address (optional)
-    # @return [void]
-    #
-    # @example Simple usage
-    #   client.track('Button Clicked', { button_name: 'Sign up' })
+    # @return [self] Returns self for method chaining
     #
-    # @example With user context
-    #   client.track('Button Clicked', { button_name: 'Sign up' }, user_id: 'user_123', group_id: 'org_456')
-    def track(event_name, properties = nil, user_id: nil, group_id: nil, ip: nil)
-      return if @shutdown
+    # @example
+    #   client.track('Button Clicked', { button_name: 'Sign up' }, user_id: 'user_123')
+    def track(event_name, properties = nil, user_id: nil, group_id: nil)
+      return self if @shutdown
 
       event = Event.new(
         type: EventType::TRACK,
@@ -87,80 +97,141 @@ module Klime
         properties: properties || {},
         user_id: user_id,
         group_id: group_id,
-        context: build_context(ip)
+        context: build_context
       )
 
       enqueue(event)
+      self
+    end
+
+    # Track a user event (sync) - blocks until sent, raises on error
+    #
+    # @param event_name [String] Name of the event
+    # @param properties [Hash] Event properties (optional)
+    # @param user_id [String] User ID (optional)
+    # @param group_id [String] Group ID (optional)
+    # @return [BatchResponse] The response from the server
+    # @raise [SendError] If the event fails to send
+    #
+    # @example
+    #   client.track!('Button Clicked', { button_name: 'Sign up' }, user_id: 'user_123')
+    def track!(event_name, properties = nil, user_id: nil, group_id: nil)
+      raise SendError.new("Client is shutdown") if @shutdown
+
+      event = Event.new(
+        type: EventType::TRACK,
+        event: event_name,
+        properties: properties || {},
+        user_id: user_id,
+        group_id: group_id,
+        context: build_context
+      )
+
+      send_sync([event])
     end
 
-    # Identify a user with traits
+    # Identify a user with traits (async)
     #
     # @param user_id [String] User ID (required)
     # @param traits [Hash] User traits (optional)
-    # @param ip [String] IP address (optional)
-    # @return [void]
+    # @return [self] Returns self for method chaining
     #
     # @example
     #   client.identify('user_123', { email: 'user@example.com', name: 'Stefan' })
-    def identify(user_id, traits = nil, ip: nil)
-      return if @shutdown
+    def identify(user_id, traits = nil)
+      return self if @shutdown
 
       event = Event.new(
         type: EventType::IDENTIFY,
         user_id: user_id,
         traits: traits || {},
-        context: build_context(ip)
+        context: build_context
       )
 
       enqueue(event)
+      self
     end
 
-    # Associate a user with a group and set group traits
+    # Identify a user with traits (sync) - blocks until sent, raises on error
+    #
+    # @param user_id [String] User ID (required)
+    # @param traits [Hash] User traits (optional)
+    # @return [BatchResponse] The response from the server
+    # @raise [SendError] If the event fails to send
+    def identify!(user_id, traits = nil)
+      raise SendError.new("Client is shutdown") if @shutdown
+
+      event = Event.new(
+        type: EventType::IDENTIFY,
+        user_id: user_id,
+        traits: traits || {},
+        context: build_context
+      )
+
+      send_sync([event])
+    end
+
+    # Associate a user with a group and set group traits (async)
     #
     # @param group_id [String] Group ID (required)
     # @param traits [Hash] Group traits (optional)
     # @param user_id [String] User ID (optional)
-    # @param ip [String] IP address (optional)
-    # @return [void]
-    #
-    # @example Simple usage
-    #   client.group('org_456', { name: 'Acme Inc', plan: 'enterprise' })
+    # @return [self] Returns self for method chaining
     #
-    # @example With user ID
+    # @example
     #   client.group('org_456', { name: 'Acme Inc' }, user_id: 'user_123')
-    def group(group_id, traits = nil, user_id: nil, ip: nil)
-      return if @shutdown
+    def group(group_id, traits = nil, user_id: nil)
+      return self if @shutdown
 
       event = Event.new(
         type: EventType::GROUP,
         group_id: group_id,
         user_id: user_id,
         traits: traits || {},
-        context: build_context(ip)
+        context: build_context
       )
 
       enqueue(event)
+      self
+    end
+
+    # Associate a user with a group (sync) - blocks until sent, raises on error
+    #
+    # @param group_id [String] Group ID (required)
+    # @param traits [Hash] Group traits (optional)
+    # @param user_id [String] User ID (optional)
+    # @return [BatchResponse] The response from the server
+    # @raise [SendError] If the event fails to send
+    def group!(group_id, traits = nil, user_id: nil)
+      raise SendError.new("Client is shutdown") if @shutdown
+
+      event = Event.new(
+        type: EventType::GROUP,
+        group_id: group_id,
+        user_id: user_id,
+        traits: traits || {},
+        context: build_context
+      )
+
+      send_sync([event])
     end
 
     # Manually flush queued events immediately
+    # Blocks until all queued events are sent
     #
-    # @return [void]
+    # @return [self] Returns self for method chaining
     def flush
-      return if @shutdown
+      return self if @shutdown
 
-      @mutex.synchronize do
-        return if @flush_in_progress
+      # Process all batches synchronously
+      loop do
+        batch = extract_batch
+        break if batch.empty?
 
-        @flush_in_progress = true
+        send_batch(batch)
       end
 
-      begin
-        do_flush
-      ensure
-        @mutex.synchronize do
-          @flush_in_progress = false
-        end
-      end
+      self
     end
 
     # Gracefully shutdown the client, flushing remaining events
@@ -169,67 +240,149 @@ module Klime
     def shutdown
       return if @shutdown
 
+      logger.info "Shutting down..."
       @shutdown = true
 
-      # Cancel scheduled flush
-      @flush_thread&.kill
+      # Signal worker thread to exit
+      @worker_thread[:should_exit] = true if @worker_thread&.alive?
 
-      # Force flush remaining events (bypass normal flush which checks @shutdown)
+      # Flush remaining events synchronously
       flush_remaining
+
+      # Wait for worker thread to finish
+      @worker_thread&.join(5) # Wait up to 5 seconds
+
+      logger.info "Shutdown complete"
+    end
+
+    # Returns the current queue size (useful for debugging)
+    # @return [Integer]
+    def queue_size
+      @queue.size
+    end
+
+    # Restart the background worker thread
+    # Call this in Puma's on_worker_boot or after a fork
+    #
+    # @return [void]
+    def restart!
+      @worker_mutex.synchronize do
+        logger.info "Restarting worker (pid: #{Process.pid})"
+
+        # Update PID
+        @pid = Process.pid
+
+        # Create fresh queue (old one is from parent process)
+        @queue = Queue.new
+
+        # Clear old thread reference
+        @worker_thread = nil
+
+        # Reset shutdown flag
+        @shutdown = false
+      end
     end
 
     private
 
     def setup_shutdown_hook
-      at_exit { shutdown }
+      at_exit do
+        @worker_thread[:should_exit] = true if @worker_thread&.alive?
+        shutdown
+      end
     end
 
-    def schedule_flush
-      return if @shutdown
+    # Check if we've forked and need to reinitialize
+    def check_for_fork!
+      return if @pid == Process.pid
+
+      logger.info "Fork detected (was: #{@pid}, now: #{Process.pid}), reinitializing"
+      restart!
+    end
+
+    # Ensure the background worker thread is running
+    # Called before every enqueue to handle thread death or fork
+    def ensure_worker_running
+      check_for_fork!
+
+      return if worker_running?
+
+      @worker_mutex.synchronize do
+        return if worker_running?
+
+        logger.debug "Starting background worker thread"
+        @worker_thread = Thread.new { run_worker }
+      end
+    end
+
+    def worker_running?
+      @worker_thread&.alive?
+    end
 
-      @flush_thread = Thread.new do
+    # Background worker loop - runs continuously, flushing at intervals
+    def run_worker
+      until Thread.current[:should_exit]
         sleep(@flush_interval / 1000.0)
-        flush unless @shutdown
-        schedule_flush unless @shutdown
+
+        next if @queue.empty? || @shutdown
+
+        begin
+          batch = extract_batch
+          send_batch(batch) unless batch.empty?
+        rescue StandardError => e
+          logger.error "Worker error: #{e.message}"
+        end
       end
+
+      logger.debug "Worker thread exiting"
     end
 
     def enqueue(event)
       # Check event size
       event_size = estimate_event_size(event)
       if event_size > MAX_EVENT_SIZE_BYTES
-        warn "Klime: Event size (#{event_size} bytes) exceeds #{MAX_EVENT_SIZE_BYTES} bytes limit"
-        return
+        logger.warn "Event rejected: size (#{event_size} bytes) exceeds #{MAX_EVENT_SIZE_BYTES} bytes limit"
+        return false
       end
 
       # Drop oldest if queue is full
-      @queue.pop(true) if @queue.size >= @max_queue_size rescue nil
+      if @queue.size >= @max_queue_size
+        begin
+          @queue.pop(true)
+          logger.warn "Queue full (#{@max_queue_size}), dropped oldest event"
+        rescue ThreadError
+          # Queue was empty, ignore
+        end
+      end
 
       @queue.push(event)
+      logger.debug "Event enqueued: #{event.type} (queue_size: #{@queue.size})"
 
-      # Check if we should flush immediately
-      flush if @queue.size >= @max_batch_size
-    end
-
-    def do_flush
-      # Cancel any scheduled flush thread
-      @flush_thread&.kill
+      # Ensure worker is running (lazy start, fork recovery)
+      ensure_worker_running
 
-      # Process batches
-      flush_remaining
+      # Check if we should flush immediately (batch size reached)
+      if @queue.size >= @max_batch_size
+        logger.debug "Batch size reached (#{@max_batch_size}), triggering immediate flush"
+        # Don't call flush directly - let worker handle it or extract batch here
+        batch = extract_batch
+        send_batch(batch) unless batch.empty?
+      end
 
-      # Schedule next flush
-      schedule_flush unless @shutdown
+      true
     end
 
-    # Flush all queued events without scheduling (used by shutdown)
+    # Flush all queued events without worker (used by shutdown)
     def flush_remaining
+      total_sent = 0
       loop do
         batch = extract_batch
         break if batch.empty?
 
         send_batch(batch)
+        total_sent += batch.size
       end
+      logger.debug "Flush complete (sent: #{total_sent} events)" if total_sent > 0
     end
 
     def extract_batch
@@ -269,6 +422,8 @@ module Klime
       attempt = 0
       delay = @retry_initial_delay / 1000.0 # Convert to seconds
 
+      logger.debug "Sending batch (size: #{batch.size}, bytes: #{request_body.bytesize})"
+
       while attempt < @retry_max_attempts
         begin
           response = make_request(uri, request_body)
@@ -284,13 +439,23 @@ module Klime
             )
 
             if batch_response.failed > 0 && batch_response.errors
-              warn "Klime: Batch partially failed. Accepted: #{batch_response.accepted}, Failed: #{batch_response.failed}"
+              logger.warn "Batch partially failed (accepted: #{batch_response.accepted}, failed: #{batch_response.failed})"
+              batch_response.errors.each do |err|
+                logger.warn "  Event #{err.index}: #{err.message} (#{err.code})"
+              end
+            else
+              logger.debug "Batch sent successfully (accepted: #{batch_response.accepted})"
             end
+
+            # Invoke success callback
+            invoke_on_success(batch_response)
             return
 
           when Net::HTTPBadRequest, Net::HTTPUnauthorized
             data = JSON.parse(response.body) rescue {}
-            warn "Klime: Permanent error (#{response.code}): #{data}"
+            error_msg = "Permanent error (#{response.code}): #{data}"
+            logger.error error_msg
+            invoke_on_error(SendError.new(error_msg, status_code: response.code.to_i, events: batch), batch)
             return
 
           when Net::HTTPTooManyRequests, Net::HTTPServiceUnavailable
@@ -299,6 +464,7 @@ module Klime
 
             attempt += 1
             if attempt < @retry_max_attempts
+              logger.warn "Rate limited (#{response.code}), retrying in #{delay}s (attempt #{attempt}/#{@retry_max_attempts})"
               sleep(delay)
               delay = [delay * 2, 16.0].min
               next
@@ -308,6 +474,7 @@ module Klime
             # Other errors - retry
             attempt += 1
             if attempt < @retry_max_attempts
+              logger.warn "Request failed (#{response.code}), retrying in #{delay}s (attempt #{attempt}/#{@retry_max_attempts})"
               sleep(delay)
               delay = [delay * 2, 16.0].min
             end
@@ -317,13 +484,58 @@ module Klime
           # Network errors - retry
           attempt += 1
           if attempt < @retry_max_attempts
+            logger.warn "Network error: #{e.message}, retrying in #{delay}s (attempt #{attempt}/#{@retry_max_attempts})"
             sleep(delay)
             delay = [delay * 2, 16.0].min
           else
-            warn "Klime: Failed to send batch after retries: #{e.message}"
+            error_msg = "Failed to send batch after #{@retry_max_attempts} attempts: #{e.message}"
+            logger.error error_msg
+            invoke_on_error(SendError.new(error_msg, events: batch), batch)
           end
         end
       end
+
+      # If we exhausted retries without returning
+      error_msg = "Failed to send batch after #{@retry_max_attempts} attempts"
+      logger.error error_msg
+      invoke_on_error(SendError.new(error_msg, events: batch), batch)
+    end
+
+    # Synchronous send for bang methods
+    def send_sync(events)
+      request_body = { batch: events.map(&:to_h) }.to_json
+      uri = URI.parse("#{@endpoint}/v1/batch")
+
+      logger.debug "Sending sync (size: #{events.size})"
+
+      response = make_request(uri, request_body)
+
+      case response
+      when Net::HTTPSuccess
+        data = JSON.parse(response.body)
+        batch_response = BatchResponse.new(
+          status: data["status"] || "ok",
+          accepted: data["accepted"] || 0,
+          failed: data["failed"] || 0,
+          errors: parse_errors(data["errors"])
+        )
+
+        logger.debug "Sync send successful (accepted: #{batch_response.accepted})"
+        batch_response
+
+      when Net::HTTPBadRequest, Net::HTTPUnauthorized
+        data = JSON.parse(response.body) rescue {}
+        raise SendError.new("Request failed (#{response.code}): #{data}", status_code: response.code.to_i, events: events)
+
+      when Net::HTTPTooManyRequests
+        raise SendError.new("Rate limited (#{response.code})", status_code: response.code.to_i, events: events)
+
+      else
+        raise SendError.new("Request failed (#{response.code})", status_code: response.code.to_i, events: events)
+      end
+    rescue StandardError => e
+      raise e if e.is_a?(SendError)
+      raise SendError.new("Network error: #{e.message}", events: events)
     end
 
     def make_request(uri, body)
@@ -340,12 +552,10 @@ module Klime
       http.request(request)
     end
 
-    def build_context(ip = nil)
-      context = EventContext.new(
+    def build_context
+      EventContext.new(
         library: LibraryInfo.new(name: "ruby-sdk", version: VERSION)
       )
-      context.ip = ip if ip
-      context
     end
 
     def estimate_event_size(event)
@@ -365,6 +575,19 @@ module Klime
         )
       end
     end
+
+    def invoke_on_error(error, batch)
+      callback = @on_error || Klime.configuration.on_error
+      callback&.call(error, batch)
+    rescue StandardError => e
+      logger.error "on_error callback raised: #{e.message}"
+    end
+
+    def invoke_on_success(response)
+      callback = @on_success || Klime.configuration.on_success
+      callback&.call(response)
+    rescue StandardError => e
+      logger.error "on_success callback raised: #{e.message}"
+    end
   end
 end
-

data/lib/klime/configuration.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Klime
+  # Configuration options for the Klime SDK
+  #
+  # @example Configure via block
+  #   Klime.configure do |config|
+  #     config.logger = Rails.logger
+  #     config.on_error = ->(error, batch) { Sentry.capture_exception(error) }
+  #   end
+  #
+  # @example Direct assignment
+  #   Klime.configuration.logger = Logger.new($stdout)
+  class Configuration
+    # Callback invoked when a batch fails to send after all retries.
+    # Receives the error and the batch of events that failed.
+    # @return [Proc, nil]
+    # @example
+    #   config.on_error = ->(error, batch) { puts "Failed: #{error.message}" }
+    attr_accessor :on_error
+
+    # Callback invoked when a batch is successfully sent.
+    # Receives the batch response with accepted/failed counts.
+    # @return [Proc, nil]
+    # @example
+    #   config.on_success = ->(response) { puts "Sent #{response.accepted} events" }
+    attr_accessor :on_success
+
+    # Logger instance setter
+    # @return [Logger]
+    attr_writer :logger
+
+    def initialize
+      @logger = nil
+      @on_error = nil
+      @on_success = nil
+    end
+
+    # Returns the configured logger, or creates a default one.
+    # Auto-detects Rails.logger if available.
+    # @return [Logger]
+    def logger
+      @logger ||= default_logger
+    end
+
+    private
+
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger
+      else
+        require "logger"
+        new_logger = Logger.new($stdout)
+        new_logger.progname = "Klime"
+        new_logger.level = Logger::INFO
+        new_logger
+      end
+    end
+  end
+end

data/lib/klime/event.rb

@@ -32,17 +32,14 @@ module Klime
   # Context information for events
   class EventContext
     attr_reader :library
-    attr_accessor :ip
 
-    def initialize(library: nil, ip: nil)
+    def initialize(library: nil)
       @library = library
-      @ip = ip
     end
 
     def to_h
       result = {}
       result[:library] = @library.to_h if @library
-      result[:ip] = @ip if @ip
       result
     end
   end

data/lib/klime/logging.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Klime
+  # Provides logging functionality to SDK classes.
+  # Wraps the configured logger with a [Klime] prefix.
+  #
+  # @example Include in a class
+  #   class MyClass
+  #     include Klime::Logging
+  #
+  #     def do_something
+  #       logger.debug "Doing something"
+  #     end
+  #   end
+  module Logging
+    # Wrapper that prefixes all log messages with [Klime]
+    class PrefixedLogger
+      PREFIX = "[Klime]"
+
+      def initialize(logger)
+        @logger = logger
+      end
+
+      def debug(msg)
+        @logger.debug("#{PREFIX} #{msg}")
+      end
+
+      def info(msg)
+        @logger.info("#{PREFIX} #{msg}")
+      end
+
+      def warn(msg)
+        @logger.warn("#{PREFIX} #{msg}")
+      end
+
+      def error(msg)
+        @logger.error("#{PREFIX} #{msg}")
+      end
+
+      # Allow setting log level on the underlying logger
+      def level=(level)
+        @logger.level = level if @logger.respond_to?(:level=)
+      end
+
+      def level
+        @logger.level if @logger.respond_to?(:level)
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def logger
+        Klime.logger
+      end
+    end
+
+    def logger
+      Klime.logger
+    end
+  end
+end

data/lib/klime/middleware.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Klime
+  # Rack middleware that ensures events are flushed after each request.
+  #
+  # This is useful when you need guaranteed delivery of events within the
+  # request lifecycle, rather than relying on background flushing.
+  #
+  # @example Rails application.rb
+  #   config.middleware.use Klime::Middleware, client: KLIME
+  #
+  # @example Rails with auto-detection
+  #   # If you set Klime.client, it will be used automatically
+  #   Klime.client = KLIME
+  #   config.middleware.use Klime::Middleware
+  #
+  # @example Rack app
+  #   use Klime::Middleware, client: klime_client
+  #
+  # @note This adds latency to every request as it waits for the flush.
+  #   Only use this if you need guaranteed per-request delivery.
+  #   For most use cases, the background worker is sufficient.
+  class Middleware
+    # @param app [#call] The Rack application
+    # @param client [Klime::Client, nil] The Klime client to use (optional if Klime.client is set)
+    def initialize(app, client: nil)
+      @app = app
+      @client = client
+    end
+
+    def call(env)
+      response = @app.call(env)
+      flush_client
+      response
+    rescue StandardError
+      flush_client
+      raise
+    end
+
+    private
+
+    def flush_client
+      client = @client || Klime.client
+      return unless client
+
+      client.flush
+    rescue StandardError => e
+      # Don't let flush errors break the request
+      Klime.logger.error "Middleware flush error: #{e.message}"
+    end
+  end
+end

data/lib/klime/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Klime
-  VERSION = "1.0.4"
+  VERSION = "1.1.0"
 end
 

data/lib/klime.rb

@@ -1,11 +1,89 @@
 # frozen_string_literal: true
 
 require_relative "klime/version"
+require_relative "klime/configuration"
+require_relative "klime/logging"
 require_relative "klime/event"
 require_relative "klime/client"
+require_relative "klime/middleware"
 
 module Klime
   class Error < StandardError; end
   class ConfigurationError < Error; end
-end
 
+  # Raised when a synchronous operation (bang method) fails
+  class SendError < Error
+    attr_reader :status_code, :events
+
+    def initialize(message, status_code: nil, events: nil)
+      super(message)
+      @status_code = status_code
+      @events = events
+    end
+  end
+
+  class << self
+    # Global client instance (optional, for use with middleware)
+    # @return [Klime::Client, nil]
+    attr_accessor :client
+
+    # Returns the global configuration instance
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the SDK with a block
+    #
+    # @example
+    #   Klime.configure do |config|
+    #     config.logger = Rails.logger
+    #     config.on_error = Proc.new { |error, batch| Sentry.capture_exception(error) }
+    #   end
+    #
+    # @yield [Configuration] the configuration instance
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Reset configuration to defaults (useful for testing)
+    # @api private
+    def reset_configuration!
+      @configuration = Configuration.new
+      @logger = nil
+      @client = nil
+    end
+
+    # Returns the configured logger wrapped with a prefix
+    # @return [Logging::PrefixedLogger]
+    def logger
+      @logger ||= Logging::PrefixedLogger.new(configuration.logger)
+    end
+
+    # Allows setting a custom logger directly
+    # @param new_logger [Logger] the logger instance to use
+    def logger=(new_logger)
+      configuration.logger = new_logger
+      @logger = Logging::PrefixedLogger.new(new_logger)
+    end
+
+    # Restart the global client's worker thread after a fork.
+    # Call this in Puma's on_worker_boot or Unicorn's after_fork.
+    #
+    # @example config/puma.rb
+    #   on_worker_boot do
+    #     Klime.restart!
+    #   end
+    #
+    # @example config/unicorn.rb
+    #   after_fork do |server, worker|
+    #     Klime.restart!
+    #   end
+    #
+    # @return [void]
+    def restart!
+      @client&.restart!
+    end
+  end
+end

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: klime
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.1.0
 platform: ruby
 authors:
 - Klime
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-12-08 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -64,7 +77,10 @@ files:
 - README.md
 - lib/klime.rb
 - lib/klime/client.rb
+- lib/klime/configuration.rb
 - lib/klime/event.rb
+- lib/klime/logging.rb
+- lib/klime/middleware.rb
 - lib/klime/version.rb
 homepage: https://github.com/klimeapp/klime-ruby
 licenses:
@@ -74,7 +90,6 @@ metadata:
   source_code_uri: https://github.com/klimeapp/klime-ruby
   documentation_uri: https://github.com/klimeapp/klime-ruby
   changelog_uri: https://github.com/klimeapp/klime-ruby/blob/main/CHANGELOG.md
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -89,8 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Klime SDK for Ruby
 test_files: []