Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

17.1 KB
Raw Blame
//! 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: &macro_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(),
    }
}