feat(int-evolution-go): exponential backoff + jitter on api_request (PR-2)

.claude/skills/int-evolution-go/scripts/evolution_go_client.py

@@ -6,7 +6,11 @@
 import argparse
 import json
 import os
+import random
+import socket
 import sys
+import time
+import urllib.error
 import urllib.parse
 import urllib.request
 from pathlib import Path
@@ -43,38 +47,103 @@ def get_config():
     return url.rstrip("/"), key
 
 
+def _backoff_retry_or_log_final(attempt, max_attempts, base_delay, max_delay, extras):
+    """Sleep with exponential backoff + jitter, ou loga falha final.
+
+    Centraliza a lógica idêntica que estava duplicada nos branches 5xx
+    (HTTPError) e URLError/socket.timeout do retry loop. `extras` carrega
+    as chaves variantes do log (`http_status` ou `error`).
+    """
+    if attempt < max_attempts - 1:
+        delay = min(base_delay * (2 ** attempt) + random.uniform(0, 0.5), max_delay)
+        print(
+            json.dumps({
+                "evt": "api_request_retry",
+                "attempt": attempt + 1,
+                "max_attempts": max_attempts,
+                **extras,
+                "delay_s": round(delay, 2),
+            })
+        )
+        time.sleep(delay)
+    else:
+        print(
+            json.dumps({
+                "evt": "api_request_failed",
+                "attempt": attempt + 1,
+                "max_attempts": max_attempts,
+                **extras,
+                "category": "transient",
+            })
+        )
+
+
+def _retry_http_call_client(do_call, max_attempts=3, base_delay=2.0, max_delay=8.0):
+    """Exponential backoff + jitter for Evolution Go API calls.
+
+    Retries on HTTP 5xx, urllib.error.URLError, and socket.timeout (transient).
+    NEVER retries on HTTP 4xx (deterministic client errors).
+
+    Returns the result of do_call() on success.
+    Raises the last exception after max_attempts are exhausted.
+    Raises immediately on HTTP 4xx (no retry).
+    Raises ValueError if max_attempts < 1 (caller error).
+    """
+    if max_attempts < 1:
+        raise ValueError("max_attempts must be >= 1")
+
+    last_exc = None
+    for attempt in range(max_attempts):
+        try:
+            return do_call()
+        except urllib.error.HTTPError as e:
+            if e.code < 500:
+                # 4xx — deterministic, raise immediately (caller decides sys.exit vs raise)
+                raise
+            last_exc = e
+            _backoff_retry_or_log_final(
+                attempt, max_attempts, base_delay, max_delay,
+                {"http_status": e.code},
+            )
+        except (urllib.error.URLError, socket.timeout) as e:
+            last_exc = e
+            _backoff_retry_or_log_final(
+                attempt, max_attempts, base_delay, max_delay,
+                {"error": str(e)},
+            )
+    raise last_exc
+
+
 def api_request(method, path, data=None):
-    """Make an HTTP request to the Evolution Go API."""
+    """Make an HTTP request to the Evolution Go API.
+
+    Applies exponential backoff + jitter on HTTP 5xx / network errors (up to 3 attempts).
+    On HTTP 4xx: raises urllib.error.HTTPError immediately (no retry, deterministic error).
+    On persistent failure after retries: raises the last exception instead of sys.exit(1),
+    allowing library callers to handle it; CLI __main__ catches and sys.exit(1) as before.
+    """
     base_url, api_key = get_config()
     url = f"{base_url}{path}"
 
     body = json.dumps(data).encode("utf-8") if data else None
-    req = urllib.request.Request(
-        url,
-        data=body,
-        method=method,
-        headers={
-            "apikey": api_key,
-            "Content-Type": "application/json",
-        },
-    )
 
-    try:
+    def _do_call():
+        req = urllib.request.Request(
+            url,
+            data=body,
+            method=method,
+            headers={
+                "apikey": api_key,
+                "Content-Type": "application/json",
+            },
+        )
         with urllib.request.urlopen(req) as resp:
             raw = resp.read()
             if raw:
                 return json.loads(raw)
             return {"message": "success"}
-    except urllib.error.HTTPError as e:
-        try:
-            error_body = json.loads(e.read())
-        except Exception:
-            error_body = {"error": str(e)}
-        print(json.dumps({"error": f"HTTP {e.code}", "details": error_body}, indent=2))
-        sys.exit(1)
-    except urllib.error.URLError as e:
-        print(json.dumps({"error": f"Connection failed: {e.reason}"}))
-        sys.exit(1)
+
+    return _retry_http_call_client(_do_call)
 
 
 def to_jid(number):
@@ -523,12 +592,23 @@ def main():
     }
 
     handler = commands.get(args.command)
-    if handler:
-        handler(args)
-    else:
+    if not handler:
         print(json.dumps({"error": f"Unknown command: {args.command}"}))
         sys.exit(1)
 
+    try:
+        handler(args)
+    except urllib.error.HTTPError as e:
+        try:
+            error_body = json.loads(e.read())
+        except Exception:
+            error_body = {"error": str(e)}
+        print(json.dumps({"error": f"HTTP {e.code}", "details": error_body}, indent=2))
+        sys.exit(1)
+    except (urllib.error.URLError, socket.timeout) as e:
+        print(json.dumps({"error": f"Connection failed: {e}"}))
+        sys.exit(1)
+
 
 if __name__ == "__main__":
     main()

.env.example

@@ -108,6 +108,13 @@ META_APP_SECRET=
 LINKEDIN_CLIENT_ID=
 LINKEDIN_CLIENT_SECRET=
 
+# ── License — headless auto-activation ───────────────
+# Set this to the email used in your first manual license registration.
+# On startup, EvoNexus calls /v1/register/auto silently and skips the manual
+# setup screen. Falls back to manual setup if the email isn't registered yet.
+# Leave empty (or unset) to keep the default behavior.
+# EVOLUTION_OPERATOR_EMAIL=operator@example.com
+
 # ── Evolution API ────────────────────────────────────
 # Your Evolution API instance URL and global API key
 EVOLUTION_API_URL=

CONTRIBUTING.md

@@ -12,7 +12,7 @@ Harassment, discrimination, or abusive behavior will not be tolerated.
 
 ### Reporting Bugs
 
-1. Check existing [issues](https://github.com/EvolutionAPI/evo-nexus/issues)
+1. Check existing [issues](https://github.com/evolution-foundation/evo-nexus/issues)
    to avoid duplicates
 2. Open a new issue with:
    - Clear, descriptive title

README.md

@@ -15,7 +15,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/EvolutionAPI/evo-nexus/releases/latest"><img src="https://img.shields.io/github/v/release/EvolutionAPI/evo-nexus?include_prereleases&label=version&color=00ffa7" alt="Latest version" /></a>
+  <a href="https://github.com/evolution-foundation/evo-nexus/releases/latest"><img src="https://img.shields.io/github/v/release/evolution-foundation/evo-nexus?include_prereleases&label=version&color=00ffa7" alt="Latest version" /></a>
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" /></a>
   <a href="https://docs.evolutionfoundation.com.br"><img src="https://img.shields.io/badge/Docs-evolutionfoundation.com.br-00ffa7" alt="Documentation" /></a>
   <a href="https://evolutionfoundation.com.br/community"><img src="https://img.shields.io/badge/Community-Join%20us-white" alt="Community" /></a>
@@ -46,7 +46,7 @@ It turns a single CLI installation into a team of **38 specialized agents** orga
 
 ## Part of the Evolution Foundation ecosystem
 
-EvoNexus is one of the projects maintained by Evolution Foundation. It is the operating layer that orchestrates the Foundation's own work — including the development of [Evo CRM Community](https://github.com/EvolutionAPI/evo-crm-community), [Evolution API](https://github.com/EvolutionAPI/evolution-api) and [Evolution Go](https://github.com/EvolutionAPI/evolution-go).
+EvoNexus is one of the projects maintained by Evolution Foundation. It is the operating layer that orchestrates the Foundation's own work — including the development of [Evo CRM Community](https://github.com/evolution-foundation/evo-crm-community), [Evolution API](https://github.com/evolution-foundation/evolution-api) and [Evolution Go](https://github.com/evolution-foundation/evolution-go).
 
 ### Why EvoNexus?
 
@@ -101,7 +101,7 @@ EvoNexus is one of the projects maintained by Evolution Foundation. It is the op
 ### Method 1 — Docker (no setup, runs anywhere)
 
 ```bash
-curl -O https://raw.githubusercontent.com/EvolutionAPI/evo-nexus/main/docker-compose.hub.yml
+curl -O https://raw.githubusercontent.com/evolution-foundation/evo-nexus/main/docker-compose.hub.yml
 docker compose -f docker-compose.hub.yml up -d
 open http://localhost:8080
 ```
@@ -117,7 +117,7 @@ npx @evoapi/evo-nexus
 ### Method 3 — Manual clone (developers / contributors)
 
 ```bash
-git clone --depth 1 https://github.com/EvolutionAPI/evo-nexus.git
+git clone --depth 1 https://github.com/evolution-foundation/evo-nexus.git
 cd evo-nexus
 
 # Interactive setup wizard

dashboard/backend/app.py

@@ -613,6 +613,43 @@ def _cors_allowed_origins():
         except Exception:
             pass
     _conn.commit()
+
+    # --- WhatsApp retry pattern: idempotency_key + error_category + last_replay_at (PR-1 2026-05-11) ---
+    # Rollback: DROP INDEX uq_trigger_idem; DROP INDEX ix_trigger_executions_idem_key
+    # Columns are nullable — old code ignores them without breaking.
+    _te_cols = {row[1] for row in _cur.execute("PRAGMA table_info(trigger_executions)").fetchall()}
+    if "idempotency_key" not in _te_cols:
+        _cur.execute("ALTER TABLE trigger_executions ADD COLUMN idempotency_key TEXT")
+        _conn.commit()
+    if "error_category" not in _te_cols:
+        _cur.execute("ALTER TABLE trigger_executions ADD COLUMN error_category TEXT")
+        _conn.commit()
+    if "last_replay_at" not in _te_cols:
+        _cur.execute("ALTER TABLE trigger_executions ADD COLUMN last_replay_at TIMESTAMP")
+        _conn.commit()
+    # Basic index for idempotency lookups by key alone
+    try:
+        _cur.execute(
+            "CREATE INDEX IF NOT EXISTS ix_trigger_executions_idem_key "
+            "ON trigger_executions (idempotency_key)"
+        )
+        _conn.commit()
+    except Exception:
+        pass
+    # Partial unique index: enforces (trigger_id, idempotency_key) uniqueness only when key IS NOT NULL.
+    # SQLite >= 3.8 supports partial indices natively; our runtime is 3.51 (confirmed).
+    # This is the DB-level guard against race-condition duplicates (Step 2 handles app-level dedup).
+    try:
+        _cur.execute(
+            "CREATE UNIQUE INDEX IF NOT EXISTS uq_trigger_idem "
+            "ON trigger_executions (trigger_id, idempotency_key) "
+            "WHERE idempotency_key IS NOT NULL"
+        )
+        _conn.commit()
+    except Exception:
+        pass
+    # --- End WhatsApp retry pattern migration ---
+
     _conn.close()
     # --- End auto-migrate ---
 

dashboard/backend/licensing.py

@@ -4,12 +4,14 @@
 
 Protocol:
   POST /v1/register/direct  — register with email/name, receive api_key
+  POST /v1/register/auto    — headless register by email (must exist server-side)
   POST /v1/activate         — validate existing api_key on startup
   GET  /api/geo             — geo-lookup from client IP
 """
 
 import hashlib
 import hmac as hmac_mod
+import os
 import socket
 import uuid
 import logging
@@ -155,6 +157,24 @@ def direct_register(email: str, name: str, instance_id: str,
     return _post("/v1/register/direct", payload)
 
 
+# ── Auto Registration (email-only, headless) ──
+
+def auto_register(email: str, instance_id: str) -> dict:
+    """Headless registration using only the operator email.
+
+    The customer must already exist on the licensing server (one prior manual
+    registration). Used by the EVOLUTION_OPERATOR_EMAIL env-var flow.
+
+    Returns {api_key, customer_id, tier, status}.
+    """
+    return _post("/v1/register/auto", {
+        "email": email,
+        "tier": TIER,
+        "instance_id": instance_id,
+        "version": VERSION,
+    })
+
+
 # ── Activation (startup with existing api_key) ──
 
 def activate(instance_id: str, api_key: str) -> bool:
@@ -260,8 +280,54 @@ def initialize_runtime():
 
 # ── Auto-register for existing installs ──────
 
+def try_auto_register_from_env(instance_id: str) -> bool:
+    """Headless activation via EVOLUTION_OPERATOR_EMAIL env var.
+
+    Requires the email to already exist on the licensing server (one prior
+    manual registration). Returns True on success.
+
+    Failures are silent — caller falls back to the existing admin-based or
+    manual setup flow.
+    """
+    email = os.environ.get("EVOLUTION_OPERATOR_EMAIL", "").strip()
+    if not email:
+        return False
+
+    try:
+        result = auto_register(email=email, instance_id=instance_id)
+    except requests.HTTPError as e:
+        status = e.response.status_code if e.response is not None else "?"
+        if status == 404:
+            logger.info("Auto-activation skipped — email not registered yet (first time?).")
+        else:
+            logger.warning(f"Auto-activation rejected ({status}): falling back to manual flow.")
+        return False
+    except Exception as e:
+        logger.warning(f"Auto-activation skipped — {e}")
+        return False
+
+    api_key = result.get("api_key")
+    if not api_key:
+        logger.warning("Auto-activation response missing api_key")
+        return False
+
+    set_runtime_config("api_key", api_key)
+    set_runtime_config("tier", result.get("tier", TIER))
+    if result.get("customer_id"):
+        set_runtime_config("customer_id", str(result["customer_id"]))
+    set_runtime_config("version", VERSION)
+    set_runtime_config("registered_at", datetime.now(timezone.utc).isoformat())
+
+    ctx = get_context()
+    ctx.api_key = api_key
+    ctx.instance_id = instance_id
+    logger.info("License activated automatically via EVOLUTION_OPERATOR_EMAIL")
+    return True
+
+
 def auto_register_if_needed():
-    """If users exist but no license, register retroactively."""
+    """If no license yet, try EVOLUTION_OPERATOR_EMAIL first, then fall back to
+    the admin-based retroactive flow."""
     try:
         instance_id = get_runtime_config("instance_id")
         api_key = get_runtime_config("api_key")
@@ -270,6 +336,15 @@ def auto_register_if_needed():
             initialize_runtime()
             return
 
+        if not instance_id:
+            instance_id = generate_instance_id()
+            set_runtime_config("instance_id", instance_id)
+
+        # First-class path: silent activation from env var.
+        if try_auto_register_from_env(instance_id):
+            return
+
+        # Fallback: if there's an admin user already, register retroactively.
         from models import User
         if User.query.count() == 0:
             return
@@ -278,10 +353,6 @@ def auto_register_if_needed():
         if not admin or not admin.email:
             return
 
-        if not instance_id:
-            instance_id = generate_instance_id()
-            set_runtime_config("instance_id", instance_id)
-
         setup_perform(
             email=admin.email or "",
             name=admin.display_name or admin.username,