linear_api/

workspace.rs

//! Teams, users, and workflow states — the workspace lookup surface every
//! board and plan operation needs (resolving team keys, assignees, and state
//! names to the IDs that issue and project mutations require).

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

use crate::client::LinearClient;
use crate::error::Result;
use crate::filter::{IdComparator, TeamFilter, UserFilter, WorkflowStateFilter};
use crate::ids::{TeamId, UserId, WorkflowStateId};
use crate::pagination::{Page, PageInfo};
use crate::types::{TeamRef, WorkflowStateType};

// ---------------------------------------------------------------------------
// GraphQL documents
// ---------------------------------------------------------------------------

/// Canonical `TeamFields` fragment — field set MUST match [`Team`].
macro_rules! team_fields_fragment {
    () => {
        "fragment TeamFields on Team { id key name description color icon private timezone \
         cyclesEnabled issueEstimationType defaultIssueEstimate }"
    };
}

/// Canonical `UserFields` fragment — field set MUST match [`User`].
macro_rules! user_fields_fragment {
    () => {
        "fragment UserFields on User { id name displayName email active admin guest avatarUrl \
         timezone }"
    };
}

/// Canonical `WorkflowStateFields` fragment — field set MUST match
/// [`WorkflowState`]. Embeds the crate-wide `TeamRefFields` fragment
/// (see [`TeamRef`]).
macro_rules! workflow_state_fields_fragment {
    () => {
        "fragment WorkflowStateFields on WorkflowState { id name type position color \
         description team { ...TeamRefFields } } \
         fragment TeamRefFields on Team { id key name }"
    };
}

const TEAM_LIST: &str = concat!(
    "query TeamList($filter: TeamFilter, $first: Int, $after: String, \
     $includeArchived: Boolean) { \
     teams(filter: $filter, first: $first, after: $after, includeArchived: $includeArchived) { \
     nodes { ...TeamFields } \
     pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } } ",
    team_fields_fragment!()
);

const TEAM_GET: &str = concat!(
    "query TeamGet($id: String!) { team(id: $id) { ...TeamFields } } ",
    team_fields_fragment!()
);

const WORKFLOW_STATE_LIST: &str = concat!(
    "query WorkflowStateList($filter: WorkflowStateFilter, $first: Int, $after: String) { \
     workflowStates(filter: $filter, first: $first, after: $after) { \
     nodes { ...WorkflowStateFields } \
     pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } } ",
    workflow_state_fields_fragment!()
);

const USER_LIST: &str = concat!(
    "query UserList($filter: UserFilter, $first: Int, $after: String, \
     $includeDisabled: Boolean) { \
     users(filter: $filter, first: $first, after: $after, includeDisabled: $includeDisabled) { \
     nodes { ...UserFields } \
     pageInfo { hasNextPage hasPreviousPage startCursor endCursor } } } ",
    user_fields_fragment!()
);

const USER_GET: &str = concat!(
    "query UserGet($id: String!) { user(id: $id) { ...UserFields } } ",
    user_fields_fragment!()
);

pub(crate) const DOCUMENTS: &[(&str, &str)] = &[
    ("TeamList", TEAM_LIST),
    ("TeamGet", TEAM_GET),
    ("WorkflowStateList", WORKFLOW_STATE_LIST),
    ("UserList", USER_LIST),
    ("UserGet", USER_GET),
];

// ---------------------------------------------------------------------------
// Models
// ---------------------------------------------------------------------------

/// A Linear team.
///
/// # Example
///
/// ```no_run
/// # async fn example() -> linear_api::Result<()> {
/// let client = linear_api::LinearClient::from_env()?;
/// let team: linear_api::workspace::Team = client.teams().get(&"ENG".into()).await?;
/// println!("{} ({}) cycles={}", team.name, team.key, team.cycles_enabled);
/// # Ok(()) }
/// ```
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct Team {
    /// Team ID.
    pub id: TeamId,
    /// Team key used in issue identifiers, e.g. `"ENG"` in `ENG-123`.
    pub key: String,
    /// Team name.
    pub name: String,
    /// Team description.
    pub description: Option<String>,
    /// Team color as a hex string.
    pub color: Option<String>,
    /// Team icon name.
    pub icon: Option<String>,
    /// Whether the team is private.
    pub private: bool,
    /// The team's timezone, e.g. `"America/Sao_Paulo"`.
    pub timezone: String,
    /// Whether cycles are enabled for the team.
    pub cycles_enabled: bool,
    /// The estimation scale in use, e.g. `"exponential"` or `"notUsed"`.
    pub issue_estimation_type: String,
    /// Default estimate applied to unestimated issues.
    pub default_issue_estimate: f64,
}

/// One issue status of a team's board (a board column).
///
/// # Example
///
/// ```no_run
/// # async fn example() -> linear_api::Result<()> {
/// use linear_api::WorkflowStateType;
///
/// let client = linear_api::LinearClient::from_env()?;
/// let team_id = linear_api::TeamId::new("88888888-8888-4888-8888-888888888888");
/// let states = client.teams().states(&team_id).await?;
/// let started = states
///     .iter()
///     .find(|s| s.state_type == WorkflowStateType::Started);
/// println!("{:?}", started.map(|s| &s.id));
/// # Ok(()) }
/// ```
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct WorkflowState {
    /// Workflow state ID.
    pub id: WorkflowStateId,
    /// Display name, e.g. `"In Progress"`.
    pub name: String,
    /// The semantic category of the state
    /// (`triage` | `backlog` | `unstarted` | `started` | `completed` |
    /// `canceled`). Unknown future categories deserialize as
    /// [`WorkflowStateType::Unrecognized`].
    #[serde(rename = "type")]
    pub state_type: WorkflowStateType,
    /// Board position; lower comes first (leftmost column).
    pub position: f64,
    /// State color as a hex string.
    pub color: String,
    /// State description.
    pub description: Option<String>,
    /// The team this state belongs to.
    pub team: TeamRef,
}

/// A Linear user (workspace member).
///
/// # Example
///
/// ```no_run
/// # async fn example() -> linear_api::Result<()> {
/// let client = linear_api::LinearClient::from_env()?;
/// let user_id = linear_api::UserId::new("9c2c88a6-99d3-4a63-a201-8ee5c7dcc374");
/// let user: linear_api::workspace::User = client.users().get(&user_id).await?;
/// println!("{} <{}>", user.display_name, user.email);
/// # Ok(()) }
/// ```
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct User {
    /// User ID.
    pub id: UserId,
    /// Full name.
    pub name: String,
    /// Display (handle) name.
    pub display_name: String,
    /// Email address.
    pub email: String,
    /// Whether the account is active.
    pub active: bool,
    /// Whether the user is a workspace admin.
    pub admin: bool,
    /// Whether the user is a guest with restricted team access.
    pub guest: bool,
    /// Avatar image URL.
    pub avatar_url: Option<String>,
    /// The user's timezone, when set.
    pub timezone: Option<String>,
}

// ---------------------------------------------------------------------------
// Requests
// ---------------------------------------------------------------------------

/// Parameters for [`TeamsService::list`]. Serialized directly as the
/// `TeamList` query variables.
///
/// # Example
///
/// ```
/// use linear_api::{StringComparator, TeamFilter};
/// use linear_api::workspace::ListTeamsRequest;
///
/// let req = ListTeamsRequest::builder()
///     .filter(
///         TeamFilter::builder()
///             .key(StringComparator::builder().eq("ENG".to_string()).build())
///             .build(),
///     )
///     .first(10)
///     .build();
/// ```
#[derive(Debug, Clone, Default, Serialize, Builder)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct ListTeamsRequest {
    /// Filter the returned teams.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filter: Option<TeamFilter>,
    /// Page size (server default 50).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub first: Option<i32>,
    /// Cursor to paginate after (a previous page's `end_cursor`).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[builder(into)]
    pub after: Option<String>,
    /// Include archived teams (server default `false`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub include_archived: Option<bool>,
}

/// Parameters for [`WorkflowStatesService::list`]. Serialized directly as
/// the `WorkflowStateList` query variables.
///
/// # Example
///
/// ```
/// use linear_api::{StringComparator, WorkflowStateFilter};
/// use linear_api::workspace::ListWorkflowStatesRequest;
///
/// let req = ListWorkflowStatesRequest::builder()
///     .filter(
///         WorkflowStateFilter::builder()
///             .r#type(StringComparator::builder().eq("started".to_string()).build())
///             .build(),
///     )
///     .build();
/// ```
#[derive(Debug, Clone, Default, Serialize, Builder)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct ListWorkflowStatesRequest {
    /// Filter the returned workflow states.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filter: Option<WorkflowStateFilter>,
    /// Page size (server default 50).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub first: Option<i32>,
    /// Cursor to paginate after (a previous page's `end_cursor`).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[builder(into)]
    pub after: Option<String>,
}

/// Parameters for [`UsersService::list`]. Serialized directly as the
/// `UserList` query variables.
///
/// # Example
///
/// ```
/// use linear_api::{StringComparator, UserFilter};
/// use linear_api::workspace::ListUsersRequest;
///
/// let req = ListUsersRequest::builder()
///     .filter(
///         UserFilter::builder()
///             .email(StringComparator::builder().eq("ada@example.com".to_string()).build())
///             .build(),
///     )
///     .build();
/// ```
#[derive(Debug, Clone, Default, Serialize, Builder)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct ListUsersRequest {
    /// Filter the returned users.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub filter: Option<UserFilter>,
    /// Page size (server default 50).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub first: Option<i32>,
    /// Cursor to paginate after (a previous page's `end_cursor`).
    #[serde(skip_serializing_if = "Option::is_none")]
    #[builder(into)]
    pub after: Option<String>,
    /// Include disabled/suspended users (server default `false`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub include_disabled: Option<bool>,
}

// ---------------------------------------------------------------------------
// Services
// ---------------------------------------------------------------------------

/// GraphQL connection shape shared by this module's list queries.
#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct Connection<T> {
    nodes: Vec<T>,
    page_info: PageInfo,
}

impl<T> From<Connection<T>> for Page<T> {
    fn from(connection: Connection<T>) -> Self {
        Page {
            nodes: connection.nodes,
            page_info: connection.page_info,
        }
    }
}

/// Operations on teams. Obtain via [`LinearClient::teams`].
#[derive(Debug, Clone, Copy)]
pub struct TeamsService<'a> {
    client: &'a LinearClient,
}

/// Operations on users. Obtain via [`LinearClient::users`].
#[derive(Debug, Clone, Copy)]
pub struct UsersService<'a> {
    client: &'a LinearClient,
}

/// Operations on workflow states. Obtain via
/// [`LinearClient::workflow_states`].
#[derive(Debug, Clone, Copy)]
pub struct WorkflowStatesService<'a> {
    client: &'a LinearClient,
}

impl LinearClient {
    /// Teams: list, get, and per-team workflow states.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// let client = linear_api::LinearClient::from_env()?;
    /// let page = client.teams().list(Default::default()).await?;
    /// for team in &page.nodes {
    ///     println!("{}: {}", team.key, team.name);
    /// }
    /// # Ok(()) }
    /// ```
    pub fn teams(&self) -> TeamsService<'_> {
        TeamsService { client: self }
    }

    /// Users: list and get workspace members.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// let client = linear_api::LinearClient::from_env()?;
    /// let page = client.users().list(Default::default()).await?;
    /// println!("{} users on the first page", page.nodes.len());
    /// # Ok(()) }
    /// ```
    pub fn users(&self) -> UsersService<'_> {
        UsersService { client: self }
    }

    /// Workflow states (issue statuses) across the workspace.
    ///
    /// For the states of one team, prefer [`TeamsService::states`].
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// let client = linear_api::LinearClient::from_env()?;
    /// let page = client.workflow_states().list(Default::default()).await?;
    /// println!("{} states on the first page", page.nodes.len());
    /// # Ok(()) }
    /// ```
    pub fn workflow_states(&self) -> WorkflowStatesService<'_> {
        WorkflowStatesService { client: self }
    }
}

impl<'a> TeamsService<'a> {
    /// Fetches one page of teams.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// use linear_api::workspace::ListTeamsRequest;
    ///
    /// let client = linear_api::LinearClient::from_env()?;
    /// let page = client
    ///     .teams()
    ///     .list(ListTeamsRequest::builder().first(50).build())
    ///     .await?;
    /// println!("has more: {}", page.page_info.has_next_page);
    /// # Ok(()) }
    /// ```
    pub async fn list(&self, req: ListTeamsRequest) -> Result<Page<Team>> {
        #[derive(Deserialize)]
        struct Data {
            teams: Connection<Team>,
        }
        let data: Data = self.client.query("TeamList", TEAM_LIST, req).await?;
        Ok(data.teams.into())
    }

    /// Lazily streams every team matching the request across pages, starting
    /// from `req.after` when set (the cursor then advances page by page).
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// use futures::TryStreamExt;
    ///
    /// let client = linear_api::LinearClient::from_env()?;
    /// let teams: Vec<_> = client
    ///     .teams()
    ///     .list_stream(Default::default())
    ///     .try_collect()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn list_stream(self, req: ListTeamsRequest) -> impl Stream<Item = Result<Team>> + 'a {
        crate::pagination::paginate(move |after| {
            let mut req = req.clone();
            // The first call keeps a caller-seeded `req.after`; later calls
            // advance to each page's end cursor.
            if after.is_some() {
                req.after = after;
            }
            async move { self.list(req).await }
        })
    }

    /// Fetches a single team by ID.
    ///
    /// Linear also resolves a team **key** (e.g. `"ENG"`) passed as the ID
    /// string.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// let client = linear_api::LinearClient::from_env()?;
    /// let team = client.teams().get(&linear_api::TeamId::new("ENG")).await?;
    /// println!("{}", team.name);
    /// # Ok(()) }
    /// ```
    pub async fn get(&self, id: &TeamId) -> Result<Team> {
        #[derive(Deserialize)]
        struct Data {
            team: Team,
        }
        let data: Data = self
            .client
            .query(
                "TeamGet",
                TEAM_GET,
                serde_json::json!({ "id": id.as_str() }),
            )
            .await?;
        Ok(data.team)
    }

    /// Fetches **all** workflow states of one team, sorted by board
    /// `position` ascending (leftmost column first).
    ///
    /// This is how you resolve state **names** to `stateId`s before issue
    /// updates. The semantic key is [`WorkflowState::state_type`]
    /// (`triage` | `backlog` | `unstarted` | `started` | `completed` |
    /// `canceled`) rather than the display name — for example, an automation might refuse
    /// writes that would move issues into `completed`/`canceled` states.
    ///
    /// Drains the `WorkflowStateList` query (capped at 100 states; teams
    /// have far fewer in practice).
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// let client = linear_api::LinearClient::from_env()?;
    /// let team_id = linear_api::TeamId::new("88888888-8888-4888-8888-888888888888");
    /// for state in client.teams().states(&team_id).await? {
    ///     println!("{:>12} {:?}", state.name, state.state_type);
    /// }
    /// # Ok(()) }
    /// ```
    pub async fn states(&self, team: &TeamId) -> Result<Vec<WorkflowState>> {
        let filter = WorkflowStateFilter {
            team: Some(TeamFilter {
                id: Some(IdComparator {
                    eq: Some(team.to_string()),
                    ..Default::default()
                }),
                ..Default::default()
            }),
            ..Default::default()
        };
        let service = self.client.workflow_states();
        let mut states = crate::pagination::collect_all(
            move |after| {
                let req = ListWorkflowStatesRequest {
                    filter: Some(filter.clone()),
                    first: Some(100),
                    after,
                };
                async move { service.list(req).await }
            },
            Some(100),
        )
        .await?;
        states.sort_by(|a, b| a.position.total_cmp(&b.position));
        Ok(states)
    }
}

impl WorkflowStatesService<'_> {
    /// Fetches one page of workflow states across the workspace.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// use linear_api::workspace::ListWorkflowStatesRequest;
    ///
    /// let client = linear_api::LinearClient::from_env()?;
    /// let page = client
    ///     .workflow_states()
    ///     .list(ListWorkflowStatesRequest::builder().first(50).build())
    ///     .await?;
    /// println!("{} states", page.nodes.len());
    /// # Ok(()) }
    /// ```
    pub async fn list(&self, req: ListWorkflowStatesRequest) -> Result<Page<WorkflowState>> {
        #[derive(Deserialize)]
        struct Data {
            #[serde(rename = "workflowStates")]
            workflow_states: Connection<WorkflowState>,
        }
        let data: Data = self
            .client
            .query("WorkflowStateList", WORKFLOW_STATE_LIST, req)
            .await?;
        Ok(data.workflow_states.into())
    }
}

impl<'a> UsersService<'a> {
    /// Fetches one page of users.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// use linear_api::workspace::ListUsersRequest;
    ///
    /// let client = linear_api::LinearClient::from_env()?;
    /// let page = client
    ///     .users()
    ///     .list(ListUsersRequest::builder().first(50).build())
    ///     .await?;
    /// println!("has more: {}", page.page_info.has_next_page);
    /// # Ok(()) }
    /// ```
    pub async fn list(&self, req: ListUsersRequest) -> Result<Page<User>> {
        #[derive(Deserialize)]
        struct Data {
            users: Connection<User>,
        }
        let data: Data = self.client.query("UserList", USER_LIST, req).await?;
        Ok(data.users.into())
    }

    /// Lazily streams every user matching the request across pages, starting
    /// from `req.after` when set (the cursor then advances page by page).
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// use futures::TryStreamExt;
    ///
    /// let client = linear_api::LinearClient::from_env()?;
    /// let users: Vec<_> = client
    ///     .users()
    ///     .list_stream(Default::default())
    ///     .try_collect()
    ///     .await?;
    /// # Ok(()) }
    /// ```
    pub fn list_stream(self, req: ListUsersRequest) -> impl Stream<Item = Result<User>> + 'a {
        crate::pagination::paginate(move |after| {
            let mut req = req.clone();
            // The first call keeps a caller-seeded `req.after`; later calls
            // advance to each page's end cursor.
            if after.is_some() {
                req.after = after;
            }
            async move { self.list(req).await }
        })
    }

    /// Fetches a single user by ID. For the authenticated user, use
    /// [`LinearClient::viewer`] instead.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example() -> linear_api::Result<()> {
    /// let client = linear_api::LinearClient::from_env()?;
    /// let user_id = linear_api::UserId::new("9c2c88a6-99d3-4a63-a201-8ee5c7dcc374");
    /// let user = client.users().get(&user_id).await?;
    /// println!("{}", user.display_name);
    /// # Ok(()) }
    /// ```
    pub async fn get(&self, id: &UserId) -> Result<User> {
        #[derive(Deserialize)]
        struct Data {
            user: User,
        }
        let data: Data = self
            .client
            .query(
                "UserGet",
                USER_GET,
                serde_json::json!({ "id": id.as_str() }),
            )
            .await?;
        Ok(data.user)
    }
}