Release v1.1.0

Author: sborsje

.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4

CHANGELOG.md

@@ -5,9 +5,16 @@ 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.3] - 2025-12-10
+## [1.1.0] - 2026-01-27
 
-- Update SDK endpoints for improved consistency
+- Add synchronous methods `track_sync()`, `identify_sync()`, and `group_sync()` that return `BatchResponse` and raise `SendError` on failure
+- Add `queue_size()` method to check pending events in queue
+- Add `on_error` and `on_success` callback parameters to constructor for handling batch results
+- Add `logger` parameter to constructor for custom logging configuration
+- Support group-only events by allowing `track()` with `group_id` alone (without `user_id`) for organization-level tracking
+- Export `BatchResponse` and `SendError` types from package
 
-- Audit and modernize SDK for better reliability
+- Expand Python version support to 3.10, 3.11, 3.12, 3.13, and 3.14 (dropped 3.9)
+
+- **BREAKING:** Remove `ip` parameter from `track()`, `identify()`, and `group()` methods
 

README.md

@@ -42,6 +42,84 @@ 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 (singleton pattern)
+- Store write key in KLIME_WRITE_KEY environment variable
+- Call shutdown() on process exit to flush remaining events (auto-registered via atexit)
+
+Install: pip install klime
+
+import os
+from klime import KlimeClient
+
+client = KlimeClient(write_key=os.environ['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? (Django, Flask, FastAPI, Starlette, etc.)
+2. Where is user identity available? (e.g., request.user.id, current_user.id, g.user, Depends() injection)
+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? (views, routes, API endpoints, services)
+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 (Django: apps.py/settings, Flask: app factory, FastAPI: lifespan/startup)
+- 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, middleware passthrough, background tasks
+
+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
@@ -55,43 +133,49 @@ KlimeClient(
     max_queue_size: Optional[int] = None,      # Optional: Max queued events (default: 1000)
     retry_max_attempts: Optional[int] = None, # Optional: Max retry attempts (default: 5)
     retry_initial_delay: Optional[int] = None, # Optional: Initial retry delay in ms (default: 1000)
-    flush_on_shutdown: Optional[bool] = None   # Optional: Auto-flush on exit (default: True)
+    flush_on_shutdown: Optional[bool] = None,  # Optional: Auto-flush on exit (default: True)
+    logger: Optional[logging.Logger] = None,   # Optional: Custom logger (default: logging.getLogger("klime"))
+    on_error: Optional[Callable] = None,       # Optional: Callback for batch failures
+    on_success: Optional[Callable] = None      # Optional: Callback for successful sends
 )
 ```
 
 ### Methods
 
-#### `track(event: str, properties: Optional[Dict] = None, user_id: Optional[str] = None, group_id: Optional[str] = None, ip: Optional[str] = None) -> None`
+#### `track(event: str, properties: Optional[Dict] = None, user_id: Optional[str] = None, group_id: Optional[str] = None) -> None`
 
-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
 
 ```python
+# 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: str, traits: Optional[Dict] = None, ip: Optional[str] = None) -> None`
+#### `identify(user_id: str, traits: Optional[Dict] = None) -> None`
 
 Identify a user with traits.
 
 ```python
 client.identify('user_123', {
     'email': 'user@example.com',
     'name': 'Stefan'
-}, ip='192.168.1.1')
+})
 ```
 
-#### `group(group_id: str, traits: Optional[Dict] = None, user_id: Optional[str] = None, ip: Optional[str] = None) -> None`
+#### `group(group_id: str, traits: Optional[Dict] = None, user_id: Optional[str] = None) -> None`
 
 Associate a user with a group and/or set group traits.
 
@@ -128,6 +212,41 @@ Gracefully shutdown the client, flushing remaining events.
 client.shutdown()
 ```
 
+#### `queue_size() -> int`
+
+Return the number of events currently in the queue.
+
+```python
+pending = client.queue_size()
+print(f"{pending} events waiting to be sent")
+```
+
+### Synchronous Methods
+
+For cases where you need confirmation that events were sent (e.g., before process exit, in tests), use the synchronous variants:
+
+#### `track_sync(event, properties, user_id, group_id) -> BatchResponse`
+
+Track an event synchronously. Raises `SendError` on failure.
+
+```python
+from klime import SendError
+
+try:
+    response = client.track_sync('Critical Action', {'key': 'value'}, user_id='user_123')
+    print(f"Sent! Accepted: {response.accepted}")
+except SendError as e:
+    print(f"Failed to send: {e.message}")
+```
+
+#### `identify_sync(user_id, traits) -> BatchResponse`
+
+Identify a user synchronously. Raises `SendError` on failure.
+
+#### `group_sync(group_id, traits, user_id) -> BatchResponse`
+
+Associate a user with a group synchronously. Raises `SendError` on failure.
+
 ## Features
 
 - **Automatic Batching**: Events are automatically batched and sent every 2 seconds or when the batch size reaches 20 events
@@ -136,6 +255,29 @@ client.shutdown()
 - **Process Exit Handling**: Automatically flushes events on process exit (via `atexit`)
 - **Zero Dependencies**: Uses only Python standard library
 
+## Performance
+
+When you call `track()`, `identify()`, or `group()`, the SDK:
+
+1. Adds the event to a thread-safe queue (microseconds)
+2. Returns immediately without waiting for network I/O
+
+Events are sent to Klime's servers in background threads. This means:
+
+- **No network blocking**: HTTP requests happen asynchronously in background threads
+- **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)
+
+```python
+# This returns immediately - no HTTP request is made here
+client.track('Button Clicked', {'button': 'signup'}, user_id='user_123')
+
+# Your code continues without waiting
+return {'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
@@ -147,6 +289,43 @@ client.shutdown()
 - `retry_initial_delay`: 1000ms
 - `flush_on_shutdown`: True
 
+### Logging
+
+The SDK uses Python's built-in `logging` module. By default, it logs to `logging.getLogger("klime")`.
+
+```python
+import logging
+
+# Enable debug logging
+logging.getLogger("klime").setLevel(logging.DEBUG)
+
+# Or provide a custom logger
+client = KlimeClient(
+    write_key='your-write-key',
+    logger=logging.getLogger("myapp.klime")
+)
+```
+
+For Django/Flask, the SDK automatically integrates with your app's logging configuration.
+
+### Callbacks
+
+```python
+def handle_error(error, events):
+    # Report to your error tracking service
+    sentry_sdk.capture_exception(error)
+    print(f"Failed to send {len(events)} events: {error}")
+
+def handle_success(response):
+    print(f"Sent {response.accepted} events")
+
+client = KlimeClient(
+    write_key='your-write-key',
+    on_error=handle_error,
+    on_success=handle_success
+)
+```
+
 ## Error Handling
 
 The SDK automatically handles:
@@ -155,6 +334,17 @@ The SDK automatically handles:
 - **Permanent errors** (400, 401): Logs error and drops event
 - **Rate limiting**: Respects `Retry-After` header
 
+For synchronous operations, use `*_sync()` methods which raise `SendError` on failure:
+
+```python
+from klime import KlimeClient, SendError
+
+try:
+    response = client.track_sync('Event', user_id='user_123')
+except SendError as e:
+    print(f"Failed: {e.message}, events: {len(e.events)}")
+```
+
 ## Size Limits
 
 - Maximum event size: 200KB
@@ -176,7 +366,7 @@ client = KlimeClient(write_key='your-write-key')
 def button_clicked():
     client.track('Button Clicked', {
         'button_name': request.json.get('buttonName')
-    }, user_id=request.json.get('userId'), ip=request.remote_addr)
+    }, user_id=request.json.get('userId'))
 
     return {'success': True}
 
@@ -198,7 +388,7 @@ class ButtonClickView(View):
     def post(self, request):
         client.track('Button Clicked', {
             'button_name': request.POST.get('buttonName')
-        }, user_id=str(request.user.id), ip=request.META.get('REMOTE_ADDR'))
+        }, user_id=str(request.user.id))
 
         return JsonResponse({'success': True})
 ```

klime/__init__.py

@@ -1,5 +1,6 @@
 from .client import KlimeClient
+from .types import BatchResponse, SendError
 
-__version__ = "1.0.2"
-__all__ = ["KlimeClient"]
+__version__ = "1.1.0"
+__all__ = ["KlimeClient", "BatchResponse", "SendError"]