@decentnetwork/peer 0.1.32 → 0.1.34

package/dist/index.d.ts

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

package/dist/peer.d.ts

@@ -1,6 +1,6 @@
 import { type BootstrapResult } from "./compat/bootstrap.js";
 import type { FriendRecord } from "./store/friends.js";
-import type { FriendConnectionEvent, FriendRequest, FriendInfoEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
+import type { CustomPacketEvent, FriendConnectionEvent, FriendRequest, FriendInfoEvent, LookupResult, NetworkNode, PeerOptions, TextMessage } from "./types/peer.js";
 export declare class Peer {
     #private;
     private constructor();
@@ -74,6 +74,22 @@ export declare class Peer {
     waitForFriendConnected(pubkey: string, timeoutMs?: number): Promise<boolean>;
     onFriendRequest(cb: (req: FriendRequest) => void): void;
     onText(cb: (msg: TextMessage) => void): void;
+    /**
+     * Send an application-defined custom packet to a friend. `id` selects the
+     * channel and its delivery class by toxcore range: **160–191 lossless**
+     * (reliable, ordered) or **192–254 lossy** (best-effort). Apps layered on
+     * the peer use this to run their own protocols alongside chat without
+     * collision — e.g. decentlan sends IP traffic on `192`. Throws if `pubkey`
+     * is not a friend or the session has no transport (fail-fast; callers that
+     * want offline delivery should use a message instead).
+     */
+    sendCustomPacket(pubkey: string, id: number, data: Uint8Array): Promise<void>;
+    /**
+     * Receive application custom packets (toxcore lossless 160–191 / lossy
+     * 192–254). SDK-internal IDs are never delivered here. See
+     * {@link sendCustomPacket}.
+     */
+    onCustomPacket(cb: (evt: CustomPacketEvent) => void): void;
     onFriendConnection(cb: (ev: FriendConnectionEvent) => void): void;
     onFriendInfo(cb: (ev: FriendInfoEvent) => void): void;
     friends(): FriendRecord[];

package/dist/peer.js

@@ -891,6 +891,32 @@ export class Peer {
     onText(cb) {
         this.#events.on("text", cb);
     }
+    /**
+     * Send an application-defined custom packet to a friend. `id` selects the
+     * channel and its delivery class by toxcore range: **160–191 lossless**
+     * (reliable, ordered) or **192–254 lossy** (best-effort). Apps layered on
+     * the peer use this to run their own protocols alongside chat without
+     * collision — e.g. decentlan sends IP traffic on `192`. Throws if `pubkey`
+     * is not a friend or the session has no transport (fail-fast; callers that
+     * want offline delivery should use a message instead).
+     */
+    async sendCustomPacket(pubkey, id, data) {
+        if (!Number.isInteger(id) || id < 160 || id > 254) {
+            throw new Error(`custom packet id must be 160-254 (lossless 160-191 / lossy 192-254), got ${id}`);
+        }
+        if (!this.#friends.get(pubkey)) {
+            throw new Error(`Not a friend: ${pubkey}`);
+        }
+        await this.#sendMessengerPacket(pubkey, id, data);
+    }
+    /**
+     * Receive application custom packets (toxcore lossless 160–191 / lossy
+     * 192–254). SDK-internal IDs are never delivered here. See
+     * {@link sendCustomPacket}.
+     */
+    onCustomPacket(cb) {
+        this.#events.on("customPacket", cb);
+    }
     onFriendConnection(cb) {
         this.#events.on("friendConnection", cb);
     }
@@ -1600,6 +1626,21 @@ export class Peer {
                     this.#debugLog(`crypto ${kind === PACKET_ID_ACTION ? "action" : "message"} from ${friendId}: "${text}"`);
                     return;
                 }
+                if (kind >= 160 && kind <= 254) {
+                    // Application custom packet (toxcore lossless 160-191 / lossy
+                    // 192-254). SDK-reserved IDs (160 UDP_ENDPOINT, 254 NAT_PING, …)
+                    // are handled by earlier branches and never reach here; anything
+                    // else belongs to the application layer (e.g. decentlan IP traffic
+                    // on 192, control on 161/162). Receiving one proves the friend is
+                    // reachable, so mark online.
+                    this.#setFriendOnline(friendId, remote.address, remote.port);
+                    this.#events.emit("customPacket", {
+                        pubkey: friendId,
+                        id: kind,
+                        data: inner
+                    });
+                    return;
+                }
                 this.#debugVerboseLog(`unknown messenger packet kind ${kind} from ${friendId}`);
                 return;
             }
@@ -2630,7 +2671,12 @@ export class Peer {
         // re-punch survive a UDP outage. Brief UDP gaps just drop a few data
         // packets (the proxied TCP stream retransmits) and the re-punch loop
         // restores the direct path within a few seconds.
-        const isBulkData = kind === PACKET_ID_MESSAGE;
+        // Native chat (64) is always bulk; an app can register one extra custom
+        // id (decentlan's IP channel = 163) via bulkDataPacketId so its
+        // high-volume traffic gets the same single-transport routing instead of
+        // fanning out over UDP + relay + TCP relay (which delivers 3-4 duplicates).
+        const isBulkData = kind === PACKET_ID_MESSAGE ||
+            (this.#opts.bulkDataPacketId !== undefined && kind === this.#opts.bulkDataPacketId);
         await this.#sendToFriend(friendId, encrypted, session, isBulkData);
     }
     /**

package/dist/types/peer.d.ts

@@ -28,6 +28,18 @@ export type PeerOptions = {
      * apps that genuinely want offline message delivery leave it false.
      */
     expressControlPlaneOnly?: boolean;
+    /**
+     * Custom packet id carrying the app's high-volume "bulk data" stream
+     * (e.g. decentlan's IP-forwarding channel). Packets sent on this id get
+     * the same single-transport routing as native chat (PACKET_ID_MESSAGE):
+     * they ride the fresh direct UDP path exclusively, or bridge over the
+     * relay when it's stale — instead of fanning out over UDP + relay + TCP
+     * relay at once (which delivers 3-4 duplicates of every packet and backs
+     * up the relay). Apps that put bulk traffic on a custom id (decentlan
+     * uses 163) MUST set this so the SDK recognises it; otherwise the bulk
+     * optimisation only applies to packet 64 and custom-id data is duplicated.
+     */
+    bulkDataPacketId?: number;
     compatibilityMode?: CompatibilityMode;
     debugLabel?: string;
 };
@@ -55,6 +67,21 @@ export type TextMessage = {
     pubkey: string;
     text: string;
 };
+/**
+ * An application-defined custom packet received from a friend, over the
+ * toxcore custom packet ranges: lossless `160–191` (reliable, ordered) or
+ * lossy `192–254` (best-effort). Apps layered on the peer (e.g. decentlan's
+ * IP traffic on `192`) use these to multiplex their own channels without
+ * colliding with chat (`PACKET_ID_MESSAGE = 64`). Packet IDs reserved by the
+ * SDK itself (e.g. `160` UDP-endpoint, `254` NAT-ping) are handled internally
+ * and never surface here.
+ */
+export type CustomPacketEvent = {
+    pubkey: string;
+    /** toxcore packet ID: 160–191 lossless, 192–254 lossy. */
+    id: number;
+    data: Uint8Array;
+};
 export type LookupResult = {
     pubkey: string;
     status: "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decentnetwork/peer",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "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",