plugsync-cli 0.1.1__tar.gz → 0.4.0__tar.gz

{plugsync_cli-0.1.1 → plugsync_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugsync-cli
-Version: 0.1.1
+Version: 0.4.0
 Summary: Command-line client for plugsync HubSpot connectors -- manage connectors and plugins like code, no repo checkout required
 Author-email: Exelab <hello@plugsync.com>
 License: Proprietary
@@ -33,8 +33,12 @@ Requires-Dist: respx>=0.21; extra == "dev"
 
 Command-line client for [plugsync](https://plugsync.com), managing HubSpot
 connectors like code: pull a connector's config to a local directory, edit
-it, push it back, diff against the remote, validate, preview a publish, and
-manage plugins -- all without cloning the plugsync backend repo.
+it, push it back to the draft, diff against a published version, validate,
+preview a publish, and manage plugins -- all without cloning the plugsync
+backend repo.
+
+`push` writes the draft and stops. Publishing is opt-in (`push --publish`),
+so a config never reaches production as a side effect of saving a file.
 
 ## Install
 
@@ -47,14 +51,16 @@ Requires Python 3.12+.
 ## Quickstart
 
 ```bash
-plugsync config set api_url https://app.plugsync.com
 plugsync auth login -e you@example.com
 plugsync pull my-connector
 ```
 
-`plugsync auth login` saves a bearer credential to `~/.plugsync/config.yaml`
-that every subsequent command reuses. `PLUGSYNC_API_URL` / `PLUGSYNC_API_KEY`
-environment variables override the config file, handy for CI.
+`api_url` defaults to the hosted platform (`https://app.plugsync.com`), so
+there's nothing to configure for the common case. Point it elsewhere with
+`plugsync config set api_url <url>`. `plugsync auth login` saves a bearer
+credential to `~/.plugsync/config.yaml` that every subsequent command
+reuses. `PLUGSYNC_API_URL` / `PLUGSYNC_API_KEY` environment variables
+override the config file, handy for CI.
 
 ## Commands
 
@@ -62,13 +68,13 @@ environment variables override the config file, handy for CI.
 |---|---|
 | `plugsync auth login` / `logout` | Authenticate (email/password JWT, or a long-lived org API key with `--token`) |
 | `plugsync config set/get/show` | Manage `~/.plugsync/config.yaml` |
-| `plugsync pull <name>` | Download a connector as a local directory |
-| `plugsync push <name>` | Upload a local connector directory |
-| `plugsync diff <name>` | Diff local vs. remote working state |
-| `plugsync validate <name>` | Validate a local connector config |
-| `plugsync preview <name>` | Preview a publish's effects |
-| `plugsync log <name>` | Show a connector's revision history |
-| `plugsync rollback <name>` | Restore a previous revision |
+| `plugsync pull <name>` | Download a connector's draft as a local directory (`--revision N` for a published version) |
+| `plugsync push <name>` | Upload a local connector directory to the draft (`--publish` to also publish) |
+| `plugsync diff <name>` | Diff local files vs. a published version |
+| `plugsync validate <name>` | Preflight the draft; non-zero exit on an error |
+| `plugsync preview <name>` | Preview a publish's effects and its preflight findings |
+| `plugsync log <name>` | Show a connector's published version history |
+| `plugsync rollback <name>` | Restore a published version into the draft |
 | `plugsync plugin init/push/list/status/logs/metrics/invoke/promote/publish/rollback` | Author and manage plugins (Enterprise tier) |
 
 Run `plugsync --help` or `plugsync <command> --help` for the full option list.

{plugsync_cli-0.1.1 → plugsync_cli-0.4.0}/README.md

@@ -2,8 +2,12 @@
 
 Command-line client for [plugsync](https://plugsync.com), managing HubSpot
 connectors like code: pull a connector's config to a local directory, edit
-it, push it back, diff against the remote, validate, preview a publish, and
-manage plugins -- all without cloning the plugsync backend repo.
+it, push it back to the draft, diff against a published version, validate,
+preview a publish, and manage plugins -- all without cloning the plugsync
+backend repo.
+
+`push` writes the draft and stops. Publishing is opt-in (`push --publish`),
+so a config never reaches production as a side effect of saving a file.
 
 ## Install
 
@@ -16,14 +20,16 @@ Requires Python 3.12+.
 ## Quickstart
 
 ```bash
-plugsync config set api_url https://app.plugsync.com
 plugsync auth login -e you@example.com
 plugsync pull my-connector
 ```
 
-`plugsync auth login` saves a bearer credential to `~/.plugsync/config.yaml`
-that every subsequent command reuses. `PLUGSYNC_API_URL` / `PLUGSYNC_API_KEY`
-environment variables override the config file, handy for CI.
+`api_url` defaults to the hosted platform (`https://app.plugsync.com`), so
+there's nothing to configure for the common case. Point it elsewhere with
+`plugsync config set api_url <url>`. `plugsync auth login` saves a bearer
+credential to `~/.plugsync/config.yaml` that every subsequent command
+reuses. `PLUGSYNC_API_URL` / `PLUGSYNC_API_KEY` environment variables
+override the config file, handy for CI.
 
 ## Commands
 
@@ -31,13 +37,13 @@ environment variables override the config file, handy for CI.
 |---|---|
 | `plugsync auth login` / `logout` | Authenticate (email/password JWT, or a long-lived org API key with `--token`) |
 | `plugsync config set/get/show` | Manage `~/.plugsync/config.yaml` |
-| `plugsync pull <name>` | Download a connector as a local directory |
-| `plugsync push <name>` | Upload a local connector directory |
-| `plugsync diff <name>` | Diff local vs. remote working state |
-| `plugsync validate <name>` | Validate a local connector config |
-| `plugsync preview <name>` | Preview a publish's effects |
-| `plugsync log <name>` | Show a connector's revision history |
-| `plugsync rollback <name>` | Restore a previous revision |
+| `plugsync pull <name>` | Download a connector's draft as a local directory (`--revision N` for a published version) |
+| `plugsync push <name>` | Upload a local connector directory to the draft (`--publish` to also publish) |
+| `plugsync diff <name>` | Diff local files vs. a published version |
+| `plugsync validate <name>` | Preflight the draft; non-zero exit on an error |
+| `plugsync preview <name>` | Preview a publish's effects and its preflight findings |
+| `plugsync log <name>` | Show a connector's published version history |
+| `plugsync rollback <name>` | Restore a published version into the draft |
 | `plugsync plugin init/push/list/status/logs/metrics/invoke/promote/publish/rollback` | Author and manage plugins (Enterprise tier) |
 
 Run `plugsync --help` or `plugsync <command> --help` for the full option list.

{plugsync_cli-0.1.1 → plugsync_cli-0.4.0}/plugsync_cli/__init__.py

@@ -1,2 +1,2 @@
 """PluSync CLI — git-like connector management."""
-__version__ = "0.1.0"
+__version__ = "0.4.0"

plugsync_cli-0.4.0/plugsync_cli/client.py

@@ -0,0 +1,351 @@
+"""HTTP client wrapper for PluSync REST API."""
+import json
+
+import httpx
+
+from plugsync_cli.compat import check_api_compat
+from plugsync_cli.config import get_api_key, get_api_url
+
+
+class DraftConflict(Exception):
+    """The draft moved on since the version the caller read.
+
+    Carries the draft version the server currently holds, so a command can tell
+    the user what to re-pull instead of surfacing a bare 409.
+    """
+
+    def __init__(self, current_version: int | None):
+        self.current_version = current_version
+        super().__init__(
+            "the connector draft changed since it was pulled"
+            + (f" (server is at draft v{current_version})" if current_version else "")
+        )
+
+
+def _render_detail(detail) -> str:
+    """The backend's `detail` as one readable block.
+
+    FastAPI answers a string for a hand-raised HTTPException, a dict for the
+    structured ones (draft conflicts, upgrade payloads), and a list of
+    per-field entries for a request-validation failure. The last one carries
+    the precise Pydantic error, which is exactly what an operator who mistyped
+    a config key needs to see.
+    """
+    if isinstance(detail, str):
+        return detail
+    if isinstance(detail, list):
+        lines = []
+        for entry in detail:
+            if isinstance(entry, dict) and "msg" in entry:
+                location = ".".join(str(part) for part in entry.get("loc", []))
+                lines.append(f"{location}: {entry['msg']}" if location else entry["msg"])
+            else:
+                lines.append(json.dumps(entry, ensure_ascii=False))
+        return "\n  ".join([""] + lines)
+    return json.dumps(detail, ensure_ascii=False, indent=2)
+
+
+def describe_http_error(exc: httpx.HTTPStatusError) -> str:
+    """A non-2xx turned into something an operator can act on.
+
+    Without this the CLI dies on the raw `raise_for_status()` traceback and
+    throws away the response body, which is where the backend says what is
+    actually wrong.
+    """
+    response, request = exc.response, exc.request
+    summary = (
+        f"{request.method} {request.url.path} failed "
+        f"(HTTP {response.status_code} {response.reason_phrase})"
+    )
+    try:
+        payload = response.json()
+    except ValueError:
+        body = (response.text or "").strip()
+        return f"{summary}: {body}" if body else summary
+
+    detail = payload.get("detail", payload) if isinstance(payload, dict) else payload
+    return f"{summary}: {_render_detail(detail)}"
+
+
+def _conflict_version(response: httpx.Response) -> int | None:
+    """The `current_version` the draft API reports in its 409 detail."""
+    try:
+        detail = response.json().get("detail")
+    except ValueError:
+        return None
+    return detail.get("current_version") if isinstance(detail, dict) else None
+
+
+class PlugSyncClient:
+    """Thin wrapper around httpx for PluSync API calls."""
+
+    def __init__(self, api_url: str | None = None, api_key: str | None = None):
+        self.api_url = api_url or get_api_url()
+        self.api_key = api_key or get_api_key()
+        if not self.api_key:
+            raise RuntimeError(
+                "No API key configured. Run 'plugsync config set api_key <key>' "
+                "or set PLUGSYNC_API_KEY environment variable."
+            )
+        try:
+            check_api_compat(self.api_url)
+        except Exception:
+            # Compat check is advisory only (issue #957): never let it
+            # block a command from running, even if it misbehaves.
+            pass
+        self.headers = {"Authorization": f"Bearer {self.api_key}"}
+
+    def _url(self, path: str) -> str:
+        return f"{self.api_url}/api{path}"
+
+    def _client(self) -> httpx.Client:
+        return httpx.Client(headers=self.headers, timeout=60.0)
+
+    def list_connectors(self) -> list[dict]:
+        with self._client() as c:
+            r = c.get(self._url("/connectors"))
+            r.raise_for_status()
+            return r.json()
+
+    def find_connector(self, name: str) -> dict | None:
+        connectors = self.list_connectors()
+        for conn in connectors:
+            if conn["name"] == name:
+                return conn
+        return None
+
+    def get_connector(self, connector_id: str) -> dict:
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}"))
+            r.raise_for_status()
+            return r.json()
+
+    def get_draft(self, connector_id: str) -> dict:
+        """The connector's editable config (backend DraftResponse).
+
+        The draft is the CLI's read AND write surface for the current config:
+        there is no server-side export, the config travels as JSON and the
+        directory format is produced locally by `serializer.py` (#1241).
+        """
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}/draft"))
+            r.raise_for_status()
+            return r.json()
+
+    def put_draft(
+        self, connector_id: str, config: dict, expected_version: int | None = None
+    ) -> dict:
+        """Replace the whole draft config. Never publishes.
+
+        `expected_version` is the `draft_version` the caller last read: the
+        backend rejects the write with 409 if the draft moved on since, which
+        is what keeps a `pull` -> edit -> `push` cycle from silently discarding
+        someone else's dashboard edit. Raises `DraftConflict` on that 409.
+        """
+        params = {} if expected_version is None else {"expected_version": expected_version}
+        with self._client() as c:
+            r = c.put(
+                self._url(f"/connectors/{connector_id}/draft"),
+                json=config,
+                params=params,
+            )
+            if r.status_code == 409:
+                raise DraftConflict(_conflict_version(r))
+            r.raise_for_status()
+            return r.json()
+
+    def config_surface(self) -> dict:
+        """The config catalogue: actions, transforms, when, sources, json_schema.
+
+        `json_schema` is `ConnectorConfigV3.model_json_schema()`, defaults
+        included: it is how `plugsync diff` knows which values the server wrote
+        from a schema default rather than the operator (#1259). Org-scoped
+        auth only -- the catalogue itself is the same for every org.
+        """
+        with self._client() as c:
+            r = c.get(self._url("/config-surface"))
+            r.raise_for_status()
+            return r.json()
+
+    def get_version(self, connector_id: str, version: int) -> dict:
+        """One published config version, config included (backend VersionResponse)."""
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}/versions/{version}"))
+            r.raise_for_status()
+            return r.json()
+
+    def preflight(self, connector_id: str) -> dict:
+        """Preflight findings on the draft, split into errors/warnings/infos."""
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}/preflight"))
+            r.raise_for_status()
+            return r.json()
+
+    def preview(self, connector_id: str) -> dict:
+        """What publishing the draft would change against the active version."""
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}/preview"))
+            r.raise_for_status()
+            return r.json()
+
+    def publish(
+        self, connector_id: str, change_summary: str | None = None, force: bool = False,
+    ) -> dict:
+        """`force` (#1367, DX-61): publish a new version even when the draft
+        is identical to the active one - the values a publish resolves (plugin
+        ARN/version, HubSpot schema) can drift without any draft edit. Unrelated
+        to `plugsync push --force`, which discards a concurrent DRAFT edit."""
+        with self._client() as c:
+            body = {}
+            if change_summary:
+                body["change_summary"] = change_summary
+            if force:
+                body["force"] = True
+            r = c.post(self._url(f"/connectors/{connector_id}/publish"), json=body)
+            r.raise_for_status()
+            return r.json()
+
+    def list_revisions(self, connector_id: str) -> list[dict]:
+        """Published config versions, newest first (backend: app/api/versions.py).
+
+        The endpoint is `/versions`: Plan 6a replaced the `/revisions` API the
+        CLI used to call, which is why `plugsync log` answered 404 (#1244).
+        """
+        with self._client() as c:
+            r = c.get(self._url(f"/connectors/{connector_id}/versions"))
+            r.raise_for_status()
+            return r.json()
+
+    def restore_revision(self, connector_id: str, version: int) -> dict:
+        """Copy a published version back into the draft, returning the draft.
+
+        Does not publish: the restored config becomes the connector's draft and
+        needs an explicit publish to go live.
+        """
+        with self._client() as c:
+            r = c.post(self._url(f"/connectors/{connector_id}/versions/{version}/restore"))
+            r.raise_for_status()
+            return r.json()
+
+    # ------------------------------------------------------------------
+    # Plugin API (T10, issue #190)
+    # ------------------------------------------------------------------
+
+    def plugin_create(self, name: str, capabilities: list[str] | None = None) -> dict:
+        """Create a new plugin (status=draft)."""
+        body: dict = {"name": name}
+        if capabilities is not None:
+            body["capabilities"] = capabilities
+        with self._client() as c:
+            r = c.post(self._url("/plugins"), json=body)
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_list(self) -> list[dict]:
+        """List all plugins for the current org."""
+        with self._client() as c:
+            r = c.get(self._url("/plugins"))
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_get(self, plugin_id: str) -> dict:
+        """Get a single plugin by ID."""
+        with self._client() as c:
+            r = c.get(self._url(f"/plugins/{plugin_id}"))
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_push(self, plugin_id: str, bundle_bytes: bytes, source_code: str) -> dict:
+        """Upload a new bundle + source_code for a plugin (multipart/form-data)."""
+        with self._client() as c:
+            r = c.post(
+                self._url(f"/plugins/{plugin_id}/push"),
+                files={"bundle": ("plugin.js", bundle_bytes, "application/javascript")},
+                data={"source_code": source_code},
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_promote(self, plugin_id: str, target: str) -> dict:
+        """Promote a plugin to staging or live."""
+        with self._client() as c:
+            r = c.post(
+                self._url(f"/plugins/{plugin_id}/promote"),
+                json={"target": target},
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_invoke(
+        self,
+        plugin_id: str,
+        payload: dict,
+        config: dict | None = None,
+        auth_credential: str | None = None,
+        auth_key: str | None = None,
+    ) -> dict:
+        """Proxy an invocation to the plugin's Lambda function.
+
+        `payload` is the event BODY only -- it lands at `event.payload` on
+        the Lambda side, not the whole PluginPayload envelope (issue #1365).
+        `config` mirrors `event.config`.
+
+        `auth_credential` is a name, never a secret in the clear: the server
+        reads it as an event source name and resolves that source's outbound
+        auth exactly as a real flow does (its credential, auth_type and
+        auth_header), falling back to a stored credential name when the org
+        has no source called that. The event.auth KEY those headers land
+        under is `auth_key` when given, else `auth_credential` itself; that
+        key is also the `auth` capability grant the server requires on the
+        plugin, mirroring what the runtime hands a plugin.
+        """
+        with self._client() as c:
+            r = c.post(
+                self._url(f"/plugins/{plugin_id}/invoke"),
+                json={
+                    "payload": payload,
+                    "config": config or {},
+                    "auth_credential": auth_credential,
+                    "auth_key": auth_key,
+                },
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_logs(
+        self,
+        plugin_id: str,
+        connector_id: str | None = None,
+        since_minutes: int | None = None,
+        limit: int | None = None,
+    ) -> dict:
+        """Tail the most recent CloudWatch log lines for a plugin.
+
+        Optional filters (#293): connector_id narrows to one connector's
+        lines, since_minutes widens the lookback, limit caps the line count.
+        """
+        params: dict = {}
+        if connector_id is not None:
+            params["connector_id"] = connector_id
+        if since_minutes is not None:
+            params["since_minutes"] = since_minutes
+        if limit is not None:
+            params["limit"] = limit
+        with self._client() as c:
+            r = c.get(self._url(f"/plugins/{plugin_id}/logs"), params=params)
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_metrics(self, plugin_id: str, window: str = "24h") -> dict:
+        """CloudWatch metrics (invocations, errors, latency) for a plugin (#293)."""
+        with self._client() as c:
+            r = c.get(
+                self._url(f"/plugins/{plugin_id}/metrics"),
+                params={"window": window},
+            )
+            r.raise_for_status()
+            return r.json()
+
+    def plugin_status(self, plugin_id: str) -> dict:
+        """Get the current status of a plugin."""
+        return self.plugin_get(plugin_id)

{plugsync_cli-0.1.1 → plugsync_cli-0.4.0}/plugsync_cli/commands/auth.py

@@ -125,6 +125,10 @@ def auth_login(email: str | None, password: str | None, token: str | None):
         raise SystemExit(1)
     except httpx.RequestError as exc:
         console.print(f"[red]Could not reach {api_url}: {exc}[/red]")
+        console.print(
+            "[yellow]Is this the right API URL? Set it with "
+            "'plugsync config set api_url <url>'.[/yellow]"
+        )
         raise SystemExit(1)
 
     data = response.json()