tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/values_2.py

@@ -0,0 +1,584 @@
+"""Pure async operations for value analytics, status, and sharing.
+
+This module covers the second slice of the values API surface — per-value
+analytics (status, balance, projections, tag breakdowns, goal progress),
+rule history, affordability checks, calendar export, skill-tree
+publishing, and the projection debug exports. The base CRUD ops live in
+``values.py``; nothing here duplicates a route owned by that file.
+
+Each op is a thin async wrapper over :class:`TetraClient`. Optional query
+and body fields are omitted when ``None`` so the backend applies its own
+defaults. Money is expressed in cents and time in seconds at the wire
+level (mirroring the Pydantic request/response models), so values pass
+through unchanged.
+"""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+
+@operation(
+    cli="values status",
+    summary="Get cumulative status for a value (timeline, balance, limits).",
+    covers=[("GET", "/api/v1/values/{uid}/status")],
+    params={
+        "uid": arg(help="Value UID"),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped status."),
+    },
+)
+async def get_value_status(
+    client: TetraClient,
+    uid: str,
+    *,
+    group_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get cumulative status for a value, including timeline and balance.
+
+    Returns current total, the event timeline, expected-vs-actual time and
+    money, surplus/deficit, hierarchy buffering, and limit validation.
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Value UID.
+        group_uid: Optional group scope.
+
+    Returns:
+        Status dict with legacy timeline fields plus balance fields.
+    """
+    params: dict[str, Any] = {}
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    return await client.get(
+        f"/api/v1/values/{uid}/status", params=params or None,
+    )
+
+
+@operation(
+    cli="values project-balance",
+    summary="Project a value's future balance from historical add/subtract rates.",
+    covers=[("GET", "/api/v1/values/{uid}/project-balance")],
+    params={
+        "uid": arg(help="Value UID"),
+        "days": opt("--days", min=1, max=365,
+                    help="Days ahead to project (1-365, default 30)."),
+    },
+)
+async def project_value_balance(
+    client: TetraClient,
+    uid: str,
+    *,
+    days: int = 30,
+) -> dict[str, Any]:
+    """Project a value's future balance based on historical rates.
+
+    Uses the average add/subtract rate from the last 30 days to estimate
+    the balance ``days`` into the future ("Will I have enough PTO?").
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Value UID.
+        days: Days ahead to project (1-365, default 30).
+
+    Returns:
+        Projection dict with projected balance and supporting figures.
+    """
+    return await client.get(
+        f"/api/v1/values/{uid}/project-balance", params={"days": days},
+    )
+
+
+@operation(
+    cli="values rule-projection",
+    summary="Project a value's balance by simulating each rule on its own schedule.",
+    covers=[("GET", "/api/v1/values/{uid}/rule-projection")],
+    params={
+        "uid": arg(help="Value UID"),
+        "months": opt("--months", min=1, max=24,
+                      help="Months to project (1-24, default 12)."),
+        "group_uid": opt("--group-uid", help="Group UID for group context."),
+    },
+)
+async def get_value_rule_projection(
+    client: TetraClient,
+    uid: str,
+    *,
+    months: int = 12,
+    start_money_balance: int | None = None,
+    start_time_balance: int | None = None,
+    group_uid: str | None = None,
+) -> dict[str, Any]:
+    """Project a value's balance using its rule schedules.
+
+    Unlike the weekly-normalized projection, this simulates each rule
+    firing at its natural cadence (bills on the 10th, paychecks every other
+    Friday) to produce a stepped trajectory.
+
+    Money balances are in cents and time balances in seconds, matching the
+    backend query contract.
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Value UID.
+        months: Months to project (1-24, default 12).
+        start_money_balance: Current money balance in cents.
+        start_time_balance: Current time balance in seconds.
+        group_uid: Optional group context (scales rules by member count).
+
+    Returns:
+        Rule-projection dict with ``points`` and per-point ``deltas``.
+    """
+    params: dict[str, Any] = {"months": months}
+    if start_money_balance is not None:
+        params["start_money_balance"] = start_money_balance
+    if start_time_balance is not None:
+        params["start_time_balance"] = start_time_balance
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    return await client.get(
+        f"/api/v1/values/{uid}/rule-projection", params=params,
+    )
+
+
+@operation(
+    cli="values goal-progress",
+    summary="Get time-to-goal progress for a value with a max_money target.",
+    covers=[("GET", "/api/v1/values/{uid}/goal-progress")],
+    params={"uid": arg(help="Value UID")},
+)
+async def get_value_goal_progress(
+    client: TetraClient, uid: str,
+) -> dict[str, Any]:
+    """Get goal progress for a value that has a max_money target.
+
+    Returns the time-to-goal calculation derived from the value's scheduled
+    money rule (current balance, target, remaining, rate, expected
+    completion date, progress percentage).
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Value UID.
+
+    Returns:
+        Goal-progress dict, or a dict with error flags if not computable.
+    """
+    return await client.get(f"/api/v1/values/{uid}/goal-progress")
+
+
+@operation(
+    cli="values tag-analytics",
+    summary="Get per-tag totals for a value's events within a date range.",
+    covers=[("GET", "/api/v1/values/{uid}/tag-analytics")],
+    params={
+        "uid": arg(help="Value UID"),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped analytics."),
+        "target_account_uid": opt("--target-account-uid",
+                                  help="Target member account UID (group context)."),
+    },
+)
+async def get_value_tag_analytics(
+    client: TetraClient,
+    uid: str,
+    *,
+    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 per-tag totals for a value's events within a date range.
+
+    Money mode is detected automatically. Events with multiple tags are
+    fully attributed to each; untagged events are excluded.
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Value UID.
+        start_date: Range start (YYYY-MM-DD, default 6 months ago).
+        end_date: Range end (YYYY-MM-DD, default today).
+        group_uid: Optional group scope.
+        target_account_uid: Optional target member for group context.
+
+    Returns:
+        Tag-analytics dict with per-tag totals.
+    """
+    params: dict[str, Any] = {}
+    if start_date is not None:
+        params["start_date"] = start_date
+    if end_date is not None:
+        params["end_date"] = end_date
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    if target_account_uid is not None:
+        params["target_account_uid"] = target_account_uid
+    return await client.get(
+        f"/api/v1/values/{uid}/tag-analytics", params=params or None,
+    )
+
+
+@operation(
+    cli="values tag-time-series",
+    summary="Get per-tag totals bucketed by week/month for a value's events.",
+    covers=[("GET", "/api/v1/values/{uid}/tag-time-series")],
+    params={
+        "uid": arg(help="Value UID"),
+        "granularity": opt("--granularity", choices=["month", "week"],
+                           help="Bucket granularity (default month)."),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped analytics."),
+        "target_account_uid": opt("--target-account-uid",
+                                  help="Target member account UID (group context)."),
+    },
+)
+async def get_value_tag_time_series(
+    client: TetraClient,
+    uid: str,
+    *,
+    granularity: str = "month",
+    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 per-tag totals bucketed by time period for a value's events.
+
+    Aggregates event amounts by tag into monthly or weekly buckets for
+    time-series charting. Empty periods within the range are included so
+    the chart axis stays continuous.
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Value UID.
+        granularity: ``month`` or ``week`` (default ``month``).
+        start_date: Range start (YYYY-MM-DD, default 6 months ago).
+        end_date: Range end (YYYY-MM-DD, default today).
+        group_uid: Optional group scope.
+        target_account_uid: Optional target member for group context.
+
+    Returns:
+        Tag time-series dict with per-tag bucketed totals.
+    """
+    params: dict[str, Any] = {"granularity": granularity}
+    if start_date is not None:
+        params["start_date"] = start_date
+    if end_date is not None:
+        params["end_date"] = end_date
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    if target_account_uid is not None:
+        params["target_account_uid"] = target_account_uid
+    return await client.get(
+        f"/api/v1/values/{uid}/tag-time-series", params=params,
+    )
+
+
+@operation(
+    cli="values week-events",
+    summary="Get this-week and last-week events for a value, with summaries.",
+    covers=[("GET", "/api/v1/values/{uid}/week-events")],
+    params={
+        "uid": arg(help="Value UID"),
+        "group_uid": opt("--group-uid", help="Group UID for group-scoped lookup."),
+        "target_account_uid": opt("--target-account-uid",
+                                  help="View a specific member's week events."),
+    },
+)
+async def get_value_week_events(
+    client: TetraClient,
+    uid: str,
+    *,
+    group_uid: str | None = None,
+    target_account_uid: str | None = None,
+) -> dict[str, Any]:
+    """Get this-week and last-week events for a value, with summaries.
+
+    Each bucket carries summary statistics (total_events,
+    total_duration_seconds, avg_feels), used by the week-comparison
+    drill-down.
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Value UID.
+        group_uid: Optional group scope.
+        target_account_uid: Optional member to view.
+
+    Returns:
+        Dict with ``this_week`` and ``last_week`` event lists + summaries.
+    """
+    params: dict[str, Any] = {}
+    if group_uid is not None:
+        params["group_uid"] = group_uid
+    if target_account_uid is not None:
+        params["target_account_uid"] = target_account_uid
+    return await client.get(
+        f"/api/v1/values/{uid}/week-events", params=params or None,
+    )
+
+
+@operation(
+    cli="values rule-history",
+    summary="Get the rule-change history for a value (newest first).",
+    covers=[("GET", "/api/v1/values/{uid}/rule-history")],
+    params={
+        "uid": arg(help="Value UID"),
+        "field": opt("--field", choices=["time_rule", "money_rule"],
+                     help="Filter by field (time_rule or money_rule)."),
+    },
+)
+async def get_value_rule_history(
+    client: TetraClient,
+    uid: str,
+    *,
+    field: str | None = None,
+) -> list[dict[str, Any]]:
+    """Get the rule-change history for a value.
+
+    Returns entries sorted by ``changed_at`` (newest first); each carries
+    ``field``, ``previous``, ``new``, ``changed_at``, ``effective_from``.
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Value UID.
+        field: Optional filter — ``time_rule`` or ``money_rule``.
+
+    Returns:
+        List of rule-history entry dicts.
+    """
+    params: dict[str, Any] = {}
+    if field is not None:
+        params["field"] = field
+    return await client.get(
+        f"/api/v1/values/{uid}/rule-history", params=params or None,
+    )
+
+
+@operation(
+    cli="values status-recalculate",
+    summary="Clear the value status cache and recalculate all value statuses.",
+    covers=[("POST", "/api/v1/values/status/recalculate")],
+)
+async def recalculate_all_values(client: TetraClient) -> dict[str, Any]:
+    """Clear all value status cache and recalculate every value's status.
+
+    Forces a fresh recalculation of all value balances and statuses after
+    clearing cached results. The endpoint takes no request body.
+
+    Args:
+        client: Authenticated TetraClient.
+
+    Returns:
+        Dict with ``cache_cleared`` and ``values_recalculated`` counts.
+    """
+    return await client.post("/api/v1/values/status/recalculate")
+
+
+@operation(
+    cli="values can-afford",
+    summary="Check whether a value's current balance can afford an amount.",
+    covers=[("POST", "/api/v1/values/{uid}/can-afford")],
+    params={"uid": arg(help="Value UID")},
+)
+async def check_can_afford(
+    client: TetraClient,
+    uid: str,
+    *,
+    amount: float,
+) -> dict[str, Any]:
+    """Check whether a value's balance can afford a given amount.
+
+    Useful before planning an activity that draws down PTO, a budget, or
+    another accumulated resource. ``amount`` is in the value's native unit
+    (cents for money values, seconds for time values), matching the
+    request schema.
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Value UID.
+        amount: Amount to test against the current balance.
+
+    Returns:
+        Dict with ``can_afford``, ``current_balance``, ``requested_amount``,
+        ``shortfall``.
+    """
+    return await client.post(
+        f"/api/v1/values/{uid}/can-afford", json={"amount": amount},
+    )
+
+
+@operation(
+    cli="values export-skill-tree",
+    summary="Serialize a value subtree as a shareable skill-tree template.",
+    covers=[("POST", "/api/v1/values/{uid}/export-skill-tree")],
+    params={"uid": arg(help="Root value UID")},
+)
+async def export_value_as_skill_tree(
+    client: TetraClient, uid: str,
+) -> dict[str, Any]:
+    """Serialize a value subtree as a shareable skill-tree template.
+
+    Captures structure only (values + goals), not events or personal
+    progress, so the template can be published or adopted by others.
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Root value UID of the subtree to export.
+
+    Returns:
+        Skill-tree template dict.
+    """
+    return await client.post(f"/api/v1/values/{uid}/export-skill-tree")
+
+
+@operation(
+    cli="values share-tree",
+    summary="Publish a value's skill-tree subtree into a group's pool.",
+    covers=[("POST", "/api/v1/values/{value_name}/share-tree")],
+    params={
+        "value_name": arg(help="Full hierarchical name of the root value"),
+        "icon": opt("--icon", help="Emoji to store on the Arena hub tile."),
+        "target_group_uid": opt("--target-group-uid",
+                                help="Target group UID (default: Everyone)."),
+    },
+)
+async def share_tree(
+    client: TetraClient,
+    value_name: str,
+    *,
+    icon: str | None = None,
+    target_group_uid: str | None = None,
+    also_everyone: bool = True,
+) -> dict[str, Any]:
+    """Publish a personal value's skill-tree subtree into a group's pool.
+
+    Creates (or resolves) a cohort value in the target group, shares every
+    goal bound to the subtree, and enrolls the caller in the cohort
+    ranking. Defaults to the Everyone group; publishing into a specific
+    group also enrolls in Everyone unless ``also_everyone`` is False.
+
+    Args:
+        client: Authenticated TetraClient.
+        value_name: Full hierarchical name of the root value.
+        icon: Optional emoji for the Arena hub tile.
+        target_group_uid: Optional target group UID (default Everyone).
+        also_everyone: Also enroll in Everyone when publishing to a specific
+            group (default True; ignored for Everyone).
+
+    Returns:
+        Dict with ``cohort_value_uid`` and ``shared_goal_count``.
+    """
+    body: dict[str, Any] = {"also_everyone": also_everyone}
+    if icon is not None:
+        body["icon"] = icon
+    if target_group_uid is not None:
+        body["target_group_uid"] = target_group_uid
+    return await client.post(
+        f"/api/v1/values/{value_name}/share-tree", json=body,
+    )
+
+
+@operation(
+    cli="values ical",
+    summary="Export a value's recurrence schedule as an iCal (.ics) file.",
+    covers=[("GET", "/api/v1/values/{uid}/ical")],
+    params={"uid": arg(help="Value UID")},
+    output="file",
+)
+async def export_value_ical(client: TetraClient, uid: str) -> tuple[bytes, str]:
+    """Export a value's schedule as an iCal (.ics) file.
+
+    Generates RFC 5545 VEVENT/RRULE entries from the value's schedule-type
+    time rule. Only works for values that have a schedule time rule.
+
+    Args:
+        client: Authenticated TetraClient.
+        uid: Value UID.
+
+    Returns:
+        A ``(content_bytes, filename)`` tuple of iCal content (text/calendar).
+    """
+    return await client.download(f"/api/v1/values/{uid}/ical")
+
+
+@operation(
+    cli="values projection-debug-csv",
+    summary="Export the week-by-week projection debug CSV for one value.",
+    covers=[("GET", "/api/v1/values/analytics/projection/debug-csv")],
+    params={
+        "value_name": opt("--value-name", help="Value name to debug (required)."),
+    },
+    output="file",
+)
+async def get_value_projection_debug_csv(
+    client: TetraClient,
+    *,
+    value_name: str,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    include_virtual_events: bool = False,
+) -> tuple[bytes, str]:
+    """Export a detailed week-by-week projection debug CSV for one value.
+
+    Shows running balance, SET events vs carryover, time-rule expected
+    values, draws_from breakdown, and optionally virtual events for
+    unfilled scheduled time. The date range defaults to 8 weeks back
+    through 8 weeks forward.
+
+    Args:
+        client: Authenticated TetraClient.
+        value_name: Name of the value to debug.
+        start_date: Range start (YYYY-MM-DD); defaults to 8 weeks back.
+        end_date: Range end (YYYY-MM-DD); defaults to 8 weeks forward.
+        include_virtual_events: Include virtual events for unfilled time.
+
+    Returns:
+        A ``(content_bytes, filename)`` tuple of CSV content (text/csv).
+    """
+    params: dict[str, Any] = {
+        "value_name": value_name,
+        "include_virtual_events": include_virtual_events,
+    }
+    if start_date is not None:
+        params["start_date"] = start_date
+    if end_date is not None:
+        params["end_date"] = end_date
+    return await client.download(
+        "/api/v1/values/analytics/projection/debug-csv", params=params,
+    )
+
+
+@operation(
+    cli="values projection-debug-zip",
+    summary="Export projection debug CSVs for all values as a zip archive.",
+    covers=[("GET", "/api/v1/values/analytics/projection/debug-zip")],
+    output="file",
+)
+async def get_all_projections_debug_zip(
+    client: TetraClient,
+    *,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    include_virtual_events: bool = False,
+) -> tuple[bytes, str]:
+    """Export projection debug CSVs for every value with SET events as a zip.
+
+    Bundles one debug CSV per value that has projection data into a single
+    zip archive. The date range defaults to 8 weeks back through 8 weeks
+    forward.
+
+    Args:
+        client: Authenticated TetraClient.
+        start_date: Range start (YYYY-MM-DD); defaults to 8 weeks back.
+        end_date: Range end (YYYY-MM-DD); defaults to 8 weeks forward.
+        include_virtual_events: Include virtual events for unfilled time.
+
+    Returns:
+        A ``(content_bytes, filename)`` tuple of zip content (application/zip).
+    """
+    params: dict[str, Any] = {
+        "include_virtual_events": include_virtual_events,
+    }
+    if start_date is not None:
+        params["start_date"] = start_date
+    if end_date is not None:
+        params["end_date"] = end_date
+    return await client.download(
+        "/api/v1/values/analytics/projection/debug-zip", params=params,
+    )

tetra_cli/api_client/operations/watch.py

@@ -0,0 +1,105 @@
+"""Pure async operations for the watch (wearable) API.
+
+The watch surface lets a paired wearable list the goals/values it can record
+against and lets the signed-in user approve a pending pairing code. 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="watch catalog",
+    summary="List goals + values the watch can record time against.",
+    covers=[("GET", "/api/v1/watch/catalog")],
+)
+async def get_watch_catalog(client: TetraClient) -> dict[str, Any]:
+    """Return the flat list of goals + values the watch can record against.
+
+    Covers the full account scope (personal + every standard group), deduped
+    by UID, each carrying a completion-prompt descriptor. Sorted by recency
+    then leaf name; capped at 500 items with ``truncated`` set when exceeded.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with ``items`` and ``truncated``.
+    """
+    return await client.get("/api/v1/watch/catalog")
+
+
+@operation(
+    cli="watch start-pair",
+    summary="Begin a watch pairing session; returns the user + device codes.",
+    covers=[("POST", "/api/v1/watch/pair/start")],
+)
+async def start_watch_pairing(client: TetraClient) -> dict[str, Any]:
+    """Begin a new watch pairing session.
+
+    Returns the short ``user_code`` the watch displays plus the high-entropy
+    ``device_code`` it polls with. Both expire in ten minutes. Takes no body.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with ``user_code``, ``device_code``, and ``expires_at``.
+    """
+    return await client.post("/api/v1/watch/pair/start")
+
+
+@operation(
+    cli="watch poll-pair",
+    summary="Poll a pending pairing for status; delivers the token once.",
+    covers=[("POST", "/api/v1/watch/pair/poll")],
+    params={"device_code": arg(help="The high-entropy device_code from start-pair.")},
+)
+async def poll_watch_pairing(
+    client: TetraClient, device_code: str,
+) -> dict[str, Any]:
+    """Poll a pending pairing for status; delivers the raw token exactly once.
+
+    Args:
+        client: Authenticated TetraClient
+        device_code: The private poll key returned by start-pair.
+
+    Returns:
+        ``{"status": "pending"}`` while waiting, ``{"status": "approved",
+        "token": ...}`` on the one-time delivery, or ``{"status": "expired"}``.
+    """
+    return await client.post(
+        "/api/v1/watch/pair/poll", json={"device_code": device_code}
+    )
+
+
+@operation(
+    cli="watch approve-pair",
+    summary="Approve a pending watch pairing code and mint a watch API key.",
+    covers=[("POST", "/api/v1/watch/pair/approve")],
+    params={"code": arg(help="The 8-char user code displayed on the watch face.")},
+)
+async def approve_watch_pairing(
+    client: TetraClient, code: str,
+) -> dict[str, Any]:
+    """Approve a pending watch pairing code, linking the watch to the account.
+
+    The signed-in user confirms they want to link this watch; the watch then
+    retrieves its minted token via a single poll call.
+
+    Args:
+        client: Authenticated TetraClient
+        code: The 8-char user code currently displayed on the watch face.
+
+    Returns:
+        ``{"status": "approved"}``.
+
+    Raises:
+        TetraClientError: 404 if the code is unknown, already used, or expired.
+    """
+    return await client.post(
+        "/api/v1/watch/pair/approve", json={"code": code}
+    )