Discord (#4367)

Resolves #(issue number)

## Description:

continuation of https://github.com/openfrontio/infra/pull/359
adds ability to put discord URL into a dedicated slot 

pc:
<img width="1917" height="921" alt="image"
src="https://github.com/user-attachments/assets/100a25d5-e998-4744-904e-df40b74ccd76"
/>

mobile:
<img width="385" height="826" alt="image"
src="https://github.com/user-attachments/assets/de904f83-c88f-41e7-9c98-81c2296ec9a2"
/>


## Please complete the following:

- [x] I have added screenshots for all UI updates
- [x] I process any text displayed to the user through translateText()
and I've added it to the en.json file
- [x] I have added relevant tests to the test directory

## Please put your Discord username so you can be contacted if a bug or
regression is found:

w.o.n

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

resources/lang/en.json

@@ -181,6 +181,16 @@
     "deny": "Deny",
     "description": "Description",
     "disband_clan": "Disband Clan",
+    "discord_default_name": "Discord",
+    "discord_expires": "That invite expires, use one set to never expire.",
+    "discord_invalid": "That isn't a valid Discord invite link.",
+    "discord_invite_unavailable": "This Discord invite is no longer valid.",
+    "discord_online_members": "{online, number} online · {members, number} members",
+    "discord_rate_limited": "Please wait a minute before verifying another Discord link.",
+    "discord_section_title": "Discord",
+    "discord_url_hint": "Use an invite set to never expire.",
+    "discord_url_label": "Discord Invite URL",
+    "discord_url_placeholder": "https://discord.gg/...",
     "error_already_member": "Already a member",
     "error_banned": "You are banned from this clan.",
     "error_banned_reason": "You are banned from this clan. Reason: {reason}",
@@ -252,6 +262,7 @@
     "open": "Open",
     "open_clan": "Open Clan",
     "open_clan_desc": "Anyone can join without an invite",
+    "open_discord": "Open Discord",
     "pending_applications": "Pending Applications",
     "pending_requests_count": "{count, plural, one {# pending request} other {# pending requests}}",
     "per_page": "Per page",

src/client/ClanApi.ts

@@ -3,6 +3,7 @@ import {
   ClanBansResponseSchema,
   type ClanBrowseResponse,
   ClanBrowseResponseSchema,
+  type ClanDiscord,
   type ClanGameFilter,
   type ClanGamesResponse,
   ClanGamesResponseSchema,
@@ -14,6 +15,7 @@ import {
   ClanMembersResponseSchema,
   type ClanRequestsResponse,
   ClanRequestsResponseSchema,
+  DiscordInviteResponseSchema,
   JoinClanResponseSchema,
 } from "../core/ClanApiSchemas";
 import { getApiBase, getUserMe } from "./Api";
@@ -24,6 +26,7 @@ export type {
   ClanBan,
   ClanBansResponse,
   ClanBrowseResponse,
+  ClanDiscord,
   ClanGame,
   ClanGameFilter,
   ClanGamePlayer,
@@ -290,7 +293,12 @@ export async function leaveClan(
 
 export async function updateClan(
   tag: string,
-  patch: { name?: string; description?: string; isOpen?: boolean },
+  patch: {
+    name?: string;
+    description?: string;
+    discordUrl?: string;
+    isOpen?: boolean;
+  },
 ): Promise<ClanInfo | { error: string }> {
   try {
     const res = await clanFetch(`/clans/${encodeURIComponent(tag)}`, {
@@ -298,6 +306,23 @@ export async function updateClan(
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(patch),
     });
+    if (res.status === 400) {
+      // Surface Discord-invite validation errors specifically so the leader
+      // knows to fix the link rather than seeing a generic failure.
+      const body = await res.json().catch(() => ({}));
+      const code = (body as { code?: string }).code;
+      if (code === "DISCORD_INVALID")
+        return { error: "clan_modal.discord_invalid" };
+      if (code === "DISCORD_EXPIRES")
+        return { error: "clan_modal.discord_expires" };
+      return { error: "clan_modal.error_failed" };
+    }
+    // The only rate limit on this endpoint is the one Discord-link
+    // verification per player per minute, so a 429 always means "wait
+    // before changing the link again".
+    if (res.status === 429) {
+      return { error: "clan_modal.discord_rate_limited" };
+    }
     if (!res.ok) {
       return {
         error: "clan_modal.error_failed",
@@ -315,6 +340,61 @@ export async function updateClan(
   }
 }
 
+// Animated icons/banners use an `a_` hash prefix and are served as .gif.
+function discordCdnAsset(
+  kind: "icons" | "banners",
+  guildId: string,
+  hash: string,
+  query = "",
+): string {
+  const ext = hash.startsWith("a_") ? "gif" : "png";
+  return `https://cdn.discordapp.com/${kind}/${guildId}/${hash}.${ext}${query}`;
+}
+
+// Fetched from the browser rather than via our server: per-player IPs sidestep
+// the rate limit Discord applies to its public invite API on shared server IPs.
+export async function fetchDiscordInvite(url: string): Promise<ClanDiscord> {
+  // The server stores the normalised short form https://discord.gg/{code}.
+  let code: string | undefined;
+  try {
+    code = new URL(url).pathname.split("/").filter(Boolean)[0];
+  } catch {
+    // Unparseable stored URL — fall through to the plain link.
+  }
+  if (!code) return { url, valid: true };
+
+  try {
+    const res = await fetch(
+      `https://discord.com/api/v10/invites/${encodeURIComponent(code)}?with_counts=true`,
+      { signal: AbortSignal.timeout(5000) },
+    );
+    // 404 => Discord no longer recognises the invite (revoked since saved).
+    if (res.status === 404) return { url, valid: false };
+    if (!res.ok) return { url, valid: true };
+    const parsed = DiscordInviteResponseSchema.safeParse(await res.json());
+    if (!parsed.success) return { url, valid: true };
+    const { guild, approximate_member_count, approximate_presence_count } =
+      parsed.data;
+    if (!guild) return { url, valid: true };
+    return {
+      url,
+      valid: true,
+      serverName: guild.name,
+      iconUrl: guild.icon
+        ? discordCdnAsset("icons", guild.id, guild.icon)
+        : null,
+      bannerUrl: guild.banner
+        ? discordCdnAsset("banners", guild.id, guild.banner, "?size=1024")
+        : null,
+      description: guild.description ?? null,
+      onlineCount: approximate_presence_count ?? null,
+      memberCount: approximate_member_count ?? null,
+    };
+  } catch {
+    return { url, valid: true };
+  }
+}
+
 export async function disbandClan(
   tag: string,
 ): Promise<true | { error: string }> {

src/client/components/clan/ClanDetailView.ts

@@ -2,12 +2,14 @@ import { html, LitElement } from "lit";
 import { customElement, property, state } from "lit/decorators.js";
 import { invalidateUserMe } from "../../Api";
 import {
+  type ClanDiscord,
   type ClanInfo,
   type ClanMember,
   type ClanMemberOrder,
   type ClanMemberSort,
   fetchClanDetail,
   fetchClanMembers,
+  fetchDiscordInvite,
   joinClan,
   leaveClan,
 } from "../../ClanApi";
@@ -52,6 +54,7 @@ export class ClanDetailView extends LitElement {
 
   @property({ type: Object }) cachedClan: ClanInfo | null = null;
   @state() private selectedClan: ClanInfo | null = null;
+  @state() private discordMeta: ClanDiscord | null = null;
   @state() private myRole: ClanRole | null = null;
   @state() private members: ClanMember[] = [];
   @state() private membersTotal = 0;
@@ -85,6 +88,23 @@ export class ClanDetailView extends LitElement {
     this.memberPage = 1;
     const knownRole = this.myClanRoles.get(this.clanTag);
     this.myRole = knownRole ?? null;
+    this.discordMeta = null;
+    if (this.cachedClan?.discordUrl) {
+      void this.loadDiscordMeta(
+        this.cachedClan.discordUrl,
+        this.clanTag,
+        this.asyncGeneration,
+      );
+    }
+  }
+
+  // Fetches live Discord invite metadata (server name, icon, counts) for the
+  // Overview card. Floating; guarded by asyncGeneration + tag so a stale
+  // response from a previous clan can't overwrite the current one.
+  private async loadDiscordMeta(url: string, tag: string, gen: number) {
+    const meta = await fetchDiscordInvite(url);
+    if (gen !== this.asyncGeneration || this.clanTag !== tag) return;
+    this.discordMeta = meta;
   }
 
   disconnectedCallback() {
@@ -134,6 +154,10 @@ export class ClanDetailView extends LitElement {
     }
 
     this.selectedClan = detail;
+    this.discordMeta = null;
+    if (detail.discordUrl) {
+      void this.loadDiscordMeta(detail.discordUrl, this.clanTag, gen);
+    }
     this.memberPage = 1;
     if (!goingToMembers) {
       // Members tab will populate these via loadInitialMembers; the
@@ -371,36 +395,46 @@ export class ClanDetailView extends LitElement {
       `;
     }
 
+    const actions = html`
+      <div class="flex flex-wrap gap-3">
+        ${this.renderActionButtons(
+          isMember,
+          isLeader,
+          isOfficer,
+          hasPendingRequest,
+          clan,
+        )}
+      </div>
+    `;
+
+    if (clan.discordUrl) {
+      // Two-column on desktop: description + stats on the left, the Discord
+      // card as a sidebar on the right, with the actions as a full-width
+      // footer below both. Footer (rather than inside the left column) so the
+      // phone stack reads description → stats → Discord → actions.
+      return html`
+        <div class="space-y-4">
+          <div class="grid gap-4 sm:grid-cols-5 items-start">
+            <div class="sm:col-span-3 flex flex-col gap-4">
+              ${this.renderDescriptionCard(clan)}
+              <div class="grid grid-cols-2 gap-4">
+                ${this.renderStatTiles(clan)}
+              </div>
+            </div>
+            <div class="sm:col-span-2">
+              ${this.renderDiscordCard(clan.discordUrl)}
+            </div>
+          </div>
+          ${actions}
+        </div>
+      `;
+    }
+
     return html`
       <div class="space-y-6">
-        <div class="bg-white/5 rounded-xl border border-white/10 p-5">
+        ${this.renderDescriptionCard(clan)}
-          <p class="text-white/70 text-sm">
+        <div class="grid grid-cols-2 gap-3">${this.renderStatTiles(clan)}</div>
-            ${clan.description || translateText("clan_modal.no_description")}
+        ${actions}
-          </p>
-        </div>
-
-        <div class="grid grid-cols-2 gap-3">
-          ${renderStat(
-            translateText("clan_modal.members"),
-            `${clan.memberCount ?? 0}`,
-          )}
-          ${renderStat(
-            translateText("clan_modal.status"),
-            clan.isOpen
-              ? translateText("clan_modal.open")
-              : translateText("clan_modal.invite_only"),
-          )}
-        </div>
-
-        <div class="flex flex-wrap gap-3">
-          ${this.renderActionButtons(
-            isMember,
-            isLeader,
-            isOfficer,
-            hasPendingRequest,
-            clan,
-          )}
-        </div>
       </div>
     `;
   }
@@ -530,6 +564,152 @@ export class ClanDetailView extends LitElement {
     `;
   }
 
+  private renderDescriptionCard(clan: ClanInfo) {
+    return html`
+      <div class="bg-white/5 rounded-xl border border-white/10 p-5">
+        <p class="text-white/70 text-sm">
+          ${clan.description || translateText("clan_modal.no_description")}
+        </p>
+      </div>
+    `;
+  }
+
+  private renderStatTiles(clan: ClanInfo) {
+    return html`
+      ${renderStat(
+        translateText("clan_modal.members"),
+        `${clan.memberCount ?? 0}`,
+      )}
+      ${renderStat(
+        translateText("clan_modal.status"),
+        clan.isOpen
+          ? translateText("clan_modal.open")
+          : translateText("clan_modal.invite_only"),
+      )}
+    `;
+  }
+
+  // Renders immediately from the stored URL (placeholder name + working join
+  // button) and fills in name/icon/counts when the Discord lookup resolves.
+  private renderDiscordCard(url: string) {
+    const meta = this.discordMeta;
+    const valid = meta?.valid === true;
+    const serverName =
+      meta?.serverName ?? translateText("clan_modal.discord_default_name");
+    const invalid = meta?.valid === false;
+    const bannerUrl = valid ? (meta?.bannerUrl ?? null) : null;
+    const description = valid ? (meta?.description ?? null) : null;
+    const showCounts =
+      valid &&
+      (typeof meta?.onlineCount === "number" ||
+        typeof meta?.memberCount === "number");
+
+    return html`
+      <div
+        class="h-full flex flex-col rounded-xl border border-[#5865F2]/25 bg-[#5865F2]/10 overflow-hidden"
+      >
+        ${bannerUrl
+          ? html`<div
+              class="relative w-full aspect-video max-h-56 overflow-hidden"
+            >
+              <img src=${bannerUrl} alt="" class="w-full h-full object-cover" />
+              <div
+                class="absolute inset-0 bg-gradient-to-t from-black/40 to-transparent"
+              ></div>
+            </div>`
+          : ""}
+        <div class="p-5 flex flex-col flex-1">
+          ${bannerUrl
+            ? ""
+            : html`<div class="flex items-center gap-2 mb-4">
+                <svg
+                  class="w-5 h-5 text-[#5865F2]"
+                  viewBox="0 0 24 24"
+                  fill="currentColor"
+                  aria-hidden="true"
+                >
+                  <path
+                    d="M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z"
+                  />
+                </svg>
+                <h3
+                  class="text-sm font-bold text-white/60 uppercase tracking-wider"
+                >
+                  ${translateText("clan_modal.discord_section_title")}
+                </h3>
+              </div>`}
+          <div class="flex items-center gap-3.5">
+            ${meta?.iconUrl
+              ? html`<img
+                  src=${meta.iconUrl}
+                  alt=""
+                  class="w-12 h-12 rounded-2xl shrink-0 object-cover ring-1 ring-white/10"
+                />`
+              : html`<div
+                  class="w-12 h-12 rounded-2xl bg-[#5865F2] flex items-center justify-center shrink-0 text-white text-lg font-bold"
+                >
+                  ${serverName.charAt(0).toUpperCase()}
+                </div>`}
+            <div class="min-w-0 flex-1">
+              <div class="text-white text-sm font-bold truncate">
+                ${serverName}
+              </div>
+              ${showCounts
+                ? html`<div
+                    class="flex items-center gap-1.5 mt-1 text-white/50 text-xs"
+                  >
+                    <span
+                      class="w-1.5 h-1.5 rounded-full bg-green-400 shrink-0"
+                    ></span>
+                    ${translateText("clan_modal.discord_online_members", {
+                      online: meta?.onlineCount ?? 0,
+                      members: meta?.memberCount ?? 0,
+                    })}
+                  </div>`
+                : ""}
+            </div>
+          </div>
+          ${description
+            ? html`<p
+                class="mt-3 text-white/50 text-xs leading-relaxed line-clamp-2"
+              >
+                ${description}
+              </p>`
+            : ""}
+          <!-- Grows when the card is stretched taller than its content,
+               pinning the button to the bottom (aligned with Manage). -->
+          <div class="flex-1"></div>
+          ${invalid
+            ? html`<p class="text-amber-400/80 text-xs mt-4">
+                ${translateText("clan_modal.discord_invite_unavailable")}
+              </p>`
+            : html`<a
+                href=${url}
+                target="_blank"
+                rel="noopener noreferrer"
+                class="mt-4 flex items-center justify-center gap-2 px-6 py-2.5 text-sm font-bold text-white uppercase tracking-wider bg-[#5865F2] hover:bg-[#4752c4] active:bg-[#3c45a5] rounded-xl transition-all shadow-lg shadow-[#5865F2]/20"
+              >
+                ${translateText("clan_modal.open_discord")}
+                <svg
+                  class="w-4 h-4"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="2"
+                  aria-hidden="true"
+                >
+                  <path
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    d="M4.5 19.5l15-15m0 0H8.25m11.25 0v11.25"
+                  />
+                </svg>
+              </a>`}
+        </div>
+      </div>
+    `;
+  }
+
   private renderActionButtons(
     isMember: boolean,
     isLeader: boolean,

src/client/components/clan/ClanManageView.ts

@@ -43,6 +43,7 @@ export class ClanManageView extends LitElement {
 
   @state() private manageName = "";
   @state() private manageDescription = "";
+  @state() private manageDiscordUrl = "";
   @state() private manageIsOpen = true;
   @state() private saving = false;
   @state() private members: ClanMember[] = [];
@@ -65,6 +66,7 @@ export class ClanManageView extends LitElement {
     if (this.selectedClan) {
       this.manageName = this.selectedClan.name;
       this.manageDescription = this.selectedClan.description ?? "";
+      this.manageDiscordUrl = this.selectedClan.discordUrl ?? "";
       this.manageIsOpen = this.selectedClan.isOpen ?? true;
     }
     this.loadMembers(1);
@@ -111,10 +113,20 @@ export class ClanManageView extends LitElement {
   private async handleSaveSettings() {
     const clan = this.selectedClan;
     if (!clan) return;
-    const patch: { name?: string; description?: string; isOpen?: boolean } = {};
+    const patch: {
+      name?: string;
+      description?: string;
+      discordUrl?: string;
+      isOpen?: boolean;
+    } = {};
     if (this.manageName !== clan.name) patch.name = this.manageName;
     if ((this.manageDescription ?? "") !== (clan.description ?? ""))
       patch.description = this.manageDescription;
+    // Discord URL is leader-only; the input only renders for leaders, so this
+    // diff is a no-op for officers (server also enforces it). "" clears the
+    // link — the server trims and coerces it to null.
+    if ((this.manageDiscordUrl ?? "") !== (clan.discordUrl ?? ""))
+      patch.discordUrl = this.manageDiscordUrl;
     if (this.manageIsOpen !== (clan.isOpen ?? true))
       patch.isOpen = this.manageIsOpen;
     if (Object.keys(patch).length === 0) return;
@@ -131,6 +143,7 @@ export class ClanManageView extends LitElement {
         detail: {
           name: result.name,
           description: result.description,
+          discordUrl: result.discordUrl,
           isOpen: result.isOpen,
         },
         bubbles: true,
@@ -358,6 +371,32 @@ export class ClanManageView extends LitElement {
               class="w-full px-4 py-3 bg-white/5 border border-white/10 rounded-xl text-white placeholder-white/20 focus:outline-none focus:ring-2 focus:ring-malibu-blue/50 focus:border-malibu-blue/50 transition-all font-medium hover:bg-white/10 text-sm resize-none"
             ></textarea>
           </div>
+          ${this.myRole === "leader"
+            ? html`
+                <div>
+                  <label
+                    class="block text-[10px] font-bold text-white/40 uppercase tracking-wider mb-2"
+                    >${translateText("clan_modal.discord_url_label")}</label
+                  >
+                  <input
+                    type="url"
+                    .value=${this.manageDiscordUrl}
+                    @input=${(e: Event) =>
+                      (this.manageDiscordUrl = (
+                        e.target as HTMLInputElement
+                      ).value)}
+                    placeholder=${translateText(
+                      "clan_modal.discord_url_placeholder",
+                    )}
+                    maxlength="255"
+                    class="w-full px-4 py-3 bg-white/5 border border-white/10 rounded-xl text-white placeholder-white/20 focus:outline-none focus:ring-2 focus:ring-malibu-blue/50 focus:border-malibu-blue/50 transition-all font-medium hover:bg-white/10 text-sm"
+                  />
+                  <p class="text-white/40 text-xs mt-2">
+                    ${translateText("clan_modal.discord_url_hint")}
+                  </p>
+                </div>
+              `
+            : ""}
           <div class="flex items-center justify-between">
             <div>
               <div class="text-white text-sm font-bold">

src/core/ClanApiSchemas.ts

@@ -36,12 +36,45 @@ export const ClanInfoSchema = z.object({
   name: z.string().max(35),
   tag: RequiredClanTagSchema,
   description: z.string().max(200),
+  // Discord invite URL set by the clan leader; null when unset. Optional
+  // because not every ClanInfo source includes it (e.g. browse results).
+  discordUrl: z.string().max(255).nullable().optional(),
   isOpen: z.boolean(),
   createdAt: z.iso.datetime().optional(),
   memberCount: z.number().optional(),
 });
 export type ClanInfo = z.infer<typeof ClanInfoSchema>;
 
+// Client-assembled view model for the clan Discord card. `valid` is false only
+// on a definitive Discord 404 (invite revoked); other failures degrade to the
+// plain link with valid: true.
+export type ClanDiscord = {
+  url: string;
+  valid: boolean;
+  serverName?: string;
+  iconUrl?: string | null;
+  bannerUrl?: string | null;
+  description?: string | null;
+  onlineCount?: number | null;
+  memberCount?: number | null;
+};
+
+// Subset of Discord's public GET /invites/{code}?with_counts=true response,
+// parsed client-side into ClanDiscord. snake_case mirrors Discord's wire format.
+export const DiscordInviteResponseSchema = z.object({
+  guild: z
+    .object({
+      id: z.string(),
+      name: z.string(),
+      icon: z.string().nullable().optional(),
+      banner: z.string().nullable().optional(),
+      description: z.string().nullable().optional(),
+    })
+    .optional(),
+  approximate_member_count: z.number().optional(),
+  approximate_presence_count: z.number().optional(),
+});
+
 export const ClanBrowseResponseSchema = z.object({
   results: ClanInfoSchema.array(),
   total: z.number(),

tests/client/clan/ClanApiMutations.test.ts

@@ -13,6 +13,7 @@ import {
   demoteMember,
   denyClanRequest,
   disbandClan,
+  fetchDiscordInvite,
   joinClan,
   kickMember,
   leaveClan,
@@ -420,4 +421,133 @@ describe("updateClan", () => {
     const result = await updateClan("TEST", { name: "x" });
     expect(result).toEqual({ error: "clan_modal.error_network" });
   });
+
+  it("maps 400 DISCORD_INVALID to the discord invalid error", async () => {
+    mockFetch(() => failRes(400, { code: "DISCORD_INVALID" }));
+    const result = await updateClan("TEST", { discordUrl: "not-a-link" });
+    expect(result).toEqual({ error: "clan_modal.discord_invalid" });
+  });
+
+  it("maps 400 DISCORD_EXPIRES to the discord expires error", async () => {
+    mockFetch(() => failRes(400, { code: "DISCORD_EXPIRES" }));
+    const result = await updateClan("TEST", {
+      discordUrl: "https://discord.gg/temp",
+    });
+    expect(result).toEqual({ error: "clan_modal.discord_expires" });
+  });
+
+  it("returns generic error on 400 with an unrecognised code", async () => {
+    mockFetch(() => failRes(400, { code: "SOMETHING_ELSE" }));
+    const result = await updateClan("TEST", { name: "x" });
+    expect(result).toEqual({ error: "clan_modal.error_failed" });
+  });
+
+  it("maps 429 to the discord rate limited error", async () => {
+    mockFetch(() => failRes(429));
+    const result = await updateClan("TEST", {
+      discordUrl: "https://discord.gg/abc",
+    });
+    expect(result).toEqual({ error: "clan_modal.discord_rate_limited" });
+  });
+});
+
+describe("fetchDiscordInvite", () => {
+  const inviteBody = {
+    guild: {
+      id: "123",
+      name: "Test Server",
+      icon: "abc",
+      banner: "a_def",
+      description: "A server",
+    },
+    approximate_member_count: 100,
+    approximate_presence_count: 42,
+  };
+
+  it("returns metadata with CDN asset URLs on success", async () => {
+    mockFetch(() => okJson(inviteBody));
+    const result = await fetchDiscordInvite("https://discord.gg/abc123");
+    expect(result).toMatchObject({
+      url: "https://discord.gg/abc123",
+      valid: true,
+      serverName: "Test Server",
+      description: "A server",
+      onlineCount: 42,
+      memberCount: 100,
+    });
+    expect(result.iconUrl).toBe("https://cdn.discordapp.com/icons/123/abc.png");
+    // Animated banner (a_ prefix) is served as .gif.
+    expect(result.bannerUrl).toBe(
+      "https://cdn.discordapp.com/banners/123/a_def.gif?size=1024",
+    );
+  });
+
+  it("parses the code from the stored discord.gg/{code} URL", async () => {
+    const fetchMock = vi.fn(() => okJson(inviteBody));
+    vi.stubGlobal("fetch", fetchMock);
+    await fetchDiscordInvite("https://discord.gg/xyz789");
+    const [requestUrl] = fetchMock.mock.calls[0] as unknown as [string];
+    expect(requestUrl).toContain("/invites/xyz789");
+  });
+
+  it("marks the invite invalid on a Discord 404", async () => {
+    mockFetch(() => failRes(404));
+    const result = await fetchDiscordInvite("https://discord.gg/gone");
+    expect(result).toEqual({ url: "https://discord.gg/gone", valid: false });
+  });
+
+  it("degrades to the plain link when Discord is unreachable", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(() => Promise.reject(new Error("network"))),
+    );
+    const result = await fetchDiscordInvite("https://discord.gg/x");
+    expect(result).toEqual({ url: "https://discord.gg/x", valid: true });
+  });
+
+  it("degrades to the plain link on a non-404 error status", async () => {
+    mockFetch(() => failRes(500));
+    const result = await fetchDiscordInvite("https://discord.gg/x");
+    expect(result).toEqual({ url: "https://discord.gg/x", valid: true });
+  });
+
+  it("returns valid with no metadata when the response lacks a guild", async () => {
+    mockFetch(() => okJson({ approximate_member_count: 5 }));
+    const result = await fetchDiscordInvite("https://discord.gg/x");
+    expect(result).toEqual({ url: "https://discord.gg/x", valid: true });
+  });
+
+  it("returns the plain link for an unparseable URL without fetching", async () => {
+    const fetchMock = vi.fn(() => okJson(inviteBody));
+    vi.stubGlobal("fetch", fetchMock);
+    const result = await fetchDiscordInvite("not a url");
+    expect(result).toEqual({ url: "not a url", valid: true });
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("passes an AbortSignal to fetch so the request can time out", async () => {
+    const fetchMock = vi.fn(() => okJson(inviteBody));
+    vi.stubGlobal("fetch", fetchMock);
+    await fetchDiscordInvite("https://discord.gg/abc123");
+    const [, init] = fetchMock.mock.calls[0] as unknown as [
+      string,
+      { signal: AbortSignal },
+    ];
+    // Pins the AbortSignal.timeout(5000) guard; without it the card could hang
+    // indefinitely on a stalled connection.
+    expect(init.signal).toBeInstanceOf(AbortSignal);
+  });
+
+  it("degrades to the plain link when the request times out", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(() =>
+        Promise.reject(
+          new DOMException("The operation timed out", "TimeoutError"),
+        ),
+      ),
+    );
+    const result = await fetchDiscordInvite("https://discord.gg/slow");
+    expect(result).toEqual({ url: "https://discord.gg/slow", valid: true });
+  });
 });

tests/client/clan/ClanApiSchemas.test.ts

@@ -57,6 +57,34 @@ describe("ClanInfoSchema", () => {
       expect(result.data.memberCount).toBeUndefined();
     }
   });
+
+  it("accepts a string discordUrl", () => {
+    const result = ClanInfoSchema.safeParse({
+      ...base,
+      discordUrl: "https://discord.gg/abc123",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a null discordUrl (link unset)", () => {
+    const result = ClanInfoSchema.safeParse({ ...base, discordUrl: null });
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.data.discordUrl).toBeNull();
+  });
+
+  it("accepts data without discordUrl (omitted by browse results)", () => {
+    const result = ClanInfoSchema.safeParse(base);
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.data.discordUrl).toBeUndefined();
+  });
+
+  it("rejects a discordUrl longer than 255 characters", () => {
+    const result = ClanInfoSchema.safeParse({
+      ...base,
+      discordUrl: "https://discord.gg/" + "a".repeat(255),
+    });
+    expect(result.success).toBe(false);
+  });
 });
 
 describe("ClanMemberSchema", () => {

tests/client/clan/ClanModalTestUtils.ts

@@ -67,6 +67,9 @@ export function clanApiMockFactory() {
       results: [],
       nextCursor: null,
     })),
+    // ClanDetailView calls this when a clan has a discordUrl; mock the degraded
+    // plain-link result so view tests never reach the real Discord network.
+    fetchDiscordInvite: vi.fn(async (url: string) => ({ url, valid: true })),
   };
 }