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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: phystack-hub-client
-Version: 0.2.7
+Version: 6.8.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.8.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.8.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.8.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,9 +74,42 @@ 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.signals import (
     SignalsService,
     InitSignalPayload,
@@ -80,7 +121,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.8.0"
 __all__ = [
     # Client
     "PhyHubClient",
@@ -96,14 +139,44 @@ __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",
     # Signals
     "SignalsService",
     "InitSignalPayload",

phystack_hub_client-6.8.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