The API for apps: own repositories, organisations, 401, device cancel, richer notifications (closes #302, closes #303, closes #304, closes #305) ecac6e8d9b41

- **The API for apps (#302-#305), found building the Android app:** `GET /api/v1/user/repos` lists the caller's own repositories, their organisations' and those they collaborate on (`?affiliation=owner,organization,collaborator`, paged with `?after=owner/name&limit=`), and `GET /api/v1/user/orgs` their organisations and role (#302); a call with no token now answers 401 (sign in) rather than 403 (#303); `DELETE /api/v1/device/code` withdraws a device sign-in the app gave up on, at once (#304); each notification says its `repository`, `reason` (participating, watching), `thread` and the kind's `label` (#305).

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

/// `DELETE /api/v1/device/code` (#304): the app gave up (its user pressed

/// Cancel): the code is withdrawn at once, so nobody can approve it later,

/// rather than waiting out its fifteen minutes. Answers 204 whether or not

/// there was such a code; a code already approved and taken is a token

/// now, which the app revokes as any other.

pub async fn cancel(State(app): State<Shared>, Json(req): Json<TokenRequest>) -> Response {

    let hash = crate::auth::token_hash(req.device_code.trim());

    match accounts::device_by_hash(&app.db, &hash).await {

        Ok(Some(d)) => match accounts::delete_device(&app.db, d.id).await {

            Ok(_) => StatusCode::NO_CONTENT.into_response(),

            Err(e) => oauth_error(StatusCode::INTERNAL_SERVER_ERROR, "server_error", &e.to_string()),

        },

        Ok(None) => StatusCode::NO_CONTENT.into_response(),

        Err(e) => oauth_error(StatusCode::INTERNAL_SERVER_ERROR, "server_error", &e.to_string()),

    }

}

        .route("/device/code", post(device::code).delete(device::cancel))

        .route("/user/repos", get(user_repos))

        .route("/user/orgs", get(user_orgs))

        // No token is 401, sign in; a token without the scope is 403 (#303).

        let Some(account) = self.account.as_ref() else {

            return Err(ApiError(StatusCode::UNAUTHORIZED, "a personal access token is required: sign in (`oh auth login`)".into()));

        };

        Ok(account)

    let rows = db::notify::inbox(&app.db, a.id, limit).await?;

    // Repositories by id, each looked up once (#305).

    let mut repos: std::collections::HashMap<i64, Option<String>> = std::collections::HashMap::new();

    for id in rows.iter().filter_map(|n| n.repo_id) {

        if let std::collections::hash_map::Entry::Vacant(e) = repos.entry(id) {

            e.insert(db::repos::get_by_id(&app.db, id).await?.map(|r| format!("{}/{}", r.owner, r.name)));

        }

    }

    let absolute = |u: String| if u.starts_with('/') { format!("{base}{u}") } else { u };

    let items = rows

            label: crate::notify::label(&n.kind).map(String::from),

            url: absolute(n.url),

            repository: n.repo_id.and_then(|id| repos.get(&id).cloned().flatten()),

            reason: n.reason,

            thread: if n.thread.is_empty() { String::new() } else { absolute(n.thread) },

}

#[derive(Deserialize)]

struct UserReposQuery {

    /// Which: `owner`, `organization`, `collaborator`, comma-separated (all three by default).

    #[serde(default)]

    affiliation: Option<String>,

    /// The last `owner/name` of the previous page.

    #[serde(default)]

    after: Option<String>,

    #[serde(default)]

    limit: Option<usize>,

}

/// `GET /user/repos` (#302): the caller's repositories, their

/// organisations' and those they collaborate on, by `owner/name`, a page

/// at a time (`?after=owner/name&limit=`, at most 100, default 50).

async fn user_repos(

    State(app): State<Shared>,

    headers: HeaderMap,

    Query(q): Query<UserReposQuery>,

) -> Result<Json<Vec<Repository>>, ApiError> {

    let c = caller(&app, &headers).await?;

    let me = c.require("repo:read")?.clone();

    let wanted: Vec<String> = q

        .affiliation

        .as_deref()

        .unwrap_or("owner,organization,collaborator")

        .split(',')

        .map(|s| s.trim().to_ascii_lowercase())

        .filter(|s| !s.is_empty())

        .collect();

    if let Some(bad) = wanted.iter().find(|w| !["owner", "organization", "collaborator"].contains(&w.as_str())) {

        return Err(ApiError(StatusCode::BAD_REQUEST, format!("unknown affiliation {bad:?}: owner, organization or collaborator")));

    }

    let orgs: Vec<String> = db::accounts::orgs_of(&app.db, me.id).await?.into_iter().map(|(o, _)| o.name).collect();

    let limit = q.limit.unwrap_or(50).clamp(1, 100);

    let mut rows = db::repos::list(&app.db).await?;

    rows.sort_by(|a, b| (&a.owner, &a.name).cmp(&(&b.owner, &b.name)));

    let mut out = Vec::new();

    for r in rows {

        if let Some(after) = q.after.as_deref() {

            if format!("{}/{}", r.owner, r.name).as_str() <= after {

                continue;

            }

        }

        let mine = (wanted.iter().any(|w| w == "owner") && r.owner == me.username)

            || (wanted.iter().any(|w| w == "organization") && orgs.contains(&r.owner))

            || (wanted.iter().any(|w| w == "collaborator") && db::accounts::collaborator_role(&app.db, r.id, me.id).await?.is_some());

        if !mine || !auth::roles::allows(auth::roles::role_for(&app.db, Some(&me), &r).await?, Access::Read) {

            continue;

        }

        out.push(repository(&app, &r));

        if out.len() == limit {

            break;

        }

    }

    Ok(Json(out))

}

/// `GET /user/orgs` (#302): the organisations the caller belongs to.

async fn user_orgs(State(app): State<Shared>, headers: HeaderMap) -> Result<Json<Vec<hub_api::UserOrg>>, ApiError> {

    let c = caller(&app, &headers).await?;

    let me = c.require("user:read")?;

    let orgs = db::accounts::orgs_of(&app.db, me.id).await?;

    Ok(Json(orgs.into_iter().map(|(o, role)| hub_api::UserOrg { name: o.name, display_name: o.display_name, role }).collect()))

            repo_id: Some(oxygenhub::db::repos::get(&app.db, "andy", "demo").await.unwrap().unwrap().id),

            kind: "issue.opened",

    // Its repository, why, its thread and the kind's label (#305).

    let bug = v["items"].as_array().unwrap().iter().find(|n| n["title"] == "andy/demo#1: Bug").unwrap();

    assert_eq!(

        (bug["repository"].as_str(), bug["reason"].as_str(), bug["label"].as_str()),

        (Some("andy/demo"), Some("participating"), Some("🐛 New Issue")),

        "{bug}"

    );

    assert_eq!(bug["thread"].as_str(), Some(format!("{}/andy/demo/issue/1", h.base).as_str()));

    // No token at all is 401, so a client knows to sign in (#303).

    assert_eq!(api(app, "GET", "/api/v1/notifications", None, None).await.0, StatusCode::UNAUTHORIZED);

    assert_eq!(api(app, "GET", "/api/v1/user", None, None).await.0, StatusCode::UNAUTHORIZED);

    let (st, orgs) = api(app, "GET", "/api/v1/user/orgs", Some(&andy_user), None).await;

    assert!(st == StatusCode::OK && orgs.is_array(), "the caller's organisations (#302): {orgs}");

    // The caller's own repositories, a page at a time (#302); bob has none.

    api(app, "POST", "/api/v1/repos", Some(&a), Some(r#"{"owner":"andy","name":"zeta","visibility":"private"}"#)).await;

    let names =

        |v: &serde_json::Value| -> Vec<String> { v.as_array().unwrap().iter().map(|r| r["name"].as_str().unwrap().to_string()).collect() };

    let (st, v) = api(app, "GET", "/api/v1/user/repos", Some(&a), None).await;

    assert_eq!((st, names(&v)), (StatusCode::OK, vec!["demo".to_string(), "zeta".to_string()]), "{v}");

    assert_eq!(names(&api(app, "GET", "/api/v1/user/repos?limit=1", Some(&a), None).await.1), ["demo"]);

    assert_eq!(names(&api(app, "GET", "/api/v1/user/repos?after=andy/demo", Some(&a), None).await.1), ["zeta"]);

    assert!(names(&api(app, "GET", "/api/v1/user/repos", Some(&b), None).await.1).is_empty(), "not bob's");

    assert_eq!(api(app, "GET", "/api/v1/user/repos?affiliation=friend", Some(&a), None).await.0, StatusCode::BAD_REQUEST);

    assert_eq!(api(app, "GET", "/api/v1/user/repos", None, None).await.0, StatusCode::UNAUTHORIZED);

    // Organisations need user:read, which this token lacks.

    assert_eq!(api(app, "GET", "/api/v1/user/orgs", Some(&a), None).await.0, StatusCode::FORBIDDEN);

    // A code the app gave up on (#304) is gone at once: the page no longer

    // takes it, and the app's poll says so.

    let (_, v) = api(app, "POST", "/api/v1/device/code", None, Some(r#"{"client":"Cancelled"}"#)).await;

    let (device, user) = (v["device_code"].as_str().unwrap().to_string(), v["user_code"].as_str().unwrap().to_string());

    let (st, _) = api(app, "DELETE", "/api/v1/device/code", None, Some(&format!(r#"{{"device_code":"{device}"}}"#))).await;

    assert_eq!(st, StatusCode::NO_CONTENT);

    let page = call(app, "GET", &format!("/device?code={user}"), None, Some(&andy), None, None).await;

    let csrf = csrf_of(&page.body);

    call(app, "POST", "/device", None, Some(&andy), None, Some(&format!("_csrf={csrf}&code={user}&action=approve"))).await;

    let (_, v) = api(app, "POST", "/api/v1/device/token", None, Some(&format!(r#"{{"device_code":"{device}"}}"#))).await;

    assert_eq!(v["error"], "expired_token", "{v}");

    let (st, _) = api(app, "DELETE", "/api/v1/device/code", None, Some(&format!(r#"{{"device_code":"{device}"}}"#))).await;

    assert_eq!(st, StatusCode::NO_CONTENT, "again: still fine");

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses (an unknown route, or a known one with the wrong method, too), cursor pagination (`?after=`), ETags on cacheable resources, and rate limits per token. Resources mirror the pages: `/repos/{owner}/{name}`, `/bookmarks`, `/changes/{hash}`, `/tree/{ref}/{path}`, `/file/{ref}/{path}`, `/blame`, `/history/{ref}` (`?path=`, `?offset=&limit=`, or `?r=REVSET` for the changes a revset selects, evaluated under a two-second budget and answering 400 when it does not parse or goes past it; Oxygen's docs/revset_query_language.md), `/compare`, `/conflicts`, `/proposals` (`?state=open|draft|landed|closed|all`, open ones and drafts by default; a source bookmark may hold `/`, and `owner/name:bookmark` naming the repository itself is its own bookmark), `/proposals/{n}/comments|reviews|checks|files`, `PATCH /proposals/{n}` (the title and description, for its author or a maintainer, and `labels`, the whole set by name, for triage; what is not given stays), `POST /proposals/{n}/land` (repo:write: what the Land button does, `409` with the blockers when it cannot; a landed proposal keeps the changes it landed and reports `landed` with who, how (`web`, or `api (token NAME)`) and when, which its event, the audit log and the push record also say, adding when nobody approved), `/proposals/{n}/content/{base|head}/{path}` (a changed file's bytes in the target's state or the projected state, for editor diff views), `/issues` (creating an issue can set its labels, assignees and milestone; `PATCH /issues/{n}` edits the title and body for the author or triage, and replaces labels, assignees or the milestone for triage, recording each on the timeline; unknown names are refused before anything changes), `/labels` (`POST` creates or changes one, `DELETE /labels/{name}` removes it; triage), `/milestones` (`POST` creates one or changes the description and due date of the one with that title, `PATCH /milestones/{title}` changes title, description, due date or state; triage), `/releases` (`PATCH /releases/{tag}` changes the title, notes or prerelease flag, repo:write), `/tags` (`POST` creates one, repo:write; `DELETE /tags/{tag}` withdraws one, a maintainer, `409` while a release uses it; §9), `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/user/repos` (the caller's own, organisations' and collaborations, `?affiliation=&after=&limit=`, #302), `/user/orgs`, `/notifications` (the caller's inbox and unread count, each with its repository, reason, thread and label, #305; `/notifications/{id}/read` and `/notifications/read` mark read; scope `user:read`), `/users/{name}`, `/users/{name}/drops` and `/drops` (§4.5), `/orgs/{name}`, `/checks/{state}` (the checks on a state, named by its hash, by its heads joined with `+`, by the one head of a single-head state, or by a bookmark), `/checks/required` (`GET`, and `PUT` of the whole list by a repository admin: the checks a proposal needs, passed, to land), `/projects/{owner}` (list, create) and `/projects/{owner}/{n}` (the board as the caller may see it, `PATCH` for title, description, privacy and closing, and `owner` to transfer it to an owner the caller may make boards under (#125: it takes the next number there, and its old address redirects), `/cards` to list them by column or add a reference or note to a column named by id or name, `/cards/{id}` to move or remove one, `POST /cards/move` (#289: `{"from", "column", "except", "state", "dry_run"}`) to move a column's cards at once, but those `except` names (card ids or issue and proposal references) and, given `state`, only those whose issue or proposal is in one, all or none and audited once, answering what moved and what was kept; `repo:write` and the page's rights to change), `/coverage` and `/tests` (a bookmark's coverage and JUnit test reports from Flow jobs, newest first, `?bookmark=&limit=`), `POST /coverage` (repo:write, #136: `{"bookmark"}` or `{"change"}` and `content`, an LCOV or Cobertura report measured off the hub, kept for that state as uploaded by the caller, shown "uploaded by NAME" wherever a run number would be, and setting no check; `oh coverage upload FILE`), `/coverage/{id}` (a report with its files) and `/tests/{id}` (a report with its cases, `?status=failed` for the failed and errored ones), `/flow/runs` (`GET`: runs newest first, `?before=N&limit=`; `POST {"bookmark"}` or `{"change"}`, repo:write: run a bookmark's current state, the default bookmark when none is named, or one change's state; with `"jobs": [NAME..]` only those jobs and what they depend on, each one a manual run starts, else `409` naming the ones it does (#130); `oh run start --job NAME`), `/flow/runs/{n}` (a run with its jobs), `/flow/runs/{n}/jobs/{job}/log` (`?after=seq&limit=`) and `/flow/runs/{n}/rerun` (repo:write: a finished run again), both answering `201 {"number", "url"}` or `409` with why nothing started, `/flow/runs/{n}/jobs/{job}/rerun` (repo:write, oxygenflow#31: that job of a finished run again, in the same run, with the jobs that depend on it; what it depends on keeps its result, so a flaky test reruns without its build; their logs, artifacts and reports go, their checks return to queued and the run is running again; `{"queued": N}`, or `409` while the run is live or for a job it lacks; RE-RUN THIS JOB on the run page, `oh run rerun N --job NAME`), `/flow/runs/{n}/cancel` (repo:write: a run still going ends as `cancelled`, its running jobs stopped when their runner next reports; `409` when it had already ended; a push to a bookmark cancels the push runs of it still going), `/search`. A change's author carries the account its key is linked to, or `null` and a `note` saying the key is not linked and where its owner links it; `via` names the delegate (an agent) that signed for the author when one did, with the delegation's scope and expiry and whether it has since been revoked, and the pages show the same as an `agent` badge, a `via` row under the author on the change page, and a count under the author in Contributors (the change page shows a "key not linked" tag, with a link to Settings → Keys for signed-in viewers). Shapes reuse `oxy --json` shapes wherever one exists (change, status, blame, diff) so tools written against the CLI work against the hub. `crates/hub-api` holds the types with `serde` derives and is what the runner and the VS Code extension will link.