openzca 0.1.51 → 0.1.53

package/README.md

@@ -48,6 +48,9 @@ openzca msg send USER_ID "Reply text" --reply-id MSG_ID
 # Reply without DB using a listen --raw payload
 openzca msg send USER_ID "Reply text" --reply-message '{"threadId":"...","msgId":"...","cliMsgId":"...","content":"...","msgType":"webchat","senderId":"...","toId":"...","ts":"..."}'
 
+# Inspect how a formatted message expands before sending/chunking
+openzca msg analyze-text GROUP_ID "- item one\n- item two" --group --json
+
 # Listen for incoming messages
 openzca listen
 
@@ -100,6 +103,7 @@ You can also open the saved file manually (for example: `open qr.png` on macOS).
 | Command | Description |
 |---------|-------------|
 | `openzca msg send <threadId> <message>` | Send text with formatting (`**bold**`, `*italic*`, `~~strike~~`, etc.), group @mention resolution (`--raw` to skip formatting), and quote replies via `--reply-id` or `--reply-message` |
+| `openzca msg analyze-text <threadId> <message>` | Build and inspect the exact text payload `msg send` would hand to `zca-js`, including rendered text length, style count, mention count, `textProperties` size, and request size estimate |
 | `openzca msg image <threadId> [file]` | Send image(s) from file or URL |
 | `openzca msg video <threadId> [file]` | Send video(s) from file or URL; single `.mp4` inputs try native video mode |
 | `openzca msg voice <threadId> [file]` | Send voice message from local file or URL (`.aac`, `.mp3`, `.m4a`, `.wav`, `.ogg`) |
@@ -123,6 +127,8 @@ Media commands accept local files, `file://` paths, and repeatable `--url` optio
 `openzca msg video` attempts native video send for a single `.mp4` input by uploading the video and thumbnail to Zalo first. If `ffmpeg` is unavailable, the input is not a single `.mp4`, or native send fails, it falls back to the normal attachment send path. Use `--thumbnail <path-or-url>` to supply the preview image explicitly.
 Local paths using `~` are expanded automatically (for positional file args, `--url`, and `OPENZCA_LISTEN_MEDIA_DIR`).
 Group text sends via `openzca msg send --group` resolve unique `@Name` or `@userId` mentions against the current group member list using member ids, display names, and usernames. Mention offsets are computed after formatting markers are parsed, so messages like `**@Alice Nguyen** hello` work. If multiple members share the same label, the command fails instead of guessing.
+When formatted text would produce an oversized outbound payload, `openzca msg send` automatically splits it into multiple sequential text messages using the final outbound text and rebased style/mention offsets. The split happens after formatting is parsed, using both rendered text length and estimated request payload size rather than the raw input string.
+Use `openzca msg analyze-text ... --json` when you need to predict whether a formatted reply will expand into a large `textProperties` payload before attempting delivery.
 Reply flows:
 
 - `--reply-id <id>` resolves a stored message from the local DB by `msgId`, `cliMsgId`, or internal message uid. This requires DB persistence to be enabled for the profile.
@@ -386,6 +392,10 @@ Listener resilience override:
 - `OPENZCA_RECENT_GROUP_MAX_PAGES`: max websocket history pages to scan for `msg recent -g` when direct group-history path fails.
   - Default: `20`.
   - Increase if a group thread is old and not found quickly.
+- `OPENZCA_TEXT_MESSAGE_MAX_LENGTH`: max rendered characters allowed per outbound text chunk before `msg send` splits it.
+  - Default: `2000`.
+- `OPENZCA_TEXT_REQUEST_PARAMS_MAX_ESTIMATE`: max estimated serialized request size allowed per outbound text chunk before `msg send` splits it.
+  - Default: `4000`.
 - `OPENZCA_LISTEN_ENFORCE_SINGLE_OWNER`: enforce one `listen` owner process per profile.
   - Default: enabled.
   - Set to `0` to allow multiple listeners on the same profile (not recommended).

package/dist/cli.js

@@ -1979,9 +1979,6 @@ function parseTimeBoundaryInput(value, _nowMs = Date.now()) {
   return void 0;
 }
 
-// src/lib/text-send.ts
-import { ThreadType } from "zca-js";
-
 // src/lib/group-mentions.ts
 var ALLOWED_START_BOUNDARY_CHARS = /* @__PURE__ */ new Set(["(", "[", "{", "<", '"', ",", ";", ":"]);
 var ALLOWED_END_BOUNDARY_CHARS = /* @__PURE__ */ new Set([",", ";", ":", "!", "?", ")", "]", "}", ">", '"']);
@@ -2086,6 +2083,9 @@ function isMentionStartBoundary(text, atIndex) {
   return /\s/u.test(previous) || ALLOWED_START_BOUNDARY_CHARS.has(previous);
 }
 
+// src/lib/text-send.ts
+import { ThreadType } from "zca-js";
+
 // src/lib/text-styles.ts
 import { TextStyle } from "zca-js";
 var TAG_STYLE_MAP = {
@@ -2333,6 +2333,8 @@ function normalizeCodeBlockLeadingWhitespace(line) {
 }
 
 // src/lib/text-send.ts
+var ZALO_TEXT_MESSAGE_MAX_LENGTH = 2e3;
+var ZALO_TEXT_REQUEST_PARAMS_MAX_ESTIMATE = 4e3;
 async function buildTextSendPayload(params) {
   if (params.raw) {
     const mentions2 = await resolveGroupMentionsIfNeeded(params, params.message);
@@ -2346,6 +2348,127 @@ async function buildTextSendPayload(params) {
     mentions
   };
 }
+async function analyzeTextSendPayload(params) {
+  const payload = await buildTextSendPayload(params);
+  const payloadObject = normalizeTextSendPayload(payload);
+  const textProperties = buildTextProperties(payloadObject.styles);
+  const mentionInfo = buildMentionInfo(
+    params.threadType,
+    payloadObject.msg,
+    payloadObject.mentions
+  );
+  const requestParams = omitUndefined({
+    message: payloadObject.msg,
+    clientId: 17e11,
+    mentionInfo,
+    imei: params.threadType === ThreadType.Group ? void 0 : "000000000000000",
+    ttl: 0,
+    visibility: params.threadType === ThreadType.Group ? 0 : void 0,
+    toid: params.threadType === ThreadType.Group ? void 0 : params.threadId,
+    grid: params.threadType === ThreadType.Group ? params.threadId : void 0,
+    textProperties
+  });
+  return {
+    payload,
+    ...buildTextSendPayloadAnalysis({
+      payloadObject,
+      rawInputLength: params.message.length,
+      textProperties,
+      mentionInfo,
+      requestParamsLengthEstimate: JSON.stringify(requestParams).length,
+      threadType: params.threadType
+    })
+  };
+}
+function planTextSendPayloadsForDelivery(params) {
+  const maxMessageLength = resolvePositiveLimit(
+    params.maxMessageLength,
+    ZALO_TEXT_MESSAGE_MAX_LENGTH
+  );
+  const maxRequestParamsLengthEstimate = resolvePositiveLimit(
+    params.maxRequestParamsLengthEstimate,
+    ZALO_TEXT_REQUEST_PARAMS_MAX_ESTIMATE
+  );
+  const chunks = [];
+  const analyses = [];
+  const pending = [params.payload];
+  while (pending.length > 0) {
+    const currentPayload = pending.shift();
+    const analysis = analyzePreparedTextSendPayload({
+      payload: currentPayload,
+      threadType: params.threadType,
+      threadId: params.threadId
+    });
+    if (isTextSendPayloadWithinDeliveryLimits(analysis, {
+      maxMessageLength,
+      maxRequestParamsLengthEstimate
+    })) {
+      chunks.push(currentPayload);
+      analyses.push(analysis);
+      continue;
+    }
+    const targetLength = computeNextChunkLength(analysis, {
+      maxMessageLength,
+      maxRequestParamsLengthEstimate
+    });
+    const splitChunks = splitTextSendPayload(currentPayload, targetLength);
+    if (splitChunks.length <= 1) {
+      throw new Error(
+        `Unable to split formatted text payload into deliverable chunks within ${targetLength} characters.`
+      );
+    }
+    pending.unshift(...splitChunks);
+  }
+  return { chunks, analyses };
+}
+function splitTextSendPayload(payload, maxLength = ZALO_TEXT_MESSAGE_MAX_LENGTH) {
+  if (!Number.isInteger(maxLength) || maxLength <= 0) {
+    throw new Error("Text chunk size must be a positive integer");
+  }
+  const payloadObject = normalizeTextSendPayload(payload);
+  if (payloadObject.msg.length <= maxLength) {
+    return [payload];
+  }
+  const chunks = [];
+  let start = 0;
+  while (start < payloadObject.msg.length) {
+    const end = findChunkEnd(payloadObject, start, maxLength);
+    chunks.push(sliceTextSendPayload(payloadObject, start, end));
+    start = end;
+  }
+  return chunks;
+}
+function analyzePreparedTextSendPayload(params) {
+  const payloadObject = normalizeTextSendPayload(params.payload);
+  const textProperties = buildTextProperties(payloadObject.styles);
+  const mentionInfo = buildMentionInfo(
+    params.threadType,
+    payloadObject.msg,
+    payloadObject.mentions
+  );
+  const requestParams = omitUndefined({
+    message: payloadObject.msg,
+    clientId: 17e11,
+    mentionInfo,
+    imei: params.threadType === ThreadType.Group ? void 0 : "000000000000000",
+    ttl: 0,
+    visibility: params.threadType === ThreadType.Group ? 0 : void 0,
+    toid: params.threadType === ThreadType.Group ? void 0 : params.threadId,
+    grid: params.threadType === ThreadType.Group ? params.threadId : void 0,
+    textProperties
+  });
+  return {
+    payload: params.payload,
+    ...buildTextSendPayloadAnalysis({
+      payloadObject,
+      rawInputLength: payloadObject.msg.length,
+      textProperties,
+      mentionInfo,
+      requestParamsLengthEstimate: JSON.stringify(requestParams).length,
+      threadType: params.threadType
+    })
+  };
+}
 async function resolveGroupMentionsIfNeeded(params, text) {
   if (params.threadType !== ThreadType.Group) {
     return void 0;
@@ -2360,6 +2483,208 @@ async function resolveGroupMentionsIfNeeded(params, text) {
   const mentions = resolveOutboundGroupMentions(text, members);
   return mentions.length > 0 ? mentions : void 0;
 }
+function normalizeTextSendPayload(payload) {
+  if (typeof payload === "string") {
+    return { msg: payload };
+  }
+  return payload;
+}
+function buildTextSendPayloadAnalysis(params) {
+  return {
+    payloadObject: params.payloadObject,
+    rawInputLength: params.rawInputLength,
+    renderedTextLength: params.payloadObject.msg.length,
+    styleCount: params.payloadObject.styles?.length ?? 0,
+    mentionCount: params.payloadObject.mentions?.length ?? 0,
+    textPropertiesLength: params.textProperties?.length ?? 0,
+    mentionInfoLength: params.mentionInfo?.length ?? 0,
+    requestParamsLengthEstimate: params.requestParamsLengthEstimate,
+    sendPath: params.threadType === ThreadType.Group ? params.mentionInfo ? "mention" : "sendmsg" : "sms"
+  };
+}
+function isTextSendPayloadWithinDeliveryLimits(analysis, limits) {
+  return analysis.renderedTextLength <= limits.maxMessageLength && analysis.requestParamsLengthEstimate <= limits.maxRequestParamsLengthEstimate;
+}
+function computeNextChunkLength(analysis, limits) {
+  const currentLength = analysis.renderedTextLength;
+  const targetLengths = [limits.maxMessageLength, currentLength - 1].filter((value) => value > 0);
+  if (analysis.requestParamsLengthEstimate > limits.maxRequestParamsLengthEstimate) {
+    targetLengths.push(
+      Math.floor(
+        currentLength * limits.maxRequestParamsLengthEstimate / analysis.requestParamsLengthEstimate
+      )
+    );
+  }
+  const targetLength = Math.max(
+    1,
+    Math.min(...targetLengths.filter((value) => Number.isFinite(value) && value > 0))
+  );
+  return Math.min(targetLength, currentLength - 1);
+}
+function resolvePositiveLimit(value, fallback) {
+  if (!value || !Number.isInteger(value) || value <= 0) {
+    return fallback;
+  }
+  return value;
+}
+function sliceTextSendPayload(payloadObject, start, end) {
+  const msg2 = payloadObject.msg.slice(start, end);
+  const styles = sliceStyles(payloadObject.styles, start, end);
+  const mentions = sliceMentions(payloadObject.mentions, start, end);
+  if (!styles && !mentions) {
+    return msg2;
+  }
+  return omitUndefined({
+    msg: msg2,
+    styles,
+    mentions
+  });
+}
+function sliceStyles(styles, start, end) {
+  if (!styles || styles.length === 0) {
+    return void 0;
+  }
+  const sliced = [];
+  for (const style of styles) {
+    const styleStart = style.start;
+    const styleEnd = style.start + style.len;
+    const overlapStart = Math.max(styleStart, start);
+    const overlapEnd = Math.min(styleEnd, end);
+    if (overlapStart >= overlapEnd) {
+      continue;
+    }
+    if (style.st === "ind_$") {
+      sliced.push({
+        start: overlapStart - start,
+        len: overlapEnd - overlapStart,
+        st: style.st,
+        indentSize: style.indentSize
+      });
+      continue;
+    }
+    sliced.push({
+      start: overlapStart - start,
+      len: overlapEnd - overlapStart,
+      st: style.st
+    });
+  }
+  return sliced.length > 0 ? sliced : void 0;
+}
+function sliceMentions(mentions, start, end) {
+  if (!mentions || mentions.length === 0) {
+    return void 0;
+  }
+  const sliced = mentions.filter((mention) => mention.pos >= start && mention.pos + mention.len <= end).map((mention) => ({
+    pos: mention.pos - start,
+    uid: mention.uid,
+    len: mention.len
+  }));
+  return sliced.length > 0 ? sliced : void 0;
+}
+function findChunkEnd(payloadObject, start, maxLength) {
+  const remaining = payloadObject.msg.length - start;
+  if (remaining <= maxLength) {
+    return payloadObject.msg.length;
+  }
+  const maxEnd = start + maxLength;
+  const newlineBreak = findPreferredBreak(payloadObject, start, maxEnd, "\n");
+  if (newlineBreak > start) {
+    return newlineBreak;
+  }
+  const whitespaceBreak = findWhitespaceBreak(payloadObject, start, maxEnd);
+  if (whitespaceBreak > start) {
+    return whitespaceBreak;
+  }
+  for (let cursor = maxEnd; cursor > start; cursor -= 1) {
+    if (isSafeSplitPosition(payloadObject.mentions, cursor)) {
+      return cursor;
+    }
+  }
+  throw new Error(
+    `Unable to split text payload safely within ${maxLength} characters.`
+  );
+}
+function findPreferredBreak(payloadObject, start, maxEnd, marker) {
+  for (let cursor = maxEnd; cursor > start; cursor -= 1) {
+    if (!isSafeSplitPosition(payloadObject.mentions, cursor)) {
+      continue;
+    }
+    if (payloadObject.msg[cursor - 1] === marker) {
+      return cursor;
+    }
+  }
+  return start;
+}
+function findWhitespaceBreak(payloadObject, start, maxEnd) {
+  for (let cursor = maxEnd; cursor > start; cursor -= 1) {
+    if (!isSafeSplitPosition(payloadObject.mentions, cursor)) {
+      continue;
+    }
+    const previousChar = payloadObject.msg[cursor - 1];
+    if (previousChar === " " || previousChar === "	") {
+      return cursor;
+    }
+  }
+  return start;
+}
+function isSafeSplitPosition(mentions, position) {
+  if (!mentions || mentions.length === 0) {
+    return true;
+  }
+  return mentions.every((mention) => {
+    const mentionEnd = mention.pos + mention.len;
+    return position <= mention.pos || position >= mentionEnd;
+  });
+}
+function buildTextProperties(styles) {
+  if (!styles || styles.length === 0) {
+    return void 0;
+  }
+  return JSON.stringify({
+    styles: styles.map((style) => {
+      if (style.st === "ind_$") {
+        return omitUndefined({
+          start: style.start,
+          len: style.len,
+          st: `ind_${style.indentSize ?? 1}0`
+        });
+      }
+      return {
+        start: style.start,
+        len: style.len,
+        st: style.st
+      };
+    }),
+    ver: 0
+  });
+}
+function buildMentionInfo(threadType, msg2, mentions) {
+  if (threadType !== ThreadType.Group || !mentions || mentions.length === 0) {
+    return void 0;
+  }
+  let totalMentionLen = 0;
+  const mentionsFinal = mentions.filter((mention) => mention.pos >= 0 && Boolean(mention.uid) && mention.len > 0).map((mention) => {
+    totalMentionLen += mention.len;
+    return {
+      pos: mention.pos,
+      uid: mention.uid,
+      len: mention.len,
+      type: mention.uid === "-1" ? 1 : 0
+    };
+  });
+  if (totalMentionLen > msg2.length) {
+    throw new Error("Invalid mentions: total mention characters exceed message length");
+  }
+  if (mentionsFinal.length === 0) {
+    return void 0;
+  }
+  return JSON.stringify(mentionsFinal);
+}
+function omitUndefined(value) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== void 0)
+  );
+}
 
 // src/lib/video-send.ts
 import { execFile } from "child_process";
@@ -6435,24 +6760,90 @@ msg.command("send <threadId> <message>").option("-g, --group", "Send to group").
       ...typeof textPayload === "string" ? { msg: textPayload } : textPayload,
       ...quote ? { quote } : {}
     } : textPayload;
-    const response = await api.sendMessage(payload, threadId, threadType);
+    const deliveryPlan = planTextSendPayloadsForDelivery({
+      payload: textPayload,
+      threadType,
+      threadId,
+      maxMessageLength: parsePositiveIntFromEnv(
+        "OPENZCA_TEXT_MESSAGE_MAX_LENGTH",
+        ZALO_TEXT_MESSAGE_MAX_LENGTH
+      ),
+      maxRequestParamsLengthEstimate: parsePositiveIntFromEnv(
+        "OPENZCA_TEXT_REQUEST_PARAMS_MAX_ESTIMATE",
+        ZALO_TEXT_REQUEST_PARAMS_MAX_ESTIMATE
+      )
+    });
+    const payloadChunks = deliveryPlan.chunks;
+    const responses = [];
+    const sentPayloads = [];
+    for (let index = 0; index < payloadChunks.length; index += 1) {
+      const chunk = payloadChunks[index];
+      const chunkPayload = quote && index === 0 ? {
+        ...typeof chunk === "string" ? { msg: chunk } : chunk,
+        quote
+      } : chunk;
+      sentPayloads.push(chunkPayload);
+      responses.push(await api.sendMessage(chunkPayload, threadId, threadType));
+    }
+    const response = responses.length === 1 ? responses[0] : {
+      chunked: true,
+      chunkCount: responses.length,
+      msgId: responses.at(-1)?.message?.msgId?.toString(),
+      response: responses
+    };
     output(response, false);
     if (await shouldWriteToDb(profile)) {
       scheduleDbWrite(profile, command, "msg.send.db.persist_error", async () => {
-        await persistOutgoingMessageBestEffort({
-          profile,
-          api,
-          threadId,
-          group: opts.group,
-          text: message,
-          msgType: "text",
-          response,
-          rawPayload: payload
-        });
+        if (payloadChunks.length === 1) {
+          await persistOutgoingMessageBestEffort({
+            profile,
+            api,
+            threadId,
+            group: opts.group,
+            text: message,
+            msgType: "text",
+            response,
+            rawPayload: payload
+          });
+          return;
+        }
+        for (let index = 0; index < payloadChunks.length; index += 1) {
+          const chunk = sentPayloads[index];
+          const chunkText = typeof chunk === "string" ? chunk : chunk.msg;
+          await persistOutgoingMessageBestEffort({
+            profile,
+            api,
+            threadId,
+            group: opts.group,
+            text: chunkText,
+            msgType: "text",
+            response: responses[index],
+            rawPayload: chunk
+          });
+        }
       });
     }
   })
 );
+msg.command("analyze-text <threadId> <message>").option("-g, --group", "Analyze as group text").option("--raw", "Analyze raw text without parsing formatting markers").option("-j, --json", "JSON output").description("Build and analyze the exact text payload that msg send would hand to zca-js. Useful for pre-send chunking/debugging.").action(
+  wrapAction(async (threadId, message, opts, command) => {
+    const threadType = asThreadType(opts.group);
+    const mentionProbeText = opts.raw ? message : parseTextStyles(message).text;
+    let listGroupMembers;
+    if (threadType === ThreadType3.Group && hasPotentialOutboundGroupMention(mentionProbeText)) {
+      const { api } = await requireApi(command);
+      listGroupMembers = (groupId) => listGroupMentionMembers(api, groupId);
+    }
+    const analysis = await analyzeTextSendPayload({
+      message,
+      raw: opts.raw,
+      threadType,
+      threadId,
+      listGroupMembers
+    });
+    output(analysis, shouldOutputJson(opts));
+  })
+);
 msg.command("image <threadId> [file]").option("-u, --url <url>", "Image URL (repeatable)", collectValues, []).option("-m, --message <message>", "Caption").option("-g, --group", "Send to group").description("Send image(s) from file or URL").action(
   wrapAction(
     async (threadId, file, opts, command) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openzca",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "Open-source zca-compatible CLI to integrate Zalo with OpenClaw",
   "type": "module",
   "bin": {