@lunora/notify 1.0.0-alpha.6 → 1.0.0-alpha.60

package/dist/index.d.ts

@@ -75,14 +75,56 @@ type RegisterInput = {
 };
 /** Filter narrowing which stored subscriptions a `list`/`broadcast` targets. */
 interface SubscriptionFilter {
+  /**
+   * Keyset pagination cursor: return only rows with `id` strictly GREATER
+   * than this value, ordered ascending by `id`. `id` is a stable,
+   * content-derived hash (see `webPushId`/`fcmId`), so ordering by it is
+   * immune to concurrent inserts/deletes elsewhere in the table — a page
+   * already walked never re-delivers or skips a row when another device
+   * registers mid-broadcast (the reviewer-flagged "stable under concurrent
+   * registers" property). `broadcastPage`/`broadcast` set this internally to
+   * walk pages; a direct `list()` caller may also page through results with
+   * it.
+   *
+   * OPTIONAL for a reason: `SubscriptionStore` is implementable outside this
+   * package. An external store that does not support cursoring may ignore
+   * `after` entirely and keep returning its (from-the-top) unpaged result —
+   * `broadcastPage` defensively re-filters whatever the store returns down
+   * to `id > after` itself, so a non-cursoring store can never cause a
+   * double-send or an infinite page-walk (each page's result only ever
+   * contains ids the previous page didn't already deliver), but it also
+   * cannot deliver the FULL matched audience beyond whatever the store's own
+   * (unpaged) response window happens to contain — implement `after`
+   * (ordered ascending by `id`, exclusive) to get real, complete pagination
+   * over a large audience.
+   */
+  after?: string;
   /** Restrict to a delivery kind. */
   kind?: SubscriptionKind;
   /**
    * Cap the number of rows returned (a `LIMIT`). Applied server-side by the
    * store, so a large audience never materializes wholesale in the isolate.
    * A non-positive/absent value means "no cap"; a fractional value is truncated.
-   * `broadcast` deliberately leaves this unset (it must reach every matched
-   * device); admin/list reads set it to bound the page.
+   *
+   * For `list`/admin reads this bounds the returned page as before. For
+   * `broadcast`, this is now an OVERALL cap on the total number of
+   * subscriptions reached across every internally-walked page (still
+   * deliberately left unset by default — it must reach every matched
+   * device); the PER-PAGE batch size is a separate, independent knob (see
+   * `defineNotify`'s `broadcastPageSize`, default 250) so a caller
+   * that sets `limit` to bound the audience doesn't also have to reason
+   * about page sizing.
+   *
+   * The non-positive sentinel means something different at each layer: at
+   * the STORE layer (`list`, and the `d1-store`/`memory-store` fetch-size
+   * hint) a non-positive `limit` means "no cap" — fetch everything. At the
+   * `broadcast`/`broadcastPage` layer, where `limit` is an AUDIENCE cap, a
+   * non-positive value instead means "no deliveries" — `broadcast({ limit: 0
+   * })` reaches nobody, not everybody. This asymmetry is deliberate: the two
+   * layers answer different questions ("how many rows to fetch" vs. "how
+   * many recipients to reach"), and unifying them would either break `list`
+   * callers relying on "no cap" or reintroduce the over-delivery this
+   * distinction fixes (see `broadcastPage`'s doc comment).
    */
   limit?: number;
   /** Restrict to a single owning user. */
@@ -96,13 +138,69 @@ interface SubscriptionFilter {
 interface SubscriptionStore {
   /** Remove a subscription by id (idempotent). */
   delete: (id: string) => Promise<void>;
+  /**
+   * Remove a subscription by id ONLY if it is owned by `userId`, and report
+   * whether it was.
+   *
+   * Separate from {@link SubscriptionStore.delete} because the caller-facing
+   * `unregister` must not be a read followed by a write: between a `get` that
+   * checks the owner and a `delete` that acts on it, a re-registration can
+   * replace the row, so the check passes for one owner and the removal lands on
+   * another's subscription.
+   *
+   * **The predicate and the removal must be ONE operation.** A store that
+   * cannot do that atomically should say so in its own documentation rather
+   * than implement this as a get-then-delete, which reintroduces the race this
+   * method exists to remove. Both shipped stores manage it: the in-memory one
+   * because a `Map` check-and-delete has no await between the two, and the D1
+   * one with a single `DELETE … WHERE id = ? AND user_id = ? RETURNING id`.
+   *
+   * `userId` is `null` for an anonymous subscription, and matches only a row
+   * that is itself unowned.
+   * @param id The subscription id.
+   * @param userId The owner the row must carry, or `null` for unowned.
+   * @returns `true` when a row was removed.
+   */
+  deleteOwned: (id: string, userId: string | null) => Promise<boolean>;
   /** Read a subscription by id, or `undefined`. */
   get: (id: string) => Promise<StoredSubscription | undefined>;
-  /** List subscriptions, optionally filtered. */
+  /**
+   * List subscriptions, optionally filtered. When `filter.after` is set,
+   * results are keyset-paginated: only rows with `id` strictly greater than
+   * `filter.after` are returned, ordered ascending by `id`. Implementing
+   * `after` is OPTIONAL (see {@link SubscriptionFilter.after}) — a store
+   * that ignores it may keep returning its unpaged result.
+   */
   list: (filter?: SubscriptionFilter) => Promise<StoredSubscription[]>;
   /** Record the latest delivery outcome for a subscription (best-effort). */
   markStatus: (id: string, status: SubscriptionStatus, error?: string) => Promise<void>;
-  /** Insert or update a subscription (upsert by id). */
+  /**
+   * Insert or update a subscription (upsert by id), refusing to move an
+   * existing row to a DIFFERENT owner.
+   *
+   * The ownership predicate is the same one {@link SubscriptionStore.deleteOwned}
+   * carries, and for the same reason: the id is derived from the endpoint or the
+   * FCM token, so it is a **caller-controlled key**. An unguarded upsert let any
+   * caller who could guess or observe another user's endpoint re-register it
+   * under their own `userId` with keys of their choosing — the victim's device
+   * then fails every send (an encryption failure is not a gone signal, so it is
+   * never pruned either) and the attacker can `unregister` it as their own. The
+   * `unregister` guard alone closed exactly half of that (CWE-639).
+   *
+   * A row with no owner is claimable (the device signed in), and a row the caller
+   * already owns is theirs to refresh — that is the routine service-worker
+   * re-registration. Anything else must REJECT (`FORBIDDEN`), not silently
+   * no-op: unlike `unregister` there is nothing safe to return, since a caller
+   * gets the stored record back and it would be someone else's delivery keys.
+   * A shared device that legitimately changes hands is handled by its current
+   * owner calling `unregister` first.
+   *
+   * **The predicate and the write must be ONE operation**, as for `deleteOwned`:
+   * between a read that checks the owner and the write that acts on it, another
+   * registration can replace the row. The D1 store puts the predicate in the
+   * `ON CONFLICT … DO UPDATE`'s own `WHERE`; the in-memory one has no `await`
+   * between the two.
+   */
   put: (subscription: StoredSubscription) => Promise<StoredSubscription>;
 }
 /** Per-recipient outcome from a fan-out `broadcast`. */
@@ -127,6 +225,18 @@ interface BroadcastResult {
   /** Total subscriptions attempted. */
   total: number;
 }
+/**
+ * Result of `broadcastPage` — one bounded page of a fan-out, plus the cursor
+ * to fetch the next page. `nextCursor` is `undefined` when this was the last
+ * page (or the store doesn't support cursoring — see
+ * {@link SubscriptionFilter.after}'s documented unpaged fallback).
+ */
+interface BroadcastPageResult {
+  /** Cursor for the next page (pass as `filter.after`), or `undefined` when done. */
+  nextCursor?: string;
+  /** The delivery outcome for just this page. */
+  result: BroadcastResult;
+}
 /**
  * The compact, stable delivery-status vocabulary emitted on notify observability
  * signals — the `status` dimension on the `notify.send` metric and the failure
@@ -134,7 +244,7 @@ interface BroadcastResult {
  *
  * - `accepted` — the provider took the message (a `Receipt.successful` send).
  * - `failed` — a provider error; the log line carries the `error` text.
- * - `gone` — the endpoint is unregistered (404/410, FCM `UNREGISTERED`) and pruned; push-only.
+ * - `gone` — the endpoint is unregistered (Web Push 404/410, FCM's `NOT_FOUND` for a dead token) and pruned; push-only.
  *
  * Web Push and FCM give no delivery/open receipts, so the vocabulary stops at the
  * send attempt: a `delivered`/`opened` status would be a lie for these channels.
@@ -179,24 +289,90 @@ interface LunoraPush {
   /**
    * Fan-out a push to every stored subscription matching `filter` (default: all).
    * Reuses the engine's retry/circuit-breaker middleware; prunes subscriptions
-   * the push service reports as gone (HTTP 404/410, FCM `UNREGISTERED`). The `to`
+   * the push service reports as gone (Web Push 404/410, FCM's `NOT_FOUND` for a dead token). The `to`
    * target is derived from each subscription, so it is omitted from the payload.
+   *
+   * Internally walks the audience in bounded pages (via {@link LunoraPush.broadcastPage},
+   * keyset-paginated on the subscription `id`) so the audience ROWS are never
+   * materialized wholesale in the isolate — see `defineNotify`'s
+   * `broadcastPageSize`. The returned `outcomes` ARE whole-audience, though: one
+   * `{ id, status }` per recipient accumulates across every page, so this call is
+   * bounded in rows held but not in outcomes reported. It also processes the WHOLE
+   * matched audience in one request/queue message; use {@link LunoraPush.broadcastPage}
+   * directly (as `runPushBroadcastPage` does) to bound a single queue message —
+   * and its result — to one page.
    */
   broadcast: (payload: PushContent, filter?: SubscriptionFilter) => Promise<BroadcastResult>;
+  /**
+   * Fan-out a push to ONE bounded page of stored subscriptions matching
+   * `filter` (page size: `defineNotify`'s `broadcastPageSize`, default
+   * 250, capped by `filter.limit` when set). Same delivery semantics as
+   * {@link LunoraPush.broadcast} (retry/circuit-breaker, gone-pruning) but
+   * scoped to a single page; returns the page's own {@link BroadcastResult}
+   * plus a `nextCursor` to fetch the next page (`undefined` when done).
+   * Backs `runPushBroadcastPage` so one queue message does bounded work
+   * regardless of audience size — most app code should call
+   * {@link LunoraPush.broadcast} instead.
+   */
+  broadcastPage: (payload: PushContent, filter?: SubscriptionFilter) => Promise<BroadcastPageResult>;
   /**
    * List stored subscriptions (optionally filtered), with the delivery
    * **secrets** stripped — the Web Push `keys` (RFC 8291 `auth`/`p256dh`) and the
    * FCM `token`. Those, plus the endpoint, are enough to deliver arbitrary push to
-   * a device, so they never cross the app-facing facade; the raw rows are
+   * a device, so no READ on this facade returns them; the raw rows are otherwise
    * reachable only through the internal `SubscriptionStore`.
+   *
+   * {@link LunoraPush.register} is the one exception, and deliberately so: it
+   * echoes back the record the caller just supplied, so it discloses nothing
+   * the caller did not already hold and never another device's row.
    */
   list: (filter?: SubscriptionFilter) => Promise<PushSubscriptionDevice[]>;
-  /** Register (upsert) a device subscription and return the stored record. */
+  /**
+   * Register (upsert) a device subscription and return the stored record (the
+   * caller's own row, secrets included).
+   *
+   * Owner-scoped, exactly as {@link LunoraPush.unregister} is: registering an
+   * endpoint that is already another user's row is REFUSED (`FORBIDDEN`) rather
+   * than re-owning it. Pass `ctx.auth?.userId` so the check has something to
+   * separate; an app that registers every device anonymously gets no separation
+   * from it (every row is unowned, and unowned rows stay claimable). A device
+   * that legitimately changes hands — one browser profile, two accounts —
+   * unregisters as its current owner first.
+   */
   register: (input: RegisterInput) => Promise<StoredSubscription>;
   /** Send a push to a single stored subscription (by id or record); `to` is derived from it. */
   send: (target: StoredSubscription | string, payload: PushContent) => Promise<Receipt>;
-  /** Remove a subscription by id (idempotent). */
-  unregister: (id: string) => Promise<void>;
+  /**
+   * Remove ONE of `owner`'s subscriptions by id (idempotent).
+   *
+   * `owner` is not optional, and the removal happens only when the stored row
+   * carries that same owner. A subscription id is derived from the endpoint
+   * (`webPushId`) or the FCM token, so it is a **caller-controlled key**: the
+   * intended call is a mutation forwarding `subscribeToPush`'s
+   * `replacedEndpoint` after a VAPID rotation, and nothing about that argument
+   * proves the browser sending it ever held the subscription it names.
+   * Deleting by id alone let any caller that could guess or observe another
+   * user's endpoint silence that device's notifications (CWE-639).
+   *
+   * A row belonging to someone else is left alone SILENTLY rather than
+   * refused, so the call cannot be used to probe which endpoints exist — the
+   * same answer, and the same absence of a write, as an id that was never
+   * registered.
+   *
+   * `{ userId: null }` (or `undefined`, which normalises to it) addresses the
+   * anonymous rows — those registered with no `userId`. An app that registers
+   * every device anonymously therefore gets no separation from this check;
+   * pass `ctx.auth?.userId` and register with it to get any.
+   */
+  unregister: (id: string, owner: PushOwner) => Promise<void>;
+}
+/** Who a {@link LunoraPush.unregister} call is acting as. */
+interface PushOwner {
+  /**
+   * The authenticated caller (`ctx.auth?.userId`), or `null`/`undefined` for
+   * an anonymous registration. Required — see {@link LunoraPush.unregister}.
+   */
+  userId: string | null | undefined;
 }
 /** A push payload without its `to` target — the facade derives `to` from the stored subscription. */
 type PushContent = Omit<PushPayload, "to">;
@@ -207,7 +383,7 @@ type PushContent = Omit<PushPayload, "to">;
  * single-channel convenience senders for the edge-safe channels.
  */
 interface LunoraNotify {
-  /** Send an outbound webhook. */
+  /** Post to a chat channel (Slack/Discord/Teams/Telegram). */
   chat: (payload: ChatPayload) => Promise<Receipt>;
   /** Deliver an in-app inbox notification. */
   inApp: (payload: InAppPayload) => Promise<Receipt>;
@@ -215,7 +391,7 @@ interface LunoraNotify {
   push: LunoraPush;
   /** Deliver a multi-channel message (one payload per channel). */
   send: (message: NotificationMessage) => Promise<Receipt[]>;
-  /** Post to a chat channel (Slack/Discord/Teams/Telegram). */
+  /** Send an outbound webhook. */
   webhook: (payload: WebhookPayload) => Promise<Receipt>;
 }
 /**
@@ -243,11 +419,32 @@ interface NotifyConfig {
    * wildcards) to hard-pin the boundary and close DNS rebinding.
    */
   allowedPushOrigins?: string[];
+  /**
+   * Page size for `push.broadcast`'s internal keyset pagination over the
+   * subscription store (default 250, minimum 1). Each page is fetched,
+   * delivered, and counted before the next page's store round trip, so a huge
+   * audience is never materialized wholesale in the isolate. Also the
+   * per-message bound `push.broadcastPage` (and `runPushBroadcastPage`) uses.
+   *
+   * Declared here, and not only on `createNotify`'s third argument, because
+   * this file is the only handle an app has: the sole production constructor is
+   * codegen's fixed `createNotify(definition, env, { log, metrics })`, so a knob
+   * that lives only on those options is unsettable by every Lunora app —
+   * while {@link SubscriptionFilter.limit}'s own docs point at it as the way to
+   * size pages.
+   */
+  broadcastPageSize?: number;
   /**
    * Optional chat provider factory (Slack/Discord/Teams/Telegram). Wire with a
    * provider from `@visulima/notification/providers/*`. Edge-safe (fetch-based).
    */
   chat?: (env: NotifyEnv) => unknown;
+  /**
+   * Max concurrent sends during a `push.broadcast` (default 10, minimum 1).
+   * Same reasoning as {@link NotifyConfig.broadcastPageSize}: this is where an
+   * app can reach it.
+   */
+  concurrency?: number;
   /** FCM (Firebase Cloud Messaging HTTP v1) config. Edge-safe — supply an OAuth2 token. */
   fcm?: FcmConfig | FcmConfigFactory;
   /** Optional in-app inbox provider factory. Edge-safe. */
@@ -333,7 +530,21 @@ declare const defineNotify: (config: NotifyConfig) => NotifyDefinition;
 declare const isNotifyDefinition: (value: unknown) => value is NotifyDefinition;
 /** Options for {@link createNotify}. */
 interface CreateNotifyOptions {
-  /** Max concurrent sends during a `broadcast` (default 10). */
+  /**
+   * Page size for `push.broadcast`'s internal keyset pagination over the
+   * subscription store (default {@link DEFAULT_BROADCAST_PAGE_SIZE}, 250).
+   *
+   * A test/tuning seam only. **Apps set `broadcastPageSize` on `defineNotify`
+   * instead** — the sole production call is codegen's fixed
+   * `createNotify(definition, env, { log, metrics })`, so nothing an app writes
+   * reaches this object. Set here it wins over the definition's value.
+   */
+  broadcastPageSize?: number;
+  /**
+   * Max concurrent sends during a `broadcast` (default 10). Test/tuning seam;
+   * apps set `concurrency` on `defineNotify` — see
+   * {@link CreateNotifyOptions.broadcastPageSize}.
+   */
   concurrency?: number;
   /**
    * Override the assembled `@visulima/notification` engine. Advanced/testing
@@ -377,6 +588,11 @@ declare const createNotify: (definition: NotifyDefinition, env: NotifyEnv, optio
 };
 /** Options for {@link routingPushProvider}. */
 interface RoutingPushOptions {
+  /**
+   * The definition's exact-origin allowlist, when configured. Its presence
+   * disables the send-time rebinding re-check (see {@link assertPushTargetResolvable}).
+   */
+  allowedPushOrigins?: string[];
   fcm?: Provider<unknown, PushPayload>;
   webPush?: Provider<unknown, PushPayload>;
 }
@@ -390,6 +606,8 @@ interface RoutingPushOptions {
 declare const routingPushProvider: (options: RoutingPushOptions) => Provider<unknown, PushPayload>;
 /** A resolved, ready-to-wire set of channel configs (edge-safe channels only). */
 interface ResolvedProviders {
+  /** The definition's `allowedPushOrigins`, threaded to the push router's send-time SSRF guard. */
+  allowedPushOrigins?: string[];
   chat?: Provider;
   fcm?: FcmConfig;
   inApp?: Provider;
@@ -407,53 +625,147 @@ declare const buildEngine: (resolved: ResolvedProviders) => Notification;
  * A broadcast job body — the JSON-serialisable payload enqueued for off-request
  * fan-out. Shaped to travel through a `@lunora/queue` producer/consumer without
  * `@lunora/notify` depending on `@lunora/queue` (the seam stays structural).
+ * `filter.after`, when set, resumes a broadcast partway through (see
+ * {@link runPushBroadcastPage}'s continuation semantics).
  */
 interface PushBroadcastJob {
-  /** Subscription filter (which devices/users to target). */
+  /** Subscription filter (which devices/users to target; `filter.after` resumes a paged broadcast). */
   filter?: SubscriptionFilter;
   /** The push payload to deliver (the `to` target is derived per subscription). */
   payload: PushContent;
+  /**
+   * Redeliver to exactly these subscription ids instead of walking a page —
+   * an earlier page's {@link PushBroadcastPageOutcome.failedIds}. Set by the
+   * consumer when it re-enqueues a page's transient failures; `filter` is
+   * ignored on such a job. See {@link runPushBroadcastPage}.
+   */
+  retryIds?: string[];
   /** Discriminator so a shared queue can multiplex message kinds. */
   type: "lunora.push.broadcast";
 }
-/** The structural slice of a `@lunora/queue` producer (`ctx.queues.&lt;name>`) used here. */
+/**
+ * One page's outcome plus the ids that need redelivering.
+ *
+ * The consumer MUST act on BOTH fields: `nextFilter` continues the broadcast and
+ * `failedIds` redelivers the recipients this page missed. Acking a message while
+ * ignoring either silently drops part of the audience.
+ */
+interface PushBroadcastPageOutcome {
+  /**
+   * Subscriptions that failed transiently on this run (gone/pruned devices are
+   * NOT here — they are deleted, not retried). Re-enqueue a job carrying these
+   * as `retryIds` to redeliver to just them.
+   */
+  failedIds: string[];
+  /**
+   * The filter for the CONTINUATION job, or `undefined` when the broadcast is
+   * finished (no further pages, or `filter.limit` is spent). Enqueue it
+   * verbatim — it carries the next page's cursor AND, when the job set
+   * `filter.limit`, the REMAINING budget.
+   *
+   * This replaces the raw `nextCursor` the runner used to return. Rebuilding
+   * the filter at the call site (`{ ...job.filter, after: nextCursor }`)
+   * forwarded the ORIGINAL `limit` to every message, so a `limit` documented
+   * as an overall audience cap (see {@link SubscriptionFilter.limit}, which
+   * `broadcast` honours as one) became a per-message cap and the walk reached
+   * the entire audience anyway.
+   */
+  nextFilter?: SubscriptionFilter;
+  /** This page's delivery result. */
+  result: BroadcastResult;
+}
+/** The structural slice of a `@lunora/queue` producer (`ctx.queues.<name>`) used here. */
 interface QueueProducerLike {
   send: (body: PushBroadcastJob) => Promise<void>;
 }
 /**
  * Enqueue a fan-out broadcast for background delivery through a `@lunora/queue`
- * queue instead of blocking the request. Pair with {@link runPushBroadcastJob} in
- * the queue consumer.
+ * queue instead of blocking the request. Pair with {@link runPushBroadcastPage} in
+ * the queue consumer — see its doc comment for how a large audience continues
+ * across MULTIPLE messages (one bounded page per message), not one.
  *
  * ```ts
- * // in a mutation/action:
- * await enqueuePushBroadcast(ctx.queues.push, { payload: { title: "New drop", body: "…" } });
+ * // lunora/notify-fanout.ts — an INTERNAL ACTION, because that is where
+ * // `ctx.push` and `ctx.queues` exist.
+ * import { internalAction, v } from "./_generated/server";
+ * import { enqueuePushBroadcast, runPushBroadcastPage } from "@lunora/notify";
  *
- * // in lunora/queues.ts consumer:
- * export const push = defineQueue({ async handler(batch, ctx) {
- *     for (const message of batch.messages) await runPushBroadcastJob(ctx.push, message.body);
- * }});
+ * export const deliverPage = internalAction
+ *     .input({ job: v.any() })
+ *     .action(async ({ args: { job }, ctx }) => {
+ *         const { failedIds, nextFilter } = await runPushBroadcastPage(ctx.push, job);
+ *
+ *         if (nextFilter !== undefined) {
+ *             // More pages remain — enqueue the continuation. Each message still
+ *             // does only ONE bounded page of work. Pass `nextFilter` VERBATIM:
+ *             // it carries the cursor and the remaining `limit` budget.
+ *             await enqueuePushBroadcast(ctx.queues.push, { filter: nextFilter, payload: job.payload });
+ *         }
+ *
+ *         if (failedIds.length > 0) {
+ *             // Redeliver ONLY the recipients that failed — never the whole page.
+ *             await enqueuePushBroadcast(ctx.queues.push, { payload: job.payload, retryIds: failedIds });
+ *         }
+ *     });
+ *
+ * // lunora/queues.ts — the consumer itself has NO ctx.push / ctx.queues: a
+ * // `QueueRunContext` is exactly `{ env, log, run }` (handler signature
+ * // `(context, batch)`, in that order). It hands each message to the action above.
+ * 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();
+ *         }
+ *     },
+ * });
+ *
+ * // in a mutation/action, to start it:
+ * await enqueuePushBroadcast(ctx.queues.push, { payload: { body: "…", title: "New drop" } });
  * ```
  */
 declare const enqueuePushBroadcast: (queue: QueueProducerLike, job: Omit<PushBroadcastJob, "type">) => Promise<void>;
 /**
- * Run an enqueued broadcast job on the consumer side, delivering through the push
- * facade (which reuses the engine's retry + circuit-breaker middleware and prunes
- * gone subscriptions).
+ * Run ONE bounded page of an enqueued broadcast job on the consumer side,
+ * delivering through the push facade's {@link LunoraPush.broadcastPage} (which
+ * reuses the engine's retry + circuit-breaker middleware and prunes gone
+ * subscriptions).
+ *
+ * RETRY / CONTINUATION SEMANTICS:
  *
- * RETRY SEMANTICS: retry is gated on `failed` — the count of TRANSIENT delivery
- * errors (a provider 5xx / network fault worth another attempt). When at least one
- * recipient `failed`, the job is RE-THROWN so the queue does NOT ack it and its
- * normal retry/backoff (and, on exhaustion, dead-letter) applies. A broadcast with
- * zero `failed` resolves and is acked — this includes the all-`pruned` case (every
- * device had unsubscribed: `sent:0`, `failed:0`, `pruned:N`), which is a SUCCESSFUL
- * prune, not a failure, so throwing on it would spuriously retry and pressure the
- * DLQ; and the empty audience (zero `total`), which has nothing to retry. Note a
- * retry re-runs the WHOLE broadcast, re-sending to the already-delivered recipients
- * (broadcast is not idempotent) — the accepted cost of getting the transiently
- * failed ones redelivered.
+ * - A job processes exactly ONE bounded page (see `defineNotify`'s
+ * `broadcastPageSize`, default 250, or `job.filter.limit` when smaller),
+ * keyset-paginated on the subscription `id` (see `SubscriptionFilter.after`)
+ * — so per-message work is bounded regardless of total audience size.
+ * - A page NEVER throws for a partial failure. Throwing discarded the page's
+ * continuation, which is the only way the broadcast advances: one device that
+ * fails permanently (a rotated VAPID keypair leaves a stale device answering
+ * `403 VapidPkHashMismatch` forever) would then stall the cursor, re-POST
+ * every already-delivered recipient on each retry, dead-letter, and leave
+ * every LATER page unreached. The page's `nextFilter` and its `failedIds`
+ * both come back instead.
+ * - The CALLER re-enqueues: `filter: nextFilter` while more pages remain, and a
+ * `retryIds: failedIds` job when any recipient failed. `@lunora/notify` cannot
+ * do it itself — it has no `@lunora/queue` dependency (the seam stays
+ * structural) and no reference to the producer that enqueued this message. See
+ * the consumer example on {@link enqueuePushBroadcast}.
+ * - `job.filter.limit` is spent across messages, not re-granted to each one:
+ * `nextFilter` carries the REMAINING budget and is `undefined` once it runs
+ * out, so `limit` caps the whole audience here exactly as it does on
+ * {@link LunoraPush.broadcast}.
+ * - A `retryIds` job redelivers to exactly those ids and throws only while ALL
+ * of them still fail, so the queue's backoff/dead-letter bounds a device that
+ * never recovers. Once any recipient recovers the run resolves and reports the
+ * rest in `failedIds`, so the narrower retry never re-sends to a device this
+ * message already reached. A recipient that turns out to be GONE — a 404/410
+ * receipt, or an id whose row no longer exists at all — counts as `pruned` here
+ * too, never as a failure: there is nothing left to redeliver to, so retrying it
+ * could only burn the queue's budget and dead-letter an unsubscribe.
+ * - Gone subscriptions (Web Push 404/410, FCM's `NOT_FOUND` for a dead token) are pruned by the page and
+ * never appear in `failedIds` — an all-`pruned` page is a success, not a
+ * failure, as is an empty page.
  */
-declare const runPushBroadcastJob: (push: LunoraPush, job: PushBroadcastJob) => Promise<BroadcastResult>;
+declare const runPushBroadcastPage: (push: LunoraPush, job: PushBroadcastJob) => Promise<PushBroadcastPageOutcome>;
 /**
  * The minimal structural slice of Cloudflare's `D1Database` this store uses. A
  * structural type (rather than importing `@cloudflare/workers-types`) keeps the
@@ -505,7 +817,21 @@ declare const d1SubscriptionStore: (database: D1Like, options?: D1StoreOptions)
  */
 declare const memorySubscriptionStore: () => SubscriptionStore;
 /**
- * Stable store id for a web-push endpoint.
+ * Stable store id for a web-push endpoint — `fnv1a64Hex` of the (long) endpoint,
+ * so re-registering the same device upserts rather than duplicates.
+ *
+ * The digest comes from the canonical `shared/fnv1a`, not a local copy. This id
+ * is a PERSISTED primary key: a digest that drifts in one copy silently re-keys
+ * every existing subscription — the old row goes dark and the device
+ * re-registers as a duplicate — so the implementation must have exactly one
+ * home. `shared/fnv1a`'s is bit-verified against a BigInt reference in
+ * `packages/replica/__tests__/apply-diff.test.ts`.
+ *
+ * Widened from the previous 32-bit FNV-1a (8 hex): at 100K devices a 32-bit key
+ * collides with ~68% probability (birthday bound), and a collision silently
+ * overwrites another device's row under the store's `ON CONFLICT(id) DO UPDATE` —
+ * so the wrong user gets the push and the victim goes dark. 64 bits drops that to
+ * negligible at any realistic device count.
  *
  * The `wp2_` prefix is a version tag (see also {@link fcmId}'s `fcm2_`): it marks
  * the 64-bit-id revision so the pre-existing 32-bit `wp_` rows stay readable and a
@@ -526,9 +852,10 @@ interface NormalizeOptions {
    *
    * When unset, the default posture applies: `https:` scheme + a host the
    * {@link assertPushEndpoint} STRING classifier does not flag as
-   * private/loopback. That classifier does NOT resolve DNS, so a public hostname
-   * resolving to a private/internal IP (e.g. `https://127.0.0.1.nip.io/…`) is NOT
-   * blocked by it — set this allowlist to close that gap.
+   * private/loopback, plus a resolved-address re-check at send time. Setting
+   * this allowlist replaces both with an exact-origin match — the hard
+   * guarantee, and the only one that also covers an internal push service you
+   * deliberately want to reach.
    */
   allowedPushOrigins?: string[];
 }
@@ -536,7 +863,8 @@ interface NormalizeOptions {
  * Normalise a `register(...)` input into a {@link StoredSubscription}. Validates
  * the shape (a web-push subscription needs `endpoint` + `keys.{p256dh,auth}`; an
  * FCM entry needs a non-empty `token`), enforces the anti-SSRF endpoint boundary
- * (see {@link assertPushEndpoint}), and stamps `createdAt`/`lastSeenAt`.
+ * (see {@link assertPushEndpoint}), validates `metadata` (see
+ * {@link validateMetadata}), and stamps `createdAt`/`lastSeenAt`.
  */
 declare const normalizeRegisterInput: (input: RegisterInput, now?: number, options?: NormalizeOptions) => StoredSubscription;
 /**
@@ -550,11 +878,97 @@ declare const targetOf: (subscription: StoredSubscription) => string;
  * (the browser/device unsubscribed) and should be pruned — as opposed to a
  * transient failure worth retrying.
  *
- * Gates on STRUCTURED signals first: a Web Push `HTTP 404/410` status or an FCM
- * `UNREGISTERED`/`NOT_REGISTERED` code, both of which the providers surface in
- * their failure receipts. The free-text {@link GONE_TEXT_FALLBACK} is a tightened
- * last resort only, so a transient error that happens to contain `expired`
- * (a cert/session expiry) can never permanently drop a valid subscription.
+ * Gates on STRUCTURED signals first: an `HTTP 404/410` status (both providers
+ * answer one for a dead endpoint/token, though FCM's is usually replaced by its
+ * error body before it reaches here) or, for FCM only, an
+ * `UNREGISTERED`/`NOT_REGISTERED` code or the `NOT_FOUND` prose that is the one
+ * signal its provider actually forwards (see {@link FCM_GONE_PATTERN}). The
+ * free-text {@link GONE_TEXT_FALLBACK} is a tightened last resort only, so a
+ * transient error that happens to contain `expired` (a cert/session expiry) can
+ * never permanently drop a valid subscription.
+ *
+ * `kind` scopes the PROVIDER-SPECIFIC patterns to the provider that emits them.
+ * The web-push provider echoes the push service's response body into
+ * `HTTP ${status}: ${body}`, so a 4xx whose prose merely contains "not
+ * registered" matched the FCM-only codes and permanently deleted a live
+ * subscription. Omit `kind` (the third-party/unknown-provider case) to test
+ * every pattern, as before.
+ */
+declare const isGoneError: (message: string | undefined, kind?: StoredSubscription["kind"]) => boolean;
+export { type BroadcastOutcome, type BroadcastResult, type CreateNotifyOptions, type D1Like, type D1PreparedLike, type D1StoreOptions,
+/**
+ * `@lunora/notify`
+ *
+ * Multi-channel notifications for Lunora, wrapping the `@visulima/notification`
+ * engine. `defineNotify` in `lunora/notify.ts` configures the edge-safe channels
+ * (Web Push + FCM, plus chat / in-app inbox / webhook); codegen wires `ctx.notify`
+ * and its `ctx.push` alias onto every handler ctx from it (mirroring `defineFlags`
+ * → `ctx.flags`).
+ *
+ * Edge-safety: Web Push (VAPID + RFC 8291) and FCM (HTTP v1) run on `fetch` + Web
+ * Crypto under workerd. APNs (`node:http2`) and SMS / Node-only queue adapters are
+ * deliberately **not** on the edge facade — route heavy fan-out through
+ * `@lunora/queue` (`enqueuePushBroadcast` / `runPushBroadcastPage`).
+ *
+ * - `@lunora/notify` — `defineNotify`, `createNotify`, config resolvers, subscription stores and types.
+ * - `@lunora/notify/web` — the browser `subscribeToPush` service-worker helper.
+ * @packageDocumentation
+ */
+FCM_ENV_KEYS, type FcmConfigFactory, type LunoraNotify, type LunoraPush, type NotifyConfig, type NotifyDefinition, type NotifyDeliveryStatus, type NotifyEnv, type NotifyLogger, type NotifyMetrics, type NotifySkipReason, type PushBroadcastJob, type PushBroadcastPageOutcome, type PushOwner, type PushSubscriptionDevice, type PushSubscriptionsResult, type QueueProducerLike, type RegisterInput, type ResolvedProviders, type RoutingPushOptions, type StoredSubscription, type SubscriptionFilter, type SubscriptionKind, type SubscriptionStatus, type SubscriptionStore,
+/**
+ * `@lunora/notify`
+ *
+ * Multi-channel notifications for Lunora, wrapping the `@visulima/notification`
+ * engine. `defineNotify` in `lunora/notify.ts` configures the edge-safe channels
+ * (Web Push + FCM, plus chat / in-app inbox / webhook); codegen wires `ctx.notify`
+ * and its `ctx.push` alias onto every handler ctx from it (mirroring `defineFlags`
+ * → `ctx.flags`).
+ *
+ * Edge-safety: Web Push (VAPID + RFC 8291) and FCM (HTTP v1) run on `fetch` + Web
+ * Crypto under workerd. APNs (`node:http2`) and SMS / Node-only queue adapters are
+ * deliberately **not** on the edge facade — route heavy fan-out through
+ * `@lunora/queue` (`enqueuePushBroadcast` / `runPushBroadcastPage`).
+ *
+ * - `@lunora/notify` — `defineNotify`, `createNotify`, config resolvers, subscription stores and types.
+ * - `@lunora/notify/web` — the browser `subscribeToPush` service-worker helper.
+ * @packageDocumentation
+ */
+WEB_PUSH_ENV_KEYS, type WebPushConfigFactory, buildEngine, createNotify, d1SubscriptionStore, defineNotify, enqueuePushBroadcast,
+/**
+ * `@lunora/notify`
+ *
+ * Multi-channel notifications for Lunora, wrapping the `@visulima/notification`
+ * engine. `defineNotify` in `lunora/notify.ts` configures the edge-safe channels
+ * (Web Push + FCM, plus chat / in-app inbox / webhook); codegen wires `ctx.notify`
+ * and its `ctx.push` alias onto every handler ctx from it (mirroring `defineFlags`
+ * → `ctx.flags`).
+ *
+ * Edge-safety: Web Push (VAPID + RFC 8291) and FCM (HTTP v1) run on `fetch` + Web
+ * Crypto under workerd. APNs (`node:http2`) and SMS / Node-only queue adapters are
+ * deliberately **not** on the edge facade — route heavy fan-out through
+ * `@lunora/queue` (`enqueuePushBroadcast` / `runPushBroadcastPage`).
+ *
+ * - `@lunora/notify` — `defineNotify`, `createNotify`, config resolvers, subscription stores and types.
+ * - `@lunora/notify/web` — the browser `subscribeToPush` service-worker helper.
+ * @packageDocumentation
+ */
+fcmFromEnv, fcmId, isGoneError, isNotifyDefinition, memorySubscriptionStore, normalizeRegisterInput, routingPushProvider, runPushBroadcastPage, targetOf,
+/**
+ * `@lunora/notify`
+ *
+ * Multi-channel notifications for Lunora, wrapping the `@visulima/notification`
+ * engine. `defineNotify` in `lunora/notify.ts` configures the edge-safe channels
+ * (Web Push + FCM, plus chat / in-app inbox / webhook); codegen wires `ctx.notify`
+ * and its `ctx.push` alias onto every handler ctx from it (mirroring `defineFlags`
+ * → `ctx.flags`).
+ *
+ * Edge-safety: Web Push (VAPID + RFC 8291) and FCM (HTTP v1) run on `fetch` + Web
+ * Crypto under workerd. APNs (`node:http2`) and SMS / Node-only queue adapters are
+ * deliberately **not** on the edge facade — route heavy fan-out through
+ * `@lunora/queue` (`enqueuePushBroadcast` / `runPushBroadcastPage`).
+ *
+ * - `@lunora/notify` — `defineNotify`, `createNotify`, config resolvers, subscription stores and types.
+ * - `@lunora/notify/web` — the browser `subscribeToPush` service-worker helper.
+ * @packageDocumentation
  */
-declare const isGoneError: (message: string | undefined) => boolean;
-export { type BroadcastOutcome, type BroadcastResult, type CreateNotifyOptions, type D1Like, type D1PreparedLike, type D1StoreOptions, FCM_ENV_KEYS, type FcmConfigFactory, type LunoraNotify, type LunoraPush, type NotifyConfig, type NotifyDefinition, type NotifyDeliveryStatus, type NotifyEnv, type NotifyLogger, type NotifyMetrics, type NotifySkipReason, type PushBroadcastJob, type PushSubscriptionDevice, type PushSubscriptionsResult, type QueueProducerLike, type RegisterInput, type ResolvedProviders, type RoutingPushOptions, type StoredSubscription, type SubscriptionFilter, type SubscriptionKind, type SubscriptionStatus, type SubscriptionStore, WEB_PUSH_ENV_KEYS, type WebPushConfigFactory, buildEngine, createNotify, d1SubscriptionStore, defineNotify, enqueuePushBroadcast, fcmFromEnv, fcmId, isGoneError, isNotifyDefinition, memorySubscriptionStore, normalizeRegisterInput, routingPushProvider, runPushBroadcastJob, targetOf, webPushFromEnv, webPushId };
+webPushFromEnv, webPushId };