linear-api 0.1.0

//! Shared scalar types, server enums, three-state input support
//! ([`Undefinable`]), and the canonical Ref/Stub structs used across modules.

use serde::{Deserialize, Deserializer, Serialize, Serializer};

use crate::ids::{
    IssueId, LabelId, ProjectId, ProjectMilestoneId, TeamId, UserId, WorkflowStateId,
};

const TIMELESS_DATE_FORMAT: &[time::format_description::BorrowedFormatItem<'static>] =
    time::macros::format_description!("[year]-[month]-[day]");

/// Linear's `TimelessDate` scalar: a calendar date with no time component,
/// serialized as `"YYYY-MM-DD"`.
///
/// A newtype (rather than a serde `with` module) so it composes inside
/// `Option<_>`, [`Undefinable<_>`], and `Vec<_>` without field attributes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TimelessDate(pub time::Date);

impl std::fmt::Display for TimelessDate {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let formatted = self
            .0
            .format(TIMELESS_DATE_FORMAT)
            .map_err(|_| std::fmt::Error)?;
        f.write_str(&formatted)
    }
}

impl std::str::FromStr for TimelessDate {
    type Err = time::error::Parse;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        time::Date::parse(s, TIMELESS_DATE_FORMAT).map(Self)
    }
}

impl From<time::Date> for TimelessDate {
    fn from(date: time::Date) -> Self {
        Self(date)
    }
}

impl Serialize for TimelessDate {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.collect_str(self)
    }
}

impl<'de> Deserialize<'de> for TimelessDate {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let s = String::deserialize(deserializer)?;
        s.parse().map_err(serde::de::Error::custom)
    }
}

/// GraphQL nullable-input tri-state: absent (leave unchanged) / `null`
/// (clear) / value (set).
///
/// Input convention across this crate: **create inputs** use `Option<T>` with
/// `#[serde(skip_serializing_if = "Option::is_none")]` (absent-when-`None`);
/// **update inputs** use `Undefinable<T>` for clearable fields, with
/// `#[serde(skip_serializing_if = "Undefinable::is_undefined", default)]` and
/// `#[builder(default, into)]`.
#[derive(Debug, Clone, Default, PartialEq)]
pub enum Undefinable<T> {
    /// Field is omitted from the request: leave unchanged.
    #[default]
    Undefined,
    /// Field is sent as `null`: clear the value.
    Null,
    /// Field is sent with a concrete value: set it.
    Value(T),
}

impl<T> Undefinable<T> {
    /// `true` when the field should be omitted from serialization entirely.
    pub fn is_undefined(&self) -> bool {
        matches!(self, Undefinable::Undefined)
    }
}

impl<T> From<T> for Undefinable<T> {
    fn from(value: T) -> Self {
        Undefinable::Value(value)
    }
}

impl<T: Serialize> Serialize for Undefinable<T> {
    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        match self {
            // `Undefined` is never reached when fields carry
            // `#[serde(skip_serializing_if = "Undefinable::is_undefined")]`;
            // serializing it as `null` is the safe fallback.
            Undefinable::Undefined | Undefinable::Null => serializer.serialize_none(),
            Undefinable::Value(value) => value.serialize(serializer),
        }
    }
}

/// Issue priority. On the wire this is an integer `0..=4`:
/// 0 = no priority, 1 = urgent, 2 = high, 3 = medium, 4 = low.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(from = "u8", into = "u8")]
#[non_exhaustive]
pub enum Priority {
    /// No priority set (0).
    None,
    /// Urgent (1).
    Urgent,
    /// High (2).
    High,
    /// Medium (3).
    Medium,
    /// Low (4).
    Low,
    /// A numeric value outside `0..=4` (future-proofing).
    Other(u8),
}

impl From<u8> for Priority {
    fn from(value: u8) -> Self {
        match value {
            0 => Priority::None,
            1 => Priority::Urgent,
            2 => Priority::High,
            3 => Priority::Medium,
            4 => Priority::Low,
            other => Priority::Other(other),
        }
    }
}

impl From<Priority> for u8 {
    fn from(value: Priority) -> Self {
        match value {
            Priority::None => 0,
            Priority::Urgent => 1,
            Priority::High => 2,
            Priority::Medium => 3,
            Priority::Low => 4,
            Priority::Other(other) => other,
        }
    }
}

/// Sort order for paginated list queries.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub enum PaginationOrderBy {
    /// Order by creation time (`"createdAt"`).
    CreatedAt,
    /// Order by last update time (`"updatedAt"`).
    UpdatedAt,
}

macro_rules! string_enum {
    (
        $(#[$meta:meta])*
        $name:ident {
            $($(#[$vmeta:meta])* $variant:ident => $wire:literal,)+
        }
    ) => {
        $(#[$meta])*
        #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
        #[serde(from = "String", into = "String")]
        #[non_exhaustive]
        pub enum $name {
            $($(#[$vmeta])* $variant,)+
            /// A wire value this crate does not know about (server-added
            /// variants deserialize here instead of failing).
            Unrecognized(String),
        }

        impl From<String> for $name {
            fn from(s: String) -> Self {
                match s.as_str() {
                    $($wire => Self::$variant,)+
                    _ => Self::Unrecognized(s),
                }
            }
        }

        impl From<$name> for String {
            fn from(v: $name) -> String {
                match v {
                    $($name::$variant => $wire.to_string(),)+
                    $name::Unrecognized(s) => s,
                }
            }
        }
    };
}

string_enum! {
    /// The kind of a workflow state (column category on a Linear board).
    WorkflowStateType {
        /// Triage inbox.
        Triage => "triage",
        /// Backlog.
        Backlog => "backlog",
        /// Not started yet.
        Unstarted => "unstarted",
        /// In progress.
        Started => "started",
        /// Done.
        Completed => "completed",
        /// Canceled.
        Canceled => "canceled",
    }
}

string_enum! {
    /// The kind of an issue relation.
    ///
    /// There is **no** `blockedBy` value — direction is positional:
    /// `issueId` *blocks* `relatedIssueId` in `issueRelationCreate`.
    IssueRelationType {
        /// The issue blocks the related issue.
        Blocks => "blocks",
        /// The issue duplicates the related issue.
        Duplicate => "duplicate",
        /// The issues are related.
        Related => "related",
        /// The issues are similar.
        Similar => "similar",
    }
}

string_enum! {
    /// The kind of a project status.
    ProjectStatusType {
        /// Backlog.
        Backlog => "backlog",
        /// Planned.
        Planned => "planned",
        /// In progress.
        Started => "started",
        /// Paused.
        Paused => "paused",
        /// Done.
        Completed => "completed",
        /// Canceled.
        Canceled => "canceled",
    }
}

string_enum! {
    /// Project health as reported in project updates.
    ProjectHealth {
        /// On track (`"onTrack"`).
        OnTrack => "onTrack",
        /// At risk (`"atRisk"`).
        AtRisk => "atRisk",
        /// Off track (`"offTrack"`).
        OffTrack => "offTrack",
    }
}

/// Minimal reference to a user.
///
/// Canonical fragment:
/// `fragment UserRefFields on User { id name displayName }`
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct UserRef {
    /// User ID.
    pub id: UserId,
    /// Full name.
    pub name: String,
    /// Display (handle) name.
    pub display_name: String,
}

/// Minimal reference to a team.
///
/// Canonical fragment:
/// `fragment TeamRefFields on Team { id key name }`
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct TeamRef {
    /// Team ID.
    pub id: TeamId,
    /// Team key, e.g. `"ENG"`.
    pub key: String,
    /// Team name.
    pub name: String,
}

/// Minimal reference to a project.
///
/// Canonical fragment:
/// `fragment ProjectRefFields on Project { id name }`
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct ProjectRef {
    /// Project ID.
    pub id: ProjectId,
    /// Project name.
    pub name: String,
}

/// Minimal reference to an issue.
///
/// Canonical fragment:
/// `fragment IssueStubFields on Issue { id identifier title }`
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct IssueStub {
    /// Issue ID.
    pub id: IssueId,
    /// Human identifier, e.g. `"ENG-123"`.
    pub identifier: String,
    /// Issue title.
    pub title: String,
}

/// Minimal reference to an issue label.
///
/// Canonical fragment:
/// `fragment LabelRefFields on IssueLabel { id name color }`
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct LabelRef {
    /// Label ID.
    pub id: LabelId,
    /// Label name.
    pub name: String,
    /// Label color as a hex string.
    pub color: String,
}

/// Minimal reference to a workflow state.
///
/// Canonical fragment:
/// `fragment StateRefFields on WorkflowState { id name type color }`
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct StateRef {
    /// Workflow state ID.
    pub id: WorkflowStateId,
    /// State name, e.g. `"In Progress"`.
    pub name: String,
    /// State category.
    #[serde(rename = "type")]
    pub state_type: WorkflowStateType,
    /// State color as a hex string.
    pub color: String,
}

/// Minimal reference to a project milestone.
///
/// Canonical fragment:
/// `fragment MilestoneRefFields on ProjectMilestone { id name }`
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct MilestoneRef {
    /// Milestone ID.
    pub id: ProjectMilestoneId,
    /// Milestone name.
    pub name: String,
}

/// Deserializes a GraphQL connection object `{"nodes": [...]}` directly into
/// a `Vec<T>`.
///
/// Use as `#[serde(deserialize_with = "crate::types::nodes")]` on embedded
/// connection fields such as an issue's `labels`.
pub fn nodes<'de, D, T>(deserializer: D) -> Result<Vec<T>, D::Error>
where
    D: Deserializer<'de>,
    T: Deserialize<'de>,
{
    #[derive(Deserialize)]
    struct Nodes<T> {
        nodes: Vec<T>,
    }
    Ok(Nodes::deserialize(deserializer)?.nodes)
}

/// Maps a mutation payload's `success: false` (with no GraphQL errors) to
/// [`Error::MutationFailed`](crate::Error::MutationFailed).
pub(crate) fn ensure_success(operation: &'static str, success: bool) -> crate::Result<()> {
    if success {
        Ok(())
    } else {
        Err(crate::Error::MutationFailed { operation })
    }
}

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

    #[test]
    fn timeless_date_roundtrip() {
        let date: TimelessDate = "2026-07-05".parse().unwrap();
        assert_eq!(date.to_string(), "2026-07-05");
        assert_eq!(serde_json::to_string(&date).unwrap(), "\"2026-07-05\"");
        let back: TimelessDate = serde_json::from_str("\"2026-07-05\"").unwrap();
        assert_eq!(back, date);
        assert!("not-a-date".parse::<TimelessDate>().is_err());
    }

    #[test]
    fn undefinable_serializes_null_and_value() {
        #[derive(Serialize)]
        struct Input {
            #[serde(skip_serializing_if = "Undefinable::is_undefined")]
            a: Undefinable<u32>,
            #[serde(skip_serializing_if = "Undefinable::is_undefined")]
            b: Undefinable<u32>,
            #[serde(skip_serializing_if = "Undefinable::is_undefined")]
            c: Undefinable<u32>,
        }
        let value = serde_json::to_value(Input {
            a: Undefinable::Undefined,
            b: Undefinable::Null,
            c: Undefinable::Value(7),
        })
        .unwrap();
        assert_eq!(value, serde_json::json!({ "b": null, "c": 7 }));
    }

    #[test]
    fn priority_maps_ints_both_ways() {
        assert_eq!(
            serde_json::from_str::<Priority>("1").unwrap(),
            Priority::Urgent
        );
        assert_eq!(serde_json::to_string(&Priority::Low).unwrap(), "4");
        assert_eq!(
            serde_json::from_str::<Priority>("9").unwrap(),
            Priority::Other(9)
        );
    }

    #[test]
    fn string_enums_keep_unrecognized_values() {
        let state: WorkflowStateType = serde_json::from_str("\"started\"").unwrap();
        assert_eq!(state, WorkflowStateType::Started);
        let novel: WorkflowStateType = serde_json::from_str("\"paused\"").unwrap();
        assert_eq!(novel, WorkflowStateType::Unrecognized("paused".into()));
        assert_eq!(
            serde_json::to_string(&ProjectHealth::OnTrack).unwrap(),
            "\"onTrack\""
        );
    }

    #[test]
    fn nodes_unwraps_connections() {
        #[derive(Deserialize)]
        struct Holder {
            #[serde(deserialize_with = "crate::types::nodes")]
            labels: Vec<String>,
        }
        let holder: Holder =
            serde_json::from_value(serde_json::json!({ "labels": { "nodes": ["a", "b"] } }))
                .unwrap();
        assert_eq!(holder.labels, vec!["a", "b"]);
    }

    #[test]
    fn ensure_success_maps_false() {
        assert!(ensure_success("Test", true).is_ok());
        assert!(matches!(
            ensure_success("Test", false),
            Err(crate::Error::MutationFailed { operation: "Test" })
        ));
    }
}