tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/data.py

@@ -0,0 +1,250 @@
+"""Pure async operations for the data export/import API.
+
+These ops mirror the backend ``/api/v1/data`` routes (see
+``backend/tetra/api/routes/data.py``). Three of them — ``preview``,
+``import`` and ``import-mapped`` — accept a CSV/zip file as a
+``multipart/form-data`` upload, which the plain JSON-only ``TetraClient``
+methods (``get``/``post``/…) cannot express. For those we go through the
+shared ``_upload`` helper below, which drives the client's underlying httpx
+``AsyncClient`` with ``files=``/``data=`` and routes the response through the
+same ``_handle_response`` normalizer every other op relies on. The helper is a
+module-level function so unit tests can monkeypatch it and assert the exact
+multipart payload (method, path, file name/bytes, form fields) without a live
+backend.
+
+The remaining routes (``fields``, ``fix-goal-statuses``) carry no body and use
+the ordinary client methods directly.
+"""
+from __future__ import annotations
+
+import json as _json
+from pathlib import Path
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.api_client.client import _handle_response
+from tetra_cli.registry import arg, operation, opt
+
+
+async def _upload(
+    client: TetraClient,
+    path: str,
+    *,
+    file_field: str,
+    file_name: str,
+    file_bytes: bytes,
+    content_type: str,
+    data: dict[str, Any] | None = None,
+) -> Any:
+    """POST a ``multipart/form-data`` request through the client's httpx layer.
+
+    The JSON-oriented ``TetraClient.post`` only sends ``application/json``, so
+    file-upload routes can't use it. This helper reaches the client's
+    underlying ``AsyncClient`` (carrying the same auth + ``X-Tetra-Agent``
+    headers) to send a real multipart body, then normalizes the response with
+    the shared ``_handle_response`` so error handling matches every other op.
+
+    Args:
+        client: Authenticated TetraClient.
+        path: API path (e.g. ``/api/v1/data/import``).
+        file_field: The multipart field name the route expects (``file``).
+        file_name: File name to send (used by the server's extension check).
+        file_bytes: Raw file contents.
+        content_type: MIME type for the file part.
+        data: Extra form fields (e.g. ``mapping`` JSON, ``sample_size``).
+
+    Returns:
+        Parsed JSON response (or normalized error via ``_handle_response``).
+    """
+    files = {file_field: (file_name, file_bytes, content_type)}
+    response = await client._client.post(path, files=files, data=data or {})
+    return _handle_response(response)
+
+
+def _read_file(file: str) -> tuple[str, bytes]:
+    """Read a local file, returning its base name and raw bytes.
+
+    Args:
+        file: Path to the local file to upload.
+
+    Returns:
+        ``(file_name, file_bytes)``.
+    """
+    p = Path(file)
+    return p.name, p.read_bytes()
+
+
+@operation(
+    cli="data fields",
+    summary="List importable Tetra fields and the transforms available for mapping.",
+    covers=[("GET", "/api/v1/data/fields")],
+)
+async def get_field_definitions(client: TetraClient) -> dict[str, Any]:
+    """List the Tetra fields and transforms available for building a mapping.
+
+    Returns the same ``fields``/``transforms`` catalog the mapped-import flow
+    validates against, so an agent can construct a valid ``--mapping`` for
+    ``data import-mapped`` without guessing field or transform names.
+
+    Args:
+        client: Authenticated TetraClient.
+
+    Returns:
+        Dict with ``fields`` (per entity-type field defs) and ``transforms``
+        (transform name -> docstring).
+    """
+    return await client.get("/api/v1/data/fields")
+
+
+@operation(
+    cli="data fix-goal-statuses",
+    summary="Transition CREATED goals that have events to IN_PROGRESS.",
+    covers=[("POST", "/api/v1/data/fix-goal-statuses")],
+)
+async def fix_goal_statuses(client: TetraClient) -> dict[str, Any]:
+    """Repair goal statuses: move CREATED goals with events to IN_PROGRESS.
+
+    A maintenance/no-body endpoint. Useful after a bulk import (or to fix
+    legacy data) where goals were never transitioned when their events landed.
+
+    Args:
+        client: Authenticated TetraClient.
+
+    Returns:
+        Detailed report dict: ``total_goals``, ``total_events``,
+        ``goals_transitioned`` (list of names), ``transitioned_count``, etc.
+    """
+    return await client.post("/api/v1/data/fix-goal-statuses")
+
+
+@operation(
+    cli="data preview",
+    summary="Preview a CSV file's columns, sample rows, and mappable Tetra fields.",
+    covers=[("POST", "/api/v1/data/preview")],
+    params={
+        "file": arg(help="Path to the CSV file to preview"),
+        "sample_size": opt("--sample-size", min=1,
+                           help="Number of sample rows to return (default 5)"),
+    },
+)
+async def preview_file(
+    client: TetraClient,
+    file: str,
+    *,
+    sample_size: int = 5,
+) -> dict[str, Any]:
+    """Preview a CSV file's structure to plan a mapped import.
+
+    Uploads the CSV (multipart) and returns its column headers, a handful of
+    sample rows, the row count, and the catalog of mappable Tetra fields and
+    transforms — everything needed to author a ``--mapping`` for
+    ``data import-mapped``.
+
+    Args:
+        client: Authenticated TetraClient.
+        file: Path to a local ``.csv`` file.
+        sample_size: How many sample rows to include (default 5).
+
+    Returns:
+        Dict with ``filename``, ``columns``, ``sample_rows``, ``row_count``,
+        ``tetra_fields`` and ``available_transforms``.
+    """
+    file_name, file_bytes = _read_file(file)
+    return await _upload(
+        client,
+        "/api/v1/data/preview",
+        file_field="file",
+        file_name=file_name,
+        file_bytes=file_bytes,
+        content_type="text/csv",
+        data={"sample_size": str(sample_size)},
+    )
+
+
+@operation(
+    cli="data import",
+    summary="Import a Tetra export zip (values, goals, events CSVs).",
+    covers=[("POST", "/api/v1/data/import")],
+    params={
+        "file": arg(help="Path to the .zip export archive to import"),
+    },
+)
+async def import_data(
+    client: TetraClient,
+    file: str,
+) -> dict[str, Any]:
+    """Import a full Tetra export: a ``.zip`` of values/goals/events CSVs.
+
+    Mirrors the export format produced by ``data export``. The server imports
+    in dependency order (values -> goals -> events), skips entities that
+    already exist, transitions goals with events to IN_PROGRESS, and awards
+    retroactive XP. Only ``.zip`` archives are accepted.
+
+    Args:
+        client: Authenticated TetraClient.
+        file: Path to a local ``.zip`` archive.
+
+    Returns:
+        Dict with per-entity ``imported`` counts, optional ``skipped`` counts,
+        ``errors`` (or None), and ``success``.
+    """
+    file_name, file_bytes = _read_file(file)
+    return await _upload(
+        client,
+        "/api/v1/data/import",
+        file_field="file",
+        file_name=file_name,
+        file_bytes=file_bytes,
+        content_type="application/zip",
+    )
+
+
+@operation(
+    cli="data import-mapped",
+    summary="Import a single CSV using a custom column->field mapping.",
+    covers=[("POST", "/api/v1/data/import-mapped")],
+    params={
+        "file": arg(help="Path to the CSV file to import"),
+        "mapping": opt("--mapping", json=True,
+                       help=("MappingConfig as a JSON dict: entity_type, "
+                             "column_mapping, and optional transforms/defaults/"
+                             "value_maps/skip_if_not_empty/sign_modifiers.")),
+    },
+)
+async def import_mapped(
+    client: TetraClient,
+    file: str,
+    *,
+    mapping: dict[str, Any],
+) -> dict[str, Any]:
+    """Import one CSV into a chosen entity type via an explicit column mapping.
+
+    The backend expects ``mapping`` as a JSON string form field alongside the
+    file; this op accepts the mapping as a dict (the CLI parses the JSON blob)
+    and serializes it to JSON for the multipart ``mapping`` field. The dict
+    must carry at least ``entity_type`` ('values' | 'goals' | 'events') and
+    ``column_mapping`` ({source column -> tetra field(s)}); ``transforms``,
+    ``defaults``, ``value_maps``, ``skip_if_not_empty`` and ``sign_modifiers``
+    are optional. Use ``data fields`` / ``data preview`` to discover valid
+    field and transform names.
+
+    Args:
+        client: Authenticated TetraClient.
+        file: Path to a local ``.csv`` file.
+        mapping: MappingConfig dict (see above).
+
+    Returns:
+        Import result dict: ``imported``, ``total_rows``, ``errors`` (or None),
+        ``success`` and, when relevant, ``skipped`` / ``goals_transitioned`` /
+        XP fields.
+    """
+    file_name, file_bytes = _read_file(file)
+    return await _upload(
+        client,
+        "/api/v1/data/import-mapped",
+        file_field="file",
+        file_name=file_name,
+        file_bytes=file_bytes,
+        content_type="text/csv",
+        data={"mapping": _json.dumps(mapping)},
+    )