from pydantic import BaseModel, Field


class EventSpec(BaseModel):
    """
    Declarative documentation for an event a plugin emits.

    Plugins list their emitted events via the ``emits`` field on
    :class:`~fastpluggy.core.module_base.FastPluggyBaseModule`::

        class MyPlugin(FastPluggyBaseModule):
            emits = [
                EventSpec(
                    name="my_plugin.thing_happened",
                    description="Fired whenever a thing happens.",
                    payload={"thing_id": "int", "label": "str"},
                ),
            ]

    These declarations appear in the admin **Events** page as a browsable
    catalog so other plugin authors can discover what to subscribe to.
    """

    name: str
    """Topic string, e.g. ``"user.login"``."""

    description: str = ""
    """Human-readable explanation of when this event fires."""

    payload: dict[str, str] = Field(default_factory=dict)
    """Mapping of payload field name → type hint string, e.g. ``{"user_id": "int"}``."""
