From f2ef8922ce547324d23475660231ff1f3ca3c731 Mon Sep 17 00:00:00 2001 From: maaz519 Date: Thu, 9 Jul 2026 18:59:02 +0530 Subject: [PATCH] chore: remove notifications planning docs (dropping the superpowers workflow) Co-Authored-By: Claude Opus 4.8 (1M context) --- .../plans/2026-07-09-notifications.md | 905 ------------------ .../specs/2026-07-09-notifications-design.md | 156 --- 2 files changed, 1061 deletions(-) delete mode 100644 docs/superpowers/plans/2026-07-09-notifications.md delete mode 100644 docs/superpowers/specs/2026-07-09-notifications-design.md diff --git a/docs/superpowers/plans/2026-07-09-notifications.md b/docs/superpowers/plans/2026-07-09-notifications.md deleted file mode 100644 index e5363ca..0000000 --- a/docs/superpowers/plans/2026-07-09-notifications.md +++ /dev/null @@ -1,905 +0,0 @@ -# Notifications Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Deliver push/desktop notifications when a user isn't looking at a conversation — including when the app is closed (Web Push) — with the engine in IIOS and the experience in the host app. - -**Architecture:** A `NotificationProjector` in IIOS reacts to `message.sent` events and runs three gates — **policy** (DM always; group only on @mention or reply-to-you), **presence** (skip if the recipient is focused on that thread), **mute** (skip if muted) — then dispatches via a swappable `NotificationPort` (Web Push/VAPID adapter). Presence comes from an explicit `focus_thread` socket signal (room membership ≠ viewing, because the sidebar joins every thread). The host app registers a push subscription + a service worker and renders/handles taps. - -**Tech Stack:** NestJS · Prisma/Postgres · socket.io · `web-push` (VAPID) · Vite/React · Browser Push API + Service Worker. - -**Spec:** `docs/superpowers/specs/2026-07-09-notifications-design.md` - ---- - -## File structure - -**iios (engine):** -- `packages/iios-service/prisma/schema.prisma` — MODIFY: `IiosNotificationSubscription` model + `muted` on `IiosThreadParticipant`. -- `packages/iios-service/src/notifications/presence.service.ts` — CREATE: in-memory focus tracker. -- `packages/iios-service/src/notifications/notification.port.ts` — CREATE: `NotificationPort` interface + DI token. -- `packages/iios-service/src/notifications/web-push.delivery.ts` — CREATE: VAPID adapter. -- `packages/iios-service/src/notifications/notification.projector.ts` — CREATE: the three gates + dispatch + prune. -- `packages/iios-service/src/notifications/notification.controller.ts` — CREATE: vapid key + subscribe/unsubscribe. -- `packages/iios-service/src/notifications/notification.module.ts` — CREATE: wiring. -- `packages/iios-service/src/messaging/message.gateway.ts` — MODIFY: `focus_thread` handler + `OnGatewayDisconnect`. -- `packages/iios-service/src/threads/threads.controller.ts` — MODIFY: `POST /v1/threads/:id/mute|unmute`. -- `packages/iios-service/src/messaging/message.service.ts` — MODIFY: `muteThread(threadId, principal, muted)`. -- `packages/iios-service/src/app.module.ts` — MODIFY: import `NotificationModule`. -- Test specs co-located: `presence.service.spec.ts`, `web-push.delivery.spec.ts`, `notification.projector.spec.ts`. - -**chat-web (experience):** -- `src/lib/notifications.ts` — CREATE: `registerPush`, `mute`, tab-title + desktop-notify helpers. -- `public/sw.js` — CREATE: service worker (`push` + `notificationclick`). -- `src/messages/provider.tsx` / `src/components/Conversation.tsx` / `src/components/Sidebar.tsx` — MODIFY: emit `focus_thread`, mute toggle, enable-notifications prompt. - ---- - -# PHASE 1 — Frontend quick win (chat-web, no backend) - -Desktop notification while the tab is unfocused + tab-title unread count, presence-gated client-side. Immediately demoable; no IIOS change. - -### Task 1: Desktop notification + tab-title unread (chat-web) - -**Files:** -- Create: `chat-web/src/lib/notifications.ts` -- Create: `chat-web/src/lib/notifications.test.ts` -- Modify: `chat-web/src/components/AppShell.tsx` (drive the title from unread), `chat-web/src/messages/provider.tsx` (fire a desktop notification on incoming message when hidden) - -- [ ] **Step 1: Write the failing test** for the pure title helper. - -`chat-web/src/lib/notifications.test.ts`: -```ts -import { describe, it, expect } from 'vitest'; -import { tabTitle } from './notifications'; - -describe('tabTitle', () => { - it('shows a count prefix when there are unread messages', () => { - expect(tabTitle(0)).toBe('Chat'); - expect(tabTitle(3)).toBe('(3) Chat'); - expect(tabTitle(150)).toBe('(99+) Chat'); - }); -}); -``` -> chat-web has no test runner yet. Add one: `pnpm add -D vitest` and a `"test": "vitest run"` script in `chat-web/package.json`. If the team prefers no test dep, keep `notifications.ts` pure and verify `tabTitle` via a scratch `node -e` instead — but prefer vitest. - -- [ ] **Step 2: Run it, expect FAIL.** `cd chat-web && pnpm test` → FAIL (`tabTitle` not exported). - -- [ ] **Step 3: Implement `notifications.ts`** (pure helpers + browser wiring): -```ts -// chat-web/src/lib/notifications.ts -export function tabTitle(unread: number): string { - if (unread <= 0) return 'Chat'; - return `(${unread > 99 ? '99+' : unread}) Chat`; -} - -/** Ask once; returns true if we may show desktop notifications. */ -export async function ensureNotifyPermission(): Promise { - if (!('Notification' in window)) return false; - if (Notification.permission === 'granted') return true; - if (Notification.permission === 'denied') return false; - return (await Notification.requestPermission()) === 'granted'; -} - -/** Show a desktop notification (Phase 1 — tab open but unfocused). */ -export function desktopNotify(title: string, body: string, onClick?: () => void): void { - if (!('Notification' in window) || Notification.permission !== 'granted') return; - const n = new Notification(title, { body, tag: title }); - if (onClick) n.onclick = () => { window.focus(); onClick(); n.close(); }; -} -``` - -- [ ] **Step 4: Run it, expect PASS.** `cd chat-web && pnpm test` → PASS. - -- [ ] **Step 5: Wire the tab title** in `AppShell.tsx`'s `Shell` component (it already has `conversations`): -```tsx -import { useEffect } from 'react'; -import { tabTitle } from '../lib/notifications'; -// inside Shell(), after `const conversations = ...`: -const unreadTotal = (conversations.data ?? []).reduce((n, c) => n + (c.unread ?? 0), 0); -useEffect(() => { document.title = tabTitle(unreadTotal); }, [unreadTotal]); -``` - -- [ ] **Step 6: Fire a desktop notification on incoming message when the tab is hidden and not viewing that thread.** In `provider.tsx`'s `useMessages`, the `message` handler already appends. Presence-gating here is at the *conversation* level, but a global hook is cleaner. Add to `AppShell.tsx`'s `Shell` a global listener via the socket: -```tsx -import { useSocket } from '../messages/provider'; -import { desktopNotify, ensureNotifyPermission } from '../lib/notifications'; -import { useNavigate, useParams } from '@tanstack/react-router'; -// inside Shell(): -const socket = useSocket(); -const navigate = useNavigate(); -const activeThreadId = (useParams({ strict: false }) as { threadId?: string }).threadId ?? null; -useEffect(() => { void ensureNotifyPermission(); }, []); -useEffect(() => { - const off = socket.on('message', (m) => { - const mine = m.senderId === session.userId; - const viewing = m.threadId === activeThreadId && !document.hidden; - if (mine || viewing) return; // presence gate (client-side) - desktopNotify(m.senderName, m.content || 'sent an attachment', - () => void navigate({ to: '/t/$threadId', params: { threadId: m.threadId } })); - }); - return off; -}, [socket, activeThreadId, session.userId, navigate]); -``` - -- [ ] **Step 7: Manual verify.** Two browser profiles; focus window A on a different conversation (or minimize) → send from B → a desktop notification appears and the tab title shows `(1) Chat`; click it → opens the thread. Sending in the conversation you're viewing → **no** notification. - -- [ ] **Step 8: Commit.** -```bash -cd chat-web && git add -A && git -c user.email=maaz@insigniaconsultancy.com commit -m "feat: desktop notifications + tab-title unread (presence-gated)" -``` - ---- - -# PHASE 2 — IIOS notification engine (TDD) - -### Task 2: Schema — subscription table + per-thread mute - -**Files:** -- Modify: `packages/iios-service/prisma/schema.prisma` - -- [ ] **Step 1: Add the model + column.** In `schema.prisma`, add to `IiosThreadParticipant` (before its `@@id`): -```prisma - muted Boolean @default(false) -``` -Add a new model and a relation on `IiosScope`: -```prisma -model IiosNotificationSubscription { - id String @id @default(cuid()) - scopeId String - scope IiosScope @relation(fields: [scopeId], references: [id], onDelete: Cascade) - actorId String - actor IiosActorRef @relation(fields: [actorId], references: [id]) - kind String @default("webpush") - endpoint String @unique - p256dh String - auth String - userAgent String? - createdAt DateTime @default(now()) - lastSeenAt DateTime @default(now()) - - @@index([actorId]) -} -``` -Add `notificationSubscriptions IiosNotificationSubscription[]` to the `IiosScope` model's relation list and `notificationSubscriptions IiosNotificationSubscription[]` to `IiosActorRef`. - -- [ ] **Step 2: Generate the migration + client** (additive; no data loss): -```bash -cd iios && DATABASE_URL='postgresql://iios:iios@localhost:5434/iios?schema=public' \ - pnpm --filter @insignia/iios-service exec prisma migrate dev --name add_notifications -``` -Expected: migration `*_add_notifications` applied; Prisma client regenerated. - -- [ ] **Step 3: Commit.** -```bash -cd iios && git add -A && git -c user.email=maaz@insigniaconsultancy.com commit -m "feat(iios): notification subscription table + per-thread mute" -``` - -### Task 3: PresenceService + gateway focus signal - -**Files:** -- Create: `packages/iios-service/src/notifications/presence.service.ts` -- Create: `packages/iios-service/src/notifications/presence.service.spec.ts` -- Modify: `packages/iios-service/src/messaging/message.gateway.ts` - -- [ ] **Step 1: Write the failing test.** `presence.service.spec.ts`: -```ts -import { describe, it, expect } from 'vitest'; -import { PresenceService } from './presence.service'; - -describe('PresenceService', () => { - it('reports viewing only for the focused thread, and clears on disconnect', () => { - const p = new PresenceService(); - expect(p.isViewing('alice', 'T1')).toBe(false); - p.setFocus('sock1', 'alice', 'T1'); - expect(p.isViewing('alice', 'T1')).toBe(true); - expect(p.isViewing('alice', 'T2')).toBe(false); // joined-elsewhere ≠ viewing - p.setFocus('sock1', 'alice', 'T2'); // moved focus - expect(p.isViewing('alice', 'T1')).toBe(false); - expect(p.isViewing('alice', 'T2')).toBe(true); - p.clearSocket('sock1'); - expect(p.isViewing('alice', 'T2')).toBe(false); - }); - it('any of the actor’s sockets counts as viewing', () => { - const p = new PresenceService(); - p.setFocus('sockA', 'bob', 'T9'); - p.setFocus('sockB', 'bob', null); // a second tab, no focus - expect(p.isViewing('bob', 'T9')).toBe(true); - }); -}); -``` - -- [ ] **Step 2: Run it, expect FAIL.** `cd iios && pnpm vitest run src/notifications/presence.service.spec.ts` → FAIL. - -- [ ] **Step 3: Implement `presence.service.ts`:** -```ts -import { Injectable } from '@nestjs/common'; - -/** In-memory focus tracker (single instance). Keyed on userId (the stable externalId, - * which the gateway has as principal.userId). Prod: back with Redis for multi-replica. */ -@Injectable() -export class PresenceService { - private readonly focus = new Map(); // socketId → focus - - setFocus(socketId: string, userId: string, threadId: string | null): void { - this.focus.set(socketId, { userId, threadId }); - } - clearSocket(socketId: string): void { - this.focus.delete(socketId); - } - isViewing(userId: string, threadId: string): boolean { - for (const f of this.focus.values()) if (f.userId === userId && f.threadId === threadId) return true; - return false; - } -} -``` - -- [ ] **Step 4: Run it, expect PASS.** - -- [ ] **Step 5: Wire the gateway.** In `message.gateway.ts`: add `OnGatewayDisconnect` to the imports and `implements`, inject `PresenceService`, and add handlers. Presence keys on `principal.userId` (the stable externalId) — which the projector already computes per participant, so the two sides match. Gateway additions: -```ts -// imports: add OnGatewayDisconnect -// class: implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect -constructor(/* …existing… */ private readonly presence: PresenceService) {} - -handleDisconnect(client: Socket): void { - this.presence.clearSocket(client.id); -} - -@SubscribeMessage('focus_thread') -focusThread(@ConnectedSocket() client: Socket, @MessageBody() body: { threadId: string | null }): void { - const { principal } = client.data as SocketState; - this.presence.setFocus(client.id, principal.userId, body?.threadId ?? null); -} -``` - `MessageGateway` must be able to inject `PresenceService` → it will be provided by `NotificationModule` and imported into `MessageModule`, OR provide `PresenceService` in a shared module. Simplest: create `NotificationModule` (Task 7) that `exports: [PresenceService]` and have `MessageModule` import it. (Do this wiring in Task 7; until then the gateway won't compile — so implement Task 3's gateway edit and Task 7's module together, or stub the provider in `MessageModule` now and move it in Task 7.) **Chosen:** provide `PresenceService` in `MessageModule` now (`providers: [PresenceService], exports: [PresenceService]`), and `NotificationModule` imports `MessageModule` to reuse it. - -- [ ] **Step 6: Run the messaging tests** to ensure the gateway still wires: `cd iios && pnpm vitest run src/messaging` → PASS. - -- [ ] **Step 7: Commit.** -```bash -cd iios && git add -A && git -c user.email=maaz@insigniaconsultancy.com commit -m "feat(iios): PresenceService + focus_thread signal (viewing != room membership)" -``` - -### Task 4: NotificationPort + Web Push adapter - -**Files:** -- Create: `packages/iios-service/src/notifications/notification.port.ts` -- Create: `packages/iios-service/src/notifications/web-push.delivery.ts` -- Create: `packages/iios-service/src/notifications/web-push.delivery.spec.ts` -- Add dep: `web-push` - -- [ ] **Step 1: Add the dependency + VAPID keys.** -```bash -cd iios && pnpm --filter @insignia/iios-service add web-push && pnpm --filter @insignia/iios-service add -D @types/web-push -cd packages/iios-service && node -e "console.log(require('web-push').generateVAPIDKeys())" -``` -Put the printed `publicKey`/`privateKey` into env as `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY`, and set `VAPID_SUBJECT=mailto:dev@insignia`. - -- [ ] **Step 2: Write the failing test** (mock the transport). `web-push.delivery.spec.ts`: -```ts -import { describe, it, expect, vi } from 'vitest'; -import { WebPushDelivery } from './web-push.delivery'; - -const sub = { endpoint: 'https://push/x', p256dh: 'k', auth: 'a' }; -const payload = { title: 'Bob', body: 'hi', data: { threadId: 'T1' } }; - -describe('WebPushDelivery', () => { - it('returns "sent" on success', async () => { - const send = vi.fn().mockResolvedValue({ statusCode: 201 }); - const d = new WebPushDelivery({ publicKey: 'p', privateKey: 'k', subject: 'mailto:x' }, send as never); - expect(await d.deliver(sub, payload)).toBe('sent'); - expect(send).toHaveBeenCalledOnce(); - }); - it('returns "gone" on 404/410 so the caller prunes', async () => { - const send = vi.fn().mockRejectedValue({ statusCode: 410 }); - const d = new WebPushDelivery({ publicKey: 'p', privateKey: 'k', subject: 'mailto:x' }, send as never); - expect(await d.deliver(sub, payload)).toBe('gone'); - }); - it('returns "failed" on other errors', async () => { - const send = vi.fn().mockRejectedValue({ statusCode: 500 }); - const d = new WebPushDelivery({ publicKey: 'p', privateKey: 'k', subject: 'mailto:x' }, send as never); - expect(await d.deliver(sub, payload)).toBe('failed'); - }); -}); -``` - -- [ ] **Step 3: Run it, expect FAIL.** - -- [ ] **Step 4: Implement the port + adapter.** -`notification.port.ts`: -```ts -export interface PushSub { endpoint: string; p256dh: string; auth: string } -export interface NotificationPayload { title: string; body: string; data: { threadId: string; interactionId?: string } } -export interface NotificationPort { - deliver(sub: PushSub, payload: NotificationPayload): Promise<'sent' | 'gone' | 'failed'>; -} -export const NOTIFICATION_PORT = Symbol('NOTIFICATION_PORT'); -``` -`web-push.delivery.ts`: -```ts -import { Injectable } from '@nestjs/common'; -import webpush from 'web-push'; -import type { NotificationPort, NotificationPayload, PushSub } from './notification.port'; - -type SendFn = typeof webpush.sendNotification; -interface Vapid { publicKey: string; privateKey: string; subject: string } - -@Injectable() -export class WebPushDelivery implements NotificationPort { - private readonly vapid?: Vapid; - constructor(vapid?: Vapid, private readonly send: SendFn = webpush.sendNotification) { - this.vapid = vapid?.publicKey ? vapid : undefined; - if (this.vapid) webpush.setVapidDetails(this.vapid.subject, this.vapid.publicKey, this.vapid.privateKey); - } - async deliver(sub: PushSub, payload: NotificationPayload): Promise<'sent' | 'gone' | 'failed'> { - if (!this.vapid) return 'failed'; // push disabled (no keys) - try { - await this.send({ endpoint: sub.endpoint, keys: { p256dh: sub.p256dh, auth: sub.auth } }, JSON.stringify(payload)); - return 'sent'; - } catch (e) { - const code = (e as { statusCode?: number }).statusCode; - return code === 404 || code === 410 ? 'gone' : 'failed'; - } - } -} -``` - -- [ ] **Step 5: Run it, expect PASS.** - -- [ ] **Step 6: Commit.** -```bash -cd iios && git add -A && git -c user.email=maaz@insigniaconsultancy.com commit -m "feat(iios): NotificationPort + Web Push (VAPID) delivery adapter" -``` - -### Task 5: NotificationProjector (the three gates) - -**Files:** -- Create: `packages/iios-service/src/notifications/notification.projector.ts` -- Create: `packages/iios-service/src/notifications/notification.projector.spec.ts` - -- [ ] **Step 1: Write the failing test.** `notification.projector.spec.ts` (mirrors `inbox.spec.ts` setup — real DB, `ms()` = MessageService, a fake `NotificationPort` capturing calls, a `PresenceService`): -```ts -import { describe, it, expect, beforeAll, afterAll, beforeEach, vi } from 'vitest'; -import { PrismaClient } from '@prisma/client'; -import { IIOS_EVENTS, type CloudEvent } from '@insignia/iios-contracts'; -import { makeFakePorts } from '@insignia/iios-testkit'; -import { resetDb } from '../test-utils/reset-db'; -import { MessageService, type MessagePrincipal } from '../messaging/message.service'; -import { ActorResolver } from '../identity/actor.resolver'; -import { OutboxBus } from '../outbox/outbox.bus'; -import { DlqService } from '../outbox/dlq.service'; -import { ProjectionCursorService } from '../projection/projection-cursor.service'; -import { PresenceService } from './presence.service'; -import { NotificationProjector } from './notification.projector'; -import type { PrismaService } from '../prisma/prisma.service'; - -const url = process.env.DATABASE_URL ?? 'postgresql://iios:iios@localhost:5434/iios?schema=public'; -const prisma = new PrismaClient({ datasources: { db: { url } } }); -const asService = prisma as unknown as PrismaService; -const actors = new ActorResolver(asService); -const ms = () => new MessageService(asService, makeFakePorts(), actors); -const alice: MessagePrincipal = { userId: 'alice', orgId: 'org_demo', appId: 'portal-demo', displayName: 'Alice' }; -const bob: MessagePrincipal = { userId: 'bob', orgId: 'org_demo', appId: 'portal-demo', displayName: 'Bob' }; - -function sub(actorId: string) { - return { scopeId: '', actorId, kind: 'webpush', endpoint: `https://push/${actorId}`, p256dh: 'k', auth: 'a' }; -} -async function seedSub(userId: string) { - const handle = await prisma.iiosSourceHandle.findFirstOrThrow({ where: { externalId: userId } }); - const actor = await prisma.iiosActorRef.findFirstOrThrow({ where: { sourceHandleId: handle.id } }); - const scope = await prisma.iiosScope.findFirstOrThrow(); - await prisma.iiosNotificationSubscription.create({ data: { ...sub(actor.id), scopeId: scope.id } }); - return actor.id; -} -async function eventsOf(type: string) { - const rows = await prisma.iiosOutboxEvent.findMany({ where: { eventType: type }, orderBy: { createdAt: 'asc' } }); - return rows.map((r) => r.cloudEvent as unknown as CloudEvent); -} - -beforeAll(async () => { await prisma.$connect(); }); -afterAll(async () => { await prisma.$disconnect(); }); -beforeEach(async () => { await resetDb(prisma); }); - -function makeProjector(presence = new PresenceService()) { - const deliver = vi.fn().mockResolvedValue('sent'); - const port = { deliver }; - const proj = new NotificationProjector(asService, new OutboxBus(), new DlqService(asService), new ProjectionCursorService(asService), presence, port as never); - return { proj, deliver, presence }; -} - -describe('NotificationProjector', () => { - it('DM: notifies the recipient (absent), never the sender', async () => { - const m = ms(); - const { threadId } = await m.openThread(null, alice, { membership: 'dm' }); - await m.addParticipant(threadId, alice, 'bob'); - await seedSub('bob'); - await m.send(threadId, alice, { content: 'hi bob' }, 'k1'); - - const { proj, deliver } = makeProjector(); - await proj.onMessageSent((await eventsOf(IIOS_EVENTS.messageSent))[0]!); - expect(deliver).toHaveBeenCalledOnce(); - expect(deliver.mock.calls[0][0].endpoint).toContain('push/'); // bob's sub - }); - - it('group without a mention: does NOT notify', async () => { - const m = ms(); - const { threadId } = await m.openThread(null, alice, { membership: 'group', creatorRole: 'ADMIN' }); - await m.addParticipant(threadId, alice, 'bob'); - await seedSub('bob'); - await m.send(threadId, alice, { content: 'hello all' }, 'k1'); - const { proj, deliver } = makeProjector(); - await proj.onMessageSent((await eventsOf(IIOS_EVENTS.messageSent))[0]!); - expect(deliver).not.toHaveBeenCalled(); - }); - - it('group WITH a mention: notifies the mentioned member', async () => { - const m = ms(); - const { threadId } = await m.openThread(null, alice, { membership: 'group', creatorRole: 'ADMIN' }); - await m.addParticipant(threadId, alice, 'bob'); - await seedSub('bob'); - await m.send(threadId, alice, { content: 'hey @bob' }, 'k1', undefined, undefined, ['bob']); - const { proj, deliver } = makeProjector(); - await proj.onMessageSent((await eventsOf(IIOS_EVENTS.messageSent))[0]!); - expect(deliver).toHaveBeenCalledOnce(); - }); - - it('presence gate: a recipient viewing the thread is NOT notified', async () => { - const m = ms(); - const { threadId } = await m.openThread(null, alice, { membership: 'dm' }); - await m.addParticipant(threadId, alice, 'bob'); - await seedSub('bob'); - await m.send(threadId, alice, { content: 'hi' }, 'k1'); - const presence = new PresenceService(); - presence.setFocus('sockB', 'bob', threadId); // bob is looking - const { proj, deliver } = makeProjector(presence); - await proj.onMessageSent((await eventsOf(IIOS_EVENTS.messageSent))[0]!); - expect(deliver).not.toHaveBeenCalled(); - }); - - it('mute gate: a muted recipient is NOT notified', async () => { - const m = ms(); - const { threadId } = await m.openThread(null, alice, { membership: 'dm' }); - await m.addParticipant(threadId, alice, 'bob'); - const bobActorId = await seedSub('bob'); - await prisma.iiosThreadParticipant.update({ where: { threadId_actorId: { threadId, actorId: bobActorId } }, data: { muted: true } }); - await m.send(threadId, alice, { content: 'hi' }, 'k1'); - const { proj, deliver } = makeProjector(); - await proj.onMessageSent((await eventsOf(IIOS_EVENTS.messageSent))[0]!); - expect(deliver).not.toHaveBeenCalled(); - }); - - it('prunes a subscription that returns "gone"', async () => { - const m = ms(); - const { threadId } = await m.openThread(null, alice, { membership: 'dm' }); - await m.addParticipant(threadId, alice, 'bob'); - await seedSub('bob'); - await m.send(threadId, alice, { content: 'hi' }, 'k1'); - const deliver = vi.fn().mockResolvedValue('gone'); - const proj = new NotificationProjector(asService, new OutboxBus(), new DlqService(asService), new ProjectionCursorService(asService), new PresenceService(), { deliver } as never); - await proj.onMessageSent((await eventsOf(IIOS_EVENTS.messageSent))[0]!); - expect(await prisma.iiosNotificationSubscription.count()).toBe(0); - }); -}); -``` - -- [ ] **Step 2: Run it, expect FAIL** (`NotificationProjector` missing). - -- [ ] **Step 3: Implement `notification.projector.ts`** (model on `inbox.projector.ts`: `claim()` idempotency + `cursor.advance`): -```ts -import { Injectable, OnModuleInit, Inject } from '@nestjs/common'; -import { CloudEvent, IIOS_EVENTS } from '@insignia/iios-contracts'; -import { PrismaService } from '../prisma/prisma.service'; -import { OutboxBus } from '../outbox/outbox.bus'; -import { DlqService } from '../outbox/dlq.service'; -import { ProjectionCursorService } from '../projection/projection-cursor.service'; -import { PresenceService } from './presence.service'; -import { NOTIFICATION_PORT, type NotificationPort } from './notification.port'; - -interface MsgData { interactionId: string; threadId: string; senderActorId: string; mentions?: string[] } - -@Injectable() -export class NotificationProjector implements OnModuleInit { - private readonly consumer = 'notification-projector'; - constructor( - private readonly prisma: PrismaService, - private readonly bus: OutboxBus, - private readonly dlq: DlqService, - private readonly cursor: ProjectionCursorService, - private readonly presence: PresenceService, - @Inject(NOTIFICATION_PORT) private readonly port: NotificationPort, - ) {} - - onModuleInit(): void { - this.dlq.registerHandler(this.consumer, (e) => this.onMessageSent(e)); - this.bus.on(IIOS_EVENTS.messageSent, (p) => void this.onMessageSent(p as CloudEvent).catch((err) => this.dlq.onConsumerFailure(this.consumer, p as CloudEvent, err))); - } - - async onMessageSent(event: CloudEvent): Promise { - if (!(await this.claim(event.id))) return; - await this.apply(event); - await this.cursor.advance(this.consumer, event); - } - - private async apply(event: CloudEvent): Promise { - const data = event.data as MsgData; - const thread = await this.prisma.iiosThread.findUnique({ where: { id: data.threadId } }); - if (!thread) return; - const membership = (thread.metadata as { membership?: string } | null)?.membership; - const interaction = await this.prisma.iiosInteraction.findUnique({ - where: { id: data.interactionId }, - include: { parts: { where: { kind: 'TEXT' }, take: 1 }, actor: { include: { sourceHandle: true } } }, - }); - const senderName = interaction?.actor?.sourceHandle?.externalId ?? 'Someone'; - const body = interaction?.parts[0]?.bodyText ?? 'sent an attachment'; - const mentions = data.mentions ?? []; - // recipients = participants except the sender - const participants = await this.prisma.iiosThreadParticipant.findMany({ - where: { threadId: data.threadId }, - include: { actor: { include: { sourceHandle: true } } }, - }); - // parent author (for reply-to-you) — one lookup - let parentAuthorActorId: string | null = null; - if (interaction?.parentInteractionId) { - const parent = await this.prisma.iiosInteraction.findUnique({ where: { id: interaction.parentInteractionId }, select: { actorId: true } }); - parentAuthorActorId = parent?.actorId ?? null; - } - - for (const p of participants) { - if (p.actorId === data.senderActorId) continue; // never the sender - const userId = p.actor?.sourceHandle?.externalId; - // gate 1: policy - const mentioned = userId != null && mentions.includes(userId); - const repliedToMe = parentAuthorActorId != null && parentAuthorActorId === p.actorId; - const eligible = membership === 'dm' || mentioned || repliedToMe; - if (!eligible) continue; - // gate 2: presence - if (userId && this.presence.isViewing(userId, data.threadId)) continue; - // gate 3: mute - if (p.muted) continue; - // dispatch to every subscription - const subs = await this.prisma.iiosNotificationSubscription.findMany({ where: { actorId: p.actorId } }); - for (const s of subs) { - const result = await this.port.deliver( - { endpoint: s.endpoint, p256dh: s.p256dh, auth: s.auth }, - { title: senderName, body, data: { threadId: data.threadId, interactionId: data.interactionId } }, - ); - if (result === 'gone') await this.prisma.iiosNotificationSubscription.delete({ where: { id: s.id } }); - } - } - } - - private async claim(eventId: string): Promise { - const res = await this.prisma.iiosProcessedEvent.createMany({ data: [{ consumerName: this.consumer, eventId }], skipDuplicates: true }); - return res.count > 0; - } -} -``` -> Note: `interaction.parentInteractionId` must be selected — add `parentInteractionId: true` isn't needed since the default include returns scalar fields; confirm the `interaction` object exposes `parentInteractionId` (it does — it's a scalar column). - -- [ ] **Step 4: Run it, expect PASS** — all 6 tests. `cd iios && pnpm vitest run src/notifications/notification.projector.spec.ts`. - -- [ ] **Step 5: Generic-safety grep** — no chat literals in the engine: -```bash -cd iios && grep -rniE "'dm'|'group'" packages/iios-service/src/notifications && echo "LEAK" || echo "clean ✓" -``` -Expected: `clean ✓` (membership is read as an opaque value from `thread.metadata`, compared to the string `'dm'` — which is the *policy* reading an opaque attribute, same as DevOpaPort; that comparison is acceptable in the notification policy gate, but keep it out of kernel messaging). If the grep flags the `membership === 'dm'` line, that is the **policy gate** and is allowed here (this file is the notification *policy plane*, not the kernel) — document it with a comment. - -- [ ] **Step 6: Commit.** -```bash -cd iios && git add -A && git -c user.email=maaz@insigniaconsultancy.com commit -m "feat(iios): NotificationProjector — policy/presence/mute gates + prune" -``` - -### Task 6: Endpoints — subscribe/unsubscribe/vapid-key + mute - -**Files:** -- Create: `packages/iios-service/src/notifications/notification.controller.ts` -- Create: `packages/iios-service/src/notifications/notification.dto.ts` -- Modify: `packages/iios-service/src/messaging/message.service.ts` (add `muteThread`) -- Modify: `packages/iios-service/src/threads/threads.controller.ts` (mute routes) - -- [ ] **Step 1: DTOs.** `notification.dto.ts`: -```ts -import { IsIn, IsObject, IsOptional, IsString } from 'class-validator'; -export class SubscribeDto { - @IsOptional() @IsIn(['webpush']) kind?: string; - @IsString() endpoint!: string; - @IsObject() keys!: { p256dh: string; auth: string }; - @IsOptional() @IsString() userAgent?: string; -} -export class UnsubscribeDto { @IsString() endpoint!: string } -``` - -- [ ] **Step 2: Controller.** `notification.controller.ts`: -```ts -import { BadRequestException, Body, Controller, Delete, Get, Headers, Post } from '@nestjs/common'; -import { PrismaService } from '../prisma/prisma.service'; -import { ActorResolver, type MessagePrincipal } from '../identity/actor.resolver'; -import { SessionVerifier } from '../platform/session.verifier'; -import { SubscribeDto, UnsubscribeDto } from './notification.dto'; - -@Controller('v1/notifications') -export class NotificationController { - constructor( - private readonly prisma: PrismaService, - private readonly actors: ActorResolver, - private readonly session: SessionVerifier, - ) {} - - @Get('vapid-public-key') - vapidKey() { return { key: process.env.VAPID_PUBLIC_KEY ?? '' }; } - - @Post('subscribe') - async subscribe(@Body() body: SubscribeDto, @Headers('authorization') auth?: string) { - const principal = this.principal(auth); - const scope = await this.actors.resolveScope(principal); - const actor = await this.actors.resolveActor(scope.id, principal); - await this.prisma.iiosNotificationSubscription.upsert({ - where: { endpoint: body.endpoint }, - create: { scopeId: scope.id, actorId: actor.id, kind: body.kind ?? 'webpush', endpoint: body.endpoint, p256dh: body.keys.p256dh, auth: body.keys.auth, userAgent: body.userAgent }, - update: { actorId: actor.id, p256dh: body.keys.p256dh, auth: body.keys.auth, lastSeenAt: new Date() }, - }); - return { ok: true }; - } - - @Delete('subscribe') - async unsubscribe(@Body() body: UnsubscribeDto) { - await this.prisma.iiosNotificationSubscription.deleteMany({ where: { endpoint: body.endpoint } }); - return { ok: true }; - } - - private principal(auth?: string): MessagePrincipal { - const token = (auth ?? '').replace(/^Bearer\s+/i, ''); - if (!token) throw new BadRequestException('Authorization bearer token is required'); - return this.session.verify(token); - } -} -``` - -- [ ] **Step 3: `muteThread` in `message.service.ts`** (append a method): -```ts -async muteThread(threadId: string, principal: MessagePrincipal, muted: boolean): Promise<{ threadId: string; muted: boolean }> { - const thread = await this.prisma.iiosThread.findUnique({ where: { id: threadId } }); - if (!thread) throw new NotFoundException('thread not found'); - const actor = await this.actors.resolveActor(thread.scopeId, principal); - await this.prisma.iiosThreadParticipant.update({ - where: { threadId_actorId: { threadId, actorId: actor.id } }, - data: { muted }, - }); - return { threadId, muted }; -} -``` - -- [ ] **Step 4: Mute routes** in `threads.controller.ts`: -```ts -@Post(':id/mute') -async mute(@Param('id') id: string, @Headers('authorization') auth?: string) { - return this.messages.muteThread(id, this.principal(auth), true); -} -@Post(':id/unmute') -async unmute(@Param('id') id: string, @Headers('authorization') auth?: string) { - return this.messages.muteThread(id, this.principal(auth), false); -} -``` - -- [ ] **Step 5: Add a service test** for `muteThread`. Append to `messaging/message.spec.ts`: -```ts -it('muteThread toggles the caller’s per-thread mute flag', async () => { - const s = gov(); - const { threadId } = await s.openThread(null, alice, { membership: 'group', creatorRole: 'ADMIN' }); - await s.muteThread(threadId, alice, true); - const aliceActor = await actorIdFor('alice'); - expect((await prisma.iiosThreadParticipant.findUniqueOrThrow({ where: { threadId_actorId: { threadId, actorId: aliceActor } } })).muted).toBe(true); - await s.muteThread(threadId, alice, false); - expect((await prisma.iiosThreadParticipant.findUniqueOrThrow({ where: { threadId_actorId: { threadId, actorId: aliceActor } } })).muted).toBe(false); -}); -``` - -- [ ] **Step 6: Run it, expect PASS.** `cd iios && pnpm vitest run src/messaging/message.spec.ts`. - -- [ ] **Step 7: Commit.** -```bash -cd iios && git add -A && git -c user.email=maaz@insigniaconsultancy.com commit -m "feat(iios): notification subscribe/unsubscribe/vapid + thread mute endpoints" -``` - -### Task 7: Module wiring - -**Files:** -- Create: `packages/iios-service/src/notifications/notification.module.ts` -- Modify: `packages/iios-service/src/app.module.ts`, `packages/iios-service/src/messaging/message.module.ts` - -- [ ] **Step 1: `message.module.ts`** — provide + export `PresenceService`: -```ts -// add to providers: PresenceService ; add to exports: PresenceService -import { PresenceService } from '../notifications/presence.service'; -``` - -- [ ] **Step 2: `notification.module.ts`:** -```ts -import { Module } from '@nestjs/common'; -import { PrismaModule } from '../prisma/prisma.module'; -import { IdentityModule } from '../identity/identity.module'; -import { OutboxModule } from '../outbox/outbox.module'; -import { ProjectionModule } from '../projection/projection.module'; -import { MessageModule } from '../messaging/message.module'; -import { NotificationController } from './notification.controller'; -import { NotificationProjector } from './notification.projector'; -import { WebPushDelivery } from './web-push.delivery'; -import { NOTIFICATION_PORT } from './notification.port'; - -@Module({ - imports: [PrismaModule, IdentityModule, OutboxModule, ProjectionModule, MessageModule], - controllers: [NotificationController], - providers: [ - NotificationProjector, - { - provide: NOTIFICATION_PORT, - useFactory: () => new WebPushDelivery( - process.env.VAPID_PUBLIC_KEY - ? { publicKey: process.env.VAPID_PUBLIC_KEY, privateKey: process.env.VAPID_PRIVATE_KEY!, subject: process.env.VAPID_SUBJECT ?? 'mailto:dev@insignia' } - : undefined, - ), - }, - ], -}) -export class NotificationModule {} -``` -> `NotificationProjector` needs `PresenceService` — it comes from `MessageModule` (exported). `DlqService`/`OutboxBus` from `OutboxModule`; `ProjectionCursorService` from `ProjectionModule`; `ActorResolver`/`SessionVerifier` (controller) from `IdentityModule`. Confirm each is exported by its module; if not, add it to that module's `exports`. - -- [ ] **Step 3: `app.module.ts`** — add `NotificationModule` to `imports` (after `MediaModule`). - -- [ ] **Step 4: Build + full suite green.** -```bash -cd iios && pnpm --filter @insignia/iios-service exec nest build && \ - docker exec iios-db psql -U iios -d postgres -c "DROP DATABASE IF EXISTS iios_test WITH (FORCE)" && \ - pnpm test && pnpm boundary -``` -Expected: BUILD OK · all tests pass (prior 192 + new presence/webpush/projector/mute) · `import-boundary: OK`. - -- [ ] **Step 5: Commit.** -```bash -cd iios && git add -A && git -c user.email=maaz@insigniaconsultancy.com commit -m "feat(iios): wire NotificationModule (projector + port + presence)" -``` - ---- - -# PHASE 3 — SDK + app (Web Push experience) - -### Task 8: Service worker + push registration (chat-web SDK layer) - -**Files:** -- Create: `chat-web/public/sw.js` -- Modify: `chat-web/src/lib/notifications.ts` (add `registerPush`, `mute`, `unmute`) - -- [ ] **Step 1: Service worker** `chat-web/public/sw.js` (served at `/sw.js`, root scope): -```js -self.addEventListener('push', (event) => { - const p = (() => { try { return event.data.json(); } catch { return { title: 'New message', body: '', data: {} }; } })(); - event.waitUntil(self.registration.showNotification(p.title, { body: p.body, tag: p.data?.threadId, data: p.data })); -}); -self.addEventListener('notificationclick', (event) => { - event.notification.close(); - const threadId = event.notification.data?.threadId; - const url = threadId ? `/t/${threadId}` : '/'; - event.waitUntil((async () => { - const all = await self.clients.matchAll({ type: 'window', includeUncontrolled: true }); - const existing = all.find((c) => 'focus' in c); - if (existing) { await existing.focus(); existing.navigate(url); } else { await self.clients.openWindow(url); } - })()); -}); -``` - -- [ ] **Step 2: `registerPush` + mute** in `chat-web/src/lib/notifications.ts` (append). Uses `IIOS_URL` from `./api`: -```ts -import { IIOS_URL } from './api'; -const authed = (t: string) => ({ 'content-type': 'application/json', authorization: `Bearer ${t}` }); - -function urlBase64ToUint8Array(b64: string): Uint8Array { - const pad = '='.repeat((4 - (b64.length % 4)) % 4); - const raw = atob((b64 + pad).replace(/-/g, '+').replace(/_/g, '/')); - return Uint8Array.from([...raw].map((c) => c.charCodeAt(0))); -} - -export async function registerPush(token: string): Promise { - if (!('serviceWorker' in navigator) || !('PushManager' in window)) return false; - if (!(await ensureNotifyPermission())) return false; - const reg = await navigator.serviceWorker.register('/sw.js'); - const { key } = await (await fetch(`${IIOS_URL}/v1/notifications/vapid-public-key`, { headers: authed(token) })).json(); - if (!key) return false; - const sub = await reg.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: urlBase64ToUint8Array(key) }); - const j = sub.toJSON(); - await fetch(`${IIOS_URL}/v1/notifications/subscribe`, { - method: 'POST', headers: authed(token), - body: JSON.stringify({ kind: 'webpush', endpoint: j.endpoint, keys: j.keys, userAgent: navigator.userAgent }), - }); - return true; -} - -export async function muteThread(token: string, threadId: string, muted: boolean): Promise { - await fetch(`${IIOS_URL}/v1/threads/${threadId}/${muted ? 'mute' : 'unmute'}`, { method: 'POST', headers: authed(token) }); -} -``` - -- [ ] **Step 3: Build check.** `cd chat-web && pnpm build` → clean. - -- [ ] **Step 4: Commit.** -```bash -cd chat-web && git add -A && git -c user.email=maaz@insigniaconsultancy.com commit -m "feat: service worker + Web Push registration (registerPush, mute)" -``` - -### Task 9: App wiring — focus signal, enable prompt, mute toggle - -**Files:** -- Modify: `chat-web/src/messages/provider.tsx` (expose `focus`), `chat-web/src/lib/message-client.ts` (add `focus`) -- Modify: `chat-web/src/components/Conversation.tsx` (emit focus on mount/visibility + mute toggle in header) -- Modify: `chat-web/src/components/Sidebar.tsx` (an "Enable notifications" button) - -- [ ] **Step 1: `message-client.ts`** — add a focus emitter: -```ts -focus(threadId: string | null): void { this.socket.emit('focus_thread', { threadId }); } -``` - -- [ ] **Step 2: Emit focus from `Conversation.tsx`.** After the existing effects, add: -```tsx -import { useSocket } from '../messages/provider'; -// inside Conversation(): const socket = useSocket(); -useEffect(() => { - socket.focus(threadId); - const onVis = () => socket.focus(document.hidden ? null : threadId); - document.addEventListener('visibilitychange', onVis); - return () => { socket.focus(null); document.removeEventListener('visibilitychange', onVis); }; -}, [socket, threadId]); -``` - -- [ ] **Step 3: Mute toggle in the conversation header** (`Conversation.tsx`, in `.pane-head`, next to add-member). Track mute from the conversation list (`convo`) — add `muted?: boolean` to `ThreadSummary` and return it from `listThreads` (IIOS: include the caller's `participant.muted` in `listThreads`; small addition). Then: -```tsx -import { muteThread } from '../lib/notifications'; -// button: - -``` -> IIOS `listThreads` change: in the participant fetch, select `muted` for the caller's row and set `muted` on each `ThreadSummary`. Add to the `ThreadSummary` interface (`message.service.ts`) `muted?: boolean` and to chat-web `types.ts`. - -- [ ] **Step 4: "Enable notifications" button** in `Sidebar.tsx` header: -```tsx -import { registerPush } from '../lib/notifications'; - -``` - -- [ ] **Step 5: Build + manual verify.** `cd chat-web && pnpm build`. Then: user B clicks **Enable notifications** (grant permission) → **fully close** B's tab → user A sends B a DM → **OS notification appears** (Web Push, app closed) → click → opens the thread. Repeat while B is *viewing* the thread → no push. Mute the thread → no push. - -- [ ] **Step 6: Commit.** -```bash -cd chat-web && git add -A && git -c user.email=maaz@insigniaconsultancy.com commit -m "feat: focus signal, enable-notifications prompt, per-thread mute toggle" -``` - -### Task 10: End-to-end verification + docs - -**Files:** -- Create: `iios/packages/iios-service/scripts/smoke-notifications.mjs` -- Modify: `iios/docs/IIOS_API_AND_SDK_GUIDE.md` (add §5.11 Notifications) - -- [ ] **Step 1: Smoke script** driving the real service with a mock push endpoint. `smoke-notifications.mjs`: sign up two dev tokens (or Supabase), create a DM, POST a fake subscription for the recipient (endpoint = a local http server you stand up that records hits), send a message, run the relay tick, assert the local endpoint received one push; then set focus (emit `focus_thread`) and assert no push. Model it on `scripts/smoke-inbox.mjs`. - -- [ ] **Step 2: Run the smoke** against a running service (`VAPID_*` set) → prints `notifications smoke: PASS`. - -- [ ] **Step 3: Docs** — add §5.11 to the API guide: the four endpoints, the payload shape, and the presence/policy/mute gates + a one-line note that the projector reacts to `message.sent`. Add `VAPID_*` to the env table. - -- [ ] **Step 4: Commit.** -```bash -cd iios && git add -A && git -c user.email=maaz@insigniaconsultancy.com commit -m "test+docs(iios): notifications smoke + API guide §5.11" -``` - ---- - -## Verification (whole feature) - -- **iios:** `pnpm test` green (presence, web-push, projector×6, mute); `pnpm boundary`; generic-safety grep shows the only `'dm'` literal in `notifications/` is the documented policy gate. -- **Manual, three states:** (1) recipient absent → push; (2) recipient viewing the thread → no push; (3) muted → no push; DM always, group only on @mention/reply. -- **App-closed:** the Web Push path fires with the tab fully closed (the real test of the feature). - -## Notes / follow-ups (out of scope, per spec §12) - -Quiet hours · global mute · per-thread level · email/FCM adapters · rich/actionable notifications · digest/batching. Multi-replica presence needs a Redis-backed `PresenceService` (v1 is in-memory, single-instance). diff --git a/docs/superpowers/specs/2026-07-09-notifications-design.md b/docs/superpowers/specs/2026-07-09-notifications-design.md deleted file mode 100644 index 27bd9dd..0000000 --- a/docs/superpowers/specs/2026-07-09-notifications-design.md +++ /dev/null @@ -1,156 +0,0 @@ -# Notifications — Design Spec - -> Push/desktop notifications for the IIOS chat app (and, by reuse, any host app on IIOS). -> Engine in IIOS (generic, governed, reusable); experience in the host app. Spans two -> repos: **iios** (engine) and **chat-web** (SDK + app). - -**Status:** approved design (2026-07-09) · next step: implementation plan. - ---- - -## 1. Goal - -Deliver notifications to a user **when the conversation isn't in front of them** — including -when the app/tab is **closed** (Web Push) — without notifying them about the chat they're -actively viewing. Build the reusable **notification engine** in IIOS so every app on the -platform (chat, support SDK, …) inherits it. - -## 2. Locked decisions - -| Decision | Choice | -|---|---| -| **Scope** | The IIOS **engine + Web Push** (works when the app is closed), phased. | -| **Trigger policy** | **DMs always** push; **group** messages push **only on @mention** (or a reply to you). Otherwise: unread badge + inbox only. Never for the thread you're actively viewing. | -| **Preferences (v1)** | **Per-thread mute** only. A muted thread sends no push (badge still updates). Quiet hours / global mute / per-level are deferred. | -| **Delivery** | A swappable **NotificationPort**; the v1 adapter is **Web Push (VAPID)**. Email/FCM are later adapters. | -| **Ownership** | Engine (decide/deliver/store) = IIOS. Experience (render/tap/service-worker) = host app/SDK. | - -## 3. Architecture - -*Engine in IIOS, experience in the host app.* A notification is generic — "inform an actor -about an interaction" — so **no chat vocabulary enters the kernel**; DM-vs-group stays the -opaque `membership` thread attribute that **policy** reads (consistent with reactions, -mentions, media). - -``` -message.sent (outbox event) - │ - ▼ -NotificationProjector ── gate 1: policy (DM? or in a group: @mentioned OR a reply to you?) - │ ── gate 2: presence (connected AND viewing that thread? → skip) - │ ── gate 3: mute (thread muted for this actor? → skip) - ▼ -NotificationPort.deliver(subscription, payload) ← Web Push (VAPID) adapter - ▼ -browser push service → service worker → OS notification → tap → open thread -``` - -## 4. Components (IIOS engine) - -### 4.1 PresenceService -The `/message` gateway already tracks connected sockets and the thread each has joined -(`open_thread` = socket.io room join). PresenceService answers **"is actor A currently -viewing thread T?"**. Backed by Redis (reuses the existing socket.io Redis adapter) so it -holds across replicas. On disconnect, presence is cleared. - -### 4.2 NotificationProjector -Reacts to `message.sent` (same idempotent-consumer pattern as `InboxProjector`; it may live -alongside it). For each recipient participant (not the sender), runs the three gates in §3, -then dispatches to each of the actor's active subscriptions. Idempotent per event id. - -**Gate 1 (policy) detail:** DM (`membership='dm'`) → eligible. Group → eligible only if the -recipient is in the message's `mentions[]` **or** the message's `parentInteractionId` points -to a message that recipient authored (a reply to them). Otherwise → not eligible (badge/inbox -only). - -### 4.3 NotificationPort + WebPushDelivery -`interface NotificationPort { deliver(sub, payload): Promise<'sent'|'gone'|'failed'> }`. -`WebPushDelivery` signs with VAPID and POSTs to the subscription endpoint. A `'gone'` -(HTTP 404/410) result → the projector **prunes** that subscription row. Swappable to -email/FCM later without touching the projector. - -### 4.4 Payload -Built from **generic** fields: `{ title: senderName, body: text snippet (or "sent an -attachment"), tag: threadId, data: { threadId, interactionId } }`. No chat-specific logic in -the kernel; `data.threadId` drives the app's deep-link. - -## 5. Data (IIOS Postgres, tenant-scoped) - -- **`IiosNotificationSubscription`** (new) — `{ id, scopeId, actorId, kind: 'webpush', - endpoint (unique), p256dh, auth, userAgent?, createdAt, lastSeenAt }`. `@@index([actorId])`. -- **Mute** — a `muted Boolean @default(false)` column on **`IiosThreadParticipant`** (per - actor+thread; already the join row). -- **Notification record / feed** — **reuse `IiosInboxItem`** (already the feed; unread = - OPEN, read = DONE). No new "notifications" table. -- **VAPID keys** — env only (`VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT`), - generated once; private key is a secret, public key is served to clients. - -## 6. Endpoints (IIOS) - -| Method | Path | Body | Purpose | -|---|---|---|---| -| GET | `/v1/notifications/vapid-public-key` | — | public key the client needs to subscribe | -| POST | `/v1/notifications/subscribe` | `{kind, endpoint, keys:{p256dh, auth}, userAgent?}` | store/refresh a push subscription for the caller | -| DELETE | `/v1/notifications/subscribe` | `{endpoint}` | remove a subscription | -| POST | `/v1/threads/:id/mute` / `/unmute` | — | set/clear the caller's `muted` flag on the thread | - -All Bearer-authed and tenant-scoped (subscriptions/mutes belong to the caller's actor+scope). - -## 7. SDK + app (host experience) - -### 7.1 SDK (chat-web `lib/notifications.ts`; belongs in `@insignia/iios-kernel-client`) -- `registerPush()` — request `Notification` permission → register the service worker → - `PushManager.subscribe({ applicationServerKey: })` → POST the subscription. -- `unregisterPush()`, `mute(threadId)` / `unmute(threadId)`. -- **`sw.js`** (service worker) — `push` event → `showNotification(title, {body, tag, data})`; - `notificationclick` → focus an existing tab or open the app, deep-linked to `data.threadId`. - -### 7.2 App (chat-web) -- **Phase 1 (no backend):** on socket `message` while `document.hidden` **and** not viewing - that thread → `new Notification(...)`; tab-title `(N)` unread from the conversation list; - optional sound. Presence-gated client-side. -- **Phase 3:** an "Enable notifications" prompt (calls `registerPush`), a 🔕 **mute** toggle in - the conversation header, and deep-link handling when a notification is tapped. - -## 8. Error handling - -- **Presence unknown** (Redis blip) → treat as **absent** (better to notify than silently - miss). Mute + policy are still enforced. -- **Mute** is **fail-closed** — if the mute read fails, do **not** send (respect the intent). -- **Dead subscription** (web-push 404/410) → delete the row; a re-subscribe re-adds it. -- **VAPID unset** → the engine logs "push disabled" and no-ops; the app is unaffected - (Phase-1 desktop notifications still work). -- Delivery is best-effort/at-least-once; the client de-dupes visible notifications by `tag`. - -## 9. Testing - -- **Unit (projector):** DM→deliver · group-no-mention→skip · group-@mention→deliver · - present-in-thread→skip · muted→skip · sender-never-notified. -- **Unit (adapter/store):** subscription CRUD; prune on 410; WebPushDelivery with a mocked - transport. -- **Unit (presence):** connected+viewing vs connected-elsewhere vs disconnected. -- **e2e:** subscribe → send while the recipient is absent → delivery invoked; send while the - recipient is viewing the thread → not invoked; mute → not invoked. - -## 10. Generic-safety - -The projector consumes generic `message.sent` events + the opaque `mentions[]` list; DM-vs- -group is read from the opaque `membership` attribute (in policy, not kernel branching). The -payload is built from generic fields. Grep must show no `'dm'`/`'group'` literals in the -notification engine — same guardrail as the rest of IIOS. - -## 11. Phasing (drives the plan) - -1. **Phase 1 — frontend quick win (chat-web only):** desktop notification while unfocused + - tab-title unread + client-side presence gate. Demoable immediately, zero backend. -2. **Phase 2 — IIOS engine (TDD):** PresenceService · `IiosNotificationSubscription` + - `participant.muted` migration · endpoints · NotificationPort + WebPushDelivery · - NotificationProjector (3 gates + prune). Full suite green. -3. **Phase 3 — SDK + app:** `sw.js` + `registerPush` + enable-prompt · mute toggle · - deep-link on click. e2e verified. - -## 12. Out of scope (deferred) - -Quiet hours · global mute · per-thread level (all/mentions/none) · email + mobile (FCM/APNs) -adapters · notification bell/feed UI beyond the existing Inbox · rich/actionable -notifications (reply-from-notification) · digest/batching.