pushmetrics-cli 0.1.0__py3-none-any.whl

pm/client/databases.py

@@ -0,0 +1,147 @@
+"""Database endpoints."""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from pm.client.base import CrudClient, PMApiError, _unwrap_result, raise_for_status
+from pm.models.databases import Database
+
+
+class DatabasesClient(CrudClient[Database]):
+    base_path = "/api/v1/database"
+    model = Database
+
+    def resolve_uid(self, ref: str) -> str:
+        """Resolve a database UID or name (case-insensitive) to its UID.
+
+        The metadata endpoints below (``/schemas/``, ``/schema/<schema>/``,
+        ``/table/<table>/<schema>/``, ``/select_star_sql/...``,
+        ``/table_exists/...``, ``/search_tables/``, ``/function_names/``)
+        accept either a UID hashid or a numeric id in the ``<pk>`` slot,
+        but UIDs are the public identifier — we always go through UIDs to
+        stay consistent with the rest of the CLI surface.
+
+        If the caller already passed an exact UID, this still validates it
+        against the workspace's database list (cheap — single round-trip).
+        """
+        items = self.list()
+        for db in items:
+            if db.uid and db.uid == ref:
+                return db.uid
+        for db in items:
+            if (
+                db.database_name
+                and db.database_name.lower() == ref.lower()
+                and db.uid
+            ):
+                return db.uid
+        raise PMApiError(
+            404,
+            f"Database not found by uid/name: {ref!r}",
+            method="GET",
+            path=f"{self.base_path}/",
+        )
+
+    def schemas(self, ref: str, *, force: bool = False) -> List[str]:
+        """List schemas in a database. Pass ``force=True`` to bypass cache."""
+        uid = self.resolve_uid(ref)
+        params: Dict[str, Any] = {}
+        if force:
+            # Rison-encoded query the schemas endpoint expects.
+            params["q"] = "(force:!t)"
+        resp = self.session.get(f"{self.base_path}/{uid}/schemas/", params=params)
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default=[]) or []
+
+    def tables(self, ref: str, schema: str) -> List[Dict[str, Any]]:
+        """List tables and views in a schema.
+
+        Uses ``?action=tree`` so the backend returns structured dicts
+        (``{name, type, databaseId, schemaName, ...}``) rather than the
+        default ``DatasourceName`` tuples (which serialize as 2-element
+        lists). Easier to render and filter on the client.
+        """
+        uid = self.resolve_uid(ref)
+        resp = self.session.get(
+            f"{self.base_path}/{uid}/schema/{schema}/",
+            params={"action": "tree"},
+        )
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default=[]) or []
+
+    def table_metadata(self, ref: str, table: str, schema: str) -> Dict[str, Any]:
+        """Describe a table: columns, primary key, foreign keys, indexes, comment.
+
+        Returns the full payload from ``/database/<uid>/table/<table>/<schema>/``
+        — top-level keys include ``name``, ``columns``, ``primaryKey``,
+        ``foreignKeys``, ``indexes``, ``comment``, ``selectStar``.
+        """
+        uid = self.resolve_uid(ref)
+        resp = self.session.get(
+            f"{self.base_path}/{uid}/table/{table}/{schema}/",
+        )
+        raise_for_status(resp)
+        body = resp.json()
+        return body if isinstance(body, dict) else {"result": body}
+
+    def select_star_sql(self, ref: str, table: str, schema: str, *, limit: int = 100) -> str:
+        """Return the dialect-correct ``SELECT * FROM <schema>.<table> LIMIT N``.
+
+        Does NOT execute the query — the canonical ``select_star`` endpoint
+        does that. Use this when you want the SQL as a template.
+        """
+        uid = self.resolve_uid(ref)
+        resp = self.session.get(
+            f"{self.base_path}/{uid}/select_star_sql/{table}/{schema}/",
+            params={"limit": limit},
+        )
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default="") or ""
+
+    def table_exists(self, ref: str, table: str, schema: str) -> Dict[str, Any]:
+        """Return ``{exists, type, resolved_name, table, schema}``.
+
+        ``resolved_name`` echoes the matched identifier — different from the
+        input on case-folding dialects (Snowflake/Oracle).
+        """
+        uid = self.resolve_uid(ref)
+        resp = self.session.get(
+            f"{self.base_path}/{uid}/table_exists/{table}/{schema}/",
+        )
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default={}) or {}
+
+    def search_tables(self, ref: str, pattern: str, *, schema: str = "") -> Dict[str, Any]:
+        """Search tables and views by substring across all non-system schemas
+        (or a single ``schema`` when provided).
+
+        Returns ``{pattern, count, results: [{schema, name, type}, ...]}``.
+        """
+        uid = self.resolve_uid(ref)
+        params: Dict[str, Any] = {"pattern": pattern}
+        if schema:
+            params["schema"] = schema
+        resp = self.session.get(
+            f"{self.base_path}/{uid}/search_tables/",
+            params=params,
+        )
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default={}) or {}
+
+    def function_names(
+        self, ref: str, *, filter: str = "", limit: int = 100
+    ) -> Dict[str, Any]:
+        """List SQL function names supported by the database engine.
+
+        Returns ``{functions, count, total, backend, [filter], [note]}``.
+        """
+        uid = self.resolve_uid(ref)
+        params: Dict[str, Any] = {"limit": limit}
+        if filter:
+            params["filter"] = filter
+        resp = self.session.get(
+            f"{self.base_path}/{uid}/function_names/",
+            params=params,
+        )
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default={}) or {}

pm/client/favorites.py

@@ -0,0 +1,14 @@
+"""Favorite endpoints.
+
+Backend supports full CRUD but `edit_columns` is empty (no meaningful PUT).
+The CLI only exposes ls/create/delete at the commands layer to match the FE.
+"""
+from __future__ import annotations
+
+from pm.client.base import CrudClient
+from pm.models.favorites import Favorite
+
+
+class FavoritesClient(CrudClient[Favorite]):
+    base_path = "/api/v1/favorite"
+    model = Favorite

pm/client/folders.py

@@ -0,0 +1,10 @@
+"""Folder endpoints (full CRUD)."""
+from __future__ import annotations
+
+from pm.client.base import CrudClient
+from pm.models.folders import Folder
+
+
+class FoldersClient(CrudClient[Folder]):
+    base_path = "/api/v1/folder"
+    model = Folder

pm/client/integrations.py

@@ -0,0 +1,14 @@
+"""Integration endpoints — list / get only.
+
+Connect/disconnect/edit go through the FE wizard because their payloads
+are AES-encrypted (OAuth tokens for Slack / Tableau / GDrive etc.).
+"""
+from __future__ import annotations
+
+from pm.client.base import CrudClient
+from pm.models.integrations import Integration
+
+
+class IntegrationsClient(CrudClient[Integration]):
+    base_path = "/api/v1/integration"
+    model = Integration

pm/client/organizations.py

@@ -0,0 +1,20 @@
+"""Organization endpoints.
+
+Backend supports GET / POST / PUT / `current`. **No GET_LIST** — the FE lists
+via `/es/organization/` (Elasticsearch). The CLI omits `list()` for now;
+use `pm orgs current` and `pm orgs get <uid>`.
+"""
+from __future__ import annotations
+
+from pm.client.base import CrudClient, raise_for_status
+from pm.models.organizations import Organization
+
+
+class OrganizationsClient(CrudClient[Organization]):
+    base_path = "/api/v1/organization"
+    model = Organization
+
+    def current(self) -> Organization:
+        resp = self.session.get(f"{self.base_path}/current")
+        raise_for_status(resp)
+        return Organization.model_validate(resp.json())

pm/client/recipients.py

@@ -0,0 +1,92 @@
+"""Recipients API client — wraps ``/api/v1/recipient/``.
+
+Standard FAB CRUD (get / create / update / delete) inherited from
+:class:`CrudClient`. ``list`` is overridden because
+``RecipientRestApi._get_list_headless`` returns
+``{results: [...], count: ...}`` (note ``results`` plural — the
+endpoint pre-dates FAB's standard ``{result: [...]}`` shape) rather
+than the standard envelope. Without the override, ``_unwrap_result``
+returns the whole response dict and the model validator wraps it as
+a single mostly-empty Recipient (codex review P2: real-world bug
+that mock-based tests never caught).
+
+The ``details`` route is also added on top — it returns the
+recipient plus its destinations, connected reports, and recent
+executions, which is the agent's primary read-path (one roundtrip
+instead of three).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pm.client.base import CrudClient, PMApiError, _unwrap_result, raise_for_status
+from pm.models.recipients import Recipient
+
+
+class RecipientsClient(CrudClient[Recipient]):
+    base_path = "/api/v1/recipient"
+    model = Recipient
+
+    def list(
+        self, params: Optional[Dict[str, Any]] = None,
+    ) -> List[Recipient]:
+        """Recipient list — backend returns ``{results, count, ids}``
+        instead of FAB's standard ``{result: [...]}``. Override
+        unwrapping to read ``results``."""
+        resp = self.session.get(f"{self.base_path}/", params=params)
+        raise_for_status(resp)
+        body = resp.json() if resp.content else {}
+        if isinstance(body, dict) and "results" in body:
+            raw = body["results"]
+        else:
+            # Defensive: tolerate the standard shape too.
+            raw = _unwrap_result(body, default=[])
+        if not isinstance(raw, list):
+            raw = [raw] if raw else []
+        return [self.model.model_validate(item) for item in raw]
+
+    def create(self, data: Dict[str, Any]) -> Recipient:
+        """Create a recipient, returning a fully-hydrated model.
+
+        FAB's POST response returns ``destinations`` as a list of bare
+        FK ids (e.g. ``[743]``), which doesn't satisfy the ``Recipient``
+        model's nested ``RecipientDestination`` shape and makes the
+        generic ``CrudClient.create`` raise a ``ValidationError``. Re-fetch
+        the created recipient by its uid so the caller gets destinations as
+        dicts - mirrors how the web app reloads after a write.
+        """
+        resp = self.session.post(f"{self.base_path}/", json=data)
+        raise_for_status(resp)
+        result = _unwrap_result(resp.json(), default={})
+        uid = result.get("uid") if isinstance(result, dict) else None
+        if not uid:
+            # Without a uid we can't re-fetch, and the POST body's
+            # ``destinations`` are bare ids that won't validate - surface a
+            # clear error rather than returning a half-built / uid-less model.
+            raise PMApiError(
+                resp.status_code,
+                "recipient create response missing 'uid'; cannot re-fetch",
+                method="POST",
+                path=f"{self.base_path}/",
+            )
+        return self.get(uid)
+
+    def update(self, uid: str, data: Dict[str, Any]) -> Recipient:
+        """Update a recipient, returning a fully-hydrated model.
+
+        Same FAB id-list ``destinations`` shape as ``create`` (and FAB PUT
+        often echoes only ``edit_columns``), so re-fetch by uid rather than
+        trusting the PUT response body.
+        """
+        resp = self.session.put(f"{self.base_path}/{uid}", json=data)
+        raise_for_status(resp)
+        return self.get(uid)
+
+    def details(self, uid: str) -> Dict[str, Any]:
+        """Fetch a recipient with destinations + connected_reports +
+        recent_executions in one call. Returns the raw response dict —
+        the connected_reports / recent_executions shapes are open and
+        evolve faster than a fixed Pydantic model would tolerate."""
+        resp = self.session.get(f"{self.base_path}/{uid}/details")
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default={}) or {}

pm/client/reports.py

@@ -0,0 +1,148 @@
+"""Report endpoints (CRUD + custom run/runs)."""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pm.client.base import CrudClient, _unwrap_result, raise_for_status
+from pm.models.reports import Report
+from pm.models.runs import Run
+
+
+class ReportsClient(CrudClient[Report]):
+    base_path = "/api/v1/report"
+    model = Report
+
+    def run(
+        self,
+        uid: str,
+        *,
+        send_to_me: bool = False,
+        email: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Trigger a noteflow run.
+
+        Hits ``POST /api/v1/report/<uid>/run/noteflow``. Returns the raw
+        backend response — typically ``{result: {noteflow_run_uid: ...}}``.
+
+        ``send_to_me=True`` causes the backend's
+        ``execute_options_to_block_properties`` to compute per-block
+        property overrides. **Without an ``email`` value, the backend
+        treats it as ``False`` and SUPPRESSES email blocks** rather than
+        redirecting them. For a true "send to me" preview that actually
+        delivers an email, pass the caller's verified email address here.
+        Other addresses must already be saved email recipients in the report
+        workspace. The backend rejects unknown or foreign-workspace addresses.
+
+        Non-email destination blocks (slack, sftp, webhook, cloud storage)
+        are always suppressed under ``send_to_me=True`` because there's
+        no equivalent "redirect to me" semantics — no per-user slack
+        channel or per-user S3 bucket.
+        """
+        if email and not send_to_me:
+            raise ValueError("email requires send_to_me=True")
+        body: Dict[str, Any] = {}
+        if send_to_me:
+            options: Dict[str, Any] = {"send_to_me": True}
+            if email:
+                # Backend reads ``options.email`` and uses it as the
+                # ``to_`` address on every email block; falsy / missing
+                # means "suppress email blocks entirely".
+                options["email"] = email
+            body["options"] = options
+        resp = self.session.post(
+            f"{self.base_path}/{uid}/run/noteflow",
+            json=body if body else None,
+        )
+        raise_for_status(resp)
+        return resp.json()
+
+    def yaml(self, uid: str) -> str:
+        """Export a report as a raw YAML string.
+
+        Hits ``GET /api/v1/report/<uid>/config`` which returns
+        ``text/plain; charset=utf-8`` — not JSON. Returns the raw text.
+        """
+        resp = self.session.get(f"{self.base_path}/{uid}/config")
+        raise_for_status(resp)
+        return resp.text
+
+    def apply_yaml(
+        self,
+        yaml_str: str,
+        *,
+        allow_create_folder: bool = False,
+    ) -> Dict[str, Any]:
+        """Create a new report from a raw YAML string.
+
+        Hits ``POST /api/v1/report/config`` with the YAML as the request
+        body (``text/plain`` — not JSON-wrapped). Returns
+        ``{uid, name, type, [warning_duplicate_uids]}``. The backend
+        also auto-fills top-level ``destinations:`` from block types and
+        attaches the new report's permission row before commit.
+
+        ``allow_create_folder=True`` passes ``?allow_create_folder=true``
+        so a YAML ``folder:`` path that doesn't fully exist gets created
+        silently. Default ``False`` rejects unknown paths — useful when
+        the YAML came from a fallible source (agent, hand-edited file)
+        and you'd rather catch typos than spawn ghost folders.
+        """
+        params: Dict[str, str] = {}
+        if allow_create_folder:
+            params["allow_create_folder"] = "true"
+        resp = self.session.post(
+            f"{self.base_path}/config",
+            data=yaml_str.encode("utf-8"),
+            headers={"Content-Type": "text/plain; charset=utf-8"},
+            params=params or None,
+        )
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default={}) or {}
+
+    def update_yaml(
+        self,
+        uid: str,
+        yaml_str: str,
+        *,
+        prune: bool = True,
+        dry_run: bool = False,
+        allow_create_folder: bool = False,
+    ) -> Dict[str, Any]:
+        """Update an existing report from a raw YAML string.
+
+        Hits ``PUT /api/v1/report/<uid>/config`` with the YAML as the
+        request body.
+
+        - ``prune`` (default ``True``): blocks absent from the YAML are
+          removed from the report (YAML is source of truth). Set ``False``
+          for upsert-no-delete semantics (kept blocks stay).
+        - ``dry_run`` (default ``False``): server applies in a savepoint,
+          captures before/after, ROLLS BACK. Returns the diff payload
+          ``{would_change, summary, yaml_diff}`` instead of ``{uid, name}``.
+        - ``allow_create_folder`` (default ``False``): allow YAML
+          ``folder:`` path that doesn't exist to be created on the fly.
+        """
+        params: Dict[str, str] = {}
+        if not prune:
+            params["prune"] = "false"
+        if dry_run:
+            params["dry_run"] = "true"
+        if allow_create_folder:
+            params["allow_create_folder"] = "true"
+        resp = self.session.put(
+            f"{self.base_path}/{uid}/config",
+            data=yaml_str.encode("utf-8"),
+            headers={"Content-Type": "text/plain; charset=utf-8"},
+            params=params or None,
+        )
+        raise_for_status(resp)
+        return _unwrap_result(resp.json(), default={}) or {}
+
+    def runs(self, uid: str) -> List[Run]:
+        """List runs of a specific report (hits /noteflow_run/, not /report/)."""
+        resp = self.session.get("/api/v1/noteflow_run/", params={"report_uid": uid})
+        raise_for_status(resp)
+        body = resp.json()
+        raw = body.get("result", []) if isinstance(body, dict) else body
+        items = [Run.model_validate(item) for item in raw]
+        filtered = [r for r in items if getattr(r, "report_uid", None) == uid]
+        return filtered or items

pm/client/roles.py

@@ -0,0 +1,100 @@
+"""Role / group endpoints.
+
+Three main roles (Admin / User / Guest) live alongside any number of
+"groups" (other roles in ``ab_role`` minus a few hidden ones like
+``Everyone`` and per-user roles — see ``RoleRestApi.base_filters``).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+from pm.client.base import CrudClient, PMApiError, raise_for_status
+from pm.models.roles import Role
+
+
+# The three main-role names recognized by ``security/models.py:MainRoles``.
+# A user has exactly one of these in their ``roles`` list at any time;
+# everything else is a group.
+MAIN_ROLE_NAMES = ("Admin", "User", "Guest")
+
+
+class RolesClient(CrudClient[Role]):
+    base_path = "/api/v1/role"
+    model = Role
+
+    def resolve_uid(self, ref: str) -> str:
+        """Accept a role UID or name (case-insensitive), return the UID.
+
+        Costs one ``/role/`` list call. Cheap — workspaces typically
+        have <50 roles.
+        """
+        items = self.list()
+        for r in items:
+            if r.uid and r.uid == ref:
+                return r.uid
+        ref_lc = ref.lower()
+        for r in items:
+            if r.name and r.name.lower() == ref_lc:
+                if r.uid:
+                    return r.uid
+        raise PMApiError(
+            404,
+            f"Role not found by uid/name: {ref!r}",
+            method="GET",
+            path=f"{self.base_path}/",
+        )
+
+    def assign_users(self, role_ref: str, user_uids: List[str]) -> Dict[str, Any]:
+        """Add users to a role / group.
+
+        Backend endpoint accepts UIDs (not integer IDs) in the body. New
+        users that are already in the role are silently skipped — the
+        server-side loop checks ``existing_users`` before inserting.
+        """
+        uid = self.resolve_uid(role_ref)
+        resp = self.session.post(
+            f"{self.base_path}/{uid}/assign_users",
+            json={"users_uid": list(user_uids)},
+        )
+        raise_for_status(resp)
+        body = resp.json()
+        return body.get("result", body) if isinstance(body, dict) else body
+
+    def revoke_users(self, role_ref: str, user_uids: List[str]) -> Dict[str, Any]:
+        """Remove users from a role / group (inverse of ``assign_users``)."""
+        uid = self.resolve_uid(role_ref)
+        resp = self.session.post(
+            f"{self.base_path}/{uid}/revoke_users",
+            json={"users_uid": list(user_uids)},
+        )
+        raise_for_status(resp)
+        body = resp.json()
+        return body.get("result", body) if isinstance(body, dict) else body
+
+    def find_main_role_id(self, name: str) -> int:
+        """Resolve ``Admin`` / ``User`` / ``Guest`` (case-insensitive)
+        to the integer ``role.id`` in the current workspace.
+
+        Integer ID is what the user PUT body needs — ``pre_update`` does
+        ``filter(lambda r: r.id == new_main_role, main_roles)``.
+        """
+        wanted_lc = name.lower()
+        matches = [n for n in MAIN_ROLE_NAMES if n.lower() == wanted_lc]
+        if not matches:
+            raise PMApiError(
+                400,
+                f"{name!r} is not a main role. Use one of: {', '.join(MAIN_ROLE_NAMES)}.",
+                method="GET",
+                path=f"{self.base_path}/",
+            )
+        target_name = matches[0]
+        for r in self.list():
+            if r.name == target_name and r.id is not None:
+                return r.id
+        raise PMApiError(
+            404,
+            f"Main role {target_name!r} not found in current workspace. "
+            "Has this workspace been initialised correctly?",
+            method="GET",
+            path=f"{self.base_path}/",
+        )