cal_core/rest/

contact.rs

// File: cal-core/src/rest/contact.rs

use crate::RecordReference;
use crate::contact::{Contact, ContactDevice};
use crate::rest::common::{
    ApiError, Id, ListRequest, PaginationParams, SearchParams, SortOrder, SortParams,
};
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, HashMap};
#[cfg(feature = "openapi")]
use utoipa::ToSchema;

/// Request to create a new contact
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[cfg_attr(feature = "openapi", schema(
    title ="Request payload for creating a new contact",
    example = json!({
        "organisation": {
            "id": "507f1f77bcf86cd799439011",
            "name": "Acme Org"
        },
        "account": {
            "id": "507f1f77bcf86cd799439012",
            "name": "Acme Account"
        },
        "primary": "+1234567890",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "capabilities": ["sms", "voice"],
        "groups": ["sales", "support"]
    })
))]
pub struct CreateContactRequest {
    /// Organisation this contact belongs to
    pub organisation: RecordReference,

    /// Account this contact belongs to
    pub account: RecordReference,

    /// Primary phone number (required)
    #[cfg_attr(
        feature = "openapi",
        schema(example = "+1234567890", pattern = r"^\+?[1-9]\d{1,14}$")
    )]
    pub primary: String,

    /// Secondary phone number
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "+0987654321"))]
    pub secondary: Option<String>,

    /// Tertiary phone number
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "+1122334455"))]
    pub tertiary: Option<String>,

    /// Contact's full name
    #[cfg_attr(feature = "openapi", schema(example = "John Doe", min_length = 1))]
    pub name: String,

    /// Contact's nickname or preferred name
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "Johnny"))]
    pub nickname: Option<String>,

    /// Contact's email address
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(
        feature = "openapi",
        schema(example = "john.doe@example.com", format = "email")
    )]
    pub email: Option<String>,

    /// Communication capabilities (e.g., sms, voice, video)
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    #[cfg_attr(feature = "openapi", schema(example = json!(["sms", "voice", "email"])))]
    pub capabilities: Vec<String>,

    /// Groups this contact belongs to
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    #[cfg_attr(feature = "openapi", schema(example = json!(["sales", "vip", "support"])))]
    pub groups: Vec<String>,

    /// Associated device information
    #[serde(skip_serializing_if = "Option::is_none")]
    pub device: Option<ContactDevice>,

    /// Primary group (deprecated - use groups instead)
    #[serde(skip_serializing_if = "Option::is_none")]
    pub group: Option<String>,

    /// Whether the contact has opted out of communications
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = false))]
    pub opt_out: Option<bool>,
}

/// Request to update an existing contact
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[cfg_attr(
    feature = "openapi",
    schema(title = "Request payload for updating a contact. All fields are optional.")
)]
#[serde(rename_all = "camelCase")]
pub struct UpdateContactRequest {
    /// Update organisation reference
    #[serde(skip_serializing_if = "Option::is_none")]
    pub organisation: Option<RecordReference>,

    /// Update account reference
    #[serde(skip_serializing_if = "Option::is_none")]
    pub account: Option<RecordReference>,

    /// Update primary phone number
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "+1234567890"))]
    pub primary: Option<String>,

    /// Update secondary phone number
    #[serde(skip_serializing_if = "Option::is_none")]
    pub secondary: Option<String>,

    /// Update tertiary phone number
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tertiary: Option<String>,

    /// Update contact's name
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "Jane Doe"))]
    pub name: Option<String>,

    /// Update nickname
    #[serde(skip_serializing_if = "Option::is_none")]
    pub nickname: Option<String>,

    /// Update email address
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "jane.doe@example.com"))]
    pub email: Option<String>,

    /// Update capabilities
    #[serde(skip_serializing_if = "Option::is_none")]
    pub capabilities: Option<Vec<String>>,

    /// Update groups
    #[serde(skip_serializing_if = "Option::is_none")]
    pub groups: Option<Vec<String>>,

    /// Update device information
    #[serde(skip_serializing_if = "Option::is_none")]
    pub device: Option<ContactDevice>,

    /// Update primary group
    #[serde(skip_serializing_if = "Option::is_none")]
    pub group: Option<String>,

    /// Update opt-out status
    #[serde(skip_serializing_if = "Option::is_none")]
    pub opt_out: Option<bool>,
}

/// Request parameters for listing contacts
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[cfg_attr(
    feature = "openapi",
    schema(title = "Query parameters for listing contacts with filtering and pagination")
)]
#[serde(rename_all = "camelCase")]
pub struct ContactListRequest {
    /// Common list parameters (pagination, sorting, search)
    #[serde(flatten)]
    pub common: ListRequest,

    /// Filter by account ID
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "507f1f77bcf86cd799439011"))]
    pub account_id: Option<String>,

    /// Filter by organisation ID
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "507f1f77bcf86cd799439012"))]
    pub organisation_id: Option<String>,

    /// Filter by name (partial match)
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "John"))]
    pub name: Option<String>,

    /// Filter by primary phone number
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "+1234567890"))]
    pub primary: Option<String>,

    /// Filter by email address
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "john@example.com"))]
    pub email: Option<String>,

    /// Filter by group membership
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "sales"))]
    pub group: Option<String>,

    /// Filter by capability
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "sms"))]
    pub capability: Option<String>,

    /// Filter by device ID
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "openapi", schema(example = "dev_123456"))]
    pub device_id: Option<String>,
}

/// Request to create multiple contacts in a single operation
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[cfg_attr(feature = "openapi", schema(
    title ="Request to create multiple contacts in batch",
    example = json!({
        "contacts": [
            {
                "organisation": {"id": "org_1", "name": "Org 1"},
                "account": {"id": "acc_1", "name": "Account 1"},
                "primary": "+1234567890",
                "name": "John Doe",
                "email": "john@example.com"
            },
            {
                "organisation": {"id": "org_1", "name": "Org 1"},
                "account": {"id": "acc_1", "name": "Account 1"},
                "primary": "+0987654321",
                "name": "Jane Doe",
                "email": "jane@example.com"
            }
        ]
    })
))]
#[serde(rename_all = "camelCase")]
pub struct BatchCreateContactsRequest {
    /// Array of contacts to create
    #[cfg_attr(feature = "openapi", schema(min_items = 1, max_items = 1000))]
    pub contacts: Vec<CreateContactRequest>,
}

/// Request to update multiple contacts in a single operation
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[cfg_attr(
    feature = "openapi",
    schema(title = "Request to update multiple contacts in batch")
)]
#[serde(rename_all = "camelCase")]
pub struct BatchUpdateContactsRequest {
    /// Array of contact updates
    #[cfg_attr(feature = "openapi", schema(min_items = 1, max_items = 1000))]
    pub updates: Vec<ContactUpdate>,
}

/// Individual contact update in a batch operation
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[cfg_attr(
    feature = "openapi",
    schema(title = "Update operation for a single contact in a batch")
)]
#[serde(rename_all = "camelCase")]
pub struct ContactUpdate {
    /// ID of the contact to update
    #[cfg_attr(feature = "openapi", schema(example = "507f1f77bcf86cd799439011"))]
    pub id: String,

    /// Update fields
    #[serde(flatten)]
    pub update: UpdateContactRequest,
}

/// Request to delete multiple contacts in a single operation
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
#[cfg_attr(feature = "openapi", schema(
    title ="Request to delete multiple contacts in batch",
    example = json!({
        "ids": [
            "507f1f77bcf86cd799439011",
            "507f1f77bcf86cd799439012",
            "507f1f77bcf86cd799439013"
        ]
    })
))]
#[serde(rename_all = "camelCase")]
pub struct BatchDeleteContactsRequest {
    /// Array of contact IDs to delete
    #[cfg_attr(feature = "openapi", schema(min_items = 1, max_items = 1000))]
    pub ids: Vec<String>,
}

/// Contact-specific error codes
#[derive(Debug, Clone)]
#[cfg_attr(feature = "openapi", derive(ToSchema))]
pub enum ContactErrorCode {
    /// Contact not found
    NotFound,
    /// Primary number already exists
    DuplicatePrimary,
    /// Invalid email format
    InvalidEmail,
    /// Invalid phone number format
    InvalidPhone,
    /// Required field is missing
    MissingRequiredField,
    /// Invalid organisation reference
    InvalidOrganisation,
    /// Invalid account reference
    InvalidAccount,
}

impl ContactErrorCode {
    /// Convert error code to string representation
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::NotFound => "CONTACT_NOT_FOUND",
            Self::DuplicatePrimary => "DUPLICATE_PRIMARY_NUMBER",
            Self::InvalidEmail => "INVALID_EMAIL_FORMAT",
            Self::InvalidPhone => "INVALID_PHONE_FORMAT",
            Self::MissingRequiredField => "MISSING_REQUIRED_FIELD",
            Self::InvalidOrganisation => "INVALID_ORGANISATION",
            Self::InvalidAccount => "INVALID_ACCOUNT",
        }
    }
}

// Helper implementations
impl CreateContactRequest {
    /// Validate the create contact request
    pub fn validate(&self) -> Result<(), ApiError> {
        if self.name.trim().is_empty() {
            return Err(ApiError::new(
                ContactErrorCode::MissingRequiredField.as_str(),
                "Contact name is required",
            )
            .with_field("name"));
        }

        if self.primary.trim().is_empty() {
            return Err(ApiError::new(
                ContactErrorCode::MissingRequiredField.as_str(),
                "Primary contact number is required",
            )
            .with_field("primary"));
        }

        if let Some(email) = &self.email {
            if !email.is_empty() && !email.contains('@') {
                return Err(ApiError::new(
                    ContactErrorCode::InvalidEmail.as_str(),
                    "Invalid email format",
                )
                .with_field("email"));
            }
        }

        Ok(())
    }
}

impl UpdateContactRequest {
    /// Apply updates to an existing contact
    pub fn apply_to(self, contact: &mut Contact) {
        if let Some(organisation) = self.organisation {
            contact.organisation = Some(organisation);
        }
        if let Some(account) = self.account {
            contact.account = account;
        }
        if let Some(primary) = self.primary {
            contact.primary = primary;
        }
        if let Some(secondary) = self.secondary {
            contact.secondary = Some(secondary);
        }
        if let Some(tertiary) = self.tertiary {
            contact.tertiary = Some(tertiary);
        }
        if let Some(name) = self.name {
            contact.name = name;
        }
        if let Some(nickname) = self.nickname {
            contact.nickname = Some(nickname);
        }
        if let Some(email) = self.email {
            contact.email = Some(email);
        }
        if let Some(capabilities) = self.capabilities {
            contact.capabilities = capabilities;
        }
        if let Some(groups) = self.groups {
            contact.groups = groups;
        }
        if let Some(device) = self.device {
            contact.device = Some(device);
        }
        if let Some(opt_out) = self.opt_out {
            contact.opt_out = Some(opt_out);
        }
        if let Some(group) = self.group {
            contact.group = Some(group);
        }
    }

    /// Check if the update request has any fields to update
    pub fn is_empty(&self) -> bool {
        self.organisation.is_none()
            && self.account.is_none()
            && self.primary.is_none()
            && self.secondary.is_none()
            && self.tertiary.is_none()
            && self.name.is_none()
            && self.nickname.is_none()
            && self.email.is_none()
            && self.capabilities.is_none()
            && self.groups.is_none()
            && self.device.is_none()
            && self.group.is_none()
            && self.opt_out.is_none()
    }
}

impl Default for ContactListRequest {
    fn default() -> Self {
        Self {
            common: ListRequest {
                pagination: PaginationParams::default(),
                sort: SortParams::default(),
                search: None,
                time_range: None,
                filters: None,
            },
            account_id: None,
            organisation_id: None,
            name: None,
            primary: None,
            email: None,
            group: None,
            capability: None,
            device_id: None,
        }
    }
}

// Convenience builders
impl ContactListRequest {
    /// Create a new contact list request with defaults
    pub fn new() -> Self {
        Self::default()
    }

    /// Set pagination parameters
    pub fn with_pagination(mut self, page: u32, page_size: u32) -> Self {
        self.common.pagination = PaginationParams::new(page, page_size);
        self
    }

    /// Set sorting parameters
    pub fn with_sorting(mut self, sort_by: String, sort_order: SortOrder) -> Self {
        self.common.sort = SortParams {
            sort_by: Some(sort_by),
            sort_order,
        };
        self
    }

    /// Set search parameters
    pub fn with_search(mut self, query: String) -> Self {
        self.common.search = Some(SearchParams {
            query,
            fields: None,
            fuzzy: false,
            highlight: None,
        });
        self
    }

    /// Filter by account ID
    pub fn with_account_id(mut self, account_id: String) -> Self {
        self.account_id = Some(account_id);
        self
    }

    /// Filter by organisation ID
    pub fn with_organisation_id(mut self, organisation_id: String) -> Self {
        self.organisation_id = Some(organisation_id);
        self
    }
}