lineark-sdk

Typed, async-first Rust SDK for the Linear GraphQL API.

Part of the lineark project — an unofficial Linear ecosystem for Rust.

Install

cargo add lineark-sdk

Quick start

use lineark_sdk::Client;
use lineark_sdk::generated::types::{User, Team};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::auto()?;

    let me = client.whoami::<User>().await?;
    println!("Logged in as: {}", me.name.as_deref().unwrap_or("?"));

    let teams = client.teams::<Team>().first(10).send().await?;
    for team in &teams.nodes {
        println!("{}: {}",
            team.key.as_deref().unwrap_or("?"),
            team.name.as_deref().unwrap_or("?"),
        );
    }

    Ok(())
}

Authentication

Create a Linear API token and provide it via any of these methods (in priority order):

Queries

Collection queries use a builder pattern with optional pagination and filtering:

// Paginate with first/last/after/before
let issues = client.issues::<Issue>().first(25).send().await?;
let page2 = client.issues::<Issue>().first(25).after(issues.page_info.end_cursor.unwrap()).send().await?;

// Search with extra filters
let results = client.search_issues::<IssueSearchResult>("bug")
    .first(10)
    .team_id("team-uuid")
    .include_comments(true)
    .send()
    .await?;

All collection queries support .first(n), .last(n), .after(cursor), .before(cursor), and .include_archived(bool).

Custom field selection

All queries are generic over T: DeserializeOwned + GraphQLFields. By default they use the generated types (which fetch all scalar fields), but you can define custom lean structs to fetch only the fields you need.

The derive macro is re-exported by lineark-sdk — you don't need to add lineark-derive to your Cargo.toml. Just import and use:

use lineark_sdk::GraphQLFields; // gives you both the trait AND #[derive(GraphQLFields)]

Custom types must include #[graphql(full_type = X)] pointing to the corresponding generated type — this is required for the type to satisfy the query's FullType constraint, and it also validates your fields at compile time (misspelled or nonexistent fields are a compile error):

use lineark_sdk::{Client, GraphQLFields};
use lineark_sdk::generated::types::Issue;
use serde::Deserialize;

#[derive(Deserialize, GraphQLFields)]
#[graphql(full_type = Issue)]
#[serde(rename_all = "camelCase")]
struct LeanIssue {
    id: Option<String>,
    title: Option<String>,
}

let client = Client::auto()?;
let issues = client.issues::<LeanIssue>().first(10).send().await?;
for issue in &issues.nodes {
    println!("{}", issue.title.as_deref().unwrap_or("?"));
}

The #[derive(GraphQLFields)] macro generates a selection() method from the struct's field names, so the query fetches exactly those fields — no overfetching. For nested objects, annotate with #[graphql(nested)] (each nested type also needs its own #[graphql(full_type = X)]):

use lineark_sdk::generated::types::Team;

#[derive(Deserialize, GraphQLFields)]
#[graphql(full_type = Issue)]
#[serde(rename_all = "camelCase")]
struct IssueWithTeam {
    id: Option<String>,
    title: Option<String>,
    #[graphql(nested)]
    team: Option<LeanTeam>,
}

#[derive(Deserialize, GraphQLFields)]
#[graphql(full_type = Team)]
#[serde(rename_all = "camelCase")]
struct LeanTeam {
    id: Option<String>,
    key: Option<String>,
}

Mutations

Mutations are also generic — use turbofish or let the type be inferred:

use lineark_sdk::generated::inputs::IssueCreateInput;
use lineark_sdk::generated::types::Issue;

let payload = client.issue_create::<Issue>(IssueCreateInput {
    title: Some("Fix the bug".to_string()),
    team_id: Some("team-uuid".to_string()),
    priority: Some(2),
    ..Default::default()
}).await?;

File upload and download

The SDK provides high-level helpers for Linear's file operations:

// Upload a file (two-step: get signed URL from Linear, then PUT to GCS)
let bytes = std::fs::read("screenshot.png")?;
let result = client.upload_file("screenshot.png", "image/png", bytes, false).await?;
println!("Asset URL: {}", result.asset_url);

// Download a file from Linear's CDN
let result = client.download_url("https://uploads.linear.app/...").await?;
std::fs::write("output.png", &result.bytes)?;

Blocking (synchronous) API

For non-async contexts, enable the blocking feature:

[dependencies]
lineark-sdk = { version = "...", features = ["blocking"] }

The blocking client mirrors the async API exactly:

use lineark_sdk::blocking_client::Client;
use lineark_sdk::generated::types::Document;

let client = Client::auto()?;

let me = client.whoami()?;
println!("Logged in as: {:?}", me.name);

let teams = client.teams().first(10).send()?;
for team in &teams.nodes {
    println!("{}: {}",
        team.key.as_deref().unwrap_or("?"),
        team.name.as_deref().unwrap_or("?"),
    );
}

// Mutations are generic — use turbofish or type inference
let payload = client.document_create::<Document>(input)?;

// File operations too
let result = client.upload_file("file.txt", "text/plain", bytes, false)?;
let downloaded = client.download_url(&result.asset_url)?;

Error handling

All methods return Result<T, LinearError>. Error variants:

• Authentication — invalid or expired token
• Forbidden — insufficient permissions
• RateLimited — API rate limit hit (includes retry_after)
• InvalidInput — bad request parameters
• GraphQL — errors returned in the GraphQL response (includes query name for diagnostics)
• Network — connection/transport failures
• HttpError — non-200 responses not covered above
• MissingData — expected data path not found in response
• AuthConfig — auth configuration error (no token found)
• Internal — internal error (e.g. runtime creation failure)

Codegen

All types, enums, inputs, and query functions are generated from Linear's official GraphQL schema. The generated code lives in src/generated/ and is checked in for reproducible builds.

License

MIT