API: the notifications inbox 42a0ba4bac4e resolution

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

}

        ("Notification", schemars::schema_for!(Notification)),

        ("Inbox", schemars::schema_for!(Inbox)),

export type Notification = {

  actor: string;

  at_ms: number;

  id: number;

  kind: string;

  read: boolean;

  title: string;

  url: string;

};

export type Inbox = {

  items: Notification[];

  unread: number;

};

        .route("/notifications", get(notifications))

        .route("/notifications/read", post(notifications_read_all))

        .route("/notifications/{id}/read", post(notification_read))

#[derive(Deserialize)]

struct InboxQuery {

    #[serde(default)]

    limit: Option<i64>,

}

/// The caller's inbox; reading and clearing it needs `user:read`, since

/// it touches nothing but the caller's own notifications.

async fn notifications(

    State(app): State<Shared>,

    headers: HeaderMap,

    Query(q): Query<InboxQuery>,

) -> Result<Json<hub_api::Inbox>, ApiError> {

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

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

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

    let base = app.config.base_url().trim_end_matches('/').to_string();

    let items = db::notify::inbox(&app.db, a.id, limit)

        .await?

        .into_iter()

        .map(|n| hub_api::Notification {

            id: n.id,

            at_ms: n.at_ms,

            kind: n.kind,

            title: n.title,

            url: if n.url.starts_with('/') { format!("{base}{}", n.url) } else { n.url },

            actor: n.actor,

            read: n.read,

        })

        .collect();

    Ok(Json(hub_api::Inbox { unread: db::notify::unread(&app.db, a.id).await?, items }))

}

async fn notification_read(State(app): State<Shared>, headers: HeaderMap, Path(id): Path<i64>) -> Result<StatusCode, ApiError> {

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

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

    db::notify::mark_read(&app.db, a.id, Some(id)).await?;

    Ok(StatusCode::NO_CONTENT)

}

async fn notifications_read_all(State(app): State<Shared>, headers: HeaderMap) -> Result<StatusCode, ApiError> {

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

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

    db::notify::mark_read(&app.db, a.id, None).await?;

    Ok(StatusCode::NO_CONTENT)

}

    // The inbox through the API: count, list, mark one read, mark all read.

    let bob_user = mint(bob.clone(), "scopes=user%3Aread").await;

    let bob_id = oxygenhub::db::accounts::account_by_name(&app.db, "bob").await.unwrap().unwrap().id;

    oxygenhub::db::notify::mark_read(&app.db, bob_id, None).await.unwrap();

    oxygenhub::db::notify::add(&app.db, bob_id, "mention", "andy/demo#1: Bug", "/andy/demo/issue/1", "andy").await.unwrap();

    oxygenhub::db::notify::add(&app.db, bob_id, "review", "andy/demo#2: Feat", "/andy/demo/proposal/2", "andy").await.unwrap();

    let (st, v) = api(app, "GET", "/api/v1/notifications", Some(&bob_user), None).await;

    assert_eq!(st, StatusCode::OK, "{v}");

    assert_eq!(v["unread"], 2);

    assert_eq!(v["items"][0]["read"], false);

    assert!(v["items"][0]["url"].as_str().unwrap().starts_with(&h.base), "absolute urls: {v}");

    let first = v["items"][0]["id"].as_i64().unwrap();

    let (st, _) = api(app, "POST", &format!("/api/v1/notifications/{first}/read"), Some(&bob_user), None).await;

    assert_eq!(st, StatusCode::NO_CONTENT);

    assert_eq!(api(app, "GET", "/api/v1/notifications", Some(&bob_user), None).await.1["unread"], 1);

    assert_eq!(api(app, "POST", "/api/v1/notifications/read", Some(&bob_user), None).await.0, StatusCode::NO_CONTENT);

    assert_eq!(api(app, "GET", "/api/v1/notifications", Some(&bob_user), None).await.1["unread"], 0);

    // Another account's notification is not the caller's to clear, and a token without user:read sees nothing.

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

JSON under `/api/v1`, bearer tokens, `application/json`, RFC 7807 problem responses, 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`, `/compare`, `/conflicts`, `/proposals`, `/proposals/{n}/comments|reviews|checks|files|land`, `/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`, `/labels`, `/milestones`, `/releases`, `/tags`, `/trust`, `/pushes`, `/hooks`, `/checks`, `/user`, `/notifications` (the caller's inbox and unread count; `/notifications/{id}/read` and `/notifications/read` mark read; scope `user:read`), `/users/{name}`, `/orgs/{name}`, `/search`. 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.

  --ok:#5fe3a1; --bad:#ff5e7a; --warn:#b48cff;

  --ok:#1f8f5f; --bad:#c62d47; --warn:#6b3fd1;