Release v1.1.0

Author: sborsje

CHANGELOG.md

@@ -5,9 +5,15 @@ 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.2] - 2025-12-16
+## [1.1.0] - 2026-01-27
 
-- Installation prompt for AI-assisted integration (Cursor, Copilot, etc.) with phased workflow guidance
+- Synchronous methods `trackSync()`, `identifySync()`, and `groupSync()` for cases requiring send confirmation
+- `getQueueSize()` method to check number of queued events
+- `onError` and `onSuccess` callback options for batch send results
+- `SendException` class for handling synchronous operation failures
+- Support for group-only events using `groupId` without `userId` for organization-level tracking
 
-- Event names in examples now use Title Case (e.g., "Report Generated", "Feature Used") instead of snake_case
+- Documentation updated to support both analytics modes (Companies & Teams vs Individual Customers)
+
+- **BREAKING:** Remove IP tracking - the `ip()` option has been removed from `TrackOptions`, `IdentifyOptions`, and `GroupOptions`
 

README.md

@@ -10,14 +10,14 @@ Add to your `pom.xml`:
 <dependency>
     <groupId>com.klime</groupId>
     <artifactId>klime</artifactId>
-    <version>1.0.2</version>
+    <version>1.1.0</version>
 </dependency>
 ```
 
 Or with Gradle:
 
 ```groovy
-implementation 'com.klime:klime:1.0.2'
+implementation 'com.klime:klime:1.1.0'
 ```
 
 ## Quick Start
@@ -69,28 +69,33 @@ public class Example {
 Copy and paste this prompt into Cursor, Copilot, or your favorite AI editor to integrate Klime:
 
 ```
-Integrate Klime for B2B customer analytics. Klime tracks user activity to identify which customers (companies) are healthy vs at risk of churning.
+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:
-- Groups = companies/organizations (your B2B customers)
-- Every track() call requires a userId (no anonymous events)
-- group() links a user to a company AND sets company traits
+- Every track() call requires either userId OR groupId (no anonymous events)
+- Use groupId 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 or Spring bean)
 - Store write key in KLIME_WRITE_KEY environment variable
 - Call shutdown() on application stop to flush remaining events
-- Pass user's IP address for geolocation (use .ip() option)
 
 Add to pom.xml:
 <dependency>
     <groupId>com.klime</groupId>
     <artifactId>klime</artifactId>
-    <version>1.0.2</version>
+    <version>1.1.0</version>
 </dependency>
 
-Or with Gradle: implementation 'com.klime:klime:1.0.2'
+Or with Gradle: implementation 'com.klime:klime:1.1.0'
 
 import com.klime.KlimeClient;
 import com.klime.TrackOptions;
@@ -102,11 +107,11 @@ KlimeClient client = KlimeClient.builder().writeKey(System.getenv("KLIME_WRITE_K
 client.identify("usr_abc123", Map.of("email", "jane@acme.com", "name", "Jane Smith"));
 
 // Track key activities:
-client.track("Report Generated", Map.of("report_type", "revenue"), TrackOptions.builder().userId("usr_abc123").ip(clientIp).build());
+client.track("Report Generated", Map.of("report_type", "revenue"), TrackOptions.builder().userId("usr_abc123").build());
 client.track("Feature Used", Map.of("feature", "export", "format", "csv"), TrackOptions.builder().userId("usr_abc123").build());
 client.track("Teammate Invited", Map.of("role", "member"), TrackOptions.builder().userId("usr_abc123").build());
 
-// Link user to their company and set company traits:
+// If Companies & Teams mode: link user to their company and set company traits
 client.group("org_456", Map.of("name", "Acme Inc", "plan", "enterprise"), GroupOptions.builder().userId("usr_abc123").build());
 
 INTEGRATION WORKFLOW:
@@ -115,7 +120,9 @@ Phase 1: Discover
 Explore the codebase to understand:
 1. What framework is used? (Spring Boot, Quarkus, Micronaut, Jakarta EE, etc.)
 2. Where is user identity available? (e.g., SecurityContextHolder, @AuthenticationPrincipal, Principal, JWT claims)
-3. How are organizations/companies modeled? (look for: organization, workspace, tenant, team, account)
+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, services, event handlers)
 5. Is there existing analytics? (search: segment, posthog, mixpanel, amplitude, track)
 Match your integration style to the framework's conventions.
@@ -124,7 +131,7 @@ Phase 2: Instrument
 Add these calls using idiomatic patterns for the framework:
 - Initialize client once (Spring: @Bean/@Configuration, Quarkus: @ApplicationScoped, Jakarta EE: @WebListener)
 - identify() in auth/login success handler
-- group() when user-org association is established
+- group() when user-org association is established (Companies & Teams mode only)
 - track() for key user actions (see below)
 
 WHAT TO TRACK:
@@ -139,7 +146,7 @@ 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 userId and groupId are obtained
+- How userId is obtained (and groupId if Companies & Teams mode)
 - Any assumptions made or questions
 ```
 
@@ -157,6 +164,8 @@ KlimeClient client = KlimeClient.builder()
     .retryMaxAttempts(5)                  // Optional
     .retryInitialDelay(Duration.ofSeconds(1)) // Optional
     .flushOnShutdown(true)                // Optional
+    .onError((error, events) -> { ... })  // Optional: callback for batch failures
+    .onSuccess((response) -> { ... })     // Optional: callback for successful sends
     .build();
 ```
 
@@ -172,7 +181,6 @@ client.track("Feature Used", Map.of(
 ), TrackOptions.builder()
     .userId("user_123")
     .groupId("org_456")
-    .ip("192.168.1.1")
     .build());
 
 // Simple usage
@@ -189,10 +197,6 @@ client.identify("user_123", Map.of(
     "name", "Stefan",
     "createdAt", "2025-01-15T10:30:00Z"
 ));
-
-// With IP address
-client.identify("user_123", Map.of("email", "user@example.com"),
-    IdentifyOptions.builder().ip("192.168.1.1").build());
 ```
 
 ### group(groupId, traits, options)
@@ -237,6 +241,36 @@ client.shutdown();
 client.shutdown().join();
 ```
 
+### getQueueSize()
+
+Get the number of events currently queued.
+
+```java
+int pending = client.getQueueSize();
+System.out.println(pending + " events waiting to be sent");
+```
+
+### Synchronous Methods
+
+For cases where you need confirmation that events were sent (e.g., in tests, before exit), use the synchronous variants:
+
+```java
+import com.klime.SendException;
+
+try {
+    BatchResponse response = client.trackSync("Critical Action", Map.of("key", "value"),
+        TrackOptions.builder().userId("user_123").build());
+    System.out.println("Sent! Accepted: " + response.getAccepted());
+} catch (SendException e) {
+    System.err.println("Failed: " + e.getMessage() + ", events: " + e.getEvents().size());
+}
+```
+
+Available sync methods:
+- `trackSync(event, properties, options)` - Track synchronously
+- `identifySync(userId, traits)` - Identify synchronously
+- `groupSync(groupId, traits, options)` - Group synchronously
+
 ## Features
 
 - **Zero dependencies**: Uses only Java standard library (Java 11+)
@@ -247,6 +281,30 @@ client.shutdown().join();
 - **Graceful shutdown**: JVM shutdown hook ensures events are flushed
 - **CompletableFuture API**: Async operations return CompletableFuture
 
+## Performance
+
+When you call `track()`, `identify()`, or `group()`, the SDK:
+
+1. Adds the event to a thread-safe `BlockingQueue` (microseconds)
+2. Returns immediately without waiting for network I/O
+
+Events are sent to Klime's servers by a background `ScheduledExecutorService`. 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)
+
+```java
+// This returns immediately - no HTTP request is made here
+client.track("Button Clicked", Map.of("button", "signup"),
+    TrackOptions.builder().userId("user_123").build());
+
+// Your code continues without waiting
+return ResponseEntity.ok(Map.of("success", true));
+```
+
+The only blocking operations are `flush().join()` and `shutdown().join()`, which wait for all queued events to be sent. These are typically only called during graceful shutdown.
+
 ## Configuration
 
 | Option              | Default               | Description                     |
@@ -260,6 +318,39 @@ client.shutdown().join();
 | `retryInitialDelay` | `1 second`            | Initial retry delay             |
 | `flushOnShutdown`   | `true`                | Auto-flush on JVM shutdown      |
 
+### Logging
+
+The SDK uses `java.util.logging` (JUL). Configure logging levels via your JUL configuration:
+
+```properties
+# logging.properties
+com.klime.level = FINE
+```
+
+Or programmatically:
+
+```java
+Logger.getLogger("com.klime").setLevel(Level.FINE);
+```
+
+For frameworks using SLF4J or Log4j, configure the standard JUL-to-SLF4J bridge.
+
+### Callbacks
+
+```java
+KlimeClient client = KlimeClient.builder()
+    .writeKey("your-write-key")
+    .onError((error, events) -> {
+        // Report to your error tracking service
+        Sentry.captureException(error);
+        System.err.println("Failed to send " + events.size() + " events: " + error.getMessage());
+    })
+    .onSuccess((response) -> {
+        System.out.println("Sent " + response.getAccepted() + " events");
+    })
+    .build();
+```
+
 ## Error Handling
 
 | Status Code | Behavior                                      |
@@ -270,6 +361,19 @@ client.shutdown().join();
 | 429         | Rate limited - retry with exponential backoff |
 | 503         | Service unavailable - retry with backoff      |
 
+For synchronous operations, use `*Sync()` methods which throw `SendException` on failure:
+
+```java
+import com.klime.SendException;
+
+try {
+    BatchResponse response = client.trackSync("Event", null,
+        TrackOptions.builder().userId("user_123").build());
+} catch (SendException e) {
+    System.err.println("Failed: " + e.getMessage() + ", events: " + e.getEvents().size());
+}
+```
+
 ## Size Limits
 
 - **Per event**: 200KB max
@@ -362,7 +466,6 @@ public class ActionServlet extends HttpServlet {
             "action", "submit"
         ), TrackOptions.builder()
             .userId(userId)
-            .ip(req.getRemoteAddr())
             .build());
     }
 }

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.klime</groupId>
     <artifactId>klime</artifactId>
-    <version>1.0.2</version>
+    <version>1.1.0</version>
     <packaging>jar</packaging>
 
     <name>Klime Java SDK</name>

src/main/java/com/klime/EventContext.java

@@ -7,36 +7,20 @@
  */
 public final class EventContext {
     private final LibraryInfo library;
-    private final String ip;
 
     /**
-     * Create a new EventContext with library info only.
+     * Create a new EventContext with library info.
      *
      * @param library the library info
      */
     public EventContext(LibraryInfo library) {
-        this(library, null);
-    }
-
-    /**
-     * Create a new EventContext with library info and IP.
-     *
-     * @param library the library info
-     * @param ip      the IP address (optional)
-     */
-    public EventContext(LibraryInfo library, String ip) {
         this.library = Objects.requireNonNull(library, "library cannot be null");
-        this.ip = ip;
     }
 
     public LibraryInfo getLibrary() {
         return library;
     }
 
-    public String getIp() {
-        return ip;
-    }
-
     /**
      * Serialize to JSON string.
      *
@@ -45,9 +29,6 @@ public String getIp() {
     public String toJson() {
         StringBuilder sb = new StringBuilder();
         sb.append("{\"library\":").append(library.toJson());
-        if (ip != null && !ip.isEmpty()) {
-            sb.append(",\"ip\":\"").append(JsonUtils.escape(ip)).append("\"");
-        }
         sb.append("}");
         return sb.toString();
     }
@@ -57,17 +38,17 @@ public boolean equals(Object o) {
         if (this == o) return true;
         if (o == null || getClass() != o.getClass()) return false;
         EventContext that = (EventContext) o;
-        return Objects.equals(library, that.library) && Objects.equals(ip, that.ip);
+        return Objects.equals(library, that.library);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(library, ip);
+        return Objects.hash(library);
     }
 
     @Override
     public String toString() {
-        return "EventContext{library=" + library + ", ip='" + ip + "'}";
+        return "EventContext{library=" + library + "}";
     }
 }