feat(reporting): mirror the TypeScript SDK's advanced path, engine errors and readback name

packages/adcp-reporting-storage/src/adcp_reporting_storage/storage.py

@@ -88,6 +88,7 @@ async def check_schema() -> None:
                 f"the reporting schema is behind this SDK (pending: {versions}). "
                 f'Run "{MIGRATE_COMMAND}" against this database{note}.',
                 code="REPORTING_SCHEMA_BEHIND",
+                config_field="python -m adcp migrate",
             )
         await staging.check_ready()
 

src/adcp/reporting/__init__.py

@@ -70,6 +70,7 @@
 )
 
 if TYPE_CHECKING:
+    from adcp.reporting import advanced as advanced
     from adcp.reporting import canonical_json as canonical_json
     from adcp.reporting import conformance as conformance
     from adcp.reporting import currency as currency
@@ -118,9 +119,6 @@
     from adcp.reporting.service_production import (
         ReportingServiceOffering as ReportingServiceOffering,
     )
-    from adcp.reporting.service_subscriptions import (
-        ReportingSubscriptionServiceOptions as ReportingSubscriptionServiceOptions,
-    )
     from adcp.reporting.service_subscriptions import (
         SubscriptionOptions as SubscriptionOptions,
     )
@@ -157,6 +155,7 @@
 
 _LAZY_SUBMODULES = frozenset(
     {
+        "advanced",
         "canonical_json",
         "conformance",
         "currency",
@@ -189,10 +188,6 @@
     "ReportingAdapter": ("service", "ReportingAdapter"),
     "ReportingProductionOptions": ("service_production", "ReportingProductionOptions"),
     "ReportingServiceOffering": ("service_production", "ReportingServiceOffering"),
-    "ReportingSubscriptionServiceOptions": (
-        "service_subscriptions",
-        "ReportingSubscriptionServiceOptions",
-    ),
     "SubscriptionOptions": ("service_subscriptions", "SubscriptionOptions"),
     "DeterministicReportingClock": ("testing", "DeterministicReportingClock"),
     "FaultInjectingReportingSealStore": ("testing", "FaultInjectingReportingSealStore"),
@@ -250,7 +245,6 @@ def __dir__() -> list[str]:
     "ReportingProductionOptions",
     "ReportingServiceOffering",
     "PrincipalRef",
-    "ReportingSubscriptionServiceOptions",
     "SubscriptionOptions",
     "DeterministicReportingClock",
     "FaultInjectingReportingSealStore",

src/adcp/reporting/_errors.py

@@ -81,8 +81,9 @@ class ReliableReportingConfigurationError(ValueError):
     vocabulary (``REPORTING_STORAGE_NOT_DURABLE``, ``REPORTING_SCHEMA_BEHIND``,
     ``SUBSCRIPTIONS_REQUIRE_STANDARD_DIMENSIONS``,
     ``SUBSCRIPTION_ROSTER_UNAVAILABLE``); those carry ``recovery="correctable"``
-    and a message whose last sentence is the fix. ``dispatched`` is always
-    ``None``: a configuration check sends nothing.
+    and a message whose last sentence is the fix; ``config_field`` names the
+    configuration key to change. ``dispatched`` is always ``None``: a
+    configuration check sends nothing.
     """
 
     dispatched = None
@@ -93,12 +94,15 @@ def __init__(
         *,
         kind: Literal["misconfiguration", "auth_required", "invalid_request"] = "misconfiguration",
         code: str | None = None,
+        config_field: str | None = None,
     ) -> None:
         super().__init__(message)
         if code is not None and code not in SELLER_CONFIGURATION_CODES:
             raise ValueError(f"unknown seller configuration code {code!r}")
         self.kind = kind
         self.code = code
+        #: The configuration key to change (the TypeScript SDK's ``configField``).
+        self.config_field = config_field
         self.recovery: Literal["correctable", "terminal"] | None = (
             "correctable" if code is not None else None
         )

src/adcp/reporting/advanced.py

@@ -0,0 +1,168 @@
+"""Reporting-subscription building blocks for hand-wired compositions (experimental).
+
+Rung 3 of the reporting-subscriptions design: most sellers enable subscriptions
+with ``ReliableReportingService(subscriptions=SubscriptionOptions(...))`` and
+never touch these. Use them to bring your own ledger, build the engine and link
+the principal runtime yourself
+(``ReliableReportingService(reporting_subscriptions=ReportingSubscriptionServiceOptions(...))``),
+or compute coverage directly. The TypeScript SDK publishes the same building
+blocks from ``@adcp/sdk/reporting/advanced``.
+
+Everything here is experimental and may change between betas. The names are
+defined in :mod:`adcp.reporting.subscriptions` and
+:mod:`adcp.reporting.service_subscriptions`, which keep exporting them.
+"""
+
+from __future__ import annotations
+
+from adcp.reporting.service_subscriptions import (
+    ManagedGenerationBinder,
+    PlanningErrorHandler,
+    PrincipalLister,
+    PrincipalResolver,
+    ProductionSubscriptionHooks,
+    ReportingSubscriptionServiceOptions,
+    SubscriptionPlanningFailure,
+)
+from adcp.reporting.subscriptions._clock import COVERAGE_INPUT_DETAILS, CoverageInputError
+from adcp.reporting.subscriptions.capabilities import (
+    ReportingSubscriptionSupport,
+    advertise_reporting_subscriptions,
+    reporting_configuration_tasks,
+    subscription_capabilities,
+    with_subscription_dimensions,
+)
+from adcp.reporting.subscriptions.coverage import (
+    DEFAULT_MAX_ITERATIONS,
+    DEFAULT_MAX_PERIODS,
+    AccountTimezoneChange,
+    ExpectedSubscriptionPeriod,
+    OwedSubscriptionPeriod,
+    SubscriptionAuthorization,
+    SubscriptionBuy,
+    SubscriptionBuyFlight,
+    SubscriptionBuyPackage,
+    SubscriptionException,
+    SubscriptionVersionWindow,
+    authorization_chain_start,
+    expected_subscription_periods,
+    owed_subscription_periods,
+    subscription_covers_account,
+    subscription_exceptions,
+    subscription_version_windows,
+)
+from adcp.reporting.subscriptions.engine import (
+    ENGINE_ERROR_CODES,
+    AccountConfigsEnder,
+    AccountDeliveryConfig,
+    AuthorizedAccount,
+    AuthorizedAccountPage,
+    GrantObservation,
+    InMemoryReportingSubscriptionStore,
+    ReportingSubscriptionDeliveryHost,
+    ReportingSubscriptionEngine,
+    ReportingSubscriptionEngineError,
+    ReportingSubscriptionHost,
+    ReportingSubscriptionPrecedenceHost,
+    ReportingSubscriptionStateConflictError,
+    ReportingSubscriptionStateCorruptError,
+    ReportingSubscriptionStateStore,
+    StoredReportingSubscriptionState,
+    decode_principal_state,
+    encode_principal_state,
+)
+from adcp.reporting.subscriptions.ledger import (
+    FrozenOwedSet,
+    SubscriptionObligationPlanner,
+    SubscriptionPlanResult,
+    subscription_obligation_id,
+)
+from adcp.reporting.subscriptions.registry import (
+    ReportingSubscriptionValidationError,
+    apply_reporting_subscriptions,
+    refresh_destination_states,
+    render_path_template,
+)
+from adcp.reporting.subscriptions.resolution import (
+    STANDARD_REPORTING_DIMENSIONS,
+    SubscriptionDestination,
+    SubscriptionMatch,
+    SubscriptionOffering,
+    SubscriptionResolution,
+    SubscriptionSelector,
+    resolve_subscription_offerings,
+)
+
+__all__ = [
+    # Engine
+    "ENGINE_ERROR_CODES",
+    "AccountConfigsEnder",
+    "AccountDeliveryConfig",
+    "AuthorizedAccount",
+    "AuthorizedAccountPage",
+    "FrozenOwedSet",
+    "GrantObservation",
+    "ReportingSubscriptionDeliveryHost",
+    "ReportingSubscriptionEngine",
+    "ReportingSubscriptionEngineError",
+    "ReportingSubscriptionHost",
+    "ReportingSubscriptionPrecedenceHost",
+    "ReportingSubscriptionStateConflictError",
+    "ReportingSubscriptionStateCorruptError",
+    # Engine stores
+    "InMemoryReportingSubscriptionStore",
+    "ReportingSubscriptionStateStore",
+    "StoredReportingSubscriptionState",
+    "decode_principal_state",
+    "encode_principal_state",
+    # Coverage function
+    "DEFAULT_MAX_ITERATIONS",
+    "DEFAULT_MAX_PERIODS",
+    "AccountTimezoneChange",
+    "ExpectedSubscriptionPeriod",
+    "OwedSubscriptionPeriod",
+    "SubscriptionAuthorization",
+    "SubscriptionBuy",
+    "SubscriptionBuyFlight",
+    "SubscriptionBuyPackage",
+    "SubscriptionException",
+    "SubscriptionVersionWindow",
+    "authorization_chain_start",
+    "expected_subscription_periods",
+    "owed_subscription_periods",
+    "subscription_covers_account",
+    "subscription_exceptions",
+    "subscription_version_windows",
+    # Calendar and selection
+    "COVERAGE_INPUT_DETAILS",
+    "CoverageInputError",
+    "STANDARD_REPORTING_DIMENSIONS",
+    "SubscriptionDestination",
+    "SubscriptionMatch",
+    "SubscriptionOffering",
+    "SubscriptionResolution",
+    "SubscriptionSelector",
+    "resolve_subscription_offerings",
+    # Capability builder
+    "ReportingSubscriptionSupport",
+    "advertise_reporting_subscriptions",
+    "reporting_configuration_tasks",
+    "subscription_capabilities",
+    "with_subscription_dimensions",
+    # Principal section validation
+    "ReportingSubscriptionValidationError",
+    "apply_reporting_subscriptions",
+    "refresh_destination_states",
+    "render_path_template",
+    # Service planner hooks
+    "ManagedGenerationBinder",
+    "PlanningErrorHandler",
+    "PrincipalLister",
+    "PrincipalResolver",
+    "ProductionSubscriptionHooks",
+    "ReportingSubscriptionServiceOptions",
+    "SubscriptionObligationPlanner",
+    "SubscriptionPlanResult",
+    "SubscriptionPlanningFailure",
+    "subscription_obligation_id",
+]