tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/conversations_2.py

@@ -0,0 +1,262 @@
+"""Annotated operations for conversation messaging, reactions, and nudges.
+
+This module covers the second slice of the conversations API surface: posting
+reactions, marking conversations read, sending nudges (DM + group), and the
+atomic create-and-send endpoints for DM and group chats, plus entity-conversation
+lookup. The plain (undecorated) agent-polling helpers (``agent/unseen`` and
+``agent/read``) live in ``operations/conversations.py`` and are intentionally
+not duplicated here.
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+
+@operation(
+    cli="conversations react",
+    summary="Add or change a reaction emoji on a message.",
+    covers=[("POST", "/api/v1/conversations/{conversation_uid}/reactions")],
+    params={
+        "conversation_uid": arg(help="Conversation UID"),
+        "message_uid": arg(help="Interaction (message) UID to react to"),
+        "emoji": arg(help="Reaction emoji (1-20 chars)"),
+    },
+)
+async def add_reaction(
+    client: TetraClient,
+    conversation_uid: str,
+    *,
+    message_uid: str,
+    emoji: str,
+) -> dict[str, Any]:
+    """Add or change a reaction on a message.
+
+    A second reaction by the same account replaces the first — there is at
+    most one reaction per account per message.
+
+    Args:
+        client: Authenticated TetraClient
+        conversation_uid: Conversation the message belongs to
+        message_uid: Interaction UID to react to
+        emoji: The reaction emoji
+
+    Returns:
+        The created reaction interaction dict.
+    """
+    body: dict[str, Any] = {"message_uid": message_uid, "emoji": emoji}
+    return await client.post(
+        f"/api/v1/conversations/{conversation_uid}/reactions", json=body
+    )
+
+
+@operation(
+    cli="conversations unreact",
+    summary="Remove a reaction from a message.",
+    covers=[
+        ("DELETE", "/api/v1/conversations/{conversation_uid}/reactions/{reaction_uid}")
+    ],
+    params={
+        "conversation_uid": arg(help="Conversation UID"),
+        "reaction_uid": arg(help="Reaction interaction UID to remove"),
+    },
+)
+async def remove_reaction(
+    client: TetraClient,
+    conversation_uid: str,
+    reaction_uid: str,
+) -> dict[str, Any]:
+    """Remove a reaction from a message.
+
+    Args:
+        client: Authenticated TetraClient
+        conversation_uid: Conversation the reaction belongs to
+        reaction_uid: The reaction interaction UID
+
+    Returns:
+        Removal confirmation dict.
+    """
+    return await client.delete(
+        f"/api/v1/conversations/{conversation_uid}/reactions/{reaction_uid}"
+    )
+
+
+@operation(
+    cli="conversations read",
+    summary="Mark a conversation as read for the current user.",
+    covers=[("POST", "/api/v1/conversations/{conversation_uid}/read")],
+    params={"conversation_uid": arg(help="Conversation UID")},
+)
+async def mark_read(
+    client: TetraClient, conversation_uid: str
+) -> dict[str, Any]:
+    """Mark a conversation as read (advances the user's read cursor).
+
+    Args:
+        client: Authenticated TetraClient
+        conversation_uid: Conversation UID
+
+    Returns:
+        Status confirmation dict.
+    """
+    return await client.post(
+        f"/api/v1/conversations/{conversation_uid}/read"
+    )
+
+
+@operation(
+    cli="conversations nudge",
+    summary="Send a nudge in a group conversation by conversation UID.",
+    covers=[("POST", "/api/v1/conversations/{conversation_uid}/nudge")],
+    params={"conversation_uid": arg(help="Group conversation UID")},
+)
+async def send_group_nudge(
+    client: TetraClient, conversation_uid: str
+) -> dict[str, Any]:
+    """Send a nudge in a group conversation.
+
+    Args:
+        client: Authenticated TetraClient
+        conversation_uid: The group conversation UID
+
+    Returns:
+        Dict with nudge_streak, max_nudge_streak, interaction_uid.
+    """
+    return await client.post(
+        f"/api/v1/conversations/{conversation_uid}/nudge"
+    )
+
+
+@operation(
+    cli="conversations dm-nudge",
+    summary="Send a nudge in a DM, addressed by the other account's UID.",
+    covers=[("POST", "/api/v1/conversations/dm/{account_uid}/nudge")],
+    params={"account_uid": arg(help="The other participant's account UID")},
+)
+async def send_dm_nudge(
+    client: TetraClient, account_uid: str
+) -> dict[str, Any]:
+    """Send a nudge in a DM conversation.
+
+    Args:
+        client: Authenticated TetraClient
+        account_uid: The other participant's account UID
+
+    Returns:
+        Dict with nudge_streak, max_nudge_streak, interaction_uid.
+    """
+    return await client.post(
+        f"/api/v1/conversations/dm/{account_uid}/nudge"
+    )
+
+
+@operation(
+    cli="conversations dm-send",
+    summary="Create the DM if needed and send the first message atomically.",
+    covers=[("POST", "/api/v1/conversations/dm/{account_uid}/messages")],
+    params={
+        "account_uid": arg(help="The other participant's account UID"),
+        "content": arg(help="Message text"),
+    },
+)
+async def send_dm_message(
+    client: TetraClient,
+    account_uid: str,
+    *,
+    content: str,
+    parent_uid: str | None = None,
+) -> dict[str, Any]:
+    """Create-and-send a DM in one round trip.
+
+    Materializes an ephemeral DM (no DB row exists until first send) and
+    delivers the first message. The handler only reads ``content`` and
+    ``parent_uid`` from the body.
+
+    Args:
+        client: Authenticated TetraClient
+        account_uid: The other participant's account UID
+        content: Message text
+        parent_uid: Optional parent interaction UID (reserved)
+
+    Returns:
+        Dict with ``conversation`` and ``interaction`` sub-objects.
+    """
+    body: dict[str, Any] = {"content": content}
+    if parent_uid is not None:
+        body["parent_uid"] = parent_uid
+    return await client.post(
+        f"/api/v1/conversations/dm/{account_uid}/messages", json=body
+    )
+
+
+@operation(
+    cli="conversations group-send",
+    summary="Create the group chat if needed and send the first message atomically.",
+    covers=[("POST", "/api/v1/conversations/group/{group_uid}/messages")],
+    params={
+        "group_uid": arg(help="Group UID"),
+        "content": arg(help="Message text"),
+    },
+)
+async def send_group_message(
+    client: TetraClient,
+    group_uid: str,
+    *,
+    content: str,
+    parent_uid: str | None = None,
+) -> dict[str, Any]:
+    """Create-and-send a group message in one round trip.
+
+    Materializes an ephemeral group conversation (no DB row until first
+    send) and delivers the first message. The handler only reads
+    ``content`` and ``parent_uid`` from the body.
+
+    Args:
+        client: Authenticated TetraClient
+        group_uid: The group UID
+        content: Message text
+        parent_uid: Optional parent interaction UID (reserved)
+
+    Returns:
+        Dict with ``conversation`` and ``interaction`` sub-objects.
+    """
+    body: dict[str, Any] = {"content": content}
+    if parent_uid is not None:
+        body["parent_uid"] = parent_uid
+    return await client.post(
+        f"/api/v1/conversations/group/{group_uid}/messages", json=body
+    )
+
+
+@operation(
+    cli="conversations entity",
+    summary="Find or create the conversation for a goal, value, or event.",
+    covers=[("GET", "/api/v1/conversations/entity/{entity_type}/{entity_uid}")],
+    params={
+        "entity_type": arg(help="Entity type: goal | value | event"),
+        "entity_uid": arg(help="Entity UID"),
+        "group_uid": opt("--group-uid", help="Owning group UID (required)"),
+    },
+)
+async def find_or_create_entity_conversation(
+    client: TetraClient,
+    entity_type: str,
+    entity_uid: str,
+    *,
+    group_uid: str,
+) -> dict[str, Any]:
+    """Find or create a conversation anchored to a goal, value, or event.
+
+    Args:
+        client: Authenticated TetraClient
+        entity_type: One of ``goal``, ``value``, ``event``
+        entity_uid: The entity UID
+        group_uid: Owning group UID (required query parameter)
+
+    Returns:
+        ConversationResponse dict including the anchor interaction UID.
+    """
+    return await client.get(
+        f"/api/v1/conversations/entity/{entity_type}/{entity_uid}",
+        params={"group_uid": group_uid},
+    )

tetra_cli/api_client/operations/cosmetics.py

@@ -0,0 +1,148 @@
+"""Pure async operations for the cosmetics API.
+
+Cosmetics are credit-purchasable Items (game characters, profile-photo unlock,
+etc.) that an account can own and equip into named slots. 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="cosmetics catalog",
+    summary="List active cosmetic Items in a category with ownership flags.",
+    covers=[("GET", "/api/v1/cosmetics/catalog")],
+    params={"category": arg(help="Item category to list (e.g. game_character).")},
+)
+async def get_cosmetics_catalog(
+    client: TetraClient, category: str,
+) -> dict[str, Any]:
+    """List all active Items in a category, each flagged with ownership.
+
+    Args:
+        client: Authenticated TetraClient
+        category: Item category to filter by (e.g. ``game_character``).
+
+    Returns:
+        A list of catalog item dicts, each with ``id``, ``name``,
+        ``description``, ``credit_cost``, and ``owned``.
+    """
+    return await client.get(
+        "/api/v1/cosmetics/catalog", params={"category": category}
+    )
+
+
+@operation(
+    cli="cosmetics equipped",
+    summary="Show the caller's currently equipped cosmetic slots.",
+    covers=[("GET", "/api/v1/cosmetics/equipped")],
+)
+async def get_cosmetics_equipped(client: TetraClient) -> dict[str, Any]:
+    """Return all currently equipped cosmetic slots for the caller.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with a ``slots`` map of slot name to ``{item_id, value,
+        equipped_at}``.
+    """
+    return await client.get("/api/v1/cosmetics/equipped")
+
+
+@operation(
+    cli="cosmetics equip",
+    summary="Equip an owned cosmetic Item into a named slot.",
+    covers=[("POST", "/api/v1/cosmetics/equip")],
+    params={
+        "slot": arg(help="Named slot to equip into."),
+        "item_id": arg(help="ID of the owned Item to equip."),
+    },
+)
+async def equip_cosmetic(
+    client: TetraClient, slot: str, item_id: str,
+) -> dict[str, Any]:
+    """Equip an owned Item into a named slot (upsert).
+
+    Args:
+        client: Authenticated TetraClient
+        slot: Named slot to equip into.
+        item_id: ID of the owned Item to equip.
+
+    Returns:
+        The equipped-slot dict.
+
+    Raises:
+        TetraClientError: 400 ``not_owned`` if the item is not owned.
+    """
+    body = {"slot": slot, "item_id": item_id}
+    return await client.post("/api/v1/cosmetics/equip", json=body)
+
+
+@operation(
+    cli="cosmetics unequip",
+    summary="Clear the cosmetic Item from a named slot (no-op if empty).",
+    covers=[("POST", "/api/v1/cosmetics/unequip")],
+    params={"slot": arg(help="Named slot to clear.")},
+)
+async def unequip_cosmetic(client: TetraClient, slot: str) -> dict[str, Any]:
+    """Remove the equipped item from a named slot.
+
+    Args:
+        client: Authenticated TetraClient
+        slot: Named slot to clear.
+
+    Returns:
+        ``{"ok": True}``.
+    """
+    return await client.post("/api/v1/cosmetics/unequip", json={"slot": slot})
+
+
+@operation(
+    cli="cosmetics unlock-profile-photo",
+    summary="Purchase the level-gated profile-photo feature unlock.",
+    covers=[("POST", "/api/v1/cosmetics/profile-photo/unlock")],
+)
+async def unlock_profile_photo(client: TetraClient) -> dict[str, Any]:
+    """Purchase the profile-photo feature unlock (level-gated, costs credits).
+
+    The endpoint takes no body — eligibility and cost are derived server-side.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        ``{"unlocked": True}`` on success.
+
+    Raises:
+        TetraClientError: 400 ``level_too_low``, item already owned, or
+            insufficient credits.
+    """
+    return await client.post("/api/v1/cosmetics/profile-photo/unlock")
+
+
+@operation(
+    cli="cosmetics set-avatar",
+    summary="Set a custom avatar URL (requires the profile-photo unlock).",
+    covers=[("PUT", "/api/v1/cosmetics/avatar")],
+    params={"url": arg(help="Custom avatar http/https URL (max 2048 chars).")},
+)
+async def set_avatar(client: TetraClient, url: str) -> dict[str, Any]:
+    """Set a custom avatar URL for the account.
+
+    Requires the profile-photo feature unlock; the URL must be http/https.
+
+    Args:
+        client: Authenticated TetraClient
+        url: Custom avatar URL.
+
+    Returns:
+        The updated avatar-slot dict.
+
+    Raises:
+        TetraClientError: 400 ``photo_locked`` if the unlock is not purchased.
+    """
+    return await client.put("/api/v1/cosmetics/avatar", json={"url": url})

tetra_cli/api_client/operations/dashboard.py

@@ -0,0 +1,282 @@
+"""Pure async operations for the dashboard API."""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import operation, opt
+
+
+@operation(
+    cli="dashboard week-snapshot",
+    summary="Get a week-at-a-glance overview of time allocations vs budget.",
+    covers=[("GET", "/api/v1/dashboard/week-snapshot")],
+    params={
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped view"),
+        "target_account_uid": opt(
+            "--target-account-uid",
+            help="View a specific member's data within a group",
+        ),
+    },
+)
+async def get_week_snapshot(
+    client: TetraClient,
+    *,
+    week_start: str | None = None,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get a week-at-a-glance overview showing time allocations vs budget.
+
+    Args:
+        client: Authenticated TetraClient
+        week_start: Reference date in YYYY-MM-DD format (defaults to current week)
+        group_uid: Group UID for a group-scoped snapshot (omit for personal)
+        target_account_uid: View a specific member's data within a group
+
+    Returns:
+        Dict with value_summaries, totals, and event_count
+    """
+    params: dict[str, Any] = {}
+    if week_start:
+        # Backend query param is `date` (not week_start); FastAPI silently
+        # ignores unknown params, so the name must match exactly.
+        params["date"] = week_start
+    if group_uid:
+        params["group_uid"] = group_uid
+    if target_account_uid:
+        params["target_account_uid"] = target_account_uid
+    return await client.get("/api/v1/dashboard/week-snapshot", params=params)
+
+
+@operation(
+    cli="dashboard feels-by-day",
+    summary="Get average feels (mood) by day over a date range.",
+    covers=[("GET", "/api/v1/dashboard/feels-by-day")],
+    params={
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped feels"),
+        "target_account_uid": opt(
+            "--target-account-uid",
+            help="View a specific member's feels within a group",
+        ),
+    },
+)
+async def get_feels_by_day(
+    client: TetraClient,
+    *,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get mood/feels trends over a date range.
+
+    Args:
+        client: Authenticated TetraClient
+        start_date: Start date in YYYY-MM-DD format (defaults to 27 days ago)
+        end_date: End date in YYYY-MM-DD format (defaults to today)
+        group_uid: Group UID for group-scoped feels (omit for personal)
+        target_account_uid: View a specific member's feels within a group
+
+    Returns:
+        Dict with 'days' list, each containing date, average feels, and count
+    """
+    params: dict[str, Any] = {}
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    if group_uid:
+        params["group_uid"] = group_uid
+    if target_account_uid:
+        params["target_account_uid"] = target_account_uid
+    return await client.get("/api/v1/dashboard/feels-by-day", params=params)
+
+
+@operation(
+    cli="dashboard day-progress",
+    summary="Get today's progress: recorded vs scheduled time.",
+    covers=[("GET", "/api/v1/dashboard/day-progress")],
+    params={
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped progress"),
+        "target_account_uid": opt(
+            "--target-account-uid",
+            help="View a specific member's day progress within a group",
+        ),
+    },
+)
+async def get_day_progress(
+    client: TetraClient,
+    *,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get today's progress showing how much scheduled time has been recorded.
+
+    Args:
+        client: Authenticated TetraClient
+        group_uid: Group UID for group-scoped progress (omit for personal)
+        target_account_uid: View a specific member's day progress within a group
+
+    Returns:
+        Dict with total_scheduled, total_recorded, and per-value breakdown
+    """
+    params: dict[str, Any] = {}
+    if group_uid:
+        params["group_uid"] = group_uid
+    if target_account_uid:
+        params["target_account_uid"] = target_account_uid
+    return await client.get("/api/v1/dashboard/day-progress", params=params)
+
+
+@operation(
+    cli="dashboard week-clock",
+    summary="Get the concentric-arc week clock (recorded/scheduled/free hours).",
+    covers=[("GET", "/api/v1/dashboard/week-clock")],
+    params={
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped week clock"),
+        "target_account_uid": opt(
+            "--target-account-uid",
+            help="View a specific member's week clock within a group",
+        ),
+    },
+)
+async def get_week_clock(
+    client: TetraClient,
+    *,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get the compact week-clock ring data for the dashboard.
+
+    Args:
+        client: Authenticated TetraClient
+        group_uid: Group UID for group-scoped week clock (omit for personal)
+        target_account_uid: View a specific member's week clock within a group
+
+    Returns:
+        Dict with recorded/scheduled-remaining/free hours and elapsed percentages
+    """
+    params: dict[str, Any] = {}
+    if group_uid:
+        params["group_uid"] = group_uid
+    if target_account_uid:
+        params["target_account_uid"] = target_account_uid
+    return await client.get("/api/v1/dashboard/week-clock", params=params)
+
+
+@operation(
+    cli="dashboard week-detail",
+    summary="Get the composite Week Detail payload (clock, snapshot, comparison).",
+    covers=[("GET", "/api/v1/dashboard/week-detail")],
+    params={
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped detail"),
+        "target_account_uid": opt(
+            "--target-account-uid",
+            help="View a specific member's data within a group",
+        ),
+    },
+)
+async def get_week_detail(
+    client: TetraClient,
+    *,
+    date: str | None = None,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get the composite Week Detail payload in one round-trip.
+
+    Args:
+        client: Authenticated TetraClient
+        date: Reference date in YYYY-MM-DD format (defaults to current week)
+        group_uid: Group UID for group-scoped detail (omit for personal)
+        target_account_uid: View a specific member's data within a group
+
+    Returns:
+        Dict with week_clock, week_snapshot, comparison, summary, and event lists
+    """
+    params: dict[str, Any] = {}
+    if date:
+        params["date"] = date
+    if group_uid:
+        params["group_uid"] = group_uid
+    if target_account_uid:
+        params["target_account_uid"] = target_account_uid
+    return await client.get("/api/v1/dashboard/week-detail", params=params)
+
+
+@operation(
+    cli="dashboard active-patterns",
+    summary="Get engagement-curated dashboard sections (streaks, on-pace, etc.).",
+    covers=[("GET", "/api/v1/dashboard/active-patterns")],
+    params={
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped patterns"),
+        "target_account_uid": opt(
+            "--target-account-uid",
+            help="View a specific member's patterns within a group",
+        ),
+    },
+)
+async def get_active_patterns(
+    client: TetraClient,
+    *,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get the curated active-patterns sections for the dashboard.
+
+    Args:
+        client: Authenticated TetraClient
+        group_uid: Group UID for group-scoped patterns (omit for personal)
+        target_account_uid: View a specific member's patterns within a group
+
+    Returns:
+        Dict with streaks, on_pace, recoverable, rhythm_due, recently_active,
+        and neglected lists
+    """
+    params: dict[str, Any] = {}
+    if group_uid:
+        params["group_uid"] = group_uid
+    if target_account_uid:
+        params["target_account_uid"] = target_account_uid
+    return await client.get("/api/v1/dashboard/active-patterns", params=params)
+
+
+@operation(
+    cli="dashboard values-week-breakdown",
+    summary="Get the per-top-level-value breakdown of the week's events and goals.",
+    covers=[("GET", "/api/v1/dashboard/values-week-breakdown")],
+    params={
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped breakdown"),
+        "target_account_uid": opt(
+            "--target-account-uid",
+            help="View a specific member's data within a group",
+        ),
+    },
+)
+async def get_values_week_breakdown(
+    client: TetraClient,
+    *,
+    date: str | None = None,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get the per-top-level-value breakdown for the week.
+
+    Args:
+        client: Authenticated TetraClient
+        date: Reference date in YYYY-MM-DD format (defaults to current week)
+        group_uid: Group UID for group-scoped breakdown (omit for personal)
+        target_account_uid: View a specific member's data within a group
+
+    Returns:
+        Dict mapping each top-level value to its week's goals and events
+    """
+    params: dict[str, Any] = {}
+    if date:
+        params["date"] = date
+    if group_uid:
+        params["group_uid"] = group_uid
+    if target_account_uid:
+        params["target_account_uid"] = target_account_uid
+    return await client.get(
+        "/api/v1/dashboard/values-week-breakdown", params=params
+    )