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

phystack_hub_client-6.16.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog — phystack-hub-client (Python)
+
+Fixed version group with npm `@phystack/hub-client` (phystack/ps-platform): same
+twin/WebRTC contract, released under the same version. The PyPI workflow only
+publishes even minors from `main`, so a Python release is the next even minor at
+or above the npm version it matches; the entries below name the npm version and
+PRs each change was ported from.
+
+## 6.16.0 — parity with npm 6.15.1 (TECH-1483)
+
+### Added
+
+- `PhyHubClient.create_web_session_code(twin_id=… | endpoint_id=…)` and
+  `PhyHubClient.subscribe_web_session_code(listener, …)`: the device-side
+  web-session claim-code issuer (npm 6.10.0 / 6.11.0, ps-platform #893, #896).
+  Same wire event (`createWebSessionCode`) and ack contract as npm; the
+  rotating issuer renews at a fraction of the code TTL with downward jitter,
+  re-mints after a socket reconnect, retries failures with capped exponential
+  backoff, and reports `unavailable` states (terminal for a non-Web twin).
+  Device sessions only, as in npm (`services/web_session_code.py`).
+
+### Parity audit — device-session semantics vs npm 6.14.0 / 6.15.0 / 6.15.1
+
+npm 6.9.0–6.15.x is mostly web-session work (browser sessions behind a web
+endpoint), which has no Python counterpart and is not needed for edge apps.
+Verified, no code change required:
+
+- Twin messages from a device are sent fire-and-forget (`_send_event` →
+  `twinMessage` without an ack callback; requests settle on the `response` twin
+  message or the 10 s timeout). npm 6.15.0 added ack-based fail-fast and
+  6.15.1 (ps-platform #927) reverted it for device sessions because the
+  edge-hub relays acks that do not describe delivery. Python never had it.
+- Consumer media dials use the client's own identity
+  (`PhyHubClient.create_media_stream(twin_id)`); the responder replies to the
+  offer's `sourceTwinId`, so this matches the 6.15.1 device behaviour.
+- Owner-only peripheral methods (`update_reported`, `update_desired`,
+  `remove`) are not gated client-side; the server decides (npm 6.15.1).
+- `disconnect()` leaves the client reusable (npm 6.14.0 fixed a cached dead
+  client on the Node side; Python re-connects through `PhyHubConnection`).
+
+Not ported (web-session only): `connect({ webApp })`, `getWebInstance()`,
+session persistence/resume, web `getPeripheralInstance()`, the `media:view`
+signaling gate (phyhub-side).
+
+## 6.8.0 — parity with npm 6.8.0 (TECH-1417)
+
+See the release notes on GitHub.

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: phystack-hub-client
-Version: 6.6.0
+Version: 6.16.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
@@ -103,6 +103,35 @@ def handle_action(data, respond):
 instance.on("my-action", handle_action)
 ```
 
+### Web-session claim codes (QR for web apps)
+
+A screen/edge app can mint the claim codes a phone scans to open a web app
+session (the device side of the web-app QR flow). Identify the Web endpoint by
+exactly one of `twin_id` (the Web twin's `_id`, what a settings twin picker
+stores) or `endpoint_id` (the Web twin's `deviceId`, as shown by the Console
+and `phy web-endpoint get`).
+
+```python
+# One code — the URL is the complete link to render as a QR
+issued = await client.create_web_session_code(twin_id=settings["remoteWeb"]["id"])
+print(issued.url, issued.expires_in)
+
+# Rotating codes for a permanently displayed QR: the listener gets the initial
+# code, every rotation, a re-mint after each reconnect, and `unavailable`
+# states while minting fails (hide the QR instead of showing a dead code).
+def render(state):
+    if state.status == "active":
+        show_qr(state.url)
+    else:
+        hide_qr(state.message)
+
+subscription = client.subscribe_web_session_code(render, endpoint_id="863d9307-…")
+subscription.refresh()   # mint now
+subscription.stop()      # release timers and the reconnect listener
+```
+
+Device sessions only: phyhub registers `createWebSessionCode` on device sockets, so a cloud-app session raises immediately.
+
 ### WebRTC DataChannel
 
 ```python

{phystack_hub_client-6.6.0 → phystack_hub_client-6.16.0}/README.md

@@ -72,6 +72,35 @@ def handle_action(data, respond):
 instance.on("my-action", handle_action)
 ```
 
+### Web-session claim codes (QR for web apps)
+
+A screen/edge app can mint the claim codes a phone scans to open a web app
+session (the device side of the web-app QR flow). Identify the Web endpoint by
+exactly one of `twin_id` (the Web twin's `_id`, what a settings twin picker
+stores) or `endpoint_id` (the Web twin's `deviceId`, as shown by the Console
+and `phy web-endpoint get`).
+
+```python
+# One code — the URL is the complete link to render as a QR
+issued = await client.create_web_session_code(twin_id=settings["remoteWeb"]["id"])
+print(issued.url, issued.expires_in)
+
+# Rotating codes for a permanently displayed QR: the listener gets the initial
+# code, every rotation, a re-mint after each reconnect, and `unavailable`
+# states while minting fails (hide the QR instead of showing a dead code).
+def render(state):
+    if state.status == "active":
+        show_qr(state.url)
+    else:
+        hide_qr(state.message)
+
+subscription = client.subscribe_web_session_code(render, endpoint_id="863d9307-…")
+subscription.refresh()   # mint now
+subscription.stop()      # release timers and the reconnect listener
+```
+
+Device sessions only: phyhub registers `createWebSessionCode` on device sockets, so a cloud-app session raises immediately.
+
 ### WebRTC DataChannel
 
 ```python

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

@@ -7,7 +7,7 @@ name = "phystack-hub-client"
 # 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"
+version = "6.16.0"
 description = "Python client for PhyHub - events, actions, DataChannel, and MediaStream"
 readme = "README.md"
 license = "MIT"

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

@@ -46,12 +46,20 @@ Or with context manager:
 
 from phystack.hub_client.client import PhyHubClient, connect_phy_client
 from phystack.hub_client.types.twin_types import (
+    PeripheralCreateResult,
+    PeripheralHandover,
+    PeripheralOwnershipLoss,
     TwinMessageResult,
     TwinMessageResultStatus,
     TwinProperties,
     TwinTypeEnum,
     TwinStatusEnum,
 )
+from phystack.hub_client.scoped_hardware_id import (
+    HARDWARE_ID_SCOPES,
+    HARDWARE_ID_USER_PART_MAX_LENGTH,
+    format_scoped_hardware_id,
+)
 from phystack.hub_client.instances import (
     BaseInstance,
     EdgeInstance,
@@ -66,6 +74,8 @@ from phystack.hub_client.services.webrtc.data_channel import (
 from phystack.hub_client.services.webrtc.media_stream import (
     MediaStreamHandler,
     MediaStreamOptions,
+    MediaTrackKind,
+    MissingMediaTrackError,
     PhygridMediaStream,
     WebcamVideoTrack,
 )
@@ -100,6 +110,13 @@ from phystack.hub_client.services.cloud_app_connection import (
     CloudAppConnectResult,
 )
 from phystack.hub_client.cloud_twins import CloudTwinStore
+from phystack.hub_client.services.web_session_code import (
+    WebSessionCode,
+    WebSessionCodeConfigError,
+    WebSessionCodeIssuer,
+    WebSessionCodeListener,
+    WebSessionCodeState,
+)
 from phystack.hub_client.services.signals import (
     SignalsService,
     InitSignalPayload,
@@ -113,7 +130,7 @@ from phystack.hub_client.services.signals import (
 
 # Kept in a fixed version group with @phystack/hub-client (npm) — same
 # contract, same release version.
-__version__ = "6.5.0"
+__version__ = "6.16.0"
 __all__ = [
     # Client
     "PhyHubClient",
@@ -129,12 +146,21 @@ __all__ = [
     "TwinProperties",
     "TwinTypeEnum",
     "TwinStatusEnum",
+    # Peripheral identity + ownership (TECH-1394)
+    "PeripheralCreateResult",
+    "PeripheralHandover",
+    "PeripheralOwnershipLoss",
+    "HARDWARE_ID_SCOPES",
+    "HARDWARE_ID_USER_PART_MAX_LENGTH",
+    "format_scoped_hardware_id",
     # WebRTC
     "DataChannelHandler",
     "DataChannelOptions",
     "PhygridDataChannel",
     "MediaStreamHandler",
     "MediaStreamOptions",
+    "MediaTrackKind",
+    "MissingMediaTrackError",
     "PhygridMediaStream",
     "WebcamVideoTrack",
     "FrameSourceTrack",
@@ -158,6 +184,12 @@ __all__ = [
     "CloudAppConnectionParams",
     "CloudAppConnectResult",
     "CloudTwinStore",
+    # Web-session claim codes (device-side QR issuer)
+    "WebSessionCode",
+    "WebSessionCodeConfigError",
+    "WebSessionCodeIssuer",
+    "WebSessionCodeListener",
+    "WebSessionCodeState",
     # Signals
     "SignalsService",
     "InitSignalPayload",

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

@@ -50,6 +50,14 @@ from phystack.hub_client.services.webrtc.data_responder import (
     DataChannelResponderOptions,
     ResponderChannel,
 )
+from phystack.hub_client.services.web_session_code import (
+    DEFAULT_RENEW_AT_FRACTION,
+    DEFAULT_REQUEST_TIMEOUT_SECONDS,
+    WebSessionCode,
+    WebSessionCodeIssuer,
+    WebSessionCodeListener,
+    create_web_session_code,
+)
 from phystack.hub_client.services.cloud_app_connection import (
     CloudAppConnection,
     CloudAppConnectionParams,
@@ -83,6 +91,7 @@ class PhyHubClient:
         DISCONNECT = "disconnect"
         TWIN_MESSAGE = "twinMessage"
         TWIN_SUBSCRIBE = "twinSubscribe"
+        TWIN_UNSUBSCRIBE = "twinUnsubscribe"
         TWIN_UPDATED = "twinUpdated"
         GET_TWIN_BY_ID = "getTwinById"
         REPORT_SCREEN_PROPERTIES = "reportScreenTwinProperties"
@@ -210,7 +219,15 @@ class PhyHubClient:
         return self
 
     async def disconnect(self) -> None:
-        """Disconnect from PhyHub."""
+        """Disconnect from PhyHub.
+
+        npm 6.7.0 parity: clears the twin listener registries, cached
+        instances, subscribed-twin set, and the emit queue — listeners
+        registered before a disconnect() do not survive into a later
+        reconnect, and queued emits fail instead of hanging. The client
+        stays reusable. WebRTC connections are NOT torn down — hold the
+        stop()/close() handles from the responder/stream APIs.
+        """
         if self._cloud_app_connection:
             await self._cloud_app_connection.disconnect()
             self._cloud_app_connection = None
@@ -221,6 +238,15 @@ class PhyHubClient:
         self._instance = None
         if self._registry:
             self._registry.clear()
+        self._twin_message_listeners.clear()
+        self._twin_update_listeners.clear()
+        self._subscribed_twins.clear()
+        pending_emits, self._emit_queue = self._emit_queue, []
+        for _method, _payload, _needs_ack, pending_future in pending_emits:
+            if pending_future and not pending_future.done():
+                pending_future.set_exception(
+                    ConnectionError("disconnect() dropped the queued emit")
+                )
 
     # =========================================================================
     # Cloud-app mode (npm PhyHubClientParams.cloudApp parity)
@@ -347,10 +373,23 @@ class PhyHubClient:
             if not twin_id:
                 return
 
+            # Ownership-loss detection (TECH-1394): peripheral hardwareIds
+            # are unique tenant-wide, so another device — or another instance
+            # on THIS device — registering the same id takes our twin over.
+            # Level-triggered against the twin's current owner identity
+            # (deviceId + desired.instanceId), not edge-triggered on the
+            # takeover event itself: every later twinUpdated re-delivers the
+            # signal, so a takeover missed during a disconnect self-heals on
+            # the next twin activity. Only instances ACQUIRED as owner are
+            # considered — a consumer holding a sibling instance's peripheral
+            # legitimately sees a foreign instanceId forever.
+            if isinstance(twin_data, dict) and twin_data.get("deviceId"):
+                self._detect_peripheral_ownership_loss(twin_id, twin_data)
+
             # Notify twin update listeners
             listeners = self._twin_update_listeners.get(twin_id)
             if listeners:
-                for callback in listeners:
+                for callback in list(listeners):
                     try:
                         callback(twin_data)
                     except Exception as e:
@@ -585,6 +624,78 @@ class PhyHubClient:
 
         return result.get("twin") if result else None
 
+    # =========================================================================
+    # Web-session claim codes (device sessions only) — npm 6.10.0 / 6.11.0 parity
+    # =========================================================================
+
+    def _assert_device_session(self, operation: str) -> None:
+        """Claim-code issuing is a device-session capability: phyhub registers
+        `createWebSessionCode` only on authenticated device sockets (a cloud
+        session would hang with no handler) — fail fast instead."""
+        if self._cloud_app_params is not None:
+            raise RuntimeError(
+                f"{operation} is only available for device sessions (screen/edge apps)"
+            )
+
+    def _web_session_code_adapter(self) -> "_WebSessionCodeAdapter":
+        return _WebSessionCodeAdapter(self)
+
+    async def create_web_session_code(
+        self,
+        *,
+        twin_id: Optional[str] = None,
+        endpoint_id: Optional[str] = None,
+        request_timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+    ) -> WebSessionCode:
+        """Mint ONE claim code for a Web endpoint (device sessions only). The
+        returned ``url`` is the complete public link
+        (``{root}/{urlId}/#code={code}``) to render as a QR. Identify the
+        endpoint by exactly one of:
+
+        - ``twin_id`` — the Web twin's ``_id``, as stored by a settings twin picker
+        - ``endpoint_id`` — the Web twin's ``deviceId``, as shown in Console/CLI
+
+        Codes expire after the endpoint's ``codeTtlSeconds``; for a
+        continuously displayed QR use :meth:`subscribe_web_session_code`, which
+        rotates them.
+        """
+        self._assert_device_session("create_web_session_code()")
+        return await create_web_session_code(
+            self._web_session_code_adapter(),
+            twin_id=twin_id,
+            endpoint_id=endpoint_id,
+            request_timeout_seconds=request_timeout_seconds,
+        )
+
+    def subscribe_web_session_code(
+        self,
+        listener: WebSessionCodeListener,
+        *,
+        twin_id: Optional[str] = None,
+        endpoint_id: Optional[str] = None,
+        renew_at_fraction: float = DEFAULT_RENEW_AT_FRACTION,
+        request_timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+    ) -> WebSessionCodeIssuer:
+        """Keep a fresh claim code available for a QR display (device sessions
+        only). ``listener`` receives a :class:`WebSessionCodeState` for the
+        initial code, every rotation (at ``renew_at_fraction`` of the code
+        TTL, with downward jitter), after every socket reconnect, and as
+        ``unavailable`` while minting fails (capped exponential backoff; a
+        non-Web twin is terminal). Returns the issuer: call ``refresh()`` to
+        mint now, ``stop()`` to release it. Must be called from a running
+        event loop.
+        """
+        self._assert_device_session("subscribe_web_session_code()")
+        issuer = WebSessionCodeIssuer(
+            self._web_session_code_adapter(),
+            listener,
+            twin_id=twin_id,
+            endpoint_id=endpoint_id,
+            renew_at_fraction=renew_at_fraction,
+            request_timeout_seconds=request_timeout_seconds,
+        )
+        return issuer.start()
+
     # =========================================================================
     # Settings API
     # =========================================================================
@@ -670,6 +781,8 @@ class PhyHubClient:
         Returns:
             Updated twin data.
         """
+        from phystack.hub_client.types.twin_types import PeripheralOwnershipLoss
+
         # Dispatch to correct event based on twin type (matches Node.js behavior)
         if twin_type == TwinTypeEnum.Screen:
             event = self.EVENTS.REPORT_SCREEN_PROPERTIES
@@ -680,6 +793,19 @@ class PhyHubClient:
 
         payload = {"twinId": twin_id, "data": properties}
         result = await self._emit_to_socket(event, payload, callback=True)
+        if result and result.get("status") not in (None, "success"):
+            # Ownership-loss fallback (TECH-1394): a report rejected with
+            # PeripheralOwnershipError means another device took the twin
+            # over while we were offline — the twinUpdated notification
+            # never reached us, so revoke here.
+            if result.get("errorType") == "PeripheralOwnershipError":
+                self._handle_peripheral_ownership_lost(
+                    twin_id, PeripheralOwnershipLoss()
+                )
+            # npm 6.5.1 parity: carry the server's reason from the ack.
+            raise RuntimeError(
+                result.get("message") or "updateReportedProperties failed"
+            )
         return result.get("twin") if result else None
 
     # =========================================================================
@@ -788,6 +914,168 @@ class PhyHubClient:
             self._device_status_cache = (now, result)
         return result
 
+    async def resolve_device_space_id(self, timeout_seconds: float = 3.0) -> str:
+        """Resolve the device's current spaceId for space-scoped hardwareId
+        minting (TECH-1394). Bypasses get_device_status's 10s cache window
+        unless the cached status already carries a spaceId; otherwise asks
+        directly with its own timeout.
+
+        Raises:
+            RuntimeError: When the status request yields no answer in time or
+                the response carries no spaceId.
+        """
+        if self._device_status_cache:
+            cached_space_id = self._device_status_cache[1].get("spaceId")
+            if cached_space_id:
+                return str(cached_space_id)
+
+        try:
+            status = await asyncio.wait_for(
+                self._emit_to_socket(self.EVENTS.GET_DEVICE_STATUS, {}, callback=True),
+                timeout=timeout_seconds,
+            )
+        except asyncio.TimeoutError as timeout_error:
+            raise RuntimeError(
+                "generate_scoped_hardware_id: could not get spaceId — "
+                f"getDeviceStatus gave no answer within {timeout_seconds}s"
+            ) from timeout_error
+
+        space_id = (status or {}).get("spaceId")
+        if not space_id:
+            raise RuntimeError(
+                "generate_scoped_hardware_id: the device status response "
+                "did not include a spaceId"
+            )
+        return str(space_id)
+
+    def _detect_peripheral_ownership_loss(
+        self, twin_id: str, twin_data: dict[str, Any]
+    ) -> None:
+        """Compare an updated twin's owner identity against a pooled
+        owner-acquired peripheral instance; revoke on mismatch."""
+        from phystack.hub_client.types.twin_types import PeripheralOwnershipLoss
+
+        registry = self._registry
+        owned_peripheral = (
+            registry.get_cached_peripheral_instance(twin_id) if registry else None
+        )
+        if owned_peripheral is None or not owned_peripheral.acquired_as_owner:
+            return
+
+        own_device_id = owned_peripheral.edge_instance.device_id
+        own_instance_id = owned_peripheral.edge_instance.id
+        if not own_device_id:
+            return
+
+        updated_device_id = twin_data.get("deviceId")
+        updated_instance_id = (
+            twin_data.get("properties", {}).get("desired", {}).get("instanceId")
+        )
+        lost_to_device = updated_device_id != own_device_id
+        lost_to_instance = (
+            not lost_to_device
+            and own_instance_id is not None
+            and updated_instance_id is not None
+            and updated_instance_id != own_instance_id
+        )
+        if not lost_to_device and not lost_to_instance:
+            return
+
+        self._handle_peripheral_ownership_lost(
+            twin_id,
+            PeripheralOwnershipLoss(
+                new_owner_device_id=updated_device_id if lost_to_device else None,
+                new_owner_instance_id=(
+                    updated_instance_id if lost_to_instance else None
+                ),
+            ),
+        )
+
+    def _handle_peripheral_ownership_lost(
+        self, twin_id: str, loss: "PeripheralOwnershipLoss"
+    ) -> None:
+        """Revoke a peripheral this app lost to another device or to another
+        instance on this device (TECH-1394):
+
+        - mark the pooled PeripheralInstance ownership-lost (its
+          emit/update_reported start raising locally, its listeners are
+          dropped, on_ownership_lost fires so the app releases the hardware);
+        - drop it from the registry pool, so a later re-acquire (after taking
+          the twin back via create_peripheral_twin) builds a fresh instance;
+        - unsubscribe from the twin room, server-side AND locally — removing
+          the id from _subscribed_twins is what stops the reconnect
+          re-subscribe from silently rejoining the room we were evicted from.
+        """
+        registry = self._registry
+        peripheral_instance = (
+            registry.get_cached_peripheral_instance(twin_id) if registry else None
+        )
+        if peripheral_instance is None:
+            return
+
+        if loss.new_owner_device_id:
+            new_owner_label = f" by device {loss.new_owner_device_id}"
+        elif loss.new_owner_instance_id:
+            new_owner_label = (
+                f" by instance {loss.new_owner_instance_id} on this device"
+            )
+        else:
+            new_owner_label = ""
+        logger.warning(
+            "peripheral %s was taken over%s — revoking the local instance",
+            twin_id,
+            new_owner_label,
+        )
+
+        self._subscribed_twins.discard(twin_id)
+        if registry:
+            registry.remove_peripheral_instance(twin_id)
+
+        # Best-effort server-side unsubscribe: phyhub already evicted our
+        # sockets from the twin room at takeover; this covers the case where
+        # that eviction failed or raced our reconnect.
+        try:
+            unsubscribe_payload = {
+                "twinId": twin_id,
+                "sourceTwinId": peripheral_instance.edge_instance.id,
+            }
+            asyncio.create_task(
+                self._emit_to_socket(self.EVENTS.TWIN_UNSUBSCRIBE, unsubscribe_payload)
+            )
+        except Exception as unsubscribe_error:
+            logger.warning(
+                "Failed to send twinUnsubscribe for taken-over peripheral %s: %s",
+                twin_id,
+                unsubscribe_error,
+            )
+
+        peripheral_instance.mark_ownership_lost(loss)
+
+    def stop_responders_for_twin(self, twin_id: str) -> None:
+        """Stop any armed media/data responders publishing on a twin.
+
+        Best-effort: used by ownership-loss revocation so a taken-over
+        peripheral stops serving viewers the new owner should serve.
+        """
+        for key in list(self._media_responders):
+            if key.startswith(f"{twin_id}:"):
+                responder = self._media_responders.pop(key)
+                try:
+                    asyncio.create_task(responder.stop())
+                except Exception as stop_error:
+                    logger.warning(
+                        "Failed to stop media responder %s: %s", key, stop_error
+                    )
+        for key in list(self._data_responders):
+            if key.startswith(f"{twin_id}:"):
+                responder = self._data_responders.pop(key)
+                try:
+                    asyncio.create_task(responder.stop())
+                except Exception as stop_error:
+                    logger.warning(
+                        "Failed to stop data responder %s: %s", key, stop_error
+                    )
+
     async def get_device_instance(self) -> Optional[dict[str, Any]]:
         """Get device instance data.
 
@@ -1126,3 +1414,31 @@ async def connect_phy_client() -> PhyHubClient:
     client = PhyHubClient.from_env()
     await client.connect()
     return client
+
+
+class _WebSessionCodeAdapter:
+    """PhyHubClient slice for the web-session code issuer (see
+    services/web_session_code.py). Kept off the client's public surface."""
+
+    def __init__(self, client: PhyHubClient) -> None:
+        self._client = client
+
+    async def ensure_connection(self) -> None:
+        connection = self._client._connection
+        if connection is not None and connection.is_connected:
+            return
+        await self._client.connect()
+
+    async def emit_with_ack(self, method: str, payload: dict[str, Any]) -> Any:
+        return await self._client._emit_to_socket(method, payload, callback=True)
+
+    async def get_twin_by_id(self, twin_id: str) -> Optional[dict[str, Any]]:
+        return await self._client.get_twin_by_id(twin_id)
+
+    def on_connect(self, handler: Callable[[], None]) -> None:
+        if self._client._connection is not None:
+            self._client._connection.on("connect", handler)
+
+    def off_connect(self, handler: Callable[[], None]) -> None:
+        if self._client._connection is not None:
+            self._client._connection.off("connect", handler)

{phystack_hub_client-6.6.0 → phystack_hub_client-6.16.0}/src/phystack/hub_client/instances/base_instance.py

@@ -109,14 +109,31 @@ class BaseInstance:
         self,
         event_type: str,
         callback: Callable[[Any, Optional[Callable[[TwinMessageResult], None]]], None],
-    ) -> None:
+    ) -> Callable[[], None]:
         """Listen for events, with optional respond callback for request-response.
 
         Args:
             event_type: Type of event to listen for.
             callback: Handler function (data, respond?) => None
+
+        Returns:
+            An unsubscribe callable that removes exactly this listener
+            (npm 6.7.0 parity).
+        """
+        return self._messaging.on(event_type, callback)
+
+    def off(
+        self,
+        event_type: str,
+        callback: Callable[[Any, Optional[Callable[[TwinMessageResult], None]]], None],
+    ) -> bool:
+        """Remove a listener registered with on(), matched by the caller's
+        original callback identity (npm 6.7.0 parity).
+
+        Returns:
+            True when a listener was found and removed.
         """
-        self._messaging.on(event_type, callback)
+        return self._messaging.off(event_type, callback)
 
     def to(self, target_twin_id: str) -> TargetedEmitter:
         """Target a specific twin for messaging.