@objectstack/service-messaging 7.8.0 → 8.0.0

package/dist/index.cjs

@@ -242,7 +242,8 @@ var PreferenceResolver = class {
       const channel = String(r.channel ?? WILDCARD);
       index.set(`${user}|${topic}|${channel}`, {
         enabled: asBool(r.enabled),
-        quietHours: parseQuietHours(r.quiet_hours)
+        quietHours: parseQuietHours(r.quiet_hours),
+        digest: parseDigest(r.digest)
       });
     }
     const nowMs = ctx.now ?? Date.now();
@@ -254,11 +255,22 @@ var PreferenceResolver = class {
       );
       if (accepted.length === 0) continue;
       let notBefore;
+      let digest;
       if (!critical) {
-        const qh = this.resolveQuietHours(index, recipient, ctx.topic);
-        notBefore = qh ? quietHoursDeferral(qh, nowMs) : void 0;
+        const cadence = this.resolveDigest(index, recipient, ctx.topic);
+        if (cadence) {
+          const d = digestDeferral(cadence, nowMs, this.resolveQuietHours(index, recipient, ctx.topic)?.tz);
+          notBefore = d.notBefore;
+          digest = { window: d.window };
+        } else {
+          const qh = this.resolveQuietHours(index, recipient, ctx.topic);
+          notBefore = qh ? quietHoursDeferral(qh, nowMs) : void 0;
+        }
       }
-      targets.push(notBefore != null ? { recipient, channels: accepted, notBefore } : { recipient, channels: accepted });
+      const target = { recipient, channels: accepted };
+      if (notBefore != null) target.notBefore = notBefore;
+      if (digest) target.digest = digest;
+      targets.push(target);
     }
     return targets;
   }
@@ -301,6 +313,20 @@ var PreferenceResolver = class {
     }
     return void 0;
   }
+  /**
+   * Resolve a recipient's digest cadence. Like quiet-hours, declared on a
+   * channel-wildcard row (`(user, *, *)` or `(user, topic, *)`) — batching is a
+   * per-person, channel-agnostic setting. Most-specific user/topic wins.
+   */
+  resolveDigest(index, user, topic) {
+    for (const u of [user, WILDCARD]) {
+      for (const t of [topic, WILDCARD]) {
+        const hit = index.get(`${u}|${t}|${WILDCARD}`);
+        if (hit?.digest) return hit.digest;
+      }
+    }
+    return void 0;
+  }
 };
 function asBool(v) {
   return v === true || v === 1 || v === "1" || v === "true";
@@ -318,6 +344,21 @@ function parseQuietHours(v) {
   if (o.start == null || o.end == null) return void 0;
   return { tz: o.tz, start: String(o.start), end: String(o.end) };
 }
+function parseDigest(v) {
+  return v === "daily" || v === "weekly" ? v : void 0;
+}
+function digestDeferral(cadence, nowMs, tz) {
+  const zone = tz ?? "UTC";
+  const { minutesOfDay, isoWeekday, date } = wallClockInTz(nowMs, zone);
+  if (cadence === "daily") {
+    const minsToMidnight = 1440 - minutesOfDay;
+    return { notBefore: nowMs + minsToMidnight * 6e4, window: date };
+  }
+  const daysToNextMonday = (8 - isoWeekday) % 7 || 7;
+  const minsToTarget = daysToNextMonday * 1440 - minutesOfDay;
+  const mondayMs = nowMs - (isoWeekday - 1) * 864e5;
+  return { notBefore: nowMs + minsToTarget * 6e4, window: wallClockInTz(mondayMs, zone).date };
+}
 function quietHoursDeferral(quietHours, nowMs) {
   const start = parseHHMM(quietHours.start);
   const end = parseHHMM(quietHours.end);
@@ -357,6 +398,38 @@ function minutesOfDayInTz(nowMs, tz) {
     return d.getUTCHours() * 60 + d.getUTCMinutes();
   }
 }
+function wallClockInTz(nowMs, tz) {
+  try {
+    const parts = new Intl.DateTimeFormat("en-US", {
+      hour12: false,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      timeZone: tz
+    }).formatToParts(new Date(nowMs));
+    const get = (t) => parts.find((p) => p.type === t)?.value ?? "0";
+    const y = Number(get("year"));
+    const mo = Number(get("month"));
+    const d = Number(get("day"));
+    const hour = Number(get("hour")) % 24;
+    const minute = Number(get("minute"));
+    const dow = new Date(Date.UTC(y, mo - 1, d)).getUTCDay();
+    return { minutesOfDay: hour * 60 + minute, isoWeekday: dow === 0 ? 7 : dow, date: `${y}-${pad(mo)}-${pad(d)}` };
+  } catch {
+    const dt = new Date(nowMs);
+    const dow = dt.getUTCDay();
+    return {
+      minutesOfDay: dt.getUTCHours() * 60 + dt.getUTCMinutes(),
+      isoWeekday: dow === 0 ? 7 : dow,
+      date: dt.toISOString().slice(0, 10)
+    };
+  }
+}
+function pad(n) {
+  return String(n).padStart(2, "0");
+}
 function msg2(err) {
   return err?.message ?? String(err);
 }
@@ -436,6 +509,13 @@ function createInboxChannel(opts) {
 // src/messaging-service.ts
 var NOTIFICATION_EVENT_OBJECT = "sys_notification";
 var READ_RECEIPT_STATES = /* @__PURE__ */ new Set(["read", "clicked", "dismissed"]);
+function isUniqueViolation(err) {
+  const e = err;
+  if (!e) return false;
+  if (e.code === "23505" || e.code === "ER_DUP_ENTRY" || e.code === "SQLITE_CONSTRAINT_UNIQUE") return true;
+  const msg3 = String(e.message ?? "").toLowerCase();
+  return msg3.includes("unique constraint failed") || msg3.includes("duplicate key") || msg3.includes("duplicate entry");
+}
 var MessagingService = class {
   constructor(ctx) {
     this.ctx = ctx;
@@ -614,13 +694,15 @@ var MessagingService = class {
   }
   /** Upsert a `read` receipt for one notification; returns 1 when it persisted. */
   async upsertReadReceipt(data, userId, notificationId, at) {
-    const existing = await data.findOne(RECEIPT_OBJECT, {
-      where: { notification_id: notificationId, user_id: userId, channel: "inbox" },
-      fields: ["id"]
-    });
-    if (existing?.id) {
+    const where = { notification_id: notificationId, user_id: userId, channel: "inbox" };
+    const flipToRead = async () => {
+      const existing = await data.findOne(RECEIPT_OBJECT, { where, fields: ["id"] });
+      if (!existing?.id) return false;
       await data.update(RECEIPT_OBJECT, { state: "read", at }, { where: { id: existing.id } });
-    } else {
+      return true;
+    };
+    if (await flipToRead()) return 1;
+    try {
       await data.insert(RECEIPT_OBJECT, {
         notification_id: notificationId,
         delivery_id: null,
@@ -630,8 +712,11 @@ var MessagingService = class {
         at,
         created_at: at
       });
+      return 1;
+    } catch (err) {
+      if (isUniqueViolation(err) && await flipToRead()) return 1;
+      throw err;
     }
-    return 1;
   }
   /**
    * The single notification ingress. Writes the L2 event, resolves the
@@ -720,7 +805,7 @@ var MessagingService = class {
       actionUrl: actionUrlFor(input, payload)
     };
     const deliveries = [];
-    for (const { recipient, channels, notBefore } of targets) {
+    for (const { recipient, channels, notBefore, digest } of targets) {
       for (const channel of channels) {
         try {
           const id = await outbox.enqueue({
@@ -730,9 +815,12 @@ var MessagingService = class {
             topic: input.topic,
             payload: deliveryPayload,
             organizationId: input.organizationId,
-            // Quiet-hours deferral (P3b): the dispatcher won't claim
-            // this row until `notBefore`. Absent ⇒ immediate.
-            notBefore
+            // Quiet-hours / digest deferral (P3b): the dispatcher won't
+            // claim this row until `notBefore`. Absent ⇒ immediate.
+            notBefore,
+            // P3b-2: tag batched deliveries so the dispatcher collapses
+            // a `(recipient, channel, window)` group into one message.
+            digestKey: digest ? `${recipient}|${channel}|${digest.window}` : void 0
           });
           deliveries.push({ channel, recipient, ok: true, externalId: id });
         } catch (err) {
@@ -902,12 +990,15 @@ var SqlNotificationOutbox = class {
       topic: input.topic ?? null,
       payload: input.payload ?? {},
       organization_id: input.organizationId ?? null,
-      partition_key: hashPartition(input.notificationId, this.partitionCount),
+      // Digest rows partition by their group key so a window's rows land in
+      // one partition and a single node collapses them under its lock.
+      partition_key: hashPartition(input.digestKey ?? input.notificationId, this.partitionCount),
       status: "pending",
       attempts: 0,
-      // Deferred dispatch (quiet-hours, P3): claim() skips pending rows
-      // whose next_attempt_at is in the future.
+      // Deferred dispatch (quiet-hours / digest, P3): claim() skips pending
+      // rows whose next_attempt_at is in the future.
       next_attempt_at: input.notBefore ?? null,
+      digest_key: input.digestKey ?? null,
       created_at: now,
       updated_at: now
     };
@@ -931,6 +1022,7 @@ var SqlNotificationOutbox = class {
     const candidates = await this.engine.find(this.objectName, {
       where: {
         status: "pending",
+        digest_key: null,
         ...partitionFilter,
         $or: [{ next_attempt_at: null }, { next_attempt_at: { $lte: now } }]
       },
@@ -949,6 +1041,36 @@ var SqlNotificationOutbox = class {
     });
     return claimed.map((r) => this.toRecord(r));
   }
+  async claimDigest(opts) {
+    const now = opts.now ?? Date.now();
+    await this.engine.update(
+      this.objectName,
+      { status: "pending", claimed_by: null, claimed_at: null, updated_at: now },
+      { where: { status: "in_flight", claimed_at: { $lt: now - opts.claimTtlMs } }, multi: true }
+    );
+    const partitionFilter = opts.partition ? { partition_key: opts.partition.index } : {};
+    const candidates = await this.engine.find(this.objectName, {
+      where: {
+        status: "pending",
+        digest_key: { $ne: null },
+        ...partitionFilter,
+        $or: [{ next_attempt_at: null }, { next_attempt_at: { $lte: now } }]
+      },
+      fields: ["id"],
+      limit: 1e4
+    });
+    if (!candidates.length) return [];
+    const ids = candidates.map((c) => c.id);
+    await this.engine.update(
+      this.objectName,
+      { status: "in_flight", claimed_by: opts.nodeId, claimed_at: now, updated_at: now },
+      { where: { id: { $in: ids }, status: "pending" }, multi: true }
+    );
+    const claimed = await this.engine.find(this.objectName, {
+      where: { id: { $in: ids }, claimed_by: opts.nodeId, claimed_at: now, status: "in_flight" }
+    });
+    return claimed.map((r) => this.toRecord(r));
+  }
   async ack(id, result) {
     const current = await this.engine.findOne(this.objectName, {
       where: { id },
@@ -1019,6 +1141,7 @@ var SqlNotificationOutbox = class {
       nextAttemptAt: r.next_attempt_at ?? void 0,
       lastAttemptedAt: r.last_attempted_at ?? void 0,
       error: r.error ?? void 0,
+      digestKey: r.digest_key ?? void 0,
       createdAt: r.created_at,
       updatedAt: r.updated_at
     };
@@ -1355,6 +1478,24 @@ var SqlHttpOutbox = class {
   }
 };
 
+// src/digest-render.ts
+function renderDigest(rows) {
+  const items = rows.map((r) => {
+    const p = r.payload ?? {};
+    return {
+      notificationId: r.notificationId,
+      title: typeof p.title === "string" && p.title ? p.title : r.topic ?? "Notification",
+      body: typeof p.body === "string" && p.body ? p.body : void 0,
+      topic: r.topic,
+      actionUrl: typeof p.actionUrl === "string" && p.actionUrl ? p.actionUrl : void 0
+    };
+  });
+  const count = items.length;
+  const title = count === 1 ? items[0].title : `You have ${count} notifications`;
+  const body = items.map((it) => `\u2022 ${it.title}`).join("\n");
+  return { title, body, severity: "info", count, items };
+}
+
 // src/dispatcher.ts
 var SINGLE_NODE_CLUSTER = {
   lock: {
@@ -1445,16 +1586,73 @@ var NotificationDispatcher = class {
         partition: { index, count: this.opts.partitionCount },
         claimTtlMs: this.opts.claimTtlMs
       });
-      if (claimed.length === 0) return;
-      await handle.renew?.(this.opts.lockTtlMs);
-      for (const row of claimed) {
-        if (handle.isHeld && !handle.isHeld()) break;
-        await this.processRow(row);
+      if (claimed.length > 0) {
+        await handle.renew?.(this.opts.lockTtlMs);
+        for (const row of claimed) {
+          if (handle.isHeld && !handle.isHeld()) break;
+          await this.processRow(row);
+        }
+      }
+      const digestRows = await this.opts.outbox.claimDigest({
+        nodeId: this.opts.nodeId,
+        limit: this.opts.batchSize,
+        partition: { index, count: this.opts.partitionCount },
+        claimTtlMs: this.opts.claimTtlMs
+      });
+      if (digestRows.length > 0) {
+        await handle.renew?.(this.opts.lockTtlMs);
+        for (const group of groupByDigestKey(digestRows)) {
+          if (handle.isHeld && !handle.isHeld()) break;
+          await this.processDigestGroup(group);
+        }
       }
     } finally {
       await handle.release();
     }
   }
+  /**
+   * Send one collapsed message for a `(recipient, channel, window)` group and
+   * ack every row in it with that one outcome. On failure the whole group
+   * re-defers together (each row keeps its own backoff via its `attempts`).
+   */
+  async processDigestGroup(rows) {
+    const channelName = rows[0].channel;
+    const recipient = rows[0].recipientId;
+    const channel = this.opts.channels.getChannel(channelName);
+    if (!channel) {
+      for (const row of rows) {
+        await this.opts.outbox.ack(row.id, { success: false, error: `channel '${channelName}' not registered`, dead: true });
+        this.opts.onAttempt?.(row, false);
+      }
+      return;
+    }
+    const digest = renderDigest(rows);
+    const notification = {
+      notificationId: rows[0].notificationId,
+      // representative event id
+      organizationId: rows[0].organizationId,
+      topic: rows[0].topic,
+      title: digest.title,
+      body: digest.body,
+      severity: "info",
+      recipients: [recipient],
+      channels: [channelName],
+      payload: { digest: true, count: digest.count, items: digest.items }
+    };
+    let result;
+    try {
+      result = await channel.send(this.opts.channelContext, { notification, channel: channelName, recipient });
+    } catch (err) {
+      result = { ok: false, error: err?.message ?? String(err) };
+    }
+    const errorClass = !result.ok && channel.classifyError ? channel.classifyError(result.error) : void 0;
+    const now = this.opts.now?.() ?? Date.now();
+    for (const row of rows) {
+      const ack = classifyDeliveryAttempt(result, errorClass, row.attempts, now, this.opts.rng);
+      await this.opts.outbox.ack(row.id, ack);
+      this.opts.onAttempt?.(row, result.ok);
+    }
+  }
   async processRow(row) {
     const channel = this.opts.channels.getChannel(row.channel);
     if (!channel) {
@@ -1496,6 +1694,19 @@ var NotificationDispatcher = class {
     this.opts.onAttempt?.(row, result.ok);
   }
 };
+function groupByDigestKey(rows) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    const key = r.digestKey ?? r.id;
+    let g = groups.get(key);
+    if (!g) {
+      g = [];
+      groups.set(key, g);
+    }
+    g.push(r);
+  }
+  return [...groups.values()];
+}
 function stableNodeOffset(nodeId, partitionCount) {
   let h = 0;
   for (let i = 0; i < nodeId.length; i++) h = h * 31 + nodeId.charCodeAt(i) | 0;
@@ -2094,6 +2305,16 @@ var NotificationDelivery = import_data4.ObjectSchema.create({
     recipient_id: import_data4.Field.text({ label: "Recipient User", required: true, searchable: true }),
     channel: import_data4.Field.text({ label: "Channel", required: true }),
     topic: import_data4.Field.text({ label: "Topic", searchable: true }),
+    // P3b-2 digest: when the recipient's preference batches this channel
+    // (`digest: daily|weekly`), the row enqueues deferred to the next window
+    // and carries `${recipient}|${channel}|${window}` here. The dispatcher's
+    // digest pass collapses all same-key rows into ONE rendered message at
+    // window time. Null ⇒ an ordinary (immediate / quiet-hours) delivery.
+    digest_key: import_data4.Field.text({
+      label: "Digest Key",
+      searchable: true,
+      description: "recipient|channel|window grouping key for batched (digest) deliveries; null for normal sends."
+    }),
     payload: import_data4.Field.json({
       label: "Payload",
       description: "Snapshot of the rendered notification content for dispatch."
@@ -2120,7 +2341,9 @@ var NotificationDelivery = import_data4.ObjectSchema.create({
     { fields: ["status", "partition_key", "next_attempt_at"] },
     // Stale-in_flight reaper.
     { fields: ["status", "claimed_at"] },
-    { fields: ["notification_id"] }
+    { fields: ["notification_id"] },
+    // P3b-2: the digest collapse pass — claim due batched rows by group.
+    { fields: ["digest_key", "status", "next_attempt_at"] }
   ]
 });
 
@@ -2465,12 +2688,15 @@ var MemoryNotificationOutbox = class {
       topic: input.topic,
       payload: input.payload ?? {},
       organizationId: input.organizationId,
-      partitionKey: hashPartition(input.notificationId, this.partitionCount),
+      // Digest rows partition by their group key so a window's rows land in
+      // one partition and a single node collapses them under its lock.
+      partitionKey: hashPartition(input.digestKey ?? input.notificationId, this.partitionCount),
       status: "pending",
       attempts: 0,
-      // Deferred dispatch (quiet-hours, P3): claim() skips pending rows
-      // whose nextAttemptAt is still in the future.
+      // Deferred dispatch (quiet-hours / digest, P3): claim() skips pending
+      // rows whose nextAttemptAt is still in the future.
       nextAttemptAt: input.notBefore,
+      digestKey: input.digestKey,
       createdAt: now,
       updatedAt: now
     });
@@ -2490,6 +2716,31 @@ var MemoryNotificationOutbox = class {
     for (const r of this.rows.values()) {
       if (out.length >= opts.limit) break;
       if (r.status !== "pending") continue;
+      if (r.digestKey != null) continue;
+      if (opts.partition && r.partitionKey !== opts.partition.index) continue;
+      if (r.nextAttemptAt != null && r.nextAttemptAt > now) continue;
+      r.status = "in_flight";
+      r.claimedBy = opts.nodeId;
+      r.claimedAt = now;
+      r.updatedAt = now;
+      out.push({ ...r });
+    }
+    return out;
+  }
+  async claimDigest(opts) {
+    const now = opts.now ?? this.clock();
+    for (const r of this.rows.values()) {
+      if (r.status === "in_flight" && (r.claimedAt ?? 0) < now - opts.claimTtlMs) {
+        r.status = "pending";
+        r.claimedBy = void 0;
+        r.claimedAt = void 0;
+        r.updatedAt = now;
+      }
+    }
+    const out = [];
+    for (const r of this.rows.values()) {
+      if (r.status !== "pending") continue;
+      if (r.digestKey == null) continue;
       if (opts.partition && r.partitionKey !== opts.partition.index) continue;
       if (r.nextAttemptAt != null && r.nextAttemptAt > now) continue;
       r.status = "in_flight";