Type Hints & Models

# ---- top-level (convert_sdk) -------------------------------------------------
from convert_sdk import (
    Core, Context, __version__,

    # Config
    SDKConfig, TransportConfig, RefreshConfig,

    # Evaluation results
    ExperienceResult,
    FeatureResult, FeatureStatus,
    ConversionResult, ConversionStatus,
    CustomSegmentsResult,

    # Diagnostic surface
    DiagnosticReason,
    ExperienceDiagnostic, FeatureDiagnostic,
    GoalDiagnostic, EntityDiagnostic,

    # Lifecycle events
    LifecycleEvent,

    # Persistence boundary
    DataStore, InMemoryDataStore,

    # Error hierarchy
    ConvertSDKError, ConfigError,
    InvalidConfigError, ConfigLoadError,
    TransportError, TrackingDeliveryError,
)

# ---- submodule paths (stable, not re-exported at top level) ------------------
from convert_sdk.events import ConversionEventPayload, QueueReleasedPayload
from convert_sdk.errors import TrackingError, ConversionDataError
from convert_sdk.ports.transport import Transport
from convert_sdk.ports.event_bus import EventBus, EventHandler
from convert_sdk.ports.storage import DataStore, visitor_state_key
from convert_sdk.domain.context_state import ContextState
from convert_sdk.domain.config_snapshot import ConfigSnapshot

from convert_sdk import ExperienceResult
from typing import Optional, Mapping, Any

result: Optional[ExperienceResult] = context.run_experience("checkout-experiment")
if result is not None:
    print(result.experience_key)   # e.g. "checkout-experiment"
    print(result.variation_id)     # e.g. "10045"
    print(result.variation_key)    # e.g. "variation-1" (or None)
    title = result.variation.get("page_title")  # read-only mapping

from convert_sdk import FeatureResult, FeatureStatus
from typing import Optional

result: Optional[FeatureResult] = context.run_feature("checkout-banner")
if result is not None:
    assert result.status is FeatureStatus.ENABLED
    headline = result.variables.get("headline", "")

from convert_sdk import FeatureStatus

FeatureStatus.ENABLED   # "enabled"
FeatureStatus.DISABLED  # "disabled"

from convert_sdk import ConversionResult, ConversionStatus

result = context.track_conversion("purchase_completed", revenue=49.99)
if result.tracked:
    print("queued", result.goal_id)
elif result.status is ConversionStatus.GOAL_NOT_FOUND:
    print("goal not in config:", result.reason)  # "goal_not_found"
elif result.status is ConversionStatus.DEDUPLICATED:
    print("already tracked:", result.reason)     # "deduplicated"

from convert_sdk import ConversionStatus

ConversionStatus.QUEUED          # "queued"     — event enqueued
ConversionStatus.DEDUPLICATED    # "deduplicated" — duplicate for (visitor, goal)
ConversionStatus.GOAL_NOT_FOUND  # "goal_not_found" — key absent from config

from convert_sdk import CustomSegmentsResult

seg = context.run_custom_segments(["high-value"], rule_data={"orders": 12})
if seg.matched:
    print("matched:", seg.matched_segment_ids)

from convert_sdk import (
    DiagnosticReason,
    ExperienceDiagnostic,
    FeatureDiagnostic,
    GoalDiagnostic,
    EntityDiagnostic,
)

exp_diag: ExperienceDiagnostic = context.diagnose_experience("checkout-experiment")
feat_diag: FeatureDiagnostic   = context.diagnose_feature("checkout-banner")
goal_diag: GoalDiagnostic      = context.diagnose_goal("purchase_completed")
ent_diag:  EntityDiagnostic    = context.diagnose_entity("experiences", "checkout-experiment")

# All share the same field access pattern:
print(exp_diag.reason)             # DiagnosticReason.RESOLVED (or a miss code)
print(exp_diag.resolved)           # bool shortcut
print(dict(exp_diag.details))      # redaction-safe operational fields

from convert_sdk import DiagnosticReason

DiagnosticReason.RESOLVED                           # "resolved"
DiagnosticReason.AUDIENCE_MISMATCH                  # "audience_mismatch"
DiagnosticReason.EXPERIENCE_NOT_FOUND               # "experience_not_found"
DiagnosticReason.FEATURE_NOT_IN_SELECTED_VARIATIONS # "feature_not_in_selected_variations"
DiagnosticReason.FEATURE_NOT_FOUND                  # "feature_not_found"
DiagnosticReason.GOAL_NOT_FOUND                     # "goal_not_found"
DiagnosticReason.ENTITY_NOT_FOUND                   # "entity_not_found"
DiagnosticReason.PROJECT_MAPPING_REQUIRED           # "project_mapping_required"

assert diag.reason is DiagnosticReason.RESOLVED
assert diag.reason == "resolved"   # both work

from convert_sdk import LifecycleEvent

LifecycleEvent.READY                      # "ready"
LifecycleEvent.CONFIG_UPDATED             # "config.updated"
LifecycleEvent.BUCKETING                  # "bucketing"
LifecycleEvent.CONVERSION                 # "conversion"
LifecycleEvent.API_QUEUE_RELEASED         # "api.queue.released"
LifecycleEvent.DATA_STORE_QUEUE_RELEASED  # "datastore.queue.released"
LifecycleEvent.DIAGNOSTIC                 # "diagnostic"

from convert_sdk import LifecycleEvent
from convert_sdk.events import ConversionEventPayload

def on_conversion(payload: ConversionEventPayload, error=None) -> None:
    print(f"goal={payload.goal_key} visitor={payload.visitor_id}")

core.on(LifecycleEvent.CONVERSION, on_conversion)

from convert_sdk import LifecycleEvent
from convert_sdk.events import QueueReleasedPayload

def on_released(payload: QueueReleasedPayload, error=None) -> None:
    if error is not None:
        print(f"delivery failed: status={payload.status_code}")
    else:
        print(f"released {payload.batch_size} events, reason={payload.reason}")

core.on(LifecycleEvent.API_QUEUE_RELEASED, on_released)

from convert_sdk.ports.transport import Transport

class MyTransport:
    def fetch_config(self, config: "SDKConfig") -> dict[str, Any]: ...
    def send_tracking(self, payload: dict[str, Any], *, sdk_key: str) -> None: ...
    def close(self) -> None: ...
    def __enter__(self) -> "Transport": ...
    def __exit__(self, *exc: Any) -> None: ...

from convert_sdk import DataStore  # top-level export

class MyStore:
    def get(self, key: str) -> Any: ...
    def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None: ...
    def has(self, key: str) -> bool: ...
    def delete(self, key: str) -> None: ...

from convert_sdk.ports.event_bus import EventBus, EventHandler

# EventHandler type alias:
# EventHandler = Callable[..., None]
# Invoked as handler(payload, error=None)

class MyEventBus:
    def on(
        self, event: "LifecycleEvent", handler: "EventHandler"
    ) -> None: ...
    def emit(
        self,
        event: "LifecycleEvent",
        payload: Any,
        error: Optional[BaseException] = None,
    ) -> None: ...

from convert_sdk import ConfigLoadError, TrackingDeliveryError

try:
    core = Core(SDKConfig(sdk_key="my-key")).initialize()
except ConfigLoadError as exc:
    print(exc.code)           # "config_load_failed"
    print(exc.endpoint)       # redacted URL — no SDK key in query string
    print(exc.status_code)    # int or None
    print(dict(exc.context))  # structured metadata mapping

# Tracking delivery failure (raised by core.flush() on a POST failure):
from convert_sdk import LifecycleEvent
from convert_sdk.errors import TrackingDeliveryError

try:
    core.flush()
except TrackingDeliveryError as exc:
    print(exc.code)         # "tracking_delivery_failed"
    print(exc.batch_size)   # int or None
    print(exc.retry_count)  # int or None

from convert_sdk.errors import ConversionDataError

try:
    context.track_conversion("purchase", conversion_data={"items": [1, 2, 3]})
except ConversionDataError as exc:
    print(exc.key)     # the offending attribute name
    print(exc.reason)  # short safe reason string