Release v1.1.0

Author: sborsje

CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.4] - 2025-12-08
+## [1.1.0] - 2026-01-26
+
 
-No user-facing changes in this release.
 

Gemfile.lock

@@ -0,0 +1,38 @@
+PATH
+  remote: .
+  specs:
+    klime (1.0.4)
+      logger
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    bigdecimal (4.0.1)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    hashdiff (1.2.1)
+    logger (1.7.0)
+    minitest (5.27.0)
+    public_suffix (7.0.2)
+    rake (13.3.1)
+    rexml (3.4.4)
+    webmock (3.26.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  klime!
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  webmock (~> 3.0)
+
+BUNDLED WITH
+   2.6.9

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: '[email protected]', 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,43 +149,48 @@ 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.
 
 ```ruby
 client.identify('user_123', {
   email: '[email protected]',
   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

klime.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "klime"
-  spec.version       = "1.0.4"
+  spec.version       = "1.1.0"
   spec.authors       = ["Klime"]
   spec.email         = ["[email protected]"]
 
@@ -21,7 +21,8 @@ Gem::Specification.new do |spec|
 
   spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
 
-  # No runtime dependencies - uses only standard library
+  # Runtime dependency - logger is being removed from default gems in Ruby 3.5
+  spec.add_dependency "logger"
 
   # Development dependencies
   spec.add_development_dependency "minitest", "~> 5.0"