@lunora/notify 1.0.0-alpha.8 → 1.0.0-alpha.81

package/README.md

@@ -22,7 +22,7 @@ export default defineNotify({
 });
 ```
 
-`.dev.vars` (scaffolded by `lunora dev` from `@lunora/config`'s package-secrets registry):
+`.dev.vars` (scaffolded by `lunora dev` from `@lunora/config`'s package-secrets registry — only for the channels `defineNotify` configures):
 
 ```
 VAPID_PUBLIC_KEY=<your-vapid-public-key>
@@ -39,40 +39,105 @@ Generate a VAPID keypair once: `npx web-push generate-vapid-keys`.
 ```ts
 import { subscribeToPush } from "@lunora/notify/web";
 
-const subscription = await subscribeToPush({ serviceWorkerUrl: "/sw.js", vapidPublicKey });
-await client.mutation("registerDevice", { subscription });
+const { replacedEndpoint, subscription } = await subscribeToPush({ serviceWorkerUrl: "/sw.js", vapidPublicKey });
+await client.mutation("registerDevice", { replacedEndpoint, subscription });
 ```
 
+Without `serviceWorkerUrl`, `subscribeToPush` uses the page's existing
+registration: await your own `navigator.serviceWorker.register()` first, or the
+call rejects with "no service worker is registered" instead of waiting for it.
+
+`replacedEndpoint` is set only after a **VAPID key rotation**: the stale browser
+subscription is dropped and a new one minted, and the new one has a new endpoint
+— hence a new store id — so it never upserts over the old row. Every send to that
+row now answers `403 VapidPkHashMismatch`, which is (correctly) not a "gone"
+signal, so nothing prunes it either. Forward it and unregister it:
+
 ```ts
 // lunora/registerDevice.ts (a mutation — storage write is fine here)
-export const registerDevice = mutation({
-    args: { subscription: v.any() },
-    handler: async (ctx, { subscription }) => {
+import { webPushId } from "@lunora/notify";
+
+export const registerDevice = mutation
+    .input({ replacedEndpoint: v.optional(v.string()), subscription: v.any() })
+    .mutation(async ({ ctx, args: { replacedEndpoint, subscription } }) => {
+        if (replacedEndpoint !== undefined) {
+            await ctx.push.unregister(webPushId(replacedEndpoint), { userId: ctx.auth?.userId });
+        }
+
         await ctx.push.register({ subscription, userId: ctx.auth?.userId });
-    },
+    });
+```
+
+`unregister`'s owner argument is **required**, and the row is removed only when
+it carries that same owner. A subscription id is derived from the endpoint, so
+`replacedEndpoint` is a caller-controlled key and nothing about it proves the
+browser that sent it ever held the subscription it names — without the scope,
+anyone who could guess or observe another user's endpoint could silence that
+device. A row owned by someone else is left alone silently, so the call cannot be
+used to probe which endpoints exist. Register with the same `userId` you
+unregister with; devices registered anonymously (`userId` absent) all share the
+one anonymous scope and get no separation from this check.
+
+`register` is scoped the same way, because an unguarded upsert closes only half
+of that: re-registering a victim's endpoint under your own `userId` (with keys of
+your choosing) takes their device dark just as effectively, and hands you
+`unregister` over it. An endpoint already registered to another user is
+**refused** (`FORBIDDEN`) rather than re-owned — unowned rows stay claimable (the
+device signed in), and a device that legitimately changes hands unregisters as
+its current owner first.
+
+**Unregister on sign-out, or the next account on that browser cannot register.**
+`subscribeToPush` REUSES the browser's existing subscription while the VAPID key
+is unchanged, so the endpoint — and the store id derived from it — is the same
+for every account that signs in on that browser. Without the sign-out call, user
+B's `register` hits user A's row and throws `FORBIDDEN`; since `register` is
+usually fire-and-forget on sign-in, that surfaces as a failed mutation and B
+silently never receives a push. Release the row where you clear the session:
+
+```ts
+// lunora/registerDevice.ts — the same file as above
+export const unregisterDevice = mutation.input({ endpoint: v.string() }).mutation(async ({ args: { endpoint }, ctx }) => {
+    await ctx.push.unregister(webPushId(endpoint), { userId: ctx.auth?.userId });
 });
 ```
 
+```ts
+// wherever you sign out. `subscription.endpoint` is on the object subscribeToPush returned.
+await client.mutation("unregisterDevice", { endpoint: subscription.endpoint });
+await auth.signOut();
+```
+
+Keep the browser subscription itself (don't call `unsubscribeFromPush`) unless
+the user is turning notifications off: dropping it re-prompts for permission on
+the next sign-in. Note that only the owner can release a row — B cannot
+`unregister` A's — so a sign-out that never runs (the tab was closed, the session
+expired) leaves the next account refused until A signs in again on that browser
+or the row is removed server-side. On a browser several people sign in on, treat
+the sign-out unregister as required, not as cleanup.
+
 ## Send (from an action)
 
 Notification sends are external I/O, so they belong in **actions** (the `notify_send_outside_action` advisor lint enforces this):
 
 ```ts
-export const announce = action({
-    args: { title: v.string(), body: v.string() },
-    handler: async (ctx, { title, body }) => {
-        const result = await ctx.push.broadcast({ title, body });
-        // result: { total, sent, pruned, failed, outcomes }
-    },
+export const announce = action.input({ title: v.string(), body: v.string() }).action(async ({ ctx, args: { title, body } }) => {
+    const result = await ctx.push.broadcast({ title, body });
+    // result: { total, sent, pruned, failed, outcomes }
 });
 ```
 
-`broadcast` reuses the engine's retry + circuit-breaker middleware and prunes subscriptions the push service reports as gone (HTTP 404/410, FCM `UNREGISTERED`). A single targeted send:
+`broadcast` reuses the engine's retry + circuit-breaker middleware and prunes subscriptions the push service reports as gone (Web Push HTTP 404/410; FCM's `NOT_FOUND` answer for a dead token, plus the `UNREGISTERED`/`NotRegistered` codes a legacy transport sends). A single targeted send:
 
 ```ts
 await ctx.push.send(subscriptionId, { title: "Hi", body: "…" });
 ```
 
+`send` and `broadcast` take per-message delivery hints, overriding the channel's `urgency` / `ttl`. Web Push sends them as the `Urgency` / `TTL` headers; FCM maps them to `android.priority` / `android.ttl`:
+
+```ts
+await ctx.push.broadcast({ title: "Approval needed", body: "…", urgency: "high", ttl: 3600 }, { userId });
+```
+
 Multi-channel through `ctx.notify.send`:
 
 ```ts
@@ -90,8 +155,36 @@ Move a large broadcast off the request path with `@lunora/queue`:
 // producer (mutation/action)
 await enqueuePushBroadcast(ctx.queues.push, { payload: { title: "New drop", body: "…" } });
 
-// consumer (lunora/queues.ts)
-for (const message of batch.messages) await runPushBroadcastJob(ctx.push, message.body);
+// lunora/notify-fanout.ts — an INTERNAL ACTION, because that is where
+// `ctx.push` and `ctx.queues` exist.
+export const deliverPage = internalAction.input({ job: v.any() }).action(async ({ args: { job }, ctx }) => {
+    const { failedIds, nextFilter } = await runPushBroadcastPage(ctx.push, job);
+
+    // One message = ONE bounded page. Discarding `nextFilter` delivers only the
+    // first page (default 250 devices) and reports success for the whole audience.
+    // Pass it verbatim — it carries the cursor AND the remaining `filter.limit`.
+    if (nextFilter !== undefined) {
+        await enqueuePushBroadcast(ctx.queues.push, { payload: job.payload, filter: nextFilter });
+    }
+
+    // Redeliver ONLY the recipients that failed — a retry of the whole page would
+    // re-POST everyone it already reached.
+    if (failedIds.length > 0) {
+        await enqueuePushBroadcast(ctx.queues.push, { payload: job.payload, retryIds: failedIds });
+    }
+});
+
+// lunora/queues.ts — a `QueueRunContext` is exactly `{ env, log, run }`: no
+// `ctx.push`, no `ctx.queues`. The consumer hands each message to the action above.
+// (Note the handler signature: `(context, batch)`, in that order.)
+export const push = defineQueue<PushBroadcastJob>({
+    handler: async (context, batch) => {
+        for (const message of batch.messages) {
+            await message.run(internal.notifyFanout.deliverPage, { job: message.body });
+            message.ack();
+        }
+    },
+});
 ```
 
 ## Subscription storage
@@ -123,15 +216,17 @@ client-supplied data, so the facade enforces two boundaries:
 - **No secrets on the app facade.** `ctx.push.list()`
   returns the registered devices with the delivery **secrets stripped** — the Web
   Push `keys` (`auth`/`p256dh`) and the FCM `token`, which together with the
-  endpoint are enough to deliver arbitrary push to a device. The raw rows are
-  reachable only through the internal `SubscriptionStore` (which handlers never
-  hold); the broadcast path uses the store directly.
+  endpoint are enough to deliver arbitrary push to a device. Every other facade
+  read is projected the same way; the broadcast path uses the store directly. The
+  one place a handler does see a raw row is the return of `ctx.push.register(...)`,
+  which echoes back the record the caller just supplied — nothing it did not
+  already hold, and never another device's.
 
 ## Delivery observability
 
 Every send is counted onto `ctx.metrics` and failures onto `ctx.log` for you — codegen threads the request's logger/metrics into `ctx.notify` (`createNotify(notifyConfig, env, { log, metrics })`), so there is nothing to wire. Two low-cardinality metric series feed the durable metric history + trend charts:
 
-- **`notify.send`** `{ channel, provider, status }` — attempted sends. `status` is `accepted` (the provider took it), `failed`, or `gone` (endpoint unregistered — 404/410 / FCM `UNREGISTERED` — and pruned). A single send counts 1; a **broadcast aggregates** into one count per `(provider, status)` bucket (value = the bucket's count), not one per recipient — each `ctx.metrics.count` is a durable write.
+- **`notify.send`** `{ channel, provider, status }` — attempted sends. `status` is `accepted` (the provider took it), `failed`, or `gone` (endpoint unregistered — Web Push 404/410, or FCM's `NOT_FOUND` for a dead token — and pruned). A single send counts 1; a **broadcast aggregates** into one count per `(provider, status)` bucket (value = the bucket's count), not one per recipient — each `ctx.metrics.count` is a durable write.
 - **`notify.skipped`** `{ channel, reason }` — a send that reached nobody: `no-subscriptions-matched` (empty broadcast) or `channel-not-configured`.
 
 A **failed** send also emits one `ctx.log.warn` line carrying the error and, for push, the subscription/user ids — trace-correlated to the enclosing action and durably archived. Successes and prunes stay off the log; failure logs stay per-recipient even in a broadcast (they have no durable write).