@lunora/notify 0.0.0 → 1.0.0-alpha.1

package/LICENSE.md

@@ -0,0 +1,111 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 anolilab and contributors
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or service
+that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software that
+   exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee using
+   the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to the
+infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN
+IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following will
+apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -1,45 +1,103 @@
 # @lunora/notify
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Multi-channel notifications for Lunora, wrapping the [`@visulima/notification`](https://visulima.com/packages/notification) engine. Web Push + FCM first (both edge-safe under workerd), plus chat, in-app inbox, and webhook channels — with device-subscription storage and queue-backed fan-out.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+- `ctx.notify` — the multi-channel facade (`send`, `chat`, `inApp`, `webhook`, `push`).
+- `ctx.push` — the device-push sub-facade (`register`, `send`, `broadcast`, `list`, `unregister`).
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Edge safety
 
-## Purpose
+Web Push (VAPID + RFC 8291) and FCM (HTTP v1) run on `fetch` + Web Crypto — no `node:*`. **APNs** (`node:http2`) and the **BullMQ / pg-boss / SQS** queue adapters are Node-only and are **not** wired into this facade; route heavy fan-out through `@lunora/queue`.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@lunora/notify`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Configure
 
-## What is OIDC Trusted Publishing?
+```ts
+// lunora/notify.ts
+import { defineNotify, webPushFromEnv, fcmFromEnv, d1SubscriptionStore } from "@lunora/notify";
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+export default defineNotify({
+    webPush: (env) => webPushFromEnv(env), // reads VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY / VAPID_SUBJECT
+    fcm: (env) => fcmFromEnv(env), // reads FCM_PROJECT_ID / FCM_ACCESS_TOKEN (prefer a getAccessToken in prod)
+    store: (env) => d1SubscriptionStore(env.DB),
+});
+```
 
-## Setup Instructions
+`.dev.vars` (scaffolded by `lunora dev` from `@lunora/config`'s package-secrets registry):
 
-To properly configure OIDC trusted publishing for this package:
+```
+VAPID_PUBLIC_KEY=<your-vapid-public-key>
+VAPID_PRIVATE_KEY=<your-vapid-private-key>
+VAPID_SUBJECT=mailto:you@example.com
+FCM_PROJECT_ID=<your-firebase-project-id>
+FCM_ACCESS_TOKEN=<your-fcm-access-token>
+```
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+Generate a VAPID keypair once: `npx web-push generate-vapid-keys`.
 
-## DO NOT USE THIS PACKAGE
+## Register a device (browser)
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```ts
+import { subscribeToPush } from "@lunora/notify/web";
 
-## More Information
+const subscription = await subscribeToPush({ serviceWorkerUrl: "/sw.js", vapidPublicKey });
+await client.mutation("registerDevice", { subscription });
+```
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```ts
+// lunora/registerDevice.ts (a mutation — storage write is fine here)
+export const registerDevice = mutation({
+    args: { subscription: v.any() },
+    handler: async (ctx, { subscription }) => {
+        await ctx.push.register({ subscription, userId: ctx.auth?.userId });
+    },
+});
+```
 
----
+## Send (from an action)
 
-**Maintained for OIDC setup purposes only**
+Notification sends are external I/O, so they belong in **actions** (the `notify_send_outside_action` advisor lint enforces this):
+
+```ts
+export const announce = action({
+    args: { title: v.string(), body: v.string() },
+    handler: async (ctx, { title, body }) => {
+        const result = await ctx.push.broadcast({ title, body });
+        // result: { total, sent, pruned, failed, outcomes }
+    },
+});
+```
+
+`broadcast` reuses the engine's retry + circuit-breaker middleware and prunes subscriptions the push service reports as gone (HTTP 404/410, FCM `UNREGISTERED`). A single targeted send:
+
+```ts
+await ctx.push.send(subscriptionId, { title: "Hi", body: "…" });
+```
+
+Multi-channel through `ctx.notify.send`:
+
+```ts
+await ctx.notify.send({
+    push: { title: "New drop", body: "…", to: pushTarget },
+    chat: { text: "New drop shipped" },
+});
+```
+
+## Queue-backed fan-out
+
+Move a large broadcast off the request path with `@lunora/queue`:
+
+```ts
+// producer (mutation/action)
+await enqueuePushBroadcast(ctx.queues.push, { payload: { title: "New drop", body: "…" } });
+
+// consumer (lunora/queues.ts)
+for (const message of batch.messages) await runPushBroadcastJob(ctx.push, message.body);
+```
+
+## Subscription storage
+
+`SubscriptionStore` implementations: `memorySubscriptionStore()` (non-durable default, tests/dev) and `d1SubscriptionStore(db)` (durable, edge-safe, lazy table creation). Lifecycle: register (upsert), list/filter (by kind or user), status marking, and automatic prune of gone subscriptions on send/broadcast.
+
+## Status
+
+Phases 0–2 and the Phase-3 advisor lints + queue-backed fan-out are shipped. Remaining: the codegen ctx-splice that auto-wires `ctx.notify` / `ctx.push` from `lunora/notify.ts` (mirroring `defineFlags` → `ctx.flags`; `createNotify` is the factory it calls), the codegen advisor feeder, and the Studio Notifications page. See `plans/165-push-notifications.md`.

package/dist/index.d.mts

@@ -0,0 +1,425 @@
+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 {
+  /** Restrict to a delivery kind. */
+  kind?: SubscriptionKind;
+  /** 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. */
+  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;
+}
+/**
+ * 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.
+   */
+  broadcast: (payload: PushContent, filter?: SubscriptionFilter) => Promise<BroadcastResult>;
+  /** List stored subscriptions (optionally filtered). */
+  list: (filter?: SubscriptionFilter) => Promise<StoredSubscription[]>;
+  /** 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 {
+  /**
+   * 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 {
+  /** 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;
+  /** 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).
+ */
+interface PushBroadcastJob {
+  /** Subscription filter (which devices/users to target). */
+  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.
+ *
+ * ```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) await runPushBroadcastJob(ctx.push, message.body);
+ * }});
+ * ```
+ */
+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).
+ */
+declare const runPushBroadcastJob: (push: LunoraPush, job: PushBroadcastJob) => Promise<unknown>;
+/**
+ * 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.
+ *
+ * ```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. */
+declare const webPushId: (endpoint: string) => string;
+/** Stable store id for an FCM device token. */
+declare const fcmId: (token: string) => 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`) and stamps `createdAt`/`lastSeenAt`.
+ */
+declare const normalizeRegisterInput: (input: RegisterInput, now?: number) => 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 NotifyEnv, 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 };