pushmetrics-cli 0.1.0__py3-none-any.whl

pm/commands/integrations.py

@@ -0,0 +1,95 @@
+"""Integration commands — ``pm integration list`` with --name / --type filters.
+
+Backend exposes ``search_columns = ["name", "type"]`` on the integration
+REST API, so we can build a FAB rison ``filters:!(...)`` query directly
+from the CLI. ``--name`` uses ``ct`` (case-insensitive substring) and
+``--type`` uses ``eq`` (types are short enum-ish tokens like ``slack`` /
+``tableau`` / ``gws`` — exact match is the natural read).
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.commands._helpers import json_option
+from pm.output import emit
+
+
+def _rison_str(s: str) -> str:
+    """Encode a string for inclusion as a Rison value.
+
+    Bare identifiers pass through unquoted; anything else gets
+    single-quote-wrapped with embedded quotes escaped as ``!'`` per the
+    Rison spec. JSON-style double quotes are NOT valid Rison — the
+    backend rejects with a parse error. Mirrors the helpers in
+    ``recipient.py`` and ``client/runs.py``.
+
+    Quote digit-leading values: a bare Rison id must not start with a
+    digit — the parser commits to a number and fails on the first
+    non-numeric char (uids/UUIDs routinely start with digits).
+    """
+    if (
+        s
+        and (s[0].isalpha() or s[0] == "_")
+        and all(c.isalnum() or c in "_-." for c in s)
+    ):
+        return s
+    return "'" + s.replace("!", "!!").replace("'", "!'") + "'"
+
+
+@click.group(name="integrations", cls=AliasedGroup, aliases={"ls": "list"})
+def integrations() -> None:
+    """Connected services (Slack, Tableau, Google Drive, ...)."""
+
+
+@integrations.command(name="list")
+@click.option(
+    "--name",
+    default=None,
+    help="Filter by name (case-insensitive substring).",
+)
+@click.option(
+    "--type",
+    "type_",
+    default=None,
+    help="Only this integration type (slack, tableau, gws, ...).",
+)
+@click.option(
+    "--limit",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Maximum number of rows to return (default: all).",
+)
+@json_option
+@click.pass_context
+def ls(
+    ctx: click.Context,
+    name: Optional[str],
+    type_: Optional[str],
+    limit: Optional[int],
+) -> None:
+    """List the integrations connected to this workspace."""
+    client = PMClient.from_profile(ctx.obj["profile"])
+
+    q_parts = []
+    if name:
+        q_parts.append(f"(col:name,opr:ct,value:{_rison_str(name)})")
+    if type_:
+        q_parts.append(f"(col:type,opr:eq,value:{_rison_str(type_)})")
+    page_size = f"page_size:{int(limit)}" if limit is not None else None
+    params: Dict[str, Any] = {}
+    if q_parts or page_size:
+        filters_str = f"filters:!({','.join(q_parts)})" if q_parts else None
+        bits = [b for b in (filters_str, page_size) if b]
+        params["q"] = f"({','.join(bits)})"
+
+    items = client.integrations.list(params=params or None)
+    client.persist()
+    emit(
+        items,
+        json_output=ctx.obj["json"],
+        columns=[("UID", "uid"), ("NAME", "name"), ("TYPE", "type")],
+    )

pm/commands/metrics_view.py

@@ -0,0 +1,195 @@
+"""`pm metrics-view` — manage and query metrics view blocks.
+
+Standard CRUD (create/list/get/update) comes from the factory. Two custom
+verbs hit semantic-layer endpoints that don't fit the standard block
+lifecycle:
+
+- ``pm metrics-view query <uid>`` — POST /api/v1/block/metrics_query.
+  Executes a semantic query (measures + dimensions + filters + time
+  range, etc.) and returns rows. The metrics_view_uid lives in the
+  request body, not the URL path.
+- ``pm metrics-view schema <uid>`` — GET /api/v1/block/<uid>/metrics_schema.
+  Returns measures/dimensions/parameters available — the "what can I
+  query?" companion to query.
+
+Two input modes for query:
+- Flag-driven: ``--measure m1 --measure m2 [--dimension d1 ...] [--time-range
+  last_30d] [--limit 100]`` — convenient for simple queries.
+- ``--stdin`` JSON body — required for complex queries (dimension_grains,
+  filters, order_by, parameters). Body keys override flag values; the
+  positional ``<uid>`` is auto-injected as ``metrics_view_uid`` if absent
+  from the body.
+
+Mixed flags + --stdin is allowed; --stdin wins on collision. Rationale:
+the agent can compose a base body via flags and override one field via
+--stdin without rebuilding the entire body.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Optional, Tuple
+
+import click
+
+from pm.client import PMClient
+from pm.commands._block_factory import make_block_group
+from pm.commands._helpers import json_option
+from pm.output import emit
+
+
+# ── query ─────────────────────────────────────────────────────────────
+
+
+def _read_stdin_json_or_none() -> Optional[dict]:
+    """Read stdin as JSON if any data is present; return None on empty.
+
+    Unlike the factory's ``_read_stdin_json``, this is non-raising for the
+    empty case — query's stdin is OPTIONAL (the caller may have provided
+    measures via flags).
+    """
+    raw = sys.stdin.read() if not sys.stdin.isatty() else ""
+    if not raw.strip():
+        return None
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(f"--stdin: invalid JSON ({exc.msg})")
+    if not isinstance(parsed, dict):
+        raise click.ClickException(
+            f"--stdin body must be a JSON object, got {type(parsed).__name__}",
+        )
+    return parsed
+
+
+@click.command(name="query")
+@click.argument("uid")
+@click.option(
+    "--measure", "measures",
+    multiple=True,
+    help="Measure to query (at least one, here or in the --stdin body). Repeatable.",
+)
+@click.option(
+    "--dimension", "dimensions",
+    multiple=True,
+    help="Dimension to group by. Repeatable.",
+)
+@click.option(
+    "--time-range",
+    default=None,
+    help="Time range (e.g. 'last_30d', 'last_1y', '2026-01-01:2026-04-01').",
+)
+@click.option(
+    "--time-grain",
+    default=None,
+    help="Time grain: day / week / month / quarter / year.",
+)
+@click.option(
+    "--limit",
+    type=int,
+    default=None,
+    help="Row limit.",
+)
+@click.option(
+    "--offset",
+    type=int,
+    default=None,
+    help="Row offset for paging.",
+)
+@click.option(
+    "--no-cache",
+    is_flag=True,
+    help="Recompute instead of using the 5-minute cache.",
+)
+@click.option(
+    "--stdin",
+    "use_stdin",
+    is_flag=True,
+    help=(
+        "Read the JSON query body from stdin, for filters, order_by, "
+        "dimension_grains or parameters. Body fields override the flags."
+    ),
+)
+@json_option
+@click.pass_context
+def query(
+    ctx: click.Context,
+    uid: str,
+    measures: Tuple[str, ...],
+    dimensions: Tuple[str, ...],
+    time_range: Optional[str],
+    time_grain: Optional[str],
+    limit: Optional[int],
+    offset: Optional[int],
+    no_cache: bool,
+    use_stdin: bool,
+) -> None:
+    """Query a metrics view.
+
+    Returns the rows and the SQL that produced them.
+    """
+    extra: dict = {}
+    if use_stdin:
+        body = _read_stdin_json_or_none()
+        if body:
+            extra = body
+
+    # Merge: flag-driven kwargs are the base; --stdin extras override on collision.
+    # metrics_view_uid is auto-injected from the positional arg.
+    measures_final = list(extra.get("measures") or measures)
+    if not measures_final:
+        raise click.ClickException(
+            "At least one measure is required. Pass --measure NAME (repeatable) "
+            "or include `measures: [...]` in --stdin body.",
+        )
+
+    client = PMClient.from_profile(ctx.obj["profile"])
+    payload = client.blocks.metrics_query(
+        uid,
+        measures=measures_final,
+        dimensions=list(extra.get("dimensions") or dimensions) or None,
+        dimension_grains=extra.get("dimension_grains"),
+        filters=extra.get("filters"),
+        time_range=extra.get("time_range") or time_range,
+        time_grain=extra.get("time_grain") or time_grain,
+        order_by=extra.get("order_by"),
+        limit=extra.get("limit") if extra.get("limit") is not None else limit,
+        offset=extra.get("offset") if extra.get("offset") is not None else offset,
+        no_cache=bool(extra.get("no_cache") or no_cache),
+        parameters=extra.get("parameters"),
+    )
+    client.persist()
+    emit(payload, json_output=ctx.obj["json"])
+
+
+# ── schema ────────────────────────────────────────────────────────────
+
+
+@click.command(name="schema")
+@click.argument("uid")
+@json_option
+@click.pass_context
+def schema(ctx: click.Context, uid: str) -> None:
+    """Show what a metrics view can be queried by.
+
+    Lists its measures, dimensions and parameters; run it before query.
+    """
+    client = PMClient.from_profile(ctx.obj["profile"])
+    result = client.blocks.metrics_schema(uid)
+    client.persist()
+    emit(result, json_output=ctx.obj["json"])
+
+
+# ── Group ────────────────────────────────────────────────────────────
+
+
+metrics_view = make_block_group(
+    "metrics-view",
+    "metrics_view",
+    crud_verbs=("create", "list", "get", "update"),
+    help_text="Metrics views (the semantic layer).\n\nBlock type: metrics_view.",
+    custom_verbs={
+        "query": query,
+        "schema": schema,
+    },
+)

pm/commands/organizations.py

@@ -0,0 +1,56 @@
+"""Organization commands (get/update/current — no list; backend uses ES for listing)."""
+from __future__ import annotations
+
+from typing import Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.commands._helpers import json_option, merge_fields, parse_data
+from pm.output import emit
+
+
+@click.group(name="organizations", cls=AliasedGroup)
+def organizations() -> None:
+    """Your organization (the owner of workspaces)."""
+
+
+@organizations.command(name="current")
+@json_option
+@click.pass_context
+def current(ctx: click.Context) -> None:
+    """Show your organization."""
+    client = PMClient.from_profile(ctx.obj["profile"])
+    org = client.organizations.current()
+    client.persist()
+    emit(org, json_output=ctx.obj["json"])
+
+
+@organizations.command(name="get")
+@click.argument("uid")
+@json_option
+@click.pass_context
+def get(ctx: click.Context, uid: str) -> None:
+    """Show one organization."""
+    client = PMClient.from_profile(ctx.obj["profile"])
+    org = client.organizations.get(uid)
+    client.persist()
+    emit(org, json_output=ctx.obj["json"])
+
+
+@organizations.command(name="update")
+@click.argument("uid")
+@click.option("--name", default=None, help="Rename the organization.")
+@click.option("--data", default=None, help="Extra fields as a JSON object.")
+@json_option
+@click.pass_context
+def update(ctx: click.Context, uid: str, name: Optional[str], data: Optional[str]) -> None:
+    """Update an organization."""
+    payload = merge_fields(parse_data(data), {"name": name})
+    if not payload:
+        raise click.UsageError("Nothing to update; pass --name or --data.")
+    client = PMClient.from_profile(ctx.obj["profile"])
+    org = client.organizations.update(uid, payload)
+    client.persist()
+    emit(org, json_output=ctx.obj["json"])

pm/commands/recipient.py

@@ -0,0 +1,226 @@
+"""`pm recipient` — workspace CRM for delivery targets.
+
+A recipient is a named record (person or team) with one or more
+destinations (email, slack). Used as the delivery target for email /
+slack sends; also gated by ``tools_json.messaging_policy`` on the
+agent side (``recipients_only`` / ``recipients_only_with_approval`` —
+see ``pm_tool._apply_messaging_policy``).
+
+Verbs:
+
+  list           — paginated list (with optional --name substring filter)
+  get <uid>      — single recipient + destinations
+  details <uid>  — recipient + destinations + connected reports + recent executions
+  create --stdin — create from a JSON body
+  update <uid> --stdin — update existing
+  delete <uid>   — remove (gated by confirm)
+"""
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Dict, Optional
+
+import click
+
+from pm._alias import AliasedGroup
+from pm.client import PMClient
+from pm.commands._helpers import (
+    confirm_delete,
+    json_option,
+    peek_name,
+    report_deleted,
+    yes_option,
+)
+from pm.output import emit
+
+
+def _read_stdin_json() -> Dict[str, Any]:
+    raw = sys.stdin.read()
+    if not raw.strip():
+        raise click.UsageError("--stdin was given but stdin was empty.")
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(f"--stdin: invalid JSON ({exc.msg})")
+    if not isinstance(parsed, dict):
+        raise click.ClickException(
+            f"--stdin body must be a JSON object, got {type(parsed).__name__}",
+        )
+    return parsed
+
+
+@click.group(name="recipient", cls=AliasedGroup, aliases={"ls": "list"})
+def recipient() -> None:
+    """Recipients: who reports are delivered to."""
+
+
+_LIST_COLUMNS = [
+    ("UID", "uid"),
+    ("NAME", "name"),
+    ("DESTINATIONS", lambda r: _format_destinations(r.get("destinations") or [])),
+]
+
+
+def _format_destinations(dests: Any) -> str:
+    """Compact one-line summary: ``email:a@b.c, slack:#ops``."""
+    if not isinstance(dests, list):
+        return ""
+    parts = []
+    for dest in dests:
+        if isinstance(dest, dict):
+            dest_type = dest.get("destination_type") or dest.get("type") or "?"
+            endpoint = dest.get("endpoint") or "?"
+            parts.append(f"{dest_type}:{endpoint}")
+    return ", ".join(parts)
+
+
+@recipient.command(name="list")
+@click.option(
+    "--name",
+    default=None,
+    help="Filter by name (case-insensitive substring).",
+)
+@click.option(
+    "--limit",
+    type=click.IntRange(min=1),
+    default=None,
+    help="Maximum number of rows to return (default: all).",
+)
+@json_option
+@click.pass_context
+def list_(ctx: click.Context, name: Optional[str], limit: Optional[int]) -> None:
+    """List recipients in the current workspace."""
+    client = PMClient.from_profile(ctx.obj["profile"])
+    # FAB rison query: filters list of (col,opr,value) tuples plus
+    # page_size. The CLI builds it directly so the client stays a
+    # thin shape over the API.
+    #
+    # Rison string encoding (codex round 8 P2 #2): bare alphanumerics
+    # need no quoting; values with shell-meta / spaces / colons need
+    # single-quote wrapping with embedded single-quotes escaped as
+    # ``!'``. JSON-style double quotes (``"..."``) are NOT valid Rison
+    # — the backend rejects with a parse error.
+    def _rison_str(s: str) -> str:
+        # Quote digit-leading values: a bare Rison id must not start
+        # with a digit — the parser commits to a number and fails on
+        # the first non-numeric char. Mirrors client/runs.py and
+        # integrations.py.
+        if (
+            s
+            and (s[0].isalpha() or s[0] == "_")
+            and all(c.isalnum() or c in "_-." for c in s)
+        ):
+            return s
+        return "'" + s.replace("!", "!!").replace("'", "!'") + "'"
+
+    q_parts = []
+    if name:
+        # ``ct`` (contains) is the case-insensitive substring operator
+        # FAB exposes via ``search_columns``.
+        q_parts.append(f"(col:name,opr:ct,value:{_rison_str(name)})")
+    page_size = f"page_size:{int(limit)}" if limit is not None else None
+    params: Dict[str, Any] = {}
+    if q_parts or page_size:
+        filters_str = f"filters:!({','.join(q_parts)})" if q_parts else None
+        bits = [b for b in (filters_str, page_size) if b]
+        params["q"] = f"({','.join(bits)})"
+    items = client.recipients.list(params=params or None)
+    client.persist()
+    emit(items, json_output=ctx.obj["json"], columns=_LIST_COLUMNS)
+
+
+@recipient.command(name="get")
+@click.argument("uid")
+@json_option
+@click.pass_context
+def get(ctx: click.Context, uid: str) -> None:
+    """Show one recipient and its destinations."""
+    client = PMClient.from_profile(ctx.obj["profile"])
+    item = client.recipients.get(uid)
+    client.persist()
+    emit(item, json_output=ctx.obj["json"])
+
+
+@recipient.command(name="details")
+@click.argument("uid")
+@json_option
+@click.pass_context
+def details(ctx: click.Context, uid: str) -> None:
+    """Show a recipient with its reports and recent runs."""
+    client = PMClient.from_profile(ctx.obj["profile"])
+    payload = client.recipients.details(uid)
+    client.persist()
+    emit(payload, json_output=ctx.obj["json"])
+
+
+@recipient.command(name="create")
+@click.option(
+    "--stdin",
+    "use_stdin",
+    is_flag=True,
+    required=True,
+    help=(
+        "Read the JSON body from stdin. Shape: {\"name\": ..., "
+        "\"destinations\": [{\"destination_type\": \"email\", "
+        "\"endpoint\": ...}]}."
+    ),
+)
+@json_option
+@click.pass_context
+def create(ctx: click.Context, use_stdin: bool) -> None:
+    """Create a recipient from a JSON body on stdin.
+
+    The body needs a name and at least one destination; each destination
+    has a destination_type (email or slack) and an endpoint (the address
+    or channel).
+    """
+    body = _read_stdin_json()
+    if not body.get("name"):
+        raise click.ClickException("Body missing required field: name")
+    if not body.get("destinations"):
+        raise click.ClickException(
+            "Body missing required field: destinations (at least one entry)",
+        )
+    client = PMClient.from_profile(ctx.obj["profile"])
+    item = client.recipients.create(body)
+    client.persist()
+    emit(item, json_output=ctx.obj["json"])
+
+
+@recipient.command(name="update")
+@click.argument("uid")
+@click.option(
+    "--stdin",
+    "use_stdin",
+    is_flag=True,
+    required=True,
+    help="Read the JSON body from stdin. Only the fields present are changed.",
+)
+@json_option
+@click.pass_context
+def update(ctx: click.Context, uid: str, use_stdin: bool) -> None:
+    """Update a recipient from a JSON body on stdin."""
+    body = _read_stdin_json()
+    client = PMClient.from_profile(ctx.obj["profile"])
+    item = client.recipients.update(uid, body)
+    client.persist()
+    emit(item, json_output=ctx.obj["json"])
+
+
+@recipient.command(name="delete")
+@click.argument("uid")
+@yes_option
+@json_option
+@click.pass_context
+def delete(ctx: click.Context, uid: str, yes: bool) -> None:
+    """Delete a recipient."""
+    if not yes:
+        name = peek_name(
+            lambda: PMClient.from_profile(ctx.obj["profile"]).recipients.get(uid), "name"
+        )
+        confirm_delete("recipient", uid, name)
+    client = PMClient.from_profile(ctx.obj["profile"])
+    client.recipients.delete(uid)
+    client.persist()
+    report_deleted(ctx, "recipient", uid)