@decentnetwork/peer 0.1.0 → 0.1.1

package/dist/peer.d.ts

@@ -41,5 +41,36 @@ export declare class Peer {
     onFriendConnection(cb: (ev: FriendConnectionEvent) => void): void;
     onFriendInfo(cb: (ev: FriendInfoEvent) => void): void;
     friends(): FriendRecord[];
+    /**
+     * Read-only snapshot of the live net_crypto session state for a
+     * friend, or null if no session has been established yet. Lets
+     * callers see whether a peer is reachable via direct UDP, only via
+     * TCP relay, or not at all — the answer is the difference between
+     * ~80ms RTT (UDP) and ~500ms+ RTT (relay) in practice, so the
+     * caller (e.g. `agentnet diag`) can show an operator where their
+     * latency is coming from. Returns:
+     *
+     *   established  — handshake complete on this side
+     *   udpRemote    — direct UDP endpoint we've seen the peer at,
+     *                  if any; null means UDP holepunch hasn't
+     *                  succeeded (yet) so traffic falls back to TCP
+     *                  relay
+     *   hasTcpRoute  — true when a TCP relay has reported a route to
+     *                  the peer
+     *   transport    — convenience derived field: which path the next
+     *                  outbound packet will actually use
+     *   lastPingRecvMs — for staleness; if older than ~32s the session
+     *                    is on its way to timeout
+     */
+    sessionStatus(pubkey: string): {
+        established: boolean;
+        udpRemote: {
+            host: string;
+            port: number;
+        } | null;
+        hasTcpRoute: boolean;
+        transport: "udp" | "tcp-relay" | "both" | "none";
+        lastPingRecvMs: number | null;
+    } | null;
     waitForFriendRequest(timeoutMs?: number): Promise<FriendRequest>;
 }

package/dist/peer.js

@@ -747,6 +747,52 @@ export class Peer {
     friends() {
         return [...this.#friends.values()];
     }
+    /**
+     * Read-only snapshot of the live net_crypto session state for a
+     * friend, or null if no session has been established yet. Lets
+     * callers see whether a peer is reachable via direct UDP, only via
+     * TCP relay, or not at all — the answer is the difference between
+     * ~80ms RTT (UDP) and ~500ms+ RTT (relay) in practice, so the
+     * caller (e.g. `agentnet diag`) can show an operator where their
+     * latency is coming from. Returns:
+     *
+     *   established  — handshake complete on this side
+     *   udpRemote    — direct UDP endpoint we've seen the peer at,
+     *                  if any; null means UDP holepunch hasn't
+     *                  succeeded (yet) so traffic falls back to TCP
+     *                  relay
+     *   hasTcpRoute  — true when a TCP relay has reported a route to
+     *                  the peer
+     *   transport    — convenience derived field: which path the next
+     *                  outbound packet will actually use
+     *   lastPingRecvMs — for staleness; if older than ~32s the session
+     *                    is on its way to timeout
+     */
+    sessionStatus(pubkey) {
+        const s = this.#friendSessions.get(pubkey);
+        if (!s)
+            return null;
+        // session.remote can be a synthetic `tcp:<dhtpk>:0` placeholder
+        // when the TCP relay path reports an endpoint with no real UDP
+        // address; treat those as no-UDP for reporting.
+        const realUdp = s.remote && !s.remote.host?.startsWith("tcp:") && s.remote.port !== 0
+            ? { host: s.remote.host, port: s.remote.port }
+            : null;
+        const transport = realUdp
+            ? s.hasTcpRoute
+                ? "both"
+                : "udp"
+            : s.hasTcpRoute
+                ? "tcp-relay"
+                : "none";
+        return {
+            established: s.established === true,
+            udpRemote: realUdp,
+            hasTcpRoute: s.hasTcpRoute === true,
+            transport,
+            lastPingRecvMs: s.lastPingRecvMs ?? null,
+        };
+    }
     waitForFriendRequest(timeoutMs = 30000) {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {

package/package.json

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