← ClaudeAtlas

post-connection-implement-relinkinglisted

Implement relinking as a first-class in-product flow and surface detailed, actionable error messages that clarify who must act and how. Use as Step 4 of post-connection implementation to eliminate integration support tickets.
merge-api/merge-unified-skills · ★ 0 · AI & Automation · score 71
Install: claude install-skill merge-api/merge-unified-skills
# Implementing Relinking and Detailed Error Messaging ## Purpose Credentials expire, permissions get revoked, and admins change — relinking lets end users re-authenticate without contacting support. Detailed error messaging (rather than "something went wrong") tells users exactly what failed and who needs to fix it. ## Prerequisites - `post-connection-build-settings-page` complete - `/api/merge/relink-integration` endpoint working --- ## Before Proceeding Tell the user: "Implementing relinking requires storing error state on the `linked_accounts` table (an `error_category` column and optionally `error_detail`). I'll generate a migration for this. Ready to proceed?" Wait for confirmation before continuing. ## Detecting that a relink is needed There is no `relink_needed` webhook. The dashboard's event list shows `LinkedAccount.status_changed`, but it has no emitter and never fires — do not build detection on it. Three signals that do work: 1. **`Issue.new` webhook** — fires when Merge opens an issue on the account (expired credentials, missing permissions, provider outage). Pair with `Issue.resolved` to clear your banner. 2. **Poll `GET /issues?linked_account_id={id}&status=ONGOING`** — the reliable backstop, and the only way to get the error detail you need for the message copy in Part 2. 3. **`status` on `GET /account-details`** — `RELINK_NEEDED` is the account-level signal, but it lags the underlying issue. Use 1 for latency and 2 for correctness. An account can