@decentnetwork/peer 0.1.139 → 0.1.140

package/dist/index.d.ts

@@ -14,4 +14,4 @@ export { LegacyProtocolNotImplementedError } from "./runtime/errors.js";
 export type { CarrierPacket, FriendMessagePacket, FriendRequestPacket, InviteReqPacket, InviteRspPacket } from "./compat/packet.js";
 export type { ToxDhtCryptoRequest } from "./compat/tox-dht-crypto.js";
 export type { CarrierAddressParts } from "./compat/address.js";
-export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";
+export type { CompatibilityMode, CustomPacketEvent, FriendConnectionEvent, FriendConnectionStatus, FriendInfoEvent, FriendRequest, InlineFileEvent, InlineSendResult, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";

package/dist/peer.d.ts

@@ -1,7 +1,7 @@
 import { type BootstrapResult } from "./compat/bootstrap.js";
 import type { FriendRecord } from "./store/friends.js";
 import { type CarrierTurnServerInfo, type RtcIceServer } from "./ice-servers.js";
-import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";
+import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, InlineFileEvent, InlineSendResult, InviteEvent, InviteResponseEvent, LookupResult, NetworkNode, PeerOptions, SendTextUntilAckOptions, TextMessage } from "./types/peer.js";
 export declare class Peer {
     #private;
     private constructor();
@@ -140,7 +140,16 @@ export declare class Peer {
         name: string;
         data: Uint8Array;
         fileType?: "image" | "audio" | "text" | "unknown";
-    }): Promise<void>;
+        deliveryTimeoutMs?: number;
+    }): Promise<InlineSendResult>;
+    /**
+     * True when this friend is a NATIVE Carrier client (iOS/Android/C SDK): its
+     * DHT/relay key differs from its identity key, where a JS peer announces its
+     * identity key as its DHT key. Natives cannot see the toxcore file-transfer
+     * protocol (sendFile) — the inline envelope is their only file path — and
+     * they never speak the JS text-ACK scheme.
+     */
+    isNativeFriend(pubkey: string): boolean;
     /** Fired when a peer sends a Carrier friend-invite (PACKET_TYPE_INVITE_REQUEST).
      *  This is the channel the iOS/Android WebRTC SDK uses for call signaling —
      *  each RtcSignal arrives as an "invite" with ext="carrier" and `data` the

package/dist/peer.js

@@ -1240,6 +1240,9 @@ export class Peer {
         }
         await this.#sendTextPlain(pubkey, text);
     }
+    /** What #sendTextPlain actually did with the message — callers that promise
+     *  delivery semantics (inline files) need to know the path and, for the live
+     *  path, where the send window stood after the last fragment. */
     async #sendTextPlain(pubkey, text) {
         const friend = this.#friends.get(pubkey);
         if (!friend) {
@@ -1307,7 +1310,10 @@ export class Peer {
                 for (const p of livePackets) {
                     await this.#sendMessengerPacket(pubkey, PACKET_ID_MESSAGE, p);
                 }
-                return;
+                // Every fragment got a packet number BELOW the counter's position now —
+                // when the peer's implicit acks advance the window past it, the whole
+                // message is confirmed on their device.
+                return { via: "online", endPacketNumber: this.#friendSessions.get(pubkey)?.sendPacketNumber };
             }
             catch (error) {
                 const emsg = error.message;
@@ -1343,7 +1349,7 @@ export class Peer {
         // no session is simply a no-op.
         if (text.length === 0) {
             this.#debugLog(`sendText: empty connection-kick to ${pubkey} with no live session — dropping (not flooding express)`);
-            return;
+            return { via: "online" };
         }
         // Offline / fallback path via Carrier express HTTP store-and-forward.
         // Skipped entirely in control-plane-only mode (decentlan's data plane):
@@ -1353,7 +1359,7 @@ export class Peer {
         if (this.#express?.hasNodes() && !this.#opts.expressControlPlaneOnly) {
             await this.#express.sendOfflineText(pubkey, packet);
             this.#debugLog(`sendText: queued via express for ${pubkey}`);
-            return;
+            return { via: "offline" };
         }
         throw new Error("friend is offline and no express node is configured");
     }
@@ -1568,7 +1574,77 @@ export class Peer {
         if (envelope.length > CARRIER_MAX_APP_BULKMSG_LEN) {
             throw new Error(`inline file too large for the message channel (${envelope.length} bytes encoded, max ${CARRIER_MAX_APP_BULKMSG_LEN})`);
         }
-        await this.sendText(pubkey, envelope);
+        // The confirmation window scales with the payload: a floor for handshake
+        // latency plus time to move the envelope at a conservative 50 KB/s, capped
+        // so a dead session can't pin the caller for ages.
+        const deliveryTimeoutMs = opts.deliveryTimeoutMs ??
+            Math.min(180_000, 20_000 + Math.ceil(envelope.length / 50));
+        if (this.#shouldRequireTextAck(pubkey)) {
+            // JS peer: the app-level text-ACK is the strongest confirmation there is
+            // — the receiving app parsed the envelope. The retry interval must be
+            // longer than one full send of the payload, or a slow path gets the
+            // whole multi-MB envelope re-blasted mid-flight.
+            await this.sendTextUntilAck(pubkey, envelope, {
+                timeoutMs: deliveryTimeoutMs,
+                retryIntervalMs: Math.max(TEXT_ACK_RETRY_MS, Math.ceil(envelope.length / 100))
+            });
+            return { delivery: "acked" };
+        }
+        // Native peer (iOS/Android/C): it will never speak our text-ACK envelope,
+        // but its toxcore DOES acknowledge every reliable packet — the very signal
+        // its own SDK surfaces to the app as "Delivered". Wait for the send window
+        // to drain past our fragments.
+        const outcome = await this.#sendTextPlain(pubkey, envelope);
+        if (outcome.via === "offline")
+            return { delivery: "offline" };
+        if (outcome.endPacketNumber === undefined)
+            return { delivery: "accepted" };
+        const acked = await this.#awaitTransportAck(pubkey, outcome.endPacketNumber, deliveryTimeoutMs);
+        this.#debugLog(`inline file "${opts.name}" to ${pubkey}: transport ${acked ? "ACKED" : `NOT confirmed within ${deliveryTimeoutMs}ms`}`);
+        return { delivery: acked ? "acked" : "accepted" };
+    }
+    /**
+     * True once the friend's implicit acks (PACKET_ID_REQUEST walks) have moved
+     * our reliable send window past `endPacketNumber` — i.e. every packet we had
+     * sent by that point is confirmed received on their device. False when the
+     * window doesn't drain in time or the session dies/rekeys under us (a new
+     * session restarts the numbering, so the old position proves nothing).
+     */
+    async #awaitTransportAck(pubkey, endPacketNumber, timeoutMs) {
+        const watched = this.#friendSessions.get(pubkey);
+        if (!watched)
+            return false;
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const session = this.#friendSessions.get(pubkey);
+            if (session !== watched || !session.established)
+                return false;
+            const start = session.sendBufferStartNum;
+            if (start !== undefined) {
+                // Wraparound-safe: the window is ≤8192 packets, so a "distance" over
+                // 2^31 means start has passed endPacketNumber.
+                const pending = (endPacketNumber - start) >>> 0;
+                if (pending === 0 || pending > 0x80000000)
+                    return true;
+            }
+            else if (!session.sendArray || session.sendArray.size === 0) {
+                return true; // nothing left unacknowledged at all
+            }
+            if (Date.now() >= deadline)
+                return false;
+            await sleep(250);
+        }
+    }
+    /**
+     * True when this friend is a NATIVE Carrier client (iOS/Android/C SDK): its
+     * DHT/relay key differs from its identity key, where a JS peer announces its
+     * identity key as its DHT key. Natives cannot see the toxcore file-transfer
+     * protocol (sendFile) — the inline envelope is their only file path — and
+     * they never speak the JS text-ACK scheme.
+     */
+    isNativeFriend(pubkey) {
+        const friend = this.#friends.get(pubkey);
+        return !!(friend?.dhtPubkey && friend.dhtPubkey !== friend.pubkey);
     }
     /** Fired when a peer sends a Carrier friend-invite (PACKET_TYPE_INVITE_REQUEST).
      *  This is the channel the iOS/Android WebRTC SDK uses for call signaling —

package/dist/types/peer.d.ts

@@ -135,6 +135,23 @@ export type TextMessage = {
      *  can see when online delivery is failing and only offline messages land. */
     via?: "online" | "offline";
 };
+/**
+ * Outcome of an inline-file send — the caller's ONLY honest basis for a "sent"
+ * checkmark. "Bytes left this machine" is not delivery.
+ */
+export type InlineSendResult = {
+    /**
+     * - "acked": the peer CONFIRMED receipt — an app-level ACK from a JS peer,
+     *   or the toxcore transport ACK from a native one (the same signal Android
+     *   surfaces as ReceiptState.Delivered). Safe to mark "sent".
+     * - "accepted": the transport took the bytes but no confirmation arrived in
+     *   the window. NOT delivered as far as anyone can prove — mark it failed or
+     *   queued, never "sent".
+     * - "offline": stored on the express relay for the peer's next pull. Mark
+     *   it queued.
+     */
+    delivery: "acked" | "accepted" | "offline";
+};
 export type SendTextUntilAckOptions = {
     /** Stable id for retries across a caller-managed outbox. Defaults to a random id. */
     deliveryId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.139",
+  "version": "0.1.140",
   "description": "Pure TypeScript port of Elastos Carrier (toxcore-derived) P2P messaging. DHT, onion routing, TCP relay, FlatBuffers app payloads, Express offline relay. Wire-compatible with iOS Beagle and the Carrier C SDK.",
   "type": "module",
   "main": "./dist/index.js",