From 877ab49fe4c34b4e5995b08bb8b444fbc05438a0 Mon Sep 17 00:00:00 2001
From: velzie <velzie@velzie.rip>
Date: Fri, 26 Jun 2026 19:16:50 -0400
Subject: [PATCH 1/2] add forceRelay options

---
 src/docs/src/Peer/connect.md         | 1 +
 src/docs/src/Peer/serve.md           | 1 +
 src/puter-js/src/modules/Peer.js     | 2 ++
 src/puter-js/types/modules/peer.d.ts | 1 +
 4 files changed, 5 insertions(+)

diff --git a/src/docs/src/Peer/connect.md b/src/docs/src/Peer/connect.md
index 9c24d8a1d5..1127673852 100644
--- a/src/docs/src/Peer/connect.md
+++ b/src/docs/src/Peer/connect.md
@@ -31,6 +31,7 @@ A string invite code created by `puter.peer.serve()`.
 `options` is an object with the following properties:
 
 - `iceServers` (`RTCIceServer[]`) Custom ICE servers (STUN/TURN) to use instead of the Puter-managed relays.
+- `forceRelay` (`boolean`) Whether to force connections to route through a relay instead of attempting peer-to-peer (default). Metering charges will increase.
 
 ## Return value
 
diff --git a/src/docs/src/Peer/serve.md b/src/docs/src/Peer/serve.md
index 9fdd43a478..e8ba914b57 100644
--- a/src/docs/src/Peer/serve.md
+++ b/src/docs/src/Peer/serve.md
@@ -27,6 +27,7 @@ const server = await puter.peer.serve(options);
 `options` is an object with the following properties:
 
 - `iceServers` (`RTCIceServer[]`) Custom ICE servers (STUN/TURN) to use instead of the Puter-managed relays.
+- `forceRelay` (`boolean`) Whether to force connections to route through a relay instead of attempting peer-to-peer (default). Metering charges will increase.
 
 ## Return value
 
diff --git a/src/puter-js/src/modules/Peer.js b/src/puter-js/src/modules/Peer.js
index 09bc7810c6..2e00fecb42 100644
--- a/src/puter-js/src/modules/Peer.js
+++ b/src/puter-js/src/modules/Peer.js
@@ -189,6 +189,7 @@ class PuterPeerConnection extends EventTarget {
         super();
         this.#peerConfig = peerConfig;
         this.peerconnection = new RTCPeerConnection({
+            iceTransportPolicy: peerConfig.forceRelay ? "relay" : "all",
             iceServers: peerConfig.iceServers,
         });
         this.#datachannel = this.peerconnection.createDataChannel('channel-1', { negotiated: true, id: 2 });
@@ -446,6 +447,7 @@ class Peer {
             authToken: this.authToken,
             iceServers,
             signallerUrl: this.#signallerUrl,
+            forceRelay: options?.forceRelay
         };
     }
     async serve (options) {
diff --git a/src/puter-js/types/modules/peer.d.ts b/src/puter-js/types/modules/peer.d.ts
index 94a36aabcf..2fab4247c0 100644
--- a/src/puter-js/types/modules/peer.d.ts
+++ b/src/puter-js/types/modules/peer.d.ts
@@ -2,6 +2,7 @@
 export interface PuterPeerOptions {
     /** Custom ICE servers (STUN/TURN) to use instead of the Puter-managed relays. */
     iceServers?: RTCIceServer[];
+    forceRelay?: boolean;
 }
 
 /** Metadata about a peer user. */

From 8a39b7e4e25a7087974127f484d84d1c62e084ae Mon Sep 17 00:00:00 2001
From: velzie <velzie@velzie.rip>
Date: Fri, 26 Jun 2026 19:30:45 -0400
Subject: [PATCH 2/2] document peerconnection

---
 src/docs/src/Peer/connect.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/docs/src/Peer/connect.md b/src/docs/src/Peer/connect.md
index 1127673852..d3e3335c89 100644
--- a/src/docs/src/Peer/connect.md
+++ b/src/docs/src/Peer/connect.md
@@ -31,7 +31,7 @@ A string invite code created by `puter.peer.serve()`.
 `options` is an object with the following properties:
 
 - `iceServers` (`RTCIceServer[]`) Custom ICE servers (STUN/TURN) to use instead of the Puter-managed relays.
-- `forceRelay` (`boolean`) Whether to force connections to route through a relay instead of attempting peer-to-peer (default). Metering charges will increase.
+- `forceRelay` (`boolean`) Whether to force connections to route through a relay instead of attempting peer-to-peer (default). Metering charges may apply.
 
 ## Return value
 
@@ -42,6 +42,7 @@ A `Promise` that resolves to a `PuterPeerConnection` instance.
 - `send(data)` - Send a message to the peer. Supports strings, `Blob`, `ArrayBuffer`, or `ArrayBufferView`.
 - `close(reason)` - Close the connection.
 - `owner` (`object`) - Information about the user who created the server.
+- `peerconnection` (`RTCPeerConnection`) - the raw underlying RTC handle for this connection.
 - `open` event: Fired when the data channel is ready.
 - `message` event: Fired when a message is received (`event.data`).
 - `close` event: Fired when the connection closes (`event.reason`).