phystack-hub-client 0.2.4__tar.gz → 6.18.1__tar.gz

phystack_hub_client-6.18.1/CHANGELOG.md

@@ -0,0 +1,65 @@
+# 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.18.0 — parity with npm 6.16.0 (TECH-1521)
+
+### Changed
+
+- Removed the hardcoded Google STUN fallback (npm 6.16.0, ps-platform #973,
+  TECH-1516/TECH-1521). `MediaStreamOptions.stun_servers` and
+  `DataChannelOptions.stun_servers` now default to the `PHYSTACK_STUN_URL` env
+  var when set, otherwise an empty list — with no `ice_servers_provider`
+  resolving, connections degrade to host candidates only instead of contacting
+  `stun.l.google.com`. All STUN normally comes from the phyhub-minted ICE list
+  (`stun:turn-<region>.phystack.com:3478`).
+- Every configuration builder now returns an explicit `RTCConfiguration`
+  (possibly with an empty server list) instead of `None`: aiortc substitutes
+  its own default — Google STUN — when a peer connection is created without a
+  configuration, which would have silently reintroduced the third-party STUN.
+- Guard tests: defaults carry no third-party STUN, and a source scan fails the
+  suite if a Google STUN host/port literal ever reappears in the package.
+
+## 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-0.2.4 → phystack_hub_client-6.18.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: phystack-hub-client
-Version: 0.2.4
+Version: 6.18.1
 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
@@ -15,11 +15,12 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
-Requires-Dist: aiohttp>=3.9.0
-Requires-Dist: aiortc>=1.6.0
-Requires-Dist: numpy>=1.24.0
-Requires-Dist: opencv-python>=4.8.0
-Requires-Dist: python-socketio[asyncio-client]>=5.10.0
+Requires-Dist: aiohttp<4.0.0,>=3.9.0
+Requires-Dist: aiortc<2.0.0,>=1.6.0
+Requires-Dist: numpy<3.0.0,>=1.24.0
+Requires-Dist: opencv-python<5.0.0,>=4.8.0
+Requires-Dist: python-engineio<4.12.0,>=4.9.0
+Requires-Dist: python-socketio[asyncio-client]<5.12.0,>=5.11.0
 Provides-Extra: dev
 Requires-Dist: black>=23.0.0; extra == 'dev'
 Requires-Dist: mypy>=1.5.0; extra == 'dev'
@@ -102,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-0.2.4 → phystack_hub_client-6.18.1}/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-0.2.4 → phystack_hub_client-6.18.1}/pyproject.toml

@@ -4,7 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "phystack-hub-client"
-version = "0.2.4"
+# 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.18.1"
 description = "Python client for PhyHub - events, actions, DataChannel, and MediaStream"
 readme = "README.md"
 license = "MIT"
@@ -22,11 +25,22 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
 ]
 dependencies = [
-    "python-socketio[asyncio_client]>=5.10.0",
-    "aiohttp>=3.9.0",
-    "aiortc>=1.6.0",
-    "opencv-python>=4.8.0",
-    "numpy>=1.24.0",
+    # Pinned to narrow ranges tested against the PhyOS hub socket.io server
+    # (socket.io 4.8.1 / engine.io 6.6.4). python-engineio 4.12+ has a bug
+    # in the WebSocket upgrade error path: _connect_websocket can pass a
+    # WebSocketError object into the packet decoder, causing
+    # "TypeError: object of type 'WebSocketError' has no len()".
+    "python-socketio[asyncio_client]>=5.11.0,<5.12.0",
+    "python-engineio>=4.9.0,<4.12.0",
+    # aiohttp 4.x is an announced future breaking release; cap below it.
+    "aiohttp>=3.9.0,<4.0.0",
+    # aiortc has had minor-version API breaks; cap at next major.
+    "aiortc>=1.6.0,<2.0.0",
+    # opencv-python 5.x is not released yet; cap at next major.
+    "opencv-python>=4.8.0,<5.0.0",
+    # numpy 2.0 was a large ABI change. Allow 2.x but cap before the next
+    # unreleased major to avoid surprise breaks.
+    "numpy>=1.24.0,<3.0.0",
 ]
 
 [project.optional-dependencies]

{phystack_hub_client-0.2.4 → phystack_hub_client-6.18.1}/src/phystack/hub_client/__init__.py

@@ -10,6 +10,12 @@ A Python client for PhyHub that provides:
 - Settings API
 
 Usage:
+    from phystack.hub_client import connect_phy_client
+
+    client = await connect_phy_client()
+    instance = await client.get_instance()
+
+Or with context manager:
     from phystack.hub_client import PhyHubClient
 
     async with PhyHubClient.from_env() as client:
@@ -38,14 +44,22 @@ Usage:
         stream = await instance.get_media_stream(peer_twin_id)
 """
 
-from phystack.hub_client.client import PhyHubClient
+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,
@@ -60,9 +74,49 @@ from phystack.hub_client.services.webrtc.data_channel import (
 from phystack.hub_client.services.webrtc.media_stream import (
     MediaStreamHandler,
     MediaStreamOptions,
+    MediaTrackKind,
+    MissingMediaTrackError,
     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.web_session_code import (
+    WebSessionCode,
+    WebSessionCodeConfigError,
+    WebSessionCodeIssuer,
+    WebSessionCodeListener,
+    WebSessionCodeState,
+)
 from phystack.hub_client.services.signals import (
     SignalsService,
     InitSignalPayload,
@@ -74,10 +128,13 @@ 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.16.0"
 __all__ = [
     # Client
     "PhyHubClient",
+    "connect_phy_client",
     # Instances
     "BaseInstance",
     "EdgeInstance",
@@ -89,14 +146,50 @@ __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",
+    "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",
+    # Web-session claim codes (device-side QR issuer)
+    "WebSessionCode",
+    "WebSessionCodeConfigError",
+    "WebSessionCodeIssuer",
+    "WebSessionCodeListener",
+    "WebSessionCodeState",
     # Signals
     "SignalsService",
     "InitSignalPayload",

phystack_hub_client-6.18.1/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