emailit 2.0.3

//! Request and response types for all Emailit API v2 resources.
//!
//! Request parameter structs use a builder pattern: construct with `::new()`
//! and chain `with_*` methods to set optional fields.

use serde::{Deserialize, Serialize};
use serde_json::Value;
use std::collections::HashMap;

// ---------------------------------------------------------------------------
// Emails
// ---------------------------------------------------------------------------

/// Parameters for sending an email via `POST /v2/emails`.
///
/// # Example
///
/// ```
/// use emailit::CreateEmailBaseOptions;
///
/// let email = CreateEmailBaseOptions::new(
///     "Acme <hi@acme.com>",
///     ["user@example.com"],
///     "Welcome!",
/// )
/// .with_html("<h1>Hello</h1>")
/// .with_tags(["onboarding"]);
/// ```
#[derive(Debug, Serialize)]
pub struct CreateEmailBaseOptions {
    /// Sender address (e.g. `"Name <email@domain.com>"`).
    pub from: String,
    /// One or more recipient addresses.
    pub to: Vec<String>,
    /// Email subject line. Cleared automatically when using [`with_template`](Self::with_template).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub subject: Option<String>,
    /// HTML body content.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub html: Option<String>,
    /// Plain-text body content.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub text: Option<String>,
    /// Template ID or alias to render instead of inline HTML/text.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub template: Option<String>,
    /// Template variables for merge-tag replacement.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub variables: Option<HashMap<String, Value>>,
    /// CC recipient addresses.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cc: Option<Vec<String>>,
    /// BCC recipient addresses.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub bcc: Option<Vec<String>>,
    /// Reply-to address.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reply_to: Option<String>,
    /// File attachments.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub attachments: Option<Vec<Attachment>>,
    /// Arbitrary tags for categorisation.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tags: Option<Vec<String>>,
    /// Arbitrary key-value metadata.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub metadata: Option<HashMap<String, Value>>,
    /// Open/click tracking overrides.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub tracking: Option<Tracking>,
    /// ISO-8601 datetime to schedule delivery for.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub scheduled_at: Option<String>,
}

impl CreateEmailBaseOptions {
    /// Creates a new email with the required fields: sender, recipients, and subject.
    pub fn new(
        from: impl Into<String>,
        to: impl IntoIterator<Item = impl Into<String>>,
        subject: impl Into<String>,
    ) -> Self {
        Self {
            from: from.into(),
            to: to.into_iter().map(|t| t.into()).collect(),
            subject: Some(subject.into()),
            html: None,
            text: None,
            template: None,
            variables: None,
            cc: None,
            bcc: None,
            reply_to: None,
            attachments: None,
            tags: None,
            metadata: None,
            tracking: None,
            scheduled_at: None,
        }
    }

    /// Sets the HTML body.
    pub fn with_html(mut self, html: impl Into<String>) -> Self {
        self.html = Some(html.into());
        self
    }

    /// Sets the plain-text body.
    pub fn with_text(mut self, text: impl Into<String>) -> Self {
        self.text = Some(text.into());
        self
    }

    /// Uses a template instead of inline content. Clears the subject field
    /// because the template defines its own subject.
    pub fn with_template(mut self, template: impl Into<String>) -> Self {
        self.template = Some(template.into());
        self.subject = None;
        self
    }

    /// Sets template variables for merge-tag replacement.
    pub fn with_variables(mut self, variables: HashMap<String, Value>) -> Self {
        self.variables = Some(variables);
        self
    }

    /// Sets CC recipients.
    pub fn with_cc(mut self, cc: impl IntoIterator<Item = impl Into<String>>) -> Self {
        self.cc = Some(cc.into_iter().map(|c| c.into()).collect());
        self
    }

    /// Sets BCC recipients.
    pub fn with_bcc(mut self, bcc: impl IntoIterator<Item = impl Into<String>>) -> Self {
        self.bcc = Some(bcc.into_iter().map(|b| b.into()).collect());
        self
    }

    /// Sets the reply-to address.
    pub fn with_reply_to(mut self, reply_to: impl Into<String>) -> Self {
        self.reply_to = Some(reply_to.into());
        self
    }

    /// Sets the file attachments.
    pub fn with_attachments(mut self, attachments: Vec<Attachment>) -> Self {
        self.attachments = Some(attachments);
        self
    }

    /// Sets tags for categorisation.
    pub fn with_tags(mut self, tags: impl IntoIterator<Item = impl Into<String>>) -> Self {
        self.tags = Some(tags.into_iter().map(|t| t.into()).collect());
        self
    }

    /// Sets arbitrary key-value metadata.
    pub fn with_metadata(mut self, metadata: HashMap<String, Value>) -> Self {
        self.metadata = Some(metadata);
        self
    }

    /// Sets open/click tracking overrides.
    pub fn with_tracking(mut self, tracking: Tracking) -> Self {
        self.tracking = Some(tracking);
        self
    }

    /// Schedules the email for later delivery at the given ISO-8601 datetime.
    pub fn with_scheduled_at(mut self, scheduled_at: impl Into<String>) -> Self {
        self.scheduled_at = Some(scheduled_at.into());
        self
    }
}

/// A file attachment to include in an email.
#[derive(Debug, Serialize, Deserialize)]
pub struct Attachment {
    /// File name as it will appear to the recipient.
    pub filename: String,
    /// Base64-encoded file content.
    pub content: String,
    /// MIME type (e.g. `"application/pdf"`). Inferred by the API if omitted.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub content_type: Option<String>,
}

impl Attachment {
    /// Creates an attachment with a filename and base64-encoded content.
    pub fn new(filename: impl Into<String>, content: impl Into<String>) -> Self {
        Self {
            filename: filename.into(),
            content: content.into(),
            content_type: None,
        }
    }

    /// Sets an explicit MIME type for this attachment.
    pub fn with_content_type(mut self, content_type: impl Into<String>) -> Self {
        self.content_type = Some(content_type.into());
        self
    }
}

/// Open and click tracking overrides for an email.
#[derive(Debug, Serialize, Deserialize)]
pub struct Tracking {
    /// Whether to track email opens.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub loads: Option<bool>,
    /// Whether to track link clicks.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub clicks: Option<bool>,
}

impl Tracking {
    /// Creates a new `Tracking` with no overrides set.
    pub fn new() -> Self {
        Self {
            loads: None,
            clicks: None,
        }
    }

    /// Enables or disables open tracking.
    pub fn with_loads(mut self, loads: bool) -> Self {
        self.loads = Some(loads);
        self
    }

    /// Enables or disables click tracking.
    pub fn with_clicks(mut self, clicks: bool) -> Self {
        self.clicks = Some(clicks);
        self
    }
}

impl Default for Tracking {
    fn default() -> Self {
        Self::new()
    }
}

/// An email returned by the Emailit API.
#[derive(Debug, Deserialize)]
pub struct Email {
    /// Unique email identifier.
    pub id: Option<String>,
    /// Object type (always `"email"`).
    pub object: Option<String>,
    /// Email type (e.g. `"transactional"`).
    #[serde(rename = "type")]
    pub email_type: Option<String>,
    /// Unique token for this email.
    pub token: Option<String>,
    /// SMTP Message-ID.
    pub message_id: Option<String>,
    /// Sender address.
    pub from: Option<String>,
    /// Recipient addresses.
    pub to: Option<Value>,
    /// CC addresses.
    pub cc: Option<Value>,
    /// BCC addresses.
    pub bcc: Option<Value>,
    /// Subject line.
    pub subject: Option<String>,
    /// Delivery status.
    pub status: Option<String>,
    /// Message size in bytes.
    pub size: Option<Value>,
    /// Scheduled delivery time.
    pub scheduled_at: Option<Value>,
    /// Creation timestamp.
    pub created_at: Option<String>,
    /// Last update timestamp.
    pub updated_at: Option<String>,
    /// Tracking settings.
    pub tracking: Option<Value>,
    /// Email metadata.
    pub meta: Option<Value>,
    /// Custom headers.
    pub headers: Option<Value>,
    /// Email body.
    pub body: Option<Value>,
    /// Raw email source.
    pub raw: Option<Value>,
    /// Attachments metadata.
    pub attachments: Option<Value>,
    /// Related IDs.
    pub ids: Option<Value>,
    /// Original email ID (for retries).
    pub original_id: Option<String>,
    /// Status message from the API.
    pub message: Option<String>,
}

/// The HTML and plain-text body of an email.
#[derive(Debug, Deserialize)]
pub struct EmailBody {
    /// Plain-text body.
    pub text: Option<String>,
    /// HTML body.
    pub html: Option<String>,
}

/// Query parameters for listing emails.
#[derive(Debug, Serialize)]
pub struct ListEmailsParams {
    /// Page number (1-based).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub page: Option<i64>,
    /// Maximum number of results per page.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<i64>,
}

/// Parameters for updating a scheduled email.
#[derive(Debug, Serialize)]
pub struct UpdateEmailParams {
    /// New scheduled delivery time (ISO-8601).
    pub scheduled_at: String,
}

// ---------------------------------------------------------------------------
// Domains
// ---------------------------------------------------------------------------

/// Parameters for adding a sending domain via `POST /v2/domains`.
#[derive(Debug, Serialize)]
pub struct CreateDomainParams {
    /// The domain name (e.g. `"example.com"`).
    pub name: String,
    /// Whether to enable open tracking for this domain.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub track_loads: Option<bool>,
    /// Whether to enable click tracking for this domain.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub track_clicks: Option<bool>,
}

impl CreateDomainParams {
    /// Creates params with the required domain name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            track_loads: None,
            track_clicks: None,
        }
    }

    /// Enables or disables open tracking.
    pub fn with_track_loads(mut self, track_loads: bool) -> Self {
        self.track_loads = Some(track_loads);
        self
    }

    /// Enables or disables click tracking.
    pub fn with_track_clicks(mut self, track_clicks: bool) -> Self {
        self.track_clicks = Some(track_clicks);
        self
    }
}

/// Parameters for updating an existing domain.
#[derive(Debug, Serialize)]
pub struct UpdateDomainParams {
    /// Whether to enable open tracking.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub track_loads: Option<bool>,
    /// Whether to enable click tracking.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub track_clicks: Option<bool>,
}

/// A sending domain returned by the Emailit API.
#[derive(Debug, Deserialize)]
pub struct Domain {
    /// Unique domain identifier.
    pub id: Option<String>,
    /// Object type (always `"domain"`).
    pub object: Option<String>,
    /// UUID of the domain.
    pub uuid: Option<String>,
    /// Domain name.
    pub name: Option<String>,
    /// DNS verification token.
    pub verification_token: Option<String>,
    /// Verification method used.
    pub verification_method: Option<String>,
    /// When the domain was verified.
    pub verified_at: Option<Value>,
    /// DKIM identifier string.
    pub dkim_identifier_string: Option<String>,
    /// When DNS records were last checked.
    pub dns_checked_at: Option<Value>,
    /// SPF record status.
    pub spf_status: Option<String>,
    /// SPF error details.
    pub spf_error: Option<Value>,
    /// DKIM record status.
    pub dkim_status: Option<String>,
    /// DKIM error details.
    pub dkim_error: Option<Value>,
    /// MX record status.
    pub mx_status: Option<String>,
    /// MX error details.
    pub mx_error: Option<Value>,
    /// Return-path record status.
    pub return_path_status: Option<String>,
    /// Return-path error details.
    pub return_path_error: Option<Value>,
    /// DMARC record status.
    pub dmarc_status: Option<String>,
    /// DMARC error details.
    pub dmarc_error: Option<Value>,
    /// Tracking CNAME status.
    pub tracking_status: Option<String>,
    /// Tracking CNAME error details.
    pub tracking_error: Option<Value>,
    /// Inbound routing status.
    pub inbound_status: Option<String>,
    /// Inbound routing error details.
    pub inbound_error: Option<Value>,
    /// Whether open tracking is enabled.
    pub track_loads: Option<bool>,
    /// Whether click tracking is enabled.
    pub track_clicks: Option<bool>,
    /// Required DNS records for verification.
    pub dns_records: Option<Value>,
    /// Whether the domain has been deleted.
    pub deleted: Option<bool>,
    /// Creation timestamp.
    pub created_at: Option<String>,
    /// Last update timestamp.
    pub updated_at: Option<String>,
}

// ---------------------------------------------------------------------------
// API Keys
// ---------------------------------------------------------------------------

/// Parameters for creating an API key via `POST /v2/api-keys`.
#[derive(Debug, Serialize)]
pub struct CreateApiKeyParams {
    /// Human-readable name for the key.
    pub name: String,
    /// Permission scope (e.g. `"full"`, `"sending"`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub scope: Option<String>,
    /// Restrict the key to a specific sending domain.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sending_domain_id: Option<String>,
}

impl CreateApiKeyParams {
    /// Creates params with the required key name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            scope: None,
            sending_domain_id: None,
        }
    }

    /// Sets the permission scope.
    pub fn with_scope(mut self, scope: impl Into<String>) -> Self {
        self.scope = Some(scope.into());
        self
    }

    /// Restricts the key to a specific sending domain ID.
    pub fn with_sending_domain_id(mut self, id: impl Into<String>) -> Self {
        self.sending_domain_id = Some(id.into());
        self
    }
}

/// Parameters for updating an existing API key.
#[derive(Debug, Serialize)]
pub struct UpdateApiKeyParams {
    /// New name for the key.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// New permission scope.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub scope: Option<String>,
    /// New sending domain restriction.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sending_domain_id: Option<String>,
}

/// An API key returned by the Emailit API.
#[derive(Debug, Deserialize)]
pub struct ApiKey {
    /// Unique key identifier.
    pub id: Option<String>,
    /// Object type (always `"api_key"`).
    pub object: Option<String>,
    /// Human-readable name.
    pub name: Option<String>,
    /// Permission scope.
    pub scope: Option<String>,
    /// Associated sending domain ID.
    pub sending_domain_id: Option<Value>,
    /// The secret key value (only returned on creation).
    pub key: Option<String>,
    /// When the key was last used.
    pub last_used_at: Option<Value>,
    /// Creation timestamp.
    pub created_at: Option<String>,
    /// Last update timestamp.
    pub updated_at: Option<String>,
    /// Whether the key has been deleted.
    pub deleted: Option<bool>,
}

// ---------------------------------------------------------------------------
// Audiences
// ---------------------------------------------------------------------------

/// Parameters for creating an audience via `POST /v2/audiences`.
#[derive(Debug, Serialize)]
pub struct CreateAudienceParams {
    /// Name of the audience.
    pub name: String,
}

impl CreateAudienceParams {
    /// Creates params with the required audience name.
    pub fn new(name: impl Into<String>) -> Self {
        Self { name: name.into() }
    }
}

/// Parameters for updating an existing audience.
#[derive(Debug, Serialize)]
pub struct UpdateAudienceParams {
    /// New audience name.
    pub name: String,
}

/// An audience (mailing list) returned by the Emailit API.
#[derive(Debug, Deserialize)]
pub struct Audience {
    /// Unique audience identifier.
    pub id: Option<String>,
    /// Object type (always `"audience"`).
    pub object: Option<String>,
    /// Audience name.
    pub name: Option<String>,
    /// Unique token for the audience.
    pub token: Option<String>,
    /// Creation timestamp.
    pub created_at: Option<String>,
    /// Last update timestamp.
    pub updated_at: Option<String>,
    /// Whether the audience has been deleted.
    pub deleted: Option<bool>,
}

// ---------------------------------------------------------------------------
// Subscribers
// ---------------------------------------------------------------------------

/// Parameters for adding a subscriber to an audience via
/// `POST /v2/audiences/:audience_id/subscribers`.
#[derive(Debug, Serialize)]
pub struct CreateSubscriberParams {
    /// Subscriber email address.
    pub email: String,
    /// Subscriber first name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub first_name: Option<String>,
    /// Subscriber last name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub last_name: Option<String>,
    /// Arbitrary custom fields.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub custom_fields: Option<HashMap<String, Value>>,
}

impl CreateSubscriberParams {
    /// Creates params with the required email address.
    pub fn new(email: impl Into<String>) -> Self {
        Self {
            email: email.into(),
            first_name: None,
            last_name: None,
            custom_fields: None,
        }
    }

    /// Sets the subscriber's first name.
    pub fn with_first_name(mut self, first_name: impl Into<String>) -> Self {
        self.first_name = Some(first_name.into());
        self
    }

    /// Sets the subscriber's last name.
    pub fn with_last_name(mut self, last_name: impl Into<String>) -> Self {
        self.last_name = Some(last_name.into());
        self
    }

    /// Sets arbitrary custom fields.
    pub fn with_custom_fields(mut self, fields: HashMap<String, Value>) -> Self {
        self.custom_fields = Some(fields);
        self
    }
}

/// Parameters for updating an existing subscriber.
#[derive(Debug, Serialize)]
pub struct UpdateSubscriberParams {
    /// New email address.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub email: Option<String>,
    /// New first name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub first_name: Option<String>,
    /// New last name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub last_name: Option<String>,
    /// Updated custom fields.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub custom_fields: Option<HashMap<String, Value>>,
    /// Whether the subscriber is subscribed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub subscribed: Option<bool>,
}

/// Query parameters for listing subscribers.
#[derive(Debug, Serialize)]
pub struct ListSubscribersParams {
    /// Page number (1-based).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub page: Option<i64>,
    /// Maximum number of results per page.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<i64>,
    /// Filter by subscription status.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub subscribed: Option<bool>,
}

/// A subscriber returned by the Emailit API.
#[derive(Debug, Deserialize)]
pub struct Subscriber {
    /// Unique subscriber identifier.
    pub id: Option<String>,
    /// Object type (always `"subscriber"`).
    pub object: Option<String>,
    /// Parent audience ID.
    pub audience_id: Option<String>,
    /// Associated contact ID.
    pub contact_id: Option<String>,
    /// Email address.
    pub email: Option<String>,
    /// First name.
    pub first_name: Option<String>,
    /// Last name.
    pub last_name: Option<String>,
    /// Custom fields.
    pub custom_fields: Option<Value>,
    /// Whether currently subscribed.
    pub subscribed: Option<bool>,
    /// When the subscriber opted in.
    pub subscribed_at: Option<Value>,
    /// When the subscriber opted out.
    pub unsubscribed_at: Option<Value>,
    /// Creation timestamp.
    pub created_at: Option<String>,
    /// Last update timestamp.
    pub updated_at: Option<String>,
    /// Whether the subscriber has been deleted.
    pub deleted: Option<bool>,
}

// ---------------------------------------------------------------------------
// Templates
// ---------------------------------------------------------------------------

/// Parameters for creating a template via `POST /v2/templates`.
#[derive(Debug, Serialize)]
pub struct CreateTemplateParams {
    /// Template name.
    pub name: String,
    /// Default subject line.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub subject: Option<String>,
    /// Default sender address.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub from: Option<String>,
    /// Default reply-to address.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reply_to: Option<String>,
    /// HTML content.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub html: Option<String>,
    /// Plain-text content.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub text: Option<String>,
}

impl CreateTemplateParams {
    /// Creates params with the required template name.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            subject: None,
            from: None,
            reply_to: None,
            html: None,
            text: None,
        }
    }

    /// Sets the default subject line.
    pub fn with_subject(mut self, subject: impl Into<String>) -> Self {
        self.subject = Some(subject.into());
        self
    }

    /// Sets the default sender address.
    pub fn with_from(mut self, from: impl Into<String>) -> Self {
        self.from = Some(from.into());
        self
    }

    /// Sets the default reply-to address.
    pub fn with_reply_to(mut self, reply_to: impl Into<String>) -> Self {
        self.reply_to = Some(reply_to.into());
        self
    }

    /// Sets the HTML content.
    pub fn with_html(mut self, html: impl Into<String>) -> Self {
        self.html = Some(html.into());
        self
    }

    /// Sets the plain-text content.
    pub fn with_text(mut self, text: impl Into<String>) -> Self {
        self.text = Some(text.into());
        self
    }
}

/// Parameters for updating an existing template.
#[derive(Debug, Serialize)]
pub struct UpdateTemplateParams {
    /// New template name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// New default subject line.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub subject: Option<String>,
    /// New default sender address.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub from: Option<String>,
    /// New default reply-to address.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reply_to: Option<String>,
    /// New HTML content.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub html: Option<String>,
    /// New plain-text content.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub text: Option<String>,
}

/// A template returned by the Emailit API.
#[derive(Debug, Deserialize)]
pub struct Template {
    /// Unique template identifier.
    pub id: Option<String>,
    /// Object type (always `"template"`).
    pub object: Option<String>,
    /// Template name.
    pub name: Option<String>,
    /// Template alias for use in send calls.
    pub alias: Option<String>,
    /// Default sender address.
    pub from: Option<String>,
    /// Default subject line.
    pub subject: Option<String>,
    /// Default reply-to address.
    pub reply_to: Option<String>,
    /// HTML content.
    pub html: Option<String>,
    /// Plain-text content.
    pub text: Option<String>,
    /// Editor type used to create the template.
    pub editor: Option<String>,
    /// When the template was last published.
    pub published_at: Option<Value>,
    /// URL to preview the template.
    pub preview_url: Option<String>,
    /// Number of saved versions.
    pub total_versions: Option<i64>,
    /// Saved version history.
    pub versions: Option<Value>,
    /// Status message from the API.
    pub message: Option<String>,
    /// Creation timestamp.
    pub created_at: Option<String>,
    /// Last update timestamp.
    pub updated_at: Option<String>,
    /// Whether the template has been deleted.
    pub deleted: Option<bool>,
}

// ---------------------------------------------------------------------------
// Suppressions
// ---------------------------------------------------------------------------

/// Parameters for creating a suppression via `POST /v2/suppressions`.
#[derive(Debug, Serialize)]
pub struct CreateSuppressionParams {
    /// Email address to suppress.
    pub email: String,
    /// Suppression type (e.g. `"bounce"`, `"complaint"`).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(rename = "type")]
    pub suppression_type: Option<String>,
    /// Reason for the suppression.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
}

impl CreateSuppressionParams {
    /// Creates params with the required email address.
    pub fn new(email: impl Into<String>) -> Self {
        Self {
            email: email.into(),
            suppression_type: None,
            reason: None,
        }
    }

    /// Sets the suppression type.
    pub fn with_type(mut self, suppression_type: impl Into<String>) -> Self {
        self.suppression_type = Some(suppression_type.into());
        self
    }

    /// Sets the reason for the suppression.
    pub fn with_reason(mut self, reason: impl Into<String>) -> Self {
        self.reason = Some(reason.into());
        self
    }
}

/// Parameters for updating an existing suppression.
#[derive(Debug, Serialize)]
pub struct UpdateSuppressionParams {
    /// New reason text.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub reason: Option<String>,
    /// Date until which to keep the suppression (ISO-8601).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub keep_until: Option<String>,
}

/// A suppression entry returned by the Emailit API.
#[derive(Debug, Deserialize)]
pub struct Suppression {
    /// Unique suppression identifier.
    pub id: Option<String>,
    /// Object type (always `"suppression"`).
    pub object: Option<String>,
    /// Suppressed email address.
    pub email: Option<String>,
    /// Suppression type.
    #[serde(rename = "type")]
    pub suppression_type: Option<String>,
    /// Reason for the suppression.
    pub reason: Option<String>,
    /// When the suppression was created.
    pub timestamp: Option<Value>,
    /// When the suppression expires.
    pub keep_until: Option<Value>,
    /// Whether the suppression has been deleted.
    pub deleted: Option<bool>,
}

// ---------------------------------------------------------------------------
// Email Verifications
// ---------------------------------------------------------------------------

/// Parameters for verifying a single email address via
/// `POST /v2/email-verifications`.
#[derive(Debug, Serialize)]
pub struct VerifyEmailParams {
    /// Email address to verify.
    pub email: String,
    /// Verification mode (e.g. `"default"`, `"strict"`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub mode: Option<String>,
}

impl VerifyEmailParams {
    /// Creates params with the required email address.
    pub fn new(email: impl Into<String>) -> Self {
        Self {
            email: email.into(),
            mode: None,
        }
    }

    /// Sets the verification mode.
    pub fn with_mode(mut self, mode: impl Into<String>) -> Self {
        self.mode = Some(mode.into());
        self
    }
}

/// The result of a single email verification.
#[derive(Debug, Deserialize)]
pub struct EmailVerification {
    /// Unique verification identifier.
    pub id: Option<String>,
    /// Object type (always `"email_verification"`).
    pub object: Option<String>,
    /// Verified email address.
    pub email: Option<String>,
    /// Verification status.
    pub status: Option<String>,
    /// Deliverability score (0.0 -- 1.0).
    pub score: Option<f64>,
    /// Risk level.
    pub risk: Option<String>,
    /// Verification result.
    pub result: Option<String>,
    /// Verification mode used.
    pub mode: Option<String>,
    /// Detailed check results.
    pub checks: Option<Value>,
    /// Parsed address components.
    pub address: Option<Value>,
    /// Suggested correction if a typo was detected.
    pub did_you_mean: Option<Value>,
    /// MX records for the domain.
    pub mx_records: Option<Value>,
}

// ---------------------------------------------------------------------------
// Email Verification Lists
// ---------------------------------------------------------------------------

/// Parameters for creating a bulk verification list via
/// `POST /v2/email-verification-lists`.
#[derive(Debug, Serialize)]
pub struct CreateEmailVerificationListParams {
    /// Name of the verification list.
    pub name: String,
    /// Email addresses to verify.
    pub emails: Vec<String>,
}

impl CreateEmailVerificationListParams {
    /// Creates params with the required list name and email addresses.
    pub fn new(
        name: impl Into<String>,
        emails: impl IntoIterator<Item = impl Into<String>>,
    ) -> Self {
        Self {
            name: name.into(),
            emails: emails.into_iter().map(|e| e.into()).collect(),
        }
    }
}

/// Query parameters for listing email verification lists.
#[derive(Debug, Serialize)]
pub struct ListEmailVerificationListsParams {
    /// Page number (1-based).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub page: Option<i64>,
    /// Maximum number of results per page.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<i64>,
}

/// Query parameters for fetching verification list results.
#[derive(Debug, Serialize)]
pub struct EmailVerificationListResultsParams {
    /// Page number (1-based).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub page: Option<i64>,
    /// Maximum number of results per page.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<i64>,
}

/// A bulk email verification list returned by the Emailit API.
#[derive(Debug, Deserialize)]
pub struct EmailVerificationList {
    /// Unique list identifier.
    pub id: Option<String>,
    /// Object type (always `"email_verification_list"`).
    pub object: Option<String>,
    /// List name.
    pub name: Option<String>,
    /// Processing status.
    pub status: Option<String>,
    /// Verification statistics.
    pub stats: Option<Value>,
    /// Creation timestamp.
    pub created_at: Option<String>,
    /// Last update timestamp.
    pub updated_at: Option<String>,
}

// ---------------------------------------------------------------------------
// Webhooks
// ---------------------------------------------------------------------------

/// Parameters for creating a webhook endpoint via `POST /v2/webhooks`.
#[derive(Debug, Serialize)]
pub struct CreateWebhookParams {
    /// Human-readable name for the webhook.
    pub name: String,
    /// URL to receive webhook POST requests.
    pub url: String,
    /// Subscribe to all event types.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub all_events: Option<bool>,
    /// Whether the webhook is enabled.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub enabled: Option<bool>,
    /// Specific event types to subscribe to.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub events: Option<Vec<String>>,
}

impl CreateWebhookParams {
    /// Creates params with the required name and endpoint URL.
    pub fn new(name: impl Into<String>, url: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            url: url.into(),
            all_events: None,
            enabled: None,
            events: None,
        }
    }

    /// Subscribes to all event types when `true`.
    pub fn with_all_events(mut self, all_events: bool) -> Self {
        self.all_events = Some(all_events);
        self
    }

    /// Enables or disables the webhook.
    pub fn with_enabled(mut self, enabled: bool) -> Self {
        self.enabled = Some(enabled);
        self
    }

    /// Sets the specific event types to subscribe to.
    pub fn with_events(mut self, events: impl IntoIterator<Item = impl Into<String>>) -> Self {
        self.events = Some(events.into_iter().map(|e| e.into()).collect());
        self
    }
}

/// Parameters for updating an existing webhook endpoint.
#[derive(Debug, Serialize)]
pub struct UpdateWebhookParams {
    /// New webhook name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// New endpoint URL.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    /// Subscribe to all event types.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub all_events: Option<bool>,
    /// Whether the webhook is enabled.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub enabled: Option<bool>,
    /// Specific event types to subscribe to.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub events: Option<Vec<String>>,
}

/// A webhook endpoint returned by the Emailit API.
#[derive(Debug, Deserialize)]
pub struct Webhook {
    /// Unique webhook identifier.
    pub id: Option<String>,
    /// Object type (always `"webhook"`).
    pub object: Option<String>,
    /// Webhook name.
    pub name: Option<String>,
    /// Endpoint URL.
    pub url: Option<String>,
    /// Whether all event types are subscribed.
    pub all_events: Option<bool>,
    /// Whether the webhook is enabled.
    pub enabled: Option<bool>,
    /// Subscribed event types.
    pub events: Option<Value>,
    /// When the webhook was last triggered.
    pub last_used_at: Option<Value>,
    /// Creation timestamp.
    pub created_at: Option<String>,
    /// Last update timestamp.
    pub updated_at: Option<String>,
    /// Whether the webhook has been deleted.
    pub deleted: Option<bool>,
}

// ---------------------------------------------------------------------------
// Contacts
// ---------------------------------------------------------------------------

/// Parameters for creating a contact via `POST /v2/contacts`.
#[derive(Debug, Serialize)]
pub struct CreateContactParams {
    /// Contact email address.
    pub email: String,
    /// Contact first name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub first_name: Option<String>,
    /// Contact last name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub last_name: Option<String>,
    /// Arbitrary custom fields.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub custom_fields: Option<HashMap<String, Value>>,
}

impl CreateContactParams {
    /// Creates params with the required email address.
    pub fn new(email: impl Into<String>) -> Self {
        Self {
            email: email.into(),
            first_name: None,
            last_name: None,
            custom_fields: None,
        }
    }

    /// Sets the contact's first name.
    pub fn with_first_name(mut self, first_name: impl Into<String>) -> Self {
        self.first_name = Some(first_name.into());
        self
    }

    /// Sets the contact's last name.
    pub fn with_last_name(mut self, last_name: impl Into<String>) -> Self {
        self.last_name = Some(last_name.into());
        self
    }

    /// Sets arbitrary custom fields.
    pub fn with_custom_fields(mut self, fields: HashMap<String, Value>) -> Self {
        self.custom_fields = Some(fields);
        self
    }
}

/// Parameters for updating an existing contact.
#[derive(Debug, Serialize)]
pub struct UpdateContactParams {
    /// New email address.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub email: Option<String>,
    /// New first name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub first_name: Option<String>,
    /// New last name.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub last_name: Option<String>,
    /// Updated custom fields.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub custom_fields: Option<HashMap<String, Value>>,
    /// Whether the contact is unsubscribed.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub unsubscribed: Option<bool>,
}

/// A contact returned by the Emailit API.
#[derive(Debug, Deserialize)]
pub struct Contact {
    /// Unique contact identifier.
    pub id: Option<String>,
    /// Object type (always `"contact"`).
    pub object: Option<String>,
    /// Email address.
    pub email: Option<String>,
    /// First name.
    pub first_name: Option<String>,
    /// Last name.
    pub last_name: Option<String>,
    /// Custom fields.
    pub custom_fields: Option<Value>,
    /// Whether the contact is unsubscribed.
    pub unsubscribed: Option<bool>,
    /// Audiences the contact belongs to.
    pub audiences: Option<Value>,
    /// Creation timestamp.
    pub created_at: Option<String>,
    /// Last update timestamp.
    pub updated_at: Option<String>,
    /// Whether the contact has been deleted.
    pub deleted: Option<bool>,
}

// ---------------------------------------------------------------------------
// Events
// ---------------------------------------------------------------------------

/// Query parameters for listing events.
#[derive(Debug, Serialize)]
pub struct ListEventsParams {
    /// Page number (1-based).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub page: Option<i64>,
    /// Maximum number of results per page.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<i64>,
    /// Filter by event type (e.g. `"email.delivered"`).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[serde(rename = "type")]
    pub event_type: Option<String>,
}

/// An event from the Emailit event log.
#[derive(Debug, Deserialize)]
pub struct Event {
    /// Unique event identifier.
    pub id: Option<String>,
    /// Object type (always `"event"`).
    pub object: Option<String>,
    /// Event type (e.g. `"email.delivered"`, `"email.bounced"`).
    #[serde(rename = "type")]
    pub event_type: Option<String>,
    /// Event payload data.
    pub data: Option<Value>,
    /// When the event occurred.
    pub created_at: Option<String>,
}

// ---------------------------------------------------------------------------
// Webhook Events
// ---------------------------------------------------------------------------

/// A parsed webhook event payload, returned by
/// [`verify_webhook_signature`](crate::verify_webhook_signature).
#[derive(Debug, Deserialize)]
pub struct WebhookEvent {
    /// Event type (e.g. `"email.delivered"`).
    #[serde(rename = "type")]
    pub event_type: String,
    /// Event payload data.
    pub data: Option<Value>,
    /// Unique event identifier.
    pub event_id: Option<String>,
    /// Event timestamp.
    pub timestamp: Option<Value>,
}

// ---------------------------------------------------------------------------
// Shared list params helper
// ---------------------------------------------------------------------------

/// Generic pagination parameters reused by several list endpoints.
#[derive(Debug, Serialize)]
pub struct ListParams {
    /// Page number (1-based).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub page: Option<i64>,
    /// Maximum number of results per page.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit: Option<i64>,
}

impl ListParams {
    /// Creates empty list params (no pagination filters).
    pub fn new() -> Self {
        Self {
            page: None,
            limit: None,
        }
    }
}

impl Default for ListParams {
    fn default() -> Self {
        Self::new()
    }
}