@antzsoft/chat-core 1.4.2 → 1.4.3

package/README.md

@@ -819,9 +819,10 @@ Forwarding creates an **independent copy** of a message in each target conversat
 
 | Field / method | Type | Description |
 |---|---|---|
-| `messagesApi.forward(messageId, targetConversationIds)` | `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. |
+| `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:**
 
@@ -856,13 +857,18 @@ 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]);
 ```
 
-**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 (client convention: `forwardDepth >= 4`), and server-side, the reduced 1-target fan-out cap once `forwardDepth >= 5` (see Limits above). 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.
+**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 >= 4`) 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 and exposes a "Forward" action in the message menu — no extra wiring needed if you're using the prebuilt UI.
+**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
 

package/dist/index.cjs

@@ -108,6 +108,7 @@ __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,
@@ -1014,6 +1015,7 @@ 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;
@@ -1113,11 +1115,16 @@ var messagesApi = {
    * 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) {
+  async forward(messageId, targetConversationIds, attachmentIds) {
     const { data } = await getApiClient().post(
       `/messages/${messageId}/forward`,
-      { targetConversationIds }
+      { targetConversationIds, ...attachmentIds ? { attachmentIds } : {} }
     );
     return data;
   }
@@ -2113,6 +2120,7 @@ var AntzChatClient = class {
   AntzChatPermissionError,
   AntzChatServerError,
   AntzChatValidationError,
+  HIGHLY_FORWARDED_DEPTH_THRESHOLD,
   MAX_FORWARD_TARGETS,
   MENTION_ALL_ID,
   appConfigApi,