#FE: Integrations (from backend Phase 5)

Frontend spec for backend Phase 5: Integrations — requirements complete 2026-10-03; B5.1 cloud-provider account list built by Pair 1 (2026-10-10). B5.2 Connect, B5.3 Edit and B5.4 on-demand Check are built on Pair1; B5.5 Disconnect endpoint partially built, server-usage guard/warning pending Phase8; remaining Git/storage activity pending; Git/storage features depend on Servers. V8 requirement It covers three things that users think of as "connected accounts".

i18n namespaces: integrations.providers.*, integrations.git.*, integrations.storage.*, integrations.create.*, integrations.errors.*. Permissions: organization-level for the provider screens; the OSS git and storage permissions for the per-server parts (see Roles & permissions).

#A. Cloud server providers (Central) — /integrations

Update 2026-10-27 (Pair 2 review fixes): a cloud account still used by a server can't be disconnected — the API answers 409 cloud_account_in_use. Show "This cloud account is used by a server and can't be disconnected." and keep the row. A personal API token can't change cloud accounts.

#Integrations — Cloud-provider list (B5.1 built contract)

Main sidebar → Integrations → cloud-provider list (/integrations). Namespaces: integrations.providers.*, integrations.errors.*, common.*. Requires integration-view; Owner/Admin have access, custom roles need the grant. Active unverified users may list; banned accounts cannot.

API: GET /api/v1/organizations/{organization}/cloud-provider-accounts with login access token. Query: page (min 1), per_page (1–50, default 10), search (name substring, max 100), provider, status. All filters combine. %, _, ! and backslashes are literal search characters, not wildcards.

• Providers: vultr, digitalocean, linode, hetzner, lightsail.
• Statuses: connected, needs_new_token. Use returned provider_label and status_label (translated via Accept-Language, English fallback).
• Rows: id, name, provider, provider_label, status, status_label, created_at, updated_at; links and meta for pagination. Newest creation first, then ID.
• Pagination links preserve approved list filters only; do not append unrelated or credential-like query values.
• No token fields, masked secret hints, server IDs or “Used by N servers” data in this response. Do not invent those values. Listing does not revalidate connectivity: display the saved status, not “checked just now”.
• Connect and Edit use published B5.2/B5.3 APIs on Pair1; Disconnect endpoint now built partially; server-usage guard/warning not built. “Needs new token” can now offer Edit to integration-manage users; a successful replacement restores Connected. B5.4 now offers an explicit Check; automatic/background detection remains unimplemented.
• Loading, accounts shown, no accounts, no matching results (Clear filters), request error with Retry, permission refused and organization missing. On organization change clear stale rows, filters/page and load only the new context.
• Empty state may offer Connect to integration-manage users on Pair1, and Pair2 now reports pulling this code through cf36220; distinguish no accounts from no matches. 401 → Login; 403 → access/banned refusal; 404 → refresh organization context; 422 → field/query validation; 429 → back off (shared 120/min/user limit).
• Done when permitted/denied and nonmember cases work; search treats special characters literally; provider/status filters and paging combine correctly; rows/counts never leak another organization's accounts; no secret/usage values are fabricated; Disconnect is presented only with its explicit partial-readiness restriction; never claim unused-server safety.

Source: Pair 1 API reference §44. Backend reports 557 Pest tests and quality/migration/isolation checks passed; this doc sync has not rerun them. Pair2 now reports B5.1–B5.5 pulled through cf36220; this supersedes the earlier doc-only report. No new product conflict; missing usage counts are a contract gap, not permission to build an invented endpoint.

#Integrations — Connect cloud provider (B5.2)

Main sidebar → Integrations → Connect MODAL (proposed UI), requires manage on organization.integrations.cloud-providers. POST /api/v1/organizations/{organization}/cloud-provider-accounts on Pair1, reference§45. Name required (max100); provider one of the five list options. For Vultr/DigitalOcean/Linode/Hetzner send credentials.token; Lightsail sends credentials.access_key + credentials.secret_key, not temporary STS/session tokens. No OAuth, custom endpoint, extra credential keys or client status/organization ID. Secrets must never enter URLs, persistence or logs.

Submitting → validating →201 metadata-only success → close and refresh list; connection activity now appears in account/organization history. Rejected credentials/missing verification permission →422 cloud_provider_credentials_rejected; keep modal and explain correction. Timeout/outage/rate-limit/invalid provider response →503 cloud_provider_unavailable; say temporary failure, not revoked token. Neither failure saves an account. Permission loss or organization deletion while saving → refuse and refresh context.429 → respect Retry-After (10/min/user across organizations).401→Login;403→manage/banned refusal;404→organization unavailable.

DigitalOcean needs account:read; Linode view_profile; Hetzner token is project-scoped. Successful read-only verification does not prove later server-create permissions. Multiple accounts/same names allowed; POST is not idempotent, so after a lost response refresh before retrying, avoiding duplicates. States: form, submitting, validation error, transient failure, permission/context changed, success. Edit is now built; on-demand Check is built, but automatic/background detection not built; Disconnect endpoint is partial until its usage guard lands.

Done when five field sets, manage/view/outsider cases, rejected/transient failures, lost-response refresh and secret boundaries are tested. Backend success tests used mocks; no genuine provider success has been verified. Pair2 reports this code pulled through cf36220.

#Integrations — Edit cloud-provider account (B5.3 built)

Proposed UI: /integrations → own organization account row → Edit MODAL. Manage on organization.integrations.cloud-providers (was organization.integrations.cloud-providers, renamed 2026-10-17); Owner/Admin/custom manage permitted, view-only refused. Unverified active users allowed. Pair1 API reference§46: PATCH /api/v1/organizations/{organization}/cloud-provider-accounts/{cloudProviderAccount}. Namespaces integrations.providers.*, integrations.errors.*, common.*.

• Prefill name; provider read-only. Credential fields empty, “Leave unchanged to keep saved credentials”. Do not submit empty fields, nulls or masked values. Provider/organization/status/ID/verification URL cannot be changed. At least name or complete credentials required; name nonempty max100.
• Rename only: omit credentials. No provider check and no status reset. Renaming a Needs new token row does not repair it. Same-name-only save is a no-op (no new time/history entry).
• Replace credentials: token for Vultr/DigitalOcean/Linode/Hetzner; complete access key+secret pair for Lightsail, never partial merge. Same strict field sets as Connect. Can combine replacement with rename. Validate new credentials →200 safe metadata, same account/provider/organization →close and refresh list. Success sets Connected; no secret returned.
• Replacement can repair unusable saved credentials without displaying them. Entering even the same token initiates verification/update; never compare against an exposed saved value.
• 422 rejected credentials / 503 temporary provider failure: retain the modal error and explain that the old name, saved credentials and status were not changed. If rename and credentials were submitted together, rename did not save separately. Do not mark the old token revoked because verification of a replacement timed out.
• 409 cloud_provider_account_changed: another edit won while verification ran. Show “This account changed. Reload it before saving again.” Reload from the list and ask the user to review; never auto-replay or overwrite. Do not expose internal conflict snapshots.
• 401→Login;403→permission/banned refusal;404→missing/deleted/wrong-organization account, refresh context;422 field errors;429 respect Retry-After. Connect+Edit+Check+Disconnect share10 attempts/min/user across organizations; never auto-retry PATCH.
• States: loading/current metadata, unchanged form, saving rename, verifying replacement, inline invalid fields, rejected credentials, temporary failure, changed-in-another-window, missing/denied and success.
• Completed edits appear in account/organization history as cloud_provider.updated; failed/conflicted/no-op saves add no activity. History never contains old/new keys. No undo endpoint: to restore former credentials, user must supply valid prior values again.
• Done when rename preserves status/secrets, Lightsail replacements require both keys, errors preserve old fields,409 forces reload/review, permission/scope loss is handled, successful lists/history update and no secret leaks. Backend reports736 tests/4252 assertions with quality checks; these are not rerun here. Provider success is still mocked, not verified with real credentials; Pair2 reports this code pulled through cf36220.

#Integrations — Check saved provider credentials (B5.4 built)

Proposed screen: /integrations account row → Check credentials, requires integration-manage (Owner/Admin/granted custom role), active login; unverified users allowed. Pair1 API reference§47: POST /api/v1/organizations/{organization}/cloud-provider-accounts/{cloudProviderAccount}/check, no body/query/input. Namespaces integrations.providers.*, integrations.errors.*, common.*.

1. User clicks Check → show Checking on that row; do not send new credentials, status, provider or organization fields. This checks saved credentials only; list refresh does not check them.
2. 200 Connected: display returned translated status, verification completed. Do not promise all future server-create permissions.
3. 200 Needs new token: check completed and credentials rejected or lacking verification permissions; display Needs new token + Edit. Do not treat200 as a generic green success or422 form error. Successful Edit verifies replacement credentials and restores Connected.
4. 503 cloud_provider_unavailable: temporary outage/timeout/rate-limit/invalid response; show safe explanation and Retry later. Saved status/fields remain unchanged; do not relabel as revoked.
5. 503 cloud_provider_credentials_unreadable: saved credentials unusable; show safe returned message + Edit. Do not print raw errors or saved secrets. Status stays unchanged; fresh verified credentials can repair it.
6. 409 cloud_provider_account_changed: another edit occurred; reload current row before offering a deliberate retry. Never apply the old check result to newly replaced credentials; no automatic POST retry.

Other errors:401→Login;403→banned/permission lost;404→deleted/missing/not-own-organization, refresh context;422 errors.input→client request invalid (remove supplied fields);429→respect Retry-After. Connect/Edit/Check/Disconnect share10 attempts/min/user across organizations. No chosen polling interval: there is no periodic Check, scheduler, automatic discovery or verification on list fetch.

States: idle, checking, connected result, needs-new-token result, temporary failure, saved-credentials unusable, conflict/reload, permission/account unavailable. Only actual status transitions update timestamps/history (cloud_provider.status_changed, safe from/to statuses and actor); unchanged status checks have no new history entry. Failed/unreadable/conflicted checks do not alter history or credentials.

Done when permitted/denied/scope/input cases work;200 both outcomes render distinctly;503 preserves status;unreadable offers Edit;409 cannot overwrite a newer token;no secrets escape;no automatic checks are claimed. Backend reports843 tests/4932 assertions and quality checks; doc sync has not rerun them. Provider successes remain mocked, genuine credential success unverified. Pair2 reports this code pulled through cf36220.

#Integrations — Disconnect provider account (B5.5 partial)

Proposed UI: organization /integrations account row → Disconnect CONFIRM; integration-manage only (Owner/Admin/granted custom role), active login, unverified users allowed. Namespace integrations.providers.*, integrations.errors.*, common.*. Pair1 API reference§48: DELETE /api/v1/organizations/{organization}/cloud-provider-accounts/{cloudProviderAccount}, no input. UI confirmation is a safeguard, not a backend typed-name/password field; never send these.

• Confirm names the account/provider and explains: removes this saved account/credentials from Central only; cloud-provider token stays valid, no upstream account/resource/server is deleted. Reconnect needs credentials again and gets a new account ID; no Undo.
• Submit→Disconnecting→200 translated result→remove row and refresh list. Returned data is a deleted metadata snapshot, even if its old status says Connected; do not reinsert it into the list.
• Other provider accounts and prior organization history remain. One safe cloud_provider.disconnected activity records actor/name/provider; credentials never appear. -401→Login;403→banned/current permission refusal;404→missing/deleted/nonmember/wrong organization or repeat removal, refresh and inform rather than repeated destructive retries;422 errors.input→bad client request, not a confirmation mismatch;429→respect Retry-After. All four mutations share10/min/user across organizations; no automatic DELETE replay.
• Cancel confirmation leaves account unchanged. On failure keep current row until refreshed; do not assume deletion. Older Edit/Check views must handle404 after disconnect rather than recreating the account or publishing old status.
• States: confirmation/cancel, removing, success/list, already removed/refreshed, denied, malformed request and retryable error. No secret display or provider verification request needed.
• Done when allowed/denied/scoped and stale dialogs work,200 snapshot removes row,repeat404 is clear,history preserved,other accounts unaffected and reconnect requirements explicit. Full readiness additionally requires the Phase8 usage blocker and server-name warning. Backend reports910 tests/5607 assertions and quality checks for endpoint only; no claim the missing guard was tested. Pair2 reports this endpoint pulled through cf36220; missing usage guard remains Phase8.

#B. Create a server on a cloud provider — wizard + live progress (moved to the Servers phase)

The backend's draft describes one flow (steps 1–7). The frontend part is the wizard and the progress screen.

Wizard fields (all values come from the API — never typed into the frontend): provider account · region · size · Ubuntu version (22.04 / 24.04 / 26.04 — settled by backend 8.7 on 2026-10-07; MongoDB is not available on 26.04, so MERN cannot use it) · stack (Nginx + PHP · Apache + PHP · Nginx + Node (MERN) · OpenLiteSpeed + PHP) · server name · optional SSH key · root password for Linode (same as V7). Review step before the final button.

Progress screen — the backend's statuses are the only states the frontend shows:

• Poll the server record while the status is Creating or Installing OSS; stop when it is Ready or Failed.
• Ready → go to the server page. Failed → show the reason the backend gives, plus Retry and Delete the server at the provider (the second is destructive: confirm dialog naming the server).
• Installing OSS can take a while (the backend's limit is around 30 minutes), so the screen must be safe to leave and come back to: show the same progress from the server record, and tell the user they can leave.
• The IP appears only after the provider reports it (step 4) — show "waiting for the IP" instead of an empty field.
• Two more things the backend parked with this flow: V7 servers on Ubuntu 20.04 can't run OSS (22.04+ only), and Hostinger servers come with Apache/MySQL pre-installed (V7 removed them first) — both belong to the Servers phase, not here.

#C. Git accounts & backup storage (stored on the servers)

Two ideas run through this whole section:

1. The account is the thing the user manages, and a server is just somewhere it is installed. So the list groups by account ("used on: Server 1, Server 2"), not by server.
2. Central keeps only a note — name, provider and which servers have it. No secret, ever. So the UI never offers "view token", and every action that needs the secret asks for it again.

#Not in this phase (kept as our record)

• Regions & sizes of a provider (read live when creating a server) → Servers phase (moved out 2026-10-03).
• Repos & branches (account → repository → branch pickers, read from the server's OSS) → Applications phase (moved out 2026-10-03). The dependent-dropdown spec moves with it.
• Creating a server on a cloud provider and the automatic OSS install → Servers phase (moved out on 2026-10-03).
• Connecting an existing / own server (paste the install command) → Servers phase.
• Server list, server details and server actions → Servers phase.

#Who can do it

Connect, edit, test and remove follow the organization roles from Phase 4 (by Pair 1) V8 requirement 2026-10-03. So every button on these screens is permission-driven: hide what the role can't do, and never show an action that will come back as "not allowed". The exact permission names are still unpublished — build the checks from the API's catalog.

#Existing users

• Vultr, Hetzner and AWS Lightsail accounts move from V7 as they are — they were already key-based. V8 requirement 2026-10-03
• DigitalOcean and Linode used a provider login in V7, so after the move the user pastes an API token once. This answers D-29: those accounts arrive needing a token, which is exactly the "Needs new token" state (5.4) — so the first login must show them clearly, with Edit, and explain why in one line.
• V7's Git and Google Drive connections used one-click login; in V8 they become a pasted token / service account stored in OSS — accepted (Q9, 2026-10-03). How they move is decided later, with the migration phase (Q10), so the screens must cope with "no accounts yet" for a migrated user and say why.
• Dropbox is not supported in Phase 5 (Q11, skipped for now). V7 users who back up to Dropbox need a plain message and another destination in the storage picker.
• (The Ubuntu 20.04 limit moved to the Servers phase with the create-server flow.)

#Open points the frontend is waiting on

Provider code availability (2026-10-10): Pair2 reports B5.1–B5.5 pulled through cf36220;1211 tests/7473 assertions, Pint/PHPStan and optimization passed after pull (not rerun by this sync). List/Connect/Edit/Check and partial Disconnect are present in its copy. No genuine provider success is established. Disconnect server-usage blocker/server-name warning remain unbuilt until Phase8; Git/storage still wait Servers.