@decentnetwork/peer 0.1.31 → 0.1.33

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

@@ -851,7 +851,11 @@ export class Peer {
             return;
         }
         // Offline / fallback path via Carrier express HTTP store-and-forward.
-        if (this.#express?.hasNodes()) {
+        // Skipped entirely in control-plane-only mode (decentlan's data plane):
+        // a VPN-style daemon must fail fast when a friend is offline rather than
+        // silently queue IP packets into HTTPS storage that never get forwarded
+        // in real time. Express there is reserved for friend-request bootstrap.
+        if (this.#express?.hasNodes() && !this.#opts.expressControlPlaneOnly) {
             await this.#express.sendOfflineText(pubkey, packet);
             this.#debugLog(`sendText: queued via express for ${pubkey}`);
             return;
@@ -887,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);
     }
@@ -1596,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;
             }

package/dist/types/peer.d.ts

@@ -17,6 +17,17 @@ export type PeerOptions = {
     friendStoreFile?: string;
     bootstrapNodes: NetworkNode[];
     expressNodes?: NetworkNode[];
+    /**
+     * When true, the express relay is used ONLY for friend-request
+     * bootstrap (a one-time control-plane handshake) and NEVER as a
+     * fallback for runtime `sendText` data. This lets a VPN-style data
+     * plane stay fail-fast (an offline friend surfaces as offline, IP
+     * packets don't silently pile into HTTPS store-and-forward) while
+     * still letting the initial friend-request reach a peer whose onion
+     * announce hasn't propagated. decentlan's daemon sets this; chat-style
+     * apps that genuinely want offline message delivery leave it false.
+     */
+    expressControlPlaneOnly?: boolean;
     compatibilityMode?: CompatibilityMode;
     debugLabel?: string;
 };
@@ -44,6 +55,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.31",
+  "version": "0.1.33",
   "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",