logion-cli 0.1.0__py3-none-any.whl

cli/commands/courses/uploads.py

@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: MIT
+"""Upload handlers for courses commands."""
+
+from __future__ import annotations
+
+import argparse
+import collections
+import mimetypes
+import sys
+from pathlib import Path
+
+from cli._config import resolve_config_from_args
+from cli._context import make_client
+from cli._errors import handle_error, print_err, validate_uuid_id
+from cli._output import emit, emit_json, to_data
+from cli.commands.courses._capability_render import (
+    append_capability_summary_lines,
+)
+
+
+def _parse_upload_file_spec(spec: str) -> tuple[str, Path]:
+    """Return ``(upload_path, file_path)`` from a ``--file`` argument."""
+    if "=" not in spec:
+        file_path = Path(spec)
+        return (file_path.name, file_path)
+
+    upload_path, file_path_str = spec.split("=", 1)
+    if not upload_path.strip():
+        raise ValueError("upload path before '=' must not be empty")
+    return (upload_path, Path(file_path_str))
+
+
+def _resolve_upload_files(
+    file_specs: list[str],
+) -> list[tuple[str, Path]] | None:
+    resolved: list[tuple[str, Path]] = []
+    for file_spec in file_specs:
+        try:
+            upload_path, path = _parse_upload_file_spec(file_spec)
+        except ValueError as exc:
+            print_err(f"Error: {exc}")
+            return None
+        if not path.is_file():
+            print_err(f"file not found: {path}")
+            return None
+        resolved.append((upload_path, path))
+
+    duplicates = [
+        name
+        for name, count in collections.Counter(
+            upload_path for upload_path, _ in resolved
+        ).items()
+        if count > 1
+    ]
+    if duplicates:
+        print_err(
+            f"duplicate file names not allowed: {sorted(set(duplicates))}"
+        )
+        return None
+    return resolved
+
+
+def handle_uploads_create(args: argparse.Namespace) -> int:
+    """Execute the courses uploads create command."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    if not args.files:
+        print_err("Error: at least one --file is required")
+        return 2
+
+    resolved = _resolve_upload_files(args.files)
+    if resolved is None:
+        return 2
+
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        files = [
+            {
+                "filename": upload_path,
+                "size_bytes": path.stat().st_size,
+                "content_type": mimetypes.guess_type(str(path))[0]
+                or "application/octet-stream",
+            }
+            for upload_path, path in resolved
+        ]
+        result = client.v1.courses.create_upload_session(
+            course_id=args.course_id,
+            files=files,
+        )
+        if config.json_output:
+            emit_json("logion.courses.uploads.create", to_data(result))
+        else:
+            emit(result, json_output=False)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_uploads_complete(args: argparse.Namespace) -> int:
+    """Execute the courses uploads complete command."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    bad_id = validate_uuid_id(args.version_id, "VERSION_ID")
+    if bad_id is not None:
+        return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.courses.complete_upload_session(
+            course_id=args.course_id,
+            version_id=args.version_id,
+        )
+        if config.json_output:
+            emit_json("logion.courses.uploads.complete", to_data(result))
+        else:
+            data = to_data(result)
+            lines: list[str] = [
+                f"version_id: {data['version_id']}",
+                f"version_number: {data['version_number']}",
+                f"status: {data['status']}",
+            ]
+            manifest_s3_key = data.get("manifest_s3_key")
+            if manifest_s3_key:
+                lines.append(f"manifest_s3_key: {manifest_s3_key}")
+            content_hash = data.get("content_hash")
+            if content_hash:
+                lines.append(f"content_hash: {content_hash}")
+            append_capability_summary_lines(lines, data)
+            sys.stdout.write("\n".join(lines))
+            sys.stdout.write("\n")
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()

cli/commands/courses/versions.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: MIT
+"""Version handlers for courses commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from cli._config import resolve_config_from_args
+from cli._context import make_client
+from cli._errors import handle_error, validate_uuid_id
+from cli._output import emit, to_data
+from cli.commands.courses._capability_render import (
+    append_approved_capability_summary_lines,
+    append_capability_summary_lines,
+)
+
+
+def handle_versions_get(args: argparse.Namespace) -> int:
+    """Execute the courses versions get command."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    bad_id = validate_uuid_id(args.version_id, "VERSION_ID")
+    if bad_id is not None:
+        return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.courses.get_version(
+            course_id=args.course_id,
+            version_id=args.version_id,
+        )
+        if config.json_output:
+            emit(result, json_output=True)
+        else:
+            data = to_data(result)
+            lines: list[str] = [
+                f"id: {data['id']}",
+                f"course_id: {data['course_id']}",
+                f"version_number: {data['version_number']}",
+                f"status: {data['status']}",
+            ]
+            manifest_s3_key = data.get("manifest_s3_key")
+            if manifest_s3_key:
+                lines.append(f"manifest_s3_key: {manifest_s3_key}")
+            content_hash = data.get("content_hash")
+            if content_hash:
+                lines.append(f"content_hash: {content_hash}")
+            created_at = data.get("created_at")
+            if created_at:
+                lines.append(f"created_at: {created_at}")
+            created_by = data.get("created_by_agent_id")
+            if created_by:
+                lines.append(f"created_by_agent_id: {created_by}")
+            append_capability_summary_lines(lines, data)
+            append_approved_capability_summary_lines(lines, data)
+            sys.stdout.write("\n".join(lines))
+            sys.stdout.write("\n")
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()

cli/commands/credits/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: MIT
+"""Credits command package."""
+
+from .parser import register
+
+__all__ = ["register"]

cli/commands/credits/_helpers.py

@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: MIT
+"""Shared helpers for credits top-up commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from typing import Any
+from uuid import UUID
+
+from cli._config import CliConfig
+from cli._errors import emit_error_json
+from cli._output import emit_json
+
+TERMINAL_STATUSES = frozenset({
+    "paid",
+    "failed",
+    "expired",
+    "cancelled",
+    "disputed",
+    "reversed",
+})
+
+
+def invalid_identifier(
+    args: argparse.Namespace,
+    label: str,
+    value: str,
+    exit_code: int = 2,
+) -> int:
+    """Emit an unsafe identifier error envelope when JSON was requested."""
+    message = f"{label} must be a valid UUID (got: {value!r})."
+    if getattr(args, "json_output", False):
+        emit_error_json("unsafe_identifier", message, exit_code)
+    else:
+        sys.stderr.write(f"Error: {message}\n")
+    return exit_code
+
+
+def validate_uuid_arg(
+    args: argparse.Namespace, value: str, label: str
+) -> int | None:
+    """Validate a UUID positional argument."""
+    if not value or not value.strip():
+        return invalid_identifier(args, label, value)
+    try:
+        UUID(value)
+    except ValueError:
+        return invalid_identifier(args, label, value)
+    return None
+
+
+def top_up_to_payload(result: Any) -> dict[str, Any]:
+    """Normalize a CreateCreditTopUpResponse to the CLI shape."""
+    raw = (
+        result.model_dump(mode="json")
+        if hasattr(result, "model_dump")
+        else dict(result)
+    )
+    payload: dict[str, Any] = {
+        "top_up_id": raw.get("top_up_id"),
+        "status": raw.get("status"),
+        "amount_cents": raw.get("amount_cents"),
+        "credit_cents_granted": raw.get("credit_cents_granted"),
+        "checkout_url": raw.get("checkout_url"),
+        "stripe_checkout_session_id": raw.get("stripe_checkout_session_id"),
+    }
+    for key, value in raw.items():
+        payload.setdefault(key, value)
+    return payload
+
+
+def emit_top_up_human(payload: dict[str, Any]) -> None:
+    """Render a top-up payload as human-readable key: value lines."""
+    lines = [
+        f"top_up_id: {payload.get('top_up_id')}",
+        f"status: {payload.get('status')}",
+        f"amount_cents: {payload.get('amount_cents')}",
+        f"credit_cents_granted: {payload.get('credit_cents_granted')}",
+    ]
+    if payload.get("checkout_url"):
+        lines.append(f"checkout_url: {payload.get('checkout_url')}")
+    if payload.get("stripe_checkout_session_id"):
+        val = payload.get("stripe_checkout_session_id")
+        lines.append(f"stripe_checkout_session_id: {val}")
+    sys.stdout.write("\n".join(lines))
+    sys.stdout.write("\n")
+
+
+def emit_wait_result(
+    config: CliConfig,
+    payload: dict[str, Any],
+    elapsed: float,
+    *,
+    final: bool,
+) -> None:
+    """Emit the current wait-state payload for a top-up."""
+    wait_payload: dict[str, Any] = {
+        **payload,
+        "elapsed_seconds": round(elapsed, 2),
+        "terminal": payload.get("status") in TERMINAL_STATUSES,
+        "final": final,
+    }
+    if config.json_output:
+        emit_json("logion.credits.top-ups.wait", wait_payload)
+        sys.stdout.write("\n")
+        return
+    summary = (
+        f"Top-up {payload.get('top_up_id')}: "
+        f"status={payload.get('status')} (elapsed {int(elapsed)}s)"
+    )
+    sys.stdout.write(summary)
+    sys.stdout.write("\n")
+
+
+def timeout_payload(top_up_id: str) -> dict[str, Any]:
+    """Return the fallback payload for an unfinished wait call."""
+    return {
+        "top_up_id": top_up_id,
+        "status": "unknown",
+        "amount_cents": None,
+        "credit_cents_granted": None,
+        "checkout_url": None,
+        "stripe_checkout_session_id": None,
+    }
+
+
+def resolve_wait(
+    config: CliConfig,
+    last_payload: dict[str, Any] | None,
+    start: float,
+    top_up_id: str,
+    timeout: int,
+) -> int:
+    """Determine the final wait result and emit it."""
+    elapsed = time.monotonic() - start
+    payload = last_payload or timeout_payload(top_up_id)
+
+    if payload.get("status") == "paid":
+        emit_wait_result(config, payload, elapsed, final=True)
+        return 0
+
+    if payload.get("status") in TERMINAL_STATUSES:
+        emit_wait_result(config, payload, elapsed, final=True)
+        return 1
+
+    msg = f"Top-up {top_up_id} did not reach terminal state within {timeout}s"
+    if config.json_output:
+        emit_error_json("top_up_timeout", msg, 2)
+    else:
+        sys.stderr.write(f"ERROR: {msg}\n")
+    return 2

cli/commands/credits/handlers.py

@@ -0,0 +1,218 @@
+# SPDX-License-Identifier: MIT
+"""Handlers for credits commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from typing import Any
+
+from cli._config import CliConfig, resolve_config_from_args
+from cli._confirm import require_yes
+from cli._context import make_client
+from cli._errors import handle_error
+from cli._output import emit_json, to_data
+from logion import LogionClient
+
+from ._helpers import (
+    TERMINAL_STATUSES,
+    emit_top_up_human,
+    emit_wait_result,
+    resolve_wait,
+    top_up_to_payload,
+    validate_uuid_arg,
+)
+
+
+def _run(
+    args: argparse.Namespace,
+    fn,
+    kind: str,
+    *,
+    json_output: bool,
+    render=None,
+):
+    """Call *fn* on the credits resource and emit the result."""
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = fn(client.v1.credits)
+        if json_output:
+            emit_json(f"logion.credits.{kind}", to_data(result))
+        elif render:
+            render(result)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def _render_balance(result: object) -> None:
+    data = to_data(result)
+    lines = [
+        f"balance_cents: {data.get('balance_cents')}",
+        f"currency_code: {data.get('currency_code', 'USD_CREDIT')}",
+    ]
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+def handle_credits_balance(args: argparse.Namespace) -> int:
+    """Execute the credits balance command."""
+    config = resolve_config_from_args(args)
+    return _run(
+        args,
+        lambda c: c.get_balance(),
+        "balance",
+        json_output=config.json_output,
+        render=_render_balance,
+    )
+
+
+def handle_credits_top_up(args: argparse.Namespace) -> int:
+    """Execute the credits top-up command."""
+    refusal = require_yes(
+        args.yes,
+        "create this credit top-up checkout session",
+    )
+    if refusal is not None:
+        return refusal
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.credits.create_top_up(
+            amount_cents=args.amount_cents
+        )
+        payload = top_up_to_payload(result)
+        if config.json_output:
+            emit_json("logion.credits.top-up", payload)
+        else:
+            emit_top_up_human(payload)
+    except Exception as exc:
+        client.close()
+        return handle_error(exc)
+    if args.wait:
+        return _poll_top_up(args, config, client, payload)
+    client.close()
+    return 0
+
+
+def _poll_top_up(
+    args: argparse.Namespace,
+    config: CliConfig,
+    client: LogionClient,
+    initial_payload: dict[str, Any],
+) -> int:
+    """Poll a top-up until terminal state or timeout."""
+    timeout = min(max(args.wait_timeout, 1), 600)
+    interval = max(getattr(args, "interval", 5), 1)
+    top_up_id = str(initial_payload.get("top_up_id"))
+    last_status: str | None = str(initial_payload.get("status", "unknown"))
+    last_payload: dict[str, Any] = initial_payload
+    start = time.monotonic()
+    try:
+        while True:
+            result = client.v1.credits.get_top_up(top_up_id=top_up_id)
+            pl = top_up_to_payload(result)
+            status = str(pl.get("status"))
+            elapsed = time.monotonic() - start
+            if status != last_status:
+                emit_wait_result(config, pl, elapsed, final=False)
+                last_status = status
+            last_payload = pl
+            if status in TERMINAL_STATUSES or elapsed >= timeout:
+                break
+            time.sleep(interval)
+    except Exception as exc:
+        client.close()
+        return handle_error(exc)
+    client.close()
+    return resolve_wait(config, last_payload, start, top_up_id, timeout)
+
+
+def handle_credits_top_ups_get(args: argparse.Namespace) -> int:
+    """Execute the credits top-ups get command."""
+    bad_id = validate_uuid_arg(args, args.top_up_id, "TOP_UP_ID")
+    if bad_id is not None:
+        return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.credits.get_top_up(top_up_id=args.top_up_id)
+        payload = top_up_to_payload(result)
+        if config.json_output:
+            emit_json("logion.credits.top-ups.get", payload)
+        else:
+            emit_top_up_human(payload)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_credits_top_ups_wait(args: argparse.Namespace) -> int:
+    """Poll until a credit top-up reaches a terminal state."""
+    bad_id = validate_uuid_arg(args, args.top_up_id, "TOP_UP_ID")
+    if bad_id is not None:
+        return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    timeout = min(max(args.wait_timeout, 1), 600)
+    interval = max(args.interval, 1)
+    try:
+        last_status: str | None = None
+        last_payload: dict[str, Any] | None = None
+        start = time.monotonic()
+        while True:
+            result = client.v1.credits.get_top_up(top_up_id=args.top_up_id)
+            pl = top_up_to_payload(result)
+            status = str(pl.get("status"))
+            elapsed = time.monotonic() - start
+            if status != last_status:
+                emit_wait_result(config, pl, elapsed, final=False)
+                last_status = status
+            last_payload = pl
+            if status in TERMINAL_STATUSES or elapsed >= timeout:
+                break
+            time.sleep(interval)
+    except Exception as exc:
+        return handle_error(exc)
+    finally:
+        client.close()
+    return resolve_wait(config, last_payload, start, args.top_up_id, timeout)
+
+
+def _render_ledger(result: object) -> None:
+    items = to_data(result)
+    if not items:
+        sys.stdout.write("No ledger entries.\n")
+    else:
+        for item in items:
+            lines = [
+                f"id: {item.get('id')}",
+                f"kind: {item.get('kind')}",
+                f"direction: {item.get('direction')}",
+                f"amount_cents: {item.get('amount_cents')}",
+                f"balance_after_cents: {item.get('balance_after_cents')}",
+                f"posted_at: {item.get('posted_at')}",
+            ]
+            if item.get("related_top_up_id"):
+                rtup = item.get("related_top_up_id")
+                lines.append(f"related_top_up_id: {rtup}")
+            sys.stdout.write("\n".join(lines) + "\n---\n")
+
+
+def handle_credits_ledger(args: argparse.Namespace) -> int:
+    """Execute the credits ledger command."""
+    config = resolve_config_from_args(args)
+    return _run(
+        args,
+        lambda c: c.list_ledger(),
+        "ledger",
+        json_output=config.json_output,
+        render=_render_ledger,
+    )

cli/commands/credits/parser.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MIT
+"""Parser registration for credits commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._options import COMMON_PARSER
+
+from .handlers import (
+    handle_credits_balance,
+    handle_credits_ledger,
+    handle_credits_top_up,
+    handle_credits_top_ups_get,
+    handle_credits_top_ups_wait,
+)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``credits`` subcommand group."""
+    parser = subparsers.add_parser(
+        "credits",
+        help="Manage credit balance, top-ups, and ledger",
+    )
+    sub = parser.add_subparsers(
+        dest="credits_command",
+        required=True,
+    )
+
+    # credits balance
+    balance = sub.add_parser(
+        "balance",
+        help="Show current credit balance",
+        parents=[COMMON_PARSER],
+    )
+    balance.set_defaults(handler=handle_credits_balance)
+
+    # credits top-up
+    top_up = sub.add_parser(
+        "top-up",
+        help="Create a credit top-up checkout session",
+        parents=[COMMON_PARSER],
+    )
+    top_up.add_argument(
+        "--amount",
+        dest="amount_cents",
+        required=True,
+        type=int,
+        help="Amount in cents for the credit top-up.",
+    )
+    top_up.add_argument(
+        "--yes",
+        action="store_true",
+        help="Confirm creating a Stripe Checkout session for this top-up.",
+    )
+    top_up.add_argument(
+        "--wait",
+        action="store_true",
+        default=False,
+        help="Poll until the top-up reaches a terminal state.",
+    )
+    top_up.add_argument(
+        "--wait-timeout",
+        dest="wait_timeout",
+        type=int,
+        default=300,
+        help="Max seconds to poll (capped at 600).",
+    )
+    top_up.set_defaults(handler=handle_credits_top_up)
+
+    # credits top-ups (nested sub-group)
+    top_ups = sub.add_parser("top-ups", help="Query credit top-ups")
+    top_ups_sub = top_ups.add_subparsers(
+        dest="credits_top_ups_command",
+        required=True,
+    )
+
+    # credits top-ups get
+    top_ups_get = top_ups_sub.add_parser(
+        "get",
+        help="Get a credit top-up by ID",
+        parents=[COMMON_PARSER],
+    )
+    top_ups_get.add_argument("top_up_id", metavar="TOP_UP_ID")
+    top_ups_get.set_defaults(handler=handle_credits_top_ups_get)
+
+    # credits top-ups wait
+    top_ups_wait = top_ups_sub.add_parser(
+        "wait",
+        help="Poll until a top-up reaches a terminal state",
+        parents=[COMMON_PARSER],
+    )
+    top_ups_wait.add_argument("top_up_id", metavar="TOP_UP_ID")
+    top_ups_wait.add_argument(
+        "--wait-timeout",
+        dest="wait_timeout",
+        type=int,
+        default=300,
+        help="Max seconds to poll (capped at 600).",
+    )
+    top_ups_wait.add_argument(
+        "--interval",
+        type=int,
+        default=5,
+        help="Seconds between polls.",
+    )
+    top_ups_wait.set_defaults(handler=handle_credits_top_ups_wait)
+
+    # credits ledger
+    ledger = sub.add_parser(
+        "ledger",
+        help="List credit ledger entries",
+        parents=[COMMON_PARSER],
+    )
+    ledger.set_defaults(handler=handle_credits_ledger)