from __future__ import annotations

from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from typing import Any, Literal, Protocol


RestFunctionVisibility = Literal["internal", "authenticated", "public"]


@dataclass(frozen=True, slots=True)
class RestFunctionDescriptor:
    id: str
    module_id: str
    name: str
    summary: str
    method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"] = "POST"
    path: str | None = None
    visibility: RestFunctionVisibility = "authenticated"
    required_scopes: tuple[str, ...] = ()
    request_schema: Mapping[str, Any] = field(default_factory=dict)
    response_schema: Mapping[str, Any] = field(default_factory=dict)
    tags: tuple[str, ...] = ()


class RestFunctionProvider(Protocol):
    def rest_functions(self) -> Sequence[RestFunctionDescriptor]:
        ...

    def invoke_rest_function(self, function_id: str, payload: Mapping[str, Any], context: Mapping[str, Any]) -> Mapping[str, Any]:
        ...


CAPABILITY_REST_FUNCTION_PROVIDER = "rest.functionProvider"