Notifications in the status bar and an inbox (0.3.0) b2dd082c57e4

// Notifications (spec §9.1): a bell in the status bar with the unread

// count across every signed-in hub, and an inbox quick pick that marks an

// entry read and opens it: in the editor when it is a proposal or issue

// of a repository in the workspace, on the hub otherwise.

import * as vscode from "vscode";

import type * as api from "./hubapi";

import { HubAuth } from "./auth";

import { HubTarget, hubTarget } from "./hub";

/** Opens a proposal or issue in the editor; false when it is not in the workspace. */

export type Opener = (target: Extract<HubTarget, { kind: "proposal" | "issue" }>) => Promise<boolean>;

interface Entry {

  base: string;

  n: api.Notification;

}

export class InboxBar implements vscode.Disposable {

  private readonly item = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Left, 39);

  private timer: NodeJS.Timeout | undefined;

  /** Unread count last seen, to announce only what is new. */

  private lastUnread: number | undefined;

  constructor(

    private readonly auth: HubAuth,

    private readonly open: Opener,

  ) {

    this.item.command = "oxygenhub.inbox";

    this.item.name = "Oxygenhub notifications";

  }

  /** Every hub's inbox; hubs that fail (offline, token without user:read) are skipped. */

  private async fetchAll(): Promise<{ unread: number; entries: Entry[]; failed: string[] }> {

    const out = { unread: 0, entries: [] as Entry[], failed: [] as string[] };

    for (const s of this.auth.all()) {

      try {

        const inbox = await this.auth.clientFor(s.base).notifications();

        out.unread += inbox.unread;

        out.entries.push(...inbox.items.map((n) => ({ base: s.base, n })));

      } catch {

        out.failed.push(s.base);

      }

    }

    out.entries.sort((a, b) => Number(a.n.read) - Number(b.n.read) || b.n.at_ms - a.n.at_ms);

    return out;

  }

  async refresh(): Promise<void> {

    if (!this.auth.all().length) {

      this.item.hide();

      return;

    }

    const { unread, entries, failed } = await this.fetchAll();

    this.item.text = unread ? `$(bell-dot) ${unread}` : "$(bell)";

    this.item.tooltip = unread ? `${unread} unread notification${unread === 1 ? "" : "s"}` : "No unread notifications";

    if (failed.length) {

      this.item.tooltip += `\nCould not read: ${failed.join(", ")} (the token needs user:read)`;

    }

    this.item.show();

    const announce = vscode.workspace.getConfiguration("oxygenhub").get<boolean>("announceNotifications") ?? true;

    if (announce && this.lastUnread !== undefined && unread > this.lastUnread) {

      const newest = entries.find((e) => !e.n.read);

      const more = unread - this.lastUnread;

      const text = more === 1 && newest ? `Oxygenhub: ${newest.n.actor ? newest.n.actor + ": " : ""}${newest.n.title}` : `Oxygenhub: ${more} new notifications`;

      void vscode.window.showInformationMessage(text, "Open Inbox").then((pick) => pick && vscode.commands.executeCommand("oxygenhub.inbox"));

    }

    this.lastUnread = unread;

  }

  /** The inbox quick pick. */

  async show(): Promise<void> {

    const { entries } = await this.fetchAll();

    type Pick = vscode.QuickPickItem & { entry?: Entry; all?: boolean };

    const items: Pick[] = entries.map((e) => ({

      label: `${e.n.read ? "$(circle-outline)" : "$(circle-filled)"} ${e.n.title}`,

      description: [e.n.actor, e.n.kind].filter(Boolean).join(" · "),

      detail: `${new Date(e.n.at_ms).toLocaleString()} · ${new URL(e.base).host}`,

      entry: e,

    }));

    if (entries.some((e) => !e.n.read)) {

      items.unshift({ label: "$(check-all) Mark all as read", all: true, alwaysShow: true });

    }

    if (!entries.length) {

      void vscode.window.showInformationMessage("Oxygenhub: your inbox is empty.");

      return;

    }

    const pick = await vscode.window.showQuickPick(items, { placeHolder: "Oxygenhub inbox", matchOnDescription: true, matchOnDetail: true });

    if (!pick) {

      return;

    }

    if (pick.all) {

      for (const s of this.auth.all()) {

        await this.auth.clientFor(s.base).markAllNotificationsRead().catch(() => undefined);

      }

      await this.refresh();

      return;

    }

    const e = pick.entry!;

    if (!e.n.read) {

      await this.auth.clientFor(e.base).markNotificationRead(e.n.id).catch(() => undefined);

    }

    const target = hubTarget(e.n.url);

    const opened = target.kind !== "other" && (await this.open(target).catch(() => false));

    if (!opened) {

      void vscode.env.openExternal(vscode.Uri.parse(e.n.url));

    }

    await this.refresh();

  }

  start(): void {

    const seconds = vscode.workspace.getConfiguration("oxygenhub").get<number>("autoRefresh") ?? 60;

    if (this.timer) {

      clearInterval(this.timer);

    }

    if (seconds > 0) {

      this.timer = setInterval(() => void this.refresh(), seconds * 1000);

    }

    void this.refresh();

  }

  dispose(): void {

    if (this.timer) {

      clearInterval(this.timer);

    }

    this.item.dispose();

  }

}

## 0.3.0

- A bell in the status bar with your unread notifications across every hub you are signed in to, and a message when new ones arrive (`oxygenhub.announceNotifications`).

- **Open Inbox**: your notifications, unread first; pick one to mark it read and open it, in the editor for proposals and issues of your workspace's repositories. Mark all as read from the top of the list.

- Needs Oxygenhub with the notifications API (2026-09-28) and a token with `user:read`.

- **Notifications**: an unread count in the status bar and an inbox that opens proposals and issues in the editor.

### 9.1 Notifications

A bell in the status bar shows the unread count summed over every signed-in hub (`GET /notifications`, polled on `oxygenhub.autoRefresh`). When the count rises, a message names the newest entry (or the number of new ones) with **Open Inbox**; `oxygenhub.announceNotifications` turns that off. **Open Inbox** is a quick pick of the newest entries, unread first, with **Mark all as read** at the top. Picking one marks it read and opens it in the editor when it is a proposal or issue of a repository in the workspace (the proposal detail or the issue view), otherwise on the hub. A hub whose token lacks `user:read` is skipped and named in the bell's tooltip.

  "version": "0.3.0",

        },

        "oxygenhub.announceNotifications": {

          "type": "boolean",

          "default": true,

          "description": "Show a message when new notifications arrive (checked on the autoRefresh interval)."

        "command": "oxygenhub.inbox",

        "title": "Open Inbox",

        "category": "Oxygenhub",

        "icon": "$(bell)"

      },

      {

import { InboxBar } from "./inbox";

let inbox: InboxBar;

  inbox = new InboxBar(auth, async (t) => {

    const repo = (await proposals.repos()).find((r) => r.base === t.base && r.owner === t.owner && r.name === t.name);

    if (!repo) {

      return false;

    }

    const client = auth.clientFor(repo.base);

    if (t.kind === "proposal") {

      const [p, checks] = await Promise.all([client.proposal(repo.owner, repo.name, t.number), client.proposalChecks(repo.owner, repo.name, t.number).catch(() => [])]);

      showDetail(repo, p, checks);

    } else {

      await showIssue(auth, repo, await client.issue(repo.owner, repo.name, t.number));

    }

    return true;

  });

  context.subscriptions.push(inbox);

    vscode.commands.registerCommand("oxygenhub.inbox", () => inbox.show()),

  inbox.start();

  void inbox.refresh();

  /** The caller's inbox: unread count and newest entries (needs user:read). */

  notifications(limit = 50): Promise<api.Inbox> {

    return this.request("GET", `/notifications?limit=${limit}`);

  }

  markNotificationRead(id: number): Promise<void> {

    return this.request("POST", `/notifications/${id}/read`);

  }

  markAllNotificationsRead(): Promise<void> {

    return this.request("POST", "/notifications/read");

  }

/** What a hub page URL points at, for opening it in the editor instead of a browser. */

export type HubTarget = { kind: "proposal" | "issue"; base: string; owner: string; name: string; number: number } | { kind: "other"; url: string };

export function hubTarget(url: string): HubTarget {

  const m = /^(https?:\/\/[^/]+)\/([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9][A-Za-z0-9._-]*)\/(proposal|issue)\/(\d+)(?:[/?#].*)?$/.exec(url);

  if (!m) {

    return { kind: "other", url };

  }

  return { kind: m[4] as "proposal" | "issue", base: m[1], owner: m[2], name: m[3], number: Number(m[5]) };

}

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;

};

import { HubClient, HubError, encodeDiffQuery, decodeDiffQuery, hubTarget } from "../out/hub.mjs";

    // The inbox: the site token acts as the administrator, andy.

    const inbox = await client.notifications();

    assert.equal(typeof inbox.unread, "number");

    assert.ok(Array.isArray(inbox.items));

    await client.markAllNotificationsRead();

    assert.equal((await client.notifications()).unread, 0);

test("hub page urls open in the editor when they are proposals or issues", () => {

  assert.deepEqual(hubTarget("https://earth.example:7343/andy/oxygen/proposal/12"), { kind: "proposal", base: "https://earth.example:7343", owner: "andy", name: "oxygen", number: 12 });

  assert.deepEqual(hubTarget("https://h/andy/demo/issue/3#c7"), { kind: "issue", base: "https://h", owner: "andy", name: "demo", number: 3 });

  assert.equal(hubTarget("https://h/andy/demo/releases/tag/v1").kind, "other");

  assert.equal(hubTarget("https://h/andy/demo/proposal/x").kind, "other");

});