Merge pull request #22 from PostHog/olly_group_support

feat: group support, anon event support

Author: oliverb123

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "posthog-rs"
 license = "MIT"
-version = "0.3.2"
+version = "0.3.3"
 authors = ["christos <[email protected]>"]
 description = "An unofficial Rust client for Posthog (https://posthog.com/)."
 repository = "https://github.com/openquery-io/posthog-rs"
@@ -18,11 +18,13 @@ 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"] }
 
 [dev-dependencies]
 dotenv = "0.15.0"
 ctor = "0.1.26"
 
 [features]
+default = ["async-client"]
 e2e-test = []
 async-client = []

src/event.rs

@@ -3,40 +3,50 @@ use std::collections::HashMap;
 use chrono::NaiveDateTime;
 use semver::Version;
 use serde::Serialize;
+use uuid::Uuid;
 
 use crate::Error;
 
 #[derive(Serialize, Debug, PartialEq, Eq)]
 pub struct Event {
     event: String,
-    properties: Properties,
-    timestamp: Option<NaiveDateTime>,
-}
-
-#[derive(Serialize, Debug, PartialEq, Eq)]
-pub struct Properties {
+    #[serde(rename = "$distinct_id")]
     distinct_id: String,
-    props: HashMap<String, serde_json::Value>,
+    properties: HashMap<String, serde_json::Value>,
+    groups: HashMap<String, String>,
+    timestamp: Option<NaiveDateTime>,
 }
 
-impl Properties {
-    fn new<S: Into<String>>(distinct_id: S) -> Self {
+impl Event {
+    /// Capture a new identified event. Unless you have a distinct ID you can
+    /// associate with a user, you probably want to use `new_anon` instead.
+    pub fn new<S: Into<String>>(event: S, distinct_id: S) -> Self {
         Self {
+            event: event.into(),
             distinct_id: distinct_id.into(),
-            props: Default::default(),
+            properties: HashMap::new(),
+            groups: HashMap::new(),
+            timestamp: None,
         }
     }
-}
 
-impl Event {
-    pub fn new<S: Into<String>>(event: S, distinct_id: S) -> Self {
-        Self {
+    /// Capture a new anonymous event.
+    /// See https://posthog.com/docs/data/anonymous-vs-identified-events#how-to-capture-anonymous-events
+    pub fn new_anon<S: Into<String>>(event: S) -> Self {
+        let mut res = Self {
             event: event.into(),
-            properties: Properties::new(distinct_id),
+            distinct_id: Uuid::now_v7().to_string(),
+            properties: HashMap::new(),
+            groups: HashMap::new(),
             timestamp: None,
-        }
+        };
+        res.insert_prop("$process_person_profile", false)
+            .expect("bools are safe for serde");
+        res
     }
 
+    /// Add a property to the event
+    ///
     /// Errors if `prop` fails to serialize
     pub fn insert_prop<K: Into<String>, P: Serialize>(
         &mut self,
@@ -45,54 +55,87 @@ impl Event {
     ) -> Result<(), Error> {
         let as_json =
             serde_json::to_value(prop).map_err(|e| Error::Serialization(e.to_string()))?;
-        let _ = self.properties.props.insert(key.into(), as_json);
+        let _ = self.properties.insert(key.into(), as_json);
         Ok(())
     }
+
+    /// Capture this as a group event. See https://posthog.com/docs/product-analytics/group-analytics#how-to-capture-group-events
+    /// Note that group events cannot be personless, and will be automatically upgraded to include person profile processing if
+    /// they were anonymous. This might lead to "empty" person profiles being created.
+    pub fn add_group(&mut self, group_name: &str, group_id: &str) {
+        // You cannot disable person profile processing for groups
+        self.insert_prop("$process_person_profile", true)
+            .expect("bools are safe for serde");
+        self.groups.insert(group_name.into(), group_id.into());
+    }
 }
 
 // This exists so that the client doesn't have to specify the API key over and over
 #[derive(Serialize)]
 pub struct InnerEvent {
     api_key: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    uuid: Option<Uuid>,
     event: String,
-    properties: Properties,
+    #[serde(rename = "$distinct_id")]
+    distinct_id: String,
+    properties: HashMap<String, serde_json::Value>,
     timestamp: Option<NaiveDateTime>,
 }
 
 impl InnerEvent {
     pub fn new(event: Event, api_key: String) -> Self {
+        Self::new_with_uuid(event, api_key, None)
+    }
+
+    pub fn new_with_uuid(event: Event, api_key: String, uuid: Option<Uuid>) -> Self {
         let mut properties = event.properties;
 
         // Add $lib_name and $lib_version to the properties
-        properties.props.insert(
+        properties.insert(
             "$lib_name".into(),
             serde_json::Value::String("posthog-rs".into()),
         );
 
         let version_str = env!("CARGO_PKG_VERSION");
-        properties.props.insert(
+        properties.insert(
             "$lib_version".into(),
             serde_json::Value::String(version_str.into()),
         );
 
         if let Ok(version) = version_str.parse::<Version>() {
-            properties.props.insert(
+            properties.insert(
                 "$lib_version__major".into(),
                 serde_json::Value::Number(version.major.into()),
             );
-            properties.props.insert(
+            properties.insert(
                 "$lib_version__minor".into(),
                 serde_json::Value::Number(version.minor.into()),
             );
-            properties.props.insert(
+            properties.insert(
                 "$lib_version__patch".into(),
                 serde_json::Value::Number(version.patch.into()),
             );
         }
 
+        if !event.groups.is_empty() {
+            properties.insert(
+                "$groups".into(),
+                serde_json::Value::Object(
+                    event
+                        .groups
+                        .into_iter()
+                        .map(|(k, v)| (k, serde_json::Value::String(v)))
+                        .collect(),
+                ),
+            );
+        }
+
         Self {
             api_key,
+            uuid,
             event: event.event,
+            distinct_id: event.distinct_id,
             properties,
             timestamp: event.timestamp,
         }
@@ -114,10 +157,21 @@ pub mod tests {
         let inner_event = InnerEvent::new(event, api_key);
 
         // Assert
-        let props = &inner_event.properties.props;
+        let props = &inner_event.properties;
         assert_eq!(
             props.get("$lib_name"),
             Some(&serde_json::Value::String("posthog-rs".to_string()))
         );
     }
+
+    #[test]
+    fn event_structure_is_correct() {
+        let mut event = Event::new("unit test event", "1234");
+        event.insert_prop("key1", "value1").unwrap();
+        let api_key = "test_api_key".to_string();
+        let inner_event = InnerEvent::new(event, api_key);
+        let payload = serde_json::to_string(&inner_event).unwrap();
+
+        println!("{}", payload);
+    }
 }