turnstack 0.1.0__py3-none-any.whl

turnstack/handlers/list_handler.py

@@ -0,0 +1,339 @@
+"""
+handlers/list_handler.py
+========================
+ListHandler — dynamic list with optional server‑side pagination.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Dict, List, TYPE_CHECKING
+
+from .base import NodeHandler
+from ..message import IncomingMessage
+from ..reply import Reply, ReplyOption
+from ..session import Session
+
+if TYPE_CHECKING:
+    from ..tree import FlowTree
+
+NEXT_PAGE_KEYWORDS = {"n", "next", "more"}
+PREV_PAGE_KEYWORDS = {"p", "prev", "previous", "back page"}
+
+PREV_PAGE_VALUE = "__prev_page__"
+NEXT_PAGE_VALUE = "__next_page__"
+
+MAX_ROWS = 10   # WhatsApp interactive list row limit
+
+
+class ListHandler(NodeHandler):
+
+    async def handle(
+        self,
+        node: Dict[str, Any],
+        session: Session,
+        message: IncomingMessage,
+        tree: "FlowTree",
+    ) -> Reply:
+        raw = (message.interactive_id or message.text or "").strip().lower()
+        interactive = node.get("interactive", False)
+
+        fetch = node.get("fetch")
+        if not fetch:
+            return self._error(session, "ListNode has no 'fetch' function.")
+
+        page_size = node.get("page_size", 8)
+        page_size = min(MAX_ROWS, max(1, page_size))
+
+        sig = inspect.signature(fetch)
+        paginated_mode = len(sig.parameters) >= 3
+
+        pkey = f"list_{session.current_node}_page"
+        page = session.pagination.get(pkey, 0)
+
+        # ── fetch data for current page ───────────────────────────────
+        if paginated_mode:
+            try:
+                if inspect.iscoroutinefunction(fetch):
+                    result = await fetch(session, page, page_size)
+                else:
+                    result = fetch(session, page, page_size)
+            except Exception as exc:
+                return self._error(session, f"Paginated fetch raised: {exc}")
+
+            if isinstance(result, tuple) and len(result) == 2:
+                items_page, total = result
+            elif isinstance(result, dict):
+                items_page = result.get("items", [])
+                total = result.get("total", 0)
+            else:
+                return self._error(session, "Paginated fetch must return (items, total) or dict with 'items' and 'total'")
+            items_page = list(items_page or [])
+            total_items = total
+        else:
+            try:
+                if inspect.iscoroutinefunction(fetch):
+                    all_items = await fetch(session)
+                else:
+                    all_items = fetch(session)
+            except Exception as exc:
+                return self._error(session, f"Fetch raised: {exc}")
+            all_items = list(all_items or [])
+            total_items = len(all_items)
+            start = page * page_size
+            items_page = all_items[start: start + page_size]
+
+        total_pages = max(1, (total_items + page_size - 1) // page_size)
+        if page >= total_pages:
+            page = total_pages - 1 if total_pages > 0 else 0
+            session.pagination[pkey] = page
+            if paginated_mode and page != (session.pagination.get(pkey, 0)):
+                try:
+                    if inspect.iscoroutinefunction(fetch):
+                        result = await fetch(session, page, page_size)
+                    else:
+                        result = fetch(session, page, page_size)
+                except Exception as exc:
+                    return self._error(session, f"Paginated fetch raised: {exc}")
+                if isinstance(result, tuple):
+                    items_page, total = result
+                else:
+                    items_page = result.get("items", [])
+                items_page = list(items_page or [])
+
+        # First render (no input)
+        if not raw:
+            session.pagination[pkey] = page
+            return self._render_list_page(
+                node, session, items_page, page, total_pages, interactive, page_size, paginated_mode
+            )
+
+        # ── handle interactive mode ─────────────────────────────────────
+        if interactive:
+            # Case 1: user clicked an interactive element (button or list row)
+            if message.interactive_id:
+                selected = message.interactive_id
+
+                # Pagination controls
+                if selected == PREV_PAGE_VALUE and page > 0:
+                    session.pagination[pkey] = page - 1
+                    return await self._enter_node(session, tree)
+                if selected == NEXT_PAGE_VALUE and page + 1 < total_pages:
+                    session.pagination[pkey] = page + 1
+                    return await self._enter_node(session, tree)
+
+                # Extra options (only shown on last page)
+                extra_opts = node.get("extra_options", [])
+                if page == total_pages - 1:
+                    for opt in extra_opts:
+                        opt_value = opt.get("value", opt.get("next", ""))
+                        if selected == opt_value:
+                            target = opt.get("next", tree.entry)
+                            self._transition_to(session, target)
+                            return await self._enter_node(session, tree)
+
+                # Normal item selection
+                if selected.startswith("list_idx_"):
+                    try:
+                        abs_idx = int(selected.split("_")[-1])
+                        start_idx = page * page_size
+                        local = abs_idx - start_idx
+                        if 0 <= local < len(items_page):
+                            selected_item = items_page[local]
+                            session.context["selected_item"] = selected_item
+                            session.context["selected_index"] = abs_idx
+                            session.pagination.pop(pkey, None)
+                            on_select = node.get("on_select", tree.entry)
+                            self._transition_to(session, on_select)
+                            return await self._enter_node(session, tree)
+                    except (ValueError, IndexError):
+                        pass
+
+                # Invalid interactive selection – re‑render with error prefix
+                rendered = self._render_list_page(
+                    node, session, items_page, page, total_pages, interactive, page_size, paginated_mode
+                )
+                rendered.body = "Invalid selection.\n\n" + rendered.body
+                return rendered
+
+            # Case 2: interactive mode, but user typed plain text (not a command)
+            else:
+                # Plain text in interactive mode is invalid – re‑render with error prefix
+                rendered = self._render_list_page(
+                    node, session, items_page, page, total_pages, interactive, page_size, paginated_mode
+                )
+                rendered.body = "Invalid selection.\n\n" + rendered.body
+                return rendered
+
+        # ── plain text (non‑interactive) mode ──────────────────────────
+        else:
+            if raw in NEXT_PAGE_KEYWORDS and page + 1 < total_pages:
+                session.pagination[pkey] = page + 1
+                return await self._enter_node(session, tree)
+            if raw in PREV_PAGE_KEYWORDS and page > 0:
+                session.pagination[pkey] = page - 1
+                return await self._enter_node(session, tree)
+            if raw.isdigit():
+                local_idx = int(raw) - 1
+                if 0 <= local_idx < len(items_page):
+                    selected_item = items_page[local_idx]
+                    abs_idx = page * page_size + local_idx
+                    session.context["selected_item"] = selected_item
+                    session.context["selected_index"] = abs_idx
+                    session.pagination.pop(pkey, None)
+                    on_select = node.get("on_select", tree.entry)
+                    self._transition_to(session, on_select)
+                    return await self._enter_node(session, tree)
+
+            # Invalid text input in plain text mode – re‑render with error prefix
+            rendered = self._render_list_page(
+                node, session, items_page, page, total_pages, interactive, page_size, paginated_mode
+            )
+            rendered.body = "Invalid selection.\n\n" + rendered.body
+            return rendered
+
+    def _render_list_page(
+        self,
+        node: Dict[str, Any],
+        session: Session,
+        items_page: List[Any],
+        page: int,
+        total_pages: int,
+        interactive: bool,
+        page_size: int,
+        paginated_mode: bool,
+    ) -> Reply:
+        if not items_page and total_pages == 0:
+            empty_text = node.get("empty_text", "No items available.")
+            if interactive:
+                return Reply(
+                    type="text",
+                    body=f"{node.get('title', 'List')}\n\n{empty_text}",
+                    phone=session.user_id,
+                    node_type="list",
+                    current_node=session.current_node,
+                )
+            else:
+                return Reply(
+                    type="text",
+                    body=f"{node.get('title', 'List')}\n\n{empty_text}\n\nReply 0 to go back.",
+                    phone=session.user_id,
+                    node_type="list",
+                    current_node=session.current_node,
+                )
+
+        title_raw = node.get("title", "Select an option")
+        if callable(title_raw):
+            title = title_raw(session)
+        else:
+            title = title_raw
+        item_label_fn = node.get("item_label", str)
+        item_desc_fn = node.get("item_description")
+        extra_opts = node.get("extra_options", [])
+
+        if interactive:
+            pagination_slots = 2 if (0 < page < total_pages - 1) else 1 if total_pages > 1 else 0
+            show_extra_on_last = (page == total_pages - 1) and len(extra_opts) > 0
+            extra_slots = len(extra_opts) if show_extra_on_last else 0
+            max_items = MAX_ROWS - pagination_slots - extra_slots
+            if max_items < 1:
+                max_items = 1
+            display_items = items_page[:max_items]
+
+            sections = []
+
+            if display_items:
+                items_section = {
+                    "title": node.get("items_section_title", "Options"),
+                    "rows": []
+                }
+                start_idx = page * page_size
+                for local_i, item in enumerate(display_items):
+                    abs_i = start_idx + local_i
+                    label = item_label_fn(item)
+                    desc = item_desc_fn(item) if item_desc_fn else ""
+                    items_section["rows"].append({
+                        "id": f"list_idx_{abs_i}",
+                        "title": label[:24],
+                        "description": desc[:72],
+                    })
+                sections.append(items_section)
+
+            actions_rows = []
+            if total_pages > 1:
+                if page > 0:
+                    actions_rows.append({
+                        "id": PREV_PAGE_VALUE,
+                        "title": "⬅️ Previous Page",
+                        "description": f"Page {page}/{total_pages}" if page > 1 else "Previous page",
+                    })
+                if page < total_pages - 1:
+                    actions_rows.append({
+                        "id": NEXT_PAGE_VALUE,
+                        "title": "➡️ Next Page",
+                        "description": f"Page {page+2}/{total_pages}" if page + 2 < total_pages else "Next page",
+                    })
+            if show_extra_on_last:
+                for opt in extra_opts:
+                    actions_rows.append({
+                        "id": opt.get("value", opt.get("next", "")),
+                        "title": opt.get("label", "")[:24],
+                        "description": opt.get("description", "")[:72],
+                    })
+            if actions_rows:
+                sections.append({
+                    "title": node.get("actions_section_title", "Actions"),
+                    "rows": actions_rows
+                })
+
+            button_label = node.get("button_label", "Options")
+            return Reply(
+                type="text",
+                body=title,
+                phone=session.user_id,
+                node_type="menu",
+                options=[],
+                current_node=session.current_node,
+                meta={
+                    "button_label": button_label,
+                    "sections": sections,
+                },
+            )
+
+        else:
+            # Plain text rendering
+            lines = [title]
+            if total_pages > 1:
+                lines.append(f"(Page {page+1}/{total_pages})")
+            lines.append("")
+            reply_options = []
+            start_idx = page * page_size
+            for local_i, item in enumerate(items_page):
+                abs_i = start_idx + local_i
+                label = item_label_fn(item)
+                desc = item_desc_fn(item) if item_desc_fn else ""
+                lines.append(f"{local_i+1}. {label}")
+                if desc:
+                    lines.append(f"   {desc}")
+                reply_options.append(ReplyOption(
+                    label=label,
+                    value=f"list_idx_{abs_i}",
+                    description=desc,
+                ))
+            lines.append("")
+            nav = []
+            if page > 0:
+                nav.append("p=prev")
+            if page < total_pages - 1:
+                nav.append("n=next")
+            nav.append("0=back")
+            lines.append(" · ".join(nav))
+            return Reply(
+                type="text",
+                body="\n".join(lines),
+                phone=session.user_id,
+                options=reply_options,
+                node_type="list",
+                suggested_replies=[o.value for o in reply_options],
+                current_node=session.current_node,
+            )

turnstack/handlers/media_handler.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+import inspect
+from typing import Any, Dict, TYPE_CHECKING
+
+from ..message import IncomingMessage
+from ..reply import Reply
+from ..session import Session
+from .base import NodeHandler
+
+if TYPE_CHECKING:
+    from ..tree import FlowTree
+
+
+class MediaHandler(NodeHandler):
+    """
+    Handles ``media`` nodes.
+
+    Calls ``generate(session, collected)`` to produce file bytes,
+    returns a ``Reply(type="media", ...)`` and then advances to ``next``.
+
+    The developer's WhatsApp adapter sends the file using their provider.
+
+    ``filename`` and ``caption`` can be plain strings or callables
+    ``(session, collected) -> str``.
+    """
+
+    async def handle(
+        self,
+        node: Dict[str, Any],
+        session: Session,
+        message: IncomingMessage,
+        tree: "FlowTree",
+    ) -> Reply:
+        generate = node.get("generate")
+        if not generate:
+            return self._error(session, "MediaNode has no 'generate' function.")
+
+        try:
+            if inspect.iscoroutinefunction(generate):
+                file_bytes = await generate(session, session.collected)
+            else:
+                file_bytes = generate(session, session.collected)
+        except Exception as exc:
+            return self._error(session, f"MediaNode generate raised: {exc}")
+
+        # resolve filename
+        filename_raw = node.get("filename", "file")
+        if callable(filename_raw):
+            filename = filename_raw(session, session.collected)
+        else:
+            filename = filename_raw
+
+        # resolve caption
+        caption_raw = node.get("caption", "")
+        if callable(caption_raw):
+            caption = caption_raw(session, session.collected)
+        else:
+            caption = caption_raw
+
+        # advance session
+        next_key = node.get("next", "welcome")
+        self._transition_to(session, next_key)
+
+        return Reply(
+            type="media",
+            node_type="media",
+            body=caption,
+            phone=session.user_id,
+            file_bytes=file_bytes,
+            filename=filename,
+            mime_type=node.get("mime_type", "application/octet-stream"),
+            current_node=session.current_node,
+        )

turnstack/handlers/menu.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+from ..message import IncomingMessage
+from ..reply import Reply, ReplyOption
+from ..session import Session
+from .base import NodeHandler
+
+if TYPE_CHECKING:
+    from ..tree import FlowTree
+
+# WhatsApp interactive list max rows
+MAX_MENU_ROWS = 10
+PREV_PAGE = "__menu_prev__"
+NEXT_PAGE = "__menu_next__"
+
+
+class MenuHandler(NodeHandler):
+    """
+    Handles ``menu`` nodes.
+
+    Accepts input via:
+    1. Interactive ID (``message.interactive_id``) — always checked first.
+       The value must match an Option's ``value`` field.
+    2. Numeric digit ("1", "2" …) — only if ``allow_numeric=True`` on the node.
+    3. Label text (case-insensitive) — fallback for text-only channels.
+    4. Back / Home keywords — "0" goes back, "00" goes home.
+    """
+
+    async def handle(
+        self,
+        node: Dict[str, Any],
+        session: Session,
+        message: IncomingMessage,
+        tree: "FlowTree",
+    ) -> Reply:
+        raw_input = (message.interactive_id or message.text or "").strip()
+        all_options = node.get("options", [])
+
+        # ── pagination state ─────────────────────────────────────────
+        # Use conservative capacity (MAX_MENU_ROWS - 2) so total_pages is
+        # stable. Exception: all options fit on one page with no nav rows.
+        if len(all_options) <= MAX_MENU_ROWS:
+            items_per_page = MAX_MENU_ROWS
+        else:
+            items_per_page = MAX_MENU_ROWS - 2  # always room for Prev + Next
+
+        pkey = f"menu_{session.current_node}_page"
+        page = session.pagination.get(pkey, 0)
+        total_pages = max(1, (len(all_options) + items_per_page - 1) // items_per_page)
+        if page >= total_pages:
+            page = total_pages - 1 if total_pages > 0 else 0
+            session.pagination[pkey] = page
+
+        # ── nothing yet — first render ────────────────────────────────
+        if not raw_input:
+            return self._render_menu_page(node, session, all_options, page, total_pages)
+
+        # ── interactive pagination ────────────────────────────────────
+        if message.interactive_id == PREV_PAGE:
+            if page > 0:
+                session.pagination[pkey] = page - 1
+            return await self._enter_node(session, tree)
+        if message.interactive_id == NEXT_PAGE:
+            if page + 1 < total_pages:
+                session.pagination[pkey] = page + 1
+            return await self._enter_node(session, tree)
+
+        # ── match option on current page ──────────────────────────────
+        start = page * items_per_page
+        page_options = all_options[start: start + items_per_page]
+        matched_next = self._match_option(page_options, message, raw_input, node.get("allow_numeric", False))
+
+        if not matched_next:
+            rendered = self._render_menu_page(node, session, all_options, page, total_pages)
+            return Reply(
+                type="text",
+                body="Invalid option. Please choose from the list.\n\n" + rendered.body,
+                phone=session.user_id,
+                options=rendered.options,
+                node_type="menu",
+                current_node=session.current_node,
+                meta=rendered.meta,
+            )
+
+        # store selected value in context for downstream access
+        session.context["last_option"] = matched_next
+
+        # clear collected when going home
+        if matched_next == tree.entry:
+            session.collected = {}
+
+        self._transition_to(session, matched_next)
+        return await self._enter_node(session, tree)
+
+    def _match_option(
+        self,
+        options: list,
+        message: IncomingMessage,
+        raw_input: str,
+        allow_numeric: bool,
+    ) -> Optional[str]:
+        for i, opt in enumerate(options, 1):
+            label = opt.get("label", "") if isinstance(opt, dict) else opt[0]
+            value = opt.get("value", opt.get("next", "")) if isinstance(opt, dict) else opt[1]
+            next_key = opt.get("next", "") if isinstance(opt, dict) else opt[1]
+
+            # 1. Interactive ID match
+            if message.interactive_id and (
+                message.interactive_id == value or message.interactive_id == next_key
+            ):
+                return next_key
+
+            # 2. Numeric
+            if allow_numeric and raw_input == str(i):
+                return next_key
+
+            # 3. Label (case-insensitive)
+            if raw_input.lower() == label.lower():
+                return next_key
+
+        return None
+
+    def _render_menu_page(
+            self,
+            node: Dict[str, Any],
+            session: Session,
+            all_options: list,
+            page: int,
+            total_pages: int,
+    ) -> Reply:
+        text_raw = node.get("text", "")
+        if callable(text_raw):
+            text = text_raw(session)
+        else:
+            text = text_raw
+        button_label = node.get("button_label", "Options")
+
+        # Reserve slots for pagination rows so total rows never exceed MAX_MENU_ROWS.
+        # On a middle page we need both Prev and Next (2 slots).
+        # On the first or last page we need one (1 slot).
+        # On a single page we need none.
+        if total_pages == 1:
+            pagination_slots = 0
+        elif 0 < page < total_pages - 1:
+            pagination_slots = 2   # Prev + Next
+        else:
+            pagination_slots = 1   # Prev or Next only
+
+        max_items    = MAX_MENU_ROWS - pagination_slots
+        start        = page * (MAX_MENU_ROWS - 2) if total_pages > 1 else 0
+        page_options = all_options[start: start + max_items]
+
+        # Build the reply options for the current page
+        reply_options = []
+        for opt in page_options:
+            label = opt.get("label", "") if isinstance(opt, dict) else opt[0]
+            value = opt.get("value", opt.get("next", "")) if isinstance(opt, dict) else opt[1]
+            desc  = opt.get("description", "") if isinstance(opt, dict) else ""
+            reply_options.append(ReplyOption(label=label, value=value, description=desc))
+
+        # Add pagination rows if needed
+        if total_pages > 1:
+            if page > 0:
+                reply_options.append(ReplyOption(
+                    label="◀ Previous Page",
+                    value=PREV_PAGE,
+                    description=f"Page {page}/{total_pages}",
+                ))
+            if page < total_pages - 1:
+                reply_options.append(ReplyOption(
+                    label="Next Page ▶",
+                    value=NEXT_PAGE,
+                    description=f"Page {page + 2}/{total_pages}",
+                ))
+
+        body = text
+
+        return Reply(
+            type="text",
+            body=body,
+            phone=session.user_id,
+            options=reply_options,
+            node_type="menu",
+            current_node=session.current_node,
+            session_state=session.lifecycle_state,
+            meta={"button_label": button_label},
+        )

turnstack/handlers/render_helpers.py

@@ -0,0 +1,28 @@
+from typing import Dict, Any
+from ..session import Session
+
+def render_node_prompt(node: Dict[str, Any], session: Session) -> str:
+    t = node.get("type")
+    if t == "menu":
+        lines = [node.get("text", ""), ""]
+        for i, opt in enumerate(node.get("options", []), 1):
+            label = opt.get("label") if isinstance(opt, dict) else opt[0]
+            lines.append(f"{i}. {label}")
+        return "\n".join(lines)
+    elif t == "input":
+        return node.get("prompt", "")
+    elif t == "confirm":
+        text = node.get("text", "")
+        if callable(text):
+            body = text(session.collected)
+        else:
+            body = text
+        lines = [body, ""]
+        for i, opt in enumerate(node.get("options", []), 1):
+            label = opt.get("label") if isinstance(opt, dict) else opt[0]
+            lines.append(f"{i}. {label}")
+        return "\n".join(lines)
+    elif t == "action":
+        return ""  # Actions produce their own reply
+    else:
+        return "Unknown node type."