@antzsoft/chat-core 1.4.1 → 1.4.3

package/README.md

@@ -764,6 +764,7 @@ import { messagesApi } from '@antzsoft/chat-core';
 | `pin` | `(messageId: string) => Promise<Message>` | Pin a message. |
 | `unpin` | `(messageId: string) => Promise<Message>` | Unpin a message. |
 | `getPinned` | `(conversationId: string) => Promise<Message[]>` | List pinned messages in a conversation. |
+| `forward` | `(messageId: string, targetConversationIds: string[]) => Promise<ForwardResult[]>` | Forward a message into one or more conversations (v1.4.2+). Max `MAX_FORWARD_TARGETS` (5) targets per call, reduced to 1 if the source message has `forwardDepth >= 5`. Each target is independent — check `success`/`error` per entry in the returned array. No hard cap on forward count. |
 
 > **Delete permissions** — `delete()` (for everyone) requires either: the message belongs to the current user AND was sent within the delete window, OR the current user is a group admin. The server default window is **216,000 s (60 hours)** when `conversation.settings.messageConfig.deleteWindowSeconds` is not set. DMs have no admin role — only the sender can delete for everyone in a DM. `deleteForMe()` is always allowed for any message. See the [integration guide — Edit & Delete section](docs/integration-guide.html#step-edit) for a ready-to-use `getDeleteOptions()` helper.
 
@@ -812,6 +813,63 @@ await messagesApi.send('conv-abc', {
 const results = await messagesApi.search({ query: 'deployment', conversationId: 'conv-abc' });
 ```
 
+#### Forward Message (v1.4.2+)
+
+Forwarding creates an **independent copy** of a message in each target conversation — never a shared row. Each copy gets its own ID, sequence number, read receipts, and delete lifecycle; deleting one copy never affects another, and none of them affect the original.
+
+| Field / method | Type | Description |
+|---|---|---|
+| `messagesApi.forward(messageId, targetConversationIds, attachmentIds?)` | `Promise<ForwardResult[]>` | Forwards into up to `MAX_FORWARD_TARGETS` (5) conversations in one call — fewer if the source message is highly forwarded, see Limits below. Pass `attachmentIds` to forward only a subset of the source message's attachments (e.g. one image out of a multi-image message); omit it to forward the whole message unchanged. An ID not on the source message is ignored. |
+| `Message.forwardedFrom` | `MessageForwardReference \| undefined` | Present on a message created via forwarding. |
+| `MAX_FORWARD_TARGETS` | `number` | `5` — matches the server's normal-case cap. |
+| `HIGHLY_FORWARDED_DEPTH_THRESHOLD` | `number` | `5` — matches the server's `forwardDepth` value that triggers BOTH the "Forwarded many times" label and the reduced fan-out cap. Use this for the label instead of hardcoding a number. |
+
+**Limits:**
+
+| Limit | Value | Behavior when exceeded |
+|---|---|---|
+| Targets per call (normal) | 5 (`MAX_FORWARD_TARGETS`) | Client: `ForwardPicker` disables further selection. Server: request rejected with a validation error if bypassed. |
+| Targets per call — highly-forwarded content (`forwardDepth >= 5`) | **1** | Server silently truncates to the first target and reports every dropped target back as an explicit `{ success: false, error }` entry in `ForwardResult[]` — never a validation error, never a fully blocked forward. Matches WhatsApp's actual behavior: reduced fan-out, not a forwarding ban. |
+| Forward API rate limit | 20 calls/min per user | `429` if exceeded (server-side `@Throttle`, not currently surfaced as a distinct client-side pre-check). |
+| Forward-count hard cap | **None** | A message can be forwarded any number of times — there is no "forwarded too many times, blocked" state. Only fan-out width is reduced at high `forwardDepth`; `forwardDepth` itself only ever drives the "Forwarded many times" label. |
+
+Because dropped targets from the highly-forwarded cap come back as regular `ForwardResult` failures, existing "Forwarded to N/M chats" UI (see the example below) needs no special-casing to handle it correctly.
+
+```typescript
+interface MessageForwardReference {
+  originalMessageId: string;        // one hop back only — never the root of a longer chain
+  originalConversationId: string;   // one hop back only
+  originalSenderId: string;         // one hop back only — NOT the original author past 1 hop
+  forwardDepth: number;             // accumulates across the whole chain
+}
+
+interface ForwardResult {
+  conversationId: string;
+  success: boolean;
+  message?: Message;   // present when success is true
+  error?: string;      // present when success is false
+}
+```
+
+```typescript
+const results = await messagesApi.forward(messageId, [convA, convB, convC]);
+const failed = results.filter(r => !r.success);
+if (failed.length > 0) {
+  console.warn(`Forward failed for ${failed.length}/${results.length} conversations`, failed);
+}
+
+// Forward only one attachment out of a multi-attachment message (e.g. image 2 of 3)
+await messagesApi.forward(messageId, [convA], [message.content.attachments![1].id]);
+```
+
+**Where `forwardedFrom` is populated.** Every place a `Message` object is returned — `messagesApi.list`/`get`, the `new_message` socket event, `syncApi` (reconnect/resync), and REST list/search/starred/pinned — always includes `forwardedFrom` when present. **`conversation_updated`'s `lastMessage` field also includes it** (a conversation-list preview showing a forwarded message can render the "Forwarded" label without a separate message fetch). If `forwardDepth` ever reads as absent/`0` where you expected a value, that's a bug to report, not expected behavior — it should never be silently missing on any of these paths.
+
+**Why only one hop of lineage is kept.** `forwardedFrom` always points at the *immediate* message being forwarded, never the ultimate original — matching WhatsApp: if you forward a message that was itself already forwarded, the new copy's `originalMessageId`/`originalSenderId` reference that intermediate copy, not the very first message in the chain. This is intentional: it keeps the true original author untraceable after more than one hop (privacy), while `forwardDepth` still accumulates across the whole chain. `forwardDepth` drives two things, both purely about slowing spread, never about blocking it: the "Forwarded many times" badge, and server-side, the reduced 1-target fan-out cap — both gated on the SAME threshold, `HIGHLY_FORWARDED_DEPTH_THRESHOLD` (currently `5`, exported from the package root). Use that constant for the label rather than hardcoding a number, so the two never drift apart again. There is no API to walk a message's full forward history — only the immediate parent is ever resolvable, and there is no forward-count ceiling that ever blocks forwarding outright.
+
+**Attachments are never re-uploaded.** A forwarded attachment reuses the same underlying storage object as the source message — only the message row referencing it is new. This is transparent to SDK consumers; `forward()` handles it server-side.
+
+**Rendering:** show a "Forwarded" (or "Forwarded many times" at `forwardDepth >= HIGHLY_FORWARDED_DEPTH_THRESHOLD`) label when `message.forwardedFrom` is present — do not render a sender name or content preview for it (unlike `replyTo`), since the message's own `content` already holds what was forwarded. The built-in `MessageItem` component in both `@antzsoft/chat-web-sdk` and `@antzsoft/chat-rn-sdk` already renders this label using the exported constant and exposes a "Forward" action in the message menu — no extra wiring needed if you're using the prebuilt UI.
+
 #### Jump to first unread message
 
 Use `direction: 'after'` with the user's `lastReadMessageId` as the cursor to fetch only the unread messages. This powers a scroll-to-first-unread experience with an "↑ Unread messages" divider.

package/dist/chat.store-UVTDBPEC.js

@@ -0,0 +1,7 @@
+import {
+  useChatStore
+} from "./chunk-UIYJAOGL.js";
+export {
+  useChatStore
+};
+//# sourceMappingURL=chat.store-UVTDBPEC.js.map

package/dist/{chunk-EOL5B7GS.js → chunk-UIYJAOGL.js}

@@ -9,11 +9,12 @@ var useChatStore = create((set) => ({
   lastSeen: {},
   replyingTo: null,
   editingMessage: null,
+  forwardingMessage: null,
   isSidebarOpen: true,
   isGroupInfoOpen: false,
   isStarredPanelOpen: false,
   messageInfoId: null,
-  setActiveConversation: (id) => set({ activeConversationId: id, replyingTo: null, editingMessage: null }),
+  setActiveConversation: (id) => set({ activeConversationId: id, replyingTo: null, editingMessage: null, forwardingMessage: null }),
   setPendingTarget: (target) => set({ pendingTarget: target }),
   addTypingUser: (conversationId, user) => set((state) => {
     const existing = state.typingUsers[conversationId] ?? [];
@@ -45,6 +46,7 @@ var useChatStore = create((set) => ({
   }),
   setReplyingTo: (message) => set({ replyingTo: message, editingMessage: null }),
   setEditingMessage: (message) => set({ editingMessage: message, replyingTo: null }),
+  setForwardingMessage: (message) => set({ forwardingMessage: message }),
   toggleSidebar: () => set((state) => ({ isSidebarOpen: !state.isSidebarOpen })),
   setSidebarOpen: (open) => set({ isSidebarOpen: open }),
   toggleGroupInfo: () => set((state) => ({ isGroupInfoOpen: !state.isGroupInfoOpen })),
@@ -57,4 +59,4 @@ var useChatStore = create((set) => ({
 export {
   useChatStore
 };
-//# sourceMappingURL=chunk-EOL5B7GS.js.map
+//# sourceMappingURL=chunk-UIYJAOGL.js.map

package/dist/chunk-UIYJAOGL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stores/chat.store.ts"],"sourcesContent":["import { create } from 'zustand';\nimport type { Message } from '../types/index.js';\n\ninterface TypingUser {\n  userId: string;\n  displayName: string;\n  avatarUrl?: string;\n}\n\nexport interface LastReadEntry {\n  messageId: string;\n  readAt: string;\n}\n\ninterface ChatState {\n  activeConversationId: string | null;\n  pendingTarget: { conversationId: string; messageId: string } | null;\n  typingUsers: Record<string, TypingUser[]>;\n  onlineUsers: string[];\n  /** keyed by conversationId — current user's last read pointer per conversation */\n  lastRead: Record<string, LastReadEntry>;\n  /** keyed by userId — last seen timestamp for each user */\n  lastSeen: Record<string, string>;\n  replyingTo: Message | null;\n  editingMessage: Message | null;\n  /** Message staged in the forward picker, null = picker closed. Unlike replyingTo,\n   * this does not fold into the next composer send — forwarding targets a different\n   * conversation and needs its own conversation-picker UI. */\n  forwardingMessage: Message | null;\n  isSidebarOpen: boolean;\n  isGroupInfoOpen: boolean;\n  isStarredPanelOpen: boolean;\n  /** messageId currently shown in the Message Info panel, null = closed */\n  messageInfoId: string | null;\n\n  setActiveConversation: (id: string | null) => void;\n  setPendingTarget: (target: { conversationId: string; messageId: string } | null) => void;\n  addTypingUser: (conversationId: string, user: TypingUser) => void;\n  removeTypingUser: (conversationId: string, userId: string) => void;\n  setUserOnline: (userId: string) => void;\n  setUserOffline: (userId: string) => void;\n  setOnlineUsers: (userIds: string[]) => void;\n  setLastRead: (conversationId: string, messageId: string, readAt: string) => void;\n  setLastSeen: (userId: string, lastSeenAt: string | null) => void;\n  setReplyingTo: (message: Message | null) => void;\n  setEditingMessage: (message: Message | null) => void;\n  setForwardingMessage: (message: Message | null) => void;\n  toggleSidebar: () => void;\n  setSidebarOpen: (open: boolean) => void;\n  toggleGroupInfo: () => void;\n  setGroupInfoOpen: (open: boolean) => void;\n  toggleStarredPanel: () => void;\n  setStarredPanelOpen: (open: boolean) => void;\n  setMessageInfoId: (id: string | null) => void;\n}\n\nexport const useChatStore = create<ChatState>((set) => ({\n  activeConversationId: null,\n  pendingTarget: null,\n  typingUsers: {},\n  onlineUsers: [],\n  lastRead: {},\n  lastSeen: {},\n  replyingTo: null,\n  editingMessage: null,\n  forwardingMessage: null,\n  isSidebarOpen: true,\n  isGroupInfoOpen: false,\n  isStarredPanelOpen: false,\n  messageInfoId: null,\n\n  setActiveConversation: (id) =>\n    set({ activeConversationId: id, replyingTo: null, editingMessage: null, forwardingMessage: null }),\n\n  setPendingTarget: (target) => set({ pendingTarget: target }),\n\n  addTypingUser: (conversationId, user) =>\n    set((state) => {\n      const existing = state.typingUsers[conversationId] ?? [];\n      const deduped = existing.filter((u) => u.userId !== user.userId);\n      return { typingUsers: { ...state.typingUsers, [conversationId]: [...deduped, user] } };\n    }),\n\n  removeTypingUser: (conversationId, userId) =>\n    set((state) => ({\n      typingUsers: {\n        ...state.typingUsers,\n        [conversationId]: (state.typingUsers[conversationId] ?? []).filter(\n          (u) => u.userId !== userId,\n        ),\n      },\n    })),\n\n  setUserOnline: (userId) =>\n    set((state) => ({\n      onlineUsers: state.onlineUsers.includes(userId)\n        ? state.onlineUsers\n        : [...state.onlineUsers, userId],\n    })),\n\n  setUserOffline: (userId) =>\n    set((state) => ({ onlineUsers: state.onlineUsers.filter((id) => id !== userId) })),\n\n  setOnlineUsers: (userIds) => set({ onlineUsers: userIds }),\n\n  setLastRead: (conversationId, messageId, readAt) =>\n    set((state) => ({\n      lastRead: { ...state.lastRead, [conversationId]: { messageId, readAt } },\n    })),\n\n  setLastSeen: (userId, lastSeenAt) =>\n    set((state) => {\n      if (lastSeenAt === null) {\n        const { [userId]: _, ...rest } = state.lastSeen;\n        return { lastSeen: rest };\n      }\n      return { lastSeen: { ...state.lastSeen, [userId]: lastSeenAt } };\n    }),\n\n  setReplyingTo: (message) => set({ replyingTo: message, editingMessage: null }),\n\n  setEditingMessage: (message) => set({ editingMessage: message, replyingTo: null }),\n\n  setForwardingMessage: (message) => set({ forwardingMessage: message }),\n\n  toggleSidebar: () => set((state) => ({ isSidebarOpen: !state.isSidebarOpen })),\n  setSidebarOpen: (open) => set({ isSidebarOpen: open }),\n\n  toggleGroupInfo: () => set((state) => ({ isGroupInfoOpen: !state.isGroupInfoOpen })),\n  setGroupInfoOpen: (open) => set({ isGroupInfoOpen: open }),\n\n  toggleStarredPanel: () => set((state) => ({ isStarredPanelOpen: !state.isStarredPanelOpen })),\n  setStarredPanelOpen: (open) => set({ isStarredPanelOpen: open }),\n\n  setMessageInfoId: (id: string | null) => set({ messageInfoId: id }),\n}));\n"],"mappings":"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","names":[]}

package/dist/index.cjs

@@ -49,11 +49,12 @@ var init_chat_store = __esm({
       lastSeen: {},
       replyingTo: null,
       editingMessage: null,
+      forwardingMessage: null,
       isSidebarOpen: true,
       isGroupInfoOpen: false,
       isStarredPanelOpen: false,
       messageInfoId: null,
-      setActiveConversation: (id) => set({ activeConversationId: id, replyingTo: null, editingMessage: null }),
+      setActiveConversation: (id) => set({ activeConversationId: id, replyingTo: null, editingMessage: null, forwardingMessage: null }),
       setPendingTarget: (target) => set({ pendingTarget: target }),
       addTypingUser: (conversationId, user) => set((state) => {
         const existing = state.typingUsers[conversationId] ?? [];
@@ -85,6 +86,7 @@ var init_chat_store = __esm({
       }),
       setReplyingTo: (message) => set({ replyingTo: message, editingMessage: null }),
       setEditingMessage: (message) => set({ editingMessage: message, replyingTo: null }),
+      setForwardingMessage: (message) => set({ forwardingMessage: message }),
       toggleSidebar: () => set((state) => ({ isSidebarOpen: !state.isSidebarOpen })),
       setSidebarOpen: (open) => set({ isSidebarOpen: open }),
       toggleGroupInfo: () => set((state) => ({ isGroupInfoOpen: !state.isGroupInfoOpen })),
@@ -106,6 +108,8 @@ __export(src_exports, {
   AntzChatPermissionError: () => AntzChatPermissionError,
   AntzChatServerError: () => AntzChatServerError,
   AntzChatValidationError: () => AntzChatValidationError,
+  HIGHLY_FORWARDED_DEPTH_THRESHOLD: () => HIGHLY_FORWARDED_DEPTH_THRESHOLD,
+  MAX_FORWARD_TARGETS: () => MAX_FORWARD_TARGETS,
   MENTION_ALL_ID: () => MENTION_ALL_ID,
   appConfigApi: () => appConfigApi,
   authApi: () => authApi,
@@ -1010,6 +1014,8 @@ function resolveSystemMessageText(message, currentUserId) {
 }
 
 // src/api/messages.ts
+var MAX_FORWARD_TARGETS = 5;
+var HIGHLY_FORWARDED_DEPTH_THRESHOLD = 5;
 var messagesApi = {
   async list(conversationId, params = {}) {
     const { cursor, direction, ...rest } = params;
@@ -1103,6 +1109,24 @@ var messagesApi = {
   async getReceipts(messageId) {
     const { data } = await getApiClient().get(`/messages/${messageId}/receipts`);
     return data;
+  },
+  /**
+   * Forwards a message into one or more target conversations (max MAX_FORWARD_TARGETS
+   * per call, also enforced server-side). Each target is independent — one failing
+   * (e.g. no longer a participant) does not block the others; check `success`/`error`
+   * per entry in the returned array.
+   *
+   * Pass `attachmentIds` to forward only a subset of the source message's attachments
+   * (e.g. one image out of a multi-image message) — omit it to forward the whole
+   * message, including all its attachments, unchanged. An ID not present on the
+   * source message is ignored server-side.
+   */
+  async forward(messageId, targetConversationIds, attachmentIds) {
+    const { data } = await getApiClient().post(
+      `/messages/${messageId}/forward`,
+      { targetConversationIds, ...attachmentIds ? { attachmentIds } : {} }
+    );
+    return data;
   }
 };
 
@@ -2096,6 +2120,8 @@ var AntzChatClient = class {
   AntzChatPermissionError,
   AntzChatServerError,
   AntzChatValidationError,
+  HIGHLY_FORWARDED_DEPTH_THRESHOLD,
+  MAX_FORWARD_TARGETS,
   MENTION_ALL_ID,
   appConfigApi,
   authApi,