tetra-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{tetra_cli-0.2.0 → tetra_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tetra-cli
-Version: 0.2.0
+Version: 0.4.0
 Summary: Standalone CLI/agent client for the Tetra API (no backend).
 Project-URL: Homepage, https://tetraoptum.com
 Requires-Python: >=3.11

{tetra_cli-0.2.0 → tetra_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tetra-cli"
-version = "0.2.0"
+version = "0.4.0"
 description = "Standalone CLI/agent client for the Tetra API (no backend)."
 readme = "README.md"
 requires-python = ">=3.11"

{tetra_cli-0.2.0 → tetra_cli-0.4.0}/tetra_cli/__init__.py

@@ -3,4 +3,4 @@
 Speaks only HTTP to a remote Tetra API with a bearer token. Contains NO
 backend server code (no models, routes, services, ORM). Safe to distribute.
 """
-__version__ = "0.1.0"
+__version__ = "0.4.0"

{tetra_cli-0.2.0 → tetra_cli-0.4.0}/tetra_cli/api_client/operations/capacity.py

@@ -61,24 +61,31 @@ async def get_group_capacity(
 
 @operation(
     cli="capacity purchase-slot",
-    summary="Buy the next credit-purchased active capacity slot.",
+    summary="Buy the next credit-purchased active capacity slots.",
     covers=[("POST", "/api/v1/capacity/purchase-slot")],
+    params={"quantity": arg(help="How many slots to buy (default 1)")},
 )
-async def purchase_capacity_slot(client: TetraClient) -> dict[str, Any]:
-    """Buy the next credit-purchased active slot (escalating credit cost).
+async def purchase_capacity_slot(
+    client: TetraClient, quantity: int = 1,
+) -> dict[str, Any]:
+    """Buy the next ``quantity`` credit-purchased active slots.
 
-    The endpoint takes no body — the next slot's cost and the caller's
-    eligibility are derived server-side from the account state.
+    Per-slot cost escalates and the purchase is all-or-nothing: the summed
+    cost is debited in one transaction or the call fails without buying any.
 
     Args:
         client: Authenticated TetraClient
+        quantity: How many slots to buy (default 1)
 
     Returns:
-        Updated capacity dict reflecting the new ``purchased_slots`` and
-        ``next_slot_cost``.
+        Updated capacity dict reflecting the new ``purchased_slots``,
+        ``next_slot_cost``, and ``slot_cost_paid`` (total credits debited).
 
     Raises:
-        TetraClientError: 400 ``insufficient_credits`` if the balance is too
-            low; 400 ``unlimited_capacity`` for Pro/comped accounts.
+        TetraClientError: 400 ``insufficient_credits`` if the balance can't
+            cover the summed cost; 400 ``free_cap_reached`` when a free
+            account would end past the slot hard cap.
     """
-    return await client.post("/api/v1/capacity/purchase-slot")
+    return await client.post(
+        "/api/v1/capacity/purchase-slot", json={"quantity": quantity}
+    )

{tetra_cli-0.2.0 → tetra_cli-0.4.0}/tetra_cli/api_client/operations/goals.py

@@ -188,6 +188,10 @@ async def create_goal(
             help=("Goal status as a label (created | in_progress | archived | "
                   "abandoned | completed) or its numeric form (1-5)."),
         ),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped update (e.g. editing a goal you "
+                 "created on a mentee's behalf). Omit for your personal scope."),
     },
 )
 async def update_goal(
@@ -206,6 +210,7 @@ async def update_goal(
     outcome_shape: str | None = None,
     outcome_names: list[str] | None = None,
     status: str | None = None,
+    group_uid: str | None = None,
 ) -> dict[str, Any]:
     """Update an existing goal. Only provided (non-None) fields are changed.
 
@@ -227,6 +232,9 @@ async def update_goal(
             2=IN_PROGRESS, 3=ARCHIVED, 4=ABANDONED, 5=COMPLETED) or a label
             string ("created" … "completed", case-insensitive). The op
             normalizes labels→int so the CLI/MCP surfaces share the behavior.
+        group_uid: Group UID for a group-scoped update. Required to edit a goal
+            that lives in a group (e.g. one created on a mentee's behalf);
+            omit for personal-scope goals.
 
     Returns:
         Updated goal dict
@@ -260,26 +268,43 @@ async def update_goal(
         body["outcome_names"] = outcome_names
     if status is not None:
         body["status"] = _normalize_status(status)
-    return await client.put(f"/api/v1/goals/{uid}", json=body)
+    path = f"/api/v1/goals/{uid}"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.put(path, json=body)
 
 
 @operation(
     cli="goals delete",
     summary="Delete a goal permanently.",
     covers=[("DELETE", "/api/v1/goals/{uid}")],
-    params={"uid": arg(help="Goal UID to delete")},
+    params={
+        "uid": arg(help="Goal UID to delete"),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped delete (e.g. a goal you created "
+                 "on a mentee's behalf). Omit for your personal scope."),
+    },
 )
-async def delete_goal(client: TetraClient, uid: str) -> dict[str, Any]:
+async def delete_goal(
+    client: TetraClient, uid: str, *, group_uid: str | None = None,
+) -> dict[str, Any]:
     """Delete a goal permanently.
 
     Args:
         client: Authenticated TetraClient
         uid: Goal UID to delete
+        group_uid: Group UID for a group-scoped delete. Required to delete a
+            goal that lives in a group (e.g. one created on a mentee's behalf);
+            omit for personal-scope goals.
 
     Returns:
         Deletion confirmation dict
     """
-    return await client.delete(f"/api/v1/goals/{uid}")
+    path = f"/api/v1/goals/{uid}"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.delete(path)
 
 
 @operation(
@@ -476,6 +501,10 @@ async def delete_goal_metric(
                           help="New parent goal name (omit to keep current)."),
         "new_priority": opt("--priority", min=1,
                             help="New priority among siblings (1 = top)."),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped move (e.g. a mentee's goal). "
+                 "Omit for your personal scope."),
     },
 )
 async def move_goal(
@@ -484,6 +513,7 @@ async def move_goal(
     uid: str,
     new_parent: str | None = None,
     new_priority: int | None = None,
+    group_uid: str | None = None,
 ) -> dict[str, Any]:
     """Move a goal to a new parent and/or position in the sibling order.
 
@@ -508,8 +538,12 @@ async def move_goal(
     body: dict[str, Any] = {"uid": uid}
     if new_parent is None:
         # Caller didn't specify — pre-fetch and use current parent so the
-        # API doesn't interpret missing as "move to root."
-        current = await client.get(f"/api/v1/goals/{uid}")
+        # API doesn't interpret missing as "move to root." Scope the read to
+        # the same group so a mentee's goal resolves.
+        read_path = f"/api/v1/goals/{uid}"
+        if group_uid is not None:
+            read_path += f"?group_uid={group_uid}"
+        current = await client.get(read_path)
         if current.get("parent"):
             body["new_parent"] = current["parent"]
         # else: goal is already a root, omit new_parent (API treats omitted
@@ -521,6 +555,8 @@ async def move_goal(
         body["new_parent"] = new_parent
     if new_priority is not None:
         body["new_priority"] = new_priority
+    if group_uid is not None:
+        body["group_uid"] = group_uid
     return await client.post("/api/v1/goals/move", json=body)
 
 
@@ -574,6 +610,10 @@ async def batch_delete_goals(
         "updates": opt("--updates", json=True,
                        help="JSON map of {goal_uid: new_priority} (1-based, sequential)."),
         "parent": opt("--parent", help="Parent goal name (omit for root siblings)."),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped reorder (e.g. a mentee's goals). "
+                 "Omit for your personal scope."),
     },
 )
 async def batch_update_goal_priorities(
@@ -581,6 +621,7 @@ async def batch_update_goal_priorities(
     *,
     updates: dict[str, int],
     parent: str | None = None,
+    group_uid: str | None = None,
 ) -> dict[str, Any]:
     """Batch-update priorities for goals within one sibling group.
 
@@ -591,6 +632,8 @@ async def batch_update_goal_priorities(
         client: Authenticated TetraClient
         updates: Map of ``{goal_uid: new_priority}`` (1 = top).
         parent: Parent goal name (null/omit for root-level siblings).
+        group_uid: Group UID for a group-scoped reorder (e.g. a mentee's
+            goals); omit for personal scope.
 
     Returns:
         Dict with ``updated`` count and the affected ``uids``.
@@ -598,7 +641,10 @@ async def batch_update_goal_priorities(
     body: dict[str, Any] = {"updates": updates}
     if parent is not None:
         body["parent"] = parent
-    return await client.post("/api/v1/goals/batch-update-priorities", json=body)
+    path = "/api/v1/goals/batch-update-priorities"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.post(path, json=body)
 
 
 @operation(
@@ -610,6 +656,14 @@ async def batch_update_goal_priorities(
                            help="Source goal UID to merge (repeatable; 2+ required)."),
         "new_goal": opt("--new-goal", json=True,
                         help="New goal data as a JSON dict (at least {\"name\": ...})."),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped merge (e.g. a mentee's goals). "
+                 "Omit for your personal scope."),
+        "for_account_uid": opt(
+            "--for-account-uid",
+            help="Merge on this member's behalf — the merged goal belongs to "
+                 "them (mentee account UID); requires --group-uid."),
     },
 )
 async def merge_goals(
@@ -617,6 +671,8 @@ async def merge_goals(
     *,
     source_uids: list[str],
     new_goal: dict[str, Any],
+    group_uid: str | None = None,
+    for_account_uid: str | None = None,
 ) -> dict[str, Any]:
     """Merge two or more goals into a new goal.
 
@@ -628,11 +684,19 @@ async def merge_goals(
         source_uids: UIDs of the goals to merge (at least 2).
         new_goal: New goal payload (must include ``name``; may include
             ``parent``, ``values``, etc.).
+        group_uid: Group UID for a group-scoped merge (e.g. a mentee's
+            goals); omit for personal scope.
+        for_account_uid: Merge on this member's behalf so the merged goal
+            belongs to them (mentee account UID); requires ``group_uid``.
 
     Returns:
         The created goal dict.
     """
     body: dict[str, Any] = {"source_uids": source_uids, "new_goal": new_goal}
+    if group_uid is not None:
+        body["group_uid"] = group_uid
+    if for_account_uid is not None:
+        body["for_account_uid"] = for_account_uid
     return await client.post("/api/v1/goals/merge", json=body)
 
 
@@ -1085,6 +1149,10 @@ async def get_goal_status_stages(
         "uid": arg(help="Goal UID"),
         "old_name": opt("--old-name", help="Current field name to rename."),
         "new_name": opt("--new-name", help="New field name."),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped rename (e.g. a mentee's goal). "
+                 "Omit for your personal scope."),
     },
 )
 async def rename_goal_field(
@@ -1093,6 +1161,7 @@ async def rename_goal_field(
     *,
     old_name: str,
     new_name: str,
+    group_uid: str | None = None,
 ) -> dict[str, Any]:
     """Rename a tuple/record field on a goal and across all its events.
 
@@ -1104,13 +1173,18 @@ async def rename_goal_field(
         uid: Goal UID.
         old_name: Existing field name.
         new_name: Replacement field name.
+        group_uid: Group UID for a group-scoped rename (e.g. a mentee's
+            goal); omit for personal scope.
 
     Returns:
         Dict with ``success``, ``events_updated``, and the new
         ``outcome_names``.
     """
     body: dict[str, Any] = {"old_name": old_name, "new_name": new_name}
-    return await client.post(f"/api/v1/goals/{uid}/rename-field", json=body)
+    path = f"/api/v1/goals/{uid}/rename-field"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.post(path, json=body)
 
 
 @operation(
@@ -1142,3 +1216,97 @@ async def reorder_all_goals(
     return await client.post(
         "/api/v1/goals/reorder-all", json={"order": order}
     )
+
+
+@operation(
+    cli="goals link-value",
+    summary="Mirror-link a goal to a value: renaming one renames the other.",
+    covers=[("POST", "/api/v1/goals/{uid}/link-value")],
+    params={
+        "uid": arg(help="Goal UID to link"),
+        "value_uid": arg(help="Value UID to link it to (same scope)"),
+        "name_source": opt(
+            "--name-source",
+            choices=["goal", "value"],
+            help="When the leaf names differ, which name wins — the loser "
+                 "is renamed to match (with descendant cascade). "
+                 "Default: goal.",
+        ),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped link (goal + value both in "
+                 "that group, e.g. a mentee's). Omit for your personal scope."),
+    },
+)
+async def link_goal_value(
+    client: TetraClient,
+    *,
+    uid: str,
+    value_uid: str,
+    name_source: str | None = None,
+    group_uid: str | None = None,
+) -> dict[str, Any]:
+    """Create the explicit 1:1 mirror link between a goal and a value.
+
+    Same scope required; a value can be the mirror of at most one goal
+    (409 when it is already linked elsewhere). While linked, leaf renames
+    propagate across the link in both directions. Independent of the
+    draws-from/adds-to assignment in the goal's ``values``.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        value_uid: Value UID in the same scope.
+        name_source: 'goal' or 'value' — which name wins when the leaves
+            differ (the loser is renamed with cascade). Defaults to 'goal'.
+        group_uid: Group UID for a group-scoped link (both goal and value
+            live in that group, e.g. a mentee's); omit for personal scope.
+
+    Returns:
+        The updated goal dict, including ``linked_value`` {uid, name}.
+    """
+    body: dict[str, Any] = {"value_uid": value_uid}
+    if name_source is not None:
+        body["name_source"] = name_source
+    path = f"/api/v1/goals/{uid}/link-value"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.post(path, json=body)
+
+
+@operation(
+    cli="goals unlink-value",
+    summary="Remove a goal's mirror link; both sides rename independently.",
+    covers=[("DELETE", "/api/v1/goals/{uid}/link-value")],
+    params={
+        "uid": arg(help="Goal UID to unlink"),
+        "group_uid": opt(
+            "--group-uid",
+            help="Group UID for a group-scoped unlink (e.g. a mentee's goal). "
+                 "Omit for your personal scope."),
+    },
+)
+async def unlink_goal_value(
+    client: TetraClient,
+    *,
+    uid: str,
+    group_uid: str | None = None,
+) -> dict[str, Any]:
+    """Remove the goal's explicit value link.
+
+    The draws-from/adds-to assignment in ``values`` is kept — unlinking
+    only stops rename mirroring.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: Goal UID.
+        group_uid: Group UID for a group-scoped unlink (e.g. a mentee's
+            goal); omit for personal scope.
+
+    Returns:
+        The updated goal dict with ``linked_value: null``.
+    """
+    path = f"/api/v1/goals/{uid}/link-value"
+    if group_uid is not None:
+        path += f"?group_uid={group_uid}"
+    return await client.delete(path)

{tetra_cli-0.2.0 → tetra_cli-0.4.0}/tetra_cli/api_client/operations/groups.py

@@ -484,6 +484,25 @@ async def mark_viewed(client: TetraClient) -> dict[str, Any]:
     return await client.post("/api/v1/social/mark-viewed")
 
 
+@operation(
+    cli="social notifications-mark-viewed",
+    summary="Mark all social notifications viewed (clears the nav badge).",
+    covers=[("POST", "/api/v1/social/notifications/mark-viewed")],
+)
+async def mark_notifications_viewed(client: TetraClient) -> dict[str, Any]:
+    """Mark every unviewed social notification as viewed.
+
+    Takes no body; keys off the authenticated caller.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with the count of notifications marked viewed.
+    """
+    return await client.post("/api/v1/social/notifications/mark-viewed")
+
+
 # =============================================================================
 # SEARCH / INVITE LINKS / SHARING
 # =============================================================================

tetra_cli-0.4.0/tetra_cli/api_client/operations/skill_tree_rankings.py

@@ -0,0 +1,152 @@
+"""Pure async operations for skill-tree rank measures.
+
+A rank measure controls how a published skill tree's cohort standings are
+scored, per goal type. Every MeasureSpec (the shape below) is a JSON object:
+
+    {
+        "form": "scalar" | "target_shaped",
+        "agg": "sum" | "max" | "count" | "total_duration" | null,
+        "column": str | null,
+        "equation": str | null,
+        "dimensions": [{"column": str, "direction": "asc" | "desc",
+                         "agg": "max" | "sum"}, ...],
+        "label": str | null
+    }
+
+``form="scalar"`` needs ``agg`` (plus ``column`` or ``equation`` for outcome
+types; ``total_duration``/``count`` need neither). ``form="target_shaped"``
+needs a non-empty ordered ``dimensions`` list — dimension 0 is the primary
+sort key, later entries break ties, each compared per its own ``direction``.
+
+There are two config layers, both keyed by ``type_key`` (a goal's outcome
+schema key):
+    - The tree's canonical ``measures`` — set only by the tree's author via
+      :func:`set_tree_rank_measures`; drives the persisted standings
+      (``SharedGoalRanking``) everyone sees.
+    - Each caller's own personal ``prefs`` — set via
+      :func:`set_tree_rank_measure_pref`; a client-side-only re-rank
+      preference that never touches the canonical measures or persisted
+      standings.
+
+:func:`get_tree_rank_measures` returns the canonical measures plus, for each
+goal type present in the tree, its ``outcome_columns`` — the valid values for
+a scalar spec's ``column`` or a dimension's ``column``.
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+_MEASURE_SPEC_SHAPE = (
+    "A MeasureSpec is a JSON object: {form: 'scalar'|'target_shaped', "
+    "agg: 'sum'|'max'|'count'|'total_duration'|null, column: str|null, "
+    "equation: str|null, dimensions: [{column, direction:'asc'|'desc', "
+    "agg:'max'|'sum'}, ...], label: str|null}. form='scalar' needs agg "
+    "(plus column or equation for outcome types; total_duration/count need "
+    "neither); form='target_shaped' needs a non-empty ordered dimensions "
+    "list (dimension 0 is primary, later entries break ties). column/"
+    "dimension columns must be one of the goal type's outcome_columns from "
+    "get_tree_rank_measures."
+)
+
+
+@operation(
+    cli="values tree rank-measures",
+    summary=(
+        "Get a published skill tree's configured rank measures plus its "
+        "available goal types. Returns {measures: {type_key: MeasureSpec}, "
+        "types: [{type_key, label, outcome_columns}]}. " + _MEASURE_SPEC_SHAPE
+    ),
+    covers=[("GET", "/api/v1/skill-trees/{tree_uid}/rank-measures")],
+    params={"tree_uid": arg(help="Root value UID of the published skill tree.")},
+)
+async def get_tree_rank_measures(client: TetraClient, tree_uid: str) -> dict[str, Any]:
+    """Get a skill tree's configured rank measures and available goal types.
+
+    Any caller who can view at least one of the tree's publish scopes may
+    call this — reuses the change-request view check, since rank-measure
+    config is standings metadata, not sensitive.
+
+    Args:
+        client: Authenticated TetraClient.
+        tree_uid: Root value UID of the published skill tree.
+
+    Returns:
+        Dict with ``measures`` (``type_key`` -> MeasureSpec dict) and
+        ``types`` (list of ``{type_key, label, outcome_columns}``).
+    """
+    return await client.get(f"/api/v1/skill-trees/{tree_uid}/rank-measures")
+
+
+@operation(
+    cli="values tree set-rank-measures",
+    summary=(
+        "Author-only: set a published skill tree's canonical rank measure "
+        "for one or more goal types, synchronously recomputing every "
+        "existing standings row for the tree's cohort goals. measures is a "
+        "JSON object mapping type_key -> MeasureSpec: {full replacement per "
+        "type_key given; types omitted from measures are left untouched}. "
+        + _MEASURE_SPEC_SHAPE + " Call get_tree_rank_measures first to see "
+        "each type's outcome_columns."
+    ),
+    covers=[("PUT", "/api/v1/skill-trees/{tree_uid}/rank-measures")],
+    params={
+        "tree_uid": arg(help="Root value UID of the published skill tree (author only)."),
+        "measures": opt(
+            "--measures", json=True,
+            help="JSON object: {type_key: MeasureSpec, ...}.",
+        ),
+    },
+)
+async def set_tree_rank_measures(
+    client: TetraClient, tree_uid: str, measures: dict[str, Any]
+) -> dict[str, Any]:
+    """Author-only: set a tree's canonical rank measure per goal type.
+
+    Args:
+        client: Authenticated TetraClient.
+        tree_uid: Root value UID of the published skill tree.
+        measures: Dict mapping ``type_key`` -> MeasureSpec dict.
+
+    Returns:
+        Dict with the saved ``measures`` map.
+    """
+    return await client.put(f"/api/v1/skill-trees/{tree_uid}/rank-measures", json=measures)
+
+
+@operation(
+    cli="values tree set-rank-measure-pref",
+    summary=(
+        "Set the caller's own personal rank-measure override for one goal "
+        "type on a published skill tree — a client-side re-rank preference "
+        "that never touches the tree's canonical measures or persisted "
+        "standings. spec is a single MeasureSpec JSON object (see below) "
+        "applied to type_key. " + _MEASURE_SPEC_SHAPE + " Returns the "
+        "caller's full updated prefs map {type_key: MeasureSpec}."
+    ),
+    covers=[("PUT", "/api/v1/skill-trees/{tree_uid}/rank-measures/prefs")],
+    params={
+        "tree_uid": arg(help="Root value UID of the published skill tree."),
+        "type_key": arg(help="Goal type key this preference applies to."),
+        "spec": opt("--spec", json=True, help="MeasureSpec as a JSON object."),
+    },
+)
+async def set_tree_rank_measure_pref(
+    client: TetraClient, tree_uid: str, type_key: str, spec: dict[str, Any]
+) -> dict[str, Any]:
+    """Upsert the caller's own rank-measure preference for one goal type.
+
+    Args:
+        client: Authenticated TetraClient.
+        tree_uid: Root value UID of the published skill tree.
+        type_key: Goal type key this preference applies to.
+        spec: MeasureSpec dict for this type.
+
+    Returns:
+        Dict with the caller's full updated prefs map (``type_key`` ->
+        MeasureSpec dict).
+    """
+    return await client.put(
+        f"/api/v1/skill-trees/{tree_uid}/rank-measures/prefs",
+        json={type_key: spec},
+    )