phystack-hub-client 0.2.7__tar.gz → 6.6.0__tar.gz

{phystack_hub_client-0.2.7 → phystack_hub_client-6.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phystack-hub-client
-Version: 0.2.7
+Version: 6.6.0
 Summary: Python client for PhyHub - events, actions, DataChannel, and MediaStream
 Project-URL: Homepage, https://github.com/phystack/phystack-pypi
 Project-URL: Documentation, https://docs.phystack.com

{phystack_hub_client-0.2.7 → phystack_hub_client-6.6.0}/pyproject.toml

@@ -4,7 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "phystack-hub-client"
-version = "0.2.7"
+# Fixed version group with the Node hub-client (@phystack/hub-client in
+# phystack/ps-platform): both clients implement the same twin/WebRTC contract
+# and are released together under the same version.
+version = "6.6.0"
 description = "Python client for PhyHub - events, actions, DataChannel, and MediaStream"
 readme = "README.md"
 license = "MIT"

{phystack_hub_client-0.2.7 → phystack_hub_client-6.6.0}/src/phystack/hub_client/__init__.py

@@ -69,6 +69,37 @@ from phystack.hub_client.services.webrtc.media_stream import (
     PhygridMediaStream,
     WebcamVideoTrack,
 )
+from phystack.hub_client.services.webrtc.media_source import (
+    FrameSourceTrack,
+    VideoFrameSource,
+)
+from phystack.hub_client.services.webrtc.media_responder import (
+    MediaStreamResponder,
+    MediaStreamResponderOptions,
+    PeerCapReachedError,
+    ResponderPeer,
+)
+from phystack.hub_client.services.webrtc.data_responder import (
+    DataChannelResponder,
+    DataChannelResponderOptions,
+    ResponderChannel,
+)
+from phystack.hub_client.advisory_validation import (
+    CompiledValidator,
+    DescriptorValidator,
+    validate_emitted_facet,
+)
+from phystack.hub_client.services.cloud_app_token import (
+    CloudAppToken,
+    CloudAppTokenExchangeError,
+    exchange_cloud_app_token,
+)
+from phystack.hub_client.services.cloud_app_connection import (
+    CloudAppConnection,
+    CloudAppConnectionParams,
+    CloudAppConnectResult,
+)
+from phystack.hub_client.cloud_twins import CloudTwinStore
 from phystack.hub_client.services.signals import (
     SignalsService,
     InitSignalPayload,
@@ -80,7 +111,9 @@ from phystack.hub_client.services.signals import (
     PurchaseProps,
 )
 
-__version__ = "0.1.0"
+# Kept in a fixed version group with @phystack/hub-client (npm) — same
+# contract, same release version.
+__version__ = "6.5.0"
 __all__ = [
     # Client
     "PhyHubClient",
@@ -104,6 +137,27 @@ __all__ = [
     "MediaStreamOptions",
     "PhygridMediaStream",
     "WebcamVideoTrack",
+    "FrameSourceTrack",
+    "VideoFrameSource",
+    "MediaStreamResponder",
+    "MediaStreamResponderOptions",
+    "PeerCapReachedError",
+    "ResponderPeer",
+    "DataChannelResponder",
+    "DataChannelResponderOptions",
+    "ResponderChannel",
+    # Advisory validation
+    "CompiledValidator",
+    "DescriptorValidator",
+    "validate_emitted_facet",
+    # Cloud-app mode
+    "CloudAppToken",
+    "CloudAppTokenExchangeError",
+    "exchange_cloud_app_token",
+    "CloudAppConnection",
+    "CloudAppConnectionParams",
+    "CloudAppConnectResult",
+    "CloudTwinStore",
     # Signals
     "SignalsService",
     "InitSignalPayload",

phystack_hub_client-6.6.0/src/phystack/hub_client/advisory_validation.py

@@ -0,0 +1,114 @@
+"""Advisory descriptor validation (opt-in, on-device).
+
+Python port of the npm hub-client ``advisory-validation.ts`` module. Validates
+the facets an edge app EMITS (reported properties, event payloads, action
+returns) against precompiled validators the app supplies from its own compiled
+descriptor schema (the build-time-embed approach).
+
+Hard rules this module enforces (npm parity):
+
+- **Opt-in.** No validator supplied -> no validation; behavior is identical to
+  a non-validating client.
+- **Advisory + routing-independent.** On a mismatch a warning is logged and the
+  caller STILL emits/sends/stores. The validation outcome never affects whether
+  or how a message goes on the wire.
+- **Fail-open.** Missing validator for a facet -> skip; any error raised inside
+  the validation path -> caught, logged, and skipped. This module never raises.
+
+Like the npm package (which deliberately does not depend on Ajv), this module
+carries no JSON-schema runtime. The opt-in contract is a set of precompiled
+validate callables: ``Callable[[Any], bool]`` that may expose the last run's
+errors on an ``errors`` attribute (duck-typed, mirroring Ajv's compiled shape).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+# A precompiled validate function: returns True/False for a payload and may
+# expose the last run's errors on an `errors` attribute (duck-typed).
+CompiledValidator = Callable[[Any], bool]
+
+# Facet names mirror the npm module: 'reported' | 'event' | 'actionReturns'.
+FACET_REPORTED = "reported"
+FACET_EVENT = "event"
+FACET_ACTION_RETURNS = "actionReturns"
+
+_default_logger = logging.getLogger("phystack.hub_client.advisory_validation")
+
+
+@dataclass
+class DescriptorValidator:
+    """Per-facet precompiled validators supplied by the edge app.
+
+    Every field is optional: a facet with no validator is simply not checked
+    (fail-open). Event validators are keyed by event type; action-return
+    validators by action name.
+    """
+
+    reported: Optional[CompiledValidator] = None
+    events: dict[str, CompiledValidator] = field(default_factory=dict)
+    action_returns: dict[str, CompiledValidator] = field(default_factory=dict)
+
+
+def _describe(descriptor_label: str, facet: str, facet_key: Optional[str]) -> str:
+    facet_part = f"{facet} '{facet_key}'" if facet_key else facet
+    return f"{facet_part} on '{descriptor_label}'"
+
+
+def validate_emitted_facet(
+    validator: Optional[CompiledValidator],
+    data: Any,
+    descriptor_label: str,
+    facet: str,
+    facet_key: Optional[str] = None,
+    logger: Optional[logging.Logger] = None,
+) -> bool:
+    """Run a single precompiled validator over ``data``, advisory + fail-open.
+
+    NEVER raises and NEVER signals "block this message" — the return value is
+    purely informational (True = conformed/skipped, False = a mismatch was
+    logged) and callers MUST emit regardless of it. A ``validator`` of ``None``
+    means the app didn't supply one for this facet -> skip (fail-open). Any
+    error raised by the validator itself is caught, logged, and treated as a
+    skip (fail-open) so a broken schema can never block telemetry.
+
+    Args:
+        validator: Precompiled validate callable, or None to skip.
+        data: The emitted payload to check.
+        descriptor_label: Identifies the descriptor/peripheral in the warning.
+        facet: Which emitted facet this is ('reported'/'event'/'actionReturns').
+        facet_key: Event type or action name, when applicable.
+        logger: Logger for warnings; defaults to the module logger.
+
+    Returns:
+        True if the data conformed or validation was skipped, False on mismatch.
+    """
+    if validator is None:
+        # Opt-out / no schema for this facet -> skip, behave like a
+        # non-validating client.
+        return True
+
+    active_logger = logger if logger is not None else _default_logger
+
+    try:
+        conforms = bool(validator(data))
+    except Exception as error:  # noqa: BLE001 - fail-open by contract
+        # Fail-open: a broken validator must never block an emit.
+        active_logger.warning(
+            "Failed to run advisory descriptor validation for %s — skipping (fail-open): %r",
+            _describe(descriptor_label, facet, facet_key),
+            error,
+        )
+        return True
+
+    if not conforms:
+        active_logger.warning(
+            "Advisory descriptor validation mismatch for %s — sending anyway (advisory): %r",
+            _describe(descriptor_label, facet, facet_key),
+            getattr(validator, "errors", None),
+        )
+
+    return conforms

{phystack_hub_client-0.2.7 → phystack_hub_client-6.6.0}/src/phystack/hub_client/client.py

@@ -6,6 +6,8 @@ Provides events, actions, DataChannel, and MediaStream functionality.
 """
 
 import asyncio
+import logging
+import time
 from typing import Any, Callable, Optional, Set
 
 from phystack.hub_client.services.phyhub_connection import (
@@ -38,10 +40,27 @@ from phystack.hub_client.services.webrtc.media_stream import (
     PhygridMediaStream,
     TwinMessagingInterface as MediaStreamMessaging,
 )
+from phystack.hub_client.services.webrtc.media_responder import (
+    MediaStreamResponder,
+    MediaStreamResponderOptions,
+    ResponderPeer,
+)
+from phystack.hub_client.services.webrtc.data_responder import (
+    DataChannelResponder,
+    DataChannelResponderOptions,
+    ResponderChannel,
+)
+from phystack.hub_client.services.cloud_app_connection import (
+    CloudAppConnection,
+    CloudAppConnectionParams,
+)
+from phystack.hub_client.cloud_twins import CloudTwin, CloudTwinStore
 from phystack.hub_client.instances.edge_instance import EdgeInstance
 from phystack.hub_client.instances.peripheral_instance import PeripheralInstance
 from phystack.hub_client.twin_registry import TwinRegistry
 
+logger = logging.getLogger("phystack.hub_client.client")
+
 
 class PhyHubClient:
     """Client for connecting to PhyHub.
@@ -72,6 +91,7 @@ class PhyHubClient:
         GET_DEVICE_STATUS = "getDeviceStatus"
         GET_DEVICE_INSTANCE = "getDeviceInstance"
         GET_DEVICE_NETWORKS = "getDeviceNetworks"
+        GET_ICE_SERVERS = "getIceServers"
 
     def __init__(
         self,
@@ -79,6 +99,7 @@ class PhyHubClient:
         access_key: Optional[str] = None,
         phyhub_url: Optional[str] = None,
         instance_id: Optional[str] = None,
+        cloud_app: Optional[CloudAppConnectionParams] = None,
     ) -> None:
         """Initialize PhyHub client.
 
@@ -87,6 +108,9 @@ class PhyHubClient:
             access_key: Access key for authentication.
             phyhub_url: PhyHub server URL.
             instance_id: Optional specific twin ID to use.
+            cloud_app: Cloud-app connection params (npm PhyHubClientParams
+                parity). When set, connect() runs the cloud-app branch (JWT
+                exchange + cloud twin lifecycle) instead of the device path.
         """
         self._connection: Optional[PhyHubConnection] = None
         self._instance_id: Optional[str] = instance_id
@@ -97,6 +121,22 @@ class PhyHubClient:
         self._twin_data_cache: dict[str, dict[str, Any]] = {}
         self._connected = False
         self._registry: Optional[TwinRegistry] = None
+        # (refresh_at_monotonic, servers) per use case ('media' / 'data')
+        self._cached_ice_servers: dict[str, tuple[float, list[dict[str, Any]]]] = {}
+        # Armed publisher fan-outs, keyed "{twin_id}:{stream_name}" (npm parity)
+        self._media_responders: dict[str, MediaStreamResponder] = {}
+        # Armed data-channel fan-outs, keyed "{twin_id}:{channel_name}" (npm parity)
+        self._data_responders: dict[str, DataChannelResponder] = {}
+        # npm parity (emitQueue): emits issued while the socket is down are
+        # queued and flushed on (re)connect instead of failing.
+        self._emit_queue: list[
+            tuple[str, dict[str, Any], bool, Optional["asyncio.Future[Any]"]]
+        ] = []
+        # npm parity: getDeviceStatus responses are cached for 10s.
+        self._device_status_cache: Optional[tuple[float, dict[str, Any]]] = None
+        self._cloud_app_params = cloud_app
+        self._cloud_app_connection: Optional[CloudAppConnection] = None
+        self._cloud_twin_store: Optional[CloudTwinStore] = None
 
         if device_id and access_key:
             self._connection = PhyHubConnection(
@@ -141,6 +181,9 @@ class PhyHubClient:
         Raises:
             ConnectionError: If connection fails.
         """
+        if self._cloud_app_params is not None:
+            return await self._connect_cloud_app()
+
         if not self._connection:
             raise ValueError("No connection configured. Use from_env() or provide credentials.")
 
@@ -153,6 +196,10 @@ class PhyHubClient:
         # Set up event handlers
         self._setup_socket_listeners()
 
+        # npm parity: on every (re)connect, re-subscribe twins (the server
+        # loses subscriptions across reconnects) and flush queued emits.
+        self._connection.on("connect", self._handle_socket_connected)
+
         # Only direct mode needs explicit authenticate/connectDevice handshake.
         # PhyOS and Simulator handle auth at Socket.IO connection time.
         if self._connection.is_direct:
@@ -164,6 +211,10 @@ class PhyHubClient:
 
     async def disconnect(self) -> None:
         """Disconnect from PhyHub."""
+        if self._cloud_app_connection:
+            await self._cloud_app_connection.disconnect()
+            self._cloud_app_connection = None
+            self._cloud_twin_store = None
         if self._connection:
             await self._connection.disconnect()
         self._connected = False
@@ -171,6 +222,85 @@ class PhyHubClient:
         if self._registry:
             self._registry.clear()
 
+    # =========================================================================
+    # Cloud-app mode (npm PhyHubClientParams.cloudApp parity)
+    # =========================================================================
+
+    async def _connect_cloud_app(self) -> "PhyHubClient":
+        """Connect the cloud-app branch: JWT exchange + cloud twin lifecycle."""
+        assert self._cloud_app_params is not None
+        self._cloud_app_connection = CloudAppConnection(self._cloud_app_params)
+        self._cloud_twin_store = CloudTwinStore()
+        result = await self._cloud_app_connection.connect()
+        self._cloud_twin_store.hydrate(result.initial_twins)
+
+        store = self._cloud_twin_store
+        socket = result.socket
+
+        def on_cloud_authenticated(payload: Any) -> None:
+            twins = payload.get("twins") if isinstance(payload, dict) else None
+            store.hydrate(twins if isinstance(twins, list) else None)
+
+        socket.on("cloudAppAuthenticated", on_cloud_authenticated)
+        socket.on("twinCreated", store.apply_created)
+        socket.on("twinUpdated", store.apply_updated)
+        socket.on("twinDeleted", store.apply_deleted)
+
+        self._connected = True
+        return self
+
+    def get_cloud_twins(self) -> list[CloudTwin]:
+        """Snapshot of the cloud twin store (cloud-app mode only, else [])."""
+        if self._cloud_twin_store is None:
+            return []
+        return self._cloud_twin_store.snapshot()
+
+    def on_cloud_twin_created(self, callback: Callable[[Any], None]) -> Callable[[], None]:
+        """Cloud twin lifecycle listener; returns an unsubscribe callable."""
+        if self._cloud_twin_store is None:
+            return lambda: None
+        return self._cloud_twin_store.on_created(callback)
+
+    def on_cloud_twin_updated(self, callback: Callable[[Any], None]) -> Callable[[], None]:
+        """Cloud twin lifecycle listener; returns an unsubscribe callable."""
+        if self._cloud_twin_store is None:
+            return lambda: None
+        return self._cloud_twin_store.on_updated(callback)
+
+    def on_cloud_twin_deleted(self, callback: Callable[[Any], None]) -> Callable[[], None]:
+        """Cloud twin lifecycle listener; returns an unsubscribe callable."""
+        if self._cloud_twin_store is None:
+            return lambda: None
+        return self._cloud_twin_store.on_deleted(callback)
+
+    async def _handle_socket_connected(self) -> None:
+        """Reconnect hook: re-subscribe twins, then flush the emit queue."""
+        for twin_id in list(self._subscribed_twins):
+            payload = {
+                "twinId": twin_id,
+                "sourceTwinId": self._instance_id,
+                "sourceDeviceId": self._connection.device_id if self._connection else None,
+            }
+            try:
+                await self._emit_to_socket(self.EVENTS.TWIN_SUBSCRIBE, payload, callback=True)
+            except Exception as resubscribe_error:
+                logger.warning(
+                    "Failed to re-subscribe twin %s after reconnect: %s",
+                    twin_id,
+                    resubscribe_error,
+                )
+
+        pending, self._emit_queue = self._emit_queue, []
+        for method, payload, callback, future in pending:
+            try:
+                result = await self._emit_to_socket(method, payload, callback=callback)
+                if future and not future.done():
+                    future.set_result(result)
+            except Exception as flush_error:
+                logger.warning("Failed to flush queued emit %s: %s", method, flush_error)
+                if future and not future.done():
+                    future.set_exception(flush_error)
+
     def _setup_socket_listeners(self) -> None:
         """Set up Socket.IO event handlers."""
         if not self._connection:
@@ -287,6 +417,14 @@ class PhyHubClient:
         self._instance = await self._registry.get_edge_instance()
         return self._instance
 
+    async def get_edge_instance(self) -> Optional[EdgeInstance]:
+        """Alias for get_instance (npm parity)."""
+        return await self.get_instance()
+
+    async def get_screen_instance(self) -> Optional[EdgeInstance]:
+        """Alias for get_instance (npm parity — no distinct screen instance)."""
+        return await self.get_instance()
+
     async def get_peripheral_instance(self, twin_id: str) -> Optional[PeripheralInstance]:
         """Get a peripheral instance by twin ID.
 
@@ -339,6 +477,17 @@ class PhyHubClient:
         if not self._connection:
             return None
 
+        # npm parity (emitQueue): while the socket is down, queue instead of
+        # failing. Fire-and-forget entries return immediately; ack-style calls
+        # await a future resolved when the queue flushes on reconnect.
+        if not self._connection.is_connected:
+            if not callback:
+                self._emit_queue.append((method, payload, False, None))
+                return None
+            pending_future: "asyncio.Future[Any]" = asyncio.get_event_loop().create_future()
+            self._emit_queue.append((method, payload, True, pending_future))
+            return await pending_future
+
         if self._connection.is_direct:
             # Direct mode: emit to event name directly
             return await self._connection.emit(method, payload, callback=callback)
@@ -626,12 +775,18 @@ class PhyHubClient:
     async def get_device_status(self) -> Optional[dict[str, Any]]:
         """Get device status (IP, serial, env, etc.).
 
+        Responses are cached for 10 seconds (npm parity).
+
         Returns:
             Device status dictionary.
         """
-        return await self._emit_to_socket(
-            self.EVENTS.GET_DEVICE_STATUS, {}, callback=True
-        )
+        now = time.monotonic()
+        if self._device_status_cache and now - self._device_status_cache[0] < 10.0:
+            return self._device_status_cache[1]
+        result = await self._emit_to_socket(self.EVENTS.GET_DEVICE_STATUS, {}, callback=True)
+        if result is not None:
+            self._device_status_cache = (now, result)
+        return result
 
     async def get_device_instance(self) -> Optional[dict[str, Any]]:
         """Get device instance data.
@@ -657,11 +812,20 @@ class PhyHubClient:
     # WebRTC Helpers
     # =========================================================================
 
-    def _create_twin_messaging_interface(self) -> DataChannelMessaging:
+    def _create_twin_messaging_interface(
+        self, identity_twin_id: Optional[str] = None
+    ) -> DataChannelMessaging:
         """Create a twin messaging interface for WebRTC handlers.
 
         This interface matches the npm TwinMessagingInterface and is used
         for WebRTC signaling (offer/answer/ice exchange).
+
+        Args:
+            identity_twin_id: Signaling identity override. A publisher on a
+                peripheral twin must sign its signaling with the PERIPHERAL
+                twin id (npm parity: peripheral-twin.ts wires a dedicated
+                WebRTC transport for this) — viewers filter incoming signals
+                by the twin they dialed. Defaults to the edge instance id.
         """
         async def send_message(target_twin_id: str, payload: dict[str, Any]) -> None:
             """Send a twin message for signaling.
@@ -674,7 +838,7 @@ class PhyHubClient:
 
             event_payload = {
                 "twinId": target_twin_id,
-                "sourceTwinId": self._instance_id,
+                "sourceTwinId": identity_twin_id or self._instance_id,
                 "sourceDeviceId": self._connection.device_id if self._connection else None,
                 "data": payload,
             }
@@ -686,9 +850,10 @@ class PhyHubClient:
             await self.subscribe_twin(twin_id)
 
         def get_own_twin_id() -> str:
-            if not self._instance_id:
+            own_twin_id = identity_twin_id or self._instance_id
+            if not own_twin_id:
                 raise ValueError("Instance ID not set")
-            return self._instance_id
+            return own_twin_id
 
         return DataChannelMessaging(
             send_message=send_message,
@@ -698,6 +863,139 @@ class PhyHubClient:
             get_own_twin_id=get_own_twin_id,
         )
 
+    # =========================================================================
+    # ICE Servers API
+    # =========================================================================
+
+    async def get_ice_servers(self, use_case: str = "media") -> list[dict[str, Any]]:
+        """Fetch ICE servers (STUN + short-lived TURN credentials) from phyhub.
+
+        Mirrors the npm client's getIceServers: emits the `getIceServers`
+        socket event ({data: {useCase}}), caches credential-bearing results
+        until shortly before their TTL expires, and raises on timeout so
+        callers can fall back to static STUN (npm parity).
+
+        Returns:
+            List of {urls, username?, credential?} dicts.
+        """
+        cached = self._cached_ice_servers.get(use_case)
+        if cached and time.monotonic() < cached[0]:
+            return cached[1]
+
+        result = await asyncio.wait_for(
+            self._emit_to_socket(
+                self.EVENTS.GET_ICE_SERVERS, {"data": {"useCase": use_case}}, callback=True
+            ),
+            timeout=10.0,
+        )
+        if not result or not isinstance(result.get("iceServers"), list):
+            raise ValueError("getIceServers(): no iceServers in response")
+
+        servers: list[dict[str, Any]] = result["iceServers"]
+        ttl_seconds = result.get("ttlSeconds") or 0
+        if ttl_seconds > 0:
+            # Refresh a margin before expiry so a fan-out never hands out
+            # nearly-expired credentials (npm parity).
+            refresh_margin = min(30.0, ttl_seconds * 0.5)
+            refresh_at = time.monotonic() + ttl_seconds - refresh_margin
+        else:
+            # Short negative-cache for unconfigured regions.
+            refresh_at = time.monotonic() + 30.0
+        self._cached_ice_servers[use_case] = (refresh_at, servers)
+        return servers
+
+    # =========================================================================
+    # Media Responder (publisher fan-out) API
+    # =========================================================================
+
+    async def accept_media_streams(
+        self,
+        twin_id: str,
+        callback: Callable[[ResponderPeer], None],
+        options: Optional[MediaStreamResponderOptions] = None,
+        stream_name: str = "default",
+    ) -> MediaStreamResponder:
+        """Arm a multi-viewer publisher fan-out on a twin (npm acceptMediaStream).
+
+        Every viewer that dials the twin gets its own peer connection with a
+        fresh track from options.create_local_track. Re-arming an existing
+        (twin_id, stream_name) stops the previous responder first.
+        """
+        responder_options = options or MediaStreamResponderOptions()
+        if responder_options.ice_servers_provider is None:
+            async def default_ice_provider() -> list[dict[str, Any]]:
+                return await self.get_ice_servers("media")
+
+            responder_options.ice_servers_provider = default_ice_provider
+
+        responder_key = f"{twin_id}:{stream_name}"
+        previous = self._media_responders.pop(responder_key, None)
+        if previous:
+            previous.stop()
+
+        responder = MediaStreamResponder(
+            twin_id=twin_id,
+            twin_messaging=self._create_twin_messaging_interface(identity_twin_id=twin_id),
+            callback=callback,
+            options=responder_options,
+            stream_name=stream_name,
+        )
+        await responder.start()
+        self._media_responders[responder_key] = responder
+        return responder
+
+    def get_media_responder(
+        self, twin_id: str, stream_name: str = "default"
+    ) -> Optional[MediaStreamResponder]:
+        """Look up an armed responder (e.g. to answer a connectStream offer)."""
+        return self._media_responders.get(f"{twin_id}:{stream_name}")
+
+    # =========================================================================
+    # Data-channel Responder (fan-out) API
+    # =========================================================================
+
+    async def accept_data_channels(
+        self,
+        twin_id: str,
+        callback: Callable[[ResponderChannel], None],
+        options: Optional[DataChannelResponderOptions] = None,
+        channel_name: str = "default",
+    ) -> DataChannelResponder:
+        """Arm a multi-peer data-channel fan-out on a twin (npm acceptDataChannel).
+
+        Every initiator that dials the twin gets its own peer connection and
+        channel; the callback fires once per opened channel. Re-arming an
+        existing (twin_id, channel_name) stops the previous responder first.
+        """
+        responder_options = options or DataChannelResponderOptions()
+        if responder_options.ice_servers_provider is None:
+            async def default_ice_provider() -> list[dict[str, Any]]:
+                return await self.get_ice_servers("media")
+
+            responder_options.ice_servers_provider = default_ice_provider
+
+        responder_key = f"{twin_id}:{channel_name}"
+        previous = self._data_responders.pop(responder_key, None)
+        if previous:
+            previous.stop()
+
+        responder = DataChannelResponder(
+            twin_id=twin_id,
+            twin_messaging=self._create_twin_messaging_interface(identity_twin_id=twin_id),
+            callback=callback,
+            options=responder_options,
+            channel_name=channel_name,
+        )
+        await responder.start()
+        self._data_responders[responder_key] = responder
+        return responder
+
+    def get_data_responder(
+        self, twin_id: str, channel_name: str = "default"
+    ) -> Optional[DataChannelResponder]:
+        """Look up an armed data-channel responder."""
+        return self._data_responders.get(f"{twin_id}:{channel_name}")
+
     async def create_data_channel(
         self,
         target_twin_id: str,
@@ -722,6 +1020,15 @@ class PhyHubClient:
         if not self._connected:
             raise ConnectionError("Not connected to PhyHub")
 
+        # npm parity: every connection gets phyhub TURN credentials by default
+        # (getWebRTCManager wires getIceServers('media') as the ICE provider).
+        options = options or DataChannelOptions()
+        if options.ice_servers_provider is None:
+            async def default_data_ice_provider() -> list[dict[str, Any]]:
+                return await self.get_ice_servers("media")
+
+            options.ice_servers_provider = default_data_ice_provider
+
         # Subscribe to target twin
         await self.subscribe_twin(target_twin_id)
 
@@ -764,6 +1071,15 @@ class PhyHubClient:
         if not self._connected:
             raise ConnectionError("Not connected to PhyHub")
 
+        # npm parity: viewers fetch phyhub TURN credentials by default — the
+        # gap that made Python consumers fail cross-network where npm worked.
+        options = options or MediaStreamOptions()
+        if options.ice_servers_provider is None:
+            async def default_media_ice_provider() -> list[dict[str, Any]]:
+                return await self.get_ice_servers("media")
+
+            options.ice_servers_provider = default_media_ice_provider
+
         # Subscribe to target twin
         await self.subscribe_twin(target_twin_id)