logion-cli 0.1.0__py3-none-any.whl

cli/commands/payments/__init__.py

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

cli/commands/payments/_orders_helpers.py

@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: MIT
+"""Shared helpers for payments order commands."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+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({"fulfilled", "failed", "refunded", "cancelled"})
+
+
+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-ish 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 order_to_payload(result: Any) -> dict[str, Any]:
+    """Normalize SDK order responses to the public CLI shape."""
+    raw = (
+        result.model_dump(mode="json")
+        if hasattr(result, "model_dump")
+        else dict(result)
+    )
+    settled_at = (
+        raw.get("settled_at")
+        or raw.get("paid_at")
+        or raw.get("transferred_at")
+    )
+    payload: dict[str, Any] = {
+        "order_id": raw.get("order_id") or raw.get("id"),
+        "status": raw.get("status"),
+        "course_id": raw.get("course_id"),
+        "amount_cents": raw.get("amount_cents"),
+        "currency": raw.get("currency"),
+        "settled_at": settled_at,
+        "purchase_flow": raw.get("purchase_flow"),
+        "balance_before_cents": raw.get("balance_before_cents"),
+        "balance_after_cents": raw.get("balance_after_cents"),
+    }
+    # Fold through any extra fields the SDK exposes
+    for key, value in raw.items():
+        payload.setdefault(key, value)
+    return payload
+
+
+def emit_wait_result(
+    config: CliConfig,
+    payload: dict[str, Any],
+    elapsed: float,
+    *,
+    final: bool,
+) -> None:
+    """Emit the current wait-state payload."""
+    wait_payload = {
+        **payload,
+        "elapsed_seconds": round(elapsed, 2),
+        "terminal": payload.get("status") in TERMINAL_STATUSES,
+        "final": final,
+    }
+    if config.json_output:
+        emit_json("logion.payments.orders.wait", wait_payload)
+        sys.stdout.write("\n")
+        return
+
+    summary = (
+        f"Order {payload.get('order_id')}: "
+        f"status={payload.get('status')} (elapsed {int(elapsed)}s)"
+    )
+    sys.stdout.write(summary)
+    sys.stdout.write("\n")
+
+
+def timeout_payload(order_id: str) -> dict[str, Any]:
+    """Return the fallback payload for an unfinished wait call."""
+    return {
+        "order_id": order_id,
+        "status": "unknown",
+        "course_id": None,
+        "amount_cents": None,
+        "currency": None,
+        "settled_at": None,
+        "purchase_flow": None,
+        "balance_before_cents": None,
+        "balance_after_cents": None,
+    }

cli/commands/payments/handlers.py

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: MIT
+"""Handlers for payments commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._config import resolve_config_from_args
+from cli._confirm import require_yes
+from cli._context import make_client
+from cli._errors import handle_error, print_err
+from cli._output import emit, emit_json, to_data
+
+from ._orders_helpers import (
+    order_to_payload,
+    validate_uuid_arg,
+)
+
+
+def handle_seller_readiness(args: argparse.Namespace) -> int:
+    """Execute the payments seller-readiness command."""
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.payments.get_seller_readiness()
+        if config.json_output:
+            emit_json("logion.payments.seller-readiness", 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_onboarding_link(args: argparse.Namespace) -> int:
+    """Execute the payments onboarding-link command."""
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.payments.create_onboarding_link()
+        if config.json_output:
+            emit_json("logion.payments.onboarding-link", 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_orders_get(args: argparse.Namespace) -> int:
+    """Execute the payments orders get command."""
+    bad_id = validate_uuid_arg(args, args.order_id, "ORDER_ID")
+    if bad_id is not None:
+        return bad_id
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.payments.get_order(order_id=args.order_id)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        payload = order_to_payload(result)
+        if config.json_output:
+            emit_json("logion.payments.orders.get", payload)
+        else:
+            emit(payload, json_output=False)
+        return 0
+    finally:
+        client.close()
+
+
+def handle_creator_earnings(args: argparse.Namespace) -> int:
+    """Execute the payments creator-earnings command."""
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = client.v1.payments.get_creator_earnings()
+        if config.json_output:
+            emit_json("logion.payments.creator-earnings", 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_cash_out(args: argparse.Namespace) -> int:
+    """Execute the payments cash-out command."""
+    if not args.dry_run:
+        refusal = require_yes(args.yes, "initiate a cash-out transfer")
+        if refusal is not None:
+            return refusal
+        if args.expected_gross_payout_cents is None:
+            print_err(
+                "Error: non-dry-run cash-out requires "
+                "--expected-gross-payout-cents from a prior preview."
+            )
+            return 2
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        if not args.dry_run:
+            preview = client.v1.payments.request_cash_out(
+                minimum_payout_cents=args.minimum_payout_cents,
+                dry_run=True,
+            )
+            preview_data = to_data(preview)
+            actual = preview_data.get("gross_payout_cents")
+            if actual != args.expected_gross_payout_cents:
+                print_err(
+                    "Error: cash-out preview changed: expected "
+                    f"{args.expected_gross_payout_cents} cents, got "
+                    f"{actual} cents. Review the new dry-run before retrying."
+                )
+                return 2
+        result = client.v1.payments.request_cash_out(
+            minimum_payout_cents=args.minimum_payout_cents,
+            dry_run=args.dry_run,
+        )
+        if config.json_output:
+            emit_json("logion.payments.cash-out", to_data(result))
+        else:
+            emit(result, json_output=False)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()

cli/commands/payments/parser.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: MIT
+"""Parser registration for payments commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._options import COMMON_PARSER
+
+from .handlers import (
+    handle_cash_out,
+    handle_creator_earnings,
+    handle_onboarding_link,
+    handle_orders_get,
+    handle_seller_readiness,
+)
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``payments`` subcommand group."""
+    parser = subparsers.add_parser(
+        "payments",
+        help="Manage payments and seller onboarding",
+    )
+    sub = parser.add_subparsers(
+        dest="payments_command",
+        required=True,
+    )
+
+    seller_readiness = sub.add_parser(
+        "seller-readiness",
+        help="Check seller readiness status",
+        parents=[COMMON_PARSER],
+    )
+    seller_readiness.set_defaults(handler=handle_seller_readiness)
+
+    onboarding_link = sub.add_parser(
+        "onboarding-link",
+        help="Create a Stripe onboarding link",
+        parents=[COMMON_PARSER],
+    )
+    onboarding_link.set_defaults(handler=handle_onboarding_link)
+
+    # payments creator-earnings
+    creator_earnings = sub.add_parser(
+        "creator-earnings",
+        help="Get creator earnings summary",
+        parents=[COMMON_PARSER],
+    )
+    creator_earnings.set_defaults(handler=handle_creator_earnings)
+
+    # payments cash-out
+    cash_out = sub.add_parser(
+        "cash-out",
+        help="Request a cash-out of accrued creator earnings",
+        parents=[COMMON_PARSER],
+    )
+    cash_out.add_argument(
+        "--minimum-payout-cents",
+        dest="minimum_payout_cents",
+        type=int,
+        default=None,
+        help="Override minimum payout threshold (in cents).",
+    )
+    cash_out.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=False,
+        help="Compute result without processing the transfer.",
+    )
+    cash_out.add_argument(
+        "--yes",
+        dest="yes",
+        action="store_true",
+        help="Confirm initiating a non-dry-run cash-out transfer.",
+    )
+    cash_out.add_argument(
+        "--expected-gross-payout-cents",
+        dest="expected_gross_payout_cents",
+        type=int,
+        default=None,
+        help="Required for execution; must match the server dry-run preview.",
+    )
+    cash_out.set_defaults(handler=handle_cash_out)
+
+    orders = sub.add_parser("orders", help="Manage orders")
+    orders_sub = orders.add_subparsers(
+        dest="payments_orders_command",
+        required=True,
+    )
+    orders_get = orders_sub.add_parser(
+        "get",
+        help="Get order details",
+        parents=[COMMON_PARSER],
+    )
+    orders_get.add_argument("order_id", metavar="ORDER_ID")
+    orders_get.set_defaults(handler=handle_orders_get)

cli/commands/recall/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+"""Recall command package — search and record locally cached evidence
+of installed capabilities and proven workflows."""
+
+from .parser import register
+
+__all__ = ["register"]

cli/commands/recall/handlers.py

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: MIT
+"""Handlers for the ``recall`` command group.
+
+Read-only fuzzy lookup over installed capabilities, prior successful
+workflows, and (future) local references.  Output carries
+``confidence`` (0..1), ``band`` (HIGH|MEDIUM|LOW|NONE), and
+``query_similarity``.  Confidence is recomputed per query; the on-disk
+index stores only the persisted prior.  Recall never executes anything;
+``danger_flags`` are surfaced for the agent's confirmation gating.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from cli._local_state import (
+    ensure_layout,
+    record_workflow_success,
+    search_recall,
+)
+from cli._output import emit_json
+
+
+def handle_recall_search(args: argparse.Namespace) -> int:
+    """Search the local recall index for *query*."""
+    home = ensure_layout(getattr(args, "target", None))
+    query = args.query.strip()
+    payload = {
+        "query": args.query,
+        "matches": [],
+        "total": 0,
+        "limit": args.limit,
+    }
+    if not query:
+        if getattr(args, "json_output", False):
+            emit_json("logion.recall.search", payload)
+            return 0
+        print("Please clarify the recall query before searching.")
+        return 0
+    results = search_recall(query, home, limit=args.limit)
+    payload = {
+        "query": args.query,
+        "matches": results,
+        "total": len(results),
+        "limit": args.limit,
+    }
+    if getattr(args, "json_output", False):
+        emit_json("logion.recall.search", payload)
+        return 0
+    if not results:
+        print(f"No recall matches for {args.query!r}.")
+        return 0
+    print(f"Top {len(results)} recall matches:")
+    for entry in results:
+        line = (
+            f"  [{entry['type']}] {entry.get('id', '?')} "
+            f"(confidence={entry.get('confidence', 0.0):.2f}, "
+            f"band={entry.get('band', 'NONE')})"
+        )
+        if entry.get("danger_flags"):
+            line += f" flags={','.join(entry['danger_flags'])}"
+        print(line)
+        title = entry.get("title")
+        if title:
+            print(f"    {title}")
+    return 0
+
+
+def handle_recall_record(args: argparse.Namespace) -> int:
+    """Record a successful workflow run into recall history."""
+    home = ensure_layout(getattr(args, "target", None))
+    if not args.command:
+        print(
+            "ERROR: at least one --command is required.",
+            file=sys.stderr,
+        )
+        return 2
+    record = record_workflow_success(
+        workflow_id=args.id,
+        title=args.title,
+        commands=args.command,
+        home=home,
+        confidence=args.confidence,
+    )
+    emit_json("logion.recall.record", record)
+    return 0

cli/commands/recall/parser.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: MIT
+"""Parser registration for recall commands."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from cli._options import COMMON_PARSER
+
+from .handlers import handle_recall_record, handle_recall_search
+
+
+def _confidence(value: str) -> float:
+    """argparse ``type=`` validator: float in the closed interval [0, 1]."""
+    try:
+        f = float(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(
+            f"--confidence must be a float, got {value!r}"
+        ) from exc
+    if not (0.0 <= f <= 1.0):
+        raise argparse.ArgumentTypeError(
+            f"--confidence must be in [0.0, 1.0], got {f}"
+        )
+    return f
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``recall`` subcommand group."""
+    parser = subparsers.add_parser(
+        "recall",
+        help="Read-only fuzzy lookup over local capabilities and workflows",
+    )
+    sub = parser.add_subparsers(
+        dest="recall_command",
+        required=True,
+    )
+
+    search = sub.add_parser(
+        "search",
+        help="Search local recall index",
+        parents=[COMMON_PARSER],
+    )
+    search.add_argument("query", metavar="QUERY")
+    search.add_argument("--limit", type=int, default=5)
+    search.add_argument("--target", type=Path, default=None)
+    search.set_defaults(handler=handle_recall_search)
+
+    record = sub.add_parser(
+        "record",
+        help="Record a successful workflow run",
+        parents=[COMMON_PARSER],
+    )
+    record.add_argument("--id", required=True)
+    record.add_argument("--title", required=True)
+    record.add_argument(
+        "--command",
+        action="append",
+        default=[],
+        help="Command included in the workflow (repeatable)",
+    )
+    record.add_argument(
+        "--confidence",
+        type=_confidence,
+        default=0.5,
+        help="Initial confidence score in [0.0, 1.0]",
+    )
+    record.add_argument("--target", type=Path, default=None)
+    record.set_defaults(handler=handle_recall_record)

cli/commands/referrals/__init__.py

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

cli/commands/referrals/_helpers.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+"""Shared helpers for referrals commands."""
+
+from __future__ import annotations
+
+import sys
+
+from cli._output import to_data
+
+
+def emit_code_human(result: object) -> None:
+    """Render a referral code result as human-readable key: value."""
+    data = to_data(result)
+    lines = [
+        f"code: {data.get('code')}",
+        f"is_default: {data.get('is_default')}",
+    ]
+    if data.get("label"):
+        lines.append(f"label: {data.get('label')}")
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+def emit_link_human(result: object) -> None:
+    """Render a referral link result as human-readable key: value."""
+    data = to_data(result)
+    lines = [
+        f"referral_code: {data.get('referral_code')}",
+        f"link: {data.get('link')}",
+    ]
+    if data.get("course_id"):
+        lines.append(f"course_id: {data.get('course_id')}")
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+def emit_stats_human(result: object) -> None:
+    """Render referral statistics as human-readable key: value."""
+    data = to_data(result)
+    lines = [
+        f"total_attributions: {data.get('total_attributions')}",
+        f"active_attributions: {data.get('active_attributions')}",
+        f"total_rewards_credited_cents: "
+        f"{data.get('total_rewards_credited_cents')}",
+        f"pending_rewards_cents: {data.get('pending_rewards_cents')}",
+    ]
+    sys.stdout.write("\n".join(lines) + "\n")
+
+
+def emit_attributions_human(result: object) -> None:
+    """Render referral attributions as human-readable entries."""
+    items = to_data(result)
+    if not items:
+        sys.stdout.write("No referral attributions.\n")
+    else:
+        for item in items:
+            lines = [
+                f"id: {item.get('id')}",
+                f"referrer_user_id: {item.get('referrer_user_id')}",
+                f"referee_user_id: {item.get('referee_user_id')}",
+                f"status: {item.get('status')}",
+                f"signup_at: {item.get('signup_at')}",
+                f"expires_at: {item.get('expires_at')}",
+            ]
+            sys.stdout.write("\n".join(lines) + "\n---\n")

cli/commands/referrals/handlers.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: MIT
+"""Handlers for referrals commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cli._confirm import require_yes
+from cli._context import make_client
+from cli._errors import handle_error, validate_uuid_id
+from cli._output import emit_json, to_data
+
+from ._helpers import (
+    emit_attributions_human,
+    emit_code_human,
+    emit_link_human,
+    emit_stats_human,
+)
+
+
+def _run(
+    args: argparse.Namespace,
+    fn,
+    kind: str,
+    *,
+    json_output: bool,
+    render=None,
+):
+    """Call *fn* on the referrals resource and emit the result."""
+    config = resolve_config_from_args(args)
+    client = make_client(config)
+    try:
+        result = fn(client.v1.referrals)
+        if json_output:
+            emit_json(f"logion.referrals.{kind}", to_data(result))
+        elif render:
+            render(result)
+    except Exception as exc:
+        return handle_error(exc)
+    else:
+        return 0
+    finally:
+        client.close()
+
+
+def handle_referrals_code(args: argparse.Namespace) -> int:
+    """Execute the referrals code command."""
+    return _run(
+        args,
+        lambda r: r.get_code(),
+        "code",
+        json_output=getattr(args, "json_output", False),
+        render=emit_code_human,
+    )
+
+
+def handle_referrals_link(args: argparse.Namespace) -> int:
+    """Execute the referrals link command."""
+    bad_id = validate_uuid_id(args.course_id, "COURSE_ID")
+    if bad_id is not None:
+        return bad_id
+    refusal = require_yes(
+        args.yes,
+        "share this referral link",
+    )
+    if refusal is not None:
+        return refusal
+    return _run(
+        args,
+        lambda r: r.get_link(course_id=args.course_id),
+        "link",
+        json_output=getattr(args, "json_output", False),
+        render=emit_link_human,
+    )
+
+
+def handle_referrals_stats(args: argparse.Namespace) -> int:
+    """Execute the referrals stats command."""
+    return _run(
+        args,
+        lambda r: r.get_stats(),
+        "stats",
+        json_output=getattr(args, "json_output", False),
+        render=emit_stats_human,
+    )
+
+
+def handle_referrals_attributions(args: argparse.Namespace) -> int:
+    """Execute the referrals attributions command."""
+    return _run(
+        args,
+        lambda r: r.list_attributions(),
+        "attributions",
+        json_output=getattr(args, "json_output", False),
+        render=emit_attributions_human,
+    )
+
+
+# Late import to avoid circulars at module scope
+from cli._config import resolve_config_from_args  # noqa: E402