tktl-cli 0.1.0a1__py3-none-any.whl

tktl/api/__init__.py

@@ -0,0 +1,29 @@
+"""Taktile API client layer."""
+
+from tktl.api.client import TktlClient
+from tktl.api.execution import run_flow
+from tktl.api.flows import create_flow, get_flow_by_slug, list_flows
+from tktl.api.versions import (
+    create_version,
+    delete_version,
+    duplicate_version,
+    get_changes,
+    get_version,
+    patch_version,
+    put_version,
+)
+
+__all__ = [
+    "TktlClient",
+    "create_flow",
+    "create_version",
+    "delete_version",
+    "duplicate_version",
+    "get_changes",
+    "get_flow_by_slug",
+    "get_version",
+    "list_flows",
+    "patch_version",
+    "put_version",
+    "run_flow",
+]

tktl/api/client.py

@@ -0,0 +1,154 @@
+"""Thin HTTP client wrapping httpx with auth, base URL, and retry logic."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from tktl.config import Config, Credentials, _DEFAULT_CONFIG_DIR
+from tktl.models.errors import AuthError, NetworkError
+
+DEFAULT_BASE_URL = "https://flow-api.taktile.com"
+
+# Retry settings for network errors
+_MAX_RETRIES = 3
+_BACKOFF_DELAYS = [1, 2, 4]  # seconds
+
+
+class TktlClient:
+    """Synchronous HTTP client for the Taktile Flow API.
+
+    Reads config and credentials from disk (or accepts explicit overrides).
+    Attaches ``X-Api-Key`` header to every request.
+    Retries network errors with exponential backoff.
+    """
+
+    def __init__(
+        self,
+        config_dir: Path = _DEFAULT_CONFIG_DIR,
+        *,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        # Load config from disk
+        config = Config(config_dir)
+        config.load()
+
+        # Determine base URL
+        if base_url is not None:
+            self._base_url = base_url
+        else:
+            self._base_url = config.get("flow_api_url") or DEFAULT_BASE_URL
+
+        # Determine API key
+        if api_key is not None:
+            self._api_key = api_key
+            self._user_id: str | None = None
+        else:
+            creds = Credentials(config_dir)
+            creds.load()
+            if not creds.api_key:
+                raise AuthError("No API key found. Run `tktl auth login` to authenticate.")
+            self._api_key = creds.api_key
+            self._user_id = creds.user_id
+
+        self._config = config
+
+        # Build the httpx client
+        self._http = httpx.Client(
+            base_url=self._base_url,
+            headers={"X-Api-Key": self._api_key},
+            transport=transport,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    # ---- HTTP verbs ----
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._request("GET", path, params=params, headers=headers)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._request("POST", path, json=json, params=params, headers=headers)
+
+    def patch(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._request("PATCH", path, json=json, params=params, headers=headers)
+
+    def put(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._request("PUT", path, json=json, params=params, headers=headers)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._request("DELETE", path, json=json, params=params, headers=headers)
+
+    # ---- internal ----
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        """Send an HTTP request with retry logic for network errors."""
+        last_exc: Exception | None = None
+
+        for attempt in range(_MAX_RETRIES + 1):
+            try:
+                return self._http.request(
+                    method,
+                    path,
+                    json=json,
+                    params=params,
+                    headers=headers,
+                )
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                if attempt < _MAX_RETRIES:
+                    time.sleep(_BACKOFF_DELAYS[attempt])
+                    continue
+                raise NetworkError(str(exc)) from exc
+
+        # Should not reach here, but satisfy type checker
+        raise NetworkError(str(last_exc))  # pragma: no cover

tktl/api/comments.py

@@ -0,0 +1,99 @@
+"""Comment API functions.
+
+Comments are per-flow-version and can be attached to nodes or the version itself.
+Create uses PUT /api/v1/comments/{comment_id} (client-generated ID).
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from tktl.api.client import TktlClient
+from tktl.models.errors import NotFoundError
+
+
+def list_comments(
+    client: TktlClient,
+    flow_version_id: str,
+    *,
+    resource_type: str | None = None,
+    resource_id: str | None = None,
+) -> list[dict[str, Any]]:
+    """List comments for a flow version.
+
+    GET /api/v1/comments?flow_version_id=...
+    """
+    params: dict[str, str] = {"flow_version_id": flow_version_id}
+    if resource_type is not None:
+        params["resource_type"] = resource_type
+    if resource_id is not None:
+        params["resource_id"] = resource_id
+
+    resp = client.get("/api/v1/comments", params=params)
+    if resp.status_code == 200:
+        return resp.json()
+    resp.raise_for_status()
+    return []  # pragma: no cover
+
+
+def create_comment(
+    client: TktlClient,
+    flow_version_id: str,
+    content: str,
+    *,
+    resource_type: str | None = None,
+    resource_id: str | None = None,
+) -> dict[str, Any]:
+    """Create a comment on a flow version or node.
+
+    PUT /api/v1/comments/{comment_id}  (client-generated UUID)
+    """
+    comment_id = str(uuid.uuid4())
+    body: dict[str, Any] = {
+        "content": content,
+        "flow_version": flow_version_id,
+    }
+    if resource_type is not None:
+        body["resource_type"] = resource_type
+    if resource_id is not None:
+        body["resource_id"] = resource_id
+
+    resp = client.put(f"/api/v1/comments/{comment_id}", json=body)
+    if resp.status_code == 200:
+        return resp.json()
+    if resp.status_code == 404:
+        raise NotFoundError(f"Flow version '{flow_version_id}' not found")
+    resp.raise_for_status()
+    return {}  # pragma: no cover
+
+
+def delete_comment(
+    client: TktlClient,
+    comment_id: str,
+) -> None:
+    """Delete a comment.
+
+    DELETE /api/v1/comments/{comment_id}
+    """
+    resp = client.delete(f"/api/v1/comments/{comment_id}")
+    if resp.status_code == 404:
+        raise NotFoundError(f"Comment '{comment_id}' not found")
+    resp.raise_for_status()
+
+
+def get_comment_summary(
+    client: TktlClient,
+    flow_version_id: str,
+) -> list[dict[str, Any]]:
+    """Get per-node comment counts for a flow version.
+
+    GET /api/v1/comments/summary/{flow_version_id}
+    """
+    resp = client.get(f"/api/v1/comments/summary/{flow_version_id}")
+    if resp.status_code == 200:
+        return resp.json()
+    if resp.status_code == 404:
+        raise NotFoundError(f"Flow version '{flow_version_id}' not found")
+    resp.raise_for_status()
+    return []  # pragma: no cover

tktl/api/connections.py

@@ -0,0 +1,86 @@
+"""Workspace connections API.
+
+The Connect API is per-workspace and lives on the workspace base URL:
+GET   {base_url}/connect/api/v1/connections                  — list all connections
+POST  {base_url}/connect/api/v1/connections                  — create a connection
+POST  {base_url}/connect/api/v1/connections/{id}/resources   — create a resource config
+PATCH {base_url}/connect/api/v1/connections/{id}/secrets      — update secrets
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from tktl.models.errors import NetworkError
+
+
+def list_connections(api_key: str, base_url: str) -> list[dict[str, Any]]:
+    """List all connections in the workspace.
+
+    GET {base_url}/connect/api/v1/connections
+    """
+    url = f"{base_url}/connect/api/v1/connections"
+
+    try:
+        resp = httpx.get(url, headers={"X-Api-Key": api_key}, timeout=15.0)
+    except httpx.HTTPError as exc:
+        raise NetworkError(f"Failed to list connections: {exc}") from exc
+
+    if resp.status_code == 200:
+        return resp.json()
+    raise NetworkError(f"Failed to list connections: HTTP {resp.status_code}")
+
+
+def create_connection(api_key: str, base_url: str, body: dict[str, Any]) -> dict[str, Any]:
+    """Create a new connection.
+
+    POST {base_url}/connect/api/v1/connections
+    """
+    url = f"{base_url}/connect/api/v1/connections"
+
+    try:
+        resp = httpx.post(url, json=body, headers={"X-Api-Key": api_key}, timeout=15.0)
+    except httpx.HTTPError as exc:
+        raise NetworkError(f"Failed to create connection: {exc}") from exc
+
+    if resp.status_code in (200, 201):
+        return resp.json()
+    raise NetworkError(f"Failed to create connection: HTTP {resp.status_code}")
+
+
+def create_resource_config(api_key: str, base_url: str, connection_id: str, body: dict[str, Any]) -> dict[str, Any]:
+    """Create a resource config on a connection.
+
+    POST {base_url}/connect/api/v1/connections/{connection_id}/resources
+    """
+    url = f"{base_url}/connect/api/v1/connections/{connection_id}/resources"
+
+    try:
+        resp = httpx.post(url, json=body, headers={"X-Api-Key": api_key}, timeout=15.0)
+    except httpx.HTTPError as exc:
+        raise NetworkError(f"Failed to create resource config: {exc}") from exc
+
+    if resp.status_code in (200, 201):
+        return resp.json()
+    raise NetworkError(f"Failed to create resource config: HTTP {resp.status_code}")
+
+
+def update_secrets(
+    api_key: str, base_url: str, connection_id: str, secrets: list[dict[str, Any]]
+) -> list[dict[str, Any]]:
+    """Update secrets on a connection.
+
+    PATCH {base_url}/connect/api/v1/connections/{connection_id}/secrets
+    """
+    url = f"{base_url}/connect/api/v1/connections/{connection_id}/secrets"
+
+    try:
+        resp = httpx.patch(url, json=secrets, headers={"X-Api-Key": api_key}, timeout=15.0)
+    except httpx.HTTPError as exc:
+        raise NetworkError(f"Failed to update secrets: {exc}") from exc
+
+    if resp.status_code == 200:
+        return resp.json()
+    raise NetworkError(f"Failed to update secrets: HTTP {resp.status_code}")