From 7834d751d00a25d998716e8bd3b5c60c4e51ef51 Mon Sep 17 00:00:00 2001
From: iomgaa <iomgaaycz@gmail.com>
Date: Mon, 24 Aug 2026 11:06:22 -0400
Subject: [PATCH] feat: export TelemetryStatus from the package root

client.telemetry_status exists so downstream can reconcile telemetry
programmatically, but annotating its return type meant reaching into
polygateway.types while the convention here is that the top-level
exports are the public API surface. The port itself stays unexported:
nobody outside the library implements it.
---
 src/polygateway/__init__.py |  2 ++
 tests/unit/test_package.py  | 12 ++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/src/polygateway/__init__.py b/src/polygateway/__init__.py
index 1a53c4e..2acadf4 100644
--- a/src/polygateway/__init__.py
+++ b/src/polygateway/__init__.py
@@ -31,6 +31,7 @@ from polygateway.types import (
     OcrLayoutResult,
     OcrTextResult,
     SourceConfig,
+    TelemetryStatus,
 )
 
 __version__ = "1.2.4"
@@ -61,6 +62,7 @@ __all__ = [
     "SourceConfig",
     "SourceDeadError",
     "SourceNotConfiguredError",
+    "TelemetryStatus",
     "TransientError",
     "__version__",
     "gather_bounded",
diff --git a/tests/unit/test_package.py b/tests/unit/test_package.py
index fd33bcf..9df149f 100644
--- a/tests/unit/test_package.py
+++ b/tests/unit/test_package.py
@@ -37,3 +37,15 @@ def test_telemetry_schema_sql_exported():
     assert callable(polygateway.telemetry_schema_sql)
     assert "missing_columns_warning" not in polygateway.__all__
     assert not hasattr(polygateway, "missing_columns_warning")
+
+
+def test_telemetry_status_exported():
+    """issue #15: `client.telemetry_status` 的返回类型必须能从顶层 import。
+
+    下游对账/告警要给这个快照做类型标注,若只在 `polygateway.types` 里,标注就得
+    深入子模块,而本库的约定是「顶层导出即公共 API 面」。`TelemetryStatusProvider`
+    则**不**导出: 它是端口,库外无实现者,导出即多一份永久承诺。
+    """
+    assert "TelemetryStatus" in polygateway.__all__
+    assert polygateway.TelemetryStatus is not None
+    assert "TelemetryStatusProvider" not in polygateway.__all__