"""
Helpers for building and writing Sensorium receipts.
"""
from __future__ import annotations

from datetime import datetime, timezone
from typing import Any, Dict, List, Optional

from receipts.domains.sensorium import SensoriumReceipt


def build_sensorium_receipt(
    *,
    frame_id: str,
    frame_hash: str,
    width: int,
    height: int,
    app_bundle_id: Optional[str] = None,
    window_title: Optional[str] = None,
    ax_elements: Optional[List[Dict[str, Any]]] = None,
    vlm_detections: Optional[List[Dict[str, Any]]] = None,
    voice_intent: Optional[Dict[str, Any]] = None,
    stale_perception: bool = False,
    stale_reason: Optional[str] = None,
    frame_path: Optional[str] = None,
    parent_ids: Optional[List[str]] = None,
    receipt_id: Optional[str] = None,
) -> SensoriumReceipt:
    """
    Build a SensoriumReceipt from basic perception fields.
    """
    rid = receipt_id or f"sensorium_{frame_id}"
    ts = datetime.now(timezone.utc)
    return SensoriumReceipt(
        receipt_id=rid,
        ts=ts,
        frame_id=frame_id,
        frame_hash=frame_hash,
        frame_path=frame_path,
        width=width,
        height=height,
        app_bundle_id=app_bundle_id,
        window_title=window_title,
        stale_perception=stale_perception,
        stale_reason=stale_reason,
        ax_elements=ax_elements or [],
        vlm_detections=vlm_detections or [],
        voice_intent=voice_intent,
        parent_ids=parent_ids or [],
    )
