"""DMS extensibility hook names.

These constants identify the well-known hook points in the DMS service layer.
Third-party code (other apps, tenant plugins) can register callables against
these names using :func:`simorgh.apps.dms.registry.register_hook`.

Usage
-----
Register a handler::

    from simorgh.apps.dms.registry import register_hook
    from simorgh.apps.dms.hooks import HOOK_POST_DOCUMENT_CREATE

    @register_hook(HOOK_POST_DOCUMENT_CREATE)
    def on_document_created(*, document, **kwargs):
        # do something after every document is created
        ...

Fire a hook (done internally by the service layer)::

    from simorgh.apps.dms.registry import fire_hook
    from simorgh.apps.dms.hooks import HOOK_POST_DOCUMENT_CREATE

    fire_hook(HOOK_POST_DOCUMENT_CREATE, document=new_doc)

All handlers receive keyword-only arguments.  Unknown extra kwargs MUST be
accepted with ``**kwargs`` for forward compatibility.
"""

from __future__ import annotations

# ---------------------------------------------------------------------------
# Document lifecycle hooks
# ---------------------------------------------------------------------------

#: Fired after a document shell is successfully created.
#: kwargs: document (Document)
HOOK_POST_DOCUMENT_CREATE = "dms.post_document_create"

#: Fired after a document is successfully updated (title/folder/type/etc.).
#: kwargs: document (Document)
HOOK_POST_DOCUMENT_UPDATE = "dms.post_document_update"

#: Fired before a document is soft-deleted (before DB write).
#: kwargs: document (Document)
HOOK_PRE_DOCUMENT_DELETE = "dms.pre_document_delete"

#: Fired after a document is soft-deleted.
#: kwargs: document (Document)
HOOK_POST_DOCUMENT_DELETE = "dms.post_document_delete"

#: Fired after a document status is changed to ARCHIVED.
#: kwargs: document (Document)
HOOK_POST_DOCUMENT_ARCHIVE = "dms.post_document_archive"

# ---------------------------------------------------------------------------
# Version lifecycle hooks
# ---------------------------------------------------------------------------

#: Fired after a document version is promoted to PUBLISHED.
#: kwargs: version (DocumentVersion), document (Document)
HOOK_POST_DOCUMENT_PUBLISH = "dms.post_document_publish"

# ---------------------------------------------------------------------------
# All hook names (for introspection / validation)
# ---------------------------------------------------------------------------

ALL_HOOKS: frozenset[str] = frozenset(
    {
        HOOK_POST_DOCUMENT_CREATE,
        HOOK_POST_DOCUMENT_UPDATE,
        HOOK_PRE_DOCUMENT_DELETE,
        HOOK_POST_DOCUMENT_DELETE,
        HOOK_POST_DOCUMENT_ARCHIVE,
        HOOK_POST_DOCUMENT_PUBLISH,
    }
)