@antzsoft/chat-core 1.3.7 → 1.3.9

package/dist/{storage-DJh54pps.d.cts → storage-C_b-SFFH.d.cts}

@@ -94,6 +94,18 @@ interface MessageContent {
     type: 'text' | 'attachment' | 'system';
     attachments?: Attachment[];
 }
+/**
+ * A @mention of a user in a group message.
+ *
+ * The mention is stored inline in `content.text` as a self-describing token
+ * `@[DisplayName](userId)` (and, for @all, `@[all](all)`). This flat array is a
+ * denormalized copy of the mentioned userIds, used for notification fan-out and
+ * "who was mentioned" lookups — it is NOT a positional/offset map.
+ *
+ * The reserved id `"all"` represents an @all mention (server resolves it to every
+ * active participant at send time).
+ */
+declare const MENTION_ALL_ID = "all";
 interface ReplyAttachmentSnapshot {
     type: FileType;
     filename: string;
@@ -139,6 +151,12 @@ interface Message {
     senderId: string;
     content: MessageContent;
     replyTo?: MessageReplyReference;
+    /**
+     * Flat list of mentioned userIds (denormalized from the `@[name](id)` tokens in
+     * `content.text`). Contains `"all"` for an @all mention. Used for fan-out and
+     * "mentions me" lookups; not a positional map.
+     */
+    mentions?: string[];
     reactions: MessageReaction[];
     lastReaction?: LastReaction | null;
     status: MessageStatus;
@@ -168,6 +186,8 @@ interface Message {
 }
 interface Participant {
     userId: string;
+    /** External system user ID of the chat user (non-builtin modes). Mirrors `user.externalId`. */
+    externalId?: string;
     role: ParticipantRole;
     joinedAt: string;
     isActive?: boolean;
@@ -379,6 +399,8 @@ interface MessageStarUpdatedEvent {
 interface TypingIndicatorEvent {
     conversationId: string;
     userId: string;
+    /** External system user ID (non-builtin modes). Absent in builtin mode. */
+    externalId?: string;
     username: string;
     displayName: string;
     avatarUrl?: string;
@@ -414,6 +436,8 @@ interface MessageDeliveredEvent {
 }
 interface MessageReceiptEntry {
     userId: string;
+    /** External system user ID (non-builtin modes). */
+    externalId?: string;
     displayName: string;
     avatarUrl?: string;
 }
@@ -508,6 +532,8 @@ interface ConversationSyncResponse {
 }
 interface ReactionUser {
     userId: string;
+    /** External system user ID (non-builtin modes). */
+    externalId?: string;
     displayName: string;
     avatarUrl?: string;
 }
@@ -550,6 +576,8 @@ interface SendMessagePayload {
     attachments?: SendMessageAttachment[];
     replyTo?: string;
     tempId: string;
+    /** Mentioned userIds (use `"all"` / MENTION_ALL_ID for @all). Derived from the tokens in `text`. */
+    mentions?: string[];
 }
 interface QuietHours {
     enabled: boolean;
@@ -817,4 +845,4 @@ declare function uploadBatchWithSlots(files: UploadableFile[], platformUploadFn:
     slotToFile: Map<string, FileResponse>;
 }>;
 
-export { type NewMessageEvent as $, type AuthResponse as A, type BatchUploadResult as B, type CrossConversationSyncResponse as C, type ConversationUpdatedEvent as D, type FileSizeLimits as E, type FileResponse as F, type LastReaction as G, type MessageAckEvent as H, type MessageContent as I, type MessageDeletedEvent as J, type MessageDeletedForMeEvent as K, type LoginCredentials as L, type Message as M, type MessageDeliveredEvent as N, type MessageMetadata as O, type PaginatedResponse as P, type MessageReaction as Q, type ResolvedCompressionConfig as R, type SendMessagePayload as S, type MessageReceiptEntry as T, type User as U, type MessageReplyReference as V, type MessageStarUpdatedEvent as W, type MessageUpdatedEvent as X, type MessagesDeliveredEvent as Y, type MultipartPartUrl as Z, type MultipartUploadInfo as _, type RegisterData as a, type OptimisticAttachment as a0, type PlatformCompressFn as a1, type PlatformUploadFn as a2, type PlatformUploadPartFn as a3, type QuietHours as a4, type ReactionGroup as a5, type ReactionUpdatedEvent as a6, type ReactionUser as a7, type ReadReceiptEvent as a8, type ReplyAttachmentSnapshot as a9, type ResolvedFileSizeLimits as aa, type SendMessageAttachment as ab, type SyncDeletedForMe as ac, type SyncDeliveredReceipt as ad, type SyncParticipantChange as ae, type SyncReactionEntry as af, type SyncReactions as ag, type SyncReadReceipt as ah, type SyncStarEntry as ai, type SystemMessageMetadata as aj, type TypingIndicatorEvent as ak, type UploadConfig as al, type UploadProgress as am, type UserStatusEvent as an, resolveConfig as ao, storageApi as ap, uploadBatch as aq, uploadBatchWithSlots as ar, type AuthTokens as b, type ConversationSyncResponse as c, type AppConfig as d, type CursorPaginatedResponse as e, type MessageReactionsResponse as f, type MessageReceiptsResponse as g, type ConversationListParams as h, type Conversation as i, type Participant as j, type ConversationUnreadCount as k, type UnreadSummary as l, type UserPreferences as m, type ResolvedConfig as n, type PersistStorage as o, type PresignedUrlRequest as p, type PresignedUrlResponse as q, type CompletedPart as r, type FileType as s, type AntzChatConfig as t, type UploadableFile as u, type Attachment as v, type CompressedFile as w, type CompressionAlgorithm as x, type CompressionConfig as y, type ConversationType as z };
+export { type MultipartUploadInfo as $, type AuthResponse as A, type BatchUploadResult as B, type CrossConversationSyncResponse as C, type ConversationUpdatedEvent as D, type FileSizeLimits as E, type FileResponse as F, type LastReaction as G, MENTION_ALL_ID as H, type MessageAckEvent as I, type MessageContent as J, type MessageDeletedEvent as K, type LoginCredentials as L, type Message as M, type MessageDeletedForMeEvent as N, type MessageDeliveredEvent as O, type PaginatedResponse as P, type MessageMetadata as Q, type ResolvedCompressionConfig as R, type SendMessagePayload as S, type MessageReaction as T, type User as U, type MessageReceiptEntry as V, type MessageReplyReference as W, type MessageStarUpdatedEvent as X, type MessageUpdatedEvent as Y, type MessagesDeliveredEvent as Z, type MultipartPartUrl as _, type RegisterData as a, type NewMessageEvent as a0, type OptimisticAttachment as a1, type PlatformCompressFn as a2, type PlatformUploadFn as a3, type PlatformUploadPartFn as a4, type QuietHours as a5, type ReactionGroup as a6, type ReactionUpdatedEvent as a7, type ReactionUser as a8, type ReadReceiptEvent as a9, type ReplyAttachmentSnapshot as aa, type ResolvedFileSizeLimits as ab, type SendMessageAttachment as ac, type SyncDeletedForMe as ad, type SyncDeliveredReceipt as ae, type SyncParticipantChange as af, type SyncReactionEntry as ag, type SyncReactions as ah, type SyncReadReceipt as ai, type SyncStarEntry as aj, type SystemMessageMetadata as ak, type TypingIndicatorEvent as al, type UploadConfig as am, type UploadProgress as an, type UserStatusEvent as ao, resolveConfig as ap, storageApi as aq, uploadBatch as ar, uploadBatchWithSlots as as, type AuthTokens as b, type ConversationSyncResponse as c, type AppConfig as d, type CursorPaginatedResponse as e, type MessageReactionsResponse as f, type MessageReceiptsResponse as g, type ConversationListParams as h, type Conversation as i, type Participant as j, type ConversationUnreadCount as k, type UnreadSummary as l, type UserPreferences as m, type ResolvedConfig as n, type PersistStorage as o, type PresignedUrlRequest as p, type PresignedUrlResponse as q, type CompletedPart as r, type FileType as s, type AntzChatConfig as t, type UploadableFile as u, type Attachment as v, type CompressedFile as w, type CompressionAlgorithm as x, type CompressionConfig as y, type ConversationType as z };

package/dist/{storage-DJh54pps.d.ts → storage-C_b-SFFH.d.ts}

@@ -94,6 +94,18 @@ interface MessageContent {
     type: 'text' | 'attachment' | 'system';
     attachments?: Attachment[];
 }
+/**
+ * A @mention of a user in a group message.
+ *
+ * The mention is stored inline in `content.text` as a self-describing token
+ * `@[DisplayName](userId)` (and, for @all, `@[all](all)`). This flat array is a
+ * denormalized copy of the mentioned userIds, used for notification fan-out and
+ * "who was mentioned" lookups — it is NOT a positional/offset map.
+ *
+ * The reserved id `"all"` represents an @all mention (server resolves it to every
+ * active participant at send time).
+ */
+declare const MENTION_ALL_ID = "all";
 interface ReplyAttachmentSnapshot {
     type: FileType;
     filename: string;
@@ -139,6 +151,12 @@ interface Message {
     senderId: string;
     content: MessageContent;
     replyTo?: MessageReplyReference;
+    /**
+     * Flat list of mentioned userIds (denormalized from the `@[name](id)` tokens in
+     * `content.text`). Contains `"all"` for an @all mention. Used for fan-out and
+     * "mentions me" lookups; not a positional map.
+     */
+    mentions?: string[];
     reactions: MessageReaction[];
     lastReaction?: LastReaction | null;
     status: MessageStatus;
@@ -168,6 +186,8 @@ interface Message {
 }
 interface Participant {
     userId: string;
+    /** External system user ID of the chat user (non-builtin modes). Mirrors `user.externalId`. */
+    externalId?: string;
     role: ParticipantRole;
     joinedAt: string;
     isActive?: boolean;
@@ -379,6 +399,8 @@ interface MessageStarUpdatedEvent {
 interface TypingIndicatorEvent {
     conversationId: string;
     userId: string;
+    /** External system user ID (non-builtin modes). Absent in builtin mode. */
+    externalId?: string;
     username: string;
     displayName: string;
     avatarUrl?: string;
@@ -414,6 +436,8 @@ interface MessageDeliveredEvent {
 }
 interface MessageReceiptEntry {
     userId: string;
+    /** External system user ID (non-builtin modes). */
+    externalId?: string;
     displayName: string;
     avatarUrl?: string;
 }
@@ -508,6 +532,8 @@ interface ConversationSyncResponse {
 }
 interface ReactionUser {
     userId: string;
+    /** External system user ID (non-builtin modes). */
+    externalId?: string;
     displayName: string;
     avatarUrl?: string;
 }
@@ -550,6 +576,8 @@ interface SendMessagePayload {
     attachments?: SendMessageAttachment[];
     replyTo?: string;
     tempId: string;
+    /** Mentioned userIds (use `"all"` / MENTION_ALL_ID for @all). Derived from the tokens in `text`. */
+    mentions?: string[];
 }
 interface QuietHours {
     enabled: boolean;
@@ -817,4 +845,4 @@ declare function uploadBatchWithSlots(files: UploadableFile[], platformUploadFn:
     slotToFile: Map<string, FileResponse>;
 }>;
 
-export { type NewMessageEvent as $, type AuthResponse as A, type BatchUploadResult as B, type CrossConversationSyncResponse as C, type ConversationUpdatedEvent as D, type FileSizeLimits as E, type FileResponse as F, type LastReaction as G, type MessageAckEvent as H, type MessageContent as I, type MessageDeletedEvent as J, type MessageDeletedForMeEvent as K, type LoginCredentials as L, type Message as M, type MessageDeliveredEvent as N, type MessageMetadata as O, type PaginatedResponse as P, type MessageReaction as Q, type ResolvedCompressionConfig as R, type SendMessagePayload as S, type MessageReceiptEntry as T, type User as U, type MessageReplyReference as V, type MessageStarUpdatedEvent as W, type MessageUpdatedEvent as X, type MessagesDeliveredEvent as Y, type MultipartPartUrl as Z, type MultipartUploadInfo as _, type RegisterData as a, type OptimisticAttachment as a0, type PlatformCompressFn as a1, type PlatformUploadFn as a2, type PlatformUploadPartFn as a3, type QuietHours as a4, type ReactionGroup as a5, type ReactionUpdatedEvent as a6, type ReactionUser as a7, type ReadReceiptEvent as a8, type ReplyAttachmentSnapshot as a9, type ResolvedFileSizeLimits as aa, type SendMessageAttachment as ab, type SyncDeletedForMe as ac, type SyncDeliveredReceipt as ad, type SyncParticipantChange as ae, type SyncReactionEntry as af, type SyncReactions as ag, type SyncReadReceipt as ah, type SyncStarEntry as ai, type SystemMessageMetadata as aj, type TypingIndicatorEvent as ak, type UploadConfig as al, type UploadProgress as am, type UserStatusEvent as an, resolveConfig as ao, storageApi as ap, uploadBatch as aq, uploadBatchWithSlots as ar, type AuthTokens as b, type ConversationSyncResponse as c, type AppConfig as d, type CursorPaginatedResponse as e, type MessageReactionsResponse as f, type MessageReceiptsResponse as g, type ConversationListParams as h, type Conversation as i, type Participant as j, type ConversationUnreadCount as k, type UnreadSummary as l, type UserPreferences as m, type ResolvedConfig as n, type PersistStorage as o, type PresignedUrlRequest as p, type PresignedUrlResponse as q, type CompletedPart as r, type FileType as s, type AntzChatConfig as t, type UploadableFile as u, type Attachment as v, type CompressedFile as w, type CompressionAlgorithm as x, type CompressionConfig as y, type ConversationType as z };
+export { type MultipartUploadInfo as $, type AuthResponse as A, type BatchUploadResult as B, type CrossConversationSyncResponse as C, type ConversationUpdatedEvent as D, type FileSizeLimits as E, type FileResponse as F, type LastReaction as G, MENTION_ALL_ID as H, type MessageAckEvent as I, type MessageContent as J, type MessageDeletedEvent as K, type LoginCredentials as L, type Message as M, type MessageDeletedForMeEvent as N, type MessageDeliveredEvent as O, type PaginatedResponse as P, type MessageMetadata as Q, type ResolvedCompressionConfig as R, type SendMessagePayload as S, type MessageReaction as T, type User as U, type MessageReceiptEntry as V, type MessageReplyReference as W, type MessageStarUpdatedEvent as X, type MessageUpdatedEvent as Y, type MessagesDeliveredEvent as Z, type MultipartPartUrl as _, type RegisterData as a, type NewMessageEvent as a0, type OptimisticAttachment as a1, type PlatformCompressFn as a2, type PlatformUploadFn as a3, type PlatformUploadPartFn as a4, type QuietHours as a5, type ReactionGroup as a6, type ReactionUpdatedEvent as a7, type ReactionUser as a8, type ReadReceiptEvent as a9, type ReplyAttachmentSnapshot as aa, type ResolvedFileSizeLimits as ab, type SendMessageAttachment as ac, type SyncDeletedForMe as ad, type SyncDeliveredReceipt as ae, type SyncParticipantChange as af, type SyncReactionEntry as ag, type SyncReactions as ah, type SyncReadReceipt as ai, type SyncStarEntry as aj, type SystemMessageMetadata as ak, type TypingIndicatorEvent as al, type UploadConfig as am, type UploadProgress as an, type UserStatusEvent as ao, resolveConfig as ap, storageApi as aq, uploadBatch as ar, uploadBatchWithSlots as as, type AuthTokens as b, type ConversationSyncResponse as c, type AppConfig as d, type CursorPaginatedResponse as e, type MessageReactionsResponse as f, type MessageReceiptsResponse as g, type ConversationListParams as h, type Conversation as i, type Participant as j, type ConversationUnreadCount as k, type UnreadSummary as l, type UserPreferences as m, type ResolvedConfig as n, type PersistStorage as o, type PresignedUrlRequest as p, type PresignedUrlResponse as q, type CompletedPart as r, type FileType as s, type AntzChatConfig as t, type UploadableFile as u, type Attachment as v, type CompressedFile as w, type CompressionAlgorithm as x, type CompressionConfig as y, type ConversationType as z };

package/docs/integration-guide.html

@@ -155,7 +155,7 @@ section.sec>h2:hover{color:#fff}
 
   <div class="section-label">What's New</div>
   <ul>
-    <li><a href="#whats-new">v1.3.7 Release Notes</a></li>
+    <li><a href="#whats-new">v1.3.9 Release Notes</a></li>
   </ul>
 
   <div class="section-label">Getting Started</div>
@@ -250,12 +250,77 @@ section.sec>h2:hover{color:#fff}
   <h2>What's New</h2>
   <p style="color:var(--muted);font-size:13px;margin-bottom:20px">Version history and release notes. Click a version to expand.</p>
 
-  <!-- ── v1.3.7 (current) ── -->
+  <!-- ── v1.3.9 (current) ── -->
+  <div class="wn-version open" id="wn-139">
+    <div class="wn-header" onclick="toggleVersion('wn-139')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.3.9</span>
+        <span class="wn-badge current">Current</span>
+        <span class="wn-date">July 2026</span>
+      </div>
+      <span class="wn-chevron">▲</span>
+    </div>
+    <div class="wn-body">
+      <div class="wn-item" id="wn-139-mentions">
+        <div class="wn-item-header" onclick="toggleItem('wn-139-mentions')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">Group @mentions — tag members, @all (admin-gated), pierces mute</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Tag specific members in a group message, or everyone via <code>@all</code> (server-gated to group admins). A mentioned user is notified <strong>even if they muted the group</strong> — the mention pierces mute — while everyone else follows normal mute rules.</p>
+          <p><strong>Storage model.</strong> A mention is stored inline in the message text as a self-describing token <code>@[DisplayName](userId)</code> (and <code>@[all](all)</code> for @all), plus a flat <code>mentions: string[]</code> array on the message (denormalized userIds, <code>'all'</code> for @all). No character offsets are stored — the token is self-locating and survives edits; the embedded name is a render fallback while the current name is resolved live.</p>
+          <p><strong>New helpers</strong> (exported from the package root):</p>
+          <ul>
+            <li><code>buildMentionText(segments)</code> → <code>{ text, mentions }</code> — composer: turn picked members into token text + the id array.</li>
+            <li><code>parseMentions(text)</code> → <code>ParsedMention[]</code> — locate tokens.</li>
+            <li><code>renderMentionParts(text, resolveName?)</code> → <code>MentionPart[]</code> — split into ordered text/mention parts; <code>resolveName(id, fallbackName)</code> supplies the current display name (handles renames), falling back to the token name for departed users.</li>
+            <li><code>extractMentionIds(text)</code> — re-derive the id array after an edit.</li>
+            <li><code>isMentionAll(mentions)</code> and <code>MENTION_ALL_ID</code> (<code>'all'</code>).</li>
+          </ul>
+          <p><strong>Type changes:</strong> <code>Message.mentions?: string[]</code> and <code>SendMessagePayload.mentions?: string[]</code> (both optional). <code>conversationsApi.getMembers()</code> now normalizes participants so <code>user.displayName</code>/<code>avatarUrl</code> arrive consistently — a drop-in name source for a mention picker.</p>
+          <p><strong>Backward compatible, additive-only.</strong> An older client viewing a mention shows the readable token text (e.g. <code>@[Alice](…)</code>) rather than crashing; a new client renders a styled <code>@Alice</code>. Requires server support to persist/notify mentions; safe to upgrade regardless. <strong>No integration changes required</strong> unless you build a mention composer/renderer.</p>
+        </div>
+      </div>
+    </div>
+  </div><!-- /.wn-version -->
+
+  <!-- ── v1.3.8 ── -->
+  <div class="wn-version open" id="wn-138">
+    <div class="wn-header" onclick="toggleVersion('wn-138')">
+      <div class="wn-title">
+        <span class="wn-ver">v1.3.8</span>
+        <span class="wn-date">July 2026</span>
+      </div>
+      <span class="wn-chevron">▲</span>
+    </div>
+    <div class="wn-body">
+      <div class="wn-item" id="wn-138-externalid">
+        <div class="wn-item-header" onclick="toggleItem('wn-138-externalid')">
+          <span class="wn-tag new">New</span>
+          <span class="wn-item-title">externalId now included on every embedded user, not just the standalone profile</span>
+          <span class="wn-chevron-sm">▾</span>
+        </div>
+        <div class="wn-item-body">
+          <p>Previously <code>externalId</code> (a user's ID in your external system, non-builtin modes) was only present on the <code>User</code> returned by <code>usersApi.list/getById/updateProfile</code>. Every <em>denormalized</em> place a user appeared dropped it, forcing a separate <code>usersApi.getById()</code> call to map a chat user back to your own system. These shapes now carry it:</p>
+          <ul>
+            <li><code>Participant</code> — new top-level <code>externalId?</code>, also mirrored on <code>Participant.user.externalId</code> (conversations API + conversation socket events).</li>
+            <li><code>Message.sender</code> — the server now populates <code>externalId</code> on the sender embed.</li>
+            <li><code>ReactionUser</code> (<code>messagesApi.getReactions</code>) — new <code>externalId?</code>.</li>
+            <li><code>MessageReceiptEntry</code> (<code>messagesApi.getReceipts</code>) — new <code>externalId?</code>.</li>
+            <li><code>TypingIndicatorEvent</code> (socket) — new <code>externalId?</code>. Present in non-builtin modes; <strong>absent in builtin mode</strong>, where no external identity exists.</li>
+          </ul>
+          <p><strong>Backward compatible, additive-only.</strong> Every field is optional. An older SDK against this server ignores the extra field; this SDK against an older server sees <code>externalId</code> as <code>undefined</code>. Note <code>externalId</code> (string, the chat user's external identity) is distinct from the pre-existing <code>Participant.externalUserId</code> (number) — both are sent; do not confuse them. Requires a server with this change to be populated; safe to upgrade regardless. <strong>No integration changes required</strong> — read <code>externalId</code> where you previously had to look it up separately.</p>
+        </div>
+      </div>
+    </div>
+  </div><!-- /.wn-version -->
+
+  <!-- ── v1.3.7 ── -->
   <div class="wn-version open" id="wn-137">
     <div class="wn-header" onclick="toggleVersion('wn-137')">
       <div class="wn-title">
         <span class="wn-ver">v1.3.7</span>
-        <span class="wn-badge current">Current</span>
         <span class="wn-date">July 2026</span>
       </div>
       <span class="wn-chevron">▲</span>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antzsoft/chat-core",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "description": "Platform-agnostic core for Antz Chat — API, socket, stores, types. Works in browser, React Native (Expo or bare), and Node.js.",
   "author": "Antz",
   "license": "MIT",