@antzsoft/chat-core 1.3.7 → 1.3.9

package/README.md

@@ -44,7 +44,8 @@ npm install @antzsoft/chat-core
 |---|---|
 | Authentication | Login, register, logout, token refresh (automatic on 401) |
 | Conversations | List, create (group/DM), update, delete, mute, pin, leave, manage members |
-| Messages | Send, edit, delete, react, star, pin, search, paginate |
+| Messages | Send, edit, delete, react, star, pin, search, paginate, @mention |
+| Mentions | Group @mentions with `@all` (admin-gated); token parse/build/render helpers; mention pierces mute |
 | File uploads | Presigned URL pipeline — request URL → upload binary (multipart POST for S3/local, PUT for Azure) → confirm. Files ≥ 10 MB on S3 or local use chunked multipart (parallel parts → complete). |
 | Real-time | Socket.IO wrapper — send/receive messages, typing, read receipts, presence |
 | State management | Zustand auth store (persisted) + chat store (typing users, online status, reply/edit state) |
@@ -778,6 +779,7 @@ interface SendData {
   attachments?: SendMessageAttachment[];
   replyTo?: string;      // messageId of the message being replied to
   tempId?: string;       // Client-generated ID for optimistic UI
+  mentions?: string[];   // Mentioned userIds ('all' for @all); derived from @[name](id) tokens in text
 }
 
 interface SearchParams {
@@ -862,6 +864,64 @@ After the user reads the messages, call `socketEmit.markRead(conversationId)` (s
 
 ---
 
+### Mentions (`@antzsoft/chat-core` utilities)
+
+Group @mentions let a user tag specific members (or everyone via `@all`). A mentioned
+user is notified **even if they muted the group** (the mention pierces mute), while
+everyone else follows normal mute rules. `@all` is server-gated to group **admins**.
+
+**Storage model.** A mention is stored inline in the message text as a self-describing
+token — `@[DisplayName](userId)`, and `@[all](all)` for @all — plus a flat
+`mentions: string[]` array on the message (denormalized userIds, `'all'` for @all).
+There are **no character offsets**: the token is self-locating and survives edits, and
+the embedded name is a *fallback* for rendering (the current name is resolved live).
+
+```typescript
+import {
+  parseMentions,
+  buildMentionText,
+  renderMentionParts,
+  extractMentionIds,
+  isMentionAll,
+  MENTION_ALL_ID,           // 'all'
+} from '@antzsoft/chat-core';
+```
+
+| Function | Signature | Use |
+|---|---|---|
+| `buildMentionText` | `(segments: MentionSegment[]) => { text; mentions }` | Composer: turn picked members into token text + the id array to send |
+| `parseMentions` | `(text) => ParsedMention[]` | Locate `@[name](id)` tokens (id, displayName, start, end) |
+| `renderMentionParts` | `(text, resolveName?) => MentionPart[]` | Split text into ordered `text`/`mention` parts for rendering |
+| `extractMentionIds` | `(text) => string[]` | Re-derive the id array from tokens (after an edit) |
+| `isMentionAll` | `(mentions?) => boolean` | True when the list targets everyone |
+
+```typescript
+// Compose — from a member picked in your @-autocomplete
+const { text, mentions } = buildMentionText([
+  'Hey ', { id: 'a1b2…', displayName: 'Alice' }, ', please review',
+]);
+// text     → "Hey @[Alice](a1b2…), please review"
+// mentions → ["a1b2…"]
+await messagesApi.send(conversationId, { text, mentions, tempId });
+
+// Render — resolve the CURRENT name from your directory; fall back to the token name
+const parts = renderMentionParts(message.content.text, (id, fallbackName) =>
+  participants.find((p) => p.userId === id)?.user?.displayName ?? fallbackName,
+);
+// parts: [{type:'text', text:'Hey '}, {type:'mention', id, displayName:'Alice'}, …]
+```
+
+**Name resolution (rename / departed member).** Always prefer the live-resolved name so
+renames show correctly; use the token's embedded name only when the id can't be resolved
+(a member who left, or a client without a directory). This mirrors how WhatsApp/Slack
+resolve mention names at render time.
+
+**Picking members.** Source the @-autocomplete from `conversationsApi.getMembers(conversationId)`
+(active members only — never pass `filter`) or the already-normalized
+`conversation.participants`. See the web/RN SDKs for a ready-made composer + renderer.
+
+---
+
 ### Conversations API (`conversationsApi`)
 
 ```typescript
@@ -2579,6 +2639,7 @@ interface Message {
   content: MessageContent;
   metadata?: MessageMetadata;
   replyTo?: MessageReplyReference;
+  mentions?: string[];       // v1.3.9+ — mentioned userIds ('all' for @all); denormalized from @[name](id) tokens in content.text
   reactions: MessageReaction[];
   status: 'sent' | 'delivered' | 'read' | 'failed' | 'deleted';
   /**
@@ -2656,6 +2717,7 @@ Returned by `messagesApi.getReceipts()`. Use as the initial load for a "Read by
 ```typescript
 interface MessageReceiptEntry {
   userId: string;
+  externalId?: string;    // external system user ID (non-builtin modes)
   displayName: string;
   avatarUrl?: string;
 }
@@ -2685,6 +2747,7 @@ Returned by `messagesApi.getReactions()`. Use as the data source for a reactions
 ```typescript
 interface ReactionUser {
   userId: string;
+  externalId?: string;    // external system user ID (non-builtin modes)
   displayName: string;
   avatarUrl?: string;
 }
@@ -2801,6 +2864,7 @@ interface MessageConfig {
 ```typescript
 interface Participant {
   userId: string;
+  externalId?: string;    // external system user ID (non-builtin modes); mirrored on user.externalId
   role: 'admin' | 'member';
   joinedAt: string;
   isActive?: boolean;
@@ -2848,6 +2912,7 @@ interface SendMessagePayload {
   attachments?: SendMessageAttachment[];
   replyTo?: string;           // messageId
   tempId: string;             // client-generated; echoed back in message_ack
+  mentions?: string[];        // mentioned userIds ('all' for @all); derived from @[name](id) tokens in text
 }
 
 interface SendMessageAttachment {
@@ -2893,6 +2958,7 @@ interface ReactionUpdatedEvent {
 interface TypingIndicatorEvent {
   conversationId: string;
   userId: string;
+  externalId?: string;    // external system user ID (non-builtin modes); absent in builtin mode
   username: string;
   displayName: string;
   avatarUrl?: string;
@@ -3056,6 +3122,34 @@ document.querySelectorAll('[data-conv-id]').forEach((el) => {
 
 ## Changelog
 
+### v1.3.9
+
+- **New: group @mentions.** Tag members in a group message; a mentioned user is notified even if they muted the group (the mention pierces mute). Mentions are stored inline in the message text as self-describing tokens `@[DisplayName](userId)` (and `@[all](all)` for @all), plus a flat, denormalized `mentions: string[]` array on the message for fan-out and "who was mentioned" lookups. No offsets are stored — the token is self-locating and survives edits.
+
+  - **New helpers** (all exported from the package root):
+    - `parseMentions(text)` → `ParsedMention[]` — locate tokens for rendering.
+    - `renderMentionParts(text, resolveName?)` → `MentionPart[]` — split text into ordered text/mention segments; pass `resolveName(id, fallbackName)` to show the *current* name from your directory (handles renames), falling back to the token's embedded name for departed/unresolvable users.
+    - `buildMentionText(segments)` → `{ text, mentions }` — compose token text + the id array from picked members.
+    - `extractMentionIds(text)` — re-derive the id array from tokens (use after an edit; a removed token drops out).
+    - `isMentionAll(mentions)` and the `MENTION_ALL_ID` constant (`'all'`).
+    - New types: `Mention` conventions via `ParsedMention`, `MentionPart`, `MentionSegment`.
+  - **Type changes:** `Message.mentions?: string[]` and `SendMessagePayload.mentions?: string[]` (both optional).
+  - **`conversationsApi.getMembers()`** now normalizes participants so `user.displayName`/`avatarUrl` arrive consistently — a drop-in name source for a mention picker.
+
+  **Backward compatible, additive-only.** Every field is optional. An old client viewing a mention message shows the readable token text (e.g. `@[Alice](…)`) rather than crashing; a new client renders a styled `@Alice`. Requires server support to persist/notify mentions; safe to upgrade regardless. **No integration changes required** unless you are building a mention composer/renderer.
+
+### v1.3.8
+
+- **`externalId` now surfaced on every embedded user shape, not just the standalone user profile.** Previously `externalId` (the user's ID in your external system, non-builtin modes) was only present on `User` returned from `usersApi.list/getById/updateProfile`. Every *denormalized* place a user appeared — conversation participants, message sender, reaction users, and read/delivery receipts — dropped it, forcing a separate `usersApi.getById()` call to map a chat user back to your own system. Those shapes now carry `externalId`:
+
+  - **`Participant`** — new top-level `externalId?` field, also mirrored onto `Participant.user.externalId`. (`conversationsApi` + conversation socket events.)
+  - **`Message.sender`** — now includes `externalId` (it is a `User`, so the field was always in the type; the server now populates it on the embed).
+  - **`ReactionUser`** (`messagesApi.getReactions`) — new `externalId?`.
+  - **`MessageReceiptEntry`** (`messagesApi.getReceipts`) — new `externalId?`.
+  - **`TypingIndicatorEvent`** (socket) — new `externalId?`. Present in non-builtin modes; **absent in builtin mode**, where no external identity exists.
+
+  **Backward compatible, additive-only.** Every field is optional (`externalId?`). An older SDK against this server simply ignores the extra field; this SDK against an older server sees `externalId` as `undefined`. Note `externalId` (a string, the chat user's external identity) is distinct from the pre-existing `Participant`-level `externalUserId` (a number) — both are sent; do not confuse them. Requires server v-with-this-change or newer to be populated; safe to upgrade regardless. **No integration changes required** — read `externalId` where you previously had to look it up separately.
+
 ### v1.3.7
 
 - **Docs only — no code changes.** Brought the docs fully up to date: added the missing

package/dist/index.cjs

@@ -106,8 +106,10 @@ __export(src_exports, {
   AntzChatPermissionError: () => AntzChatPermissionError,
   AntzChatServerError: () => AntzChatServerError,
   AntzChatValidationError: () => AntzChatValidationError,
+  MENTION_ALL_ID: () => MENTION_ALL_ID,
   appConfigApi: () => appConfigApi,
   authApi: () => authApi,
+  buildMentionText: () => buildMentionText,
   connectSocket: () => connectSocket,
   conversationsApi: () => conversationsApi,
   createAuthStore: () => createAuthStore,
@@ -116,6 +118,7 @@ __export(src_exports, {
   devicesApi: () => devicesApi,
   disconnectSocket: () => disconnectSocket,
   encryptPayload: () => encryptPayload,
+  extractMentionIds: () => extractMentionIds,
   fetchServerKeys: () => fetchServerKeys,
   generateEphemeralKey: () => generateEphemeralKey,
   getApiClient: () => getApiClient,
@@ -127,14 +130,17 @@ __export(src_exports, {
   getSocketStatus: () => getSocketStatus,
   initApiClient: () => initApiClient,
   initAuthStore: () => initAuthStore,
+  isMentionAll: () => isMentionAll,
   isTransitEnvelope: () => isTransitEnvelope,
   messagesApi: () => messagesApi,
   normalizeAxiosError: () => normalizeAxiosError,
   normalizeConversation: () => normalizeConversation,
   onSocketStatus: () => onSocketStatus,
+  parseMentions: () => parseMentions,
   performHandshake: () => performHandshake,
   reconnectSocket: () => reconnectSocket,
   refreshSocketAuth: () => refreshSocketAuth,
+  renderMentionParts: () => renderMentionParts,
   resetAuthStore: () => resetAuthStore,
   resolveConfig: () => resolveConfig,
   resolveSystemMessageText: () => resolveSystemMessageText,
@@ -1105,11 +1111,13 @@ function normalizeParticipant(p) {
   const hasUserDetails = p.displayName || p.username || p.avatarUrl;
   return {
     userId: p.userId,
+    externalId: p.externalId ?? p.user?.externalId,
     role: p.role,
     joinedAt: p.joinedAt,
     isActive: p.isActive,
     user: hasUserDetails ? {
       id: p.userId,
+      externalId: p.externalId,
       tenantId: "",
       email: "",
       username: p.username ?? "",
@@ -1217,7 +1225,7 @@ var conversationsApi = {
       `/conversations/${conversationId}/participants`,
       filter ? { params: { filter } } : void 0
     );
-    return data;
+    return (data ?? []).map(normalizeParticipant);
   },
   /**
    * Get unread message count for a single conversation.
@@ -1943,6 +1951,80 @@ var socketEmit = {
 // src/index.ts
 init_chat_store();
 
+// src/types/index.ts
+var MENTION_ALL_ID = "all";
+
+// src/utils/mentions.ts
+var MENTION_TOKEN_SOURCE = "@\\[([^\\]]+)\\]\\((all|[a-fA-F0-9]{24})\\)";
+function sanitizeDisplayName(name) {
+  return name.replace(/[\[\]()]/g, "").trim() || "user";
+}
+function parseMentions(text) {
+  if (!text) return [];
+  const re = new RegExp(MENTION_TOKEN_SOURCE, "g");
+  const out = [];
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    out.push({
+      id: m[2],
+      displayName: m[1],
+      start: m.index,
+      end: m.index + m[0].length
+    });
+  }
+  return out;
+}
+function renderMentionParts(text, resolveName) {
+  if (!text) return [];
+  const mentions = parseMentions(text);
+  if (mentions.length === 0) return [{ type: "text", text }];
+  const parts = [];
+  let cursor = 0;
+  for (const mn of mentions) {
+    if (mn.start > cursor) {
+      parts.push({ type: "text", text: text.slice(cursor, mn.start) });
+    }
+    const displayName = resolveName ? resolveName(mn.id, mn.displayName) : mn.displayName;
+    parts.push({ type: "mention", id: mn.id, displayName });
+    cursor = mn.end;
+  }
+  if (cursor < text.length) {
+    parts.push({ type: "text", text: text.slice(cursor) });
+  }
+  return parts;
+}
+function buildMentionText(segments) {
+  let text = "";
+  const ids = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const seg of segments) {
+    if (typeof seg === "string") {
+      text += seg;
+    } else {
+      text += `@[${sanitizeDisplayName(seg.displayName)}](${seg.id})`;
+      if (!seen.has(seg.id)) {
+        seen.add(seg.id);
+        ids.push(seg.id);
+      }
+    }
+  }
+  return { text, mentions: ids };
+}
+function extractMentionIds(text) {
+  const ids = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const mn of parseMentions(text)) {
+    if (!seen.has(mn.id)) {
+      seen.add(mn.id);
+      ids.push(mn.id);
+    }
+  }
+  return ids;
+}
+function isMentionAll(mentions) {
+  return !!mentions?.includes(MENTION_ALL_ID);
+}
+
 // src/client-facade.ts
 var AntzChatClient = class {
   constructor(rawConfig) {
@@ -2001,8 +2083,10 @@ var AntzChatClient = class {
   AntzChatPermissionError,
   AntzChatServerError,
   AntzChatValidationError,
+  MENTION_ALL_ID,
   appConfigApi,
   authApi,
+  buildMentionText,
   connectSocket,
   conversationsApi,
   createAuthStore,
@@ -2011,6 +2095,7 @@ var AntzChatClient = class {
   devicesApi,
   disconnectSocket,
   encryptPayload,
+  extractMentionIds,
   fetchServerKeys,
   generateEphemeralKey,
   getApiClient,
@@ -2022,14 +2107,17 @@ var AntzChatClient = class {
   getSocketStatus,
   initApiClient,
   initAuthStore,
+  isMentionAll,
   isTransitEnvelope,
   messagesApi,
   normalizeAxiosError,
   normalizeConversation,
   onSocketStatus,
+  parseMentions,
   performHandshake,
   reconnectSocket,
   refreshSocketAuth,
+  renderMentionParts,
   resetAuthStore,
   resolveConfig,
   resolveSystemMessageText,