tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/gamification.py

@@ -0,0 +1,470 @@
+"""Pure async operations for the gamification API.
+
+Covers XP progress and history, credits (history + gifting), the item catalog
+and purchases, daily engagement, activities and feature discoveries, streak
+freezes, feature-access checks, contextual XP breakdowns, and the gem (XP-boost)
+catalog and purchases.
+
+Each op is a thin async wrapper over ``TetraClient`` that mirrors the backend
+route contract (path, method, params, body field names). Optional body/query
+fields that are ``None`` are omitted so the API applies its own defaults.
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+# =============================================================================
+# PROGRESS
+# =============================================================================
+
+@operation(
+    cli="gamification progress",
+    summary="Get current gamification progress (level, XP, credits, streak).",
+    covers=[("GET", "/api/v1/gamification/progress")],
+)
+async def get_progress(client: TetraClient) -> dict[str, Any]:
+    """Get current gamification progress.
+
+    Returns level, XP, credits, streak, multiplier, and unlocked features.
+    """
+    return await client.get("/api/v1/gamification/progress")
+
+
+# =============================================================================
+# XP HISTORY & BREAKDOWN
+# =============================================================================
+
+@operation(
+    cli="gamification xp-history",
+    summary="List recent XP ledger entries with their source.",
+    covers=[("GET", "/api/v1/gamification/xp/history")],
+    params={
+        "limit": opt("--limit", min=1, max=200, help="Max entries (1-200)."),
+        "offset": opt("--offset", min=0, help="Entries to skip."),
+    },
+)
+async def get_xp_history(
+    client: TetraClient,
+    *,
+    limit: int = 50,
+    offset: int = 0,
+) -> dict[str, Any]:
+    """List XP ledger history.
+
+    Args:
+        client: Authenticated TetraClient
+        limit: Maximum entries to return (1-200)
+        offset: Number of entries to skip (for paging)
+
+    Returns:
+        Dict with ``entries`` list and ``total`` count
+    """
+    return await client.get(
+        "/api/v1/gamification/xp/history",
+        params={"limit": limit, "offset": offset},
+    )
+
+
+@operation(
+    cli="gamification xp-breakdown",
+    summary="Get a contextual XP breakdown for a goal or a value.",
+    covers=[("GET", "/api/v1/gamification/xp/breakdown")],
+    params={
+        "goal_name": opt("--goal-name", help="Goal name to break down."),
+        "value_name": opt("--value-name", help="Value name to break down."),
+    },
+)
+async def get_xp_breakdown(
+    client: TetraClient,
+    *,
+    goal_name: str | None = None,
+    value_name: str | None = None,
+) -> dict[str, Any]:
+    """Get contextual XP breakdown for a goal or value.
+
+    Exactly one of ``goal_name`` / ``value_name`` should be provided; the
+    backend 400s if neither is given. Only the provided filter is sent.
+
+    Returns:
+        Dict with summary stats, source breakdown, weekly stacked data,
+        and individual XP entries with formula details.
+    """
+    params: dict[str, Any] = {}
+    if goal_name is not None:
+        params["goal_name"] = goal_name
+    if value_name is not None:
+        params["value_name"] = value_name
+    return await client.get(
+        "/api/v1/gamification/xp/breakdown", params=params,
+    )
+
+
+# =============================================================================
+# DAILY ENGAGEMENT
+# =============================================================================
+
+@operation(
+    cli="gamification engagement-today",
+    summary="Get today's engagement record (activities, streak, XP).",
+    covers=[("GET", "/api/v1/gamification/engagement/today")],
+)
+async def get_today_engagement(client: TetraClient) -> dict[str, Any]:
+    """Get today's engagement record.
+
+    Returns activities, streak, discoveries, and XP earned today.
+    """
+    return await client.get("/api/v1/gamification/engagement/today")
+
+
+# =============================================================================
+# CREDITS
+# =============================================================================
+
+@operation(
+    cli="gamification credit-history",
+    summary="List recent credit transactions (earnings and spending).",
+    covers=[("GET", "/api/v1/gamification/credits/history")],
+    params={
+        "limit": opt("--limit", min=1, max=200, help="Max transactions (1-200)."),
+        "offset": opt("--offset", min=0, help="Transactions to skip."),
+    },
+)
+async def get_credit_history(
+    client: TetraClient,
+    *,
+    limit: int = 50,
+    offset: int = 0,
+) -> dict[str, Any]:
+    """List credit transaction history.
+
+    Args:
+        client: Authenticated TetraClient
+        limit: Maximum transactions to return (1-200)
+        offset: Number of transactions to skip (for paging)
+
+    Returns:
+        Dict with ``transactions`` list and ``total`` count
+    """
+    return await client.get(
+        "/api/v1/gamification/credits/history",
+        params={"limit": limit, "offset": offset},
+    )
+
+
+@operation(
+    cli="gamification gift-credits",
+    summary="Gift credits to a connected user (daily-capped, user-only).",
+    covers=[("POST", "/api/v1/gamification/credits/gift")],
+    params={
+        "to_account_uid": arg(help="Recipient account UID."),
+        "amount": arg(help="Number of credits to gift (positive integer)."),
+    },
+)
+async def gift_credits(
+    client: TetraClient,
+    *,
+    to_account_uid: str,
+    amount: int,
+) -> dict[str, Any]:
+    """Gift credits to a connected user.
+
+    ``amount`` is a count of credits (not cents); it is passed through
+    unchanged. The backend enforces a positive amount, a connection check,
+    and a daily gifting cap.
+
+    Args:
+        client: Authenticated TetraClient
+        to_account_uid: Recipient account UID
+        amount: Number of credits to transfer
+    """
+    return await client.post(
+        "/api/v1/gamification/credits/gift",
+        json={"to_account_uid": to_account_uid, "amount": amount},
+    )
+
+
+# =============================================================================
+# ITEMS & OWNERSHIP
+# =============================================================================
+
+@operation(
+    cli="gamification items",
+    mcp_tool="list_gamification_items",
+    summary="List the item catalog with ownership and purchasable flags.",
+    covers=[("GET", "/api/v1/gamification/items")],
+    params={
+        "category": opt("--category", help="Filter items by category."),
+    },
+)
+async def list_items(
+    client: TetraClient,
+    *,
+    category: str | None = None,
+) -> dict[str, Any]:
+    """List all items with ownership status.
+
+    Args:
+        client: Authenticated TetraClient
+        category: Optional category filter
+
+    Returns:
+        Dict with ``items`` list (each with ``owned``/``purchasable``)
+    """
+    params: dict[str, Any] = {}
+    if category is not None:
+        params["category"] = category
+    return await client.get("/api/v1/gamification/items", params=params)
+
+
+@operation(
+    cli="gamification owned",
+    summary="List the IDs of items the caller owns.",
+    covers=[("GET", "/api/v1/gamification/owned")],
+)
+async def get_owned_items(client: TetraClient) -> dict[str, Any]:
+    """Get the list of owned item IDs.
+
+    Fast endpoint for checking ownership without full item details.
+
+    Returns:
+        Dict with ``item_ids`` list
+    """
+    return await client.get("/api/v1/gamification/owned")
+
+
+# =============================================================================
+# PURCHASES
+# =============================================================================
+
+@operation(
+    cli="gamification purchase",
+    summary="Purchase an item with credits.",
+    covers=[("POST", "/api/v1/gamification/purchase")],
+    params={
+        "item_id": arg(help="Item ID to purchase."),
+    },
+)
+async def purchase_item(
+    client: TetraClient,
+    *,
+    item_id: str,
+) -> dict[str, Any]:
+    """Purchase an item with credits.
+
+    Deducts credits and adds the item to owned items.
+
+    Args:
+        client: Authenticated TetraClient
+        item_id: Item ID to purchase
+
+    Returns:
+        Dict with ``success``, ``item_id``, ``credit_balance``, ``message``
+    """
+    return await client.post(
+        "/api/v1/gamification/purchase", json={"item_id": item_id},
+    )
+
+
+# =============================================================================
+# ACTIVITIES & DISCOVERIES
+# =============================================================================
+
+@operation(
+    cli="gamification record-activity",
+    summary="Record an activity (screen view, app open, etc.).",
+    covers=[("POST", "/api/v1/gamification/activity")],
+    params={
+        "type": arg(help="Activity type (e.g. 'screen_view')."),
+        "screen": opt("--screen", help="Screen name for screen_view activities."),
+    },
+)
+async def record_activity(
+    client: TetraClient,
+    *,
+    type: str,
+    screen: str | None = None,
+) -> dict[str, Any]:
+    """Record an activity.
+
+    Activities are deduplicated per day and capped at the daily XP limit.
+
+    Args:
+        client: Authenticated TetraClient
+        type: Activity type (e.g. 'screen_view', 'app_open')
+        screen: Optional screen name (for screen_view activities)
+
+    Returns:
+        Dict with ``xp_awarded`` and ``discoveries``
+    """
+    body: dict[str, Any] = {"type": type}
+    if screen is not None:
+        body["screen"] = screen
+    return await client.post("/api/v1/gamification/activity", json=body)
+
+
+@operation(
+    cli="gamification record-discovery",
+    summary="Record a first-time feature discovery (one-time XP).",
+    covers=[("POST", "/api/v1/gamification/discovery")],
+    params={
+        "feature": arg(help="Feature identifier that was discovered."),
+    },
+)
+async def record_discovery(
+    client: TetraClient,
+    *,
+    feature: str,
+) -> dict[str, Any]:
+    """Record a feature discovery.
+
+    First-time discoveries award one-time XP (not subject to the daily cap).
+
+    Args:
+        client: Authenticated TetraClient
+        feature: Feature identifier
+
+    Returns:
+        Dict with ``xp_awarded`` and ``already_discovered``
+    """
+    return await client.post(
+        "/api/v1/gamification/discovery", json={"feature": feature},
+    )
+
+
+# =============================================================================
+# STREAK FREEZE
+# =============================================================================
+
+@operation(
+    cli="gamification streak-freeze",
+    summary="Purchase a streak freeze for a missed day.",
+    covers=[("POST", "/api/v1/gamification/streak-freeze")],
+    params={
+        "for_date": arg(help="Date to freeze (YYYY-MM-DD, within grace period)."),
+        "freeze_type": opt(
+            "--freeze-type",
+            choices=["single", "weekend"],
+            help="'single' (25 credits) or 'weekend' (40 credits).",
+        ),
+    },
+)
+async def purchase_streak_freeze(
+    client: TetraClient,
+    *,
+    for_date: str,
+    freeze_type: str = "single",
+) -> dict[str, Any]:
+    """Purchase a streak freeze for a missed day.
+
+    Must be purchased within 24 hours of the missed day; limited to 3 freezes
+    per 30-day period.
+
+    Args:
+        client: Authenticated TetraClient
+        for_date: Date to freeze (ISO YYYY-MM-DD)
+        freeze_type: 'single' (25 credits) or 'weekend' (40 credits)
+
+    Returns:
+        Dict with ``success``, ``for_date``, ``cost``, ``credit_balance``
+    """
+    return await client.post(
+        "/api/v1/gamification/streak-freeze",
+        json={"for_date": for_date, "freeze_type": freeze_type},
+    )
+
+
+# =============================================================================
+# FEATURE ACCESS
+# =============================================================================
+
+@operation(
+    cli="gamification feature-access",
+    summary="Check whether the caller can access a gated feature.",
+    covers=[("GET", "/api/v1/gamification/features/{feature_id}/accessible")],
+    params={
+        "feature_id": arg(help="Feature identifier to check access for."),
+    },
+)
+async def check_feature_access(
+    client: TetraClient,
+    feature_id: str,
+) -> dict[str, Any]:
+    """Check if the caller can access a gated feature.
+
+    Args:
+        client: Authenticated TetraClient
+        feature_id: Feature identifier
+
+    Returns:
+        Dict with ``feature_id`` and ``accessible``
+    """
+    return await client.get(
+        f"/api/v1/gamification/features/{feature_id}/accessible",
+    )
+
+
+# =============================================================================
+# GEMS (XP BOOSTS)
+# =============================================================================
+
+@operation(
+    cli="gamification gems",
+    summary="List the gem catalog (credit-priced consumable XP boosts).",
+    covers=[("GET", "/api/v1/gamification/gems")],
+)
+async def list_gems(client: TetraClient) -> dict[str, Any]:
+    """List the gem catalog.
+
+    Returns:
+        Dict with a ``gems`` list of catalog entries
+    """
+    return await client.get("/api/v1/gamification/gems")
+
+
+@operation(
+    cli="gamification active-boosts",
+    summary="List the caller's currently-active gem XP boosts.",
+    covers=[("GET", "/api/v1/gamification/active-xp-boosts")],
+)
+async def get_active_xp_boosts(client: TetraClient) -> dict[str, Any]:
+    """List the caller's currently-active gem boosts.
+
+    Returns:
+        Dict with a ``boosts`` list (gem_type, goal_uid, multiplier, expiry)
+    """
+    return await client.get("/api/v1/gamification/active-xp-boosts")
+
+
+@operation(
+    cli="gamification purchase-gem",
+    summary="Buy a gem with credits (goal-scope gems require a goal UID).",
+    covers=[("POST", "/api/v1/gamification/gems/{gem_id}/purchase")],
+    params={
+        "gem_id": arg(help="Gem ID to purchase."),
+        "goal_uid": opt("--goal-uid", help="Target goal UID (goal-scope gems only)."),
+    },
+)
+async def purchase_gem(
+    client: TetraClient,
+    gem_id: str,
+    *,
+    goal_uid: str | None = None,
+) -> dict[str, Any]:
+    """Buy a gem with credits.
+
+    Goal-scope gems require ``goal_uid``; account-scope gems leave it null.
+    The backend supplies the caller's personal group scope automatically.
+
+    Args:
+        client: Authenticated TetraClient
+        gem_id: Gem ID to purchase
+        goal_uid: Target goal UID for goal-scope gems
+
+    Returns:
+        Purchase result dict
+    """
+    body: dict[str, Any] = {"goal_uid": goal_uid}
+    return await client.post(
+        f"/api/v1/gamification/gems/{gem_id}/purchase", json=body,
+    )