crates/hub-api/src/lib.rs at f3e5e2bc78e9 · andymccall/oxygenhub

# f3e5e2bc78e9 oxygenhub / crates / hub-api / src / lib.rs
38.5 KiB · Rust · last changed Transfer a project to another owner 25 days ago source blame history raw
//! Types of the OxygenHub JSON API (hub spec §12.1). Everything here is
//! `serde` data with no behaviour, so clients in other languages can be
//! generated from it and the server can never drift from them.
//!
//! Shapes reuse `oxy --json`'s where one exists (hashes as lowercase hex,
//! times as milliseconds since the epoch), so tools written against the
//! command line work against the hub.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

/// A repository as the API lists it.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Repository {
    pub owner: String,
    pub name: String,
    pub description: String,
    pub default_bookmark: String,
    pub visibility: Visibility,
    /// Milliseconds since the epoch.
    pub created_ms: i64,
    pub updated_ms: i64,
    /// `https://…/{owner}/{name}`, what `oxy clone` takes.
    pub clone_url: String,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum Visibility {
    Public,
    Internal,
    Private,
}

impl Visibility {
    pub fn as_str(self) -> &'static str {
        match self {
            Visibility::Public => "public",
            Visibility::Internal => "internal",
            Visibility::Private => "private",
        }
    }

    pub fn parse(s: &str) -> Option<Visibility> {
        Some(match s {
            "public" => Visibility::Public,
            "internal" => Visibility::Internal,
            "private" => Visibility::Private,
            _ => return None,
        })
    }
}

/// A bookmark: a name for a set of heads (spec §10.1).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Bookmark {
    pub name: String,
    pub heads: Vec<String>,
    /// Number of changes in the bookmark's state.
    pub changes: usize,
    pub default: bool,
}

/// A tag: a name for one state, with its attestation when signed.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Tag {
    pub name: String,
    pub heads: Vec<String>,
    pub message: String,
    pub signer: Option<String>,
}

/// One change in a history listing.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ChangeSummary {
    pub hash: String,
    pub message: String,
    pub author: Author,
    pub when_ms: u64,
    pub deps: Vec<String>,
    pub head: bool,
    pub signature: Signature,
    /// Signed for the author by a delegate (an agent), when it was.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub via: Option<Via>,
}

/// A delegate that signed a change for its author (Oxygen spec §14.2).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Via {
    pub name: String,
    pub key: String,
    /// The delegation's scope, `changes` for an agent.
    pub scope: String,
    pub expires_ms: Option<u64>,
    /// The delegation has since been revoked or withdrawn.
    pub revoked: bool,
}

/// Who wrote a change: the linked account when the signing key is linked,
/// else the key alone.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Author {
    pub name: String,
    pub email: String,
    pub key: String,
    /// The hub account this key is linked to, when any.
    pub account: Option<String>,
    /// Set when the change is signed by a key no account has linked, and
    /// says how its owner links it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
}

impl Author {
    /// What `note` says for a key that no account has linked.
    pub const UNLINKED: &'static str =
        "signed by a key not linked to any account; its owner links it under Settings → Keys (/settings/keys)";

    /// The note for an author with this key and account.
    pub fn note_for(key: &str, account: &Option<String>) -> Option<String> {
        (!key.is_empty() && account.is_none()).then(|| Self::UNLINKED.to_string())
    }
}

/// Signature status of a change as `oxy verify` reports it.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "status", rename_all = "lowercase")]
pub enum Signature {
    Unsigned,
    Valid { key: String, sealed: bool, revoked: bool },
    Invalid { reason: String },
}

/// An RFC 7807 problem response.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Problem {
    pub status: u16,
    pub title: String,
    pub detail: String,
}

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

    #[test]
    fn visibility_round_trips() {
        for v in [Visibility::Public, Visibility::Internal, Visibility::Private] {
            assert_eq!(Visibility::parse(v.as_str()), Some(v));
        }
        assert_eq!(Visibility::parse("secret"), None);
    }
}

// ---------------------------------------------------------------- proposals

/// A proposal: a request to add changes to a target bookmark (hub spec §7).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Proposal {
    pub number: i64,
    pub title: String,
    pub body: String,
    pub author: String,
    pub state: ProposalState,
    pub target: String,
    pub source: ProposalSource,
    /// The changes the proposal adds, dependency order, newest last.
    pub changes: Vec<ChangeSummary>,
    /// Heads of the projected state (target plus the changes), when computed.
    pub projected_heads: Vec<String>,
    pub projected_state: Option<String>,
    pub conflicted: bool,
    pub approvals: Vec<Approval>,
    pub landable: bool,
    pub blockers: Vec<String>,
    pub created_ms: i64,
    pub updated_ms: i64,
    /// `https://hub/{owner}/{name}/proposal/{number}`.
    pub url: String,
    /// Where `oxy` fetches the changes from.
    pub repository_url: String,
    /// The fork's clone URL when the source is a fork.
    pub source_url: Option<String>,
    /// Who landed it, how and when, once landed.
    #[serde(default)]
    pub landed: Option<Landed>,
    /// Asked to review and not yet reviewing, in the order asked.
    #[serde(default)]
    pub requested_reviewers: Vec<String>,
    #[serde(default)]
    pub labels: Vec<Label>,
}

/// How a proposal was landed.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Landed {
    pub by: String,
    /// `web`, or `api (token NAME)`.
    pub via: String,
    pub when_ms: i64,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum ProposalState {
    Draft,
    Open,
    Landed,
    Closed,
}

impl ProposalState {
    pub fn as_str(self) -> &'static str {
        match self {
            ProposalState::Draft => "draft",
            ProposalState::Open => "open",
            ProposalState::Landed => "landed",
            ProposalState::Closed => "closed",
        }
    }

    pub fn parse(s: &str) -> Option<ProposalState> {
        Some(match s {
            "draft" => ProposalState::Draft,
            "open" => ProposalState::Open,
            "landed" => ProposalState::Landed,
            "closed" => ProposalState::Closed,
            _ => return None,
        })
    }
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "kind", rename_all = "lowercase")]
pub enum ProposalSource {
    /// A bookmark of the same repository.
    Bookmark { bookmark: String },
    /// A bookmark of a fork.
    Fork { owner: String, name: String, bookmark: String },
    /// An explicit list of change hashes.
    Changes { hashes: Vec<String> },
}

/// A reviewer's approval, counted only when backed by a seal over every
/// change of the proposal signed with a key linked to the reviewer.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Approval {
    pub account: String,
    pub sealed: bool,
    pub key: Option<String>,
}

// ------------------------------------------------------------------ issues

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Issue {
    pub number: i64,
    pub title: String,
    pub body: String,
    pub author: String,
    pub state: String,
    pub reason: String,
    pub labels: Vec<Label>,
    pub assignees: Vec<String>,
    pub milestone: Option<String>,
    pub comments: i64,
    pub locked: bool,
    pub pinned: bool,
    pub created_ms: i64,
    pub updated_ms: i64,
    pub closed_ms: Option<i64>,
    pub url: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Label {
    pub name: String,
    pub colour: String,
    pub description: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Milestone {
    pub title: String,
    pub description: String,
    pub due_ms: Option<i64>,
    pub state: String,
    pub open: i64,
    pub closed: i64,
}

/// `POST /repos/{o}/{n}/milestones`: create a milestone, or change the
/// description and due date of the one with that title (triage).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewMilestone {
    pub title: String,
    #[serde(default)]
    pub description: String,
    /// `YYYY-MM-DD`, UTC; absent for no due date.
    #[serde(default)]
    pub due: Option<String>,
}

/// `PATCH /repos/{o}/{n}/milestones/{title}`: only the fields given change
/// (triage).
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct MilestoneEdit {
    #[serde(default)]
    pub title: Option<String>,
    #[serde(default)]
    pub description: Option<String>,
    /// `YYYY-MM-DD`; the empty string clears the due date.
    #[serde(default)]
    pub due: Option<String>,
    /// `open` or `closed`.
    #[serde(default)]
    pub state: Option<String>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Comment {
    pub id: i64,
    pub author: String,
    pub body: String,
    pub created_ms: i64,
    /// For proposal comments: the file and the atom the comment anchors to.
    pub path: Option<String>,
    pub anchor: Option<Atom>,
    pub resolved: bool,
}

/// One entry in the caller's inbox (hub spec §10).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Notification {
    pub id: i64,
    pub at_ms: i64,
    /// `issue.opened`, `proposal.comment`, `mention`, `review`, …
    pub kind: String,
    pub title: String,
    /// The page on the hub, absolute.
    pub url: String,
    pub actor: String,
    pub read: bool,
}

/// `GET /notifications`: the unread count and the newest entries, unread first.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Inbox {
    pub unread: i64,
    pub items: Vec<Notification>,
}

/// A file a proposal changes, between the target's state and the
/// projected state (hub spec §7.2). Fetch either side's bytes from
/// `/proposals/{number}/content/{base|head}/{path}`.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProposalFile {
    pub path: String,
    /// For a rename, the path in the target's state.
    pub from: Option<String>,
    /// `added`, `removed`, `modified`, `renamed`, `mode` or `replaced`.
    pub kind: String,
    pub added: usize,
    pub removed: usize,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Atom {
    pub change: String,
    pub index: u32,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Review {
    pub id: i64,
    pub author: String,
    pub verdict: String,
    pub body: String,
    pub sealed: bool,
    pub created_ms: i64,
    /// The AI assistant that answered for `author`, empty for a person's
    /// own review (hub spec §13.4).
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub via: String,
}

// ------------------------------------------------------------- repository

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct TreeEntry {
    pub name: String,
    pub path: String,
    pub kind: String,
    pub exec: bool,
    pub size: Option<u64>,
    pub conflicted: bool,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct BlameLine {
    pub line: usize,
    pub change: String,
    pub index: u32,
    pub author: String,
    pub when_ms: u64,
    pub text: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct FileChange {
    pub path: String,
    pub kind: String,
    pub from: Option<String>,
    pub added: usize,
    pub removed: usize,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ChangeDetail {
    pub change: ChangeSummary,
    pub body: String,
    pub dependents: Vec<String>,
    pub in_bookmarks: Vec<String>,
    pub in_tags: Vec<String>,
    pub files: Vec<FileChange>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct History {
    pub reference: String,
    pub heads: Vec<String>,
    pub total: usize,
    pub offset: usize,
    pub changes: Vec<ChangeSummary>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Conflict {
    pub bookmark: String,
    pub path: String,
    pub kind: String,
    pub contributors: Vec<String>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Push {
    pub at_ms: i64,
    pub pusher: String,
    pub reference: String,
    pub ok: bool,
    pub reason: String,
    pub old_state: String,
    pub new_state: String,
    pub heads: i64,
    pub changes: i64,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Trust {
    pub policy: Option<Policy>,
    pub signed: usize,
    pub sealed: usize,
    pub unsigned: usize,
    pub invalid: Vec<String>,
    pub hub_key: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Policy {
    pub serial: u64,
    pub expires_ms: u64,
    pub roots: Vec<String>,
    pub root_threshold: u32,
    pub rules: Vec<Rule>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Rule {
    pub pattern: String,
    pub keys: Vec<String>,
    pub threshold: u32,
    pub require: String,
    pub allow_conflicts: bool,
}

// ---------------------------------------------------------- hooks, checks

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Hook {
    pub id: i64,
    pub url: String,
    pub events: String,
    pub active: bool,
    pub created_ms: i64,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewHook {
    pub url: String,
    pub secret: String,
    #[serde(default = "star")]
    pub events: String,
}

fn star() -> String {
    "*".into()
}

/// An OxygenFlow run (hub spec §13.2).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct FlowRun {
    /// The run's number within its repository.
    pub number: i64,
    pub bookmark: String,
    /// The state's hash, as checks are keyed.
    pub state: String,
    /// Its heads, full change hashes.
    pub heads: Vec<String>,
    /// `queued`, `running`, `passed`, `failed` or `error` (an invalid pipeline).
    pub status: String,
    /// `push`, `manual` or `rerun:N`.
    pub trigger: String,
    pub actor: String,
    pub pipeline_hash: String,
    /// An invalid pipeline's problems.
    pub error: String,
    pub created_ms: i64,
    pub finished_ms: Option<i64>,
    pub url: String,
    /// For a run waiting for a runner, its first queued job's 1-based
    /// place among all queued jobs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub queue_position: Option<i64>,
    /// Filled by the single-run endpoint.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub jobs: Vec<FlowJob>,
}

/// A job of a run.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct FlowJob {
    pub name: String,
    /// `queued`, `running`, `passed`, `failed`, `skipped` or `error`.
    pub status: String,
    pub depends_on: Vec<String>,
    pub runner: String,
    pub exit_code: Option<i64>,
    pub error: String,
    pub started_ms: Option<i64>,
    pub finished_ms: Option<i64>,
    /// Log lines stored so far.
    pub log_lines: i64,
    /// Why a queued job no runner can take waits (OxygenFlow spec §11.4);
    /// empty when it only waits its turn.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub waiting: String,
}

/// A line of a job's log.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct FlowLogLine {
    /// Increasing within the job; pass the last one as `after` for more.
    pub seq: i64,
    /// Milliseconds since the job started.
    pub t: i64,
    /// `stdout`, `stderr` or `flow` (the runner's own notes).
    pub stream: String,
    pub text: String,
}

/// A check on a state hash (hub spec §13.1).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Check {
    pub state: String,
    pub name: String,
    pub status: CheckStatus,
    pub summary: String,
    pub url: String,
    pub reporter: String,
    /// The seal attestation's reference when the checker sealed the changes.
    pub seal: Option<String>,
    pub started_ms: i64,
    pub finished_ms: Option<i64>,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum CheckStatus {
    Queued,
    Running,
    Passed,
    Failed,
    Cancelled,
    Skipped,
}

impl CheckStatus {
    pub fn as_str(self) -> &'static str {
        match self {
            CheckStatus::Queued => "queued",
            CheckStatus::Running => "running",
            CheckStatus::Passed => "passed",
            CheckStatus::Failed => "failed",
            CheckStatus::Cancelled => "cancelled",
            CheckStatus::Skipped => "skipped",
        }
    }

    pub fn parse(s: &str) -> Option<CheckStatus> {
        Some(match s {
            "queued" => CheckStatus::Queued,
            "running" => CheckStatus::Running,
            "passed" => CheckStatus::Passed,
            "failed" => CheckStatus::Failed,
            "cancelled" => CheckStatus::Cancelled,
            "skipped" => CheckStatus::Skipped,
            _ => return None,
        })
    }
}

/// What a checker posts.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewCheck {
    pub state: String,
    pub name: String,
    pub status: CheckStatus,
    #[serde(default)]
    pub summary: String,
    #[serde(default)]
    pub url: String,
    /// Hex of a seal attestation reference the checker pushed, if any.
    #[serde(default)]
    pub seal: Option<String>,
}

// ------------------------------------------------------------- accounts

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct User {
    pub username: String,
    pub display_name: String,
    pub is_admin: bool,
    pub keys: Vec<String>,
    pub created_ms: i64,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Organisation {
    pub name: String,
    pub display_name: String,
    pub description: String,
    pub members: Vec<String>,
}

/// Forms accepted by the write endpoints.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewRepository {
    pub owner: String,
    pub name: String,
    #[serde(default)]
    pub description: String,
    #[serde(default = "public")]
    pub visibility: Visibility,
}

fn public() -> Visibility {
    Visibility::Public
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewIssue {
    pub title: String,
    #[serde(default)]
    pub body: String,
    /// Label names; each must exist. Needs triage.
    #[serde(default)]
    pub labels: Vec<String>,
    /// Usernames. Needs triage.
    #[serde(default)]
    pub assignees: Vec<String>,
    /// A milestone's title. Needs triage.
    #[serde(default)]
    pub milestone: Option<String>,
}

/// `PATCH /repos/{o}/{n}/issues/{number}`: only the fields given change.
/// Title and body: the author or triage. The rest: triage.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct IssueEdit {
    #[serde(default)]
    pub title: Option<String>,
    #[serde(default)]
    pub body: Option<String>,
    /// The whole set of labels.
    #[serde(default)]
    pub labels: Option<Vec<String>>,
    /// The whole set of assignees.
    #[serde(default)]
    pub assignees: Option<Vec<String>>,
    /// A milestone's title; the empty string clears it.
    #[serde(default)]
    pub milestone: Option<String>,
}

/// The checks a proposal needs, passed, to land on the repository's
/// default bookmark (hub spec §13.1). `GET` and `PUT
/// /repos/{o}/{n}/checks/required`.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct RequiredChecks {
    pub names: Vec<String>,
}

/// A project (hub spec §8.2).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Project {
    pub owner: String,
    pub number: i64,
    pub title: String,
    pub description: String,
    pub public: bool,
    pub closed: bool,
    pub updated_ms: i64,
    /// The board on the hub, absolute.
    pub url: String,
}

/// A card as the caller may see it.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProjectCard {
    pub id: i64,
    /// `issue`, `proposal` or `note`.
    pub kind: String,
    /// `owner/name#N`; empty for a note.
    pub reference: String,
    /// The issue's or proposal's title, or the note.
    pub title: String,
    /// The issue's or proposal's state; empty for a note.
    pub state: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProjectColumn {
    pub id: i64,
    pub name: String,
    pub cards: Vec<ProjectCard>,
}

/// `GET /projects/{owner}/{n}`.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Board {
    pub project: Project,
    pub columns: Vec<ProjectColumn>,
}

/// `POST /projects/{owner}`.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewProject {
    pub title: String,
    #[serde(default)]
    pub description: String,
    #[serde(default)]
    pub private: bool,
}

/// `PATCH /projects/{owner}/{n}`: only the fields given change.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProjectEdit {
    /// Transfer the board to this owner (#125): one the caller may make
    /// boards under. It takes the next number there.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub owner: Option<String>,
    #[serde(default)]
    pub title: Option<String>,
    #[serde(default)]
    pub description: Option<String>,
    #[serde(default)]
    pub private: Option<bool>,
    #[serde(default)]
    pub closed: Option<bool>,
}

/// `POST /projects/{owner}/{n}/cards`: a reference (`repo#12`) or a note,
/// into the column named (by id or name; the first column when absent).
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewCard {
    #[serde(default)]
    pub column: Option<String>,
    #[serde(default)]
    pub reference: String,
    #[serde(default)]
    pub note: String,
}

/// `PATCH /projects/{owner}/{n}/cards/{id}`: move to a column (id or name).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct CardMove {
    pub column: String,
}

/// `POST /repos/{o}/{n}/labels`: create a label, or change one of that name.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewLabel {
    pub name: String,
    /// `#rrggbb`; a default when absent.
    #[serde(default)]
    pub colour: Option<String>,
    #[serde(default)]
    pub description: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewComment {
    pub body: String,
    /// For a proposal: anchor the comment to this file's line (1-based) of
    /// the projected state; the hub records the line's atom.
    #[serde(default)]
    pub path: Option<String>,
    #[serde(default)]
    pub line: Option<usize>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewProposal {
    pub title: String,
    #[serde(default)]
    pub body: String,
    pub target: String,
    /// A bookmark here, or `owner/name:bookmark` of a fork.
    pub source: String,
    #[serde(default)]
    pub draft: bool,
}

/// `POST .../proposals/{number}/reviewers`: accounts to ask for a review.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ReviewRequest {
    pub reviewers: Vec<String>,
}

/// `POST .../proposals/{number}/review-requests`: ask an AI assistant the
/// repository may use (hub spec §13.4) to review; it answers as a `comment`
/// review via the assistant.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct AssistantRequest {
    pub assistant: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewReview {
    pub verdict: String,
    #[serde(default)]
    pub body: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct IssueStateChange {
    /// `open` or `closed`.
    pub state: String,
    #[serde(default)]
    pub reason: String,
}

/// A webhook payload's envelope (hub spec §12.2).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct WebhookEnvelope {
    pub event: String,
    pub delivery: String,
    pub repository: Option<Repository>,
    pub actor: String,
    pub at_ms: i64,
    pub data: serde_json::Value,
}

/// A server-sent event on a proposal's stream.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProposalEvent {
    pub number: i64,
    pub kind: String,
    pub check: Option<Check>,
}

// --------------------------------------------------------------- releases

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Release {
    pub tag: String,
    pub title: String,
    pub notes: String,
    pub prerelease: bool,
    pub latest: bool,
    pub author: String,
    pub heads: Vec<String>,
    pub signer: Option<String>,
    pub assets: Vec<ReleaseAsset>,
    pub archives: Vec<String>,
    pub created_ms: i64,
    pub url: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ReleaseAsset {
    pub name: String,
    pub size: i64,
    /// BLAKE3 of the content, hex.
    pub hash: String,
    pub content_type: String,
    pub downloads: i64,
    pub url: String,
    /// The OxygenFlow run and job whose artifact has this content, if any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub built_by: Option<AssetBuild>,
}

/// Where a release asset was built (hub spec §9): a job's artifact with the
/// same BLAKE3, and that job's signed receipt when one was kept.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct AssetBuild {
    pub run: i64,
    pub job: String,
    pub artifact: String,
    pub run_url: String,
    /// The receipt attestation, hex; `None` when the receipt was not signed.
    pub receipt: Option<String>,
    pub receipt_url: Option<String>,
    pub signer: Option<String>,
}

/// `PATCH /repos/{o}/{n}/proposals/{number}`: what is given changes,
/// the rest stays (oxygenhub#76).
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProposalEdit {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub body: Option<String>,
    /// The whole set of labels, by name (triage); oxygenhub#80.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub labels: Option<Vec<String>>,
}

/// `PATCH /repos/{owner}/{name}/releases/{tag}`: what to change; fields
/// left out stay as they are.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ReleaseEdit {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub notes: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub prerelease: Option<bool>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewRelease {
    pub tag: String,
    pub title: String,
    #[serde(default)]
    pub notes: Option<String>,
    #[serde(default)]
    pub prerelease: bool,
}

/// Every type of the API, for schema generation.
pub fn schemas() -> Vec<(&'static str, schemars::Schema)> {
    vec![
        ("Repository", schemars::schema_for!(Repository)),
        ("Visibility", schemars::schema_for!(Visibility)),
        ("Bookmark", schemars::schema_for!(Bookmark)),
        ("Tag", schemars::schema_for!(Tag)),
        ("ChangeSummary", schemars::schema_for!(ChangeSummary)),
        ("Author", schemars::schema_for!(Author)),
        ("Signature", schemars::schema_for!(Signature)),
        ("Problem", schemars::schema_for!(Problem)),
        ("Proposal", schemars::schema_for!(Proposal)),
        ("ProposalState", schemars::schema_for!(ProposalState)),
        ("ProposalSource", schemars::schema_for!(ProposalSource)),
        ("Approval", schemars::schema_for!(Approval)),
        ("Issue", schemars::schema_for!(Issue)),
        ("Label", schemars::schema_for!(Label)),
        ("Milestone", schemars::schema_for!(Milestone)),
        ("NewMilestone", schemars::schema_for!(NewMilestone)),
        ("MilestoneEdit", schemars::schema_for!(MilestoneEdit)),
        ("Comment", schemars::schema_for!(Comment)),
        ("ProposalFile", schemars::schema_for!(ProposalFile)),
        ("Notification", schemars::schema_for!(Notification)),
        ("Inbox", schemars::schema_for!(Inbox)),
        ("Atom", schemars::schema_for!(Atom)),
        ("Review", schemars::schema_for!(Review)),
        ("TreeEntry", schemars::schema_for!(TreeEntry)),
        ("BlameLine", schemars::schema_for!(BlameLine)),
        ("FileChange", schemars::schema_for!(FileChange)),
        ("ChangeDetail", schemars::schema_for!(ChangeDetail)),
        ("History", schemars::schema_for!(History)),
        ("Conflict", schemars::schema_for!(Conflict)),
        ("Push", schemars::schema_for!(Push)),
        ("Trust", schemars::schema_for!(Trust)),
        ("Policy", schemars::schema_for!(Policy)),
        ("Rule", schemars::schema_for!(Rule)),
        ("Hook", schemars::schema_for!(Hook)),
        ("NewHook", schemars::schema_for!(NewHook)),
        ("Check", schemars::schema_for!(Check)),
        ("CheckStatus", schemars::schema_for!(CheckStatus)),
        ("NewCheck", schemars::schema_for!(NewCheck)),
        ("User", schemars::schema_for!(User)),
        ("Organisation", schemars::schema_for!(Organisation)),
        ("NewRepository", schemars::schema_for!(NewRepository)),
        ("NewIssue", schemars::schema_for!(NewIssue)),
        ("IssueEdit", schemars::schema_for!(IssueEdit)),
        ("ReleaseEdit", schemars::schema_for!(ReleaseEdit)),
        ("ProposalEdit", schemars::schema_for!(ProposalEdit)),
        ("NewLabel", schemars::schema_for!(NewLabel)),
        ("RequiredChecks", schemars::schema_for!(RequiredChecks)),
        ("Project", schemars::schema_for!(Project)),
        ("ProjectCard", schemars::schema_for!(ProjectCard)),
        ("ProjectColumn", schemars::schema_for!(ProjectColumn)),
        ("Board", schemars::schema_for!(Board)),
        ("NewProject", schemars::schema_for!(NewProject)),
        ("ProjectEdit", schemars::schema_for!(ProjectEdit)),
        ("NewCard", schemars::schema_for!(NewCard)),
        ("CardMove", schemars::schema_for!(CardMove)),
        ("NewComment", schemars::schema_for!(NewComment)),
        ("NewProposal", schemars::schema_for!(NewProposal)),
        ("NewReview", schemars::schema_for!(NewReview)),
        ("IssueStateChange", schemars::schema_for!(IssueStateChange)),
        ("WebhookEnvelope", schemars::schema_for!(WebhookEnvelope)),
        ("ProposalEvent", schemars::schema_for!(ProposalEvent)),
        ("Release", schemars::schema_for!(Release)),
        ("FlowRun", schemars::schema_for!(FlowRun)),
        ("FlowJob", schemars::schema_for!(FlowJob)),
        ("FlowLogLine", schemars::schema_for!(FlowLogLine)),
        ("AssetBuild", schemars::schema_for!(AssetBuild)),
        ("ReleaseAsset", schemars::schema_for!(ReleaseAsset)),
        ("NewRelease", schemars::schema_for!(NewRelease)),
    ]
}

/// An OxygenFlow runner (`GET /api/v1/runners`, site administrators).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Runner {
    pub id: i64,
    pub name: String,
    /// `online`, `offline`, `draining` or `disabled`.
    pub status: String,
    /// What it serves: empty for the whole site, an owner, or `owner/name`.
    pub serves: String,
    pub arch: String,
    pub os: String,
    pub version: String,
    pub labels: Vec<String>,
    pub max_jobs: i64,
    pub memory_mib: Option<i64>,
    pub cpus: Option<i64>,
    /// The key that signs its receipts (KeyId hex), empty until bound.
    pub key: String,
    /// `registered` or `config` (a hub.toml token).
    pub source: String,
    pub last_seen_ms: Option<i64>,
    /// Jobs it is running now.
    pub running: i64,
}

/// A job a runner ran or is running.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct RunnerJob {
    pub repo: String,
    pub run: i64,
    pub job: String,
    pub status: String,
    pub started_ms: Option<i64>,
    pub finished_ms: Option<i64>,
}

/// A job in the queue: running ones first, then queued ones in the order
/// runners claim them.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct QueueItem {
    pub repo: String,
    pub run: i64,
    pub job: String,
    /// `running` or `queued`.
    pub status: String,
    /// The runner holding it, when running.
    pub runner: String,
}

// ------------------------------------------------------------- assistants

/// An AI assistant at a level (hub spec §13.4). The token never leaves the
/// hub: `has_token` says whether one is set.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Assistant {
    pub name: String,
    pub endpoint: String,
    pub api: String,
    pub model: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub headers: String,
    pub enabled: bool,
    pub budget: i64,
    pub has_token: bool,
    /// Where it comes from: empty for the level's own, else `the site` or
    /// `the NAME organisation`.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub from: String,
    /// Off because a level above turned a name like it off.
    #[serde(default)]
    pub off_above: bool,
}

/// `POST …/assistants`: add one, or change the one of that name. A
/// `preset` (`anthropic`, `openai`, `gemini`, `deepseek`, `mistral`,
/// `perplexity`, `ollama`) fills what is left out; the model must be one
/// the endpoint lists when it lists any; `token` is write-only.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewAssistant {
    #[serde(default)]
    pub name: String,
    #[serde(default)]
    pub preset: String,
    #[serde(default)]
    pub endpoint: String,
    #[serde(default)]
    pub api: String,
    pub model: String,
    #[serde(default)]
    pub token: String,
    #[serde(default)]
    pub headers: String,
    #[serde(default = "yes")]
    pub enabled: bool,
    #[serde(default)]
    pub budget: Option<i64>,
}

fn yes() -> bool {
    true
}

/// A level's prompt and those it inherits, outermost first.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct AssistantPrompt {
    pub prompt: String,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub inherited: Vec<(String, String)>,
}

/// `GET /repos/{o}/{n}/coverage`: a coverage report from a Flow job
/// (oxygenhub#113); `percent` values are of lines, functions and branches,
/// absent when nothing was counted.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct CoverageReport {
    pub id: i64,
    pub run: i64,
    pub job: String,
    pub bookmark: String,
    /// The run's state, by hash.
    pub state: String,
    /// `lcov` or `cobertura`.
    pub format: String,
    pub lines_found: i64,
    pub lines_hit: i64,
    pub percent: Option<f64>,
    pub functions_found: i64,
    pub functions_hit: i64,
    pub branches_found: i64,
    pub branches_hit: i64,
    pub files: i64,
    /// Files the report named that are not in the run's state.
    pub dropped: i64,
    pub created_ms: i64,
    /// The report on the hub's Coverage tab, absolute.
    pub url: String,
}

/// One file of a coverage report.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct CoverageFile {
    pub path: String,
    pub lines_found: i64,
    pub lines_hit: i64,
    pub percent: Option<f64>,
    pub functions_found: i64,
    pub functions_hit: i64,
    pub branches_found: i64,
    pub branches_hit: i64,
}

/// `GET /repos/{o}/{n}/coverage/{id}`: a report with its files.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct CoverageDetail {
    pub report: CoverageReport,
    pub files: Vec<CoverageFile>,
}

/// `GET /repos/{o}/{n}/tests`: a JUnit test report from a Flow job
/// (oxygenhub#114).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct TestReport {
    pub id: i64,
    pub run: i64,
    pub job: String,
    pub bookmark: String,
    pub state: String,
    pub tests: i64,
    pub passed: i64,
    pub failed: i64,
    pub errors: i64,
    pub skipped: i64,
    /// The cases' times added up.
    pub time_ms: i64,
    pub created_ms: i64,
    pub url: String,
}

/// One test case of a report.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct TestCase {
    pub suite: String,
    pub classname: String,
    pub name: String,
    /// `passed`, `failed`, `error` or `skipped`.
    pub status: String,
    pub time_ms: i64,
    pub message: String,
    /// A failure's text and output, cut to 16 KiB; empty for a pass.
    pub output: String,
}

/// `GET /repos/{o}/{n}/tests/{id}`: a report with its cases
/// (`?status=failed` for the failed and errored ones).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct TestReportDetail {
    pub report: TestReport,
    pub cases: Vec<TestCase>,
}
`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet
Keyboard
