zammad-api 0.4.0

//! Strongly typed Zammad entities.
//!
//! Every record type carries an `extra` field that captures custom attributes
//! Zammad returns but that aren't covered by the typed schema. Use it to
//! read or write Object-Manager custom fields without having to redefine the
//! whole model.
//!
//! For tickets the crate exposes two shapes: the compact [`Ticket`] (default)
//! and [`TicketExpanded`], which carries human-readable name strings
//! Zammad adds when `expand=true` is sent. Select between them at call site
//! via [`crate::api::TicketsApi::list`] vs [`crate::api::TicketsApi::list_expanded`].

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};

/// A Zammad ticket (compact form - IDs only).
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Ticket {
    /// Numeric ticket ID.
    pub id: u64,
    /// Customer-facing ticket number (e.g. `"100123"`).
    #[serde(default)]
    pub number: Option<String>,
    /// Ticket subject / title.
    #[serde(default)]
    pub title: Option<String>,
    /// ID of the assigned group (queue).
    #[serde(default)]
    pub group_id: Option<u64>,
    /// ID of the current state (`new`, `open`, `closed`, ...).
    #[serde(default)]
    pub state_id: Option<u64>,
    /// ID of the assigned priority.
    #[serde(default)]
    pub priority_id: Option<u64>,
    /// ID of the customer this ticket belongs to.
    #[serde(default)]
    pub customer_id: Option<u64>,
    /// ID of the agent currently owning the ticket.
    #[serde(default)]
    pub owner_id: Option<u64>,
    /// ID of the customer's organization, if any.
    #[serde(default)]
    pub organization_id: Option<u64>,
    /// Free-form internal note attached to the ticket.
    #[serde(default)]
    pub note: Option<String>,
    /// When the ticket was created.
    #[serde(default)]
    pub created_at: Option<DateTime<Utc>>,
    /// When the ticket was last updated.
    #[serde(default)]
    pub updated_at: Option<DateTime<Utc>>,
    /// Any attribute Zammad returned that isn't modelled above (typically
    /// Object-Manager custom fields).
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// A Zammad ticket returned with `expand=true`.
///
/// In addition to the numeric `*_id` fields carried by [`Ticket`], the
/// server adds human-readable name strings for group, state, priority,
/// customer, owner and organization.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct TicketExpanded {
    /// Numeric ticket ID.
    pub id: u64,
    /// Customer-facing ticket number.
    #[serde(default)]
    pub number: Option<String>,
    /// Ticket subject / title.
    #[serde(default)]
    pub title: Option<String>,
    /// ID of the assigned group.
    #[serde(default)]
    pub group_id: Option<u64>,
    /// Name of the assigned group, e.g. `"Users"`.
    #[serde(default)]
    pub group: Option<String>,
    /// ID of the current state.
    #[serde(default)]
    pub state_id: Option<u64>,
    /// Name of the current state, e.g. `"open"`.
    #[serde(default)]
    pub state: Option<String>,
    /// ID of the assigned priority.
    #[serde(default)]
    pub priority_id: Option<u64>,
    /// Name of the assigned priority, e.g. `"2 normal"`.
    #[serde(default)]
    pub priority: Option<String>,
    /// ID of the customer.
    #[serde(default)]
    pub customer_id: Option<u64>,
    /// Login / email of the customer.
    #[serde(default)]
    pub customer: Option<String>,
    /// ID of the owning agent.
    #[serde(default)]
    pub owner_id: Option<u64>,
    /// Login / email of the owning agent.
    #[serde(default)]
    pub owner: Option<String>,
    /// ID of the customer's organization.
    #[serde(default)]
    pub organization_id: Option<u64>,
    /// Name of the customer's organization.
    #[serde(default)]
    pub organization: Option<String>,
    /// Free-form internal note.
    #[serde(default)]
    pub note: Option<String>,
    /// When the ticket was created.
    #[serde(default)]
    pub created_at: Option<DateTime<Utc>>,
    /// When the ticket was last updated.
    #[serde(default)]
    pub updated_at: Option<DateTime<Utc>>,
    /// Any attribute Zammad returned that isn't modelled above.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// A Zammad user (agent or customer).
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct User {
    /// Numeric user ID.
    pub id: u64,
    /// Login (often the email).
    #[serde(default)]
    pub login: Option<String>,
    /// Given name.
    #[serde(default)]
    pub firstname: Option<String>,
    /// Family name.
    #[serde(default)]
    pub lastname: Option<String>,
    /// Primary email.
    #[serde(default)]
    pub email: Option<String>,
    /// Personal website URL.
    #[serde(default)]
    pub web: Option<String>,
    /// Landline phone.
    #[serde(default)]
    pub phone: Option<String>,
    /// Mobile phone.
    #[serde(default)]
    pub mobile: Option<String>,
    /// Fax number.
    #[serde(default)]
    pub fax: Option<String>,
    /// Free-form internal note.
    #[serde(default)]
    pub note: Option<String>,
    /// ID of the primary organization, if any.
    #[serde(default)]
    pub organization_id: Option<u64>,
    /// Whether the account is active.
    #[serde(default)]
    pub active: Option<bool>,
    /// Whether the email is verified.
    #[serde(default)]
    pub verified: Option<bool>,
    /// When the user was created.
    #[serde(default)]
    pub created_at: Option<DateTime<Utc>>,
    /// When the user was last updated.
    #[serde(default)]
    pub updated_at: Option<DateTime<Utc>>,
    /// Any attribute not modelled above (incl. custom fields).
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// Payload for `POST /api/v1/users`.
#[derive(Debug, Clone, Default, Serialize)]
pub struct NewUser {
    /// Given name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub firstname: Option<String>,
    /// Family name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub lastname: Option<String>,
    /// Primary email.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub email: Option<String>,
    /// Login (defaults server-side to the email).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub login: Option<String>,
    /// Landline phone.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub phone: Option<String>,
    /// Mobile phone.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mobile: Option<String>,
    /// Organization name (Zammad resolves it to an ID).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub organization: Option<String>,
    /// Role names, e.g. `["Customer"]` or `["Agent"]`.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub roles: Vec<String>,
    /// Additional fields (custom attributes, etc.).
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

impl NewUser {
    /// Convenience constructor seeded with the primary email.
    pub fn with_email(email: impl Into<String>) -> Self {
        Self {
            email: Some(email.into()),
            ..Self::default()
        }
    }

    /// Set the given name.
    pub fn firstname(mut self, s: impl Into<String>) -> Self {
        self.firstname = Some(s.into());
        self
    }
    /// Set the family name.
    pub fn lastname(mut self, s: impl Into<String>) -> Self {
        self.lastname = Some(s.into());
        self
    }
    /// Set the phone.
    pub fn phone(mut self, s: impl Into<String>) -> Self {
        self.phone = Some(s.into());
        self
    }
    /// Append a role.
    pub fn role(mut self, s: impl Into<String>) -> Self {
        self.roles.push(s.into());
        self
    }
    /// Set an arbitrary custom field on the new user.
    pub fn field(mut self, key: impl Into<String>, value: impl Into<Value>) -> Self {
        self.extra.insert(key.into(), value.into());
        self
    }
}

/// A ticket article (note, email, phone log, ...).
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Article {
    /// Numeric article ID.
    pub id: u64,
    /// ID of the parent ticket.
    #[serde(default)]
    pub ticket_id: Option<u64>,
    /// Subject line.
    #[serde(default)]
    pub subject: Option<String>,
    /// Article body (plain text or HTML depending on `content_type`).
    #[serde(default)]
    pub body: Option<String>,
    /// Sender address (free-form string Zammad chose).
    #[serde(default)]
    pub from: Option<String>,
    /// Recipient address.
    #[serde(default)]
    pub to: Option<String>,
    /// CC recipients.
    #[serde(default)]
    pub cc: Option<String>,
    /// Reply-To header.
    #[serde(default)]
    pub reply_to: Option<String>,
    /// MIME content type (`text/plain`, `text/html`).
    #[serde(default)]
    pub content_type: Option<String>,
    /// Article type (`note`, `email`, `phone`, ...).
    #[serde(rename = "type", default)]
    pub article_type: Option<String>,
    /// Sender role (`Agent`, `Customer`, `System`).
    #[serde(default)]
    pub sender: Option<String>,
    /// Whether the article is hidden from customers.
    #[serde(default)]
    pub internal: Option<bool>,
    /// When the article was created.
    #[serde(default)]
    pub created_at: Option<DateTime<Utc>>,
    /// When the article was last updated.
    #[serde(default)]
    pub updated_at: Option<DateTime<Utc>>,
    /// File attachments on the article.
    #[serde(default)]
    pub attachments: Vec<Attachment>,
    /// Any attribute not modelled above.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// Payload for `POST /api/v1/ticket_articles` and inline `article` on ticket creation.
#[derive(Debug, Clone, Default, Serialize)]
pub struct NewArticle {
    /// Subject line.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub subject: Option<String>,
    /// Article body.
    pub body: String,
    /// Article type, e.g. `note`, `email`, `phone`, `web`, `sms`.
    #[serde(rename = "type", skip_serializing_if = "Option::is_none")]
    pub article_type: Option<String>,
    /// Whether the article should be hidden from customers.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub internal: Option<bool>,
    /// MIME content type - `text/plain` (default server-side) or `text/html`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub content_type: Option<String>,
    /// Sender role override (`Agent`, `Customer`, `System`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sender: Option<String>,
    /// From address (mail-type articles).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub from: Option<String>,
    /// To address (mail-type articles).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub to: Option<String>,
    /// CC addresses.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cc: Option<String>,
    /// Inline attachments.
    #[serde(skip_serializing_if = "Vec::is_empty", default)]
    pub attachments: Vec<NewAttachment>,
    /// Parent ticket - filled in automatically by
    /// [`crate::api::ArticlesApi::create`], not needed when used inline.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub ticket_id: Option<u64>,
}

impl NewArticle {
    /// Build with the given body. Without an explicit `article_type` the
    /// server defaults to a note.
    pub fn new(body: impl Into<String>) -> Self {
        Self {
            body: body.into(),
            ..Self::default()
        }
    }

    /// Set the subject line.
    pub fn subject(mut self, s: impl Into<String>) -> Self {
        self.subject = Some(s.into());
        self
    }
    /// Set the article type (`note`, `email`, `phone`, `web`, `sms`, ...).
    pub fn article_type(mut self, s: impl Into<String>) -> Self {
        self.article_type = Some(s.into());
        self
    }
    /// Set the MIME content type (`text/plain` or `text/html`).
    pub fn content_type(mut self, s: impl Into<String>) -> Self {
        self.content_type = Some(s.into());
        self
    }
    /// Mark the article as internal (hidden from customers).
    pub fn internal(mut self, b: bool) -> Self {
        self.internal = Some(b);
        self
    }
    /// Override the sender role.
    pub fn sender(mut self, s: impl Into<String>) -> Self {
        self.sender = Some(s.into());
        self
    }
    /// Set the From address.
    pub fn from(mut self, s: impl Into<String>) -> Self {
        self.from = Some(s.into());
        self
    }
    /// Set the To address.
    pub fn to(mut self, s: impl Into<String>) -> Self {
        self.to = Some(s.into());
        self
    }
    /// Set the CC addresses.
    pub fn cc(mut self, s: impl Into<String>) -> Self {
        self.cc = Some(s.into());
        self
    }
    /// Append an attachment.
    pub fn attach(mut self, a: NewAttachment) -> Self {
        self.attachments.push(a);
        self
    }
}

/// Attachment metadata returned by Zammad.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Attachment {
    /// Numeric attachment ID.
    pub id: u64,
    /// File name as uploaded.
    #[serde(default)]
    pub filename: Option<String>,
    /// File size - Zammad reports this as a stringified integer.
    #[serde(default)]
    pub size: Option<String>,
    /// Server-side preferences blob (content type, content disposition, ...).
    #[serde(default)]
    pub preferences: Option<Value>,
}

/// Attachment payload for outbound articles. `data` is base64-encoded.
#[derive(Debug, Clone, Serialize)]
pub struct NewAttachment {
    /// File name to show in Zammad.
    pub filename: String,
    /// Base64-encoded file content.
    pub data: String,
    /// MIME type, e.g. `text/plain`, `application/pdf`.
    #[serde(rename = "mime-type")]
    pub mime_type: String,
}

impl NewAttachment {
    /// Build from raw bytes - performs base64 encoding for you.
    pub fn from_bytes(
        filename: impl Into<String>,
        mime_type: impl Into<String>,
        bytes: &[u8],
    ) -> Self {
        use base64::Engine;
        Self {
            filename: filename.into(),
            mime_type: mime_type.into(),
            data: base64::engine::general_purpose::STANDARD.encode(bytes),
        }
    }
}

/// A Zammad organization.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Organization {
    /// Numeric organization ID.
    pub id: u64,
    /// Display name.
    #[serde(default)]
    pub name: Option<String>,
    /// Whether the organization is shared with all agents.
    #[serde(default)]
    pub shared: Option<bool>,
    /// Email domain used for automatic assignment.
    #[serde(default)]
    pub domain: Option<String>,
    /// Whether new users with `@domain` emails get auto-assigned.
    #[serde(default)]
    pub domain_assignment: Option<bool>,
    /// Whether the organization is active.
    #[serde(default)]
    pub active: Option<bool>,
    /// Free-form internal note.
    #[serde(default)]
    pub note: Option<String>,
    /// When the organization was created.
    #[serde(default)]
    pub created_at: Option<DateTime<Utc>>,
    /// When the organization was last updated.
    #[serde(default)]
    pub updated_at: Option<DateTime<Utc>>,
    /// Any attribute not modelled above (incl. custom fields).
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// Payload for `POST /api/v1/organizations`.
#[derive(Debug, Clone, Default, Serialize)]
pub struct NewOrganization {
    /// Display name (required).
    pub name: String,
    /// Email domain used for automatic assignment.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub domain: Option<String>,
    /// Whether to share the organization with all agents.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub shared: Option<bool>,
    /// Free-form internal note.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
    /// Additional fields (custom attributes, etc.).
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

impl NewOrganization {
    /// Build with the given name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            ..Self::default()
        }
    }
}

/// A Zammad group (queue).
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Group {
    /// Numeric group ID.
    pub id: u64,
    /// Display name.
    #[serde(default)]
    pub name: Option<String>,
    /// ID of the signature attached to outbound mail from this group.
    #[serde(default)]
    pub signature_id: Option<u64>,
    /// ID of the email-address record this group sends from.
    #[serde(default)]
    pub email_address_id: Option<u64>,
    /// Follow-up policy, e.g. `"yes"` / `"new_ticket"`.
    #[serde(default)]
    pub follow_up_possible: Option<String>,
    /// Whether follow-ups are reassigned to the previous owner.
    #[serde(default)]
    pub follow_up_assignment: Option<bool>,
    /// Whether the group is active.
    #[serde(default)]
    pub active: Option<bool>,
    /// Free-form note.
    #[serde(default)]
    pub note: Option<String>,
    /// Any attribute not modelled above.
    #[serde(flatten)]
    pub extra: Map<String, Value>,
}

/// A configurable ticket state.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct TicketState {
    /// Numeric state ID.
    pub id: u64,
    /// Display name (`new`, `open`, `closed`, ...).
    #[serde(default)]
    pub name: Option<String>,
    /// ID of the underlying state type.
    #[serde(default)]
    pub state_type_id: Option<u64>,
    /// Whether tickets in this state ignore escalation timers.
    #[serde(default)]
    pub ignore_escalation: Option<bool>,
    /// Whether this is the default state on ticket creation.
    #[serde(default)]
    pub default_create: Option<bool>,
    /// Whether this is the default state on customer follow-up.
    #[serde(default)]
    pub default_follow_up: Option<bool>,
    /// Whether the state is active.
    #[serde(default)]
    pub active: Option<bool>,
    /// Free-form note.
    #[serde(default)]
    pub note: Option<String>,
}

/// A configurable ticket priority.
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct TicketPriority {
    /// Numeric priority ID.
    pub id: u64,
    /// Display name (`1 low`, `2 normal`, `3 high`, ...).
    #[serde(default)]
    pub name: Option<String>,
    /// Whether this is the default priority on ticket creation.
    #[serde(default)]
    pub default_create: Option<bool>,
    /// Icon class shown in the UI.
    #[serde(default)]
    pub ui_icon: Option<String>,
    /// Color used in the UI.
    #[serde(default)]
    pub ui_color: Option<String>,
    /// Whether the priority is active.
    #[serde(default)]
    pub active: Option<bool>,
    /// Free-form note.
    #[serde(default)]
    pub note: Option<String>,
}

#[cfg(test)]
mod tests {
    use super::NewAttachment;

    #[test]
    fn attachment_encodes_bytes_as_base64() {
        let a = NewAttachment::from_bytes("hi.txt", "text/plain", b"foobar");
        assert_eq!(a.data, "Zm9vYmFy");
    }
}