linear_api/

comments.rs

//! Issue comment threads: read an issue's comments and create, update, or
//! delete comments (threading included).
//!
//! Entry point: [`LinearClient::comments`].
//!
//! ```no_run
//! # async fn run() -> linear_api::Result<()> {
//! use linear_api::comments::CommentListRequest;
//! use linear_api::{IssueRef, LinearClient};
//!
//! let client = LinearClient::from_env()?;
//! // The "last 5 comments" deep-view call shape:
//! let page = client
//!     .comments()
//!     .list_for_issue(
//!         IssueRef::identifier("ENG-123"),
//!         CommentListRequest::builder().first(5).build(),
//!     )
//!     .await?;
//! for comment in &page.nodes {
//!     println!("{}", comment.body);
//! }
//! # Ok(()) }
//! ```

use bon::Builder;
use futures::Stream;
use serde::{Deserialize, Serialize};
use time::OffsetDateTime;

use crate::client::LinearClient;
use crate::error::{Error, Result};
use crate::ids::{CommentId, IssueRef};
use crate::pagination::{Page, PageInfo};
use crate::types::{UserRef, ensure_success};

/// Appends the canonical `CommentFields` fragment (and the `UserRefFields`
/// fragment it depends on) to an operation. Field sets MUST stay in sync with
/// [`Comment`] and [`UserRef`].
macro_rules! with_comment_fragments {
    ($op:literal) => {
        concat!(
            $op,
            " fragment CommentFields on Comment {",
            " id body url user { ...UserRefFields }",
            " createdAt editedAt resolvedAt parent { id } }",
            " fragment UserRefFields on User { id name displayName }",
        )
    };
}

const COMMENTS_FOR_ISSUE: &str = with_comment_fragments!(
    "query CommentsForIssue($id: String!, $first: Int, $after: String) { \
     issue(id: $id) { comments(first: $first, after: $after) { \
     nodes { ...CommentFields } \
     pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } } }"
);

const COMMENT_CREATE: &str = with_comment_fragments!(
    "mutation CommentCreate($input: CommentCreateInput!) { \
     commentCreate(input: $input) { success comment { ...CommentFields } } }"
);

const COMMENT_UPDATE: &str = with_comment_fragments!(
    "mutation CommentUpdate($id: String!, $input: CommentUpdateInput!) { \
     commentUpdate(id: $id, input: $input) { success comment { ...CommentFields } } }"
);

const COMMENT_DELETE: &str =
    "mutation CommentDelete($id: String!) { commentDelete(id: $id) { success } }";

pub(crate) const DOCUMENTS: &[(&str, &str)] = &[
    ("CommentsForIssue", COMMENTS_FOR_ISSUE),
    ("CommentCreate", COMMENT_CREATE),
    ("CommentUpdate", COMMENT_UPDATE),
    ("CommentDelete", COMMENT_DELETE),
];

/// One comment on an issue.
///
/// Wire shape: the canonical fragment
/// `fragment CommentFields on Comment { id body url user { ...UserRefFields }
/// createdAt editedAt resolvedAt parent { id } }`.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct Comment {
    /// Comment ID.
    pub id: CommentId,
    /// The comment content, in markdown.
    pub body: String,
    /// URL of the comment on linear.app.
    pub url: String,
    /// The author. `None` for some integration-authored comments (e.g. bots
    /// posting via `createAsUser`).
    #[serde(default)]
    pub user: Option<UserRef>,
    /// When the comment was created.
    #[serde(with = "time::serde::rfc3339")]
    pub created_at: OffsetDateTime,
    /// When the comment was last edited, if ever.
    #[serde(default, with = "time::serde::rfc3339::option")]
    pub edited_at: Option<OffsetDateTime>,
    /// When the comment thread was resolved, if it has been.
    #[serde(default, with = "time::serde::rfc3339::option")]
    pub resolved_at: Option<OffsetDateTime>,
    /// The parent comment when this comment is a threaded reply.
    #[serde(default)]
    pub parent: Option<CommentParent>,
}

/// Reference to the parent of a threaded comment.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct CommentParent {
    /// Parent comment ID.
    pub id: CommentId,
}

/// Pagination controls for [`CommentsService::list_for_issue`].
///
/// For the "latest N comments" pattern pass `first: N`; ordering follows
/// Linear's default connection order (`createdAt`).
///
/// ```
/// use linear_api::comments::CommentListRequest;
///
/// let req = CommentListRequest::builder().first(5).build();
/// assert_eq!(req.first, Some(5));
/// ```
#[derive(Debug, Clone, Default, Serialize, Builder)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct CommentListRequest {
    /// Page size (server default 50). Page size multiplies query complexity;
    /// prefer modest values.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub first: Option<i32>,
    /// Cursor to resume from — a previous page's
    /// [`end_cursor`](crate::PageInfo::end_cursor).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[builder(into)]
    pub after: Option<String>,
}

/// Input for [`CommentsService::create`] (`commentCreate`).
///
/// ```
/// use linear_api::comments::CommentCreateInput;
///
/// let input = CommentCreateInput::builder()
///     .issue_id("ENG-123")
///     .body("Deployed to staging.".to_owned())
///     .build();
/// assert_eq!(input.issue_id, "ENG-123");
/// ```
#[derive(Debug, Clone, Serialize, Builder)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct CommentCreateInput {
    /// The issue to comment on. Pass `IssueId.to_string()` or an `"ENG-123"`
    /// identifier string; the UUID is the safest form.
    #[builder(into)]
    pub issue_id: String,
    /// The comment content, in markdown.
    pub body: String,
    /// Parent comment to nest this comment under (threading).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub parent_id: Option<CommentId>,
    /// Attribution label for bot-style comments: create the comment as a
    /// user with this name (only honored for OAuth apps in `actor=app` mode).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub create_as_user: Option<String>,
}

/// Wire input for `commentUpdate` — internal; the public surface is
/// [`CommentsService::update`]'s `body` parameter.
#[derive(Serialize)]
struct CommentUpdateInput {
    body: String,
}

/// Comment operations, obtained via [`LinearClient::comments`].
///
/// ```no_run
/// # async fn run() -> linear_api::Result<()> {
/// let client = linear_api::LinearClient::from_env()?;
/// let comment = client
///     .comments()
///     .create_on(linear_api::IssueRef::identifier("ENG-123"), "On it.")
///     .await?;
/// println!("created {}", comment.url);
/// # Ok(()) }
/// ```
#[derive(Clone, Copy)]
pub struct CommentsService<'a> {
    client: &'a LinearClient,
}

impl LinearClient {
    /// Comment operations: read an issue's thread, create, update, delete.
    ///
    /// ```no_run
    /// # async fn run() -> linear_api::Result<()> {
    /// # let client = linear_api::LinearClient::from_env()?;
    /// let comments = client.comments();
    /// # Ok(()) }
    /// ```
    pub fn comments(&self) -> CommentsService<'_> {
        CommentsService { client: self }
    }
}

impl<'a> CommentsService<'a> {
    /// Fetches one page of an issue's comment thread
    /// (`issue(id:) { comments }`).
    ///
    /// For the "latest N comments" pattern pass `first: N` on the request;
    /// ordering follows Linear's default connection order (`createdAt`).
    ///
    /// ```no_run
    /// # async fn run() -> linear_api::Result<()> {
    /// # let client = linear_api::LinearClient::from_env()?;
    /// use linear_api::IssueRef;
    /// use linear_api::comments::CommentListRequest;
    ///
    /// let page = client
    ///     .comments()
    ///     .list_for_issue(
    ///         IssueRef::identifier("ENG-123"),
    ///         CommentListRequest::builder().first(5).build(),
    ///     )
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub async fn list_for_issue(
        &self,
        issue: impl Into<IssueRef>,
        req: CommentListRequest,
    ) -> Result<Page<Comment>> {
        #[derive(Serialize)]
        struct Vars<'v> {
            id: &'v str,
            #[serde(skip_serializing_if = "Option::is_none")]
            first: Option<i32>,
            #[serde(skip_serializing_if = "Option::is_none")]
            after: Option<&'v str>,
        }
        #[derive(Deserialize)]
        struct Data {
            issue: IssueNode,
        }
        #[derive(Deserialize)]
        struct IssueNode {
            comments: Connection,
        }
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Connection {
            nodes: Vec<Comment>,
            page_info: PageInfo,
        }

        let issue = issue.into();
        let data: Data = self
            .client
            .query(
                "CommentsForIssue",
                COMMENTS_FOR_ISSUE,
                Vars {
                    id: issue.api_string(),
                    first: req.first,
                    after: req.after.as_deref(),
                },
            )
            .await?;
        Ok(Page {
            nodes: data.issue.comments.nodes,
            page_info: data.issue.comments.page_info,
        })
    }

    /// Lazily streams an issue's whole comment thread across pages via
    /// [`paginate`](crate::paginate).
    ///
    /// `req.first` controls the page size; a pre-set `req.after` seeds the
    /// first page's cursor.
    ///
    /// ```no_run
    /// # async fn run() -> linear_api::Result<()> {
    /// # let client = linear_api::LinearClient::from_env()?;
    /// use futures::TryStreamExt;
    /// use linear_api::IssueRef;
    /// use linear_api::comments::CommentListRequest;
    ///
    /// let comments: Vec<_> = client
    ///     .comments()
    ///     .list_for_issue_stream(
    ///         IssueRef::identifier("ENG-123"),
    ///         CommentListRequest::builder().build(),
    ///     )
    ///     .try_collect()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn list_for_issue_stream(
        &self,
        issue: impl Into<IssueRef>,
        req: CommentListRequest,
    ) -> impl Stream<Item = Result<Comment>> + 'a {
        let service = *self;
        // Resolve to an owned ref before building the closure so the stream
        // borrows nothing but the client.
        let issue = issue.into();
        crate::pagination::paginate(move |cursor| {
            let mut req = req.clone();
            if cursor.is_some() {
                req.after = cursor;
            }
            let issue = issue.clone();
            async move { service.list_for_issue(issue, req).await }
        })
    }

    /// Creates a comment (`commentCreate`). Thread replies via
    /// [`parent_id`](CommentCreateInput::parent_id).
    ///
    /// ```no_run
    /// # async fn run() -> linear_api::Result<()> {
    /// # let client = linear_api::LinearClient::from_env()?;
    /// use linear_api::comments::CommentCreateInput;
    ///
    /// let comment = client
    ///     .comments()
    ///     .create(
    ///         CommentCreateInput::builder()
    ///             .issue_id("ENG-123")
    ///             .body("Run finished: all green.".to_owned())
    ///             .build(),
    ///     )
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub async fn create(&self, input: CommentCreateInput) -> Result<Comment> {
        #[derive(Serialize)]
        struct Vars {
            input: CommentCreateInput,
        }
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Data {
            comment_create: CommentPayload,
        }

        let data: Data = self
            .client
            .mutation("CommentCreate", COMMENT_CREATE, Vars { input })
            .await?;
        data.comment_create.into_comment("CommentCreate")
    }

    /// Convenience: creates a plain markdown comment on an issue.
    ///
    /// ```no_run
    /// # async fn run() -> linear_api::Result<()> {
    /// # let client = linear_api::LinearClient::from_env()?;
    /// use linear_api::IssueRef;
    ///
    /// client
    ///     .comments()
    ///     .create_on(IssueRef::identifier("ENG-123"), "On it.")
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub async fn create_on(
        &self,
        issue: impl Into<IssueRef>,
        body: impl Into<String>,
    ) -> Result<Comment> {
        let issue = issue.into();
        self.create(
            CommentCreateInput::builder()
                .issue_id(issue.api_string())
                .body(body.into())
                .build(),
        )
        .await
    }

    /// Replaces a comment's markdown body (`commentUpdate`).
    ///
    /// ```no_run
    /// # async fn run() -> linear_api::Result<()> {
    /// # let client = linear_api::LinearClient::from_env()?;
    /// use linear_api::CommentId;
    ///
    /// let id = CommentId::new("9d2a…");
    /// client.comments().update(&id, "Edited: rollout done.").await?;
    /// # Ok(()) }
    /// ```
    pub async fn update(&self, id: &CommentId, body: impl Into<String>) -> Result<Comment> {
        #[derive(Serialize)]
        struct Vars<'v> {
            id: &'v str,
            input: CommentUpdateInput,
        }
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Data {
            comment_update: CommentPayload,
        }

        let data: Data = self
            .client
            .mutation(
                "CommentUpdate",
                COMMENT_UPDATE,
                Vars {
                    id: id.as_str(),
                    input: CommentUpdateInput { body: body.into() },
                },
            )
            .await?;
        data.comment_update.into_comment("CommentUpdate")
    }

    /// Deletes a comment (`commentDelete`).
    ///
    /// ```no_run
    /// # async fn run() -> linear_api::Result<()> {
    /// # let client = linear_api::LinearClient::from_env()?;
    /// use linear_api::CommentId;
    ///
    /// let id = CommentId::new("9d2a…");
    /// client.comments().delete(&id).await?;
    /// # Ok(()) }
    /// ```
    pub async fn delete(&self, id: &CommentId) -> Result<()> {
        #[derive(Serialize)]
        struct Vars<'v> {
            id: &'v str,
        }
        #[derive(Deserialize)]
        #[serde(rename_all = "camelCase")]
        struct Data {
            comment_delete: DeletePayload,
        }
        #[derive(Deserialize)]
        struct DeletePayload {
            success: bool,
        }

        let data: Data = self
            .client
            .mutation("CommentDelete", COMMENT_DELETE, Vars { id: id.as_str() })
            .await?;
        ensure_success("CommentDelete", data.comment_delete.success)
    }
}

/// Shared `commentCreate`/`commentUpdate` payload shape.
#[derive(Deserialize)]
struct CommentPayload {
    success: bool,
    #[serde(default)]
    comment: Option<Comment>,
}

impl CommentPayload {
    fn into_comment(self, operation: &'static str) -> Result<Comment> {
        ensure_success(operation, self.success)?;
        self.comment.ok_or(Error::MissingData { operation })
    }
}