tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/events.py

@@ -0,0 +1,734 @@
+"""Pure async operations for the events API."""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.api_client.operations.tags import resolve_tag_uid
+from tetra_cli.registry import arg, operation, opt
+
+
+@operation(
+    cli="events list",
+    summary="List events with optional filtering and pagination.",
+    covers=[("GET", "/api/v1/events/")],
+    params={
+        "on_date": opt("--on-date", help="Filter to a specific date (YYYY-MM-DD)"),
+        "start_date": opt("--start", help="Range start, inclusive (YYYY-MM-DD). May be used alone."),
+        "end_date": opt("--end", help="Range end, inclusive (YYYY-MM-DD). May be used alone."),
+        "limit": opt("--limit", help="Maximum events to return"),
+        "offset": opt("--offset", help="Events to skip for pagination"),
+        "sort_order": opt("--sort-order", choices=["asc", "desc"],
+                          help="Sort order (newest first = desc)"),
+        "goal": opt("--goal", help="Filter to a goal's full hierarchical name"),
+        "tag": opt("--tag", help="Filter to a tag (case-insensitive, hierarchy-expanded)"),
+    },
+)
+async def list_events(
+    client: TetraClient,
+    *,
+    on_date: str | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    sort_order: str = "desc",
+    goal: str | None = None,
+    tag: str | None = None,
+) -> dict[str, Any]:
+    """List events with optional filtering and pagination.
+
+    Args:
+        client: Authenticated TetraClient
+        on_date: Filter to specific date (YYYY-MM-DD format)
+        start_date: Range start, inclusive (YYYY-MM-DD). May be given without
+            end_date to fetch everything on/after the date.
+        end_date: Range end, inclusive (YYYY-MM-DD). May be given without
+            start_date to fetch everything on/before the date.
+        limit: Maximum events to return (default 50)
+        offset: Number of events to skip for pagination
+        sort_order: 'desc' (newest first) or 'asc' (oldest first)
+        goal: Filter to events linked to this goal's full hierarchical name
+            (e.g. "Social > Trent"). Unknown names return an empty list.
+        tag: Filter to events tagged with this tag (case-insensitive exact
+            name). Tag hierarchy is expanded — a parent tag includes events
+            tagged with any descendant. Unknown names return an empty list.
+
+    Returns:
+        Dict with 'events' list and 'total' count
+    """
+    return await client.get(
+        "/api/v1/events/",
+        params={
+            "on_date": on_date,
+            "start_date": start_date,
+            "end_date": end_date,
+            "limit": limit,
+            "offset": offset,
+            "sort_order": sort_order,
+            "goal": goal,
+            "tag": tag,
+        },
+    )
+
+
+@operation(
+    cli="events get",
+    summary="Get a single event by its UID.",
+    covers=[("GET", "/api/v1/events/{uid}")],
+    params={"uid": arg(help="Event UID")},
+)
+async def get_event(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Get a single event by its UID.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: The event's unique identifier
+
+    Returns:
+        Event dict
+    """
+    return await client.get(f"/api/v1/events/{uid}")
+
+
+@operation(
+    cli="events create",
+    summary="Create a new event recording time or money spent.",
+    covers=[("POST", "/api/v1/events/")],
+    params={
+        "day": arg(help="Date in YYYY-MM-DD format"),
+        "goals": opt("--goal", repeatable=True, help="Goal name (repeatable)"),
+        "values": opt("--value", repeatable=True, help="Value name (repeatable)"),
+        "duration_minutes": opt("--duration-minutes",
+                                help="Duration in minutes (converted to seconds)"),
+        "amount_dollars": opt("--amount-dollars",
+                              help="Amount in dollars (converted to cents)"),
+        "description": opt("--description", help="What happened during this event"),
+        "feels": opt("--feels", min=-2, max=2, help="Mood rating from -2 to +2"),
+        "outcome": opt("--outcome", json=True,
+                       help="Goal metric outcome as a JSON value"),
+        "tag_uids": opt("--tag-uid", repeatable=True, help="Tag UID (repeatable)"),
+    },
+)
+async def create_event(
+    client: TetraClient,
+    *,
+    day: str,
+    goals: list[str] | None = None,
+    values: list[str] | None = None,
+    duration_minutes: float | None = None,
+    amount_dollars: float | None = None,
+    description: str | None = None,
+    feels: int | None = None,
+    start: str | None = None,
+    end: str | None = None,
+    outcome: Any | None = None,
+    tag_uids: list[str] | None = None,
+    group_uid: str | None = None,
+    for_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Create a new event recording time or money spent.
+
+    Converts duration_minutes -> seconds and amount_dollars -> cents before
+    sending to the API, which stores all time in seconds and money in cents.
+
+    Args:
+        client: Authenticated TetraClient
+        day: Date in YYYY-MM-DD format (required)
+        goals: List of goal names (full hierarchical paths)
+        values: List of value names (full hierarchical paths)
+        duration_minutes: Duration in minutes; converted to seconds for API
+        amount_dollars: Money amount in dollars; converted to cents for API
+        description: What happened during this event
+        feels: Mood rating from -2 (terrible) to +2 (great)
+        start: Start time as ISO datetime
+        end: End time as ISO datetime
+        outcome: Goal metric outcome - number, list of numbers, or list of records
+        tag_uids: UIDs of tags to attach to the event
+
+    Returns:
+        Created event dict
+    """
+    body: dict[str, Any] = {"day": day}
+    if goals:
+        body["goals"] = goals
+    if values:
+        body["values"] = values
+    if duration_minutes is not None:
+        body["duration"] = int(duration_minutes * 60)
+    if amount_dollars is not None:
+        body["amount"] = int(amount_dollars * 100)
+    if description:
+        body["description"] = description
+    if feels is not None:
+        body["feels"] = feels
+    if start:
+        body["start"] = start
+    if end:
+        body["end"] = end
+    if outcome is not None:
+        body["outcome"] = outcome
+    if tag_uids:
+        body["tag_uids"] = tag_uids
+    # Creation context — pair (group_uid, for_account_uid) picks the
+    # shape A/B/C per docs/architecture/creation-context.md. Backend
+    # resolver validates the combination.
+    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/events/", json=body)
+
+
+@operation(
+    cli="events update",
+    summary="Update an existing event. Only provided fields are changed.",
+    covers=[("PUT", "/api/v1/events/{uid}")],
+    params={
+        "uid": arg(help="Event UID"),
+        "goals": opt("--goal", repeatable=True,
+                     help="Goal name (repeatable; replaces all)"),
+        "values": opt("--value", repeatable=True,
+                      help="Value name (repeatable; replaces all)"),
+        "duration_minutes": opt("--duration-minutes",
+                                help="Duration in minutes (converted to seconds)"),
+        "amount_dollars": opt("--amount-dollars",
+                              help="Amount in dollars (converted to cents)"),
+        "feels": opt("--feels", min=-2, max=2, help="Mood rating from -2 to +2"),
+        "outcome": opt("--outcome", json=True,
+                       help="Goal metric outcome as a JSON value"),
+        "tag_uids": opt("--tag-uid", repeatable=True,
+                        help="Tag UID (repeatable; replaces all)"),
+    },
+)
+async def update_event(
+    client: TetraClient,
+    *,
+    uid: str,
+    day: str | None = None,
+    goals: list[str] | None = None,
+    values: list[str] | None = None,
+    duration_minutes: float | None = None,
+    amount_dollars: float | None = None,
+    description: str | None = None,
+    feels: int | None = None,
+    start: str | None = None,
+    end: str | None = None,
+    outcome: Any | None = None,
+    tag_uids: list[str] | None = None,
+) -> dict[str, Any]:
+    """Update an existing event. Only provided fields are changed.
+
+    Like create_event, converts duration_minutes -> seconds and
+    amount_dollars -> cents. Only fields explicitly passed (not None) are
+    included in the PATCH body so callers can update a single field cleanly.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: The event's unique identifier (required)
+        day: New date in YYYY-MM-DD format
+        goals: New list of goal names (replaces all goals)
+        values: New list of value names (replaces all values)
+        duration_minutes: New duration in minutes
+        amount_dollars: New money amount in dollars
+        description: New description
+        feels: New mood rating (-2 to +2)
+        start: New start time as ISO datetime
+        end: New end time as ISO datetime
+        outcome: New goal metric outcome
+        tag_uids: New tag UIDs (replaces all tags)
+
+    Returns:
+        Updated event dict
+    """
+    body: dict[str, Any] = {}
+    if day is not None:
+        body["day"] = day
+    if goals is not None:
+        body["goals"] = goals
+    if values is not None:
+        body["values"] = values
+    if duration_minutes is not None:
+        body["duration"] = int(duration_minutes * 60)
+    if amount_dollars is not None:
+        body["amount"] = int(amount_dollars * 100)
+    if description is not None:
+        body["description"] = description
+    if feels is not None:
+        body["feels"] = feels
+    if start is not None:
+        body["start"] = start
+    if end is not None:
+        body["end"] = end
+    if outcome is not None:
+        body["outcome"] = outcome
+    if tag_uids is not None:
+        body["tag_uids"] = tag_uids
+    return await client.put(f"/api/v1/events/{uid}", json=body)
+
+
+@operation(
+    cli="events delete",
+    summary="Delete an event permanently.",
+    covers=[("DELETE", "/api/v1/events/{uid}")],
+    params={"uid": arg(help="Event UID")},
+)
+async def delete_event(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Delete an event permanently.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: The event's unique identifier
+
+    Returns:
+        Deletion confirmation dict
+    """
+    return await client.delete(f"/api/v1/events/{uid}")
+
+
+@operation(
+    cli="events bulk-edit",
+    summary="Edit multiple events at once (UID-based).",
+    covers=[("POST", "/api/v1/events/bulk-edit")],
+    params={
+        "event_uids": opt("--uid", repeatable=True,
+                          help="Event UID to edit (repeatable, required)"),
+        "set_goals": opt("--set-goal", repeatable=True,
+                         help="Replace goals on all selected events"),
+        "set_values": opt("--set-value", repeatable=True,
+                          help="Replace values on all selected events"),
+        "set_feels": opt("--set-feels", min=-2, max=2,
+                         help="Set feels on all selected events"),
+        "add_tag_uids": opt("--add-tag-uid", repeatable=True,
+                            help="Add these tag UIDs to all selected events"),
+        "remove_tag_uids": opt("--remove-tag-uid", repeatable=True,
+                               help="Remove these tag UIDs from all selected events"),
+        "add_tags": opt("--add-tag", repeatable=True,
+                        help="Add tag by NAME (resolved to a UID; repeatable)"),
+        "remove_tags": opt("--remove-tag", repeatable=True,
+                           help="Remove tag by NAME (resolved to a UID; repeatable)"),
+    },
+)
+async def bulk_edit_events(
+    client: TetraClient,
+    *,
+    event_uids: list[str],
+    set_goals: list[str] | None = None,
+    set_values: list[str] | None = None,
+    set_feels: int | None = None,
+    add_tag_uids: list[str] | None = None,
+    remove_tag_uids: list[str] | None = None,
+    add_tags: list[str] | None = None,
+    remove_tags: list[str] | None = None,
+) -> dict[str, Any]:
+    """Edit multiple events at once. Useful for moving events between goals.
+
+    Builds a patch dict from only the provided fields, so partial updates work
+    without overwriting fields the caller didn't touch.
+
+    Tags may be supplied by UID (``add_tag_uids`` / ``remove_tag_uids``) or by
+    NAME (``add_tags`` / ``remove_tags``). Names are resolved to UIDs inside
+    the op via the shared ``resolve_tag_uid`` helper, so both the CLI and the
+    MCP surface inherit name→uid resolution. The resolved names are appended to
+    any UIDs already passed.
+
+    Args:
+        client: Authenticated TetraClient
+        event_uids: List of event UIDs to edit (required)
+        set_goals: Replace goals on all selected events
+        set_values: Replace values on all selected events
+        set_feels: Set feels on all selected events
+        add_tag_uids: Add these tag UIDs to all selected events
+        remove_tag_uids: Remove these tag UIDs from all selected events
+        add_tags: Tag names to add (each resolved to a UID via /tags/search)
+        remove_tags: Tag names to remove (each resolved to a UID)
+
+    Returns:
+        Dict with 'updated_count'
+
+    Raises:
+        TetraClientError: If a tag name in add_tags/remove_tags has no exact
+            (case-insensitive) match.
+    """
+    resolved_add: list[str] = list(add_tag_uids or [])
+    for tag_name in add_tags or []:
+        resolved_add.append(await resolve_tag_uid(client, tag_name))
+    resolved_remove: list[str] = list(remove_tag_uids or [])
+    for tag_name in remove_tags or []:
+        resolved_remove.append(await resolve_tag_uid(client, tag_name))
+
+    patch: dict[str, Any] = {}
+    if set_goals is not None:
+        patch["goals"] = set_goals
+    if set_values is not None:
+        patch["values"] = set_values
+    if set_feels is not None:
+        patch["feels"] = set_feels
+    if resolved_add:
+        patch["add_tag_uids"] = resolved_add
+    if resolved_remove:
+        patch["remove_tag_uids"] = resolved_remove
+    return await client.post(
+        "/api/v1/events/bulk-edit", json={"uids": event_uids, "patch": patch}
+    )
+
+
+@operation(
+    cli="events calendar",
+    summary="Get events organized by day for a calendar month view.",
+    covers=[("GET", "/api/v1/events/calendar/{year}/{month}")],
+    params={
+        "year": arg(help="Calendar year (e.g. 2026)"),
+        "month": arg(help="Calendar month (1-12)"),
+    },
+)
+async def get_calendar(client: TetraClient, *, year: int, month: int) -> dict[str, Any]:
+    """Get events organized by day for a calendar month view.
+
+    Args:
+        client: Authenticated TetraClient
+        year: Calendar year (e.g., 2026)
+        month: Calendar month (1-12)
+
+    Returns:
+        Dict with 'days' mapping date strings to lists of events
+    """
+    return await client.get(f"/api/v1/events/calendar/{year}/{month}")
+
+
+@operation(
+    cli="events get-batch",
+    summary="Fetch multiple events by UID in a single request.",
+    covers=[("POST", "/api/v1/events/batch")],
+    params={
+        "uids": opt("--uid", repeatable=True,
+                    help="Event UID to fetch (repeatable, required)"),
+    },
+)
+async def get_events_batch(
+    client: TetraClient, *, uids: list[str],
+) -> dict[str, Any]:
+    """Fetch multiple events by UID in a single request.
+
+    Performance helper for bulk reads — fetches up to 100 events in one
+    call instead of N round-trips.
+
+    Args:
+        client: Authenticated TetraClient
+        uids: Event UIDs to fetch (max 100)
+
+    Returns:
+        Dict with 'events' (found) and 'not_found' (missing UIDs) lists
+    """
+    return await client.post("/api/v1/events/batch", json={"uids": uids})
+
+
+@operation(
+    cli="events bulk-delete",
+    summary="Delete multiple events in one batch operation.",
+    covers=[("POST", "/api/v1/events/bulk-delete")],
+    params={
+        "uids": opt("--uid", repeatable=True,
+                    help="Event UID to delete (repeatable, required)"),
+        "reason": opt("--reason", help="Reason recorded on the soft delete"),
+    },
+)
+async def bulk_delete_events(
+    client: TetraClient,
+    *,
+    uids: list[str],
+    reason: str | None = None,
+) -> dict[str, Any]:
+    """Delete multiple events in a single batch operation.
+
+    Auto-generated events are not deletable and come back in ``failed_uids``;
+    the rest of the batch still succeeds.
+
+    Args:
+        client: Authenticated TetraClient
+        uids: Event UIDs to delete (required)
+        reason: Optional reason recorded on the soft delete
+
+    Returns:
+        Dict with 'deleted_count', 'deleted_uids', and 'failed_uids'
+    """
+    body: dict[str, Any] = {"uids": uids}
+    if reason is not None:
+        body["reason"] = reason
+    return await client.post("/api/v1/events/bulk-delete", json=body)
+
+
+@operation(
+    cli="events duplicates",
+    summary="Find groups of duplicate events sharing identical field values.",
+    covers=[("GET", "/api/v1/events/duplicates")],
+)
+async def find_duplicates(client: TetraClient) -> dict[str, Any]:
+    """Find groups of duplicate events sharing identical field values.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with 'duplicate_count', 'duplicate_groups', and a 'duplicates'
+        list of {fingerprint, uids, count}
+    """
+    return await client.get("/api/v1/events/duplicates")
+
+
+@operation(
+    cli="events delete-duplicates",
+    summary="Delete duplicate events, keeping one of each group.",
+    covers=[("POST", "/api/v1/events/duplicates/delete")],
+)
+async def delete_duplicates(client: TetraClient) -> dict[str, Any]:
+    """Delete duplicate events, keeping one of each duplicate group.
+
+    For each group of identical events the lowest UID is kept and the rest
+    are deleted.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with 'deleted_count', 'kept_count', and 'deleted_uids'
+    """
+    return await client.post("/api/v1/events/duplicates/delete")
+
+
+@operation(
+    cli="events generate",
+    summary="Generate (or preview) PLANNED events for unlogged time slots.",
+    covers=[("POST", "/api/v1/events/generate")],
+    params={
+        "start_date": arg(help="Range start date (YYYY-MM-DD)"),
+        "end_date": arg(help="Range end date (YYYY-MM-DD)"),
+        "persist": opt("--persist",
+                       help="Save generated events (omit for preview only)"),
+    },
+)
+async def generate_events(
+    client: TetraClient,
+    *,
+    start_date: str,
+    end_date: str,
+    persist: bool = False,
+) -> dict[str, Any]:
+    """Generate system PLANNED events for unlogged time slots in a date range.
+
+    PLANNED events are derived from Value time_rules for slots not already
+    covered by RECORD or user PLANNED events. With ``persist=False`` (default)
+    the result is a preview; ``persist=True`` saves them.
+
+    Args:
+        client: Authenticated TetraClient
+        start_date: Range start date (YYYY-MM-DD)
+        end_date: Range end date (YYYY-MM-DD)
+        persist: True to save events, False to preview only
+
+    Returns:
+        Dict with 'generated_count' and 'events'
+    """
+    return await client.post(
+        "/api/v1/events/generate",
+        json={
+            "start_date": start_date,
+            "end_date": end_date,
+            "persist": persist,
+        },
+    )
+
+
+@operation(
+    cli="events auto-accept",
+    summary="Auto-accept PLANNED events for a past date.",
+    covers=[("POST", "/api/v1/events/auto-accept")],
+    params={"date": arg(help="Date to auto-accept (YYYY-MM-DD)")},
+)
+async def auto_accept_events(
+    client: TetraClient, *, date: str,
+) -> dict[str, Any]:
+    """Auto-accept PLANNED events for a past date.
+
+    PLANNED events with no RECORD overlap become EXECUTED; those that overlap
+    a RECORD become NOT_EXECUTED.
+
+    Args:
+        client: Authenticated TetraClient
+        date: Target date (YYYY-MM-DD)
+
+    Returns:
+        Dict with 'executed_count', 'not_executed_count', 'executed_uids',
+        and 'not_executed_uids'
+    """
+    return await client.post(
+        "/api/v1/events/auto-accept", json={"date": date},
+    )
+
+
+@operation(
+    cli="events accept",
+    summary="Accept a PLANNED event, marking it EXECUTED.",
+    covers=[("POST", "/api/v1/events/{uid}/accept")],
+    params={"uid": arg(help="PLANNED event UID")},
+)
+async def accept_planned_event(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Accept a PLANNED event, marking it as EXECUTED.
+
+    Confirms the planned event happened as scheduled.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: The PLANNED event's UID
+
+    Returns:
+        The updated event dict
+    """
+    return await client.post(f"/api/v1/events/{uid}/accept")
+
+
+@operation(
+    cli="events reject",
+    summary="Reject a PLANNED event, marking it NOT_EXECUTED.",
+    covers=[("POST", "/api/v1/events/{uid}/reject")],
+    params={"uid": arg(help="PLANNED event UID")},
+)
+async def reject_planned_event(client: TetraClient, uid: str) -> dict[str, Any]:
+    """Reject a PLANNED event, marking it as NOT_EXECUTED.
+
+    Records that the planned event did not happen; the event is kept for
+    planning-accuracy metrics.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: The PLANNED event's UID
+
+    Returns:
+        The updated event dict
+    """
+    return await client.post(f"/api/v1/events/{uid}/reject")
+
+
+@operation(
+    cli="events promote-to-goal",
+    summary="Promote a free-form event into a new record-shaped goal.",
+    covers=[("POST", "/api/v1/events/{uid}/promote-to-goal")],
+    params={
+        "uid": arg(help="Event UID to promote"),
+        "goal_name": opt("--goal-name", help="Name for the new goal (required)"),
+    },
+)
+async def promote_event_to_goal(
+    client: TetraClient, *, uid: str, goal_name: str,
+) -> dict[str, Any]:
+    """Promote a free-form event into a new record-shaped goal.
+
+    Creates a ``record``-shaped goal whose outcome field names mirror the
+    event's outcome columns, links the event to it, and canonicalizes the
+    event's outcome keys to the goal's fields.
+
+    Args:
+        client: Authenticated TetraClient
+        uid: UID of the event to promote (must have free-form columns)
+        goal_name: Name for the new goal
+
+    Returns:
+        Dict with 'goal' and 'event'
+    """
+    return await client.post(
+        f"/api/v1/events/{uid}/promote-to-goal",
+        json={"goal_name": goal_name},
+    )
+
+
+@operation(
+    cli="events add-with",
+    summary="Tag a co-attendee on an event.",
+    covers=[("POST", "/api/v1/events/{event_uid}/with")],
+    params={
+        "event_uid": arg(help="Event UID to tag the co-attendee on"),
+        "with_account_uid": opt("--with-account-uid",
+                                help="Account UID of the co-attendee (required)"),
+    },
+)
+async def add_with_tag(
+    client: TetraClient, *, event_uid: str, with_account_uid: str,
+) -> dict[str, Any]:
+    """Tag a co-attendee on an event ("with" feature).
+
+    If the pair is already connected the tag is active immediately; otherwise
+    a peer-connection request is created and the tag is pending_connect.
+
+    Args:
+        client: Authenticated TetraClient
+        event_uid: UID of the event to tag
+        with_account_uid: Account UID of the co-attendee
+
+    Returns:
+        The created with-tag dict
+    """
+    return await client.post(
+        f"/api/v1/events/{event_uid}/with",
+        json={"with_account_uid": with_account_uid},
+    )
+
+
+@operation(
+    cli="events remove-with",
+    summary="Remove a co-attendee with-tag from an event.",
+    covers=[("DELETE", "/api/v1/events/with/{tag_uid}")],
+    params={"tag_uid": arg(help="With-tag UID to remove")},
+)
+async def remove_with_tag(client: TetraClient, tag_uid: str) -> dict[str, Any]:
+    """Remove a co-attendee with-tag.
+
+    Either the event owner or the tagged account may remove it. Removing does
+    not delete an already-created mirror event.
+
+    Args:
+        client: Authenticated TetraClient
+        tag_uid: The with-tag's UID
+
+    Returns:
+        Empty dict (the endpoint returns 204 No Content)
+    """
+    return await client.delete(f"/api/v1/events/with/{tag_uid}")
+
+
+@operation(
+    cli="events with-inbox",
+    summary="List pending with-tags awaiting a mirror event.",
+    covers=[("GET", "/api/v1/events/with/inbox")],
+)
+async def list_with_inbox(client: TetraClient) -> dict[str, Any]:
+    """List pending with-tags where the caller is the tagged co-attendee.
+
+    These are tags that have no mirror event yet — candidates for
+    ``create_with_mirror``.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with a 'tags' list
+    """
+    return await client.get("/api/v1/events/with/inbox")
+
+
+@operation(
+    cli="events mirror-with",
+    summary="Create the mirror event for an accepted with-tag.",
+    covers=[("POST", "/api/v1/events/with/{tag_uid}/mirror")],
+    params={"tag_uid": arg(help="With-tag UID to mirror")},
+)
+async def create_with_mirror(client: TetraClient, tag_uid: str) -> dict[str, Any]:
+    """Create the mirror event for an accepted with-tag.
+
+    Idempotent — re-calling returns the existing mirror.
+
+    Args:
+        client: Authenticated TetraClient
+        tag_uid: The with-tag's UID
+
+    Returns:
+        Dict with 'mirror_event_uid', 'group_uid', and 'goal_uids'
+    """
+    return await client.post(f"/api/v1/events/with/{tag_uid}/mirror")