phystack-hub-client 0.2.1__tar.gz → 0.2.3__tar.gz

{phystack_hub_client-0.2.1 → phystack_hub_client-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phystack-hub-client
-Version: 0.2.1
+Version: 0.2.3
 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.1 → phystack_hub_client-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "phystack-hub-client"
-version = "0.2.1"
+version = "0.2.3"
 description = "Python client for PhyHub - events, actions, DataChannel, and MediaStream"
 readme = "README.md"
 license = "MIT"

{phystack_hub_client-0.2.1 → phystack_hub_client-0.2.3}/src/phystack/hub_client/__init__.py

@@ -7,7 +7,7 @@ A Python client for PhyHub that provides:
 - WebRTC MediaStream for P2P video/audio
 - Twin instance management (Edge, Peripheral, etc.)
 - Properties API (reported/desired)
-- Settings API with subscriptions
+- Settings API
 
 Usage:
     from phystack.hub_client import PhyHubClient
@@ -27,8 +27,8 @@ Usage:
         instance.on_update_desired(lambda props: print("Desired changed:", props))
 
         # Settings (for edge apps)
-        settings = client.get_settings()
-        client.on_settings_update(lambda s: print("Settings updated:", s))
+        settings = await client.get_settings()
+        instance.on_update_desired(lambda props: print("Desired changed:", props))
 
         # DataChannel
         dc = await instance.get_data_channel(peer_twin_id)
@@ -63,6 +63,16 @@ from phystack.hub_client.services.webrtc.media_stream import (
     PhygridMediaStream,
     WebcamVideoTrack,
 )
+from phystack.hub_client.services.signals import (
+    SignalsService,
+    InitSignalPayload,
+    DataRequestTypeEnum,
+    DataResidencyEnum,
+    EventTypeEnum,
+    CheckoutProps,
+    CheckoutProduct,
+    PurchaseProps,
+)
 
 __version__ = "0.1.0"
 __all__ = [
@@ -87,4 +97,13 @@ __all__ = [
     "MediaStreamOptions",
     "PhygridMediaStream",
     "WebcamVideoTrack",
+    # Signals
+    "SignalsService",
+    "InitSignalPayload",
+    "DataRequestTypeEnum",
+    "DataResidencyEnum",
+    "EventTypeEnum",
+    "CheckoutProps",
+    "CheckoutProduct",
+    "PurchaseProps",
 ]

{phystack_hub_client-0.2.1 → phystack_hub_client-0.2.3}/src/phystack/hub_client/client.py

@@ -10,8 +10,8 @@ from typing import Any, Callable, Optional, Set
 
 from phystack.hub_client.services.phyhub_connection import (
     PhyHubConnection,
-    DirectConnectionConfig,
-    is_direct_mode,
+    ConnectionConfig,
+    ConnectionMode,
 )
 from phystack.hub_client.twin_messaging import (
     TwinMessaging,
@@ -23,6 +23,7 @@ from phystack.hub_client.types.twin_types import (
     TwinMessageResultStatus,
     TwinResponse,
     TwinProperties,
+    TwinTypeEnum,
     EventPayload,
 )
 from phystack.hub_client.services.webrtc.data_channel import (
@@ -65,7 +66,12 @@ class PhyHubClient:
         TWIN_SUBSCRIBE = "twinSubscribe"
         TWIN_UPDATED = "twinUpdated"
         GET_TWIN_BY_ID = "getTwinById"
-        REPORT_PROPERTIES = "reportPeripheralTwinProperties"
+        REPORT_SCREEN_PROPERTIES = "reportScreenTwinProperties"
+        REPORT_EDGE_PROPERTIES = "reportEdgeTwinProperties"
+        REPORT_PERIPHERAL_PROPERTIES = "reportPeripheralTwinProperties"
+        GET_DEVICE_STATUS = "getDeviceStatus"
+        GET_DEVICE_INSTANCE = "getDeviceInstance"
+        GET_DEVICE_NETWORKS = "getDeviceNetworks"
 
     def __init__(
         self,
@@ -88,17 +94,17 @@ class PhyHubClient:
         self._subscribed_twins: Set[str] = set()
         self._twin_message_listeners: dict[str, Set[Callable[[dict[str, Any]], None]]] = {}
         self._twin_update_listeners: dict[str, Set[Callable[[dict[str, Any]], None]]] = {}
-        self._settings_update_listeners: Set[Callable[[dict[str, Any]], None]] = set()
         self._twin_data_cache: dict[str, dict[str, Any]] = {}
         self._connected = False
         self._registry: Optional[TwinRegistry] = None
 
         if device_id and access_key:
             self._connection = PhyHubConnection(
-                DirectConnectionConfig(
+                ConnectionConfig(
+                    mode=ConnectionMode.DIRECT,
+                    url=phyhub_url or "https://phyhub.eu.omborigrid.net",
                     device_id=device_id,
                     access_key=access_key,
-                    phyhub_url=phyhub_url or "https://phyhub.eu.omborigrid.net",
                     instance_id=instance_id,
                 )
             )
@@ -147,8 +153,12 @@ class PhyHubClient:
         # Set up event handlers
         self._setup_socket_listeners()
 
-        # Authenticate and connect device
-        await self._initialize_device_twin()
+        # Only direct mode needs explicit authenticate/connectDevice handshake.
+        # PhyOS and Simulator handle auth at Socket.IO connection time.
+        if self._connection.is_direct:
+            await self._initialize_device_twin()
+        else:
+            print(f"[PhyHubClient] Connected ({self._connection.config.mode.value} mode)")
 
         return self
 
@@ -216,18 +226,6 @@ class PhyHubClient:
                     except Exception as e:
                         print(f"[PhyHubClient] Error in twin update listener: {e}")
 
-            # Check for settings updates on edge instance
-            if twin_id == self._instance_id and isinstance(twin_data, dict):
-                props = twin_data.get("properties", {})
-                desired = props.get("desired", {})
-                settings = desired.get("settings", {})
-                if settings and self._settings_update_listeners:
-                    for callback in self._settings_update_listeners:
-                        try:
-                            callback(settings)
-                        except Exception as e:
-                            print(f"[PhyHubClient] Error in settings update listener: {e}")
-
         self._connection.on(self.EVENTS.TWIN_UPDATED, on_twin_updated)
 
     async def _initialize_device_twin(self) -> None:
@@ -322,22 +320,34 @@ class PhyHubClient:
         # Fire and forget - use asyncio to schedule
         asyncio.create_task(self._emit_to_socket(self.EVENTS.TWIN_MESSAGE, event_payload))
 
-    async def _emit_to_socket(self, method: str, payload: dict[str, Any]) -> None:
-        """Emit to socket with proper mode handling.
+    async def _emit_to_socket(
+        self, method: str, payload: dict[str, Any], callback: bool = False
+    ) -> Any:
+        """Unified emit — routes through instance ID channel or direct, based on mode.
 
         In direct mode: socket.emit(method, payload)
-        In PhyOS mode: socket.emit(instanceId, { method, ...payload })
+        In PhyOS/Simulator mode: socket.emit(instanceId, { method, ...payload })
+
+        Args:
+            method: Event/method name.
+            payload: Data to send.
+            callback: If True, wait for ack response (for RPC calls).
+
+        Returns:
+            Response from server if callback is True, else None.
         """
         if not self._connection:
-            return
+            return None
 
-        if is_direct_mode():
+        if self._connection.is_direct:
             # Direct mode: emit to event name directly
-            await self._connection.emit(method, payload)
+            return await self._connection.emit(method, payload, callback=callback)
         else:
-            # PhyOS mode: emit to instanceId channel with method in payload
+            # PhyOS/Simulator: wrap in instance ID channel with method field
             phyos_payload = {"method": method, **payload}
-            await self._connection.emit(self._instance_id or "", phyos_payload)
+            return await self._connection.emit(
+                self._instance_id or "", phyos_payload, callback=callback
+            )
 
     def on_twin_message(
         self,
@@ -418,10 +428,7 @@ class PhyHubClient:
         Returns:
             Twin data dictionary.
         """
-        if not self._connection:
-            return None
-
-        result = await self._connection.emit(
+        result = await self._emit_to_socket(
             self.EVENTS.GET_TWIN_BY_ID,
             {"data": {"twinId": twin_id}},
             callback=True,
@@ -444,43 +451,7 @@ class PhyHubClient:
             return instance.get_settings()
         return {}
 
-    async def get_edge_settings(self) -> dict[str, Any]:
-        """Alias for get_settings().
 
-        Returns:
-            Settings dictionary.
-        """
-        return await self.get_settings()
-
-    def on_settings_update(
-        self, callback: Callable[[dict[str, Any]], None]
-    ) -> None:
-        """Subscribe to settings changes in edge desired properties.
-
-        Args:
-            callback: Handler called with new settings when they change.
-        """
-        self._settings_update_listeners.add(callback)
-
-        # Subscribe to edge twin updates if connected
-        if self._instance_id:
-            asyncio.create_task(self.subscribe_twin(self._instance_id))
-
-    def off_settings_update(
-        self, callback: Callable[[dict[str, Any]], None]
-    ) -> bool:
-        """Remove settings update callback.
-
-        Args:
-            callback: Callback to remove.
-
-        Returns:
-            True if removed, False otherwise.
-        """
-        if callback in self._settings_update_listeners:
-            self._settings_update_listeners.discard(callback)
-            return True
-        return False
 
     # =========================================================================
     # Twin Update API
@@ -535,26 +506,153 @@ class PhyHubClient:
     # =========================================================================
 
     async def update_reported_properties(
-        self, twin_id: str, properties: dict[str, Any]
+        self,
+        twin_id: str,
+        properties: dict[str, Any],
+        twin_type: Optional[TwinTypeEnum] = None,
     ) -> Optional[dict[str, Any]]:
         """Update reported properties for a twin.
 
         Args:
             twin_id: Twin ID to update.
             properties: Properties to set.
+            twin_type: Twin type to determine correct event. Defaults to Peripheral.
 
         Returns:
             Updated twin data.
         """
-        if not self._connection:
-            return None
+        # Dispatch to correct event based on twin type (matches Node.js behavior)
+        if twin_type == TwinTypeEnum.Screen:
+            event = self.EVENTS.REPORT_SCREEN_PROPERTIES
+        elif twin_type == TwinTypeEnum.Edge:
+            event = self.EVENTS.REPORT_EDGE_PROPERTIES
+        else:
+            event = self.EVENTS.REPORT_PERIPHERAL_PROPERTIES
 
         payload = {"twinId": twin_id, "data": properties}
-        result = await self._connection.emit(
-            self.EVENTS.REPORT_PROPERTIES, payload, callback=True
-        )
+        result = await self._emit_to_socket(event, payload, callback=True)
         return result.get("twin") if result else None
 
+    # =========================================================================
+    # Signals / Analytics API
+    # =========================================================================
+
+    async def initialize_signals(
+        self, params: Optional["InitSignalPayload"] = None
+    ) -> "SignalsService":
+        """Initialize the signals/analytics service.
+
+        When called without params, auto-populates from device status and
+        instance twin data (matches Node.js hub-client behavior).
+
+        Args:
+            params: Optional signal initialization parameters. If None,
+                    auto-populates from device status and edge instance.
+
+        Returns:
+            Initialized SignalsService instance.
+        """
+        from phystack.hub_client.services.signals import SignalsService, InitSignalPayload
+
+        # Auto-populate from device status + instance (matches Node.js)
+        device_status: dict[str, Any] = {}
+        instance_data: dict[str, Any] = {}
+
+        if not params:
+            device_status = await self.get_device_status() or {}
+            edge_instance = await self.get_instance()
+            if edge_instance:
+                instance_data = edge_instance._twin_data or {}
+
+        p = params or InitSignalPayload()
+
+        payload = InitSignalPayload(
+            tenant_id=p.tenant_id or device_status.get("tenantId", ""),
+            space_id=p.space_id or device_status.get("spaceId", ""),
+            device_id=p.device_id or instance_data.get("deviceId") or device_status.get("deviceId", ""),
+            installation_id=p.installation_id or (
+                instance_data.get("properties", {}).get("desired", {}).get("installationId", "")
+            ),
+            environment=p.environment or device_status.get("gridEnv", ""),
+            data_residency=p.data_residency or (
+                device_status.get("dataResidency", "")
+            ).upper(),
+            country=p.country or "SE",
+            app_id=p.app_id or "XXXXXXXXXXXXXXXXXXXXXXXX",
+            app_version=p.app_version or "XXXXXXXXXXXXXXXXXXXXXXXX",
+            installation_version=p.installation_version or "XXXXXXXXXXXXXXXXXXXXXXXX",
+            ip=p.ip or (
+                device_status.get("ip", [{}])[0].get("ipv4", "N/A")
+                if isinstance(device_status.get("ip"), list) and device_status.get("ip")
+                else "N/A"
+            ),
+            session_id=p.session_id,
+            client_id=p.client_id,
+            latitude=p.latitude,
+            longitude=p.longitude,
+            location_accuracy=p.location_accuracy,
+            create_new_session_after_last_activity_mins=p.create_new_session_after_last_activity_mins,
+        )
+
+        service = SignalsService(self, payload)
+        await service.initialize()
+        return service
+
+    async def send_signal(
+        self, data_type: "DataRequestTypeEnum", data: dict[str, Any]
+    ) -> Any:
+        """Send a signal to the server.
+
+        Args:
+            data_type: Type of signal (EVENT, SESSION, CLIENT, CHECKOUT, PURCHASE).
+            data: Signal data (already key-shortened).
+        """
+        from phystack.hub_client.services.signals import DataRequestTypeEnum
+
+        event_map = {
+            DataRequestTypeEnum.EVENT: "sendEventSignal",
+            DataRequestTypeEnum.CHECKOUT: "sendEventSignal",
+            DataRequestTypeEnum.PURCHASE: "sendEventSignal",
+            DataRequestTypeEnum.SESSION: "sendSessionSignal",
+            DataRequestTypeEnum.CLIENT: "sendClientSignal",
+        }
+        event = event_map.get(data_type, "sendEventSignal")
+        return await self._emit_to_socket(event, {"data": data})
+
+    # =========================================================================
+    # Device API
+    # =========================================================================
+
+    async def get_device_status(self) -> Optional[dict[str, Any]]:
+        """Get device status (IP, serial, env, etc.).
+
+        Returns:
+            Device status dictionary.
+        """
+        return await self._emit_to_socket(
+            self.EVENTS.GET_DEVICE_STATUS, {}, callback=True
+        )
+
+    async def get_device_instance(self) -> Optional[dict[str, Any]]:
+        """Get device instance data.
+
+        Returns:
+            Device instance dictionary.
+        """
+        return await self._emit_to_socket(
+            self.EVENTS.GET_DEVICE_INSTANCE, {}, callback=True
+        )
+
+    async def get_device_networks(self) -> Optional[dict[str, Any]]:
+        """Get available networks on the device.
+
+        Returns:
+            Device networks dictionary.
+        """
+        return await self._emit_to_socket(
+            self.EVENTS.GET_DEVICE_NETWORKS, {}, callback=True
+        )
+
     # =========================================================================
     # WebRTC Helpers
     # =========================================================================

{phystack_hub_client-0.2.1 → phystack_hub_client-0.2.3}/src/phystack/hub_client/instances/base_instance.py

@@ -148,20 +148,24 @@ class BaseInstance:
 
     async def on_data_channel(
         self,
-        target_twin_id: str,
         callback: Callable[["PhygridDataChannel"], None],
         channel_name: str = "default",
     ) -> None:
-        """Listen for incoming DataChannel from a twin.
+        """Listen for incoming DataChannel from any twin.
+
+        Accepts the first incoming connection and locks to that source
+        (matches Node.js hub-client behavior).
 
         Args:
-            target_twin_id: ID of the twin to listen from.
             callback: Handler for incoming channel.
             channel_name: Name of the channel to listen for.
         """
+        from phystack.hub_client.services.webrtc.data_channel import DataChannelOptions
+
         channel = await self._client.create_data_channel(
-            target_twin_id=target_twin_id,
+            target_twin_id="",
             is_initiator=False,
+            options=DataChannelOptions(accept_from_any_source=True),
             channel_name=channel_name,
             blocking=False,
         )
@@ -201,20 +205,24 @@ class BaseInstance:
 
     async def on_media_stream(
         self,
-        target_twin_id: str,
         callback: Callable[["PhygridMediaStream"], None],
         stream_name: str = "default",
     ) -> None:
-        """Listen for incoming MediaStream from a twin.
+        """Listen for incoming MediaStream from any twin.
+
+        Accepts the first incoming connection and locks to that source
+        (matches Node.js hub-client behavior).
 
         Args:
-            target_twin_id: ID of the twin to listen from.
             callback: Handler for incoming stream.
             stream_name: Name of the stream to listen for.
         """
+        from phystack.hub_client.services.webrtc.media_stream import MediaStreamOptions
+
         stream = await self._client.create_media_stream(
-            target_twin_id=target_twin_id,
+            target_twin_id="",
             is_initiator=False,
+            options=MediaStreamOptions(accept_from_any_source=True),
             stream_name=stream_name,
             blocking=False,
         )

{phystack_hub_client-0.2.1 → phystack_hub_client-0.2.3}/src/phystack/hub_client/instances/edge_instance.py

@@ -55,7 +55,11 @@ class EdgeInstance(BaseInstance):
         Returns:
             Updated twin data.
         """
-        result = await self._client.update_reported_properties(self.id, properties)
+        from phystack.hub_client.types.twin_types import TwinTypeEnum
+
+        result = await self._client.update_reported_properties(
+            self.id, properties, twin_type=TwinTypeEnum.Edge
+        )
         if result:
             self._update_twin_data(result)
         return result or {}
@@ -182,7 +186,7 @@ class EdgeInstance(BaseInstance):
             }
         }
 
-        result = await self._client._connection.emit(
+        result = await self._client._emit_to_socket(
             "createPeripheralTwin", payload, callback=True
         )
         return result.get("twin", {}) if result else {}
@@ -194,7 +198,7 @@ class EdgeInstance(BaseInstance):
             List of peripheral twin data.
         """
         payload = {"data": {"instanceId": self.id}}
-        result = await self._client._connection.emit(
+        result = await self._client._emit_to_socket(
             "getPeripheralTwins", payload, callback=True
         )
         return result.get("twins", []) if result else []

{phystack_hub_client-0.2.1 → phystack_hub_client-0.2.3}/src/phystack/hub_client/instances/peripheral_instance.py

@@ -57,7 +57,11 @@ class PeripheralInstance(BaseInstance):
         Returns:
             Updated twin data.
         """
-        result = await self._client.update_reported_properties(self.id, properties)
+        from phystack.hub_client.types.twin_types import TwinTypeEnum
+
+        result = await self._client.update_reported_properties(
+            self.id, properties, twin_type=TwinTypeEnum.Peripheral
+        )
         if result:
             self._update_twin_data(result)
         return result or {}