tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/archive.py

@@ -0,0 +1,114 @@
+"""Pure async operations for the archive API.
+
+The archive surface lets an agent inspect and recover entities (values,
+goals, events) that were soft-deleted. Listing and inspecting are reads;
+restore recreates the entity from its archived snapshot, while permanent
+delete removes the archived row for good (irreversible).
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+
+@operation(
+    cli="archive list",
+    summary="List archived (soft-deleted) entities, newest first.",
+    covers=[("GET", "/api/v1/archive/")],
+    params={
+        "entity_type": opt(
+            "--entity-type",
+            choices=["value", "goal", "event"],
+            help="Filter by entity type (value | goal | event).",
+        ),
+    },
+)
+async def list_archived(
+    client: TetraClient,
+    *,
+    entity_type: str | None = None,
+) -> list[dict[str, Any]]:
+    """List all archived entities for the current user.
+
+    Optionally filter by entity type. Results come back sorted by deletion
+    date, most recent first.
+
+    Args:
+        client: Authenticated TetraClient
+        entity_type: Optional filter — one of 'value', 'goal', or 'event'.
+            When None, all archived entities are returned.
+
+    Returns:
+        List of archived-entity dicts (uid, original_uid, entity_type,
+        entity_name, deleted_at, deleted_reason, cascade_from_uid).
+    """
+    params: dict[str, Any] = {}
+    if entity_type is not None:
+        params["entity_type"] = entity_type
+    return await client.get("/api/v1/archive/", params=params or None)
+
+
+@operation(
+    cli="archive get",
+    summary="Get a single archived entity by its archive UID.",
+    covers=[("GET", "/api/v1/archive/{uid}")],
+    params={"uid": arg(help="Archive entry UID")},
+)
+async def get_archived(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Get a single archived entity by UID.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: The archive entry's UID (not the original entity UID).
+
+    Returns:
+        Archived-entity dict.
+    """
+    return await client.get(f"/api/v1/archive/{uid}")
+
+
+@operation(
+    cli="archive restore",
+    summary="Restore an archived entity, recreating it with its original data.",
+    covers=[("POST", "/api/v1/archive/{uid}/restore")],
+    params={"uid": arg(help="Archive entry UID to restore")},
+)
+async def restore_archived(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Restore an archived entity.
+
+    The entity is recreated from its archived snapshot. Restoration fails
+    (the API returns an error) if an active entity with the same name
+    already exists, or if restoring a goal/value would exceed the account's
+    active-entity capacity.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: The archive entry's UID to restore.
+
+    Returns:
+        Restore result dict with 'restored' (bool) and the recreated
+        entity 'uid' on success.
+    """
+    return await client.post(f"/api/v1/archive/{uid}/restore")
+
+
+@operation(
+    cli="archive delete",
+    summary="Permanently delete an archived entity (irreversible).",
+    covers=[("DELETE", "/api/v1/archive/{uid}")],
+    params={"uid": arg(help="Archive entry UID to permanently delete")},
+)
+async def delete_archived(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Permanently delete an archived entity.
+
+    This action cannot be undone — the archived row is removed entirely and
+    the entity can no longer be restored.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: The archive entry's UID to permanently delete.
+
+    Returns:
+        Deletion confirmation dict ({'deleted': True} on 204).
+    """
+    return await client.delete(f"/api/v1/archive/{uid}")

tetra_cli/api_client/operations/awards.py

@@ -0,0 +1,123 @@
+"""Pure async operations for the awards API.
+
+Awards are the gamification catalog: definitions describe possible
+achievements, progress tracks a user toward each one, evaluation scans data to
+grant missing awards, and seeding installs the predefined definitions. These
+ops mirror the backend ``/api/v1/awards`` routes one-to-one.
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+
+@operation(
+    cli="awards definitions",
+    summary="List all award definitions in the catalog.",
+    covers=[("GET", "/api/v1/awards/definitions")],
+)
+async def list_award_definitions(client: TetraClient) -> dict[str, Any]:
+    """List the catalog of all possible awards with criteria and rewards.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with a 'definitions' list.
+    """
+    return await client.get("/api/v1/awards/definitions")
+
+
+@operation(
+    cli="awards progress",
+    summary="Show progress toward all awards.",
+    covers=[("GET", "/api/v1/awards/progress")],
+)
+async def get_award_progress(client: TetraClient) -> dict[str, Any]:
+    """Get progress (level, triggers, credits) toward every award.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with an 'awards' list and a 'summary'.
+    """
+    return await client.get("/api/v1/awards/progress")
+
+
+@operation(
+    cli="awards progress-for",
+    summary="Show progress toward a single award.",
+    covers=[("GET", "/api/v1/awards/progress/{award_id}")],
+    params={"award_id": arg(help="Award definition id")},
+)
+async def get_award_progress_for(
+    client: TetraClient, award_id: str
+) -> dict[str, Any]:
+    """Get progress toward one specific award.
+
+    Args:
+        client: Authenticated TetraClient
+        award_id: The award definition id to look up.
+
+    Returns:
+        Award progress dict for the given award.
+    """
+    return await client.get(f"/api/v1/awards/progress/{award_id}")
+
+
+@operation(
+    cli="awards evaluate",
+    summary="Scan data and grant any missing awards.",
+    covers=[("POST", "/api/v1/awards/evaluate")],
+    params={
+        "start_date": opt("--start-date", help="Only consider data from this date (YYYY-MM-DD)"),
+        "end_date": opt("--end-date", help="Only consider data until this date (YYYY-MM-DD)"),
+    },
+)
+async def evaluate_awards(
+    client: TetraClient,
+    *,
+    dry_run: bool = False,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    as_regular: bool = False,
+) -> dict[str, Any]:
+    """Evaluate all data and grant awards that should have been earned.
+
+    Useful after a data import. ``dry_run`` calculates without granting.
+    ``as_regular`` is superuser-only and grants full (non-retroactive) credits.
+
+    Args:
+        client: Authenticated TetraClient
+        dry_run: If True, calculate but do not grant awards.
+        start_date: Optional lower bound date filter (YYYY-MM-DD).
+        end_date: Optional upper bound date filter (YYYY-MM-DD).
+        as_regular: Superuser only — grant as regular awards with full credits.
+
+    Returns:
+        Dict with 'results', 'total_credits', 'total_xp', and 'dry_run'.
+    """
+    body: dict[str, Any] = {"dry_run": dry_run, "as_regular": as_regular}
+    if start_date is not None:
+        body["start_date"] = start_date
+    if end_date is not None:
+        body["end_date"] = end_date
+    return await client.post("/api/v1/awards/evaluate", json=body)
+
+
+@operation(
+    cli="awards seed",
+    summary="Seed predefined award definitions into the database.",
+    covers=[("POST", "/api/v1/awards/seed")],
+)
+async def seed_award_definitions(client: TetraClient) -> dict[str, Any]:
+    """Create any predefined award definitions that don't already exist.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with 'created' count and a 'message'.
+    """
+    return await client.post("/api/v1/awards/seed")

tetra_cli/api_client/operations/capacity.py

@@ -0,0 +1,84 @@
+"""Pure async operations for the capacity API.
+
+Capacity tracks how many *active* entities the caller (or a group) may hold.
+Personal scope exposes the effective cap, current usage, credit-purchased
+slots, and the escalating cost of the next slot; group scope exposes the
+shared-pool cap. Slots are bought with credits via ``purchase-slot``.
+
+These ops are the single source of truth for both the CLI and MCP surfaces —
+each is a thin async wrapper over :class:`TetraClient`.
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation
+
+
+@operation(
+    cli="capacity status",
+    summary="Show the caller's active/archive capacity usage and next-slot cost.",
+    covers=[("GET", "/api/v1/capacity/")],
+)
+async def get_capacity(client: TetraClient) -> dict[str, Any]:
+    """Show active-entity capacity status for the caller's personal scope.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with ``effective_cap`` (null == unlimited for Pro),
+        ``active_count``, ``archive_cap``, ``archive_count``, ``is_pro``,
+        ``at_capacity``, ``purchased_slots`` (credit-bought cap slots), and
+        ``next_slot_cost`` (credit price of the next slot; null for Pro/comp).
+    """
+    return await client.get("/api/v1/capacity/")
+
+
+@operation(
+    cli="capacity group",
+    summary="Show shared-pool capacity for a group the caller can see.",
+    covers=[("GET", "/api/v1/capacity/group/{group_uid}")],
+    params={"group_uid": arg(help="Group UID")},
+)
+async def get_group_capacity(
+    client: TetraClient, group_uid: str,
+) -> dict[str, Any]:
+    """Show shared-pool capacity for a group the caller can see.
+
+    Non-members of a private group get a 404 (surfaced as a ``Not found``
+    error) so the endpoint never discloses the group's existence.
+
+    Args:
+        client: Authenticated TetraClient
+        group_uid: Group UID
+
+    Returns:
+        Dict with the group's ``effective_cap`` (null == unlimited),
+        ``active_count``, ``is_unlimited``, and ``at_capacity``.
+    """
+    return await client.get(f"/api/v1/capacity/group/{group_uid}")
+
+
+@operation(
+    cli="capacity purchase-slot",
+    summary="Buy the next credit-purchased active capacity slot.",
+    covers=[("POST", "/api/v1/capacity/purchase-slot")],
+)
+async def purchase_capacity_slot(client: TetraClient) -> dict[str, Any]:
+    """Buy the next credit-purchased active slot (escalating credit cost).
+
+    The endpoint takes no body — the next slot's cost and the caller's
+    eligibility are derived server-side from the account state.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Updated capacity dict reflecting the new ``purchased_slots`` and
+        ``next_slot_cost``.
+
+    Raises:
+        TetraClientError: 400 ``insufficient_credits`` if the balance is too
+            low; 400 ``unlimited_capacity`` for Pro/comped accounts.
+    """
+    return await client.post("/api/v1/capacity/purchase-slot")