corvix.domain
=============

.. py:module:: corvix.domain

.. autoapi-nested-parse::

   Domain models for GitHub notifications.



Attributes
----------

.. autoapisummary::

   corvix.domain._MIN_API_REPO_SEGMENTS
   corvix.domain._MIN_RESOURCE_SEGMENTS
   corvix.domain._RELEASE_TAG_SEGMENTS
   corvix.domain._ACTIONS_RUNS_SEGMENTS
   corvix.domain._API_RESOURCE_TO_WEB_PATH


Classes
-------

.. autoapisummary::

   corvix.domain.Notification
   corvix.domain.NotificationRecord


Functions
---------

.. autoapisummary::

   corvix.domain._as_object_map
   corvix.domain._require_non_empty_str
   corvix.domain._optional_str
   corvix.domain._optional_bool
   corvix.domain._optional_float
   corvix.domain._optional_str_list
   corvix.domain._optional_context
   corvix.domain.parse_timestamp
   corvix.domain.format_timestamp
   corvix.domain.notification_key
   corvix.domain._get_non_empty_str_or_default
   corvix.domain._derive_web_url
   corvix.domain._map_subject_api_url_to_web


Module Contents
---------------

.. py:data:: _MIN_API_REPO_SEGMENTS
   :value: 4


.. py:data:: _MIN_RESOURCE_SEGMENTS
   :value: 2


.. py:data:: _RELEASE_TAG_SEGMENTS
   :value: 3


.. py:data:: _ACTIONS_RUNS_SEGMENTS
   :value: 3


.. py:data:: _API_RESOURCE_TO_WEB_PATH

.. py:function:: _as_object_map(value: object) -> dict[str, object] | None

.. py:function:: _require_non_empty_str(payload: collections.abc.Mapping[str, object], key: str, label: str) -> str

.. py:function:: _optional_str(payload: collections.abc.Mapping[str, object], key: str) -> str | None

.. py:function:: _optional_bool(payload: collections.abc.Mapping[str, object], key: str, default: bool, label: str) -> bool

.. py:function:: _optional_float(payload: collections.abc.Mapping[str, object], key: str, default: float, label: str) -> float

.. py:function:: _optional_str_list(payload: collections.abc.Mapping[str, object], key: str) -> list[str]

.. py:function:: _optional_context(payload: collections.abc.Mapping[str, object], key: str) -> dict[str, object]

.. py:function:: parse_timestamp(value: str) -> datetime.datetime

   Parse an ISO8601 timestamp into a timezone-aware datetime.


.. py:function:: format_timestamp(value: datetime.datetime) -> str

   Format a timezone-aware datetime as an ISO8601 string.


.. py:class:: Notification

   Normalized notification from GitHub's notifications API.


   .. py:attribute:: thread_id
      :type:  str


   .. py:attribute:: repository
      :type:  str


   .. py:attribute:: reason
      :type:  str


   .. py:attribute:: subject_title
      :type:  str


   .. py:attribute:: subject_type
      :type:  str


   .. py:attribute:: unread
      :type:  bool


   .. py:attribute:: updated_at
      :type:  datetime.datetime


   .. py:attribute:: thread_url
      :type:  str | None
      :value: None



   .. py:attribute:: subject_url
      :type:  str | None
      :value: None



   .. py:attribute:: web_url
      :type:  str | None
      :value: None



   .. py:attribute:: account_id
      :type:  str
      :value: 'primary'



   .. py:attribute:: account_label
      :type:  str
      :value: 'Primary'



   .. py:method:: from_api_payload(payload: collections.abc.Mapping[str, object], *, account_id: str = 'primary', account_label: str = 'Primary') -> Notification
      :classmethod:


      Build a notification from a GitHub API response payload.



.. py:class:: NotificationRecord

   Scored and rule-evaluated notification persisted for dashboards.


   .. py:attribute:: notification
      :type:  Notification


   .. py:attribute:: score
      :type:  float


   .. py:attribute:: excluded
      :type:  bool


   .. py:attribute:: matched_rules
      :type:  list[str]
      :value: []



   .. py:attribute:: actions_taken
      :type:  list[str]
      :value: []



   .. py:attribute:: dismissed
      :type:  bool
      :value: False



   .. py:attribute:: context
      :type:  dict[str, object]


   .. py:method:: to_dict() -> dict[str, object]

      Convert to a JSON-serializable dictionary.



   .. py:method:: from_dict(payload: collections.abc.Mapping[str, object]) -> NotificationRecord
      :classmethod:


      Parse a stored record.



.. py:function:: notification_key(notification: Notification) -> str

   Return a stable account-scoped key for a notification.


.. py:function:: _get_non_empty_str_or_default(payload: collections.abc.Mapping[str, object], key: str, default: str) -> str

.. py:function:: _derive_web_url(payload: collections.abc.Mapping[str, object]) -> str | None

.. py:function:: _map_subject_api_url_to_web(subject_url: str, repo_name: str, repo_base: str) -> str | None