guzli-cli 0.2.0__py3-none-any.whl

guzli/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "0.2.0"
+
+__all__ = ["__version__", "cli"]

guzli/__main__.py

@@ -0,0 +1,4 @@
+from guzli.cli import main
+
+if __name__ == "__main__":
+    main()

guzli/auth.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Protocol
+
+from guzli.errors import ApiError, ConfigError
+
+
+class AuthProvider(Protocol):
+    @property
+    def mode(self) -> str: ...
+
+    def headers(self) -> dict[str, str]: ...
+
+
+class AuthCapability(str, Enum):
+    API_KEY_OR_BEARER = "api_key_or_bearer"
+    IDENTITY = "identity"
+    BEARER_ONLY = "bearer_only"
+    API_KEY_ONLY = "api_key_only"
+
+
+@dataclass(frozen=True)
+class ApiKeyAuth:
+    api_key: str
+    mode: str = "api_key"
+
+    def headers(self) -> dict[str, str]:
+        return {"X-API-Key": self.api_key}
+
+
+@dataclass(frozen=True)
+class BearerAuth:
+    """Static bearer token. Used when the CLI was configured with a manually pasted
+    JWT (`--bearer-token` / `GUZLI_BEARER_TOKEN`) and we have no refresh handle.
+
+    For OAuth-managed sessions with auto-refresh, see RefreshableBearerAuth."""
+
+    token: str
+    mode: str = "bearer"
+
+    def headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.token}"}
+
+
+# Refresh callback contract: takes the current refresh_handle string and returns
+# (new_access_token, new_refresh_handle, new_expires_at_iso). The implementation
+# typically POSTs to /api/public/v2/auth/cli/oauth/refresh and parses the response.
+RefreshCallback = Callable[[str], tuple[str, str, str]]
+
+# Persist callback contract: called with (access_token, refresh_handle, expires_at_iso)
+# after a successful refresh. Implementation writes back to the StoredProfile so the
+# new tokens survive across CLI invocations.
+PersistCallback = Callable[[str, str, str], None]
+
+
+class RefreshableBearerAuth:
+    """OAuth-managed bearer token with proactive refresh.
+
+    Holds a short-lived engine access token, an opaque refresh handle, and the
+    access token's expiry. On every `headers()` call, checks whether the access
+    token will expire within `refresh_skew_seconds` — if so, calls the engine's
+    /auth/cli/oauth/refresh endpoint via `refresh_callback`, rotates both the
+    access token AND refresh handle, persists the new values via `persist_callback`.
+
+    Stateful (not a frozen dataclass) because refresh mutates the token in-place
+    to amortize across many requests in the same CLI invocation."""
+
+    mode = "bearer"
+
+    def __init__(
+        self,
+        access_token: str,
+        refresh_handle: str,
+        expires_at: str | None,
+        refresh_callback: RefreshCallback,
+        persist_callback: PersistCallback,
+        refresh_skew_seconds: int = 60,
+        server_hint: str | None = None,
+    ) -> None:
+        self._access_token = access_token
+        self._refresh_handle = refresh_handle
+        self._expires_at = _parse_iso(expires_at) if expires_at else None
+        self._refresh_callback = refresh_callback
+        self._persist_callback = persist_callback
+        self._refresh_skew = timedelta(seconds=refresh_skew_seconds)
+        self._server_hint = server_hint
+
+    @property
+    def current_refresh_handle(self) -> str:
+        return self._refresh_handle
+
+    def headers(self) -> dict[str, str]:
+        self._refresh_if_needed()
+        return {"Authorization": f"Bearer {self._access_token}"}
+
+    def _refresh_if_needed(self) -> None:
+        if not self._expires_at:
+            return  # No expiry known — treat as long-lived; never auto-refresh
+        now = datetime.now(timezone.utc)
+        if self._expires_at - now > self._refresh_skew:
+            return  # Not near expiry
+        try:
+            new_access, new_handle, new_expires_iso = self._refresh_callback(self._refresh_handle)
+        except ApiError as exc:
+            # Bubble up with a clearer hint — refresh failures are almost always recoverable
+            # only via re-login, not retry. Surface that explicitly.
+            server = self._server_hint or "this server"
+            if exc.status_code == 404:
+                # Sessions live in each engine's own database; a profile created against
+                # one engine (e.g. local dev) cannot refresh against another (e.g. prod).
+                raise ConfigError(
+                    f"CLI session not found on {server} — sessions are per-environment, "
+                    "so a profile logged in against one engine cannot refresh against another. "
+                    f"Log in to this server first: "
+                    f"`guzli --profile <name> --base-url {server} auth login`."
+                ) from exc
+            raise ConfigError(
+                f"CLI session refresh failed ({exc}). "
+                "Run `guzli auth login --mode oauth --organization-id <uuid>` again."
+            ) from exc
+        self._access_token = new_access
+        self._refresh_handle = new_handle
+        self._expires_at = _parse_iso(new_expires_iso)
+        self._persist_callback(new_access, new_handle, new_expires_iso)
+
+
+@dataclass(frozen=True)
+class AuthSelector:
+    api_key_auth: ApiKeyAuth | None
+    bearer_auth: AuthProvider | None = None  # Either BearerAuth (static) or RefreshableBearerAuth
+
+    def require_api_key(self) -> ApiKeyAuth:
+        if not self.api_key_auth:
+            raise ConfigError("GUZLI_API_KEY is required for this operation")
+        return self.api_key_auth
+
+    def require_bearer(self) -> AuthProvider:
+        if not self.bearer_auth:
+            raise ConfigError(
+                "No CLI session. Run `guzli auth login --mode oauth --organization-id <uuid>` "
+                "to start one, or paste a JWT via GUZLI_BEARER_TOKEN / --bearer-token. "
+                "Credential-sensitive routes (api-keys, webhooks, audit) reject "
+                "API-key auth by design."
+            )
+        return self.bearer_auth
+
+    def select(
+        self,
+        capability: AuthCapability = AuthCapability.API_KEY_OR_BEARER,
+    ) -> AuthProvider:
+        if capability == AuthCapability.BEARER_ONLY:
+            return self.require_bearer()
+        if capability == AuthCapability.API_KEY_ONLY:
+            return self.require_api_key()
+        if capability == AuthCapability.IDENTITY:
+            if self.bearer_auth:
+                return self.bearer_auth
+            if self.api_key_auth:
+                return self.api_key_auth
+            raise ConfigError(
+                "Identity operation requires OAuth bearer auth or an identity-signing API key."
+            )
+        if self.api_key_auth:
+            return self.api_key_auth
+        if self.bearer_auth:
+            return self.bearer_auth
+        raise ConfigError(
+            "No Guzli credentials configured. Run `guzli auth login` or set GUZLI_API_KEY."
+        )
+
+
+def _parse_iso(value: str) -> datetime:
+    """Parse an ISO-8601 datetime. Accepts both `Z` and `+00:00` UTC suffixes."""
+    cleaned = value.replace("Z", "+00:00") if value.endswith("Z") else value
+    parsed = datetime.fromisoformat(cleaned)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed

guzli/cli.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from guzli.commands import (
+    admin,
+    auth,
+    campaigns,
+    conversations,
+    integrations,
+    telephony,
+    voice_calls,
+)
+from guzli.commands.common import print_error
+from guzli.errors import ApiError, GuzliSkillError, ValidationError
+from guzli.runtime import build_context
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        handler = getattr(args, "handler", None)
+        if not handler:
+            raise ValidationError("No command selected")
+        if getattr(args, "auth_only", False):
+            handler(args)
+            return
+        context = build_context(args)
+        handler(context, args)
+    except GuzliSkillError as exc:
+        if getattr(args, "output", "text") == "json":
+            to_dict = getattr(exc, "to_dict", None)
+            error = (
+                to_dict()
+                if callable(to_dict)
+                else {
+                    "code": exc.__class__.__name__.replace("Error", "").lower() or "error",
+                    "message": str(exc),
+                    "retryable": False,
+                }
+            )
+            print(json.dumps({"ok": False, "error": error}, sort_keys=True), file=sys.stderr)
+            raise SystemExit(1) from None
+        print_error(str(exc))
+        if isinstance(exc, ApiError) and exc.detail:
+            print_error(f"Detail: {exc.detail}")
+        raise SystemExit(1) from None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="guzli", description="Guzli CLI for humans and agents")
+    parser.add_argument("--profile", help="Named auth profile from ~/.guzli/config.json")
+    parser.add_argument("--base-url", dest="base_url")
+    parser.add_argument("--api-key", dest="api_key")
+    parser.add_argument(
+        "--bearer-token",
+        dest="bearer_token",
+        help=(
+            "JWT session token (env: GUZLI_BEARER_TOKEN or GUZLI_JWT). "
+            "Required for api-keys / webhooks / audit subcommands."
+        ),
+    )
+    parser.add_argument("--agent-id", dest="agent_id")
+    parser.add_argument("--organization-id", dest="organization_id")
+    parser.add_argument("--timeout-seconds", dest="timeout_seconds", type=int)
+    parser.add_argument(
+        "--output",
+        choices=["text", "json"],
+        default="text",
+        help="Global output mode; JSON mode also emits structured errors",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    conversations.register(subparsers)
+    auth.register(subparsers)
+    integrations.register(subparsers)
+    campaigns.register(subparsers)
+    telephony.register(subparsers)
+    voice_calls.register(subparsers)
+    admin.register(subparsers)
+    return parser

guzli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI adapters. Business behavior belongs in workflows and services."""