pipefy-cli 0.3.0a1__py3-none-any.whl

pipefy_cli/commands/member.py

@@ -0,0 +1,126 @@
+"""Pipe member subcommands."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import typer
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import (
+    confirm_destructive,
+    run_cli_command,
+)
+
+member_app = typer.Typer(help="Pipe member operations.", no_args_is_help=True)
+
+
+def _parse_members_json(raw: str) -> list[dict[str, Any]]:
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"Invalid JSON for --members: {exc}") from exc
+    if not isinstance(parsed, list) or not parsed:
+        raise typer.BadParameter("--members must be a non-empty JSON array of objects.")
+    for i, item in enumerate(parsed):
+        if not isinstance(item, dict):
+            raise typer.BadParameter(f"--members[{i}] must be an object.")
+        if "email" not in item or "role_name" not in item:
+            raise typer.BadParameter(
+                f"--members[{i}] must include 'email' and 'role_name'."
+            )
+    return parsed
+
+
+def _parse_user_ids(raw: str) -> list[str]:
+    parts = [p.strip() for p in raw.replace(",", " ").split() if p.strip()]
+    if not parts:
+        raise typer.BadParameter(
+            "Provide at least one user id (comma-separated or space-separated)."
+        )
+    return parts
+
+
+@member_app.command("list")
+def member_list(
+    ctx: typer.Context,
+    pipe_id: str = typer.Option(..., "--pipe", help="Pipe id."),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """List members of a pipe."""
+
+    async def factory(client: PipefyClient):
+        return await client.get_pipe_members(pipe_id)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@member_app.command("invite")
+def member_invite(
+    ctx: typer.Context,
+    pipe_id: str = typer.Option(..., "--pipe", help="Pipe id."),
+    members_json: str = typer.Option(
+        ...,
+        "--members",
+        help='JSON array: [{"email":"a@b.com","role_name":"admin"}, ...].',
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Invite users to a pipe."""
+
+    members = _parse_members_json(members_json)
+
+    async def factory(client: PipefyClient):
+        return await client.invite_members(pipe_id, members)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@member_app.command("remove")
+def member_remove(
+    ctx: typer.Context,
+    pipe_id: str = typer.Option(..., "--pipe", help="Pipe id."),
+    user_ids: str = typer.Option(
+        ...,
+        "--user-ids",
+        help="Comma-separated Pipefy user ids or UUIDs to remove from the pipe.",
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Remove users from a pipe."""
+
+    ids = _parse_user_ids(user_ids)
+
+    confirm_destructive(
+        yes=yes, verb="remove", description=f"{len(ids)} member(s) from pipe {pipe_id}"
+    )
+
+    async def factory(client: PipefyClient):
+        return await client.remove_members_from_pipe(pipe_id, ids)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@member_app.command("set-role")
+def member_set_role(
+    ctx: typer.Context,
+    pipe_id: str = typer.Option(..., "--pipe", help="Pipe id."),
+    member_id: str = typer.Option(..., "--member", help="Member user id."),
+    role_name: str = typer.Option(
+        ..., "--role", help="Role name (e.g. member, admin)."
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Set a member's role on a pipe."""
+
+    rn = role_name.strip()
+    if not rn:
+        typer.echo("--role must be non-empty.", err=True)
+        raise typer.Exit(2)
+
+    async def factory(client: PipefyClient):
+        return await client.set_role(pipe_id, member_id, rn)
+
+    run_cli_command(ctx, json_out, factory)

pipefy_cli/commands/org.py

@@ -0,0 +1,60 @@
+"""Organization metadata (read-only)."""
+
+from __future__ import annotations
+
+import typer
+from pipefy_sdk import PipefyClient
+
+from pipefy_cli.commands._common import (
+    ID_POSITIONAL_CONTEXT_SETTINGS,
+    run_cli_command,
+    settings_and_token,
+    validate_positional_id,
+)
+
+org_app = typer.Typer(help="Organization operations.", no_args_is_help=True)
+
+_MISSING_ORG_ID = (
+    "Missing organization id. Pass ORGANIZATION_ID as the first argument, set "
+    "PIPEFY_ORG_ID in the environment, or obtain an id from "
+    "`pipefy pipe list --json` (organizations[].id)."
+)
+
+
+def _optional_org_id(value: str | None) -> str | None:
+    if value is None:
+        return None
+    return validate_positional_id(value)
+
+
+@org_app.command("get", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def org_get(
+    ctx: typer.Context,
+    organization_id: str | None = typer.Argument(
+        None,
+        help=(
+            "Numeric organization id. Omit when PIPEFY_ORG_ID is set "
+            "(see docs/config.md)."
+        ),
+        callback=_optional_org_id,
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Fetch organization details (``get_organization``)."""
+
+    pipefy_settings, _token = settings_and_token(ctx)
+    resolved = (organization_id or "").strip()
+    if not resolved:
+        env_default = pipefy_settings.org_id
+        resolved = env_default.strip() if env_default else ""
+
+    if not resolved:
+        typer.echo(_MISSING_ORG_ID, err=True)
+        raise typer.Exit(2)
+
+    oid = resolved
+
+    async def factory(client: PipefyClient):
+        return await client.get_organization(oid)
+
+    run_cli_command(ctx, json_out, factory)

pipefy_cli/commands/phase.py

@@ -0,0 +1,264 @@
+"""Phase subcommands."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+from pipefy_sdk import PipefyClient
+from pipefy_sdk.phase_inventory import (
+    get_phase_not_found_message,
+    is_get_phase_not_found_error,
+)
+
+from pipefy_cli.commands._common import (
+    ID_POSITIONAL_CONTEXT_SETTINGS,
+    confirm_destructive,
+    parse_json_object,
+    resource_id_argument,
+    run_cli_command,
+    validate_cards_page_size,
+)
+
+phase_app = typer.Typer(help="Pipe phase operations.", no_args_is_help=True)
+
+
+@phase_app.command("get", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def phase_get(
+    ctx: typer.Context,
+    phase_id: str = resource_id_argument(help="Phase id."),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Print machine-readable JSON to stdout.",
+    ),
+    required_only: bool = typer.Option(
+        False,
+        "--required-only",
+        help="Return only required fields (same query as MCP get_phase_fields).",
+    ),
+) -> None:
+    """Load phase metadata and fields by id (via ``get_phase_fields``)."""
+
+    async def factory(client: PipefyClient):
+        return await client.get_phase_fields(phase_id, required_only=required_only)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@phase_app.command(
+    "targets",
+    context_settings=ID_POSITIONAL_CONTEXT_SETTINGS,
+)
+def phase_targets(
+    ctx: typer.Context,
+    phase_id: str = resource_id_argument(
+        help="Source phase id (card's current phase)."
+    ),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Print machine-readable JSON to stdout.",
+    ),
+) -> None:
+    """List phases a card may move to from this phase (UI transition rules)."""
+
+    async def factory(client: PipefyClient):
+        return await client.get_phase_allowed_move_targets(phase_id)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@phase_app.command(
+    "count",
+    context_settings=ID_POSITIONAL_CONTEXT_SETTINGS,
+)
+def phase_count(
+    ctx: typer.Context,
+    phase_id: str = resource_id_argument(help="Phase id."),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Print machine-readable JSON to stdout.",
+    ),
+) -> None:
+    """Return native ``Phase.cards_count`` for a phase (fast inventory).
+
+    On the start-form phase, ``cards_count`` may be 0 while cards still exist;
+    use ``pipefy phase cards`` to list cards when the count looks wrong.
+    """
+
+    async def factory(client: PipefyClient):
+        try:
+            return await client.get_phase(phase_id)
+        except ValueError as exc:
+            if is_get_phase_not_found_error(exc):
+                raise ValueError(get_phase_not_found_message(phase_id)) from exc
+            raise
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@phase_app.command("cards", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def phase_cards(
+    ctx: typer.Context,
+    phase_id: str = resource_id_argument(help="Phase id."),
+    first: int = typer.Option(
+        50,
+        "--first",
+        help="Max cards per page (1-500).",
+    ),
+    after: str | None = typer.Option(
+        None,
+        "--after",
+        help="Cursor from pageInfo.endCursor of a previous call.",
+    ),
+    include_fields: bool = typer.Option(
+        False,
+        "--include-fields",
+        help="Include each card's custom fields in the response.",
+    ),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Print machine-readable JSON to stdout.",
+    ),
+) -> None:
+    """List cards in a phase (``Phase.cards`` pagination)."""
+
+    first = validate_cards_page_size(first)
+
+    async def factory(client: PipefyClient):
+        return await client.get_phase_cards(
+            phase_id,
+            first=first,
+            after=after,
+            include_fields=include_fields,
+        )
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@phase_app.command("create")
+def phase_create(
+    ctx: typer.Context,
+    pipe_id: str = typer.Option(
+        ..., "--pipe", help="Pipe id that will contain the phase."
+    ),
+    name: str = typer.Option(..., "--name", "-n", help="Phase display name."),
+    done: bool = typer.Option(False, "--done", help="Mark as a final/done phase."),
+    index: float | None = typer.Option(
+        None,
+        "--index",
+        help="Optional position index within the pipe.",
+    ),
+    description: str | None = typer.Option(None, "--description", "-d"),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Create a phase in a pipe."""
+
+    stripped = name.strip()
+    if not stripped:
+        typer.echo("Phase name must be non-empty.", err=True)
+        raise typer.Exit(2)
+
+    async def factory(client: PipefyClient):
+        return await client.create_phase(
+            pipe_id,
+            stripped,
+            done=done,
+            index=index,
+            description=description,
+        )
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@phase_app.command("update", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def phase_update(
+    ctx: typer.Context,
+    phase_id: str = resource_id_argument(help="Phase id."),
+    name: str | None = typer.Option(None, "--name", "-n"),
+    description: str | None = typer.Option(None, "--description", "-d"),
+    done: bool | None = typer.Option(
+        None,
+        "--done/--no-done",
+        help="Set or clear the final-phase flag.",
+    ),
+    color: str | None = typer.Option(None, "--color"),
+    lateness_time: int | None = typer.Option(None, "--lateness-time"),
+    can_receive_from_draft: bool | None = typer.Option(
+        None,
+        "--can-receive-from-draft/--no-can-receive-from-draft",
+    ),
+    extra_json: str | None = typer.Option(
+        None,
+        "--extra",
+        help="JSON object merged into UpdatePhaseInput (snake_case keys).",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Update a phase (Pipefy ``UpdatePhaseInput``). Resolves current name when omitted."""
+
+    extra = parse_json_object(extra_json, "--extra")
+    update_attrs: dict[str, Any] = {}
+    if name is not None:
+        update_attrs["name"] = name
+    if description is not None:
+        update_attrs["description"] = description
+    if done is not None:
+        update_attrs["done"] = done
+    if color is not None:
+        update_attrs["color"] = color
+    if lateness_time is not None:
+        update_attrs["lateness_time"] = lateness_time
+    if can_receive_from_draft is not None:
+        update_attrs["can_receive_card_directly_from_draft"] = can_receive_from_draft
+    if extra:
+        update_attrs.update(extra)
+    if not update_attrs:
+        typer.echo(
+            "Provide at least one of: --name, --description, --done, --color, "
+            "--lateness-time, --can-receive-from-draft, --extra.",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    async def factory(client: PipefyClient):
+        if "name" not in update_attrs:
+            phase_info = await client.get_phase_fields(phase_id)
+            current = phase_info.get("phase_name")
+            if not current:
+                raise typer.BadParameter(
+                    f"Phase {phase_id} not found or has no name; pass --name explicitly."
+                )
+            update_attrs["name"] = current
+        return await client.update_phase(phase_id, **update_attrs)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@phase_app.command("delete", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def phase_delete(
+    ctx: typer.Context,
+    phase_id: str = resource_id_argument(help="Phase id."),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip confirmation prompt.",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Delete a phase permanently."""
+
+    confirm_destructive(yes=yes, description=f"phase {phase_id}")
+
+    async def factory(client: PipefyClient):
+        return await client.delete_phase(phase_id)
+
+    run_cli_command(ctx, json_out, factory)

pipefy_cli/commands/pipe.py

@@ -0,0 +1,167 @@
+"""Pipe subcommands."""
+
+from __future__ import annotations
+
+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,
+)
+
+pipe_app = typer.Typer(help="Pipe operations.", no_args_is_help=True)
+
+
+@pipe_app.command("get", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def pipe_get(
+    ctx: typer.Context,
+    pipe_id: str = resource_id_argument(help="Pipe id."),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Print machine-readable JSON to stdout.",
+    ),
+) -> None:
+    """Load a pipe by id (phases, labels, start form)."""
+
+    async def factory(client: PipefyClient):
+        return await client.get_pipe(pipe_id)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@pipe_app.command("list")
+def pipe_list(
+    ctx: typer.Context,
+    name: str | None = typer.Option(
+        None,
+        "--name",
+        "-n",
+        help="Optional pipe name filter (fuzzy match server-side).",
+    ),
+    max_per_org: int = typer.Option(
+        500,
+        "--max-per-org",
+        min=1,
+        max=500,
+        help="Maximum pipes returned per organization (1-500).",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Search pipes across organizations (same as MCP ``search_pipes``)."""
+
+    async def factory(client: PipefyClient):
+        return await client.search_pipes(name, max_pipes_per_org=max_per_org)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@pipe_app.command("create")
+def pipe_create(
+    ctx: typer.Context,
+    name: str = typer.Argument(..., help="Display name for the new pipe."),
+    org_id: str = typer.Option(
+        ...,
+        "--org",
+        help="Organization id that will own the pipe.",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Create an empty pipe in an organization."""
+
+    stripped = name.strip()
+    if not stripped:
+        typer.echo("Pipe name must be non-empty.", err=True)
+        raise typer.Exit(2)
+
+    async def factory(client: PipefyClient):
+        return await client.create_pipe(stripped, org_id)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@pipe_app.command("update", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def pipe_update(
+    ctx: typer.Context,
+    pipe_id: str = resource_id_argument(help="Pipe id."),
+    name: str | None = typer.Option(None, "--name"),
+    icon: str | None = typer.Option(None, "--icon"),
+    color: str | None = typer.Option(None, "--color"),
+    preferences_json: str | None = typer.Option(
+        None,
+        "--preferences",
+        help="JSON object for pipe preferences (UpdatePipeInput).",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Update pipe settings (pass at least one attribute)."""
+
+    preferences = parse_json_object(preferences_json, "--preferences")
+    if preferences == {}:
+        preferences = None
+    if all(x is None for x in (name, icon, color, preferences)):
+        raise typer.BadParameter(
+            "Provide at least one of: --name, --icon, --color, --preferences (non-empty)."
+        )
+
+    async def factory(client: PipefyClient):
+        return await client.update_pipe(
+            pipe_id,
+            name=name,
+            icon=icon,
+            color=color,
+            preferences=preferences,
+        )
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@pipe_app.command("delete", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def pipe_delete(
+    ctx: typer.Context,
+    pipe_id: str = resource_id_argument(help="Pipe id."),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip confirmation prompt.",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Delete a pipe permanently."""
+
+    confirm_destructive(yes=yes, description=f"pipe {pipe_id}")
+
+    async def factory(client: PipefyClient):
+        return await client.delete_pipe(pipe_id)
+
+    run_cli_command(ctx, json_out, factory)
+
+
+@pipe_app.command("clone", context_settings=ID_POSITIONAL_CONTEXT_SETTINGS)
+def pipe_clone(
+    ctx: typer.Context,
+    template_pipe_id: str = resource_id_argument(
+        help="Source pipe id to use as template.",
+    ),
+    org_id: str | None = typer.Option(
+        None,
+        "--org",
+        help="Optional organization id for the cloned pipe.",
+    ),
+    json_out: bool = typer.Option(False, "--json", "-j"),
+) -> None:
+    """Clone a pipe from a template pipe id."""
+
+    async def factory(client: PipefyClient):
+        return await client.clone_pipe(
+            template_pipe_id,
+            organization_id=org_id,
+        )
+
+    run_cli_command(ctx, json_out, factory)