Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Service trait for properties.
//!
//! Access control is represented in the method types: every entity-scoped
//! method takes a [`ViewReceipt`] or [`EditReceipt`] proving the caller's
//! access, and owner-scoped methods take the caller's identity plus their
//! team-membership receipt. User-facing callers mint receipts through the
//! entity access service at the inbound edge; internal (machine) callers mint
//! via [`EntityAccessReceipt::dangerously_assert_internal_user`], which makes
//! unchecked paths explicit and greppable.
use std::collections::HashMap;
use entity_access::domain::models::{EntityAccessReceipt, MemberTeamRole};
use macro_user_id::user_id::MacroUserIdStr;
use models_properties::EntityType;
use models_properties::api::requests::SetPropertyValue;
use models_properties::api::{
AddPropertyOptionRequest, CreatePropertyDefinitionRequest, UpdatePropertyOptionRequest,
};
use models_properties::service::entity_property_with_definition::EntityPropertyWithDefinition;
use models_properties::service::property_change_source::PropertyChangeSource;
use models_properties::service::property_definition::PropertyDefinition;
use models_properties::service::property_definition_with_options::PropertyDefinitionWithOptions;
use models_properties::service::property_option::PropertyOption;
use models_properties::service::property_value::PropertyValue;
use system_properties::SystemPropertyKey;
use uuid::Uuid;
use super::error::PropertiesErr;
use super::model::{
EditReceipt, EntityOptionUpdateOutcome, EntityPropertyInfo, EntityPropertyOptionSelection,
EntityPropertyOptionUpdate, PropertyOptionReplacePlan, PropertyTargetKey, TagScope, TagSet,
ViewReceipt,
};
/// The caller's team-membership proof, used to scope definition/option/tag
/// operations to the team the caller actually belongs to.
pub type TeamReceipt = EntityAccessReceipt<MemberTeamRole>;
/// The team id a team receipt proves membership of, if any.
pub fn team_id_from_receipt(team: Option<&TeamReceipt>) -> Option<Uuid> {
team.and_then(|receipt| Uuid::parse_str(&receipt.entity().entity_id).ok())
}
/// Service trait for property operations.
pub trait PropertiesService: Send + Sync + 'static {
/// Get all properties attached to an entity, with definitions, values, and
/// options. Tag properties are restricted to the viewer's own and their
/// teams' definitions (the viewer being the receipt's authenticated user).
fn get_entity_properties(
&self,
access: &ViewReceipt,
) -> impl Future<Output = Result<Vec<EntityPropertyInfo>, PropertiesErr>> + Send;
/// Get the tag sets visible to a caller — their personal set plus their
/// teams' sets — with options attached.
fn list_caller_tag_sets(
&self,
user_id: &str,
) -> impl Future<Output = Result<Vec<PropertyDefinitionWithOptions>, PropertiesErr>> + Send;
/// Get a property value for an entity by property definition ID.
/// Returns `None` if the property is not attached to the entity.
fn get_property_value(
&self,
access: &ViewReceipt,
property_definition_id: Uuid,
) -> impl Future<Output = Result<Option<PropertyValue>, PropertiesErr>> + Send;
/// Get a system property value for an entity.
/// Returns `None` if the property is not attached to the entity.
fn get_system_property_value(
&self,
access: &ViewReceipt,
property_key: SystemPropertyKey,
) -> impl Future<Output = Result<Option<PropertyValue>, PropertiesErr>> + Send;
/// Set or update a property value for an entity, or attach a property without a value.
/// Returns the canonical property assignment, definition, and persisted value.
/// Validates property options if the value contains select options.
/// Linking Parent Task / Subtasks additionally requires edit access to the
/// referenced tasks.
fn set_entity_property(
&self,
access: &EditReceipt,
property_definition_id: Uuid,
value: Option<SetPropertyValue>,
) -> impl Future<Output = Result<EntityPropertyWithDefinition, PropertiesErr>> + Send;
/// [`Self::set_entity_property`] that records the outside event behind the
/// change on the published `entity_property.updated`.
fn set_entity_property_with_source(
&self,
access: &EditReceipt,
property_definition_id: Uuid,
value: Option<SetPropertyValue>,
source: Option<PropertyChangeSource>,
) -> impl Future<Output = Result<EntityPropertyWithDefinition, PropertiesErr>> + Send;
/// Append the project's agent assignees to a newly added task, preserving
/// existing assignees and concurrent edits. Both capabilities must belong
/// to the same actor. Publishes assignment changes with the task's attribution.
/// The caller verifies the task's current project membership.
/// Documents that are no longer tasks are ignored.
fn inherit_project_agent_assignees(
&self,
project: &ViewReceipt,
task: &EditReceipt,
) -> impl Future<Output = Result<(), PropertiesErr>> + Send;
/// Add one option to a multi-select entity property value atomically.
/// Attaches the property if needed and dedupes. Validates the option belongs
/// to the (multi-select) property. Prefer this over `set_entity_property`
/// for add/remove of a single option: it composes with concurrent changes
/// instead of clobbering them.
fn add_entity_property_option(
&self,
access: &EditReceipt,
property_definition_id: Uuid,
option_id: Uuid,
) -> impl Future<Output = Result<(), PropertiesErr>> + Send;
/// Remove one option from a multi-select entity property value atomically.
/// A no-op if absent.
fn remove_entity_property_option(
&self,
access: &EditReceipt,
property_definition_id: Uuid,
option_id: Uuid,
) -> impl Future<Output = Result<(), PropertiesErr>> + Send;
/// Get a single property definition by ID, readable by the caller (their own,
/// their team's, or a system property). Returns [`PropertiesErr::NotFound`] if
/// the definition doesn't exist or isn't visible to the caller.
fn get_property_definition(
&self,
property_definition_id: Uuid,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
) -> impl Future<Output = Result<PropertyDefinition, PropertiesErr>> + Send;
/// Apply a complete tag-picker selection across one or more of an entity's
/// multi-select properties in a single transaction, returning each
/// property's final option ids for cache reconciliation.
///
/// Each property change is a delta (options to add / remove) so the whole
/// selection composes with concurrent edits under a per-row lock rather than
/// clobbering them. Validates that every added option belongs to its
/// (multi-select) property before any write; the persistence is
/// all-or-nothing, so a failure on any property rolls back the whole batch.
fn bulk_update_entity_property_options(
&self,
access: &EditReceipt,
updates: Vec<EntityPropertyOptionUpdate>,
) -> impl Future<Output = Result<Vec<EntityPropertyOptionSelection>, PropertiesErr>> + Send;
/// Apply one shared option delta to several entities at once, returning a
/// per-entity outcome aligned to `access` (same length and order).
///
/// The shared delta (`add_option_ids` / `remove_option_ids` on one
/// multi-select `property_definition_id`) is validated once up front; a bad
/// property or option fails the whole call. Each entity is then updated in
/// its own transaction, so the batch is best-effort: an entity whose type
/// does not accept the property, or whose write fails, is reported as
/// [`EntityOptionUpdateOutcome::Failed`] without aborting the rest. Callers
/// mint one [`EditReceipt`] per entity at the edge and pass only the
/// entities the caller may edit; entities the caller cannot edit are handled
/// there, not here.
fn bulk_update_entities_property_options(
&self,
access: &[EditReceipt],
property_definition_id: Uuid,
add_option_ids: Vec<Uuid>,
remove_option_ids: Vec<Uuid>,
) -> impl Future<Output = Result<Vec<EntityOptionUpdateOutcome>, PropertiesErr>> + Send;
/// List property definitions owned by the given team and/or user, sorted by
/// display name. Set `include_system` to true to also include system properties.
/// When `for_entity_type` is provided, definitions that cannot be attached to
/// that entity type are excluded.
fn list_property_definitions(
&self,
team: Option<&TeamReceipt>,
user_id: Option<&MacroUserIdStr<'_>>,
include_system: bool,
for_entity_type: Option<EntityType>,
) -> impl Future<Output = Result<Vec<PropertyDefinition>, PropertiesErr>> + Send;
/// Same as [`Self::list_property_definitions`], but including each definition's
/// select options.
fn list_property_definitions_with_options(
&self,
team: Option<&TeamReceipt>,
user_id: Option<&MacroUserIdStr<'_>>,
include_system: bool,
for_entity_type: Option<EntityType>,
) -> impl Future<Output = Result<Vec<PropertyDefinitionWithOptions>, PropertiesErr>> + Send;
/// Create a property definition owned by the caller (their user property,
/// or their team's when the request has team scope). Fails with
/// [`PropertiesErr::TeamMembershipRequired`] for team scope without a team.
/// Validates the request and creates any select options atomically.
fn create_property_definition(
&self,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
request: &CreatePropertyDefinitionRequest,
) -> impl Future<Output = Result<PropertyDefinition, PropertiesErr>> + Send;
/// Delete a property definition owned by the caller.
///
/// Fails with [`PropertiesErr::NotFound`] if the definition doesn't exist or
/// isn't owned by the caller (their user property or a property of their team),
/// and with [`PropertiesErr::SystemPropertyNotModifiable`] for system properties.
fn delete_property_definition(
&self,
property_definition_id: Uuid,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
) -> impl Future<Output = Result<(), PropertiesErr>> + Send;
/// Get all options for a property definition readable by the caller (for dropdowns).
fn get_property_options(
&self,
property_definition_id: Uuid,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
) -> impl Future<Output = Result<Vec<PropertyOption>, PropertiesErr>> + Send;
/// Batch options for requested definitions readable by the caller.
/// Missing or inaccessible definitions are omitted, including their options.
fn get_property_options_batch(
&self,
property_definition_ids: &[Uuid],
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
) -> impl Future<Output = Result<HashMap<Uuid, Vec<PropertyOption>>, PropertiesErr>> + Send;
/// Add a new option to a select property owned by the caller.
/// Validates the request against the property's data type, including the
/// tag color rules.
fn add_property_option(
&self,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
property_definition_id: Uuid,
request: &AddPropertyOptionRequest,
) -> impl Future<Output = Result<PropertyOption, PropertiesErr>> + Send;
/// Get or create an option by exact value on a property owned by the caller.
/// Preserves existing option metadata and tolerates concurrent creation.
fn get_or_create_property_option(
&self,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
property_definition_id: Uuid,
request: &AddPropertyOptionRequest,
) -> impl Future<Output = Result<PropertyOption, PropertiesErr>> + Send;
/// Update a property option in place (rename / recolor / reorder) on a
/// property owned by the caller. The option id is preserved, so the change
/// is reflected on every entity that references it.
fn update_property_option(
&self,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
property_definition_id: Uuid,
option_id: Uuid,
request: &UpdatePropertyOptionRequest,
) -> impl Future<Output = Result<PropertyOption, PropertiesErr>> + Send;
/// Apply a whole-set option change on a `SelectString` property owned by
/// the caller, in one transaction. Fails with
/// [`PropertiesErr::OptionNotFound`] when a deleted or rewritten option is
/// not on the definition and [`PropertiesErr::DuplicateOptionValue`] when
/// two options would share a value; neither partially applies.
fn replace_property_options(
&self,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
property_definition_id: Uuid,
plan: PropertyOptionReplacePlan,
) -> impl Future<Output = Result<Vec<PropertyOption>, PropertiesErr>> + Send;
/// Delete a property option on a property owned by the caller, stripping
/// its id from every entity value that references it.
fn delete_property_option(
&self,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
property_definition_id: Uuid,
option_id: Uuid,
) -> impl Future<Output = Result<(), PropertiesErr>> + Send;
/// List the caller's tag sets: their personal set, plus their team's set
/// when on a team. Pure read - a scope with no provisioned definition yet
/// returns an empty set.
fn list_tag_sets(
&self,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
) -> impl Future<Output = Result<Vec<TagSet>, PropertiesErr>> + Send;
/// Provision (get-or-create) the caller's tag set for the scope and return
/// it. Fails with [`PropertiesErr::TeamMembershipRequired`] for team scope
/// without a team.
fn ensure_tag_set(
&self,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
scope: TagScope,
) -> impl Future<Output = Result<TagSet, PropertiesErr>> + Send;
/// Share one of the caller's personal labels with their team by moving it
/// into the team tag set, provisioning that set if the team has none yet.
///
/// The option id survives the move, so every entity already carrying the
/// label keeps resolving to it. Fails with
/// [`PropertiesErr::ConflictingTeamLabel`] when the team already has a label
/// of that name (trimmed, case-insensitive), carrying that label so the
/// caller can offer [`Self::merge_tag_option`] instead. Requires the option
/// to be a label in the caller's own tag set and the caller to be on a team.
fn promote_tag_option(
&self,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
option_id: Uuid,
) -> impl Future<Output = Result<PropertyOption, PropertiesErr>> + Send;
/// Replace one of the caller's personal labels with an existing team label:
/// every entity carrying the personal label is retagged with the team label
/// (deduped if it already has both), then the personal label is deleted.
///
/// The team label's name and color win. Requires the source option to be a
/// label in the caller's own tag set and the target to be a label in their
/// team's tag set.
fn merge_tag_option(
&self,
user_id: &MacroUserIdStr<'_>,
team: Option<&TeamReceipt>,
option_id: Uuid,
target_option_id: Uuid,
) -> impl Future<Output = Result<PropertyOption, PropertiesErr>> + Send;
/// Get an entity's stored properties with definitions, values, and options,
/// sorted by display name. Personal tag properties of other users are
/// filtered out. Does not include computed metadata properties
/// (see [`Self::get_entity_metadata_properties`]).
fn get_entity_properties_with_definitions(
&self,
access: &ViewReceipt,
) -> impl Future<Output = Result<Vec<EntityPropertyWithDefinition>, PropertiesErr>> + Send;
/// Get an entity's read-only metadata properties, computed on-the-fly from
/// the entity itself (name, owner, timestamps, ...).
/// Returns `None` when the entity doesn't exist (or the id is malformed);
/// entity types without metadata yield `Some(vec![])`.
fn get_entity_metadata_properties(
&self,
access: &ViewReceipt,
) -> impl Future<Output = Result<Option<Vec<EntityPropertyWithDefinition>>, PropertiesErr>> + Send;
/// Get properties for multiple entities, keyed by entity id and type.
/// An empty `property_ids` fetches all properties for the given entities;
/// otherwise only the requested definitions are returned. Personal tag
/// properties of other users are filtered out per receipt.
fn get_bulk_entity_properties(
&self,
access: &[ViewReceipt],
property_ids: Vec<Uuid>,
) -> impl Future<
Output = Result<
HashMap<PropertyTargetKey, Vec<EntityPropertyWithDefinition>>,
PropertiesErr,
>,
> + Send;
/// Delete all properties attached to an entity.
fn delete_entity_properties(
&self,
access: &EditReceipt,
) -> impl Future<Output = Result<(), PropertiesErr>> + Send;
/// Look up an entity property by its ID, returning the entity it is
/// attached to so the caller can mint an edit receipt for
/// [`Self::delete_entity_property`]. Returns `None` if it doesn't exist.
fn lookup_entity_property(
&self,
entity_property_id: Uuid,
) -> impl Future<Output = Result<Option<PropertyTargetKey>, PropertiesErr>> + Send;
/// Delete a single entity property by its ID. The receipt must be for the
/// entity the property is attached to. Fails when the property doesn't
/// exist, is required for the entity type, or the receipt is for a
/// different entity.
fn delete_entity_property(
&self,
access: &EditReceipt,
entity_property_id: Uuid,
) -> impl Future<Output = Result<(), PropertiesErr>> + Send;
}