# (c) Copyright 2025 Perceptic Technologies Ltd. All rights reserved.
#
# AUTO-GENERATED FILE - DO NOT EDIT
# Generated from: perceptic-workflow.schema.json

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any, ClassVar
from perceptic_workflow.definitions import GetEventsQueryResponse
from perceptic_workflow.definitions import WorkflowStatus


class PercepticWorkflow(ABC):
    """
    Defines the standard Perceptic Workflow control updates that all workflows must support to handle user interaction. These update names are reserved and invoked directly by the Perceptic Core V3 API.

    This is a mixin class that provides the method signatures and constants for
    the Perceptic workflow interface. Since Temporal's @workflow.defn decorator
    must be applied to concrete classes, implement this mixin in your workflow class
    and apply the appropriate decorators.

    Example:
        @workflow.defn
        class MyWorkflow(PercepticWorkflow):
            @workflow.query(name=PercepticWorkflow.QUERY_GET_EVENTS)
            def get_events(self, page_size: int, next_page_token: str | None = None) -> GetEventsQueryResponse:
                return GetEventsQueryResponse(events=self._events[:page_size], next_page_token=None)
    """

    # The reserved query name for retrieves the workflow-specific status payload.
    QUERY_GET_STATUS: str = "getStatus"
    # The reserved query name for retrieves workflow events using paginated offset-based access.
    QUERY_GET_EVENTS: str = "getEvents"
    _REQUIRED_TEMPORAL_HANDLERS: ClassVar[dict[str, tuple[str, str]]] = {
        "get_status": ("query", "QUERY_GET_STATUS"),
        "get_events": ("query", "QUERY_GET_EVENTS"),
    }


    @abstractmethod
    def get_status(
        self
    ) -> WorkflowStatus:
        """
        Retrieves the workflow-specific status payload.


        Returns:
            
        """
        ...

    @abstractmethod
    def get_events(
        self,
        page_size: int,
        next_page_token: str | None = None
    ) -> GetEventsQueryResponse:
        """
        Retrieves workflow events using paginated offset-based access.

        Args:
            page_size: Maximum number of events to return in a page.
        Args:
            next_page_token: Opaque pagination token from a previous response.

        Returns:
            
        """
        ...
