corvix.web.schemas

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

DashboardItemResponse	A single notification row rendered by the dashboard table.
DashboardGroupResponse	A group of dashboard items (e.g. grouped by repository or reason).
DashboardSummaryResponse	Aggregate counts shown in the dashboard shell.
AccountErrorResponse	A per-account fetch failure recorded during a poll cycle.
PollerStatusResponse	Poller health surfaced to the UI for the staleness warning banner.
BrowserTabNotificationsConfigResponse	In-tab browser notification settings echoed to the frontend.
NotificationsConfigResponse	Notification configuration relevant to the browser client.
SnapshotResponse	Full dashboard snapshot returned by GET /api/v1/snapshot.
RuleSnippetsResponse	Prefilled ignore-rule snippets for a single notification.

Functions

_dashboard_item_response(→ DashboardItemResponse)	Convert a dashboarding.DashboardItem into its response schema.
build_snapshot_response(→ SnapshotResponse)	Assemble a typed SnapshotResponse from dashboard data.

Module Contents

class corvix.web.schemas.DashboardItemResponse

A single notification row rendered by the dashboard table.

account_id: str

account_label: str

thread_id: str

repository: str

reason: str

subject_type: str

subject_title: str

unread: bool

updated_at: str

score: float

web_url: str | None

matched_rules: list[str]

actions_taken: list[str]

class corvix.web.schemas.DashboardGroupResponse

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

name: str

items: list[DashboardItemResponse]

class corvix.web.schemas.DashboardSummaryResponse

Aggregate counts shown in the dashboard shell.

unread_items: int

read_items: int

group_count: int

repository_count: int

reason_count: int

class corvix.web.schemas.AccountErrorResponse

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

account_id: str

account_label: str

error: str

class corvix.web.schemas.PollerStatusResponse

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

status: str

last_poll_time: str | None

last_error: str | None

last_error_time: str | None

stale: bool

account_errors: list[AccountErrorResponse]

class corvix.web.schemas.BrowserTabNotificationsConfigResponse

In-tab browser notification settings echoed to the frontend.

enabled: bool

max_per_cycle: int

cooldown_seconds: int

class corvix.web.schemas.NotificationsConfigResponse

Notification configuration relevant to the browser client.

enabled: bool

browser_tab: BrowserTabNotificationsConfigResponse

class corvix.web.schemas.SnapshotResponse

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

name: str

include_read: bool

sort_by: str

descending: bool

generated_at: str | None

groups: list[DashboardGroupResponse]

total_items: int

summary: DashboardSummaryResponse

dashboard_names: list[str]

poller: PollerStatusResponse

notifications_config: NotificationsConfigResponse | None

class corvix.web.schemas.RuleSnippetsResponse

Prefilled ignore-rule snippets for a single notification.

dashboard_name: str

dashboard_ignore_rule_snippet: str

global_exclude_rule_snippet: str

dashboard_ignore_rule_with_context_snippet: str | None

global_exclude_rule_with_context_snippet: str | None

has_context: bool

corvix.web.schemas._dashboard_item_response(item: corvix.dashboarding.DashboardItem) → DashboardItemResponse

Convert a dashboarding.DashboardItem into its response schema.

corvix.web.schemas.build_snapshot_response(*, data: corvix.dashboarding.DashboardData, dashboard_names: list[str], poller: PollerStatusResponse, notifications_config: corvix.config.notifications.NotificationsConfig | None) → SnapshotResponse

Assemble a typed 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.