@vrtmrz/livesync-commonlib 0.1.0-rc.0

package/dist/rpc/transports/DiagRTCPeerConnections.types.js

@@ -0,0 +1,12 @@
+const DiagRTCFailureReasonCodes = {
+  ICE_GATHERING_NOT_COMPLETED: "ICE_GATHERING_NOT_COMPLETED",
+  ICE_CONNECTIVITY_FAILED: "ICE_CONNECTIVITY_FAILED",
+  STUN_REQUEST_TIMEOUT: "STUN_REQUEST_TIMEOUT",
+  SIGNALING_NOT_STABLE: "SIGNALING_NOT_STABLE",
+  CONNECTION_DROPPED_AFTER_ESTABLISHED: "CONNECTION_DROPPED_AFTER_ESTABLISHED",
+  NETWORK_INTERRUPTED: "NETWORK_INTERRUPTED",
+  UNKNOWN: "UNKNOWN"
+};
+export {
+  DiagRTCFailureReasonCodes
+};

package/dist/rpc/transports/DiagRTCPeerConnections.utils.d.ts

@@ -0,0 +1,33 @@
+import { type DiagRTCPeerConnectionInternalStateHistory, type DiagRTCFailureDiagnosis, type DiagRTCPeerConnectionMetrics, type DiagRTCFailureStats } from "./DiagRTCPeerConnections.types.js";
+/**
+ * Diagnoses the failure reason of a failed RTCPeerConnection based on its internal state history and selected candidate pair information.
+ * @param internalStateHistory The internal state history of the RTCPeerConnection.
+ * @param selectedPair The selected candidate pair information.
+ * @returns The diagnosis of the RTC failure.
+ */
+export declare function diagnoseRtcFailure(internalStateHistory: DiagRTCPeerConnectionInternalStateHistory, selectedPair: Record<string, unknown> | undefined): DiagRTCFailureDiagnosis;
+/**
+ * Describes the current progress of the RTCPeerConnection based on its internal state history and selected candidate pair information.
+ *  This is useful for providing user-friendly status messages during the connection process.
+ * @param internalStateHistory The internal state history of the RTCPeerConnection.
+ * @param selectedPair The selected candidate pair information.
+ * @returns A user-friendly description of the current connection progress.
+ */
+export declare function describeRTCProgress(internalStateHistory: DiagRTCPeerConnectionInternalStateHistory, selectedPair: Record<string, unknown> | undefined): string;
+/**
+ * Fetches the RTCPeerConnection statistics and returns a structured metrics object.
+ * This is useful for diagnosing connection issues and understanding the connection performance.
+ * @param instanceId An identifier for the RTCPeerConnection instance, used for logging.
+ * @param peer The RTCPeerConnection instance to fetch stats from.
+ * @returns A structured object containing the connection metrics, or undefined if fetching stats failed.
+ */
+export declare function getPeerConnectionStats(instanceId: string, peer: RTCPeerConnection): Promise<DiagRTCPeerConnectionMetrics | undefined>;
+/**
+ * Audits the RTCPeerConnection for failures and returns a structured failure report.
+ * This is useful for diagnosing connection issues and understanding the reasons for failure.
+ * @param instanceId An identifier for the RTCPeerConnection instance, used for logging.
+ * @param internalStateHistory The internal state history of the RTCPeerConnection.
+ * @param peer The RTCPeerConnection instance to audit.
+ * @returns A structured object containing the failure diagnosis and metrics, or undefined if auditing failed.
+ */
+export declare function auditRtcConnectionFailures(instanceId: string, internalStateHistory: DiagRTCPeerConnectionInternalStateHistory, peer: RTCPeerConnection): Promise<DiagRTCFailureStats | undefined>;

package/dist/rpc/transports/DiagRTCPeerConnections.utils.js

@@ -0,0 +1,217 @@
+import { Logger, LOG_LEVEL_DEBUG, LOG_LEVEL_INFO } from "../../common/logger.js";
+import {
+  DiagRTCFailureReasonCodes
+} from "./DiagRTCPeerConnections.types.js";
+function asFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function formatHistory(history) {
+  return history.length > 0 ? history.join(">") : "none";
+}
+function getLastOrFallback(items, fallback) {
+  if (items.length === 0) return fallback;
+  return items[items.length - 1] ?? fallback;
+}
+function tryGetValue(record, key) {
+  const value = record[key];
+  if (typeof value === "string" || typeof value === "number") {
+    return value;
+  }
+  return "unknown";
+}
+function maskIdentifier(value) {
+  if (value === "unknown") return value;
+  if (value.length <= 8) return "[id]";
+  return `${value.slice(0, 4)}...${value.slice(-4)}`;
+}
+function diagnoseRtcFailure(internalStateHistory, selectedPair) {
+  const hasSelectedPair = !!selectedPair;
+  const selectedPairState = selectedPair?.state ?? "unknown";
+  const requestsSent = asFiniteNumber(selectedPair?.requestsSent);
+  const responsesReceived = asFiniteNumber(selectedPair?.responsesReceived);
+  const hasIceGatheringStarted = internalStateHistory.iceGatheringHistory.includes("gathering");
+  const hasIceGatheringComplete = internalStateHistory.iceGatheringHistory.includes("complete");
+  const hasIceChecking = internalStateHistory.iceConnectionHistory.includes("checking");
+  const hasIceConnected = internalStateHistory.iceConnectionHistory.includes("connected");
+  const hasIceFailed = internalStateHistory.iceConnectionHistory.includes("failed");
+  const hasIceDisconnected = internalStateHistory.iceConnectionHistory.includes("disconnected");
+  const hasConnectionConnected = internalStateHistory.connectionHistory.includes("connected");
+  const hasConnectionFailed = internalStateHistory.connectionHistory.includes("failed");
+  const hasSignalingStable = internalStateHistory.signalingHistory.includes("stable");
+  if (!hasSelectedPair && hasIceGatheringStarted && !hasIceGatheringComplete) {
+    return {
+      reasonCode: DiagRTCFailureReasonCodes.ICE_GATHERING_NOT_COMPLETED,
+      userMessage: "Connection could not collect enough network candidates. Check VPN, proxy, or firewall settings."
+    };
+  }
+  if (hasIceChecking && hasIceFailed && !hasIceConnected) {
+    return {
+      reasonCode: DiagRTCFailureReasonCodes.ICE_CONNECTIVITY_FAILED,
+      userMessage: "Connection attempt reached candidate checks but no route was established."
+    };
+  }
+  if (hasSelectedPair && selectedPairState !== "succeeded" && (requestsSent ?? 0) > 0 && (responsesReceived ?? 0) === 0) {
+    return {
+      reasonCode: DiagRTCFailureReasonCodes.STUN_REQUEST_TIMEOUT,
+      userMessage: "Connection requests were sent but no response was returned. Network path may block UDP/STUN."
+    };
+  }
+  if (!hasSignalingStable) {
+    return {
+      reasonCode: DiagRTCFailureReasonCodes.SIGNALING_NOT_STABLE,
+      userMessage: "Connection negotiation did not reach a stable signalling state."
+    };
+  }
+  if (hasConnectionConnected && hasConnectionFailed) {
+    return {
+      reasonCode: DiagRTCFailureReasonCodes.CONNECTION_DROPPED_AFTER_ESTABLISHED,
+      userMessage: "Connection was established once, but dropped afterwards."
+    };
+  }
+  if (hasIceDisconnected && hasIceFailed) {
+    return {
+      reasonCode: DiagRTCFailureReasonCodes.NETWORK_INTERRUPTED,
+      userMessage: "Connection was interrupted while exchanging data."
+    };
+  }
+  return {
+    reasonCode: DiagRTCFailureReasonCodes.UNKNOWN,
+    userMessage: "Connection failed for an unknown reason. Please retry and collect diagnostics."
+  };
+}
+function describeRTCProgress(internalStateHistory, selectedPair) {
+  const lastConnectionState = getLastOrFallback(internalStateHistory.connectionHistory, "new");
+  const lastIceConnectionState = getLastOrFallback(internalStateHistory.iceConnectionHistory, "new");
+  const lastIceGatheringState = getLastOrFallback(internalStateHistory.iceGatheringHistory, "new");
+  const lastSignalingState = getLastOrFallback(internalStateHistory.signalingHistory, "stable");
+  const pairState = tryGetValue(selectedPair ?? {}, "state");
+  const requestsSent = tryGetValue(selectedPair ?? {}, "requestsSent");
+  const responsesReceived = tryGetValue(selectedPair ?? {}, "responsesReceived");
+  if (lastConnectionState === "connected" || lastIceConnectionState === "connected") {
+    return `Connected (pair=${pairState})`;
+  }
+  if (lastConnectionState === "failed" || lastIceConnectionState === "failed") {
+    const diagnosis = diagnoseRtcFailure(internalStateHistory, selectedPair);
+    return `Failed (${diagnosis.reasonCode})`;
+  }
+  if (lastIceConnectionState === "checking") {
+    if (requestsSent !== "unknown" && responsesReceived !== "unknown") {
+      return `Checking connectivity (responses ${responsesReceived}/${requestsSent})`;
+    }
+    return "Checking connectivity";
+  }
+  if (lastIceGatheringState === "gathering") {
+    return "Gathering network candidates";
+  }
+  if (lastSignalingState !== "stable") {
+    return `Negotiating signalling (${lastSignalingState})`;
+  }
+  if (lastConnectionState === "connecting" || lastIceConnectionState === "new") {
+    return "Starting peer connection";
+  }
+  return `Verbose state: State=${lastConnectionState}, ice=${lastIceConnectionState}, pair=${pairState}`;
+}
+async function getPeerConnectionStats(instanceId, peer) {
+  try {
+    const stats = await peer.getStats();
+    const reports = [];
+    stats.forEach((value) => {
+      reports.push(value);
+    });
+    const selectedPair = reports.map((r) => r).find((r) => {
+      return r.type === "candidate-pair" && (r.selected === true || r.nominated === true);
+    });
+    const selectedPairId = tryGetValue(selectedPair ?? {}, "id") ?? "none";
+    const state = tryGetValue(selectedPair ?? {}, "state");
+    const localCandidateId = tryGetValue(selectedPair ?? {}, "localCandidateId");
+    const remoteCandidateId = tryGetValue(selectedPair ?? {}, "remoteCandidateId");
+    const currentRoundTripTime = tryGetValue(selectedPair ?? {}, "currentRoundTripTime");
+    const totalRoundTripTime = tryGetValue(selectedPair ?? {}, "totalRoundTripTime");
+    const requestsSent = tryGetValue(selectedPair ?? {}, "requestsSent");
+    const responsesReceived = tryGetValue(selectedPair ?? {}, "responsesReceived");
+    const packetsDiscardedOnSend = tryGetValue(selectedPair ?? {}, "packetsDiscardedOnSend");
+    const bytesSent = tryGetValue(selectedPair ?? {}, "bytesSent");
+    const bytesReceived = tryGetValue(selectedPair ?? {}, "bytesReceived");
+    return {
+      selectedPair,
+      selectedPairId,
+      state,
+      localCandidateId,
+      remoteCandidateId,
+      currentRoundTripTime,
+      totalRoundTripTime,
+      requestsSent,
+      responsesReceived,
+      packetsDiscardedOnSend,
+      bytesSent,
+      bytesReceived,
+      // raw
+      reports
+    };
+  } catch (ex) {
+    Logger(
+      `[DiagRTC:${instanceId}] progress/getStats threw: ${ex instanceof Error ? ex.message : String(ex)}`,
+      LOG_LEVEL_DEBUG
+    );
+    return void 0;
+  }
+}
+async function auditRtcConnectionFailures(instanceId, internalStateHistory, peer) {
+  try {
+    const stats = await getPeerConnectionStats(instanceId, peer);
+    if (!stats) {
+      Logger(
+        `[DiagRTC:${instanceId}] failed/getStats: Unable to retrieve connection statistics.`,
+        LOG_LEVEL_INFO
+      );
+      return void 0;
+    }
+    const reports = stats.reports;
+    const diagnosis = diagnoseRtcFailure(internalStateHistory, stats.selectedPair);
+    const connectionHistory = formatHistory(internalStateHistory.connectionHistory);
+    const iceConnectionHistory = formatHistory(internalStateHistory.iceConnectionHistory);
+    const iceGatheringHistory = formatHistory(internalStateHistory.iceGatheringHistory);
+    const signalingHistory = formatHistory(internalStateHistory.signalingHistory);
+    const maskedSelectedPairId = maskIdentifier(String(stats.selectedPairId));
+    const maskedLocalCandidateId = maskIdentifier(String(stats.localCandidateId));
+    const maskedRemoteCandidateId = maskIdentifier(String(stats.remoteCandidateId));
+    Logger(
+      `[DiagRTC:${instanceId}] failed/summary: reasonCode=${diagnosis.reasonCode}, userMessage="${diagnosis.userMessage}", history.connection=${connectionHistory}, history.iceConnection=${iceConnectionHistory}, history.iceGathering=${iceGatheringHistory}, history.signaling=${signalingHistory}`,
+      LOG_LEVEL_INFO
+    );
+    Logger(
+      `[DiagRTC:${instanceId}] failed/getStats/detail: reports=${reports.length}, reasonCode=${diagnosis.reasonCode}, userMessage="${diagnosis.userMessage}", history.connection=${connectionHistory}, history.iceConnection=${iceConnectionHistory}, history.iceGathering=${iceGatheringHistory}, history.signaling=${signalingHistory}, selectedPair=${maskedSelectedPairId}, pairState=${stats.state}, localCandidate=${maskedLocalCandidateId}, remoteCandidate=${maskedRemoteCandidateId}, rtt=${stats.currentRoundTripTime}, totalRtt=${stats.totalRoundTripTime}, requestsSent=${stats.requestsSent}, responsesReceived=${stats.responsesReceived}, packetsDiscardedOnSend=${stats.packetsDiscardedOnSend}, bytesSent=${stats.bytesSent}, bytesReceived=${stats.bytesReceived}`,
+      LOG_LEVEL_DEBUG
+    );
+    return {
+      diagnosis,
+      stats: {
+        reportsCount: reports.length,
+        selectedPair: {
+          id: maskedSelectedPairId,
+          state: stats.state,
+          localCandidateId: maskedLocalCandidateId,
+          remoteCandidateId: maskedRemoteCandidateId,
+          currentRoundTripTime: stats.currentRoundTripTime,
+          totalRoundTripTime: stats.totalRoundTripTime,
+          requestsSent: stats.requestsSent,
+          responsesReceived: stats.responsesReceived,
+          packetsDiscardedOnSend: stats.packetsDiscardedOnSend,
+          bytesSent: stats.bytesSent,
+          bytesReceived: stats.bytesReceived
+        }
+      }
+    };
+  } catch (ex) {
+    Logger(
+      `[DiagRTC:${instanceId}] failed/getStats threw: ${ex instanceof Error ? ex.message : String(ex)}`,
+      LOG_LEVEL_DEBUG
+    );
+  }
+}
+export {
+  auditRtcConnectionFailures,
+  describeRTCProgress,
+  diagnoseRtcFailure,
+  getPeerConnectionStats
+};

package/dist/rpc/transports/TrysteroTransport.d.ts

@@ -0,0 +1,216 @@
+import { type Room } from "@trystero-p2p/nostr";
+import { RpcRoom } from "../RpcRoom.js";
+import { RpcPouchDBProxy } from "../pouchdb/RpcPouchDBProxy.js";
+import type { RpcRoomOptions, TransportAdapter } from "../types.js";
+import type { P2PConnectionInfo } from "../../common/models/setting.type.js";
+/**
+ * Lightweight presence record broadcast by each peer when it joins the room.
+ * The `peerId` field MUST match the Trystero sender ID to prevent spoofing.
+ */
+export type TrysteroAdvertisement = {
+    /** The Trystero `selfId` of the sending peer. */
+    peerId: string;
+    /** Human-readable device / vault name. */
+    name: string;
+    /** Optional platform tag (e.g. `"desktop"`, `"mobile"`). */
+    platform: string;
+};
+/** The handle returned by {@link attachAdvertisement}. */
+export type AdvertisementHandle = {
+    /**
+     * All currently known peers, keyed by `peerId`.
+     * Updated in real-time as advertisements arrive or peers leave.
+     */
+    readonly peers: ReadonlyMap<string, TrysteroAdvertisement>;
+    /**
+     * (Re-)broadcast your own advertisement.
+     * Pass a `toPeerId` to send only to that peer; omit to broadcast to all.
+     */
+    sendAdvertisement(toPeerId?: string): Promise<void>;
+    /** Stop listening for advertisements and clear the peer map. */
+    stop(): void;
+};
+/**
+ * Attach advertisement-based peer discovery to an already-joined Trystero room.
+ *
+ * - Sends your advertisement to every peer that joins after this call.
+ * - Stores incoming advertisements in `handle.peers`.
+ * - Removes entries when peers leave.
+ *
+ * @param room         An active Trystero room.
+ * @param localPeerId  Your own Trystero `selfId`.
+ * @param name         Human-readable name broadcast to other peers.
+ * @param platform     Optional platform string (default `"unknown"`).
+ */
+export declare function attachAdvertisement(room: Room, localPeerId: string, name: string, platform?: string): AdvertisementHandle;
+/**
+ * Options forwarded to the `RpcRoom` constructor when creating a room through
+ * the high-level helpers (`serveTrysteroDB`, `connectTrysteroDBClient`, or by
+ * calling `joinTrysteroRoom` and then constructing `RpcRoom` manually).
+ *
+ * Trystero internally chunks at ~16 348 bytes (16 KiB minus a 36-byte header).
+ * Setting `maxWirePayloadBytes` above that threshold causes double-chunking.
+ * The Trystero-appropriate default is therefore **15 360 bytes** (15 KiB),
+ * which leaves ~1 KiB of headroom for the JSON wrapper overhead.
+ *
+ * Trystero uses WebRTC SCTP data channels which guarantee delivery and order,
+ * so missing-chunk retransmission virtually never triggers.  `chunkMissingRetryMs`
+ * can safely be lowered from the generic default of 350 ms to **150 ms**.
+ */
+export type TrysteroRoomOptions = Pick<RpcRoomOptions, "canAcceptRequest" | "onProtocolWarning"> & {
+    maxWirePayloadBytes?: number;
+    chunkMissingRetryMs?: number;
+};
+/** Trystero-appropriate defaults for `RpcRoom`. */
+export declare const TRYSTERO_RPC_DEFAULTS: {
+    /** Stay below Trystero's internal ~16 348-byte chunk boundary. */
+    readonly maxWirePayloadBytes: number;
+    /** SCTP guarantees delivery; retransmission is a last-resort safety net. */
+    readonly chunkMissingRetryMs: 150;
+};
+/**
+ * Wrap an already-joined Trystero `Room` as a `TransportAdapter` for `RpcRoom`.
+ *
+ * A dedicated Trystero action channel named `"rpc2"` is created on the room.
+ * Note: Trystero does not expose per-handler unsubscription for `onPeerJoin`
+ * / `onPeerLeave`, so the returned cleanup stubs are no-ops.  Close the
+ * Trystero room via `leave()` when done.
+ *
+ * @param room  An active Trystero `Room` returned by `joinRoom()`.
+ * @returns     A `TransportAdapter` that can be passed to `new RpcRoom(...)`.
+ */
+export declare function wrapTrysteroRoom(room: Room): TransportAdapter;
+/** The result of joining a Trystero room. */
+export type TrysteroRoomHandle = {
+    /** `TransportAdapter` ready to pass to `new RpcRoom(...)`. */
+    transport: TransportAdapter;
+    /** This peer's own ID (Trystero `selfId`). */
+    peerId: string;
+    /** Leave the Trystero room and release resources. */
+    leave: () => Promise<void>;
+    /**
+     * Attach advertisement-based peer discovery to this room.
+     * Call once after joining; returns a handle to read and re-broadcast.
+     */
+    advertise: (name: string, platform?: string) => AdvertisementHandle;
+    /**
+     * Returns the current WebRTC peer connections keyed by peer ID.
+     * Equivalent to the Trystero `room.getPeers()` call.
+     */
+    getPeers: () => Record<string, RTCPeerConnection>;
+    /**
+     * The underlying Trystero `Room` instance.
+     * Use when you need raw access to Trystero APIs such as `makeAction`,
+     * `onPeerJoin`, or `onPeerLeave` beyond what the helpers expose.
+     */
+    room: Room;
+};
+/**
+ * Join a Trystero room from a {@link P2PConnectionInfo} and return a
+ * `TransportAdapter` together with this peer's own ID.
+ *
+ * The raw passphrase is hashed with `mixedHash` before being passed to
+ * Trystero, matching the convention used by `TrysteroReplicatorP2PServer`.
+ */
+export declare function joinTrysteroRoom(settings: P2PConnectionInfo): TrysteroRoomHandle;
+/**
+ * Join a Trystero room from a `sls+p2p://` connection string and return a
+ * `TransportAdapter` together with this peer's own ID.
+ *
+ * The URL must be parseable by {@link ConnectionStringParser.parse} as type
+ * `"p2p"`, i.e. it must start with `sls+p2p://`.
+ *
+ * @example
+ * ```ts
+ * const handle = joinTrysteroRoomFromUrl(
+ *     "sls+p2p://my-room?relays=wss://relay.example.com&appId=my-app"
+ * );
+ * const rpcRoom = new RpcRoom({ transport: handle.transport });
+ * ```
+ */
+export declare function joinTrysteroRoomFromUrl(url: string): TrysteroRoomHandle;
+/** The result of starting a DB server over Trystero. */
+export type TrysteroDBServerHandle = {
+    /** This peer's own ID.  Share it with clients so they can call `session()`. */
+    peerId: string;
+    /** The `RpcRoom` that hosts the DB methods. */
+    rpcRoom: RpcRoom;
+    /** Stop serving and leave the room. */
+    close: () => Promise<void>;
+    /**
+     * Attach advertisement-based peer discovery so that clients can find this
+     * server without needing the peerId passed out-of-band.
+     */
+    advertise: (name: string, platform?: string) => AdvertisementHandle;
+};
+/**
+ * **Server side.**  Join a Trystero room and expose `db` as a set of RPC
+ * methods.  The caller's `peerId` is returned so that it can be shared with
+ * clients (e.g. via a separate signalling channel or advertisement).
+ *
+ * @param settings  P2P connection settings (from `P2PConnectionInfo` or parsed
+ *                  from a `sls+p2p://` URL via {@link ConnectionStringParser}).
+ * @param db        The PouchDB database to expose.
+ * @param ns        Method namespace (default `"pdb"`).
+ *
+ * @example
+ * ```ts
+ * const server = serveTrysteroDB(settings, db);
+ * console.log("server peer ID:", server.peerId);
+ * // Share server.peerId with the client out-of-band.
+ * ```
+ */
+export declare function serveTrysteroDB(settings: P2PConnectionInfo, db: PouchDB.Database<object>, ns?: string, options?: TrysteroRoomOptions): TrysteroDBServerHandle;
+/** The result of connecting to a DB server over Trystero. */
+export type TrysteroDBClientHandle = {
+    /** Proxy object usable with `PouchDB.replicate()` or `replicateShim()`. */
+    proxy: RpcPouchDBProxy;
+    /** The `RpcRoom` used to communicate with the server. */
+    rpcRoom: RpcRoom;
+    /** Disconnect and leave the room. */
+    close: () => Promise<void>;
+    /**
+     * Attach advertisement-based peer discovery so this client can locate the
+     * server peer without needing its peerId passed statically.
+     */
+    advertise: (name: string, platform?: string) => AdvertisementHandle;
+};
+/**
+ * **Client side.**  Join a Trystero room and create an {@link RpcPouchDBProxy}
+ * pointing at `serverPeerId`.  The proxy can be passed directly to
+ * `PouchDB.replicate()` or `replicateShim()`.
+ *
+ * @param settings      P2P connection settings.
+ * @param serverPeerId  The `peerId` of the server peer (returned by
+ *                      {@link serveTrysteroDB}).
+ * @param dbName        Logical name for the remote database.
+ * @param ns            Method namespace, must match the server's `ns`
+ *                      (default `"pdb"`).
+ *
+ * @example
+ * ```ts
+ * const client = connectTrysteroDBClient(settings, serverPeerId, "my-db");
+ * await PouchDB.replicate(client.proxy, localDb, { live: false });
+ * await client.close();
+ * ```
+ */
+export declare function connectTrysteroDBClient(settings: P2PConnectionInfo, serverPeerId: string, dbName: string, ns?: string, options?: TrysteroRoomOptions): TrysteroDBClientHandle;
+/**
+ * Join a Trystero room, advertise as `name`, wait `timeoutMs`, collect all
+ * received peer advertisements, then leave the room and return the results.
+ *
+ * Useful for CLI-style peer discovery where you need a one-shot list of
+ * present peers before deciding how to connect.
+ *
+ * @param settings   P2P connection settings.
+ * @param name       Your local device / vault name advertised to others.
+ * @param timeoutMs  How long to listen before returning (milliseconds).
+ * @param platform   Optional platform tag (default `"unknown"`).
+ *
+ * @example
+ * ```ts
+ * const peers = await collectTrysteroAdvertisements(settings, "my-vault", 5000);
+ * console.log(peers.map(p => `${p.name} (${p.peerId})`));
+ * ```
+ */
+export declare function collectTrysteroAdvertisements(settings: P2PConnectionInfo, name: string, timeoutMs: number, platform?: string): Promise<TrysteroAdvertisement[]>;

package/dist/rpc/transports/TrysteroTransport.js

@@ -0,0 +1,134 @@
+import { joinRoom, selfId } from "@trystero-p2p/nostr";
+import { RpcRoom } from "../RpcRoom.js";
+import { exposeDB } from "../pouchdb/RpcPouchDBServer.js";
+import { RpcPouchDBProxy } from "../pouchdb/RpcPouchDBProxy.js";
+import { ConnectionStringParser } from "../../common/ConnectionString.js";
+import { compatGlobal } from "../../common/coreEnvFunctions.js";
+import { generateJoinRoomOptions } from "./trysteroUtils.js";
+const RPC_ACTION_NAME = "rpc2";
+const AD_ACTION_NAME = "ad";
+function attachAdvertisement(room, localPeerId, name, platform = "unknown") {
+  const peerMap = /* @__PURE__ */ new Map();
+  const localAd = { peerId: localPeerId, name, platform };
+  const [sendAd, arrivedAd] = room.makeAction(AD_ACTION_NAME);
+  const sendAdvertisement = (toPeerId) => sendAd(localAd, toPeerId).then(() => void 0);
+  room.onPeerJoin((peerId) => {
+    void sendAdvertisement(peerId);
+  });
+  room.onPeerLeave((peerId) => {
+    peerMap.delete(peerId);
+  });
+  arrivedAd((data, peerId) => {
+    if (data.peerId === localPeerId) return;
+    if (data.peerId !== peerId) return;
+    peerMap.set(peerId, data);
+  });
+  return {
+    get peers() {
+      return peerMap;
+    },
+    sendAdvertisement,
+    stop() {
+      peerMap.clear();
+    }
+  };
+}
+const TRYSTERO_RPC_DEFAULTS = {
+  /** Stay below Trystero's internal ~16 348-byte chunk boundary. */
+  maxWirePayloadBytes: 15 * 1024,
+  /** SCTP guarantees delivery; retransmission is a last-resort safety net. */
+  chunkMissingRetryMs: 150
+};
+function wrapTrysteroRoom(room) {
+  const [sendRpc, arrivedRpc] = room.makeAction(RPC_ACTION_NAME);
+  return {
+    send(message, peerId) {
+      return sendRpc(message, peerId).then(() => void 0);
+    },
+    onMessage(handler) {
+      arrivedRpc((data, peerId) => handler(data, peerId));
+      return () => void 0;
+    },
+    onPeerJoin(handler) {
+      room.onPeerJoin((peerId) => handler(peerId));
+      return () => void 0;
+    },
+    onPeerLeave(handler) {
+      room.onPeerLeave((peerId) => handler(peerId));
+      return () => void 0;
+    }
+  };
+}
+function joinTrysteroRoom(settings) {
+  const options = generateJoinRoomOptions(settings);
+  const room = joinRoom(options, settings.P2P_roomID, {
+    handshakeTimeoutMs: 3e4,
+    onJoinError(error) {
+      console.error("Failed to join Trystero room:", error);
+    }
+  });
+  const currentPeerId = selfId;
+  return {
+    transport: wrapTrysteroRoom(room),
+    peerId: currentPeerId,
+    leave: () => room.leave(),
+    advertise: (name, platform = "unknown") => attachAdvertisement(room, currentPeerId, name, platform),
+    getPeers: () => room.getPeers(),
+    room
+  };
+}
+function joinTrysteroRoomFromUrl(url) {
+  const result = ConnectionStringParser.parse(url);
+  if (result.type !== "p2p") {
+    throw new Error(`Expected a sls+p2p:// connection string, but got type: "${result.type}"`);
+  }
+  return joinTrysteroRoom(result.settings);
+}
+function serveTrysteroDB(settings, db, ns = "pdb", options) {
+  const roomHandle = joinTrysteroRoom(settings);
+  const rpcRoom = new RpcRoom({ ...TRYSTERO_RPC_DEFAULTS, transport: roomHandle.transport, ...options });
+  exposeDB(rpcRoom, db, ns);
+  return {
+    peerId: roomHandle.peerId,
+    rpcRoom,
+    close: async () => {
+      rpcRoom.close();
+      await roomHandle.leave();
+    },
+    advertise: roomHandle.advertise
+  };
+}
+function connectTrysteroDBClient(settings, serverPeerId, dbName, ns = "pdb", options) {
+  const roomHandle = joinTrysteroRoom(settings);
+  const rpcRoom = new RpcRoom({ ...TRYSTERO_RPC_DEFAULTS, transport: roomHandle.transport, ...options });
+  const proxy = new RpcPouchDBProxy(rpcRoom.session(serverPeerId), dbName, ns);
+  return {
+    proxy,
+    rpcRoom,
+    close: async () => {
+      rpcRoom.close();
+      await roomHandle.leave();
+    },
+    advertise: roomHandle.advertise
+  };
+}
+async function collectTrysteroAdvertisements(settings, name, timeoutMs, platform = "unknown") {
+  const roomHandle = joinTrysteroRoom(settings);
+  const adHandle = roomHandle.advertise(name, platform);
+  await adHandle.sendAdvertisement();
+  await new Promise((resolve) => compatGlobal.setTimeout(resolve, timeoutMs));
+  const peers = [...adHandle.peers.values()];
+  adHandle.stop();
+  await roomHandle.leave();
+  return peers;
+}
+export {
+  TRYSTERO_RPC_DEFAULTS,
+  attachAdvertisement,
+  collectTrysteroAdvertisements,
+  connectTrysteroDBClient,
+  joinTrysteroRoom,
+  joinTrysteroRoomFromUrl,
+  serveTrysteroDB,
+  wrapTrysteroRoom
+};

package/dist/rpc/transports/trysteroUtils.d.ts

@@ -0,0 +1,3 @@
+import type { BaseRoomConfig } from "@trystero-p2p/nostr";
+import type { P2PConnectionInfo } from "../../common/models/setting.type.js";
+export declare function generateJoinRoomOptions(settings: P2PConnectionInfo): BaseRoomConfig;

package/dist/rpc/transports/trysteroUtils.js

@@ -0,0 +1,37 @@
+import { mixedHash } from "octagonal-wheels/hash/purejs";
+import { compatGlobal } from "../../common/coreEnvFunctions.js";
+import { createDiagRTCPeerConnectionConstructor } from "./DiagRTCPeerConnections.js";
+function generateJoinRoomOptions(settings) {
+  const passphraseNumbers = mixedHash(settings.P2P_passphrase, 0);
+  const passphrase = passphraseNumbers[0].toString(36) + passphraseNumbers[1].toString(36);
+  const relays = settings.P2P_relays.split(",").map((e) => e.trim()).filter((e) => e.length > 0);
+  const turnServers = settings.P2P_turnServers.split(",").map((e) => e.trim()).filter((e) => e.length > 0);
+  const relayConfig = {
+    manualReconnection: true,
+    urls: relays
+    // ...(typeof rtcPolyfill === "function" ? { rtcPolyfill } : {}),
+  };
+  const options = {
+    appId: settings.P2P_AppID || "self-hosted-livesync",
+    password: passphrase,
+    relayConfig
+  };
+  if (settings.P2P_useDiagRTC) {
+    options.rtcPolyfill = createDiagRTCPeerConnectionConstructor();
+  } else if (typeof compatGlobal.RTCPeerConnection !== "undefined") {
+    options.rtcPolyfill = compatGlobal.RTCPeerConnection;
+  }
+  if (turnServers.length > 0) {
+    options.turnConfig = [
+      {
+        urls: turnServers,
+        username: settings.P2P_turnUsername,
+        credential: settings.P2P_turnCredential
+      }
+    ];
+  }
+  return options;
+}
+export {
+  generateJoinRoomOptions
+};