caraer-cli 0.1.2__py3-none-any.whl

caraer_cli/project/webhooks_sync.py

@@ -0,0 +1,233 @@
+"""Sync webhooks between src/app/webhooks/*.json and the remote API."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from caraer_cli.api import webhooks as webhook_api
+from caraer_cli.api.client import CaraerApiClient
+from caraer_cli.project.paths import webhooks_dir
+from caraer_cli.project.schema import ProjectConfig
+from caraer_cli.project.state import load_state, save_state
+
+LOCAL_WEBHOOK_KEYS = (
+    "uuid",
+    "topic",
+    "deliveryMode",
+    "webhookFormat",
+    "description",
+    "url",
+    "serverlessFunction",
+    "enabled",
+)
+
+
+def _slug(value: str) -> str:
+    text = value.strip().lower()
+    text = re.sub(r"[^a-z0-9]+", "-", text)
+    return text.strip("-") or "webhook"
+
+
+def webhook_filename(item: dict[str, Any]) -> str:
+    topic = str(item.get("topic") or "webhook")
+    mode = str(item.get("deliveryMode") or "").lower()
+    uuid = str(item.get("uuid") or "")[:8]
+    parts = [_slug(topic)]
+    if mode:
+        parts.append(_slug(mode))
+    if uuid:
+        parts.append(uuid)
+    return "-".join(parts) + ".json"
+
+
+def discover_local_webhooks(root: Path, config: ProjectConfig) -> list[tuple[Path, dict[str, Any]]]:
+    base = webhooks_dir(root, config.srcDir)
+    if not base.is_dir():
+        return []
+    found: list[tuple[Path, dict[str, Any]]] = []
+    for path in sorted(base.glob("*.json")):
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            found.append((path, data))
+    return found
+
+
+def _sanitize_local_webhook(item: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = {}
+    for key in LOCAL_WEBHOOK_KEYS:
+        if key in item and item[key] is not None:
+            payload[key] = item[key]
+    # Prefer portable function name over uuid in local files.
+    sf = payload.get("serverlessFunction")
+    if isinstance(sf, dict):
+        name = sf.get("name")
+        uuid = sf.get("uuid")
+        cleaned: dict[str, Any] = {}
+        if name:
+            cleaned["name"] = name
+        elif uuid:
+            cleaned["uuid"] = uuid
+        if cleaned:
+            payload["serverlessFunction"] = cleaned
+        else:
+            payload.pop("serverlessFunction", None)
+    return payload
+
+
+def _resolve_serverless_for_api(
+    payload: dict[str, Any],
+    *,
+    fn_by_name: dict[str, str],
+) -> dict[str, Any]:
+    out = dict(payload)
+    out.pop("uuid", None)  # never send local uuid as create identity unless updating
+    sf = out.get("serverlessFunction")
+    if not isinstance(sf, dict):
+        return out
+    if sf.get("uuid"):
+        out["serverlessFunction"] = {"uuid": sf["uuid"]}
+        return out
+    name = sf.get("name")
+    if name and name in fn_by_name:
+        out["serverlessFunction"] = {"uuid": fn_by_name[name]}
+        return out
+    if name:
+        raise ValueError(
+            f"Webhook references function '{name}' but no UUID is known. "
+            "Push functions first or set serverlessFunction.uuid."
+        )
+    return out
+
+
+def _match_key(item: dict[str, Any]) -> str:
+    topic = str(item.get("topic") or "")
+    mode = str(item.get("deliveryMode") or "")
+    return f"{topic}|{mode}"
+
+
+def push_webhooks(
+    client: CaraerApiClient,
+    root: Path,
+    config: ProjectConfig,
+    *,
+    delete_missing: bool = False,
+) -> dict[str, Any]:
+    if not config.appUuid:
+        raise ValueError("App has no remote UUID. Run 'caraer apps select' or 'caraer apps push'.")
+
+    remote = webhook_api.list_webhooks(client, config.appUuid, page=1, limit=200)
+    remote_items = [i for i in (remote.get("data") or []) if isinstance(i, dict)]
+    by_uuid = {str(i.get("uuid")): i for i in remote_items if i.get("uuid")}
+    by_key = {_match_key(i): i for i in remote_items}
+
+    state = load_state(root)
+    fn_state = state.get("functions") or {}
+    fn_by_name = {
+        name: str(meta["uuid"])
+        for name, meta in fn_state.items()
+        if isinstance(meta, dict) and meta.get("uuid")
+    }
+    wh_state: dict[str, Any] = state.setdefault("webhooks", {})
+
+    results: list[dict[str, Any]] = []
+    local_uuids: set[str] = set()
+    local_keys: set[str] = set()
+
+    for path, raw in discover_local_webhooks(root, config):
+        local = _sanitize_local_webhook(raw)
+        key = _match_key(local)
+        local_keys.add(key)
+        tracked = wh_state.get(path.stem) or {}
+        existing_uuid = str(local.get("uuid") or tracked.get("uuid") or "")
+        remote_item = by_uuid.get(existing_uuid) if existing_uuid else by_key.get(key)
+
+        api_payload = _resolve_serverless_for_api(local, fn_by_name=fn_by_name)
+
+        if remote_item and remote_item.get("uuid"):
+            uuid = str(remote_item["uuid"])
+            local_uuids.add(uuid)
+            response = webhook_api.update_webhook(client, config.appUuid, uuid, api_payload)
+            data = response.get("data") or {}
+            results.append({"file": path.name, "uuid": data.get("uuid", uuid), "action": "updated"})
+            wh_state[path.stem] = {"uuid": data.get("uuid", uuid), "topic": local.get("topic")}
+        else:
+            create_payload = {k: v for k, v in api_payload.items() if k != "uuid"}
+            response = webhook_api.create_webhook(client, config.appUuid, create_payload)
+            data = response.get("data") or {}
+            uuid = data.get("uuid")
+            if uuid:
+                local_uuids.add(str(uuid))
+            results.append({"file": path.name, "uuid": uuid, "action": "created"})
+            if uuid:
+                wh_state[path.stem] = {"uuid": uuid, "topic": local.get("topic")}
+            # Persist uuid back into the local file for stable future matches.
+            if uuid and not raw.get("uuid"):
+                raw["uuid"] = uuid
+                path.write_text(json.dumps(_sanitize_local_webhook(raw), indent=2) + "\n", encoding="utf-8")
+
+    deleted: list[dict[str, Any]] = []
+    if delete_missing:
+        for item in remote_items:
+            uuid = str(item.get("uuid") or "")
+            if not uuid or uuid in local_uuids:
+                continue
+            if _match_key(item) in local_keys:
+                continue
+            webhook_api.delete_webhook(client, config.appUuid, uuid)
+            deleted.append({"uuid": uuid, "topic": item.get("topic"), "action": "deleted"})
+            for stem, meta in list(wh_state.items()):
+                if isinstance(meta, dict) and meta.get("uuid") == uuid:
+                    wh_state.pop(stem, None)
+
+    save_state(root, state)
+    return {"webhooks": results, "deleted": deleted}
+
+
+def pull_webhooks(
+    client: CaraerApiClient,
+    root: Path,
+    config: ProjectConfig,
+) -> dict[str, Any]:
+    if not config.appUuid:
+        raise ValueError("App has no remote UUID. Run 'caraer apps select' or 'caraer apps push'.")
+
+    remote = webhook_api.list_webhooks(client, config.appUuid, page=1, limit=200)
+    remote_items = [i for i in (remote.get("data") or []) if isinstance(i, dict)]
+    base = webhooks_dir(root, config.srcDir)
+    base.mkdir(parents=True, exist_ok=True)
+
+    # Clear previous webhook files for a clean export.
+    for existing in base.glob("*.json"):
+        existing.unlink()
+
+    state = load_state(root)
+    fn_state = state.get("functions") or {}
+    uuid_to_name = {
+        str(meta["uuid"]): name
+        for name, meta in fn_state.items()
+        if isinstance(meta, dict) and meta.get("uuid")
+    }
+    wh_state: dict[str, Any] = {}
+    pulled: list[dict[str, Any]] = []
+
+    for item in remote_items:
+        local = _sanitize_local_webhook(item)
+        sf = local.get("serverlessFunction")
+        if isinstance(sf, dict) and sf.get("uuid"):
+            name = uuid_to_name.get(str(sf["uuid"]))
+            if name:
+                local["serverlessFunction"] = {"name": name}
+        filename = webhook_filename(item)
+        path = base / filename
+        path.write_text(json.dumps(local, indent=2) + "\n", encoding="utf-8")
+        stem = path.stem
+        if item.get("uuid"):
+            wh_state[stem] = {"uuid": item["uuid"], "topic": item.get("topic")}
+        pulled.append({"file": filename, "uuid": item.get("uuid"), "topic": item.get("topic")})
+
+    state["webhooks"] = wh_state
+    save_state(root, state)
+    return {"webhooks": pulled}

caraer_cli/resolve.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from caraer_cli.context import AppContext
+from caraer_cli.local_app import resolve_app_file_path
+
+
+def resolve_app_uuid(app_ctx: AppContext, app_uuid: str | None) -> str:
+    """Resolve a remote app UUID from an explicit arg or the selected profile app."""
+    resolved = (app_uuid or "").strip() or (app_ctx.profile.app_uuid or "").strip()
+    if not resolved:
+        local = (app_ctx.profile.app_file or "").strip()
+        hint = (
+            f" A local app file is selected ({local}); run 'caraer apps push' "
+            "to create it remotely first."
+            if local
+            else ""
+        )
+        raise ValueError(
+            "No remote app selected. Pass an app UUID, or run "
+            "'caraer apps select <uuid>' (after 'caraer apps list')."
+            + hint
+        )
+    return resolved
+
+
+def resolve_app_file(app_ctx: AppContext, app_file: str | None = None) -> Path:
+    """Resolve a local app file from an explicit arg or the selected profile file."""
+    resolved = (app_file or "").strip() or (app_ctx.profile.app_file or "").strip()
+    if not resolved:
+        raise ValueError(
+            "No local app file selected. Pass --file, or run "
+            "'caraer apps select <uuid|path>' / 'caraer apps pull'."
+        )
+    return resolve_app_file_path(resolved)
+
+
+def resolve_optional_file(
+    app_ctx: AppContext,
+    file: str | None,
+    *,
+    required_message: str | None = None,
+) -> Path | None:
+    """Resolve --file, falling back to the selected local app file."""
+    if file:
+        return resolve_app_file_path(file)
+    if app_ctx.profile.app_file:
+        try:
+            return resolve_app_file_path(app_ctx.profile.app_file)
+        except (FileNotFoundError, ValueError):
+            pass
+    if required_message:
+        raise ValueError(required_message)
+    return None

caraer_cli/schemas/app.caraer.schema.json

@@ -0,0 +1,175 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/caraer/caraer-cli/main/schemas/app.caraer.schema.json",
+  "title": "Caraer app manifest (app.caraer.yaml)",
+  "type": "object",
+  "required": ["name", "label", "authMethod", "details"],
+  "additionalProperties": true,
+  "properties": {
+    "uuid": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Remote app UUID (filled after push)."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable machine name."
+    },
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable display name."
+    },
+    "description": { "type": "string" },
+    "runtime": {
+      "type": "string",
+      "enum": ["nodejs22", "python312"],
+      "description": "App-level runtime for platformVersion 2026.2."
+    },
+    "authMethod": {
+      "type": "string",
+      "enum": ["OAUTH2", "API_KEY"]
+    },
+    "oauthRedirectUris": {
+      "type": "array",
+      "items": { "type": "string", "format": "uri" },
+      "description": "Required when authMethod is OAUTH2."
+    },
+    "requiredScopes": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "settingsSchema": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/settingField" }
+    },
+    "pricingPlans": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/pricingPlan" }
+    },
+    "appBars": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/appBar" }
+    },
+    "externalOAuthProviders": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/oauthProvider" }
+    },
+    "webhookRateLimitPerMinute": { "type": "integer", "minimum": 0 },
+    "billFailedWebhookRequests": { "type": "boolean" },
+    "details": {
+      "type": "object",
+      "required": ["category", "brandColor"],
+      "additionalProperties": true,
+      "properties": {
+        "title": { "type": "string" },
+        "description": { "type": "string" },
+        "category": {
+          "type": "string",
+          "description": "Marketplace main category (e.g. developer_tools)."
+        },
+        "subcategories": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "url": { "type": "string", "format": "uri" },
+        "image": { "type": "string" },
+        "brandColor": {
+          "type": "string",
+          "pattern": "^#[0-9A-Fa-f]{6}$"
+        },
+        "textColor": {
+          "type": "string",
+          "pattern": "^#[0-9A-Fa-f]{6}$"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "settingField": {
+      "type": "object",
+      "required": ["name", "type"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "label": { "type": "string" },
+        "type": {
+          "type": "string",
+          "enum": [
+            "SINGLE_LINE",
+            "MULTI_LINE",
+            "SINGLE_SELECT",
+            "MULTI_SELECT",
+            "RECORD_SINGLE_SELECT",
+            "RECORD_MULTI_SELECT",
+            "OBJECT_SINGLE_SELECT",
+            "OBJECT_MULTI_SELECT",
+            "PROPERTY_SINGLE_SELECT",
+            "PROPERTY_MULTI_SELECT",
+            "SWITCH",
+            "MAPPING",
+            "SECRET"
+          ]
+        },
+        "required": { "type": "boolean" },
+        "helpText": { "type": "string" },
+        "defaultValue": {},
+        "options": { "type": "array" },
+        "optionsSource": {}
+      }
+    },
+    "pricingPlan": {
+      "type": "object",
+      "required": ["pricingType"],
+      "additionalProperties": true,
+      "properties": {
+        "title": { "type": "string" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "pricingType": { "type": "string", "enum": ["FLAT", "TIERED"] },
+        "pricePerUnit": { "type": ["number", "string"] },
+        "unit": { "type": "string" },
+        "tiers": { "type": "array" }
+      }
+    },
+    "appBar": {
+      "type": "object",
+      "required": ["location", "label"],
+      "additionalProperties": true,
+      "properties": {
+        "location": {
+          "type": "string",
+          "enum": [
+            "RECORD_PREVIEW",
+            "RECORD_OVERVIEW",
+            "RECORD_DETAIL",
+            "TOOL_BAR",
+            "TRAIT_BAR"
+          ]
+        },
+        "label": { "type": "string", "minLength": 1 },
+        "actionLabel": { "type": "string" },
+        "iframeUrl": { "type": "string" },
+        "webhook": { "type": "object" }
+      }
+    },
+    "oauthProvider": {
+      "type": "object",
+      "required": ["name", "authorizeUrl", "tokenUrl"],
+      "additionalProperties": true,
+      "properties": {
+        "uuid": { "type": "string", "format": "uuid" },
+        "name": { "type": "string", "minLength": 1 },
+        "authorizeUrl": { "type": "string" },
+        "tokenUrl": { "type": "string" },
+        "clientId": { "type": "string" },
+        "logo": { "type": "string" },
+        "scopes": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

caraer_cli/schemas/function.caraer.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/caraer/caraer-cli/main/schemas/function.caraer.schema.json",
+  "title": "Caraer function manifest (function.caraer.json)",
+  "type": "object",
+  "required": ["name", "runtime"],
+  "additionalProperties": true,
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Function name (usually matches the folder name)."
+    },
+    "runtime": {
+      "type": "string",
+      "enum": ["nodejs22", "python312"]
+    },
+    "entry": {
+      "type": "string",
+      "description": "Entrypoint file; defaults to index.js or main.py."
+    },
+    "description": { "type": "string" },
+    "uuid": {
+      "type": "string",
+      "format": "uuid",
+      "description": "Remote function UUID (filled after push)."
+    }
+  }
+}

caraer_cli/schemas/inbound.caraer.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/caraer/caraer-cli/main/schemas/inbound.caraer.schema.json",
+  "title": "Caraer inbound route config",
+  "type": "object",
+  "required": ["name", "serverlessFunction"],
+  "additionalProperties": true,
+  "properties": {
+    "uuid": { "type": "string", "format": "uuid" },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Public route name (path segment)."
+    },
+    "authMode": {
+      "type": "string",
+      "enum": ["NONE", "SHARED_SECRET", "INSTALLATION_TOKEN"],
+      "default": "NONE"
+    },
+    "sharedSecret": {
+      "type": "string",
+      "description": "Recommended when authMode is SHARED_SECRET."
+    },
+    "hasSharedSecret": { "type": "boolean" },
+    "enqueue": {
+      "type": "boolean",
+      "description": "When true, invoke as an installation job."
+    },
+    "description": { "type": "string" },
+    "enabled": { "type": "boolean" },
+    "serverlessFunction": {
+      "$ref": "#/$defs/serverlessFunctionRef"
+    }
+  },
+  "$defs": {
+    "serverlessFunctionRef": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string" },
+        "uuid": { "type": "string", "format": "uuid" }
+      },
+      "anyOf": [
+        { "required": ["name"] },
+        { "required": ["uuid"] }
+      ]
+    }
+  }
+}

caraer_cli/schemas/lifecycle.caraer.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/caraer/caraer-cli/main/schemas/lifecycle.caraer.schema.json",
+  "title": "Caraer lifecycle hook config",
+  "type": "object",
+  "required": ["topic", "deliveryMode"],
+  "additionalProperties": true,
+  "properties": {
+    "topic": {
+      "type": "string",
+      "enum": [
+        "app.installed",
+        "app.uninstalled",
+        "app.rotated",
+        "app.updated"
+      ]
+    },
+    "deliveryMode": {
+      "type": "string",
+      "enum": ["SERVERLESS", "HTTP"]
+    },
+    "enabled": { "type": "boolean" },
+    "description": { "type": "string" },
+    "webhookFormat": { "type": "string" },
+    "secret": { "type": "string" },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Required when deliveryMode is HTTP."
+    },
+    "serverlessFunction": {
+      "$ref": "#/$defs/serverlessFunctionRef",
+      "description": "Required when deliveryMode is SERVERLESS."
+    }
+  },
+  "$defs": {
+    "serverlessFunctionRef": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string" },
+        "uuid": { "type": "string", "format": "uuid" }
+      },
+      "anyOf": [
+        { "required": ["name"] },
+        { "required": ["uuid"] }
+      ]
+    }
+  }
+}

caraer_cli/schemas/schedule.caraer.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/caraer/caraer-cli/main/schemas/schedule.caraer.schema.json",
+  "title": "Caraer schedule config",
+  "type": "object",
+  "required": ["name", "schedule", "serverlessFunction"],
+  "additionalProperties": true,
+  "properties": {
+    "uuid": { "type": "string", "format": "uuid" },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "schedule": {
+      "type": "string",
+      "minLength": 1,
+      "description": "5–6 field cron expression (Spring-style)."
+    },
+    "enabled": { "type": "boolean" },
+    "description": { "type": "string" },
+    "serverlessFunction": {
+      "$ref": "#/$defs/serverlessFunctionRef"
+    }
+  },
+  "$defs": {
+    "serverlessFunctionRef": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string" },
+        "uuid": { "type": "string", "format": "uuid" }
+      },
+      "anyOf": [
+        { "required": ["name"] },
+        { "required": ["uuid"] }
+      ]
+    }
+  }
+}

caraer_cli/schemas/webhook.caraer.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/caraer/caraer-cli/main/schemas/webhook.caraer.schema.json",
+  "title": "Caraer webhook config",
+  "type": "object",
+  "required": ["topic", "deliveryMode"],
+  "additionalProperties": true,
+  "properties": {
+    "uuid": { "type": "string", "format": "uuid" },
+    "topic": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Event topic (e.g. record.created)."
+    },
+    "deliveryMode": {
+      "type": "string",
+      "enum": ["HTTP", "SERVERLESS"]
+    },
+    "webhookFormat": {
+      "type": "string",
+      "enum": ["USER_FRIENDLY", "RAW"]
+    },
+    "description": { "type": "string" },
+    "enabled": { "type": "boolean" },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "Required when deliveryMode is HTTP."
+    },
+    "secret": { "type": "string" },
+    "serverlessFunction": {
+      "$ref": "#/$defs/serverlessFunctionRef",
+      "description": "Required when deliveryMode is SERVERLESS."
+    }
+  },
+  "$defs": {
+    "serverlessFunctionRef": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string" },
+        "uuid": { "type": "string", "format": "uuid" }
+      },
+      "anyOf": [
+        { "required": ["name"] },
+        { "required": ["uuid"] }
+      ]
+    }
+  }
+}