@ours.network/notifications 0.3.1-nightly.2 → 0.3.1-nightly.4

package/README.md

@@ -56,11 +56,11 @@ Responses are never cached. User and producer credentials have separate scopes.
 | 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, 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-target` | User | `{ "url": "/fleet/chats/agents/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" }` |
+| POST `/api/v1/delete-target` | Producer | `{ "url": "/fleet/chats/agents/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/agents/agent" }` |
 
 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
@@ -140,3 +140,36 @@ 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.
+
+Conversation notification links use canonical contact (`/fleet/chats/contacts/:id`), agent (`/fleet/chats/agents/:id`), and task room (`/fleet/tasks/:taskId/room` or `/fleet/tasks/:taskId/rooms/:key`) paths. Deploy producers, this service, and the app together. Summary rows retain `source`/`chat` and include `kind` (`contact`, `agent`, or `room`) to distinguish colliding IDs. Filters and message anchors do not change target identity. Old query-based conversation URLs are intentionally unsupported; stored payload URLs are neither converted nor deleted by this change. Existing navigation-target security restrictions still apply.

package/dist/chat-target.d.ts

@@ -1,9 +1,8 @@
-/** Stable conversation identity, independent of list filters and mobile detail state. */
-export declare function chatTarget(path: string): {
+export interface ChatTarget {
+    kind: 'contact' | 'agent' | 'room';
     source: 'work' | 'messenger';
     chat: string;
-} | null;
-export declare function chatKey(value: {
-    source: string;
-    chat: string;
-}): string;
+}
+/** Stable conversation identity, independent of list filters and message anchors. */
+export declare function chatTarget(path: string): ChatTarget | null;
+export declare function chatKey(value: ChatTarget): string;

package/dist/chat-target.js

@@ -1,15 +1,34 @@
-/** Stable conversation identity, independent of list filters and mobile detail state. */
+import { target as navigationTarget } from './validation.js';
+/** Stable conversation identity, independent of list filters and message anchors. */
 export function chatTarget(path) {
-    const url = new URL(path, 'https://ours.invalid');
-    if (url.pathname === '/fleet/chats') {
-        const chat = url.searchParams.get('chat');
-        if (!chat || chat.length > 512)
+    try {
+        navigationTarget(path);
+        const url = new URL(path, 'https://ours.invalid');
+        if (['source', 'chat', 'task', 'detail'].some(key => url.searchParams.has(key)))
             return null;
-        return { source: url.searchParams.get('source') === 'messenger' ? 'messenger' : 'work', chat };
+        // Match the original path: URL normalization must not turn malformed arity into a target.
+        const parts = path.split(/[?#]/, 1)[0].split('/').slice(1).map(decodeURIComponent);
+        if (parts.some(part => !part || /[\x00-\x1f\x7f]/.test(part) || part === '.' || part === '..'))
+            return null;
+        if (parts.length === 4 && parts[0] === 'fleet' && parts[1] === 'chats') {
+            if (parts[2] === 'contacts')
+                return { kind: 'contact', source: 'messenger', chat: parts[3] };
+            if (parts[2] === 'agents')
+                return { kind: 'agent', source: 'work', chat: parts[3] };
+        }
+        if (parts[0] === 'fleet' && parts[1] === 'tasks' && /^[A-Za-z0-9_-]{1,120}$/.test(parts[2] ?? '')) {
+            if (parts.length === 4 && parts[3] === 'room')
+                return { kind: 'room', source: 'work', chat: `room-${parts[2]}` };
+            if (parts.length === 5 && parts[3] === 'rooms' && /^[A-Za-z][A-Za-z0-9_-]*$/.test(parts[4])
+                && !['constructor', 'prototype', '__proto__'].includes(parts[4])) {
+                return { kind: 'room', source: 'work', chat: `room-${parts[2]}:${parts[4]}` };
+            }
+        }
     }
+    catch { /* Unsupported persisted input is unknown, never a missing target. */ }
     return null;
 }
 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]);
+    const chat = value.kind === 'contact' && /^[a-f0-9]{64}$/i.test(value.chat) ? value.chat.toUpperCase() : value.chat;
+    return JSON.stringify([value.kind, value.source, chat]);
 }

package/dist/server.js

@@ -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') {
@@ -128,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

@@ -1,3 +1,4 @@
+import { type ChatTarget } from './chat-target.js';
 import type { PushSubscription } from 'web-push';
 export interface Notification {
     id: string;
@@ -17,6 +18,16 @@ interface Device {
     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;
@@ -41,11 +52,9 @@ export declare class Store {
     summary(userId: string): {
         unread: number;
         revision: number;
-        chats: {
-            source: "work" | "messenger";
-            chat: string;
+        chats: (ChatTarget & {
             count: number;
-        }[];
+        })[];
         sections: {
             chats: number;
             tasks: number;
@@ -57,7 +66,10 @@ export declare class Store {
     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;
+    produce(value: Omit<Notification, 'id' | 'createdAt' | 'readAt'>): Notification | {
+        id: string;
+        duplicate: true;
+    };
     due(now: number): {
         device: Device | undefined;
         notification: Notification | undefined;
@@ -67,6 +79,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');
         }
@@ -107,10 +111,10 @@ export class Store {
         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))
+            if (/^\/fleet\/tasks(?:\/[^/]+)?\/?$/.test(url.pathname))
                 sections.tasks++;
             else if (targetForSection) {
-                if (typeof n.taskId === 'string' || targetForSection.source === 'work' && /^room-[^:]+(?::[^:]+)?$/.test(targetForSection.chat))
+                if (typeof n.taskId === 'string' || targetForSection.kind === 'room')
                     sections.tasks++;
                 else if (targetForSection.source === 'messenger')
                     sections.chats++;
@@ -176,18 +180,26 @@ export class Store {
         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 || 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() });
@@ -198,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.2",
+  "version": "0.3.1-nightly.4",
   "description": "Authenticated web push delivery and shared notification inbox",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",