Skip to content

Self-improving AI Employees for everyone

feat(schema): Wave 6 Phase 4 - generalized loadOptionsMethod dispatch registry

trohitga3c1ac297155
diff --git a/server/routers/schemas.py b/server/routers/schemas.py
index f1ab2dea..c00f8376 100644
--- a/server/routers/schemas.py
+++ b/server/routers/schemas.py
@@ -89,3 +89,28 @@ async def list_specs():
schema. Editor uses this on boot to prefetch the full set."""
return {"node_types": list_node_types_with_spec()}
+
+
[email protected]("/nodes/options/{method}")
+async def load_options(method: str, body: dict | None = None):
+ """Wave 6 Phase 4: REST mirror of the load_options WS handler.
+
+ Resolves a ``loadOptionsMethod`` string against the registry and
+ returns the dynamic dropdown contents. Body is the per-method
+ parameter map (e.g. ``{"group_id": "..."}`` for
+ whatsappGroupMembers).
+ """
+ from services.node_option_loaders import dispatch_load_options
+
+ params = (body or {}).get("params", body or {}) if isinstance(body, dict) else {}
+ options = await dispatch_load_options(method, params)
+ return {"method": method, "options": options}
+
+
[email protected]("/nodes/options")
+async def list_load_options():
+ """Registered loadOptionsMethod names. Editor probes this on boot
+ to know which dynamic-option loaders are wired backend-side."""
+ from services.node_option_loaders import list_load_options_methods
+
+ return {"methods": list_load_options_methods()}
diff --git a/server/routers/websocket.py b/server/routers/websocket.py
index 441f9e1b..4f253cc9 100644
--- a/server/routers/websocket.py
+++ b/server/routers/websocket.py
@@ -278,6 +278,37 @@ async def handle_list_node_specs(
return {"node_types": list_node_types_with_spec()}
+@ws_handler("method")
+async def handle_load_options(
+ data: Dict[str, Any], websocket: WebSocket
+) -> Dict[str, Any]:
+ """Wave 6 Phase 4: unified loadOptionsMethod dispatcher.
+
+ Replaces the per-method WS handlers (whatsapp_groups, whatsapp_newsletters,
+ etc.) with a single registry-driven endpoint. ``loadOptionsMethod`` strings
+ declared via Pydantic ``Field(json_schema_extra={"loadOptionsMethod": "..."})``
+ on the backend NodeSpec are resolved here.
+
+ Body: ``{"method": "...", "params": {...}}``
+ Response: ``{"options": [{"value": ..., "label": ...}]}``
+ """
+ from services.node_option_loaders import dispatch_load_options
+
+ options = await dispatch_load_options(data["method"], data.get("params", {}))
+ return {"method": data["method"], "options": options}
+
+
+@ws_handler()
+async def handle_list_load_options_methods(
+ data: Dict[str, Any], websocket: WebSocket
+) -> Dict[str, Any]:
+ """Return registered loadOptionsMethod names. Editor uses this to
+ know which dynamic-option loaders are wired."""
+ from services.node_option_loaders import list_load_options_methods
+
+ return {"methods": list_load_options_methods()}
+
+
# ============================================================================
# Credential Registry Handler (Nango-style bulk fetch for 20 -> 5000 providers)
# ============================================================================
@@ -3188,6 +3219,9 @@ MESSAGE_HANDLERS: Dict[str, MessageHandler] = {
# Wave 6 Phase 2: unified NodeSpec (input + output + metadata).
"get_node_spec": handle_get_node_spec,
"list_node_specs": handle_list_node_specs,
+ # Wave 6 Phase 4: generic loadOptionsMethod dispatcher.
+ "load_options": handle_load_options,
+ "list_load_options_methods": handle_list_load_options_methods,
# Credential registry (Nango-style bulk catalogue for credentials panel)
"get_credential_catalogue": handle_get_credential_catalogue,
diff --git a/server/services/node_option_loaders/__init__.py b/server/services/node_option_loaders/__init__.py
new file mode 100644
index 00000000..d834c010
--- /dev/null
+++ b/server/services/node_option_loaders/__init__.py
@@ -0,0 +1,67 @@
+"""Generic loadOptionsMethod dispatch registry.
+
+Wave 6 Phase 4. Generalises the WhatsApp-only dynamic-options pattern
+to a registry mirroring services/node_executor._build_handler_registry().
+
+The editor calls a single endpoint:
+
+ POST /api/nodes/options/{method}
+
+with body ``{"node_type": "...", "params": {...}}`` and the dispatcher
+looks up the registered async loader, invokes it, and returns the
+resulting ``[{"value": ..., "label": ...}]`` list. WS mirror at
+``load_options`` matches the Wave 3 handler convention.
+
+Registering a new dynamic-option loader: define an async function in
+its own module under this package, import it here, and add the entry
+to ``LOAD_OPTIONS_REGISTRY``. No frontend change needed - the
+``loadOptionsMethod`` string in the Pydantic ``Field(json_schema_extra=)``
+is what wires it through.
+"""
+
+from typing import Any, Awaitable, Callable, Optional
+
+from .whatsapp_loaders import (
+ load_whatsapp_channels,
+ load_whatsapp_group_members,
+ load_whatsapp_groups,
+)
+
+
+# Async loader signature: (params: dict) -> list of {value, label, ...}
+LoadOptionsFn = Callable[[dict[str, Any]], Awaitable[list[dict[str, Any]]]]
+
+
+LOAD_OPTIONS_REGISTRY: dict[str, LoadOptionsFn] = {
+ # WhatsApp - already implemented; this just exposes them under the
+ # unified dispatcher name.
+ "whatsappGroups": load_whatsapp_groups,
+ "whatsappChannels": load_whatsapp_channels,
+ "whatsappGroupMembers": load_whatsapp_group_members,
+ # Gmail / Calendar / Telegram / Twitter loaders land in follow-up
+ # commits. The registry is the seam - adding them is a one-line
+ # registration once the loader function exists.
+}
+
+
+async def dispatch_load_options(
+ method: str, params: Optional[dict[str, Any]] = None
+) -> list[dict[str, Any]]:
+ """Look up and invoke a registered loader.
+
+ Returns an empty list when the method isn't registered (matches
+ n8n's tolerant fallback - the dropdown stays empty rather than
+ erroring out)."""
+
+ loader = LOAD_OPTIONS_REGISTRY.get(method)
+ if loader is None:
+ return []
+ return await loader(params or {})
+
+
+def list_load_options_methods() -> list[str]:
+ """Stable alphabetised list of registered method names. The editor
+ prefetches this once on boot so it knows which ``loadOptionsMethod``
+ values are wired."""
+
+ return sorted(LOAD_OPTIONS_REGISTRY.keys())
diff --git a/server/services/node_option_loaders/whatsapp_loaders.py b/server/services/node_option_loaders/whatsapp_loaders.py
new file mode 100644
index 00000000..dc2d9964
--- /dev/null
+++ b/server/services/node_option_loaders/whatsapp_loaders.py
@@ -0,0 +1,69 @@
+"""WhatsApp loadOptions adapters.
+
+Wave 6 Phase 4. Thin wrappers around the existing WhatsApp WS handlers
+that normalise the response into the unified ``[{value, label}]`` shape
+the frontend ``useLoadOptionsQuery`` consumes.
+
+Today the editor talks to ``handle_whatsapp_groups`` /
+``handle_whatsapp_newsletters`` / ``handle_whatsapp_group_info``
+directly via dedicated WS message types. These adapters expose the
+same data through the unified ``load_options`` dispatcher so the
+``loadOptionsMethod`` schema field wires straight through with no
+per-method WS handler. The legacy WS handlers stay live for back-compat.
+"""
+
+from typing import Any
+
+
+async def load_whatsapp_groups(params: dict[str, Any]) -> list[dict[str, Any]]:
+ """List WhatsApp groups for the recipient_type='group' selector."""
+
+ from routers.whatsapp import handle_whatsapp_groups as _wa_groups
+
+ response = await _wa_groups()
+ groups = response.get("groups", []) if isinstance(response, dict) else []
+ return [
+ {
+ "value": g.get("group_jid") or g.get("id") or "",
+ "label": g.get("name") or g.get("subject") or g.get("group_jid", ""),
+ }
+ for g in groups
+ ]
+
+
+async def load_whatsapp_channels(params: dict[str, Any]) -> list[dict[str, Any]]:
+ """List subscribed newsletter channels for the channel_jid selector."""
+
+ from routers.whatsapp import handle_whatsapp_newsletters as _wa_newsletters
+
+ response = await _wa_newsletters()
+ channels = response.get("newsletters", []) if isinstance(response, dict) else []
+ return [
+ {
+ "value": c.get("channel_jid") or c.get("id") or "",
+ "label": c.get("name") or c.get("channel_jid", ""),
+ }
+ for c in channels
+ ]
+
+
+async def load_whatsapp_group_members(params: dict[str, Any]) -> list[dict[str, Any]]:
+ """List members of a specific WhatsApp group for the senderNumber
+ selector. Depends on ``params['group_id']``."""
+
+ from routers.whatsapp import handle_whatsapp_group_info as _wa_group_info
+
+ group_id = params.get("group_id") or params.get("groupId") or ""
+ if not group_id:
+ return []
+ response = await _wa_group_info(group_id)
+ participants = (
+ response.get("participants", []) if isinstance(response, dict) else []
+ )
+ return [
+ {
+ "value": p.get("phone") or p.get("jid") or "",
+ "label": p.get("name") or p.get("phone") or p.get("jid", ""),
+ }
+ for p in participants
+ ]
diff --git a/server/tests/test_node_spec.py b/server/tests/test_node_spec.py
index 2f9f1b35..8c6aca5b 100644
--- a/server/tests/test_node_spec.py
+++ b/server/tests/test_node_spec.py
@@ -1,11 +1,12 @@
-"""Wave 6 Phase 1 — NodeSpec contract tests.
+"""Wave 6 NodeSpec contract tests.
Locks in the public shape emitted by services/node_input_schemas.py,
-services/node_spec.py, and the /api/schemas/nodes/*/spec.json endpoint.
+services/node_spec.py, services/node_option_loaders, and the
+/api/schemas/nodes/*/spec.json + /api/schemas/nodes/options/* endpoints.
Mirrors the Wave 3 test posture for node_output_schemas.
"""
-import pytest
+import pytest # noqa: F401 (used by @pytest.mark.asyncio on Phase 4 tests)
from services.node_input_schemas import (
NODE_INPUT_MODELS,
@@ -353,3 +354,31 @@ class TestWave6FullCoverage:
def test_input_model_count_at_least_100(self):
from services.node_input_schemas import NODE_INPUT_MODELS
assert len(NODE_INPUT_MODELS) >= 100
+
+
+class TestPhase4LoadOptions:
+ """Wave 6 Phase 4: unified loadOptionsMethod dispatch registry."""
+
+ def test_registry_has_whatsapp_methods(self):
+ from services.node_option_loaders import LOAD_OPTIONS_REGISTRY
+ for method in ["whatsappGroups", "whatsappChannels", "whatsappGroupMembers"]:
+ assert method in LOAD_OPTIONS_REGISTRY
+
+ def test_list_methods_sorted(self):
+ from services.node_option_loaders import list_load_options_methods
+ methods = list_load_options_methods()
+ assert methods == sorted(methods)
+ assert len(methods) >= 3
+
+ @pytest.mark.asyncio
+ async def test_unknown_method_returns_empty(self):
+ from services.node_option_loaders import dispatch_load_options
+ result = await dispatch_load_options("nonExistentMethodXyz", {})
+ assert result == []
+
+ @pytest.mark.asyncio
+ async def test_dispatch_passes_params(self):
+ # Smoke test: unknown method tolerates arbitrary params, doesn't crash
+ from services.node_option_loaders import dispatch_load_options
+ result = await dispatch_load_options("unknown", {"group_id": "abc"})
+ assert result == []