@lofa199419/waha-v2 2.1.0

package/README.md

@@ -0,0 +1,50 @@
+# `@lofa199419/waha-v2`
+
+OpenClaw WAHA v2 channel plugin with a packaged local CLI wrapper for WAHA session and messaging operations.
+
+## What ships
+
+- OpenClaw plugin files: `index.ts`, `src/`, `openclaw.plugin.json`
+- Skill docs: `skills/waha-v2/SKILL.md`
+- Local CLI wrappers:
+  - `bin/waha-cli`
+  - `bin/wa`
+  - `bin/wa-adv`
+  - `bin/waha-advanced-entrypoint`
+  - `bin/waha_cli.py`
+
+## Install into an OpenClaw state dir
+
+```bash
+npm install @lofa199419/waha-v2
+node node_modules/@lofa199419/waha-v2/scripts/install-openclaw-extension.mjs --state-dir /data/.openclaw --force
+```
+
+Or with `OPENCLAW_STATE_DIR`:
+
+```bash
+OPENCLAW_STATE_DIR=/data/.openclaw node node_modules/@lofa199419/waha-v2/scripts/install-openclaw-extension.mjs --force
+```
+
+## Runtime configuration
+
+The plugin package does not ship secrets. Provide WAHA configuration through your container or startup flow and render:
+
+```bash
+/data/.openclaw/extensions/waha-v2/bin/.env
+```
+
+Expected values:
+
+```dotenv
+WAHA_URL=https://your-waha-host
+WAHA_API_KEY=your-api-key
+WAHA_SESSION_DEFAULT=power
+```
+
+## Publish checklist
+
+```bash
+npm pack --dry-run
+npm publish --access public
+```

package/bin/wa

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+if [[ -f "$DIR/.env" ]]; then
+  set -a
+  source "$DIR/.env"
+  set +a
+fi
+ARGS=("$@")
+HAS_SESSION=0
+for ((i=0; i<${#ARGS[@]}; i++)); do
+  if [[ "${ARGS[$i]}" == "--session" ]]; then
+    HAS_SESSION=1
+    break
+  fi
+done
+if [[ $HAS_SESSION -eq 0 && -n "${WAHA_SESSION_DEFAULT:-}" ]]; then
+  ARGS+=(--session "$WAHA_SESSION_DEFAULT")
+fi
+exec "$DIR/waha-cli" "${ARGS[@]}"

package/bin/wa-adv

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+if [[ -f "$DIR/.env" ]]; then
+  set -a
+  source "$DIR/.env"
+  set +a
+fi
+exec "$DIR/waha-advanced-entrypoint" "$@"

package/bin/waha-advanced-entrypoint

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+DIR="$(cd "$(dirname "$0")" && pwd)"
+ENTRYPOINT="$DIR/waha_cli.py"
+
+if [[ ! -f "$ENTRYPOINT" ]]; then
+  echo "waha-v2: missing WAHA CLI shim at $ENTRYPOINT" >&2
+  exit 1
+fi
+
+exec python3 "$ENTRYPOINT" "$@"

package/bin/waha-cli

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+DIR="$(cd "$(dirname "$0")" && pwd)"
+ENV_FILE="$DIR/.env"
+if [ -f "$ENV_FILE" ]; then
+  set -a
+  # shellcheck disable=SC1090
+  . "$ENV_FILE"
+  set +a
+fi
+exec "$DIR/waha-advanced-entrypoint" "$@"

package/bin/waha_cli.py

@@ -0,0 +1,549 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import os
+import pathlib
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+VERSION = "3.0.0"
+SCRIPT_DIR = pathlib.Path(__file__).resolve().parent
+OPENCLAW_CHANNEL_ID = "waha-v2"
+DEFAULT_CHARS_PER_SECOND = 12
+DEFAULT_MAX_CHUNK_LENGTH = 1500
+SEEN_DELAY_MS = 3000
+MIN_DELAY_MS = 600
+MAX_DELAY_MS = 8000
+
+
+def env(name: str, default: str | None = None) -> str | None:
+    return os.environ.get(name, default)
+
+
+def state_dir() -> pathlib.Path:
+    configured = env("OPENCLAW_STATE_DIR")
+    if configured:
+        return pathlib.Path(configured)
+    home = pathlib.Path(env("HOME", str(pathlib.Path.home()))).expanduser()
+    return home / ".openclaw"
+
+
+def parse_dotenv(path: pathlib.Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    if not path.exists():
+        return values
+    for raw_line in path.read_text().splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip().strip("'").strip('"')
+    return values
+
+
+def load_openclaw_channel_config() -> dict:
+    config_path = state_dir() / "openclaw.json"
+    if not config_path.exists():
+        return {}
+    try:
+        data = json.loads(config_path.read_text())
+    except Exception:
+        return {}
+    channels = data.get("channels")
+    if not isinstance(channels, dict):
+        return {}
+    channel = channels.get(OPENCLAW_CHANNEL_ID)
+    return channel if isinstance(channel, dict) else {}
+
+
+def resolve_account_config(channel_config: dict, session_name: str | None) -> dict:
+    accounts = channel_config.get("accounts")
+    if not isinstance(accounts, dict):
+        return {}
+    wanted = (session_name or "").strip().lower()
+    if not wanted:
+        return {}
+    exact = accounts.get(session_name)
+    if isinstance(exact, dict):
+        return exact
+    for account_id, config in accounts.items():
+        if not isinstance(config, dict):
+            continue
+        account_name = str(config.get("name", account_id)).strip().lower()
+        account_session = str(config.get("session", "")).strip().lower()
+        if wanted in {str(account_id).strip().lower(), account_name, account_session}:
+            return config
+    return {}
+
+
+def resolved_config(session_name: str | None = None) -> dict[str, str]:
+    dotenv = parse_dotenv(SCRIPT_DIR / ".env")
+    channel = load_openclaw_channel_config()
+    account = resolve_account_config(channel, session_name)
+
+    session_value = (
+        env("WAHA_SESSION_DEFAULT")
+        or env("WAHA_DEFAULT_SESSION")
+        or str(account.get("session", "")).strip()
+        or str(channel.get("session", "")).strip()
+        or dotenv.get("WAHA_SESSION_DEFAULT")
+        or dotenv.get("WAHA_DEFAULT_SESSION")
+        or "default"
+    )
+    return {
+        "WAHA_URL": (
+            str(account.get("baseUrl", "")).strip()
+            or str(channel.get("baseUrl", "")).strip()
+            or env("WAHA_URL")
+            or dotenv.get("WAHA_URL", "")
+        ),
+        "WAHA_API_KEY": (
+            str(account.get("apiKey", "")).strip()
+            or str(channel.get("apiKey", "")).strip()
+            or env("WAHA_API_KEY")
+            or dotenv.get("WAHA_API_KEY", "")
+        ),
+        "WAHA_SESSION_DEFAULT": session_value,
+    }
+
+
+def resolved_typing_config(session_name: str | None = None) -> dict[str, object]:
+    channel = load_openclaw_channel_config()
+    account = resolve_account_config(channel, session_name)
+    typing: dict = channel.get("typing") if isinstance(channel.get("typing"), dict) else {}
+    account_typing: dict = account.get("typing") if isinstance(account.get("typing"), dict) else {}
+
+    def pick(name: str, default):
+        if name in account_typing:
+            return account_typing[name]
+        if name in typing:
+            return typing[name]
+        return default
+
+    return {
+        "enabled": pick("enabled", True) is not False,
+        "chunking": pick("chunking", True) is not False,
+        "charsPerSecond": int(pick("charsPerSecond", DEFAULT_CHARS_PER_SECOND)),
+        "maxChunkLength": int(pick("maxChunkLength", DEFAULT_MAX_CHUNK_LENGTH)),
+        "debug": pick("debug", False) is True,
+    }
+
+
+def require_resolved(name: str, session_name: str | None = None) -> str:
+    value = resolved_config(session_name).get(name, "")
+    if not value:
+        if name == "WAHA_URL" or name == "WAHA_API_KEY":
+            print(
+                f"Missing required config: {name}. Checked channels.{OPENCLAW_CHANNEL_ID} in "
+                f"{state_dir() / 'openclaw.json'}, then environment, then {SCRIPT_DIR / '.env'}",
+                file=sys.stderr,
+            )
+        else:
+            print(f"Missing required config: {name}", file=sys.stderr)
+        sys.exit(2)
+    return value
+
+
+def default_session() -> str:
+    return require_resolved("WAHA_SESSION_DEFAULT")
+
+
+def normalize_base_url(value: str) -> str:
+    return value.rstrip("/")
+
+
+def sleep_ms(delay_ms: int) -> None:
+    time.sleep(max(0, delay_ms) / 1000.0)
+
+
+def calc_typing_delay_ms(text: str, chars_per_second: int) -> int:
+    raw = round((len(text) / max(chars_per_second, 1)) * 1000)
+    return max(MIN_DELAY_MS, min(MAX_DELAY_MS, raw))
+
+
+def chunk_waha_message(text: str, max_length: int) -> list[str]:
+    chunks: list[str] = []
+    paragraphs = text.split("\n\n")
+    for para in paragraphs:
+        trimmed = para.strip()
+        if not trimmed:
+            continue
+        if len(trimmed) <= max_length:
+            chunks.append(trimmed)
+            continue
+        current = trimmed
+        while len(current) > max_length:
+            split_at = max(current.rfind("\n", 0, max_length), current.rfind(" ", 0, max_length))
+            if split_at <= 0:
+                split_at = max_length
+            part = current[:split_at].strip()
+            if part:
+                chunks.append(part)
+            current = current[split_at:].strip()
+        if current:
+            chunks.append(current)
+    if chunks:
+        return chunks
+    stripped = text.strip()
+    return [stripped] if stripped else []
+
+
+def debug_log(enabled: bool, message: str) -> None:
+    if not enabled:
+        return
+    print(f"[waha-cli delivery] {time.strftime('%Y-%m-%dT%H:%M:%S%z')} {message}", file=sys.stderr)
+
+
+def send_presence(endpoint: str, session: str, chat_id: str) -> None:
+    waha_request("POST", endpoint, {"session": session, "chatId": chat_id}, session_name=session)
+
+
+def waha_request(method: str, path: str, body: dict | None = None, query: dict | None = None, session_name: str | None = None):
+    base_url = normalize_base_url(require_resolved("WAHA_URL", session_name))
+    api_key = require_resolved("WAHA_API_KEY", session_name)
+    url = f"{base_url}{path}"
+    if query:
+      filtered = {k: v for k, v in query.items() if v is not None}
+      if filtered:
+        url = f"{url}?{urllib.parse.urlencode(filtered)}"
+    data = None
+    headers = {
+        "X-Api-Key": api_key,
+        "User-Agent": f"waha-cli/{VERSION}",
+        "Accept": "application/json, text/plain;q=0.9, */*;q=0.8",
+    }
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+    req = urllib.request.Request(url, data=data, headers=headers, method=method)
+    try:
+        with urllib.request.urlopen(req) as resp:
+            payload = resp.read()
+            content_type = resp.headers.get("content-type", "")
+            if "application/json" in content_type:
+                return json.loads(payload.decode("utf-8"))
+            return payload.decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        try:
+            error_body = exc.read().decode("utf-8")
+            parsed = json.loads(error_body)
+            message = parsed.get("message", error_body)
+        except Exception:
+            message = exc.reason
+        print(f"WAHA API error ({exc.code}): {message}", file=sys.stderr)
+        sys.exit(1)
+    except urllib.error.URLError as exc:
+        print(f"WAHA API request failed: {exc.reason}", file=sys.stderr)
+        sys.exit(1)
+
+
+def print_json(data):
+    print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def print_help():
+    print(
+        f"""waha-cli v{VERSION}
+
+Usage:
+  waha-cli --help
+  waha-cli --version
+  waha-cli <command> [options]
+
+Session and Auth:
+  waha-list-sessions
+  waha-get-session --session NAME
+  waha-create-session --name NAME
+  waha-start-session --session NAME
+  waha-stop-session --session NAME
+  waha-restart-session --session NAME
+  waha-delete-session --session NAME
+  waha-logout-session --session NAME
+  waha-get-qr-code --session NAME
+  waha-request-pairing-code --session NAME --phone-number NUMBER
+  waha-check-auth-status --session NAME
+
+Chats and Messages:
+  waha-get-chats [--session NAME] [--limit N] [--offset N]
+  waha-get-messages --chat-id ID [--session NAME] [--limit N] [--offset N]
+  waha-send-text --chat-id ID --text TEXT [--session NAME]
+
+Optional env:
+  WAHA_SESSION_DEFAULT / WAHA_DEFAULT_SESSION
+Fallback env:
+  WAHA_URL
+  WAHA_API_KEY
+
+Default config source:
+  OPENCLAW_STATE_DIR/openclaw.json -> channels.waha-v2"""
+    )
+
+
+def add_session_arg(parser):
+    parser.add_argument("--session", default=default_session())
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--help", action="store_true")
+    parser.add_argument("--version", action="store_true")
+    parser.add_argument("command", nargs="?")
+    parser.add_argument("rest", nargs=argparse.REMAINDER)
+    return parser
+
+
+def cmd_list_sessions(_args):
+    print_json(waha_request("GET", "/api/sessions"))
+
+
+def cmd_get_session(args):
+    print_json(waha_request("GET", f"/api/sessions/{urllib.parse.quote(args.session, safe='')}", session_name=args.session))
+
+
+def cmd_create_session(args):
+    body = {"name": args.name}
+    print_json(waha_request("POST", "/api/sessions", body, session_name=args.name))
+
+
+def cmd_simple_post(args, suffix):
+    print_json(
+        waha_request(
+            "POST",
+            f"/api/sessions/{urllib.parse.quote(args.session, safe='')}/{suffix}",
+            session_name=args.session,
+        )
+    )
+
+
+def cmd_delete_session(args):
+    waha_request("DELETE", f"/api/sessions/{urllib.parse.quote(args.session, safe='')}", session_name=args.session)
+    print(f'Session "{args.session}" deleted successfully.')
+
+
+def cmd_logout_session(args):
+    waha_request("POST", f"/api/sessions/{urllib.parse.quote(args.session, safe='')}/logout", session_name=args.session)
+    print(f'Session "{args.session}" logged out successfully.')
+
+
+def cmd_get_qr_code(args):
+    qr = waha_request(
+        "GET",
+        f"/api/{urllib.parse.quote(args.session, safe='')}/auth/qr",
+        query={"format": "raw"},
+        session_name=args.session,
+    )
+    if isinstance(qr, dict) and "value" in qr:
+        qr = qr["value"]
+    print(f'QR Code value for session "{args.session}":')
+    print(qr)
+
+
+def cmd_request_pairing_code(args):
+    result = waha_request(
+        "POST",
+        f"/api/{urllib.parse.quote(args.session, safe='')}/auth/request-code",
+        {"phoneNumber": args.phone_number},
+        session_name=args.session,
+    )
+    code = result.get("code", "<missing>")
+    print(
+        f'Pairing code requested for {args.phone_number} on session "{args.session}".\n'
+        f"Code: {code}\n"
+        "Enter this code in WhatsApp on your phone."
+    )
+
+
+def cmd_check_auth_status(args):
+    info = waha_request("GET", f"/api/sessions/{urllib.parse.quote(args.session, safe='')}", session_name=args.session)
+    messages = {
+        "STOPPED": "Session is stopped. Start it first.",
+        "STARTING": "Session is starting up...",
+        "SCAN_QR_CODE": "Waiting for QR code scan. Use waha-get-qr-code or waha-request-pairing-code.",
+        "WORKING": "Session is authenticated and working.",
+        "FAILED": "Session has failed. Try restarting or re-authenticating.",
+    }
+    text = [
+        f"Session: {args.session}",
+        f"Status: {info.get('status', 'UNKNOWN')}",
+        messages.get(info.get("status"), f"Unknown status: {info.get('status')}"),
+    ]
+    me = info.get("me")
+    if isinstance(me, dict):
+        if me.get("id"):
+            text.append(f"Account ID: {me['id']}")
+        if me.get("pushName"):
+            text.append(f"Name: {me['pushName']}")
+    print("\n".join(text))
+
+
+def cmd_get_chats(args):
+    print_json(
+        waha_request(
+            "GET",
+            f"/api/{urllib.parse.quote(args.session, safe='')}/chats",
+            query={"limit": args.limit, "offset": args.offset},
+            session_name=args.session,
+        )
+    )
+
+
+def cmd_get_messages(args):
+    query = {"limit": args.limit, "offset": args.offset}
+    print_json(
+        waha_request(
+            "GET",
+            f"/api/{urllib.parse.quote(args.session, safe='')}/chats/{urllib.parse.quote(args.chat_id, safe='')}/messages",
+            query=query,
+            session_name=args.session,
+        )
+    )
+
+
+def cmd_send_text(args):
+    typing_cfg = resolved_typing_config(args.session)
+    typing_enabled = bool(typing_cfg["enabled"])
+    chunking_enabled = bool(typing_cfg["chunking"])
+    chars_per_second = int(typing_cfg["charsPerSecond"])
+    max_chunk_length = int(typing_cfg["maxChunkLength"])
+    debug_enabled = bool(typing_cfg["debug"])
+
+    chunks = chunk_waha_message(args.text, max_chunk_length) if chunking_enabled else [args.text.strip()]
+    chunks = [chunk for chunk in chunks if chunk]
+    if not chunks:
+        print("Nothing to send.", file=sys.stderr)
+        sys.exit(1)
+
+    debug_log(debug_enabled, f"queued outbound send chat={args.chat_id} session={args.session}")
+    sleep_ms(SEEN_DELAY_MS)
+    waha_request(
+        "POST",
+        "/api/sendSeen",
+        {"session": args.session, "chatId": args.chat_id},
+        session_name=args.session,
+    )
+    debug_log(debug_enabled, f"marked seen after {SEEN_DELAY_MS}ms chat={args.chat_id}")
+
+    pre_output_typing_started = False
+    if typing_enabled:
+        send_presence("/api/startTyping", args.session, args.chat_id)
+        pre_output_typing_started = True
+        debug_log(debug_enabled, f"pre-output started typing chat={args.chat_id}")
+
+    debug_log(
+        debug_enabled,
+        f"output ready chat={args.chat_id} chunking={chunking_enabled} chunks={len(chunks)} totalLen={len(args.text)}",
+    )
+
+    message_ids: list[str] = []
+    if pre_output_typing_started:
+        send_presence("/api/stopTyping", args.session, args.chat_id)
+        debug_log(debug_enabled, f"pre-output stopped typing chat={args.chat_id}")
+
+    if len(chunks) == 1:
+        result = waha_request(
+            "POST",
+            "/api/sendText",
+            {"session": args.session, "chatId": args.chat_id, "text": chunks[0]},
+            session_name=args.session,
+        )
+        message_ids.append(str(result.get("id", "<missing>")))
+        debug_log(debug_enabled, f"sent single reply chat={args.chat_id} len={len(chunks[0])}")
+    else:
+        for i, chunk in enumerate(chunks):
+            if i > 0 and typing_enabled:
+                send_presence("/api/startTyping", args.session, args.chat_id)
+                debug_log(debug_enabled, f"chunk {i + 1}/{len(chunks)} started typing chat={args.chat_id}")
+                sleep_ms(calc_typing_delay_ms(chunk, chars_per_second))
+                send_presence("/api/stopTyping", args.session, args.chat_id)
+                debug_log(debug_enabled, f"chunk {i + 1}/{len(chunks)} stopped typing chat={args.chat_id}")
+
+            result = waha_request(
+                "POST",
+                "/api/sendText",
+                {"session": args.session, "chatId": args.chat_id, "text": chunk},
+                session_name=args.session,
+            )
+            message_ids.append(str(result.get("id", "<missing>")))
+            debug_log(debug_enabled, f"sent chunk {i + 1}/{len(chunks)} chat={args.chat_id} len={len(chunk)}")
+
+    print("Message sent successfully.")
+    for index, message_id in enumerate(message_ids, start=1):
+        if len(message_ids) == 1:
+            print(f"Message ID: {message_id}")
+        else:
+            print(f"Chunk {index} Message ID: {message_id}")
+
+
+COMMANDS = {
+    "waha-list-sessions": ("List sessions", cmd_list_sessions),
+    "waha-get-session": ("Get session", cmd_get_session),
+    "waha-create-session": ("Create session", cmd_create_session),
+    "waha-start-session": ("Start session", lambda args: cmd_simple_post(args, "start")),
+    "waha-stop-session": ("Stop session", lambda args: cmd_simple_post(args, "stop")),
+    "waha-restart-session": ("Restart session", lambda args: cmd_simple_post(args, "restart")),
+    "waha-delete-session": ("Delete session", cmd_delete_session),
+    "waha-logout-session": ("Logout session", cmd_logout_session),
+    "waha-get-qr-code": ("Get QR code", cmd_get_qr_code),
+    "waha-request-pairing-code": ("Request pairing code", cmd_request_pairing_code),
+    "waha-check-auth-status": ("Check auth status", cmd_check_auth_status),
+    "waha-get-chats": ("Get chats", cmd_get_chats),
+    "waha-list-chats": ("List chats", cmd_get_chats),
+    "waha-get-messages": ("Get messages", cmd_get_messages),
+    "waha-send-text": ("Send text", cmd_send_text),
+}
+
+
+def command_parser(command: str):
+    parser = argparse.ArgumentParser(prog=f"waha-cli {command}")
+    if command in {"waha-get-session", "waha-start-session", "waha-stop-session", "waha-restart-session", "waha-delete-session", "waha-logout-session", "waha-get-qr-code", "waha-check-auth-status"}:
+        add_session_arg(parser)
+    elif command == "waha-create-session":
+        parser.add_argument("--name", required=True)
+    elif command == "waha-request-pairing-code":
+        add_session_arg(parser)
+        parser.add_argument("--phone-number", required=True)
+    elif command in {"waha-get-chats", "waha-list-chats"}:
+        add_session_arg(parser)
+        parser.add_argument("--limit", type=int, default=50)
+        parser.add_argument("--offset", type=int, default=0)
+    elif command == "waha-get-messages":
+        add_session_arg(parser)
+        parser.add_argument("--chat-id", required=True)
+        parser.add_argument("--limit", type=int, default=20)
+        parser.add_argument("--offset", type=int, default=0)
+    elif command == "waha-send-text":
+        add_session_arg(parser)
+        parser.add_argument("--chat-id", required=True)
+        parser.add_argument("--text", required=True)
+    return parser
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.help or not args.command:
+        print_help()
+        return 0
+    if args.version:
+        print(VERSION)
+        return 0
+
+    command = args.command.replace("_", "-")
+    handler_entry = COMMANDS.get(command)
+    if handler_entry is None:
+        print(f"Unknown command: {args.command}", file=sys.stderr)
+        print_help()
+        return 2
+
+    cmd_parser = command_parser(command)
+    cmd_args = cmd_parser.parse_args(args.rest)
+    handler_entry[1](cmd_args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())