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

package/dist/index.d.ts

@@ -15,6 +15,15 @@ type NotifyEnv = Record<string, unknown>;
 type SubscriptionKind = "fcm" | "web-push";
 /** The last-known delivery outcome recorded on a subscription. */
 type SubscriptionStatus = "expired" | "failed" | "ok";
+/** The delivery outcomes of one broadcast page, grouped for {@link SubscriptionStore.applyOutcomes}. */
+interface SubscriptionOutcomes {
+  failed: {
+    error?: string;
+    id: string;
+  }[];
+  gone: string[];
+  ok: string[];
+}
 /**
  * A registered device/browser subscription. Web Push carries a W3C Push API
  * `endpoint` + `keys`; FCM carries a device registration `token`. `id` is a
@@ -111,9 +120,20 @@ interface SubscriptionFilter {
    * 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
-   * `CreateNotifyOptions`'s `broadcastPageSize`, default 250) so a caller
+   * `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. */
@@ -125,8 +145,39 @@ interface SubscriptionFilter {
  * and a D1-backed store (durable, edge-safe).
  */
 interface SubscriptionStore {
+  /**
+   * Apply a whole broadcast page's delivery outcomes at once (best-effort):
+   * `ok` ids are marked ok, `failed` ids marked failed with their error, `gone`
+   * ids deleted. OPTIONAL — when absent, `broadcast` calls `markStatus` /
+   * `delete` per id.
+   */
+  applyOutcomes?: (outcomes: SubscriptionOutcomes) => Promise<void>;
   /** 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>;
   /**
@@ -139,7 +190,33 @@ interface SubscriptionStore {
   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`. */
@@ -183,7 +260,7 @@ interface BroadcastPageResult {
  *
  * - `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.
@@ -228,26 +305,28 @@ 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 a huge audience is never
-   * materialized wholesale in the isolate — see `CreateNotifyOptions`'s
-   * `broadcastPageSize`. This call still processes the WHOLE matched
-   * audience in one request/queue message; use {@link LunoraPush.broadcastPage}
-   * directly (as `runPushBroadcastJob` does) to bound a single queue message
-   * to one page.
+   * 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: `CreateNotifyOptions`'s `broadcastPageSize`, default
+   * `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 `runPushBroadcastJob` so one queue message does bounded work
+   * Backs `runPushBroadcastPage` so one queue message does bounded work
    * regardless of audience size — most app code should call
    * {@link LunoraPush.broadcast} instead.
    */
@@ -256,18 +335,66 @@ interface LunoraPush {
    * 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>;
 }
-/** A push payload without its `to` target — the facade derives `to` from the stored subscription. */
+/** 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. Its `ttl` / `urgency` override the channel defaults per
+ * message on every push transport (Web Push, FCM, APNs, Expo).
+ */
 type PushContent = Omit<PushPayload, "to">;
 /**
  * The multi-channel notification facade — spliced onto ctx as `ctx.notify`.
@@ -276,7 +403,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>;
@@ -284,7 +411,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>;
 }
 /**
@@ -312,11 +439,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. */
@@ -405,14 +553,18 @@ interface CreateNotifyOptions {
   /**
    * Page size for `push.broadcast`'s internal keyset pagination over the
    * subscription store (default {@link DEFAULT_BROADCAST_PAGE_SIZE}, 250).
-   * Each page is fetched, delivered, and counted independently 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 so `runPushBroadcastJob`) uses. A test/tuning seam — most apps never
-   * need to set this.
+   *
+   * 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). */
+  /**
+   * 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
@@ -456,7 +608,19 @@ 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>;
+  /**
+   * Backoff base for the in-router group retry, in ms (default 250 — the
+   * engine's own). Only a TEST double passes anything else, for the same
+   * reason {@link ResilienceOptions.retryBaseDelay} exists: a mock that fails
+   * on purpose would otherwise spend the real ~1 s of backoff per partial.
+   */
+  retryBaseDelay?: number;
   webPush?: Provider<unknown, PushPayload>;
 }
 /**
@@ -469,6 +633,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;
@@ -487,45 +653,102 @@ declare const buildEngine: (resolved: ResolvedProviders) => Notification;
  * 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 runPushBroadcastJob}'s continuation semantics).
+ * {@link runPushBroadcastPage}'s continuation semantics).
  */
 interface PushBroadcastJob {
   /** 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
+ * 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) {
- *         const { nextCursor } = 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 (nextCursor !== undefined) {
+ *         if (nextFilter !== undefined) {
  *             // More pages remain — enqueue the continuation. Each message still
- *             // does only ONE bounded page of work.
- *             await enqueuePushBroadcast(ctx.queues.push, {
- *                 payload: message.body.payload,
- *                 filter: { ...message.body.filter, after: nextCursor },
- *             });
+ *             // 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>;
@@ -535,43 +758,48 @@ declare const enqueuePushBroadcast: (queue: QueueProducerLike, job: Omit<PushBro
  * reuses the engine's retry + circuit-breaker middleware and prunes gone
  * subscriptions).
  *
- * RETRY / CONTINUATION SEMANTICS (rewritten for plan 222 / NOTIFY-01 — a
- * broadcast job used to process the WHOLE audience in one message, which could
- * exceed Worker CPU/wall limits for a large audience and made a retry re-run
- * everything):
+ * RETRY / CONTINUATION SEMANTICS:
  *
- * - A job now processes exactly ONE bounded page (see `CreateNotifyOptions`'s
- * page-size option, default 250, or `job.filter.limit` when smaller),
+ * - 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.
- * - Retry is still gated on `result.failed` — the count of TRANSIENT delivery
- * errors (a provider 5xx / network fault worth another attempt). When at
- * least one recipient in THIS PAGE `failed`, the job is RE-THROWN so the
- * queue does NOT ack it and its normal retry/backoff (and, on exhaustion,
- * dead-letter) applies — to just this page, not the whole broadcast.
- * - A page with zero `failed` resolves and is acked — this includes the
- * all-`pruned` case (every device on the page 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-page case (zero `total`), which has nothing to retry.
- * - The returned `nextCursor` is set when more pages remain. `@lunora/notify`
- * does NOT enqueue the continuation itself — it has no `@lunora/queue`
- * dependency (the seam stays structural) and no reference to the producer
- * that enqueued this message — so the CALLER (the `lunora/queues.ts`
- * consumer) is responsible for re-enqueueing with `filter.after: nextCursor`
- * when present. See the consumer example on {@link enqueuePushBroadcast}.
- * - A retry of a page redelivers only that page's already-delivered recipients
- * on a transient partial failure (a page is not individually idempotent) —
- * the accepted cost of getting the transiently failed ones redelivered, now
- * scoped to one page instead of the whole broadcast.
- */
-declare const runPushBroadcastJob: (push: LunoraPush, job: PushBroadcastJob) => Promise<BroadcastPageResult>;
+ * - 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 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
  * store runtime-agnostic and trivially fakeable in tests.
  */
 interface D1Like {
+  batch: (statements: D1PreparedLike[]) => Promise<unknown>;
   prepare: (query: string) => D1PreparedLike;
 }
 interface D1PreparedLike {
@@ -587,27 +815,6 @@ interface D1StoreOptions {
   /** Table name (default `lunora_push_subscriptions`). Must be a bare identifier. */
   tableName?: string;
 }
-/**
- * A D1-backed {@link SubscriptionStore}. Edge-safe (D1 is a Worker binding). The
- * backing table is created lazily on first use (`CREATE TABLE IF NOT EXISTS`), so
- * no migration step is required for the subscription table itself.
- *
- * ID SCHEME / LAZY MIGRATION: `id` (the `PRIMARY KEY`, upserted via `ON
- * CONFLICT(id) DO UPDATE`) is a version-prefixed digest of the endpoint/token —
- * currently `wp2_`/`fcm2_` (64-bit FNV-1a; see `normalize.ts`). No table migration
- * runs when the id scheme is revised: a returning device re-registers under its new
- * id and upserts a fresh row, while its old-prefix row (`wp_`/`fcm_`) ages out via
- * the normal gone-pruning on the next failed send. So a table can transiently hold
- * both an old- and new-prefix row for one device — expected, self-healing, and the
- * reason a prefix must NEVER be reused for a different scheme.
- *
- * ```ts
- * export default defineNotify({
- *     webPush: (env) => webPushFromEnv(env),
- *     store: (env) => d1SubscriptionStore(env.DB),
- * });
- * ```
- */
 declare const d1SubscriptionStore: (database: D1Like, options?: D1StoreOptions) => SubscriptionStore;
 /**
  * An in-memory {@link SubscriptionStore} — the zero-dependency default. Suitable
@@ -617,7 +824,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
@@ -638,9 +859,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[];
 }
@@ -663,11 +885,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 SubscriptionOutcomes, 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 };