caraer-cli 0.1.2__py3-none-any.whl

caraer_cli/__init__.py

@@ -0,0 +1,4 @@
+"""Caraer external developer CLI."""
+
+__all__ = ["__version__"]
+__version__ = "0.1.2"

caraer_cli/api/__init__.py

@@ -0,0 +1 @@
+"""API client modules for Caraer backend domains."""

caraer_cli/api/apps.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+from caraer_cli.api.client import CaraerApiClient
+
+
+def list_apps(
+    client: CaraerApiClient,
+    *,
+    app_type: str,
+    page: int,
+    limit: int,
+    query: str | None = None,
+) -> dict[str, Any]:
+    if app_type == "my":
+        return client.request(
+            "POST",
+            "/api/v2/apps/my/index",
+            json_body={
+                "filters": [],
+                "sort": [{"key": "name", "direction": "asc"}],
+                "show": [],
+                "limit": limit,
+                "page": page,
+                "query": query or "",
+            },
+        )
+    return client.request(
+        "POST",
+        "/api/v2/apps/index",
+        params={"type": app_type},
+        json_body={
+            "filters": [],
+            "sort": [{"key": "name", "direction": "asc"}],
+            "show": [],
+            "limit": limit,
+            "page": page,
+            "query": query or "",
+        },
+    )
+
+
+def get_app(client: CaraerApiClient, app_uuid: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/{app_uuid}")
+
+
+def get_public_app(client: CaraerApiClient, app_uuid: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/public/{app_uuid}")
+
+
+def create_public_app(client: CaraerApiClient, payload: dict[str, Any]) -> dict[str, Any]:
+    return client.request("POST", "/api/v2/apps/public", json_body=payload)
+
+
+def update_public_app(client: CaraerApiClient, app_uuid: str, payload: dict[str, Any]) -> dict[str, Any]:
+    return client.request("PUT", f"/api/v2/apps/public/{app_uuid}", json_body=payload)
+
+
+def migrate_app_to_v2(
+    client: CaraerApiClient,
+    app_uuid: str,
+    *,
+    runtime: str | None = None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {}
+    if runtime:
+        body["runtime"] = runtime
+    return client.request(
+        "POST",
+        f"/api/v2/apps/{app_uuid}/migrate-v2",
+        json_body=body,
+        timeout_seconds=max(client.context.timeout_seconds, 60.0),
+    )
+
+
+def submit_for_review(client: CaraerApiClient, app_uuid: str) -> dict[str, Any]:
+    return client.request("POST", f"/api/v2/apps/public/{app_uuid}/submit")

caraer_cli/api/auth.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+from caraer_cli.api.client import CaraerApiClient
+
+
+def login(client: CaraerApiClient, email: str, password: str) -> dict[str, Any]:
+    return client.request(
+        "POST",
+        "/api/v2/auth/login",
+        json_body={"email": email, "password": password},
+        allow_unauthenticated=True,
+    )
+
+
+def device_start(client: CaraerApiClient) -> dict[str, Any]:
+    return client.request(
+        "POST",
+        "/api/v2/auth/device/start",
+        allow_unauthenticated=True,
+    )
+
+
+def device_poll(client: CaraerApiClient, device_code: str) -> dict[str, Any]:
+    return client.request(
+        "POST",
+        "/api/v2/auth/device/poll",
+        json_body={"deviceCode": device_code},
+        allow_unauthenticated=True,
+    )
+
+
+def refresh(client: CaraerApiClient, refresh_token: str) -> dict[str, Any]:
+    return client.request(
+        "POST",
+        "/api/v2/auth/refresh",
+        json_body={"refreshToken": refresh_token},
+        allow_unauthenticated=True,
+    )
+
+
+def me(client: CaraerApiClient) -> dict[str, Any]:
+    # /auth/me is company-optional; a stale company header causes "Company not found".
+    return client.request("GET", "/api/v2/auth/me", send_company_header=False)
+
+
+def companies(client: CaraerApiClient) -> dict[str, Any]:
+    return client.request("GET", "/api/v2/auth/companies", send_company_header=False)
+
+
+def logout(client: CaraerApiClient) -> dict[str, Any]:
+    return client.request("POST", "/api/v2/auth/logout", send_company_header=False)

caraer_cli/api/client.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+import httpx
+
+from caraer_cli.errors import ApiError, AuthError, parse_api_error
+
+# Serverless create/update can wait on GCP provisioning.
+DEFAULT_TIMEOUT_SECONDS = 120.0
+
+
+@dataclass
+class RequestContext:
+    base_url: str
+    token: str | None
+    company_uuid: str | None
+    sandbox_uuid: str | None = None
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
+    verify_ssl: bool = True
+    debug: bool = False
+    profile_name: str | None = None
+    refresh_token: str | None = None
+    on_tokens_refreshed: Callable[[str, str | None], None] | None = None
+
+
+class CaraerApiClient:
+    def __init__(self, context: RequestContext) -> None:
+        self.context = context
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: dict[str, Any] | None = None,
+        allow_unauthenticated: bool = False,
+        send_company_header: bool = True,
+        send_sandbox_header: bool = True,
+        timeout_seconds: float | None = None,
+        _retried: bool = False,
+    ) -> dict[str, Any]:
+        headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "X-Request-Id": _new_request_id(),
+        }
+        if self.context.token:
+            headers["Authorization"] = f"Bearer {self.context.token}"
+        if send_company_header and self.context.company_uuid:
+            headers["X-Caraer-Company-Uuid"] = self.context.company_uuid
+        # Sandbox management APIs must hit the owner company, not the clone.
+        if send_company_header and send_sandbox_header and self.context.sandbox_uuid:
+            headers["X-Caraer-Sandbox-Uuid"] = self.context.sandbox_uuid
+
+        if not allow_unauthenticated and "Authorization" not in headers:
+            raise ApiError(message="Not logged in. Run 'caraer auth login'.", status=401, payload=None)
+
+        url = self.context.base_url.rstrip("/") + path
+        timeout = timeout_seconds if timeout_seconds is not None else self.context.timeout_seconds
+        try:
+            with httpx.Client(timeout=timeout, verify=self.context.verify_ssl) as client:
+                response = client.request(
+                    method.upper(), url, headers=headers, params=params, json=json_body
+                )
+        except httpx.TimeoutException as exc:
+            raise ApiError(
+                message=(
+                    f"Request timed out after {timeout:.0f}s ({method.upper()} {path}). "
+                    "Serverless function create/update can take a while. "
+                    "Retry, or raise the limit with "
+                    "'caraer profile set --timeout-seconds 300'."
+                ),
+                status=408,
+                payload=None,
+            ) from exc
+        except httpx.TransportError as exc:
+            raise ApiError(
+                message=f"Network error talking to {self.context.base_url}: {exc}",
+                status=503,
+                payload=None,
+            ) from exc
+
+        if response.status_code >= 400:
+            payload = _safe_json(response)
+            # Transparent refresh on 401 when we have a refresh token.
+            if (
+                response.status_code == 401
+                and not _retried
+                and not allow_unauthenticated
+                and self.context.refresh_token
+                and path != "/api/v2/auth/refresh"
+            ):
+                if self._try_refresh():
+                    return self.request(
+                        method,
+                        path,
+                        params=params,
+                        json_body=json_body,
+                        allow_unauthenticated=allow_unauthenticated,
+                        send_company_header=send_company_header,
+                        send_sandbox_header=send_sandbox_header,
+                        timeout_seconds=timeout_seconds,
+                        _retried=True,
+                    )
+            error = parse_api_error(response.status_code, payload)
+            request_id = (
+                (payload or {}).get("requestId")
+                if isinstance(payload, dict)
+                else None
+            ) or response.headers.get("X-Request-Id")
+            if request_id and "Request ID:" not in error.message:
+                error.message = f"{error.message}\nRequest ID: {request_id}"
+            if error.message == "Company not found" and self.context.company_uuid:
+                error.message = (
+                    f"Company not found ({self.context.company_uuid}). "
+                    "Run 'caraer company clear', then 'caraer company list' and "
+                    "'caraer company select <uuid>'."
+                )
+            if self.context.debug:
+                error.message += f"\n[debug] response body: {response.text}"
+            raise error
+
+        payload = _safe_json(response)
+        if payload is None:
+            return {}
+        if isinstance(payload, dict):
+            return payload
+        return {"data": payload}
+
+    def _try_refresh(self) -> bool:
+        refresh_token = self.context.refresh_token
+        if not refresh_token:
+            return False
+        try:
+            response = self.request(
+                "POST",
+                "/api/v2/auth/refresh",
+                json_body={"refreshToken": refresh_token},
+                allow_unauthenticated=True,
+                _retried=True,
+            )
+        except (ApiError, AuthError):
+            return False
+        data = response.get("data") if isinstance(response.get("data"), dict) else response
+        if not isinstance(data, dict):
+            return False
+        access = data.get("accessToken")
+        token_obj = data.get("token")
+        if not access and isinstance(token_obj, dict):
+            access = token_obj.get("token")
+        if not access:
+            return False
+        new_refresh = data.get("refreshToken") or refresh_token
+        self.context.token = str(access)
+        self.context.refresh_token = str(new_refresh) if new_refresh else None
+        if self.context.on_tokens_refreshed:
+            self.context.on_tokens_refreshed(
+                str(access),
+                str(new_refresh) if new_refresh else None,
+            )
+        return True
+
+
+def _new_request_id() -> str:
+    import uuid
+
+    return str(uuid.uuid4())
+
+
+def _safe_json(response: httpx.Response) -> dict[str, Any] | None:
+    try:
+        payload = response.json()
+    except ValueError:
+        return None
+    if isinstance(payload, dict):
+        return payload
+    return {"data": payload}

caraer_cli/api/functions.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any
+
+from caraer_cli.api.client import CaraerApiClient
+
+
+def list_functions(client: CaraerApiClient, app_uuid: str, page: int, limit: int) -> dict[str, Any]:
+    return client.request(
+        "POST",
+        f"/api/v2/apps/{app_uuid}/serverless-functions/index",
+        json_body={
+            "filters": [],
+            "sort": [{"key": "createdAt", "direction": "desc"}],
+            "show": [],
+            "limit": limit,
+            "page": page,
+            "query": "",
+        },
+    )
+
+
+def get_function(client: CaraerApiClient, app_uuid: str, function_uuid: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/{app_uuid}/serverless-functions/{function_uuid}")
+
+
+def create_function(client: CaraerApiClient, app_uuid: str, payload: dict[str, Any]) -> dict[str, Any]:
+    # GCP provisioning regularly exceeds short HTTP timeouts.
+    return client.request(
+        "POST",
+        f"/api/v2/apps/{app_uuid}/serverless-functions",
+        json_body=payload,
+        timeout_seconds=max(client.context.timeout_seconds, 300.0),
+    )
+
+
+def update_function(
+    client: CaraerApiClient, app_uuid: str, function_uuid: str, payload: dict[str, Any]
+) -> dict[str, Any]:
+    return client.request(
+        "PUT",
+        f"/api/v2/apps/{app_uuid}/serverless-functions/{function_uuid}",
+        json_body=payload,
+        timeout_seconds=max(client.context.timeout_seconds, 300.0),
+    )
+
+
+def delete_function(client: CaraerApiClient, app_uuid: str, function_uuid: str) -> dict[str, Any]:
+    return client.request(
+        "DELETE",
+        f"/api/v2/apps/{app_uuid}/serverless-functions/{function_uuid}",
+        timeout_seconds=max(client.context.timeout_seconds, 180.0),
+    )
+
+
+def test_function(
+    client: CaraerApiClient,
+    app_uuid: str,
+    function_uuid: str,
+    record_uuid: str,
+    event_type: str,
+    force_provision: bool = False,
+) -> dict[str, Any]:
+    return client.request(
+        "POST",
+        f"/api/v2/apps/{app_uuid}/serverless-functions/{function_uuid}/test",
+        json_body={
+            "recordUuid": record_uuid,
+            "eventType": event_type,
+            "forceProvision": force_provision,
+        },
+    )

caraer_cli/api/installation.py

@@ -0,0 +1,93 @@
+"""API client for app installation state, secrets, jobs, and connections."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from caraer_cli.api.client import CaraerApiClient
+
+
+def get_state(client: CaraerApiClient, app_uuid: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/{app_uuid}/installation/state")
+
+
+def put_state(client: CaraerApiClient, app_uuid: str, payload: dict[str, Any]) -> dict[str, Any]:
+    return client.request(
+        "PUT",
+        f"/api/v2/apps/{app_uuid}/installation/state",
+        json_body=payload,
+    )
+
+
+def get_state_key(client: CaraerApiClient, app_uuid: str, key: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/{app_uuid}/installation/state/{key}")
+
+
+def put_state_key(
+    client: CaraerApiClient, app_uuid: str, key: str, value: Any
+) -> dict[str, Any]:
+    body = value if isinstance(value, dict) and set(value.keys()) == {"value"} else {"value": value}
+    return client.request(
+        "PUT",
+        f"/api/v2/apps/{app_uuid}/installation/state/{key}",
+        json_body=body,
+    )
+
+
+def delete_state_key(client: CaraerApiClient, app_uuid: str, key: str) -> dict[str, Any]:
+    return client.request("DELETE", f"/api/v2/apps/{app_uuid}/installation/state/{key}")
+
+
+def list_secrets(client: CaraerApiClient, app_uuid: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/{app_uuid}/installation/secrets")
+
+
+def put_secret(
+    client: CaraerApiClient, app_uuid: str, name: str, value: str
+) -> dict[str, Any]:
+    return client.request(
+        "PUT",
+        f"/api/v2/apps/{app_uuid}/installation/secrets/{name}",
+        json_body={"value": value},
+    )
+
+
+def delete_secret(client: CaraerApiClient, app_uuid: str, name: str) -> dict[str, Any]:
+    return client.request("DELETE", f"/api/v2/apps/{app_uuid}/installation/secrets/{name}")
+
+
+def list_connections(client: CaraerApiClient, app_uuid: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/{app_uuid}/installation/connections")
+
+
+def delete_connection(
+    client: CaraerApiClient, app_uuid: str, provider: str
+) -> dict[str, Any]:
+    return client.request(
+        "DELETE", f"/api/v2/apps/{app_uuid}/installation/connections/{provider}"
+    )
+
+
+def enqueue_job(
+    client: CaraerApiClient,
+    app_uuid: str,
+    *,
+    function_name: str,
+    payload: dict[str, Any] | None = None,
+    delay_seconds: float = 0,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "functionName": function_name,
+        "payload": payload or {},
+    }
+    if delay_seconds:
+        body["delaySeconds"] = delay_seconds
+    return client.request(
+        "POST",
+        f"/api/v2/apps/{app_uuid}/installation/jobs",
+        json_body=body,
+    )
+
+
+def get_job(client: CaraerApiClient, app_uuid: str, job_id: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/{app_uuid}/installation/jobs/{job_id}")

caraer_cli/api/integration_runtime.py

@@ -0,0 +1,77 @@
+"""API client for app schedules, inbound routes, and external OAuth providers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from caraer_cli.api.client import CaraerApiClient
+
+
+def list_schedules(client: CaraerApiClient, app_uuid: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/{app_uuid}/schedules")
+
+
+def create_schedule(client: CaraerApiClient, app_uuid: str, payload: dict[str, Any]) -> dict[str, Any]:
+    return client.request("POST", f"/api/v2/apps/{app_uuid}/schedules", json_body=payload)
+
+
+def update_schedule(
+    client: CaraerApiClient, app_uuid: str, schedule_uuid: str, payload: dict[str, Any]
+) -> dict[str, Any]:
+    return client.request(
+        "PUT", f"/api/v2/apps/{app_uuid}/schedules/{schedule_uuid}", json_body=payload
+    )
+
+
+def delete_schedule(client: CaraerApiClient, app_uuid: str, schedule_uuid: str) -> dict[str, Any]:
+    return client.request("DELETE", f"/api/v2/apps/{app_uuid}/schedules/{schedule_uuid}")
+
+
+def list_inbound_routes(client: CaraerApiClient, app_uuid: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/{app_uuid}/inbound-routes")
+
+
+def create_inbound_route(client: CaraerApiClient, app_uuid: str, payload: dict[str, Any]) -> dict[str, Any]:
+    return client.request(
+        "POST", f"/api/v2/apps/{app_uuid}/inbound-routes", json_body=payload
+    )
+
+
+def update_inbound_route(
+    client: CaraerApiClient, app_uuid: str, route_uuid: str, payload: dict[str, Any]
+) -> dict[str, Any]:
+    return client.request(
+        "PUT", f"/api/v2/apps/{app_uuid}/inbound-routes/{route_uuid}", json_body=payload
+    )
+
+
+def delete_inbound_route(client: CaraerApiClient, app_uuid: str, route_uuid: str) -> dict[str, Any]:
+    return client.request("DELETE", f"/api/v2/apps/{app_uuid}/inbound-routes/{route_uuid}")
+
+
+def list_external_oauth_providers(client: CaraerApiClient, app_uuid: str) -> dict[str, Any]:
+    return client.request("GET", f"/api/v2/apps/{app_uuid}/external-oauth-providers")
+
+
+def create_external_oauth_provider(
+    client: CaraerApiClient, app_uuid: str, payload: dict[str, Any]
+) -> dict[str, Any]:
+    return client.request(
+        "POST", f"/api/v2/apps/{app_uuid}/external-oauth-providers", json_body=payload
+    )
+
+
+def update_external_oauth_provider(
+    client: CaraerApiClient, app_uuid: str, provider_uuid: str, payload: dict[str, Any]
+) -> dict[str, Any]:
+    return client.request(
+        "PUT",
+        f"/api/v2/apps/{app_uuid}/external-oauth-providers/{provider_uuid}",
+        json_body=payload,
+    )
+
+
+def delete_external_oauth_provider(
+    client: CaraerApiClient, app_uuid: str, provider_uuid: str
+) -> dict[str, Any]:
+    return client.request("DELETE", f"/api/v2/apps/{app_uuid}/external-oauth-providers/{provider_uuid}")