corvix.web.schemas
==================

.. py:module:: corvix.web.schemas

.. autoapi-nested-parse::

   Typed response schemas for the Corvix web API.

   These dataclasses are the single source of truth for the JSON shapes returned
   by the ``/api/v1`` route handlers. Litestar serializes them directly and
   auto-generates an OpenAPI document from their annotations; the frontend's
   TypeScript types are code-generated from that document (see
   ``scripts/export_openapi.py`` and ``frontend/src/api-types.gen.ts``).

   Every field is required (no defaults) so the generated OpenAPI schema marks
   each property as required and the TypeScript types never become accidentally
   optional. ``str | None`` fields map to a nullable-but-present property, matching
   how the handlers always emit the key.



Classes
-------

.. autoapisummary::

   corvix.web.schemas.DashboardItemResponse
   corvix.web.schemas.DashboardGroupResponse
   corvix.web.schemas.DashboardSummaryResponse
   corvix.web.schemas.AccountErrorResponse
   corvix.web.schemas.PollerStatusResponse
   corvix.web.schemas.BrowserTabNotificationsConfigResponse
   corvix.web.schemas.NotificationsConfigResponse
   corvix.web.schemas.SnapshotResponse
   corvix.web.schemas.RuleSnippetsResponse


Functions
---------

.. autoapisummary::

   corvix.web.schemas._dashboard_item_response
   corvix.web.schemas.build_snapshot_response


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

.. py:class:: DashboardItemResponse

   A single notification row rendered by the dashboard table.


   .. py:attribute:: account_id
      :type:  str


   .. py:attribute:: account_label
      :type:  str


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


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


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


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


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


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


   .. py:attribute:: updated_at
      :type:  str


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


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


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


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


.. py:class:: DashboardGroupResponse

   A group of dashboard items (e.g. grouped by repository or reason).


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: items
      :type:  list[DashboardItemResponse]


.. py:class:: DashboardSummaryResponse

   Aggregate counts shown in the dashboard shell.


   .. py:attribute:: unread_items
      :type:  int


   .. py:attribute:: read_items
      :type:  int


   .. py:attribute:: group_count
      :type:  int


   .. py:attribute:: repository_count
      :type:  int


   .. py:attribute:: reason_count
      :type:  int


.. py:class:: AccountErrorResponse

   A per-account fetch failure recorded during a poll cycle.


   .. py:attribute:: account_id
      :type:  str


   .. py:attribute:: account_label
      :type:  str


   .. py:attribute:: error
      :type:  str


.. py:class:: PollerStatusResponse

   Poller health surfaced to the UI for the staleness warning banner.


   .. py:attribute:: status
      :type:  str


   .. py:attribute:: last_poll_time
      :type:  str | None


   .. py:attribute:: last_error
      :type:  str | None


   .. py:attribute:: last_error_time
      :type:  str | None


   .. py:attribute:: stale
      :type:  bool


   .. py:attribute:: account_errors
      :type:  list[AccountErrorResponse]


.. py:class:: BrowserTabNotificationsConfigResponse

   In-tab browser notification settings echoed to the frontend.


   .. py:attribute:: enabled
      :type:  bool


   .. py:attribute:: max_per_cycle
      :type:  int


   .. py:attribute:: cooldown_seconds
      :type:  int


.. py:class:: NotificationsConfigResponse

   Notification configuration relevant to the browser client.


   .. py:attribute:: enabled
      :type:  bool


   .. py:attribute:: browser_tab
      :type:  BrowserTabNotificationsConfigResponse


.. py:class:: SnapshotResponse

   Full dashboard snapshot returned by ``GET /api/v1/snapshot``.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: include_read
      :type:  bool


   .. py:attribute:: sort_by
      :type:  str


   .. py:attribute:: descending
      :type:  bool


   .. py:attribute:: generated_at
      :type:  str | None


   .. py:attribute:: groups
      :type:  list[DashboardGroupResponse]


   .. py:attribute:: total_items
      :type:  int


   .. py:attribute:: summary
      :type:  DashboardSummaryResponse


   .. py:attribute:: dashboard_names
      :type:  list[str]


   .. py:attribute:: poller
      :type:  PollerStatusResponse


   .. py:attribute:: notifications_config
      :type:  NotificationsConfigResponse | None


.. py:class:: RuleSnippetsResponse

   Prefilled ignore-rule snippets for a single notification.


   .. py:attribute:: dashboard_name
      :type:  str


   .. py:attribute:: dashboard_ignore_rule_snippet
      :type:  str


   .. py:attribute:: global_exclude_rule_snippet
      :type:  str


   .. py:attribute:: dashboard_ignore_rule_with_context_snippet
      :type:  str | None


   .. py:attribute:: global_exclude_rule_with_context_snippet
      :type:  str | None


   .. py:attribute:: has_context
      :type:  bool


.. py:function:: _dashboard_item_response(item: corvix.dashboarding.DashboardItem) -> DashboardItemResponse

   Convert a ``dashboarding.DashboardItem`` into its response schema.


.. py:function:: build_snapshot_response(*, data: corvix.dashboarding.DashboardData, dashboard_names: list[str], poller: PollerStatusResponse, notifications_config: corvix.config.notifications.NotificationsConfig | None) -> SnapshotResponse

   Assemble a typed :class:`SnapshotResponse` from dashboard data.

   Centralizes the mapping from the internal ``DashboardData`` dataclass (plus
   the already-resolved poller status and config state) to the wire schema so
   the route handler stays thin and the contract lives in one place.