@lunora/notify 0.0.0 → 1.0.0-alpha.10

package/dist/index.d.ts

@@ -0,0 +1,684 @@
+import { FcmConfig } from '@visulima/notification/providers/fcm';
+export type { FcmConfig } from '@visulima/notification/providers/fcm';
+import { PushSubscriptionLike, WebPushConfig } from '@visulima/notification/providers/web-push';
+export type { PushSubscriptionLike, WebPushConfig } from '@visulima/notification/providers/web-push';
+import { ChatPayload, Receipt, InAppPayload, PushPayload, NotificationMessage, WebhookPayload, Notification, Provider } from '@visulima/notification';
+export type { ChatPayload, InAppPayload, NotificationMessage, PushPayload, Receipt, WebhookPayload } from '@visulima/notification';
+/**
+ * A Worker `env` projected as a plain record (vars, secrets and bindings are
+ * `unknown`-valued). `defineNotify` factories receive this so a config can read
+ * VAPID/FCM secrets and pick bindings (D1, Queues) at request/isolate time —
+ * mirroring the `config.ai?.(env)` / flags `provider(env)` thunk pattern.
+ */
+type NotifyEnv = Record<string, unknown>;
+/** The delivery kind a stored device subscription targets. */
+type SubscriptionKind = "fcm" | "web-push";
+/** The last-known delivery outcome recorded on a subscription. */
+type SubscriptionStatus = "expired" | "failed" | "ok";
+/**
+ * A registered device/browser subscription. Web Push carries a W3C Push API
+ * `endpoint` + `keys`; FCM carries a device registration `token`. `id` is a
+ * stable, storage-safe identifier derived from the target (see `subscriptionId`).
+ */
+interface StoredSubscription {
+  /** Unix-ms creation time. */
+  createdAt: number;
+  /** Web Push service endpoint URL (web-push only). */
+  endpoint?: string;
+  /** Stable identifier (endpoint/token derived) used as the store key. */
+  id: string;
+  /** Web Push client keys (web-push only). */
+  keys?: {
+    auth: string;
+    p256dh: string;
+  };
+  /** The delivery channel this subscription targets. */
+  kind: SubscriptionKind;
+  /** Last delivery error message, when `lastStatus` is `failed`/`expired`. */
+  lastError?: string;
+  /** Unix-ms time of the most recent register/send touch. */
+  lastSeenAt: number;
+  /** Last-known delivery outcome. */
+  lastStatus?: SubscriptionStatus;
+  /** Arbitrary app metadata (device name, locale, topics, …). */
+  metadata?: Record<string, unknown>;
+  /** FCM device registration token (fcm only). */
+  token?: string;
+  /** Owning user id, or `null` when anonymous. */
+  userId?: string | null;
+}
+/**
+ * The admin-facing projection of a {@link StoredSubscription} — a registered
+ * device as surfaced by the gated `__lunora_admin__:listPushSubscriptions` RPC
+ * (backing the Studio Notifications page). The delivery **secrets** are dropped:
+ * the Web Push `keys` (the RFC 8291 `auth`/`p256dh` encryption material) and the
+ * FCM `token` are never sent to the browser — only the endpoint / kind / owner /
+ * timestamps and the last-send status + error the page renders.
+ */
+type PushSubscriptionDevice = Omit<StoredSubscription, "keys" | "token">;
+/** Payload of a `__lunora_admin__:listPushSubscriptions` call — the registered devices, secrets redacted. */
+interface PushSubscriptionsResult {
+  /** The registered device subscriptions matching the request filter (secrets stripped). */
+  subscriptions: PushSubscriptionDevice[];
+}
+/** Input accepted by `ctx.push.register(...)` — a web-push subscription or an FCM token. */
+type RegisterInput = {
+  kind?: "web-push";
+  metadata?: Record<string, unknown>;
+  subscription: PushSubscriptionLike | string;
+  userId?: string | null;
+} | {
+  kind: "fcm";
+  metadata?: Record<string, unknown>;
+  token: string;
+  userId?: string | null;
+};
+/** 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.
+   *
+   * 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
+   * `CreateNotifyOptions`'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. */
+  userId?: string | null;
+}
+/**
+ * Persistence for device subscriptions. Implementations back `ctx.push`'s
+ * lifecycle (register, list, prune). Ships with an in-memory store (tests/dev)
+ * and a D1-backed store (durable, edge-safe).
+ */
+interface SubscriptionStore {
+  /** Remove a subscription by id (idempotent). */
+  delete: (id: string) => Promise<void>;
+  /** Read a subscription by id, or `undefined`. */
+  get: (id: string) => Promise<StoredSubscription | undefined>;
+  /**
+   * 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). */
+  put: (subscription: StoredSubscription) => Promise<StoredSubscription>;
+}
+/** Per-recipient outcome from a fan-out `broadcast`. */
+interface BroadcastOutcome {
+  /** Delivery error message when `status` is not `ok`. */
+  error?: string;
+  /** The subscription this outcome belongs to. */
+  id: string;
+  /** `expired` subscriptions were pruned from the store. */
+  status: SubscriptionStatus;
+}
+/** Aggregate result of a `broadcast`. */
+interface BroadcastResult {
+  /** Number of subscriptions that failed (non-gone). */
+  failed: number;
+  /** Per-subscription outcomes. */
+  outcomes: BroadcastOutcome[];
+  /** Number of pruned (gone/expired) subscriptions. */
+  pruned: number;
+  /** Number of subscriptions delivered successfully. */
+  sent: number;
+  /** 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
+ * log line. Modeled on Novu's execution status, but honest to edge push:
+ *
+ * - `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.
+ *
+ * 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.
+ * The one place a later `seen`/`read` is real is the in-app inbox, where the
+ * client posts a read receipt back — out of scope here.
+ */
+type NotifyDeliveryStatus = "accepted" | "failed" | "gone";
+/**
+ * Why a send fanned out to nobody — the "sent 0 because…" signal (mirrors Novu's
+ * pre-send `DetailEnum` reasons). Emitted as the `reason` dimension on a
+ * `notify.skipped` metric so a no-op is visible in the Studio metric/trend view
+ * instead of silent.
+ *
+ * - `no-subscriptions-matched` — the store held no device for the broadcast filter.
+ * - `channel-not-configured` — the target channel was never wired in `defineNotify`.
+ */
+type NotifySkipReason = "channel-not-configured" | "no-subscriptions-matched";
+/**
+ * The minimal structural slice of `ctx.log` the notify facade emits through — just
+ * the `warn` severity it uses for a failed delivery. Structural (rather than a
+ * dependency on `@lunora/server`'s `LunoraLogger`) so codegen passes the real
+ * `ctx.log` and a test passes a spy — the D1-store `D1Like` pattern, applied to
+ * observability.
+ */
+interface NotifyLogger {
+  warn: (message: string, fields?: Record<string, unknown>) => void;
+}
+/**
+ * The minimal structural slice of `ctx.metrics` the notify facade emits through —
+ * the `count` instrument backing the `notify.send` / `notify.skipped` series.
+ * Structural for the same reason as {@link NotifyLogger}.
+ */
+interface NotifyMetrics {
+  count: (name: string, value?: number, attributes?: Record<string, unknown>) => void;
+}
+/**
+ * The push sub-facade — spliced onto ctx as `ctx.push` (and reachable as
+ * `ctx.notify.push`). Owns the device-subscription lifecycle plus targeted and
+ * fan-out push delivery through the edge-safe Web Push / FCM providers.
+ */
+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`
+   * 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.
+   */
+  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
+   * 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
+   * 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
+   * reachable only through the internal `SubscriptionStore`.
+   */
+  list: (filter?: SubscriptionFilter) => Promise<PushSubscriptionDevice[]>;
+  /** Register (upsert) a device subscription and return the stored record. */
+  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>;
+}
+/** A push payload without its `to` target — the facade derives `to` from the stored subscription. */
+type PushContent = Omit<PushPayload, "to">;
+/**
+ * The multi-channel notification facade — spliced onto ctx as `ctx.notify`.
+ * `send` delivers a fully-specified multi-channel message through the engine;
+ * `push` is the device-push sub-facade; `chat` / `inApp` / `webhook` are
+ * single-channel convenience senders for the edge-safe channels.
+ */
+interface LunoraNotify {
+  /** Send an outbound webhook. */
+  chat: (payload: ChatPayload) => Promise<Receipt>;
+  /** Deliver an in-app inbox notification. */
+  inApp: (payload: InAppPayload) => Promise<Receipt>;
+  /** The device-push sub-facade (identical object to `ctx.push`). */
+  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). */
+  webhook: (payload: WebhookPayload) => Promise<Receipt>;
+}
+/**
+ * Resolves a channel provider factory from the Worker `env`. Receiving `env`
+ * (rather than a constructed provider) lets a config read VAPID/FCM secrets and
+ * bindings at request time. Return `undefined` to leave the channel unwired.
+ */
+type WebPushConfigFactory = (env: NotifyEnv) => WebPushConfig | undefined;
+type FcmConfigFactory = (env: NotifyEnv) => FcmConfig | undefined;
+/** Options accepted by `defineNotify`. */
+interface NotifyConfig {
+  /**
+   * Exact origins (`https://host[:port]`) a client-supplied Web Push `endpoint`
+   * may register from. When set (non-empty), `register()` requires the endpoint's
+   * origin to be one of these — the strongest anti-SSRF posture, and the way to
+   * close DNS rebinding for a facade that accepts client-controlled endpoints.
+   *
+   * When unset, the default posture applies: an endpoint must be `https:` with a
+   * host a STRING classifier does not flag as private / loopback / link-local.
+   * 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
+   * — `register()` also emits a one-shot dev warning in this case. Set this to the
+   * push services your app actually uses (e.g. `["https://fcm.googleapis.com",
+   * "https://updates.push.services.mozilla.com"]` — exact origins only, no
+   * wildcards) to hard-pin the boundary and close DNS rebinding.
+   */
+  allowedPushOrigins?: string[];
+  /**
+   * Optional chat provider factory (Slack/Discord/Teams/Telegram). Wire with a
+   * provider from `@visulima/notification/providers/*`. Edge-safe (fetch-based).
+   */
+  chat?: (env: NotifyEnv) => unknown;
+  /** FCM (Firebase Cloud Messaging HTTP v1) config. Edge-safe — supply an OAuth2 token. */
+  fcm?: FcmConfig | FcmConfigFactory;
+  /** Optional in-app inbox provider factory. Edge-safe. */
+  inApp?: (env: NotifyEnv) => unknown;
+  /**
+   * Builds the subscription store from `env` (usually a D1-backed store from a
+   * binding). Defaults to a non-durable in-memory store with a dev warning.
+   */
+  store?: (env: NotifyEnv) => SubscriptionStore;
+  /** Optional outbound-webhook provider factory. Edge-safe (fetch-based). */
+  webhook?: (env: NotifyEnv) => unknown;
+  /** Web Push (VAPID + RFC 8291) config. Fully edge-safe (Web Crypto only). */
+  webPush?: WebPushConfig | WebPushConfigFactory;
+}
+/**
+ * A branded {@link NotifyConfig} produced by `defineNotify`. This is the default
+ * export of `lunora/notify.ts`; codegen imports it into the generated worker and
+ * wires `ctx.notify` / `ctx.push` from it (mirroring `defineFlags` → `ctx.flags`).
+ */
+interface NotifyDefinition extends NotifyConfig {
+  /** Runtime brand used by `isNotifyDefinition` and codegen discovery. */
+  readonly isLunoraNotify: true;
+}
+/**
+ * `.dev.vars` / Worker `env` keys the built-in config resolvers read. Mirrored in
+ * `@lunora/config`'s package-secrets registry so `lunora dev` scaffolds them into
+ * `.dev.vars.example`.
+ */
+declare const WEB_PUSH_ENV_KEYS: {
+  readonly privateKey: "VAPID_PRIVATE_KEY";
+  readonly publicKey: "VAPID_PUBLIC_KEY";
+  readonly subject: "VAPID_SUBJECT";
+};
+declare const FCM_ENV_KEYS: {
+  readonly accessToken: "FCM_ACCESS_TOKEN";
+  readonly projectId: "FCM_PROJECT_ID";
+};
+/**
+ * Resolve a {@link WebPushConfig} from the Worker `env` VAPID secrets
+ * (`VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT`). Returns `undefined`
+ * when any is missing, leaving the Web Push channel unwired rather than throwing —
+ * so an app can ship FCM-only (or vice versa) without failing ctx construction.
+ *
+ * Generate a VAPID keypair once with `npx web-push generate-vapid-keys` (or any
+ * P-256 tool) and set `VAPID_SUBJECT` to a `mailto:` or `https:` contact.
+ */
+declare const webPushFromEnv: (env: NotifyEnv, overrides?: Partial<WebPushConfig>) => WebPushConfig | undefined;
+/**
+ * Resolve an {@link FcmConfig} from the Worker `env` (`FCM_PROJECT_ID` plus a
+ * static `FCM_ACCESS_TOKEN`). Returns `undefined` when the project id is missing.
+ *
+ * The static token is convenient for local dev but expires; in production prefer
+ * passing your own `getAccessToken` (e.g. wrapping `google-auth-library`) via
+ * `defineNotify({ fcm: (env) => ({ ...fcmFromEnv(env), getAccessToken }) })` —
+ * that keeps the provider edge-safe (no Google SDK / `node:crypto` bundled).
+ */
+declare const fcmFromEnv: (env: NotifyEnv, overrides?: Partial<FcmConfig>) => FcmConfig | undefined;
+/**
+ * Declare the notification channels for a Lunora app. Pure validation +
+ * branding — codegen discovers the default export of `lunora/notify.ts`, imports
+ * it into the generated worker, and wires `ctx.notify` / `ctx.push` from it
+ * (mirrors how `defineFlags` feeds codegen to build `ctx.flags`).
+ *
+ * ```ts
+ * // lunora/notify.ts
+ * import { defineNotify, webPushFromEnv, fcmFromEnv } from "@lunora/notify";
+ * import { d1SubscriptionStore } from "@lunora/notify";
+ *
+ * export default defineNotify({
+ *     webPush: (env) => webPushFromEnv(env),   // VAPID_* from .dev.vars
+ *     fcm: (env) => fcmFromEnv(env),           // FCM_PROJECT_ID / FCM_ACCESS_TOKEN
+ *     store: (env) => d1SubscriptionStore(env.DB),
+ * });
+ * ```
+ *
+ * Only edge-safe channels are wired here — Web Push and FCM run on Web Crypto +
+ * `fetch` under workerd. APNs (`node:http2`) and SMS/Node-only queue adapters are
+ * intentionally **not** exposed on the edge facade; route heavy fan-out through
+ * `@lunora/queue` instead (see `broadcastViaQueue`).
+ */
+declare const defineNotify: (config: NotifyConfig) => NotifyDefinition;
+/** True when a value is a {@link defineNotify} result (the runtime brand check). */
+declare const isNotifyDefinition: (value: unknown) => value is NotifyDefinition;
+/** Options for {@link createNotify}. */
+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.
+   */
+  broadcastPageSize?: number;
+  /** Max concurrent sends during a `broadcast` (default 10). */
+  concurrency?: number;
+  /**
+   * Override the assembled `@visulima/notification` engine. Advanced/testing
+   * seam — pass a `Notification` built with your own (mock) providers to bypass
+   * config resolution entirely.
+   */
+  engine?: Notification;
+  /**
+   * The request's `ctx.log` (structural {@link NotifyLogger}). Codegen threads
+   * `ctx.log` in; when present the facade emits one `warn` line per FAILED
+   * delivery — trace-correlated to the enclosing action and durably archived by
+   * the log sink. Successes and prunes stay off the log to keep the archive
+   * clean; they are counted on `metrics` instead. Absent ⇒ no log emits.
+   */
+  log?: NotifyLogger;
+  /**
+   * The request's `ctx.metrics` (structural {@link NotifyMetrics}). Codegen
+   * threads `ctx.metrics` in; when present the facade counts every send on the
+   * `notify.send` series (dimensions `channel` / `provider` / `status`) and every
+   * no-op on `notify.skipped` (`channel` / `reason`) — feeding the durable metric
+   * history + trend charts. Absent ⇒ no metric emits.
+   */
+  metrics?: NotifyMetrics;
+  /** Suppress the in-memory-store dev warning (tests set this). */
+  silent?: boolean;
+}
+/**
+ * Build the `ctx.notify` / `ctx.push` facades for a request from a
+ * {@link NotifyDefinition} (the `lunora/notify.ts` default export) and the Worker
+ * `env`. Codegen calls this to splice the facades onto ctx — the same shape as
+ * `createFlags` for `ctx.flags`. Returns both facades; `notify.push` is the very
+ * same object exposed as `ctx.push`.
+ *
+ * The engine and the dev fallback store are memoized per isolate (see
+ * {@link NotifyRuntime}), so repeat calls with the same `definition`/`env` are
+ * cheap — only the thin facade closures below are rebuilt each call.
+ */
+declare const createNotify: (definition: NotifyDefinition, env: NotifyEnv, options?: CreateNotifyOptions) => {
+  notify: LunoraNotify;
+  push: LunoraPush;
+};
+/** Options for {@link routingPushProvider}. */
+interface RoutingPushOptions {
+  fcm?: Provider<unknown, PushPayload>;
+  webPush?: Provider<unknown, PushPayload>;
+}
+/**
+ * A composite push {@link Provider} that dispatches each send to the Web Push or
+ * FCM provider by the shape of the payload `to` target — so a single `push`
+ * channel on the {@link Notification} facade transparently handles both browser
+ * subscriptions and mobile device tokens, and the engine's middleware wraps them
+ * uniformly.
+ */
+declare const routingPushProvider: (options: RoutingPushOptions) => Provider<unknown, PushPayload>;
+/** A resolved, ready-to-wire set of channel configs (edge-safe channels only). */
+interface ResolvedProviders {
+  chat?: Provider;
+  fcm?: FcmConfig;
+  inApp?: Provider;
+  webhook?: Provider;
+  webPush?: WebPushConfig;
+}
+/**
+ * Assemble the `@visulima/notification` engine from resolved channel configs and
+ * attach the reused retry + circuit-breaker middleware. Only edge-safe channels
+ * are wired (Web Push, FCM, chat, in-app, webhook); APNs and SMS are excluded
+ * from the edge facade by construction.
+ */
+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 runPushBroadcastJob}'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;
+  /** 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. */
+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 — 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: "…" } });
+ *
+ * // 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);
+ *
+ *         if (nextCursor !== 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 },
+ *             });
+ *         }
+ *     }
+ * }});
+ * ```
+ */
+declare const enqueuePushBroadcast: (queue: QueueProducerLike, job: Omit<PushBroadcastJob, "type">) => Promise<void>;
+/**
+ * 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 (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):
+ *
+ * - A job now processes exactly ONE bounded page (see `CreateNotifyOptions`'s
+ * page-size option, 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>;
+/**
+ * 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 {
+  prepare: (query: string) => D1PreparedLike;
+}
+interface D1PreparedLike {
+  all: <T = Record<string, unknown>>() => Promise<{
+    results: T[];
+  }>;
+  bind: (...values: unknown[]) => D1PreparedLike;
+  first: <T = Record<string, unknown>>() => Promise<T | null>;
+  run: () => Promise<unknown>;
+}
+/** Options for {@link d1SubscriptionStore}. */
+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
+ * for tests, local dev and a single-isolate app, but **not durable**: entries live
+ * only for the isolate's lifetime. Use {@link import("./d1-store").d1SubscriptionStore}
+ * (or another backing store) for production so subscriptions survive restarts.
+ */
+declare const memorySubscriptionStore: () => SubscriptionStore;
+/**
+ * Stable store id for a web-push endpoint.
+ *
+ * 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
+ * returning device simply re-registers under the new id, its stale `wp_` row aging
+ * out via normal gone-pruning. A future third revision must mint `wp3_` and repeat
+ * the lazy migration — NEVER reuse a prefix.
+ */
+declare const webPushId: (endpoint: string) => string;
+/** Stable store id for an FCM device token. See {@link webPushId} for the `_2` version-prefix contract. */
+declare const fcmId: (token: string) => string;
+/** Options threaded into {@link normalizeRegisterInput} from the notify definition. */
+interface NormalizeOptions {
+  /**
+   * Exact origins (`https://host[:port]`) a web-push endpoint may register from.
+   * When set (non-empty), the endpoint's origin must be one of these — the
+   * strongest anti-SSRF posture, and the ONLY way to close DNS rebinding for a
+   * facade that accepts client-controlled endpoints.
+   *
+   * 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.
+   */
+  allowedPushOrigins?: string[];
+}
+/**
+ * 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}), validates `metadata` (see
+ * {@link validateMetadata}), and stamps `createdAt`/`lastSeenAt`.
+ */
+declare const normalizeRegisterInput: (input: RegisterInput, now?: number, options?: NormalizeOptions) => StoredSubscription;
+/**
+ * The provider `to` target for a stored subscription: the W3C Push subscription
+ * (JSON-stringified) for web-push, or the raw device token for FCM. Matches the
+ * shapes the `@visulima/notification` web-push / fcm providers accept.
+ */
+declare const targetOf: (subscription: StoredSubscription) => string;
+/**
+ * Whether a provider error message indicates the subscription is permanently gone
+ * (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.
+ */
+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 };