recala-cli 0.6.0__py3-none-any.whl

recala_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Recala from the terminal: drive a company by hand or through an AI agent."""
+
+__version__ = "0.6.0"

recala_cli/__main__.py

@@ -0,0 +1,3 @@
+from recala_cli.main import cli
+
+cli()

recala_cli/article_runs.py

@@ -0,0 +1,372 @@
+"""Short status reads and actionable outcomes for article work that outlives a request."""
+
+import re
+from datetime import UTC, datetime, timedelta
+from shlex import quote
+
+from recala_cli.display import display_name
+from recala_cli.endpoints import ARTICLE_SHOW, GENERATION_STATUS, CADENCE_SHOW
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.human import describe_fields, finding_sentences, recheck_findings
+from recala_cli.polling import poll_until
+from recala_cli.views import company_timezone, moment_in
+
+
+def hold_text(hold, article_id=None, *, ctx=None):
+    """Render the C1 explanation and its one supported recovery path for a person."""
+    if not hold:
+        return ""
+    identifier = str(article_id or "")[:8]
+    if hold.get("recognised") is False:
+        return ("Held for a reason Recala cannot explain yet. "
+                f"Contact support with the article id {identifier}.")
+    explanation = display_name(hold.get("explanation"))
+    lines = [f"Held: {display_name(hold.get('title')) or 'The article needs attention'}"]
+    if explanation:
+        lines.append(explanation)
+    detail = str(hold.get("detail") or "").strip()
+    if detail and display_name(detail) != explanation:
+        lines.append("Why:")
+        for index, text in enumerate(_hold_findings(hold.get("code") or "", detail), 1):
+            lines.append(f"{index}. {text}")
+    codes = list(dict.fromkeys(hold.get("codes") or []))
+    primary = hold.get("code") or (codes[0] if codes else None)
+    others = [code.replace("_", " ").lower() for code in codes if code != primary]
+    if others:
+        lines.append("Also held for: " + ", ".join(others))
+    recheck = hold.get("recheck")
+    if recheck is not None:
+        zone = company_timezone(ctx, hold) if ctx is not None else hold.get("timezone")
+        when = moment_in(recheck.get("at"), zone) or "date not recorded"
+        verdict = "passed" if recheck.get("cleared") else "still blocked"
+        lines.append(f"Last check: {when}, {verdict}")
+    next_action = _hold_next_action(hold, identifier)
+    if next_action:
+        lines.append(f"Next: {next_action}")
+    return "\n".join(lines)
+
+
+#: Whole sentences joined with "; " (a method review's findings); a "; " after other text stays inside one finding.
+_JOINED_SENTENCES = re.compile(r"(?<=[.!?»”])\s*;\s+")
+
+
+def _hold_findings(code, detail):
+    """One line per finding the API listed (on "- " lines, or as whole sentences joined by "; ")."""
+    if "\n- " in "\n" + detail:
+        texts = [finding["text"] for finding in recheck_findings(code, detail, {}, split_message=True)]
+    else:
+        texts = [sentence for part in _JOINED_SENTENCES.split(detail) for sentence in finding_sentences(part)]
+    return [" ".join(text.removeprefix("- ").split()) for text in texts if text.strip()]
+
+
+def _hold_next_action(hold, identifier):
+    """Only offer commands whose recovery operation exists in this CLI."""
+    next_step = display_name(hold.get("next_step"))
+    action = hold.get("action")
+    command = ""
+    if identifier:
+        identifier = quote(identifier)
+        if action in {"regenerate", "requeue_composition"}:
+            command = f"recala article regenerate {identifier}"
+        elif action == "approve":
+            command = f"recala article approve {identifier}"
+        elif action == "edit":
+            command = (f"recala article edit {identifier} --body-file <file> "
+                       f"&& recala article recheck {identifier}")
+    if action in {"swap_product", "recheck_brand"}:
+        command = "(in the portal)"
+    return " ".join(value for value in (next_step, command) if value)
+
+
+def _json_hold_message(hold, article_id=None):
+    """Preserve the existing JSON error.message bytes; human views use C1 above."""
+    if not hold:
+        return ""
+    code = hold.get("code") or ", ".join(hold.get("codes") or []) or "article_held"
+    detail = hold.get("detail") or describe_fields(hold.get("reasons") or {})
+    explanation = hold.get("explanation") if hold.get("recognised", True) else None
+    text = f"Held ({code}): " + " — ".join(str(v) for v in (detail, explanation) if v)
+    action = hold.get("action") or ""
+    if article_id:
+        identifier = quote(str(article_id))
+        if action in {"regenerate", "requeue_composition"} or "re-run" in text.lower():
+            text += f"\nNext: recala article regenerate {identifier}"
+        elif action in {"edit", "recheck_brand", "swap_product"}:
+            text += f"\nNext: recala article edit {identifier} --body-file <file>; recala article recheck {identifier}"
+        elif action == "approve":
+            text += f"\nNext: recala article approve {identifier}"
+    return text
+
+
+#: The research allowance's stop: no re-run can change it until the ledger's day resets.
+RESEARCH_QUOTA_STOP = "method_search_quota_ledger_blocked"
+
+
+def ensure_outcome(result, client=None, *, ctx=None):
+    """Exit 6 for holds/failures; exit 8 when a research allowance stopped the run."""
+    quota_evidence = [
+        result.get("failure_code"),
+        result.get("failure_reason"),
+        result.get("errors"),
+        result.get("hold"),
+        result.get("error_message"),
+        result.get("recovery"),
+    ]
+    if RESEARCH_QUOTA_STOP in str(quota_evidence):
+        zone = result.get("timezone")
+        if not zone and client:
+            try:
+                zone = (client.call(CADENCE_SHOW).get("cadence") or {}).get("timezone")
+            except CliError:
+                pass
+        # The research ledger's day is UTC, independent of publication cadence.
+        reset = result.get("retry_at") or result.get("resets_at")
+        if not reset:
+            reset = (
+                datetime.now(UTC).replace(hour=0, minute=0, second=0, microsecond=0)
+                + timedelta(days=1)
+            ).isoformat()
+        raise CliError(
+            ExitCode.RATE_LIMITED,
+            RESEARCH_QUOTA_STOP,
+            "Daily research limit reached; try again after " + moment_in(reset, zone),
+            details=result,
+        )
+    # "skipped" is a CMS push that never ran (auto-publish off), a normal result;
+    # only the run's own state can end as skipped.
+    states = {
+        result.get("state"),
+        result.get("cms_status") if result.get("cms_status") != "skipped" else None,
+        result.get("cms_publish_status") if result.get("cms_publish_status") != "skipped" else None,
+    }
+    failed_states = states & {"held", "failed", "skipped"}
+    state = (
+        "held" if "held" in states else next(iter(failed_states), result.get("state"))
+    )
+    if (
+        result.get("success") is False
+        or state in {"held", "failed", "skipped"}
+        or result.get("hold")
+    ):
+        if ctx is not None and ctx.obj.get("as_json"):
+            message = _json_hold_message(result.get("hold"), result.get("article_id"))
+        else:
+            message = hold_text(result.get("hold"), result.get("article_id"), ctx=ctx)
+        if not message:
+            cause = ": ".join(str(result[key]) for key in ("failure_code", "failure_reason") if result.get(key))
+            message = f"Article generation failed ({cause})." if cause else "Article generation failed: " + describe_fields(
+                result.get("errors") or result.get("error_message") or state)
+            queue_id = result.get("queue_id") or result.get("run_id")
+            if queue_id and client and not result.get("article_id"):
+                message += f"\nStart again: {restart_command(client, str(queue_id))}"
+        raise CliError(
+            ExitCode.CONFLICT,
+            "article_held"
+            if result.get("hold") or state == "held"
+            else "generation_failed",
+            message,
+            details=result,
+        )
+    return result
+
+
+def resume_command(client, identifier, *, article=False):
+    return f"recala article {'status' if article else 'run'} {quote(identifier)} --org {quote(client.org_id)}"
+
+
+def restart_command(client, identifier):
+    return f"recala article create --topic {quote(identifier)} --org {quote(client.org_id)}"
+
+
+def wait_for_article(ctx, client, identifier, *, regeneration=False, regenerate_id=None):
+    next_command = resume_command(client, identifier, article=regeneration)
+
+    def read():
+        if regeneration:
+            detail = client.call(ARTICLE_SHOW, path={"article_id": identifier})
+            article = detail.get("article") or {}
+            return {
+                **article,
+                "article_id": identifier,
+                "hold": detail.get("hold"),
+                "state": _regeneration_state(article.get("cms_publish_status")),
+                "title": article.get("article_title") or article.get("topic"),
+                **({"recovery": detail["recovery"]} if detail.get("recovery") else {}),
+            }
+        result = client.call(GENERATION_STATUS, path={"queue_id": identifier})
+        result.setdefault("queue_id", identifier)
+        result["state"] = result.get("state") or result.get("status")
+        if result["state"] in {"completed", "published", "failed"} and result.get(
+            "article_id"
+        ):
+            detail = client.call(
+                ARTICLE_SHOW, path={"article_id": result["article_id"]}
+            )
+            article = detail.get("article") or {}
+            result.update(
+                hold=detail.get("hold"),
+                title=article.get("article_title") or article.get("topic"),
+                cms_status=article.get("cms_publish_status"),
+                grade=article.get("evaluation_grade") or None,  # the API stores "" for an article it never graded
+            )
+            if article.get("cms_publish_status") == "held":
+                result["state"] = "held"
+        return result
+
+    def finished(result):
+        state = result.get("state")
+        if not state:
+            raise CliError(
+                ExitCode.UNAVAILABLE,
+                "unreadable_run",
+                "The API did not report the run's state.",
+            )
+        return state not in {
+            "regenerating",
+            "processing",
+            "queued",
+            "running",
+        }
+
+    try:
+        result = poll_until(
+            ctx,
+            read,
+            finished,
+            label="Waiting for article",
+            timeout_seconds=7200,
+            describe=lambda r: (
+                f"{r.get('title') or r.get('topic') or 'Article'}: {r.get('current_node') or r.get('state')}"
+            ),
+        )
+    except KeyboardInterrupt:
+        raise CliError(
+            ExitCode.UNAVAILABLE,
+            "run_continues",
+            f"The run continues. Check it with: {next_command}",
+            details={"run_id": identifier, "next": {"command": next_command}},
+        ) from None
+    except CliError as error:
+        error.message += f" Check the existing run with: {next_command}."
+        raise
+    if not regeneration and result.get("state") in {"pending", "interrupted", "cancelled", "canceled"}:
+        command = restart_command(client, identifier)
+        raise CliError(
+            ExitCode.UNAVAILABLE, "run_interrupted",
+            f"The run is not running (reset or interrupted). Start again: {command}",
+            details={**result, "run_id": identifier, "next": {"command": command}},
+        )
+    if not regeneration and not _ended_readably(result):
+        raise CliError(
+            ExitCode.UNAVAILABLE, "unexpected_run_state",
+            f"The run ended as '{result.get('state')}' without a readable article. "
+            f"Check it with: {next_command}",
+            details={**result, "run_id": identifier, "next": {"command": next_command}},
+        )
+    if regeneration:
+        ensure_rerun_ran(result, regenerate_id, ctx=ctx)
+    return ensure_outcome(result, client, ctx=ctx)
+
+
+def failed_rerun(recovery):
+    """The article's receipt of a re-run that stopped before replacing its draft, or None."""
+    return recovery if isinstance(recovery, dict) and recovery.get("status") == "failed" else None
+
+
+def ensure_rerun_ran(result, regenerate_id, *, ctx=None):
+    """Exit 6 when this re-run stopped before replacing the draft: the draft's old hold is not its outcome.
+
+    A receipt naming another run is an earlier one; without a run id (an older API) it is this run's,
+    because a re-run that writes a new draft replaces the receipt. A research-allowance stop is left
+    to ``ensure_outcome``, which says when the allowance resets."""
+    recovery = failed_rerun(result.get("recovery"))
+    if (recovery is None or recovery.get("run_id") not in (None, regenerate_id)
+            or RESEARCH_QUOTA_STOP in (recovery.get("refusal_codes") or [])):
+        return result
+    refused = recovery.get("code") == "rerun_refused"
+    as_json = ctx is not None and ctx.obj.get("as_json")
+    raise CliError(ExitCode.CONFLICT, "rerun_refused" if refused else "rerun_failed",
+                   rerun_stop_text(recovery, result.get("hold"), str(result.get("article_id") or ""),
+                                   full_ids=as_json),
+                   details=result)
+
+
+def rerun_stop_text(recovery, hold, article_id, *, full_ids=False):
+    """What stopped, why, what still holds the draft, and one next step; agents get the ids in full."""
+    refused = recovery.get("code") == "rerun_refused"
+    identifier = quote(article_id if full_ids else article_id[:8])
+    command = f"recala article regenerate {identifier}"
+    message = display_name(recovery.get("message")) or "The re-run stopped. Your previous draft is unchanged."
+    if full_ids:
+        return f"{message}\nNext: {command}"
+    lines = [message]
+    if display_name(recovery.get("detail")):
+        lines.append(f"Why: {display_name(recovery['detail'])}")
+    if hold:
+        lines.append(f"Still held: {display_name(hold.get('title')) or 'the article needs attention'}")
+    lines.append(f"Next: {_refused_rerun_step(recovery.get('refusal_codes') or [], identifier)}, then run again: {command}"
+                 if refused else f"Next: try again later: {command}")
+    return "\n".join(lines)
+
+
+def _refused_rerun_step(codes, identifier):
+    """What changes the method's answer: the run in progress ending, an author to sign it, or material it can cite."""
+    if "method_run_in_flight" in codes:
+        return "a run of this article is already in progress; wait for it to finish"
+    if "commission_author_missing" in codes:
+        return (f"sign it with an active author (recala authors list, then recala article person {identifier} "
+                "--person <person>)")
+    return "add material Recala can cite (recala knowledge add-url <url> or recala knowledge add <file>)"
+
+
+def _ended_readably(result):
+    """Success needs an article; failed, held and skipped runs carry their own cause."""
+    state = result.get("state")
+    if state in {"failed", "held", "skipped"}:
+        return True
+    return state in {"completed", "published"} and bool(result.get("article_id"))
+
+
+def _regeneration_state(cms_publish_status):
+    """The article's CMS status is the regeneration's state; a skipped push is not an outcome."""
+    return "draft" if cms_publish_status == "skipped" else cms_publish_status
+
+
+def describe_run(result, *, ctx=None):
+    prefix = (
+        f"Charge mode: {result['charge_mode']}\n" if result.get("charge_mode") else ""
+    )
+    title = result.get("title") or result.get("topic") or "The article"
+    if result.get("article_id"):
+        title += f" [{str(result['article_id'])[:8]}]"
+    if result.get("hold"):
+        return prefix + title + "\n" + hold_text(result["hold"], result.get("article_id"), ctx=ctx)
+    if result.get("state") in {"processing", "queued", "running"}:
+        return (
+            prefix
+            + f"Started: {title} (run {result.get('run_id')}).\nCheck: {result.get('check_command')}"
+        )
+    if result.get("state") == "published" or result.get("cms_status") == "published":
+        outcome = "published."
+    elif "skipped" in (result.get("cms_status"), result.get("cms_publish_status")):
+        outcome = "Ready for review; not pushed to the CMS."
+    else:
+        outcome = "ready for review."
+    if outcome == "published.":
+        return prefix + f"{title}: {outcome}"
+    return prefix + f"{title}: {outcome}" + review_next_step(result)
+
+
+def review_next_step(result):
+    """The grade, then the two commands that take a fresh draft to its signer."""
+    letter = result.get("grade") or result.get("evaluation_grade")  # a re-run reads the article row itself
+    grade = f" Grade {letter}." if letter else ""
+    if not result.get("article_id"):
+        return grade
+    identifier = quote(str(result["article_id"])[:8])
+    if letter and str(letter)[0].upper() not in "ABC":  # below C the lead reads and fixes it; nobody signs it yet
+        return (f"{grade}\nNext: below C it is not ready for anyone to sign. Read it with recala article show "
+                f"{identifier} --markdown, fix it with recala article edit {identifier} --body-file <file>, which "
+                f"keeps it a draft, then run recala article recheck {identifier}")
+    return (f"{grade}\nNext: read it with recala article show {identifier} --markdown, "
+            f"then hand it over with recala article submit {identifier}")

recala_cli/auth.py

@@ -0,0 +1,196 @@
+"""Credentials: which token a request carries, keeping a session fresh, and signing in.
+
+Two kinds of credential reach the API as a Bearer token:
+
+* an **API key** (``rcl_live_…`` / ``rcl_test_…``) for agents and CI: set RECALA_API_KEY,
+  or paste it with ``recala login --with-token``. Never refreshed; revoked in Settings.
+* a **session** from ``recala login`` (a device code approved in the browser), which
+  carries a refresh token and is renewed a minute before it expires.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import platform
+import time
+import uuid
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+from typing import Any
+from urllib.parse import urlsplit
+
+from recala_cli import __version__, config
+from recala_cli.client import RecalaClient
+from recala_cli.endpoints import DEVICE_START, DEVICE_TOKEN, TOKEN_REFRESH
+from recala_cli.errors import CliError, ExitCode, session_expired
+
+API_KEY_PREFIX = "rcl_"
+_REFRESH_MARGIN_SECONDS = 60
+_SLOW_DOWN_STEP_SECONDS = 5
+_REFUSED_SIGN_IN = {
+    "access_denied": "The sign-in was declined in the browser.",
+    "expired_token": "The sign-in code expired. Run `recala login` again.",
+}
+
+
+def bearer_token(client: RecalaClient) -> str:
+    """The token for this command: the environment's, else the stored one (refreshed if due)."""
+    from_environment = config.environment_token()
+    if from_environment:
+        return from_environment
+    credentials = config.load_credentials()
+    if not credentials.get("access_token"):
+        raise CliError(
+            ExitCode.NOT_AUTHENTICATED, "not_authenticated", "Not signed in. Run `recala login`, or set RECALA_API_KEY."
+        )
+    if (credentials.get("kind") == "session" or credentials.get("refresh_token")) and _due_for_refresh(credentials):
+        credentials = _refresh(client, credentials)
+    if credentials.get("kind") == "session" or credentials.get("refresh_token"):
+        client.refresh_session = lambda: _recover_session(client, credentials.get("session_id"))
+    return str(credentials["access_token"])
+
+
+def _recover_session(client: RecalaClient, session_id: str | None) -> str:
+    credentials = config.load_credentials()
+    if (credentials.get("kind") != "session" and not credentials.get("refresh_token")) or credentials.get("session_id") != session_id:
+        raise session_expired()
+    token = credentials.get("access_token")
+    if token and token != client.token:
+        return str(token)  # another process already rotated the stored session
+    return str(_refresh(client, credentials)["access_token"])
+
+
+def credential_kind() -> str:
+    """What this command authenticates with: "api_key", "session" or "access_token"."""
+    from_environment = config.environment_token()
+    if from_environment:
+        return "api_key" if from_environment.startswith(API_KEY_PREFIX) else "access_token"
+    credentials = config.load_credentials()
+    if credentials.get("kind"):
+        return str(credentials["kind"])
+    token = str(credentials.get("access_token") or "")
+    return ("api_key" if token.startswith(API_KEY_PREFIX) else "access_token") if token else "none"
+
+
+def session_id() -> str | None:
+    """The stored sign-in's local id (an [a]ll grant is bound to it); None for keys and environment tokens."""
+    if config.environment_token():
+        return None
+    credentials = config.load_credentials()
+    return None if credentials.get("kind") == "api_key" else credentials.get("session_id")
+
+
+def store_pasted_token(token: str) -> dict[str, Any]:
+    token = token.strip()
+    if not token:
+        raise CliError(ExitCode.USAGE, "empty_token", "No token on standard input.")
+    kind = "api_key" if token.startswith(API_KEY_PREFIX) else "access_token"
+    stored: dict[str, Any] = {"kind": kind, "access_token": token}
+    if kind != "api_key":
+        stored["session_id"] = _new_session_id()  # a person's token: an [a]ll answer may be recorded for it
+    config.save_credentials(stored)
+    config.forget_grant()
+    return {"signed_in": True, "kind": kind}
+
+
+_OS_NAMES = {"Darwin": "macOS", "Linux": "Linux", "Windows": "Windows"}
+
+
+def client_label() -> str:
+    """What the browser shows next to the code ("Recala CLI 0.3.0 on macOS"): the machine's kind, never its name."""
+    system = platform.system()
+    return f"Recala CLI {__version__} on {_OS_NAMES.get(system, system or 'a computer')}"
+
+
+def _new_session_id() -> str:
+    """Names one sign-in on this machine so an [a]ll grant ends with it. Local only, never sent."""
+    return uuid.uuid4().hex
+
+
+def device_login(
+    client: RecalaClient,
+    *,
+    sleep: Callable[[float], None],
+    open_browser: Callable[[str], Any] | None,
+    present_code: Callable[[str, str], None],
+    waiting: Callable[[], AbstractContextManager[Any]] = contextlib.nullcontext,
+) -> dict[str, Any]:
+    """RFC 8628 device authorization: show a code, let the person approve it, poll for the session."""
+    grant = client.call(DEVICE_START, json={"client": client_label()}, authenticated=False)
+    present_code(grant["verification_uri"], grant["user_code"])
+    if open_browser is not None:
+        open_browser(grant.get("verification_uri_complete") or grant["verification_uri"])
+    with waiting():
+        session = _poll_for_session(client, grant, sleep)
+    config.save_credentials({**_session_from(session), "session_id": _new_session_id()})
+    config.forget_grant()
+    config.set_web_url(_origin(grant["verification_uri"]))
+    return {"signed_in": True, "email": (session.get("user") or {}).get("email")}
+
+
+def _origin(url: str) -> str:
+    parts = urlsplit(url)
+    return f"{parts.scheme}://{parts.netloc}"
+
+
+def _poll_for_session(client: RecalaClient, grant: dict[str, Any], sleep: Callable[[float], None]) -> dict[str, Any]:
+    interval, waited, lifetime = int(grant.get("interval", 5)), 0, int(grant.get("expires_in", 600))
+    while waited < lifetime:
+        sleep(interval)
+        waited += interval
+        try:
+            session = client.call(DEVICE_TOKEN, json={"device_code": grant["device_code"]}, authenticated=False)
+        except CliError as refusal:
+            if refusal.code == "authorization_pending":
+                continue
+            if refusal.code == "slow_down":
+                interval += _SLOW_DOWN_STEP_SECONDS
+                continue
+            if refusal.code in _REFUSED_SIGN_IN:
+                message = _REFUSED_SIGN_IN[refusal.code]
+                raise CliError(ExitCode.NOT_AUTHENTICATED, refusal.code, message, refusal.status) from refusal
+            raise
+        answer: dict[str, Any] = session
+        return answer
+    raise CliError(ExitCode.NOT_AUTHENTICATED, "expired_token", _REFUSED_SIGN_IN["expired_token"])
+
+
+def _due_for_refresh(credentials: dict[str, Any]) -> bool:
+    expires_at = credentials.get("expires_at")
+    return expires_at is not None and time.time() >= float(expires_at) - _REFRESH_MARGIN_SECONDS
+
+
+def _refresh(client: RecalaClient, credentials: dict[str, Any]) -> dict[str, Any]:
+    expired = session_expired()
+    if not credentials.get("refresh_token"):
+        raise expired
+    try:
+        session = client.call(TOKEN_REFRESH, json={"refresh_token": credentials["refresh_token"]}, authenticated=False)
+    except ValueError as invalid_response:
+        raise expired from invalid_response
+    except CliError as refusal:
+        if refusal.exit_code in (ExitCode.NOT_AUTHENTICATED, ExitCode.INVALID):
+            expired.status = refusal.status
+            raise expired from refusal
+        raise
+    if not isinstance(session, dict) or not isinstance(session.get("access_token"), str) or not session["access_token"]:
+        raise expired
+    try:
+        renewed = {**credentials, **_session_from(session)}
+    except (TypeError, ValueError) as invalid_response:
+        raise expired from invalid_response
+    config.save_credentials(renewed)
+    return renewed
+
+
+def _session_from(session: dict[str, Any]) -> dict[str, Any]:
+    stored: dict[str, Any] = {
+        "kind": "session",
+        "access_token": session["access_token"],
+        "refresh_token": session.get("refresh_token"),
+        "expires_at": time.time() + int(session.get("expires_in", 3600)),
+    }
+    email = (session.get("user") or {}).get("email")
+    if email:
+        stored["email"] = email
+    return stored

recala_cli/client.py

@@ -0,0 +1,103 @@
+"""The one HTTP client: base URL, bearer token, organization header, error mapping.
+
+Every command goes through ``RecalaClient.call``. It sends X-Recala-Org-ID, the
+header the API's get_current_user selects a company by, and turns every refusal
+or network failure into a CliError with a stable exit code.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from recala_cli import __version__
+from recala_cli.endpoints import ME, Endpoint
+from recala_cli.errors import CliError, DryRunStop, error_from_response, network_failure, session_expired
+
+
+def _auth_layer_refusal(response: httpx.Response) -> bool:
+    if response.status_code != 401:
+        return False
+    try:
+        body = response.json()
+    except ValueError:
+        return False
+    detail = body.get("detail") if isinstance(body, dict) else None
+    return isinstance(detail, str) and detail in ("Invalid token", "Invalid user", "Missing Bearer token")
+
+
+class RecalaClient:
+    def __init__(
+        self,
+        api_url: str,
+        *,
+        org_id: str | None = None,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self.org_id = org_id
+        self.token: str | None = None
+        self._me: Any = None  # GET /me answered once per command; any write forgets it
+        self.refresh_session: Callable[[], str] | None = None
+        self.dry_run = False  # --dry-run: reads go out, no write ever does
+        self._http = httpx.Client(
+            base_url=api_url,
+            transport=transport,
+            timeout=timeout,
+            headers={"User-Agent": f"recala-cli/{__version__}"},
+        )
+
+    @property
+    def known_me(self) -> Any:
+        """GET /me as this command already read it, else None."""
+        return self._me
+
+    def call(
+        self,
+        endpoint: Endpoint,
+        *,
+        path: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        content: bytes | None = None,
+        extra_headers: dict[str, str] | None = None,
+        authenticated: bool = True,
+        timeout: float | None = None,
+    ) -> Any:
+        if endpoint is ME and self._me is not None:
+            return self._me
+        if self.dry_run and endpoint.writes:
+            raise DryRunStop(f"send {endpoint.method} {endpoint.url_path(**(path or {}))}")
+        headers = dict(extra_headers or {})
+        if authenticated:
+            headers["Authorization"] = f"Bearer {self.token}"
+        if self.org_id and "X-Recala-Org-ID" not in headers:
+            headers["X-Recala-Org-ID"] = self.org_id
+        for attempt in range(2):
+            try:
+                response = self._http.request(
+                    endpoint.method, endpoint.url_path(**(path or {})), params=params, json=json, content=content,
+                    headers=headers, timeout=httpx.USE_CLIENT_DEFAULT if timeout is None else timeout,
+                )
+            except httpx.HTTPError as exc:
+                raise network_failure(exc, writes=endpoint.writes) from exc
+            if _auth_layer_refusal(response) and authenticated:
+                expired = session_expired(response.status_code, code=error_from_response(response).code)
+                if attempt or self.refresh_session is None:
+                    raise expired
+                try:
+                    self.token = self.refresh_session()
+                except CliError as refusal:
+                    raise expired from refusal
+                headers["Authorization"] = f"Bearer {self.token}"
+                continue
+            if response.is_error:
+                raise error_from_response(response, writes=endpoint.writes)
+            answer = response.json() if response.content else None
+            if endpoint is ME:
+                self._me = answer
+            elif endpoint.writes:
+                self._me = None
+            return answer