@eryxenx/insta-chat 2.0.3 → 2.0.4

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@eryxenx/insta-chat` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/) and uses
 [Semantic Versioning](https://semver.org/).
 
+## [2.0.4] - 2026-10-10
+
+### Fixed
+
+- **Captioned media lagged behind its text.** A message carrying both text and
+  an attachment uploads the media first, then commits the caption and the media
+  back-to-back, so the text and the image land together instead of the image
+  trailing by the whole upload time. Instagram's DM media mutation has no caption
+  field, so caption + attachment is still two messages; this only removes the
+  perceived gap after the caption.
+
+### Added
+
+- `antiSuspension.waitForTurn(threadID, { immediate })`: an immediate turn that
+  still counts against the volume caps but skips the inter-message gap, so a
+  captioned attachment can follow its caption at once.
+
 ## [1.0.12] - 2026-10-10
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eryxenx/insta-chat",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": " Unofficial Instagram Chat API for Node.js | Build Instagram DM bots on personal accounts \u2014 send messages, media, voice notes, reactions, edit & unsend, listen for incoming chats. No browser at runtime",
   "main": "index.js",
   "types": "index.d.ts",

package/src/methods/media.js

@@ -95,22 +95,28 @@ class MediaMethods {
   }
 
   async _send(threadID, uploadOptions, options) {
-    // The attached text is sent as its own message *before* the media, so the
-    // recipient sees the caption on top and the photo/attachment underneath.
-    // (GoatBot-Pro commands format a message as a header line followed by an
-    // image — sending the media first renders the image on top, which is not
-    // what the commands intend.) Media sends count against the same
-    // pacing/volume budget as text, so both are paced.
-    if (options.text) {
-      await globalAntiSuspension.waitForTurn(threadID);
-      await this._sendCaption(threadID, options.text);
-    }
-    await globalAntiSuspension.waitForTurn(threadID);
+    // Instagram's DM media mutation has no caption field, so an attachment with
+    // text is necessarily two messages. The recipient-visible contract is that
+    // the caption reaches Instagram before the media (so the text renders on top
+    // and the image underneath — what GoatBot-Pro commands intend).
+    //
+    // The upload is by far the slow part of a media send. If the caption is
+    // committed while the upload is still in flight, the text appears at once
+    // and the image arrives a couple of seconds later on its own. Doing the
+    // upload first and then committing caption + media back-to-back makes the
+    // two land together, which is what a person perceives as "one message".
     const metadata = await this._upload(threadID, uploadOptions);
     const fbid = metadata.fbid || metadata.video_id || metadata.audio_id;
     if (!fbid) throw new Error(`Upload returned no media id: ${JSON.stringify(metadata)}`);
     let result;
     try {
+      if (options.text) {
+        await globalAntiSuspension.waitForTurn(threadID);
+        await this._sendCaption(threadID, options.text);
+      }
+      // Count the media against the same pacing/volume budget, but with no gap
+      // after a caption so the image immediately follows the text.
+      await globalAntiSuspension.waitForTurn(threadID, { immediate: !!options.text });
       result = await this._commitMedia(threadID, fbid, options);
     } catch (error) {
       globalAntiSuspension.noteSendError(error);

package/src/utils/antiSuspension.js

@@ -204,19 +204,34 @@ class SendPacer extends EventEmitter {
     return true;
   }
 
-  waitForTurn(threadID) {
+  waitForTurn(threadID, opts) {
     if (!this.enabled) return Promise.resolve();
-    const run = this._queue.then(() => this._turn(threadID));
+    const run = this._queue.then(() => this._turn(threadID, opts));
     this._queue = run.catch(() => {});
     return run.catch(() => {});
   }
 
-  async _turn(threadID) {
+  async _turn(threadID, opts = {}) {
     this._rollWindows();
     this._decayStrikes();
     this._prune();
 
     const key = String(threadID);
+
+    // A captioned media is one logical message. Instagram's own client sends the
+    // caption text and the attachment back-to-back, not seconds apart, so the
+    // media pass asks for an immediate turn: still counted against the volume
+    // caps (so the hourly/daily budget stays accurate) but without the
+    // inter-message gap that made the image trail the text.
+    if (opts && opts.immediate) {
+      const stamp = Date.now();
+      this.lastSendAt = stamp;
+      this.perThreadLastSendAt.set(key, stamp);
+      this.hourSendCount++;
+      this.daySendCount++;
+      return;
+    }
+
     const cooling = this.isCoolingDown();
     const overCap = this.hourSendCount >= this._hourlyCap() || this.daySendCount >= this.dailyCap;