fix(gear-sync): surface the backend's actual error in the sync tray (#12)

Gear-sync failures showed a hardcoded message guessed from the HTTP status
(e.g. a 404 always claimed 'character not found — link your character on the
profile page'), which buried the real reason and is now misleading since the
backend auto-provisions characters.

ApiResult now carries an optional Detail; the batch gear-sync path extracts
FastAPI's 'detail' from the error body and GearSyncService prefers it for the
overlay/chat message, falling back to a categorized message when absent.

Bump to v0.4.1.

Author: aaronbcarlisle

XIVRaidPlannerPlugin/Api/ApiResult.cs

@@ -17,11 +17,14 @@ public readonly struct ApiResult<T>
     public T? Value { get; }
     public ApiError Error { get; }
 
-    private ApiResult(bool ok, T? value, ApiError error)
+    /// <summary>Server-provided error message (e.g. FastAPI's "detail"), when available.</summary>
+    public string? Detail { get; }
+
+    private ApiResult(bool ok, T? value, ApiError error, string? detail)
     {
-        IsSuccess = ok; Value = value; Error = error;
+        IsSuccess = ok; Value = value; Error = error; Detail = detail;
     }
 
-    public static ApiResult<T> Ok(T value) => new(true, value, ApiError.None);
-    public static ApiResult<T> Fail(ApiError error) => new(false, default, error);
+    public static ApiResult<T> Ok(T value) => new(true, value, ApiError.None, null);
+    public static ApiResult<T> Fail(ApiError error, string? detail = null) => new(false, default, error, detail);
 }

XIVRaidPlannerPlugin/Api/RaidPlannerClient.cs

@@ -67,6 +67,28 @@ private HttpClient CreateHttpClient()
         _ => ApiError.Unknown,
     };
 
+    /// <summary>Pull the human-readable message out of a FastAPI error body (<c>{"detail": "..."}</c>).</summary>
+    private static string? ExtractErrorDetail(string? body)
+    {
+        if (string.IsNullOrWhiteSpace(body)) return null;
+        try
+        {
+            using var doc = JsonDocument.Parse(body);
+            if (doc.RootElement.ValueKind == JsonValueKind.Object &&
+                doc.RootElement.TryGetProperty("detail", out var detail) &&
+                detail.ValueKind == JsonValueKind.String)
+            {
+                var text = detail.GetString();
+                return string.IsNullOrWhiteSpace(text) ? null : text;
+            }
+        }
+        catch (JsonException)
+        {
+            // Non-JSON or unexpected shape — fall back to the categorized error.
+        }
+        return null;
+    }
+
     // ==================== Tier Resolution ====================
 
     /// <summary>
@@ -418,7 +440,8 @@ public async Task<ApiResult<PluginBatchGearsetSyncResult>> SyncBatchGearsetsAsyn
             if (!response.IsSuccessStatusCode)
             {
                 _log.Error($"[BatchGearSync] {statusCode} from {endpoint} | body: {responseBody}");
-                return ApiResult<PluginBatchGearsetSyncResult>.Fail(MapStatus(response.StatusCode));
+                return ApiResult<PluginBatchGearsetSyncResult>.Fail(
+                    MapStatus(response.StatusCode), ExtractErrorDetail(responseBody));
             }
 
             _log.Info($"[BatchGearSync] {statusCode} OK | body: {responseBody}");

XIVRaidPlannerPlugin/Services/GearSyncService.cs

@@ -68,6 +68,26 @@ private void RecordSyncResult(int jobCount, string? error)
         _config.Save();
     }
 
+    /// <summary>
+    /// Build the user-facing gear-sync error. Prefers the backend's own message
+    /// (FastAPI "detail") so the overlay/chat show exactly why it failed, falling
+    /// back to a categorized message when the server gave no detail.
+    /// </summary>
+    private static string BuildSyncErrorMessage(ApiError error, string? detail)
+    {
+        if (!string.IsNullOrWhiteSpace(detail))
+            return $"[XRP] {detail}";
+
+        return error switch
+        {
+            ApiError.Unauthorized => "[XRP] API key rejected — re-authorize via /xrp config.",
+            ApiError.NotFound => "[XRP] Gear sync failed (404) — check your API URL in /xrp config.",
+            ApiError.Server => "[XRP] Backend error during gear sync (500). Check the server logs.",
+            ApiError.Network => "[XRP] Gear sync failed — network error. Check your API URL and connection.",
+            _ => "[XRP] Gear sync rejected by server. Check the Dalamud log for details.",
+        };
+    }
+
     // ==================== Pure diff (TDD) ====================
 
     /// <summary>
@@ -323,14 +343,7 @@ public void SyncSavedGearsets()
             }
             else
             {
-                var errMsg = result.Error switch
-                {
-                    ApiError.Unauthorized => "[XRP] API key rejected — re-authorize via /xrp config.",
-                    ApiError.NotFound => $"[XRP] Gearset sync failed (404): character '{charName}' on '{charWorld}' not found, or API URL is wrong. Link your character on the profile page. Check the Dalamud log for details.",
-                    ApiError.Server => "[XRP] Backend error during gearset sync (500). Check the server logs.",
-                    ApiError.Unknown => $"[XRP] Gearset sync rejected by server (422). Your character may not be linked, or a payload field is invalid. Check the Dalamud log for details.",
-                    _ => "[XRP] Gearset sync failed — network error. Check your API URL and connection.",
-                };
+                var errMsg = BuildSyncErrorMessage(result.Error, result.Detail);
                 RecordSyncResult(0, errMsg.Replace("[XRP] ", string.Empty));
                 _thread.RunOnUi(() =>
                 {
@@ -444,9 +457,7 @@ public void SyncProfileGear()
             }
             else
             {
-                var errMsg = result.Error == ApiError.Unauthorized
-                    ? "[XRP] API key rejected — re-authorize via /xrp config"
-                    : "[XRP] Failed to sync gear. Check connection.";
+                var errMsg = BuildSyncErrorMessage(result.Error, result.Detail);
                 RecordSyncResult(0, errMsg.Replace("[XRP] ", string.Empty));
                 _thread.RunOnUi(() =>
                 {

XIVRaidPlannerPlugin/XIVRaidPlannerPlugin.csproj

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project Sdk="Dalamud.NET.Sdk/15.0.0">
   <PropertyGroup>
-    <Version>0.4.0</Version>
+    <Version>0.4.1</Version>
     <PackageProjectUrl>https://github.com/aaronbcarlisle/XIVRaidPlannerPlugin</PackageProjectUrl>
     <PackageLicenseExpression>AGPL-3.0-or-later</PackageLicenseExpression>
     <IsPackable>false</IsPackable>

XIVRaidPlannerPlugin/XIVRaidPlannerPlugin.json

@@ -5,7 +5,7 @@
   "Description": "Displays loot priority rankings during savage raids and auto-logs loot drops to your FFXIV Raid Planner static. Syncs gear, saved gearsets, mounts, and collection progress to the web app. Requires an API key from the web app.\n\nCommands:\n/xrp - Toggle BiS gear viewer\n/xrp priority - Toggle priority overlay\n/xrp split - Toggle split-clear assignment overlay\n/xrp sync - Run all enabled sync modules (gearsets, mounts)\n/xrp gearsync - Sync saved gearsets for all tracked jobs\n/xrp syncgear - Sync currently equipped gear\n/xrp mountsync - Sync owned mounts and totem counts\n/xrp config - Open configuration",
   "ApplicableVersion": "any",
   "IconUrl": "https://raw.githubusercontent.com/aaronbcarlisle/XIVRaidPlannerPlugin/main/XIVRaidPlannerPlugin/Images/icon.png",
-  "Changelog": "v0.4.0 — Gear, mount & collection sync\n\nAdded\n- Mount farm sync: /xrp mountsync (also runs as part of /xrp sync) syncs owned mounts and totem counts to your static.\n- Batch gearset sync: /xrp gearsync syncs your saved gearsets for every tracked job in one pass.\n- /xrp syncgear syncs only your currently equipped gear.\n- Character window Gear Sync overlay — an FFXIV-native sync tray with gear, mount, and collection actions right on your Character window.\n- Collection participant sync and a catalog ID resolver (/xrp resolve-ids).\n- Split Clear overlay: /xrp split surfaces in-game run assignments for split-clear nights.\n\nv0.3.3 fixes still apply: BiS viewer Refresh no longer hides the Sync Gear button or wipes the equipped column, and the embedded plugin icon renders in the installer.",
+  "Changelog": "v0.4.1 — Clearer sync errors\n\nFixed\n- Gear sync now shows the server's actual reason when it fails, right in the Character window sync tray and in chat, instead of a generic message. Pairs with a website fix so first-time sign-ins no longer hit a 'character not linked' error — your character is created automatically on first sync.\n\nv0.4.0 — Gear, mount & collection sync\n\nAdded\n- Mount farm sync: /xrp mountsync (also runs as part of /xrp sync) syncs owned mounts and totem counts to your static.\n- Batch gearset sync: /xrp gearsync syncs your saved gearsets for every tracked job in one pass.\n- /xrp syncgear syncs only your currently equipped gear.\n- Character window Gear Sync overlay — an FFXIV-native sync tray with gear, mount, and collection actions right on your Character window.\n- Collection participant sync and a catalog ID resolver (/xrp resolve-ids).\n- Split Clear overlay: /xrp split surfaces in-game run assignments for split-clear nights.\n\nv0.3.3 fixes still apply: BiS viewer Refresh no longer hides the Sync Gear button or wipes the equipped column, and the embedded plugin icon renders in the installer.",
   "Tags": [
     "raid",
     "loot",