"""Delivery domain contracts: DeliveryMode, DeliveryContract, acceptance and WS payloads.

Per tech_spec §13.1 and §14. Author: Vasiliy Zdanovskiy
email: vasilyvz@gmail.com
"""

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum
from typing import Any, Literal, TypedDict


class DeliveryMode(str, Enum):
    """Final delivery modes returned by the server."""

    IMMEDIATE = "immediate"
    POLL = "poll"
    WS = "ws"
    WS_WITH_STATUS = "ws_with_status"


@dataclass(frozen=True)
class DeliveryContract:
    """Effective delivery contract for one accepted execution request."""

    mode: DeliveryMode
    terminal_only: bool
    status_observable: bool = False


class ExecutionAcceptancePayload(TypedDict, total=False):
    """Canonical response payload from async-capable execution endpoints."""

    accepted: bool
    job_id: str | None
    ws_id: str | None
    delivery: dict[str, Any]
    message: str | None


class WsSubscribePayload(TypedDict):
    """Canonical subscribe request payload sent to /ws."""

    action: Literal["subscribe"]
    subscription_type: Literal["queue_job", "ws_delivery"]
    id: str


class WsDeliveryTerminalPayload(TypedDict, total=False):
    """Final WS delivery payload for ws_id."""

    event: Literal["delivery_completed", "delivery_failed", "delivery_cancelled"]
    ws_id: str
    job_id: str | None
    result: dict[str, Any] | None
    error: str | None
