tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/social_3.py

@@ -0,0 +1,618 @@
+"""Pure async operations for the social API — group membership, ownership,
+content links, and Arena cohort standings/joins.
+
+This module wraps a slice of the ``/api/v1/social`` router covering:
+
+* group ownership transfer + member removal / leave-for / accept / decline /
+  role + label changes,
+* sub-group removal and group content (events listing, goal/value unlink),
+* Arena cohort standings (Everyone + any group) and joins, plus the caller's
+  own skill-tree cohort participation.
+
+Every op is a thin async wrapper over :class:`TetraClient`; optional body and
+query fields that are ``None`` are omitted so the backend's own defaults apply.
+"""
+from typing import Any
+from urllib.parse import urlencode
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+# All social routes are mounted under this prefix.
+_BASE = "/api/v1/social"
+
+
+# =============================================================================
+# OWNERSHIP + MEMBERSHIP
+# =============================================================================
+
+@operation(
+    cli="social transfer-ownership",
+    summary="Transfer group ownership to another member.",
+    covers=[("POST", "/api/v1/social/groups/{uid}/transfer")],
+    params={
+        "uid": arg(help="Group UID whose ownership is being transferred"),
+        "new_owner_group_uid": opt(
+            "--new-owner",
+            help="Group UID of the new owner (a member of this group).",
+        ),
+    },
+)
+async def transfer_group_ownership(
+    client: TetraClient,
+    *,
+    uid: str,
+    new_owner_group_uid: str,
+) -> dict[str, Any]:
+    """Transfer ownership of a group to another member.
+
+    The new owner is identified by their group UID (people are groups of
+    one). ``new_owner_group_uid`` is sent as a query parameter to mirror the
+    backend handler signature.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Group UID whose ownership is being transferred
+        new_owner_group_uid: Group UID of the new owner
+
+    Returns:
+        The new owner's membership record.
+    """
+    query = urlencode({"new_owner_group_uid": new_owner_group_uid})
+    return await client.post(f"{_BASE}/groups/{uid}/transfer?{query}")
+
+
+@operation(
+    cli="social remove-member",
+    summary="Remove (kick) a member from a group.",
+    covers=[("DELETE", "/api/v1/social/groups/{uid}/members/{member_uid}")],
+    params={
+        "uid": arg(help="Group UID"),
+        "member_uid": arg(help="Member's group UID to remove"),
+    },
+)
+async def remove_group_member(
+    client: TetraClient, uid: str, member_uid: str,
+) -> dict[str, Any]:
+    """Remove a member from a group (kick).
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Group UID
+        member_uid: Group UID of the member to remove
+
+    Returns:
+        Deletion confirmation dict (the endpoint returns 204).
+    """
+    return await client.delete(f"{_BASE}/groups/{uid}/members/{member_uid}")
+
+
+@operation(
+    cli="social leave-for",
+    summary="Remove an owned group from another group.",
+    covers=[("POST", "/api/v1/social/groups/{uid}/leave/{member_uid}")],
+    params={
+        "uid": arg(help="Group UID to leave"),
+        "member_uid": arg(help="Owned group UID being withdrawn from the group"),
+    },
+)
+async def leave_group_for(
+    client: TetraClient, uid: str, member_uid: str,
+) -> dict[str, Any]:
+    """Withdraw an owned group from another group's membership.
+
+    The caller must own ``member_uid``. The membership is fully deleted.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Group UID to leave
+        member_uid: Group UID (owned by the caller) being withdrawn
+
+    Returns:
+        Status dict ``{"status": "left"}``.
+    """
+    return await client.post(f"{_BASE}/groups/{uid}/leave/{member_uid}", json=None)
+
+
+@operation(
+    cli="social accept-member",
+    summary="Accept an invite or approve a join request for a member.",
+    covers=[("POST", "/api/v1/social/groups/{uid}/members/{member_uid}/accept")],
+    params={
+        "uid": arg(help="Group UID"),
+        "member_uid": arg(help="Member's group UID (own UID to accept own invite)"),
+        "requested_label": opt(
+            "--requested-label", choices=["mentor", "mentee", "coop"],
+            help="Optionally request a different label on accept.",
+        ),
+    },
+)
+async def accept_group_member(
+    client: TetraClient,
+    uid: str,
+    member_uid: str,
+    *,
+    requested_label: str | None = None,
+) -> dict[str, Any]:
+    """Accept an invitation (invitee) or approve a join request (admin).
+
+    Pass ``requested_label`` to request a different label than the one
+    assigned; downgrades auto-accept while upgrades await owner approval.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Group UID
+        member_uid: Member's group UID. Use the caller's own personal-group
+            UID to accept their own invitation.
+        requested_label: Optional requested label (mentor/mentee/coop).
+
+    Returns:
+        The resulting membership record.
+    """
+    body: dict[str, Any] | None = None
+    if requested_label is not None:
+        body = {"requested_label": requested_label}
+    return await client.post(
+        f"{_BASE}/groups/{uid}/members/{member_uid}/accept", json=body,
+    )
+
+
+@operation(
+    cli="social decline-member",
+    summary="Decline an invite or deny a join request for a member.",
+    covers=[("POST", "/api/v1/social/groups/{uid}/members/{member_uid}/decline")],
+    params={
+        "uid": arg(help="Group UID"),
+        "member_uid": arg(help="Member's group UID (own UID to decline own invite)"),
+    },
+)
+async def decline_group_member(
+    client: TetraClient, uid: str, member_uid: str,
+) -> dict[str, Any]:
+    """Decline an invitation (invitee) or deny a join request (admin).
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Group UID
+        member_uid: Member's group UID
+
+    Returns:
+        Deletion confirmation dict (the endpoint returns 204).
+    """
+    return await client.post(
+        f"{_BASE}/groups/{uid}/members/{member_uid}/decline", json=None,
+    )
+
+
+@operation(
+    cli="social member-label",
+    summary="Change a member's role label (mentor/mentee/coop).",
+    covers=[("PUT", "/api/v1/social/groups/{uid}/members/{member_uid}/label")],
+    params={
+        "uid": arg(help="Group UID"),
+        "member_uid": arg(help="Member's group UID"),
+        "label": opt(
+            "--label", choices=["mentor", "mentee", "coop"],
+            help="New role label.",
+        ),
+    },
+)
+async def update_member_label(
+    client: TetraClient,
+    uid: str,
+    member_uid: str,
+    *,
+    label: str,
+) -> dict[str, Any]:
+    """Change a member's role label (mentor/mentee/coop).
+
+    Only the group owner may change labels; changing power dynamics triggers
+    a consent reset. ``label`` is sent as a query parameter to mirror the
+    backend handler signature.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Group UID
+        member_uid: Member's group UID
+        label: New label — one of mentor/mentee/coop
+
+    Returns:
+        The updated membership record.
+    """
+    query = urlencode({"label": label})
+    return await client.put(
+        f"{_BASE}/groups/{uid}/members/{member_uid}/label?{query}",
+    )
+
+
+@operation(
+    cli="social member-role",
+    summary="Change a member's role (owner/admin/member).",
+    covers=[("PUT", "/api/v1/social/groups/{uid}/members/{member_uid}/role")],
+    params={
+        "uid": arg(help="Group UID"),
+        "member_uid": arg(help="Member's group UID"),
+        "role": opt(
+            "--role", choices=["owner", "admin", "member"],
+            help="New role.",
+        ),
+    },
+)
+async def update_member_role(
+    client: TetraClient,
+    uid: str,
+    member_uid: str,
+    *,
+    role: str,
+) -> dict[str, Any]:
+    """Change a member's role (owner/admin/member).
+
+    ``role`` is sent as a query parameter to mirror the backend handler
+    signature. Promoting to owner and demoting are handled server-side.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Group UID
+        member_uid: Member's group UID
+        role: New role — one of owner/admin/member
+
+    Returns:
+        The updated membership record.
+    """
+    query = urlencode({"role": role})
+    return await client.put(
+        f"{_BASE}/groups/{uid}/members/{member_uid}/role?{query}",
+    )
+
+
+@operation(
+    cli="social remove-sub-group",
+    summary="Remove a sub-group from a composite group.",
+    covers=[("DELETE", "/api/v1/social/groups/{uid}/sub-groups/{sub_uid}")],
+    params={
+        "uid": arg(help="Composite group UID"),
+        "sub_uid": arg(help="Sub-group UID to remove"),
+    },
+)
+async def remove_sub_group(
+    client: TetraClient, uid: str, sub_uid: str,
+) -> dict[str, Any]:
+    """Remove a sub-group from a composite group.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Composite group UID
+        sub_uid: Sub-group UID to remove
+
+    Returns:
+        Deletion confirmation dict (the endpoint returns 204).
+    """
+    return await client.delete(f"{_BASE}/groups/{uid}/sub-groups/{sub_uid}")
+
+
+# =============================================================================
+# GROUP CONTENT
+# =============================================================================
+
+@operation(
+    cli="social group-events",
+    summary="List events from group members' mapped goals and values.",
+    covers=[("GET", "/api/v1/social/groups/{uid}/content/events")],
+    params={
+        "uid": arg(help="Group UID"),
+        "member_uid": opt("--member-uid", help="Filter by member account UID."),
+        "goal": opt("--goal", help="Filter by group goal name."),
+        "value": opt("--value", help="Filter by group value name."),
+        "start_date": opt("--start-date", help="On or after (YYYY-MM-DD)."),
+        "end_date": opt("--end-date", help="On or before (YYYY-MM-DD)."),
+        "limit": opt("--limit", min=1, max=200, help="Pagination limit (1-200)."),
+        "offset": opt("--offset", min=0, help="Pagination offset."),
+    },
+)
+async def list_group_member_events(
+    client: TetraClient,
+    uid: str,
+    *,
+    member_uid: str | None = None,
+    goal: str | None = None,
+    value: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    limit: int | None = None,
+    offset: int | None = None,
+) -> dict[str, Any]:
+    """List events from group members' mapped goals and values.
+
+    Returns events with member attribution and group goal/value context.
+    Any active member can view; blind groups return an empty result. All
+    filters are optional query parameters; ``None`` values are dropped by the
+    client so the backend defaults (limit=50, offset=0) apply.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Group UID
+        member_uid: Filter by member account UID
+        goal: Filter by group goal name
+        value: Filter by group value name
+        start_date: Inclusive lower bound (YYYY-MM-DD)
+        end_date: Inclusive upper bound (YYYY-MM-DD)
+        limit: Pagination limit (1-200)
+        offset: Pagination offset (>=0)
+
+    Returns:
+        Dict with ``events``, ``total``, and ``members``.
+    """
+    params: dict[str, Any] = {
+        "member_uid": member_uid,
+        "goal": goal,
+        "value": value,
+        "start_date": start_date,
+        "end_date": end_date,
+        "limit": limit,
+        "offset": offset,
+    }
+    return await client.get(f"{_BASE}/groups/{uid}/content/events", params=params)
+
+
+@operation(
+    cli="social unlink-goal",
+    summary="Unlink a personal goal from a group goal.",
+    covers=[("DELETE", "/api/v1/social/groups/{uid}/content/goals/{goal_uid}/link")],
+    params={
+        "uid": arg(help="Group UID"),
+        "goal_uid": arg(help="Group goal UID to unlink"),
+    },
+)
+async def unlink_group_goal(
+    client: TetraClient, uid: str, goal_uid: str,
+) -> dict[str, Any]:
+    """Remove the link between a personal goal and a group goal.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Group UID
+        goal_uid: Group goal UID to unlink
+
+    Returns:
+        Deletion confirmation dict (the endpoint returns 204).
+    """
+    return await client.delete(
+        f"{_BASE}/groups/{uid}/content/goals/{goal_uid}/link",
+    )
+
+
+@operation(
+    cli="social unlink-value",
+    summary="Unlink a personal value from a group value.",
+    covers=[("DELETE", "/api/v1/social/groups/{uid}/content/values/{val_uid}/link")],
+    params={
+        "uid": arg(help="Group UID"),
+        "val_uid": arg(help="Group value UID to unlink"),
+    },
+)
+async def unlink_group_value(
+    client: TetraClient, uid: str, val_uid: str,
+) -> dict[str, Any]:
+    """Remove the link between a personal value and a group value.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Group UID
+        val_uid: Group value UID to unlink
+
+    Returns:
+        Deletion confirmation dict (the endpoint returns 204).
+    """
+    return await client.delete(
+        f"{_BASE}/groups/{uid}/content/values/{val_uid}/link",
+    )
+
+
+# =============================================================================
+# ARENA — EVERYONE COHORTS
+# =============================================================================
+
+@operation(
+    cli="social everyone-tree-standings",
+    summary="Leaderboard + viewer standing for an Everyone skill-tree cohort.",
+    covers=[(
+        "GET",
+        "/api/v1/social/groups/everyone/skill-trees/{cohort_value_uid}/standings",
+    )],
+    params={"cohort_value_uid": arg(help="Cohort value (skill tree) UID")},
+)
+async def everyone_tree_standings(
+    client: TetraClient, cohort_value_uid: str,
+) -> dict[str, Any]:
+    """Top-50 leaderboard plus the viewer's standing for one Everyone skill tree.
+
+    The viewer's row is always included even when outside the top 50; an empty
+    cohort returns an empty leaderboard and a viewer with ``rank=None``.
+
+    Args:
+        client: Authenticated TetraClient
+        cohort_value_uid: Cohort value (skill tree) UID
+
+    Returns:
+        Standings dict (leaderboard + viewer).
+    """
+    return await client.get(
+        f"{_BASE}/groups/everyone/skill-trees/{cohort_value_uid}/standings",
+    )
+
+
+@operation(
+    cli="social everyone-goal-standings",
+    summary="Leaderboard + viewer standing for an Everyone goal cohort.",
+    covers=[(
+        "GET",
+        "/api/v1/social/groups/everyone/goals/{cohort_goal_uid}/standings",
+    )],
+    params={"cohort_goal_uid": arg(help="Cohort goal UID")},
+)
+async def everyone_goal_standings(
+    client: TetraClient, cohort_goal_uid: str,
+) -> dict[str, Any]:
+    """Top-50 leaderboard plus the viewer's standing for one Everyone goal cohort.
+
+    Members are ranked by their best single-event score descending.
+
+    Args:
+        client: Authenticated TetraClient
+        cohort_goal_uid: Cohort goal UID
+
+    Returns:
+        Standings dict (leaderboard + viewer).
+    """
+    return await client.get(
+        f"{_BASE}/groups/everyone/goals/{cohort_goal_uid}/standings",
+    )
+
+
+@operation(
+    cli="social everyone-join-tree",
+    summary="Adopt a published skill tree and join its Everyone cohort.",
+    covers=[(
+        "POST",
+        "/api/v1/social/groups/everyone/skill-trees/{cohort_value_uid}/join",
+    )],
+    params={"cohort_value_uid": arg(help="Cohort value (skill tree) UID")},
+)
+async def everyone_join_tree(
+    client: TetraClient, cohort_value_uid: str,
+) -> dict[str, Any]:
+    """Adopt a published skill tree and join its Everyone cohort.
+
+    Idempotent: when already a member, returns the current standing without
+    re-adopting.
+
+    Args:
+        client: Authenticated TetraClient
+        cohort_value_uid: Cohort value (skill tree) UID
+
+    Returns:
+        The viewer's standing in the joined cohort.
+    """
+    return await client.post(
+        f"{_BASE}/groups/everyone/skill-trees/{cohort_value_uid}/join", json=None,
+    )
+
+
+@operation(
+    cli="social everyone-join-goal",
+    summary="Adopt a public goal and join its Everyone cohort.",
+    covers=[("POST", "/api/v1/social/groups/everyone/goals/{cohort_goal_uid}/join")],
+    params={"cohort_goal_uid": arg(help="Cohort goal UID")},
+)
+async def everyone_join_goal(
+    client: TetraClient, cohort_goal_uid: str,
+) -> dict[str, Any]:
+    """Adopt a public goal and join its Everyone cohort.
+
+    Idempotent via the backend's "Already linked" guard.
+
+    Args:
+        client: Authenticated TetraClient
+        cohort_goal_uid: Cohort goal UID
+
+    Returns:
+        The viewer's standing in the joined cohort.
+    """
+    return await client.post(
+        f"{_BASE}/groups/everyone/goals/{cohort_goal_uid}/join", json=None,
+    )
+
+
+@operation(
+    cli="social my-tree-cohorts",
+    summary="List the cohorts the caller's personal skill tree participates in.",
+    covers=[("GET", "/api/v1/social/skill-trees/mine/{source_value_uid}/cohorts")],
+    params={"source_value_uid": arg(help="Root value UID of the caller's tree")},
+)
+async def my_tree_cohorts(
+    client: TetraClient, source_value_uid: str,
+) -> dict[str, Any]:
+    """List every cohort the caller's personal tree participates in.
+
+    Walks the caller's own ValueLinks from ``source_value_uid`` and reports
+    their standing (rank, size, percentile, tier, is_god) in each linked
+    cohort. Account-scoped to the caller.
+
+    Args:
+        client: Authenticated TetraClient
+        source_value_uid: Root value UID of the caller's skill tree
+
+    Returns:
+        Dict with a ``cohorts`` list.
+    """
+    return await client.get(
+        f"{_BASE}/skill-trees/mine/{source_value_uid}/cohorts",
+    )
+
+
+# =============================================================================
+# ARENA — GROUP-SCOPED COHORTS
+# =============================================================================
+
+@operation(
+    cli="social group-tree-standings",
+    summary="Leaderboard + viewer standing for a skill-tree cohort in a group.",
+    covers=[(
+        "GET",
+        "/api/v1/social/groups/{group_uid}/arena/skill-trees/{cohort_value_uid}/standings",
+    )],
+    params={
+        "group_uid": arg(help="Group UID"),
+        "cohort_value_uid": arg(help="Cohort value (skill tree) UID"),
+    },
+)
+async def group_tree_standings(
+    client: TetraClient, group_uid: str, cohort_value_uid: str,
+) -> dict[str, Any]:
+    """Top-50 leaderboard plus the viewer's standing for one skill tree in a group.
+
+    Requires the viewer to be a member of the group.
+
+    Args:
+        client: Authenticated TetraClient
+        group_uid: Group UID
+        cohort_value_uid: Cohort value (skill tree) UID
+
+    Returns:
+        Standings dict (leaderboard + viewer).
+    """
+    return await client.get(
+        f"{_BASE}/groups/{group_uid}/arena/skill-trees/{cohort_value_uid}/standings",
+    )
+
+
+@operation(
+    cli="social group-goal-standings",
+    summary="Leaderboard + viewer standing for a goal cohort in a group.",
+    covers=[(
+        "GET",
+        "/api/v1/social/groups/{group_uid}/arena/goals/{cohort_goal_uid}/standings",
+    )],
+    params={
+        "group_uid": arg(help="Group UID"),
+        "cohort_goal_uid": arg(help="Cohort goal UID"),
+    },
+)
+async def group_goal_standings(
+    client: TetraClient, group_uid: str, cohort_goal_uid: str,
+) -> dict[str, Any]:
+    """Top-50 leaderboard plus the viewer's standing for one goal cohort in a group.
+
+    Requires the viewer to be a member of the group.
+
+    Args:
+        client: Authenticated TetraClient
+        group_uid: Group UID
+        cohort_goal_uid: Cohort goal UID
+
+    Returns:
+        Standings dict (leaderboard + viewer).
+    """
+    return await client.get(
+        f"{_BASE}/groups/{group_uid}/arena/goals/{cohort_goal_uid}/standings",
+    )