recala-cli 0.6.0__py3-none-any.whl

recala_cli/commands/connect.py

@@ -0,0 +1,395 @@
+"""`recala connect`: where articles are published (the CMS) and how they are measured (Search Console).
+
+Secrets never travel as arguments: a CMS token or an application password comes
+from an environment variable, stdin or a hidden prompt and goes only into the request
+body sent to Recala, which stores it encrypted. Search Console is connected with
+Google's own sign-in in the browser (the CLI opens the link and waits), then the
+property is chosen here; Recala never sees a Google password.
+"""
+
+from __future__ import annotations
+
+import copy
+
+import os
+from typing import Any
+from urllib.parse import urlsplit
+
+import click
+
+from recala_cli import config
+from recala_cli.client import RecalaClient
+from recala_cli.endpoints import (
+    CMS_STATUS,
+    GSC_PROPERTIES,
+    GSC_PROPERTY,
+    GSC_SERVICE_ACCOUNT,
+    GSC_SERVICE_ACCOUNT_CHECK,
+    GSC_STATUS,
+    ORG_SHOW,
+    PEOPLE_LIST,
+    SANITY_CONNECT,
+    SANITY_STATUS,
+    INDEXING_SITEMAPS,
+    WORDPRESS_CONNECT,
+    WORDPRESS_VERIFY,
+)
+from recala_cli.confirm import is_interactive
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.polling import BROWSER_POLL_SECONDS, open_in_browser, poll_until
+from recala_cli.prompts import ask, ask_optional, ask_secret, choose
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, optional_read, sanity_or_none, accepted_yes_option, dry_run_option
+from recala_cli.views import company_timezone, connection_lines, sitemap_lines
+
+GSC_WAIT_SECONDS = 600
+CMS_WAIT_SECONDS = 600
+_GSC_CONNECTED = {"backfilling", "waiting_for_data", "live", "stale"}
+SANITY_TOKEN_ENV = "RECALA_SANITY_TOKEN"
+SANITY_HOOK_ENV = "RECALA_SANITY_BUILD_HOOK"
+WP_PASSWORD_ENV = "RECALA_WP_APP_PASSWORD"
+SERVICE_ACCOUNT_OFF = ("The service-account method is not enabled on this Recala server. Ask Recala support to enable "
+                       "it, or use: recala connect gsc --oauth")
+
+
+def organization(client: RecalaClient) -> dict[str, Any]:
+    shown = client.call(ORG_SHOW, path={"org_id": str(client.org_id)}) or {}
+    return dict(shown.get("org") or {})
+
+
+def read_connections(client: RecalaClient, *, with_sitemap: bool = True) -> dict[str, Any]:
+    status = {"cms": optional_read(client, CMS_STATUS), "search_console": optional_read(client, GSC_STATUS),
+              "org": organization(client)}
+    if (status["cms"] or {}).get("provider") == "Sanity":
+        status["sanity"] = sanity_or_none(client)
+    if with_sitemap:
+        status["sitemap"] = _sitemap_or_none(client)
+    return status
+
+
+def _sitemap_or_none(client: RecalaClient) -> dict[str, Any] | None:
+    """Sitemaps live in Search Console: without a connection (409) there is nothing to show, not a failure."""
+    try:
+        return optional_read(client, INDEXING_SITEMAPS)  # type: ignore[no-any-return]
+    except CliError as error:
+        if error.exit_code == ExitCode.CONFLICT:
+            return None
+        raise
+
+
+@click.group()
+def connect() -> None:
+    """Connections: the company's CMS and Google Search Console."""
+
+
+@connect.command("status")
+@common_options
+@command_runner(contextual_human=lambda ctx, s: "\n".join(connection_lines(s, zone=company_timezone(ctx, s))))
+def status(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """CMS, Search Console and sitemap: next steps.
+
+    The CMS (its endpoint and the public site), Search Console and the sitemap, with the next step for each."""
+    return read_connections(open_client(ctx, org_flag))
+
+
+# ── Sanity ──────────────────────────────────────────────────────────────────────
+
+
+def suggested_blog(org: dict[str, Any]) -> str | None:
+    """The blog the website scan found, else the website's /blog."""
+    if org.get("blog_base_url"):
+        return str(org["blog_base_url"]).rstrip("/")
+    website = str(org.get("website_url") or "").rstrip("/")
+    return f"{website}/blog" if website else None
+
+
+def sanity_author_map(ctx: click.Context, client: RecalaClient, pairs: tuple[str, ...]) -> dict[str, str]:
+    """``PERSON=SANITY_AUTHOR_ID`` pairs, else ask for each author's Sanity author document ID."""
+    if pairs:
+        mapping = dict(pair.split("=", 1) for pair in pairs if "=" in pair)
+        if len(mapping) != len(pairs):
+            raise CliError(ExitCode.USAGE, "invalid_author", "--author takes PERSON_ID=SANITY_AUTHOR_ID.")
+        return mapping
+    people = (client.call(PEOPLE_LIST) or {}).get("people") or []
+    if not people:
+        raise CliError(ExitCode.CONFLICT, "no_authors", "Add an author first: recala authors add --name ... --title ...")
+    mapping = {}
+    for person in people:
+        answer = ask_optional(ctx, None, label=f"Sanity author document ID for {person.get('display_name')}")
+        if answer:
+            mapping[str(person["id"])] = answer
+    if not mapping:
+        raise CliError(ExitCode.USAGE, "missing_input",
+                       "Map at least one author: --author PERSON_ID=SANITY_AUTHOR_ID (the author's document ID in Studio).")
+    return mapping
+
+
+@connect.command("sanity")
+@common_options
+@command_runner(human=lambda r: f"Sanity connected: project {r.get('project_id')}, dataset {r.get('dataset')}.")
+@click.option("--project", "project_id", default=None, help="Sanity project ID.")
+@click.option("--dataset", default=None, help="Dataset (default production).")
+@click.option("--schema-profile", type=click.Choice(["post", "article"]), default=None,
+              help="Sanity document schema (default post; prompts when interactive).")
+@click.option("--blog-url", default=None, help="The public HTTPS address where articles appear.")
+@click.option("--author", "authors", multiple=True, help="PERSON_ID=SANITY_AUTHOR_ID. Repeat for each author.")
+@click.option("--token-stdin", is_flag=True, help="Read the CMS secret from one stdin line; never echoes it.")
+@accepted_yes_option
+@dry_run_option
+def sanity(ctx: click.Context, org_flag: str | None, project_id: str | None, dataset: str | None, blog_url: str | None,
+           authors: tuple[str, ...], token_stdin: bool, schema_profile: str | None) -> dict[str, Any]:
+    """Publish to Sanity. The write token comes from RECALA_SANITY_TOKEN, --token-stdin or a hidden prompt."""
+    return connect_sanity(ctx, open_client(ctx, org_flag), project_id=project_id, dataset=dataset, blog_url=blog_url,
+                          authors=authors, token_stdin=token_stdin, schema_profile=schema_profile)
+
+
+def connect_sanity(ctx: click.Context, client: RecalaClient, *, project_id: str | None = None,
+                   dataset: str | None = None, blog_url: str | None = None,
+                   authors: tuple[str, ...] = (), token_stdin: bool = False,
+                   schema_profile: str | None = None) -> dict[str, Any]:
+    org = organization(client)
+    body: dict[str, Any] = {
+        "project_id": ask(ctx, project_id, label="Sanity project ID", flag="--project"),
+        "dataset": ask(ctx, dataset, label="Dataset", flag="--dataset", default="production"),
+        "blog_url": ask(ctx, blog_url, label="Public blog address (https)", flag="--blog-url",
+                        default=suggested_blog(org) if is_interactive(ctx) and not blog_url else None),
+        "author_map": sanity_author_map(ctx, client, authors),
+        "schema_profile": choose(ctx, [("post", "post: documents with a status field"), ("article", "article: documents without a status field")],
+                                 label="Schema profile", flag="--schema-profile", value=schema_profile,
+                                 default="post"),
+    }
+    token = ask_secret(ctx, label="Sanity write token", env=SANITY_TOKEN_ENV, token_stdin=token_stdin)
+    hook = ask_secret_optional(SANITY_HOOK_ENV)
+    confirm(ctx, client, f"Connect Sanity project {body['project_id']} ({body['dataset']}) to publish on "
+            f"{body['blog_url']}?")
+    connected: dict[str, Any] = client.call(SANITY_CONNECT, json={**body, "token": token,
+                                                                  **({"build_hook_url": hook} if hook else {})})
+    return {**connected, "schema_profile": body["schema_profile"]}
+
+
+def ask_secret_optional(env: str) -> str:
+    """An optional secret: only ever from the environment."""
+    return os.environ.get(env, "").strip()
+
+
+# ── WordPress ───────────────────────────────────────────────────────────────────
+
+
+def _wordpress_com_address(ctx: click.Context, site: str, wpcom_address: str | None) -> str:
+    """A WordPress.com site behind its own domain (halconia.es) connects through its *.wordpress.com address."""
+    if ".wordpress.com" in site:
+        return site
+    return ask(ctx, wpcom_address, label=f"The WordPress.com address of {site} (e.g. yoursite.wordpress.com)",
+               flag="--wpcom-address")
+
+
+@connect.command("wordpress")
+@common_options
+@command_runner(human=lambda r: f"WordPress connected ({r.get('mode')}): {r.get('site_url') or r.get('blog_url')}.")
+@click.option("--site", default=None, help="The WordPress site address.")
+@click.option("--user", "user_login", default=None, help="Self-hosted: the WordPress user that publishes.")
+@click.option("--wordpress-com", "wordpress_com", is_flag=True, help="The site is hosted on WordPress.com "
+              "(also behind your own domain).")
+@click.option("--wpcom-address", default=None, help="With --wordpress-com and your own domain: the *.wordpress.com address.")
+@click.option("--token-stdin", is_flag=True, help="Read the application password from one stdin line; never echoes it.")
+@accepted_yes_option
+@dry_run_option
+def wordpress(ctx: click.Context, org_flag: str | None, site: str | None, user_login: str | None, wordpress_com: bool,
+              wpcom_address: str | None, token_stdin: bool) -> dict[str, Any]:
+    """Publish to WordPress.
+
+    Self-hosted with an application password
+    (RECALA_WP_APP_PASSWORD, --token-stdin or a hidden prompt),
+    or WordPress.com with its sign-in in the browser."""
+    return connect_wordpress(ctx, open_client(ctx, org_flag), site=site, user_login=user_login,
+                             wordpress_com=wordpress_com, wpcom_address=wpcom_address, token_stdin=token_stdin)
+
+
+def connect_wordpress(ctx: click.Context, client: RecalaClient, *, site: str | None = None,
+                      user_login: str | None = None, wordpress_com: bool = False,
+                      wpcom_address: str | None = None, token_stdin: bool = False) -> dict[str, Any]:
+    org = organization(client)
+    address = ask(ctx, site, label="WordPress site address", flag="--site", default=org.get("website_url") or None)
+    if wordpress_com:
+        address = _wordpress_com_address(ctx, address, wpcom_address)
+    confirm(ctx, client, f"Connect the WordPress site {address}?")
+    verified = client.call(WORDPRESS_VERIFY, json={"url": address, "return_path": "/portal/settings"}) or {}
+    if not verified.get("available"):
+        hint = (" If it is a WordPress.com site behind your own domain, run: recala connect wordpress --wordpress-com"
+                if not wordpress_com else "")
+        raise CliError(ExitCode.CONFLICT, "wordpress_unavailable", f"{verified.get('error') or 'Not available.'}{hint}")
+    if verified.get("mode") == "wpcom":
+        return _connect_wordpress_com(ctx, client, verified, public_site=org.get("website_url") or "")
+    login = ask(ctx, user_login, label="WordPress user", flag="--user")
+    password = ask_secret(ctx, label="Application password (WordPress → Users → Profile)",
+                          env=WP_PASSWORD_ENV, token_stdin=token_stdin)
+    connected: dict[str, Any] = client.call(WORDPRESS_CONNECT, json={
+        "site_url": address, "user_login": login, "password": password,
+        "return_context": verified.get("return_context")})
+    return connected
+
+
+def _connect_wordpress_com(ctx: click.Context, client: RecalaClient, verified: dict[str, Any], *,
+                           public_site: str) -> dict[str, Any]:
+    open_in_browser(ctx, verified["auth_url"], why="Approve Recala on WordPress.com in your browser:")
+    cms = poll_until(ctx, lambda: client.call(CMS_STATUS) or {}, lambda c: bool(c.get("connected")),
+                     label="Waiting for WordPress.com approval in your browser", timeout_seconds=CMS_WAIT_SECONDS,
+                     interval_seconds=BROWSER_POLL_SECONDS, outside_ticks=False,
+                     done=lambda c: f"WordPress.com connected: {c.get('site_url')}")
+    return {"mode": "wpcom", "blog_url": cms.get("site_url"), "public_site": public_site, "connected": True}
+
+
+# ── Search Console ──────────────────────────────────────────────────────────────
+
+
+def suggested_property(properties: list[dict[str, Any]], website: str) -> str | None:
+    """The domain property for the company's own site first, then a URL-prefix property of it."""
+    host = (urlsplit(website if "//" in website else f"https://{website}").hostname or "").removeprefix("www.")
+    if not host:
+        return None
+    ranked = [p["site_url"] for p in properties if p.get("site_url") == f"sc-domain:{host}"]
+    ranked += [p["site_url"] for p in properties
+               if (urlsplit(p.get("site_url", "")).hostname or "").removeprefix("www.") == host]
+    return ranked[0] if ranked else None
+
+
+def connect_search_console(ctx: click.Context, client: RecalaClient, *, property_choice: str | None,
+                           force_oauth: bool = False) -> dict[str, Any]:
+    """Google sign-in in the browser (if needed), then the property, chosen here."""
+    current = client.call(GSC_STATUS) or {}
+    if force_oauth or current.get("state") in ("not_connected", "needs_reconnect", None):
+        link = f"{config.web_url()}/portal/settings?gsc=connect&org={client.org_id}"
+        open_in_browser(ctx, link, why="Sign in with Google in your browser to connect Search Console:")
+        current = poll_until(ctx, lambda: client.call(GSC_STATUS) or {},
+                             lambda s: s.get("state") not in ("not_connected", "needs_reconnect", None),
+                             label="Waiting for Google sign-in in your browser", timeout_seconds=GSC_WAIT_SECONDS,
+                             interval_seconds=BROWSER_POLL_SECONDS, outside_ticks=False,
+                             done=lambda s: "Google account connected")
+    if current.get("state") == "connecting" or (property_choice and property_choice != current.get("property")):
+        current = choose_property(ctx, client, property_choice)
+    return current
+
+
+def choose_property(ctx: click.Context, client: RecalaClient, property_choice: str | None) -> dict[str, Any]:
+    listed = client.call(GSC_PROPERTIES) or {}
+    properties = listed.get("properties") or []
+    if not properties:
+        raise CliError(ExitCode.CONFLICT, "no_properties",
+                       "This Google account has no verified Search Console property. Verify the site in Search Console, "
+                       "then run: recala connect gsc")
+    website = organization(client).get("website_url") or ""
+    chosen = choose(ctx, [(p["site_url"], f"{p['site_url']}  ({p.get('permission_level')})") for p in properties],
+                    label="Which Search Console property is this company's site?", flag="--property",
+                    value=property_choice,
+                    default=listed.get("suggested_property") or suggested_property(properties, website))
+    confirm(ctx, client, f"Use the Search Console property {chosen}?")
+    client.call(GSC_PROPERTY, json={"property": chosen})
+    answer: dict[str, Any] = client.call(GSC_STATUS) or {}
+    return answer
+
+
+def _describe_gsc(ctx: click.Context, result: dict[str, Any]) -> str:
+    zone = company_timezone(ctx, result)
+    lines = connection_lines({"search_console": result.get("search_console"), "cms": result.get("cms"),
+                              "org": result.get("org")}, zone=zone)[-2:] if result.get("search_console") else []
+    if result.get("service_account"):
+        account = result["service_account"]
+        lines = [account.get("instruction") or f"Add {account.get('email')} as a Restricted user."]
+    if result.get("sitemap"):
+        lines.extend(sitemap_lines(result["sitemap"], zone))
+    return "\n".join(lines) or str(result)
+
+
+@connect.command("gsc")
+@common_options
+@command_runner(contextual_human=_describe_gsc)
+@click.option("--oauth", "force_oauth", is_flag=True, help="Sign in with Google in the browser (the default path).")
+@click.option("--property", "property_choice", default=None, help="The property to use, e.g. sc-domain:example.com.")
+@click.option("--service-account", "how", is_flag=True, help="Instead: the email to add as a Restricted user.")
+@click.option("--check", "prop", default=None, help="With the service account: connect this property once it was added.")
+@accepted_yes_option
+@dry_run_option
+def gsc(ctx: click.Context, org_flag: str | None, force_oauth: bool, property_choice: str | None, how: bool,
+        prop: str | None) -> dict[str, Any]:
+    """Connect Google Search Console.
+
+    Google sign-in in the browser, then choose the property."""
+    if how and prop:
+        raise click.UsageError("Choose --service-account or --check <property>.")
+    client = open_client(ctx, org_flag)
+    if how:
+        account = _service_account(client)
+        if account is not None:
+            return {"service_account": account}
+        if not is_interactive(ctx) or not click.confirm(f"  {SERVICE_ACCOUNT_OFF}\n  Connect with Google sign-in now?",
+                                                         default=True, err=True):
+            raise CliError(ExitCode.CONFLICT, "service_account_not_configured", SERVICE_ACCOUNT_OFF, 503)
+        force_oauth = True
+    if prop:
+        confirm(ctx, client, f"Connect {prop} through Recala's service account?")
+        checked: dict[str, Any] = client.call(GSC_SERVICE_ACCOUNT_CHECK, json={"property": prop})
+        return {"search_console": checked}
+    connected = connect_search_console(ctx, client, property_choice=property_choice, force_oauth=force_oauth)
+    return {"search_console": connected}
+
+
+def _service_account(client: RecalaClient) -> dict[str, Any] | None:
+    """The service account's email, or None when the server has no service account configured (a 503)."""
+    try:
+        answer: dict[str, Any] = client.call(GSC_SERVICE_ACCOUNT)
+        return answer
+    except CliError as error:
+        if error.status != 503:
+            raise
+        return None
+
+
+@connect.command("sitemap", hidden=True)  # same view as `recala index sitemaps`
+@common_options
+@command_runner(contextual_human=lambda ctx, r: "\n".join(sitemap_lines(r, company_timezone(ctx, r))))
+def sitemap(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """The site's sitemaps in Search Console.
+
+    Health, errors and last read."""
+    answer: dict[str, Any] = open_client(ctx, org_flag).call(INDEXING_SITEMAPS)
+    return answer
+
+
+@click.group()
+def cms() -> None:
+    """The CMS where the company publishes."""
+
+
+@cms.command("connect")
+@common_options
+@command_runner(human=lambda r: f"CMS connected: {r.get('provider') or r.get('cms_type') or r.get('mode') or 'Sanity'}.")
+@click.option("--provider", type=click.Choice(["sanity", "wordpress"]), default=None)
+@click.option("--project", "project_id", default=None)
+@click.option("--dataset", default=None)
+@click.option("--schema-profile", type=click.Choice(["post", "article"]), default=None,
+              help="Sanity document schema (default post; prompts when interactive).")
+@click.option("--blog-url", default=None)
+@click.option("--author", "authors", multiple=True, help="PERSON_ID=SANITY_AUTHOR_ID.")
+@click.option("--site", default=None)
+@click.option("--user", "user_login", default=None)
+@click.option("--wordpress-com", is_flag=True)
+@click.option("--wpcom-address", default=None)
+@click.option("--token-stdin", is_flag=True, help="Read the CMS token/password from one stdin line; never echoes it.")
+@accepted_yes_option
+@dry_run_option
+def connect_cms(ctx: click.Context, org_flag: str | None, provider: str | None, project_id: str | None,
+                dataset: str | None, blog_url: str | None, authors: tuple[str, ...], site: str | None,
+                user_login: str | None, wordpress_com: bool, wpcom_address: str | None, token_stdin: bool,
+                schema_profile: str | None) -> dict[str, Any]:
+    """Connect Sanity or WordPress. Credentials come from env, --token-stdin or a hidden human prompt."""
+    client = open_client(ctx, org_flag)
+    provider = choose(ctx, [("sanity", "Sanity"), ("wordpress", "WordPress")], label="CMS provider",
+                      flag="--provider", value=provider)
+    if provider == "sanity":
+        return connect_sanity(ctx, client, project_id=project_id, dataset=dataset, blog_url=blog_url,
+                              authors=authors, token_stdin=token_stdin, schema_profile=schema_profile)
+    return connect_wordpress(ctx, client, site=site, user_login=user_login, wordpress_com=wordpress_com,
+                             wpcom_address=wpcom_address, token_stdin=token_stdin)
+
+
+cms.add_command(copy.copy(status), name="status")  # same view as `recala connect status`
+cms.commands["status"].hidden = True

recala_cli/commands/credits.py

@@ -0,0 +1,46 @@
+"""`recala credits`: everything that limits spending, before any paid action."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from recala_cli.client import RecalaClient
+from recala_cli.endpoints import (
+    BILLING_CREDITS,
+    BILLING_MANAGED_USAGE,
+    BILLING_SPEND,
+    BILLING_SUBSCRIPTION,
+    CREDITS_SUMMARY,
+    ENTITLEMENTS,
+)
+from recala_cli.runtime import command_runner, common_options, open_client, optional_read
+from recala_cli.views import describe_credits
+
+
+def read_credits(client: RecalaClient) -> dict[str, Any]:
+    """The balance, the plan, the managed cap, the portal's summary (plan, left, reset) and the plan's caps."""
+    entitlements = optional_read(client, ENTITLEMENTS)
+    return {
+        "credits": client.call(BILLING_CREDITS),
+        "subscription": client.call(BILLING_SUBSCRIPTION),
+        "managed_usage": client.call(BILLING_MANAGED_USAGE),
+        "summary": optional_read(client, CREDITS_SUMMARY),
+        "entitlements": entitlements if (entitlements or {}).get("enabled") else None,
+    }
+
+
+@click.command()
+@common_options
+@command_runner(human=describe_credits)
+@click.option("--spend", is_flag=True, help="Also Recala's provider spend this month and today (owners).")
+def credits(ctx: click.Context, org_flag: str | None, spend: bool) -> dict[str, Any]:
+    """Plan, articles left, reset date, extras, caps.
+
+    Unlimited when no plan caps apply."""
+    client = open_client(ctx, org_flag)
+    answer = read_credits(client)
+    if spend:
+        answer["provider_spend"] = client.call(BILLING_SPEND)
+    return answer

recala_cli/commands/faithful_translations.py

@@ -0,0 +1,70 @@
+"""Explicit owner consent for automatic approval of verified faithful translations."""
+
+import click
+
+from recala_cli import auth
+from recala_cli.endpoints import FAITHFUL_TRANSLATIONS_SET, FAITHFUL_TRANSLATIONS_SHOW
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, accepted_yes_option
+
+SETTING = "auto_approve_faithful_translations"
+
+
+def _owner_session_client(ctx, org_flag):
+    if auth.credential_kind() == "api_key":
+        raise CliError(
+            ExitCode.FORBIDDEN, "human_only",
+            "This setting requires a signed-in company owner. Run: recala login",
+        )
+    return open_client(ctx, org_flag)
+
+
+def _describe_setting(result):
+    state = "on" if result[SETTING] else "off"
+    prefix = "Dry run — " if result.get("dry_run") else ""
+    return f"{prefix}Faithful translation auto-approval: {state}"
+
+
+@click.group("faithful-translations")
+def faithful_translations():
+    """Auto-approve verified translations (owners).
+
+    Ordinary auto-approve is also required."""
+
+
+@faithful_translations.command("show")
+@common_options
+@command_runner(human=_describe_setting)
+def show(ctx, org_flag):
+    """Show the saved faithful-translation approval setting."""
+    return _owner_session_client(ctx, org_flag).call(FAITHFUL_TRANSLATIONS_SHOW)
+
+
+def _change_setting(ctx, org_flag, enabled, dry_run):
+    client = _owner_session_client(ctx, org_flag)
+    if dry_run:
+        return {"dry_run": True, SETTING: enabled}
+    confirm(ctx, client, f"Turn faithful translation auto-approval {'on' if enabled else 'off'}?")
+    return client.call(FAITHFUL_TRANSLATIONS_SET, json={"enabled": enabled})
+
+
+@faithful_translations.command("enable")
+@common_options
+@command_runner(human=_describe_setting)
+@click.option("--dry-run", is_flag=True, help="Preview the setting without saving.")
+@accepted_yes_option
+def enable(ctx, org_flag, dry_run):
+    """Opt into auto-approving verified translations.
+
+    Approval happens after the source and translation checks pass."""
+    return _change_setting(ctx, org_flag, True, dry_run)
+
+
+@faithful_translations.command("disable")
+@common_options
+@command_runner(human=_describe_setting)
+@click.option("--dry-run", is_flag=True, help="Preview the setting without saving.")
+@accepted_yes_option
+def disable(ctx, org_flag, dry_run):
+    """Turn off the faithful-translation approval opt-in."""
+    return _change_setting(ctx, org_flag, False, dry_run)

recala_cli/commands/gsc.py

@@ -0,0 +1,79 @@
+"""Google Search Console: read the stored numbers (connect with `recala connect gsc`).
+
+The numbers come from what Recala has stored, never from a live call to Google, so exploring them costs nothing. Only
+Google's final days are counted. A company with no numbers gets its state in words, never a zero.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from recala_cli.endpoints import GSC_PERFORMANCE
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.runtime import command_runner, common_options, open_client
+from recala_cli.search_numbers import ranked_lines, totals_sentence
+
+SWITCHED_OFF = "Google Search Console isn't switched on for this company yet."
+#: Like `recala bing data`, these fail: there is a step for the person to take.
+_NEEDS_A_STEP = {
+    "not_connected": ("gsc_not_connected", "Google Search Console isn't connected for this company. Connect it: recala connect gsc"),
+    "connecting": ("gsc_not_connected", "Signed in to Google. Choose the property: recala connect gsc"),
+    "needs_reconnect": ("gsc_needs_reconnect", "Google access was lost. Reconnect: recala connect gsc"),
+}
+_NO_NUMBERS_YET = {
+    "backfilling": "{site}: first import running.",
+    "pending_review": "{site}: Recala is checking that this property is the company's. Numbers appear once that is done.",
+    "waiting_for_data": "{site}: connected, and Google has no search data for it in this period.",
+}
+
+
+@click.group()
+def gsc() -> None:
+    """Google Search Console: its search numbers."""
+
+
+def _this_period(block: dict[str, Any] | None) -> list[dict[str, Any]]:
+    """A key with no impressions in this period is absent from it, not a result of zero."""
+    rows = (block or {}).get("rows") or []
+    return [{"key": row["key"], **row["current"]} for row in rows if row["current"]["impressions"]]
+
+
+def _describe_performance(data: dict[str, Any]) -> str:
+    source = data.get("source") or {}
+    site = source.get("property")
+    totals = data.get("totals")
+    if not totals:
+        fallback = "{site}: no Search Console numbers stored for this period yet."
+        return _NO_NUMBERS_YET.get(source.get("state") or "", fallback).format(site=site)
+    queries = data.get("queries") or {}
+    period = (queries.get("window") or {}).get("current") or {}
+    lines = [f"{site}, {period.get('start')} to {period.get('end')}",
+             f"{totals_sentence(totals)}. Final data through {source.get('final_through')}."]
+    if source.get("stale_since"):
+        lines.append(f"Updates stopped on {source['stale_since']}.")
+    lines += ranked_lines("Top queries", _this_period(queries)) + ranked_lines("Top pages", _this_period(data.get("pages")))
+    hidden = (queries.get("anonymized_share") or {}).get("clicks")
+    if hidden:
+        lines.append(f"{hidden:.0%} of clicks come from searches Google does not name.")
+    return "\n".join(lines)
+
+
+@gsc.command("data")
+@common_options
+@command_runner(human=_describe_performance)
+@click.option("--days", type=click.IntRange(7, 90), default=28, show_default=True, help="How many days back to read.")
+def data(ctx: click.Context, org_flag: str | None, days: int) -> dict[str, Any]:
+    """The stored search numbers: totals, top queries and top pages."""
+    client = open_client(ctx, org_flag)
+    try:
+        answer: dict[str, Any] = client.call(GSC_PERFORMANCE, params={"window_days": days})
+    except CliError as error:
+        if error.exit_code == ExitCode.NOT_FOUND:
+            raise CliError(ExitCode.NOT_FOUND, "gsc_unavailable", SWITCHED_OFF, 404) from error
+        raise
+    step = _NEEDS_A_STEP.get((answer.get("source") or {}).get("state") or "")
+    if step:
+        raise CliError(ExitCode.CONFLICT, *step, 409)
+    return answer