fruxon 2.0.1__tar.gz → 2.0.2__tar.gz

{fruxon-2.0.1 → fruxon-2.0.2}/HISTORY.md

@@ -1,5 +1,82 @@
 # History
 
+## Unreleased — `fruxon messages list --reason EMAIL_THREAD_UNAVAILABLE`
+
+- `--reason` takes the server's new `EMAIL_THREAD_UNAVAILABLE` (fruxon-backend
+  #1494): an email thread's pinned conversation could not take the message (its
+  topic is missing, abandoned or mismatched, or its session belongs to another
+  thread), so it was withheld, the Gmail thread labelled `Fruxon/Needs human`,
+  and it is never replayed. It was refused as a typo before reaching the server.
+  A server without it answers 400 for it.
+
+## Unreleased — a link to fill in an LLM provider's API key
+
+- **`fruxon llm-providers connect <provider>`** creates a config for an LLM
+  provider and prints a credential link. A human opens it, signs in to Fruxon
+  and types the API key (Bedrock's access key pair, Vertex's service account
+  key); the page tests it with the provider and publishes the config, which an
+  agent pins as `provider.tenantConfigId`. So an agent building an agent through
+  the CLI hands the user a link instead of asking for the key, and never sees
+  it. `--config <id>` fills an existing config instead; `--name` and
+  `--param name=value` (a non-secret setting such as `region`; required ones
+  are checked, and a secret is refused, before anything is created) shape the
+  new one. A key the provider turns down saves nothing and five lock the link;
+  one it could not check is saved with a warning. The link opens only for a
+  workspace member whose role may set up model providers (`llm_providers:write`,
+  which the Developer preset carries); `--no-sign-in` mints one whoever holds it
+  can fill (Admin or Owner). `--for`, `--note` and `--expires-in-hours` go on
+  the link. A config the command created is deleted again when no link could be
+  minted for it. A provider sharing another's credential is pointed at its
+  owner.
+- **`fruxon llm-providers link-status <provider> <config> <request>`** says
+  where that link stands — `OPEN`, `FILLED`, `REFUSED`, `EXPIRED`, `LOCKED` or
+  `WITHDRAWN` — and `--wait` waits until it is filled or stops working. Exits 0
+  for open or filled, 13 once it stopped working, 14 when `--wait` runs out.
+- Client methods `create_llm_provider_config`, `delete_llm_provider_config`,
+  `create_llm_credential_link` and `get_llm_credential_link`.
+
+## Unreleased — a link to fill in an integration's credentials
+
+- **`fruxon integrations connect <integration>`** creates a config for an
+  integration that takes an API key, a bearer token or a username and password,
+  and prints a credential link. A human opens it, signs in to Fruxon and types
+  the credential; the page tests it against the service and publishes the
+  config. So an agent building an agent through the CLI hands the user a link
+  instead of asking for the secret, and never sees it. `--config <id>` fills an
+  existing config instead; `--name`, `--auth-method` (when the integration
+  declares several methods a link can fill) and `--param name=value` (a
+  connection setting such as a subdomain; required ones are checked before
+  anything is created) shape the new one. The link opens only for a workspace
+  member whose role may set up integrations; `--no-sign-in` mints one whoever
+  holds it can fill. `--for`, `--note` and `--expires-in-hours` (1–720, default
+  168) go on the link. A config the command created is deleted again when no
+  link could be minted for it. OAuth integrations are pointed at
+  `integrations authorize`. Needs `integrations:write`, which the default
+  login preset carries (fruxon-backend #1487); a `--no-sign-in` link also needs
+  `workspace:write` (Admin or Owner).
+- Client methods `create_integration_config`, `delete_integration_config` and
+  `create_credential_link`.
+
+## Unreleased — `fruxon messages list --reason` takes every withhold reason
+
+- `--reason` accepted only `HUMAN_OWNED_CONVERSATION` and `ADMISSION_REFUSED`, so
+  `--reason OVER_BUDGET` and the other email-channel reasons were refused as typos
+  before reaching the server. It now takes every server `InboundWithholdReason`:
+  `NOT_ADDRESSED`, the email channel's `AUTO_REPLY`, `BULK_OR_LIST`, `BOUNCE`,
+  `OWN_ADDRESS`, `NOT_FOR_RECIPIENT`, `UNVERIFIED_SENDER`, `OVER_BUDGET`,
+  `THREAD_HAS_ANOTHER_SENDER`, `DELIVERY_DEFERRED_TOO_LONG`, and the new
+  `DRAFT_EDITED` (a customer wrote while a person was editing the agent's Gmail
+  draft; fruxon-backend #1488). A server without `DRAFT_EDITED` answers 400 for it.
+
+## Unreleased — a quality check that could not run is no failed reply
+
+- `AgentJudgeActivity.pass_rate` is `passed / (passed + failed)`, as the server
+  now computes it (fruxon-backend #1482). A check that could not run (a model
+  error or a timeout) gave no verdict: it is counted in `errors` only, where it
+  used to count against the rate. A log-only agent whose checks errored gets
+  `None`, not 0, so the `fruxon dash` Quality check tile shows its average score.
+  The docstring said "errors included"; it now says what the field holds.
+
 ## Unreleased — `o` in `fruxon dash` opens the same page in the web app
 
 - `o` opens the web app on the exact tab or record behind what the console

{fruxon-2.0.1 → fruxon-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fruxon
-Version: 2.0.1
+Version: 2.0.2
 Summary: The Fruxon SDK is a lightweight Python client for integrating with the Fruxon platform.
 Project-URL: bugs, https://github.com/fruxon-ai/fruxon-sdk/issues
 Project-URL: changelog, https://github.com/fruxon-ai/fruxon-sdk/blob/main/HISTORY.md
@@ -143,11 +143,13 @@ Integrations + tools:
 | `fruxon integrations list/get/create/update/verify/open` | Manage external integrations — the connections agents draw tools from. `create`/`update`/`verify` take a `--file` JSON body; `open` opens the dashboard. |
 | `fruxon integrations configs list/get/update/publish` | The per-integration auth/config records. `update --file` patches a config's draft (only the fields sent; `{"egressCountry": ""}` clears an egress pin) and prints it with secrets masked; `publish` makes the draft the revision tool calls resolve, asks first (`--yes` in agent mode), and prints the new revision's `id` and `version`, never the credentials. |
 | `fruxon integrations authorize <integration>` | Mint an application-level OAuth authorization URL to **connect** an integration — auto-detects its OAuth2 method (`--auth-method` to pick, `--scope`/`--config-param` to tune). OAuth needs a browser consent step, so the CLI hands you the link; a human clicks it, and the connection is saved as a tenant config a slot can pin. |
+| `fruxon integrations connect <integration>` | Create a config for an API-key, token or password integration (Stripe, most REST APIs) and print a **credential link**: a human opens it, signs in to Fruxon, types the credential, and the page tests it and publishes the config. The secret never passes through the terminal or an agent driving the CLI. `--config <id>` fills an existing config, `--param name=value` sets a connection setting, `--no-sign-in` mints a link anyone holding it can fill (for a client without a Fruxon login), `--expires-in-hours` 1–720. Needs `integrations:write` (the default login preset); `--no-sign-in` also needs `workspace:write` (Admin or Owner). |
 | `fruxon integrations triggers <integration>` | List the event types an integration can fire an agent on — each descriptor's `id` is the `eventType` a trigger listens for, plus the `payloadFields` (dotted paths) a binding's `parameterMappings` can read. Discovery for wiring an inbound-event trigger without guessing. |
 | `fruxon integrations mcp …` | Inspect and enable the MCP server for an integration. |
 | `fruxon tools list/get/create/update/delete/run` | Manage the tools inside an integration. Integration-scoped. `get` and `run` select the tool with `--tool`; `run` executes it outside any agent — real credentials, real result — with `-p key=value`, and `-c` naming the config that supplies credentials. The tenant list API hides internal `knowledge_base` / `assets` tools; `tools list` recovers them by ID and lists them like any other (`--no-include-internal` for the raw server answer). |
 | `fruxon keys list/mint/revoke/delete/history/scopes` | Audit and revoke scoped tokens. Minting opens the dashboard so the secret never enters the CLI process. |
 | `fruxon llm-providers list/get/models` | Browse LLM providers and models supported at the tenant level. |
+| `fruxon llm-providers connect <provider>` / `link-status` | Create a config for an LLM provider and print a **credential link**: a human opens it, signs in to Fruxon, types the API key (or access keys, or service account key), and the page tests it with the provider and publishes the config an agent pins as `provider.tenantConfigId`. The key never passes through the terminal or an agent driving the CLI. `--config <id>` fills an existing config, `--param name=value` sets a non-secret setting such as Bedrock's `region`, `--no-sign-in` mints a link anyone holding it can fill (Admin or Owner). `link-status <provider> <config> <request> [--wait]` says when it was filled. |
 | `fruxon llm-providers configs list/get/test/publish` | The workspace's saved LLM credentials — the `provider.tenantConfigId` an agent pins. `get` shows the draft (secrets masked), the published revision and last known health. `test` probes the draft on every provider surface that shares the credential (or just one, given that surface's provider id), one line per failing surface, exit 12 on failure (`llm_providers:test`). `publish` ships the draft as a new revision that every agent on the config switches to — it confirms, needs `--yes` in agent mode, and does not wait on a passing test (`llm_providers:write`). |
 | `fruxon assets create/list/get/wait/operations/delete` | Manage knowledge-base (RAG) assets an agent can query — upload local files, wait for async ingestion, inspect operations, and use the ids for `assetConfig.assetIds`. `delete` confirms + refuses without `--yes` in agent mode. |
 | `fruxon knowledge-bases list/get/create/update/publish/archive/delete` | The authored, reviewable corpus behind a `manual_knowledge` asset — **not** the asset itself, which is what gets searched (`get` prints the asset id as `backingAssetId`). **`publish` is the step that makes any of it findable**: only `PUBLISHED` documents travel in a snapshot, and only publishing the *base* moves one, so a base full of finished articles answers nothing until it runs. It returns on *acceptance*, not searchability — RAG ingests afterwards, so a pending publish state is normal. `list` hides archived bases, which keep answering for agents already attached to them; `delete` is refused while an agent revision still attaches one, and `archive` is the reversible path. |

{fruxon-2.0.1 → fruxon-2.0.2}/README.md

@@ -108,11 +108,13 @@ Integrations + tools:
 | `fruxon integrations list/get/create/update/verify/open` | Manage external integrations — the connections agents draw tools from. `create`/`update`/`verify` take a `--file` JSON body; `open` opens the dashboard. |
 | `fruxon integrations configs list/get/update/publish` | The per-integration auth/config records. `update --file` patches a config's draft (only the fields sent; `{"egressCountry": ""}` clears an egress pin) and prints it with secrets masked; `publish` makes the draft the revision tool calls resolve, asks first (`--yes` in agent mode), and prints the new revision's `id` and `version`, never the credentials. |
 | `fruxon integrations authorize <integration>` | Mint an application-level OAuth authorization URL to **connect** an integration — auto-detects its OAuth2 method (`--auth-method` to pick, `--scope`/`--config-param` to tune). OAuth needs a browser consent step, so the CLI hands you the link; a human clicks it, and the connection is saved as a tenant config a slot can pin. |
+| `fruxon integrations connect <integration>` | Create a config for an API-key, token or password integration (Stripe, most REST APIs) and print a **credential link**: a human opens it, signs in to Fruxon, types the credential, and the page tests it and publishes the config. The secret never passes through the terminal or an agent driving the CLI. `--config <id>` fills an existing config, `--param name=value` sets a connection setting, `--no-sign-in` mints a link anyone holding it can fill (for a client without a Fruxon login), `--expires-in-hours` 1–720. Needs `integrations:write` (the default login preset); `--no-sign-in` also needs `workspace:write` (Admin or Owner). |
 | `fruxon integrations triggers <integration>` | List the event types an integration can fire an agent on — each descriptor's `id` is the `eventType` a trigger listens for, plus the `payloadFields` (dotted paths) a binding's `parameterMappings` can read. Discovery for wiring an inbound-event trigger without guessing. |
 | `fruxon integrations mcp …` | Inspect and enable the MCP server for an integration. |
 | `fruxon tools list/get/create/update/delete/run` | Manage the tools inside an integration. Integration-scoped. `get` and `run` select the tool with `--tool`; `run` executes it outside any agent — real credentials, real result — with `-p key=value`, and `-c` naming the config that supplies credentials. The tenant list API hides internal `knowledge_base` / `assets` tools; `tools list` recovers them by ID and lists them like any other (`--no-include-internal` for the raw server answer). |
 | `fruxon keys list/mint/revoke/delete/history/scopes` | Audit and revoke scoped tokens. Minting opens the dashboard so the secret never enters the CLI process. |
 | `fruxon llm-providers list/get/models` | Browse LLM providers and models supported at the tenant level. |
+| `fruxon llm-providers connect <provider>` / `link-status` | Create a config for an LLM provider and print a **credential link**: a human opens it, signs in to Fruxon, types the API key (or access keys, or service account key), and the page tests it with the provider and publishes the config an agent pins as `provider.tenantConfigId`. The key never passes through the terminal or an agent driving the CLI. `--config <id>` fills an existing config, `--param name=value` sets a non-secret setting such as Bedrock's `region`, `--no-sign-in` mints a link anyone holding it can fill (Admin or Owner). `link-status <provider> <config> <request> [--wait]` says when it was filled. |
 | `fruxon llm-providers configs list/get/test/publish` | The workspace's saved LLM credentials — the `provider.tenantConfigId` an agent pins. `get` shows the draft (secrets masked), the published revision and last known health. `test` probes the draft on every provider surface that shares the credential (or just one, given that surface's provider id), one line per failing surface, exit 12 on failure (`llm_providers:test`). `publish` ships the draft as a new revision that every agent on the config switches to — it confirms, needs `--yes` in agent mode, and does not wait on a passing test (`llm_providers:write`). |
 | `fruxon assets create/list/get/wait/operations/delete` | Manage knowledge-base (RAG) assets an agent can query — upload local files, wait for async ingestion, inspect operations, and use the ids for `assetConfig.assetIds`. `delete` confirms + refuses without `--yes` in agent mode. |
 | `fruxon knowledge-bases list/get/create/update/publish/archive/delete` | The authored, reviewable corpus behind a `manual_knowledge` asset — **not** the asset itself, which is what gets searched (`get` prints the asset id as `backingAssetId`). **`publish` is the step that makes any of it findable**: only `PUBLISHED` documents travel in a snapshot, and only publishing the *base* moves one, so a base full of finished articles answers nothing until it runs. It returns on *acceptance*, not searchability — RAG ingests afterwards, so a pending publish state is normal. `list` hides archived bases, which keep answering for agents already attached to them; `delete` is refused while an agent revision still attaches one, and `archive` is the reversible path. |

{fruxon-2.0.1 → fruxon-2.0.2}/src/fruxon/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.0.1'
-__version_tuple__ = version_tuple = (2, 0, 1)
+__version__ = version = '2.0.2'
+__version_tuple__ = version_tuple = (2, 0, 2)
 
 __commit_id__ = commit_id = None

{fruxon-2.0.1 → fruxon-2.0.2}/src/fruxon/cli/examples.py

@@ -696,6 +696,10 @@ _EXAMPLES: dict[str, list[tuple[str, str]]] = {
             "fruxon integrations authorize google_sheets",
             "Mint an OAuth connect link to hand a human (auto-detects the method)",
         ),
+        (
+            "fruxon integrations connect stripe",
+            "Create a config and mint a link a human fills its API key in; the secret never reaches the CLI",
+        ),
         ("fruxon integrations triggers gmail", "Discover the event types + payload paths a trigger can wire to"),
         ("fruxon integrations create -f config.json", "Wire up a new external service"),
         ("fruxon integrations open my-integration", "Open the dashboard config page"),
@@ -731,6 +735,14 @@ _EXAMPLES: dict[str, list[tuple[str, str]]] = {
         ("fruxon llm-providers configs test vertex_ai 4950…", "Probe every surface sharing the credential"),
         ("fruxon llm-providers configs test vertex_ai_maas 4950…", "…or just that one surface"),
         ("fruxon llm-providers configs publish vertex_ai 4950…", "Ship the draft; every agent on it switches"),
+        (
+            "fruxon llm-providers connect openai",
+            "Create a config and mint a link a human fills its API key in; the key never reaches the CLI",
+        ),
+        (
+            "fruxon llm-providers link-status openai <config-id> <request-id> --wait",
+            "Wait until the human filled the link (or it stopped working)",
+        ),
     ],
     "keys": [
         ("fruxon keys list", "Audit existing API keys"),

{fruxon-2.0.1 → fruxon-2.0.2}/src/fruxon/cli/integrations.py

@@ -26,7 +26,7 @@ import typer
 from rich.markup import escape
 
 from fruxon.cli import app
-from fruxon.cli._shared import build_client, confirm_or_die, load_json_body, print_connect_nudge
+from fruxon.cli._shared import build_client, confirm_or_die, format_ts, load_json_body, print_connect_nudge
 from fruxon.exceptions import FruxonError
 from fruxon.fruxon import Integration
 from fruxon.ui import (
@@ -676,6 +676,303 @@ def integrations_authorize(
     )
 
 
+# ─────────────────────────────────────────────────────────────────────────────
+# connect — a credential link for an API key, token or password
+# ─────────────────────────────────────────────────────────────────────────────
+
+# What a credential link can take: the page renders a form for these, never an OAuth consent.
+_LINKABLE_CREDENTIAL_TYPES = {"API_KEY", "BEARER_TOKEN", "BASIC_AUTH"}
+
+_MAX_LINK_HOURS = 720
+
+
+@integrations_app.command("connect")
+def integrations_connect(
+    integration: Annotated[str, typer.Argument(help="Integration to connect (e.g. stripe).")],
+    config_id: Annotated[
+        str | None,
+        typer.Option("--config", help="Fill this existing config's credentials instead of creating a config."),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option("--name", help="Display name of the new config. Defaults to the integration's name."),
+    ] = None,
+    auth_method: Annotated[
+        str | None,
+        typer.Option(
+            "--auth-method",
+            help="The auth-metadata id the new config uses. Omit when the integration declares one it can link.",
+        ),
+    ] = None,
+    param: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--param",
+            help="key=value non-secret connection setting for the new config (repeatable, e.g. subdomain=acme).",
+        ),
+    ] = None,
+    sign_in: Annotated[
+        bool,
+        typer.Option(
+            "--sign-in/--no-sign-in",
+            help=(
+                "Open only for a signed-in workspace member who may set up integrations (default). "
+                "--no-sign-in: whoever holds the link can fill it."
+            ),
+        ),
+    ] = True,
+    for_email: Annotated[
+        str | None,
+        typer.Option("--for", help="Who the link is for, shown in the config's open-links list. Never checked."),
+    ] = None,
+    note: Annotated[str | None, typer.Option("--note", help="A note shown above the form.")] = None,
+    expires_in_hours: Annotated[
+        int | None,
+        typer.Option(
+            "--expires-in-hours",
+            min=1,
+            max=_MAX_LINK_HOURS,
+            help=f"How long the link works: 1 to {_MAX_LINK_HOURS} hours. Default 168 (7 days).",
+        ),
+    ] = None,
+    workspace: Annotated[str | None, typer.Option("--workspace", help="Workspace identifier override.")] = None,
+    base_url: Annotated[str | None, typer.Option("--base-url", help="API base URL override.")] = None,
+    output: Annotated[
+        str | None,
+        typer.Option("--output", "-o", help="Output format: text (default for humans), json (default in agent mode)."),
+    ] = None,
+):
+    """Mint a link a human opens to fill in an integration's credentials.
+
+    For an API key, a bearer token or a username and password. Creates a
+    config for the integration (or takes [bold]--config <id>[/bold]) and prints
+    a link to a Fruxon page. Whoever opens it types the credential there; the
+    page tests it against the service and publishes the config, which a slot's
+    `tenantConfigId` can then pin. The values never pass through this
+    terminal, nor through an AI agent driving the CLI: hand the link to the
+    human, never ask them for the secret.
+
+    The link opens only for a member of this workspace signed in to Fruxon
+    whose role may set up integrations, so holding it proves nothing and it is
+    safe to show in a chat. [bold]--no-sign-in[/bold] mints one that whoever
+    holds it can fill, for a client or partner without a Fruxon login: send
+    that one privately. A new link for a config replaces the one sent before.
+
+    OAuth integrations connect through [bold]fruxon integrations authorize[/bold]
+    instead. Needs the `integrations:write` scope (the default login preset
+    has it); a [bold]--no-sign-in[/bold] link also needs `workspace:write`, which
+    only Admin and Owner hold.
+
+    Examples:
+        fruxon integrations connect stripe
+        fruxon integrations connect zendesk --param subdomain=acme
+        fruxon integrations connect stripe --config <config-id>
+        fruxon integrations connect stripe --no-sign-in --for cfo@client.com --expires-in-hours 48
+    """
+    output = _resolve_write_output(output)
+    parameters = _parse_key_values(param, flag="--param", example="subdomain=acme")
+    if config_id is not None and (name is not None or auth_method is not None or parameters):
+        fail(
+            "--name, --auth-method and --param set up a new config; --config fills one that exists.",
+            hint="Drop [bold]--config[/bold] to create a config, or drop the others to fill the existing one.",
+            code=EXIT_VALIDATION,
+        )
+
+    client = build_client(workspace, base_url)
+    created = config_id is None
+    if config_id is None:
+        config_id = _create_linkable_config(client, integration, name, auth_method, parameters)
+
+    try:
+        link = client.create_credential_link(
+            integration,
+            config_id,
+            require_sign_in=sign_in,
+            intended_for_email=for_email,
+            note=note,
+            ttl_hours=expires_in_hours,
+        )
+    except FruxonError as e:
+        leftover = _delete_new_config(client, integration, config_id) if created else None
+        fail_from_api_error(e, hint=_hint_for_link_error(e, integration, leftover))
+
+    url = link.get("url") or ""
+    if output == "json":
+        record = {
+            "integration": integration,
+            "configId": config_id,
+            "createdConfig": created,
+            "requestId": link.get("id"),
+            "url": url,
+            "mode": link.get("mode"),
+            "expiresAt": link.get("expiresAt"),
+        }
+        print(json.dumps(record, indent=2))
+        return
+
+    if stderr.is_terminal:
+        print_banner(subtitle=f"connect · {integration}")
+    stderr.print()
+    what = f"a new config [dim]{config_id}[/dim]" if created else f"config [dim]{config_id}[/dim]"
+    say_ok(f"Open this link to fill in the [bold]{escape(integration)}[/bold] credentials for {what}:")
+    stderr.print()
+    print(url)
+    stderr.print()
+    who = (
+        "Opens for a workspace member signed in to Fruxon who may set up integrations."
+        if str(link.get("mode") or "").upper() == "SIGN_IN"
+        else "Whoever holds it can fill it in: send it privately."
+    )
+    stderr.print(f"     [dim]{who} Works until {format_ts(link.get('expiresAt'))} UTC.[/dim]")
+    stderr.print(
+        "     [dim]Once filled, the config is published: pin it with a slot's tenantConfigId "
+        f"(fruxon integrations configs get {integration} {config_id}).[/dim]"
+    )
+
+
+def _create_linkable_config(
+    client, integration: str, name: str | None, auth_method: str | None, parameters: dict[str, str]
+) -> str:
+    """Create the unpublished config a credential link fills; return its id. Exits on anything it can't link."""
+    try:
+        meta = client.get_integration(integration)
+    except FruxonError as e:
+        fail_from_api_error(e, hint=_hint_for_error(e))
+
+    config_metadata = meta.config_metadata if isinstance(meta.config_metadata, dict) else {}
+    methods = [m for m in config_metadata.get("authMetadata") or [] if isinstance(m, dict)]
+    method = _linkable_method(integration, methods, auth_method)
+    _check_connection_parameters(integration, config_metadata.get("parametersMetadata"), parameters)
+
+    body = {
+        "displayName": name or meta.display_name or integration,
+        "parameters": parameters,
+        "auth": {"integrationAuthMetadataId": method["id"], "level": "APPLICATION", "parameters": {}},
+    }
+    try:
+        config = client.create_integration_config(integration, body)
+    except FruxonError as e:
+        fail_from_api_error(e, hint=_hint_for_config_error(e, integration))
+    return str(config.get("id"))
+
+
+def _linkable_method(integration: str, methods: list[dict], auth_method: str | None) -> dict:
+    """The application-level API key / token / password method the new config uses, or exit saying why not."""
+
+    def credential_type(m: dict) -> str:
+        # A custom method names the standard shape its credential is entered in, as the backend's
+        # EffectiveCredentialType does (e.g. an email + password it exchanges for a session token).
+        return str(m.get("userCredentialAuthType") or m.get("type") or "").upper()
+
+    def application_level(m: dict) -> bool:
+        return "APPLICATION" in {str(level).upper() for level in (m.get("supportedLevels") or [])}
+
+    def oauth_hint() -> str | None:
+        if any(credential_type(m) == "O_AUTH2" and application_level(m) for m in methods):
+            return f"It signs in through OAuth: run [bold]fruxon integrations authorize {integration}[/bold]."
+        return None
+
+    if auth_method is not None:
+        chosen = next((m for m in methods if str(m.get("id")) == auth_method), None)
+        if chosen is None:
+            declared = ", ".join(str(m.get("id")) for m in methods) or "(none)"
+            fail(
+                f"[bold]{integration}[/bold] declares no auth method [bold]{auth_method}[/bold].",
+                hint=f"Declared methods: {declared}.",
+                code=EXIT_VALIDATION,
+            )
+        if credential_type(chosen) not in _LINKABLE_CREDENTIAL_TYPES or not application_level(chosen):
+            fail(
+                f"Auth method [bold]{auth_method}[/bold] is not an API key, token or password the workspace shares, "
+                "so a link can't fill it.",
+                hint=oauth_hint() or "Connect it from the dashboard.",
+                code=EXIT_VALIDATION,
+            )
+        return chosen
+
+    linkable = [m for m in methods if credential_type(m) in _LINKABLE_CREDENTIAL_TYPES and application_level(m)]
+    if not linkable:
+        fail(
+            f"[bold]{integration}[/bold] takes no API key, token or password a link can fill.",
+            hint=oauth_hint() or "Connect it from the dashboard.",
+            code=EXIT_VALIDATION,
+        )
+    if len(linkable) > 1:
+        listed = ", ".join(f"{m.get('id')} ({m.get('displayName') or m.get('type')})" for m in linkable)
+        fail(
+            f"[bold]{integration}[/bold] declares more than one method a link can fill — pick one with --auth-method.",
+            hint=f"Methods: {listed}.",
+            code=EXIT_VALIDATION,
+        )
+    return linkable[0]
+
+
+def _check_connection_parameters(integration: str, declared: object, parameters: dict[str, str]) -> None:
+    """Refuse --param values the config would not take, and a required setting left out, before creating anything."""
+    fields = {str(p.get("name")): p for p in declared or [] if isinstance(p, dict) and p.get("name")}
+    unknown = sorted(set(parameters) - set(fields))
+    if unknown:
+        fail(
+            f"[bold]{integration}[/bold] has no connection setting {', '.join(unknown)}.",
+            hint=f"Its settings: {', '.join(sorted(fields)) or '(none)'}.",
+            code=EXIT_VALIDATION,
+        )
+    secret = sorted(n for n in parameters if fields[n].get("secret"))
+    if secret:
+        fail(
+            f"{', '.join(secret)} is secret, so it doesn't go on the command line.",
+            hint="Connect this integration from the dashboard.",
+            code=EXIT_VALIDATION,
+        )
+    missing = sorted(
+        n for n, p in fields.items() if p.get("required") and p.get("defaultValue") is None and n not in parameters
+    )
+    if missing:
+        fail(
+            f"[bold]{integration}[/bold] needs {', '.join(missing)} to connect.",
+            hint="Pass each with [bold]--param name=value[/bold].",
+            code=EXIT_VALIDATION,
+        )
+
+
+def _delete_new_config(client, integration: str, config_id: str) -> str | None:
+    """Delete the config this command created when no link could be minted for it; its id when it is still there."""
+    try:
+        client.delete_integration_config(integration, config_id)
+    except FruxonError:
+        return config_id
+    return None
+
+
+def _hint_for_link_error(error: FruxonError, integration: str, leftover: str | None) -> str | None:
+    from fruxon.exceptions import FruxonAPIError
+
+    hint = _hint_for_config_error(error, integration)
+    if isinstance(error, FruxonAPIError) and error.error_code == "not_linkable":
+        hint = (
+            "Connect it from the dashboard, or with "
+            f"[bold]fruxon integrations authorize {integration}[/bold] for OAuth."
+        )
+    if leftover is not None:
+        cleanup = f"The config it created, {leftover}, is still there: delete it from the dashboard."
+        hint = f"{hint} {cleanup}" if hint else cleanup
+    return hint
+
+
+def _parse_key_values(pairs: list[str] | None, *, flag: str, example: str) -> dict[str, str]:
+    parsed: dict[str, str] = {}
+    for pair in pairs or []:
+        key, sep, value = pair.partition("=")
+        if not sep or not key:
+            fail(
+                f"Invalid {flag} [bold]{escape(pair)}[/bold] — expected key=value.",
+                hint=f"e.g. {flag} {example}",
+                code=EXIT_VALIDATION,
+            )
+        parsed[key] = value
+    return parsed
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # configs — tenant-level integration configs
 # ─────────────────────────────────────────────────────────────────────────────