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.

41.3 KB
Raw Blame
pub use channel_sender::ChannelSender;
use chrono::{DateTime, Utc};
#[cfg(feature = "list")]
use item_filters::ast::{
    LiteralTree,
    channel::{ChannelLiteral, ChannelThreadLiteral},
};
#[cfg(any(feature = "list", feature = "outbound"))]
use macro_user_id::email::ReadEmailParts;
use macro_user_id::user_id::MacroUserIdStr;
use models_pagination::{CreatedAt, CursorVal, Identify, SortOn};
#[cfg(feature = "list")]
use models_pagination::{Query, SimpleSortMethod};
use serde::{Deserialize, Serialize};
use std::collections::{HashMap, HashSet};
use uuid::Uuid;

pub use bot_id::BotId;

/// Actor identity for channel mutations.
pub type Sender = ChannelSender<'static>;

/// Public bot profile attached to bot-authored messages.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct BotSenderProfile {
    /// Bot display name.
    pub name: String,
    /// Bot avatar URL.
    pub avatar_url: Option<String>,
}

/// Filter for the type of channel attachments to return.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum ChannelAttachmentType {
    /// Static file attachments (images, videos).
    Static,
    /// Document storage service attachments.
    Dss,
}

/// Notification state filters shared with all other item types.
pub use item_filters::NotificationFilters;

/// A top-level message with thread info, reactions, and attachments.
#[derive(Debug, Clone)]
pub struct ChannelMessage {
    /// Message id.
    pub id: Uuid,
    /// Channel this message belongs to.
    pub channel_id: Uuid,
    /// User who sent the message.
    pub sender_id: String,
    /// For an agent (bot) message, the id of the user who triggered it.
    pub triggered_by: Option<String>,
    /// Bot profile when the sender is a bot.
    pub bot_profile: Option<BotSenderProfile>,
    /// Message body.
    pub content: String,
    /// When the message was created.
    pub created_at: DateTime<Utc>,
    /// When the message was last updated.
    pub updated_at: DateTime<Utc>,
    /// When the message was edited (if ever).
    pub edited_at: Option<DateTime<Utc>>,
    /// When the message was soft-deleted (if ever).
    pub deleted_at: Option<DateTime<Utc>>,
    /// Thread metadata and preview replies.
    pub thread: ThreadInfo,
    /// Aggregated reactions on this message.
    pub reactions: Vec<CountedReaction>,
    /// Attachments on this message.
    pub attachments: Vec<MessageAttachment>,
}

impl Identify for ChannelMessage {
    type Id = Uuid;

    fn id(&self) -> Self::Id {
        self.id
    }
}

/// Lightweight channel message used when rendering a channel as an AI attachment.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RecentChannelMessage {
    /// Message id.
    pub message_id: Uuid,
    /// Thread parent id, if this message is a reply.
    pub thread_id: Option<Uuid>,
    /// Sender actor id.
    pub sender_id: String,
    /// Message body.
    pub content: String,
    /// Message creation timestamp.
    pub created_at: DateTime<Utc>,
    /// Message update timestamp.
    pub updated_at: DateTime<Utc>,
    /// Message deletion timestamp, if any.
    pub deleted_at: Option<DateTime<Utc>>,
    /// Message mentions formatted as `{ENTITY_TYPE}:{ENTITY_ID}`.
    pub mentions: Vec<String>,
}

impl SortOn<CreatedAt> for ChannelMessage {
    fn sort_on(sort_type: CreatedAt) -> impl FnMut(&Self) -> CursorVal<CreatedAt> {
        move |msg| CursorVal {
            sort_type,
            last_val: msg.created_at,
        }
    }
}

/// Thread metadata + preview replies for a top-level message.
#[derive(Debug, Clone)]
pub struct ThreadInfo {
    /// Total number of replies in the thread.
    pub reply_count: i64,
    /// Timestamp of the most recent reply.
    pub latest_reply_at: Option<DateTime<Utc>>,
    /// Oldest N replies for the collapsed thread preview.
    pub preview: Vec<ThreadReply>,
}

/// A reply shown in a thread preview.
#[derive(Debug, Clone)]
pub struct ThreadReply {
    /// Reply id.
    pub id: Uuid,
    /// User who sent the reply.
    pub sender_id: String,
    /// For an agent (bot) reply, the id of the user who triggered it.
    pub triggered_by: Option<String>,
    /// Bot profile when the sender is a bot.
    pub bot_profile: Option<BotSenderProfile>,
    /// Reply body.
    pub content: String,
    /// When the reply was created.
    pub created_at: DateTime<Utc>,
    /// When the reply was last updated.
    pub updated_at: DateTime<Utc>,
    /// When the reply was edited (if ever).
    pub edited_at: Option<DateTime<Utc>>,
    /// Aggregated reactions on this reply.
    pub reactions: Vec<CountedReaction>,
    /// Attachments on this reply.
    pub attachments: Vec<MessageAttachment>,
}

/// A reaction emoji with the list of users who reacted.
#[derive(Debug, Clone, Serialize)]
pub struct CountedReaction {
    /// The emoji string.
    pub emoji: String,
    /// User ids who added this reaction.
    pub users: Vec<String>,
}

/// Message details needed to notify its author about a new reaction.
#[derive(Debug, Clone)]
pub struct ReactionMessageContext {
    /// Message author.
    pub sender: Sender,
    /// Root thread id when this message is a reply.
    pub thread_id: Option<Uuid>,
    /// Macro Markdown message body.
    pub content: String,
}

/// An attachment on a message.
#[derive(Debug, Clone)]
pub struct MessageAttachment {
    /// Attachment id.
    pub id: Uuid,
    /// Type of attached entity (e.g. "document").
    pub entity_type: String,
    /// Id of the attached entity.
    pub entity_id: String,
    /// Optional width (for images).
    pub width: Option<i32>,
    /// Optional height (for images).
    pub height: Option<i32>,
    /// When the attachment was created.
    pub created_at: DateTime<Utc>,
}

/// An attachment in a channel (for the channel-level attachments listing).
#[derive(Debug, Clone)]
pub struct ChannelAttachment {
    /// Attachment id.
    pub id: Uuid,
    /// Channel this attachment belongs to.
    pub channel_id: Uuid,
    /// Message this attachment is on.
    pub message_id: Uuid,
    /// The user who sent the message containing this attachment.
    pub sender_id: String,
    /// Type of attached entity (e.g. "document").
    pub entity_type: String,
    /// Id of the attached entity.
    pub entity_id: String,
    /// Optional width (for images).
    pub width: Option<i32>,
    /// Optional height (for images).
    pub height: Option<i32>,
    /// When the attachment was created.
    pub created_at: DateTime<Utc>,
}

impl Identify for ChannelAttachment {
    type Id = Uuid;

    fn id(&self) -> Self::Id {
        self.id
    }
}

impl SortOn<CreatedAt> for ChannelAttachment {
    fn sort_on(sort_type: CreatedAt) -> impl FnMut(&Self) -> CursorVal<CreatedAt> {
        move |a| CursorVal {
            sort_type,
            last_val: a.created_at,
        }
    }
}

/// Role of a channel participant.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
#[cfg_attr(feature = "outbound", derive(sqlx::Type))]
#[cfg_attr(
    feature = "outbound",
    sqlx(type_name = "comms_participant_role", rename_all = "lowercase")
)]
pub enum ParticipantRole {
    /// Channel owner.
    Owner,
    /// Channel admin.
    Admin,
    /// Regular member.
    #[default]
    Member,
}

impl std::str::FromStr for ParticipantRole {
    type Err = String;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        match s {
            "owner" => Ok(Self::Owner),
            "admin" => Ok(Self::Admin),
            "member" => Ok(Self::Member),
            other => Err(format!("unknown participant role: {other}")),
        }
    }
}

/// An active participant in a channel.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChannelParticipant {
    /// Channel id.
    pub channel_id: Uuid,
    /// User id.
    pub user_id: String,
    /// Role in the channel.
    pub role: ParticipantRole,
    /// When the user joined.
    pub joined_at: DateTime<Utc>,
    /// When the user left (None if still active).
    pub left_at: Option<DateTime<Utc>>,
}

/// A reference to an attachment entity originating from a channel message.
#[derive(Debug, Clone, PartialEq)]
pub struct AttachmentChannelReference {
    /// Channel that contains the message.
    pub channel_id: Uuid,
    /// Optional channel name (DMs do not have a name).
    pub channel_name: Option<String>,
    /// Message that contains the attachment reference.
    pub message_id: Uuid,
    /// If the message belongs to a thread this is the parent id.
    pub thread_id: Option<Uuid>,
    /// Sender of the message.
    pub sender_id: String,
    /// Full message content (might be used for preview/snippet).
    pub message_content: String,
    /// When the message itself was created.
    pub message_created_at: DateTime<Utc>,
    /// When the attachment row was created.
    pub attachment_created_at: DateTime<Utc>,
}

/// A reference to an attachment entity from a comment: a message on a
/// document, initiative, CRM record, or call rather than on a channel.
#[derive(Debug, Clone, PartialEq)]
pub struct AttachmentCommentReference {
    /// Stored type of the entity the comment belongs to.
    pub parent_entity_type: String,
    /// Id of the entity the comment belongs to.
    pub parent_entity_id: String,
    /// Message that contains the reference.
    pub message_id: Uuid,
    /// If the message belongs to a thread this is the parent id.
    pub thread_id: Option<Uuid>,
    /// Sender of the message.
    pub sender_id: String,
    /// Full message content (might be used for preview/snippet).
    pub message_content: String,
    /// When the message itself was created.
    pub message_created_at: DateTime<Utc>,
    /// When the mention or attachment row was created.
    pub attachment_created_at: DateTime<Utc>,
}

/// A reference to an attachment entity from any non-message source entity.
#[derive(Debug, Clone, PartialEq)]
pub struct AttachmentGenericReference {
    /// Type of the source entity (e.g., "document", "chat", etc.).
    pub source_entity_type: String,
    /// ID of the source entity.
    pub source_entity_id: String,
    /// Type of the referenced entity.
    pub entity_type: String,
    /// ID of the referenced entity.
    pub entity_id: String,
    /// User who created this reference (optional for non-user sources).
    pub user_id: Option<String>,
    /// When this reference was created.
    pub created_at: DateTime<Utc>,
}

/// A reference to an attachment entity, tagged by source kind.
#[derive(Debug, Clone, PartialEq)]
pub enum AttachmentEntityReference {
    /// Referenced from a channel message.
    Channel(AttachmentChannelReference),
    /// Referenced from a comment on a non-channel entity.
    Comment(AttachmentCommentReference),
    /// Referenced from any non-message source entity.
    Generic(AttachmentGenericReference),
}

/// Raw row returned from the top-level messages query.
#[derive(Debug, Clone)]
pub struct TopLevelMessageRow {
    /// Message id.
    pub id: Uuid,
    /// Channel id.
    pub channel_id: Uuid,
    /// Sender user id.
    pub sender_id: String,
    /// For an agent (bot) message, the id of the user who triggered it.
    pub triggered_by: Option<String>,
    /// Message content.
    pub content: String,
    /// Created timestamp.
    pub created_at: DateTime<Utc>,
    /// Updated timestamp.
    pub updated_at: DateTime<Utc>,
    /// Edited timestamp.
    pub edited_at: Option<DateTime<Utc>>,
    /// Deleted timestamp.
    pub deleted_at: Option<DateTime<Utc>>,
}

/// Combined thread statistics and preview replies from a single query.
#[derive(Debug, Clone)]
pub struct ThreadData {
    /// Total number of replies in this thread.
    pub reply_count: i64,
    /// Timestamp of the latest reply.
    pub latest_reply_at: Option<DateTime<Utc>>,
    /// Oldest N replies for the thread preview (oldest-first).
    pub preview_replies: Vec<ThreadReplyRow>,
}

/// Raw row returned from the thread data query.
#[derive(Debug, Clone)]
pub struct ThreadReplyRow {
    /// Reply id.
    pub id: Uuid,
    /// Parent message id.
    pub thread_id: Uuid,
    /// Sender user id.
    pub sender_id: String,
    /// For an agent (bot) reply, the id of the user who triggered it.
    pub triggered_by: Option<String>,
    /// Reply content.
    pub content: String,
    /// Created timestamp.
    pub created_at: DateTime<Utc>,
    /// Updated timestamp.
    pub updated_at: DateTime<Utc>,
    /// Edited timestamp.
    pub edited_at: Option<DateTime<Utc>>,
}

/// Type of channel.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, strum::Display, strum::EnumString,
)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[cfg_attr(feature = "outbound", derive(sqlx::Type))]
#[cfg_attr(
    feature = "outbound",
    sqlx(type_name = "comms_channel_type", rename_all = "snake_case")
)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum ChannelType {
    /// Public channel.
    Public,
    /// Private group channel.
    Private,
    /// One-to-one direct message channel.
    DirectMessage,
    /// Team channel.
    Team,
}

/// Request to add a user to all organization channels.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct AddUserToOrgChannelsRequest {
    /// User to add.
    pub user_id: String,
    /// Organization id.
    pub org_id: i64,
}

/// Request to remove a user from all organization channels.
#[derive(Debug, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct RemoveUserFromOrgChannelsRequest {
    /// User to remove.
    pub user_id: String,
    /// Organization id.
    pub org_id: i64,
}

/// Request to check user membership in channels.
#[derive(Debug, Serialize, Deserialize)]
pub struct CheckChannelsForUserRequest {
    /// User id to check.
    pub user_id: String,
    /// Channel ids to check.
    pub channel_ids: Vec<Uuid>,
}

/// User activity data for a channel.
#[derive(Debug, Serialize, Deserialize)]
pub struct UserActivityForChannel {
    /// User id for the activity.
    pub user_id: String,
    /// Activity update timestamp.
    pub updated_at: chrono::NaiveDateTime,
}

/// Information about a channel used in search responses.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct ChannelHistoryInfo {
    /// Channel id.
    pub item_id: Uuid,
    /// Channel creation timestamp.
    pub created_at: DateTime<Utc>,
    /// Channel update timestamp.
    pub updated_at: DateTime<Utc>,
    /// Last viewed timestamp for requesting user.
    pub viewed_at: Option<DateTime<Utc>>,
    /// Last interaction timestamp for requesting user.
    pub interacted_at: Option<DateTime<Utc>>,
    /// Channel owner user id.
    pub user_id: String,
    /// Channel type string.
    pub channel_type: String,
}

/// Request for channel history data.
#[derive(Debug, Serialize, Deserialize)]
pub struct GetChannelsHistoryRequest {
    /// Requesting user id.
    pub user_id: String,
    /// Channel ids to fetch.
    pub channel_ids: Vec<Uuid>,
}

/// Response for channel history data.
#[derive(Debug, Serialize, Deserialize)]
pub struct GetChannelsHistoryResponse {
    /// History data keyed by channel id.
    pub channels_history: HashMap<Uuid, ChannelHistoryInfo>,
}

/// Request to create a welcome message.
#[derive(Debug, Serialize, Deserialize)]
pub struct CreateWelcomeMessageRequest {
    /// User id the welcome message is from/for.
    pub welcome_user_id: MacroUserIdStr<'static>,
    /// User id to send the welcome message to.
    pub to_user_id: MacroUserIdStr<'static>,
}

/// Channel message response used by search indexing.
#[derive(Debug, Serialize, Deserialize)]
pub struct GetChannelMessageResponse {
    /// Channel id.
    pub channel_id: Uuid,
    /// Channel name.
    pub name: Option<String>,
    /// Channel type.
    pub channel_type: ChannelType,
    /// Organization id.
    pub org_id: Option<i64>,
    /// Message data.
    pub channel_message: RecentChannelMessage,
}

/// Request to fetch channel metadata.
#[derive(Debug, Serialize, Deserialize)]
pub struct ChannelMetadataRequest {
    /// Channel id.
    pub channel_id: Uuid,
}

/// Request to fetch channel attachment text.
#[derive(Debug, Serialize, Deserialize)]
pub struct ChannelAttachmentTextRequest {
    /// Channel id.
    pub channel_id: Uuid,
    /// Optional lower bound.
    pub since: Option<chrono::DateTime<chrono::Utc>>,
    /// Optional row limit.
    pub limit: Option<i64>,
}

/// A user's activity (view/interaction) within a channel.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Activity {
    /// Activity row id.
    pub id: Uuid,
    /// Id of the user this activity belongs to.
    pub user_id: String,
    /// Id of the channel this activity is for.
    pub channel_id: Uuid,
    /// When the activity row was created.
    pub created_at: DateTime<Utc>,
    /// When the activity row was last updated.
    pub updated_at: DateTime<Utc>,
    /// The last time the user viewed the channel.
    pub viewed_at: Option<DateTime<Utc>>,
    /// The last time the user interacted with the channel
    /// (e.g. reacting, replying, sending a message).
    pub interacted_at: Option<DateTime<Utc>>,
}

/// The kind of activity a user performs in a channel.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
#[serde(rename_all = "lowercase")]
pub enum ActivityType {
    /// The user viewed the channel.
    View,
    /// The user interacted with the channel.
    Interact,
}

/// Result of a get-or-create channel operation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum GetOrCreateAction {
    /// An existing channel was returned.
    Get,
    /// A new channel was created.
    Create,
}

/// Request to create a channel.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateChannelRequest {
    /// Optional channel name.
    pub name: Option<String>,
    /// Channel type.
    pub channel_type: ChannelType,
    /// Team id for team channels.
    pub team_id: Option<Uuid>,
    /// Whether team members automatically join this channel. Defaults to false.
    #[serde(default)]
    #[cfg_attr(feature = "inbound", schema(default = false))]
    pub auto_join_team: bool,
    /// Participants to add, excluding the owner.
    #[cfg_attr(feature = "inbound", schema(value_type = HashSet<String>))]
    pub participants: HashSet<MacroUserIdStr<'static>>,
}

/// Persisted channel data returned by channel creation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CreatedChannel {
    /// Created channel id.
    pub id: Uuid,
    /// All active user participants added during creation.
    pub participant_user_ids: Vec<MacroUserIdStr<'static>>,
}

/// Response containing a channel's reusable join code.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ChannelJoinCodeResponse {
    /// Reusable code for joining the channel.
    pub join_code: Uuid,
}

/// Response returned after creating a channel.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateChannelResponse {
    /// Created channel id.
    pub id: String,
}

/// Request to get or create a direct message channel.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct GetOrCreateDmRequest {
    /// Recipient user id (`macro|...`) or agent persona id (`bot|...`).
    #[cfg_attr(feature = "inbound", schema(value_type = String))]
    pub recipient_id: Sender,
}

/// Request to get or create a private channel.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct GetOrCreatePrivateRequest {
    /// Recipient user ids.
    #[cfg_attr(feature = "inbound", schema(value_type = HashSet<String>))]
    pub recipients: HashSet<MacroUserIdStr<'static>>,
}

/// Response for get-or-create channel operations.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct GetOrCreateChannelResponse {
    /// Channel id.
    pub channel_id: String,
    /// Whether the channel was fetched or created.
    pub action: GetOrCreateAction,
}

/// Request to patch a channel.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct PatchChannelRequest {
    /// New channel name.
    pub channel_name: Option<String>,
    /// Sets whether the channel is a team channel.
    ///
    /// `true` converts a non-team channel to a team channel, while `false`
    /// converts a team channel to a private channel.
    pub convert_to_team_channel: Option<bool>,
    /// Whether team members should automatically join the channel.
    pub auto_join_team: Option<bool>,
}

/// Shareable entity type referenced by a channel message.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ReferencedShareItemType {
    /// Agent session entity.
    AgentSession,
    /// Database entity.
    Database,
    /// Document entity.
    Document,
    /// Chat entity.
    Chat,
    /// Project entity.
    Project,
    /// Email thread entity.
    EmailThread,
    /// Call entity.
    Call,
    /// Calendar event entity: one owner's projection of a meeting.
    CalendarEvent,
    /// Form entity: posting one lets the channel respond to it.
    Form,
    /// External chat added to Macro: mentioning one lets the channel read it.
    ExternalChat,
}

impl ReferencedShareItemType {
    /// Parse a raw entity type from the transport/storage representation.
    pub fn from_raw(raw: &str) -> Option<Self> {
        match raw {
            "agent_session" => Some(Self::AgentSession),
            "database" => Some(Self::Database),
            "document" => Some(Self::Document),
            "chat" => Some(Self::Chat),
            "project" => Some(Self::Project),
            "thread" | "email" | "email_thread" => Some(Self::EmailThread),
            "call" => Some(Self::Call),
            "calendar_event" => Some(Self::CalendarEvent),
            "form" => Some(Self::Form),
            "external_chat" => Some(Self::ExternalChat),
            _ => None,
        }
    }

    /// Return the storage representation of this item type.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::AgentSession => "agent_session",
            Self::Database => "database",
            Self::Document => "document",
            Self::Chat => "chat",
            Self::Project => "project",
            Self::EmailThread => "thread",
            Self::Call => "call",
            Self::CalendarEvent => "calendar_event",
            Self::Form => "form",
            Self::ExternalChat => "external_chat",
        }
    }

    /// Entity-type strings that should match when looking up references.
    ///
    /// Mentions store email threads as `"thread"`. The share menu historically
    /// stored `"email"`, so lookups treat those aliases as the same entity.
    pub fn reference_lookup_types(entity_type: &str) -> Vec<String> {
        match Self::from_raw(entity_type) {
            Some(Self::EmailThread) => vec![
                "thread".to_string(),
                "email".to_string(),
                "email_thread".to_string(),
            ],
            _ => vec![entity_type.to_string()],
        }
    }
}

/// Shareable item referenced by a channel message.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ReferencedShareItem {
    entity_id: String,
    entity_type: ReferencedShareItemType,
}

impl ReferencedShareItem {
    /// Build a typed referenced share item.
    pub fn new(entity_id: impl Into<String>, entity_type: ReferencedShareItemType) -> Self {
        Self {
            entity_id: entity_id.into(),
            entity_type,
        }
    }

    /// Build a typed referenced share item from raw entity data.
    pub fn from_raw(entity_id: impl Into<String>, entity_type: &str) -> Option<Self> {
        Some(Self::new(
            entity_id,
            ReferencedShareItemType::from_raw(entity_type)?,
        ))
    }

    /// Referenced entity id.
    pub fn entity_id(&self) -> &str {
        &self.entity_id
    }

    /// Referenced entity type.
    pub fn entity_type(&self) -> ReferencedShareItemType {
        self.entity_type
    }
}

/// Whether a referenced item was granted to a channel.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReferenceShareOutcome {
    /// A channel grant exists. An existing direct grant is left as it was.
    Shared,
    /// The actor's access is below what sharing this kind of item requires.
    NotPermitted,
}

/// One referenced item and whether it was shared with the channel.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReferenceShareResult {
    /// Referenced entity id.
    pub entity_id: String,
    /// Referenced entity type.
    pub entity_type: ReferencedShareItemType,
    /// Grant outcome.
    pub outcome: ReferenceShareOutcome,
}

/// Request to add participants.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct AddParticipantsRequest {
    /// User ids to add.
    #[cfg_attr(feature = "inbound", schema(value_type = HashSet<String>))]
    pub participants: HashSet<MacroUserIdStr<'static>>,
}

/// Request to remove participants.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct RemoveParticipantsRequest {
    /// User ids to remove.
    pub participants: Vec<String>,
}

/// Channel metadata needed for notifications.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ChannelMetadata {
    /// Channel type.
    pub channel_type: ChannelType,
    /// Resolved display name.
    pub channel_name: String,
}

/// Persisted channel message returned by mutation operations.
#[derive(Debug, Clone, Serialize)]
pub struct MutatedMessage {
    /// Message id.
    pub id: Uuid,
    /// Channel id.
    pub channel_id: Uuid,
    /// Thread parent id.
    pub thread_id: Option<Uuid>,
    /// Sender actor id.
    pub sender_id: ChannelSender<'static>,
    /// For an agent (bot) message, the id of the user who triggered it.
    pub triggered_by: Option<String>,
    /// The client the user triggered it through, such as "Claude Code".
    pub triggered_via: Option<String>,
    /// Message body.
    pub content: String,
    /// Created timestamp.
    pub created_at: DateTime<Utc>,
    /// Updated timestamp.
    pub updated_at: DateTime<Utc>,
    /// Edited timestamp.
    pub edited_at: Option<DateTime<Utc>>,
    /// Deleted timestamp.
    pub deleted_at: Option<DateTime<Utc>>,
}

/// Channel info row used by mutation logic.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ChannelInfo {
    /// Channel id.
    pub id: Uuid,
    /// Stored channel name.
    pub name: Option<String>,
    /// Channel type.
    pub channel_type: ChannelType,
    /// Organization id.
    pub org_id: Option<i64>,
    /// Team id.
    pub team_id: Option<Uuid>,
}

/// Request for a batched channel preview lookup.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct GetBatchChannelPreviewRequest {
    /// Channel ids to look up.
    pub channel_ids: Vec<String>,
}

/// Response for a batched channel preview lookup.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct GetBatchChannelPreviewResponse {
    /// Resolved channel previews, one per requested channel id.
    pub previews: Vec<ChannelPreview>,
}

/// Preview entry for a single channel id.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ChannelPreview {
    /// Viewer can access the channel.
    Access(ChannelPreviewData),
    /// Viewer cannot access the channel.
    NoAccess(WithChannelId),
    /// Channel does not exist.
    DoesNotExist(WithChannelId),
}

/// Preview payload returned for accessible channels.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ChannelPreviewData {
    /// Static image file used as the channel's profile picture, when accessible.
    pub profile_picture_id: Option<Uuid>,
    /// Channel id.
    pub channel_id: String,
    /// Resolved channel display name.
    pub channel_name: String,
    /// Channel type.
    pub channel_type: ChannelType,
}

/// Preview payload returned for channels with only id information.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct WithChannelId {
    /// Channel id.
    pub channel_id: String,
}

/// User display-name components used for channel-name resolution.
#[cfg(feature = "list")]
#[derive(Debug, Deserialize)]
pub struct UserName {
    /// Macro user id.
    pub id: MacroUserIdStr<'static>,
    /// First name, if present.
    pub first_name: Option<String>,
    /// Last name, if present.
    pub last_name: Option<String>,
}

#[cfg(feature = "list")]
impl UserName {
    /// Attempt to create a display name for this user.
    pub fn display_name(&self) -> Option<String> {
        const NA: &str = "N/A";
        match (
            self.first_name.as_deref().filter(|v| *v != NA),
            self.last_name.as_deref().filter(|v| *v != NA),
        ) {
            (None, None) => None,
            (None, Some(last)) => Some(last.to_string()),
            (Some(first), None) => Some(first.to_string()),
            (Some(first), Some(last)) => Some(format!("{first} {last}")),
        }
    }
}

/// Lookup from Macro user id to display name.
#[cfg(any(feature = "list", feature = "outbound"))]
pub(crate) type NameLookup = HashMap<MacroUserIdStr<'static>, String>;

/// Produce the human-readable fallback for a Macro user id.
#[cfg(any(feature = "list", feature = "outbound"))]
pub(crate) fn fallback_user_name(user_id: &MacroUserIdStr<'_>) -> String {
    user_id.email_part().local_part().to_string()
}

/// Channel list request.
#[cfg(feature = "list")]
#[derive(Debug)]
pub struct GetChannelsRequest {
    /// Requesting user id.
    pub macro_id: MacroUserIdStr<'static>,
    /// Optional result limit.
    pub limit: Option<u32>,
    /// Whether aggregate frecency should be loaded for the returned channels.
    pub include_frecency: bool,
    /// Cursor, sort, and channel-level filter.
    pub query: Query<Uuid, SimpleSortMethod, LiteralTree<ChannelLiteral>>,
}

#[cfg(feature = "list")]
impl GetChannelsRequest {
    /// Convert into repository params.
    pub fn into_params(self) -> GetChannelsParams {
        GetChannelsParams {
            macro_id: self.macro_id,
            limit: self.limit,
            query: self.query,
        }
    }
}

/// Channel list repository parameters.
#[cfg(feature = "list")]
#[derive(Debug)]
pub struct GetChannelsParams {
    macro_id: MacroUserIdStr<'static>,
    limit: Option<u32>,
    query: Query<Uuid, SimpleSortMethod, LiteralTree<ChannelLiteral>>,
}

/// An entity whose references are looked up, as stored on reference edges
/// (for example `crm_company` and the company id).
#[cfg(feature = "list")]
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ReferenceTarget {
    /// Stored entity type of the referenced entity.
    pub entity_type: String,
    /// Referenced entity id.
    pub entity_id: String,
}

/// What a live reference to a target belongs to.
#[cfg(feature = "list")]
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum ReferenceSource {
    /// A document or task whose content references the target.
    Document(String),
    /// An undeleted message that references the target.
    Message(ReferencingMessage),
}

/// An undeleted message that mentions or attaches a reference target.
#[cfg(feature = "list")]
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct ReferencingMessage {
    /// The message id.
    pub message_id: Uuid,
    /// The root of the message's thread, or `None` for a top-level message.
    pub thread_id: Option<Uuid>,
    /// The channel or discussion the message belongs to.
    pub parent: MessageParent,
}

#[cfg(feature = "list")]
impl ReferencingMessage {
    /// The top-level message the reference appears under: the thread root
    /// for a reply, otherwise the message itself.
    pub fn root_id(&self) -> Uuid {
        self.thread_id.unwrap_or(self.message_id)
    }
}

/// The channel or discussion a message belongs to.
#[cfg(feature = "list")]
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum MessageParent {
    /// A channel message.
    Channel(Uuid),
    /// A discussion message on a document.
    Document(String),
    /// A discussion message on an initiative.
    Initiative(Uuid),
    /// A discussion message on a CRM company.
    CrmCompany(Uuid),
    /// A discussion message on a CRM contact.
    CrmContact(Uuid),
    /// A message in a call's thread.
    Call(Uuid),
}

#[cfg(feature = "list")]
impl MessageParent {
    /// Parse a stored parent, or `None` for an unknown parent type or id.
    pub fn from_stored(parent_type: &str, parent_id: &str) -> Option<Self> {
        let uuid = || Uuid::parse_str(parent_id).ok();
        Some(match parent_type {
            "channel" => Self::Channel(uuid()?),
            "document" => Self::Document(parent_id.to_owned()),
            "initiative" => Self::Initiative(uuid()?),
            "crm_company" => Self::CrmCompany(uuid()?),
            "crm_contact" => Self::CrmContact(uuid()?),
            "call" => Self::Call(uuid()?),
            _ => return None,
        })
    }
}

/// Channel thread reply rows request.
#[cfg(feature = "list")]
#[derive(Debug)]
pub struct GetThreadReplyRowsRequest {
    /// Requesting user id.
    pub macro_id: MacroUserIdStr<'static>,
    /// Optional result limit.
    pub limit: Option<u32>,
    /// Cursor, sort, and channel-thread-level filter.
    pub query: Query<Uuid, SimpleSortMethod, LiteralTree<ChannelThreadLiteral>>,
}

#[cfg(feature = "list")]
impl GetThreadReplyRowsRequest {
    /// Convert into repository params.
    pub fn into_params(self) -> GetThreadReplyRowsParams {
        GetThreadReplyRowsParams {
            macro_id: self.macro_id,
            limit: self.limit,
            query: self.query,
        }
    }
}

/// Channel thread reply rows repository parameters.
#[cfg(feature = "list")]
#[derive(Debug)]
pub struct GetThreadReplyRowsParams {
    macro_id: MacroUserIdStr<'static>,
    limit: Option<u32>,
    query: Query<Uuid, SimpleSortMethod, LiteralTree<ChannelThreadLiteral>>,
}

#[cfg(feature = "list")]
impl GetThreadReplyRowsParams {
    /// Requesting user id.
    pub fn user(&self) -> &MacroUserIdStr<'static> {
        &self.macro_id
    }

    /// Optional result limit.
    pub fn limit(&self) -> Option<u32> {
        self.limit
    }

    /// Cursor, sort, and channel-thread-level filter.
    pub fn query(&self) -> &Query<Uuid, SimpleSortMethod, LiteralTree<ChannelThreadLiteral>> {
        &self.query
    }
}

#[cfg(feature = "list")]
impl GetChannelsParams {
    /// Requesting user id.
    pub fn user(&self) -> &MacroUserIdStr<'static> {
        &self.macro_id
    }

    /// Optional result limit.
    pub fn limit(&self) -> Option<u32> {
        self.limit
    }

    /// Cursor, sort, and channel-level filter.
    pub fn query(&self) -> &Query<Uuid, SimpleSortMethod, LiteralTree<ChannelLiteral>> {
        &self.query
    }
}

/// Channel data plus active participants.
#[cfg(feature = "list")]
#[derive(Debug, Clone)]
pub struct ChannelWithParticipants {
    /// Channel info.
    pub channel: ChannelListItem,
    /// Active channel participants.
    pub participants: Vec<ChannelParticipant>,
    /// Whether the requesting user is an active participant of the channel
    /// (has a `comms_channel_participants` row with `left_at IS NULL`).
    /// False for team channels of the user's teams they have not joined.
    pub is_participant: bool,
}

/// Channel list item.
#[cfg(feature = "list")]
#[derive(Debug, Clone)]
pub struct ChannelListItem {
    /// Channel id.
    pub id: Uuid,
    /// Resolved or stored name.
    pub name: Option<String>,
    /// Channel type.
    pub channel_type: ChannelType,
    /// Organization id.
    pub org_id: Option<i64>,
    /// Team id.
    pub team_id: Option<Uuid>,
    /// Whether team members automatically join the channel.
    pub auto_join_team: bool,
    /// Creation timestamp.
    pub created_at: DateTime<Utc>,
    /// Update timestamp.
    pub updated_at: DateTime<Utc>,
    /// Channel owner user id.
    pub owner_id: MacroUserIdStr<'static>,
}

/// Latest-message bundle for channel list results.
#[cfg(feature = "list")]
#[derive(Debug, Clone, Default)]
pub struct LatestMessage {
    /// Latest message including thread replies.
    pub latest_message: Option<RecentChannelMessage>,
    /// Latest non-thread top-level message.
    pub latest_non_thread_message: Option<RecentChannelMessage>,
}

/// Channel list result enriched with latest messages, activity, and frecency.
#[cfg(feature = "list")]
#[derive(Debug, Clone)]
pub struct ChannelWithLatest {
    /// Persona identity for the viewer's private agent conversation.
    pub agent_dm: Option<super::agent_dm::AgentDmProfile>,
    /// Channel plus participants.
    pub channel: ChannelWithParticipants,
    /// Latest message data.
    pub latest_message: LatestMessage,
    /// Last viewed timestamp for requesting user.
    pub viewed_at: Option<DateTime<Utc>>,
    /// Last interaction timestamp for requesting user.
    pub interacted_at: Option<DateTime<Utc>>,
    /// Aggregate frecency score.
    pub frecency_score: Option<frecency::domain::models::AggregateFrecency>,
}

#[cfg(feature = "list")]
impl Identify for ChannelWithLatest {
    type Id = Uuid;

    fn id(&self) -> Self::Id {
        self.channel.channel.id
    }
}

#[cfg(feature = "list")]
impl SortOn<SimpleSortMethod> for ChannelWithLatest {
    fn sort_on(sort: SimpleSortMethod) -> impl FnMut(&Self) -> CursorVal<SimpleSortMethod> {
        move |channel| {
            let last_val = match sort {
                SimpleSortMethod::ViewedAt => channel.viewed_at.unwrap_or_default(),
                SimpleSortMethod::UpdatedAt => channel.channel.channel.updated_at,
                SimpleSortMethod::CreatedAt => channel.channel.channel.created_at,
                SimpleSortMethod::ViewedUpdated => channel
                    .viewed_at
                    .unwrap_or(channel.channel.channel.updated_at),
            };

            CursorVal {
                sort_type: sort,
                last_val,
            }
        }
    }
}

/// Raw preview row returned from the repository.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ChannelPreviewRow {
    /// Static image file used as the channel's profile picture.
    pub profile_picture_id: Option<Uuid>,
    /// Channel info.
    pub info: ChannelInfo,
    /// Whether the viewer can access the channel.
    pub has_access: bool,
}

/// Persisted entity-to-entity mention.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct EntityMention {
    /// Mention id.
    pub id: Uuid,
    /// Type of the entity that owns the mention.
    pub source_entity_type: String,
    /// Id of the entity that owns the mention.
    pub source_entity_id: String,
    /// Type of the mentioned entity.
    pub entity_type: String,
    /// Id of the mentioned entity.
    pub entity_id: String,
    /// User who recorded the mention.
    pub user_id: Option<String>,
    /// Created timestamp.
    pub created_at: DateTime<Utc>,
}

/// Options for creating an entity mention.
#[derive(Debug, Clone)]
pub struct CreateEntityMentionOptions {
    /// Type of the entity that owns the mention.
    pub source_entity_type: String,
    /// Id of the entity that owns the mention.
    pub source_entity_id: String,
    /// Type of the mentioned entity.
    pub entity_type: String,
    /// Id of the mentioned entity.
    pub entity_id: String,
    /// User who recorded the mention.
    pub user_id: Option<String>,
}

/// Request body for `POST /channels/mentions`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateEntityMentionRequest {
    /// Type of the entity that owns the mention.
    pub source_entity_type: String,
    /// Id of the entity that owns the mention.
    pub source_entity_id: String,
    /// Type of the mentioned entity.
    pub entity_type: String,
    /// Id of the mentioned entity.
    pub entity_id: String,
}

/// Response body for `POST /channels/mentions`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateEntityMentionResponse {
    /// Mention id.
    pub id: String,
    /// Type of the entity that owns the mention.
    pub source_entity_type: String,
    /// Id of the entity that owns the mention.
    pub source_entity_id: String,
    /// Type of the mentioned entity.
    pub entity_type: String,
    /// Id of the mentioned entity.
    pub entity_id: String,
    /// User who recorded the mention.
    pub user_id: Option<String>,
    /// Created timestamp.
    pub created_at: DateTime<Utc>,
}

/// Response body for `DELETE /channels/mentions/{mention_id}`.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct DeleteEntityMentionResponse {
    /// Whether the mention was deleted.
    pub deleted: bool,
}

#[cfg(test)]
mod test;