"""Public extension interface for CleverAgents resource types.

This package provides the stable API that third-party developers use to
implement custom resource types without modifying core code.

## Quick Start

To implement a custom resource type:

1. Subclass :class:`ResourceType` and implement all abstract methods.
2. Register the class with :func:`register_resource_type`.
3. Import and use the type from ``cleveragents.resources``.

Example::

    from cleveragents.resources import (
        ResourceType,
        ResourceConfig,
        ResourceStatus,
        register_resource_type,
    )

    class MyDatabaseType(ResourceType):
        def provision(self, config: ResourceConfig) -> ResourceStatus:
            # Connect and initialise the database
            return ResourceStatus.ACTIVE

        def deprovision(self, config: ResourceConfig) -> ResourceStatus:
            # Tear down the database
            return ResourceStatus.DEPROVISIONED

        def status(self, config: ResourceConfig) -> ResourceStatus:
            # Check whether the resource is reachable
            return ResourceStatus.ACTIVE

        def validate_config(self, config: ResourceConfig) -> list[str]:
            errors: list[str] = []
            if not config.properties.get("host"):
                errors.append("'host' is required in properties")
            return errors

        def to_dict(self) -> dict[str, object]:
            return {"type": "myorg/database", "version": "1.0"}

    register_resource_type("myorg/database", MyDatabaseType)

See Also:
    - :class:`ResourceType` — abstract base class all custom types must subclass
    - :class:`ResourceConfig` — configuration container passed to lifecycle methods
    - :class:`ResourceStatus` — enum of possible resource lifecycle states
    - :func:`register_resource_type` — register a custom type by name
    - :func:`get_resource_type` — retrieve a registered type class by name
    - :func:`list_resource_types` — list all registered type names
"""

from cleveragents.resources.extension import (
    ResourceConfig,
    ResourceStatus,
    ResourceType,
    get_resource_type,
    list_resource_types,
    register_resource_type,
)

__all__ = [
    "ResourceConfig",
    "ResourceStatus",
    "ResourceType",
    "get_resource_type",
    "list_resource_types",
    "register_resource_type",
]
