iii-sdk 0.11.3.dev2__tar.gz → 0.11.4__tar.gz

{iii_sdk-0.11.3.dev2 → iii_sdk-0.11.4}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: iii-sdk
-Version: 0.11.3.dev2
+Version: 0.11.4
 Summary: III SDK for Python
-Project-URL: Homepage, https://github.com/iii-hq/sdk
-Project-URL: Repository, https://github.com/iii-hq/sdk
+Project-URL: Homepage, https://github.com/iii-hq/iii
+Project-URL: Repository, https://github.com/iii-hq/iii
 Author: III
 License: Apache-2.0
 Keywords: iii,sdk
@@ -53,7 +53,7 @@ iii = register_worker("ws://localhost:49134")
 def greet(data):
     return {"message": f"Hello, {data['name']}!"}
 
-iii.register_function({"id": "greet"}, greet)
+iii.register_function("greet", greet)
 
 iii.register_trigger({
     "type": "http",
@@ -72,7 +72,7 @@ print(result)  # {"message": "Hello, world!"}
 | Operation                | Signature                                         | Description                                            |
 | ------------------------ | ------------------------------------------------- | ------------------------------------------------------ |
 | Initialize               | `register_worker(url, options?)`                  | Create an SDK instance and auto-connect                |
-| Register function        | `iii.register_function({"id": id}, handler)`      | Register a function that can be invoked by name        |
+| Register function        | `iii.register_function(id, handler)`              | Register a function that can be invoked by name        |
 | Register trigger         | `iii.register_trigger({"type": ..., "function_id": ..., "config": ...})` | Bind a trigger (HTTP, cron, queue, etc.) to a function |
 | Invoke (await result)    | `iii.trigger({"function_id": id, "payload": data})` | Invoke a function and wait for the result           |
 | Invoke (fire-and-forget) | `iii.trigger({"function_id": id, ..., "action": TriggerAction.Void()})` | Fire-and-forget |
@@ -86,7 +86,7 @@ print(result)  # {"message": "Hello, world!"}
 def create_order(data):
     return {"status_code": 201, "body": {"id": "123", "item": data["body"]["item"]}}
 
-iii.register_function({"id": "orders.create"}, create_order)
+iii.register_function("orders::create", create_order)
 ```
 
 ### Registering Triggers
@@ -94,7 +94,7 @@ iii.register_function({"id": "orders.create"}, create_order)
 ```python
 iii.register_trigger({
     "type": "http",
-    "function_id": "orders.create",
+    "function_id": "orders::create",
     "config": {"api_path": "/orders", "http_method": "POST"},
 })
 ```
@@ -102,7 +102,7 @@ iii.register_trigger({
 ### Invoking Functions
 
 ```python
-result = iii.trigger({"function_id": "orders.create", "payload": {"body": {"item": "widget"}}})
+result = iii.trigger({"function_id": "orders::create", "payload": {"body": {"item": "widget"}}})
 ```
 
 ## Modules

{iii_sdk-0.11.3.dev2 → iii_sdk-0.11.4}/README.md

@@ -22,7 +22,7 @@ iii = register_worker("ws://localhost:49134")
 def greet(data):
     return {"message": f"Hello, {data['name']}!"}
 
-iii.register_function({"id": "greet"}, greet)
+iii.register_function("greet", greet)
 
 iii.register_trigger({
     "type": "http",
@@ -41,7 +41,7 @@ print(result)  # {"message": "Hello, world!"}
 | Operation                | Signature                                         | Description                                            |
 | ------------------------ | ------------------------------------------------- | ------------------------------------------------------ |
 | Initialize               | `register_worker(url, options?)`                  | Create an SDK instance and auto-connect                |
-| Register function        | `iii.register_function({"id": id}, handler)`      | Register a function that can be invoked by name        |
+| Register function        | `iii.register_function(id, handler)`              | Register a function that can be invoked by name        |
 | Register trigger         | `iii.register_trigger({"type": ..., "function_id": ..., "config": ...})` | Bind a trigger (HTTP, cron, queue, etc.) to a function |
 | Invoke (await result)    | `iii.trigger({"function_id": id, "payload": data})` | Invoke a function and wait for the result           |
 | Invoke (fire-and-forget) | `iii.trigger({"function_id": id, ..., "action": TriggerAction.Void()})` | Fire-and-forget |
@@ -55,7 +55,7 @@ print(result)  # {"message": "Hello, world!"}
 def create_order(data):
     return {"status_code": 201, "body": {"id": "123", "item": data["body"]["item"]}}
 
-iii.register_function({"id": "orders.create"}, create_order)
+iii.register_function("orders::create", create_order)
 ```
 
 ### Registering Triggers
@@ -63,7 +63,7 @@ iii.register_function({"id": "orders.create"}, create_order)
 ```python
 iii.register_trigger({
     "type": "http",
-    "function_id": "orders.create",
+    "function_id": "orders::create",
     "config": {"api_path": "/orders", "http_method": "POST"},
 })
 ```
@@ -71,7 +71,7 @@ iii.register_trigger({
 ### Invoking Functions
 
 ```python
-result = iii.trigger({"function_id": "orders.create", "payload": {"body": {"item": "widget"}}})
+result = iii.trigger({"function_id": "orders::create", "payload": {"body": {"item": "widget"}}})
 ```
 
 ## Modules

{iii_sdk-0.11.3.dev2 → iii_sdk-0.11.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iii-sdk"
-version = "0.11.3.dev2"
+version = "0.11.4"
 description = "III SDK for Python"
 authors = [{ name = "III" }]
 license = { text = "Apache-2.0" }
@@ -27,8 +27,8 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/iii-hq/sdk"
-Repository = "https://github.com/iii-hq/sdk"
+Homepage = "https://github.com/iii-hq/iii"
+Repository = "https://github.com/iii-hq/iii"
 
 [project.optional-dependencies]
 dev = [

{iii_sdk-0.11.3.dev2 → iii_sdk-0.11.4}/src/iii/__init__.py

@@ -21,7 +21,6 @@ from .iii_types import (
     OnTriggerTypeRegistrationInput,
     OnTriggerTypeRegistrationResult,
     RegisterFunctionFormat,
-    RegisterFunctionInput,
     RegisterFunctionMessage,
     RegisterServiceInput,
     RegisterTriggerInput,
@@ -92,7 +91,6 @@ __all__ = [
     "HttpInvocationConfig",
     "MessageType",
     "RegisterFunctionFormat",
-    "RegisterFunctionInput",
     "RegisterFunctionMessage",
     "RegisterServiceInput",
     "RegisterTriggerInput",

{iii_sdk-0.11.3.dev2 → iii_sdk-0.11.4}/src/iii/iii.py

@@ -27,7 +27,6 @@ from .iii_constants import (
     InitOptions,
 )
 from .iii_types import (
-    FunctionInfo,
     HttpInvocationConfig,
     InvocationResultMessage,
     InvokeFunctionMessage,
@@ -44,13 +43,10 @@ from .iii_types import (
     StreamChannelRef,
     TriggerActionEnqueue,
     TriggerActionVoid,
-    TriggerInfo,
     TriggerRequest,
-    TriggerTypeInfo,
     UnregisterFunctionMessage,
     UnregisterTriggerMessage,
     UnregisterTriggerTypeMessage,
-    WorkerInfo,
 )
 from .stream import (
     IStream,
@@ -128,11 +124,6 @@ class III:
         self._reconnect_task: asyncio.Task[None] | None = None
         self._running = False
         self._receiver_task: asyncio.Task[None] | None = None
-        self._functions_available_callbacks: set[
-            Callable[[list[FunctionInfo]], None]
-        ] = set()
-        self._functions_available_trigger: Trigger | None = None
-        self._functions_available_function_id: str | None = None
         self._reconnection_config = (
             self._options.reconnection_config or DEFAULT_RECONNECTION_CONFIG
         )
@@ -796,7 +787,7 @@ class III:
 
     def register_function(
         self,
-        func_or_id: RegisterFunctionInput | dict[str, Any] | str,
+        function_id: str,
         handler_or_invocation: RemoteFunctionHandler | HttpInvocationConfig,
         *,
         description: str | None = None,
@@ -814,27 +805,28 @@ class III:
         block the event loop.  Each handler receives a single ``data``
         argument containing the trigger payload.
 
-        When ``func_or_id`` is a ``str``, the simplified API is used:
         ``request_format`` and ``response_format`` are auto-extracted
-        from the handler's type hints when not explicitly provided.
+        from the handler's type hints when omitted or passed as ``None``
+        (the default).  To opt out of auto-extraction, pass an explicit
+        schema (``RegisterFunctionFormat`` or ``dict``).  This behavior
+        is Python-specific -- the Node SDK does not auto-extract from TS
+        types, because TypeScript types are erased at runtime.
 
         Args:
-            func_or_id: A ``RegisterFunctionInput``, dict with ``id``, or
-                a plain string function ID.  When a string is passed, use
-                keyword arguments for ``description``, ``metadata``,
-                ``request_format``, and ``response_format``.
+            function_id: Unique string identifier for the function.
             handler_or_invocation: A callable handler or
                 ``HttpInvocationConfig``.  Callable handlers receive one
                 positional argument (``data`` -- the trigger payload) and
                 may return a value.
-            description: Human-readable description (only with string ID).
-            metadata: Arbitrary metadata (only with string ID).
-            request_format: Schema describing expected input (only with
-                string ID).  Auto-extracted from handler type hints when
-                omitted.
-            response_format: Schema describing expected output (only with
-                string ID).  Auto-extracted from handler type hints when
-                omitted.
+            description: Human-readable description.
+            metadata: Arbitrary metadata.
+            request_format: Schema describing expected input.  When
+                ``None`` (default), auto-extracted from the handler's
+                first-parameter type hint.  Pass an explicit schema to
+                override; there is no way to register with no schema
+                when the handler is typed.
+            response_format: Schema describing expected output.  Same
+                auto-extraction semantics as ``request_format``.
 
         Returns:
             A ``FunctionRef`` with an ``id`` attribute and an
@@ -842,14 +834,15 @@ class III:
             the function from the engine.
 
         Raises:
-            ValueError: If ``id`` is empty or already registered.
-            TypeError: If ``handler_or_invocation`` is not callable or
+            TypeError: If ``function_id`` is not a string, or if
+                ``handler_or_invocation`` is not callable or
                 ``HttpInvocationConfig``.
+            ValueError: If ``function_id`` is empty or already registered.
 
         Examples:
             >>> def greet(data):
             ...     return {'message': f"Hello, {data['name']}!"}
-            >>> fn = iii.register_function({"id": "greet", "description": "Greets a user"}, greet)
+            >>> fn = iii.register_function("greet", greet, description="Greets a user")
             >>> fn.unregister()
 
             >>> from pydantic import BaseModel
@@ -861,31 +854,29 @@ class III:
             ...     return GreetOutput(message=f"Hello, {data.name}!")
             >>> fn = iii.register_function("greet", greet, description="Greets a user")
         """
-        if isinstance(func_or_id, str):
-            # Simplified API: auto-extract formats from handler type hints
-            handler_for_extraction = (
-                handler_or_invocation if callable(handler_or_invocation) else None
-            )
-            if request_format is None and handler_for_extraction is not None:
-                request_format = extract_request_format(handler_for_extraction)
-            if response_format is None and handler_for_extraction is not None:
-                response_format = extract_response_format(handler_for_extraction)
-            func = RegisterFunctionInput(
-                id=func_or_id,
-                description=description,
-                metadata=metadata,
-                request_format=request_format,
-                response_format=response_format,
+        if not isinstance(function_id, str):
+            raise TypeError(
+                f"function_id must be str, got {type(function_id).__name__}"
             )
-        elif isinstance(func_or_id, dict):
-            func = RegisterFunctionInput(**func_or_id)
-        else:
-            func = func_or_id
-
-        if not func.id or not func.id.strip():
+        if not function_id or not function_id.strip():
             raise ValueError("id is required")
-        if func.id in self._functions:
-            raise ValueError(f"function id '{func.id}' already registered")
+        if function_id in self._functions:
+            raise ValueError(f"function id '{function_id}' already registered")
+
+        handler_for_extraction = (
+            handler_or_invocation if callable(handler_or_invocation) else None
+        )
+        if request_format is None and handler_for_extraction is not None:
+            request_format = extract_request_format(handler_for_extraction)
+        if response_format is None and handler_for_extraction is not None:
+            response_format = extract_response_format(handler_for_extraction)
+        func = RegisterFunctionInput(
+            id=function_id,
+            description=description,
+            metadata=metadata,
+            request_format=request_format,
+            response_format=response_format,
+        )
 
         if isinstance(handler_or_invocation, HttpInvocationConfig):
             msg = RegisterFunctionMessage(
@@ -1096,148 +1087,6 @@ class III:
                 invocation_id=invocation_id,
             )
 
-    def list_functions(self) -> list[FunctionInfo]:
-        """List all functions registered with the engine across all workers.
-
-        Returns:
-            A list of ``FunctionInfo`` objects describing each function.
-
-        Examples:
-            >>> for fn in iii.list_functions():
-            ...     print(fn.function_id, fn.description)
-        """
-        return self._run_on_loop(self.list_functions_async())
-
-    async def list_functions_async(self) -> list[FunctionInfo]:
-        """List all functions registered with the engine across all workers.
-
-        Returns:
-            A list of ``FunctionInfo`` objects describing each function.
-
-        Examples:
-            >>> for fn in await iii.list_functions_async():
-            ...     print(fn.function_id, fn.description)
-        """
-        result = await self.trigger_async(
-            {"function_id": "engine::functions::list", "payload": {}}
-        )
-        functions_data = result.get("functions", [])
-        return [FunctionInfo(**f) for f in functions_data]
-
-    def list_workers(self) -> list[WorkerInfo]:
-        """List all workers currently connected to the engine.
-
-        Returns:
-            A list of ``WorkerInfo`` objects with worker metadata.
-
-        Examples:
-            >>> for w in iii.list_workers():
-            ...     print(w.name, w.worker_id)
-        """
-        return self._run_on_loop(self.list_workers_async())
-
-    async def list_workers_async(self) -> list[WorkerInfo]:
-        """List all workers currently connected to the engine.
-
-        Returns:
-            A list of ``WorkerInfo`` objects with worker metadata.
-
-        Examples:
-            >>> for w in await iii.list_workers_async():
-            ...     print(w.name, w.worker_id)
-        """
-        result = await self.trigger_async(
-            {"function_id": "engine::workers::list", "payload": {}}
-        )
-        workers_data = result.get("workers", [])
-        return [WorkerInfo(**w) for w in workers_data]
-
-    def list_triggers(self, include_internal: bool = False) -> list[TriggerInfo]:
-        """List all triggers registered with the engine.
-
-        Args:
-            include_internal: If ``True``, include engine-internal triggers
-                (e.g. ``functions-available``). Defaults to ``False``.
-
-        Returns:
-            A list of ``TriggerInfo`` objects.
-
-        Examples:
-            >>> triggers = iii.list_triggers()
-            >>> internal = iii.list_triggers(include_internal=True)
-        """
-        return self._run_on_loop(self.list_triggers_async(include_internal))
-
-    async def list_triggers_async(
-        self, include_internal: bool = False
-    ) -> list[TriggerInfo]:
-        """List all triggers registered with the engine.
-
-        Args:
-            include_internal: If ``True``, include engine-internal triggers
-                (e.g. ``functions-available``). Defaults to ``False``.
-
-        Returns:
-            A list of ``TriggerInfo`` objects.
-
-        Examples:
-            >>> triggers = await iii.list_triggers_async()
-            >>> internal = await iii.list_triggers_async(include_internal=True)
-        """
-        result = await self.trigger_async(
-            {
-                "function_id": "engine::triggers::list",
-                "payload": {"include_internal": include_internal},
-            }
-        )
-        triggers_data = result.get("triggers", [])
-        return [TriggerInfo(**t) for t in triggers_data]
-
-    def list_trigger_types(
-        self, include_internal: bool = False
-    ) -> list[TriggerTypeInfo]:
-        """List all trigger types registered with the engine.
-
-        Args:
-            include_internal: If ``True``, include engine-internal trigger
-                types (e.g. ``engine::functions-available``). Defaults to ``False``.
-
-        Returns:
-            A list of ``TriggerTypeInfo`` objects with ``trigger_request_format``
-            and ``call_request_format`` schemas.
-
-        Examples:
-            >>> trigger_types = iii.list_trigger_types()
-            >>> for tt in trigger_types:
-            ...     print(tt.id, tt.trigger_request_format)
-        """
-        return self._run_on_loop(self.list_trigger_types_async(include_internal))
-
-    async def list_trigger_types_async(
-        self, include_internal: bool = False
-    ) -> list[TriggerTypeInfo]:
-        """List all trigger types registered with the engine.
-
-        Args:
-            include_internal: If ``True``, include engine-internal trigger
-                types (e.g. ``engine::functions-available``). Defaults to ``False``.
-
-        Returns:
-            A list of ``TriggerTypeInfo`` objects with ``trigger_request_format``
-            and ``call_request_format`` schemas.
-
-        Examples:
-            >>> trigger_types = await iii.list_trigger_types_async()
-        """
-        result = await self.trigger_async(
-            {
-                "function_id": "engine::trigger-types::list",
-                "payload": {"include_internal": include_internal},
-            }
-        )
-        types_data = result.get("trigger_types", [])
-        return [TriggerTypeInfo(**t) for t in types_data]
-
     def create_channel(self, buffer_size: int | None = None) -> Channel:
         """Create a streaming channel pair for worker-to-worker data transfer.
 
@@ -1258,7 +1107,7 @@ class III:
 
         Examples:
             >>> ch = iii.create_channel()
-            >>> fn = iii.register_function({"id": "producer"}, producer_handler)
+            >>> fn = iii.register_function("producer", producer_handler)
             >>> iii.trigger({"function_id": "producer", "payload": {"output": ch.writer_ref}})
         """
         return self._run_on_loop(self.create_channel_async(buffer_size))
@@ -1279,7 +1128,7 @@ class III:
 
         Examples:
             >>> ch = await iii.create_channel_async()
-            >>> fn = iii.register_function({"id": "producer"}, producer_handler)
+            >>> fn = iii.register_function("producer", producer_handler)
             >>> await iii.trigger_async({"function_id": "producer", "payload": {"output": ch.writer_ref}})
         """
         result = await self.trigger_async(
@@ -1341,69 +1190,6 @@ class III:
         )
         asyncio.run_coroutine_threadsafe(self._send(msg), self._loop)
 
-    def on_functions_available(
-        self, callback: Callable[[list[FunctionInfo]], None]
-    ) -> Callable[[], None]:
-        """Subscribe to function-availability events from the engine.
-
-        The callback fires whenever the set of available functions changes
-        (e.g. a new worker connects or a function is unregistered).
-
-        Args:
-            callback (Callable[[list[FunctionInfo]], None]): Receives the
-                current list of ``FunctionInfo`` objects each time
-                availability changes.
-
-        Returns:
-            A callable that unsubscribes when called.  Calling the
-            returned function removes the callback and, if no callbacks
-            remain, tears down the internal trigger.
-
-        Examples:
-            >>> def on_change(functions):
-            ...     print("Available:", [f.function_id for f in functions])
-            >>> unsub = iii.on_functions_available(on_change)
-            >>> # later ...
-            >>> unsub()
-        """
-        self._functions_available_callbacks.add(callback)
-
-        if not self._functions_available_trigger:
-            if not self._functions_available_function_id:
-                self._functions_available_function_id = (
-                    f"iii.on_functions_available.{uuid.uuid4()}"
-                )
-
-            function_id = self._functions_available_function_id
-            if function_id not in self._functions:
-
-                async def handler(data: dict[str, Any]) -> None:
-                    functions_data = data.get("functions", [])
-                    functions = [FunctionInfo(**f) for f in functions_data]
-                    for cb in list(self._functions_available_callbacks):
-                        cb(functions)
-
-                self.register_function({"id": function_id}, handler)
-
-            self._functions_available_trigger = self.register_trigger(
-                {
-                    "type": "engine::functions-available",
-                    "function_id": function_id,
-                    "config": {},
-                }
-            )
-
-        def unsubscribe() -> None:
-            self._functions_available_callbacks.discard(callback)
-            if (
-                len(self._functions_available_callbacks) == 0
-                and self._functions_available_trigger
-            ):
-                self._functions_available_trigger.unregister()
-                self._functions_available_trigger = None
-
-        return unsubscribe
-
     def create_stream(self, stream_name: str, stream: IStream[Any]) -> None:
         """Register a custom stream implementation, overriding the engine default.
 
@@ -1451,12 +1237,12 @@ class III:
             )
             return await stream.list_groups(input_data)
 
-        self.register_function({"id": f"stream::get({stream_name})"}, get_handler)
-        self.register_function({"id": f"stream::set({stream_name})"}, set_handler)
-        self.register_function({"id": f"stream::delete({stream_name})"}, delete_handler)
-        self.register_function({"id": f"stream::list({stream_name})"}, list_handler)
+        self.register_function(f"stream::get({stream_name})", get_handler)
+        self.register_function(f"stream::set({stream_name})", set_handler)
+        self.register_function(f"stream::delete({stream_name})", delete_handler)
+        self.register_function(f"stream::list({stream_name})", list_handler)
         self.register_function(
-            {"id": f"stream::list_groups({stream_name})"}, list_groups_handler
+            f"stream::list_groups({stream_name})", list_groups_handler
         )
 
 

{iii_sdk-0.11.3.dev2 → iii_sdk-0.11.4}/src/iii/stream.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import Any, Generic, List, Literal, TypeVar
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 TData = TypeVar("TData")
 
@@ -91,6 +91,20 @@ class StreamUpdateInput(BaseModel):
     ops: list["UpdateOp"]
 
 
+class UpdateOpError(BaseModel):
+    """Per-op error returned by ``state::update`` / ``stream::update``.
+
+    Currently emitted only by the ``merge`` op when input violates the
+    new validation bounds. Successfully applied ops are still
+    reflected in the response's ``new_value``.
+    """
+
+    op_index: int
+    code: str
+    message: str
+    doc_url: str | None = None
+
+
 class StreamSetResult(BaseModel, Generic[TData]):
     """Result of stream set operation."""
 
@@ -103,6 +117,12 @@ class StreamUpdateResult(BaseModel, Generic[TData]):
 
     old_value: TData | None = None
     new_value: TData
+    # Per-op errors. Currently emitted only by the ``merge`` op for
+    # validation rejections. Field is omitted from the JSON wire when
+    # empty. ``default_factory`` is used (not ``= []``) to keep
+    # Pydantic's parameterized-Generic + default handling well-behaved
+    # across Python versions.
+    errors: list[UpdateOpError] = Field(default_factory=list)
 
 
 class StreamDeleteResult(BaseModel):
@@ -135,6 +155,14 @@ class UpdateDecrement(BaseModel):
     by: int | float
 
 
+class UpdateAppend(BaseModel):
+    """Append operation for stream update."""
+
+    type: str = "append"
+    path: str
+    value: Any
+
+
 class UpdateRemove(BaseModel):
     """Remove operation for stream update."""
 
@@ -143,14 +171,42 @@ class UpdateRemove(BaseModel):
 
 
 class UpdateMerge(BaseModel):
-    """Merge operation for stream update."""
+    """Shallow merge an object into the target.
+
+    The target is the root (when ``path`` is omitted, an empty string,
+    or an empty list) or an arbitrary nested location specified by an
+    array of literal segments.
+
+    Path forms accepted:
+      - ``None`` / ``""`` / ``[]``: merge at the root.
+      - ``"foo"``: equivalent to ``["foo"]`` -- single first-level key.
+      - ``["a", "b", "c"]``: nested path. Each element is a *literal*
+        key. ``["a.b"]`` writes a single key named ``"a.b"``, not
+        ``a -> b``.
+
+    Engine semantics:
+      - Missing or non-object intermediates along the path are
+        auto-replaced with ``{}``.
+      - The merge is shallow at the target node (top-level keys of
+        ``value`` overwrite same-named keys; siblings preserved).
+
+    Validation: invalid paths/values (depth > 32 segments, segment >
+    256 bytes, value depth > 16, > 1024 top-level keys, or any
+    ``__proto__`` / ``constructor`` / ``prototype`` segment or
+    top-level key) are rejected with a structured error in the
+    ``errors`` array of the ``state::update`` / ``stream::update``
+    response. The merge does not apply when an error is returned.
+    """
 
     type: str = "merge"
-    path: str
+    # Optional. Accepts a single string or a list of literal segments.
+    # Pydantic resolves ``str | list[str]`` via smart-union: string
+    # input -> str, array input -> list[str].
+    path: str | list[str] | None = None
     value: Any
 
 
-UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateRemove | UpdateMerge
+UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateAppend | UpdateRemove | UpdateMerge
 
 
 class StreamTriggerConfig(BaseModel):