tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/conversations.py

@@ -0,0 +1,447 @@
+"""Pure async operations for the conversations / AI-thread messages API."""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+
+@operation(
+    cli="conversations list",
+    summary="List the caller's conversations with previews and unread counts.",
+    covers=[("GET", "/api/v1/conversations")],
+    params={
+        "include_muted": opt("--include-muted",
+                             help="Include muted conversations in the list."),
+    },
+)
+async def list_conversations(
+    client: TetraClient, *, include_muted: bool = False,
+) -> dict[str, Any]:
+    """List all conversations for the caller.
+
+    Args:
+        client: Authenticated TetraClient.
+        include_muted: When True, muted conversations are included; by
+            default they are hidden (matching the web inbox).
+
+    Returns:
+        Dict with a ``conversations`` list, each carrying last-message
+        preview, unread count, participants, and mute state.
+    """
+    params: dict[str, Any] = {"include_muted": include_muted}
+    return await client.get("/api/v1/conversations", params=params)
+
+
+@operation(
+    cli="conversations ai",
+    summary="Get (creating if needed) the caller's AI conversation.",
+    covers=[("GET", "/api/v1/conversations/ai")],
+)
+async def get_ai_conversation(client: TetraClient) -> dict[str, Any]:
+    """Return (creating if needed) the caller's AI conversation."""
+    return await client.get("/api/v1/conversations/ai")
+
+
+@operation(
+    cli="conversations stream",
+    summary="Open the agent SSE stream of the caller's AI-thread interactions.",
+    covers=[("GET", "/api/v1/conversations/ai/stream")],
+    output="stream",
+    manual=True,
+)
+async def stream_ai_thread(client: TetraClient) -> Any:
+    """Open the agent-only SSE stream for the caller's AI thread.
+
+    This endpoint returns a ``text/event-stream`` (Server-Sent Events), not a
+    JSON body, and requires API-key auth. It is exposed here so the agent
+    surface can advertise the stream; consumers that need the live frames must
+    read the raw response rather than the parsed JSON the standard client
+    returns. Marked ``manual`` so the generators treat it as a streaming op.
+
+    Args:
+        client: Authenticated TetraClient (must carry an API key).
+
+    Returns:
+        Whatever the underlying client yields for the stream endpoint.
+    """
+    return await client.get("/api/v1/conversations/ai/stream")
+
+
+@operation(
+    cli="conversations attachable-scope",
+    summary="List group UIDs whose entities may be attached in a conversation.",
+    covers=[("GET", "/api/v1/conversations/{conversation_uid}/attachable-scope")],
+    params={"conversation_uid": arg(help="Conversation UID")},
+)
+async def get_attachable_scope(
+    client: TetraClient, conversation_uid: str,
+) -> dict[str, Any]:
+    """Return the group UIDs whose entities may be attached here.
+
+    Args:
+        client: Authenticated TetraClient.
+        conversation_uid: Conversation UID to scope.
+
+    Returns:
+        Dict with a sorted ``group_uids`` list.
+    """
+    return await client.get(
+        f"/api/v1/conversations/{conversation_uid}/attachable-scope"
+    )
+
+
+@operation(
+    cli="conversations messages",
+    summary="Get a page of a conversation's messages (newest first).",
+    covers=[("GET", "/api/v1/conversations/{conversation_uid}/messages")],
+    params={
+        "conversation_uid": arg(help="Conversation UID"),
+        "limit": opt("--limit", min=1, max=100,
+                     help="Max messages to return (1-100, default 50)."),
+        "cursor": opt("--cursor", help="ISO datetime cursor for pagination."),
+    },
+)
+async def get_messages(
+    client: TetraClient,
+    conversation_uid: str,
+    *,
+    cursor: str | None = None,
+    limit: int = 50,
+) -> dict[str, Any]:
+    """Return a page of messages (newest first)."""
+    params: dict[str, Any] = {"limit": limit}
+    if cursor:
+        params["cursor"] = cursor
+    return await client.get(
+        f"/api/v1/conversations/{conversation_uid}/messages", params=params
+    )
+
+
+@operation(
+    cli="conversations unseen",
+    summary="List interactions this identity has not seen (oldest first).",
+    covers=[("GET", "/api/v1/conversations/{conversation_uid}/agent/unseen")],
+    params={
+        "conversation_uid": arg(help="Conversation UID"),
+        "limit": opt("--limit", min=1, max=500, help="Max interactions (default 200)."),
+    },
+)
+async def get_unseen(
+    client: TetraClient, conversation_uid: str, *, limit: int = 200
+) -> dict[str, Any]:
+    """Return interactions this API-key identity has not seen (oldest first)."""
+    return await client.get(
+        f"/api/v1/conversations/{conversation_uid}/agent/unseen",
+        params={"limit": limit},
+    )
+
+
+@operation(
+    cli="conversations mark-read",
+    summary="Advance this identity's read cursor to now.",
+    covers=[("POST", "/api/v1/conversations/{conversation_uid}/agent/read")],
+    params={"conversation_uid": arg(help="Conversation UID")},
+)
+async def mark_agent_read(client: TetraClient, conversation_uid: str) -> dict[str, Any]:
+    """Advance this API-key identity's read cursor to now."""
+    return await client.post(
+        f"/api/v1/conversations/{conversation_uid}/agent/read"
+    )
+
+
+@operation(
+    cli="conversations send",
+    summary="Post a plain text message to a conversation.",
+    covers=[("POST", "/api/v1/conversations/{conversation_uid}/messages")],
+    params={
+        "conversation_uid": arg(help="Conversation UID"),
+        "content": opt("--content", help="Message text."),
+        "reply_to_uid": opt("--reply-to", help="Quoted-reply target interaction UID."),
+    },
+)
+async def post_message(
+    client: TetraClient,
+    conversation_uid: str,
+    *,
+    content: str,
+    reply_to_uid: str | None = None,
+) -> dict[str, Any]:
+    """Post a plain text message (optionally a quoted reply)."""
+    body: dict[str, Any] = {"content": content}
+    if reply_to_uid:
+        body["reply_to_uid"] = reply_to_uid
+    return await client.post(
+        f"/api/v1/conversations/{conversation_uid}/messages", json=body
+    )
+
+
+@operation(
+    cli="conversations action",
+    summary="Post a structured action report to a conversation.",
+    covers=[("POST", "/api/v1/conversations/{conversation_uid}/messages")],
+    params={
+        "conversation_uid": arg(help="Conversation UID"),
+        "content": opt("--content", help="One-line human-readable summary."),
+        "action": opt("--action", json=True,
+                      help="ActionPayload as a JSON object (action_type, subject_type, ...)."),
+        "reason": opt("--reason", help="Why the action was taken (merged into action.reason)."),
+        "reply_to_uid": opt("--reply-to", help="Quoted-reply target interaction UID."),
+    },
+)
+async def post_action(
+    client: TetraClient,
+    conversation_uid: str,
+    *,
+    content: str,
+    action: dict[str, Any],
+    reason: str | None = None,
+    reply_to_uid: str | None = None,
+) -> dict[str, Any]:
+    """Post a structured action report.
+
+    Args:
+        content: One-line human-readable summary.
+        action: ActionPayload dict (action_type, subject_type, subject_uid, ...).
+        reason: Convenience — merged into ``action['reason']`` if given.
+        reply_to_uid: Optional quoted-reply target.
+    """
+    payload = dict(action)
+    if reason is not None:
+        payload["reason"] = reason
+    body: dict[str, Any] = {
+        "content": content,
+        "interaction_type": "action",
+        "action": payload,
+    }
+    if reply_to_uid:
+        body["reply_to_uid"] = reply_to_uid
+    return await client.post(
+        f"/api/v1/conversations/{conversation_uid}/messages", json=body
+    )
+
+
+@operation(
+    cli="conversations mute",
+    summary="Mute a conversation for the caller.",
+    covers=[("POST", "/api/v1/conversations/{conversation_uid}/mute")],
+    params={"conversation_uid": arg(help="Conversation UID to mute")},
+)
+async def mute_conversation(
+    client: TetraClient, conversation_uid: str,
+) -> dict[str, Any]:
+    """Mute a conversation for the caller.
+
+    Args:
+        client: Authenticated TetraClient.
+        conversation_uid: Conversation UID to mute.
+
+    Returns:
+        Dict with ``is_muted: True``.
+    """
+    return await client.post(f"/api/v1/conversations/{conversation_uid}/mute")
+
+
+@operation(
+    cli="conversations unmute",
+    summary="Unmute a conversation for the caller.",
+    covers=[("DELETE", "/api/v1/conversations/{conversation_uid}/mute")],
+    params={"conversation_uid": arg(help="Conversation UID to unmute")},
+)
+async def unmute_conversation(
+    client: TetraClient, conversation_uid: str,
+) -> dict[str, Any]:
+    """Unmute a conversation for the caller.
+
+    Args:
+        client: Authenticated TetraClient.
+        conversation_uid: Conversation UID to unmute.
+
+    Returns:
+        Dict with ``is_muted: False``.
+    """
+    return await client.delete(f"/api/v1/conversations/{conversation_uid}/mute")
+
+
+@operation(
+    cli="conversations dm",
+    summary="Find or preview a direct-message conversation with an account.",
+    covers=[("POST", "/api/v1/conversations/dm/{account_uid}")],
+    params={"account_uid": arg(help="Other account's UID")},
+)
+async def find_or_create_dm(
+    client: TetraClient, account_uid: str,
+) -> dict[str, Any]:
+    """Find an existing DM, or return an ephemeral preview if none exists.
+
+    No DB row is created until the first message is sent; the preview carries
+    enough participant info to render the chat header.
+
+    Args:
+        client: Authenticated TetraClient.
+        account_uid: The other participant's account UID.
+
+    Returns:
+        DM detail dict (``is_ephemeral`` True when no row exists yet).
+    """
+    return await client.post(f"/api/v1/conversations/dm/{account_uid}")
+
+
+@operation(
+    cli="conversations group",
+    summary="Find or preview a group conversation for a group.",
+    covers=[("POST", "/api/v1/conversations/group/{group_uid}")],
+    params={"group_uid": arg(help="Group UID")},
+)
+async def find_or_create_group_conversation(
+    client: TetraClient, group_uid: str,
+) -> dict[str, Any]:
+    """Find an existing group chat, or return an ephemeral preview if none.
+
+    As with DMs, no DB row is created until the first message is sent.
+
+    Args:
+        client: Authenticated TetraClient.
+        group_uid: The group's UID.
+
+    Returns:
+        Conversation dict (``is_ephemeral`` True when no row exists yet).
+    """
+    return await client.post(f"/api/v1/conversations/group/{group_uid}")
+
+
+# ---------------------------------------------------------------------------
+# AI-thread convenience ops — resolve the caller's AI conversation, then act.
+# These keep the historic ``messages read/post/reply/action`` ergonomics on the
+# generated surface so an agent never has to fetch the AI conversation UID by
+# hand. Each delegates to the route-level op above (and thus inherits coverage).
+# ---------------------------------------------------------------------------
+
+@operation(
+    cli="conversations ai-read",
+    summary="Read the caller's AI thread (unseen by default, or full history with --all).",
+    covers=[
+        ("GET", "/api/v1/conversations/ai"),
+        ("GET", "/api/v1/conversations/{conversation_uid}/agent/unseen"),
+        ("GET", "/api/v1/conversations/{conversation_uid}/messages"),
+    ],
+    params={
+        "all_": opt("--all", help="Show recent history instead of just unseen."),
+        "limit": opt("--limit", help="Max messages."),
+    },
+)
+async def ai_read(
+    client: TetraClient,
+    *,
+    all_: bool = False,
+    limit: int = 50,
+) -> dict[str, Any]:
+    """Read the caller's AI thread, resolving the AI conversation first.
+
+    Args:
+        client: Authenticated TetraClient.
+        all_: When True, return recent history; otherwise just unseen messages.
+        limit: Maximum number of messages to return.
+
+    Returns:
+        The messages payload (history or unseen) for the AI conversation.
+    """
+    convo = await get_ai_conversation(client)
+    if all_:
+        return await get_messages(client, convo["uid"], limit=limit)
+    return await get_unseen(client, convo["uid"], limit=limit)
+
+
+@operation(
+    cli="conversations ai-post",
+    summary="Post a plain message to the caller's AI thread.",
+    covers=[
+        ("GET", "/api/v1/conversations/ai"),
+        ("POST", "/api/v1/conversations/{conversation_uid}/messages"),
+    ],
+    params={"content": arg(help="Message text.")},
+)
+async def ai_post(client: TetraClient, content: str) -> dict[str, Any]:
+    """Post a plain message to the caller's AI thread.
+
+    Args:
+        client: Authenticated TetraClient.
+        content: The message text to post.
+
+    Returns:
+        The created interaction dict.
+    """
+    convo = await get_ai_conversation(client)
+    return await post_message(client, convo["uid"], content=content)
+
+
+@operation(
+    cli="conversations ai-reply",
+    summary="Post a quoted reply to a message in the caller's AI thread.",
+    covers=[
+        ("GET", "/api/v1/conversations/ai"),
+        ("POST", "/api/v1/conversations/{conversation_uid}/messages"),
+    ],
+    params={
+        "interaction_uid": arg(help="Interaction UID to reply to."),
+        "content": arg(help="Reply text."),
+    },
+)
+async def ai_reply(
+    client: TetraClient, interaction_uid: str, content: str,
+) -> dict[str, Any]:
+    """Post a quoted reply to a specific message/action in the AI thread.
+
+    Args:
+        client: Authenticated TetraClient.
+        interaction_uid: The interaction being replied to.
+        content: The reply text.
+
+    Returns:
+        The created interaction dict.
+    """
+    convo = await get_ai_conversation(client)
+    return await post_message(
+        client, convo["uid"], content=content, reply_to_uid=interaction_uid,
+    )
+
+
+@operation(
+    cli="conversations ai-action",
+    summary="Log a structured action report to the caller's AI thread.",
+    covers=[
+        ("GET", "/api/v1/conversations/ai"),
+        ("POST", "/api/v1/conversations/{conversation_uid}/messages"),
+    ],
+    params={
+        "content": opt("--content", help="One-line human-readable summary."),
+        "action": opt("--action", json=True,
+                      help="ActionPayload as a JSON object (action_type, subject_type, ...)."),
+        "reason": opt("--reason", help="Why the action was taken."),
+        "reply_to_uid": opt("--reply-to", help="Interaction UID this answers."),
+    },
+)
+async def ai_action(
+    client: TetraClient,
+    *,
+    content: str,
+    action: dict[str, Any],
+    reason: str | None = None,
+    reply_to_uid: str | None = None,
+) -> dict[str, Any]:
+    """Log a structured action report to the caller's AI thread.
+
+    Args:
+        client: Authenticated TetraClient.
+        content: One-line human-readable summary.
+        action: ActionPayload dict (action_type, subject_type, subject_uid, ...).
+        reason: Optional reason merged into ``action['reason']``.
+        reply_to_uid: Optional quoted-reply target interaction UID.
+
+    Returns:
+        The created interaction dict.
+    """
+    convo = await get_ai_conversation(client)
+    return await post_action(
+        client, convo["uid"], content=content, action=action,
+        reason=reason, reply_to_uid=reply_to_uid,
+    )