"""Synthetic teaching example. No network calls or real customer data.

This file demonstrates the resource-access decision inside one read-only tool.
It is not an authentication service, webhook handler or complete agent.

Run: python3 order_status_example.py
"""

from dataclasses import dataclass
from typing import Mapping


@dataclass(frozen=True)
class Principal:
    # Created only by the application's validated session adapter.
    # Never construct this object from a chat message or tool arguments.
    customer_id: str


@dataclass(frozen=True)
class Order:
    owner_id: str
    state: str
    estimated_delivery: str | None


def get_order_status(
    *,
    principal: Principal | None,
    order_reference: str,
    orders: Mapping[str, Order],
) -> dict:
    """Return only data that this authenticated customer may read."""
    if principal is None:
        return {"status": "verification_required"}

    order = orders.get(order_reference)
    if order is None or order.owner_id != principal.customer_id:
        # Use the same customer-visible outcome for absent and foreign orders.
        return {"status": "not_available"}

    return {
        "status": "ok",
        "order": {
            "reference": order_reference,
            "state": order.state,
            "estimated_delivery": order.estimated_delivery,
        },
    }


def verify_example() -> None:
    orders = {
        "ORD-204": Order("CUSTOMER-A", "dispatched", "2026-11-09"),
        "ORD-205": Order("CUSTOMER-B", "processing", None),
    }
    customer_a = Principal("CUSTOMER-A")
    customer_b = Principal("CUSTOMER-B")

    assert get_order_status(
        principal=None, order_reference="ORD-204", orders=orders
    ) == {"status": "verification_required"}

    allowed = get_order_status(
        principal=customer_a, order_reference="ORD-204", orders=orders
    )
    assert allowed == {
        "status": "ok",
        "order": {
            "reference": "ORD-204",
            "state": "dispatched",
            "estimated_delivery": "2026-11-09",
        },
    }
    assert "owner_id" not in allowed["order"]

    foreign = get_order_status(
        principal=customer_a, order_reference="ORD-205", orders=orders
    )
    absent = get_order_status(
        principal=customer_a, order_reference="DOES-NOT-EXIST", orders=orders
    )
    assert foreign == absent == {"status": "not_available"}

    no_date = get_order_status(
        principal=customer_b, order_reference="ORD-205", orders=orders
    )
    assert no_date["order"]["estimated_delivery"] is None

    try:
        # A model must not be able to add an owner override to the tool.
        get_order_status(
            principal=customer_a,
            order_reference="ORD-205",
            orders=orders,
            customer_id="CUSTOMER-B",
        )
    except TypeError:
        pass
    else:
        raise AssertionError("Unexpected customer override accepted")


if __name__ == "__main__":
    verify_example()
    print("Passed: anonymous access, own order, foreign order, missing order,")
    print("minimal output, unknown delivery date and rejected owner override.")