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

# 8297a33b9a4c oxygenhub / crates / hub-api / src / lib.rs
64.8 KiB · Rust · last changed A phone as the second factor: Keystore keys approve sign-ins by the number the browser shows, and the sudo step asks a stale session again before sensitive changes (closes #356) 4 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>,
    /// Who set it to land when its checks pass (oxygenhub#261), while set.
    #[serde(default)]
    pub auto_land: Option<String>,
    /// 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)]
#[serde(deny_unknown_fields)]
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>,
    /// Where the anchor sits now: its 1-based line in `path` in the
    /// projected state, when the atom is still live there.
    #[serde(default)]
    pub line: Option<usize>,
    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,
    /// The repository it is about, `owner/name` (#305).
    #[serde(default)]
    pub repository: Option<String>,
    /// Why the caller is told: `participating` or `watching`.
    #[serde(default)]
    pub reason: String,
    /// The thread it belongs to (its page, without a fragment), absolute:
    /// a client groups the inbox by it.
    #[serde(default)]
    pub thread: String,
    /// The kind as the hub's pages label it ("🐛 New Issue"), when it has one.
    #[serde(default)]
    pub label: Option<String>,
}

/// `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,
    /// The diff with three lines of context, up to `DIFF_LINES` lines.
    #[serde(default)]
    pub lines: Vec<DiffLine>,
    /// Whether `lines` stops short of the whole diff.
    #[serde(default)]
    pub truncated: bool,
}

/// Lines of one file's diff the API sends at most.
pub const DIFF_LINES: usize = 2000;

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct DiffLine {
    /// `context`, `add`, `del`, or `gap` (lines left out between hunks).
    pub kind: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub old: Option<u32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub new: Option<u32>,
    #[serde(default)]
    pub text: String,
}

#[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,
    /// Why it ran on its runner (oxygenflow#42): "holds the image, idle,
    /// speed 100 (class 3)".
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub placed: String,
    /// Its approval gate (oxygenflow#57): `waiting` while it waits for a
    /// person to approve or reject it, `approved` or `rejected` after;
    /// empty for a job with no gate.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub approval: String,
    /// When it entered the queue (made, or run again), and when a runner
    /// claimed it: its wait is `started_ms - queued_ms` (oxygenhub#348).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub queued_ms: Option<i64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ready_ms: Option<i64>,
    /// Where its time went, as its runner reported (oxygenflow#35):
    /// `image`, `prepare`, `run` and `finish`, in that order.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub phases: Vec<FlowPhase>,
    /// The most disk and memory it took, as its runner reported, in MiB.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub peak_disk_mib: Option<i64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub peak_memory_mib: Option<i64>,
}

/// A phase of a job and its milliseconds.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct FlowPhase {
    pub name: String,
    pub ms: u64,
}

/// A report: what a Flow job published (OxygenFlow `output { report … }`)
/// or an upload, as docs/reports.md describes (oxygenhub#348).
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct Report {
    /// Its id, as the web page's `?id=` carries it.
    pub id: i64,
    /// The name the pipeline gave it (`report "frame-timing"`).
    pub name: String,
    /// `coverage`, `tests`, `performance` or `custom`.
    pub kind: String,
    pub title: String,
    pub summary: String,
    pub metrics: Vec<ReportMetric>,
    /// Its `[context]` table.
    pub context: serde_json::Value,
    /// The run and job that published it; none for an upload.
    pub run: Option<i64>,
    pub job: String,
    pub bookmark: String,
    /// The state it measured.
    pub state: String,
    /// How many files it has and their size together.
    pub files: i64,
    pub bytes: i64,
    pub created_ms: i64,
    /// When its files expired under retention (docs/reports.md §3.3): its
    /// metrics stay, its files are gone.
    pub files_expired_ms: Option<i64>,
    /// Its page on the hub.
    pub url: String,
    /// Its files, filled when one report is asked for.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub manifest: Vec<ReportFile>,
}

/// A metric of a report.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct ReportMetric {
    pub key: String,
    pub value: f64,
    pub unit: String,
    /// `lower`, `higher`, or empty.
    pub better: String,
    pub fail_above: Option<f64>,
    pub fail_below: Option<f64>,
}

/// A file of a report.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ReportFile {
    pub path: String,
    pub size: i64,
}

/// 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>,
}

/// `POST /user/runner-token`: a one-time token that registers a runner for
/// the caller's own repositories, as a phone does when its owner offers it
/// as a runner (oxygenhub-android#8). Spent by `flow runner register` (or
/// the app), within 24 hours.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct RunnerToken {
    pub token: String,
    /// Whose repositories the runner will serve.
    pub owner: String,
}

/// `GET /user/proposals`: the caller's proposals to act on, as the web
/// dashboard lists them: open ones by others in repositories they belong
/// to that they have not reviewed yet, and their own open and draft ones.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct UserProposals {
    pub review: Vec<ProposalBrief>,
    pub authored: Vec<ProposalBrief>,
    /// With `?landable=true` (#311): the open proposals the caller could
    /// land now, in repositories they can write to, with no blockers.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub landable: Vec<ProposalBrief>,
}

/// `GET /user/sky` (oxygenhub-android#23): Your sky's data, as the web
/// dashboard's backdrop reads it (docs/backgrounds.md §5): the caller's
/// repositories, newest-updated first, and their events of the last 30
/// days, newest first.
/// `GET /repos/{owner}/{name}/sky` gives one repository's in the same shape.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct UserSky {
    /// The hub's clock (milliseconds), to age the events by.
    pub now: i64,
    /// `owner/name` of each repository.
    pub repos: Vec<String>,
    /// `[repo, kind, at_ms, n]`: an index into `repos`; kind 0 a push of
    /// `n` changes, 1 a proposal event, 2 an issue event, 3 a release, 4 a
    /// Flow run.
    pub events: Vec<[i64; 4]>,
}

/// `GET /user/flow/runs` (oxygenhub-android#26): a run of one of the
/// caller's repositories, with its jobs, for a monitor across them all.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct UserFlowRun {
    /// `owner/name`.
    pub repository: String,
    #[serde(flatten)]
    pub run: FlowRun,
}

/// `GET /user/flow/runs` query: `before` (created before, ms) pages back.
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
pub struct UserFlowRunsQuery {
    #[serde(default)]
    pub limit: Option<i64>,
    #[serde(default)]
    pub before: Option<i64>,
}

/// `GET /user/starter?owner=X` (#347): the assistants a new repository
/// under `owner` may ask for its starting files; empty when none is set up
/// or the caller cannot create there.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct StarterAssistants {
    pub assistants: Vec<StarterAssistant>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct StarterAssistant {
    pub name: String,
    pub model: String,
    /// `the site` or `the acme organisation`.
    pub from: String,
}

/// `POST /repos/{owner}/{name}/starter`: what to make, and which assistant
/// (the first available when not given).
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
pub struct StarterRequest {
    pub description: String,
    #[serde(default)]
    pub assistant: Option<String>,
}

/// Where a repository's starter stands: `running`, `done` (with the
/// change and its files), `failed` (with why), or `none`.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct StarterStatus {
    pub status: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub assistant: String,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub change: String,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub files: Vec<String>,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub error: String,
}

/// An issue in a list across repositories: `GET /user/issues` (#359),
/// the open issues assigned to the caller, newest-updated first.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct IssueBrief {
    /// `owner/name`.
    pub repository: String,
    pub number: i64,
    pub title: String,
    pub updated_ms: i64,
    /// `https://hub/{owner}/{name}/issue/{number}`.
    pub url: String,
}

/// `POST /user/authenticators` (oxygenhub#356): this phone as a second
/// factor. `public_key` is hex of the Keystore key's SubjectPublicKeyInfo
/// (or its bare uncompressed P-256 point); `code` is the account's current
/// authenticator-app code, which adding a phone needs.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewAuthenticator {
    pub public_key: String,
    pub code: String,
}

/// A phone that approves sign-ins and sensitive actions for its account.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Authenticator {
    /// The sign-in (token) it belongs to: signing that phone out removes it.
    pub id: i64,
    pub name: String,
    pub created_ms: i64,
    /// When it last approved something; 0 for never.
    pub last_used_ms: i64,
    /// The caller's own phone.
    #[serde(default)]
    pub this: bool,
}

/// An approval waiting for the caller's phone (`GET /user/approvals`).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct PendingApproval {
    pub id: String,
    /// `signin` or `stepup`.
    pub kind: String,
    /// What it is for: "Sign in from Firefox on Linux, 203.0.113.9".
    pub what: String,
    /// The three numbers to offer; the browser shows one of them.
    pub choices: Vec<i64>,
    pub created_ms: i64,
    pub expires_ms: i64,
}

/// `POST /user/approvals/{id}`: the phone's answer. To approve, `number`
/// is the one picked and `signature` the hex DER ECDSA signature, by the
/// phone's key, over `oxygenhub approval v1\n{id}\n{number}\napprove`.
/// A denial needs neither.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ApprovalAnswer {
    pub approve: bool,
    #[serde(default)]
    pub number: i64,
    #[serde(default)]
    pub signature: String,
}

/// `GET /user/proposals` query.
#[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)]
pub struct UserProposalsQuery {
    /// Also list what the caller can land now (slower: each proposal's
    /// projected state is worked out).
    #[serde(default)]
    pub landable: bool,
}

/// A proposal in a list across repositories.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ProposalBrief {
    /// `owner/name`.
    pub repository: String,
    pub number: i64,
    pub title: String,
    pub author: String,
    pub state: ProposalState,
    pub conflicted: bool,
    pub updated_ms: i64,
    /// `https://hub/{owner}/{name}/proposal/{number}`.
    pub url: String,
}

/// `GET /user/orgs` (#302): an organisation the caller belongs to, and
/// their role there.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct UserOrg {
    pub name: String,
    pub display_name: String,
    pub role: 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)]
#[serde(deny_unknown_fields)]
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,
    /// The issue's or proposal's label names (oxygenhub#293).
    #[serde(default)]
    pub labels: Vec<String>,
    /// An issue's assignees' usernames.
    #[serde(default)]
    pub assignees: Vec<String>,
    /// When it was archived (ms), for an archived card (oxygenhub#293).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub archived_ms: Option<i64>,
}

#[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)]
#[serde(deny_unknown_fields)]
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 /projects/{owner}/{n}/cards/move` (#289): every card of column
/// `from` to `column` at once, but those `except` names (card ids, or issue
/// and proposal numbers as `12`, `#12`, `name#12` or `owner/name#12`) and,
/// given `state`, only cards whose issue or proposal is in one of them
/// (`closed`, `landed`…). With `dry_run`, nothing moves.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct CardsMove {
    pub from: String,
    pub column: String,
    #[serde(default)]
    pub except: Vec<String>,
    #[serde(default)]
    pub state: Vec<String>,
    #[serde(default)]
    pub dry_run: bool,
}

/// What a bulk move moved, and what it left in the column.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct CardsMoved {
    pub moved: Vec<ProjectCard>,
    pub kept: Vec<ProjectCard>,
    pub dry_run: bool,
}

/// `POST /projects/{owner}/{n}/cards/archive` (oxygenhub#293): take the
/// cards of column `from` off the board, kept and restorable, but those
/// `except` names and, given `state`, only cards whose issue or proposal is
/// in one of them; given `older_days`, only cards that joined the column
/// more than that many days ago. With `dry_run`, nothing is archived.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct CardsArchive {
    pub from: String,
    #[serde(default)]
    pub older_days: Option<i64>,
    #[serde(default)]
    pub except: Vec<String>,
    #[serde(default)]
    pub state: Vec<String>,
    #[serde(default)]
    pub dry_run: bool,
}

/// What an archive took off the board, and what it left in the column.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct CardsArchived {
    pub archived: Vec<ProjectCard>,
    pub kept: Vec<ProjectCard>,
    pub dry_run: bool,
}

/// `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)]
#[serde(deny_unknown_fields)]
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>>,
    /// `closed`, `open` (reopen a closed one, or make a draft ready for
    /// review) or `draft` (turn an open one back into a draft), by its
    /// author or with triage access, as the page's buttons do
    /// (oxygenhub#140, #313).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub state: Option<String>,
    /// `false` makes a draft ready for review, `true` turns an open
    /// proposal back into a draft: the same as `state`, in the words a
    /// proposal is created with (#313).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub draft: Option<bool>,
}

/// `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)]
#[serde(deny_unknown_fields)]
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>,
}

/// A drop (oxygenhub#279): a small snippet of one or more files, its own
/// Oxygen repository, never listed among repositories. `GET /drops` lists
/// yours, `GET /users/{name}/drops` someone's public ones, and
/// `GET /drops/{id}` one with its files' content.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Drop {
    /// 24 hex digits, unique on the hub.
    pub id: String,
    pub owner: String,
    pub title: String,
    pub description: String,
    /// `public` (listed on its owner's Drops page) or `secret` (unlisted:
    /// readable by anyone with its address).
    pub visibility: String,
    /// The drop's page.
    pub url: String,
    /// What `oxy clone` takes.
    pub clone_url: String,
    pub created_ms: i64,
    pub updated_ms: i64,
    pub files: Vec<DropFile>,
    /// How many have starred it, and whether the caller has (oxygenhub#349).
    #[serde(default)]
    pub stars: i64,
    #[serde(default)]
    pub starred: bool,
    /// The drop it was forked from, its page, while that drop exists.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub forked_from: Option<String>,
    /// Its files without the site around them, for an `<iframe>` (#280).
    #[serde(default)]
    pub embed_url: String,
}

/// A comment on a drop (oxygenhub#349).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct DropComment {
    /// Its number on the drop.
    pub id: i64,
    pub author: String,
    /// Markdown.
    pub body: String,
    pub created_ms: i64,
}

/// `POST /drops/{id}/comments`.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewDropComment {
    pub body: String,
}

/// `POST /repos/{owner}/{name}/attachments?name=FILE` (oxygenhub#350): a
/// file attached for an issue, comment or proposal to show; the body is the
/// file's bytes.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Attachment {
    pub id: i64,
    pub name: String,
    pub size: i64,
    /// Checked from the bytes: an image the page may show, or
    /// `application/octet-stream`.
    pub content_type: String,
    /// An image shown in place; anything else is a download.
    pub inline: bool,
    pub url: String,
    /// What to put in an issue or comment: `![name](url)` for an image,
    /// `[name](url)` otherwise.
    pub markdown: String,
}

/// A drop's stars after `PUT` or `DELETE /drops/{id}/star`.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct DropStars {
    pub stars: i64,
    pub starred: bool,
}

/// One of a drop's files. Lists carry no content; one drop's view carries
/// the content of each text file up to 512 KiB.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct DropFile {
    pub name: String,
    pub size: u64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub content: Option<String>,
    /// The file's bytes on the default bookmark.
    pub raw_url: String,
}

/// `POST /drops`: a new drop with at least one file.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewDrop {
    #[serde(default)]
    pub title: String,
    #[serde(default)]
    pub description: String,
    /// Unlisted, readable by anyone with its address.
    #[serde(default)]
    pub secret: bool,
    pub files: Vec<NewDropFile>,
}

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

/// `PATCH /drops/{id}`: what to change; what is left out stays.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct DropEdit {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub secret: Option<bool>,
    /// Files to write, or to remove (`content` null); others are kept.
    #[serde(default)]
    pub files: Vec<DropFileEdit>,
    /// The change's message (default "Edit TITLE").
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub message: Option<String>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct DropFileEdit {
    pub name: String,
    #[serde(default)]
    pub content: Option<String>,
}

/// `POST …/tags` (#295): tag the state of `target` (a bookmark, tag or
/// change; the default bookmark when absent).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct NewTag {
    pub name: String,
    #[serde(default)]
    pub target: Option<String>,
    #[serde(default)]
    pub message: Option<String>,
}

#[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,
}

/// `GET /repos/{o}/{n}/diffusion` (oxygenhub#153): what a repository
/// takes from (the subrepos it pins) and what it diffuses to (the
/// repositories that pin it), each as the Diffusion pages show it.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct Diffusion {
    pub takes_from: Vec<DiffusionPin>,
    pub diffuses_to: Vec<DiffusionPin>,
}

/// One pin of an upstream by a consumer, both named `owner/name`.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct DiffusionPin {
    pub upstream: String,
    pub consumer: String,
    /// Where the consumer pins it.
    pub path: String,
    /// The consumer's bookmark its bumps land on.
    pub bookmark: String,
    /// Upstream changes the pin lacks; absent when the hub cannot tell.
    #[serde(default)]
    pub behind: Option<u64>,
    /// `off`, `green` or `any`.
    pub follow: String,
    /// The open bump proposal's number, on the consumer.
    #[serde(default)]
    pub bump: Option<i64>,
    /// The newest run of the bump: number and status.
    #[serde(default)]
    pub run: Option<i64>,
    #[serde(default)]
    pub run_status: Option<String>,
    /// The pill: the upstream's half, then the consumer's.
    pub upstream_state: DiffusionHalf,
    pub consumer_state: DiffusionHalf,
}

/// One half of the Diffusion pill.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct DiffusionHalf {
    /// `green`, `amber`, `red`, `grey` or `off`.
    pub tone: String,
    /// What the pill says: `checked`, `untested`, `passes`, `up to date`…
    pub word: String,
    /// The sentence behind it.
    pub title: String,
}

/// Every type of the API, for schema generation.
pub fn schemas() -> Vec<(&'static str, schemars::Schema)> {
    vec![
        ("Repository", schemars::schema_for!(Repository)),
        ("Diffusion", schemars::schema_for!(Diffusion)),
        ("DiffusionPin", schemars::schema_for!(DiffusionPin)),
        ("DiffusionHalf", schemars::schema_for!(DiffusionHalf)),
        ("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)),
        ("FlowPhase", schemars::schema_for!(FlowPhase)),
        ("Report", schemars::schema_for!(Report)),
        ("ReportMetric", schemars::schema_for!(ReportMetric)),
        ("ReportFile", schemars::schema_for!(ReportFile)),
        ("AssetBuild", schemars::schema_for!(AssetBuild)),
        ("ReleaseAsset", schemars::schema_for!(ReleaseAsset)),
        ("NewRelease", schemars::schema_for!(NewRelease)),
        ("Drop", schemars::schema_for!(Drop)),
        ("DropComment", schemars::schema_for!(DropComment)),
        ("NewDropComment", schemars::schema_for!(NewDropComment)),
        ("DropStars", schemars::schema_for!(DropStars)),
        ("Attachment", schemars::schema_for!(Attachment)),
        ("NewDrop", schemars::schema_for!(NewDrop)),
        ("DropEdit", schemars::schema_for!(DropEdit)),
        ("UserProposals", schemars::schema_for!(UserProposals)),
        ("ProposalBrief", schemars::schema_for!(ProposalBrief)),
        ("IssueBrief", schemars::schema_for!(IssueBrief)),
        ("NewAuthenticator", schemars::schema_for!(NewAuthenticator)),
        ("Authenticator", schemars::schema_for!(Authenticator)),
        ("PendingApproval", schemars::schema_for!(PendingApproval)),
        ("ApprovalAnswer", schemars::schema_for!(ApprovalAnswer)),
        ("StarterAssistants", schemars::schema_for!(StarterAssistants)),
        ("StarterStatus", schemars::schema_for!(StarterStatus)),
        ("StarterRequest", schemars::schema_for!(StarterRequest)),
        ("TestReport", schemars::schema_for!(TestReport)),
        ("TestReportDetail", schemars::schema_for!(TestReportDetail)),
    ]
}

/// 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,
    /// What it measured at its last claim (oxygenflow#40): free disk in
    /// MiB, the 1-minute load ×100, its speed score (100 on the reference
    /// machine) and class 1–5, its kernel.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub free_disk_mib: Option<i64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub load_x100: Option<i64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub speed: Option<i64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub speed_class: Option<i64>,
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub kernel: String,
}

/// 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,
    /// Who uploaded it from a workstation (#136), when no Flow job made it;
    /// `run` and `job` are then 0 and "upload".
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub uploaded_by: Option<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>,
}

/// `GET /api/v1/admin/runner-updates` (oxygenhub#322): where runner builds
/// come from, every level's settings, the test groups, each runner's policy
/// and what it is offered, and the builds held back (#326). Site
/// administrators only.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct RunnerUpdates {
    /// The repository whose releases carry runner builds (`owner/name`).
    pub repo: String,
    pub settings: Vec<UpdateSetting>,
    pub groups: Vec<RunnerGroup>,
    pub runners: Vec<RunnerUpdate>,
    pub holds: Vec<HeldBuild>,
}

/// One level's update settings; `None` inherits from the next level out.
/// `PUT /api/v1/admin/runner-updates/settings` takes one.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct UpdateSetting {
    /// `site`, `owner`, `group` or `runner`.
    pub scope: String,
    /// Empty for the site; the owner's name, the group's id, the runner's id.
    #[serde(default)]
    pub key: String,
    #[serde(default)]
    pub updates: Option<bool>,
    /// `stable`, `canary` or a version.
    #[serde(default)]
    pub channel: Option<String>,
    /// Hours (UTC) in which updates may start, `02-05`.
    #[serde(default)]
    pub window: Option<String>,
    #[serde(default)]
    pub dry_run: Option<bool>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct RunnerGroup {
    pub id: i64,
    /// Empty for a group of the site's runners.
    pub owner: String,
    pub name: String,
    /// A share of the runners in reach; `None`: chosen ones.
    pub percent: Option<i64>,
    /// Its runners now, by name.
    pub members: Vec<String>,
    /// The wave it takes a version in (oxygenflow#84); `None`: after every wave.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wave: Option<i64>,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct RunnerUpdate {
    pub id: i64,
    pub name: String,
    /// The owner it serves; empty for the site's.
    pub owner: String,
    pub version: String,
    pub groups: Vec<String>,
    pub updates: bool,
    pub channel: String,
    #[serde(default)]
    pub window: Option<String>,
    pub dry_run: bool,
    /// Where each setting came from, in the order updates, channel, window, dry run.
    pub from: Vec<String>,
    /// What the hub would offer it now, in words.
    pub now: String,
    /// What it last said about its update.
    pub said: String,
}

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct HeldBuild {
    pub version: String,
    pub runner: String,
    pub why: String,
    pub at_ms: i64,
}
`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet
Keyboard
