pipefy-cli 0.3.0a1__py3-none-any.whl

pipefy_cli/commands/report_pipe.py

@@ -0,0 +1,290 @@
+"""Pipe-level reports (CRUD, columns, export)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import (
+    ID_POSITIONAL_CONTEXT_SETTINGS,
+    confirm_destructive,
+    parse_json_object,
+    parse_json_value,
+    prepare_report_cards_filter_cli,
+    resource_id_argument,
+    run_cli_command,
+    run_pipefy_client_coroutine,
+    write_export_csv_to_stdout,
+)
+
+report_pipe_app = typer.Typer(help="Pipe reports.", no_args_is_help=True)
+
+
+def _parse_order(raw: str | None) -> dict[str, Any] | None:
+    if raw is None or not raw.strip():
+        return None
+    parsed = parse_json_value(raw, "--order")
+    if not isinstance(parsed, dict):
+        raise typer.BadParameter("--order must be a JSON object")
+    return parsed
+
+
+@report_pipe_app.command("list")
+def report_pipe_list(
+    ctx: typer.Context,
+    pipe: str = typer.Option(..., "--pipe", help="Pipe UUID."),
+    first: int = typer.Option(30, "--first", help="Page size."),
+    after: str | None = typer.Option(None, "--after", help="Pagination cursor."),
+    search: str | None = typer.Option(None, "--search"),
+    report_id: str | None = typer.Option(None, "--report-id"),
+    order: str | None = typer.Option(None, "--order", help="JSON sort object."),
+    json_out: bool = typer.Option(
+        False, "--json", "-j", help="Print machine-readable JSON to stdout."
+    ),
+) -> None:
+    """List pipe reports (``get_pipe_reports``)."""
+    order_obj = _parse_order(order)
+
+    async def factory(client: PipefyClient):
+        return await client.get_pipe_reports(
+            pipe,
+            first=first,
+            after=after,
+            search=search,
+            report_id=report_id,
+            order=order_obj,
+        )
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@report_pipe_app.command("get")
+def report_pipe_get(
+    ctx: typer.Context,
+    pipe: str = typer.Option(..., "--pipe", help="Pipe UUID."),
+    report_id: str = typer.Option(..., "--report-id", help="Pipe report id."),
+    json_out: bool = typer.Option(
+        False, "--json", "-j", help="Print machine-readable JSON to stdout."
+    ),
+) -> None:
+    """Fetch one pipe report (``get_pipe_report``)."""
+
+    async def factory(client: PipefyClient):
+        raw = await client.get_pipe_reports(pipe, first=1, report_id=report_id)
+        edges = (raw.get("pipeReports") or {}).get("edges") or []
+        node = edges[0].get("node") if edges and isinstance(edges[0], dict) else None
+        if not node:
+            return {
+                "success": False,
+                "message": f"Pipe report not found (id={report_id}).",
+            }
+        return {"success": True, "pipeReport": node}
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@report_pipe_app.command("columns")
+def report_pipe_columns(
+    ctx: typer.Context,
+    pipe: str = typer.Option(..., "--pipe", help="Pipe UUID."),
+    json_out: bool = typer.Option(
+        False, "--json", "-j", help="Print machine-readable JSON to stdout."
+    ),
+) -> None:
+    """List report column definitions (``get_pipe_report_columns``)."""
+
+    async def factory(client: PipefyClient):
+        return await client.get_pipe_report_columns(pipe)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@report_pipe_app.command("filterable-fields")
+def report_pipe_filterable_fields(
+    ctx: typer.Context,
+    pipe: str = typer.Option(..., "--pipe", help="Pipe UUID."),
+    json_out: bool = typer.Option(
+        False, "--json", "-j", help="Print machine-readable JSON to stdout."
+    ),
+) -> None:
+    """List filterable fields for pipe reports (``get_pipe_report_filterable_fields``)."""
+
+    async def factory(client: PipefyClient):
+        return await client.get_pipe_report_filterable_fields(pipe)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@report_pipe_app.command("create")
+def report_pipe_create(
+    ctx: typer.Context,
+    pipe: str = typer.Option(..., "--pipe", help="Pipe id."),
+    name: str = typer.Option(..., "--name", "-n"),
+    fields: str | None = typer.Option(
+        None, "--fields", help="Optional JSON array of column internal names."
+    ),
+    filter_json: str | None = typer.Option(
+        None, "--filter", help="Optional JSON filter object."
+    ),
+    formulas: str | None = typer.Option(
+        None, "--formulas", help="Optional JSON array of arrays."
+    ),
+    json_out: bool = typer.Option(
+        False, "--json", "-j", help="Print machine-readable JSON to stdout."
+    ),
+) -> None:
+    """Create a pipe report (``create_pipe_report``)."""
+    fields_list = parse_json_value(fields, "--fields") if fields else None
+    if fields_list is not None and not isinstance(fields_list, list):
+        raise typer.BadParameter("--fields must be a JSON array")
+    filt = prepare_report_cards_filter_cli(parse_json_object(filter_json, "--filter"))
+    formulas_val = parse_json_value(formulas, "--formulas") if formulas else None
+    if formulas_val is not None and not isinstance(formulas_val, list):
+        raise typer.BadParameter("--formulas must be a JSON array")
+
+    async def factory(client: PipefyClient):
+        return await client.create_pipe_report(
+            pipe,
+            name.strip(),
+            fields=fields_list,
+            filter=filt,
+            formulas=formulas_val,
+        )
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@report_pipe_app.command("update", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def report_pipe_update(
+    ctx: typer.Context,
+    report_id: str = resource_id_argument(help="Pipe report id."),
+    name: str | None = typer.Option(None, "--name", "-n"),
+    color: str | None = typer.Option(None, "--color"),
+    fields: str | None = typer.Option(None, "--fields"),
+    filter_json: str | None = typer.Option(None, "--filter"),
+    formulas: str | None = typer.Option(None, "--formulas"),
+    featured_field: str | None = typer.Option(None, "--featured-field"),
+    json_out: bool = typer.Option(
+        False, "--json", "-j", help="Print machine-readable JSON to stdout."
+    ),
+) -> None:
+    """Update a pipe report (``update_pipe_report``)."""
+    fields_list = parse_json_value(fields, "--fields") if fields else None
+    if fields_list is not None and not isinstance(fields_list, list):
+        raise typer.BadParameter("--fields must be a JSON array")
+    filt = prepare_report_cards_filter_cli(parse_json_object(filter_json, "--filter"))
+    formulas_val = parse_json_value(formulas, "--formulas") if formulas else None
+    if formulas_val is not None and not isinstance(formulas_val, list):
+        raise typer.BadParameter("--formulas must be a JSON array")
+
+    async def factory(client: PipefyClient):
+        return await client.update_pipe_report(
+            report_id,
+            name=name.strip() if name else None,
+            color=color,
+            fields=fields_list,
+            filter=filt,
+            formulas=formulas_val,
+            featured_field=featured_field,
+        )
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@report_pipe_app.command("delete", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def report_pipe_delete(
+    ctx: typer.Context,
+    report_id: str = resource_id_argument(help="Pipe report id."),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    json_out: bool = typer.Option(
+        False, "--json", "-j", help="Print machine-readable JSON to stdout."
+    ),
+) -> None:
+    """Delete a pipe report (``delete_pipe_report``)."""
+    confirm_destructive(yes=yes, description=f"pipe report {report_id}", verb="delete")
+
+    async def factory(client: PipefyClient):
+        return await client.delete_pipe_report(report_id)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@report_pipe_app.command("export")
+def report_pipe_export(
+    ctx: typer.Context,
+    pipe: str = typer.Option(..., "--pipe", help="Pipe id."),
+    report_id: str = typer.Option(..., "--report-id", help="Pipe report id."),
+    format_: str = typer.Option(
+        "json",
+        "--format",
+        help="json: print mutation + poll metadata; csv: wait for fileURL and stream bytes.",
+    ),
+    sort_by: str | None = typer.Option(
+        None, "--sort-by", help="JSON ReportSortDirectionInput."
+    ),
+    filter_json: str | None = typer.Option(None, "--filter"),
+    columns: str | None = typer.Option(
+        None, "--columns", help="JSON array of column ids."
+    ),
+    poll_timeout: float = typer.Option(
+        90.0,
+        "--poll-timeout",
+        help="Seconds to poll export status before failing (CSV only).",
+    ),
+    json_out: bool = typer.Option(
+        False, "--json", "-j", help="Print machine-readable JSON to stdout."
+    ),
+) -> None:
+    """Start a pipe report export (``export_pipe_report``); csv waits and streams the file."""
+    fmt = format_.strip().lower()
+    if fmt not in ("json", "csv"):
+        raise typer.BadParameter("--format must be json or csv")
+    if fmt == "csv" and json_out:
+        raise typer.BadParameter(
+            "--json is mutually exclusive with --format csv (CSV is written as raw bytes to stdout)."
+        )
+    sort_obj = parse_json_object(sort_by, "--sort-by")
+    filt = prepare_report_cards_filter_cli(parse_json_object(filter_json, "--filter"))
+    cols = parse_json_value(columns, "--columns") if columns else None
+    if cols is not None and not isinstance(cols, list):
+        raise typer.BadParameter("--columns must be a JSON array")
+
+    if fmt == "json":
+
+        async def factory(client: PipefyClient):
+            return await client.export_pipe_report(
+                pipe,
+                report_id,
+                sort_by=sort_obj,
+                filter=filt,
+                columns=cols,
+            )
+
+        run_cli_command(ctx, json_out, factory)
+        return
+
+    async def csv_factory(client: PipefyClient) -> None:
+        start = await client.export_pipe_report(
+            pipe,
+            report_id,
+            sort_by=sort_obj,
+            filter=filt,
+            columns=cols,
+        )
+        exp = (start.get("exportPipeReport") or {}).get("pipeReportExport") or {}
+        export_id = exp.get("id")
+        if not export_id:
+            typer.echo(
+                "Could not read export id from exportPipeReport response.", err=True
+            )
+            raise typer.Exit(1)
+        await write_export_csv_to_stdout(
+            export_id=str(export_id),
+            poll_fetch=client.get_pipe_report_export,
+            unwrap_status=lambda raw: (raw or {}).get("pipeReportExport") or {},
+            poll_timeout_seconds=poll_timeout,
+        )
+
+    run_pipefy_client_coroutine(ctx, csv_factory, value_error_exit_code=1)

pipefy_cli/commands/table.py

@@ -0,0 +1,151 @@
+"""Database table subcommands."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import (
+    ID_POSITIONAL_CONTEXT_SETTINGS,
+    confirm_destructive,
+    parse_json_object,
+    resource_id_argument,
+    run_cli_command,
+)
+
+table_app = typer.Typer(help="Database table operations.", no_args_is_help=True)
+
+
+@table_app.command("list")
+def table_list(
+    ctx: typer.Context,
+    ids: str | None = typer.Option(
+        None,
+        "--ids",
+        help="Comma-separated table ids; when set, loads those tables via get_tables.",
+    ),
+    name: str | None = typer.Option(
+        None,
+        "--name",
+        "-n",
+        help="Optional table name filter (ignored when --ids is set).",
+    ),
+    first: int = typer.Option(
+        100,
+        "--first",
+        min=1,
+        max=500,
+        help="Max tables per organization when searching (1-500, default 100).",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Search tables across organizations, or fetch specific tables by id."""
+
+    id_list: list[str] | None = None
+    if ids is not None and ids.strip():
+        id_list = [p.strip() for p in ids.split(",") if p.strip()]
+        if not id_list:
+            raise typer.BadParameter("--ids must list at least one table id.")
+
+    async def factory(client: PipefyClient):
+        if id_list is not None:
+            return await client.get_tables(id_list)
+        return await client.search_tables(name, first=first)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@table_app.command("get", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def table_get(
+    ctx: typer.Context,
+    table_id: str = resource_id_argument(help="Table id."),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Load one table by id."""
+
+    async def factory(client: PipefyClient):
+        return await client.get_table(table_id)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@table_app.command("create")
+def table_create(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Table display name."),
+    org_id: str = typer.Option(
+        ...,
+        "--org",
+        help="Organization id that will own the table.",
+    ),
+    extra_json: str | None = typer.Option(
+        None,
+        "--extra",
+        help="JSON object of extra CreateTableInput fields.",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Create a database table."""
+
+    stripped = name.strip()
+    if not stripped:
+        typer.echo("Table name must be non-empty.", err=True)
+        raise typer.Exit(2)
+    extra = parse_json_object(extra_json, "--extra") or {}
+
+    async def factory(client: PipefyClient):
+        return await client.create_table(stripped, org_id, **extra)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@table_app.command("update", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def table_update(
+    ctx: typer.Context,
+    table_id: str = resource_id_argument(help="Table id."),
+    name: str | None = typer.Option(None, "--name"),
+    description: str | None = typer.Option(None, "--description", "-d"),
+    extra_json: str | None = typer.Option(
+        None,
+        "--extra",
+        help="JSON object merged into UpdateTableInput.",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Update table attributes."""
+
+    extra = parse_json_object(extra_json, "--extra") or {}
+    attrs: dict[str, Any] = {}
+    if name is not None:
+        attrs["name"] = name
+    if description is not None:
+        attrs["description"] = description
+    attrs.update(extra)
+    if not attrs:
+        raise typer.BadParameter(
+            "Provide at least one of: --name, --description, --extra (non-empty)."
+        )
+
+    async def factory(client: PipefyClient):
+        return await client.update_table(table_id, **attrs)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@table_app.command("delete", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def table_delete(
+    ctx: typer.Context,
+    table_id: str = resource_id_argument(help="Table id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Delete a database table permanently."""
+
+    confirm_destructive(yes=yes, description=f"table {table_id}")
+
+    async def factory(client: PipefyClient):
+        return await client.delete_table(table_id)
+
+    run_cli_command(ctx, json_out, factory)

pipefy_cli/commands/usage.py

@@ -0,0 +1,100 @@
+"""AI usage dashboards (agents, automations, credits)."""
+
+from __future__ import annotations
+
+import typer
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import parse_json_object, run_cli_command
+
+usage_app = typer.Typer(help="AI and automation usage metrics.", no_args_is_help=True)
+
+
+def _parse_date_range(from_iso: str, to_iso: str) -> dict[str, str]:
+    return {"from": from_iso.strip(), "to": to_iso.strip()}
+
+
+@usage_app.command("agents")
+def usage_agents(
+    ctx: typer.Context,
+    organization: str = typer.Option(
+        ...,
+        "--organization",
+        "--org",
+        help="Organization UUID (or numeric id resolvable by SDK).",
+    ),
+    date_from: str = typer.Option(
+        ..., "--from", help="ISO8601 start (filter_date.from)."
+    ),
+    date_to: str = typer.Option(..., "--to", help="ISO8601 end (filter_date.to)."),
+    filters: str | None = typer.Option(
+        None, "--filters", help="Optional JSON object (FilterParams shape)."
+    ),
+    search: str | None = typer.Option(
+        None, "--search", help="Optional free-text search."
+    ),
+    sort: str | None = typer.Option(
+        None, "--sort", help="Optional JSON sort criteria object."
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """AI agent usage for an org (``get_agents_usage``)."""
+    filt = parse_json_object(filters, "--filters")
+    sort_obj = parse_json_object(sort, "--sort")
+
+    async def factory(client: PipefyClient):
+        return await client.get_agents_usage(
+            organization,
+            _parse_date_range(date_from, date_to),
+            filters=filt,
+            search=search,
+            sort=sort_obj,
+        )
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@usage_app.command("automations")
+def usage_automations(
+    ctx: typer.Context,
+    organization: str = typer.Option(..., "--organization", "--org"),
+    date_from: str = typer.Option(..., "--from"),
+    date_to: str = typer.Option(..., "--to"),
+    filters: str | None = typer.Option(None, "--filters"),
+    search: str | None = typer.Option(None, "--search"),
+    sort: str | None = typer.Option(None, "--sort"),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Automation usage for an org (``get_automations_usage``)."""
+    filt = parse_json_object(filters, "--filters")
+    sort_obj = parse_json_object(sort, "--sort")
+
+    async def factory(client: PipefyClient):
+        return await client.get_automations_usage(
+            organization,
+            _parse_date_range(date_from, date_to),
+            filters=filt,
+            search=search,
+            sort=sort_obj,
+        )
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@usage_app.command("credits")
+def usage_credits(
+    ctx: typer.Context,
+    organization: str = typer.Option(..., "--organization", "--org"),
+    period: str = typer.Option(
+        "current_month",
+        "--period",
+        help="current_month | last_month | last_3_months",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """AI credit usage dashboard (``get_ai_credit_usage``)."""
+
+    async def factory(client: PipefyClient):
+        return await client.get_ai_credit_usage(organization, period)
+
+    run_cli_command(ctx, json_out, factory)

pipefy_cli/commands/webhook.py

@@ -0,0 +1,141 @@
+"""Webhook subcommands."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import (
+    ID_POSITIONAL_CONTEXT_SETTINGS,
+    confirm_destructive,
+    parse_json_object,
+    resource_id_argument,
+    run_cli_command,
+)
+
+webhook_app = typer.Typer(help="Pipe webhook operations.", no_args_is_help=True)
+
+
+def _parse_actions_json(raw: str) -> list[str]:
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"Invalid JSON for --actions: {exc}") from exc
+    if not isinstance(parsed, list) or not parsed:
+        raise typer.BadParameter("--actions must be a non-empty JSON array of strings.")
+    out: list[str] = []
+    for item in parsed:
+        if not isinstance(item, str) or not item.strip():
+            raise typer.BadParameter("Each action must be a non-empty string.")
+        out.append(item.strip())
+    return out
+
+
+@webhook_app.command("list")
+def webhook_list(
+    ctx: typer.Context,
+    pipe_id: str = typer.Option(..., "--pipe", help="Pipe id."),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """List webhooks on a pipe."""
+
+    async def factory(client: PipefyClient):
+        return await client.get_webhooks(pipe_id)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@webhook_app.command("create")
+def webhook_create(
+    ctx: typer.Context,
+    pipe_id: str = typer.Option(..., "--pipe", help="Pipe id."),
+    url: str = typer.Option(..., "--url", help="HTTPS callback URL."),
+    actions_json: str = typer.Option(
+        ...,
+        "--actions",
+        help='JSON array of event action strings, e.g. \'["card.create","card.move"]\'.',
+    ),
+    extra_json: str | None = typer.Option(
+        None,
+        "--extra",
+        help="JSON object of extra CreateWebhookInput fields.",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Create a webhook."""
+
+    actions = _parse_actions_json(actions_json)
+    extra = parse_json_object(extra_json, "--extra") or {}
+    u = url.strip()
+    if not u:
+        typer.echo("--url must be non-empty.", err=True)
+        raise typer.Exit(2)
+
+    async def factory(client: PipefyClient):
+        return await client.create_webhook(pipe_id, u, actions, **extra)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@webhook_app.command("update", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def webhook_update(
+    ctx: typer.Context,
+    webhook_id: str = resource_id_argument(help="Webhook id."),
+    name: str | None = typer.Option(None, "--name"),
+    url: str | None = typer.Option(None, "--url"),
+    actions_json: str | None = typer.Option(
+        None,
+        "--actions",
+        help="JSON array of event action strings (non-empty when provided).",
+    ),
+    headers_json: str | None = typer.Option(
+        None,
+        "--headers",
+        help="JSON object of custom HTTP headers.",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Update a webhook (pass at least one attribute)."""
+
+    kwargs: dict[str, Any] = {}
+    if name is not None:
+        if not name.strip():
+            raise typer.BadParameter("--name, when provided, must be non-empty.")
+        kwargs["name"] = name.strip()
+    if url is not None:
+        if not url.strip():
+            raise typer.BadParameter("--url, when provided, must be non-empty.")
+        kwargs["url"] = url.strip()
+    if actions_json is not None:
+        kwargs["actions"] = _parse_actions_json(actions_json)
+    if headers_json is not None:
+        kwargs["headers"] = parse_json_object(headers_json, "--headers") or {}
+    if not kwargs:
+        raise typer.BadParameter(
+            "Provide at least one of: --name, --url, --actions, --headers."
+        )
+
+    async def factory(client: PipefyClient):
+        return await client.update_webhook(webhook_id, **kwargs)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@webhook_app.command("delete", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def webhook_delete(
+    ctx: typer.Context,
+    webhook_id: str = resource_id_argument(help="Webhook id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Delete a webhook permanently."""
+
+    confirm_destructive(yes=yes, description=f"webhook {webhook_id}")
+
+    async def factory(client: PipefyClient):
+        return await client.delete_webhook(webhook_id)
+
+    run_cli_command(ctx, json_out, factory)