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
//! Toolset inbound adapter for the CRM domain.
//!
//! Exposes team-scoped CRM company tools (`ListCompanies`, `GetCompany`,
//! `CreateCompany`, `CreateContact`) to AI agents. The company's own
//! properties (its Stage, Owner, Revenue and custom properties) are written
//! through the properties toolset's `SetEntityProperty` with
//! `entity_type = company`. Pipelines, whose entries carry their own stage
//! and fields, have their own tools in [`pipelines`].
mod create_company;
mod create_contact;
mod get_company;
mod list_companies;
pub mod pipelines;
pub mod transfer;
#[cfg(test)]
mod test;
use std::collections::HashMap;
use std::sync::Arc;
use ai_toolset::{AsyncToolCollection, RequestContext, ToolCallError};
use entity_access::domain::{
models::{
AccessError, Entity, EntityAccessReceipt, EntityPermission, EntityType, MemberTeamRole,
TeamRole, ViewAccessLevel,
},
ports::EntityAccessService,
};
use models_properties::DataType;
use models_properties::service::entity_property_with_definition::EntityPropertyWithDefinition;
use models_properties::service::property_option::PropertyOptionValue;
use models_properties::service::property_value::PropertyValue;
use properties::PropertiesService;
use schemars::JsonSchema;
use serde::Serialize;
use system_properties::{StageOption, SystemPropertyKey};
use uuid::Uuid;
use crate::domain::{
auth::{CrmCompanyReceipt, CrmTeamReceipt},
model::CrmError,
service::CrmService,
stages::CRM_TEAM_STAGE_DEFINITION_NAME,
};
pub use create_company::{CreateCompany, CreateCompanyResponse};
pub use create_contact::{CreateContact, CreateContactResponse};
pub use get_company::{GetCompany, GetCompanyResponse};
pub use list_companies::{ListCompanies, ListCompaniesResponse};
/// Service context for CRM AI tools.
pub struct CrmToolContext<CSvc, ESvc, PSvc>
where
CSvc: CrmService,
ESvc: EntityAccessService,
PSvc: PropertiesService,
{
/// The CRM service used to read company records.
pub service: Arc<CSvc>,
/// The entity access service used to resolve the caller's team
/// membership and CRM entity permissions.
pub entity_access_service: Arc<ESvc>,
/// The properties domain service used to read company property values
/// (Stage / Owner / Revenue plus custom properties) and the team's
/// property definitions.
pub properties: Arc<PSvc>,
}
impl<CSvc, ESvc, PSvc> Clone for CrmToolContext<CSvc, ESvc, PSvc>
where
CSvc: CrmService,
ESvc: EntityAccessService,
PSvc: PropertiesService,
{
fn clone(&self) -> Self {
Self {
service: self.service.clone(),
entity_access_service: self.entity_access_service.clone(),
properties: self.properties.clone(),
}
}
}
impl<CSvc, ESvc, PSvc> CrmToolContext<CSvc, ESvc, PSvc>
where
CSvc: CrmService,
ESvc: EntityAccessService,
PSvc: PropertiesService,
{
/// Create a new CRM tool context.
pub fn new(service: CSvc, entity_access_service: ESvc, properties: Arc<PSvc>) -> Self {
Self {
service: Arc::new(service),
entity_access_service: Arc::new(entity_access_service),
properties,
}
}
}
/// Create the CRM toolset.
pub fn crm_toolset<CSvc, ESvc, PSvc>() -> AsyncToolCollection<CrmToolContext<CSvc, ESvc, PSvc>>
where
CSvc: CrmService,
ESvc: EntityAccessService,
PSvc: PropertiesService,
{
AsyncToolCollection::new()
.add_tool::<ListCompanies, CrmToolContext<CSvc, ESvc, PSvc>>()
.add_tool::<GetCompany, CrmToolContext<CSvc, ESvc, PSvc>>()
.add_tool::<CreateCompany, CrmToolContext<CSvc, ESvc, PSvc>>()
.add_tool::<CreateContact, CrmToolContext<CSvc, ESvc, PSvc>>()
}
/// A company's own Stage property: the select option id currently set plus its
/// human-readable label.
#[derive(Debug, Clone, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ToolCompanyStage {
/// The stage property option id (usable with SetEntityProperty).
pub option_id: Uuid,
/// The stage's display label (e.g. "Lead", "Customer").
pub label: String,
}
/// The builtin CRM company property values extracted from a company's
/// entity properties.
#[derive(Debug, Default)]
pub(crate) struct CompanyCrmProps {
pub(crate) stage: Option<ToolCompanyStage>,
pub(crate) owner_user_id: Option<String>,
pub(crate) revenue: Option<f64>,
}
/// The catalog of stage options available to a team: the system Stage
/// definition's options plus any team-scoped definition named "Stage"
/// (teams can customize their pipeline stages).
#[derive(Debug, Default)]
pub(crate) struct StageOptionCatalog {
/// option id -> label
labels: HashMap<Uuid, String>,
/// Ids of team-scoped select definitions named "Stage". Teams with a
/// customized pipeline store their stage values under one of these
/// definitions instead of the system Stage definition, so property
/// fetches filtered by definition id must include them.
team_stage_definition_ids: Vec<Uuid>,
}
impl StageOptionCatalog {
/// Resolve a stage option id to its label. Falls back to the builtin
/// [`StageOption`] constants when the id isn't in the catalog.
pub(crate) fn label_for(&self, option_id: Uuid) -> Option<String> {
self.labels
.get(&option_id)
.cloned()
.or_else(|| StageOption::from_uuid(option_id).map(|s| s.display_value().to_string()))
}
/// Resolve a user-supplied `stage` filter (an option id or a label,
/// matched case-insensitively) to the set of matching option ids.
pub(crate) fn matching_option_ids(&self, stage: &str) -> Vec<Uuid> {
let trimmed = stage.trim();
if let Ok(id) = Uuid::parse_str(trimmed) {
return vec![id];
}
self.labels
.iter()
.filter(|(_, label)| label.eq_ignore_ascii_case(trimmed))
.map(|(id, _)| *id)
.collect()
}
/// Ids of the team-scoped "Stage" definitions (empty when the team
/// only uses the system Stage definition).
pub(crate) fn team_stage_definition_ids(&self) -> &[Uuid] {
&self.team_stage_definition_ids
}
/// The distinct stage labels known to this team, for actionable error
/// messages.
pub(crate) fn known_labels(&self) -> Vec<String> {
let mut labels: Vec<String> = self.labels.values().cloned().collect();
labels.sort();
labels.dedup();
labels
}
}
/// Load the stage option catalog for the team proven by `team`: options of
/// the system Stage definition (id `00000001-0000-0000-0000-000000000010`)
/// plus any team-scoped select definition named "Stage".
pub(crate) async fn load_stage_option_catalog<PSvc>(
properties: &PSvc,
team: &properties::TeamReceipt,
) -> Result<StageOptionCatalog, ToolCallError>
where
PSvc: PropertiesService,
{
let defs = properties
.list_property_definitions_with_options(Some(team), None, true, None)
.await
.map_err(|e| ToolCallError {
description: "failed to load the team's stage options".to_string(),
internal_error: e.into(),
})?;
let mut labels = HashMap::new();
let mut team_stage_definition_ids = Vec::new();
for def in defs {
let is_stage_definition = def.definition.id == SystemPropertyKey::STAGE_UUID
|| (def.definition.display_name == CRM_TEAM_STAGE_DEFINITION_NAME
&& matches!(
def.definition.data_type,
DataType::SelectString | DataType::SelectNumber
));
if !is_stage_definition {
continue;
}
if def.definition.id != SystemPropertyKey::STAGE_UUID {
team_stage_definition_ids.push(def.definition.id);
}
for option in def.property_options {
let label = match option.value {
PropertyOptionValue::String(s) => s,
PropertyOptionValue::Number(n) => n.to_string(),
};
labels.insert(option.id, label);
}
}
// Make sure the builtin defaults are always resolvable, even if the
// seed rows are missing from this environment.
for stage in [
StageOption::Lead,
StageOption::Qualified,
StageOption::Demo,
StageOption::Trial,
StageOption::Negotiation,
StageOption::Customer,
StageOption::Churned,
] {
labels
.entry(stage.uuid())
.or_insert_with(|| stage.display_value().to_string());
}
Ok(StageOptionCatalog {
labels,
team_stage_definition_ids,
})
}
/// Extract the builtin CRM props (Stage / Owner / Revenue) from a
/// company's entity properties. The stage may live on the system Stage
/// definition or on a team-scoped select definition named "Stage";
/// teams with customized pipelines use the latter, so its value wins
/// over one set under the system definition.
pub(crate) fn extract_company_crm_props(
props: &[EntityPropertyWithDefinition],
stages: &StageOptionCatalog,
) -> CompanyCrmProps {
let mut out = CompanyCrmProps::default();
let mut system_stage: Option<ToolCompanyStage> = None;
let mut team_stage: Option<ToolCompanyStage> = None;
for prop in props {
let definition_id = prop.property.property_definition_id;
if definition_id == SystemPropertyKey::COMPANY_OWNER_UUID {
if let Some(PropertyValue::EntityRef(refs)) = &prop.value {
out.owner_user_id = refs.first().map(|r| r.entity_id.clone());
}
continue;
}
if definition_id == SystemPropertyKey::REVENUE_UUID {
if let Some(PropertyValue::Num(n)) = prop.value {
out.revenue = Some(n);
}
continue;
}
let is_system_stage = definition_id == SystemPropertyKey::STAGE_UUID;
let is_team_stage = !is_system_stage
&& (stages.team_stage_definition_ids.contains(&definition_id)
|| prop.definition.display_name == CRM_TEAM_STAGE_DEFINITION_NAME);
let slot = if is_system_stage {
&mut system_stage
} else if is_team_stage {
&mut team_stage
} else {
continue;
};
if slot.is_none()
&& let Some(PropertyValue::SelectOption(option_ids)) = &prop.value
&& let Some(option_id) = option_ids.first().copied()
{
// Prefer the options attached to the property itself, then
// the team catalog / builtin defaults.
let label = prop
.options
.as_ref()
.and_then(|options| {
options
.iter()
.find(|o| o.id == option_id)
.map(|o| match &o.value {
PropertyOptionValue::String(s) => s.clone(),
PropertyOptionValue::Number(n) => n.to_string(),
})
})
.or_else(|| stages.label_for(option_id))
.unwrap_or_else(|| option_id.to_string());
*slot = Some(ToolCompanyStage { option_id, label });
}
}
out.stage = team_stage.or(system_stage);
out
}
/// Properties view receipts for a batch of company ids
/// (`entity_type = company`). Asserted rather than minted: callers only pass
/// company ids whose access was already verified through the CRM seam (the
/// caller's own team listing, or a company permission check) — re-checking
/// each company here would repeat that lookup per company.
pub(crate) fn company_view_receipts(
user_id: ¯o_user_id::user_id::MacroUserIdStr<'static>,
company_ids: impl IntoIterator<Item = Uuid>,
) -> Vec<properties::ViewReceipt> {
company_ids
.into_iter()
.map(|id| {
EntityAccessReceipt::<ViewAccessLevel>::dangerously_assert_authenticated_user(
user_id.clone(),
&id.to_string(),
EntityType::CrmCompany,
)
})
.collect()
}
/// Resolve the caller's team and mint a member-level team receipt for
/// CRM listing calls. Errors with an actionable message when the caller
/// has no team.
pub(crate) async fn caller_team_receipt<ESvc>(
entity_access_service: &ESvc,
request_context: &RequestContext,
) -> Result<(CrmTeamReceipt<MemberTeamRole>, TeamRole), ToolCallError>
where
ESvc: EntityAccessService,
{
let team_info = entity_access_service
.get_user_team(&request_context.user_id)
.await
.map_err(team_access_error)?;
let Some(team_info) = team_info else {
return Err(ToolCallError {
description: "user is not in a team, so there is no team CRM to query".to_string(),
internal_error: anyhow::anyhow!("user is not in a team"),
});
};
let receipt = EntityAccessReceipt::try_new_authenticated_user(
request_context.user_id.clone(),
Entity {
entity_id: team_info.team_id.to_string(),
entity_type: EntityType::Team,
},
EntityPermission::TeamRole {
role: team_info.role,
},
)
.map_err(team_access_error)?;
let receipt = CrmTeamReceipt::from_team_receipt(receipt).map_err(crm_error)?;
Ok((receipt, team_info.role))
}
/// Resolve the caller's permission on a CRM company (derived from their
/// role on the owning team) and mint a view receipt for it, returning the
/// owning team id. Access failures collapse to "not found" so company ids
/// can't be probed across teams.
pub(crate) async fn company_view_receipt<ESvc>(
entity_access_service: &ESvc,
request_context: &RequestContext,
company_id: Uuid,
) -> Result<(CrmCompanyReceipt<ViewAccessLevel>, Uuid), ToolCallError>
where
ESvc: EntityAccessService,
{
let company_id = company_id.to_string();
let (permission, team_id, team_role) = match entity_access_service
.get_crm_entity_permission_with_team(
Some(&request_context.user_id),
&company_id,
EntityType::CrmCompany,
)
.await
{
Ok(triple) => triple,
Err(
AccessError::Unauthorized
| AccessError::UnauthorizedWithMessage(_)
| AccessError::NotFound(_),
) => return Err(company_not_found()),
Err(e) => {
return Err(ToolCallError {
description: "failed to verify access to the CRM company".to_string(),
internal_error: e.into(),
});
}
};
if !permission.satisfies::<ViewAccessLevel>() {
return Err(company_not_found());
}
let receipt = EntityAccessReceipt::try_new_authenticated_user(
request_context.user_id.clone(),
Entity {
entity_id: company_id,
entity_type: EntityType::CrmCompany,
},
permission,
)
.map_err(|e| ToolCallError {
description: "failed to verify access to the CRM company".to_string(),
internal_error: e.into(),
})?;
Ok((CrmCompanyReceipt::new(receipt, team_id, team_role), team_id))
}
fn company_not_found() -> ToolCallError {
ToolCallError {
description: "CRM company not found or not accessible to the caller's team".to_string(),
internal_error: anyhow::anyhow!("crm company not found or not accessible"),
}
}
/// Map an [`AccessError`] into an actionable tool error.
pub(crate) fn team_access_error(err: AccessError) -> ToolCallError {
let description = match err {
AccessError::Unauthorized | AccessError::UnauthorizedWithMessage(_) => {
"user is not a member of a team"
}
AccessError::NotFound(_) => "team not found",
AccessError::BadRequest(_) => "invalid team membership",
AccessError::Unavailable(_) | AccessError::Internal(_) => {
"failed to verify team membership"
}
};
ToolCallError {
description: description.to_string(),
internal_error: err.into(),
}
}
/// Map a [`CrmError`] into an actionable tool error.
pub(crate) fn crm_error(err: CrmError) -> ToolCallError {
ToolCallError {
description: crm_error_description(&err),
internal_error: err.into(),
}
}
/// What went wrong, in words the model can act on.
pub(crate) fn crm_error_description(err: &CrmError) -> String {
match err {
CrmError::CompanyNotFoundForTeam => {
"CRM company not found for the caller's team".to_string()
}
CrmError::ContactNotFoundForTeam => {
"CRM contact not found for the caller's team".to_string()
}
CrmError::InvalidRequest(msg) => msg.clone(),
CrmError::CrmDisabledForTeam => "CRM is turned off for the caller's team".to_string(),
CrmError::CompanyAlreadyExistsForTeam => {
"the team already tracks a company with that domain".to_string()
}
CrmError::ContactAlreadyExistsForCompany => {
"the company already has a contact with that email".to_string()
}
CrmError::StageEditRoleRequired(role) => format!(
"editing deal stages requires the {} team role",
role.as_db_str()
),
_ => "CRM request failed".to_string(),
}
}