FlyMagic — xCloud Magic Login

One-click, password-free Magic Login to every WordPress site you host on xCloud.

FlyMagic is a lightweight Chrome extension (Manifest V3, vanilla JS — no build step, no frameworks). Paste your xCloud API key once, then open the popup, search your sites, and click one to land straight in its /wp-admin dashboard in a new tab. No passwords, no copy-pasting login links.

---

Features

• 🔑 One-time setup — paste your xCloud API token; it's stored locally in chrome.storage.local and only ever sent to app.xcloud.host.
• 🔎 Instant search — search bar at the top filters all sites client-side by name and domain as you type.
• 🏷 Clear site cards — each card shows the site's display name on top and its domain/URL beneath; when xCloud only stores the domain, it's shown once (no duplicate line).
• ⚡ One-click Magic Login — click a site → FlyMagic calls the xCloud API and opens the password-free login URL in a new tab.
• 🗂 All your sites — automatically pages through the full sites list (not just the first page).
• 💾 Smart cache — re-opening the popup paints instantly from cache, then refreshes in the background. Manual refresh button included.
• 🎨 xCloud branding — official logo, brand-blue palette, light & dark mode (follows your OS theme).
• 🛡 Robust states — clear loading, empty, and error states; automatic re-auth prompt on an invalid/expired key.

---

Installation (Load unpacked)

FlyMagic isn't on the Chrome Web Store — load it directly from this folder:

1. Download / copy the flymagic/ folder to your computer.
2. Open Chrome and go to chrome://extensions.
3. Toggle Developer mode on (top-right corner).
4. Click Load unpacked.
5. Select the flymagic/ folder (the one containing manifest.json).
6. FlyMagic appears in your toolbar. Pin it via the puzzle-piece menu for quick access.

Works in any Chromium-based browser that supports Manifest V3 — Chrome, Edge, Brave, Arc, Opera, etc.

---

Getting your xCloud API key

FlyMagic authenticates with a Sanctum personal access token from your xCloud account:

1. Sign in at app.xcloud.host.
2. Open Account → API Tokens — direct path: /user/api-tokens.
3. Click Create New Token.
4. Select scopes:
   • read:sites — required to list your sites.
   • write:sites — required to generate Magic Login URLs.
   • (or * for full access.)
5. Copy the token immediately — xCloud shows it only once.
6. Open the FlyMagic popup and paste it into the onboarding screen → Save & Connect.

You can view (masked), change, or delete the key any time from Settings (the gear icon in the popup header).

---

Usage

1. Click the FlyMagic toolbar icon.
2. Type in the search bar to filter your sites (by name or domain).
3. Click a site → a spinner shows while FlyMagic requests a Magic Login URL, then your WordPress dashboard opens in a new tab, already logged in.
4. Use the ↻ refresh button to re-pull the site list from xCloud.

Magic Login URLs are short-lived (xCloud expires them ~10 minutes after creation) and log you in as the site's WordPress admin user.

---

Troubleshooting

Symptom	Cause & fix
"Your API key is invalid or expired."	The token was revoked, mistyped, or truncated. Open Settings → Change key and paste a fresh token.
"…missing the required scope/permission." (403)	Your token lacks write:sites / the site:magic-login permission. Create a new token with read:sites + write:sites (or *).
"Magic Login is unavailable for this site." (422)	The site isn't a WordPress site, or Magic Login is disabled on its server.
"Too many requests." (429)	xCloud rate-limits Magic Login to 30/min per user. Wait a moment and retry.
"Couldn't reach xCloud."	Network/offline issue. Check your connection and hit Retry.
Site list is empty	The account has no sites yet, or the token is scoped to a team without sites.
Favicons missing	FlyMagic tries each site's own /favicon.ico; if it's unreachable it falls back to a coloured monogram. This is cosmetic only.
Popup shows old sites	The list is cached for speed — click ↻ refresh to re-fetch.

---

Privacy & security

• Your API key lives only in chrome.storage.local on your machine.
• FlyMagic talks to exactly one host: https://app.xcloud.host (declared in host_permissions). Magic Login URLs returned by the API open in a normal tab.
• Permissions requested: storage (save your key + site cache) and tabs (open the login URL in a new tab). Nothing else.
• No analytics, no third-party calls, no remote code.

---

How it works (API reference)

FlyMagic is built against the official xCloud Public API (v1). Contract used (verified from the live OpenAPI spec at app.xcloud.host/api/v1/docs):

• Base URL: https://app.xcloud.host/api/v1
• Auth: Authorization: Bearer <token> + Accept: application/json
• List sites: GET /sites?per_page=100&page=N → { success, message, data: { items: [ …sites ], pagination: { current_page, last_page, total, per_page } } } (parsing is tolerant of data.data[] / data.meta aliases too)
• Magic Login: POST /sites/{uuid}/magic-login → { success, message, data: { url, expires_at, admin_user } } — the password-free URL is in data.url.

Response parsing is intentionally tolerant of minor field-name drift so the extension keeps working if the API evolves.

---

File structure

flymagic/
├── manifest.json            # MV3 manifest (storage + tabs, host app.xcloud.host)
├── popup.html / popup.js    # main UI: onboarding + searchable site list
├── options.html / options.js# settings: view / change / delete API key
├── styles.css               # shared styling, brand palette, light + dark
├── lib/
│   └── xcloud.js            # storage helpers + xCloud API client
├── assets/
│   ├── xcloud-logo.svg      # official xCloud mark (brand blue)
│   ├── xcloud-logo-white.svg# white variant for the header
│   └── icon-source.svg      # branded tile used to render the PNG icons
└── icons/
    ├── icon16.png  icon48.png  icon128.png

---

FlyMagic is an independent tool and is not officially affiliated with xCloud. It uses the official xCloud Public API with your own API token.