@ai-matrx/messaging 0.15.82 → 0.16.0

package/CHANGELOG.md

@@ -1,12 +1,57 @@
 # Changelog — `@ai-matrx/messaging`
 
+## 0.16.0
+
+**DM soft expiry.** A direct message can carry `softExpiresAt` (column
+`communication.dm_messages.soft_expires_at`). Past that instant the message is
+LAPSED: still readable and actionable, never hidden or edited, and it no longer
+counts as unread. The reader's `last_read_at` watermark is never moved for it.
+Lapsed is derived live, never stamped — no sweeper, no schedule.
+
+- `Message.softExpiresAt: string | null` (required) and
+  `DraftMessage.softExpiresAt?: string`; every message read selects
+  `soft_expires_at`, and `insertMessage` writes it only when a draft sets it.
+- `isLapsed(message, now)` — the ONE lapse rule — and `softExpiryTime(message)`,
+  both exported from the core entry.
+- Store: an incoming message that has already lapsed never increments
+  `unreadCount` (store rule 6) — judged on the SERVER's clock (below).
+- Engine: ONE timer for the soonest pending expiry across the loaded inbox. When
+  it fires, the due conversations' counts are RE-READ from the server
+  (`get_dm_unread_count` already excludes lapsed messages), so
+  `totalUnreadConversations` and every badge follow without a reload. Lapse is
+  judged on the server's clock: each `pendingSoftExpiries` answer carries the
+  database's `now()` and the engine keeps the offset, so a browser clock that runs
+  fast never hides a message the server still counts; an expiry already past
+  re-reads the server's count at once instead of subtracting locally.
+- Repository: `unreadCount(conversationId)` (read only) and
+  `pendingSoftExpiries(conversationIds)` → `{ byConversation, serverNow }`, through
+  `public.get_dm_pending_soft_expiries` — ONE answer per conversation (its soonest
+  pending expiry), chunked 200 conversations per call, so a busy thread can never
+  starve its neighbours out of a row cap.
+- `MessageBubble`: a lapsed message renders muted and outlined with a small
+  clock + "Past" marker in its meta row; its chips and links keep working.
+  `ConversationView` drives it from one clock per thread.
+
+**Requires the database.** Every message read now names `soft_expires_at`, and
+`pendingSoftExpiries` calls `public.get_dm_pending_soft_expiries`; against a
+database without them DM reads fail. matrx-frontend
+`migrations/dm_soft_expiry_and_dm_pairs_with_email.sql` is on production since 2026-10-04.
+
+### Consumer action
+
+- Any code that constructs a `Message` literal (fixtures, demos, optimistic
+  stand-ins) adds `softExpiresAt: null`.
+- A sender that wants a soft expiry passes `softExpiresAt` (ISO instant) on the
+  draft — never compare the field directly; ask `isLapsed`.
+- A custom repository implementing `MessagingRepository` adds `unreadCount` and
+  `pendingSoftExpiries`.
+
 ## 0.15.82
 ### The unread badge is a content-sized pill again
 
 - `.mx-msg__row-preview span` also matched the unread badge (a span in the same row) and stretched a "1" to a ~100px bar; the selector is now `.mx-msg__row-preview > span:first-child`, the preview text only.
 - Consumer action: delete any host override pinning `.mx-msg__row-preview > .mx-msg__badge` to `flex: 0 0 auto`.
 
-
 ## 0.15.81
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/index.cjs

@@ -56,6 +56,7 @@ __export(src_exports, {
   groupMessages: () => groupMessages,
   inboxTopic: () => inboxTopic,
   invalidResponse: () => invalidResponse,
+  isLapsed: () => isLapsed,
   isSameDay: () => isSameDay,
   messagingClientId: () => messagingClientId,
   normalizeMessagingError: () => normalizeMessagingError,
@@ -67,6 +68,7 @@ __export(src_exports, {
   projectParticipantRole: () => projectParticipantRole,
   projectUserSummary: () => projectUserSummary,
   resolveActor: () => resolveActor,
+  softExpiryTime: () => softExpiryTime,
   splitText: () => splitText,
   summarizeText: () => summarizeText,
   toMessagingArchiveFilter: () => toMessagingArchiveFilter,
@@ -973,7 +975,8 @@ function projectBroadcastMessage(value) {
     action: projectMessageAction(record["action"]),
     attachments: projectAttachmentList(record["attachments"]),
     references: projectReferenceList(record["references"]),
-    metadata
+    metadata,
+    softExpiresAt: str(record, "softExpiresAt")
   };
 }
 function projectMessage(row, fallbackOrganizationId) {
@@ -1003,7 +1006,8 @@ function projectMessage(row, fallbackOrganizationId) {
     action,
     attachments: projectAttachments(metadata),
     references: projectReferences(metadata),
-    metadata
+    metadata,
+    softExpiresAt: str(row, "soft_expires_at")
   };
 }
 function projectParticipantRole(value) {
@@ -1056,6 +1060,18 @@ function projectConversationSummary(row, viewerId, fallbackOrganizationId) {
   };
 }
 
+// src/core/lapse.ts
+function softExpiryTime(message) {
+  if (message.softExpiresAt === null) return null;
+  const parsed = Date.parse(message.softExpiresAt);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function isLapsed(message, now = Date.now()) {
+  const at = softExpiryTime(message);
+  if (at === null) return false;
+  return at <= (typeof now === "number" ? now : now.getTime());
+}
+
 // src/core/types.ts
 var asConversationId = (value) => value;
 var asMessageId = (value) => value;
@@ -1093,7 +1109,8 @@ function insertOrdered(messages, message) {
   next.splice(index, 0, message);
   return next;
 }
-function createMessagingStore() {
+function createMessagingStore(options = {}) {
+  const now = options.now ?? Date.now;
   let conversations = [];
   let conversationSummaries = /* @__PURE__ */ new Map();
   let hasMoreConversations = false;
@@ -1330,7 +1347,7 @@ function createMessagingStore() {
       if (existing === void 0) return;
       if (message.deliveryState === "sending" || message.deletedAt !== null) return;
       if (existing.lastMessageAt !== null && message.createdAt < existing.lastMessageAt) return;
-      const shouldCount = args.incrementUnread === true;
+      const shouldCount = args.incrementUnread === true && !isLapsed(message, now());
       replaceOneSummary(message.conversationId, (item) => ({
         ...item,
         lastMessageContent: message.content,
@@ -1393,14 +1410,25 @@ function optimisticMessage(args) {
     action: args.action ?? null,
     attachments: args.attachments ?? [],
     references: args.references ?? [],
-    metadata: {}
+    metadata: {},
+    softExpiresAt: args.softExpiresAt ?? null
   };
 }
 
 // src/core/engine.ts
+var SOFT_EXPIRY_GRACE_MS = 2e3;
+var MAX_TIMER_DELAY_MS = 2147483647;
 function createMessagingEngine(options) {
   const { repository, manager, identity } = options;
-  const store = createMessagingStore();
+  const browserNow = options.now ?? Date.now;
+  let serverClockOffsetMs = 0;
+  const now = () => browserNow() + serverClockOffsetMs;
+  function learnServerClock(serverNow) {
+    if (serverNow === null) return;
+    const server = Date.parse(serverNow);
+    if (Number.isFinite(server)) serverClockOffsetMs = server - browserNow();
+  }
+  const store = createMessagingStore({ now });
   const conversationPageSize = options.conversationPageSize ?? 30;
   const messagePageSize = options.messagePageSize ?? 50;
   const openChannels = /* @__PURE__ */ new Map();
@@ -1414,6 +1442,8 @@ function createMessagingEngine(options) {
   let inboxChannel = null;
   let conversationCursor = null;
   let disposed = false;
+  const pendingExpiry = /* @__PURE__ */ new Map();
+  let expiryTimer = null;
   function report(event) {
     options.onDiagnostic?.(event);
   }
@@ -1456,6 +1486,72 @@ function createMessagingEngine(options) {
     }).catch(() => void 0);
     return current;
   }
+  function scheduleExpiryTimer() {
+    if (expiryTimer !== null) {
+      clearTimeout(expiryTimer);
+      expiryTimer = null;
+    }
+    if (disposed || pendingExpiry.size === 0) return;
+    const soonest = Math.min(...pendingExpiry.values());
+    const delay = Math.min(
+      MAX_TIMER_DELAY_MS,
+      Math.max(0, soonest + SOFT_EXPIRY_GRACE_MS - now())
+    );
+    expiryTimer = setTimeout(() => {
+      expiryTimer = null;
+      void fireSoftExpiry();
+    }, delay);
+  }
+  function noteSoftExpiry(id, at) {
+    if (at === null) return;
+    if (at <= now() && (store.snapshot().conversationSummaries.get(id)?.unreadCount ?? 0) === 0) {
+      return;
+    }
+    const held = pendingExpiry.get(id);
+    if (held !== void 0 && held <= at) return;
+    pendingExpiry.set(id, at);
+    scheduleExpiryTimer();
+  }
+  async function refreshPendingExpiries(ids) {
+    const summaries = store.snapshot().conversationSummaries;
+    const counted = ids.filter((id) => (summaries.get(id)?.unreadCount ?? 0) > 0);
+    ids.forEach((id) => pendingExpiry.delete(id));
+    if (counted.length > 0) {
+      const pending = await repository.pendingSoftExpiries(counted);
+      if (disposed) return;
+      learnServerClock(pending.serverNow);
+      pending.byConversation.forEach(
+        (at, id) => noteSoftExpiry(id, softExpiryTime({ softExpiresAt: at }))
+      );
+    }
+    scheduleExpiryTimer();
+  }
+  async function fireSoftExpiry() {
+    if (disposed) return;
+    const at = now();
+    const due = [...pendingExpiry.entries()].filter(([, expiry]) => expiry <= at).map(([id]) => id);
+    due.forEach((id) => pendingExpiry.delete(id));
+    await Promise.all(
+      due.map(async (id) => {
+        if ((store.snapshot().conversationSummaries.get(id)?.unreadCount ?? 0) === 0) return;
+        try {
+          const count = await repository.unreadCount(id);
+          if (!disposed) store.setUnreadCount(id, count);
+        } catch (error) {
+          reportError(error, "softExpiryUnread", { conversationId: id });
+        }
+      })
+    );
+    if (disposed) return;
+    await refreshPendingExpiries(due).catch(
+      (error) => reportError(error, "softExpiryRefresh")
+    );
+  }
+  function watchSoftExpiries(ids) {
+    void refreshPendingExpiries(ids).catch(
+      (error) => reportError(error, "softExpiryRefresh")
+    );
+  }
   const outbox = createOutbox({
     ...options.outboxStorage !== void 0 ? { storage: options.outboxStorage } : {},
     send: (draft, clientMessageId) => repository.insertMessage(draft, clientMessageId),
@@ -1482,7 +1578,8 @@ function createMessagingEngine(options) {
             ...entry.draft.replyToId !== void 0 ? { replyToId: entry.draft.replyToId } : {},
             ...entry.draft.action !== void 0 ? { action: entry.draft.action } : {},
             ...entry.draft.attachments !== void 0 ? { attachments: [...entry.draft.attachments] } : {},
-            ...entry.draft.references !== void 0 ? { references: [...entry.draft.references] } : {}
+            ...entry.draft.references !== void 0 ? { references: [...entry.draft.references] } : {},
+            ...entry.draft.softExpiresAt !== void 0 ? { softExpiresAt: entry.draft.softExpiresAt } : {}
           })
         );
       });
@@ -1511,6 +1608,7 @@ function createMessagingEngine(options) {
     if (disposed) return;
     conversationCursor = page.nextCursor;
     store.setConversations(page.items, page.hasMore);
+    watchSoftExpiries([...store.snapshot().conversationSummaries.keys()]);
   }
   async function reloadArchivedCount() {
     if (disposed) return;
@@ -1705,6 +1803,7 @@ function createMessagingEngine(options) {
               store.ingest(message);
               const isMine = message.senderId === identity.userId;
               store.applyLastMessage(message, { incrementUnread: !isMine });
+              if (!isMine) noteSoftExpiry(message.conversationId, softExpiryTime(message));
               if (!isMine && store.snapshot().activeConversationId === message.conversationId) {
                 void persistRead(message.conversationId).catch(() => void 0);
               }
@@ -1766,6 +1865,7 @@ function createMessagingEngine(options) {
         });
         conversationCursor = page.nextCursor;
         store.appendConversations(page.items, page.hasMore);
+        watchSoftExpiries(page.items.map((item) => item.conversation.id));
       } catch (error) {
         reportError(error, "loadMoreConversations");
       }
@@ -1785,7 +1885,10 @@ function createMessagingEngine(options) {
         const directSummary = missingSummary ? await repository.getConversationSummary(id) : null;
         if (!openIsLive(id, generation, ownedChannel)) return;
         store.setConversationReadFailure(id, null);
-        if (directSummary !== null) store.setConversationSummary(directSummary);
+        if (directSummary !== null) {
+          store.setConversationSummary(directSummary);
+          watchSoftExpiries([id]);
+        }
         await persistRead(
           id,
           () => openIsLive(id, generation, ownedChannel)
@@ -1880,6 +1983,9 @@ function createMessagingEngine(options) {
     },
     dispose() {
       disposed = true;
+      if (expiryTimer !== null) clearTimeout(expiryTimer);
+      expiryTimer = null;
+      pendingExpiry.clear();
       openChannels.forEach((_handle, id) => {
         initialReadGeneration.set(id, (initialReadGeneration.get(id) ?? 0) + 1);
       });
@@ -2141,10 +2247,13 @@ var RPCS = {
   /** Conversation list + participants + last message + unread, keyset paged. */
   conversationsWithDetails: "get_dm_conversations_with_details",
   unreadCount: "get_dm_unread_count",
+  /** The soonest future soft expiry per conversation, plus the server's clock. */
+  pendingSoftExpiries: "get_dm_pending_soft_expiries",
   userInfo: "get_dm_user_info",
   isParticipant: "is_dm_participant"
 };
-var MESSAGE_COLUMNS = "id,conversation_id,sender_id,organization_id,content,message_type,status,reply_to_id,client_message_id,action_data,media_url,media_thumbnail_url,media_metadata,created_at,edited_at,deleted_at,deleted_for_everyone,metadata";
+var MESSAGE_COLUMNS = "id,conversation_id,sender_id,organization_id,content,message_type,status,reply_to_id,client_message_id,action_data,media_url,media_thumbnail_url,media_metadata,created_at,edited_at,deleted_at,deleted_for_everyone,metadata,soft_expires_at";
+var PENDING_SOFT_EXPIRY_CHUNK = 200;
 var PARTICIPANT_COLUMNS = "conversation_id,user_id,role,joined_at,last_read_at,is_muted,is_archived";
 var CONVERSATION_COLUMNS = "id,type,group_name,group_image_url,created_by,organization_id,created_at,updated_at,metadata";
 function optionalOrg(organizationId) {
@@ -2565,6 +2674,9 @@ function createMessagingRepository(options) {
         // confirmed row instead of showing the message twice.
         client_message_id: clientMessageId,
         action_data: draft.action ?? null,
+        // SOFT EXPIRY: written only when the sender sets one. Lapsed is
+        // derived from it live (`isLapsed`), never stamped.
+        ...draft.softExpiresAt !== void 0 ? { soft_expires_at: draft.softExpiresAt } : {},
         metadata: {
           ...draft.metadata ?? {},
           ...draft.attachments !== void 0 && draft.attachments.length > 0 ? { attachments: draft.attachments } : {},
@@ -2617,6 +2729,56 @@ function createMessagingRepository(options) {
       }
       return Math.floor(unread);
     },
+    async unreadCount(conversationId) {
+      const operation = "unreadCount";
+      const me = await actingUser(operation);
+      const unread = await withSessionRetry(
+        operation,
+        () => rpc(
+          RPCS.unreadCount,
+          { p_conversation_id: conversationId, p_user_id: me },
+          operation
+        )
+      );
+      if (typeof unread !== "number" || !Number.isFinite(unread) || unread < 0) {
+        throw invalidResponse(operation, `${RPCS.unreadCount} returned ${JSON.stringify(unread)}`);
+      }
+      return Math.floor(unread);
+    },
+    async pendingSoftExpiries(conversationIds) {
+      const operation = "pendingSoftExpiries";
+      const unique = [...new Set(conversationIds)];
+      const byConversation = /* @__PURE__ */ new Map();
+      let serverNow = null;
+      for (let start = 0; start < unique.length; start += PENDING_SOFT_EXPIRY_CHUNK) {
+        const chunk = unique.slice(start, start + PENDING_SOFT_EXPIRY_CHUNK);
+        const answer = await withSessionRetry(
+          operation,
+          () => rpc(
+            RPCS.pendingSoftExpiries,
+            { p_conversation_ids: chunk },
+            operation
+          )
+        );
+        const now = answer?.["server_now"];
+        const pending = answer?.["pending"];
+        if (typeof now !== "string" || !Array.isArray(pending)) {
+          throw invalidResponse(
+            operation,
+            `${RPCS.pendingSoftExpiries} returned ${JSON.stringify(answer)}`
+          );
+        }
+        serverNow = now;
+        for (const row of pending) {
+          const id = row["conversation_id"];
+          const at = row["soft_expires_at"];
+          if (typeof id === "string" && typeof at === "string") {
+            byConversation.set(id, at);
+          }
+        }
+      }
+      return { byConversation, serverNow };
+    },
     async setConversationFlags(conversationId, flags) {
       const operation = "setConversationFlags";
       const me = await actingUser(operation);