@lunora/notify 1.0.0-alpha.1 → 1.0.0-alpha.2

package/README.md

@@ -98,6 +98,19 @@ for (const message of batch.messages) await runPushBroadcastJob(ctx.push, messag
 
 `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.
 
+## Delivery observability
+
+Every send is counted onto `ctx.metrics` and failures onto `ctx.log` for you — codegen threads the request's logger/metrics into `ctx.notify` (`createNotify(notifyConfig, env, { log, metrics })`), so there is nothing to wire. Two low-cardinality metric series feed the durable metric history + trend charts:
+
+- **`notify.send`** `{ channel, provider, status }` — attempted sends. `status` is `accepted` (the provider took it), `failed`, or `gone` (endpoint unregistered — 404/410 / FCM `UNREGISTERED` — and pruned). A single send counts 1; a **broadcast aggregates** into one count per `(provider, status)` bucket (value = the bucket's count), not one per recipient — each `ctx.metrics.count` is a durable write.
+- **`notify.skipped`** `{ channel, reason }` — a send that reached nobody: `no-subscriptions-matched` (empty broadcast) or `channel-not-configured`.
+
+A **failed** send also emits one `ctx.log.warn` line carrying the error and, for push, the subscription/user ids — trace-correlated to the enclosing action and durably archived. Successes and prunes stay off the log; failure logs stay per-recipient even in a broadcast (they have no durable write).
+
+`accepted` means the provider **accepted** the message, not that it was delivered or opened: Web Push and FCM give no delivery/open receipts, so the status stops at the send attempt. See [Observability → Delivery metrics](/docs/concepts/observability#delivery-metrics-notify).
+
 ## 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`.
+Shipped: Web Push + FCM channels, chat / in-app / webhook senders, device-subscription storage (memory + D1), queue-backed fan-out, the codegen ctx-splice that auto-wires `ctx.notify` / `ctx.push` from `lunora/notify.ts` (via `createNotify`, mirroring `defineFlags` → `ctx.flags`), the `notify_send_outside_action` advisor lint, the Studio **Notifications** page (registered-device inspector), and [delivery observability](#delivery-observability).
+
+Deferred: a filterable per-delivery **activity feed** and per-device history (a Novu-style drill-down). Web Push / FCM give no delivery/open receipts, so it would report only the send-attempt outcome; it needs a field-level predicate on the durable log reader (or a dedicated store) and is not planned until asked for.

package/dist/index.d.mts

@@ -119,6 +119,49 @@ interface BroadcastResult {
   /** Total subscriptions attempted. */
   total: number;
 }
+/**
+ * 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
@@ -268,6 +311,22 @@ interface CreateNotifyOptions {
    * 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;
 }
@@ -422,4 +481,4 @@ declare const targetOf: (subscription: StoredSubscription) => string;
  * (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 };
+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 };

package/dist/index.d.ts

@@ -119,6 +119,49 @@ interface BroadcastResult {
   /** Total subscriptions attempted. */
   total: number;
 }
+/**
+ * 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
@@ -268,6 +311,22 @@ interface CreateNotifyOptions {
    * 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;
 }
@@ -422,4 +481,4 @@ declare const targetOf: (subscription: StoredSubscription) => string;
  * (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 };
+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 };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 export { FCM_ENV_KEYS, WEB_PUSH_ENV_KEYS, fcmFromEnv, webPushFromEnv } from './packem_shared/FCM_ENV_KEYS-DY4-A717.mjs';
 export { defineNotify, isNotifyDefinition } from './packem_shared/defineNotify-B6S_47C2.mjs';
-export { createNotify } from './packem_shared/createNotify-Gg40Htm-.mjs';
+export { createNotify } from './packem_shared/createNotify-bDWs4qBm.mjs';
 export { buildEngine, routingPushProvider } from './packem_shared/buildEngine-DlmjvnNk.mjs';
 export { enqueuePushBroadcast, runPushBroadcastJob } from './packem_shared/enqueuePushBroadcast-DiK7Hyja.mjs';
 export { d1SubscriptionStore } from './packem_shared/d1SubscriptionStore-Dv3VPMI_.mjs';

package/dist/packem_shared/{createNotify-Gg40Htm-.mjs → createNotify-bDWs4qBm.mjs}

@@ -5,6 +5,12 @@ import { normalizeRegisterInput, targetOf, isGoneError } from './fcmId-B-YPgHi7.
 
 const resolveMaybeFactory = (value, env) => typeof value === "function" ? value(env) : value;
 const receiptError = (receipt) => receipt.successful ? void 0 : receipt.errorMessages.join("; ");
+const pushDeliveryStatus = (receipt, error) => {
+  if (receipt.successful) {
+    return "accepted";
+  }
+  return isGoneError(error) ? "gone" : "failed";
+};
 const mapWithConcurrency = async (items, limit, task) => {
   const results = Array.from({ length: items.length });
   let cursor = 0;
@@ -63,6 +69,16 @@ const createNotify = (definition, env, options = {}) => {
   }
   const subscriptionStore = store;
   const concurrency = Math.max(1, options.concurrency ?? 10);
+  const { log, metrics } = options;
+  const countSend = (channel, provider, status, count = 1) => {
+    metrics?.count("notify.send", count, { channel, provider: provider ?? channel, status });
+  };
+  const warnFailedSend = (channel, provider, fields) => {
+    log?.warn(`notify ${channel} delivery failed`, { channel, provider: provider ?? channel, status: "failed", ...fields });
+  };
+  const observeSkip = (channel, reason) => {
+    metrics?.count("notify.skipped", 1, { channel, reason });
+  };
   const resolveSubscription = async (target) => {
     if (typeof target !== "string") {
       return target;
@@ -73,28 +89,54 @@ const createNotify = (definition, env, options = {}) => {
     }
     return found;
   };
-  const deliver = async (subscription, payload) => {
+  const deliver = async (subscription, payload, countInline) => {
     const receipt = await engine.sendToChannel("push", { ...payload, to: targetOf(subscription) });
     const error = receiptError(receipt);
-    if (receipt.successful) {
+    const status = pushDeliveryStatus(receipt, error);
+    if (status === "accepted") {
       await subscriptionStore.markStatus(subscription.id, "ok");
-    } else if (isGoneError(error)) {
+    } else if (status === "gone") {
       await subscriptionStore.delete(subscription.id);
     } else {
       await subscriptionStore.markStatus(subscription.id, "failed", error);
     }
-    return receipt;
+    if (status === "failed") {
+      warnFailedSend("push", subscription.kind, { error, subscriptionId: subscription.id, userId: subscription.userId ?? null });
+    }
+    if (countInline) {
+      countSend("push", subscription.kind, status);
+    }
+    return { receipt, status };
   };
   const push = {
     broadcast: async (payload, filter) => {
       const subscriptions = await subscriptionStore.list(filter);
-      const outcomes = await mapWithConcurrency(subscriptions, concurrency, async (subscription) => {
-        const receipt = await deliver(subscription, payload);
-        if (receipt.successful) {
+      if (subscriptions.length === 0) {
+        observeSkip("push", "no-subscriptions-matched");
+      }
+      const rows = await mapWithConcurrency(subscriptions, concurrency, async (subscription) => {
+        const { receipt, status } = await deliver(subscription, payload, false);
+        return { kind: subscription.kind, receipt, status, subscription };
+      });
+      const buckets = /* @__PURE__ */ new Map();
+      for (const { kind, status } of rows) {
+        const key = `${kind}\0${status}`;
+        const bucket = buckets.get(key);
+        if (bucket === void 0) {
+          buckets.set(key, { count: 1, kind, status });
+        } else {
+          bucket.count += 1;
+        }
+      }
+      for (const { count, kind, status } of buckets.values()) {
+        countSend("push", kind, status, count);
+      }
+      const outcomes = rows.map(({ receipt, status, subscription }) => {
+        if (status === "accepted") {
           return { id: subscription.id, status: "ok" };
         }
         const error = receiptError(receipt);
-        return isGoneError(error) ? { error, id: subscription.id, status: "expired" } : { error, id: subscription.id, status: "failed" };
+        return status === "gone" ? { error, id: subscription.id, status: "expired" } : { error, id: subscription.id, status: "failed" };
       });
       return {
         failed: outcomes.filter((outcome) => outcome.status === "failed").length,
@@ -106,20 +148,41 @@ const createNotify = (definition, env, options = {}) => {
     },
     list: (filter) => subscriptionStore.list(filter),
     register: (input) => subscriptionStore.put(normalizeRegisterInput(input)),
-    send: async (target, payload) => deliver(await resolveSubscription(target), payload),
+    send: async (target, payload) => {
+      const { receipt } = await deliver(await resolveSubscription(target), payload, true);
+      return receipt;
+    },
     unregister: (id) => subscriptionStore.delete(id)
   };
   const sendToChannel = async (channel, payload) => {
     if (engine.getProvider(channel) === void 0) {
+      observeSkip(channel, "channel-not-configured");
       throw new LunoraError("BAD_REQUEST", `@lunora/notify: the "${channel}" channel is not configured in defineNotify(...)`);
     }
-    return engine.sendToChannel(channel, payload);
+    const receipt = await engine.sendToChannel(channel, payload);
+    const status = receipt.successful ? "accepted" : "failed";
+    countSend(channel, receipt.provider, status);
+    if (status === "failed") {
+      warnFailedSend(channel, receipt.provider, { error: receiptError(receipt) });
+    }
+    return receipt;
   };
   const notify = {
     chat: (payload) => sendToChannel("chat", payload),
     inApp: (payload) => sendToChannel("inapp", payload),
     push,
-    send: (message) => engine.send(message),
+    send: async (message) => {
+      const receipts = await engine.send(message);
+      for (const receipt of receipts) {
+        const channel = receipt.channel ?? "unknown";
+        const status = receipt.successful ? "accepted" : "failed";
+        countSend(channel, receipt.provider, status);
+        if (status === "failed") {
+          warnFailedSend(channel, receipt.provider, { error: receiptError(receipt) });
+        }
+      }
+      return receipts;
+    },
     webhook: (payload) => sendToChannel("webhook", payload)
   };
   return { notify, push };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/notify",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "description": "Multi-channel notifications for Lunora — ctx.notify / ctx.push over @visulima/notification: edge-safe Web Push + FCM, plus chat, in-app inbox and webhook channels, with subscription storage and queue-backed fan-out",
   "keywords": [
     "cloudflare",