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.

18.4 KB
Raw Blame
//! Domain models for CRM companies and their related records.

use std::collections::BTreeMap;

use chrono::{DateTime, Utc};
use serde_json::Value;

/// A [`CrmCompany`] bundled with display metadata resolved from
/// `crm_domain_directory` against the primary (earliest-created) domain.
/// `name` / `description` are `None` when no directory row exists or
/// the row is in negative-cache state (NULL fields).
#[derive(Debug, Clone)]
pub struct CrmCompanyForSoup {
    /// The underlying company record.
    pub company: CrmCompany,
    /// Display name: the team-scoped `crm_companies.custom_name` override when
    /// set (manual creation), otherwise the primary domain's directory
    /// entry.
    pub name: Option<String>,
    /// Display description from the primary domain's directory entry.
    pub description: Option<String>,
    /// When the requesting user last viewed this company
    /// (`UserHistory.updatedAt`), or `None` if never viewed. Drives the
    /// soup `viewed_at` / `viewed_updated` sorts and the recently-viewed
    /// feed. `None` for sources that don't resolve view history (search).
    pub viewed_at: Option<DateTime<Utc>>,
}

/// A [`CrmCompany`] bundled with its directory display metadata
/// (same as [`CrmCompanyForSoup`]) plus its full contact list — the
/// shape returned by `GET /crm/companies/{company_id}`. Lets the FE
/// hydrate the company panel in a single round trip instead of
/// composing a soup call with a follow-up contacts call.
#[derive(Debug, Clone)]
pub struct CrmCompanyWithContacts {
    /// The underlying company record (with domains pre-populated).
    pub company: CrmCompany,
    /// Display name: the team-scoped `crm_companies.custom_name` override when
    /// set (manual creation), otherwise the primary domain's directory
    /// entry.
    pub name: Option<String>,
    /// Display description from the primary domain's directory entry.
    pub description: Option<String>,
    /// Contacts attached to this company, subject to the caller's
    /// `include_hidden` flag (non-admins get only visible contacts).
    pub contacts: Vec<CrmContact>,
}

/// A known external company tracked by a team (CRM-style record). A company
/// aggregates zero or more email domains and individual contacts that are
/// considered to belong to the same external party.
///
/// Company display metadata (name, description, icon) lives in
/// `crm_domain_directory` keyed by domain — look it up via
/// [`DomainMetadata`] when needed. Manually created companies may
/// additionally carry a team-scoped `crm_companies.custom_name` override that
/// read paths COALESCE over the directory name.
#[derive(Debug, Clone, serde::Serialize)]
pub struct CrmCompany {
    /// The id of the company
    pub id: uuid::Uuid,
    /// The id of the team that owns this company record
    pub team_id: uuid::Uuid,
    /// Whether email sync is enabled for this company
    pub email_sync: bool,
    /// Whether the company is hidden from CRM listings for the owning
    /// team. Display-only opt-out; setting it to `true` also forces
    /// `email_sync = false` (see
    /// [`crate::domain::service::CrmService::set_company_hidden`]).
    pub hidden: bool,
    /// Earliest known email interaction with this company. Repository
    /// read paths fill this from `crm_companies.first_interaction`, not
    /// the row's lifecycle `created_at`.
    pub created_at: DateTime<Utc>,
    /// Most recent known email interaction with this company. Repository
    /// read paths fill this from `crm_companies.last_interaction`, not
    /// the row's lifecycle `updated_at`.
    pub updated_at: DateTime<Utc>,
    /// All domains associated with this company
    pub domains: Vec<CrmDomain>,
}

/// Cached metadata about a company keyed on its email domain. Resolved
/// by [`CompanyMetadataResolver`] and stored in `crm_domain_directory`.
///
/// Every scalar is `Option` and every list defaults empty: the resolver
/// may succeed with little data, including an all-empty negative-cache row.
/// Unavailable results stay pending for a bounded retry instead.
///
/// [`CompanyMetadataResolver`]: crate::domain::company_metadata_resolver::CompanyMetadataResolver
#[derive(Debug, Clone, Default, PartialEq)]
pub struct DomainMetadata {
    /// Company display name.
    pub name: Option<String>,
    /// Short company description.
    pub description: Option<String>,
    /// Logo / icon URL.
    pub icon_url: Option<String>,
    /// Historical Apollo organization id retained for stored-data compatibility.
    pub apollo_organization_id: Option<String>,
    /// Canonical company website.
    pub website_url: Option<String>,
    /// LinkedIn company URL.
    pub linkedin_url: Option<String>,
    /// Twitter / X URL.
    pub twitter_url: Option<String>,
    /// Facebook URL.
    pub facebook_url: Option<String>,
    /// Primary industry.
    pub industry: Option<String>,
    /// Free-text keywords / tags.
    pub keywords: Vec<String>,
    /// Detected technologies.
    pub technologies: Vec<String>,
    /// Estimated headcount.
    pub estimated_num_employees: Option<i32>,
    /// Estimated annual revenue, in dollars.
    pub annual_revenue: Option<i64>,
    /// Human-readable annual revenue (e.g. "100M").
    pub annual_revenue_printed: Option<String>,
    /// Total funding raised, in dollars.
    pub total_funding: Option<i64>,
    /// Human-readable total funding (e.g. "251.2M").
    pub total_funding_printed: Option<String>,
    /// Latest funding stage (e.g. "Series D").
    pub latest_funding_stage: Option<String>,
    /// Date of the latest funding round.
    pub latest_funding_round_date: Option<DateTime<Utc>>,
    /// Year the company was founded.
    pub founded_year: Option<i32>,
    /// Ticker symbol if publicly traded.
    pub publicly_traded_symbol: Option<String>,
    /// Exchange if publicly traded.
    pub publicly_traded_exchange: Option<String>,
    /// Company phone number.
    pub phone: Option<String>,
    /// Full formatted HQ address.
    pub raw_address: Option<String>,
    /// HQ street address.
    pub street_address: Option<String>,
    /// HQ city.
    pub city: Option<String>,
    /// HQ state / region.
    pub state: Option<String>,
    /// HQ postal code.
    pub postal_code: Option<String>,
    /// HQ country.
    pub country: Option<String>,
    /// Historical provider payload retained alongside the modeled metadata.
    pub raw: Option<Value>,
}

/// A domain (e.g. "acme.com") associated with a [`CrmCompany`]. A company
/// may have many domains.
#[derive(Debug, Clone, serde::Serialize)]
pub struct CrmDomain {
    /// The id of the domain record
    pub id: uuid::Uuid,
    /// The id of the company the domain belongs to
    pub company_id: uuid::Uuid,
    /// The domain (e.g. "acme.com"). Stored lowercased.
    pub domain: String,
    /// When the domain record was created
    pub created_at: DateTime<Utc>,
}

/// A contact (individual external party) belonging to a [`CrmCompany`].
/// Tracked per `(company_id, email)`; `name` is the first non-NULL display
/// name observed across the team's populates.
#[derive(Debug, Clone, serde::Serialize)]
pub struct CrmContact {
    /// The id of the contact record
    pub id: uuid::Uuid,
    /// The id of the company the contact belongs to; `None` for a
    /// contact without a company
    pub company_id: Option<uuid::Uuid>,
    /// The contact's email address; `None` for a manually created
    /// contact added by name alone
    pub email: Option<String>,
    /// Display name observed for the contact, if any
    pub name: Option<String>,
    /// Whether the contact is hidden from CRM listings for the owning
    /// team. Set via [`crate::domain::service::CrmService::set_contact_hidden`]
    /// (individual hide) or cascaded from a company-level hide.
    pub hidden: bool,
    /// Earliest known interaction with this contact
    pub first_interaction: DateTime<Utc>,
    /// Most recent known interaction with this contact
    pub last_interaction: DateTime<Utc>,
    /// When the contact record was created
    pub created_at: DateTime<Utc>,
    /// When the contact record was last updated
    pub updated_at: DateTime<Utc>,
}

/// What a depopulate teardown actually removed. Every field is `false` on
/// the no-op paths (unknown contact, malformed email), so
/// [`Self::removed_anything`] distinguishes a real teardown from a call
/// that found nothing to do — the cleanup job logs on that basis.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct DepopulateContactOutcome {
    /// The `crm_contact_sources` row for this `(contact, link)` was deleted.
    pub source_deleted: bool,
    /// The `crm_contacts` row was deleted: no sibling source rows remained
    /// and the contact was not `manually_created`.
    pub contact_deleted: bool,
    /// The `crm_companies` row was deleted (cascading to `crm_domains`): no
    /// sibling contacts remained and the company was neither killswitched
    /// (`email_sync = false`) nor `manually_created`.
    pub company_deleted: bool,
}

impl DepopulateContactOutcome {
    /// Whether the teardown deleted any row at all.
    pub fn removed_anything(&self) -> bool {
        self.source_deleted || self.contact_deleted || self.company_deleted
    }
}

/// Result of [`crate::domain::companies_repo::CompaniesRepository::crm_scope_precheck`].
///
/// Carries the per-input authorization status the caller (`EmailService`)
/// needs to either accept or reject a CRM-scoped query before it runs.
#[derive(Debug, Clone)]
pub struct CrmScopePrecheck {
    /// `team_crm_settings.crm_enabled` for the requesting team. `false`
    /// when the team's row exists with `crm_enabled = false`, *or* when no
    /// row exists at all (older teams predating `team_crm_settings`).
    pub crm_enabled: bool,
    /// One row per requested domain, in the same order as the input list.
    /// **Exception:** when `crm_enabled = false`, this vec is empty —
    /// the email service short-circuits on the killswitch before
    /// consulting per-input rows, so the per-domain probes are skipped
    /// and callers must not assume length parity with the input list
    /// without first checking `crm_enabled`.
    pub domains: Vec<CrmDomainStatus>,
    /// One row per requested address, in the same order as the input
    /// list. Same `crm_enabled = false` exception as [`Self::domains`].
    pub addresses: Vec<CrmAddressStatus>,
}

/// Per-domain authorization status. See [`CrmScopePrecheck`].
#[derive(Debug, Clone)]
pub struct CrmDomainStatus {
    /// The domain as supplied (lowercased).
    pub domain: String,
    /// Whether a `crm_domains` row exists for this `(team_id, domain)`.
    pub exists: bool,
    /// `crm_companies.hidden` for the company owning the matched
    /// `crm_domains` row. `false` when `!exists`.
    pub company_hidden: bool,
    /// `crm_companies.email_sync` for the company owning the matched
    /// `crm_domains` row. `false` when `!exists`.
    pub email_sync: bool,
}

/// Per-address authorization status. See [`CrmScopePrecheck`].
#[derive(Debug, Clone)]
pub struct CrmAddressStatus {
    /// The address as supplied (lowercased).
    pub address: String,
    /// Whether a `crm_contacts` row exists whose company belongs to the
    /// requesting team. Cross-team contacts (same email under a different
    /// team's company) are reported as `exists = false` so existence
    /// doesn't leak across teams.
    pub exists: bool,
    /// Whether any matching team contact is hidden. `false` when `!exists`.
    pub contact_hidden: bool,
    /// Whether any matching contact's company is hidden. `false` when `!exists`.
    pub company_hidden: bool,
    /// Whether every matching contact's company enables email sync. `false` when `!exists`.
    pub email_sync: bool,
}

/// Minimum team role required for a CRM governance capability. Members
/// can edit visible CRM records (e.g. company properties), but the
/// governance capabilities these settings gate stay restricted to
/// admin (default) vs owner. Maps to the `team_role` Postgres enum;
/// `member` is deliberately not representable.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
#[cfg_attr(feature = "outbound", derive(sqlx::Type))]
#[cfg_attr(
    feature = "outbound",
    sqlx(type_name = "team_role", rename_all = "lowercase")
)]
#[cfg_attr(feature = "axum", derive(utoipa::ToSchema))]
pub enum CrmPermissionRole {
    /// Team admins and owners.
    Admin,
    /// Team owners only.
    Owner,
}

impl CrmPermissionRole {
    /// The `team_role` enum literal for SQL binds (queries bind text and
    /// cast with `::team_role`).
    pub fn as_db_str(&self) -> &'static str {
        match self {
            CrmPermissionRole::Admin => "admin",
            CrmPermissionRole::Owner => "owner",
        }
    }
}

/// Team-level CRM configuration stored on `team_crm_settings`
/// (everything except the `crm_enabled` killswitch, which stays owned
/// by the teams crate).
#[derive(Debug, Clone)]
pub struct CrmTeamSettings {
    /// Who can change the deal stage set in CRM settings.
    pub edit_stages_role: CrmPermissionRole,
    /// Who can move deals out of a closed stage.
    pub move_closed_deals_role: CrmPermissionRole,
    /// Who can delete (hide) CRM records.
    pub delete_records_role: CrmPermissionRole,
    /// Stage option ids counting as closed deals; `None` = the client
    /// falls back to its label heuristic.
    pub closed_stage_ids: Option<Vec<uuid::Uuid>>,
    /// System stage option id to team stage option id for seeded stages.
    /// Entries may outlive their stage; readers check membership in the set.
    pub legacy_stage_ids: BTreeMap<uuid::Uuid, uuid::Uuid>,
    /// Team saved views — an opaque JSON array owned by the frontend.
    pub team_views: Value,
    /// Team view applied by default when a member opens the CRM view.
    pub default_team_view_id: Option<String>,
    /// Whether email sync keeps personal-provider addresses (gmail.com
    /// etc.) out of the CRM. When off, sync files them as contacts
    /// without a company.
    pub exclude_personal_emails: bool,
}

impl Default for CrmTeamSettings {
    fn default() -> Self {
        Self {
            edit_stages_role: CrmPermissionRole::Admin,
            move_closed_deals_role: CrmPermissionRole::Admin,
            delete_records_role: CrmPermissionRole::Admin,
            closed_stage_ids: None,
            legacy_stage_ids: BTreeMap::new(),
            team_views: Value::Array(Vec::new()),
            default_team_view_id: None,
            exclude_personal_emails: true,
        }
    }
}

/// A domain a team keeps out of email sync.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CrmBlockedDomain {
    /// The blocked domain, lowercase.
    pub domain: String,
    /// When it was added.
    pub created_at: DateTime<Utc>,
}

/// Field-wise partial update of [`CrmTeamSettings`]. Outer `None` =
/// leave the column unchanged; for the two nullable columns the inner
/// `None` clears the value. `team_views` is replaced whole (last-wins).
#[derive(Debug, Clone, Default)]
pub struct CrmTeamSettingsPatch {
    /// New `edit_stages_role`, if provided.
    pub edit_stages_role: Option<CrmPermissionRole>,
    /// New `move_closed_deals_role`, if provided.
    pub move_closed_deals_role: Option<CrmPermissionRole>,
    /// New `delete_records_role`, if provided.
    pub delete_records_role: Option<CrmPermissionRole>,
    /// New `closed_stage_ids`; `Some(None)` clears to the heuristic.
    pub closed_stage_ids: Option<Option<Vec<uuid::Uuid>>>,
    /// Replacement `legacy_stage_ids` map.
    pub legacy_stage_ids: Option<BTreeMap<uuid::Uuid, uuid::Uuid>>,
    /// Replacement `team_views` array.
    pub team_views: Option<Value>,
    /// New `default_team_view_id`; `Some(None)` clears it.
    pub default_team_view_id: Option<Option<String>>,
    /// New `exclude_personal_emails`, if provided.
    pub exclude_personal_emails: Option<bool>,
}

/// Errors that can occur in the CRM domain.
#[derive(Debug, thiserror::Error)]
pub enum CrmError {
    /// Storage layer error
    #[error("Storage layer error {0}")]
    StorageLayerError(#[from] anyhow::Error),
    /// Company id is not owned by the requesting team.
    #[error("crm company not found for team")]
    CompanyNotFoundForTeam,
    /// Contact id is not owned by the requesting team.
    #[error("crm contact not found for team")]
    ContactNotFoundForTeam,
    /// Request rejected for a client-side reason (e.g. blank comment text).
    #[error("{0}")]
    InvalidRequest(String),
    /// The request asks for hidden CRM rows but the caller's team role is
    /// below admin/owner.
    #[error("Querying hidden CRM companies requires admin/owner team role")]
    AdminRoleRequired,
    /// The request changes governance fields of the team CRM settings
    /// (permission thresholds, closed stages) but the caller's team role
    /// is below admin/owner.
    #[error("changing crm permission or stage settings requires admin/owner team role")]
    SettingsAdminRequired,
    /// Caller's team role is below the team's `edit_stages_role`.
    #[error("editing deal stages requires the {} team role", .0.as_db_str())]
    StageEditRoleRequired(CrmPermissionRole),
    /// Tried to mutate a CRM company in a way that contradicts its
    /// `hidden = true` state — currently raised when attempting to
    /// re-enable `email_sync` on a hidden company.
    #[error("crm company is hidden")]
    CompanyHidden,
    /// The team already tracks a company for the requested domain.
    #[error("a crm company already exists for this domain")]
    CompanyAlreadyExistsForTeam,
    /// The company already has a contact with the requested email.
    #[error("a crm contact with this email already exists for the company")]
    ContactAlreadyExistsForCompany,
    /// The team-level `team_crm_settings.crm_enabled` killswitch is off.
    #[error("crm is not enabled for this team")]
    CrmDisabledForTeam,
    /// Entity access receipt did not contain a valid team UUID.
    #[error("invalid team id in entity access receipt")]
    InvalidTeamId,
}

/// Contact fields plus the owning team/company and the viewer's history.
#[derive(Debug, Clone)]
pub struct CrmContactForSoup {
    /// The original team-owned contact; its identity is never merged.
    pub contact: CrmContact,
    /// Team owning the company/contact record.
    pub team_id: uuid::Uuid,
    /// The company's display name (team override, directory name, or
    /// domain); `None` for a contact without a company.
    pub company_name: Option<String>,
    /// When this viewer last opened this particular contact record.
    pub viewed_at: Option<DateTime<Utc>>,
}