| 1 | /** |
| 2 | * Notifications: the notify service (`services/notify`) keeps one feed per |
| 3 | * person, a Durable Object holding their open tabs' sockets, their latest |
| 4 | * notifications, live unread counts, their browser push subscriptions and |
| 5 | * the phones the g1t app pushes to. |
| 6 | * |
| 7 | * Chat tells it about every message a person should count or hear of, the |
| 8 | * events service about every inbox item, and the site forwards each tab's |
| 9 | * `/-/live` socket to it. Wire shapes are snake_case end to end. |
| 10 | */ |
| 11 | import type { AgentLook } from "./agent-look"; |
| 12 | import type { CardAction } from "./chat"; |
| 13 | import type { ServiceBinding } from "./clients"; |
| 14 | import type { User } from "./identity"; |
| 15 | |
| 16 | /** |
| 17 | * What a notification is about; the preferences decide which ones toast and |
| 18 | * push. `security` is an urgent security alert (critical or high, a refused |
| 19 | * push, a vulnerability report), shown like a mention; the rest of the |
| 20 | * security items are ordinary `inbox` ones. |
| 21 | */ |
| 22 | export type NotificationKind = "dm" | "mention" | "thread_reply" | "inbox" | "agent_waiting" | "approval" | "security"; |
| 23 | |
| 24 | export const NOTIFICATION_KINDS: readonly NotificationKind[] = ["dm", "mention", "thread_reply", "inbox", "agent_waiting", "approval", "security"]; |
| 25 | |
| 26 | /** Who it is from: a person, an agent, or g1t itself. */ |
| 27 | export type NotificationActor = { |
| 28 | kind: "user" | "agent" | "system"; |
| 29 | id: string; |
| 30 | /** How they show: a display name. */ |
| 31 | name: string; |
| 32 | /** A person's uploaded avatar hash, or null for the letter avatar. */ |
| 33 | avatar?: string | null; |
| 34 | /** What an agent's face is drawn from when it chose none. */ |
| 35 | avatar_seed?: string | null; |
| 36 | /** An agent's chosen face (./agent-look.ts). */ |
| 37 | look?: AgentLook | null; |
| 38 | }; |
| 39 | |
| 40 | export type FeedNotification = { |
| 41 | /** Unique per notification: the same id twice is told once. */ |
| 42 | id: string; |
| 43 | kind: NotificationKind; |
| 44 | /** The workspace's slug. */ |
| 45 | workspace: string; |
| 46 | title: string; |
| 47 | /** A short preview, a line or two. */ |
| 48 | body: string; |
| 49 | /** Where clicking it goes, relative to the site. */ |
| 50 | href: string; |
| 51 | actor: NotificationActor; |
| 52 | /** The conversation it is in, for a chat notification: toasts for the open one are skipped, and pushes collapse by it. */ |
| 53 | channel_id?: string | null; |
| 54 | /** The thread it is in, for a reply: quick replies go there. */ |
| 55 | thread_root?: string | null; |
| 56 | /** |
| 57 | * The chat card it is about, when that card has something to press: a |
| 58 | * session at its cap (Approve more, Stop, Open), a draft issue (File |
| 59 | * issue, Discard). The toast and the notifications panel show these |
| 60 | * actions, and pressing one goes to the site's `card_action`, exactly as |
| 61 | * on the card itself. |
| 62 | */ |
| 63 | card?: NotificationCard | null; |
| 64 | created_at: string; |
| 65 | }; |
| 66 | |
| 67 | /** A card's place and its main actions, carried on a notification about it. */ |
| 68 | export type NotificationCard = { |
| 69 | /** The conversation the card is in. */ |
| 70 | channel_id: string; |
| 71 | /** The message that is the card. */ |
| 72 | message_id: string; |
| 73 | /** The card's actions as it offers them: ids, labels, inputs and links, the same as on the card. */ |
| 74 | actions: CardAction[]; |
| 75 | }; |
| 76 | |
| 77 | /** How much a person hears of. Counts always move; this governs toasts and pushes. */ |
| 78 | export type NotifyLevel = "all" | "dms_mentions" | "none"; |
| 79 | |
| 80 | export const NOTIFY_LEVELS: readonly NotifyLevel[] = ["all", "dms_mentions", "none"]; |
| 81 | |
| 82 | export type NotifyPreferences = { |
| 83 | level: NotifyLevel; |
| 84 | /** A different level for a workspace, by slug. */ |
| 85 | workspaces: Record<string, NotifyLevel>; |
| 86 | }; |
| 87 | |
| 88 | /** A change to them: a workspace set to null goes back to the general level. */ |
| 89 | export type NotifyPreferencesChange = { level?: NotifyLevel; workspaces?: Record<string, NotifyLevel | null> }; |
| 90 | |
| 91 | export const DEFAULT_NOTIFY_PREFERENCES: NotifyPreferences = { level: "dms_mentions", workspaces: {} }; |
| 92 | |
| 93 | /** A browser's push subscription, as `PushSubscription.toJSON()` gives it. */ |
| 94 | export type PushSubscriptionJson = { |
| 95 | endpoint: string; |
| 96 | expiration_time?: number | null; |
| 97 | keys: { p256dh: string; auth: string }; |
| 98 | }; |
| 99 | |
| 100 | /** |
| 101 | * A phone the g1t app runs on, as the app registers it: the push token |
| 102 | * Expo gave it (`ExponentPushToken[…]`), which platform, and a name to |
| 103 | * know it by (at most 100 characters). |
| 104 | */ |
| 105 | export type PushDevice = { token: string; platform: "android" | "ios"; name?: string | null }; |
| 106 | |
| 107 | /** A conversation's unread counts for one person. */ |
| 108 | export type ChannelCounts = { channel_id: string; unread: number; mentions: number; muted: boolean }; |
| 109 | |
| 110 | /** |
| 111 | * What a person has unread in a workspace. `chat_unread` leaves out muted |
| 112 | * conversations, as the rail's badge does; mentions count everywhere. |
| 113 | * `inbox_unread` is the person's whole inbox, which is not per workspace. |
| 114 | * `complete` says `per_channel` was read from chat itself (on connect), so |
| 115 | * a conversation left out of it has nothing unread. |
| 116 | */ |
| 117 | export type FeedCounts = { |
| 118 | workspace: string; |
| 119 | chat_unread: number; |
| 120 | chat_mentions: number; |
| 121 | inbox_unread: number; |
| 122 | per_channel: Omit<ChannelCounts, "muted">[]; |
| 123 | complete: boolean; |
| 124 | }; |
| 125 | |
| 126 | // ── Presence and status ────────────────────────────────────────────────── |
| 127 | // |
| 128 | // Presence is worked out live by the person's feed from their open tabs: |
| 129 | // `active` while a tab has been used in the last few minutes, `away` when |
| 130 | // every tab has sat idle (or they set themselves away), `offline` once no |
| 131 | // tab is open. Status is what they say about themselves: an emoji and a |
| 132 | // few words, cleared at a time they chose. Do Not Disturb silences toasts |
| 133 | // and pushes until a time; counts still move. |
| 134 | // |
| 135 | // Both are kept by the notify service (the feed, one per person) and told |
| 136 | // to everyone who shares a workspace with them, over the same socket, |
| 137 | // through one presence room per workspace. Nothing polls. |
| 138 | |
| 139 | export type Presence = "active" | "away" | "offline"; |
| 140 | |
| 141 | /** |
| 142 | * Who set a status: the person, or something acting for them. Calendars |
| 143 | * and other integrations set `calendar` or `integration` (with their own |
| 144 | * `clear_at`); a status the person set by hand is never replaced by one. |
| 145 | */ |
| 146 | export type StatusSource = "manual" | "calendar" | "integration"; |
| 147 | |
| 148 | export const STATUS_SOURCES: readonly StatusSource[] = ["manual", "calendar", "integration"]; |
| 149 | |
| 150 | export type PersonStatus = { |
| 151 | /** One emoji, or a custom emoji's `:name:`; null for none. */ |
| 152 | emoji: string | null; |
| 153 | /** A few words: "In a meeting". At most 100 characters. */ |
| 154 | text: string; |
| 155 | /** When it clears itself (RFC 3339); null keeps it until changed. */ |
| 156 | clear_at: string | null; |
| 157 | source: StatusSource; |
| 158 | /** When it was set (RFC 3339). */ |
| 159 | set_at: string; |
| 160 | }; |
| 161 | |
| 162 | /** How a person shows to the people who share a workspace with them. */ |
| 163 | export type PresenceEntry = { |
| 164 | user_id: string; |
| 165 | username: string; |
| 166 | presence: Presence; |
| 167 | /** Do Not Disturb, until then (RFC 3339); null when off. */ |
| 168 | dnd_until: string | null; |
| 169 | status: PersonStatus | null; |
| 170 | /** When this last changed, in ms: a later word wins. */ |
| 171 | at: number; |
| 172 | }; |
| 173 | |
| 174 | /** The signed-in person's own: what everyone sees, and whether they set themselves away. */ |
| 175 | export type OwnPresence = PresenceEntry & { away_manual: boolean }; |
| 176 | |
| 177 | /** |
| 178 | * A change to your own. `status: null` clears it; `away` sets (or ends) |
| 179 | * being away by hand; `dnd_until: null` resumes notifications. |
| 180 | */ |
| 181 | export type PresenceChange = { |
| 182 | status?: { emoji?: string | null; text: string; clear_at?: string | null; source?: StatusSource } | null; |
| 183 | away?: boolean; |
| 184 | dnd_until?: string | null; |
| 185 | }; |
| 186 | |
| 187 | // ── Live repository pages ──────────────────────────────────────────────── |
| 188 | // |
| 189 | // A tab on a repository's page asks to watch it (`watchRepo`, through the |
| 190 | // site, which first checks the person may read it). The events service |
| 191 | // then tells notify of everything that happens there that a page shows |
| 192 | // (`repoChanged`, from crates/contracts/src/live.rs), and the actions |
| 193 | // service of runs' jobs starting and finishing; notify passes each change |
| 194 | // to the feeds watching that repository (one topic per repository), whose |
| 195 | // tabs refresh the page (apps/web/app/lib/repo-live.ts). |
| 196 | |
| 197 | /** |
| 198 | * Something that happened in a repository, as live pages hear of it: what |
| 199 | * kind of thing moved and where, never anything written in it. |
| 200 | */ |
| 201 | export type RepoChange = { |
| 202 | repo_id: string; |
| 203 | /** `owner/name`, as the person watching it asked for it; filled in by notify. */ |
| 204 | repo?: string | null; |
| 205 | /** The event's type (`git.push`, `pull.updated`, `checks.completed`, …), or `run.updated` for a run's job starting or finishing. */ |
| 206 | kind: string; |
| 207 | /** The full ref a push or deletion moved (`refs/heads/main`), or a run's. */ |
| 208 | ref?: string | null; |
| 209 | /** The issue or pull request it is on, or the pull request a run ran for. */ |
| 210 | number?: number | null; |
| 211 | /** The commit: where a push left its ref, the one checked or reported on. */ |
| 212 | sha?: string | null; |
| 213 | /** A workflow run's id. */ |
| 214 | run?: string | null; |
| 215 | /** How many commits a push brought to its branch, when it was counted. */ |
| 216 | commits?: number | null; |
| 217 | /** RFC 3339. */ |
| 218 | at: string; |
| 219 | }; |
| 220 | |
| 221 | /** How long one `watchRepo` lasts: a page open longer asks again before it runs out. */ |
| 222 | export const REPO_WATCH_MS = 15 * 60_000; |
| 223 | |
| 224 | /** What the feed socket sends a tab. */ |
| 225 | export type FeedEvent = |
| 226 | | { type: "hello"; notifications: FeedNotification[]; vapid_public_key: string | null; preferences: NotifyPreferences } |
| 227 | | { type: "notification"; notification: FeedNotification; toast: boolean } |
| 228 | | ({ type: "counts" } & FeedCounts) |
| 229 | | { type: "preferences"; preferences: NotifyPreferences } |
| 230 | /** The person's inbox count as it now is, after items arrive or are marked anywhere. */ |
| 231 | | { type: "inbox"; unread: number } |
| 232 | /** |
| 233 | * People in a workspace: everyone known on connect (`full`), then each |
| 234 | * one as they change. |
| 235 | */ |
| 236 | | { type: "presence"; workspace: string; people: PresenceEntry[]; full: boolean } |
| 237 | /** Your own presence, status and Do Not Disturb, on connect and after every change. */ |
| 238 | | { type: "me"; me: OwnPresence } |
| 239 | /** What changed in repositories you are watching the pages of (`watchRepo`). */ |
| 240 | | { type: "repo"; changes: RepoChange[] }; |
| 241 | |
| 242 | /** |
| 243 | * What a tab sends over the feed socket: plain `ping` every 25 s (answered |
| 244 | * without waking the feed), and a state frame whenever it gains or loses |
| 245 | * focus, moves to another page, or goes idle (no input for a while) or |
| 246 | * back, and the inbox count the page last read. |
| 247 | */ |
| 248 | export type FeedClientFrame = |
| 249 | | { type: "state"; focused: boolean; path: string; idle?: boolean } |
| 250 | | { type: "inbox"; unread: number }; |
| 251 | |
| 252 | /** |
| 253 | * One delivery from chat: counts to move for one person in one |
| 254 | * conversation, and maybe a notification. `set` replaces the counts (after |
| 255 | * reading, or writing); otherwise they are added. |
| 256 | */ |
| 257 | export type FeedDelivery = { |
| 258 | user_id: string; |
| 259 | workspace: string; |
| 260 | counts?: { |
| 261 | channel_id: string; |
| 262 | unread: number; |
| 263 | mentions: number; |
| 264 | muted?: boolean | null; |
| 265 | set?: boolean; |
| 266 | } | null; |
| 267 | notification?: FeedNotification | null; |
| 268 | }; |
| 269 | |
| 270 | /** What the site hands the feed with a socket: who, and the counts read from chat and the inbox just now. */ |
| 271 | export type FeedSeed = { |
| 272 | workspace: string | null; |
| 273 | per_channel: ChannelCounts[] | null; |
| 274 | inbox_unread: number | null; |
| 275 | /** Every workspace the person belongs to, by slug: whose rooms hear of their presence. */ |
| 276 | workspaces?: string[] | null; |
| 277 | }; |
| 278 | |
| 279 | /** Headers the site sets on a forwarded feed socket. */ |
| 280 | export const NOTIFY_VIEWER_HEADER = "x-g1t-notify-viewer"; |
| 281 | export const NOTIFY_SEED_HEADER = "x-g1t-notify-seed"; |
| 282 | |
| 283 | export type NotifyStatus = { |
| 284 | preferences: NotifyPreferences; |
| 285 | /** How many browsers get pushes. */ |
| 286 | subscriptions: number; |
| 287 | /** How many phones the g1t app pushes to (absent from a service older than them). */ |
| 288 | devices?: number; |
| 289 | /** Whether this browser's endpoint is one of them, when it was asked about. */ |
| 290 | subscribed: boolean; |
| 291 | /** The public key a browser subscribes with; null when push is not set up. */ |
| 292 | vapid_public_key: string | null; |
| 293 | }; |
| 294 | |
| 295 | export type NotifyApi = { |
| 296 | /** Tells a person: their open tabs at once, and a push when none is in front of them. */ |
| 297 | notify(target: { user_id?: string; username?: string }, notification: FeedNotification): Promise<{ ok: boolean }>; |
| 298 | /** Many at once, as chat sends them for a message. */ |
| 299 | deliver(items: FeedDelivery[]): Promise<{ ok: boolean }>; |
| 300 | subscribe(user: User, subscription: PushSubscriptionJson, userAgent?: string | null): Promise<{ ok: boolean }>; |
| 301 | unsubscribe(user: User, endpoint: string): Promise<{ ok: boolean }>; |
| 302 | /** A phone the app runs on gets pushes too; the newest 10 are kept. `ok` is false for a token that is not Expo's. */ |
| 303 | /** `off`: this g1t sends phones nothing (PHONE_PUSH=off). */ |
| 304 | registerDevice(user: User, device: PushDevice): Promise<{ ok: boolean; off?: boolean }>; |
| 305 | /** That phone stops getting them: the app signed out. */ |
| 306 | unregisterDevice(user: User, token: string): Promise<{ ok: boolean }>; |
| 307 | status(user: User, endpoint?: string | null): Promise<NotifyStatus>; |
| 308 | setPreferences(user: User, preferences: NotifyPreferencesChange): Promise<NotifyPreferences>; |
| 309 | /** Sends the person a test notification, toasted and pushed whatever their focus. */ |
| 310 | test(user: User): Promise<{ ok: boolean; pushed: number }>; |
| 311 | /** Your own presence, status and Do Not Disturb. */ |
| 312 | presence(user: User): Promise<OwnPresence>; |
| 313 | /** |
| 314 | * Changes your own, and tells everyone who shares a workspace with you. |
| 315 | * Integrations set a status for someone the same way, with their own |
| 316 | * `source`; one the person set by hand is kept over theirs. |
| 317 | */ |
| 318 | setPresence(user: Pick<User, "id" | "username">, change: PresenceChange): Promise<OwnPresence>; |
| 319 | /** |
| 320 | * For services: how a workspace's people show now (`userIds` narrows it). |
| 321 | * Someone the room has never heard from is not listed: they are offline. |
| 322 | */ |
| 323 | workspacePresence(workspace: string, userIds?: string[] | null): Promise<PresenceEntry[]>; |
| 324 | /** |
| 325 | * When the person was last on the workspace's Home page (RFC 3339), or |
| 326 | * null when they never were. Kept with them, so it is the same on every |
| 327 | * device. |
| 328 | */ |
| 329 | lastVisit(user: Pick<User, "id">, workspace: string): Promise<{ seen_at: string | null }>; |
| 330 | /** |
| 331 | * Marks that visit at `at` (RFC 3339): Home sends the time the page |
| 332 | * loaded, once the person has looked at it. It only moves forward, never |
| 333 | * past now nor more than a day behind it. |
| 334 | */ |
| 335 | markVisit(user: Pick<User, "id">, workspace: string, at: string): Promise<{ seen_at: string | null }>; |
| 336 | /** |
| 337 | * The person's tabs hear what changes in the repository, for |
| 338 | * `REPO_WATCH_MS`. The caller must have checked they may read it: notify |
| 339 | * checks nothing. `repo` is its `owner/name`, passed on with each change. |
| 340 | */ |
| 341 | watchRepo(user: Pick<User, "id">, repoId: string, repo: string): Promise<{ ok: boolean; until: string | null }>; |
| 342 | /** For services: what changed in repositories (`crates/contracts/src/live.rs`), told to whoever watches each. */ |
| 343 | repoChanged(changes: RepoChange[]): Promise<{ ok: boolean }>; |
| 344 | }; |
| 345 | |
| 346 | async function rpc<T>(service: ServiceBinding, method: string, args: object): Promise<T> { |
| 347 | const response = await service.fetch(`https://service/rpc/${method}`, { |
| 348 | method: "POST", |
| 349 | headers: { "content-type": "application/json" }, |
| 350 | body: JSON.stringify(args), |
| 351 | }); |
| 352 | if (!response.ok) throw new Error(`${method} failed with status ${response.status}`); |
| 353 | return (await response.json()) as T; |
| 354 | } |
| 355 | |
| 356 | export function notifyClient(service: ServiceBinding): NotifyApi { |
| 357 | const call = <T>(method: string, args: object) => rpc<T>(service, method, args); |
| 358 | return { |
| 359 | notify: (target, notification) => call("notify", { user_id: target.user_id ?? null, username: target.username ?? null, notification }), |
| 360 | deliver: (items) => call("deliver", { items }), |
| 361 | subscribe: (user, subscription, userAgent) => call("subscribe", { user_id: user.id, subscription, user_agent: userAgent ?? null }), |
| 362 | unsubscribe: (user, endpoint) => call("unsubscribe", { user_id: user.id, endpoint }), |
| 363 | registerDevice: (user, device) => call("register_device", { user_id: user.id, device }), |
| 364 | unregisterDevice: (user, token) => call("unregister_device", { user_id: user.id, token }), |
| 365 | status: (user, endpoint) => call("status", { user_id: user.id, endpoint: endpoint ?? null }), |
| 366 | setPreferences: (user, preferences) => call("set_preferences", { user_id: user.id, preferences }), |
| 367 | test: (user) => call("test", { user_id: user.id, username: user.username }), |
| 368 | presence: (user) => call("presence", { user_id: user.id, username: user.username }), |
| 369 | setPresence: (user, change) => call("set_presence", { user_id: user.id, username: user.username, change }), |
| 370 | workspacePresence: (workspace, userIds) => call("workspace_presence", { workspace, user_ids: userIds ?? null }), |
| 371 | lastVisit: (user, workspace) => call("last_visit", { user_id: user.id, workspace }), |
| 372 | markVisit: (user, workspace, at) => call("mark_visit", { user_id: user.id, workspace, at }), |
| 373 | watchRepo: (user, repoId, repo) => call("watch_repo", { user_id: user.id, repo_id: repoId, repo }), |
| 374 | repoChanged: (changes) => call("repo_changed", { changes }), |
| 375 | }; |
| 376 | } |