"""Pillar backend SDK — register server-side tools and handle tool calls.

Quick start::

    from pillar import Pillar, ToolContext

    pillar = Pillar(secret="plr_...")

    @pillar.tool(description="Look up a customer by email")
    async def lookup_customer(email: str, ctx: ToolContext) -> dict:
        customer = await db.get_customer(email=email)
        return {"name": customer.name, "plan": customer.plan}
"""
from __future__ import annotations

import sys
from typing import Any, TypedDict

if sys.version_info >= (3, 11):
    from typing import Required
else:
    from typing_extensions import Required

from pillar._client import Pillar
from pillar._context import CallerInfo, ToolContext
from pillar._errors import (
    PillarError,
    RegistrationError,
    SignatureVerificationError,
    ToolNotFoundError,
)


class ConfirmationResponse(TypedDict, total=False):
    """Standard shape for a confirmation response returned by a tool handler.

    Return this from your tool handler when the user should confirm before
    the action is performed. Pillar will render a channel-appropriate
    confirmation UI and re-call your handler with ``ctx.confirmed = True``
    after the user confirms.
    """

    confirmation_required: Required[bool]
    title: str
    message: str
    details: dict[str, str]
    confirm_payload: dict[str, Any]


__all__ = [
    "CallerInfo",
    "ConfirmationResponse",
    "Pillar",
    "PillarError",
    "RegistrationError",
    "SignatureVerificationError",
    "ToolContext",
    "ToolNotFoundError",
]

__version__ = "0.1.0"
