🌿Fern -- feat: add feature flags with local evaluation, strongly typed errors, and smart endpoint configuration

CHANGELOG.md

@@ -1,3 +1,44 @@
+## 0.6.0 - 2025-11-05
+
+### Added
+
+- Feature flags support (boolean, multivariate, payloads)
+- Local evaluation for 100-1000x faster flag evaluation with background polling
+- Automatic `$feature_flag_called` event tracking with deduplication
+- Property-based targeting and group (B2B) support
+- New methods: `is_feature_enabled()`, `get_feature_flag()`, `get_feature_flags()`, `get_feature_flag_payload()`
+
+#### New Dependencies:
+
+- Added `sha1` for flag matching algorithms
+- Added `regex` for property matching in feature flags
+- Added `tokio` (optional) for async local evaluation with background polling
+- Added `json` and `gzip` features to `reqwest` for flag payloads and compression
+- Dev dependencies: `httpmock` for testing, `futures` for async tests
+
+## 0.5.0 - 2025-11-05
+
+### Minor Changes
+
+Configuration system now accepts base URLs instead of full endpoint URLs
+- Provide just the hostname (e.g., `https://eu.posthog.com`)
+- SDK automatically appends `/i/v0/e/` for single events and `/batch/` for batch events
+- Old format with full URLs still works - paths are automatically stripped and normalized
+- Enables simultaneous use of both single-event and batch endpoints
+## 0.4.0 - 2025-11-05
+
+### Minor Changes
+
+ - Refactored error handling to use organized error types (`TransportError`, `ValidationError`, `InitializationError`) with structured data (timeouts, status codes, batch sizes) that can be pattern matched
+    - Existing errors will continue to work with deprecation warnings. 
+
+ - New helper methods:
+    - `is_retryable()` - identifies transient errors (timeouts, 5xx, 429)  
+    - `is_client_error()` - identifies 4xx errors
+
+#### New Dependencies:
+ - Added `thiserror` to reduce writing manual error handling boilerplate
+
 ## 0.2.6 - 2025-01-08
 
 

Cargo.toml

@@ -12,19 +12,29 @@ rust-version = "1.78.0"
 reqwest = { version = "0.11.3", default-features = false, features = [
     "rustls-tls",
     "blocking",
+    "json",
+    "gzip",
 ] }
 serde = { version = "1.0.125", features = ["derive"] }
 chrono = { version = "0.4.19", features = ["serde"] }
 serde_json = "1.0.64"
 semver = "1.0.24"
-derive_builder = "0.20.2"
 uuid = { version = "1.13.2", features = ["serde", "v7"] }
+sha1 = "0.10"
+regex = "1.10"
+tokio = { version = "1", features = ["rt", "sync", "time", "macros"], optional = true }
+url = "2.5"
+thiserror = "2.0"
 
 [dev-dependencies]
 dotenv = "0.15.0"
 ctor = "0.1.26"
+tokio = { version = "1", features = ["full"] }
+httpmock = "0.7"
+serde_json = "1.0"
+futures = "0.3"
 
 [features]
 default = ["async-client"]
 e2e-test = []
-async-client = []
+async-client = ["tokio"]

README.md

@@ -1,6 +1,6 @@
 # PostHog Rust
 
-Please see the main [PostHog docs](https://posthog.com/docs).
+Please see the main [PostHog docs](https://posthog.com/docs)
 
 **This crate is under development**
 
@@ -13,12 +13,243 @@ Add `posthog-rs` to your `Cargo.toml`.
 posthog-rs = "0.3.7"
 ```
 
+## Basic Usage (US Region)
+
 ```rust
+use posthog_rs::{Event, ClientOptionsBuilder};
+
+// Simple initialization with API key (defaults to US region)
 let client = posthog_rs::client(env!("POSTHOG_API_KEY"));
 
-let mut event = posthog_rs::Event::new("test", "1234");
-event.insert_prop("key1", "value1").unwrap();
-event.insert_prop("key2", vec!["a", "b"]).unwrap();
+// Create and send an event
+let mut event = Event::new("user_signed_up", "user_distinct_id");
+event.insert_prop("plan", "premium").unwrap();
+event.insert_prop("source", "web").unwrap();
+
+client.capture(event).unwrap();
+```
+
+## EU Region Configuration
+
+```rust
+use posthog_rs::{Event, ClientOptionsBuilder};
+
+// Configure for EU region - just provide the base URL
+let options = ClientOptionsBuilder::new()
+    .api_key("phc_your_api_key")
+    .api_endpoint("https://eu.posthog.com")  // SDK handles /i/v0/e/ and /batch/ automatically
+    .build()
+    .unwrap();
+
+let client = posthog_rs::client(options);
 
+// Single event capture
+let event = Event::new("user_signed_up", "user_distinct_id");
 client.capture(event).unwrap();
+
+// Batch event capture (uses same base URL, different endpoint path)
+let events = vec![
+    Event::new("page_view", "user_1"),
+    Event::new("button_click", "user_2"),
+];
+client.capture_batch(events).unwrap();
+```
+
+## Backward Compatibility
+
+Old format with full URLs still works - the SDK automatically normalizes them:
+
+```rust
+// This still works - path is automatically stripped
+let options = ClientOptionsBuilder::new()
+    .api_key("phc_your_api_key")
+    .api_endpoint("https://eu.posthog.com/i/v0/e/")  // Gets normalized to base URL
+    .build()
+    .unwrap();
+```
+
+## Feature Flags
+
+The SDK now supports PostHog feature flags, allowing you to control feature rollout and run A/B tests.
+
+### Basic Usage
+
+```rust
+use posthog_rs::{ClientOptionsBuilder, FlagValue};
+use std::collections::HashMap;
+use serde_json::json;
+
+let options = ClientOptionsBuilder::default()
+    .api_key("phc_your_project_key")
+    .build()
+    .unwrap();
+
+let client = posthog_rs::client(options);
+
+// Check if a feature is enabled
+let is_enabled = client.is_feature_enabled(
+    "feature-key".to_string(),
+    "user-id".to_string(),
+    None, None, None
+).unwrap();
+
+// Get feature flag value (boolean or variant)
+match client.get_feature_flag(
+    "feature-key".to_string(),
+    "user-id".to_string(),
+    None, None, None
+).unwrap() {
+    Some(FlagValue::Boolean(enabled)) => println!("Flag is: {}", enabled),
+    Some(FlagValue::String(variant)) => println!("Variant: {}", variant),
+    None => println!("Flag is disabled"),
+}
+```
+
+### With Properties
+
+```rust
+// Include person properties for flag evaluation
+let mut person_props = HashMap::new();
+person_props.insert("plan".to_string(), json!("enterprise"));
+person_props.insert("country".to_string(), json!("US"));
+
+let flag = client.get_feature_flag(
+    "premium-feature".to_string(),
+    "user-id".to_string(),
+    None,
+    Some(person_props),
+    None
+).unwrap();
+```
+
+### With Groups (B2B)
+
+```rust
+// For B2B apps with group-based flags
+let mut groups = HashMap::new();
+groups.insert("company".to_string(), "company-123".to_string());
+
+let mut group_props = HashMap::new();
+let mut company_props = HashMap::new();
+company_props.insert("size".to_string(), json!(500));
+group_props.insert("company".to_string(), company_props);
+
+let flag = client.get_feature_flag(
+    "b2b-feature".to_string(),
+    "user-id".to_string(),
+    Some(groups),
+    None,
+    Some(group_props)
+).unwrap();
 ```
+
+### Get All Flags
+
+```rust
+// Get all feature flags for a user
+let response = client.get_feature_flags(
+    "user-id".to_string(),
+    None, None, None
+).unwrap();
+
+for (key, value) in response.feature_flags {
+    println!("Flag {}: {:?}", key, value);
+}
+```
+
+### Feature Flag Payloads
+
+```rust
+// Get additional data associated with a feature flag
+let payload = client.get_feature_flag_payload(
+    "onboarding-flow".to_string(),
+    "user-id".to_string()
+).unwrap();
+
+if let Some(data) = payload {
+    println!("Payload: {}", data);
+}
+```
+
+### Local Evaluation (High Performance)
+
+For significantly faster flag evaluation, enable local evaluation to cache flag definitions locally:
+
+```rust
+use posthog_rs::ClientOptionsBuilder;
+
+let options = ClientOptionsBuilder::default()
+    .api_key("phc_your_project_key")
+    .personal_api_key("phx_your_personal_key") // Required for local evaluation
+    .enable_local_evaluation(true)
+    .poll_interval_seconds(30) // Update cache every 30s
+    .build()
+    .unwrap();
+
+let client = posthog_rs::client(options);
+
+// Flag evaluations now happen locally (no API calls needed)
+let enabled = client.is_feature_enabled(
+    "new-feature".to_string(),
+    "user-123".to_string(),
+    None, None, None
+).unwrap();
+```
+
+**Performance:** Local evaluation is 100-1000x faster than API evaluation (~119µs vs ~125ms per request).
+
+Get your personal API key at: https://app.posthog.com/me/settings
+
+### Automatic Event Tracking
+
+The SDK automatically captures `$feature_flag_called` events when you evaluate feature flags. These events include:
+- Feature flag key and response value
+- Deduplication per user + flag + value combination
+- Rich metadata (payloads, versions, request IDs)
+
+To disable automatic events globally:
+```rust
+let options = ClientOptionsBuilder::default()
+    .api_key("phc_your_key")
+    .send_feature_flag_events(false)
+    .build()
+    .unwrap();
+```
+
+## Error Handling
+
+The SDK provides error handling with semantic categories:
+
+```rust
+use posthog_rs::{Error, TransportError, ValidationError};
+
+match client.capture(event).await {
+    Ok(_) => println!("Event sent successfully"),
+    Err(Error::Transport(TransportError::Timeout(duration))) => {
+        eprintln!("Request timed out after {:?}", duration);
+        // Retry logic here
+    }
+    Err(Error::Transport(TransportError::HttpError(401, _))) => {
+        eprintln!("Invalid API key - check your configuration");
+    }
+    Err(e) if e.is_retryable() => {
+        // Automatically handles: timeouts, 5xx errors, 429 rate limits
+        tokio::time::sleep(Duration::from_secs(2)).await;
+        client.capture(event).await?;
+    }
+    Err(e) => eprintln!("Permanent error: {}", e),
+}
+```
+
+### Error Categories
+
+- **TransportError**: Network issues (DNS, timeouts, HTTP errors, connection failures)
+- **ValidationError**: Data problems (serialization, batch size, invalid timestamps)
+- **InitializationError**: Configuration issues (already initialized, not initialized)
+
+### Helper Methods
+
+- `is_retryable()`: Returns `true` for transient errors (timeouts, 5xx, 429)
+- `is_client_error()`: Returns `true` for 4xx HTTP errors
+
+See [`examples/error_classification.rs`](examples/error_classification.rs) for comprehensive error handling patterns