Generate all 122 client actions from the OpenAPI spec

Adds python and python-async flavours to GenerateSdkMethods in the proxy and
wires them up here, taking the method surface from 9 hand-written methods to
122 typed ones on each client.

Generated code lands in its own module, overwritten whole. Nothing
hand-written lives there, so a regeneration cannot lose an edit; _actions.py
keeps the hand-written core (the instance REST routes and the action() call
every generated method is built on) and composes the generated classes in.

Python needs no equivalent of the PHP flavours' instanceId ordering
workaround: required parameters stay positional, everything optional sits
behind a bare star, and instance_id comes last. The star is emitted even for
actions with no optional fields, so a trailing positional argument never means
something different on one method than on another.

The emitters build their output line by line rather than from a heredoc. PHP
strips the closing marker's indentation uniformly, which is fine for a
language that ignores whitespace and wrong for one where it is syntax -- the
first version produced 122 methods with unusable indentation.

Tests go from 25 to 147: one per action, asserting the action name and the
exact payload, with sample values carrying each parameter's own name so a
swap with an adjacent parameter cannot pass.

Author: WaAPIapp

CONTRIBUTING.md

@@ -7,13 +7,30 @@ tools are generated from `storage/swagger.json`, which is why both stay
 current, while a hand-maintained SDK falls behind — the Laravel SDK named 25 of
 122 actions before its methods were generated.
 
-`GenerateSdkMethods` in the proxy repository emits the PHP and Laravel
-flavours today. `src/waapi/_actions.py` is the target for its Python flavour.
-Until that lands, prefer widening `client.action(...)` usage in the README over
-adding hand-written wrappers: every hand-written method is one more place a
+`GenerateSdkMethods` in the proxy repository emits them, with a `python` and a
+`python-async` flavour:
+
+```bash
+python3 scripts/sync_actions.py ../eazewhatsapp-proxy
+# wrote 122 sync and 122 async methods, and 122 tests
+```
+
+That overwrites two files whole, and nothing hand-written lives in either:
+
+- `src/waapi/_generated.py` — `GeneratedActions` and `GeneratedAsyncActions`
+- `tests/test_generated_actions.py` — one payload test per action
+
+The script refuses to write if the two surfaces come out at different sizes or
+if the generator emitted nothing, and it runs `ruff` over its own output, so a
+file marked DO NOT EDIT never needs a human to fix its formatting.
+
+Hand-written methods live in `src/waapi/_actions.py`, which composes the
+generated classes in. Add one there only if it cannot come from the spec — the
+instance endpoints are the current example, because they are ordinary REST
+routes rather than client actions. Anything added by hand is one more place a
 future API change has to reach.
 
-If you do add one by hand, mirror it in **both** `ActionsMixin` and
+If you do add one, mirror it in **both** `ActionsMixin` and
 `AsyncActionsMixin` — `test_sync_and_async_expose_the_same_methods` fails
 otherwise, on purpose.
 

README.md

@@ -80,18 +80,25 @@ except FailedActionError as e:
 
 All inherit from `WaAPIError`.
 
-## Endpoints not wrapped yet
+## Coverage
 
-The API exposes 122 client actions. This release wraps the common ones; every
-other action is reachable by name:
+All **122 client actions** are wrapped, typed, and available on both clients:
 
 ```python
-client.action("send-seen", {"chatId": "4915112345678@c.us"})
-client.action("create-group", {"title": "Ops", "participants": ["4915112345678@c.us"]})
+client.create_group(group_name="Ops", group_participants=["4915112345678@c.us"])
+client.send_media(chat_id="4915112345678@c.us", media_url="https://example.com/report.pdf")
+client.get_contacts()
 ```
 
-The remaining wrappers are generated from the OpenAPI specification rather than
-written by hand — see [CONTRIBUTING.md](CONTRIBUTING.md).
+They are generated from the same OpenAPI specification the n8n node and the MCP
+tools come from, so they track the API instead of drifting behind it — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+An action added to the API since the last release is still reachable by name:
+
+```python
+client.action("some-new-action", {"chatId": "4915112345678@c.us"})
+```
 
 ## Configuration
 

scripts/sync_actions.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Regenerate src/waapi/_generated.py and tests/test_generated_actions.py.
+
+The API has 122 client actions. Writing them by hand would put every future
+API change in four places -- the n8n node, the MCP tools, the PHP SDKs and
+here -- so they are generated from the same OpenAPI specification the others
+use, by `sdk:generate-methods` in the proxy repository.
+
+Everything generated lands in its own module, which this script overwrites
+whole. Nothing hand-written lives there, so a regeneration can never lose
+someone's edit; the hand-written core stays in _actions.py and composes the
+generated classes in.
+
+    python3 scripts/sync_actions.py ../eazewhatsapp-proxy
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+HEADER = '''"""Client actions generated from the WaAPI OpenAPI specification.
+
+DO NOT EDIT. Regenerate with:
+
+    python3 scripts/sync_actions.py ../eazewhatsapp-proxy
+
+Hand-written methods belong in _actions.py, which composes these classes in.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+
+class _Calls:
+    """The contract the mixins rely on, declared for the type checker only."""
+
+    if TYPE_CHECKING:
+
+        def action(
+            self,
+            name: str,
+            payload: dict[str, Any] | None = None,
+            *,
+            instance_id: int | str | None = None,
+        ) -> Any: ...
+'''
+
+TEST_HEADER = '''"""Generated payload tests -- one per client action.
+
+DO NOT EDIT. Regenerate with:
+
+    python3 scripts/sync_actions.py ../eazewhatsapp-proxy
+
+These methods hold no logic: they name an action and forward named arguments.
+So their real failure modes are a wrong action string and a parameter that is
+dropped or swapped with its neighbour, and both are visible in the request
+that leaves the SDK. Sample values carry the parameter's own name for exactly
+that reason -- identical values could not tell a swap from a correct call.
+"""
+
+from __future__ import annotations
+'''
+
+
+def generate(proxy: Path, *args: str) -> str:
+    """Run the generator and return only the emitted code.
+
+    The command reports how many methods it wrote on stdout as well, which is
+    useful in a terminal and a syntax error in a Python file.
+    """
+    result = subprocess.run(
+        [sys.executable and "php", "artisan", "sdk:generate-methods", *args],
+        cwd=proxy,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    body = re.sub(r"^\s*INFO\s+\d+ methods generated\.\s*$", "", result.stdout, flags=re.MULTILINE)
+    return body.rstrip() + "\n"
+
+
+def count_methods(source: str) -> int:
+    return len(re.findall(r"^\s+(?:async )?def \w+\(", source, flags=re.MULTILINE))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("proxy", type=Path, help="path to the eazewhatsapp-proxy checkout")
+    args = parser.parse_args()
+
+    proxy = args.proxy.expanduser().resolve()
+    if not (proxy / "artisan").is_file():
+        raise SystemExit(f"not a Laravel checkout: {proxy}")
+
+    sync = generate(proxy, "--flavour=python")
+    asyncronous = generate(proxy, "--flavour=python-async")
+    tests = generate(proxy, "--flavour=python", "--tests")
+
+    n_sync, n_async = count_methods(sync), count_methods(asyncronous)
+    if n_sync != n_async:
+        raise SystemExit(f"sync/async surfaces differ: {n_sync} vs {n_async}")
+    if n_sync == 0:
+        raise SystemExit("the generator emitted nothing -- check the spec path")
+
+    module = (
+        HEADER
+        + "\n\nclass GeneratedActions(_Calls):\n"
+        + '    """Every client action, blocking."""\n'
+        + sync
+        + "\n\nclass GeneratedAsyncActions(_Calls):\n"
+        + '    """Every client action, awaited."""\n'
+        + asyncronous
+    )
+    (ROOT / "src" / "waapi" / "_generated.py").write_text(module)
+
+    (ROOT / "tests" / "test_generated_actions.py").write_text(TEST_HEADER + tests)
+
+    written = [
+        ROOT / "src" / "waapi" / "_generated.py",
+        ROOT / "tests" / "test_generated_actions.py",
+    ]
+    tidy(written)
+
+    print(f"wrote {n_sync} sync and {n_async} async methods, and {count_tests(tests)} tests")
+    return 0
+
+
+def tidy(paths: list[Path]) -> None:
+    """Bring the generated files up to the project's lint rules.
+
+    Emitting blank lines to PEP 8's satisfaction from a PHP string builder is
+    possible and pointless: the formatter already knows the rules, and letting
+    it run means a lint failure can never be something a human has to fix by
+    hand in a file marked DO NOT EDIT.
+    """
+    for command in (["ruff", "check", "--fix", "--quiet"], ["ruff", "format", "--quiet"]):
+        try:
+            subprocess.run([*command, *map(str, paths)], cwd=ROOT, check=True)
+        except FileNotFoundError:
+            print("ruff not on PATH -- generated files left unformatted", file=sys.stderr)
+            return
+
+
+def count_tests(source: str) -> int:
+    return len(re.findall(r"^def test_", source, flags=re.MULTILINE))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())