Add named payload API, group builder, and group! macro (#61)

Client API additions for multi-part observations and groups:
- ObservationPayloadHandle for adding payloads to existing observations
- named_payload(), named_debug(), named_raw_payload() on ObservationBuilder
- GroupBuilder, GroupHandle, SendGroup for observation hierarchies
- group! macro for creating groups with source info
- ExecutionHandle::placeholder() for error paths

Author: Dig-Doug

crates/observation-tools-client/src/execution.rs

@@ -84,6 +84,15 @@ impl ExecutionHandle {
   pub fn base_url(&self) -> &str {
     &self.base_url
   }
+
+  /// Create a placeholder handle (for stub observations when no execution context exists)
+  pub(crate) fn placeholder() -> Self {
+    Self {
+      execution_id: ExecutionId::nil(),
+      uploader_tx: async_channel::unbounded().0,
+      base_url: String::new(),
+    }
+  }
 }
 
 #[napi]

crates/observation-tools-client/src/group.rs

@@ -0,0 +1,178 @@
+//! Group builder and handle types for hierarchical observation grouping
+
+use crate::client::UploaderMessage;
+use crate::context;
+use crate::execution::ExecutionHandle;
+use crate::observation::ObservationBuilder;
+use crate::observation_handle::SendObservation;
+use crate::Error;
+use observation_tools_shared::GroupId;
+use observation_tools_shared::ObservationId;
+use observation_tools_shared::ObservationType;
+use observation_tools_shared::Payload;
+use std::collections::HashMap;
+
+/// Builder for creating groups
+///
+/// Groups are first-class hierarchical containers for observations.
+/// They are themselves observations with `ObservationType::Group`.
+pub struct GroupBuilder {
+  name: String,
+  custom_id: Option<GroupId>,
+  parent_group_id: Option<GroupId>,
+  metadata: HashMap<String, String>,
+}
+
+impl GroupBuilder {
+  /// Create a new group builder with the given name
+  pub fn new(name: impl Into<String>) -> Self {
+    Self {
+      name: name.into(),
+      custom_id: None,
+      parent_group_id: None,
+      metadata: HashMap::new(),
+    }
+  }
+
+  /// Set a custom group ID
+  pub fn id(mut self, id: impl Into<String>) -> Self {
+    self.custom_id = Some(GroupId::from(id.into()));
+    self
+  }
+
+  /// Set the parent group ID (for creating child groups)
+  pub(crate) fn parent(mut self, parent_id: GroupId) -> Self {
+    self.parent_group_id = Some(parent_id);
+    self
+  }
+
+  /// Add metadata to the group
+  pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
+    self.metadata.insert(key.into(), value.into());
+    self
+  }
+
+  /// Build and send the group using the current execution context
+  pub fn build(self) -> SendGroup {
+    match context::get_current_execution() {
+      Some(execution) => self.build_with_execution(&execution),
+      None => {
+        log::trace!(
+          "No execution context available for group '{}'",
+          self.name
+        );
+        SendGroup::stub(Error::NoExecutionContext)
+      }
+    }
+  }
+
+  /// Build and send the group with an explicit execution handle
+  pub fn build_with_execution(self, execution: &ExecutionHandle) -> SendGroup {
+    let group_id = self.custom_id.unwrap_or_else(GroupId::new);
+    let observation_id = ObservationId::new();
+
+    let group_handle = GroupHandle {
+      group_id,
+      execution_id: execution.id(),
+      uploader_tx: execution.uploader_tx.clone(),
+      base_url: execution.base_url().to_string(),
+    };
+
+    // Serialize metadata as the payload
+    let payload = if self.metadata.is_empty() {
+      Payload::json("{}".to_string())
+    } else {
+      Payload::json(serde_json::to_string(&self.metadata).unwrap_or_else(|_| "{}".to_string()))
+    };
+
+    let mut builder = ObservationBuilder::new(self.name)
+      .with_id(observation_id)
+      .observation_type(ObservationType::Group)
+      .execution(execution);
+
+    if let Some(parent_id) = self.parent_group_id {
+      builder = builder.parent_group(parent_id);
+    }
+    for (k, v) in self.metadata {
+      builder = builder.metadata(k, v);
+    }
+
+    let send = builder.send_observation(payload);
+    SendGroup::from_send_observation(group_handle, send)
+  }
+}
+
+/// Handle to a created group
+#[derive(Clone, Debug)]
+#[allow(dead_code)]
+pub struct GroupHandle {
+  pub(crate) group_id: GroupId,
+  pub(crate) execution_id: observation_tools_shared::models::ExecutionId,
+  pub(crate) uploader_tx: async_channel::Sender<UploaderMessage>,
+  pub(crate) base_url: String,
+}
+
+impl GroupHandle {
+  /// Get the group ID
+  pub fn id(&self) -> GroupId {
+    self.group_id.clone()
+  }
+
+  /// Create a child group builder with this group as parent
+  pub fn child(&self, name: impl Into<String>) -> GroupBuilder {
+    GroupBuilder::new(name).parent(self.group_id.clone())
+  }
+
+  /// Construct a GroupHandle from a known ID without creating/sending a group.
+  ///
+  /// This is useful for the tracing layer which already knows span IDs
+  /// and doesn't need to create group observations for every span.
+  pub fn from_id(group_id: GroupId, execution: &ExecutionHandle) -> Self {
+    Self {
+      group_id,
+      execution_id: execution.id(),
+      uploader_tx: execution.uploader_tx.clone(),
+      base_url: execution.base_url().to_string(),
+    }
+  }
+}
+
+/// Result of sending a group, allowing waiting for upload
+pub struct SendGroup {
+  group_handle: GroupHandle,
+  send: SendObservation,
+}
+
+impl SendGroup {
+  fn stub(error: Error) -> Self {
+    Self {
+      group_handle: GroupHandle {
+        group_id: GroupId::new(),
+        execution_id: observation_tools_shared::models::ExecutionId::nil(),
+        uploader_tx: async_channel::unbounded().0,
+        base_url: String::new(),
+      },
+      send: SendObservation::stub(error),
+    }
+  }
+
+  pub(crate) fn from_send_observation(group_handle: GroupHandle, send: SendObservation) -> Self {
+    Self { group_handle, send }
+  }
+
+  /// Wait for the group to be uploaded
+  pub async fn wait_for_upload(mut self) -> crate::error::Result<GroupHandle> {
+    self.send.wait_for_upload().await?;
+    Ok(self.group_handle)
+  }
+
+  /// Get a reference to the group handle
+  pub fn handle(&self) -> &GroupHandle {
+    &self.group_handle
+  }
+
+  /// Consume and return the group handle
+  pub fn into_handle(self) -> GroupHandle {
+    self.group_handle
+  }
+}

crates/observation-tools-client/src/lib.rs

@@ -10,6 +10,7 @@ mod client;
 pub(crate) mod context;
 mod error;
 mod execution;
+mod group;
 mod logger;
 mod observation;
 mod observation_handle;
@@ -26,13 +27,19 @@ pub use error::Error;
 pub use error::Result;
 pub use execution::BeginExecution;
 pub use execution::ExecutionHandle;
+pub use group::GroupBuilder;
+pub use group::GroupHandle;
+pub use group::SendGroup;
 pub use logger::ObservationLogger;
 pub use observation::ObservationBuilder;
 pub use observation_handle::ObservationHandle;
+pub use observation_handle::ObservationPayloadHandle;
 pub use observation_handle::SendObservation;
-// Re-export procedural macro
+// Re-export procedural macros
+pub use observation_tools_macros::group;
 pub use observation_tools_macros::observe;
 // Re-export from shared for convenience
+pub use observation_tools_shared::GroupId;
 pub use observation_tools_shared::Payload;
 pub use observation_tools_shared::PayloadBuilder;
 
@@ -64,3 +71,4 @@ pub fn current_execution() -> Option<ExecutionHandle> {
 pub fn clear_global_execution() {
   context::clear_global_execution()
 }
+

crates/observation-tools-client/src/observation.rs

@@ -4,7 +4,9 @@ use crate::client::ObservationUploadResult;
 use crate::client::UploaderMessage;
 use crate::context;
 use crate::execution::ExecutionHandle;
+use crate::group::GroupHandle;
 use crate::observation_handle::ObservationHandle;
+use crate::observation_handle::ObservationPayloadHandle;
 use crate::observation_handle::SendObservation;
 use crate::Error;
 use napi_derive::napi;
@@ -43,6 +45,8 @@ pub struct ObservationBuilder {
   custom_id: Option<ObservationId>,
   /// Explicit execution handle (overrides context)
   execution: Option<ExecutionHandle>,
+  /// Parent group ID (for group observations)
+  parent_group_id: Option<GroupId>,
 }
 
 impl ObservationBuilder {
@@ -58,6 +62,7 @@ impl ObservationBuilder {
       log_level: LogLevel::Info,
       custom_id: None,
       execution: None,
+      parent_group_id: None,
     }
   }
 
@@ -79,6 +84,12 @@ impl ObservationBuilder {
     self
   }
 
+  /// Add a group to the observation
+  pub fn group(mut self, group: &GroupHandle) -> Self {
+    self.group_ids.push(group.id());
+    self
+  }
+
   /// Add metadata to the observation
   pub fn metadata(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
     self.metadata.insert(key.into(), value.into());
@@ -113,6 +124,12 @@ impl ObservationBuilder {
     self
   }
 
+  /// Set the parent group ID (for group observations)
+  pub(crate) fn parent_group(mut self, id: GroupId) -> Self {
+    self.parent_group_id = Some(id);
+    self
+  }
+
   /// Serialize the value as JSON and send the observation
   ///
   /// Returns a `SendObservation` which allows you to wait for the upload
@@ -143,6 +160,59 @@ impl ObservationBuilder {
     self.send_observation(payload)
   }
 
+  /// Send the observation with a named serde-serialized payload, returning a handle
+  /// that allows adding more named payloads later.
+  pub fn named_payload<T: ?Sized + Serialize + 'static>(
+    self,
+    name: impl Into<String>,
+    value: &T,
+  ) -> ObservationPayloadHandle {
+    if TypeId::of::<T>() == TypeId::of::<Payload>() {
+      panic!("Use named_raw_payload() method to set Payload directly");
+    }
+    let payload = Payload::json(serde_json::to_string(value).unwrap_or_default());
+    self.send_named_observation(name, payload)
+  }
+
+  /// Send the observation with a named Debug-formatted payload
+  pub fn named_debug<T: Debug + ?Sized>(
+    self,
+    name: impl Into<String>,
+    value: &T,
+  ) -> ObservationPayloadHandle {
+    let payload = Payload::debug(format!("{:#?}", value));
+    self.send_named_observation(name, payload)
+  }
+
+  /// Send the observation with a named raw payload
+  pub fn named_raw_payload(self, name: impl Into<String>, payload: Payload) -> ObservationPayloadHandle {
+    self.send_named_observation(name, payload)
+  }
+
+  fn send_named_observation(
+    mut self,
+    name: impl Into<String>,
+    payload: Payload,
+  ) -> ObservationPayloadHandle {
+    let execution = match self.execution.take().or_else(context::get_current_execution) {
+      Some(exec) => exec,
+      None => {
+        let send = SendObservation::stub(Error::NoExecutionContext);
+        return ObservationPayloadHandle::new(
+          send.into_handle(),
+          ExecutionHandle::placeholder(),
+        );
+      }
+    };
+
+    // Send the observation metadata + named payload (single path, no duplication)
+    let send = self.send_with_execution_and_name(payload, name, &execution);
+    let handle = send.into_handle();
+
+    ObservationPayloadHandle::new(handle, execution.clone())
+  }
+
+
   /// Internal method to build and send the observation
   pub(crate) fn send_observation(mut self, payload: Payload) -> SendObservation {
     let Some(execution) = self.execution.take().or_else(context::get_current_execution) else {
@@ -197,7 +267,7 @@ impl ObservationBuilder {
       observation_type: self.observation_type,
       log_level: self.log_level,
       group_ids: self.group_ids,
-      parent_group_id: None,
+      parent_group_id: self.parent_group_id,
       metadata: self.metadata,
       source: self.source,
       parent_span_id,