@ours.network/notifications 0.3.1-nightly.1 → 0.3.1-nightly.3

package/README.md

@@ -55,15 +55,29 @@ Responses are never cached. User and producer credentials have separate scopes.
 | POST `/api/v1/devices/delete` | User | `{ "id": "device-id" }`, only that user's device |
 | GET `/api/v1/devices/status?id=...` | User | `{ "active": true }` |
 | GET `/api/v1/inbox?limit=50&before=...` | User | Items, shared unread count, revision, next cursor |
-| GET `/api/v1/summary` | User | Shared unread count, revision, and per-chat source/identity/count |
+| GET `/api/v1/summary` | User | Shared unread count, revision, per-chat source/identity/count, and `sections: {chats, tasks}` |
 | POST `/api/v1/read-target` | User | `{ "url": "/fleet/chats?chat=agent", "revision": OBSERVED_REVISION }`, reads only this chat up to the revision captured before its history load |
 | POST `/api/v1/read` | User | `{ "ids": ["notification-id"] }`, idempotent shared read |
+| POST `/api/v1/delete` | User | `{ "ids": ["notification-id"] }` → `{ "removed": COUNT }`; persistently removes only this user’s entries and queued deliveries after the client has confirmed target absence |
+| POST `/api/v1/delete-target` | Producer | `{ "url": "/fleet/chats?chat=agent" }` → `{ "removed": COUNT }`; only its credential’s user/source and exact canonical conversation, including filter/anchor variants |
 | POST `/api/v1/send` | Producer | `{ "eventId": "stable-event-id", "title": "Agent completed", "body": "Open the chat", "url": "/fleet/chats?chat=agent&detail=1" }` |
 
 Inbox admission and queued delivery are one fsynced atomic snapshot. The service
 deduplicates by user/source/event ID; replay must retain identical title/body/URL
 or it receives 409. Inbox entries survive failed pushes and service restart.
-Reading stops remaining queued deliveries. Device endpoints cannot transfer
+Producer send payloads may include `taskId`: a stable task ID for an associated
+ACP agent, or `null` for an explicitly standalone agent. Omission remains supported.
+The association is persisted and cannot change when replaying the same event ID.
+Summary section counts are independent of browser inventories: task-page URLs,
+encoded work task rooms and explicit task associations count under Tasks. An explicit
+task association takes precedence over the source. Messenger destinations, including
+room CIDs that open in Messenger, and explicit standalone agents count under Chats.
+Legacy ACP notifications without association
+and unknown destinations remain in the total and Notifications inbox only. Each
+unread contributes at most once to a section. Reading or deletion updates these
+counts with the same durable revision as the total.
+
+Reading stops remaining queued deliveries. Deleting confirmed stale inbox records updates the shared revision, unread summary and presence subscribers atomically. Generic loading, permission or network failures do not establish target absence; callers must validate absence through the owning service. Device endpoints cannot transfer
 between users, and only supported HTTPS push-provider hosts and valid P-256
 subscription keys are accepted. Navigation stays within `/fleet`.
 
@@ -126,3 +140,34 @@ limit remove frozen/disconnected clients. Only that foreground device's push
 is suppressed; its inbox item remains unread until explicitly marked read.
 Other devices still receive push. `inbox.changed` invalidates account-wide inbox
 views after producer admission or reads. Presence is ephemeral across restart.
+
+## Task lifecycle delivery and diagnostics
+
+Task notifications from Fleet identify creation and every committed lifecycle change,
+including block/unblock and deletion. Task routes remain eligible for push while a
+registered device is foreground; ordinary chat delivery keeps its existing server
+presence policy. The browser must display every push it has already received:
+Safari can revoke subscriptions after silent pushes, so suppression must happen
+before sending, never by returning from the worker's push handler.
+
+`GET /api/v1/delivery/status` requires the owner's user credential (never a producer
+credential). It returns active device/pending-job counts and the latest 100 safe
+outcomes for that account: provider acceptance, foreground suppression, expired
+endpoint, scheduled retry, cancellation or no registered device. The service retains
+at most 1,000 outcomes per account. Records contain IDs, timestamps, attempt counts
+and numeric provider status only; endpoints, encryption keys, notification contents
+and provider bodies are excluded. `provider_accepted` proves provider acceptance,
+not display or receipt on a phone.
+
+Failed push jobs persist with exponential backoff capped at one hour until they
+succeed, are read/deleted, or their endpoint expires (404/410). Restart preserves
+retry work. Re-registering a subscription with changed keys gets a new device ID,
+so a late expiry response cannot remove its replacement. Background subscription
+renewal requires the workspace page to reopen and reconcile its subscription;
+revoked permission requires an explicit user action in browser/device settings.
+
+Acceptance receipts retain event identity and a canonical payload hash even after
+an inbox item is deleted, preventing retry resurrection. Legacy inbox entries are
+admitted as receipts on load. The existing inbox/job caps remain; a separate cap of
+100,000 receipts per account rejects new events explicitly rather than evicting
+dedupe evidence. Upgrades must preserve the service's state file and scoped credentials.

package/dist/chat-target.js

@@ -9,4 +9,7 @@ export function chatTarget(path) {
     }
     return null;
 }
-export function chatKey(value) { return JSON.stringify([value.source, value.chat]); }
+export function chatKey(value) {
+    const chat = value.source === 'messenger' && /^[a-f0-9]{64}$/i.test(value.chat) ? value.chat.toUpperCase() : value.chat;
+    return JSON.stringify([value.source, chat]);
+}

package/dist/server.js

@@ -44,7 +44,7 @@ export function createNotificationService(config, send) {
             if (req.headers.origin || req.headers.cookie || req.headers['sec-fetch-site'])
                 throw new HttpError(403, 'use authenticated gateway');
             const url = new URL(req.url ?? '/', 'http://localhost');
-            const producerRoute = url.pathname === '/api/v1/send';
+            const producerRoute = ['/api/v1/send', '/api/v1/delete-target'].includes(url.pathname);
             const authorization = req.headers.authorization ?? '';
             const credential = (producerRoute ? config.producers : config.users).find(c => same(authorization, `Bearer ${c.token}`));
             if (!credential)
@@ -61,6 +61,8 @@ export function createNotificationService(config, send) {
             let result;
             if (req.method === 'GET' && url.pathname === '/api/v1/push/config')
                 result = { publicKey: config.vapid.publicKey };
+            else if (req.method === 'GET' && url.pathname === '/api/v1/delivery/status')
+                result = store.deliveryStatus(user);
             else if (req.method === 'GET' && url.pathname === '/api/v1/summary')
                 result = store.summary(user);
             else if (req.method === 'GET' && url.pathname === '/api/v1/inbox') {
@@ -88,16 +90,31 @@ export function createNotificationService(config, send) {
                 store.read(user, ids.map(id => text(id, 100)));
                 result = { ok: true };
             }
-            else if (req.method === 'POST' && producerRoute) {
+            else if (req.method === 'POST' && url.pathname === '/api/v1/delete') {
+                const value = await body(req), ids = value.ids;
+                if ('userId' in value || 'source' in value || !Array.isArray(ids) || ids.length > 100)
+                    throw new HttpError(400, 'invalid notification ids');
+                result = { removed: store.deleteNotifications(user, ids.map(id => text(id, 100))) };
+            }
+            else if (req.method === 'POST' && url.pathname === '/api/v1/delete-target') {
+                const value = await body(req);
+                if ('userId' in value || 'source' in value)
+                    throw new HttpError(400, 'recipient and source are credential scoped');
+                result = { removed: store.deleteTarget(user, credential.source, target(value.url)) };
+            }
+            else if (req.method === 'POST' && url.pathname === '/api/v1/send') {
                 const value = await body(req);
                 if ('userId' in value || 'source' in value)
                     throw new HttpError(400, 'recipient and source are credential scoped');
-                result = store.produce({ userId: user, source: credential.source, eventId: text(value.eventId, 512),
+                const taskId = value.taskId === undefined ? undefined : value.taskId === null ? null : text(value.taskId, 120);
+                if (typeof taskId === 'string' && !/^[A-Za-z0-9_-]+$/.test(taskId))
+                    throw new HttpError(400, 'invalid task identity');
+                result = store.produce({ ...(taskId === undefined ? {} : { taskId }), userId: user, source: credential.source, eventId: text(value.eventId, 512),
                     title: text(value.title, 160), body: text(value.body, 512), url: target(value.url) });
             }
             else
                 throw new HttpError(404, 'route not found');
-            if (req.method === 'POST' && ['/api/v1/send', '/api/v1/read', '/api/v1/read-target'].includes(url.pathname))
+            if (req.method === 'POST' && ['/api/v1/send', '/api/v1/read', '/api/v1/read-target', '/api/v1/delete', '/api/v1/delete-target'].includes(url.pathname))
                 presence.notify(user);
             res.end(JSON.stringify(result));
         }
@@ -113,21 +130,21 @@ export function createNotificationService(config, send) {
     const drain = () => draining ??= (async () => {
         for (const j of store.due(Date.now())) {
             if (!j.device || !j.notification || j.notification.readAt) {
-                store.finish(j.id, 'sent', Date.now());
+                store.finish(j.id, 'sent', Date.now(), j.notification?.readAt ? 'read_cancelled' : 'missing_target');
                 continue;
             }
-            if (presence.online(j.device.userId, j.device.id)) {
-                store.finish(j.id, 'sent', Date.now());
+            if (!/^\/fleet\/tasks(?:\/[^/]+)?\/?$/.test(new URL(j.notification.url, 'https://ours.invalid').pathname) && presence.online(j.device.userId, j.device.id)) {
+                store.finish(j.id, 'sent', Date.now(), 'foreground_suppressed');
                 continue;
             }
             try {
-                await deliver(j.device.subscription, JSON.stringify({ v: 1, kind: 'notification', title: j.notification.title,
+                const result = await deliver(j.device.subscription, JSON.stringify({ v: 1, kind: 'notification', title: j.notification.title,
                     body: j.notification.body, url: j.notification.url, notification_id: j.notification.id, tag: j.notification.id }));
-                store.finish(j.id, 'sent', Date.now());
+                store.finish(j.id, 'sent', Date.now(), 'provider_accepted', result?.statusCode);
             }
             catch (error) {
                 const status = error.statusCode;
-                store.finish(j.id, status === 404 || status === 410 ? 'gone' : 'retry', Date.now());
+                store.finish(j.id, status === 404 || status === 410 ? 'gone' : 'retry', Date.now(), status === 404 || status === 410 ? 'endpoint_expired' : 'retry_scheduled', status);
             }
         }
     })().finally(() => { draining = undefined; });

package/dist/store.d.ts

@@ -10,12 +10,23 @@ export interface Notification {
     createdAt: string;
     createdRevision?: number;
     readAt: string | null;
+    taskId?: string | null;
 }
 interface Device {
     id: string;
     userId: string;
     subscription: PushSubscription;
 }
+export type DeliveryOutcome = 'provider_accepted' | 'foreground_suppressed' | 'endpoint_expired' | 'retry_scheduled' | 'read_cancelled' | 'missing_target' | 'no_device';
+interface Delivery {
+    userId: string;
+    notificationId: string;
+    deviceId?: string;
+    at: string;
+    outcome: DeliveryOutcome;
+    attempt: number;
+    statusCode?: number;
+}
 /** Single-writer local service. Mutations commit a fsynced atomic snapshot before acknowledgement. */
 export declare class Store {
     private readonly file;
@@ -45,10 +56,21 @@ export declare class Store {
             chat: string;
             count: number;
         }[];
+        sections: {
+            chats: number;
+            tasks: number;
+        };
     };
     readTarget(userId: string, url: string, revision: number): void;
     read(userId: string, ids: string[]): void;
-    produce(value: Omit<Notification, 'id' | 'createdAt' | 'readAt'>): Notification;
+    /** Delete only this user's confirmed stale entries and their pending deliveries. */
+    deleteNotifications(userId: string, ids: string[]): number;
+    /** A producer may retire only its own notifications for the canonical conversation. */
+    deleteTarget(userId: string, source: string, url: string): number;
+    produce(value: Omit<Notification, 'id' | 'createdAt' | 'readAt'>): Notification | {
+        id: string;
+        duplicate: true;
+    };
     due(now: number): {
         device: Device | undefined;
         notification: Notification | undefined;
@@ -58,6 +80,13 @@ export declare class Store {
         attempts: number;
         due: number;
     }[];
-    finish(id: string, status: 'sent' | 'gone' | 'retry', now: number): void;
+    /** Bounded, account-scoped operational evidence; never endpoints, keys, payloads or provider bodies. */
+    deliveryStatus(userId: string): {
+        devices: number;
+        pending: number;
+        recent: Delivery[];
+    };
+    private recordDelivery;
+    finish(id: string, status: 'sent' | 'gone' | 'retry', now: number, outcome?: DeliveryOutcome, statusCode?: number): void;
 }
 export {};

package/dist/store.js

@@ -1,8 +1,10 @@
 import { chatTarget, chatKey } from './chat-target.js';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { HttpError } from './validation.js';
+const fingerprint = (value) => createHash('sha256')
+    .update(JSON.stringify([value.userId, value.source, value.eventId, value.title, value.body, value.url, value.taskId === undefined ? [] : [value.taskId]])).digest('hex');
 /** Single-writer local service. Mutations commit a fsynced atomic snapshot before acknowledgement. */
 export class Store {
     file;
@@ -29,6 +31,8 @@ export class Store {
         }
         try {
             this.state = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : { version: 1, revision: 0, devices: [], notifications: [], jobs: [] };
+            this.state.receipts ??= this.state.notifications.map(n => ({ userId: n.userId, source: n.source, eventId: n.eventId, id: n.id, fingerprint: fingerprint(n) }));
+            this.state.deliveries ??= [];
             if (this.state.version !== 1 || !Array.isArray(this.state.notifications) || !Array.isArray(this.state.devices) || !Array.isArray(this.state.jobs))
                 throw new Error('invalid notification state');
         }
@@ -104,7 +108,20 @@ export class Store {
     summary(userId) {
         const unread = this.state.notifications.filter(n => n.userId === userId && !n.readAt);
         const groups = new Map();
+        const sections = { chats: 0, tasks: 0 };
         for (const n of unread) {
+            const url = new URL(n.url, 'https://ours.invalid'), targetForSection = chatTarget(n.url);
+            if (/^\/fleet\/tasks(?:\/[^/]+)?\/?$/.test(url.pathname))
+                sections.tasks++;
+            else if (targetForSection) {
+                if (typeof n.taskId === 'string' || targetForSection.source === 'work' && /^room-[^:]+(?::[^:]+)?$/.test(targetForSection.chat))
+                    sections.tasks++;
+                else if (targetForSection.source === 'messenger')
+                    sections.chats++;
+                else if (n.taskId === null)
+                    sections.chats++;
+                // Older ACP records carry no association: leave them in the total only.
+            }
             const target = chatTarget(n.url);
             if (!target)
                 continue;
@@ -112,7 +129,7 @@ export class Store {
             group.count++;
             groups.set(key, group);
         }
-        return { unread: unread.length, revision: this.state.revision, chats: [...groups.values()] };
+        return { unread: unread.length, revision: this.state.revision, chats: [...groups.values()], sections };
     }
     readTarget(userId, url, revision) {
         if (!Number.isSafeInteger(revision) || revision < 0 || revision > this.state.revision)
@@ -138,19 +155,51 @@ export class Store {
             s.jobs = s.jobs.filter(j => !s.notifications.find(n => n.id === j.notificationId)?.readAt);
         });
     }
+    /** Delete only this user's confirmed stale entries and their pending deliveries. */
+    deleteNotifications(userId, ids) {
+        const chosen = new Set(ids);
+        const removed = new Set(this.state.notifications.filter(n => n.userId === userId && chosen.has(n.id)).map(n => n.id));
+        if (!removed.size)
+            return 0;
+        this.commit(s => {
+            s.notifications = s.notifications.filter(n => !removed.has(n.id));
+            s.jobs = s.jobs.filter(j => !removed.has(j.notificationId));
+        });
+        return removed.size;
+    }
+    /** A producer may retire only its own notifications for the canonical conversation. */
+    deleteTarget(userId, source, url) {
+        const target = chatTarget(url);
+        if (!target)
+            throw new HttpError(400, 'expected chat target');
+        const key = chatKey(target);
+        const ids = this.state.notifications.filter(n => n.userId === userId && n.source === source && (() => {
+            const other = chatTarget(n.url);
+            return other && chatKey(other) === key;
+        })()).map(n => n.id);
+        return this.deleteNotifications(userId, ids);
+    }
     produce(value) {
+        const receipt = this.state.receipts.find(r => r.userId === value.userId && r.source === value.source && r.eventId === value.eventId);
+        if (receipt && receipt.fingerprint !== fingerprint(value))
+            throw new HttpError(409, 'event id reused');
         const previous = this.state.notifications.find(n => n.userId === value.userId && n.source === value.source && n.eventId === value.eventId);
         if (previous) {
-            if (previous.title !== value.title || previous.body !== value.body || previous.url !== value.url)
+            if (previous.title !== value.title || previous.body !== value.body || previous.url !== value.url || previous.taskId !== value.taskId)
                 throw new HttpError(409, 'event id reused');
             return previous;
         }
+        if (receipt)
+            return { id: receipt.id, duplicate: true };
         // Explicit capacity failure instead of silently evicting unread history or dedupe records.
-        if (this.state.notifications.filter(n => n.userId === value.userId).length >= 10_000 || this.state.jobs.length >= 20_000)
+        if (this.state.receipts.filter(r => r.userId === value.userId).length >= 100_000 || this.state.notifications.filter(n => n.userId === value.userId).length >= 10_000 || this.state.jobs.length >= 20_000)
             throw new HttpError(503, 'notification capacity exceeded');
         const n = { ...value, id: randomUUID(), createdAt: new Date().toISOString(), createdRevision: this.state.revision + 1, readAt: null };
         this.commit(s => {
             s.notifications.push(n);
+            s.receipts.push({ userId: n.userId, source: n.source, eventId: n.eventId, id: n.id, fingerprint: fingerprint(n) });
+            if (!s.devices.some(d => d.userId === n.userId))
+                this.recordDelivery(s, { userId: n.userId, notificationId: n.id, at: n.createdAt, outcome: 'no_device', attempt: 0 });
             for (const d of s.devices)
                 if (d.userId === n.userId)
                     s.jobs.push({ id: randomUUID(), notificationId: n.id, deviceId: d.id, attempts: 0, due: Date.now() });
@@ -161,20 +210,35 @@ export class Store {
         return this.state.jobs.filter(j => j.due <= now).slice(0, 32).map(j => ({ ...j,
             device: this.state.devices.find(d => d.id === j.deviceId), notification: this.state.notifications.find(n => n.id === j.notificationId) }));
     }
-    finish(id, status, now) {
+    /** Bounded, account-scoped operational evidence; never endpoints, keys, payloads or provider bodies. */
+    deliveryStatus(userId) {
+        return { devices: this.state.devices.filter(d => d.userId === userId).length,
+            pending: this.state.jobs.filter(j => this.state.notifications.some(n => n.id === j.notificationId && n.userId === userId)).length,
+            recent: this.state.deliveries.filter(d => d.userId === userId).slice(-100).reverse() };
+    }
+    recordDelivery(state, value) {
+        const sameUser = state.deliveries.filter(d => d.userId === value.userId).slice(-999);
+        state.deliveries = [...state.deliveries.filter(d => d.userId !== value.userId), ...sameUser, value];
+    }
+    finish(id, status, now, outcome = status === 'sent' ? 'provider_accepted' : status === 'gone' ? 'endpoint_expired' : 'retry_scheduled', statusCode) {
         this.commit(s => {
             const j = s.jobs.find(j => j.id === id);
             if (!j)
                 return;
+            const n = s.notifications.find(n => n.id === j.notificationId);
+            if (n)
+                this.recordDelivery(s, { userId: n.userId, notificationId: n.id, deviceId: j.deviceId,
+                    at: new Date(now).toISOString(), outcome, attempt: j.attempts + 1,
+                    ...(Number.isInteger(statusCode) && statusCode >= 100 && statusCode <= 599 ? { statusCode } : {}) });
             if (status === 'gone') {
                 s.devices = s.devices.filter(d => d.id !== j.deviceId);
                 s.jobs = s.jobs.filter(v => v.deviceId !== j.deviceId);
             }
-            else if (status === 'sent' || j.attempts >= 7)
+            else if (status === 'sent')
                 s.jobs = s.jobs.filter(v => v.id !== id);
             else {
-                j.attempts++;
-                j.due = now + Math.min(60_000 * 2 ** j.attempts, 3_600_000);
+                j.attempts = Math.min(j.attempts + 1, 1024);
+                j.due = now + Math.min(60_000 * 2 ** Math.min(j.attempts, 6), 3_600_000);
             }
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/notifications",
-  "version": "0.3.1-nightly.1",
+  "version": "0.3.1-nightly.3",
   "description": "Authenticated web push delivery and shared notification inbox",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",